# 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.

## 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.