推进 UI run summary helper 文档

text10.txt

@@ -1346,3 +1346,68 @@ browser_interp_smoke=ok
 一小段开发者说明，列出 `createRunSummary(...)` 与 `summarizeRunResult(...)` 的输入/输出和
 语义边界，方便后续 SDK/API 或其他 UI panel 复用；保持文档只描述 host/runtime boundary，
  不扩展 CNC 语义。
+
+十九、2026-06-14 继续执行记录：UI run summary helper docs
+
+本轮继续沿 OPFS/session/UI boundary 推进，把 INI panel run summary 纯 helper 的输入/输出
+和语义边界写入独立开发者说明，便于后续 SDK/API 或其他 UI panel 复用。
+
+完成内容：
+
+- 新增 `wasm-port/docs/ui-run-summary-helpers.md`；
+- 文档说明：
+  - `createRunSummary(program, runtime, snapshot)`；
+  - `summarizeRunResult(resultText, snapshots)`；
+- 明确 helper 只处理 host/runtime boundary facts：
+  - program source；
+  - snapshot label；
+  - workflow；
+  - OPFS/WASM program path；
+  - INI WASM path；
+  - canonical event count；
+  - motion snapshot count；
+- 明确 helper 不解释 G-code、tool、parameter、planner、kinematics 或 modal 语义；
+- `wasm-port/docs/compatibility-validation.md` 同步加入 UI helper Node smoke 验证入口；
+- `wasm-port/tests/host/verify_host_smokes.sh` 继续自动调用 UI node smoke wrapper；
+- 未改变 UI runtime、OPFS bridge、interpreter run API、G-code 文本、canonical-event 输出
+  或 LinuxCNC-owned runtime semantics。
+
+验证已通过：
+
+```bash
+git diff --check
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+wasm-port/tests/host/verify_host_smokes.sh
+wasm-port/tools/verify_vendor_sync.sh
+wasm-port/tools/verify_no_standalone_cnc_semantics.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
+wasm-port/tests/opfs/node/verify_file_service.sh
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_interp_browser.sh
+```
+
+关键输出：
+
+```text
+ini_panel_run_summary_node_smoke=ok
+ui_node_smokes=ok
+host_wasm_opfs_browser_smokes=ok
+vendor sync up to date
+standalone CNC semantics guard complete
+interp_wasm_node_smoke=ok
+sim_configs_wasm_node_inventory_executed=28
+sim_configs_wasm_node_inventory_passed=28
+sim_configs_wasm_node_inventory_skipped=131
+sim_configs_wasm_node_inventory_unexpected_fail=0
+opfs_file_service_node_smoke=ok
+browser_ini_opfs_smoke=ok
+browser_interp_smoke=ok
+```
+
+下一步建议：
+
+继续沿 OPFS/session/UI boundary 推进。优先把 UI helper 文档里的 helper 输入/输出，和
+运行时实际调用点再做一次一致性检查，确保 `run-summary.js` 的导出与文档同步，之后再把
+同类 helper 模式推广到其他 UI panel；仍只做 host/runtime boundary 文档化，不扩展 CNC
+语义。

wasm-port/docs/compatibility-validation.md

@@ -60,6 +60,12 @@ The current OPFS host-boundary validation command is:
 wasm-port/tests/opfs/node/verify_file_service.sh
 ```
 
+The current UI helper Node smoke validation command is:
+
+```bash
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+```
+
 The current browser smoke validation command is:
 
 ```bash
@@ -102,6 +108,7 @@ wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
 wasm-port/tests/wasm/node/verify_nc_files_wasm.sh
 wasm-port/tests/wasm/node/verify_tp_wasm.sh
 wasm-port/tests/opfs/node/verify_file_service.sh
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
 wasm-port/tests/browser/verify_ini_panel_browser.sh
 wasm-port/tests/browser/verify_interp_browser.sh
 wasm-port/tests/host/verify_host_smokes.sh

wasm-port/docs/ui-run-summary-helpers.md

@@ -0,0 +1,99 @@
+# UI Run Summary Helpers
+
+## Purpose
+
+`runtime/ui/ini-panel/run-summary.js` contains small host-boundary helpers for
+summarizing an INI panel G-code run. These helpers are intentionally pure so
+browser UI panels, SDK-facing wrappers, and Node smoke tests can share the same
+summary shape without reading DOM text or parsing log output.
+
+The helpers do not implement CNC behavior. G-code execution, canonical events,
+tool handling, parameters, kinematics, and planner behavior remain owned by the
+vendored LinuxCNC runtime.
+
+## `createRunSummary(program, runtime, snapshot)`
+
+`program` describes the host-selected program path mapping:
+
+```js
+{
+  source: "default" | "snapshot",
+  opfsPath: "linuxcnc/gcode/ui-session.ngc",
+  wasmPath: "/work/ui-session.ngc"
+}
+```
+
+`runtime` describes already-observed runtime boundary results:
+
+```js
+{
+  runStatus: "ok",
+  snapshotLabel: "ui-machine-session/ui-machine-session.json",
+  iniWasmPath: "/work/session-machine.ini",
+  canonicalEventCount: 2,
+  motionSnapshotCount: 2
+}
+```
+
+`snapshot` is the optional machine session snapshot loaded by the UI. The helper
+reads only snapshot metadata such as `workflow` and `snapshotLabel`.
+
+The returned summary has this shape:
+
+```js
+{
+  runStatus: "ok",
+  programSource: "snapshot",
+  snapshotLabel: "ui-machine-session/ui-machine-session.json",
+  workflow: "save-session-snapshot",
+  programOpfsPath: "linuxcnc/gcode/ui-session.ngc",
+  programWasmPath: "/work/ui-session.ngc",
+  iniWasmPath: "/work/session-machine.ini",
+  canonicalEventCount: 2,
+  motionSnapshotCount: 2
+}
+```
+
+## `summarizeRunResult(resultText, snapshots)`
+
+`resultText` is the raw text returned by the LinuxCNC interpreter WASM call.
+`snapshots` is the UI's already-parsed motion snapshot list.
+
+The helper returns:
+
+```js
+{
+  canonicalEventCount: 2,
+  motionSnapshotCount: 2
+}
+```
+
+`canonicalEventCount` only counts result lines beginning with `canon_event=`.
+`motionSnapshotCount` is only `snapshots.length`.
+
+## Boundary Rules
+
+- Do not parse G-code text in these helpers.
+- Do not infer tool, parameter, kinematics, planner, or modal semantics.
+- Do not derive new canonical events in JavaScript.
+- Do not make UI helper output a promotion signal for runtime families blocked
+  by host dependencies.
+- Keep new fields limited to host/runtime boundary facts already produced by
+  the LinuxCNC-owned runtime or UI staging layer.
+
+## Validation
+
+Run the focused Node smoke after changing these helpers:
+
+```bash
+wasm-port/tests/ui/node/verify_ini_panel_run_summary.sh
+```
+
+The aggregate UI Node smoke is:
+
+```bash
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+```
+
+`wasm-port/tests/host/verify_host_smokes.sh` includes the UI Node smoke so these
+helpers are also covered by the regular host/WASM/browser gate.