推进 INI 面板浏览器 control-page contract 暴露

2026-06-15 06:03:44 +08:00
parent 41caecf116
commit 37b79c1d1a
5 changed files with 104 additions and 0 deletions
--- a/text12.txt
+++ b/text12.txt
@@ -798,3 +798,68 @@ host_wasm_opfs_browser_smokes=ok
 `createIniPanelShellViewModel().controlPage.contract` 或等价 browser-exposed contract，
 把 Node 端 contract gate 延伸到真实嵌入页面流程；仍保持只读，不新增控制按钮，不解析 G-code，
 不解释 canonical events。
+
+九、2026-06-15 继续执行记录：INI panel browser control-page contract exposure
+
+本轮按“第一原则：加快实质性推进”继续推进 browser/UI workflow，把 Node 端 shell control-page
+contract 延伸到真实 browser iframe 流程，使 `control-page.html` 暴露可读 contract，并由
+browser smoke 在读取 embedded panel state 前校验 API shape。
+
+完成内容：
+
+- `wasm-port/runtime/ui/ini-panel/control-page.js` 引入
+  `createIniPanelShellControlPageContract()`；
+- `window.linuxCncIniPanelControlPageApi` 新增 `getControlPageContract()`；
+- `ini_panel_control_page_smoke.html` 在真实 control-page iframe 中校验：
+  - `methodNames`
+  - `readonlyStatusApiManifest.apiName`
+  - `readonlyStatusApiMethodNames`
+  - `relatedControlPageMethods`
+  - `readonlyStatusApiStatusFields`
+- `docs/panel-entry.md` 记录
+  `linuxCncIniPanelControlPageApi.getControlPageContract()` browser API；
+- `verify_ini_panel_entry_docs.mjs` 覆盖 browser-exposed contract API 文档与源码入口；
+- 未新增控制按钮；
+- 未解析 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_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_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
+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
+```
+
+下一步建议：
+
+继续推进 OPFS/session persistence。下一批建议增加一个 browser control-page readonly status
+snapshot smoke，直接通过 `linuxCncIniPanelControlPageApi` 读取 `readStatus()` 或等价只读状态，
+并校验 save/load session 后的 `stateBundle`、`workflowStatus`、`controlView` 一致暴露；仍保持
+只读，不新增控制按钮，不解析 G-code，不解释 canonical events。
--- a/wasm-port/docs/panel-entry.md
+++ b/wasm-port/docs/panel-entry.md
@@ -68,6 +68,9 @@ 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 browser control page also exposes this contract through
+`linuxCncIniPanelControlPageApi.getControlPageContract()`, so real iframe-based
+smokes can verify the same API shape before reading the embedded panel state.

 The control-page refresh workflow lives in
 `runtime/ui/ini-panel/control-page-refresh-workflow.js`. Use
--- a/wasm-port/runtime/ui/ini-panel/control-page.js
+++ b/wasm-port/runtime/ui/ini-panel/control-page.js
@@ -4,6 +4,9 @@ import {
 import {
  createMachineSessionControlPageController,
 } from "./control-page-controller.js";
+import {
+  createIniPanelShellControlPageContract,
+} from "./ui-shell.js";

 const panelFrameNode = document.getElementById("panel-frame");
 const statusNode = document.getElementById("control-page-status");
@@ -20,6 +23,7 @@ controller.mount();

 window.linuxCncIniPanelControlPageApi = {
  getControlView: controller.getControlView,
+  getControlPageContract: createIniPanelShellControlPageContract,
  getPanelApi: controller.getPanelApi,
  loadControlPageSessionState: controller.loadSessionState,
  refreshControlPage: controller.refresh,
--- a/wasm-port/tests/browser/ini_panel_control_page_smoke.html
+++ b/wasm-port/tests/browser/ini_panel_control_page_smoke.html
@@ -63,6 +63,7 @@ TOOL_TABLE = browser-tool.tbl
      const controlPageApi = controlDoc.defaultView.linuxCncIniPanelControlPageApi;
      if (
        !controlPageApi?.getControlView ||
+        !controlPageApi?.getControlPageContract ||
        !controlPageApi?.getPanelApi ||
        !controlPageApi?.loadControlPageSessionState ||
        !controlPageApi?.refreshControlPage ||
@@ -71,6 +72,33 @@ TOOL_TABLE = browser-tool.tbl
        throw new Error("control page API namespace did not expose control helpers");
      }

+      const controlPageContract = controlPageApi.getControlPageContract();
+      assertEqual(
+        controlPageContract.methodNames.join(","),
+        "createController,loadSessionState,readStatus,refresh,renderView",
+        "control page contract methods",
+      );
+      assertEqual(
+        controlPageContract.readonlyStatusApiManifest.apiName,
+        "machine-session-readonly-status",
+        "control page contract readonly status API name",
+      );
+      assertEqual(
+        controlPageContract.readonlyStatusApiMethodNames.join(","),
+        "readStatus",
+        "control page contract readonly status API methods",
+      );
+      assertEqual(
+        controlPageContract.relatedControlPageMethods.join(","),
+        "loadSessionState,readStatus,refresh,renderView",
+        "control page contract related methods",
+      );
+      assertEqual(
+        controlPageContract.readonlyStatusApiStatusFields.join(","),
+        "stateBundle,workflowStatus,overview,controlView,report,runReadiness,run,session,status",
+        "control page contract readonly status fields",
+      );
+
      const panelFrame = controlDoc.getElementById("panel-frame");
      const panelDoc = await waitFor(
        () => panelFrame?.contentDocument,
--- a/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs
+++ b/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs
@@ -22,6 +22,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = resolve(__dirname, "../../..");
 const docText = readFileSync(resolve(root, "docs/panel-entry.md"), "utf8");
 const shellText = readFileSync(resolve(root, "runtime/ui/ini-panel/ui-shell.js"), "utf8");
+const controlPageText = readFileSync(resolve(root, "runtime/ui/ini-panel/control-page.js"), "utf8");
 const refreshWorkflowText = readFileSync(
  resolve(root, "runtime/ui/ini-panel/control-page-refresh-workflow.js"),
  "utf8",
@@ -119,6 +120,9 @@ assert.deepEqual(
 assert.equal(createIniPanelShellViewModel().controlPage.readStatus, readMachineSessionReadonlyStatus);
 assert.equal(createIniPanelShellViewModel().controlPage.refresh, refreshMachineSessionControlPage);
 assert.equal(typeof createIniPanelShellViewModel().controlPage.renderView, "function");
+assert.match(controlPageText, /\bgetControlPageContract\b/);
+assert.match(controlPageText, /\bcreateIniPanelShellControlPageContract\b/);
+assert.match(docText, /\blinuxCncIniPanelControlPageApi\.getControlPageContract\b/);

 for (const entry of INI_PANEL_ENTRIES) {
  const escapedHref = entry.href.replace(".", "\\.");