推进 INI 面板 shell handoff workflow DOM mount helper

2026-06-15 14:28:22 +08:00
parent e1e0c7f6d2
commit 6b6629ce73
9 changed files with 530 additions and 4 deletions
--- a/text12.txt
+++ b/text12.txt
@@ -3246,3 +3246,99 @@ host_wasm_opfs_browser_smokes=ok
 `renderIniPanelShellSessionHandoffWorkflowState()` 或 `mountIniPanelShellSessionHandoffWorkflow()`），把
 workflow render-state 渲染进稳定 DOM contract，方便外部 shell 直接挂载 end-to-end handoff 总览；仍保持只读，
 不新增控制按钮，不解析 G-code。
+
+四十一、2026-06-15 继续执行记录：INI panel shell handoff workflow DOM mount helper
+
+本轮按“第一原则：加快实质性推进”继续推进 SDK/API surface 与 browser/UI workflow，为 shell
+handoff 增加 workflow DOM contract/readiness/render/mount helper，让外部 shell 可以直接挂载
+end-to-end handoff 总览 DOM。
+
+完成内容：
+
+- `ui-shell.js` 新增：
+  - `createIniPanelShellSessionHandoffWorkflowDomContract()`；
+  - `createIniPanelShellSessionHandoffWorkflowDomReadiness()`；
+  - `renderIniPanelShellSessionHandoffWorkflowState()`；
+  - `mountIniPanelShellSessionHandoffWorkflow()`；
+- workflow DOM helper 复用现有 mount DOM helper 模式，提供稳定 selectors、dataset keys、row dataset keys、
+  readiness 检查、render result 和 structured mount result；
+- `createIniPanelShellViewModel()` 暴露：
+  - `shellSessionHandoffWorkflowDomContract`；
+  - `createShellSessionHandoffWorkflowDomContract`；
+  - `createShellSessionHandoffWorkflowDomReadiness`；
+  - `renderShellSessionHandoffWorkflowState`；
+  - `mountShellSessionHandoffWorkflow`；
+- `createIniPanelLaunchApiManifest().methods` 新增：
+  - `getShellSessionHandoffWorkflowDomContract`；
+  - `getShellSessionHandoffWorkflowDomReadiness`；
+  - `renderShellSessionHandoffWorkflowState`；
+  - `mountShellSessionHandoffWorkflow`；
+- launch method count 更新为 39；
+- `launch.html` 新增默认 workflow overview DOM 区域：
+  - `[data-handoff-workflow]`；
+  - `[data-handoff-workflow-status]`；
+  - `[data-handoff-workflow-rows]`；
+- `launch.html` 的 `window.linuxCncIniPanelLaunchApi` 暴露对应 browser API，并默认渲染 workflow overview；
+- `ini_panel_shell_integration_workflow_smoke.html` 新增外部 shell-owned workflow DOM 区域：
+  - `[data-external-shell-workflow]`；
+  - `[data-external-shell-workflow-status]`；
+  - `[data-external-shell-workflow-rows]`；
+- browser smoke 通过 shared workflow DOM helpers 校验：
+  - DOM readiness；
+  - workflow DOM mount phase；
+  - workflow row count；
+  - workflow dataset scope；
+  - workflow status line；
+- Node smoke 覆盖 workflow DOM contract/readiness/render/mount 的 ready/missing 路径；
+- 文档同步记录 workflow DOM helper 用法；
+- 未新增控制按钮；
+- 未解析 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 workflow overview page/helper，把 workflow
+DOM mount helper 接入一个独立 overview surface 或 shared panel band，方便外部 shell 无需手动拼 DOM
+就能复用 end-to-end handoff 总览；仍保持只读，不新增控制按钮，不解析 G-code。
--- a/wasm-port/docs/panel-entry.md
+++ b/wasm-port/docs/panel-entry.md
@@ -37,6 +37,10 @@ import {
  createIniPanelShellSessionHandoffWorkflowSummary,
  createIniPanelShellSessionHandoffWorkflowDisplayViewModel,
  createIniPanelShellSessionHandoffWorkflowRenderState,
+  createIniPanelShellSessionHandoffWorkflowDomContract,
+  createIniPanelShellSessionHandoffWorkflowDomReadiness,
+  renderIniPanelShellSessionHandoffWorkflowState,
+  mountIniPanelShellSessionHandoffWorkflow,
  renderIniPanelShellSessionHandoffMountState,
  createIniPanelShellSessionHandoffPackageReport,
  createIniPanelShellSessionHandoffPackageRenderState,
@@ -266,12 +270,28 @@ when an outer shell needs that end-to-end summary compressed into stable
 `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
 `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 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,
--- a/wasm-port/runtime/ui/ini-panel/launch.html
+++ b/wasm-port/runtime/ui/ini-panel/launch.html
@@ -99,6 +99,10 @@
        <p data-handoff-mount-status>Checking shell handoff mount readiness.</p>
        <dl data-handoff-mount-rows></dl>
      </section>
+      <section class="handoff-status" aria-label="Shell handoff workflow summary" data-handoff-workflow>
+        <p data-handoff-workflow-status>Checking shell handoff workflow summary.</p>
+        <dl data-handoff-workflow-rows></dl>
+      </section>
    </section>
  </main>
  <script type="module">
@@ -114,6 +118,10 @@
      createIniPanelShellSessionHandoffWorkflowSummary,
      createIniPanelShellSessionHandoffWorkflowDisplayViewModel,
      createIniPanelShellSessionHandoffWorkflowRenderState,
+      createIniPanelShellSessionHandoffWorkflowDomContract,
+      createIniPanelShellSessionHandoffWorkflowDomReadiness,
+      renderIniPanelShellSessionHandoffWorkflowState,
+      mountIniPanelShellSessionHandoffWorkflow,
      renderIniPanelShellSessionHandoffMountState,
    } from "./ui-shell.js";

