cnc_wams/wasm-port/docs/ui-panel-state-summary.md

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:

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

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

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

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

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

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

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

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:

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:

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