推进 INI 面板 shell control-page contract helper

text12.txt

@@ -729,3 +729,72 @@ host_wasm_opfs_browser_smokes=ok
 直接校验 `createIniPanelShellViewModel().controlPage` 的所有方法名、manifest 字段和只读边界，
 使外部页面接入前能运行一个快速 contract gate；仍保持只描述 UI/host boundary facts，不在 JS
 中解释 G-code、canonical events 或 CNC 运行语义。
+
+八、2026-06-15 继续执行记录：INI panel shell control-page contract helper
+
+本轮按“第一原则：加快实质性推进”继续推进 SDK/API surface，为 shell-facing control-page API
+增加可复用 contract helper 和 focused contract gate，使外部页面接入前能快速校验方法名、
+manifest 字段和只读边界。
+
+完成内容：
+
+- `wasm-port/runtime/ui/ini-panel/ui-shell.js` 新增
+  `createIniPanelShellControlPageContract()`；
+- `createIniPanelShellViewModel().controlPage` 新增 `contract`；
+- contract 固定描述：
+  - `methodNames`
+  - `readonlyStatusApiManifest`
+  - `readonlyStatusApiMethodNames`
+  - `readonlyStatusApiStatusFields`
+  - `relatedControlPageMethods`
+- 新增 `verify_ini_panel_shell_control_page_contract.mjs/.sh` focused contract smoke；
+- `verify_ui_node_smokes.sh` 接入 shell control-page contract smoke；
+- `verify_ini_panel_ui_shell.mjs` 与 `verify_ini_panel_entry_docs.mjs` 覆盖 contract 暴露；
+- `docs/panel-entry.md` 记录 `createIniPanelShellControlPageContract()` 和
+  `controlPage.contract`；
+- 未新增控制按钮；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未改变 OPFS/session persistence、LinuxCNC interpreter、tool、parameter、planner 或
+  LinuxCNC-owned runtime semantics。
+
+验证已通过：
+
+```bash
+git diff --check
+wasm-port/tests/ui/node/verify_ini_panel_shell_control_page_contract.sh
+wasm-port/tests/ui/node/verify_ini_panel_entry_docs.sh
+wasm-port/tests/ui/node/verify_ui_node_smokes.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
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+wasm-port/tests/host/verify_host_smokes.sh
+```
+
+关键输出：
+
+```text
+ini_panel_shell_control_page_contract_node_smoke=ok
+ini_panel_entry_docs_node_smoke=ok
+ui_node_smokes=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
+browser_ini_opfs_smoke=ok
+browser_ini_control_page_smoke=ok
+browser_ini_launch_smoke=ok
+host_wasm_opfs_browser_smokes=ok
+```
+
+下一步建议：
+
+继续推进 browser/UI workflow。下一批建议让 browser control-page smoke 读取并校验
+`createIniPanelShellViewModel().controlPage.contract` 或等价 browser-exposed contract，
+把 Node 端 contract gate 延伸到真实嵌入页面流程；仍保持只读，不新增控制按钮，不解析 G-code，
+不解释 canonical events。

wasm-port/docs/panel-entry.md

@@ -11,6 +11,7 @@ control view:
 import {
   INI_PANEL_ENTRIES,
   createIniPanelLauncherLinkViewModel,
+  createIniPanelShellControlPageContract,
   createIniPanelShellViewModel,
   getIniPanelEntryByHref,
   getVisibleIniPanelEntries,
@@ -60,6 +61,13 @@ outer shell needs one stable read of `stateBundle`, `workflowStatus`,
 Use `createMachineSessionReadonlyStatusApiManifest()` or
 `controlPage.readonlyStatusApiManifest` when you only need the API shape and
 method names.
+Use `createIniPanelShellControlPageContract()` or `controlPage.contract` when
+an outer shell needs a fast contract check for `createController`,
+`loadSessionState`, `readStatus`, `refresh`, `renderView`, the readonly status
+manifest, and its status fields before mounting the embedded panel. The
+contract lists readonly status fields for `stateBundle`, `workflowStatus`,
+`overview`, `controlView`, `report`, `runReadiness`, `run`, `session`, and
+`status`.
 
 The control-page refresh workflow lives in
 `runtime/ui/ini-panel/control-page-refresh-workflow.js`. Use

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

@@ -61,6 +61,23 @@ export function createIniPanelLauncherLinkViewModel(entries = getVisibleIniPanel
   }));
 }
 
