# 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.
`runtime/ui/ini-panel/session-workflow.js` contains the reusable UI workflows
for saving, restoring, loading, and restore-loading a machine session snapshot
as host-boundary operations.

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"
}
```

## `saveMachineSessionSnapshotWorkflow(input)`

The workflow writes the current INI/tool/parameter text files, writes the
default G-code program, saves the machine session snapshot, and returns the
snapshot summary, field state, and log lines for UI consumers.

The persistence functions are injected by the caller:

```js
{
  saveMachineTextFiles,
  saveGcodeProgram,
  saveMachineSessionSnapshot
}
```

## `restoreMachineSessionSnapshotWorkflow(input)`

The workflow loads the machine session snapshot, loads the persisted machine
text files so the editor can be restored, and optionally loads the machine
session into the interpreter WASM filesystem. The optional restore-load path
reuses `loadMachineSessionIntoWasmWorkflow()` so standalone load and
restore-load consumers share the same load summary, field state, and load log
line model.

When `loadSession` is omitted, the returned `fields` contain the OPFS snapshot
paths. When `loadSession` is supplied, the returned `fields` contain the loaded
WASM paths for INI/parameter/tool-table files and the snapshot G-code OPFS
path.

The returned object has this shape:

```js
{
  snapshot: { ... },
  editorIniText: "[EMC]\n...",
  summary: { snapshotLabel: "...", workflow: "save-session-snapshot" },
  fields: {
    sessionIni: "/work/session-machine.ini",
    sessionParameters: "/work/session-linuxcnc.var",
    sessionToolTable: "/work/session-tool.tbl",
    sessionGcode: "linuxcnc/gcode/ui-session.ngc",
    sessionSnapshot: "ui-machine-session/ui-machine-session.json"
  },
  loadSummary: { iniWasmPath: "/work/session-machine.ini" },
  loadedSession: { ... },
  logLines: [
    "Snapshot: ui-machine-session/ui-machine-session.json",
    "Workflow: save-session-snapshot",
    "Loaded machine session into the interpreter WASM filesystem."
  ]
}
```

The returned object has this shape:

```js
{
  snapshot: { ... },
  summary: { snapshotLabel: "...", workflow: "save-session-snapshot" },
  fields: {
    sessionIni: "linuxcnc/machines/xyzab-tdr/machine.ini",
    sessionParameters: "linuxcnc/machines/xyzab-tdr/linuxcnc.var",
    sessionToolTable: "linuxcnc/machines/xyzab-tdr/tool.tbl",
    sessionGcode: "linuxcnc/gcode/ui-session.ngc",
    sessionSnapshot: "ui-machine-session/ui-machine-session.json"
  },
  logLines: [
    "Snapshot: ui-machine-session/ui-machine-session.json",
    "Workflow: save-session-snapshot"
  ]
}
```

## 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.
- `sessionSnapshotSaveLogLines(summary)` renders the save-workflow snapshot
  paths used by the INI panel.
- `sessionSnapshotRestoreLogLines(summary)` renders the restore-workflow
  snapshot paths used by the INI panel.

## 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
wasm-port/tests/ui/node/verify_ini_panel_session_workflow.sh
```

The aggregate UI Node smoke is:

```bash
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
```