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.

The CNC simulation program must be derived primarily from the LinuxCNC source program. Work in this port must strictly follow LinuxCNC behavior, structure, and semantics, except where a documented standalone runtime boundary requires an adapter.

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 CNC simulation program is primarily sourced from LinuxCNC source code; port-specific code must adapt LinuxCNC to standalone native/WASM execution, not replace LinuxCNC CNC behavior.
3. The standalone port is a separate program and separate workspace.
4. Reuse comes before rewrite.
5. Native runtime dependencies are replaced at the edges, not copied whole.
6. Machine state and controller-visible behavior are first-class compatibility targets, not optional nice-to-haves.
7. 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.