# 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`.
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:

```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.