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.

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.