diff --git a/text12.txt b/text12.txt index 93e78c5..cc6eda6 100644 --- a/text12.txt +++ b/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。 diff --git a/wasm-port/docs/panel-entry.md b/wasm-port/docs/panel-entry.md index 7e5ffcb..3dc1cd3 100644 --- a/wasm-port/docs/panel-entry.md +++ b/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 diff --git a/wasm-port/runtime/ui/ini-panel/ui-shell.js b/wasm-port/runtime/ui/ini-panel/ui-shell.js index 1a1d85f..7f1aed8 100644 --- a/wasm-port/runtime/ui/ini-panel/ui-shell.js +++ b/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(), diff --git a/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs b/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs index 3e206ba..a13eb71 100644 --- a/wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs +++ b/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", diff --git 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 new file mode 100644 index 0000000..355aced --- /dev/null +++ b/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"); diff --git a/wasm-port/tests/ui/node/verify_ini_panel_shell_control_page_contract.sh b/wasm-port/tests/ui/node/verify_ini_panel_shell_control_page_contract.sh new file mode 100755 index 0000000..babf970 --- /dev/null +++ b/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" diff --git a/wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs b/wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs index 17bddfa..2045d7c 100644 --- a/wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs +++ b/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()); diff --git a/wasm-port/tests/ui/node/verify_ui_node_smokes.sh b/wasm-port/tests/ui/node/verify_ui_node_smokes.sh index cb23e1f..01f62af 100755 --- a/wasm-port/tests/ui/node/verify_ui_node_smokes.sh +++ b/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"