cnc_wams/PROJECT_COMPLETION_TRACKER.md

Project Completion Tracker

Last updated: 2026-06-16 CST

This file tracks the overall completion state of the LinuxCNC WASM/browser port. Use it for project-level status and acceptance tracking. Use text16.txt for turn-by-turn continuation notes and next-batch execution records.

Current Status

• Active continuation file: text16.txt
• Latest completed batch: AXIS run summary
• 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.
• text16.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, and supports fit/zoom/reset/view-mode preview controls. 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=28, passed=28, skipped=131, unexpected_fail=0; docs/sim-configs-coverage-handoff.md records the release-gate baseline.
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:

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

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:

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:

wasm-port/tests/host/verify_project_release_gate.sh

Run this if browser interpreter behavior is touched:

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:

wasm-port/tests/native/verify_nc_files.sh
wasm-port/tests/native/verify_sim_configs.sh

Final Acceptance Checklist

• Working tree is clean.
• Latest continuation state has moved to text15.txt.
• git diff --check passes.
• Vendor sync guard passes.
• Standalone CNC semantics guard passes.
• Interpreter WASM Node smoke passes.
• Sim config WASM inventory has unexpected_fail=0.
• UI Node smoke passes.
• Browser INI panel smoke passes.
• Host aggregate smoke passes.
• Project release gate wrapper passes.
• Runtime blocked families remain documented.
• Project release handoff docs smoke passes.
• README/docs explain supported workflows and blocked items.