cnc_wams/wasm-port/runtime/sdk/README.md

# LinuxCNC WASM SDK

This SDK exposes browser/Node JavaScript wrappers for standalone WASM modules
built from vendored LinuxCNC source.

## Boundary

The SDK is a host-boundary layer only. It may:

- load generated Emscripten modules;
- allocate and free C strings;
- write text files into the Emscripten filesystem;
- call exported C ABI functions;
- return LinuxCNC-produced text output to JavaScript callers.

The SDK must not implement G-code interpretation, canonical motion behavior,
tool semantics, parameter semantics, kinematics, or planner behavior. Those
behaviors must continue to come from vendored LinuxCNC source through the C ABI.

## Entrypoints

Use `src/index.js` for stable imports:

```js
import {
  INI_PANEL_ENTRIES,
  analyzeIniRuntimeBoundaries,
  createControlPageBrowserApiManifest,
  createControlPageBrowserApiMethods,
  createControlPageBrowserApiSchema,
  createIniPanelLaunchApiManifest,
  createIniPanelLauncherLinkViewModel,
  createIniPanelShellApiSurfaceInventory,
  createIniPanelShellControlPageContract,
  createIniPanelShellIntegrationManifest,
  createIniPanelShellIntegrationReadiness,
  createIniPanelShellIntegrationSchema,
  createIniPanelShellIntegrationWorkflowPlan,
  createIniPanelShellSessionReadinessWorkflowReport,
  createIniPanelShellViewModel,
  createIniPanelShellWorkflowOverviewContract,
  createIniPanelShellWorkflowOverviewEmbeddingMountDomContract,
  createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactDisplayViewModel,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactDomContract,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactDomReadiness,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryDomContract,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryDomReadiness,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryRenderState,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryViewModel,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowActionPlan,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowDomContract,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowDomReadiness,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowRenderState,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowSummaryViewModel,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactRenderState,
  runIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflow,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlGateExecutionSummaryViewModel,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlan,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowDomContract,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowDomReadiness,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowRenderState,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowSummaryViewModel,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlan,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanDomContract,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanDomReadiness,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanRenderState,
  createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationSummaryViewModel,
  VIRTUAL_HAL_COMMAND_SCRIPT_FIXTURES,
  VIRTUAL_HAL_COVERAGE_STATES,
  VIRTUAL_HAL_MOTION_CONTROLLER_MATRIX_FIXTURES,
  VIRTUAL_HAL_PROJECT_PIN_GROUPS,
  VIRTUAL_HAL_SIM_CONFIG_INVENTORY_ARTIFACT_HASHES,
  VIRTUAL_HAL_SIM_CONFIG_INVENTORY_BASELINE,
  VIRTUAL_HAL_SIM_CONFIG_EVIDENCE_EXPANSION_CANDIDATES,
  VIRTUAL_HAL_SIM_CONFIG_SOURCE_TARGETS,
  VIRTUAL_HAL_SOURCE_DERIVED_CAPABILITIES,
  VIRTUAL_HAL_SIMULATION_REPLACEMENT_TARGETS,
  VIRTUAL_HAL_SIMULATION_RUNTIME_CAPABILITIES,
  VIRTUAL_HAL_SOURCE_FILES,
  VIRTUAL_HAL_SYSTEM_PIN_FAMILIES,
  VIRTUAL_HAL_WASM_BRIDGE_FUNCTIONS,
  applyVirtualHalAction,
  applyVirtualHalPinUpdates,
  applyVirtualHalToInterpSdk,
  createLinuxCncIniSdk,
  createLinuxCncInterpSdk,
  createLinuxCncVirtualHalRuntime,
  createVirtualHalCommandScriptFixtureReport,
  createVirtualHalMotionControllerMatrixReport,
  createMachineSessionPersistenceDisplayViewModel,
  createMachineSessionPersistenceRenderState,
  createMachineSessionPersistenceSummary,
  createVirtualHalBridgeActionPlan,
  createVirtualHalBridgeReadiness,
  createVirtualHalIntegrityReport,
  createVirtualHalPinInventory,
  createVirtualHalPinRegistry,
  createVirtualHalProjectReport,
  createVirtualHalSimConfigEvidenceExpansionReport,
  createVirtualHalSimConfigSourceCoverageReport,
  createVirtualHalSimulationReplacementReport,
  createVirtualHalSimulationRuntimeReport,
  createVirtualHalSourceComplianceReport,
  createVirtualHalState,
  createVirtualHalSystemCoverageReport,
  createVirtualHalWasmBridgeSnapshot,
  executeVirtualHalCommand,
  executeVirtualHalcmd,
  readVirtualHalPin,
  stepVirtualHalMotion,
  stepVirtualHalMotionController,
  writeVirtualHalPin,
  createMachineSessionSnapshotPayload,
  createVirtualHalSessionPayload,
  createProjectReleaseGateActionPlan,
  createProjectReleaseGateExecutionManifest,
  createProjectReleaseGateExecutionSummaryViewModel,
  createProjectReleaseGateManifest,
  createProjectReleaseGateResultMatrix,
  createProjectReleaseReadinessArtifactJsonWorkflow,
  createProjectReleaseReadinessArtifactUrlWorkflowActionPlan,
  createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel,
  createProjectReleaseReadinessArtifactValidation,
  createProjectReleaseReadinessArtifactValidationActionPlan,
  createProjectReleaseReadinessArtifactValidationSummaryViewModel,
  createProjectReleaseReadinessReport,
  createProjectReleaseReadinessSummaryViewModel,
  createSessionSnapshot,
  defaultMachinePaths,
  gcodeFilenameFromProgramPath,
  gcodeProgramPath,
  getIniPanelEntryByHref,
  getIniPanelEntryManifest,
  getOpfsRoot,
  getVisibleIniPanelEntries,
  isSupportedIniPanelControlPageApiManifest,
  isSupportedIniPanelLaunchApiManifest,
  isSupportedIniPanelShellIntegrationManifest,
  loadIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrl,
  loadProjectReleaseReadinessArtifactUrlWorkflow,
  loadMachineSessionFromOpfs,
  loadMachineSessionSnapshot,
  loadMachineTextFiles,
  loadMachineToolTableFromOpfs,
  loadTextFile,
  machineFilePaths,
  machineIniPath,
  mountIniPanelShellWorkflowOverviewEmbeddingMountState,
  mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryState,
  mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowState,
  mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowState,
  mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanState,
  mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactState,
  normalizeOpfsPath,
  parameterFilePath,
  parseProjectReleaseReadinessArtifactJson,
  planIniFileContextStaging,
  planSimConfigStaging,
  createProjectBatchAcceptanceActionPlan,
  createProjectBatchAcceptanceCapabilityMatrix,
  createProjectBatchAcceptanceChecklist,
  createProjectBatchAcceptanceReport,
  createProjectBatchAcceptanceReportJsonWorkflow,
  createProjectBatchAcceptanceReportUrlWorkflowActionPlan,
  createProjectBatchAcceptanceReportUrlWorkflowSummaryViewModel,
  createProjectBatchAcceptanceReportValidationActionPlan,
  createProjectBatchAcceptanceReportValidationSummaryViewModel,
  createProjectBatchAcceptanceReportValidation,
  createProjectBatchAcceptanceSummaryViewModel,
  createProjectBatchAcceptanceWorkflow,
  loadProjectBatchAcceptanceReportUrlWorkflow,
  createProjectReleaseBrowserDiagnosticsArtifactValidation,
  readMachineSessionReadiness,
  restoreVirtualHalStateFromSessionSnapshot,
  renderIniPanelShellWorkflowOverviewEmbeddingMountState,
  renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryState,
  renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowState,
  renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowState,
  renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanState,
  renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactState,
  restoreMachineParametersFromOpfs,
  saveMachineSessionSnapshot,
  saveMachineTextFiles,
  saveSessionSnapshot,
  saveTextFile,
  sessionSnapshotPath,
  toolTablePath,
  validateIniPanelShellWorkflowOverviewReleaseReadinessArtifactJson,
  validateSessionSnapshot,
} from "./src/index.js";
```

