# 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.
8. Frontend, browser tests, and Node WASM tests should call generated WASM
   modules through `runtime/sdk/src/index.js`. SDK code is a host-boundary
   layer only: it may load modules, manage strings, write Emscripten files,
   and call exported C ABI functions, but it must not implement G-code,
   canonical motion, tool, parameter, kinematics, or planner semantics.
9. All build scripts must be incremental. Native and WASM builds must reuse
   object files, dependency files, and command fingerprints, and must not
   unconditionally recompile unchanged source files.

## 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.
