推进 INI 面板 control-page API manifest predicate

wasm-port/docs/panel-entry.md

@@ -10,7 +10,9 @@ control view:
 ```js
 import {
   INI_PANEL_ENTRIES,
+  createControlPageBrowserApiManifest,
   createControlPageBrowserApiMethods,
+  createControlPageBrowserApiSchema,
   createIniPanelLaunchApiManifest,
   createIniPanelLaunchApiSchema,
   createIniPanelLauncherLinkViewModel,
@@ -27,6 +29,7 @@ import {
   refreshMachineSessionControlPage,
   controlPageStatusText,
   renderMachineSessionControlView,
+  isSupportedIniPanelControlPageApiManifest,
   isSupportedIniPanelLaunchApiManifest,
 } from "../runtime/ui/ini-panel/ui-shell.js";
 ```
@@ -78,6 +81,14 @@ smokes can verify the same API shape before reading the embedded panel state.
 Use `linuxCncIniPanelControlPageApi.getControlPageApiMethods()` when a browser
 outer page needs the exact exposed method list before calling the read-only
 control page API.
+Use `createControlPageBrowserApiSchema()`,
+`createControlPageBrowserApiManifest()`, or
+`linuxCncIniPanelControlPageApi.getControlPageApiSchema()` and
+`linuxCncIniPanelControlPageApi.getControlPageApiManifest()` when a browser
+outer page needs a versioned control-page API description before reading the
+embedded panel. Use `isSupportedIniPanelControlPageApiManifest()` or
+`linuxCncIniPanelControlPageApi.isSupportedControlPageApiManifest()` for a
+read-only compatibility predicate before consuming that manifest.
 Use `linuxCncIniPanelControlPageApi.readControlPageStatus()` when a browser
 outer page needs the same readonly status snapshot from the real embedded
 control page after save/load session workflows.

wasm-port/runtime/ui/ini-panel/control-page.js

@@ -5,8 +5,11 @@ import {
   createMachineSessionControlPageController,
 } from "./control-page-controller.js";
 import {
+  createControlPageBrowserApiManifest,
   createControlPageBrowserApiMethods,
+  createControlPageBrowserApiSchema,
   createIniPanelShellControlPageContract,
+  isSupportedIniPanelControlPageApiManifest,
 } from "./ui-shell.js";
 
 const panelFrameNode = document.getElementById("panel-frame");
