cnc_wams/wasm-port/docs/axis-style-simulation-implementation.md

# AXIS-Style Browser Simulation Implementation Plan

This document defines the implementation plan for evolving
`runtime/ui/simulation/index.html` toward a browser simulation surface inspired
by LinuxCNC AXIS. It is a product/UI implementation guide, not permission to
reimplement LinuxCNC CNC semantics in JavaScript.

## Reference Target

The reference UI is LinuxCNC AXIS with:

- a top menu and compact icon toolbar;
- Manual Control and MDI tabs;
- machine controls for axis selection, jog mode, homing, spindle, coolant,
  feed/rapid/spindle overrides, jog speed, and max velocity;
- active G-code modal display;
- a combined preview/DRO area;
- a 3D toolpath preview with machine extents and tool marker;
- DRO rows for relative/absolute position, distance-to-go, work offsets,
  G92 offsets, tool length offsets, and velocity;
- a scrollable G-code source pane with active line;
- a bottom status bar for E-stop, tool, and coordinate mode.

The browser implementation should match the operational shape of AXIS while
staying suitable for a web runtime and the current WASM/OPFS architecture.

## Non-Negotiable Boundary

LinuxCNC remains the only CNC semantic source.

Browser JavaScript may:

- render UI layout and interaction state;
- call the existing LinuxCNC-backed WASM SDK;
- stage G-code, INI, parameter, and tool-table text into OPFS or the
  Emscripten filesystem;
- display LinuxCNC-produced canonical output, motion events, modal state,
  run status, and validated runtime summaries;
- animate playback over LinuxCNC-produced motion events.

Browser JavaScript must not implement:

- G-code interpretation;
- modal semantics;
- cutter/tool compensation semantics;
- parameter semantics;
- kinematics;
- remap behavior;
- planner behavior;
- canonical motion semantics beyond display mapping of LinuxCNC-produced
  canonical fields.

## Current Baseline

The current simulation page already has:

- LinuxCNC interpreter WASM execution through `createLinuxCncInterpSdk()`;
- selectable test programs under `runtime/ui/simulation/programs/`;
- custom G-code text and browser File execution through LinuxCNC WASM;
- editable G-code pane plus run-editor-text workflow;
- canonical output rendering;
- program-line rendering;
- motion table;
- final and playback axis readout;
- SVG toolpath preview;
- reset/step/play/finish playback over LinuxCNC canonical motion events;
- browser smoke coverage in `tests/browser/verify_real_simulation_browser.sh`;
- Node contract coverage in `tests/ui/node/verify_real_simulation_programs.sh`.

## Target Layout

The first AXIS-style browser layout should be a single operator workspace:

```text
menu/toolbar/status badges
┌───────────────────────┬─────────────────────────────────────┐
│ Manual / MDI tabs     │ Preview / DRO tabs                   │
│ Jog controls          │ 3D or 2.5D toolpath viewport          │
│ spindle/coolant       │ DRO overlay / panel                  │
│ overrides/speeds      │ active tool marker                   │
│ active modal codes    │ machine/work extents                 │
├───────────────────────┴─────────────────────────────────────┤
│ G-code source with active execution line                      │
├───────────────────────────────────────────────────────────────┤
│ E-stop | tool | position mode | run state | program state      │
└───────────────────────────────────────────────────────────────┘
```

The Phase 1 implementation has replaced the former three-column MVP with this
AXIS-style shell while preserving the existing LinuxCNC-backed execution and
playback APIs.

## Implementation Phases

### Phase 1: AXIS-Style Shell

Status: implemented.

Build the visual shell around the existing simulation state:

- menu bar: File, Machine, View, Help;
- toolbar: open, reload, run, pause, step, stop, reset, zoom controls;
- left panel tabs: Manual Control and MDI;
- right panel tabs: Preview and DRO;
- lower G-code pane;
- bottom status bar.

Controls may initially be display-only or disabled when no real runtime action
exists, but they must show explicit readiness/blocked state.

Validation:

- browser smoke proves all AXIS-style regions render;
- current program selection and playback still work;
- no existing simulation API is removed.

Current implemented regions:

- `data-axis-shell="titlebar"`;
- `data-axis-shell="menubar"`;
- `data-axis-shell="toolbar"`;
- `data-axis-shell="manual-mdi"`;
- `data-axis-shell="preview-dro"`;
- `data-axis-shell="gcode-pane"`;
- `data-axis-shell="machine-state"`;
- `data-axis-shell="statusbar"`.

### Phase 2: Program Execution Workflow

Status: active; custom text/file execution and editor-text execution are implemented.

Upgrade the G-code pane and execution controls:

- load a selected built-in test program;
- run through LinuxCNC WASM;
- reset/step/play/pause/finish playback from toolbar and keyboard-accessible
  buttons;
