Files
cnc_wams/wasm-port/docs/panel-entry.md

371 lines
21 KiB
Markdown

# INI Panel Entry
This page is the short entry map for the INI panel UI shell.
## Shell Module
Use the shell-facing module when an outer UI needs entry links or a read-only
control view:
```js
import {
INI_PANEL_ENTRIES,
createControlPageBrowserApiManifest,
createControlPageBrowserApiMethods,
createControlPageBrowserApiSchema,
createIniPanelLaunchApiManifest,
createIniPanelLaunchApiSchema,
createIniPanelLauncherLinkViewModel,
createIniPanelShellControlPageContract,
createIniPanelShellIntegrationManifest,
createIniPanelShellIntegrationReadiness,
createIniPanelShellIntegrationSchema,
createIniPanelShellIntegrationWorkflowPlan,
createIniPanelShellSessionHandoffActionPlan,
createIniPanelShellSessionHandoffChecklist,
createIniPanelShellSessionHandoffCompatibilityReport,
createIniPanelShellSessionHandoffDisplayViewModel,
createIniPanelShellSessionHandoffPackage,
createIniPanelShellSessionHandoffPackageDisplayViewModel,
createIniPanelShellSessionHandoffPackageMountDisplayViewModel,
createIniPanelShellSessionHandoffPackageMountRenderState,
createIniPanelShellSessionHandoffPackageMountState,
createIniPanelShellSessionHandoffMountDomContract,
createIniPanelShellSessionHandoffMountDomReadiness,
mountIniPanelShellSessionHandoff,
mountIniPanelShellSessionHandoffFromControlPage,
createIniPanelShellSessionHandoffWorkflowSummary,
createIniPanelShellSessionHandoffWorkflowDisplayViewModel,
createIniPanelShellSessionHandoffWorkflowRenderState,
createIniPanelShellSessionHandoffWorkflowDomContract,
createIniPanelShellSessionHandoffWorkflowDomReadiness,
createIniPanelShellWorkflowOverviewContract,
createIniPanelShellWorkflowOverviewReadiness,
createIniPanelShellWorkflowOverviewEmbeddingReport,
createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel,
createIniPanelShellWorkflowOverviewEmbeddingRenderState,
createIniPanelShellWorkflowOverviewEmbeddingDomContract,
mountIniPanelShellWorkflowOverviewEmbedding,
renderIniPanelShellSessionHandoffWorkflowState,
mountIniPanelShellSessionHandoffWorkflow,
renderIniPanelShellSessionHandoffMountState,
createIniPanelShellSessionHandoffPackageReport,
createIniPanelShellSessionHandoffPackageRenderState,
createIniPanelShellSessionHandoffPackageSchema,
createIniPanelShellSessionHandoffRenderState,
createIniPanelShellSessionHandoffSnapshot,
createIniPanelShellSessionHandoffSummary,
createIniPanelShellSessionHandoffSummarySchema,
createIniPanelShellViewModel,
getIniPanelEntryByHref,
getVisibleIniPanelEntries,
createMachineSessionControlPageController,
createMachineSessionReadonlyStatus,
createMachineSessionReadonlyStatusApiManifest,
readMachineSessionReadonlyStatus,
loadMachineSessionForControlPageWorkflow,
createControlPageSessionLoadState,
refreshMachineSessionControlPage,
controlPageStatusText,
renderMachineSessionControlView,
isSupportedIniPanelControlPageApiManifest,
isSupportedIniPanelLaunchApiManifest,
isSupportedIniPanelShellIntegrationManifest,
isSupportedIniPanelShellSessionHandoffPackage,
isSupportedIniPanelShellSessionHandoffSummary,
} from "../runtime/ui/ini-panel/ui-shell.js";
```
`ui-shell.js` re-exports the entry manifest, the read-only control-page
controller, the unified read-only status API, the readonly-status API manifest,
and the control-view renderer. It does not implement CNC behavior.
## Pages
| Page | Path | Role |
| --- | --- | --- |
| Launch | `runtime/ui/ini-panel/launch.html` | Read-only entry page for available panel surfaces. |
| Edit and run | `runtime/ui/ini-panel/index.html` | Editable INI panel and existing run workflow surface. |
| Read-only control view | `runtime/ui/ini-panel/control-page.html` | Read-only control view backed by the panel API. |
| Workflow overview | `runtime/ui/ini-panel/workflow-overview.html` | Read-only shell handoff workflow overview surface. |
## Visible Entries
The visible launch entries come from `getVisibleIniPanelEntries()`:
| Entry id | Href | Title |
| --- | --- | --- |
| `edit-run` | `./index.html` | Open edit and run panel |
| `control-view` | `./control-page.html` | Open read-only control view |
| `workflow-overview` | `./workflow-overview.html` | Open shell handoff overview |
Launcher pages can render links from `createIniPanelLauncherLinkViewModel()`
without reading manifest field names directly. Each item has `entryId`, `href`,
and `label`.
Outer shells can call `createIniPanelShellViewModel()` when they need one
read-only model with `pages`, `launcherLinks`, and `controlPage` helpers for
mounting the existing control-page controller, refresh workflow, and renderer.
Use `controlPage.readStatus` or `readMachineSessionReadonlyStatus()` when an
outer shell needs one stable read of `stateBundle`, `workflowStatus`,
`overview`, `controlView`, `session`, `runReadiness`, and `run`.
Use `createMachineSessionReadonlyStatusApiManifest()` or
`controlPage.readonlyStatusApiManifest` when you only need the API shape and
method names.
Use `createIniPanelShellControlPageContract()` or `controlPage.contract` when
an outer shell needs a fast contract check for `createController`,
`loadSessionState`, `readStatus`, `refresh`, `renderView`, the readonly status
manifest, and its status fields before mounting the embedded panel. The
contract lists readonly status fields for `stateBundle`, `workflowStatus`,
`overview`, `controlView`, `report`, `runReadiness`, `run`, `session`, and
`status`.
The browser control page also exposes this contract through
`linuxCncIniPanelControlPageApi.getControlPageContract()`, so real iframe-based
smokes can verify the same API shape before reading the embedded panel state.
Use `linuxCncIniPanelControlPageApi.getControlPageApiMethods()` when a browser
outer page needs the exact exposed method list before calling the read-only
control page API.
Use `createControlPageBrowserApiSchema()`,
`createControlPageBrowserApiManifest()`, or
`linuxCncIniPanelControlPageApi.getControlPageApiSchema()` and
`linuxCncIniPanelControlPageApi.getControlPageApiManifest()` when a browser
outer page needs a versioned control-page API description before reading the
embedded panel. Use `isSupportedIniPanelControlPageApiManifest()` or
`linuxCncIniPanelControlPageApi.isSupportedControlPageApiManifest()` for a
read-only compatibility predicate before consuming that manifest.
Use `linuxCncIniPanelControlPageApi.readControlPageStatus()` when a browser
outer page needs the same readonly status snapshot from the real embedded
control page after save/load session workflows.
The launch page exposes `linuxCncIniPanelLaunchApi.getControlPageApiMethods()`
from the same shell view-model so entry pages can consume the available
read-only control-page API list without loading the control-page iframe first.
Use `createIniPanelLaunchApiManifest()` or
`linuxCncIniPanelLaunchApi.getLaunchApiManifest()` when an outer shell needs a
single read-only description of launch methods, visible entries, target pages,
the control-page browser API methods, and OPFS/session persistence capabilities
for machine files, session snapshots, and read-only status.
Use `createIniPanelLaunchApiSchema()`,
`linuxCncIniPanelLaunchApi.getLaunchApiSchema()`, or `manifestVersion` when an
outer shell needs to check launch manifest compatibility before consuming these
fields.
Use `isSupportedIniPanelLaunchApiManifest()` or
`linuxCncIniPanelLaunchApi.isSupportedLaunchApiManifest()` for a read-only
compatibility predicate before using a launch manifest.
Use `createIniPanelShellIntegrationSchema()`,
`createIniPanelShellIntegrationManifest()`,
`linuxCncIniPanelLaunchApi.getShellIntegrationSchema()`, or
`linuxCncIniPanelLaunchApi.getShellIntegrationManifest()` when an outer shell
needs one versioned read of pages, launcher links, launch API metadata,
control-page API metadata, OPFS/session persistence capabilities, and current
compatibility status. Use `isSupportedIniPanelShellIntegrationManifest()` when
the outer shell needs to check that integration manifest before consuming it.
Use `createIniPanelShellIntegrationReadiness()` or
`linuxCncIniPanelLaunchApi.getShellIntegrationReadiness()` when the outer shell
needs a read-only `ready`/`blocked` status, failed check names, API names, and
counts for pages, methods, and persistence capabilities before mounting any
embedded control page.
Use `createIniPanelShellIntegrationWorkflowPlan()` when the outer shell needs a
Node-testable read-only plan for the control-page target, required launch and
control-page API methods, readiness gate, and readonly status handoff fields
before opening a browser frame.
Use `createIniPanelShellSessionHandoffSummary()` when the outer shell needs one
read-only display summary of readiness, target page, persistence capabilities,
readonly status fields, handoff methods, and blocking reasons. Browser shells
can read the same summary through
`linuxCncIniPanelLaunchApi.getShellSessionHandoffSummary()`.
Use `createIniPanelShellSessionHandoffSummarySchema()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffSummarySchema()` for the
versioned summary shape, and `isSupportedIniPanelShellSessionHandoffSummary()`
or `linuxCncIniPanelLaunchApi.isSupportedShellSessionHandoffSummary()` before
consuming a summary from a browser shell.
Use `createIniPanelShellSessionHandoffCompatibilityReport()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffCompatibilityReport()` when an
outer shell needs display-ready diagnostics for schema support, missing fields,
api/version mismatches, and current blocking reasons before consuming the
handoff summary.
Use `createIniPanelShellSessionHandoffDisplayViewModel()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffDisplayViewModel()` when an
outer shell needs the same diagnostics as stable read-only label/value rows for
DOM display.
Use `createIniPanelShellSessionHandoffSnapshot()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffSnapshot()` when an outer shell
needs one read-only API read that includes readiness, handoff summary,
compatibility report, and display view-model together.
Use `createIniPanelShellSessionHandoffRenderState()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffRenderState()` when an outer
shell needs the snapshot compressed into launch-side DOM state with a status
line, stable rows, and `[data-handoff-shell]` phase/readiness flags. The launch
page renders `[data-handoff-status]` and `[data-handoff-rows]` from this helper
without adding control actions.
Use `createIniPanelShellSessionHandoffActionPlan()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffActionPlan()` when an outer
shell needs a read-only next-step description derived from the same snapshot:
target page, required readonly methods, blocking reasons, display rows, and
ready/blocked next step ids. The action plan describes what an outer shell can
do next; it does not execute actions or add controls.
Use `createIniPanelShellSessionHandoffChecklist()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffChecklist()` when an outer
shell needs the same handoff state as stable health rows for display: render
state, target page, load-session method, read-status method, blocking reasons,
display rows, and next step ids. The checklist is read-only and does not
execute the action plan.
Use `createIniPanelShellSessionHandoffPackage()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffPackage()` when an outer shell
needs one browser API read containing the launch/control method manifests,
snapshot, render-state, action-plan, and checklist. The package is a read-only
handoff artifact and does not execute action-plan steps.
Use `createIniPanelShellSessionHandoffPackageSchema()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffPackageSchema()` for the
versioned package shape, and `isSupportedIniPanelShellSessionHandoffPackage()`
or `linuxCncIniPanelLaunchApi.isSupportedShellSessionHandoffPackage()` before
consuming a package from a browser shell.
Use `createIniPanelShellSessionHandoffPackageReport()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffPackageReport()` when an outer
shell needs display-ready diagnostics for package schema support, missing
package fields, missing manifest fields, api/version mismatches, and checklist
blocking reasons.
Use `createIniPanelShellSessionHandoffPackageDisplayViewModel()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffPackageDisplayViewModel()`
when an outer shell needs the package report compressed into stable read-only
label/value rows for DOM display.
Use `createIniPanelShellSessionHandoffPackageRenderState()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffPackageRenderState()` when an
outer shell needs the package display view-model compressed into launch-side
DOM state. The launch page renders `[data-handoff-status]` and
`[data-handoff-rows]` from the package render-state so the first page shows
package-level schema/report status.
Use `createIniPanelShellSessionHandoffPackageMountState()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffPackageMountState()` when an
outer shell needs one read-only mount-state that combines package render-state,
the control-page target, required readonly methods, and the current
control-page session readiness snapshot.
Use `createIniPanelShellSessionHandoffPackageMountDisplayViewModel()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffPackageMountDisplayViewModel()`
when an outer shell needs mount-state checks as stable read-only label/value
rows. Use `createIniPanelShellSessionHandoffPackageMountRenderState()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffPackageMountRenderState()`
when those rows need a status line and `[data-handoff-shell]` style dataset
flags for DOM rendering. Use
`createIniPanelShellSessionHandoffMountDomContract()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffMountDomContract()` when an
outer shell needs the required mount/status/rows selectors, mount dataset keys,
row dataset keys, and render-result fields before rendering into shell-owned
DOM. Use `createIniPanelShellSessionHandoffMountDomReadiness()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffMountDomReadiness()` to check
that the required document and nodes exist before calling the renderer. Use
`mountIniPanelShellSessionHandoff()` or
`linuxCncIniPanelLaunchApi.mountShellSessionHandoff()` when an outer shell
needs one browser-side workflow result containing the contract, DOM readiness,
mount render-state, renderer result, and any mount error as data. Use
`mountIniPanelShellSessionHandoffFromControlPage()` or
`linuxCncIniPanelLaunchApi.mountShellSessionHandoffFromControlPage()` when an
outer shell has a control-page API or already-observed session-load state and
needs one read-only result containing the derived mount-state, mount display
view-model, mount render-state, and DOM mount workflow result. Use
`readIniPanelShellSessionHandoffStatusFromControlPage()` or
`linuxCncIniPanelLaunchApi.readShellSessionHandoffStatusFromControlPage()`
when an outer shell needs to read the control-page readonly status and verify
the expected handoff status fields as a structured ready/blocked result. Use
`createIniPanelShellSessionHandoffWorkflowSummary()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffWorkflowSummary()` when an
outer shell needs one stable end-to-end summary that combines mount workflow,
control-page mount workflow, readonly status result, and current blocking
reasons into display rows. Use
`createIniPanelShellSessionHandoffWorkflowDisplayViewModel()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffWorkflowDisplayViewModel()`
when an outer shell needs that end-to-end summary compressed into stable
`title`, `statusText`, `detailText`, and rows for direct display. Use
`createIniPanelShellSessionHandoffWorkflowRenderState()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffWorkflowRenderState()` when an
outer shell needs that workflow display-model compressed into stable
`dataset`, `statusLine`, and rows for direct DOM rendering. Use
`createIniPanelShellSessionHandoffWorkflowDomContract()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffWorkflowDomContract()` when an
outer shell needs the required workflow mount/status/rows selectors, mount
dataset keys, and row dataset keys before rendering workflow overview DOM. Use
`createIniPanelShellSessionHandoffWorkflowDomReadiness()` or
`linuxCncIniPanelLaunchApi.getShellSessionHandoffWorkflowDomReadiness()` to
check that those workflow DOM nodes exist before rendering. Use
`renderIniPanelShellSessionHandoffWorkflowState()` or
`linuxCncIniPanelLaunchApi.renderShellSessionHandoffWorkflowState()` when an
outer shell needs the shared read-only DOM renderer for workflow overview rows.
Use `mountIniPanelShellSessionHandoffWorkflow()` or
`linuxCncIniPanelLaunchApi.mountShellSessionHandoffWorkflow()` when an outer
shell needs one structured workflow DOM mount result containing contract,
readiness, render-state, render result, and any mount error as data. Use
`createIniPanelShellWorkflowOverviewContract()` or
`linuxCncIniPanelLaunchApi.getWorkflowOverviewContract()` when an outer shell
needs the `workflow-overview.html` page href, browser API namespace, and method
names before embedding that page. Use
`createIniPanelShellWorkflowOverviewReadiness()` or
`linuxCncIniPanelLaunchApi.getWorkflowOverviewReadiness()` to check whether a
loaded workflow overview iframe exposes the expected read-only API. Use
`mountIniPanelShellWorkflowOverviewEmbedding()` or
`linuxCncIniPanelLaunchApi.mountWorkflowOverviewEmbedding()` when an outer
shell needs one structured embedding result containing contract readiness,
render-state, workflow overview mount result, and any mount error as data. The
workflow overview page also exposes
`linuxCncIniPanelWorkflowOverviewApi.mountWorkflowOverviewEmbedding()` for the
same read-only embedding path from inside the iframe. Use
`createIniPanelShellWorkflowOverviewEmbeddingReport()` or
`linuxCncIniPanelLaunchApi.getWorkflowOverviewEmbeddingReport()` when an outer
shell needs display-ready diagnostics for overview API readiness, missing
methods, embedding readiness, mount phase, render row count, and embedding
errors. The workflow overview page also exposes
`linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewEmbeddingReport()` for
the same report shape. Use
`createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel()` or
`linuxCncIniPanelLaunchApi.getWorkflowOverviewEmbeddingDisplayViewModel()` when
an outer shell needs that report compressed into stable `title`, `statusText`,
`detailText`, and read-only label/value rows for direct rendering. The workflow
overview page also exposes
`linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewEmbeddingDisplayViewModel()`.
Use `createIniPanelShellWorkflowOverviewEmbeddingRenderState()` or
`linuxCncIniPanelLaunchApi.getWorkflowOverviewEmbeddingRenderState()` when an
outer shell needs that display view-model compressed into stable `statusLine`,
`dataset`, and rows for a shared DOM renderer. The workflow overview page also
exposes `linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewEmbeddingRenderState()`.
Use `createIniPanelShellWorkflowOverviewEmbeddingDomContract()` or
`linuxCncIniPanelLaunchApi.getWorkflowOverviewEmbeddingDomContract()` when an
outer shell needs the required embedding report mount/status/rows selectors,
mount dataset keys, row dataset keys, and render-result fields before adding a
DOM renderer. The workflow overview page also exposes
`linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewEmbeddingDomContract()`.
Use
`renderIniPanelShellSessionHandoffMountState()` or
`linuxCncIniPanelLaunchApi.renderShellSessionHandoffMountState()` when an outer
shell needs the shared read-only DOM renderer for those rows. The launch page
renders the default waiting mount state into `[data-handoff-mount]`,
`[data-handoff-mount-status]`, and `[data-handoff-mount-rows]` without opening
the control page. The launch page also renders a default workflow overview into
`[data-handoff-workflow]`, `[data-handoff-workflow-status]`, and
`[data-handoff-workflow-rows]`.
The browser workflow smoke
`tests/browser/ini_panel_shell_integration_workflow_smoke.html` verifies the
same external shell handoff: read integration manifest, pass readiness gate,
open the control page target, mount waiting and ready mount-state into an
external shell-owned `[data-external-shell-mount]` DOM region through the shared
mount workflows, then read and validate readonly machine-session status through
the shared status workflow.
The control-page refresh workflow lives in
`runtime/ui/ini-panel/control-page-refresh-workflow.js`. Use
`refreshMachineSessionControlPage()` when an outer shell needs a structured
refresh result with `phase`, `statusText`, `view`, `renderResult`, and `error`.
`controlPageStatusText()` formats the already-observed panel status fields for
the read-only status line, and `createControlPageRefreshState()` is the stable
state-shape helper used by the workflow.
The control-page session workflow lives in
`runtime/ui/ini-panel/control-page-session-workflow.js`. Use
`loadMachineSessionForControlPageWorkflow()` when an outer shell needs a
read-only readiness snapshot for the embedded panel API and first control view.
`createControlPageSessionLoadState()` is the stable state-shape helper for
`waiting-panel`, `waiting-api`, `waiting-session`, `ready`, and `error` phases.
## Boundary
The entry shell only links pages and renders already-observed panel state. It
does not parse G-code, infer canonical events, or implement LinuxCNC-owned
tool, parameter, planner, or kinematics behavior.