推进 INI 面板 shell handoff snapshot API

text13.txt

@@ -0,0 +1,509 @@
+项目整体完成情况与后续执行计划
+
+生成时间：2026-06-15 CST
+
+本文件接替 `text12.txt`。后续工作按 `text13.txt` 执行；除非明确要求审计旧记录，
+不要再回到 `text1/text2/text3/text4/text5/text6/text7/text8/text9/text10/text11/text12`
+扩展进度。`text12.txt` 作为历史归档保留。
+
+一、第一原则：加快实质性推进
+
+后续批次必须以“实质性能力优先”为第一遵守原则。
+
+1. 优先级从高到低：
+
+- OPFS/session persistence；
+- SDK/API surface；
+- browser/UI workflow；
+- sim config coverage promotion；
+- host/runtime boundary proof；
+- 文档化可执行工作流。
+
+2. 每批默认应产出至少一种可直接复用的能力：
+
+- 可调用 helper；
+- 可复用 API；
+- 可验证用户流程；
+- 可执行 gate；
+- 可提升覆盖面的 runtime boundary proof；
+- 能直接指导下一步实现的设计/清单。
+
+3. 暂停低收益推进：
+
+- 不再把“局部常量化、路径变量收敛、断言分组整理”作为主目标；
+- 只有当它支撑可复用 workflow/API/gate 时，才允许做测试胶水；
+- 禁止为了推进而扩大 CNC 语义边界；
+- 禁止启动性能测试，除非已有明确用户流程需要性能基线。
+
+4. LinuxCNC 仍是唯一 CNC 语义来源：
+
+- G-code、remap、tool、parameter、planner、kinematics、user-M、tool DB、Python remap
+  等语义必须来自 LinuxCNC upstream 或 vendored LinuxCNC C/C++/配置/脚本源码；
+- JS/browser 只允许做 build、source sync、runtime shim、filesystem staging、OPFS、
+  WASM/browser boundary、测试胶水、文档和机器可读 gate/artifact；
+- 不在 JS 中重写 G-code 或 CNC 语义；
+- 不修改 vendored LinuxCNC 源文件来让测试通过；
+- 不把 full-process/HAL/UI/Python/tool DB 依赖伪装成 standalone pass；
+- 不把 expected failure 硬改成 pass，除非已有 LinuxCNC-owned runtime proof，并且
+  native、Node、browser gate 都按顺序通过；
+- browser 不能依赖目录枚举。
+
+二、续接状态与防重规则
+
+1. 当前续接点。
+
+`text12.txt` 已推进到：
+
+```text
+二十六、2026-06-15 继续执行记录：INI panel shell session handoff summary schema gate
+```
+
+本文件从 `text13.txt` 重新开始记录后续进度。
+
+2. 每轮开始前必须先执行：
+
+```bash
+git status --short
+git log -5 --oneline
+tail -n 120 text13.txt
+awk '/^[一二三四五六七八九十百]+、/ {print}' text13.txt | sort | uniq -d
+```
+
+执行规则：
+
+- 如果 `git status --short` 是 clean，且最新提交已经包含当前建议工作，不要重复追加记录；
+- 每轮只追加一个新的中文编号记录；
+- 提交前再次检查标题唯一性；
+- `text13.txt` 只记录新的后续进度，不复制 `text12.txt` 的长历史；
+- 每批完成后，如果要写记录，先写 `text13.txt`，再提交该批代码和记录；
+- 如果发现重复记录，先做 dedupe 清理并提交，再继续新功能或新 guard；
+- `text12.txt` 不再追加新进度，除非明确要求审计或修正历史记录。
+
+三、当前完成情况摘要
+
+1. 当前工作树状态。
+
+切换到 `text13.txt` 时工作树包含上一批未提交改动：
+
+```text
+M text12.txt
+M wasm-port/docs/panel-entry.md
+M wasm-port/runtime/ui/ini-panel/launch.html
+M wasm-port/runtime/ui/ini-panel/ui-shell.js
+M wasm-port/tests/browser/ini_panel_launch_smoke.html
+M wasm-port/tests/browser/ini_panel_shell_integration_workflow_smoke.html
+M wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs
+M wasm-port/tests/ui/node/verify_ini_panel_launch_api_manifest.mjs
+M wasm-port/tests/ui/node/verify_ini_panel_shell_integration_manifest.mjs
+M wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs
+```
+
+上述改动对应 `text12.txt` 第 26 条：shell session handoff summary schema gate。
+
+2. 最近提交：
+
+```text
+01817f6 推进 INI 面板 shell handoff summary browser API
+b31b9a2 推进 INI 面板 shell session handoff summary
+ee665c4 推进 INI 面板 shell integration workflow plan
+a663c8d 推进 INI 面板 shell integration browser workflow smoke
+1f9a8c3 推进 INI 面板 shell integration readiness helper
+```
+
+3. 关键基线保持稳定。
+
+- `linuxcnc/nc_files` native Layer 1：
+  - `total 107`
+  - `pass 101`
+  - `expected_fail 6`
+  - `unexpected_fail 0`
+- `linuxcnc/configs/sim` native Layer 2：
+  - `total 159`
+  - `pass 151`
+  - `expected_fail 8`
+  - `unexpected_fail 0`
+- Node sim-config inventory：
+  - `executed=28`
+  - `passed=28`
+  - `skipped=131`
+  - `unexpected_fail=0`
+
+4. blocked runtime family 仍未 promotion。
+
+仍 blocked，不允许 promotion：
+
+- `L4-USER-M-PROCESS`
+- `L4-TOOL-DB`
+- `L4-PYTHON-REMAP`
+
+当前 host 仍按缺少 LinuxCNC host runtime 处理，不执行任何：
+
+```bash
+ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_millturn_user_m_runtime.sh
+ENABLE_TOOL_DB_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_tool_db_runtime.sh
+ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_python_remap_runtime.sh
+```
+
+四、当前实质能力进展
+
+1. INI panel/UI helper 能力。
+
+当前 UI helper 已覆盖：
+
+- run summary；
+- run workflow；
+- session snapshot summary；
+- session load summary；
+- machine file save/load summary；
+- panel state summary；
+- session snapshot save/restore workflow；
+- entry manifest、launcher link view-model、shell view-model；
+- read-only control-page controller；
+- read-only control-page refresh workflow；
+- read-only control-page session readiness workflow；
+- shell integration readiness、workflow plan、session handoff summary；
+- shell session handoff summary versioned schema 与 compatibility predicate。
+
+当前聚合验证入口：
+
+```bash
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+```
+
+2. Browser/UI workflow 验证。
+
+当前 browser INI panel smoke 覆盖真实 OPFS/session persistence workflow 与外部 shell handoff：
+
+```bash
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+```
+
+关键输出：
+
+```text
+browser_ini_opfs_smoke=ok
+browser_ini_control_page_smoke=ok
+browser_ini_launch_smoke=ok
+browser_ini_shell_integration_workflow_smoke=ok
+```
+
+五、当前必须保持通过的验证入口
+
+每批后续改动至少运行：
+
+```bash
+git diff --check
+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/ui/node/verify_ui_node_smokes.sh
+wasm-port/tests/host/verify_host_smokes.sh
+```
+
+如果涉及 browser interpreter smoke，再运行：
+
+```bash
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_interp_browser.sh
+```
+
+涉及 native baseline 或大范围 source/staging 改动时，再运行：
+
+```bash
+wasm-port/tests/native/verify_nc_files.sh
+wasm-port/tests/native/verify_sim_configs.sh
+```
+
+六、下一步建议
+
+继续推进 SDK/API surface 与 browser/UI workflow 的交界。下一批建议增加一个
+`createIniPanelShellSessionHandoffCompatibilityReport()` 或等价 helper，把 summary schema
+支持状态、缺失字段、version/apiName mismatch 与 blocking reasons 合并成可显示报告，便于外部
+shell 在 UI 中解释为什么不能消费 handoff summary；仍保持只读，不新增控制按钮，不解析 G-code。
+
+一、2026-06-15 继续执行记录：INI panel shell session handoff compatibility report
+
+本轮按“第一原则：加快实质性推进”创建 `text13.txt` 续接文件，并继续推进 SDK/API
+surface 与 browser/UI workflow 的交界：新增 shell session handoff compatibility report，让外部
+shell 能读取 display-ready 诊断，判断 handoff summary 是否可消费以及失败原因。
+
+完成内容：
+
+- 新建 `text13.txt`，接替 `text12.txt` 作为后续执行记录；
+- `ui-shell.js` 新增 `createIniPanelShellSessionHandoffCompatibilityReport()`；
+- compatibility report 输出：
+  - `apiName: "ini-panel-shell-session-handoff-compatibility-report"`；
+  - `reportVersion: 1`；
+  - `phase: "ready" | "blocked"`；
+  - `compatible`；
+  - `summarySupported`；
+  - `handoffReady`；
+  - `schema`；
+  - `summary`；
+  - `missingFields`；
+  - `mismatchFields`；
+  - `blockingReasons`；
+- `createIniPanelShellViewModel()` 新增：
+  - `shellSessionHandoffCompatibilityReport`；
+  - `createShellSessionHandoffCompatibilityReport`；
+- `createIniPanelLaunchApiManifest().methods` 新增
+  `getShellSessionHandoffCompatibilityReport`；
+- `launch.html` 的 `window.linuxCncIniPanelLaunchApi` 新增真实 browser 入口
+  `getShellSessionHandoffCompatibilityReport()`；
+- `ini_panel_launch_smoke.html` 校验真实 launch iframe 的 compatibility report：
+  - `compatible === true`；
+  - `summarySupported === true`；
+  - `missingFields` 为空；
+- `ini_panel_shell_integration_workflow_smoke.html` 校验外部 shell handoff workflow 能读取
+  compatibility report，并确认当前 report 无 blocking reasons；
+- `verify_ini_panel_shell_integration_manifest.mjs` 覆盖：
+  - ready report 完整 shape；
+  - 错误 `summaryVersion` 进入 `mismatchFields`；
+  - 缺字段进入 `missingFields`；
+  - `null` summary 返回完整缺字段列表；
+  - blocked workflow 的 `blockingReasons` 和 `compatible === false`；
+- `verify_ini_panel_launch_api_manifest.mjs`、`verify_ini_panel_ui_shell.mjs`、
+  `verify_ini_panel_entry_docs.mjs` 与 `docs/panel-entry.md` 同步记录和校验新 helper/API；
+- 未新增控制按钮；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未新增 JS CNC 语义；
+- 未改变 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_integration_manifest.sh
+wasm-port/tests/ui/node/verify_ini_panel_launch_api_manifest.sh
+wasm-port/tests/ui/node/verify_ini_panel_ui_shell.sh
+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_shell_integration_manifest_node_smoke=ok
+ini_panel_launch_api_manifest_node_smoke=ok
+ini_panel_ui_shell_node_smoke=ok
+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
+browser_ini_shell_integration_workflow_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
+```
+
+下一步建议：
+
+继续推进 browser/UI workflow。下一批建议把 compatibility report 用到一个真实的外部 shell
+display view-model 或 DOM smoke 中，让 launch 页面能直接展示 handoff 是否可消费、缺失字段和
+blocking reasons；仍保持只读，不新增控制按钮，不解析 G-code。
+
+二、2026-06-15 继续执行记录：INI panel shell handoff display view-model
+
+本轮按“第一原则：加快实质性推进”继续推进 browser/UI workflow，把上一批 compatibility
+report 接入可复用 display view-model 与真实 launch DOM，让外部 shell 能直接展示 handoff
+是否可消费、缺失字段、mismatch fields 与 blocking reasons。
+
+完成内容：
+
+- `ui-shell.js` 新增 `createIniPanelShellSessionHandoffDisplayViewModel()`；
+- display view-model 输出：
+  - `phase: "ready" | "blocked"`；
+  - `title`；
+  - `statusText`；
+  - `detailText`；
+  - `rows`；
+- `rows` 固定覆盖：
+  - `summary-supported`；
+  - `handoff-ready`；
+  - `missing-fields`；
+  - `mismatch-fields`；
+  - `blocking-reasons`；
+- `createIniPanelShellViewModel()` 新增：
+  - `shellSessionHandoffDisplayViewModel`；
+  - `createShellSessionHandoffDisplayViewModel`；
+- `createIniPanelLaunchApiManifest().methods` 新增
+  `getShellSessionHandoffDisplayViewModel`；
+- `launch.html` 的 `window.linuxCncIniPanelLaunchApi` 新增真实 browser 入口
+  `getShellSessionHandoffDisplayViewModel()`；
+- `launch.html` 新增只读 DOM 展示区域：
+  - `[data-handoff-status]`；
+  - `[data-handoff-rows]`；
+  - `[data-handoff-value="missing-fields"]`；
+  - `[data-handoff-value="blocking-reasons"]`；
+- `ini_panel_launch_smoke.html` 校验真实 launch iframe：
+  - display view-model `statusText === "Ready"`；
+  - display rows 数量为 5；
+  - DOM status 为 `Ready: No blocking reasons`；
+  - DOM missing fields 为 `none`；
+  - DOM blocking reasons 为 `none`；
+- `ini_panel_shell_integration_workflow_smoke.html` 校验外部 shell workflow 能读取
+  display view-model，并确认 display status/detail 与 compatibility report 一致；
+- `verify_ini_panel_shell_integration_manifest.mjs` 覆盖：
+  - ready display view-model 完整 shape；
+  - 错误 `summaryVersion` 显示到 `mismatch-fields` row；
+- `verify_ini_panel_ui_shell.mjs` 覆盖 shell view-model 的 display view-model shape；
+- `verify_ini_panel_launch_api_manifest.mjs`、`verify_ini_panel_entry_docs.mjs` 与
+  `docs/panel-entry.md` 同步记录和校验新 helper/API/DOM 节点；
+- 未新增控制按钮；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未新增 JS CNC 语义；
+- 未改变 OPFS/session persistence、LinuxCNC interpreter、tool、parameter、planner 或
+  LinuxCNC-owned runtime semantics。
+
+验证已通过：
+
+```bash
+git diff --check
+wasm-port/tests/ui/node/verify_ini_panel_ui_shell.sh
+wasm-port/tests/ui/node/verify_ini_panel_shell_integration_manifest.sh
+wasm-port/tests/ui/node/verify_ini_panel_launch_api_manifest.sh
+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_ui_shell_node_smoke=ok
+ini_panel_shell_integration_manifest_node_smoke=ok
+ini_panel_launch_api_manifest_node_smoke=ok
+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
+browser_ini_shell_integration_workflow_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/UI workflow 的交界。下一批建议新增一个只读
+`createIniPanelShellSessionHandoffSnapshot()` 或等价 helper，把 integration readiness、handoff
+summary、compatibility report、display view-model 聚合成单次外部 shell snapshot API，减少外部
+shell 多次读取 launch API 的组合风险；仍保持只读，不新增控制按钮，不解析 G-code。
+
+三、2026-06-15 继续执行记录：INI panel shell handoff snapshot API
+
+本轮按“第一原则：加快实质性推进”继续推进 OPFS/session persistence 与 browser/UI workflow
+的交界，新增只读 shell handoff snapshot API，把 integration readiness、handoff summary、
+compatibility report 和 display view-model 聚合成单次外部 shell 读取。
+
+完成内容：
+
+- `ui-shell.js` 新增 `createIniPanelShellSessionHandoffSnapshot()`；
+- snapshot 输出：
+  - `apiName: "ini-panel-shell-session-handoff-snapshot"`；
+  - `snapshotVersion: 1`；
+  - `phase`；
+  - `ready`；
+  - `readiness`；
+  - `summary`；
+  - `compatibilityReport`；
+  - `displayViewModel`；
+- `createIniPanelShellViewModel()` 新增：
+  - `shellSessionHandoffSnapshot`；
+  - `createShellSessionHandoffSnapshot`；
+- `createIniPanelLaunchApiManifest().methods` 新增
+  `getShellSessionHandoffSnapshot`；
+- `launch.html` 的 `window.linuxCncIniPanelLaunchApi` 新增真实 browser 入口
+  `getShellSessionHandoffSnapshot()`；
+- `ini_panel_launch_smoke.html` 校验真实 launch iframe：
+  - snapshot version 为 1；
+  - snapshot `ready === true`；
+  - snapshot readiness 与独立 readiness API 一致；
+  - snapshot summary 与独立 summary API 一致；
+  - snapshot display view-model 与独立 display API 一致；
+- `ini_panel_shell_integration_workflow_smoke.html` 校验外部 shell workflow 能读取 snapshot，
+  并确认 snapshot display status 为 `Ready`；
+- `verify_ini_panel_shell_integration_manifest.mjs` 覆盖：
+  - ready snapshot 完整 shape；
+  - default snapshot 包含 5 个 display rows；
+- `verify_ini_panel_ui_shell.mjs` 覆盖 shell view-model 的 snapshot 聚合关系；
+- `verify_ini_panel_launch_api_manifest.mjs`、`verify_ini_panel_entry_docs.mjs` 与
+  `docs/panel-entry.md` 同步记录和校验新 helper/API；
+- 未新增控制按钮；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未新增 JS CNC 语义；
+- 未改变 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_integration_manifest.sh
+wasm-port/tests/ui/node/verify_ini_panel_launch_api_manifest.sh
+wasm-port/tests/ui/node/verify_ini_panel_ui_shell.sh
+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_shell_integration_manifest_node_smoke=ok
+ini_panel_launch_api_manifest_node_smoke=ok
+ini_panel_ui_shell_node_smoke=ok
+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
+browser_ini_shell_integration_workflow_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
+```
+
+下一步建议：
+
+继续推进 browser/UI workflow。下一批建议在 launch 页面或等价外部 shell view 中增加一个只读
+snapshot consumer helper，把 snapshot 直接压成 launch-side render state，并对 blocked snapshot
+做 focused browser smoke；仍保持只读，不新增控制按钮，不解析 G-code。