创建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/PROJECT_COMPLETION_TRACKER.md
+++ b/PROJECT_COMPLETION_TRACKER.md
@@ -41,6 +41,7 @@ The project is complete for the current scope when all of the following are true
 | LinuxCNC semantic boundary | Stable | JS/browser remains glue, staging, OPFS, WASM/browser boundary, docs, and tests only. |
 | Real browser simulation priority | Active first priority | Future batches should prioritize the real UI/browser CNC simulation page, with visible machine/session loading, G-code program state, LinuxCNC-backed interpreter execution, machine readiness/status panels, toolpath/preview rendering from LinuxCNC-produced output or validated runtime events, and browser smoke coverage. First entry point: `wasm-port/runtime/ui/simulation/index.html`; gate: `wasm-port/tests/browser/verify_real_simulation_browser.sh`. See `wasm-port/docs/real-browser-simulation-priority.md`. |
 | Real browser simulation page | MVP active | `runtime/ui/simulation/index.html` loads in Chromium, exposes a selector for multiple LinuxCNC-backed test programs, runs them through interpreter WASM, and now includes reset/step/play/finish playback over LinuxCNC canonical motion events. It highlights active G-code and motion rows, updates live axis readout, moves the toolhead, and grows the executed SVG toolpath. Current program set covers square contour, Z pocket contour, incremental loop, G2/G3 arcs, and G81 drilling. |
+| AXIS-style simulation shell | Planned | Implementation plan exists at `wasm-port/docs/axis-style-simulation-implementation.md`; next batch should build the AXIS-inspired shell while preserving current LinuxCNC-backed execution and playback APIs. |
 | Vendor/source guard | Stable | `verify_vendor_sync.sh` and standalone semantic guard are required every batch. |
 | Interpreter WASM smoke | Stable | `interp_wasm_node_smoke=ok`. |
 | Sim config inventory | Stable with skips | `executed=28`, `passed=28`, `skipped=131`, `unexpected_fail=0`; `docs/sim-configs-coverage-handoff.md` records the release-gate baseline. |
@@ -88,6 +89,9 @@ Current first priority:
 - Playback controls now expose reset/step/play/finish over LinuxCNC canonical
  motion events, with active G-code line highlighting, active motion row
  highlighting, live axis readout, moving toolhead, and executed-path rendering.
+- Next planned UI batch: follow `wasm-port/docs/axis-style-simulation-implementation.md`
+  to create an AXIS-inspired browser shell with menu/toolbar, Manual/MDI tabs,
+  Preview/DRO tabs, G-code pane, and status bar.
 - The page must be visible and operator-oriented, not another release dashboard.
 - It should use OPFS/session persistence, staged G-code, and existing
  LinuxCNC-backed WASM SDK execution.
--- a/text15.txt
+++ b/text15.txt
@@ -1748,3 +1748,39 @@ real_browser_simulation_priority_docs_node_smoke=ok
 - 回放基于 LinuxCNC WASM 输出的 canonical motion events；
 - JS 不解释 G-code，不规划刀路，不计算 CNC 语义；
 - JS 只做播放索引、DOM 高亮、坐标显示、已执行路径和 toolhead 渲染。
+
+八十一、2026-06-16 继续执行记录：AXIS 风格仿真实现文档
+
+用户给出 LinuxCNC AXIS 界面截图，要求参考该界面编写程序，并先创建实现文档。本批只创建
+实现文档和文档 gate，不改 simulation 页面行为。
+
+本批新增：
+
+- `wasm-port/docs/axis-style-simulation-implementation.md`；
+- 文档定义 AXIS-style browser simulation 的目标布局：
+  - menu/toolbar/status badges；
+  - Manual Control / MDI tabs；
+  - Preview / DRO tabs；
+  - G-code source pane；
+  - bottom status bar；
+  - 参考 AXIS 的 spindle/coolant/override/jog/active G-code/DRO/toolpath 结构；
+- 文档定义阶段：
+  - Phase 1 AXIS-style shell；
+  - Phase 2 program execution workflow；
+  - Phase 3 DRO and modal display；
+  - Phase 4 preview upgrade；
+  - Phase 5 machine/session integration；
+- 文档明确下一批立即任务：在不移除当前功能的前提下，重构
+  `runtime/ui/simulation/index.html` 为 AXIS-inspired shell，并扩展 browser smoke；
+- README、real-browser priority docs、PROJECT_COMPLETION_TRACKER 链接该实现计划；
+- 新增文档 smoke：
+  - `wasm-port/tests/docs/node/verify_axis_style_simulation_docs.mjs`；
+  - `wasm-port/tests/docs/node/verify_axis_style_simulation_docs.sh`；
+- host smoke 和 project release gate 接入该文档 smoke。
+
+本批保持 LinuxCNC 语义边界：
+
+- 文档明确 LinuxCNC 仍是唯一 CNC semantic source；
+- Browser JS 只能负责 UI、OPFS/session、SDK/WASM 调用、LinuxCNC-produced output 渲染和播放；
+- 禁止在 JS 中实现 G-code、modal、tool compensation、parameter、kinematics、remap、planner 或
+  canonical motion 语义。
--- a/wasm-port/README.md
+++ b/wasm-port/README.md
@@ -23,6 +23,8 @@ Z pocket contour, incremental loop, G2/G3 arc path, and G81 drill pattern. The
 page also includes playback controls that step or play through LinuxCNC
 canonical motion events, highlighting the active G-code line and moving the
 toolhead over the executed toolpath.
