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.

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.

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