推进 INI 面板 machine file helper 文档

text10.txt

@@ -1540,6 +1540,62 @@ browser_interp_smoke=ok
 抽取为纯 helper 并接入 `verify_ui_node_smokes.sh`；保持 helper 只描述 host/runtime 边界，
 不扩展 CNC 语义。
 
+二十五、2026-06-14 继续执行记录：INI panel machine file helper docs
+
+本轮继续沿 OPFS/session/UI boundary 推进，把 machine file summary helper 的文档入口
+补到 UI helper docs 索引，保持文档与验证入口同步。
+
+完成内容：
+
+- 新增 `wasm-port/docs/ui-machine-file-helpers.md`；
+- 在 `wasm-port/docs/compatibility-validation.md` 增加该文档入口；
+- `wasm-port/tests/ui/node/verify_ini_panel_machine_file_summary.sh` 继续纳入
+  `verify_ui_node_smokes.sh`；
+- 未改变 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/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
+wasm-port/tests/host/verify_host_smokes.sh
+```
+
+关键输出：
+
+```text
+ini_panel_machine_file_summary_node_smoke=ok
+ini_panel_run_summary_node_smoke=ok
+ini_panel_session_summary_node_smoke=ok
+ui_node_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
+host_wasm_opfs_browser_smokes=ok
+```
+
+下一步建议：
+
+继续沿 OPFS/session/UI boundary 推进。优先扫描 INI panel 中是否还有类似
+“日志文本 / DOM 状态 / 机器可读状态”三份并行维护的 host-boundary 数据，如果有，继续
+抽取为纯 helper 并接入 `verify_ui_node_smokes.sh`；保持 helper 只描述 host/runtime 边界，
+不扩展 CNC 语义。
+
 二十四、2026-06-14 继续执行记录：INI panel machine file summary helper
 
 本轮继续沿 OPFS/session/UI boundary 推进，把 INI panel 的 machine text file save/load

wasm-port/docs/compatibility-validation.md

@@ -70,6 +70,7 @@ UI helper docs:
 
 - `wasm-port/docs/ui-run-summary-helpers.md`
 - `wasm-port/docs/ui-session-summary-helpers.md`
+- `wasm-port/docs/ui-machine-file-helpers.md`
 
 The current browser smoke validation command is:
 

wasm-port/docs/ui-machine-file-helpers.md

@@ -0,0 +1,68 @@
+# UI Machine File Helpers
+
+## Purpose
+
+`runtime/ui/ini-panel/machine-file-summary.js` contains small host-boundary
+helpers for summarizing machine text file save/load actions. These helpers are
+pure so browser UI panels, SDK-facing wrappers, and Node smoke tests can share
+the same data shape without parsing log text.
+
+The helpers do not implement CNC behavior. They only describe OPFS path mapping
+and captured text lengths for machine files staged by the UI.
+
+## `createMachineFileSaveSummary(paths, gcodePath)`
+
+`paths` is the object returned by `saveMachineTextFiles(...)`.
+`gcodePath` is the OPFS path returned by `saveGcodeProgram(...)`.
+
+The returned summary has this shape:
+
+```js
+{
+  iniOpfsPath: "linuxcnc/machines/xyzab-tdr/machine.ini",
+  toolTableOpfsPath: "linuxcnc/machines/xyzab-tdr/tool.tbl",
+  parameterOpfsPath: "linuxcnc/machines/xyzab-tdr/linuxcnc.var",
+  gcodeOpfsPath: "linuxcnc/gcode/ui-session.ngc"
+}
+```
+
+## `createMachineFileLoadSummary(files)`
+
+`files` is the object returned by `loadMachineTextFiles(...)`.
+
+The returned summary has this shape:
+
+```js
+{
+  iniBytes: 26,
+  toolTableBytes: 13,
+  parameterBytes: 7
+}
+```
+
+## Log Helpers
+
+- `machineFileSaveLogLines(summary)` renders the staged OPFS paths.
+- `machineFileLoadLogLines(summary)` renders the loaded byte lengths.
+
+## 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 CNC behavior from the staged file names or lengths.
+- 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_machine_file_summary.sh
+```
+
+The aggregate UI Node smoke is:
+
+```bash
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+```