推进 INI 面板 shell handoff mount DOM contract helper

text12.txt

@@ -2720,3 +2720,78 @@ host_wasm_opfs_browser_smokes=ok
 继续推进 SDK/API surface。下一批建议为 shared mount DOM renderer 增加 schema/contract helper
 （例如 `createIniPanelShellSessionHandoffMountDomContract()`），让外部 shell 可在渲染前校验所需
 DOM nodes、dataset keys 与 row dataset prefix；仍保持只读，不新增控制按钮，不解析 G-code。
+
+三十四、2026-06-15 继续执行记录：INI panel shell handoff mount DOM contract helper
+
+本轮按“第一原则：加快实质性推进”继续推进 SDK/API surface 与 browser/UI workflow，把 shared
+mount DOM renderer 的隐式 DOM 约定抽成可复用 contract/readiness helper，让外部 shell 能在渲染前
+校验所需 DOM nodes、dataset keys 与 row dataset prefix。
+
+完成内容：
+
+- `ui-shell.js` 新增 `createIniPanelShellSessionHandoffMountDomContract()`；
+- `ui-shell.js` 新增 `createIniPanelShellSessionHandoffMountDomReadiness()`；
+- `renderIniPanelShellSessionHandoffMountState()` 改为复用 DOM readiness gate，并支持通过 contract
+  统一 selectors 与 row dataset prefix；
+- `createIniPanelShellViewModel()` 暴露 `shellSessionHandoffMountDomContract`、
+  `createShellSessionHandoffMountDomContract` 与 `createShellSessionHandoffMountDomReadiness`；
+- `createIniPanelLaunchApiManifest().methods` 新增：
+  - `getShellSessionHandoffMountDomContract`；
+  - `getShellSessionHandoffMountDomReadiness`；
+- `launch.html` 的 `window.linuxCncIniPanelLaunchApi` 暴露对应 browser API；
+- `ini_panel_shell_integration_workflow_smoke.html` 改为先构造外部 shell-owned DOM contract，再执行
+  readiness 校验，随后用同一 contract 渲染 waiting/ready mount-state；
+- Node smoke 覆盖默认 contract、外部 row dataset prefix、DOM readiness ready/missing 路径、launch
+  manifest 方法清单与文档记录；
+- 未新增控制按钮；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未新增 JS CNC 语义；
+- 未改变 OPFS/session persistence、LinuxCNC interpreter、tool、parameter、planner 或
+  LinuxCNC-owned runtime semantics。
+
+验证已通过：
+
+```bash
+git diff --check
+wasm-port/tests/ui/node/verify_ini_panel_ui_shell.sh
+wasm-port/tests/ui/node/verify_ini_panel_launch_api_manifest.sh
+wasm-port/tests/ui/node/verify_ini_panel_shell_integration_manifest.sh
+wasm-port/tests/ui/node/verify_ini_panel_entry_docs.sh
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+wasm-port/tools/verify_vendor_sync.sh
+wasm-port/tools/verify_no_standalone_cnc_semantics.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
+wasm-port/tests/host/verify_host_smokes.sh
+```
+
+关键输出：
+
+```text
+ini_panel_ui_shell_node_smoke=ok
+ini_panel_launch_api_manifest_node_smoke=ok
+ini_panel_shell_integration_manifest_node_smoke=ok
+ini_panel_entry_docs_node_smoke=ok
+ui_node_smokes=ok
+browser_ini_opfs_smoke=ok
+browser_ini_control_page_smoke=ok
+browser_ini_launch_smoke=ok
+browser_ini_shell_integration_workflow_smoke=ok
+vendor sync up to date
+standalone CNC semantics guard complete
+interp_wasm_node_smoke=ok
+sim_configs_wasm_node_inventory_executed=28
+sim_configs_wasm_node_inventory_passed=28
+sim_configs_wasm_node_inventory_skipped=131
+sim_configs_wasm_node_inventory_unexpected_fail=0
+host_wasm_opfs_browser_smokes=ok
+```
+
+下一步建议：
+
+继续推进 SDK/API surface。下一批建议把 shell handoff mount DOM contract/readiness 聚合进一个
+可复用的 browser-side mount workflow helper（例如 `mountIniPanelShellSessionHandoff()`），让外部
+shell 一次调用即可完成 contract 生成、DOM readiness、mount-state render 与 structured result；仍
+保持只读，不新增控制按钮，不解析 G-code。