@@ -145,6 +153,8 @@
    }
    const handoffMountRenderState = shellViewModel.shellSessionHandoffPackageMountRenderState;
    renderIniPanelShellSessionHandoffMountState(handoffMountRenderState, { documentRef: document });
+    const handoffWorkflowRenderState = shellViewModel.shellSessionHandoffWorkflowRenderState;
+    renderIniPanelShellSessionHandoffWorkflowState(handoffWorkflowRenderState, { documentRef: document });

    window.linuxCncIniPanelLaunchApi = {
      isSupportedLaunchApiManifest: isSupportedIniPanelLaunchApiManifest,
@@ -244,6 +254,21 @@
          options ?? shellViewModel.shellSessionHandoffWorkflowDisplayViewModel,
        )
      ),
+      getShellSessionHandoffWorkflowDomContract: (options) => (
+        createIniPanelShellSessionHandoffWorkflowDomContract(options)
+      ),
+      getShellSessionHandoffWorkflowDomReadiness: (options) => (
+        createIniPanelShellSessionHandoffWorkflowDomReadiness(options ?? { documentRef: document })
+      ),
+      renderShellSessionHandoffWorkflowState: (renderState, options) => (
+        renderIniPanelShellSessionHandoffWorkflowState(renderState, options ?? { documentRef: document })
+      ),
+      mountShellSessionHandoffWorkflow: (options) => (
+        mountIniPanelShellSessionHandoffWorkflow(options ?? {
+          renderState: shellViewModel.shellSessionHandoffWorkflowRenderState,
+          documentRef: document,
+        })
+      ),
      isSupportedShellSessionHandoffPackage: shellViewModel.isSupportedShellSessionHandoffPackage,
      getLauncherLinks: () => shellViewModel.launcherLinks,
      getControlPageApiMethods: () => shellViewModel.controlPage.browserApiMethods,
--- a/wasm-port/runtime/ui/ini-panel/ui-shell.js
+++ b/wasm-port/runtime/ui/ini-panel/ui-shell.js
@@ -152,6 +152,10 @@ export function createIniPanelLaunchApiManifest(entries = getVisibleIniPanelEntr
      "getShellSessionHandoffWorkflowSummary",
      "getShellSessionHandoffWorkflowDisplayViewModel",
      "getShellSessionHandoffWorkflowRenderState",
+      "getShellSessionHandoffWorkflowDomContract",
+      "getShellSessionHandoffWorkflowDomReadiness",
+      "renderShellSessionHandoffWorkflowState",
+      "mountShellSessionHandoffWorkflow",
      "isSupportedShellSessionHandoffPackage",
      "getLauncherLinks",
      "getControlPageApiMethods",
@@ -1529,6 +1533,187 @@ export function createIniPanelShellSessionHandoffWorkflowRenderState(
  };
 }

