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;
• 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:

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      │
└───────────────────────────────────────────────────────────────┘

This should replace the current three-column MVP only after the new layout has equivalent smoke coverage.

Implementation Phases

Phase 1: AXIS-Style Shell

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.

Phase 2: Program Execution Workflow

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.

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:

window.linuxCncRealSimulationApi

Required methods:

• getState();
• getPrograms();
• runProgramById(programId);
• getPlaybackFrame();
• resetPlayback();
• stepPlayback(delta);
• play();
• pause();
• finishPlayback();
• 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:

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.