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`.
- Editable AXIS-style G-code pane:
  - loaded file/custom/built-in program text is visible in a textarea;
  - editor text can be changed before execution;
  - toolbar `Run Editor Text` executes the current editor contents;
  - `getProgramText()`, `setProgramText()`, and `runEditorProgramText()` are
    exposed on the browser API.
- 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)`
- `getProgramText()`
- `setProgramText(text, metadata)`
- `runEditorProgramText()`
- `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

Status: complete.

Implemented:

- 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)`.
- expose `linuxCncRealSimulationApi.runEditorProgramText()`.

Validation:

- browser smoke sets editor text, runs it, and verifies changed LinuxCNC
  canonical output.

### 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 "OPFS Program Persistence" because the page can now load, edit, and
run real G-code text/files, but programs are not yet saved to or restored from
OPFS from within the AXIS shell.

## Execution Record

### 一、2026-06-16 Real G-code Editor Pane

按 `text16.txt` 的 Immediate Suggested Start 推进，完成 AXIS shell 内真实 G-code 编辑区。

本批新增实质能力：

- `runtime/ui/simulation/index.html` 新增 editable G-code pane：
  - `data-axis-shell="program-editor"`；
  - `textarea[data-program-editor]`；
  - `data-program-editor-status`；
- 工具栏新增：
  - `Run Editor Text`；
- 页面状态新增 `programEditorState`；
- 内置程序加载、真实文本执行、真实文件加载都会同步到 editor textarea；
- editor textarea 修改后可直接运行；
- `window.linuxCncRealSimulationApi` 新增：
  - `getProgramText()`；
  - `setProgramText(text, metadata)`；
  - `runEditorProgramText()`；
- browser smoke 新增验证：
  - 初始内置程序会同步到 editor；
  - `runProgramText()` 后 editor 同步自定义文本；
  - `loadProgramFile()` 后 editor 同步文件文本和 filename metadata；
  - `setProgramText()` 修改 editor 内容；
  - `runEditorProgramText()` 通过 LinuxCNC WASM 执行修改后的 G-code，并验证 canonical output
    出现修改后的坐标。

关键验证：

```text
browser_real_simulation_page_smoke=ok
real_simulation_programs_node_smoke=ok
```

语义边界：

- editor 只保存和显示 G-code 文本；
- G-code 执行仍通过 LinuxCNC-backed WASM；
- JS 不解释 G-code、不规划刀路、不推导 modal/machine semantics。