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

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:

{
  source: "default" | "snapshot",
  opfsPath: "linuxcnc/gcode/ui-session.ngc",
  wasmPath: "/work/ui-session.ngc"
}

runtime describes already-observed runtime boundary results:

{
  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. When runtime.snapshotLabel is present, it is used as the returned snapshotLabel; otherwise the helper falls back to snapshot.metadata.snapshotLabel and then null.

The returned summary has this shape:

{
  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:

{
  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:

wasm-port/tests/ui/node/verify_ini_panel_run_summary.sh

The aggregate UI Node smoke is:

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.