接入 INI 面板只读 session readiness handoff

2026-06-16 06:47:48 +08:00
parent 03db34485e
commit 68ff2fb5d6
16 changed files with 164 additions and 8 deletions
--- a/wasm-port/docs/panel-entry.md
+++ b/wasm-port/docs/panel-entry.md
@@ -126,7 +126,8 @@ read-only model with `pages`, `launcherLinks`, and `controlPage` helpers for
 mounting the existing control-page controller, refresh workflow, and renderer.
 Use `controlPage.readStatus` or `readMachineSessionReadonlyStatus()` when an
 outer shell needs one stable read of `stateBundle`, `workflowStatus`,
-`overview`, `controlView`, `session`, `runReadiness`, and `run`.
+`overview`, `controlView`, `sessionReadiness`, `session`, `runReadiness`, and
+`run`.
 Use `createMachineSessionReadonlyStatusApiManifest()` or
 `controlPage.readonlyStatusApiManifest` when you only need the API shape and
 method names.
@@ -433,7 +434,8 @@ state-shape helper used by the workflow.
 The control-page session workflow lives in
 `runtime/ui/ini-panel/control-page-session-workflow.js`. Use
 `loadMachineSessionForControlPageWorkflow()` when an outer shell needs a
-read-only readiness snapshot for the embedded panel API and first control view.
+read-only readiness snapshot for the embedded panel API, machine-session
+ready/blocked state, and first control view.
 `createControlPageSessionLoadState()` is the stable state-shape helper for
 `waiting-panel`, `waiting-api`, `waiting-session`, `ready`, and `error` phases.

