# UI Panel State Summary

## Purpose

`runtime/ui/ini-panel/panel-state-summary.js` contains a pure helper for
bundling the already-observed host/runtime boundary state of the INI panel into
a single machine-readable snapshot.

The helper does not implement CNC behavior. It only packages the summary
objects produced by the run/session/machine-file helpers and the visible badge
state so browser tests or future UI consumers can compare panel state without
reading ad hoc DOM text.

Upper-level UI/API consumers should read `createMachineSessionStateReport(...)`
or `window.linuxCncIniPanelApi.getMachineSessionStateReport()` rather than
scraping DOM nodes or depending on `window.linuxCncIniPanelMachineSessionState`
directly. The legacy `window.getMachineSessionStateReport()` and
`window.getMachineSessionStateReportExport()` globals remain as compatibility
shims.

For control-page polling, use
`window.linuxCncIniPanelApi.getMachineSessionWorkflowStatus()`. It returns a
smaller workflow-facing object derived from the same report data.
For a single read call, use `window.linuxCncIniPanelApi.getMachineSessionStateBundle()`.
For direct rendering, use `window.linuxCncIniPanelApi.getMachineSessionControlView()`.
The panel also exposes
`window.linuxCncIniPanelApi.renderMachineSessionControlView(container)`, which
renders the current view into a supplied DOM container.

## `createIniPanelStateSummary(input)`

`input` may contain:

```js
{
  badges: { ini: "INI WASM: ready", interp: "Interpreter WASM: ready", opfs: "OPFS: ready" },
  machine: { machine: "xyzab-tdr", kinematics: "trivkins" },
  machineFiles: { iniOpfsPath: "...", toolTableOpfsPath: "...", parameterOpfsPath: "...", gcodeOpfsPath: "..." },
  sessionSnapshot: { snapshotLabel: "...", workflow: "save-session-snapshot" },
  sessionLoad: { iniOpfsPath: "...", iniWasmPath: "..." },
  run: { runStatus: "ok", programSource: "snapshot" },
  fiveaxisRemap: "ok"
}
```

The returned snapshot preserves those nested objects and normalizes missing
badge entries to `null`.

## `createMachineSessionStateSnapshot(input)`

This helper builds the richer state snapshot used by the INI panel and exposed
as `window.linuxCncIniPanelMachineSessionState`.

It preserves the base panel state and adds:

```js
{
  selectedProgram: { source: "snapshot", opfsPath: "...", wasmPath: "..." },
  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",
    runStatus: "ok",
    runSource: "snapshot",
    runSnapshot: "ui-machine-session/ui-machine-session.json",
    runWorkflow: "save-session-snapshot",
    runOpfsPath: "linuxcnc/gcode/ui-session.ngc",
    runWasmPath: "/work/ui-session.ngc"
  },
  lastAction: "run-gcode",
  error: null
}
```

The INI panel updates this state after save, restore, load, run, and error
paths so browser tests and future API consumers can read one machine-readable
state object instead of collecting DOM fields and log text.

## `createMachineSessionStateReport(state)`

This helper converts the richer state snapshot into a stable consumer report
with four sections:

```js
{
  readiness: { ini: "...", interp: "...", opfs: "..." },
  session: { snapshotLabel: "...", workflow: "...", ini: "...", parameters: "...", toolTable: "...", gcode: "..." },
  loaded: { iniWasmPath: "...", parameterWasmPath: "...", toolTableWasmPath: "..." },
  program: { source: "snapshot", opfsPath: "...", wasmPath: "..." },
  run: { status: "ok", canonicalEventCount: 2, motionSnapshotCount: 2, iniWasmPath: "..." },
  status: { lastAction: "run-gcode", error: null, fiveaxisRemap: "ok" }
}
```

The report is intended for upper-level UI consumers or export paths that want a
stable summary shape without touching DOM nodes.

## `createMachineSessionStateReportExport(state, options)`

This helper wraps the report in a stable export payload:

```js
{
  filename: "machine-session-state-report.json",
  mediaType: "application/json",
  report: { ... },
  text: "{\n  ...\n}\n"
}
```

It is a small export-layer helper for future copy/download/UI SDK wrappers.

## `createMachineSessionWorkflowStatus(state)`

This helper derives a lightweight status object for upper-level control pages:

```js
{
  readiness: { ini: "...", interp: "...", opfs: "..." },
  lastAction: "run-gcode",
  error: null,
  session: { snapshotLabel: "...", workflow: "...", gcode: "..." },
  run: { status: "ok", canonicalEventCount: 2, motionSnapshotCount: 2, iniWasmPath: "..." }
}
```

It is intended for polling or status panels that need current UI workflow
state without parsing logs, DOM nodes, or transient window state.

## `createMachineSessionStateBundle(state, options)`

This helper packages the current report, export payload, and workflow status
into one read-only object:

```js
{
  report: { ... },
  export: { filename: "...", mediaType: "application/json", report: { ... }, text: "{...}\n" },
  workflowStatus: { readiness: { ... }, lastAction: "...", error: null, session: { ... }, run: { ... } }
}
```

It is the preferred single-entry helper for control-page polling and other
upper-level UI consumers that want one stable read instead of stitching the
three views together themselves.

## `createMachineSessionControlView(bundle)`

This helper maps a bundle into UI-ready status and sections:

```js
{
  status: { lastAction: "run-gcode", error: null, runStatus: "ok" },
  sections: [
    { id: "readiness", title: "Readiness", rows: [{ label: "INI", value: "..." }] },
    { id: "session", title: "Session", rows: [{ label: "Workflow", value: "..." }] },
    { id: "run", title: "Run", rows: [{ label: "Canonical events", value: 2 }] }
  ]
}
```

It is a presentation mapping over the bundle only. It does not parse G-code,
canonical events, or LinuxCNC-owned runtime content.

A minimal read-only browser consumer can render the sections directly:

```js
window.linuxCncIniPanelApi.renderMachineSessionControlView(
  document.getElementById("machine-session-control-view"),
);
```

Consumers should treat `rows` as display data and keep actions wired through
explicit workflow APIs instead of deriving behavior from labels.

For external pages that only have a view object, import the pure renderer:

```js
import { renderMachineSessionControlView } from "./control-view-renderer.js";

renderMachineSessionControlView(container, view);
```

## Boundary Rules

- Do not parse G-code text in this helper.
- Do not infer CNC semantics from the nested summaries.
- Keep the helper as a bundling layer over already-observed UI boundary state.
- Keep workflow result objects as host/runtime boundary facts; this helper must
  not promote, reinterpret, or synthesize CNC behavior.

## Validation

The helper is covered by:

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