cnc_wams/wasm-port/README.md

# LinuxCNC WASM Port Workspace

This directory is the standalone workspace for the WASM-based simulation port.

## Current Release Handoff

Start from `docs/project-release-handoff.md` for the current project-level
handoff. It links the browser/UI workflow surface, SDK surface,
OPFS/session persistence scope, sim-config coverage baseline, blocked
host/runtime families, source reuse rules, drift rules, and acceptance tracker.

The project release gate for the current scope is:

```bash
wasm-port/tests/host/verify_project_release_gate.sh
```

It executes these minimum release validation commands:

```bash
git diff --check
wasm-port/tools/verify_vendor_sync.sh
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
wasm-port/tests/host/verify_host_smokes.sh
```

Expected handoff smoke outputs include:

```text
project_release_handoff_docs_node_smoke=ok
opfs_session_docs_node_smoke=ok
sim_configs_coverage_docs_node_smoke=ok
host_runtime_boundary_docs_node_smoke=ok
sdk_surface_node_smoke=ok
host_wasm_opfs_browser_smokes=ok
project_release_gate=ok
```

Browser/UI entry points are documented in `docs/panel-entry.md`. Stable SDK
imports are documented in `runtime/sdk/README.md` and should come from
`runtime/sdk/src/index.js`.

Rules:

1. `linuxcnc/` is treated as the upstream source tree.
2. The porting work must not modify LinuxCNC source files in-place.
3. Port-specific code, build scripts, adapters, tests, and documentation live here.
4. LinuxCNC source is consumed by reference, copy, generated snapshot, or scripted extraction.
5. The browser/WASM product is managed as a separate program.
6. Browser UI and tests should call WASM modules through `runtime/sdk/src/index.js`.
   The SDK is a thin module-loading, string-allocation, Emscripten-FS, and C
   ABI wrapper; it must not implement CNC semantics.

Suggested layout:

- `docs/`
  Porting strategy and execution documents.
- `vendor/`
  Controlled copies or generated snapshots of LinuxCNC source files selected for porting.
- `patches/`
  Patch sets applied only to vendored copies, never directly to `linuxcnc/`.
- `tools/`
  Extraction, sync, verification, and code generation scripts.
- `runtime/`
  WASM core, JS SDK, HTML frontend, and OPFS adapters.
- `tests/`
  Port-specific regression tests and browser harnesses.

Recommended target structure after the port takes shape:

```text
wasm-port/
├── README.md
├── docs/
│   ├── scope-and-baseline.md
│   ├── source-reuse-map.md
│   ├── state-porting-strategy.md
│   ├── wasm-build-strategy.md
│   ├── frontend-architecture.md
│   ├── opfs-file-model.md
│   ├── compatibility-validation.md
│   └── drift-report.md
├── vendor/
│   └── linuxcnc/
│       └── src/
│           ├── emc/
│           │   ├── ini/
│           │   ├── kinematics/
│           │   ├── rs274ngc/
│           │   └── tp/
│           ├── hal/
│           │   └── components/
│           └── libnml/
│               └── posemath/
├── patches/
│   ├── vendor-linuxcnc-ini.patch
│   ├── vendor-linuxcnc-rs274ngc.patch
│   ├── vendor-linuxcnc-tp.patch
│   └── vendor-linuxcnc-kinematics.patch
├── tools/
│   ├── extract_sources.sh
│   ├── apply_vendor_patches.sh
│   ├── verify_vendor_sync.sh
│   ├── generate_source_manifest.py
│   └── compare_with_upstream.sh
├── runtime/
│   ├── core/
│   │   ├── include/
│   │   ├── shims/
│   │   ├── adapters/
│   │   ├── canon/
│   │   ├── session/
│   │   ├── simulation/
│   │   ├── linuxcnc_wrap/
│   │   └── c_api/
│   ├── sdk/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── ui/
│   │   ├── public/
│   │   ├── src/
│   │   │   ├── panels/
│   │   │   ├── preview/
│   │   │   ├── state/
│   │   │   ├── machine/
│   │   │   └── files/
│   │   ├── package.json
│   │   └── index.html
│   └── opfs/
│       ├── file-service.js
│       ├── snapshot-store.js
│       └── path-model.js
├── tests/
│   ├── native/
│   │   ├── ini/
│   │   ├── params/
│   │   ├── interp/
│   │   ├── tp/
│   │   └── kinematics/
│   ├── wasm/
│   │   ├── node/
│   │   └── browser/
│   └── fixtures/
│       ├── ini/
│       ├── gcode/
│       ├── tools/
│       ├── params/
│       └── machines/
├── build/
│   ├── native/
│   └── wasm/
└── dist/
    ├── sdk/
    └── web/
```

Directory intent:

- `vendor/linuxcnc/`: read-only copied LinuxCNC source selected for the port.
- `runtime/core/`: the standalone simulation engine built around vendored LinuxCNC code.
- `runtime/sdk/`: JavaScript/TypeScript API for calling the WASM engine.
  Stable imports should come from `runtime/sdk/src/index.js`. SDK code may
  adapt host/runtime edges, but G-code, tool, parameter, kinematics, and
  planner behavior must remain in vendored LinuxCNC source.
- `runtime/ui/`: HTML + JavaScript CNC simulation frontend.
- `runtime/opfs/`: OPFS-backed persistence layer.
- `tests/fixtures/`: stable simulation inputs shared by native and browser tests.
- `build/` and `dist/`: generated outputs only; never hand-edited.

Project-level OPFS/session persistence and release-gate handoff is documented in
`docs/opfs-session-persistence.md`.
Sim-config inventory coverage and release-gate handoff is documented in
`docs/sim-configs-coverage-handoff.md`.
Host/runtime boundary release-gate handoff is documented in
`docs/host-runtime-boundary-handoff.md`.
Project-level release acceptance and next-maintainer handoff is documented in
`docs/project-release-handoff.md`.

The presence of this directory means the port is managed independently of the
native LinuxCNC tree even though LinuxCNC remains the semantic source of truth.