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