240 lines
8.7 KiB
Markdown
240 lines
8.7 KiB
Markdown
# 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.
|
|
For a ready-made read-only page, open
|
|
`runtime/ui/ini-panel/control-page.html`. It embeds the panel in a hidden iframe
|
|
and mirrors the same control view into the visible page.
|
|
The page uses `createMachineSessionControlPageController(...)` from
|
|
`runtime/ui/ini-panel/control-page-controller.js` so other read-only shells can
|
|
reuse the same iframe/API polling contract.
|
|
For a light navigation entry, open `runtime/ui/ini-panel/launch.html`.
|
|
Its entry list is defined in `runtime/ui/ini-panel/entry-manifest.js`.
|
|
For a single shell-facing import, use `runtime/ui/ini-panel/ui-shell.js`, which
|
|
re-exports the entry manifest, control page controller, and control view renderer.
|
|
For the short page/entry map, see `docs/panel-entry.md`.
|
|
|
|
## `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: "..." },
|
|
runReadiness: { phase: "ready", canRun: true, runButton: { enabled: true } },
|
|
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: "..." },
|
|
runReadiness: { phase: "ready", canRun: true, buttonEnabled: true, programOpfsPath: "..." },
|
|
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: "..." },
|
|
overview: { phase: "ran", missing: [], status: { lastAction: "run-gcode" } },
|
|
runReadiness: { phase: "ready", canRun: true, buttonEnabled: true },
|
|
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.
|
|
|
|
## `createMachineSessionWorkflowOverview(report)`
|
|
|
|
This helper folds the already-normalized report into a single read-only
|
|
workflow object for shell and control-page consumers:
|
|
|
|
```js
|
|
{
|
|
phase: "waiting" | "ready" | "ran",
|
|
missing: [],
|
|
readiness: { ini: "...", interp: "...", opfs: "..." },
|
|
session: { snapshotLabel: "...", workflow: "...", ini: "...", gcode: "..." },
|
|
loaded: { iniWasmPath: "...", parameterWasmPath: "...", toolTableWasmPath: "..." },
|
|
runReadiness: { phase: "ready", canRun: true },
|
|
run: { status: "ok", canonicalEventCount: 2, motionSnapshotCount: 2 },
|
|
status: { lastAction: "run-gcode", error: null }
|
|
}
|
|
```
|
|
|
|
It combines existing UI/host boundary facts only. It does not inspect G-code
|
|
or derive CNC behavior.
|
|
|
|
## `createMachineSessionStateBundle(state, options)`
|
|
|
|
This helper packages the current report, export payload, and workflow status
|
|
into one read-only object:
|
|
|
|
```js
|
|
{
|
|
report: { ... },
|
|
overview: { phase: "ran", missing: [] },
|
|
export: { filename: "...", mediaType: "application/json", report: { ... }, text: "{...}\n" },
|
|
workflowStatus: { readiness: { ... }, overview: { ... }, lastAction: "...", 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: "workflow", title: "Workflow", rows: [{ label: "Phase", value: "ran" }] },
|
|
{ id: "run", title: "Run", rows: [{ label: "Ready", value: "ready" }] }
|
|
]
|
|
}
|
|
```
|
|
|
|
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
|
|
```
|