推进 INI 面板 session load summary helper

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

@@ -0,0 +1,85 @@
+# UI Session Summary Helpers
+
+## Purpose
+
+`runtime/ui/ini-panel/session-summary.js` contains small host-boundary helpers
+for summarizing machine session snapshot state.
+`runtime/ui/ini-panel/session-load-summary.js` contains the matching helpers
+for machine-session load state. 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. G-code execution, canonical events,
+tool handling, parameters, kinematics, and planner behavior remain owned by the
+vendored LinuxCNC runtime.
+
+## `createSessionSnapshotSummary(snapshot, fallbackLabel)`
+
+`snapshot` is the saved machine session snapshot loaded by the UI.
+`fallbackLabel` is the UI-selected label to prefer when present.
+
+The returned summary has this shape:
+
+```js
+{
+  snapshotLabel: "ui-machine-session/ui-machine-session.json",
+  workflow: "save-session-snapshot",
+  defaultGcodeOpfsPath: "linuxcnc/gcode/ui-session.ngc",
+  iniOpfsPath: "linuxcnc/machines/xyzab-tdr/machine.ini",
+  parameterOpfsPath: "linuxcnc/machines/xyzab-tdr/linuxcnc.var",
+  toolTableOpfsPath: "linuxcnc/machines/xyzab-tdr/tool.tbl",
+  gcodeOpfsPath: "linuxcnc/gcode/ui-session.ngc"
+}
+```
+
+## `createMachineSessionLoadSummary(session)`
+
+`session` is the loaded interpreter/session bridge result. The helper extracts
+the OPFS and WASM path mapping plus the captured parameter/tool-table result
+texts.
+
+The returned summary has this shape:
+
+```js
+{
+  iniOpfsPath: "linuxcnc/machines/xyzab-tdr/machine.ini",
+  iniWasmPath: "/work/session-machine.ini",
+  parameterOpfsPath: "linuxcnc/machines/xyzab-tdr/linuxcnc.var",
+  parameterWasmPath: "/work/session-linuxcnc.var",
+  parameterResult: "restore_parameters=0",
+  toolTableOpfsPath: "linuxcnc/machines/xyzab-tdr/tool.tbl",
+  toolTableWasmPath: "/work/session-tool.tbl",
+  toolTableResult: "tooldata_load=0"
+}
+```
+
+## Log Helpers
+
+- `sessionSnapshotSummaryLogLines(summary)` renders snapshot label, workflow,
+  and default G-code path.
+- `sessionSnapshotMetadataLogLines(summary)` renders the metadata subset used in
+  save/restore log summaries.
+- `machineSessionLoadLogLines(summary)` renders the interpreter/session
+  OPFS-to-WASM mapping and captured result lines.
+
+## 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 load result strings.
+- 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_session_summary.sh
+```
+
+The aggregate UI Node smoke is:
+
+```bash
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+```