cnc_wams/wasm-port/docs/real-browser-simulation-priority.md

Real Browser Simulation Priority

This document is a standing project constraint for all work after 2026-06-16.

Primary Objective

The first priority is to deliver a real browser CNC simulation page, not more project metadata or dashboard-only helpers. Future batches should prefer visible, interactive browser capability that moves the product toward an operator-usable CNC simulation surface.

The target page must become a real CNC simulation page with:

• a machine/session loader backed by the existing OPFS/session workflow;
• a G-code program view backed by persisted or staged program text;
• LinuxCNC-backed interpreter execution through the existing WASM SDK;
• machine state panels for run status, active program, machine files, and missing readiness;
• a toolpath/preview area driven by LinuxCNC-produced interpreter/canonical output or existing validated runtime events, not JavaScript-owned CNC semantics;
• browser smoke coverage that proves the page loads, renders nonempty runtime state, and can run a representative LinuxCNC-backed program flow.

The first implementation entry point is:

runtime/ui/simulation/index.html

Its browser gate is:

wasm-port/tests/browser/verify_real_simulation_browser.sh

The current page includes a real LinuxCNC-backed test-program selector and motion playback controls. The browser gate runs each listed program through the WASM interpreter and verifies that rendered program rows, canonical output, motion rows, active-line playback, executed toolpath points, moving toolhead, 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:

docs/axis-style-simulation-implementation.md

Phase 1 of that plan is implemented in runtime/ui/simulation/index.html with an AXIS-inspired shell and browser smoke coverage for shell regions, tab switching, toolbar playback, and LinuxCNC-backed program execution.

Batch Priority

Unless a user explicitly changes priority, choose work in this order:

1. Real UI/browser simulation page capability.
2. Browser workflow smoke for that simulation capability.
3. UI APIs needed by the simulation page.
4. OPFS/session integration needed by the simulation page.
5. SDK/API helpers only when they directly unblock the simulation page.
6. Documentation or release metadata only when it creates an executable gate or protects the simulation-page direction.

Every implementation batch still must produce at least one callable API, verifiable workflow, executable gate, or real UI/browser capability.

Boundary Rules

The browser simulation page must not implement CNC semantics in JavaScript. G-code interpretation, canonical motion behavior, tool semantics, parameter semantics, kinematics, remap behavior, and planner behavior must remain owned by vendored LinuxCNC source and existing LinuxCNC-backed WASM C ABI boundaries.

JavaScript/browser code may own:

• layout and interaction state;
• OPFS/session persistence;
• file staging into the Emscripten filesystem;
• calls into the SDK/WASM boundary;
• rendering LinuxCNC-produced output, canonical events, and validated runtime summaries;
• non-CNC UI state such as selected file, active tab, viewport mode, and validation messages.

Required Evidence

The priority is enforced by:

wasm-port/tests/docs/node/verify_real_browser_simulation_priority_docs.sh
wasm-port/tests/ui/node/verify_real_simulation_programs.sh
wasm-port/tests/host/verify_host_smokes.sh
wasm-port/tests/host/verify_project_release_gate.sh

The docs gate must verify that this priority document, the release handoff, the README, and PROJECT_COMPLETION_TRACKER.md all point future work toward a real browser CNC simulation page while preserving the LinuxCNC semantic boundary.