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