`createLinuxCncIniSdk()` wraps the INI parser module built from vendored
LinuxCNC `inifile.cc` and exposes `getString()` plus `getBool()`. Boolean
conversion is performed by vendored LinuxCNC `iniFindBool()`.

`createLinuxCncInterpSdk()` wraps the interpreter-core module built from
vendored LinuxCNC RS274NGC sources and exposes:

- `runProgram(programText)`
- `runProgramWithIni(programText, iniPath)`
- `runFile(path)`
- `runFileWithIni(path, iniPath)`
- `runFileWithIniContinueOnError(path, iniPath)`
- `runSimConfigProgram({ iniPath, programPath, files, executionMode })`
- `runFiveAxisRemapFile(path, iniPath)`
- `runRemapFile(path, iniPath)`
- `runRemapIoMdiSequence(iniPath)`
- `restoreParameters(path)`
- `saveParameters(path, values)`
- `loadToolTable(path, options)`
- `saveToolTable(path)`
- `writeTextFile(path, text)`
- `readTextFile(path)`

`loadToolTable()` accepts `{ randomToolChanger: true }` to select the
LinuxCNC random-toolchanger branch before calling vendored
`tooldata_load()`. The SDK only forwards that runtime boundary flag.

`runFiveAxisRemapFile()` is a narrow host boundary for vendored LinuxCNC
sample-machine remap validation. Callers provide INI/remap/demo files in the
WASM filesystem; the C ABI runs vendored LinuxCNC `REMAP`, O-word, file
execution, and HAL adapter paths.