- highlight active G-code line and current motion row;
- show run status, source program, motion count, and current frame.
- load operator-provided G-code text through `runProgramText()`;
- load browser `File` objects through `loadProgramFile()`;
- edit visible G-code in the AXIS shell and run it through
  `runEditorProgramText()`;

Built-in test programs must live in:

```text
runtime/ui/simulation/programs/
```

Each program should have its own module and be exported through
`runtime/ui/simulation/programs/index.js`. The simulation renderer should keep
importing the inventory through the program index rather than embedding G-code
fixtures in `simulation-app.js`.

Validation:

- browser smoke runs at least one linear program, one arc program, and one
  canned-cycle program through toolbar actions;
- active-line, toolhead, executed path, and status bar update together.

### Phase 3: DRO and Modal Display

Add a DRO panel modeled after AXIS:

- relative actual X/Y/Z/A/B/C;
- distance-to-go when available from LinuxCNC-produced or validated runtime
  events;
- G54 and G92 rows when available from canonical output or runtime summaries;
- tool length offset rows when available;
- velocity from playback delta or LinuxCNC-produced runtime field when
  available;
- active G-code modal display from LinuxCNC output only.

Fallback values must be marked as unavailable rather than invented.

Validation:

- Node and browser tests verify no unavailable field is silently fabricated;
- modal/DRO display is derived from LinuxCNC output or explicit unavailable
  state.

### Phase 4: Preview Upgrade

Improve the preview from a simple SVG polyline into an AXIS-like viewport:

- dark viewport theme;
- work envelope and extents grid;
- full path versus executed path;
- active tool marker;
- zoom fit / pan / reset view;
- optional orthographic 3D using Three.js only if it stays stable in browser
  smoke and canvas-pixel checks.

Validation:

- browser smoke verifies nonblank preview, executed path growth, toolhead
  movement, and stable viewport controls;
- mobile and desktop screenshots must not show overlapping UI.

### Phase 5: Machine/Session Integration

Connect the AXIS-style shell to the existing OPFS/session workflow:

- load machine session from OPFS;
- show machine file readiness;
- show loaded INI/parameter/tool-table/program paths;
- stage files into WASM before execution;
- block run controls with explicit reasons when session readiness is missing.

Validation:

- OPFS/session browser smoke covers load -> run -> playback;
- release gate includes the AXIS-style simulation workflow.

## Required APIs

The page should expose a stable browser API under:

```js
window.linuxCncRealSimulationApi
```

Required methods:

- `getState()`;
- `getPrograms()`;
- `runProgramById(programId)`;
- `getPlaybackFrame()`;
- `resetPlayback()`;
- `stepPlayback(delta)`;
- `play()`;
- `pause()`;
- `finishPlayback()`;
- `runProgramText(programText, metadata)`;
- `loadProgramFile(file)`;
- `getProgramText()`;
- `setProgramText(text, metadata)`;
- `runEditorProgramText()`;
- future: `loadProgramText(text, metadata)`;
- future: `loadMachineSessionFromOpfs(options)`;
- future: `getMachineReadiness()`;
- future: `getDroState()`;
- future: `getModalState()`.

API additions must be covered by Node or browser smoke before being relied on
by UI controls.

## Visual Design Rules

Use the reference as an operational model, not a pixel-perfect clone.

- Keep controls dense and tool-like.
- Prefer plain borders, compact buttons, tabs, and status strips.
- Avoid landing-page composition, marketing cards, oversized hero text, and
  decorative backgrounds.
- Keep preview large and central.
- Keep G-code visible during playback.
- Keep status and blocked reasons visible without modal interruptions.
- Use icons where available, but text labels are acceptable until a stable icon
  dependency exists.

## Acceptance Gates

Every implementation batch must keep these passing:

```bash
wasm-port/tests/ui/node/verify_real_simulation_programs.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
wasm-port/tests/docs/node/verify_real_browser_simulation_priority_docs.sh
wasm-port/tests/host/verify_project_release_gate.sh
```

When AXIS-style shell work starts, add or extend browser assertions for:

- menu bar;
- toolbar;
- Manual Control tab;
- MDI tab;
- Preview tab;
- DRO tab;
- active G-code pane;
- status bar;
- playback controls driving the same LinuxCNC-backed state as the API.

## Immediate Next Batch

Implement Phase 1 without removing current functionality:

1. Restructure `runtime/ui/simulation/index.html` into the AXIS-style shell.
2. Preserve existing program selector and playback API.
3. Move current playback buttons into the toolbar.
4. Add Manual Control and MDI tabs with readiness/blocked state.
5. Add Preview and DRO tabs with current preview and readout.
6. Add bottom status bar.
7. Extend `real_simulation_page_smoke.html` to verify the new shell regions.

The first implementation batch should be UI structure plus smoke coverage; it
must not invent machine-control behavior that is not backed by LinuxCNC/WASM or
existing session/readiness APIs.