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. The browser gate runs each listed program through the WASM interpreter and verifies that rendered program rows, canonical output, motion rows, toolpath points, 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.

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.