`runRemapFile()` is the generic remap-test equivalent for vendored LinuxCNC
tests such as `tests/remap/duplicate-o-word`. It reads LinuxCNC INI
`SUBROUTINE_PATH` and `REMAP` entries, then calls vendored LinuxCNC
`Interp::parse_remap()`, `open()`, `read()`, and `execute()`.

`runRemapIoMdiSequence()` is a narrow regression boundary for the NGC-only
branch of vendored LinuxCNC `tests/remap/remap-io/test-ngc.ini`. The C ABI
reads LinuxCNC `REMAP` entries, then feeds the upstream test driver's MDI
command sequence into vendored `Interp::execute()`. JavaScript only copies the
vendored INI/subroutine files into the WASM filesystem and forwards the INI
path; it does not implement M62-M68, M66 input, or remap semantics.

`runFileWithIni()` is the plain interpreter-file equivalent for upstream tests
that need LinuxCNC INI search paths, such as
`tests/interp/sub-call-from-sub`. The C ABI reads LinuxCNC
`SUBROUTINE_PATH` and then calls vendored `Interp::open()`, `read()`, and
`execute()`; the SDK only copies files and forwards paths.

`runSimConfigProgram()` is a convenience host boundary for representative
LinuxCNC `configs/sim` programs. Callers provide `{ path, text, executable }`
file entries, an INI path, and a program path. The SDK writes those text files
into the Emscripten filesystem, applies executable bits for user M-code files,
then forwards to `runFileWithIni()` by default or to `runFiveAxisRemapFile()`
when `executionMode: "fiveAxisRemap"` is explicitly requested.

`planIniFileContextStaging()` is the generic file-staging planner for
LinuxCNC INI-driven interpreter runs. Callers provide vendored source-manifest
text, a source root, an INI file name, INI text, and a target WASM directory.
The planner reads only INI file references and the manifest, then returns the
INI, `[DISPLAY]OPEN_FILE`, `[EMCIO]TOOL_TABLE`,
`[RS274NGC]PARAMETER_FILE`, `[RS274NGC]SUBROUTINE_PATH`,
`[RS274NGC]USER_M_PATH`, and remap-NGC files that should be copied into the
Emscripten filesystem. Each planned file includes `sourceRel`, `wasmPath`, the
legacy alias `path`, and `executable`. It does not implement G-code, tool,
parameter, remap, or user-M semantics.

`planSimConfigStaging()` is the companion convenience wrapper for
representative LinuxCNC `configs/sim` programs. Callers provide the vendored
source manifest text, machine relative path, INI file name, and INI text. It
uses `planIniFileContextStaging()` with a `configs/sim/<machine>` source root
and `configs/sim` upward-search boundary.

`analyzeIniRuntimeBoundaries()` is a host-boundary classifier for LinuxCNC
INI-driven runs. It reads INI text plus optional execution text and manifest
text, then reports declared HAL, UI, HALUI MDI, Python, tool-database, and
external user-M process dependencies. User-M accounting is per execution code:
`executionCodes` lists `M100..M199` codes seen in the supplied execution text,
while `unstagedExecutionCodes` lists the subset not backed by vendored
`USER_M_PATH` files. Python accounting keeps UI/DB references separate from
Python remap runtime references, so a UI handler or DB program does not imply
Python-remap coverage. It also returns the currently recommended Layer 4
blocked kind for hard process boundaries such as `L4-TOOL-DB` and
`L4-USER-M-PROCESS`. The classifier is policy/accounting only: it does not
execute HAL, task, UI, Python, user-M, or tool-database behavior and does not
change interpreter semantics.

`runFileWithIniContinueOnError()` uses the same LinuxCNC-backed file execution
path but keeps the runner loop going after LinuxCNC reports an error, matching
upstream `rs274 -n 0` regression tests such as `tests/interp/oword-unwind`.
It does not implement or reinterpret LinuxCNC error semantics.

## Project-level virtual HAL boundary

The SDK exposes a project-level browser/Node virtual HAL boundary for UI,
session, diagnostics, and standalone interpreter bridge workflows. It is shared
through `runtime/sdk/src/index.js`, so simulation pages, INI-panel shells,
Node smokes, and external dashboards can use the same objects instead of
private page state.

