推进 SDK API surface exports and smoke

wasm-port/runtime/sdk/README.md

@@ -24,10 +24,40 @@ Use `src/index.js` for stable imports:
 ```js
 import {
   analyzeIniRuntimeBoundaries,
+  createIniPanelLaunchApiManifest,
+  createIniPanelShellViewModel,
+  createIniPanelShellWorkflowOverviewEmbeddingMountDomContract,
+  createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness,
   createLinuxCncIniSdk,
   createLinuxCncInterpSdk,
+  createMachineSessionSnapshotPayload,
+  createSessionSnapshot,
+  defaultMachinePaths,
+  gcodeFilenameFromProgramPath,
+  gcodeProgramPath,
+  getOpfsRoot,
+  isSupportedIniPanelLaunchApiManifest,
+  loadMachineSessionFromOpfs,
+  loadMachineSessionSnapshot,
+  loadMachineTextFiles,
+  loadMachineToolTableFromOpfs,
+  loadTextFile,
+  machineFilePaths,
+  machineIniPath,
+  mountIniPanelShellWorkflowOverviewEmbeddingMountState,
+  normalizeOpfsPath,
+  parameterFilePath,
   planIniFileContextStaging,
   planSimConfigStaging,
+  renderIniPanelShellWorkflowOverviewEmbeddingMountState,
+  restoreMachineParametersFromOpfs,
+  saveMachineSessionSnapshot,
+  saveMachineTextFiles,
+  saveSessionSnapshot,
+  saveTextFile,
+  sessionSnapshotPath,
+  toolTablePath,
+  validateSessionSnapshot,
 } from "./src/index.js";
 ```
 
@@ -123,3 +153,49 @@ change interpreter semantics.
 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.
+
+## 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.
+- `machineFilePaths()`, `saveMachineTextFiles()`, `loadMachineTextFiles()`, and
+  `gcodeFilenameFromProgramPath()` for machine-file and G-code file helpers.
+- `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:
+
+- `createIniPanelLaunchApiManifest()` and
+  `isSupportedIniPanelLaunchApiManifest()` for launch API negotiation.
+- `createIniPanelShellViewModel()` for a complete read-only shell integration
+  bundle.
+- `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.

wasm-port/runtime/sdk/src/index.js

@@ -5,3 +5,91 @@ export {
   planIniFileContextStaging,
   planSimConfigStaging,
 } from "./sim-config-staging.js";
+
+export {
+  defaultMachinePaths,
+  gcodeProgramPath,
+  machineIniPath,
+  machineRoot,
+  normalizeOpfsPath,
+  opfsPath,
+  parameterFilePath,
+  previewCachePath,
+  sessionSnapshotPath,
+  splitOpfsPath,
+  toolTablePath,
+} from "../../opfs/path-model.js";
+export {
+  ensureParentDir,
+  getOpfsRoot,
+  loadTextFile,
+  saveTextFile,
+} from "../../opfs/file-service.js";
+export {
+  createMachineSessionSnapshotPayload,
+  createSessionSnapshot,
+  loadMachineSessionSnapshot,
+  loadSessionSnapshot,
+  saveMachineSessionSnapshot,
+  saveSessionSnapshot,
+  validateSessionSnapshot,
+} from "../../opfs/snapshot-store.js";
+export {
+  gcodeFilenameFromProgramPath,
+  loadGcodeProgram,
+  loadMachineTextFiles,
+  machineFilePaths,
+  saveGcodeProgram,
+  saveMachineTextFiles,
+} from "../../opfs/machine-file-store.js";
+export {
+  restoreMachineParametersFromOpfs,
+  saveMachineParametersToOpfs,
+} from "../../opfs/linuxcnc-parameter-bridge.js";
+export {
+  loadMachineToolTableFromOpfs,
+  saveMachineToolTableToOpfs,
+} from "../../opfs/linuxcnc-tool-table-bridge.js";
+export { loadMachineSessionFromOpfs } from "../../opfs/linuxcnc-machine-session-bridge.js";
+
+export {
+  createIniPanelLaunchApiManifest,
+  createIniPanelLaunchApiSchema,
+  createIniPanelShellIntegrationManifest,
+  createIniPanelShellIntegrationReadiness,
+  createIniPanelShellIntegrationSchema,
+  createIniPanelShellIntegrationWorkflowPlan,
+  createIniPanelShellSessionHandoffCompatibilityReport,
+  createIniPanelShellSessionHandoffPackage,
+  createIniPanelShellSessionHandoffPackageMountDisplayViewModel,
+  createIniPanelShellSessionHandoffPackageMountRenderState,
+  createIniPanelShellSessionHandoffPackageMountState,
+  createIniPanelShellSessionHandoffPackageReport,
+  createIniPanelShellSessionHandoffPackageRenderState,
+  createIniPanelShellSessionHandoffPackageSchema,
+  createIniPanelShellSessionHandoffSummary,
+  createIniPanelShellSessionHandoffSummarySchema,
+  createIniPanelShellViewModel,
+  createIniPanelShellWorkflowOverviewContract,
+  createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel,
+  createIniPanelShellWorkflowOverviewEmbeddingDomContract,
+  createIniPanelShellWorkflowOverviewEmbeddingDomReadiness,
+  createIniPanelShellWorkflowOverviewEmbeddingMountDisplayViewModel,
+  createIniPanelShellWorkflowOverviewEmbeddingMountDomContract,
+  createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness,
+  createIniPanelShellWorkflowOverviewEmbeddingMountRenderState,
+  createIniPanelShellWorkflowOverviewEmbeddingRenderState,
+  createIniPanelShellWorkflowOverviewEmbeddingReport,
+  createIniPanelShellWorkflowOverviewReadiness,
+  isSupportedIniPanelLaunchApiManifest,
+  isSupportedIniPanelShellIntegrationManifest,
+  isSupportedIniPanelShellSessionHandoffPackage,
+  isSupportedIniPanelShellSessionHandoffSummary,
+  mountIniPanelShellSessionHandoff,
+  mountIniPanelShellWorkflowOverviewEmbedding,
+  mountIniPanelShellWorkflowOverviewEmbeddingMountState,
+  mountIniPanelShellWorkflowOverviewEmbeddingState,
+  renderIniPanelShellSessionHandoffMountState,
+  renderIniPanelShellWorkflowOverviewEmbeddingMountState,
+  renderIniPanelShellWorkflowOverviewEmbeddingState,
+} from "../../ui/ini-panel/ui-shell.js";