+export function createIniPanelShellSessionHandoffWorkflowDomContract({
+  rowDatasetPrefix = "handoffWorkflow",
+  selectors = {},
+} = {}) {
+  const mountSelector = selectors.mount ?? "[data-handoff-workflow]";
+  const statusSelector = selectors.status ?? "[data-handoff-workflow-status]";
+  const rowsSelector = selectors.rows ?? "[data-handoff-workflow-rows]";
+  return {
+    apiName: "ini-panel-shell-session-handoff-workflow-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 createIniPanelShellSessionHandoffWorkflowDomReadiness({
+  rowDatasetPrefix = "handoffWorkflow",
+  contract = createIniPanelShellSessionHandoffWorkflowDomContract({ 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-workflow-dom-readiness",
+    readinessVersion: 1,
+    phase: ready ? "ready" : "blocked",
+    ready,
+    missing,
+    checks,
+    contract,
+  };
+}
+
+export function renderIniPanelShellSessionHandoffWorkflowState(
+  renderState = createIniPanelShellSessionHandoffWorkflowRenderState(),
+  {
+    rowDatasetPrefix = "handoffWorkflow",
+    contract = createIniPanelShellSessionHandoffWorkflowDomContract({ rowDatasetPrefix }),
+    documentRef = globalThis.document,
+    mountNode = documentRef?.querySelector?.(contract.selectors.mount),
+    statusNode = documentRef?.querySelector?.(contract.selectors.status),
+    rowsNode = documentRef?.querySelector?.(contract.selectors.rows),
+  } = {},
+) {
+  const readiness = createIniPanelShellSessionHandoffWorkflowDomReadiness({
+    contract,
+    documentRef,
+    mountNode,
+    statusNode,
+    rowsNode,
+  });
+  if (!readiness.ready) {
+    throw new Error(
+      `Shell handoff workflow DOM is not ready: ${readiness.missing.join(", ")}`,
+    );
+  }
+
+  mountNode.dataset.handoffPhase = renderState?.dataset?.handoffPhase ?? "blocked";
+  mountNode.dataset.handoffReady = renderState?.dataset?.handoffReady ?? "false";
+  mountNode.dataset.handoffScope = renderState?.dataset?.handoffScope ?? "workflow";
+  statusNode.textContent = renderState?.statusLine ?? "Blocked: No workflow render state";
+  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[`${effectiveRowDatasetPrefix}Row`] = row.id;
+    term.dataset[`${effectiveRowDatasetPrefix}Status`] = renderState?.ready ? "pass" : "blocked";
+    term.textContent = row.label;
+    const detail = documentRef.createElement("dd");
+    detail.dataset[`${effectiveRowDatasetPrefix}Value`] = row.id;
+    detail.dataset[`${effectiveRowDatasetPrefix}Status`] = renderState?.ready ? "pass" : "blocked";
+    detail.textContent = row.value;
+    rowsNode.append(term, detail);
+  }
+
+  return {
+    rendered: true,
+    statusLine: statusNode.textContent,
+    rowCount: rows.length,
+    rowIds: rows.map(({ id }) => id),
+    dataset: {
+      handoffPhase: mountNode.dataset.handoffPhase,
+      handoffReady: mountNode.dataset.handoffReady,
+      handoffScope: mountNode.dataset.handoffScope,
+    },
+  };
+}
+
+export function mountIniPanelShellSessionHandoffWorkflow({
+  renderState = createIniPanelShellSessionHandoffWorkflowRenderState(),
+  rowDatasetPrefix = "handoffWorkflow",
+  contract = createIniPanelShellSessionHandoffWorkflowDomContract({ rowDatasetPrefix }),
+  documentRef = globalThis.document,
+  mountNode = documentRef?.querySelector?.(contract.selectors.mount),
+  statusNode = documentRef?.querySelector?.(contract.selectors.status),
+  rowsNode = documentRef?.querySelector?.(contract.selectors.rows),
+} = {}) {
+  const domReadiness = createIniPanelShellSessionHandoffWorkflowDomReadiness({
+    contract,
+    documentRef,
+    mountNode,
+    statusNode,
+    rowsNode,
+  });
+  if (!domReadiness.ready) {
+    return {
+      apiName: "ini-panel-shell-session-handoff-workflow-dom-mount",
+      workflowVersion: 1,
+      phase: "blocked",
+      ready: false,
+      statusLine: `Blocked: ${domReadiness.missing.join(", ")}`,
+      contract,
+      domReadiness,
+      renderState,
+      renderResult: null,
+      error: null,
+    };
+  }
+
+  try {
+    const renderResult = renderIniPanelShellSessionHandoffWorkflowState(renderState, {
+      contract,
+      documentRef,
+      mountNode,
+      statusNode,
+      rowsNode,
+    });
+    return {
+      apiName: "ini-panel-shell-session-handoff-workflow-dom-mount",
+      workflowVersion: 1,
+      phase: renderState?.phase === "ready" ? "ready" : "blocked",
+      ready: renderState?.ready === true,
+      statusLine: renderResult.statusLine,
+      contract,
+      domReadiness,
+      renderState,
+      renderResult,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      apiName: "ini-panel-shell-session-handoff-workflow-dom-mount",
+      workflowVersion: 1,
+      phase: "blocked",
+      ready: false,
+      statusLine: `Blocked: ${error?.message ?? "workflow DOM mount error"}`,
+      contract,
+      domReadiness,
+      renderState,
+      renderResult: null,
+      error: error?.message ?? String(error),
+    };
+  }
+}
+
 export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries()) {
  const shellIntegrationManifest = createIniPanelShellIntegrationManifest(entries);
  const shellIntegrationReadiness = createIniPanelShellIntegrationReadiness(shellIntegrationManifest);
@@ -1614,6 +1799,7 @@ export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries
  const shellSessionHandoffWorkflowRenderState = createIniPanelShellSessionHandoffWorkflowRenderState(
    shellSessionHandoffWorkflowDisplayViewModel,
  );
+  const shellSessionHandoffWorkflowDomContract = createIniPanelShellSessionHandoffWorkflowDomContract();
  return {
    pages: entries.map(({ id, href, title }) => ({
      id,
@@ -1645,6 +1831,7 @@ export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries
    shellSessionHandoffWorkflowSummary,
    shellSessionHandoffWorkflowDisplayViewModel,
    shellSessionHandoffWorkflowRenderState,
+    shellSessionHandoffWorkflowDomContract,
    launchApiSchema: createIniPanelLaunchApiSchema(),
    launchApiManifest: createIniPanelLaunchApiManifest(entries),
    isSupportedShellIntegrationManifest: isSupportedIniPanelShellIntegrationManifest,
@@ -1676,6 +1863,10 @@ export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries
    createShellSessionHandoffWorkflowSummary: createIniPanelShellSessionHandoffWorkflowSummary,
    createShellSessionHandoffWorkflowDisplayViewModel: createIniPanelShellSessionHandoffWorkflowDisplayViewModel,
    createShellSessionHandoffWorkflowRenderState: createIniPanelShellSessionHandoffWorkflowRenderState,
+    createShellSessionHandoffWorkflowDomContract: createIniPanelShellSessionHandoffWorkflowDomContract,
+    createShellSessionHandoffWorkflowDomReadiness: createIniPanelShellSessionHandoffWorkflowDomReadiness,
+    renderShellSessionHandoffWorkflowState: renderIniPanelShellSessionHandoffWorkflowState,
+    mountShellSessionHandoffWorkflow: mountIniPanelShellSessionHandoffWorkflow,
    isSupportedShellSessionHandoffPackage: isSupportedIniPanelShellSessionHandoffPackage,
    controlPage: {
      browserApiSchema: createControlPageBrowserApiSchema(),
--- a/wasm-port/tests/browser/ini_panel_shell_integration_workflow_smoke.html
+++ b/wasm-port/tests/browser/ini_panel_shell_integration_workflow_smoke.html
@@ -10,6 +10,10 @@
    <p data-external-shell-mount-status>waiting</p>
    <dl data-external-shell-mount-rows></dl>
  </section>
+  <section data-external-shell-workflow>
+    <p data-external-shell-workflow-status>waiting</p>
+    <dl data-external-shell-workflow-rows></dl>
+  </section>
  <script type="module">
    function assertEqual(actual, expected, label) {
      if (actual !== expected) {
@@ -94,6 +98,10 @@ TOOL_TABLE = browser-shell-tool.tbl
        !launchApi?.getShellSessionHandoffWorkflowSummary ||
        !launchApi?.getShellSessionHandoffWorkflowDisplayViewModel ||
        !launchApi?.getShellSessionHandoffWorkflowRenderState ||
+        !launchApi?.getShellSessionHandoffWorkflowDomContract ||
+        !launchApi?.getShellSessionHandoffWorkflowDomReadiness ||
+        !launchApi?.renderShellSessionHandoffWorkflowState ||
+        !launchApi?.mountShellSessionHandoffWorkflow ||
        !launchApi?.isSupportedShellSessionHandoffPackage
      ) {
        throw new Error("launch API namespace did not expose shell integration helpers");
@@ -371,6 +379,23 @@ TOOL_TABLE = browser-shell-tool.tbl
      const workflowRenderState = launchApi.getShellSessionHandoffWorkflowRenderState(
        workflowDisplayResult,
      );
+      const externalWorkflowDomContract = launchApi.getShellSessionHandoffWorkflowDomContract({
+        rowDatasetPrefix: "externalWorkflow",
+        selectors: {
+          mount: "[data-external-shell-workflow]",
+          status: "[data-external-shell-workflow-status]",
+          rows: "[data-external-shell-workflow-rows]",
+        },
+      });
+      const externalWorkflowDomReadiness = launchApi.getShellSessionHandoffWorkflowDomReadiness({
+        contract: externalWorkflowDomContract,
+        documentRef: document,
+      });
+      const workflowDomMountResult = launchApi.mountShellSessionHandoffWorkflow({
+        renderState: workflowRenderState,
+        contract: externalWorkflowDomContract,
+        documentRef: document,
+      });
      assertEqual(readonlyStatusResult.phase, "ready", "shell handoff readonly status result phase");
      assertEqual(readonlyStatusResult.ready, true, "shell handoff readonly status result readiness");
      assertEqual(
@@ -387,6 +412,19 @@ TOOL_TABLE = browser-shell-tool.tbl
      assertEqual(workflowRenderState.phase, "ready", "shell handoff workflow render-state phase");
      assertEqual(workflowRenderState.statusLine, "Ready: No blocking reasons", "shell handoff workflow render-state status");
      assertEqual(workflowRenderState.dataset.handoffScope, "workflow", "shell handoff workflow render-state scope");
+      assertEqual(externalWorkflowDomReadiness.ready, true, "shell handoff workflow DOM readiness");
+      assertEqual(workflowDomMountResult.phase, "ready", "shell handoff workflow DOM mount phase");
+      assertEqual(workflowDomMountResult.renderResult.rowCount, 5, "shell handoff workflow DOM mount rows");
+      assertEqual(
+        document.querySelector("[data-external-shell-workflow]").dataset.handoffScope,
+        "workflow",
+        "shell handoff workflow DOM scope",
+      );
+      assertEqual(
+        document.querySelector("[data-external-shell-workflow-status]").textContent,
+        "Ready: No blocking reasons",
+        "shell handoff workflow DOM status",
+      );
      assertEqual(
        readonlyStatus.workflowStatus.lastAction,
        "load-session",
--- a/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs
@@ -35,6 +35,10 @@ import {
  createIniPanelShellSessionHandoffWorkflowSummary,
  createIniPanelShellSessionHandoffWorkflowDisplayViewModel,
  createIniPanelShellSessionHandoffWorkflowRenderState,
+  createIniPanelShellSessionHandoffWorkflowDomContract,
+  createIniPanelShellSessionHandoffWorkflowDomReadiness,
+  renderIniPanelShellSessionHandoffWorkflowState,
+  mountIniPanelShellSessionHandoffWorkflow,
  renderIniPanelShellSessionHandoffMountState,
  createIniPanelShellSessionHandoffPackageReport,
  createIniPanelShellSessionHandoffPackageRenderState,
@@ -109,6 +113,10 @@ const requiredShellExports = [
  "createIniPanelShellSessionHandoffWorkflowSummary",
  "createIniPanelShellSessionHandoffWorkflowDisplayViewModel",
  "createIniPanelShellSessionHandoffWorkflowRenderState",
+  "createIniPanelShellSessionHandoffWorkflowDomContract",
+  "createIniPanelShellSessionHandoffWorkflowDomReadiness",
+  "renderIniPanelShellSessionHandoffWorkflowState",
+  "mountIniPanelShellSessionHandoffWorkflow",
  "renderIniPanelShellSessionHandoffMountState",
  "createIniPanelShellSessionHandoffPackageReport",
  "createIniPanelShellSessionHandoffPackageRenderState",
@@ -327,6 +335,18 @@ assert.equal(
  createIniPanelShellSessionHandoffWorkflowRenderState().phase,
  "blocked",
 );
+assert.equal(
+  createIniPanelShellSessionHandoffWorkflowDomContract().selectors.mount,
+  "[data-handoff-workflow]",
+);
+assert.equal(
+  createIniPanelShellSessionHandoffWorkflowDomReadiness().phase,
+  "blocked",
+);
+assert.equal(
+  mountIniPanelShellSessionHandoffWorkflow().phase,
+  "blocked",
+);
 assert.equal(isSupportedIniPanelShellSessionHandoffPackage(createIniPanelShellViewModel().shellSessionHandoffPackage), true);
 assert.equal(isSupportedIniPanelShellIntegrationManifest(createIniPanelShellViewModel().shellIntegrationManifest), true);
 assert.deepEqual(createIniPanelShellViewModel().launchApiSchema, createIniPanelLaunchApiSchema());
@@ -492,6 +512,10 @@ assert.match(docText, /\blinuxCncIniPanelLaunchApi\.readShellSessionHandoffStatu
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getShellSessionHandoffWorkflowSummary\b/);
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getShellSessionHandoffWorkflowDisplayViewModel\b/);
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getShellSessionHandoffWorkflowRenderState\b/);
+assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getShellSessionHandoffWorkflowDomContract\b/);
+assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getShellSessionHandoffWorkflowDomReadiness\b/);
+assert.match(docText, /\blinuxCncIniPanelLaunchApi\.renderShellSessionHandoffWorkflowState\b/);
+assert.match(docText, /\blinuxCncIniPanelLaunchApi\.mountShellSessionHandoffWorkflow\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/);
@@ -516,6 +540,10 @@ assert.match(shellIntegrationWorkflowSmokeText, /\breadShellSessionHandoffStatus
 assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffWorkflowSummary\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffWorkflowDisplayViewModel\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffWorkflowRenderState\b/);
+assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffWorkflowDomContract\b/);
+assert.match(shellIntegrationWorkflowSmokeText, /\bgetShellSessionHandoffWorkflowDomReadiness\b/);
+assert.match(shellIntegrationWorkflowSmokeText, /\brenderShellSessionHandoffWorkflowState\b/);
+assert.match(shellIntegrationWorkflowSmokeText, /\bmountShellSessionHandoffWorkflow\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\brenderShellSessionHandoffMountState\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\bdata-external-shell-mount\b/);
 assert.match(shellIntegrationWorkflowSmokeText, /\bdata-external-mount-value\b/);
--- a/wasm-port/tests/ui/node/verify_ini_panel_launch_api_manifest.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_launch_api_manifest.mjs
@@ -72,6 +72,10 @@ assert.deepEqual(manifest, {
    "getShellSessionHandoffWorkflowSummary",
    "getShellSessionHandoffWorkflowDisplayViewModel",
    "getShellSessionHandoffWorkflowRenderState",
+    "getShellSessionHandoffWorkflowDomContract",
+    "getShellSessionHandoffWorkflowDomReadiness",
+    "renderShellSessionHandoffWorkflowState",
+    "mountShellSessionHandoffWorkflow",
    "isSupportedShellSessionHandoffPackage",
    "getLauncherLinks",
    "getControlPageApiMethods",
@@ -199,7 +203,14 @@ assert.match(launchText, /\breadShellSessionHandoffStatusFromControlPage\b/);
 assert.match(launchText, /\bgetShellSessionHandoffWorkflowSummary\b/);
 assert.match(launchText, /\bgetShellSessionHandoffWorkflowDisplayViewModel\b/);
 assert.match(launchText, /\bgetShellSessionHandoffWorkflowRenderState\b/);
+assert.match(launchText, /\bgetShellSessionHandoffWorkflowDomContract\b/);
+assert.match(launchText, /\bgetShellSessionHandoffWorkflowDomReadiness\b/);
+assert.match(launchText, /\brenderShellSessionHandoffWorkflowState\b/);
+assert.match(launchText, /\bmountShellSessionHandoffWorkflow\b/);
 assert.match(launchText, /\bisSupportedShellSessionHandoffPackage\b/);
+assert.match(launchText, /\bdata-handoff-workflow\b/);
+assert.match(launchText, /\bdata-handoff-workflow-status\b/);
+assert.match(launchText, /\bdata-handoff-workflow-rows\b/);
 assert.match(launchText, /\bdata-handoff-mount\b/);
 assert.match(launchText, /\bdata-handoff-mount-status\b/);
 assert.match(launchText, /\bdata-handoff-mount-rows\b/);
--- a/wasm-port/tests/ui/node/verify_ini_panel_shell_integration_manifest.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_shell_integration_manifest.mjs
@@ -31,6 +31,10 @@ import {
  createIniPanelShellSessionHandoffWorkflowSummary,
  createIniPanelShellSessionHandoffWorkflowDisplayViewModel,
  createIniPanelShellSessionHandoffWorkflowRenderState,
+  createIniPanelShellSessionHandoffWorkflowDomContract,
+  createIniPanelShellSessionHandoffWorkflowDomReadiness,
+  renderIniPanelShellSessionHandoffWorkflowState,
+  mountIniPanelShellSessionHandoffWorkflow,
  createIniPanelShellSessionHandoffPackageReport,
  createIniPanelShellSessionHandoffPackageRenderState,
  createIniPanelShellSessionHandoffPackageSchema,
@@ -157,7 +161,7 @@ assert.deepEqual(readiness, {
  counts: {
    pages: 2,
    launcherLinks: 2,
-    launchMethods: 35,
+    launchMethods: 39,
    controlPageMethods: 11,
    persistenceCapabilities: 3,
  },
@@ -219,7 +223,7 @@ assert.deepEqual(handoffSummary, {
    counts: {
      pages: 2,
      launcherLinks: 2,
-      launchMethods: 35,
+      launchMethods: 39,
      controlPageMethods: 11,
      persistenceCapabilities: 3,
    },
@@ -731,6 +735,18 @@ assert.equal(
  createIniPanelShellSessionHandoffWorkflowRenderState().phase,
  "blocked",
 );
+assert.equal(
+  createIniPanelShellSessionHandoffWorkflowDomContract().selectors.mount,
+  "[data-handoff-workflow]",
+);
+assert.equal(
+  createIniPanelShellSessionHandoffWorkflowDomReadiness().phase,
+  "blocked",
+);
+assert.equal(
+  mountIniPanelShellSessionHandoffWorkflow().phase,
+  "blocked",
+);
 assert.deepEqual(
  createIniPanelShellSessionHandoffPackageMountState({
    handoffPackage,
@@ -1142,7 +1158,7 @@ assert.deepEqual(createIniPanelShellIntegrationReadiness(blockedManifest), {
  counts: {
    pages: 2,
    launcherLinks: 2,
-    launchMethods: 35,
+    launchMethods: 39,
    controlPageMethods: 11,
    persistenceCapabilities: 3,
  },
@@ -1319,6 +1335,10 @@ assert.match(shellText, /\bexport function readIniPanelShellSessionHandoffStatus
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffWorkflowSummary\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffWorkflowDisplayViewModel\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffWorkflowRenderState\b/);
+assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffWorkflowDomContract\b/);
+assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffWorkflowDomReadiness\b/);
+assert.match(shellText, /\bexport function renderIniPanelShellSessionHandoffWorkflowState\b/);
+assert.match(shellText, /\bexport function mountIniPanelShellSessionHandoffWorkflow\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageReport\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageRenderState\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageSchema\b/);
@@ -1352,6 +1372,10 @@ assert.match(docText, /\breadIniPanelShellSessionHandoffStatusFromControlPage\b/
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffWorkflowSummary\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffWorkflowDisplayViewModel\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffWorkflowRenderState\b/);
+assert.match(docText, /\bcreateIniPanelShellSessionHandoffWorkflowDomContract\b/);
+assert.match(docText, /\bcreateIniPanelShellSessionHandoffWorkflowDomReadiness\b/);
+assert.match(docText, /\brenderIniPanelShellSessionHandoffWorkflowState\b/);
+assert.match(docText, /\bmountIniPanelShellSessionHandoffWorkflow\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageReport\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageRenderState\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageSchema\b/);
--- a/wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs
@@ -31,6 +31,10 @@ import {
  createIniPanelShellSessionHandoffWorkflowSummary,
  createIniPanelShellSessionHandoffWorkflowDisplayViewModel,
  createIniPanelShellSessionHandoffWorkflowRenderState,
+  createIniPanelShellSessionHandoffWorkflowDomContract,
+  createIniPanelShellSessionHandoffWorkflowDomReadiness,
+  renderIniPanelShellSessionHandoffWorkflowState,
+  mountIniPanelShellSessionHandoffWorkflow,
  renderIniPanelShellSessionHandoffMountState,
  createIniPanelShellSessionHandoffPackageReport,
  createIniPanelShellSessionHandoffPackageRenderState,
@@ -110,6 +114,10 @@ assert.equal(typeof readIniPanelShellSessionHandoffStatusFromControlPage, "funct
 assert.equal(typeof createIniPanelShellSessionHandoffWorkflowSummary, "function");
 assert.equal(typeof createIniPanelShellSessionHandoffWorkflowDisplayViewModel, "function");
 assert.equal(typeof createIniPanelShellSessionHandoffWorkflowRenderState, "function");
+assert.equal(typeof createIniPanelShellSessionHandoffWorkflowDomContract, "function");
+assert.equal(typeof createIniPanelShellSessionHandoffWorkflowDomReadiness, "function");
+assert.equal(typeof renderIniPanelShellSessionHandoffWorkflowState, "function");
+assert.equal(typeof mountIniPanelShellSessionHandoffWorkflow, "function");
 assert.equal(typeof renderIniPanelShellSessionHandoffMountState, "function");
 assert.equal(typeof createIniPanelShellSessionHandoffPackageReport, "function");
 assert.equal(typeof createIniPanelShellSessionHandoffPackageRenderState, "function");
@@ -732,6 +740,22 @@ assert.equal(
  shellViewModel.createShellSessionHandoffWorkflowRenderState,
  createIniPanelShellSessionHandoffWorkflowRenderState,
 );
+assert.equal(
+  shellViewModel.createShellSessionHandoffWorkflowDomContract,
+  createIniPanelShellSessionHandoffWorkflowDomContract,
+);
+assert.equal(
+  shellViewModel.createShellSessionHandoffWorkflowDomReadiness,
+  createIniPanelShellSessionHandoffWorkflowDomReadiness,
+);
+assert.equal(
+  shellViewModel.renderShellSessionHandoffWorkflowState,
+  renderIniPanelShellSessionHandoffWorkflowState,
+);
+assert.equal(
+  shellViewModel.mountShellSessionHandoffWorkflow,
+  mountIniPanelShellSessionHandoffWorkflow,
+);
 assert.equal(shellViewModel.createShellSessionHandoffPackageReport, createIniPanelShellSessionHandoffPackageReport);
 assert.equal(shellViewModel.createShellSessionHandoffPackageSchema, createIniPanelShellSessionHandoffPackageSchema);
 assert.equal(shellViewModel.isSupportedShellSessionHandoffPackage, isSupportedIniPanelShellSessionHandoffPackage);
@@ -1006,6 +1030,75 @@ const readyWorkflowRenderState = createIniPanelShellSessionHandoffWorkflowRender
 );
 assert.equal(readyWorkflowRenderState.phase, "ready");
 assert.equal(readyWorkflowRenderState.statusLine, "Ready: No blocking reasons");
+assert.deepEqual(
+  createIniPanelShellSessionHandoffWorkflowDomReadiness({
+    documentRef: mountDocument,
+    mountNode,
+    statusNode: mountStatusNode,
+    rowsNode: mountRowsNode,
+  }),
+  {
+    apiName: "ini-panel-shell-session-handoff-workflow-dom-readiness",
+    readinessVersion: 1,
+    phase: "ready",
+    ready: true,
+    missing: [],
+    checks: {
+      document: true,
+      mount: true,
+      status: true,
+      rows: true,
+      rowDatasetPrefix: true,
+    },
+    contract: createIniPanelShellSessionHandoffWorkflowDomContract(),
+  },
+);
+assert.deepEqual(
+  createIniPanelShellSessionHandoffWorkflowDomReadiness({ documentRef: mountDocument }).missing,
+  ["mount", "status", "rows"],
+);
+assert.deepEqual(
+  renderIniPanelShellSessionHandoffWorkflowState(workflowRenderState, {
+    documentRef: mountDocument,
+    mountNode,
+    statusNode: mountStatusNode,
+    rowsNode: mountRowsNode,
+  }),
+  {
+    rendered: true,
+    statusLine: "Blocked: mount:blocked",
+    rowCount: 5,
+    rowIds: [
+      "mount-workflow",
+      "control-page-mount-workflow",
+      "readonly-status-workflow",
+      "readonly-status-missing-fields",
+      "blocking-reasons",
+    ],
+    dataset: {
+      handoffPhase: "blocked",
+      handoffReady: "false",
+      handoffScope: "workflow",
+    },
+  },
+);
+const workflowDomMountResult = mountIniPanelShellSessionHandoffWorkflow({
+  renderState: workflowRenderState,
+  documentRef: mountDocument,
+  mountNode,
+  statusNode: mountStatusNode,
+  rowsNode: mountRowsNode,
+});
+assert.equal(workflowDomMountResult.apiName, "ini-panel-shell-session-handoff-workflow-dom-mount");
+assert.equal(workflowDomMountResult.workflowVersion, 1);
+assert.equal(workflowDomMountResult.phase, "blocked");
+assert.equal(workflowDomMountResult.ready, false);
+assert.equal(workflowDomMountResult.renderResult.rowCount, 5);
+assert.equal(workflowDomMountResult.renderResult.dataset.handoffScope, "workflow");
+assert.equal(
+  mountIniPanelShellSessionHandoffWorkflow({ documentRef: mountDocument }).renderResult,
+  null,
+);
 assert.deepEqual(
  mountIniPanelShellSessionHandoff({ documentRef: mountDocument }).renderResult,
  null,