- `createVirtualHalState()` creates the normalized browser virtual HAL state.
- `applyVirtualHalAction()` applies stable manual-control actions such as
  ESTOP, power, home, jog, spindle, coolant, brake, touch-off, and limit
  override.
- `createLinuxCncVirtualHalRuntime()` wraps that state in a small runtime with
  `dispatch()`, `getDroState()`, `getLimitsHomeState()`,
  `getMachineStatusState()`, `getWasmBridgeSnapshot()`, `getPinRegistry()`,
  `readPin()`, `writePin()`, `applyPinUpdates()`, `executeHalCommand()`,
  `executeHalcmd()`, `stepMotion()`, `stepMotionController()`,
  `getSimulationRuntimeReport()`, `getSimulationReplacementReport()`,
  `getSourceComplianceReport()`, `getSimConfigPromotionCandidateReport()`,
  `getSimConfigMacroLoadFixtureReport()`, `getIntegrityReport()`,
  `getPinInventory()`, `getProjectReport()`, and `applyToInterpSdk()`.
- `VIRTUAL_HAL_SIMULATION_RUNTIME_CAPABILITIES`,
  `VIRTUAL_HAL_SIMULATION_REPLACEMENT_TARGETS`,
  `VIRTUAL_HAL_SOURCE_DERIVED_CAPABILITIES`,
  `executeVirtualHalCommand()`, `executeVirtualHalcmd()`,
  `stepVirtualHalMotion()`, `stepVirtualHalMotionController()`,
  `VIRTUAL_HAL_MOTION_CONTROLLER_MATRIX_FIXTURES`,
  `createVirtualHalMotionControllerMatrixReport()`,
  `createVirtualHalSimulationRuntimeReport()`, and
  `createVirtualHalSimulationReplacementReport()` expose a simulation-grade
  replacement for the host LinuxCNC realtime HAL, `halcmd`, and motion
  controller runtime. It supports HAL pin/signal/param storage, `setp`,
  `sets`, `newsig`, `net`, `show`, `getp`, `gets`, `loadrt`/`loadusr` stubs,
  `addf`, thread start/stop, and servo-period motion stepping for browser
  simulation and Node dashboards. The motion controller matrix rows also carry
  LinuxCNC `configs/sim` evidence for external offsets, QtDragon multi-joint,
  and vismach remap simulation coverage. When callers pass `manifestText` or
  `manifestEntries`, the matrix report checks those associated sim-config
  source files against the vendored LinuxCNC manifest and exposes
  `manifestChecked` plus `missingManifestFiles`.
- `VIRTUAL_HAL_SIM_CONFIG_PROMOTION_CANDIDATES` and
  `createVirtualHalSimConfigPromotionCandidateReport()` expose the current
  source-derived sim-config promotion candidate set. The first candidates keep
  the inventory baseline unchanged while naming LinuxCNC INI/G-code source
  files, current Node `PASS` evidence, blocked-family exclusions, target
  browser diagnostics evidence, and the required virtual HAL reports for
  QtDragon on-abort, PUMA seam-weld, and rose-engine promotion planning.
- `VIRTUAL_HAL_SIM_CONFIG_EVIDENCE_EXPANSION_CANDIDATES` and
  `createVirtualHalSimConfigEvidenceExpansionReport()` expose the next
  browser-diagnostics expansion candidates that already have Node `PASS`,
  browser `REP`, and source-derived virtual HAL evidence. These rows remain
  evidence planning artifacts only: they keep the inventory baseline unchanged
  and do not unlock Python remap, tool DB, external user-M, upstream demo, or
  asset-only rows.
- `VIRTUAL_HAL_SIM_CONFIG_MACRO_LOAD_FIXTURES`,
  `VIRTUAL_HAL_SIM_CONFIG_MACRO_LOAD_BLOCKED_FIXTURES`, and
  `VIRTUAL_HAL_SIM_CONFIG_MACRO_LOAD_AUDIT_CANDIDATES` plus
  `createVirtualHalSimConfigMacroLoadFixtureReport()` expose non-main
  macro/load fixture evidence for virtual HAL diagnostics. The report keeps
  `nonMainFixture === true`, separates fixture paths from manifest-backed
  LinuxCNC source files, and prevents macro/load rows such as rose-engine
  `rcone.ngc` or external-offsets `queuebuster.ngc` from being promoted as
  standalone browser main programs. Blocked fixture rows such as SilverDragon
  `tool_sensor.ngc` remain excluded until their Python UI/process boundary is
  proven outside virtual HAL. Audit candidates such as industrial-lathe
  `toolchange.ngc` rows stay machine-readable negative evidence until owning
  INI and UI/process source evidence is complete.
