cnc_wams/text16.txt

# text16.txt - LinuxCNC WASM/browser port continuation

Created: 2026-06-16 CST

This file continues from `text15.txt`. Use it for the next execution batches.

## Current Repository State

- Branch: `master`
- Remote sync state at creation: `master...origin/master`
- Latest commit at creation:

```text
69ccf93 支持真实G代码程序执行
```

- Working tree at creation: clean
- Active project tracker still exists at `PROJECT_COMPLETION_TRACKER.md`
- Previous continuation file: `text15.txt`

## Current Priority

The first priority remains the real browser CNC simulation page:

```text
wasm-port/runtime/ui/simulation/index.html
```

Primary supporting docs:

```text
wasm-port/docs/real-browser-simulation-priority.md
wasm-port/docs/axis-style-simulation-implementation.md
PROJECT_COMPLETION_TRACKER.md
```

Do not switch back to dashboard-only metadata work unless it directly creates a
gate or unblocks the browser simulation page.

## Completed Since text15 Start

The browser simulation page now has:

- AXIS-style browser shell:
  - titlebar;
  - File / Machine / View / Help menubar;
  - toolbar;
  - Manual Control / MDI tabs;
  - Preview / DRO tabs;
  - G-code pane;
  - machine-state pane;
  - bottom status bar.
- LinuxCNC-backed WASM execution through `createLinuxCncInterpSdk()`.
- Built-in test program selector.
- Built-in program directory:

```text
wasm-port/runtime/ui/simulation/programs/
```

- Current built-in program modules:
  - `square-linear.js`;
  - `pocket-z.js`;
  - `incremental-loop.js`;
  - `arc-g2-g3.js`;
  - `drill-g81.js`.
- Program inventory export:

```text
wasm-port/runtime/ui/simulation/programs/index.js
```

- Reset / Step Back / Play / Step Forward / Finish playback over LinuxCNC
  canonical motion events.
- Active G-code line highlighting.
- Active and executed motion row highlighting.
- Live XYZ/ABC readout.
- Full toolpath and executed-path SVG rendering.
- Moving toolhead marker.
- Real operator-provided G-code execution:
  - `linuxCncRealSimulationApi.runProgramText(programText, metadata)`;
  - `linuxCncRealSimulationApi.loadProgramFile(file)`;
  - toolbar `Open` file input for `.ngc/.nc/.tap/.gcode/.txt`.
- Program source metadata:
  - `program.source`;
  - `program.sourceLabel`;
  - `program.filename`;
  - `document.body.dataset.simulationProgramSource`.

## Current Browser API

Available on the simulation page:

```js
window.linuxCncRealSimulationApi
```

Current methods:

- `getState()`
- `getPrograms()`
- `runProgramById(programId)`
- `runProgramText(programText, metadata)`
- `loadProgramFile(file)`
- `getPlaybackFrame()`
- `resetPlayback()`
- `stepPlayback(delta)`
- `play()`
- `pause()`
- `finishPlayback()`

All G-code execution must continue to go through LinuxCNC-backed WASM. Browser
JS must not interpret G-code or implement planner/machine semantics.

## Validation Baseline

The latest full validation completed successfully:

```text
real_simulation_programs_node_smoke=ok
ui_node_smokes=ok
browser_real_simulation_page_smoke=ok
axis_style_simulation_docs_node_smoke=ok
real_browser_simulation_priority_docs_node_smoke=ok
project_release_gate=ok
```

Useful focused commands:

```bash
wasm-port/tests/ui/node/verify_real_simulation_programs.sh
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
wasm-port/tests/docs/node/verify_axis_style_simulation_docs.sh
wasm-port/tests/docs/node/verify_real_browser_simulation_priority_docs.sh
```

Full gate:

```bash
wasm-port/tests/host/verify_project_release_gate.sh
```

## Semantic Boundary

LinuxCNC remains the only CNC semantic source.

Browser code may:

- render UI layout and interaction state;
- read user-selected G-code files/text;
- call the SDK/WASM boundary;
- render LinuxCNC-produced canonical output;
- animate playback over LinuxCNC-produced canonical motion events;
- stage future OPFS/session files when that integration is added.

Browser code must not implement:

- G-code interpretation;
- modal semantics;
- tool/cutter compensation semantics;
- parameter semantics;
- kinematics;
- remap behavior;
- planner behavior;
- machine-control behavior not backed by LinuxCNC/WASM or validated session APIs.

## Next Recommended Batches

### 1. Real G-code Editor Pane

Add an editable G-code text pane to the AXIS shell:

- show loaded file/custom text in an editor area;
- allow editing before run;
- add `Run Editor Text`;
- preserve line numbers and active-line highlighting;
- expose `linuxCncRealSimulationApi.getProgramText()`;
- expose `linuxCncRealSimulationApi.setProgramText(text, metadata)`.

Validation:

- browser smoke edits a line, runs it, and verifies changed LinuxCNC canonical
  output;
- Node smoke verifies editor text state helpers if factored into JS modules.

### 2. OPFS Program Persistence

Connect real G-code programs to OPFS:

- save current program text to OPFS;
- load program text from OPFS;
- show OPFS path in status/readiness;
- keep browser file loading as an import path, not the only path.

Validation:

- browser smoke load file -> save OPFS -> reload OPFS -> run -> playback.

### 3. AXIS DRO/Modal State Expansion

Improve the DRO panel without inventing unsupported data:

- derive any available fields from LinuxCNC output or validated summaries;
- show unavailable fields as `n/a`;
- add tests that prevent silently fabricated G54/G92/TLO/DTG values.

Validation:

- browser smoke verifies no `undefined` and no fabricated unavailable values.

### 4. Preview Controls

Add AXIS-like preview controls:

- zoom fit;
- reset view;
- optional pan/viewport scale state;
- keep SVG nonblank and stable.

Validation:

- browser smoke verifies viewBox changes/reset and toolhead/path remain visible.

### 5. Machine/Session Integration

Use the existing OPFS/session workflow:

- load machine session;
- show machine file readiness;
- stage INI/parameter/tool-table/program into WASM;
- block run with explicit reasons when readiness is missing.

Validation:

- OPFS/session browser smoke covers load -> run -> playback.

## Adding More Built-In Test Programs

To add a built-in test:

1. Add a module under:

```text
wasm-port/runtime/ui/simulation/programs/
```

2. Export an object with:

```js
{
  id,
  label,
  category,
  text,
  expectedMotionTypes,
}
```

3. Import it in:

```text
wasm-port/runtime/ui/simulation/programs/index.js
```

4. Add it to `SIMULATION_TEST_PROGRAMS`.

5. Run:

```bash
wasm-port/tests/ui/node/verify_real_simulation_programs.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
```

## Commit / Upload Rule

After each completed implementation batch:

1. Run focused smoke(s).
2. Run `wasm-port/tests/host/verify_project_release_gate.sh` when feasible.
3. Commit with a Chinese title and conclusion body.
4. Push to:

```text
http://154.8.160.151:3000/wangdequan/cnc_wams.git
```

## Immediate Suggested Start

Start with "Real G-code Editor Pane" because the page can already execute
operator-provided text/files, but the text is not yet visible/editable inside
the AXIS shell after loading.