--- a/wasm-port/runtime/ui/ini-panel/control-page-session-workflow.js
+++ b/wasm-port/runtime/ui/ini-panel/control-page-session-workflow.js
@@ -5,6 +5,7 @@ export function createControlPageSessionLoadState({
  controlViewReady = false,
  stateBundle = null,
  workflowStatus = null,
+  sessionReadiness = null,
  controlView = null,
  error = null,
 } = {}) {
@@ -15,11 +16,19 @@ export function createControlPageSessionLoadState({
    controlViewReady,
    stateBundle,
    workflowStatus,
+    sessionReadiness,
    controlView,
    error,
  };
 }

+function getSessionReadiness(stateBundle, workflowStatus) {
+  return workflowStatus?.sessionReadiness
+    ?? stateBundle?.workflowStatus?.sessionReadiness
+    ?? stateBundle?.report?.sessionReadiness
+    ?? null;
+}
+
 export function loadMachineSessionForControlPageWorkflow({
  getPanelWindow,
  getPanelApi,
@@ -63,22 +72,28 @@ export function loadMachineSessionForControlPageWorkflow({
  }

  if (!controlView) {
+    const stateBundle = panelApi.getMachineSessionStateBundle?.() ?? null;
+    const workflowStatus = panelApi.getMachineSessionWorkflowStatus?.() ?? null;
    return createControlPageSessionLoadState({
      phase: "waiting-session",
      panelReady: true,
      apiReady: true,
-      stateBundle: panelApi.getMachineSessionStateBundle?.() ?? null,
-      workflowStatus: panelApi.getMachineSessionWorkflowStatus?.() ?? null,
+      stateBundle,
+      workflowStatus,
+      sessionReadiness: getSessionReadiness(stateBundle, workflowStatus),
    });
  }

+  const stateBundle = panelApi.getMachineSessionStateBundle?.() ?? null;
+  const workflowStatus = panelApi.getMachineSessionWorkflowStatus?.() ?? null;
  return createControlPageSessionLoadState({
    phase: "ready",
    panelReady: true,
    apiReady: true,
    controlViewReady: true,
-    stateBundle: panelApi.getMachineSessionStateBundle?.() ?? null,
-    workflowStatus: panelApi.getMachineSessionWorkflowStatus?.() ?? null,
+    stateBundle,
+    workflowStatus,
+    sessionReadiness: getSessionReadiness(stateBundle, workflowStatus),
    controlView,
  });
 }
--- a/wasm-port/runtime/ui/ini-panel/panel-state-summary.js
+++ b/wasm-port/runtime/ui/ini-panel/panel-state-summary.js
@@ -3,6 +3,7 @@ export function createIniPanelStateSummary({
  machine = null,
  machineFiles = null,
  sessionSnapshot = null,
+  sessionReadiness = null,
  sessionLoad = null,
  runReadiness = null,
  run = null,
@@ -17,6 +18,7 @@ export function createIniPanelStateSummary({
    machine,
    machineFiles,
    sessionSnapshot,
+    sessionReadiness,
    sessionLoad,
    runReadiness,
    run,
@@ -29,6 +31,7 @@ export function createMachineSessionStateSnapshot({
  machine = null,
  machineFiles = null,
  sessionSnapshot = null,
+  sessionReadiness = null,
  sessionLoad = null,
  runReadiness = null,
  selectedProgram = null,
@@ -44,6 +47,7 @@ export function createMachineSessionStateSnapshot({
      machine,
      machineFiles,
      sessionSnapshot,
+      sessionReadiness,
      sessionLoad,
      runReadiness,
      run,
@@ -72,6 +76,7 @@ export function createMachineSessionStateReport(state = {}) {
  const badges = state.badges ?? {};
  const fields = state.fields ?? {};
  const sessionSnapshot = state.sessionSnapshot ?? {};
+  const sessionReadiness = state.sessionReadiness ?? null;
  const sessionLoad = state.sessionLoad ?? {};
  const runReadiness = state.runReadiness ?? {};
  const selectedProgram = state.selectedProgram ?? {};
@@ -90,6 +95,7 @@ export function createMachineSessionStateReport(state = {}) {
      toolTable: fields.sessionToolTable ?? sessionSnapshot.toolTableOpfsPath ?? sessionLoad.toolTableWasmPath ?? null,
      gcode: fields.sessionGcode ?? sessionSnapshot.gcodeOpfsPath ?? null,
    },
+    sessionReadiness,
    loaded: {
      iniWasmPath: sessionLoad.iniWasmPath ?? null,
      parameterWasmPath: sessionLoad.parameterWasmPath ?? null,
@@ -141,6 +147,7 @@ export function createMachineSessionWorkflowStatus(state = {}) {
  return {
    readiness: report.readiness,
    overview,
+    sessionReadiness: report.sessionReadiness ?? null,
    runReadiness: report.runReadiness,
    lastAction: report.status.lastAction,
    error: report.status.error,
--- a/wasm-port/runtime/ui/ini-panel/readonly-status-api.js
+++ b/wasm-port/runtime/ui/ini-panel/readonly-status-api.js
@@ -4,12 +4,17 @@ export function createMachineSessionReadonlyStatus({
  controlView = null,
 } = {}) {
  const overview = stateBundle?.overview ?? workflowStatus?.overview ?? null;
+  const sessionReadiness = workflowStatus?.sessionReadiness
+    ?? stateBundle?.workflowStatus?.sessionReadiness
+    ?? stateBundle?.report?.sessionReadiness
+    ?? null;
  return {
    stateBundle,
    workflowStatus,
    overview,
    controlView,
    report: stateBundle?.report ?? null,
+    sessionReadiness,
    runReadiness: workflowStatus?.runReadiness ?? stateBundle?.report?.runReadiness ?? null,
    run: workflowStatus?.run ?? stateBundle?.report?.run ?? null,
    session: workflowStatus?.session ?? stateBundle?.report?.session ?? null,
@@ -42,6 +47,7 @@ export function createMachineSessionReadonlyStatusApiManifest() {
      "overview",
      "controlView",
      "report",
+      "sessionReadiness",
      "runReadiness",
      "run",
      "session",
--- a/wasm-port/tests/browser/ini_panel_control_page_smoke.html
+++ b/wasm-port/tests/browser/ini_panel_control_page_smoke.html
@@ -218,6 +218,11 @@ TOOL_TABLE = browser-tool.tbl
        "load-session",
        "control page readonly status workflow last action after load",
      );
+      assertEqual(
+        loadedStatus.sessionReadiness.ready,
+        true,
+        "control page readonly status session readiness",
+      );
      assertEqual(
        loadedStatus.controlView.status.lastAction,
        "load-session",
--- a/wasm-port/tests/browser/ini_panel_shell_integration_workflow_smoke.html
+++ b/wasm-port/tests/browser/ini_panel_shell_integration_workflow_smoke.html
@@ -268,6 +268,11 @@ TOOL_TABLE = browser-shell-tool.tbl
      assertEqual(handoffSummary.handoffMethods.loadSessionState, "loadControlPageSessionState", "shell handoff load method");
      assertEqual(handoffSummary.handoffMethods.readStatus, "readControlPageStatus", "shell handoff status method");
      assertEqual(handoffSummary.readonlyStatusFields.includes("session"), true, "shell handoff readonly session field");
+      assertEqual(
+        handoffSummary.readonlyStatusFields.includes("sessionReadiness"),
+        true,
+        "shell handoff readonly session readiness field",
+      );
      assertEqual(handoffSummary.persistenceCapabilities.length, 3, "shell handoff persistence capabilities");
      assertEqual(readiness.apiNames.launch, "ini-panel-launch", "shell integration launch API name");
      assertEqual(
@@ -531,6 +536,11 @@ TOOL_TABLE = browser-shell-tool.tbl
      });
      assertEqual(readonlyStatusResult.phase, "ready", "shell handoff readonly status result phase");
      assertEqual(readonlyStatusResult.ready, true, "shell handoff readonly status result readiness");
+      assertEqual(
+        readonlyStatus.sessionReadiness.ready,
+        true,
+        "shell handoff readonly status session readiness",
+      );
      assertEqual(
        readonlyStatusResult.missingStatusFields.join(","),
        "",
--- a/wasm-port/tests/ui/node/verify_ini_panel_control_page_controller.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_control_page_controller.mjs
@@ -93,6 +93,7 @@ assert.deepEqual(controller.readStatus(), {
  overview: null,
  controlView: expectedView,
  report: expectedStateBundle.report,
+  sessionReadiness: null,
  runReadiness: null,
  run: null,
  session: null,
@@ -109,6 +110,7 @@ assert.deepEqual(controller.loadSessionState(), {
  controlViewReady: true,
  stateBundle: expectedStateBundle,
  workflowStatus: expectedWorkflowStatus,
+  sessionReadiness: null,
  controlView: expectedView,
  error: null,
 });
--- a/wasm-port/tests/ui/node/verify_ini_panel_control_page_session_workflow.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_control_page_session_workflow.mjs
@@ -21,6 +21,11 @@ const workflowStatus = {
  overview: {
    phase: "ready",
  },
+  sessionReadiness: {
+    phase: "ready",
+    ready: true,
+    missing: [],
+  },
  lastAction: "load-session",
  error: null,
 };
@@ -40,6 +45,7 @@ assert.deepEqual(createControlPageSessionLoadState({ phase: "waiting-panel" }),
  controlViewReady: false,
  stateBundle: null,
  workflowStatus: null,
+  sessionReadiness: null,
  controlView: null,
  error: null,
 });
@@ -81,6 +87,7 @@ assert.deepEqual(
    apiReady: true,
    stateBundle,
    workflowStatus,
+    sessionReadiness: workflowStatus.sessionReadiness,
  }),
 );

@@ -101,6 +108,7 @@ assert.deepEqual(
    controlViewReady: true,
    stateBundle,
    workflowStatus,
+    sessionReadiness: workflowStatus.sessionReadiness,
    controlView,
  }),
 );
--- a/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs
@@ -430,6 +430,7 @@ assert.deepEqual(createControlPageSessionLoadState({ phase: "waiting-panel" }),
  controlViewReady: false,
  stateBundle: null,
  workflowStatus: null,
+  sessionReadiness: null,
  controlView: null,
  error: null,
 });
--- a/wasm-port/tests/ui/node/verify_ini_panel_readonly_status_api.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_readonly_status_api.mjs
@@ -30,6 +30,11 @@ const stateBundle = {
 };
 const workflowStatus = {
  overview: stateBundle.overview,
+  sessionReadiness: {
+    phase: "ready",
+    ready: true,
+    missing: [],
+  },
  runReadiness: stateBundle.report.runReadiness,
  session: stateBundle.report.session,
  run: stateBundle.report.run,
@@ -56,6 +61,7 @@ assert.deepEqual(
    overview: stateBundle.overview,
    controlView,
    report: stateBundle.report,
+    sessionReadiness: workflowStatus.sessionReadiness,
    runReadiness: stateBundle.report.runReadiness,
    run: stateBundle.report.run,
    session: stateBundle.report.session,
@@ -73,6 +79,7 @@ assert.deepEqual(createMachineSessionReadonlyStatus(), {
  overview: null,
  controlView: null,
  report: null,
+  sessionReadiness: null,
  runReadiness: null,
  run: null,
  session: null,
@@ -103,6 +110,7 @@ assert.deepEqual(createMachineSessionReadonlyStatusApiManifest(), {
    "overview",
    "controlView",
    "report",
+    "sessionReadiness",
    "runReadiness",
    "run",
    "session",
--- a/wasm-port/tests/ui/node/verify_ini_panel_shell_control_page_contract.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_shell_control_page_contract.mjs
@@ -59,6 +59,7 @@ assert.deepEqual(contract, {
    "overview",
    "controlView",
    "report",
+    "sessionReadiness",
    "runReadiness",
    "run",
    "session",
--- 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
@@ -217,6 +217,7 @@ assert.deepEqual(workflowPlan, {
      "overview",
      "controlView",
      "report",
+      "sessionReadiness",
      "runReadiness",
      "run",
      "session",
@@ -272,6 +273,7 @@ assert.deepEqual(handoffSummary, {
    "overview",
    "controlView",
    "report",
+    "sessionReadiness",
    "runReadiness",
    "run",
    "session",
--- a/wasm-port/tests/ui/node/verify_ini_panel_state_summary.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_state_summary.mjs
@@ -68,6 +68,12 @@ const expectedEmptyRunReadinessReport = {
  iniWasmPath: null,
 };

+const sessionReadinessFixture = {
+  phase: "ready",
+  ready: true,
+  missing: [],
+};
+
 const expectedWorkflowOverview = {
  phase: "ran",
  missing: [],
@@ -120,6 +126,7 @@ const summary = createIniPanelStateSummary({
    snapshotLabel: "ui-machine-session/ui-machine-session.json",
    workflow: "save-session-snapshot",
  },
+  sessionReadiness: sessionReadinessFixture,
  sessionLoad: {
    iniOpfsPath: "linuxcnc/machines/xyzab-tdr/machine.ini",
    iniWasmPath: "/work/session-machine.ini",
@@ -152,6 +159,7 @@ assert.deepEqual(summary, {
    snapshotLabel: "ui-machine-session/ui-machine-session.json",
    workflow: "save-session-snapshot",
  },
+  sessionReadiness: sessionReadinessFixture,
  sessionLoad: {
    iniOpfsPath: "linuxcnc/machines/xyzab-tdr/machine.ini",
    iniWasmPath: "/work/session-machine.ini",
@@ -175,6 +183,7 @@ assert.deepEqual(
    machine: null,
    machineFiles: null,
    sessionSnapshot: null,
+    sessionReadiness: null,
    sessionLoad: null,
    runReadiness: null,
    run: null,
@@ -195,6 +204,7 @@ assert.deepEqual(
    sessionSnapshot: {
      snapshotLabel: "ui-machine-session/ui-machine-session.json",
    },
+    sessionReadiness: sessionReadinessFixture,
    sessionLoad: {
      iniWasmPath: "/work/session-machine.ini",
    },
@@ -237,6 +247,7 @@ assert.deepEqual(
    sessionSnapshot: {
      snapshotLabel: "ui-machine-session/ui-machine-session.json",
    },
+    sessionReadiness: sessionReadinessFixture,
    sessionLoad: {
      iniWasmPath: "/work/session-machine.ini",
    },
@@ -311,6 +322,7 @@ assert.deepEqual(
      parameterWasmPath: "/work/session-linuxcnc.var",
      toolTableWasmPath: "/work/session-tool.tbl",
    },
+    sessionReadiness: sessionReadinessFixture,
    runReadiness: runReadinessFixture,
    selectedProgram: {
      source: "snapshot",
@@ -344,6 +356,7 @@ assert.deepEqual(
      toolTable: "/work/session-tool.tbl",
      gcode: "linuxcnc/gcode/ui-session.ngc",
    },
+    sessionReadiness: sessionReadinessFixture,
    loaded: {
      iniWasmPath: "/work/session-machine.ini",
      parameterWasmPath: "/work/session-linuxcnc.var",
@@ -383,6 +396,7 @@ const expectedExportReport = {
    toolTable: null,
    gcode: null,
  },
+  sessionReadiness: null,
  loaded: {
    iniWasmPath: "/work/session-machine.ini",
    parameterWasmPath: null,
@@ -446,6 +460,7 @@ assert.deepEqual(
      runWorkflow: "save-session-snapshot",
    },
    runReadiness: runReadinessFixture,
+    sessionReadiness: sessionReadinessFixture,
    run: {
      runStatus: "ok",
      canonicalEventCount: 2,
@@ -492,6 +507,7 @@ assert.deepEqual(
      },
    },
    runReadiness: expectedRunReadinessReport,
+    sessionReadiness: sessionReadinessFixture,
    lastAction: "run-gcode",
    error: null,
    session: {
@@ -525,6 +541,7 @@ const expectedBundleReport = {
    toolTable: null,
    gcode: "linuxcnc/gcode/ui-session.ngc",
  },
+  sessionReadiness: sessionReadinessFixture,
  loaded: {
    iniWasmPath: null,
    parameterWasmPath: null,
@@ -569,6 +586,7 @@ assert.deepEqual(
      runWorkflow: "save-session-snapshot",
    },
    runReadiness: runReadinessFixture,
+    sessionReadiness: sessionReadinessFixture,
    run: {
      runStatus: "ok",
      canonicalEventCount: 2,
@@ -593,6 +611,7 @@ assert.deepEqual(
        opfs: "OPFS: ready",
      },
      overview: expectedWorkflowOverview,
+      sessionReadiness: sessionReadinessFixture,
      lastAction: "run-gcode",
      error: null,
      runReadiness: expectedRunReadinessReport,
--- a/wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs
@@ -96,6 +96,7 @@ assert.deepEqual(createControlPageSessionLoadState({ phase: "waiting-panel" }),
  controlViewReady: false,
  stateBundle: null,
  workflowStatus: null,
+  sessionReadiness: null,
  controlView: null,
  error: null,
 });
@@ -1078,6 +1079,7 @@ assert.deepEqual(missingStatusResult.missingStatusFields, [
  "overview",
  "controlView",
  "report",
+  "sessionReadiness",
  "runReadiness",
  "run",
  "session",