- `createVirtualHalSourceComplianceReport()` is the machine-readable gate for
  the virtual HAL source rule. It maps replacement targets, runtime
  capabilities, and HAL pin families back to LinuxCNC source files such as
  `linuxcnc/bin/axis`, `linuxcnc/src/hal/utils/halcmd_commands.cc`,
  `linuxcnc/src/emc/usr_intf/halui.cc`, `linuxcnc/src/emc/task/taskclass.cc`,
  and `linuxcnc/src/emc/motion/motion.c`, then reports whether the Web
  simulation HAL is source-complete.
- `createVirtualHalWasmBridgeSnapshot()` returns the pin/value rows that can be
  applied through the interpreter SDK HAL bridge. It includes AXIS internal pin
  names such as `jog.x`, full HAL names such as `axisui.jog.x`, task/power
  names such as `halui.machine.is-on`, and spindle/coolant names such as
  `spindle.0.speed-out` and `iocontrol.0.coolant-flood`.
- `createVirtualHalPinRegistry()`, `readVirtualHalPin()`,
  `writeVirtualHalPin()`, and `applyVirtualHalPinUpdates()` expose the project
  virtual HAL as a source-derived pin service. Callers can read/write HAL names
  such as `halui.machine.on`, `spindle.0.speed-out`,
  `motion.tooloffset.z`, or `joint.0.homed` without duplicating pin mapping.
- `createVirtualHalIntegrityReport()` verifies registry completeness, duplicate
  pin absence, required project pins, and source coverage in one machine
  readable report.
- `createVirtualHalPinInventory()` returns a stable project inventory grouped
  by `VIRTUAL_HAL_PROJECT_PIN_GROUPS`.
- `VIRTUAL_HAL_SYSTEM_PIN_FAMILIES`, `VIRTUAL_HAL_SOURCE_FILES`, and
  `VIRTUAL_HAL_COVERAGE_STATES` expose the source-derived coverage model for
  AXIS, HALUI, iocontrol, motion, axis, joint, spindle, coolant, and tool pins.
- `createVirtualHalSystemCoverageReport()` expands that source-derived model
  into a machine-readable completeness report. It records the LinuxCNC source
  files used as evidence, concrete declared pin rows, represented bridge pins,
  and explicit `bridge-only` / `runtime-boundary` rows.
- `createVirtualHalBridgeReadiness()` checks that a snapshot has required
  bridge pins and that caller-provided WASM function evidence covers
  `VIRTUAL_HAL_WASM_BRIDGE_FUNCTIONS`.
- `createVirtualHalBridgeActionPlan()` turns blocked bridge readiness into the
  next build/verify commands.
- `createVirtualHalProjectReport()` packages state, DRO, limits/home, machine
  status, pin inventory, pin registry, integrity, system coverage, simulation
  runtime evidence, bridge snapshot, bridge readiness, and action plan into one
  stable report for dashboards or release artifacts.
- `applyVirtualHalToInterpSdk()` applies a virtual HAL state to any interpreter
  SDK instance exposing `applyVirtualHalState()` or `applyVirtualHalSnapshot()`.

For simulation, this replaces the host `halcmd`, HAL object store, and basic
motion feedback loop. It is a virtual realtime HAL runtime replacement for
browser workflows, but still not a Linux kernel hard-realtime ABI: kernel
realtime scheduling, external device drivers, native HAL module ABI behavior,
HALUI process behavior, and Tcl/Python process integration remain explicit
boundaries.

In practical Web simulation terms, the completed virtual HAL evidence improves
the system by making HAL/UI/machine-state diagnostics inspectable without host
LinuxCNC processes. Browser and Node workflows can share one source-derived HAL
pin/signal/param registry, execute deterministic `halcmd`-style command
fixtures, advance motion feedback through servo-period stepping, persist
virtual HAL diagnostics through OPFS/session artifacts, and expose release URL
workflow evidence for 8 diagnostics-ready promotion candidates across 3
families and 17 LinuxCNC source files. These are simulation and evidence
surface improvements only; Python remap runtime, tool DB process protocol,
external user-M execution, native HAL module ABI behavior, and JavaScript-owned
CNC semantics remain outside this scope.

## Project release readiness export

