创建AXIS风格仿真实现文档

结论：新增 AXIS-style browser simulation 实现计划，明确布局、阶段、API、验收 gate 和 LinuxCNC 语义边界，并接入文档 smoke 与 release gate。
2026-06-16 21:41:30 +08:00
parent 9e149107dc
commit c88aac551b
9 changed files with 357 additions and 0 deletions
--- a/wasm-port/docs/axis-style-simulation-implementation.md
+++ b/wasm-port/docs/axis-style-simulation-implementation.md
@@ -0,0 +1,262 @@
+# 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:
+
+```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      │
+└───────────────────────────────────────────────────────────────┘
+```
+
+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:
+
+```js
+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:
+
+```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.