wasm-port/docs/panel-entry.md

@@ -30,7 +30,8 @@ import {
   createIniPanelShellSessionHandoffPackageMountDisplayViewModel,
   createIniPanelShellSessionHandoffPackageMountRenderState,
   createIniPanelShellSessionHandoffPackageMountState,
-  renderIniPanelShellSessionHandoffMountState,
+  createIniPanelShellSessionHandoffMountDomContract,
+  createIniPanelShellSessionHandoffMountDomReadiness,
   renderIniPanelShellSessionHandoffMountState,
   createIniPanelShellSessionHandoffPackageReport,
   createIniPanelShellSessionHandoffPackageRenderState,
@@ -226,11 +227,20 @@ 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 `renderIniPanelShellSessionHandoffMountState()` or
+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
+`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
+shell needs the shared read-only DOM renderer for those rows. The launch page
-state into `[data-handoff-mount]`, `[data-handoff-mount-status]`, and
+renders the default waiting mount state into `[data-handoff-mount]`,
-`[data-handoff-mount-rows]` without opening the control page.
+`[data-handoff-mount-status]`, and `[data-handoff-mount-rows]` without opening
+the control page.
 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,

wasm-port/runtime/ui/ini-panel/launch.html

@@ -106,6 +106,8 @@
       createIniPanelLauncherLinkViewModel,
       createIniPanelShellViewModel,
       isSupportedIniPanelLaunchApiManifest,
+      createIniPanelShellSessionHandoffMountDomContract,
+      createIniPanelShellSessionHandoffMountDomReadiness,
       renderIniPanelShellSessionHandoffMountState,
     } from "./ui-shell.js";
 
@@ -180,6 +182,12 @@
           ),
         )
       ),
+      getShellSessionHandoffMountDomContract: (options) => (
+        createIniPanelShellSessionHandoffMountDomContract(options)
+      ),
+      getShellSessionHandoffMountDomReadiness: (options) => (
+        createIniPanelShellSessionHandoffMountDomReadiness(options ?? { documentRef: document })
+      ),
       renderShellSessionHandoffMountState: (renderState, options) => (
         renderIniPanelShellSessionHandoffMountState(renderState, options ?? { documentRef: document })
       ),

wasm-port/runtime/ui/ini-panel/ui-shell.js

@@ -143,6 +143,8 @@ export function createIniPanelLaunchApiManifest(entries = getVisibleIniPanelEntr
       "getShellSessionHandoffPackageMountState",
       "getShellSessionHandoffPackageMountDisplayViewModel",
       "getShellSessionHandoffPackageMountRenderState",
+      "getShellSessionHandoffMountDomContract",
+      "getShellSessionHandoffMountDomReadiness",
       "renderShellSessionHandoffMountState",
       "isSupportedShellSessionHandoffPackage",
       "getLauncherLinks",
@@ -1079,21 +1081,85 @@ export function createIniPanelShellSessionHandoffPackageMountRenderState(
   };
 }
 
+export function createIniPanelShellSessionHandoffMountDomContract({
+  rowDatasetPrefix = "handoffMount",
+  selectors = {},
+} = {}) {
+  const mountSelector = selectors.mount ?? "[data-handoff-mount]";
+  const statusSelector = selectors.status ?? "[data-handoff-mount-status]";
+  const rowsSelector = selectors.rows ?? "[data-handoff-mount-rows]";
+  return {
+    apiName: "ini-panel-shell-session-handoff-mount-dom-contract",
+    contractVersion: 1,
+    requiredNodeIds: ["mount", "status", "rows"],
+    selectors: {
+      mount: mountSelector,
+      status: statusSelector,
+      rows: rowsSelector,
+    },
+    mountDatasetKeys: ["handoffPhase", "handoffReady", "handoffScope"],
+    rowDatasetPrefix,
+    rowDatasetKeys: {
+      term: [`${rowDatasetPrefix}Row`, `${rowDatasetPrefix}Status`],
+      detail: [`${rowDatasetPrefix}Value`, `${rowDatasetPrefix}Status`],
+    },
+    renderResultFields: ["rendered", "statusLine", "rowCount", "rowIds", "dataset"],
+  };
+}
+
+export function createIniPanelShellSessionHandoffMountDomReadiness({
+  rowDatasetPrefix = "handoffMount",
+  contract = createIniPanelShellSessionHandoffMountDomContract({ rowDatasetPrefix }),
+  documentRef = globalThis.document,
+  mountNode = documentRef?.querySelector?.(contract.selectors.mount),
+  statusNode = documentRef?.querySelector?.(contract.selectors.status),
+  rowsNode = documentRef?.querySelector?.(contract.selectors.rows),
+} = {}) {
+  const checks = {
+    document: Boolean(documentRef?.createElement),
+    mount: Boolean(mountNode),
+    status: Boolean(statusNode),
+    rows: Boolean(rowsNode),
+    rowDatasetPrefix: Boolean(contract.rowDatasetPrefix),
+  };
+  const missing = Object.entries(checks)
+    .filter(([, passed]) => !passed)
+    .map(([name]) => name);
+  const ready = missing.length === 0;
+
+  return {
+    apiName: "ini-panel-shell-session-handoff-mount-dom-readiness",
+    readinessVersion: 1,
+    phase: ready ? "ready" : "blocked",
+    ready,
+    missing,
+    checks,
+    contract,
+  };
+}
+
 export function renderIniPanelShellSessionHandoffMountState(
   renderState = createIniPanelShellSessionHandoffPackageMountRenderState(),
   {
-    documentRef = globalThis.document,
-    mountNode = documentRef?.querySelector?.("[data-handoff-mount]"),
-    statusNode = documentRef?.querySelector?.("[data-handoff-mount-status]"),
-    rowsNode = documentRef?.querySelector?.("[data-handoff-mount-rows]"),
     rowDatasetPrefix = "handoffMount",
+    contract = createIniPanelShellSessionHandoffMountDomContract({ rowDatasetPrefix }),
+    documentRef = globalThis.document,
+    mountNode = documentRef?.querySelector?.(contract.selectors.mount),
+    statusNode = documentRef?.querySelector?.(contract.selectors.status),
+    rowsNode = documentRef?.querySelector?.(contract.selectors.rows),
   } = {},
 ) {
-  if (!documentRef?.createElement) {
+  const readiness = createIniPanelShellSessionHandoffMountDomReadiness({
-    throw new Error("A DOM document is required to render shell handoff mount state.");
+    contract,
-  }
+    documentRef,
-  if (!mountNode || !statusNode || !rowsNode) {
+    mountNode,
-    throw new Error("Mount, status, and rows nodes are required to render shell handoff mount state.");
+    statusNode,
+    rowsNode,
+  });
+  if (!readiness.ready) {
+    throw new Error(
+      `Shell handoff mount DOM is not ready: ${readiness.missing.join(", ")}`,
+    );
   }
 
   mountNode.dataset.handoffPhase = renderState?.dataset?.handoffPhase ?? "blocked";
@@ -1103,14 +1169,15 @@ export function renderIniPanelShellSessionHandoffMountState(
   rowsNode.replaceChildren();
 
   const rows = Array.isArray(renderState?.rows) ? renderState.rows : [];
+  const effectiveRowDatasetPrefix = contract.rowDatasetPrefix;
   for (const row of rows) {
     const term = documentRef.createElement("dt");
-    term.dataset[`${rowDatasetPrefix}Row`] = row.id;
+    term.dataset[`${effectiveRowDatasetPrefix}Row`] = row.id;
-    term.dataset[`${rowDatasetPrefix}Status`] = row.status;
+    term.dataset[`${effectiveRowDatasetPrefix}Status`] = row.status;
     term.textContent = row.label;
     const detail = documentRef.createElement("dd");
-    detail.dataset[`${rowDatasetPrefix}Value`] = row.id;
+    detail.dataset[`${effectiveRowDatasetPrefix}Value`] = row.id;
-    detail.dataset[`${rowDatasetPrefix}Status`] = row.status;
+    detail.dataset[`${effectiveRowDatasetPrefix}Status`] = row.status;
     detail.textContent = row.value;
     rowsNode.append(term, detail);
   }
@@ -1191,6 +1258,7 @@ export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries
   const shellSessionHandoffPackageMountRenderState = createIniPanelShellSessionHandoffPackageMountRenderState(
     shellSessionHandoffPackageMountDisplayViewModel,
   );
+  const shellSessionHandoffMountDomContract = createIniPanelShellSessionHandoffMountDomContract();
   return {
     pages: entries.map(({ id, href, title }) => ({
       id,
@@ -1218,6 +1286,7 @@ export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries
     shellSessionHandoffPackageMountState,
     shellSessionHandoffPackageMountDisplayViewModel,
     shellSessionHandoffPackageMountRenderState,
+    shellSessionHandoffMountDomContract,
     launchApiSchema: createIniPanelLaunchApiSchema(),
     launchApiManifest: createIniPanelLaunchApiManifest(entries),
     isSupportedShellIntegrationManifest: isSupportedIniPanelShellIntegrationManifest,
@@ -1240,6 +1309,8 @@ export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries
     createShellSessionHandoffPackageMountState: createIniPanelShellSessionHandoffPackageMountState,
     createShellSessionHandoffPackageMountDisplayViewModel: createIniPanelShellSessionHandoffPackageMountDisplayViewModel,
     createShellSessionHandoffPackageMountRenderState: createIniPanelShellSessionHandoffPackageMountRenderState,
+    createShellSessionHandoffMountDomContract: createIniPanelShellSessionHandoffMountDomContract,
+    createShellSessionHandoffMountDomReadiness: createIniPanelShellSessionHandoffMountDomReadiness,
     renderShellSessionHandoffMountState: renderIniPanelShellSessionHandoffMountState,
     isSupportedShellSessionHandoffPackage: isSupportedIniPanelShellSessionHandoffPackage,
     controlPage: {

wasm-port/tests/browser/ini_panel_shell_integration_workflow_smoke.html

@@ -85,6 +85,8 @@ TOOL_TABLE = browser-shell-tool.tbl
         !launchApi?.getShellSessionHandoffPackageMountState ||
         !launchApi?.getShellSessionHandoffPackageMountDisplayViewModel ||
         !launchApi?.getShellSessionHandoffPackageMountRenderState ||
+        !launchApi?.getShellSessionHandoffMountDomContract ||
+        !launchApi?.getShellSessionHandoffMountDomReadiness ||
         !launchApi?.renderShellSessionHandoffMountState ||
         !launchApi?.isSupportedShellSessionHandoffPackage
       ) {
@@ -109,16 +111,27 @@ TOOL_TABLE = browser-shell-tool.tbl
       const handoffPackageMountState = launchApi.getShellSessionHandoffPackageMountState();
       const handoffPackageMountDisplay = launchApi.getShellSessionHandoffPackageMountDisplayViewModel();
       const handoffPackageMountRenderState = launchApi.getShellSessionHandoffPackageMountRenderState();
+      const externalMountDomContract = launchApi.getShellSessionHandoffMountDomContract({
+        rowDatasetPrefix: "externalMount",
+        selectors: {
+          mount: "[data-external-shell-mount]",
+          status: "[data-external-shell-mount-status]",
+          rows: "[data-external-shell-mount-rows]",
+        },
+      });
+      const externalMountDomReadiness = launchApi.getShellSessionHandoffMountDomReadiness({
+        contract: externalMountDomContract,
+        documentRef: document,
+      });
       const waitingMountRenderResult = launchApi.renderShellSessionHandoffMountState(
         handoffPackageMountRenderState,
         {
+          contract: externalMountDomContract,
           documentRef: document,
-          mountNode: document.querySelector("[data-external-shell-mount]"),
-          statusNode: document.querySelector("[data-external-shell-mount-status]"),
-          rowsNode: document.querySelector("[data-external-shell-mount-rows]"),
-          rowDatasetPrefix: "externalMount",
         },
       );
+      assertEqual(externalMountDomContract.rowDatasetPrefix, "externalMount", "external shell mount DOM contract prefix");
+      assertEqual(externalMountDomReadiness.ready, true, "external shell mount DOM readiness");
       assertEqual(handoffSummarySchema.summaryVersion, 1, "shell handoff summary schema version");
       assertEqual(
         launchApi.isSupportedShellSessionHandoffSummary(handoffSummary),
@@ -280,11 +293,8 @@ TOOL_TABLE = browser-shell-tool.tbl
       const readyMountRenderResult = launchApi.renderShellSessionHandoffMountState(
         readyMountRenderState,
         {
+          contract: externalMountDomContract,
           documentRef: document,
-          mountNode: document.querySelector("[data-external-shell-mount]"),
-          statusNode: document.querySelector("[data-external-shell-mount-status]"),
-          rowsNode: document.querySelector("[data-external-shell-mount-rows]"),
-          rowDatasetPrefix: "externalMount",
         },
       );
       assertEqual(readyMountState.ready, true, "shell handoff package mount-state readiness");

wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs

@@ -27,6 +27,8 @@ import {
   createIniPanelShellSessionHandoffPackageMountDisplayViewModel,
   createIniPanelShellSessionHandoffPackageMountRenderState,
   createIniPanelShellSessionHandoffPackageMountState,
+  createIniPanelShellSessionHandoffMountDomContract,
+  createIniPanelShellSessionHandoffMountDomReadiness,
   renderIniPanelShellSessionHandoffMountState,
   createIniPanelShellSessionHandoffPackageReport,
   createIniPanelShellSessionHandoffPackageRenderState,
@@ -93,6 +95,8 @@ const requiredShellExports = [
   "createIniPanelShellSessionHandoffPackageMountDisplayViewModel",
   "createIniPanelShellSessionHandoffPackageMountRenderState",
   "createIniPanelShellSessionHandoffPackageMountState",
+  "createIniPanelShellSessionHandoffMountDomContract",
+  "createIniPanelShellSessionHandoffMountDomReadiness",
   "renderIniPanelShellSessionHandoffMountState",
   "createIniPanelShellSessionHandoffPackageReport",
   "createIniPanelShellSessionHandoffPackageRenderState",
@@ -279,6 +283,14 @@ assert.deepEqual(
     createIniPanelShellViewModel().shellSessionHandoffPackageMountDisplayViewModel,
   ),
 );
+assert.deepEqual(
+  createIniPanelShellViewModel().shellSessionHandoffMountDomContract,
+  createIniPanelShellSessionHandoffMountDomContract(),
+);
+assert.equal(
+  createIniPanelShellSessionHandoffMountDomReadiness({ documentRef: null }).ready,
+  false,
+);
 assert.equal(isSupportedIniPanelShellSessionHandoffPackage(createIniPanelShellViewModel().shellSessionHandoffPackage), true);
 assert.equal(isSupportedIniPanelShellIntegrationManifest(createIniPanelShellViewModel().shellIntegrationManifest), true);
 assert.deepEqual(createIniPanelShellViewModel().launchApiSchema, createIniPanelLaunchApiSchema());
@@ -436,6 +448,8 @@ assert.match(docText, /\bdata-handoff-rows\b/);
 assert.match(docText, /\bdata-external-shell-mount\b/);
 assert.match(docText, /\brenderIniPanelShellSessionHandoffMountState\b/);
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.renderShellSessionHandoffMountState\b/);
+assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getShellSessionHandoffMountDomContract\b/);
+assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getShellSessionHandoffMountDomReadiness\b/);
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getControlPageApiMethods\b/);
 assert.match(docText, /\bini_panel_shell_integration_workflow_smoke\.html\b/);
 assert.match(browserIniPanelText, /\bini_panel_shell_integration_workflow_smoke\.html\b/);
@@ -452,6 +466,8 @@ assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffPackage
 assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffPackage\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffPackageReport\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffPackageMountRenderState\b/);
+assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffMountDomContract\b/);
+assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffMountDomReadiness\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\brenderShellSessionHandoffMountState\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\bdata-external-shell-mount\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\bdata-external-mount-value\b/);

wasm-port/tests/ui/node/verify_ini_panel_launch_api_manifest.mjs

@@ -63,6 +63,8 @@ assert.deepEqual(manifest, {
     "getShellSessionHandoffPackageMountState",
     "getShellSessionHandoffPackageMountDisplayViewModel",
     "getShellSessionHandoffPackageMountRenderState",
+    "getShellSessionHandoffMountDomContract",
+    "getShellSessionHandoffMountDomReadiness",
     "renderShellSessionHandoffMountState",
     "isSupportedShellSessionHandoffPackage",
     "getLauncherLinks",
@@ -182,6 +184,8 @@ assert.match(launchText, /\bgetShellSessionHandoffPackageRenderState\b/);
 assert.match(launchText, /\bgetShellSessionHandoffPackageMountState\b/);
 assert.match(launchText, /\bgetShellSessionHandoffPackageMountDisplayViewModel\b/);
 assert.match(launchText, /\bgetShellSessionHandoffPackageMountRenderState\b/);
+assert.match(launchText, /\bgetShellSessionHandoffMountDomContract\b/);
+assert.match(launchText, /\bgetShellSessionHandoffMountDomReadiness\b/);
 assert.match(launchText, /\brenderShellSessionHandoffMountState\b/);
 assert.match(launchText, /\bisSupportedShellSessionHandoffPackage\b/);
 assert.match(launchText, /\bdata-handoff-mount\b/);

wasm-port/tests/ui/node/verify_ini_panel_shell_integration_manifest.mjs

@@ -23,6 +23,8 @@ import {
   createIniPanelShellSessionHandoffPackageMountDisplayViewModel,
   createIniPanelShellSessionHandoffPackageMountRenderState,
   createIniPanelShellSessionHandoffPackageMountState,
+  createIniPanelShellSessionHandoffMountDomContract,
+  createIniPanelShellSessionHandoffMountDomReadiness,
   createIniPanelShellSessionHandoffPackageReport,
   createIniPanelShellSessionHandoffPackageRenderState,
   createIniPanelShellSessionHandoffPackageSchema,
@@ -93,6 +95,7 @@ const handoffPackageMountDisplayViewModel = createIniPanelShellSessionHandoffPac
 const handoffPackageMountRenderState = createIniPanelShellSessionHandoffPackageMountRenderState(
   handoffPackageMountDisplayViewModel,
 );
+const handoffMountDomContract = createIniPanelShellSessionHandoffMountDomContract();
 
 assert.deepEqual(schema, {
   apiName: "ini-panel-shell-integration",
@@ -148,7 +151,7 @@ assert.deepEqual(readiness, {
   counts: {
     pages: 2,
     launcherLinks: 2,
-    launchMethods: 27,
+    launchMethods: 29,
     controlPageMethods: 11,
     persistenceCapabilities: 3,
   },
@@ -210,7 +213,7 @@ assert.deepEqual(handoffSummary, {
     counts: {
       pages: 2,
       launcherLinks: 2,
-      launchMethods: 27,
+      launchMethods: 29,
       controlPageMethods: 11,
       persistenceCapabilities: 3,
     },
@@ -666,6 +669,38 @@ assert.deepEqual(handoffPackageMountRenderState, {
     handoffScope: "mount",
   },
 });
+assert.deepEqual(handoffMountDomContract, {
+  apiName: "ini-panel-shell-session-handoff-mount-dom-contract",
+  contractVersion: 1,
+  requiredNodeIds: ["mount", "status", "rows"],
+  selectors: {
+    mount: "[data-handoff-mount]",
+    status: "[data-handoff-mount-status]",
+    rows: "[data-handoff-mount-rows]",
+  },
+  mountDatasetKeys: ["handoffPhase", "handoffReady", "handoffScope"],
+  rowDatasetPrefix: "handoffMount",
+  rowDatasetKeys: {
+    term: ["handoffMountRow", "handoffMountStatus"],
+    detail: ["handoffMountValue", "handoffMountStatus"],
+  },
+  renderResultFields: ["rendered", "statusLine", "rowCount", "rowIds", "dataset"],
+});
+assert.deepEqual(createIniPanelShellSessionHandoffMountDomReadiness({ documentRef: null }), {
+  apiName: "ini-panel-shell-session-handoff-mount-dom-readiness",
+  readinessVersion: 1,
+  phase: "blocked",
+  ready: false,
+  missing: ["document", "mount", "status", "rows"],
+  checks: {
+    document: false,
+    mount: false,
+    status: false,
+    rows: false,
+    rowDatasetPrefix: true,
+  },
+  contract: handoffMountDomContract,
+});
 assert.deepEqual(
   createIniPanelShellSessionHandoffPackageMountState({
     handoffPackage,
@@ -1077,7 +1112,7 @@ assert.deepEqual(createIniPanelShellIntegrationReadiness(blockedManifest), {
   counts: {
     pages: 2,
     launcherLinks: 2,
-    launchMethods: 27,
+    launchMethods: 29,
     controlPageMethods: 11,
     persistenceCapabilities: 3,
   },
@@ -1246,6 +1281,8 @@ assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPack
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageMountDisplayViewModel\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageMountRenderState\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageMountState\b/);
+assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffMountDomContract\b/);
+assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffMountDomReadiness\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageReport\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageRenderState\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageSchema\b/);
@@ -1271,6 +1308,8 @@ assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageDisplayViewMode
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageMountDisplayViewModel\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageMountRenderState\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageMountState\b/);
+assert.match(docText, /\bcreateIniPanelShellSessionHandoffMountDomContract\b/);
+assert.match(docText, /\bcreateIniPanelShellSessionHandoffMountDomReadiness\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageReport\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageRenderState\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageSchema\b/);

wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs

@@ -23,6 +23,8 @@ import {
   createIniPanelShellSessionHandoffPackageMountDisplayViewModel,
   createIniPanelShellSessionHandoffPackageMountRenderState,
   createIniPanelShellSessionHandoffPackageMountState,
+  createIniPanelShellSessionHandoffMountDomContract,
+  createIniPanelShellSessionHandoffMountDomReadiness,
   renderIniPanelShellSessionHandoffMountState,
   createIniPanelShellSessionHandoffPackageReport,
   createIniPanelShellSessionHandoffPackageRenderState,
@@ -94,6 +96,8 @@ assert.equal(typeof createIniPanelShellSessionHandoffPackageDisplayViewModel, "f
 assert.equal(typeof createIniPanelShellSessionHandoffPackageMountDisplayViewModel, "function");
 assert.equal(typeof createIniPanelShellSessionHandoffPackageMountRenderState, "function");
 assert.equal(typeof createIniPanelShellSessionHandoffPackageMountState, "function");
+assert.equal(typeof createIniPanelShellSessionHandoffMountDomContract, "function");
+assert.equal(typeof createIniPanelShellSessionHandoffMountDomReadiness, "function");
 assert.equal(typeof renderIniPanelShellSessionHandoffMountState, "function");
 assert.equal(typeof createIniPanelShellSessionHandoffPackageReport, "function");
 assert.equal(typeof createIniPanelShellSessionHandoffPackageRenderState, "function");
@@ -247,6 +251,10 @@ assert.deepEqual(
     shellViewModel.shellSessionHandoffPackageMountDisplayViewModel,
   ),
 );
+assert.deepEqual(
+  shellViewModel.shellSessionHandoffMountDomContract,
+  createIniPanelShellSessionHandoffMountDomContract(),
+);
 assert.equal(isSupportedIniPanelShellSessionHandoffPackage(shellViewModel.shellSessionHandoffPackage), true);
 assert.deepEqual(shellViewModel.shellSessionHandoffDisplayViewModel, {
   phase: "ready",
@@ -566,6 +574,23 @@ assert.deepEqual(shellViewModel.shellSessionHandoffPackageMountRenderState, {
     handoffScope: "mount",
   },
 });
+assert.deepEqual(shellViewModel.shellSessionHandoffMountDomContract, {
+  apiName: "ini-panel-shell-session-handoff-mount-dom-contract",
+  contractVersion: 1,
+  requiredNodeIds: ["mount", "status", "rows"],
+  selectors: {
+    mount: "[data-handoff-mount]",
+    status: "[data-handoff-mount-status]",
+    rows: "[data-handoff-mount-rows]",
+  },
+  mountDatasetKeys: ["handoffPhase", "handoffReady", "handoffScope"],
+  rowDatasetPrefix: "handoffMount",
+  rowDatasetKeys: {
+    term: ["handoffMountRow", "handoffMountStatus"],
+    detail: ["handoffMountValue", "handoffMountStatus"],
+  },
+  renderResultFields: ["rendered", "statusLine", "rowCount", "rowIds", "dataset"],
+});
 assert.equal(
   createIniPanelShellSessionHandoffPackageMountState({
     handoffPackage: shellViewModel.shellSessionHandoffPackage,
@@ -662,6 +687,14 @@ assert.equal(
   shellViewModel.createShellSessionHandoffPackageMountRenderState,
   createIniPanelShellSessionHandoffPackageMountRenderState,
 );
+assert.equal(
+  shellViewModel.createShellSessionHandoffMountDomContract,
+  createIniPanelShellSessionHandoffMountDomContract,
+);
+assert.equal(
+  shellViewModel.createShellSessionHandoffMountDomReadiness,
+  createIniPanelShellSessionHandoffMountDomReadiness,
+);
 assert.equal(
   shellViewModel.renderShellSessionHandoffMountState,
   renderIniPanelShellSessionHandoffMountState,
@@ -735,6 +768,33 @@ const mountStatusNode = { textContent: "" };
 const mountDocument = {
   createElement: (tagName) => ({ tagName, dataset: {}, textContent: "" }),
 };
+assert.deepEqual(
+  createIniPanelShellSessionHandoffMountDomReadiness({
+    documentRef: mountDocument,
+    mountNode,
+    statusNode: mountStatusNode,
+    rowsNode: mountRowsNode,
+  }),
+  {
+    apiName: "ini-panel-shell-session-handoff-mount-dom-readiness",
+    readinessVersion: 1,
+    phase: "ready",
+    ready: true,
+    missing: [],
+    checks: {
+      document: true,
+      mount: true,
+      status: true,
+      rows: true,
+      rowDatasetPrefix: true,
+    },
+    contract: createIniPanelShellSessionHandoffMountDomContract(),
+  },
+);
+assert.deepEqual(
+  createIniPanelShellSessionHandoffMountDomReadiness({ documentRef: mountDocument }).missing,
+  ["mount", "status", "rows"],
+);
 assert.deepEqual(
   renderIniPanelShellSessionHandoffMountState(shellViewModel.shellSessionHandoffPackageMountRenderState, {
     documentRef: mountDocument,
@@ -762,6 +822,15 @@ assert.deepEqual(
 );
 assert.equal(mountRowsNode.children[7].dataset.handoffMountValue, "session-load-state");
 assert.equal(mountRowsNode.children[7].dataset.handoffMountStatus, "blocked");
+const externalContract = createIniPanelShellSessionHandoffMountDomContract({
+  rowDatasetPrefix: "externalMount",
+  selectors: {
+    mount: "[data-external-shell-mount]",
+    status: "[data-external-shell-mount-status]",
+    rows: "[data-external-shell-mount-rows]",
+  },
+});
+assert.equal(externalContract.rowDatasetKeys.detail[0], "externalMountValue");
 
 assert.deepEqual(controller.render(), { rendered: true });
 assert.equal(statusNode.textContent, "run-gcode | ok | -");