150 lines
4.4 KiB
Markdown
150 lines
4.4 KiB
Markdown
# UI Run Summary Helpers
|
|
|
|
## Purpose
|
|
|
|
`runtime/ui/ini-panel/run-summary.js` contains small host-boundary helpers for
|
|
summarizing an INI panel G-code run.
|
|
`runtime/ui/ini-panel/run-workflow.js` contains the reusable UI workflow for
|
|
selecting the session/default G-code program, loading it from OPFS, staging it
|
|
into the interpreter WASM filesystem, invoking the LinuxCNC interpreter, and
|
|
returning run field/log state. These helpers are intentionally pure so browser
|
|
UI panels, SDK-facing wrappers, and Node smoke tests can share the same summary
|
|
shape without reading DOM text or parsing log output.
|
|
|
|
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.
|
|
|
|
## `createRunSummary(program, runtime, snapshot)`
|
|
|
|
`program` describes the host-selected program path mapping:
|
|
|
|
```js
|
|
{
|
|
source: "default" | "snapshot",
|
|
opfsPath: "linuxcnc/gcode/ui-session.ngc",
|
|
wasmPath: "/work/ui-session.ngc"
|
|
}
|
|
```
|
|
|
|
`runtime` describes already-observed runtime boundary results:
|
|
|
|
```js
|
|
{
|
|
runStatus: "ok",
|
|
snapshotLabel: "ui-machine-session/ui-machine-session.json",
|
|
iniWasmPath: "/work/session-machine.ini",
|
|
canonicalEventCount: 2,
|
|
motionSnapshotCount: 2
|
|
}
|
|
```
|
|
|
|
`snapshot` is the optional machine session snapshot loaded by the UI. The helper
|
|
reads only snapshot metadata such as `workflow` and `snapshotLabel`.
|
|
When `runtime.snapshotLabel` is present, it is used as the returned
|
|
`snapshotLabel`; otherwise the helper falls back to `snapshot.metadata.snapshotLabel`
|
|
and then `null`.
|
|
|
|
The returned summary has this shape:
|
|
|
|
```js
|
|
{
|
|
runStatus: "ok",
|
|
programSource: "snapshot",
|
|
snapshotLabel: "ui-machine-session/ui-machine-session.json",
|
|
workflow: "save-session-snapshot",
|
|
programOpfsPath: "linuxcnc/gcode/ui-session.ngc",
|
|
programWasmPath: "/work/ui-session.ngc",
|
|
iniWasmPath: "/work/session-machine.ini",
|
|
canonicalEventCount: 2,
|
|
motionSnapshotCount: 2
|
|
}
|
|
```
|
|
|
|
## `summarizeRunResult(resultText, snapshots)`
|
|
|
|
`resultText` is the raw text returned by the LinuxCNC interpreter WASM call.
|
|
`snapshots` is the UI's already-parsed motion snapshot list.
|
|
|
|
The helper returns:
|
|
|
|
```js
|
|
{
|
|
canonicalEventCount: 2,
|
|
motionSnapshotCount: 2
|
|
}
|
|
```
|
|
|
|
`canonicalEventCount` only counts result lines beginning with `canon_event=`.
|
|
`motionSnapshotCount` is only `snapshots.length`.
|
|
|
|
## `runGcodeSessionWorkflow(input)`
|
|
|
|
The workflow requires a loaded machine session and injected host/runtime
|
|
functions:
|
|
|
|
```js
|
|
{
|
|
interp,
|
|
loadedSession,
|
|
snapshot,
|
|
loadGcodeProgram,
|
|
gcodeFilenameFromProgramPath,
|
|
summarizeRun
|
|
}
|
|
```
|
|
|
|
It returns the selected program mapping, raw interpreter result text, run
|
|
summary, UI field state, log lines, and optional UI motion snapshots produced
|
|
by the injected `summarizeRun` callback:
|
|
|
|
```js
|
|
{
|
|
program: {
|
|
source: "snapshot",
|
|
opfsPath: "linuxcnc/gcode/ui-session.ngc",
|
|
wasmPath: "/work/ui-session.ngc",
|
|
text: "G0 X1\n"
|
|
},
|
|
resultText: "canon_event=...",
|
|
summary: { runStatus: "ok", programSource: "snapshot" },
|
|
fields: { runStatus: "ok", sessionGcode: "linuxcnc/gcode/ui-session.ngc" },
|
|
motionSnapshots: [{ line: 1 }],
|
|
logLines: ["Program: linuxcnc/gcode/ui-session.ngc -> /work/ui-session.ngc"]
|
|
}
|
|
```
|
|
|
|
`selectSessionGcodeProgram(input)` is the pure program-selection helper used by
|
|
the workflow. Invalid snapshot G-code paths fall back to the UI default program.
|
|
|
|
## 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 canonical events in JavaScript.
|
|
- Keep canonical-event and motion parsing in the existing UI display layer or
|
|
inject it as already-observed UI state; the workflow must not own CNC
|
|
semantics.
|
|
- Do not make UI helper output a promotion signal for runtime families blocked
|
|
by host dependencies.
|
|
- 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_run_summary.sh
|
|
wasm-port/tests/ui/node/verify_ini_panel_run_workflow.sh
|
|
```
|
|
|
|
The aggregate UI Node smoke is:
|
|
|
|
```bash
|
|
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
|
|
```
|
|
|
|
`wasm-port/tests/host/verify_host_smokes.sh` includes the UI Node smoke so these
|
|
helpers are also covered by the regular host/WASM/browser gate.
|