推进 INI 面板 workflow overview embedding DOM contract

2026-06-15 18:20:44 +08:00
parent f70fc09770
commit 3cfd4b371e
12 changed files with 207 additions and 12 deletions
--- a/text13.txt
+++ b/text13.txt
@@ -1492,3 +1492,96 @@ host_wasm_opfs_browser_smokes=ok
 `createIniPanelShellWorkflowOverviewEmbeddingDomContract()` 或等价 helper，定义 embedding
 report 渲染所需 mount/status/rows selectors、dataset keys 和 render-result fields，并为后续
 真实 DOM renderer 做准备；仍保持只读，不新增控制按钮，不解析 G-code。
+
+十四、2026-06-15 继续执行记录：INI panel workflow overview embedding DOM contract
+
+本轮按 `text13.txt` 执行，不扩展 `text12.txt`。继续推进 browser/UI workflow，新增只读
+workflow-overview embedding DOM contract，定义 embedding report 渲染所需的 mount/status/rows
+selectors、dataset keys 和 render-result fields，为后续真实 DOM renderer 做准备。
+
+完成内容：
+
+- `ui-shell.js` 新增 `createIniPanelShellWorkflowOverviewEmbeddingDomContract()`；
+- DOM contract 输出：
+  - `apiName: "ini-panel-shell-workflow-overview-embedding-dom-contract"`；
+  - `contractVersion: 1`；
+  - `requiredNodeIds: ["mount", "status", "rows"]`；
+  - 默认 selectors：
+    - `[data-workflow-overview-embedding]`；
+    - `[data-workflow-overview-embedding-status]`；
+    - `[data-workflow-overview-embedding-rows]`；
+  - `mountDatasetKeys`；
+  - `rowDatasetPrefix`；
+  - `rowDatasetKeys`；
+  - `renderResultFields`；
+- 支持外部 shell 传入自定义 `rowDatasetPrefix` 与 selectors；
+- `createIniPanelLaunchApiManifest().methods` 新增
+  `getWorkflowOverviewEmbeddingDomContract`；
+- `launch.html` 的 `window.linuxCncIniPanelLaunchApi` 新增真实 browser 入口
+  `getWorkflowOverviewEmbeddingDomContract()`；
+- `workflow-overview.html` 的 `window.linuxCncIniPanelWorkflowOverviewApi` 新增
+  `getWorkflowOverviewEmbeddingDomContract()`；
+- `verify_ini_panel_ui_shell.mjs` 覆盖默认 contract 完整 shape 与自定义 prefix/selectors；
+- `verify_ini_panel_launch_api_manifest.mjs` 覆盖 launch manifest 与 launch 页面真实 API；
+- `verify_ini_panel_shell_integration_manifest.mjs` 覆盖 helper export、默认 contract、
+  launch method count 与文档记录；
+- `verify_ini_panel_entry_docs.mjs` 与 `docs/panel-entry.md` 同步记录新 helper/API；
+- `ini_panel_workflow_overview_smoke.html` 校验 workflow overview iframe 自身 DOM contract API；
+- `ini_panel_launch_smoke.html` 校验真实 launch iframe 读取真实 workflow overview iframe 的
+  embedding DOM contract；
+- `ini_panel_shell_integration_workflow_smoke.html` 校验外部 shell workflow 可读取自定义
+  rowDatasetPrefix 的 DOM contract；
+- 未新增控制按钮；
+- 未执行 action-plan；
+- 未解析 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_workflow_overview_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
+```
+
+下一步建议：
+
+继续推进 browser/UI workflow。下一批建议新增只读
+`createIniPanelShellWorkflowOverviewEmbeddingDomReadiness()` 或等价 helper，检查 embedding
+report DOM contract 需要的 document/mount/status/rows 节点是否存在，输出 missing/checks，
+为真实 DOM renderer 做最后前置 gate；仍保持只读，不新增控制按钮，不解析 G-code。
--- a/wasm-port/docs/panel-entry.md
+++ b/wasm-port/docs/panel-entry.md
@@ -44,6 +44,7 @@ import {
  createIniPanelShellWorkflowOverviewEmbeddingReport,
  createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel,
  createIniPanelShellWorkflowOverviewEmbeddingRenderState,
+  createIniPanelShellWorkflowOverviewEmbeddingDomContract,
  mountIniPanelShellWorkflowOverviewEmbedding,
  renderIniPanelShellSessionHandoffWorkflowState,
  mountIniPanelShellSessionHandoffWorkflow,
@@ -324,6 +325,12 @@ Use `createIniPanelShellWorkflowOverviewEmbeddingRenderState()` or
 outer shell needs that display view-model compressed into stable `statusLine`,
 `dataset`, and rows for a shared DOM renderer. The workflow overview page also
 exposes `linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewEmbeddingRenderState()`.
+Use `createIniPanelShellWorkflowOverviewEmbeddingDomContract()` or
+`linuxCncIniPanelLaunchApi.getWorkflowOverviewEmbeddingDomContract()` when an
+outer shell needs the required embedding report mount/status/rows selectors,
+mount dataset keys, row dataset keys, and render-result fields before adding a
+DOM renderer. The workflow overview page also exposes
+`linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewEmbeddingDomContract()`.
 Use
 `renderIniPanelShellSessionHandoffMountState()` or
 `linuxCncIniPanelLaunchApi.renderShellSessionHandoffMountState()` when an outer
--- a/wasm-port/runtime/ui/ini-panel/launch.html
+++ b/wasm-port/runtime/ui/ini-panel/launch.html
@@ -288,6 +288,9 @@
      getWorkflowOverviewEmbeddingRenderState: (displayViewModel) => (
        shellViewModel.createWorkflowOverviewEmbeddingRenderState(displayViewModel)
      ),
+      getWorkflowOverviewEmbeddingDomContract: (options) => (
+        shellViewModel.createWorkflowOverviewEmbeddingDomContract(options)
+      ),
      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
@@ -162,6 +162,7 @@ export function createIniPanelLaunchApiManifest(entries = getVisibleIniPanelEntr
      "getWorkflowOverviewEmbeddingReport",
      "getWorkflowOverviewEmbeddingDisplayViewModel",
      "getWorkflowOverviewEmbeddingRenderState",
+      "getWorkflowOverviewEmbeddingDomContract",
      "isSupportedShellSessionHandoffPackage",
      "getLauncherLinks",
      "getControlPageApiMethods",
@@ -1942,6 +1943,32 @@ export function createIniPanelShellWorkflowOverviewEmbeddingRenderState(
  };
 }

+export function createIniPanelShellWorkflowOverviewEmbeddingDomContract({
+  rowDatasetPrefix = "workflowOverviewEmbedding",
+  selectors = {},
+} = {}) {
+  const mountSelector = selectors.mount ?? "[data-workflow-overview-embedding]";
+  const statusSelector = selectors.status ?? "[data-workflow-overview-embedding-status]";
+  const rowsSelector = selectors.rows ?? "[data-workflow-overview-embedding-rows]";
+  return {
+    apiName: "ini-panel-shell-workflow-overview-embedding-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 createIniPanelShellViewModel(entries = getVisibleIniPanelEntries()) {
  const shellIntegrationManifest = createIniPanelShellIntegrationManifest(entries);
  const shellIntegrationReadiness = createIniPanelShellIntegrationReadiness(shellIntegrationManifest);
@@ -2103,6 +2130,7 @@ export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries
    createWorkflowOverviewEmbeddingReport: createIniPanelShellWorkflowOverviewEmbeddingReport,
    createWorkflowOverviewEmbeddingDisplayViewModel: createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel,
    createWorkflowOverviewEmbeddingRenderState: createIniPanelShellWorkflowOverviewEmbeddingRenderState,
+    createWorkflowOverviewEmbeddingDomContract: createIniPanelShellWorkflowOverviewEmbeddingDomContract,
    isSupportedShellSessionHandoffPackage: isSupportedIniPanelShellSessionHandoffPackage,
    controlPage: {
      browserApiSchema: createControlPageBrowserApiSchema(),
--- a/wasm-port/runtime/ui/ini-panel/workflow-overview.html
+++ b/wasm-port/runtime/ui/ini-panel/workflow-overview.html
@@ -92,6 +92,7 @@
      createIniPanelShellWorkflowOverviewEmbeddingReport,
      createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel,
      createIniPanelShellWorkflowOverviewEmbeddingRenderState,
+      createIniPanelShellWorkflowOverviewEmbeddingDomContract,
      mountIniPanelShellWorkflowOverviewEmbedding,
      renderIniPanelShellSessionHandoffWorkflowState,
      mountIniPanelShellSessionHandoffWorkflow,
@@ -143,6 +144,9 @@
      getWorkflowOverviewEmbeddingRenderState: (displayViewModel) => (
        createIniPanelShellWorkflowOverviewEmbeddingRenderState(displayViewModel)
      ),
+      getWorkflowOverviewEmbeddingDomContract: (options) => (
+        createIniPanelShellWorkflowOverviewEmbeddingDomContract(options)
+      ),
    };
  </script>
 </body>
--- a/wasm-port/tests/browser/ini_panel_launch_smoke.html
+++ b/wasm-port/tests/browser/ini_panel_launch_smoke.html
@@ -106,6 +106,7 @@
        !launchApi?.getWorkflowOverviewEmbeddingReport ||
        !launchApi?.getWorkflowOverviewEmbeddingDisplayViewModel ||
        !launchApi?.getWorkflowOverviewEmbeddingRenderState ||
+        !launchApi?.getWorkflowOverviewEmbeddingDomContract ||
        !launchApi?.isSupportedShellSessionHandoffPackage ||
        !launchApi?.getLauncherLinks ||
        !launchApi?.getControlPageApiMethods
@@ -633,7 +634,8 @@
        !workflowOverviewApi?.mountWorkflowOverviewEmbedding ||
        !workflowOverviewApi?.getWorkflowOverviewEmbeddingReport ||
        !workflowOverviewApi?.getWorkflowOverviewEmbeddingDisplayViewModel ||
-        !workflowOverviewApi?.getWorkflowOverviewEmbeddingRenderState
+        !workflowOverviewApi?.getWorkflowOverviewEmbeddingRenderState ||
+        !workflowOverviewApi?.getWorkflowOverviewEmbeddingDomContract
      ) {
        throw new Error("workflow overview API namespace did not expose shell helpers");
      }
@@ -652,6 +654,7 @@
      const workflowOverviewEmbeddingRenderState = launchApi.getWorkflowOverviewEmbeddingRenderState(
        workflowOverviewEmbeddingDisplay,
      );
+      const workflowOverviewEmbeddingDomContract = launchApi.getWorkflowOverviewEmbeddingDomContract();
      assertEqual(workflowOverviewApi.getWorkflowOverviewContract().pageHref, "./workflow-overview.html", "workflow overview page contract");
      assertEqual(workflowOverviewReadiness.ready, true, "workflow overview readiness");
      assertEqual(workflowOverviewReadiness.missing.join(","), "", "workflow overview readiness missing");
@@ -672,14 +675,12 @@
      assertEqual(workflowOverviewEmbeddingDisplay.rows.length, 6, "workflow overview embedding display rows");
      assertEqual(workflowOverviewEmbeddingRenderState.statusLine, "Blocked: embedding:blocked, mount:blocked", "workflow overview embedding render-state status");
      assertEqual(workflowOverviewEmbeddingRenderState.dataset.handoffScope, "workflow-overview-embedding", "workflow overview embedding render-state scope");
+      assertEqual(workflowOverviewEmbeddingDomContract.selectors.mount, "[data-workflow-overview-embedding]", "workflow overview embedding DOM contract mount");
+      assertEqual(workflowOverviewEmbeddingDomContract.rowDatasetKeys.detail[0], "workflowOverviewEmbeddingValue", "workflow overview embedding DOM contract row key");
      assertEqual(
-        workflowOverviewApi.getWorkflowOverviewEmbeddingRenderState(
-          workflowOverviewApi.getWorkflowOverviewEmbeddingDisplayViewModel(
-            workflowOverviewApi.getWorkflowOverviewEmbeddingReport(workflowOverviewEmbedding),
-          ),
-        ).dataset.handoffScope,
-        workflowOverviewEmbeddingRenderState.dataset.handoffScope,
-        "workflow overview self embedding render-state",
+        workflowOverviewApi.getWorkflowOverviewEmbeddingDomContract().selectors.mount,
+        workflowOverviewEmbeddingDomContract.selectors.mount,
+        "workflow overview self embedding DOM contract",
      );
      status.textContent = "browser_ini_launch_smoke=ok";
      console.log("browser_ini_launch_smoke=ok");
--- a/wasm-port/tests/browser/ini_panel_shell_integration_workflow_smoke.html
+++ b/wasm-port/tests/browser/ini_panel_shell_integration_workflow_smoke.html
@@ -108,6 +108,7 @@ TOOL_TABLE = browser-shell-tool.tbl
        !launchApi?.getWorkflowOverviewEmbeddingReport ||
        !launchApi?.getWorkflowOverviewEmbeddingDisplayViewModel ||
        !launchApi?.getWorkflowOverviewEmbeddingRenderState ||
+        !launchApi?.getWorkflowOverviewEmbeddingDomContract ||
        !launchApi?.isSupportedShellSessionHandoffPackage
      ) {
        throw new Error("launch API namespace did not expose shell integration helpers");
@@ -300,6 +301,9 @@ TOOL_TABLE = browser-shell-tool.tbl
      const workflowOverviewEmbeddingRenderState = launchApi.getWorkflowOverviewEmbeddingRenderState(
        workflowOverviewEmbeddingDisplay,
      );
+      const workflowOverviewEmbeddingDomContract = launchApi.getWorkflowOverviewEmbeddingDomContract({
+        rowDatasetPrefix: "externalOverviewEmbedding",
+      });
      assertEqual(workflowOverviewReadiness.ready, true, "shell workflow overview iframe readiness");
      assertEqual(workflowOverviewReadiness.missing.join(","), "", "shell workflow overview iframe missing methods");
      assertEqual(workflowOverviewEmbedding.apiName, "ini-panel-shell-workflow-overview-embedding", "shell workflow overview embedding API");
@@ -314,6 +318,8 @@ TOOL_TABLE = browser-shell-tool.tbl
      assertEqual(workflowOverviewEmbeddingDisplay.rows.length, 6, "shell workflow overview embedding display rows");
      assertEqual(workflowOverviewEmbeddingRenderState.dataset.handoffScope, "workflow-overview-embedding", "shell workflow overview embedding render-state scope");
      assertEqual(workflowOverviewEmbeddingRenderState.rows.length, 6, "shell workflow overview embedding render-state rows");
+      assertEqual(workflowOverviewEmbeddingDomContract.selectors.rows, "[data-workflow-overview-embedding-rows]", "shell workflow overview embedding DOM rows selector");
+      assertEqual(workflowOverviewEmbeddingDomContract.rowDatasetKeys.term[0], "externalOverviewEmbeddingRow", "shell workflow overview embedding DOM row prefix");

      const controlDoc = await loadFrame(`../../runtime/ui/ini-panel/${controlTarget.href.slice(2)}`);
      const controlPageApi = controlDoc.defaultView.linuxCncIniPanelControlPageApi;
--- a/wasm-port/tests/browser/ini_panel_workflow_overview_smoke.html
+++ b/wasm-port/tests/browser/ini_panel_workflow_overview_smoke.html
@@ -38,7 +38,8 @@
        !workflowApi?.createWorkflowOverviewRenderState ||
        !workflowApi?.getWorkflowOverviewEmbeddingReport ||
        !workflowApi?.getWorkflowOverviewEmbeddingDisplayViewModel ||
-        !workflowApi?.getWorkflowOverviewEmbeddingRenderState
+        !workflowApi?.getWorkflowOverviewEmbeddingRenderState ||
+        !workflowApi?.getWorkflowOverviewEmbeddingDomContract
      ) {
        throw new Error("workflow overview API namespace did not expose overview helpers");
      }
@@ -64,6 +65,7 @@
      });
      const embeddingDisplay = workflowApi.getWorkflowOverviewEmbeddingDisplayViewModel(embeddingReport);
      const embeddingRenderState = workflowApi.getWorkflowOverviewEmbeddingRenderState(embeddingDisplay);
+      const embeddingDomContract = workflowApi.getWorkflowOverviewEmbeddingDomContract();

      assertEqual(summary.summaryVersion, 1, "workflow overview summary version");
      assertEqual(displayViewModel.title, "Shell handoff workflow", "workflow overview display title");
@@ -84,6 +86,8 @@
      assertEqual(embeddingDisplay.rows.length, 6, "workflow overview embedding display rows");
      assertEqual(embeddingRenderState.statusLine, "Blocked: embedding:blocked, mount:blocked", "workflow overview embedding render-state status");
      assertEqual(embeddingRenderState.dataset.handoffScope, "workflow-overview-embedding", "workflow overview embedding render-state scope");
+      assertEqual(embeddingDomContract.selectors.status, "[data-workflow-overview-embedding-status]", "workflow overview embedding DOM contract status selector");
+      assertEqual(embeddingDomContract.renderResultFields.includes("rowIds"), true, "workflow overview embedding DOM contract render fields");
      assertEqual(
        workflowDoc.querySelector("[data-handoff-workflow]").dataset.handoffScope,
        "workflow",
--- a/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs
@@ -42,6 +42,7 @@ import {
  createIniPanelShellWorkflowOverviewEmbeddingReport,
  createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel,
  createIniPanelShellWorkflowOverviewEmbeddingRenderState,
+  createIniPanelShellWorkflowOverviewEmbeddingDomContract,
  mountIniPanelShellWorkflowOverviewEmbedding,
  renderIniPanelShellSessionHandoffWorkflowState,
  mountIniPanelShellSessionHandoffWorkflow,
@@ -126,6 +127,7 @@ const requiredShellExports = [
  "createIniPanelShellWorkflowOverviewEmbeddingReport",
  "createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel",
  "createIniPanelShellWorkflowOverviewEmbeddingRenderState",
+  "createIniPanelShellWorkflowOverviewEmbeddingDomContract",
  "mountIniPanelShellWorkflowOverviewEmbedding",
  "renderIniPanelShellSessionHandoffWorkflowState",
  "mountIniPanelShellSessionHandoffWorkflow",
@@ -429,6 +431,7 @@ assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffSumm
 assert.match(shellText, /\bexport function createIniPanelShellWorkflowOverviewEmbeddingReport\b/);
 assert.match(shellText, /\bexport function createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel\b/);
 assert.match(shellText, /\bexport function createIniPanelShellWorkflowOverviewEmbeddingRenderState\b/);
+assert.match(shellText, /\bexport function createIniPanelShellWorkflowOverviewEmbeddingDomContract\b/);
 assert.match(shellText, /\bexport function isSupportedIniPanelControlPageApiManifest\b/);
 assert.match(shellText, /\bexport function isSupportedIniPanelLaunchApiManifest\b/);
 assert.match(shellText, /\bexport function isSupportedIniPanelShellIntegrationManifest\b/);
@@ -460,6 +463,7 @@ assert.match(launchText, /\bgetShellSessionHandoffPackageReport\b/);
 assert.match(launchText, /\bgetWorkflowOverviewEmbeddingReport\b/);
 assert.match(launchText, /\bgetWorkflowOverviewEmbeddingDisplayViewModel\b/);
 assert.match(launchText, /\bgetWorkflowOverviewEmbeddingRenderState\b/);
+assert.match(launchText, /\bgetWorkflowOverviewEmbeddingDomContract\b/);
 assert.match(launchText, /\bisSupportedShellSessionHandoffPackage\b/);
 assert.match(launchText, /\bdata-handoff-shell\b/);
 assert.match(launchText, /\bdata-handoff-status\b/);
@@ -496,6 +500,7 @@ assert.match(docText, /\bcreateIniPanelShellSessionHandoffSummarySchema\b/);
 assert.match(docText, /\bcreateIniPanelShellWorkflowOverviewEmbeddingReport\b/);
 assert.match(docText, /\bcreateIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel\b/);
 assert.match(docText, /\bcreateIniPanelShellWorkflowOverviewEmbeddingRenderState\b/);
+assert.match(docText, /\bcreateIniPanelShellWorkflowOverviewEmbeddingDomContract\b/);
 assert.match(docText, /\bisSupportedIniPanelControlPageApiManifest\b/);
 assert.match(docText, /\bisSupportedIniPanelLaunchApiManifest\b/);
 assert.match(docText, /\bisSupportedIniPanelShellIntegrationManifest\b/);
@@ -522,6 +527,7 @@ assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getShellSessionHandoffPackag
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getWorkflowOverviewEmbeddingReport\b/);
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getWorkflowOverviewEmbeddingDisplayViewModel\b/);
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getWorkflowOverviewEmbeddingRenderState\b/);
+assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getWorkflowOverviewEmbeddingDomContract\b/);
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.isSupportedShellSessionHandoffPackage\b/);
 assert.match(docText, /\bdata-handoff-shell\b/);
 assert.match(docText, /\bdata-handoff-status\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
@@ -82,6 +82,7 @@ assert.deepEqual(manifest, {
    "getWorkflowOverviewEmbeddingReport",
    "getWorkflowOverviewEmbeddingDisplayViewModel",
    "getWorkflowOverviewEmbeddingRenderState",
+    "getWorkflowOverviewEmbeddingDomContract",
    "isSupportedShellSessionHandoffPackage",
    "getLauncherLinks",
    "getControlPageApiMethods",
@@ -228,6 +229,7 @@ assert.match(launchText, /\bmountWorkflowOverviewEmbedding\b/);
 assert.match(launchText, /\bgetWorkflowOverviewEmbeddingReport\b/);
 assert.match(launchText, /\bgetWorkflowOverviewEmbeddingDisplayViewModel\b/);
 assert.match(launchText, /\bgetWorkflowOverviewEmbeddingRenderState\b/);
+assert.match(launchText, /\bgetWorkflowOverviewEmbeddingDomContract\b/);
 assert.match(launchText, /\bisSupportedShellSessionHandoffPackage\b/);
 assert.match(launchText, /\bdata-handoff-workflow\b/);
 assert.match(launchText, /\bdata-handoff-workflow-status\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
@@ -38,6 +38,7 @@ import {
  createIniPanelShellWorkflowOverviewEmbeddingReport,
  createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel,
  createIniPanelShellWorkflowOverviewEmbeddingRenderState,
+  createIniPanelShellWorkflowOverviewEmbeddingDomContract,
  mountIniPanelShellWorkflowOverviewEmbedding,
  renderIniPanelShellSessionHandoffWorkflowState,
  mountIniPanelShellSessionHandoffWorkflow,
@@ -167,7 +168,7 @@ assert.deepEqual(readiness, {
  counts: {
    pages: 3,
    launcherLinks: 3,
-    launchMethods: 45,
+    launchMethods: 46,
    controlPageMethods: 11,
    persistenceCapabilities: 3,
  },
@@ -229,7 +230,7 @@ assert.deepEqual(handoffSummary, {
    counts: {
      pages: 3,
      launcherLinks: 3,
-      launchMethods: 45,
+      launchMethods: 46,
      controlPageMethods: 11,
      persistenceCapabilities: 3,
    },
@@ -785,6 +786,10 @@ assert.equal(
  ).dataset.handoffScope,
  "workflow-overview-embedding",
 );
+assert.equal(
+  createIniPanelShellWorkflowOverviewEmbeddingDomContract().selectors.mount,
+  "[data-workflow-overview-embedding]",
+);
 assert.deepEqual(
  createIniPanelShellWorkflowOverviewReadiness({
    overviewApi: {
@@ -1213,7 +1218,7 @@ assert.deepEqual(createIniPanelShellIntegrationReadiness(blockedManifest), {
  counts: {
    pages: 3,
    launcherLinks: 3,
-    launchMethods: 45,
+    launchMethods: 46,
    controlPageMethods: 11,
    persistenceCapabilities: 3,
  },
@@ -1398,6 +1403,7 @@ assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPack
 assert.match(shellText, /\bexport function createIniPanelShellWorkflowOverviewEmbeddingReport\b/);
 assert.match(shellText, /\bexport function createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel\b/);
 assert.match(shellText, /\bexport function createIniPanelShellWorkflowOverviewEmbeddingRenderState\b/);
+assert.match(shellText, /\bexport function createIniPanelShellWorkflowOverviewEmbeddingDomContract\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageRenderState\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffPackageSchema\b/);
 assert.match(shellText, /\bexport function createIniPanelShellSessionHandoffRenderState\b/);
@@ -1438,6 +1444,7 @@ assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageReport\b/);
 assert.match(docText, /\bcreateIniPanelShellWorkflowOverviewEmbeddingReport\b/);
 assert.match(docText, /\bcreateIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel\b/);
 assert.match(docText, /\bcreateIniPanelShellWorkflowOverviewEmbeddingRenderState\b/);
+assert.match(docText, /\bcreateIniPanelShellWorkflowOverviewEmbeddingDomContract\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageRenderState\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffPackageSchema\b/);
 assert.match(docText, /\bcreateIniPanelShellSessionHandoffRenderState\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
@@ -38,6 +38,7 @@ import {
  createIniPanelShellWorkflowOverviewEmbeddingReport,
  createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel,
  createIniPanelShellWorkflowOverviewEmbeddingRenderState,
+  createIniPanelShellWorkflowOverviewEmbeddingDomContract,
  mountIniPanelShellWorkflowOverviewEmbedding,
  renderIniPanelShellSessionHandoffWorkflowState,
  mountIniPanelShellSessionHandoffWorkflow,
@@ -127,6 +128,7 @@ assert.equal(typeof createIniPanelShellWorkflowOverviewReadiness, "function");
 assert.equal(typeof createIniPanelShellWorkflowOverviewEmbeddingReport, "function");
 assert.equal(typeof createIniPanelShellWorkflowOverviewEmbeddingDisplayViewModel, "function");
 assert.equal(typeof createIniPanelShellWorkflowOverviewEmbeddingRenderState, "function");
+assert.equal(typeof createIniPanelShellWorkflowOverviewEmbeddingDomContract, "function");
 assert.equal(typeof mountIniPanelShellWorkflowOverviewEmbedding, "function");
 assert.equal(typeof renderIniPanelShellSessionHandoffWorkflowState, "function");
 assert.equal(typeof mountIniPanelShellSessionHandoffWorkflow, "function");
@@ -805,6 +807,10 @@ assert.equal(
  shellViewModel.createWorkflowOverviewEmbeddingRenderState,
  createIniPanelShellWorkflowOverviewEmbeddingRenderState,
 );
+assert.equal(
+  shellViewModel.createWorkflowOverviewEmbeddingDomContract,
+  createIniPanelShellWorkflowOverviewEmbeddingDomContract,
+);
 assert.equal(shellViewModel.createShellSessionHandoffPackageReport, createIniPanelShellSessionHandoffPackageReport);
 assert.equal(shellViewModel.createShellSessionHandoffPackageSchema, createIniPanelShellSessionHandoffPackageSchema);
 assert.equal(shellViewModel.isSupportedShellSessionHandoffPackage, isSupportedIniPanelShellSessionHandoffPackage);
@@ -1272,6 +1278,34 @@ assert.deepEqual(
    },
  },
 );
+assert.deepEqual(createIniPanelShellWorkflowOverviewEmbeddingDomContract(), {
+  apiName: "ini-panel-shell-workflow-overview-embedding-dom-contract",
+  contractVersion: 1,
+  requiredNodeIds: ["mount", "status", "rows"],
+  selectors: {
+    mount: "[data-workflow-overview-embedding]",
+    status: "[data-workflow-overview-embedding-status]",
+    rows: "[data-workflow-overview-embedding-rows]",
+  },
+  mountDatasetKeys: ["handoffPhase", "handoffReady", "handoffScope"],
+  rowDatasetPrefix: "workflowOverviewEmbedding",
+  rowDatasetKeys: {
+    term: ["workflowOverviewEmbeddingRow", "workflowOverviewEmbeddingStatus"],
+    detail: ["workflowOverviewEmbeddingValue", "workflowOverviewEmbeddingStatus"],
+  },
+  renderResultFields: ["rendered", "statusLine", "rowCount", "rowIds", "dataset"],
+});
+assert.deepEqual(
+  createIniPanelShellWorkflowOverviewEmbeddingDomContract({
+    rowDatasetPrefix: "externalEmbedding",
+    selectors: {
+      mount: "[data-external-embedding]",
+      status: "[data-external-embedding-status]",
+      rows: "[data-external-embedding-rows]",
+    },
+  }).rowDatasetKeys.detail,
+  ["externalEmbeddingValue", "externalEmbeddingStatus"],
+);
 assert.deepEqual(
  mountIniPanelShellWorkflowOverviewEmbedding({ overviewApi: null }).readiness.missing,
  shellViewModel.shellWorkflowOverviewContract.methodNames,