# LinuxCNC WASM Port Workspace

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

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.

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.