+export function createIniPanelShellControlPageContract() {
+  const readonlyStatusApiManifest = createMachineSessionReadonlyStatusApiManifest();
+  return {
+    methodNames: [
+      "createController",
+      "loadSessionState",
+      "readStatus",
+      "refresh",
+      "renderView",
+    ],
+    readonlyStatusApiManifest,
+    readonlyStatusApiMethodNames: Object.keys(readonlyStatusApiManifest.methods),
+    readonlyStatusApiStatusFields: readonlyStatusApiManifest.statusFields,
+    relatedControlPageMethods: readonlyStatusApiManifest.relatedControlPageMethods,
+  };
+}
+
 export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries()) {
   return {
     pages: entries.map(({ id, href, title }) => ({
@@ -70,6 +87,7 @@ export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries
     })),
     launcherLinks: createIniPanelLauncherLinkViewModel(entries),
     controlPage: {
+      contract: createIniPanelShellControlPageContract(),
       createController: createMachineSessionControlPageController,
       loadSessionState: loadMachineSessionForControlPageWorkflow,
       readonlyStatusApiManifest: createMachineSessionReadonlyStatusApiManifest(),

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

@@ -8,6 +8,7 @@ import {
   controlPageStatusText,
   createControlPageSessionLoadState,
   createIniPanelLauncherLinkViewModel,
+  createIniPanelShellControlPageContract,
   createIniPanelShellViewModel,
   createMachineSessionReadonlyStatus,
   createMachineSessionReadonlyStatusApiManifest,
@@ -35,6 +36,7 @@ const requiredShellExports = [
   "controlPageStatusText",
   "createControlPageSessionLoadState",
   "createIniPanelLauncherLinkViewModel",
+  "createIniPanelShellControlPageContract",
   "createIniPanelShellViewModel",
   "getIniPanelEntryByHref",
   "getVisibleIniPanelEntries",
@@ -90,6 +92,10 @@ assert.deepEqual(
 );
 assert.deepEqual(createIniPanelShellViewModel().pages, getVisibleIniPanelEntries());
 assert.deepEqual(createIniPanelShellViewModel().launcherLinks, createIniPanelLauncherLinkViewModel());
+assert.deepEqual(
+  createIniPanelShellViewModel().controlPage.contract,
+  createIniPanelShellControlPageContract(),
+);
 assert.equal(controlPageStatusText({ lastAction: "run-gcode", runStatus: "ok", error: null }), "run-gcode | ok | -");
 assert.deepEqual(createControlPageSessionLoadState({ phase: "waiting-panel" }), {
   phase: "waiting-panel",

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

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createIniPanelShellControlPageContract,
+  createIniPanelShellViewModel,
+  createMachineSessionControlPageController,
+  createMachineSessionReadonlyStatusApiManifest,
+  loadMachineSessionForControlPageWorkflow,
+  readMachineSessionReadonlyStatus,
+  refreshMachineSessionControlPage,
+  renderMachineSessionControlView,
+} from "../../../runtime/ui/ini-panel/ui-shell.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "../../..");
+const shellText = readFileSync(resolve(root, "runtime/ui/ini-panel/ui-shell.js"), "utf8");
+const docText = readFileSync(resolve(root, "docs/panel-entry.md"), "utf8");
+
+const expectedMethodNames = [
+  "createController",
+  "loadSessionState",
+  "readStatus",
+  "refresh",
+  "renderView",
+];
+
+const contract = createIniPanelShellControlPageContract();
+const manifest = createMachineSessionReadonlyStatusApiManifest();
+
+assert.deepEqual(contract, {
+  methodNames: expectedMethodNames,
+  readonlyStatusApiManifest: manifest,
+  readonlyStatusApiMethodNames: ["readStatus"],
+  readonlyStatusApiStatusFields: [
+    "stateBundle",
+    "workflowStatus",
+    "overview",
+    "controlView",
+    "report",
+    "runReadiness",
+    "run",
+    "session",
+    "status",
+  ],
+  relatedControlPageMethods: [
+    "loadSessionState",
+    "readStatus",
+    "refresh",
+    "renderView",
+  ],
+});
+
+const shellViewModel = createIniPanelShellViewModel();
+assert.deepEqual(Object.keys(shellViewModel.controlPage), [
+  "contract",
+  "createController",
+  "loadSessionState",
+  "readonlyStatusApiManifest",
+  "readStatus",
+  "refresh",
+  "renderView",
+]);
+assert.deepEqual(shellViewModel.controlPage.contract, contract);
+assert.deepEqual(shellViewModel.controlPage.readonlyStatusApiManifest, manifest);
+assert.equal(shellViewModel.controlPage.createController, createMachineSessionControlPageController);
+assert.equal(shellViewModel.controlPage.loadSessionState, loadMachineSessionForControlPageWorkflow);
+assert.equal(shellViewModel.controlPage.readStatus, readMachineSessionReadonlyStatus);
+assert.equal(shellViewModel.controlPage.refresh, refreshMachineSessionControlPage);
+assert.equal(shellViewModel.controlPage.renderView, renderMachineSessionControlView);
+
+for (const methodName of contract.methodNames) {
+  assert.equal(typeof shellViewModel.controlPage[methodName], "function");
+  assert.match(docText, new RegExp(`\\b${methodName}\\b`));
+}
+
+for (const fieldName of contract.readonlyStatusApiStatusFields) {
+  assert.match(docText, new RegExp(`\\b${fieldName}\\b`));
+}
+
+assert.match(shellText, /\bexport function createIniPanelShellControlPageContract\b/);
+assert.match(docText, /\bcreateIniPanelShellControlPageContract\b/);
+assert.match(docText, /\bcontrolPage\.contract\b/);
+assert.doesNotMatch(shellText, /\bparseGcode\b|\bcanonicalEvents\b|\btoolTable\b|\bplanner\b/);
+
+console.log("ini_panel_shell_control_page_contract_node_smoke=ok");

wasm-port/tests/ui/node/verify_ini_panel_shell_control_page_contract.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+node "$ROOT_DIR/tests/ui/node/verify_ini_panel_shell_control_page_contract.mjs"

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

@@ -4,6 +4,7 @@ import {
   INI_PANEL_ENTRIES,
   controlPageStatusText,
   createIniPanelLauncherLinkViewModel,
+  createIniPanelShellControlPageContract,
   createIniPanelShellViewModel,
   createMachineSessionReadonlyStatus,
   createMachineSessionReadonlyStatusApiManifest,
@@ -43,6 +44,7 @@ assert.equal(getIniPanelEntryByHref("./index.html")?.id, "edit-run");
 assert.equal(typeof createMachineSessionControlPageController, "function");
 assert.equal(typeof createMachineSessionReadonlyStatus, "function");
 assert.equal(typeof createMachineSessionReadonlyStatusApiManifest, "function");
+assert.equal(typeof createIniPanelShellControlPageContract, "function");
 assert.equal(typeof loadMachineSessionForControlPageWorkflow, "function");
 assert.equal(typeof readMachineSessionReadonlyStatus, "function");
 assert.equal(typeof refreshMachineSessionControlPage, "function");
@@ -84,6 +86,7 @@ assert.deepEqual(shellViewModel.pages, [
 ]);
 assert.deepEqual(shellViewModel.launcherLinks, createIniPanelLauncherLinkViewModel());
 assert.equal(shellViewModel.controlPage.createController, createMachineSessionControlPageController);
+assert.deepEqual(shellViewModel.controlPage.contract, createIniPanelShellControlPageContract());
 assert.equal(shellViewModel.controlPage.loadSessionState, loadMachineSessionForControlPageWorkflow);
 assert.equal(shellViewModel.controlPage.readonlyStatusApiManifest.apiName, "machine-session-readonly-status");
 assert.deepEqual(shellViewModel.controlPage.readonlyStatusApiManifest, createMachineSessionReadonlyStatusApiManifest());

wasm-port/tests/ui/node/verify_ui_node_smokes.sh

@@ -15,6 +15,7 @@ ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
 "$ROOT_DIR/tests/ui/node/verify_ini_panel_readonly_status_api.sh"
 "$ROOT_DIR/tests/ui/node/verify_ini_panel_entry_manifest.sh"
 "$ROOT_DIR/tests/ui/node/verify_ini_panel_ui_shell.sh"
+"$ROOT_DIR/tests/ui/node/verify_ini_panel_shell_control_page_contract.sh"
 "$ROOT_DIR/tests/ui/node/verify_ini_panel_entry_docs.sh"
 
 echo "ui_node_smokes=ok"