cnc_wams/wasm-port

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, the real browser simulation priority constraint, and acceptance tracker.

The first priority for subsequent work is documented in docs/real-browser-simulation-priority.md: move quickly toward a real browser CNC simulation page with visible machine/session loading, G-code program state, LinuxCNC-backed interpreter execution, and browser smoke coverage. This does not relax the LinuxCNC semantic boundary; browser code still must not implement G-code, tool, parameter, kinematics, remap, or planner semantics. The first real simulation entry point is runtime/ui/simulation/index.html, validated by tests/browser/verify_real_simulation_browser.sh. It now exposes multiple LinuxCNC-backed test programs from the page selector: square contour, Z pocket contour, incremental loop, G2/G3 arc path, and G81 drill pattern. The page also includes playback controls that step or play through LinuxCNC canonical motion events, highlighting the active G-code line and moving the toolhead over the executed toolpath. The current UI direction is the AXIS-style simulation shell in docs/axis-style-simulation-implementation.md; Phase 1 is implemented in runtime/ui/simulation/index.html. Built-in simulation test programs live under runtime/ui/simulation/programs/ and are exported by runtime/ui/simulation/programs/index.js. The page can also execute operator-provided G-code text or loaded browser files through the LinuxCNC-backed WASM interpreter via linuxCncRealSimulationApi.runProgramText() and linuxCncRealSimulationApi.loadProgramFile().

The project release gate for the current scope is:

wasm-port/tests/host/verify_project_release_gate.sh

It executes these minimum release validation commands:

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:

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
real_browser_simulation_priority_docs_node_smoke=ok
real_simulation_programs_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:

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. The real browser CNC simulation page priority is documented in docs/real-browser-simulation-priority.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.