From c88aac551bbfdf009d8151b08e38d0147b65e61a Mon Sep 17 00:00:00 2001 From: wangdequan Date: Tue, 16 Jun 2026 21:41:30 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=9B=E5=BB=BAAXIS=E9=A3=8E=E6=A0=BC?= =?UTF-8?q?=E4=BB=BF=E7=9C=9F=E5=AE=9E=E7=8E=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 结论：新增 AXIS-style browser simulation 实现计划，明确布局、阶段、API、验收 gate 和 LinuxCNC 语义边界，并接入文档 smoke 与 release gate。 --- PROJECT_COMPLETION_TRACKER.md | 4 + text15.txt | 36 +++ wasm-port/README.md | 2 + .../axis-style-simulation-implementation.md | 262 ++++++++++++++++++ .../docs/real-browser-simulation-priority.md | 6 + .../verify_axis_style_simulation_docs.mjs | 39 +++ .../node/verify_axis_style_simulation_docs.sh | 6 + wasm-port/tests/host/verify_host_smokes.sh | 1 + .../tests/host/verify_project_release_gate.sh | 1 + 9 files changed, 357 insertions(+) create mode 100644 wasm-port/docs/axis-style-simulation-implementation.md create mode 100644 wasm-port/tests/docs/node/verify_axis_style_simulation_docs.mjs create mode 100755 wasm-port/tests/docs/node/verify_axis_style_simulation_docs.sh diff --git a/PROJECT_COMPLETION_TRACKER.md b/PROJECT_COMPLETION_TRACKER.md index 18fbbc5..0bb21fc 100644 --- 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. diff --git a/text15.txt b/text15.txt index 24e8bea..916e406 100644 --- 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 语义。 diff --git a/wasm-port/README.md b/wasm-port/README.md index 1d34520..712cfd7 100644 --- 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: diff --git a/wasm-port/docs/axis-style-simulation-implementation.md b/wasm-port/docs/axis-style-simulation-implementation.md new file mode 100644 index 0000000..2ed2b1f --- /dev/null +++ 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. diff --git a/wasm-port/docs/real-browser-simulation-priority.md b/wasm-port/docs/real-browser-simulation-priority.md index ccb838b..70c9139 100644 --- 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: diff --git a/wasm-port/tests/docs/node/verify_axis_style_simulation_docs.mjs b/wasm-port/tests/docs/node/verify_axis_style_simulation_docs.mjs new file mode 100644 index 0000000..39cf251 --- /dev/null +++ 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"); diff --git a/wasm-port/tests/docs/node/verify_axis_style_simulation_docs.sh b/wasm-port/tests/docs/node/verify_axis_style_simulation_docs.sh new file mode 100755 index 0000000..d86e657 --- /dev/null +++ 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" diff --git a/wasm-port/tests/host/verify_host_smokes.sh b/wasm-port/tests/host/verify_host_smokes.sh index 2a0df99..b152088 100755 --- 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" diff --git a/wasm-port/tests/host/verify_project_release_gate.sh b/wasm-port/tests/host/verify_project_release_gate.sh index 7d1ed01..ca485e8 100755 --- 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"