@@ -23,6 +26,9 @@ const controller = createMachineSessionControlPageController({
 controller.mount();
 
 window.linuxCncIniPanelControlPageApi = {
+  isSupportedControlPageApiManifest: isSupportedIniPanelControlPageApiManifest,
+  getControlPageApiSchema: createControlPageBrowserApiSchema,
+  getControlPageApiManifest: createControlPageBrowserApiManifest,
   getControlPageApiMethods: createControlPageBrowserApiMethods,
   getControlView: controller.getControlView,
   getControlPageContract: createIniPanelShellControlPageContract,

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

@@ -87,6 +87,33 @@ export function isSupportedIniPanelLaunchApiManifest(manifest, schema = createIn
   return schema.fields.every((fieldName) => Object.hasOwn(manifest, fieldName));
 }
 
+export function createControlPageBrowserApiSchema() {
+  return {
+    apiName: "ini-panel-control-page",
+    manifestVersion: 1,
+    fields: [
+      "apiName",
+      "manifestVersion",
+      "methods",
+      "contract",
+      "readonlyStatusApiManifest",
+    ],
+  };
+}
+
+export function isSupportedIniPanelControlPageApiManifest(
+  manifest,
+  schema = createControlPageBrowserApiSchema(),
+) {
+  if (!manifest || typeof manifest !== "object") {
+    return false;
+  }
+  if (manifest.apiName !== schema.apiName || manifest.manifestVersion !== schema.manifestVersion) {
+    return false;
+  }
+  return schema.fields.every((fieldName) => Object.hasOwn(manifest, fieldName));
+}
+
 export function createIniPanelLaunchApiManifest(entries = getVisibleIniPanelEntries()) {
   const schema = createIniPanelLaunchApiSchema();
   return {
@@ -148,6 +175,9 @@ export function createIniPanelShellControlPageContract() {
 
 export function createControlPageBrowserApiMethods() {
   return [
+    "isSupportedControlPageApiManifest",
+    "getControlPageApiSchema",
+    "getControlPageApiManifest",
     "getControlPageApiMethods",
     "getControlPageContract",
     "getControlView",
@@ -159,6 +189,18 @@ export function createControlPageBrowserApiMethods() {
   ];
 }
 
+export function createControlPageBrowserApiManifest() {
+  const schema = createControlPageBrowserApiSchema();
+  const contract = createIniPanelShellControlPageContract();
+  return {
+    apiName: schema.apiName,
+    manifestVersion: schema.manifestVersion,
+    methods: createControlPageBrowserApiMethods(),
+    contract,
+    readonlyStatusApiManifest: contract.readonlyStatusApiManifest,
+  };
+}
+
 export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries()) {
   return {
     pages: entries.map(({ id, href, title }) => ({
@@ -170,9 +212,12 @@ export function createIniPanelShellViewModel(entries = getVisibleIniPanelEntries
     launchApiSchema: createIniPanelLaunchApiSchema(),
     launchApiManifest: createIniPanelLaunchApiManifest(entries),
     controlPage: {
+      browserApiSchema: createControlPageBrowserApiSchema(),
+      browserApiManifest: createControlPageBrowserApiManifest(),
       browserApiMethods: createControlPageBrowserApiMethods(),
       contract: createIniPanelShellControlPageContract(),
       createController: createMachineSessionControlPageController,
+      isSupportedBrowserApiManifest: isSupportedIniPanelControlPageApiManifest,
       loadSessionState: loadMachineSessionForControlPageWorkflow,
       readonlyStatusApiManifest: createMachineSessionReadonlyStatusApiManifest(),
       readStatus: readMachineSessionReadonlyStatus,

wasm-port/tests/browser/ini_panel_control_page_smoke.html

@@ -62,6 +62,9 @@ TOOL_TABLE = browser-tool.tbl
       const controlDoc = await loadControlPageFrame();
       const controlPageApi = controlDoc.defaultView.linuxCncIniPanelControlPageApi;
       const expectedControlPageApiMethods = [
+        "isSupportedControlPageApiManifest",
+        "getControlPageApiSchema",
+        "getControlPageApiManifest",
         "getControlPageApiMethods",
         "getControlPageContract",
         "getControlView",
@@ -72,6 +75,9 @@ TOOL_TABLE = browser-tool.tbl
         "renderControlPage",
       ];
       if (
+        !controlPageApi?.isSupportedControlPageApiManifest ||
+        !controlPageApi?.getControlPageApiSchema ||
+        !controlPageApi?.getControlPageApiManifest ||
         !controlPageApi?.getControlPageApiMethods ||
         !controlPageApi?.getControlView ||
         !controlPageApi?.getControlPageContract ||
@@ -94,6 +100,39 @@ TOOL_TABLE = browser-tool.tbl
         "control page browser API namespace methods",
       );
 
+      const controlPageApiSchema = controlPageApi.getControlPageApiSchema();
+      assertEqual(
+        controlPageApiSchema.manifestVersion,
+        1,
+        "control page API schema manifest version",
+      );
+      assertEqual(
+        controlPageApiSchema.fields.includes("readonlyStatusApiManifest"),
+        true,
+        "control page API schema readonly status field",
+      );
+      const controlPageApiManifest = controlPageApi.getControlPageApiManifest();
+      assertEqual(
+        controlPageApi.isSupportedControlPageApiManifest(controlPageApiManifest),
+        true,
+        "control page API supports manifest",
+      );
+      assertEqual(
+        controlPageApi.isSupportedControlPageApiManifest({ ...controlPageApiManifest, apiName: "other" }),
+        false,
+        "control page API rejects unsupported manifest name",
+      );
+      assertEqual(
+        controlPageApiManifest.methods.join(","),
+        expectedControlPageApiMethods.join(","),
+        "control page API manifest methods",
+      );
+      assertEqual(
+        controlPageApiManifest.readonlyStatusApiManifest.apiName,
+        "machine-session-readonly-status",
+        "control page API manifest readonly status API name",
+      );
+
       const controlPageContract = controlPageApi.getControlPageContract();
       assertEqual(
         controlPageContract.methodNames.join(","),

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

@@ -6,8 +6,10 @@ import { dirname, resolve } from "node:path";
 import {
   INI_PANEL_ENTRIES,
   controlPageStatusText,
+  createControlPageBrowserApiManifest,
   createControlPageSessionLoadState,
   createControlPageBrowserApiMethods,
+  createControlPageBrowserApiSchema,
   createIniPanelLaunchApiManifest,
   createIniPanelLaunchApiSchema,
   createIniPanelLauncherLinkViewModel,
@@ -19,6 +21,7 @@ import {
   readMachineSessionReadonlyStatus,
   refreshMachineSessionControlPage,
   getVisibleIniPanelEntries,
+  isSupportedIniPanelControlPageApiManifest,
   isSupportedIniPanelLaunchApiManifest,
 } from "../../../runtime/ui/ini-panel/ui-shell.js";
 
@@ -40,7 +43,9 @@ const sessionWorkflowText = readFileSync(
 const requiredShellExports = [
   "INI_PANEL_ENTRIES",
   "controlPageStatusText",
+  "createControlPageBrowserApiManifest",
   "createControlPageBrowserApiMethods",
+  "createControlPageBrowserApiSchema",
   "createControlPageSessionLoadState",
   "createIniPanelLaunchApiManifest",
   "createIniPanelLaunchApiSchema",
@@ -49,6 +54,7 @@ const requiredShellExports = [
   "createIniPanelShellViewModel",
   "getIniPanelEntryByHref",
   "getVisibleIniPanelEntries",
+  "isSupportedIniPanelControlPageApiManifest",
   "isSupportedIniPanelLaunchApiManifest",
   "createMachineSessionControlPageController",
   "createMachineSessionReadonlyStatus",
@@ -106,6 +112,15 @@ assert.deepEqual(createIniPanelShellViewModel().launchApiSchema, createIniPanelL
 assert.deepEqual(createIniPanelShellViewModel().launchApiManifest, createIniPanelLaunchApiManifest());
 assert.equal(isSupportedIniPanelLaunchApiManifest(createIniPanelShellViewModel().launchApiManifest), true);
 assert.equal(createIniPanelShellViewModel().launchApiManifest.manifestVersion, createIniPanelLaunchApiSchema().manifestVersion);
+assert.deepEqual(
+  createIniPanelShellViewModel().controlPage.browserApiSchema,
+  createControlPageBrowserApiSchema(),
+);
+assert.deepEqual(
+  createIniPanelShellViewModel().controlPage.browserApiManifest,
+  createControlPageBrowserApiManifest(),
+);
+assert.equal(isSupportedIniPanelControlPageApiManifest(createIniPanelShellViewModel().controlPage.browserApiManifest), true);
 assert.deepEqual(
   createIniPanelShellViewModel().controlPage.contract,
   createIniPanelShellControlPageContract(),
@@ -138,9 +153,15 @@ assert.equal(createIniPanelShellViewModel().controlPage.readStatus, readMachineS
 assert.equal(createIniPanelShellViewModel().controlPage.refresh, refreshMachineSessionControlPage);
 assert.equal(typeof createIniPanelShellViewModel().controlPage.renderView, "function");
 assert.match(shellText, /\bexport function createControlPageBrowserApiMethods\b/);
+assert.match(shellText, /\bexport function createControlPageBrowserApiManifest\b/);
+assert.match(shellText, /\bexport function createControlPageBrowserApiSchema\b/);
 assert.match(shellText, /\bexport function createIniPanelLaunchApiSchema\b/);
 assert.match(shellText, /\bexport function createIniPanelLaunchApiManifest\b/);
+assert.match(shellText, /\bexport function isSupportedIniPanelControlPageApiManifest\b/);
 assert.match(shellText, /\bexport function isSupportedIniPanelLaunchApiManifest\b/);
+assert.match(controlPageText, /\bisSupportedControlPageApiManifest\b/);
+assert.match(controlPageText, /\bgetControlPageApiSchema\b/);
+assert.match(controlPageText, /\bgetControlPageApiManifest\b/);
 assert.match(controlPageText, /\bgetControlPageApiMethods\b/);
 assert.match(launchText, /\blinuxCncIniPanelLaunchApi\b/);
 assert.match(launchText, /\bisSupportedLaunchApiManifest\b/);
@@ -151,10 +172,16 @@ assert.match(controlPageText, /\bgetControlPageContract\b/);
 assert.match(controlPageText, /\breadControlPageStatus\b/);
 assert.match(controlPageText, /\bcreateIniPanelShellControlPageContract\b/);
 assert.match(docText, /\blinuxCncIniPanelControlPageApi\.getControlPageApiMethods\b/);
+assert.match(docText, /\blinuxCncIniPanelControlPageApi\.getControlPageApiSchema\b/);
+assert.match(docText, /\blinuxCncIniPanelControlPageApi\.getControlPageApiManifest\b/);
+assert.match(docText, /\blinuxCncIniPanelControlPageApi\.isSupportedControlPageApiManifest\b/);
 assert.match(docText, /\blinuxCncIniPanelControlPageApi\.getControlPageContract\b/);
 assert.match(docText, /\blinuxCncIniPanelControlPageApi\.readControlPageStatus\b/);
+assert.match(docText, /\bcreateControlPageBrowserApiManifest\b/);
+assert.match(docText, /\bcreateControlPageBrowserApiSchema\b/);
 assert.match(docText, /\bcreateIniPanelLaunchApiManifest\b/);
 assert.match(docText, /\bcreateIniPanelLaunchApiSchema\b/);
+assert.match(docText, /\bisSupportedIniPanelControlPageApiManifest\b/);
 assert.match(docText, /\bisSupportedIniPanelLaunchApiManifest\b/);
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.isSupportedLaunchApiManifest\b/);
 assert.match(docText, /\blinuxCncIniPanelLaunchApi\.getLaunchApiSchema\b/);

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

@@ -4,7 +4,9 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
+  createControlPageBrowserApiManifest,
   createControlPageBrowserApiMethods,
+  createControlPageBrowserApiSchema,
   createIniPanelLaunchApiManifest,
   createIniPanelShellControlPageContract,
   createIniPanelShellViewModel,
@@ -14,6 +16,7 @@ import {
   readMachineSessionReadonlyStatus,
   refreshMachineSessionControlPage,
   renderMachineSessionControlView,
+  isSupportedIniPanelControlPageApiManifest,
 } from "../../../runtime/ui/ini-panel/ui-shell.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -31,6 +34,20 @@ const expectedMethodNames = [
 
 const contract = createIniPanelShellControlPageContract();
 const manifest = createMachineSessionReadonlyStatusApiManifest();
+const browserApiSchema = createControlPageBrowserApiSchema();
+const browserApiManifest = createControlPageBrowserApiManifest();
+
+assert.deepEqual(browserApiSchema, {
+  apiName: "ini-panel-control-page",
+  manifestVersion: 1,
+  fields: [
+    "apiName",
+    "manifestVersion",
+    "methods",
+    "contract",
+    "readonlyStatusApiManifest",
+  ],
+});
 
 assert.deepEqual(contract, {
   methodNames: expectedMethodNames,
@@ -55,22 +72,43 @@ assert.deepEqual(contract, {
   ],
 });
 
+assert.deepEqual(browserApiManifest, {
+  apiName: "ini-panel-control-page",
+  manifestVersion: 1,
+  methods: createControlPageBrowserApiMethods(),
+  contract,
+  readonlyStatusApiManifest: manifest,
+});
+assert.equal(isSupportedIniPanelControlPageApiManifest(browserApiManifest), true);
+assert.equal(isSupportedIniPanelControlPageApiManifest({ ...browserApiManifest, manifestVersion: 2 }), false);
+assert.equal(isSupportedIniPanelControlPageApiManifest({ ...browserApiManifest, apiName: "other" }), false);
+const missingReadonlyManifest = { ...browserApiManifest };
+delete missingReadonlyManifest.readonlyStatusApiManifest;
+assert.equal(isSupportedIniPanelControlPageApiManifest(missingReadonlyManifest), false);
+assert.equal(isSupportedIniPanelControlPageApiManifest(null), false);
+
 const shellViewModel = createIniPanelShellViewModel();
 assert.deepEqual(shellViewModel.launchApiManifest, createIniPanelLaunchApiManifest());
 assert.deepEqual(Object.keys(shellViewModel.controlPage), [
+  "browserApiSchema",
+  "browserApiManifest",
   "browserApiMethods",
   "contract",
   "createController",
+  "isSupportedBrowserApiManifest",
   "loadSessionState",
   "readonlyStatusApiManifest",
   "readStatus",
   "refresh",
   "renderView",
 ]);
+assert.deepEqual(shellViewModel.controlPage.browserApiSchema, browserApiSchema);
+assert.deepEqual(shellViewModel.controlPage.browserApiManifest, browserApiManifest);
 assert.deepEqual(shellViewModel.controlPage.browserApiMethods, createControlPageBrowserApiMethods());
 assert.deepEqual(shellViewModel.controlPage.contract, contract);
 assert.deepEqual(shellViewModel.controlPage.readonlyStatusApiManifest, manifest);
 assert.equal(shellViewModel.controlPage.createController, createMachineSessionControlPageController);
+assert.equal(shellViewModel.controlPage.isSupportedBrowserApiManifest, isSupportedIniPanelControlPageApiManifest);
 assert.equal(shellViewModel.controlPage.loadSessionState, loadMachineSessionForControlPageWorkflow);
 assert.equal(shellViewModel.controlPage.readStatus, readMachineSessionReadonlyStatus);
 assert.equal(shellViewModel.controlPage.refresh, refreshMachineSessionControlPage);
@@ -86,8 +124,14 @@ for (const fieldName of contract.readonlyStatusApiStatusFields) {
 }
 
 assert.match(shellText, /\bexport function createIniPanelShellControlPageContract\b/);
+assert.match(shellText, /\bexport function createControlPageBrowserApiManifest\b/);
 assert.match(shellText, /\bexport function createControlPageBrowserApiMethods\b/);
+assert.match(shellText, /\bexport function createControlPageBrowserApiSchema\b/);
+assert.match(shellText, /\bexport function isSupportedIniPanelControlPageApiManifest\b/);
 assert.match(docText, /\bcreateIniPanelShellControlPageContract\b/);
+assert.match(docText, /\bcreateControlPageBrowserApiManifest\b/);
+assert.match(docText, /\bcreateControlPageBrowserApiSchema\b/);
+assert.match(docText, /\bisSupportedIniPanelControlPageApiManifest\b/);
 assert.match(docText, /\bcontrolPage\.contract\b/);
 assert.doesNotMatch(shellText, /\bparseGcode\b|\bcanonicalEvents\b|\btoolTable\b|\bplanner\b/);
 

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

@@ -3,7 +3,9 @@ import assert from "node:assert/strict";
 import {
   INI_PANEL_ENTRIES,
   controlPageStatusText,
+  createControlPageBrowserApiManifest,
   createControlPageBrowserApiMethods,
+  createControlPageBrowserApiSchema,
   createIniPanelLaunchApiManifest,
   createIniPanelLaunchApiSchema,
   createIniPanelLauncherLinkViewModel,
@@ -17,6 +19,7 @@ import {
   getIniPanelEntryByHref,
   getIniPanelEntryManifest,
   getVisibleIniPanelEntries,
+  isSupportedIniPanelControlPageApiManifest,
   isSupportedIniPanelLaunchApiManifest,
   loadMachineSessionForControlPageWorkflow,
   readMachineSessionReadonlyStatus,
@@ -48,7 +51,9 @@ 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 createControlPageBrowserApiManifest, "function");
 assert.equal(typeof createControlPageBrowserApiMethods, "function");
+assert.equal(typeof createControlPageBrowserApiSchema, "function");
 assert.equal(typeof createIniPanelLaunchApiManifest, "function");
 assert.equal(typeof createIniPanelLaunchApiSchema, "function");
 assert.equal(typeof createIniPanelShellControlPageContract, "function");
@@ -56,6 +61,7 @@ assert.equal(typeof loadMachineSessionForControlPageWorkflow, "function");
 assert.equal(typeof readMachineSessionReadonlyStatus, "function");
 assert.equal(typeof refreshMachineSessionControlPage, "function");
 assert.equal(typeof renderMachineSessionControlView, "function");
+assert.equal(typeof isSupportedIniPanelControlPageApiManifest, "function");
 assert.equal(typeof isSupportedIniPanelLaunchApiManifest, "function");
 
 const shellManifest = getIniPanelEntryManifest();
@@ -97,9 +103,17 @@ assert.deepEqual(shellViewModel.launchApiSchema, createIniPanelLaunchApiSchema()
 assert.deepEqual(shellViewModel.launchApiManifest, createIniPanelLaunchApiManifest());
 assert.equal(isSupportedIniPanelLaunchApiManifest(shellViewModel.launchApiManifest), true);
 assert.equal(shellViewModel.launchApiManifest.manifestVersion, createIniPanelLaunchApiSchema().manifestVersion);
+assert.deepEqual(shellViewModel.controlPage.browserApiSchema, createControlPageBrowserApiSchema());
+assert.deepEqual(shellViewModel.controlPage.browserApiManifest, createControlPageBrowserApiManifest());
 assert.deepEqual(shellViewModel.controlPage.browserApiMethods, createControlPageBrowserApiMethods());
+assert.equal(isSupportedIniPanelControlPageApiManifest(shellViewModel.controlPage.browserApiManifest), true);
+assert.equal(
+  shellViewModel.controlPage.browserApiManifest.manifestVersion,
+  createControlPageBrowserApiSchema().manifestVersion,
+);
 assert.equal(shellViewModel.controlPage.createController, createMachineSessionControlPageController);
 assert.deepEqual(shellViewModel.controlPage.contract, createIniPanelShellControlPageContract());
+assert.equal(shellViewModel.controlPage.isSupportedBrowserApiManifest, isSupportedIniPanelControlPageApiManifest);
 assert.equal(shellViewModel.controlPage.loadSessionState, loadMachineSessionForControlPageWorkflow);
 assert.equal(shellViewModel.controlPage.readonlyStatusApiManifest.apiName, "machine-session-readonly-status");
 assert.deepEqual(shellViewModel.controlPage.readonlyStatusApiManifest, createMachineSessionReadonlyStatusApiManifest());