wasm-simulator/docs/architecture.md

WASM CNC simulator architecture

Native code boundary

The wasm core should expose a small C ABI and hide all LinuxCNC internals. The browser should never call LinuxCNC classes directly. This keeps the UI independent from whether the backend is LinuxCNC RS274, Fanuc preprocessing, Siemens preprocessing, or a future independent interpreter.

Current ABI entry points:

• cnc_sim_create
• cnc_sim_destroy
• cnc_sim_reset
• cnc_sim_set_dialect
• cnc_sim_load_config_json
• cnc_sim_parse_program
• cnc_sim_last_error

The event callback emits normalized CncSimEvent records. JavaScript can transform those records into JSON, binary buffers, or renderable typed arrays.

LinuxCNC integration plan

Functional behavior must come from LinuxCNC source code, not independently designed project code. See docs/linuxcnc-source-policy.md.

1. Build a native CanonEventSink that implements all functions declared in canon.hh.
2. Link the sink with src/emc/rs274ngc and src/emc/nml_intf instead of the task controller.
3. Stub or remove Python remap support for the first browser target.
4. Compile with Emscripten after replacing dlopen, Python, HAL and filesystem-only features.
5. Compare event output with native LinuxCNC using the same G-code corpus.

Current Workstreams

The current porting work is being split into six small contexts and should be advanced in this order:

1. switchkins/remap generator and tables
2. linuxcnc-kinematics source manifest
3. WASM filesystem and OPFS persistence
4. browser app integration
5. Node and browser smoke coverage
6. source-link, build, and documentation constraints

Each step should stay source-backed and close one small gap at a time. A single pass should advance one workstream context only; crossing into another context requires naming the dependency and keeping the edit set minimal. The synchronized source-map guard for these contexts is docs/linuxcnc-workstreams-source-map.md.

Dialect expansion

LinuxCNC support should be the baseline. Fanuc and Siemens support should be implemented as dialect adapters, not by forking the simulator core.

Fanuc high-priority items:

• Macro B variables and expression semantics
• G65, G66, G67 macro calls
• common fixed cycles
• cutter compensation and work offsets
• lathe cycles where required

Siemens high-priority items:

• named variables and arithmetic expressions
• CYCLE* canned cycles
• TRANS, ROT, SCALE, MIRROR
• TRAORI and CYCLE800
• frame and workpiece coordinate transforms

Commercial simulator parity

Feature parity needs more than G-code parsing:

• exact toolpath display with modal state inspection
• configurable machine kinematics and limits
• holder, fixture and stock collision detection
• material removal simulation
• time estimation with acceleration and lookahead
• diagnostics for unsupported controller-specific words
• reproducible comparison tests for each controller dialect

Five-axis and RTCP

RTCP pivot events are emitted only for known LinuxCNC switchkins modes. These paths must use formulas copied from LinuxCNC source code, not independently derived geometry. The current source mapping is:

• M428 / XYZBC_TRT: linuxcnc/src/emc/kinematics/trtfuncs.c, xyzbcKinematicsForward() and xyzbcKinematicsInverse()
• M430 / USERK_IDENTITY: linuxcnc/src/emc/kinematics/userkfuncs.c, delegating to identityKinematicsForward() and identityKinematicsInverse() in kins_util.c
• The retained 5axiskins helpers map to linuxcnc/src/emc/kinematics/5axiskins.c, fiveaxis_KinematicsForward() and fiveaxis_KinematicsInverse()

RTCP is opt-in through config JSON. When enabled, the original motion events remain programmed tool-tip motion and an additional rtcp-pivot event is emitted for each rapid/feed/arc event. This keeps the ABI useful for both toolpath display and machine-axis/pivot visualization.

Current files:

• core/src/rtcp_kinematics.h
• core/src/rtcp_kinematics.cpp
• core/tests/rtcp_kinematics_smoke.cpp

The next integration step is to add more LinuxCNC source-backed kinematics for additional switchkins or machine topologies.