推进 INI 面板 shell handoff workflow DOM mount helper

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(),