cnc_wams/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;
• derives the CNC simulation program primarily from the LinuxCNC source program and strictly follows LinuxCNC behavior, structure, and semantics unless a documented standalone runtime boundary requires adaptation;
• 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.

Current Direction

The migration target is the LinuxCNC source program itself, adapted to run as the standalone WASM simulation program. The project must not evolve a project-authored interpreter, planner, or CNC semantics layer now that the porting harness is running.

Existing minimal runtime wrappers are migration probes only. They are allowed to expose, compile, and validate vendored LinuxCNC code, but they must not be expanded into a separate implementation of G-code behavior.

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. Treat the LinuxCNC source program as the primary implementation source for the CNC simulation program. Standalone code must strictly follow vendored LinuxCNC behavior and may only adapt runtime edges such as filesystem, HAL, IPC, process model, and browser integration.
3. Do not add new project-authored CNC semantics when LinuxCNC source exists. Replace temporary wrapper behavior with direct calls into vendored LinuxCNC source, or with the narrowest shims needed to make those calls compile.
4. Prefer wrappers, shims, and extraction scripts over invasive source edits.
5. Preserve LinuxCNC semantics for:
   • G-code execution;
   • modal state;
   • parameter and variable behavior;
   • kinematics;
   • planner behavior;
   • machine and controller state visible to software.
6. Replace only the native runtime edges:
   • file IO;
   • process model;
   • HAL runtime;
   • IPC;
   • GUI.
7. 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.