cnc/wasm-port/AGENTS.md

AGENTS.md

Scope

This file defines agent operating rules for the standalone LinuxCNC WASM simulation port located under wasm-port/.

This workspace is separate from the upstream LinuxCNC tree in ../linuxcnc/.

Primary Objective

Build a standalone CNC simulation system that:

• reuses LinuxCNC source as the semantic source of truth;
• compiles core CNC logic to WASM;
• uses HTML + JavaScript for the frontend;
• uses OPFS for browser persistence;
• does not drive real hardware;
• preserves LinuxCNC software behavior as closely as practical.

Repository Boundaries

1. ../linuxcnc/ is upstream and must be treated as read-only input for the port effort.
2. Port-specific code must live under wasm-port/.
3. Vendored LinuxCNC source copies must live under wasm-port/vendor/linuxcnc/.
4. Any source-level adaptation must be applied to vendored copies only.
5. Never treat experimental files under ../linuxcnc/web/ as the official port target. The official port program is managed here.

Engineering Rules

1. Reuse LinuxCNC source before reimplementing any CNC logic.
2. Prefer wrappers, shims, and extraction scripts over invasive source edits.
3. Preserve LinuxCNC semantics for:
   • G-code execution;
   • modal state;
   • parameter and variable behavior;
   • kinematics;
   • planner behavior;
   • machine and controller state visible to software.
4. Replace only the native runtime edges:
   • file IO;
   • process model;
   • HAL runtime;
   • IPC;
   • GUI.
5. Frontend code must be implemented with web technology, not migrated from native GUI code.

Required Layout

The standalone port should use these major areas:

• docs/
• vendor/
• patches/
• tools/
• runtime/core/
• runtime/sdk/
• runtime/ui/
• runtime/opfs/
• tests/

Do not collapse these concerns back into the upstream tree.

File Ownership

• docs/: planning, architecture, drift tracking, validation
• vendor/: copied upstream source
• patches/: patches against vendored copies
• tools/: extraction and sync scripts
• runtime/core/: standalone native/WASM simulation runtime
• runtime/sdk/: JS or TS SDK
• runtime/ui/: HTML + JavaScript simulation frontend
• runtime/opfs/: browser persistence layer
• tests/: standalone native and browser regression coverage

Validation Requirements

Every migrated feature should be validated against LinuxCNC-native behavior using one or more of:

• existing LinuxCNC tests;
• extracted native harness tests;
• WASM regression tests;
• browser smoke tests.

Validation should cover:

• path output;
• machine/controller state;
• parameter and variable behavior;
• kinematic transforms;
• file/config loading.

Non-Goals

This project must not:

• attempt realtime hardware control;
• port LinuxCNC drivers to the browser;
• recreate LinuxCNC's native process topology;
• rewrite major CNC semantics in JavaScript if LinuxCNC source can be reused;
• depend on LinuxCNC native GUI code as implementation code.

Working Style

When extending this workspace:

1. Update docs before or alongside structural changes.
2. Keep extraction and patching reproducible.
3. Keep adapters narrow and explicit.
4. Keep LinuxCNC-derived logic traceable to its upstream file origin.