+The next UI implementation direction is the AXIS-style simulation shell in
+`docs/axis-style-simulation-implementation.md`.

 The project release gate for the current scope is:

--- 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.
--- a/wasm-port/docs/real-browser-simulation-priority.md
+++ b/wasm-port/docs/real-browser-simulation-priority.md
@@ -42,6 +42,12 @@ and declared motion types stay aligned with LinuxCNC-produced output. The first
 program set covers linear contouring, Z moves, incremental mode, G2/G3 arcs,
 and G81 drilling.

+The AXIS-style simulation UI implementation plan is maintained in:
+
+```text
+docs/axis-style-simulation-implementation.md
+```
+
 ## Batch Priority

 Unless a user explicitly changes priority, choose work in this order:
--- a/wasm-port/tests/docs/node/verify_axis_style_simulation_docs.mjs
+++ b/wasm-port/tests/docs/node/verify_axis_style_simulation_docs.mjs
@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const doc = readFileSync(resolve(root, "docs/axis-style-simulation-implementation.md"), "utf8");
+const readme = readFileSync(resolve(root, "README.md"), "utf8");
+const priority = readFileSync(resolve(root, "docs/real-browser-simulation-priority.md"), "utf8");
+
+for (const required of [
+  "AXIS-Style Browser Simulation Implementation Plan",
+  "LinuxCNC remains the only CNC semantic source",
+  "Manual Control and MDI",
+  "Preview and DRO",
+  "G-code source with active execution line",
+  "window.linuxCncRealSimulationApi",
+  "SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh",
+  "Immediate Next Batch",
+]) {
+  assert.ok(doc.includes(required), `axis-style simulation doc missing ${required}`);
+}
+
+for (const forbidden of [
+  "reimplement LinuxCNC CNC semantics in JavaScript",
+]) {
+  assert.ok(doc.includes(forbidden), `axis-style simulation doc should explicitly reject ${forbidden}`);
+}
+
+assert.ok(
+  readme.includes("docs/axis-style-simulation-implementation.md"),
+  "README should link AXIS-style implementation plan",
+);
+assert.ok(
+  priority.includes("docs/axis-style-simulation-implementation.md"),
+  "priority doc should link AXIS-style implementation plan",
+);
+
+console.log("axis_style_simulation_docs_node_smoke=ok");
--- a/wasm-port/tests/docs/node/verify_axis_style_simulation_docs.sh
+++ b/wasm-port/tests/docs/node/verify_axis_style_simulation_docs.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+node "$ROOT_DIR/tests/docs/node/verify_axis_style_simulation_docs.mjs"
--- a/wasm-port/tests/host/verify_host_smokes.sh
+++ b/wasm-port/tests/host/verify_host_smokes.sh
@@ -19,6 +19,7 @@ SKIP_TP_BUILD=1 "$ROOT_DIR/tests/wasm/node/verify_tp_wasm.sh"
 "$ROOT_DIR/tests/docs/node/verify_host_runtime_boundary_docs.sh"
 "$ROOT_DIR/tests/docs/node/verify_project_release_handoff_docs.sh"
 "$ROOT_DIR/tests/docs/node/verify_real_browser_simulation_priority_docs.sh"
+"$ROOT_DIR/tests/docs/node/verify_axis_style_simulation_docs.sh"
 "$ROOT_DIR/tests/ui/node/verify_ui_node_smokes.sh"
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_ini_panel_browser.sh"
 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_real_simulation_browser.sh"
--- a/wasm-port/tests/host/verify_project_release_gate.sh
+++ b/wasm-port/tests/host/verify_project_release_gate.sh
@@ -19,6 +19,7 @@ SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_release_art
 "$ROOT_DIR/tests/ui/node/verify_ui_node_smokes.sh"
 "$ROOT_DIR/tests/sdk/node/verify_project_release_artifact_url_workflow.sh"
 "$ROOT_DIR/tests/docs/node/verify_real_browser_simulation_priority_docs.sh"
+"$ROOT_DIR/tests/docs/node/verify_axis_style_simulation_docs.sh"
 "$ROOT_DIR/tests/host/verify_host_smokes.sh"

 node "$ROOT_DIR/tests/host/write_project_release_readiness_artifact.mjs"