wasm-port/tests/host/verify_host_smokes.sh

@@ -13,6 +13,7 @@ SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/wasm/node/verify_sim_configs_inventory_wasm
 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/wasm/node/verify_nc_files_wasm.sh"
 SKIP_TP_BUILD=1 "$ROOT_DIR/tests/wasm/node/verify_tp_wasm.sh"
 "$ROOT_DIR/tests/opfs/node/verify_file_service.sh"
+"$ROOT_DIR/tests/sdk/node/verify_sdk_surface.sh"
 "$ROOT_DIR/tests/ui/node/verify_ui_node_smokes.sh"
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_ini_panel_browser.sh"
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_interp_browser.sh"

wasm-port/tests/sdk/node/verify_sdk_surface.mjs

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  analyzeIniRuntimeBoundaries,
+  createIniPanelLaunchApiManifest,
+  createIniPanelShellViewModel,
+  createIniPanelShellWorkflowOverviewEmbeddingMountDomContract,
+  createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness,
+  createLinuxCncIniSdk,
+  createLinuxCncInterpSdk,
+  createMachineSessionSnapshotPayload,
+  createSessionSnapshot,
+  defaultMachinePaths,
+  gcodeFilenameFromProgramPath,
+  gcodeProgramPath,
+  getOpfsRoot,
+  isSupportedIniPanelLaunchApiManifest,
+  loadMachineSessionFromOpfs,
+  loadMachineSessionSnapshot,
+  loadMachineTextFiles,
+  loadMachineToolTableFromOpfs,
+  loadTextFile,
+  machineFilePaths,
+  machineIniPath,
+  mountIniPanelShellWorkflowOverviewEmbeddingMountState,
+  normalizeOpfsPath,
+  parameterFilePath,
+  planIniFileContextStaging,
+  planSimConfigStaging,
+  renderIniPanelShellWorkflowOverviewEmbeddingMountState,
+  restoreMachineParametersFromOpfs,
+  saveMachineSessionSnapshot,
+  saveMachineTextFiles,
+  saveSessionSnapshot,
+  saveTextFile,
+  sessionSnapshotPath,
+  toolTablePath,
+  validateSessionSnapshot,
+} from "../../../runtime/sdk/src/index.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "../../..");
+const sdkIndexText = readFileSync(resolve(root, "runtime/sdk/src/index.js"), "utf8");
+const sdkReadmeText = readFileSync(resolve(root, "runtime/sdk/README.md"), "utf8");
+const trackerText = readFileSync(resolve(root, "../PROJECT_COMPLETION_TRACKER.md"), "utf8");
+
+const requiredExports = [
+  ["createLinuxCncIniSdk", createLinuxCncIniSdk],
+  ["createLinuxCncInterpSdk", createLinuxCncInterpSdk],
+  ["planIniFileContextStaging", planIniFileContextStaging],
+  ["planSimConfigStaging", planSimConfigStaging],
+  ["analyzeIniRuntimeBoundaries", analyzeIniRuntimeBoundaries],
+  ["getOpfsRoot", getOpfsRoot],
+  ["saveTextFile", saveTextFile],
+  ["loadTextFile", loadTextFile],
+  ["machineIniPath", machineIniPath],
+  ["toolTablePath", toolTablePath],
+  ["parameterFilePath", parameterFilePath],
+  ["gcodeProgramPath", gcodeProgramPath],
+  ["sessionSnapshotPath", sessionSnapshotPath],
+  ["defaultMachinePaths", defaultMachinePaths],
+  ["normalizeOpfsPath", normalizeOpfsPath],
+  ["createMachineSessionSnapshotPayload", createMachineSessionSnapshotPayload],
+  ["createSessionSnapshot", createSessionSnapshot],
+  ["saveSessionSnapshot", saveSessionSnapshot],
+  ["saveMachineSessionSnapshot", saveMachineSessionSnapshot],
+  ["loadMachineSessionSnapshot", loadMachineSessionSnapshot],
+  ["validateSessionSnapshot", validateSessionSnapshot],
+  ["machineFilePaths", machineFilePaths],
+  ["saveMachineTextFiles", saveMachineTextFiles],
+  ["loadMachineTextFiles", loadMachineTextFiles],
+  ["gcodeFilenameFromProgramPath", gcodeFilenameFromProgramPath],
+  ["restoreMachineParametersFromOpfs", restoreMachineParametersFromOpfs],
+  ["loadMachineToolTableFromOpfs", loadMachineToolTableFromOpfs],
+  ["loadMachineSessionFromOpfs", loadMachineSessionFromOpfs],
+  ["createIniPanelLaunchApiManifest", createIniPanelLaunchApiManifest],
+  ["isSupportedIniPanelLaunchApiManifest", isSupportedIniPanelLaunchApiManifest],
+  ["createIniPanelShellViewModel", createIniPanelShellViewModel],
+  [
+    "createIniPanelShellWorkflowOverviewEmbeddingMountDomContract",
+    createIniPanelShellWorkflowOverviewEmbeddingMountDomContract,
+  ],
+  [
+    "createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness",
+    createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness,
+  ],
+  [
+    "renderIniPanelShellWorkflowOverviewEmbeddingMountState",
+    renderIniPanelShellWorkflowOverviewEmbeddingMountState,
+  ],
+  [
+    "mountIniPanelShellWorkflowOverviewEmbeddingMountState",
+    mountIniPanelShellWorkflowOverviewEmbeddingMountState,
+  ],
+];
+
+for (const [name, value] of requiredExports) {
+  assert.equal(typeof value, "function", `${name} SDK export drift`);
+  assert.match(sdkIndexText, new RegExp(`\\b${name}\\b`));
+  assert.match(sdkReadmeText, new RegExp(`\\b${name}\\b`));
+}
+
+assert.equal(machineIniPath("sdk-mill"), "linuxcnc/machines/sdk-mill/machine.ini");
+assert.deepEqual(defaultMachinePaths("sdk-mill"), machineFilePaths("sdk-mill"));
+assert.equal(gcodeProgramPath("demo.ngc"), "linuxcnc/gcode/demo.ngc");
+assert.equal(sessionSnapshotPath("sdk-session"), "linuxcnc/sessions/sdk-session/snapshot.json");
+assert.equal(normalizeOpfsPath("linuxcnc/machines/sdk-mill/tool.tbl"), "linuxcnc/machines/sdk-mill/tool.tbl");
+assert.equal(gcodeFilenameFromProgramPath("linuxcnc/gcode/demo.ngc"), "demo.ngc");
+
+const launchManifest = createIniPanelLaunchApiManifest();
+assert.equal(isSupportedIniPanelLaunchApiManifest(launchManifest), true);
+assert.equal(
+  launchManifest.methods.includes("mountWorkflowOverviewEmbeddingMountState"),
+  true,
+);
+
+const shellViewModel = createIniPanelShellViewModel();
+assert.equal(
+  shellViewModel.launchApiManifest.methods.includes("mountWorkflowOverviewEmbeddingMountState"),
+  true,
+);
+assert.equal(
+  shellViewModel.mountWorkflowOverviewEmbeddingMountState,
+  mountIniPanelShellWorkflowOverviewEmbeddingMountState,
+);
+
+const blockedMount = mountIniPanelShellWorkflowOverviewEmbeddingMountState({ documentRef: null });
+assert.equal(blockedMount.apiName, "ini-panel-shell-workflow-overview-embedding-mount-dom-mount");
+assert.equal(blockedMount.ready, false);
+assert.deepEqual(blockedMount.domReadiness.missing, ["document", "mount", "status", "rows"]);
+
+assert.match(sdkReadmeText, /OPFS\/session persistence/);
+assert.match(sdkReadmeText, /INI panel shell handoff/);
+assert.match(sdkReadmeText, /workflow overview embedding/);
+assert.match(trackerText, /SDK\/API surface/);
+
+console.log("sdk_surface_node_smoke=ok");

wasm-port/tests/sdk/node/verify_sdk_surface.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+node "$ROOT_DIR/tests/sdk/node/verify_sdk_surface.mjs"