`createProjectReleaseGateManifest()` returns the required release gate IDs,
commands, expected smoke outputs, and gate count for CI dashboards and external
SDK callers. `createProjectReleaseGateResultMatrix()` maps observed gate output
and explicit gate results onto that manifest as stable `passed`/`unknown` rows.
`createProjectReleaseGateActionPlan()` turns that matrix into pending gate
commands, the next gate command, stable display rows, and a shell script that
external CI can execute or show without duplicating the manifest order.
`createProjectReleaseGateExecutionManifest()` packages the same gate manifest
with caller-provided explicit results and observed output evidence. Each row
includes the command, expected output, matched observed output when present,
evidence kind, and `passed`/`unknown` status so CI or browser dashboards can
render release-gate execution state without scraping shell scripts.
`createProjectReleaseGateExecutionSummaryViewModel()` turns that execution
manifest into stable dashboard status text, evidence counts, next missing gate,
summary rows, and normalized per-gate rows.
`createProjectReleaseReadinessReport()` returns a machine-readable release
readiness report that embeds the same manifest, result matrix, action plan,
gate execution manifest, gate execution summary view-model, sim-config
inventory baseline, and blocked runtime families. It is evidence driven: the
default report is `ready: false` until the caller supplies observed gate output
such as `project_release_gate=ok` or explicit gate results.
`createProjectReleaseReadinessSummaryViewModel()` turns the report into stable
status text, a status line, and display rows for dashboards without executing
any gate.
`createProjectBatchAcceptanceCapabilityMatrix()` normalizes per-batch evidence
and classifies accepted `api`, `workflow`, `gate`, and `browser` capabilities
separately from rejected docs-only or unknown entries.
`createProjectBatchAcceptanceWorkflow()` packages that capability matrix with
release-gate evidence for the project rule that each batch must produce at
least one callable API, verifiable workflow, executable gate, or browser
capability. The companion
`createProjectBatchAcceptanceSummaryViewModel()` and
`createProjectBatchAcceptanceActionPlan()` helpers make that evidence
dashboard-friendly and provide the next gate command when the batch acceptance
smoke has not been observed. `createProjectBatchAcceptanceChecklist()` combines
the capability matrix, gate evidence, and action plan into pass/blocked rows
for release dashboards. `createProjectBatchAcceptanceReport()` packages the
matrix, workflow, summary, action plan, and checklist into one stable object
for external CI or release dashboards.
`createProjectBatchAcceptanceReportValidation()` validates that report shape
without copying test assertions.
`createProjectBatchAcceptanceReportValidationSummaryViewModel()` and
`createProjectBatchAcceptanceReportValidationActionPlan()` expose dashboard rows
and the next artifact gate command for blocked report validation.
`createProjectBatchAcceptanceReportJsonWorkflow()` is the non-throwing JSON
workflow for external CI systems that exchange batch acceptance reports as
strings.
`loadProjectBatchAcceptanceReportUrlWorkflow()` is the fetch-driven URL
workflow for hosted batch acceptance reports. It returns fetch status, the JSON
workflow, report validation, and missing evidence without throwing.
`createProjectBatchAcceptanceReportUrlWorkflowSummaryViewModel()` and
`createProjectBatchAcceptanceReportUrlWorkflowActionPlan()` turn the same URL
workflow into dashboard rows and ordered input/fetch/gate actions.
`loadProjectReleaseReadinessArtifactUrlWorkflow()` can also fetch a browser
diagnostics artifact. When that artifact includes
`virtualHalSessionDiagnostics`, validation checks the saved-session diagnostics
artifact alongside the live virtual HAL evidence so URL workflows can prove
both live diagnostics and restored-session diagnostics are release-ready.

This helper does not execute shell commands and does not inspect or implement
CNC behavior. It only packages project-level release evidence and blocked
runtime policy that are already documented in `docs/project-release-handoff.md`
and `../PROJECT_COMPLETION_TRACKER.md`.

