# 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:

```text
runtime/ui/simulation/index.html
```

Its browser gate is:

```bash
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.

## 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:

```bash
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.