cnc_wams/wasm-port/SKILL.md

SKILL.md

Skill Name

LinuxCNC WASM Simulation Port

Purpose

This skill guides work inside wasm-port/ for building a standalone LinuxCNC-based CNC simulation program.

It is intended for tasks involving:

• source extraction from upstream LinuxCNC;
• vendoring and patching selected LinuxCNC modules;
• wrapping LinuxCNC compute code for native and WASM use;
• preserving interpreter, planner, kinematics, HAL-visible, and INI-visible semantics;
• building HTML + JavaScript + OPFS frontend integration.

When To Use

Use this skill when the work involves any of the following:

• deciding whether to reuse or reimplement LinuxCNC code;
• mapping CNC features to LinuxCNC source files;
• creating or updating extraction scripts under tools/;
• defining standalone runtime structure under runtime/core/;
• building browser-facing WASM APIs;
• integrating OPFS-backed configuration and session persistence;
• validating LinuxCNC-equivalent simulation behavior.

Core Principles

1. Upstream LinuxCNC is the semantic source of truth.
2. The standalone port is a separate program and separate workspace.
3. Reuse comes before rewrite.
4. Native runtime dependencies are replaced at the edges, not copied whole.
5. Machine state and controller-visible behavior are first-class compatibility targets, not optional nice-to-haves.
6. Do not continue building a project-authored CNC program once the porting harness runs; move behavior back to vendored LinuxCNC source functions.

Source Reuse Priorities

Highest-priority source reuse targets:

• src/emc/rs274ngc
• src/emc/tp
• src/emc/kinematics
• src/libnml/posemath
• src/emc/ini

Secondary semantic references:

• src/hal/hal.h
• src/hal/halmodule.cc
• src/emc/ini/inihal.cc

Reference-only UI sources:

• src/emc/usr_intf/axis
• src/hal/user_comps/vismach
• configs/sim/axis/vismach/5axis

Required Port Boundaries

The port should preserve or expose these LinuxCNC behaviors:

• G-code parsing and execution
• canonical motion generation
• parameter file semantics
• named variable lookup semantics
• _ini[...] lookup semantics
• _hal[...] lookup semantics through simulation adapter
• planner behavior
• 3-axis through 5-axis kinematics
• machine/controller state visible to software

The port should replace these native dependencies:

• Linux process orchestration
• NML transport implementation
• HAL runtime internals
• realtime scheduling
• native GUI implementation
• native filesystem assumptions

Implementation Pattern

Preferred order of work:

1. Identify upstream file owners for the feature.
2. Extract files into vendor/linuxcnc/.
3. Add wrappers or shims in runtime/core/.
4. Apply minimal patches only to vendored copies if needed.
5. Build a native standalone harness first.
6. Build the WASM export layer second.
7. Build the JS SDK and HTML frontend last.

Current migration emphasis:

• Treat linuxcnc_interp_minimal_runtime.cpp as a temporary probe surface.
• Retire hand-written convert_g() behavior by linking and calling vendored LinuxCNC interpreter conversion code.
• Add shims only for host/runtime edges that prevent vendored LinuxCNC source from compiling.
• Do not add new G-code behavior in JavaScript or in standalone C++ wrappers except as a short-lived adapter around LinuxCNC code.

Filesystem And Browser Guidance

For browser use:

• WASM core should not directly own OPFS logic.
• JavaScript host should own OPFS and file management.
• WASM core should operate on abstract file services or explicit byte blobs.

Recommended browser storage targets:

• INI files
• tool tables
• parameter files
• G-code programs
• preview caches
• session snapshots

Validation Pattern

For each migrated feature, validate in this order:

1. Upstream LinuxCNC behavior
2. Standalone native extracted-core behavior
3. WASM behavior in Node or CLI harness
4. Browser behavior through the frontend

Always record:

• source origin
• any shim introduced
• any vendored patch introduced
• known deviations from upstream behavior

Deliverable Bias

Prefer deliverables that directly improve execution readiness:

• source reuse maps
• extraction scripts
• standalone runtime wrappers
• regression fixtures
• drift reports

Prefer not to spend time on speculative abstractions unless they reduce real migration complexity.