继续完成 web-rtcp-5axis-sim-plan
结论：完成 LinuxCNC kinematics WASM ABI 覆盖，并将 web-rtcp-5axis-sim-plan 的 RTCP frame/boundary adapter 接到 xyzac-trt kinematics SDK；Node、build、browser smoke 验证通过。
This commit is contained in:
298
textbak/PROJECT_COMPLETION_TRACKER.md
Normal file
298
textbak/PROJECT_COMPLETION_TRACKER.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# Project Completion Tracker
|
||||
|
||||
Last updated: 2026-06-20 CST
|
||||
|
||||
This file tracks the overall completion state of the LinuxCNC WASM/browser port.
|
||||
Use it for project-level status and acceptance tracking. Use `text34.txt` for
|
||||
turn-by-turn continuation notes and next-batch execution records.
|
||||
|
||||
## Current Status
|
||||
|
||||
- Active continuation file: `text34.txt`
|
||||
- Latest completed batch: real simulation handoff external shell receipt audit verification assertion dedupe
|
||||
- Latest relevant commit: use `git log -1 --oneline` after each committed batch
|
||||
- Working tree at tracker creation: clean
|
||||
- Required policy: LinuxCNC remains the only CNC semantic source
|
||||
- First priority: real UI/browser CNC simulation page; see `wasm-port/docs/real-browser-simulation-priority.md`
|
||||
- Current scope status: complete after final clean-tree release validation
|
||||
|
||||
## Completion Definition
|
||||
|
||||
The project is complete for the current scope when all of the following are true:
|
||||
|
||||
- Browser UI workflows are usable and validated:
|
||||
- real browser CNC simulation page
|
||||
- INI panel
|
||||
- control page
|
||||
- workflow overview
|
||||
- external shell handoff
|
||||
- OPFS/session persistence
|
||||
- SDK/API surface exposes stable helpers for external callers.
|
||||
- Sim config coverage has clear pass/skip/promotion state.
|
||||
- Host/runtime blocked families are explicitly documented and not falsely promoted.
|
||||
- All required gates pass.
|
||||
- Documentation explains what is supported, blocked, and how to verify it.
|
||||
- `text34.txt` contains the current continuation record and the working tree is clean.
|
||||
|
||||
## Area Status
|
||||
|
||||
| Area | Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| 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 operator-provided G-code text/files through interpreter WASM or through the loaded session INI path when a machine session is staged and enabled, includes an editable G-code pane with Run Editor Text plus OPFS save/load program persistence, shows OPFS machine/session readiness, loaded WASM session paths, a Use Session toggle, standalone/session-backed run mode, compact run summary, and browser virtual HAL state for AXIS manual controls. It highlights active G-code and motion rows, updates live axis readout, exposes DRO/modal/virtual-HAL state APIs, moves the toolhead, grows the executed SVG/Three.js toolpath, supports fit/zoom/reset/view-mode preview controls, and now shows compact operator-facing evidence-expansion family drilldown, evidence status strip, evidence copy/export view-model diagnostics, evidence/session handoff summary, synchronized machine/session handoff control label, matching status bar/run summary handoff state, save/restore handoff status-history plus diagnostics snapshot, a read-only handoff operator snapshot getter/DOM view, snapshot-derived handoff operator action-plan API/DOM state, compact handoff status getter, diagnostics compact handoff row, status bar handoff action hint, handoff preflight checklist view-model, copyable handoff review note view-model, shell-friendly handoff review packet JSON/digest, packet copy/export text, packet verification status, compact verification badge, status bar packet badge text/state/digest, read-only handoff statusbar snapshot API/DOM/dataset, copyable statusbar receipt text, receipt verification, compact statusbar receipt badge, and an external shell badge snapshot that summarizes packet/receipt/action/preflight/baseline/digest into one shell-readable string without changing release artifacts. Current built-in program set covers square contour, Z pocket contour, incremental loop, G2/G3 arcs, and G81 drilling. |
|
||||
| AXIS-style simulation shell | Phase 2/3/4/5 partial | `runtime/ui/simulation/index.html` now uses an AXIS-inspired titlebar, menubar, toolbar, Manual/MDI tabs, Preview/DRO tabs, G-code pane, machine-state pane, and status bar while preserving current LinuxCNC-backed execution and playback APIs. Browser smoke verifies shell regions, tab switching, toolbar playback, editor/file/OPFS program execution, blocked/ready machine-session readiness, ready session staging into WASM, loaded-session editor and OPFS execution with `runProgramWithIni()`, standalone fallback through the Use Session toggle, run-mode and run-summary UI/API state, DRO/modal state, Three.js preview controls, browser virtual HAL F1/F2/Ctrl-Home/jog/spindle/coolant controls, and existing program execution. |
|
||||
| Simulation test program library | Active | Built-in browser simulation programs live in `wasm-port/runtime/ui/simulation/programs/`, one module per program, exported through `programs/index.js`; `verify_real_simulation_programs.sh` checks directory-backed inventory, IDs, defaults, and playback contracts. |
|
||||
| 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=82`, `passed=82`, `skipped=77`, `unexpected_fail=0`; `docs/sim-configs-coverage-handoff.md` records the release-gate baseline. The 2026-06-20 remaining-skip audit found 2 skipped main-program rows and 0 rows with `promotion_allowed=1`, so the baseline must not change without new LinuxCNC-owned native/Node/browser proof. Browser diagnostics evidence expansion now includes eleven ready source-derived REP candidates, including the full current TRT table-rotary-tilting batch, all with `promotionAllowed=false`; the real simulation diagnostics panel and release URL workflow summaries expose the eleven-row full candidate/G-code lists plus three-family/source-count drilldown, the real simulation page shows the same family drilldown as an operator-facing diagnostics view, and the INI workflow overview has a separate evidence-expansion family/source filter with summary/action-plan helpers plus query/hash UI-state presets for external shell reads. |
|
||||
| Native nc_files baseline | Stable | Last recorded Layer 1: `total 107`, `pass 101`, `expected_fail 6`, `unexpected_fail 0`. |
|
||||
| Native sim configs baseline | Stable | Last recorded Layer 2: `total 159`, `pass 151`, `expected_fail 8`, `unexpected_fail 0`. |
|
||||
| OPFS/session persistence | Stable for current scope | Browser smoke passes, SDK re-exports OPFS/session helpers including `readMachineSessionReadiness()` and `createMachineSessionPersistenceSummary()`, the UI exposes `getMachineSessionPersistenceSummary()`, and `docs/opfs-session-persistence.md` defines the project-level release gate. |
|
||||
| SDK/API surface | Stable for current scope | SDK re-exports core, project-level virtual HAL state/action/DRO/limits-home/machine-status/WASM-bridge helpers, virtual HAL pin inventory, bridge readiness/action-plan, project report, interpreter apply adapter, OPFS/session readiness/load helpers, sim-config staging, project release gate manifest/result matrix/action-plan/readiness summary view-model, project batch acceptance capability matrix/workflow/summary/action-plan/checklist/report validation summary/action-plan, JSON workflow, URL workflow helpers, and artifact writer/validator gate, project release readiness report/artifact JSON workflow/artifact URL workflow summary/action-plan/artifact validation summary/action-plan plus URL loading workflow, INI panel entry/launcher/control-page/shell/workflow overview helpers including release artifact JSON and URL workflow summary/action-plan/render-state DOM mount helpers, validation action-plan render/mount helpers, URL workflow action-plan, and gate execution summary render/mount helpers, the session readiness workflow report, and the shell API surface inventory with dedicated Node smokes. |
|
||||
| Browser/UI workflow | Stable for current scope | Workflow overview embedding mount DOM closure is complete, and INI panel session workflows plus read-only control/shell handoff expose, render, mount, fetch, validate, summarize, action-plan, and report OPFS/session readiness, OPFS/session persistence summary, release readiness artifact JSON/URL workflows, validation/rendering/URL workflow summaries/action-plans/gate execution summaries, and API surface inventory before loading or reading WASM session state. |
|
||||
| Workflow overview embedding | Stable for current scope | Report/display/render, DOM contract/readiness/renderer, mount result/display/render, mount DOM contract/readiness/renderer/wrapper exist. |
|
||||
| Host/runtime boundary proof | Stable blocked state | Host smoke passes; runtime families remain blocked and `docs/host-runtime-boundary-handoff.md` records host readiness, promotion blockers, dispatch, and evidence gates. |
|
||||
| Documentation/release gate | Stable for current scope | `docs/project-release-handoff.md` links README, panel entry, SDK, OPFS/session, sim-config, host/runtime, source reuse, drift, tracker acceptance paths, and the machine-readable release readiness report/artifact. |
|
||||
| Project release gate wrapper | Stable | `tests/host/verify_project_release_gate.sh` runs the documented minimum release validation commands including the release artifact URL browser workflow gate, SDK URL workflow gate, and project batch acceptance workflow/artifact gate, writes `build/project-release-readiness.json` and `build/project-batch-acceptance.json`, verifies embedded gate manifest/result matrix/action-plan evidence plus batch acceptance report evidence through SDK validation workflows, and ends with `project_release_gate=ok`. |
|
||||
|
||||
## Blocked Runtime Families
|
||||
|
||||
Do not promote these without real LinuxCNC-owned runtime proof and the required
|
||||
native -> Node/WASM -> browser/host validation sequence:
|
||||
|
||||
- `L4-USER-M-PROCESS`
|
||||
- `L4-TOOL-DB`
|
||||
- `L4-PYTHON-REMAP`
|
||||
|
||||
Do not run these unless the host environment actually provides the needed
|
||||
LinuxCNC runtime:
|
||||
|
||||
```bash
|
||||
ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_millturn_user_m_runtime.sh
|
||||
ENABLE_TOOL_DB_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_tool_db_runtime.sh
|
||||
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_python_remap_runtime.sh
|
||||
```
|
||||
|
||||
## Remaining Work
|
||||
|
||||
Execute these in order unless a later user request explicitly changes priority.
|
||||
|
||||
### 0. Real Browser CNC Simulation Page
|
||||
|
||||
Current first priority:
|
||||
|
||||
- Build a real UI/browser CNC simulation page as quickly as possible.
|
||||
- First MVP exists at `wasm-port/runtime/ui/simulation/index.html`.
|
||||
- The page now includes selectable test programs for square contour, Z pocket
|
||||
contour, incremental loop, G2/G3 arcs, and G81 drilling, with browser smoke
|
||||
coverage for each program.
|
||||
- The browser simulation state now carries a source-derived millturn
|
||||
`L4-USER-M-PROCESS` virtual HAL proof for the `M429 -> M129` turn transition
|
||||
and `M428 -> M128` mill transition. It verifies switchkins guard pins and
|
||||
`ini.[xz].*` limit pin state without enabling external process execution or
|
||||
inventory promotion, and the real browser simulation page smoke now asserts
|
||||
that proof directly from `linuxCncRealSimulationState`.
|
||||
- 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 load/stage a ready OPFS machine session through existing LinuxCNC-backed
|
||||
session helpers without adding browser-owned CNC semantics.
|
||||
- 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.
|
||||
- It should expose machine/session readiness, active program state, run status,
|
||||
and a toolpath/preview surface based on LinuxCNC-produced interpreter output,
|
||||
canonical events, or validated runtime summaries.
|
||||
- Add browser smoke coverage proving the page loads, renders nonempty runtime
|
||||
state, and runs a representative LinuxCNC-backed flow.
|
||||
- Do not implement G-code, tool, parameter, kinematics, remap, planner, or
|
||||
canonical motion semantics in JavaScript.
|
||||
|
||||
Constraint document:
|
||||
|
||||
```bash
|
||||
wasm-port/tests/docs/node/verify_real_browser_simulation_priority_docs.sh
|
||||
```
|
||||
|
||||
### 1. Browser/UI Workflow Closure
|
||||
|
||||
Current next task:
|
||||
|
||||
- Current scope is complete for the established release baseline. Continue future
|
||||
work from `text15.txt`, and keep each batch tied to a callable API, verifiable
|
||||
workflow, executable gate, or real UI/browser capability.
|
||||
|
||||
Then complete the closure:
|
||||
|
||||
- Mount render-state DOM renderer is complete.
|
||||
- Non-throwing mount workflow wrapper is complete.
|
||||
- Expose each helper through:
|
||||
- `createIniPanelLaunchApiManifest().methods`
|
||||
- `createIniPanelShellViewModel()`
|
||||
- `window.linuxCncIniPanelLaunchApi`
|
||||
- `window.linuxCncIniPanelWorkflowOverviewApi`
|
||||
- Cover each helper in:
|
||||
- UI Node smoke
|
||||
- launch API manifest test
|
||||
- shell integration manifest test
|
||||
- entry docs test
|
||||
- workflow overview browser smoke
|
||||
- launch browser smoke
|
||||
- shell integration browser smoke
|
||||
- `docs/panel-entry.md`
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- External shell can render workflow overview embedding mount state with a
|
||||
custom DOM contract.
|
||||
- Missing DOM returns structured blocked results where applicable.
|
||||
- No control buttons or CNC semantic parsing are added.
|
||||
|
||||
### 2. SDK/API Surface Consolidation
|
||||
|
||||
Work items:
|
||||
|
||||
- Audit `runtime/sdk/src/index.js`. Done.
|
||||
- Export stable helpers that external callers should use. Done for core, OPFS/session, sim-config staging, project release readiness, INI panel entry/launcher/control-page/shell/workflow overview helpers.
|
||||
- Add or update SDK smoke for export shape and manifest compatibility. Done via `tests/sdk/node/verify_sdk_surface.sh`.
|
||||
- Update `runtime/sdk/README.md` with usage examples and unsupported areas. Done for the current SDK surface.
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- SDK exports match documented browser/UI helper surface.
|
||||
- SDK tests pass in Node.
|
||||
- No CNC semantics are implemented in JS.
|
||||
|
||||
### 3. OPFS/Session Persistence Summary
|
||||
|
||||
Work items:
|
||||
|
||||
- Add a project-level OPFS/session workflow summary helper or report. Done as `docs/opfs-session-persistence.md`.
|
||||
- Include machine files, session snapshot, readonly control status, and handoff
|
||||
readiness. Done through linked UI docs plus browser and host gate references.
|
||||
- Add browser smoke coverage for save -> restore -> readonly status -> shell
|
||||
handoff. Existing browser smoke remains the gate for this workflow.
|
||||
- Document OPFS scope and failure modes. Done.
|
||||
- Add docs smoke for the project-level handoff. Done via `tests/docs/node/verify_opfs_session_docs.sh`.
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- `browser_ini_opfs_smoke=ok` remains stable.
|
||||
- External callers can inspect persistence readiness and failures.
|
||||
- `opfs_session_docs_node_smoke=ok` is included in the host aggregate gate.
|
||||
|
||||
### 4. Sim Config Coverage Promotion Matrix
|
||||
|
||||
Work items:
|
||||
|
||||
- Keep inventory `unexpected_fail=0`.
|
||||
- Make skip reasons machine-readable and documented:
|
||||
- `ASSET_ONLY`
|
||||
- `L4_PYTHON_REMAP`
|
||||
- `L4_TOOL_DB`
|
||||
- `L4_USER_M_PROCESS`
|
||||
- `NON_MAIN_CLASS`
|
||||
- `UPSTREAM_DEMO`
|
||||
- Promote only configs with LinuxCNC-owned proof.
|
||||
- Add short release handoff for current inventory baseline. Done via `docs/sim-configs-coverage-handoff.md`.
|
||||
- Add docs smoke for inventory baseline and skip reason map. Done via `tests/docs/node/verify_sim_configs_coverage_docs.sh`.
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- No skipped config lacks a documented reason.
|
||||
- No blocked runtime family is falsely promoted.
|
||||
- `sim_configs_coverage_docs_node_smoke=ok` is included in the host aggregate gate.
|
||||
|
||||
### 5. Host/Runtime Boundary Reports
|
||||
|
||||
Work items:
|
||||
|
||||
- Consolidate runtime family proof reports. Done via `docs/host-runtime-boundary-handoff.md`.
|
||||
- Keep missing host runtime as blocked. Done; current status remains `host_blocked_for_all_opt_in_native_probes`.
|
||||
- If real runtime becomes available, validate in native -> Node/WASM -> browser/host order.
|
||||
- Add docs smoke for host/runtime boundary handoff. Done via `tests/docs/node/verify_host_runtime_boundary_docs.sh`.
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- `verify_host_smokes.sh` remains stable.
|
||||
- Boundaries are documented and machine-readable.
|
||||
- `host_runtime_boundary_docs_node_smoke=ok` is included in the host aggregate gate.
|
||||
|
||||
### 6. Documentation/Release Gate
|
||||
|
||||
Work items:
|
||||
|
||||
- Update `README.md`. Done.
|
||||
- Update `docs/panel-entry.md`. Done.
|
||||
- Update `docs/source-reuse-map.md`. Done.
|
||||
- Update `docs/drift-report.md`. Done.
|
||||
- Add or refresh final acceptance checklist. Done via
|
||||
`docs/project-release-handoff.md`.
|
||||
- Add a machine-readable release readiness SDK report for CI/external callers.
|
||||
Done via `createProjectReleaseReadinessReport()`.
|
||||
- Add docs smoke for project release handoff. Done via
|
||||
`tests/docs/node/verify_project_release_handoff_docs.sh`.
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- A new developer can run validation from README/docs without reading old
|
||||
`text1` through `text14`.
|
||||
- `project_release_handoff_docs_node_smoke=ok` is included in the host
|
||||
aggregate gate.
|
||||
|
||||
## Required Gates
|
||||
|
||||
Run these for each implementation batch:
|
||||
|
||||
```bash
|
||||
git diff --check
|
||||
wasm-port/tools/verify_vendor_sync.sh
|
||||
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
|
||||
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
|
||||
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
|
||||
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
|
||||
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_release_artifact_url_workflow_browser.sh
|
||||
wasm-port/tests/sdk/node/verify_project_batch_acceptance_workflow.sh
|
||||
wasm-port/tests/docs/node/verify_real_browser_simulation_priority_docs.sh
|
||||
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
|
||||
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
|
||||
wasm-port/tests/host/verify_host_smokes.sh
|
||||
```
|
||||
|
||||
Or run the same current-scope minimum gate through:
|
||||
|
||||
```bash
|
||||
wasm-port/tests/host/verify_project_release_gate.sh
|
||||
```
|
||||
|
||||
Run this if browser interpreter behavior is touched:
|
||||
|
||||
```bash
|
||||
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_interp_browser.sh
|
||||
```
|
||||
|
||||
Run these for native/source/staging or promotion work:
|
||||
|
||||
```bash
|
||||
wasm-port/tests/native/verify_nc_files.sh
|
||||
wasm-port/tests/native/verify_sim_configs.sh
|
||||
```
|
||||
|
||||
## Final Acceptance Checklist
|
||||
|
||||
- [x] Working tree is clean.
|
||||
- [x] Latest continuation state has moved to `text15.txt`.
|
||||
- [x] `git diff --check` passes.
|
||||
- [x] Vendor sync guard passes.
|
||||
- [x] Standalone CNC semantics guard passes.
|
||||
- [x] Interpreter WASM Node smoke passes.
|
||||
- [x] Sim config WASM inventory has `unexpected_fail=0`.
|
||||
- [x] UI Node smoke passes.
|
||||
- [x] Browser INI panel smoke passes.
|
||||
- [x] Host aggregate smoke passes.
|
||||
- [x] Project release gate wrapper passes.
|
||||
- [x] Runtime blocked families remain documented.
|
||||
- [x] Project release handoff docs smoke passes.
|
||||
- [x] README/docs explain supported workflows and blocked items.
|
||||
Reference in New Issue
Block a user