The executable release gate uses the same helper to write
`build/project-release-readiness.json` after all project checks pass, then
validates that artifact with
`tests/host/verify_project_release_readiness_artifact.sh`. External tools can
load that JSON with `parseProjectReleaseReadinessArtifactJson()` and validate
it with `createProjectReleaseReadinessArtifactValidation()` without copying the
host test assertions. The validation result includes `expectedGateCount` and
`expectedGateIds` so external callers can compare an artifact against the
current manifest, plus `gateManifestReady`, `gateExecutionManifestReady`,
`gateExecutionSummaryReady`, `gateResultMatrixReady`, and
`gateActionPlanReady` so stale artifacts that omit the embedded gate evidence
chain fail the same executable gate.
`createProjectReleaseReadinessArtifactValidationSummaryViewModel()` turns that
validation result into stable status text and display rows for dashboards or
browser shells without reinterpreting the artifact fields.
`createProjectReleaseReadinessArtifactValidationActionPlan()` turns a blocked
artifact validation result into the exact project release gate and artifact
validation commands to run next, plus the missing evidence list and shell
script. Ready validations return no commands.
`createProjectReleaseReadinessArtifactJsonWorkflow()` is the non-throwing
one-call wrapper for dashboards that receive artifact JSON text. It parses,
validates, builds the validation summary, and builds the action plan. Invalid
JSON returns a blocked workflow with `parsed: false` and the same next-command
action plan instead of throwing.
`loadProjectReleaseReadinessArtifactUrlWorkflow()` is the SDK-side URL workflow
for callers that supply a `fetch` implementation. It fetches the artifact URL,
runs the JSON workflow, and returns fetch status, validation, summary, and
action-plan output without executing release gates.
`createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel()` turns the
URL workflow result into stable dashboard status text and rows for ready,
missing-input, fetch-failure, and artifact-validation-blocked states.
`createProjectReleaseReadinessArtifactUrlWorkflowActionPlan()` turns the same
URL workflow into ordered workflow-level actions, distinguishing caller input,
fetch checks, and executable gate commands while preserving a shell script for
command actions.
`tests/sdk/node/verify_project_release_artifact_url_workflow.sh` is the
dedicated executable SDK gate for that URL workflow. It verifies caller-provided
fetch handling, ready summaries, action plans, missing input, HTTP failure,
thrown fetch errors, and ends with
`project_release_artifact_url_workflow_node_smoke=ok`.
`tests/sdk/node/verify_project_batch_acceptance_workflow.sh` is the executable
SDK gate for the per-batch acceptance workflow. It runs the workflow smoke,
writes `build/project-batch-acceptance.json` through
`write_project_batch_acceptance_artifact.mjs`, validates that artifact through
`verify_project_batch_acceptance_artifact.sh`, and emits
`project_batch_acceptance_workflow_node_smoke=ok` before ending with
`project_batch_acceptance_artifact_node_smoke=ok`.

## OPFS/session persistence exports

The SDK entrypoint re-exports the OPFS/session persistence helpers used by the
browser panel so external callers can stage the same files without importing
private module paths:

- `getOpfsRoot()`, `saveTextFile()`, and `loadTextFile()` for browser OPFS text
  persistence.
- `machineIniPath()`, `toolTablePath()`, `parameterFilePath()`,
  `gcodeProgramPath()`, `sessionSnapshotPath()`, `defaultMachinePaths()`, and
  `normalizeOpfsPath()` for stable OPFS path construction.
- `createMachineSessionSnapshotPayload()`, `createSessionSnapshot()`,
  `saveSessionSnapshot()`, `saveMachineSessionSnapshot()`,
  `loadMachineSessionSnapshot()`, and `validateSessionSnapshot()` for session
  snapshot persistence.
- `createVirtualHalSessionPayload()` and
  `restoreVirtualHalStateFromSessionSnapshot()` for saving and restoring Web
  virtual HAL state with source compliance, sim-config coverage, halcmd
  fixtures, and motion controller matrix evidence.
- `machineFilePaths()`, `saveMachineTextFiles()`, `loadMachineTextFiles()`, and
  `gcodeFilenameFromProgramPath()` for machine-file and G-code file helpers.
- `readMachineSessionReadiness()` for checking persisted INI, parameter,
  tool-table, optional G-code, and optional session snapshot files before
  loading a session.
- `restoreMachineParametersFromOpfs()`, `loadMachineToolTableFromOpfs()`, and
  `loadMachineSessionFromOpfs()` for loading OPFS machine state into the
  LinuxCNC-backed interpreter SDK.

These helpers only move and validate host files. Parameter and tool-table
effects still come from the LinuxCNC-backed interpreter SDK methods they call.

## INI panel shell handoff exports

The SDK entrypoint also re-exports the stable INI panel shell handoff surface
for external browser shells:

- `INI_PANEL_ENTRIES`, `getIniPanelEntryManifest()`,
  `getIniPanelEntryByHref()`, `getVisibleIniPanelEntries()`, and
  `createIniPanelLauncherLinkViewModel()` for discovering launch pages and
  rendering shell-owned launcher links from the stable entry manifest.
- `createIniPanelLaunchApiManifest()` and
  `isSupportedIniPanelLaunchApiManifest()` for launch API negotiation.
- `createControlPageBrowserApiSchema()`,
  `createControlPageBrowserApiManifest()`,
  `createControlPageBrowserApiMethods()`,
  `createIniPanelShellControlPageContract()`, and
  `isSupportedIniPanelControlPageApiManifest()` for read-only control-page API
  negotiation.
