# 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 `text15.txt` for turn-by-turn continuation notes and next-batch execution records. ## Current Status - Active continuation file: `text15.txt` - Latest completed batch: real browser simulation test program selector - 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. - `text15.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 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. | | 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, 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. - 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. - 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.