- `createIniPanelShellIntegrationSchema()`,
  `createIniPanelShellIntegrationManifest()`,
  `createIniPanelShellIntegrationReadiness()`,
  `createIniPanelShellIntegrationWorkflowPlan()`, and
  `isSupportedIniPanelShellIntegrationManifest()` for checking launch and
  control-page compatibility before embedding.
- `createIniPanelShellViewModel()` for a complete read-only shell integration
  bundle.
- `createMachineSessionPersistenceSummary()` for a machine-readable OPFS/session
  persistence summary covering machine files, session snapshot, session
  readiness, session load, readonly status, and shell handoff readiness rows.
  `createMachineSessionPersistenceDisplayViewModel()` and
  `createMachineSessionPersistenceRenderState()` turn the summary into stable
  display and render data.
  `createIniPanelShellSessionHandoffWorkflowSummary()` can include this as the
  read-only `persistence-summary` row.
- `createIniPanelShellWorkflowOverviewContract()` for discovering the workflow
  overview iframe API contract.
- `validateIniPanelShellWorkflowOverviewReleaseReadinessArtifactJson()` for the
  read-only workflow overview artifact validation wrapper exposed by
  `workflow-overview.html`. Use
  `runIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflow()` when
  a shell already has artifact JSON and needs parse, validation, summary,
  action-plan, and gate execution summary output in one non-throwing workflow.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowSummaryViewModel()`
  turns that JSON workflow into stable dashboard status text and rows.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowActionPlan()`
  exposes the JSON workflow next-command plan without requiring callers to read
  internal workflow fields.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowDomContract()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowDomReadiness()`,
  `renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowState()`,
  and `mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowState()`
  let a shell render or mount that JSON workflow render-state into caller-owned
  DOM without executing release gate commands.
  Use
  `loadIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrl()` when a
  browser or shell should fetch the artifact JSON URL, validate it, and
  optionally mount the resulting render-state into caller-owned DOM. The URL
  workflow result includes `validationSummaryViewModel` and
  `gateExecutionSummaryViewModel` for dashboards.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowSummaryViewModel()`
  turns the full URL workflow result into stable status text and rows.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlan()`
  exposes the same URL workflow next-action/next-command plan through the
  browser workflow overview surface.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlanRenderState()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlanDomContract()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlanDomReadiness()`,
  `renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlanState()`,
  and `mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlanState()`
  let the fixed workflow overview URL form render the URL workflow action plan
  beside the URL workflow rows.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowRenderState()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowDomContract()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowDomReadiness()`,
  `renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowState()`,
  and `mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowState()`
  let callers render the URL workflow status into their own DOM.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlan()`
  exposes the direct artifact-validation next-command plan when callers already
  have parsed or validated artifact JSON.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanRenderState()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanDomContract()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanDomReadiness()`,
  `renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanState()`,
  and `mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanState()`
  let callers render that validation action plan into caller-owned DOM.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryViewModel()`
  and
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlGateExecutionSummaryViewModel()`
  expose the embedded release gate execution summary for external shells without
  requiring callers to parse artifact internals.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryRenderState()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryDomContract()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryDomReadiness()`,
  `renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryState()`,
  and `mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryState()`
  let callers render the per-gate execution summary rows into caller-owned DOM.
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactDisplayViewModel()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactRenderState()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationSummaryViewModel()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactDomContract()`,
  `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactDomReadiness()`,
  `renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactState()`, and
  `mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactState()` when an
  outer shell needs to render that validation into caller-owned DOM.
- `createIniPanelShellApiSurfaceInventory()` for a machine-readable inventory
  of launch, control-page, workflow overview, persistence, and session
  readiness report API counts, including persistence summary row counts.
  `createIniPanelShellViewModel()` also includes
  this inventory as a read-only workflow summary row so browser overview pages
  and external shells can display API coverage without private imports.
- `createIniPanelShellSessionReadinessWorkflowReport()` for a machine-readable
  session readiness workflow report with phase, missing reasons, status line,
  and stable rows.
- `createIniPanelShellWorkflowOverviewEmbeddingMountDomContract()` and
  `createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness()` for
  workflow overview embedding mount DOM checks.
- `renderIniPanelShellWorkflowOverviewEmbeddingMountState()` for rendering a
  mount render-state into caller-owned DOM.
- `mountIniPanelShellWorkflowOverviewEmbeddingMountState()` for a non-throwing
  workflow overview embedding mount wrapper that returns structured blocked
  results when DOM nodes are missing.

The workflow overview embedding helpers are UI/runtime boundary helpers only.
They render status and rows already produced by the shell view-model; they do
not parse G-code, execute action plans, or implement CNC semantics.