上传真实浏览器仿真推进

结论：新增 LinuxCNC WASM 驱动的真实浏览器仿真页面，接入 browser smoke、release gate、SDK 与项目交付文档，并完成当前推进批次的验收记录。
2026-06-16 20:59:21 +08:00
parent 19eabdf06e
commit 24e1fc18b1
39 changed files with 7563 additions and 59 deletions
--- a/wasm-port/docs/panel-entry.md
+++ b/wasm-port/docs/panel-entry.md
@@ -163,6 +163,31 @@ when an outer shell needs to validate a project release readiness artifact JSON
 through the same read-only workflow overview surface. It parses the artifact,
 returns stable validation rows, and does not execute release gates or CNC
 behavior.
+Use `runIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflow()` or
+`linuxCncIniPanelWorkflowOverviewApi.runWorkflowOverviewReleaseReadinessArtifactJsonWorkflow()`
+when the shell already has artifact JSON and needs parse, validation, summary,
+action-plan, and gate execution summary output in one workflow result.
+Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryViewModel()` or
+`linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryViewModel()`
+when the shell needs the artifact's release gate execution summary rows.
+Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryRenderState()`,
+`createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryDomContract()`,
+`createIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryDomReadiness()`,
+`renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryState()`, or
+`mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryState()` when the
+shell needs to render those per-gate rows into caller-owned DOM.
+Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowSummaryViewModel()` or
+`linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewReleaseReadinessArtifactJsonWorkflowSummaryViewModel()`
+when the shell needs stable status text and rows for that JSON workflow.
+Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowActionPlan()` or
+`linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewReleaseReadinessArtifactJsonWorkflowActionPlan()`
+when the shell needs the JSON workflow next-command plan without inspecting
+internal workflow fields.
+Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowDomContract()`,
+`createIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowDomReadiness()`,
+`renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowState()`, or
+`mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactJsonWorkflowState()` when the
+shell needs to render that JSON workflow state into caller-owned DOM.
 Use `loadIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrl()` or
 `linuxCncIniPanelWorkflowOverviewApi.loadWorkflowOverviewReleaseReadinessArtifactUrl()`
 when the shell should fetch the artifact JSON URL, validate it, and optionally
@@ -173,10 +198,30 @@ Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowSumma
 `linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewReleaseReadinessArtifactUrlWorkflowSummaryViewModel()`
 when the shell needs one stable status line and dashboard rows for the whole
 artifact URL fetch/validate/render/mount workflow.
+Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowRenderState()`,
+`createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowDomContract()`,
+`createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowDomReadiness()`,
+`renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowState()`, or
+`mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowState()` when the
+shell needs to render that URL workflow state into caller-owned DOM.
+Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlan()` or
+`linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlan()`
+when the shell needs the ordered next-action/next-command plan for that URL
+workflow without executing release gates.
 Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationSummaryViewModel()` or
 `linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewReleaseReadinessArtifactValidationSummaryViewModel()`
 when the shell needs stable artifact validation status text and dashboard rows
 without interpreting validation flags itself.
+Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlan()` or
+`linuxCncIniPanelWorkflowOverviewApi.getWorkflowOverviewReleaseReadinessArtifactValidationActionPlan()`
+when direct artifact JSON validation needs its own ordered next-command plan
+without executing release gates.
+Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanRenderState()`,
+`createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanDomContract()`,
+`createIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanDomReadiness()`,
+`renderIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanState()`, or
+`mountIniPanelShellWorkflowOverviewReleaseReadinessArtifactValidationActionPlanState()` when the
+shell needs to render that validation action plan into caller-owned DOM.
 Use `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactDisplayViewModel()`,
 `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactRenderState()`,
 `createIniPanelShellWorkflowOverviewReleaseReadinessArtifactDomContract()`,
--- a/wasm-port/docs/project-release-handoff.md
+++ b/wasm-port/docs/project-release-handoff.md
@@ -13,6 +13,8 @@ Use these documents as the current handoff set:
 - `docs/panel-entry.md` for browser/UI entry points and shell handoff helpers.
 - `runtime/sdk/README.md` for stable SDK imports from `runtime/sdk/src/index.js`.
 - `docs/opfs-session-persistence.md` for OPFS/session persistence scope.
+- `docs/real-browser-simulation-priority.md` for the standing first priority:
+  build the real browser CNC simulation page before lower-value metadata work.
 - `docs/sim-configs-coverage-handoff.md` for sim-config inventory status.
 - `docs/host-runtime-boundary-handoff.md` for blocked runtime families.
 - `docs/source-reuse-map.md` and `docs/drift-report.md` for LinuxCNC source
@@ -24,6 +26,26 @@ continuation records are in `../text15.txt`.

 ## Supported current workflows

+## First Priority Constraint
+
+Subsequent work must prioritize a real browser CNC simulation page. The page
+should converge on visible machine/session loading, G-code program state,
+LinuxCNC-backed interpreter execution, machine readiness/status panels, and a
+toolpath/preview area backed by LinuxCNC-produced output or validated runtime
+events. The authoritative constraint is
+`docs/real-browser-simulation-priority.md`.
+Its executable docs gate is
+`verify_real_browser_simulation_priority_docs.sh`, which is included in the
+host smoke and project release gate and ends with
+`real_browser_simulation_priority_docs_node_smoke=ok`.
+The first implementation entry point is `runtime/ui/simulation/index.html`,
+validated by `verify_real_simulation_browser.sh`, which ends with
+`browser_real_simulation_page_smoke=ok`.
+
+This priority does not permit JavaScript-owned CNC semantics. G-code, tool,
+parameter, kinematics, remap, planner, and canonical motion behavior must remain
+owned by vendored LinuxCNC source and existing LinuxCNC-backed WASM boundaries.
+
 - INI panel launch, edit/run page, read-only control page, workflow overview,
  and external shell handoff are exposed from `runtime/ui/ini-panel/`.
 - External shells should use the read-only helpers documented in
@@ -76,15 +98,86 @@ continuation records are in `../text15.txt`.
  that SDK URL workflow into stable dashboard rows and status text.
  `createProjectReleaseReadinessArtifactUrlWorkflowActionPlan()` turns blocked
  URL workflows into ordered input, fetch, and command actions for CI tooling.
+  `createProjectBatchAcceptanceCapabilityMatrix()` classifies per-batch evidence
+  into accepted API/workflow/gate/browser capabilities and rejected entries.
+  `createProjectBatchAcceptanceWorkflow()` records the per-batch acceptance rule
+  that each batch must ship at least one callable API, verifiable workflow,
+  executable gate, or browser capability. Its summary view-model and action-plan
+  helpers provide dashboard rows and the next batch-acceptance gate command.
+  `createProjectBatchAcceptanceChecklist()` combines those results into
+  pass/blocked checklist rows for external release dashboards.
+  `createProjectBatchAcceptanceReport()` packages the matrix, workflow,
+  summary, action plan, and checklist into one stable CI/dashboard object.
+  `createProjectBatchAcceptanceReportValidation()` and
+  `createProjectBatchAcceptanceReportJsonWorkflow()` validate that object from
+  parsed data or JSON text without throwing.
+  `createProjectBatchAcceptanceReportValidationSummaryViewModel()` and
+  `createProjectBatchAcceptanceReportValidationActionPlan()` expose dashboard
+  rows and the next artifact gate command for blocked report validation.
+  `loadProjectBatchAcceptanceReportUrlWorkflow()` fetches hosted batch
+  acceptance report JSON through a caller-provided `fetch` implementation, then
+  runs the same validation workflow without throwing.
+  `createProjectBatchAcceptanceReportUrlWorkflowSummaryViewModel()` and
+  `createProjectBatchAcceptanceReportUrlWorkflowActionPlan()` expose dashboard
+  rows and ordered input/fetch/gate actions for that URL workflow.
+  The executable batch acceptance gate writes
+  `build/project-batch-acceptance.json` with
+  `write_project_batch_acceptance_artifact.mjs` and validates it through
+  `verify_project_batch_acceptance_artifact.sh`, ending with
+  `project_batch_acceptance_artifact_node_smoke=ok`.
+  Workflow overview shells can use
+  `getWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryViewModel()`
+  and
+  `getWorkflowOverviewReleaseReadinessArtifactUrlGateExecutionSummaryViewModel()`
+  to display the embedded release gate execution summary without parsing
+  artifact internals. They can render or mount those per-gate rows through
+  `getWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryRenderState()`,
+  `getWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryDomContract()`,
+  `getWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryDomReadiness()`,
+  `renderWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryState()`, and
+  `mountWorkflowOverviewReleaseReadinessArtifactGateExecutionSummaryState()`, and
+  `getWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlan()` to show
+  the URL workflow next action or command without executing gates. Direct JSON
+  validation callers can use
+  `getWorkflowOverviewReleaseReadinessArtifactValidationActionPlan()` for the
+  artifact-validation next-command plan. They can render or mount that action
+  plan through
+  `getWorkflowOverviewReleaseReadinessArtifactValidationActionPlanRenderState()`,
+  `getWorkflowOverviewReleaseReadinessArtifactValidationActionPlanDomContract()`,
+  `getWorkflowOverviewReleaseReadinessArtifactValidationActionPlanDomReadiness()`,
+  `renderWorkflowOverviewReleaseReadinessArtifactValidationActionPlanState()`, and
+  `mountWorkflowOverviewReleaseReadinessArtifactValidationActionPlanState()`.
  Browser shells can also pass the JSON to
  `linuxCncIniPanelWorkflowOverviewApi.validateWorkflowOverviewReleaseReadinessArtifactJson()`
  through the workflow overview iframe and receive stable validation rows. They
+  can call `runWorkflowOverviewReleaseReadinessArtifactJsonWorkflow()` when they
+  need parse, validation, summary, action-plan, and gate execution summary
+  output in one workflow result, and
+  `getWorkflowOverviewReleaseReadinessArtifactJsonWorkflowSummaryViewModel()`
+  when they need stable dashboard rows for that JSON workflow. The JSON
+  workflow action plan is available through
+  `getWorkflowOverviewReleaseReadinessArtifactJsonWorkflowActionPlan()`. They
+  can render or mount the JSON workflow state into caller-owned DOM through
+  `getWorkflowOverviewReleaseReadinessArtifactJsonWorkflowDomContract()`,
+  `getWorkflowOverviewReleaseReadinessArtifactJsonWorkflowDomReadiness()`,
+  `renderWorkflowOverviewReleaseReadinessArtifactJsonWorkflowState()`, and
+  `mountWorkflowOverviewReleaseReadinessArtifactJsonWorkflowState()`. They
  can also call
  `linuxCncIniPanelWorkflowOverviewApi.loadWorkflowOverviewReleaseReadinessArtifactUrl()`
  to fetch the artifact URL, validate it, and optionally mount the resulting
  read-only render state. That URL workflow includes a validation summary
  view-model and can be summarized with
  `getWorkflowOverviewReleaseReadinessArtifactUrlWorkflowSummaryViewModel()`.
+  The same workflow can expose the ordered next-action plan through
+  `getWorkflowOverviewReleaseReadinessArtifactUrlWorkflowActionPlan()`. Shells
+  can render or mount the URL workflow state through
+  `getWorkflowOverviewReleaseReadinessArtifactUrlWorkflowRenderState()`,
+  `getWorkflowOverviewReleaseReadinessArtifactUrlWorkflowDomContract()`,
+  `getWorkflowOverviewReleaseReadinessArtifactUrlWorkflowDomReadiness()`,
+  `renderWorkflowOverviewReleaseReadinessArtifactUrlWorkflowState()`, and
+  `mountWorkflowOverviewReleaseReadinessArtifactUrlWorkflowState()`.
+  Direct artifact JSON validation can expose its own next-command plan through
+  `getWorkflowOverviewReleaseReadinessArtifactValidationActionPlan()`.
  When the outer shell needs DOM output, the workflow
  overview iframe also exposes
  display, render-state, DOM readiness, renderer, and mount helpers for the
@@ -126,6 +219,7 @@ SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_opfs_session_workflow_browser.sh
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_release_artifact_url_workflow_browser.sh
+wasm-port/tests/sdk/node/verify_project_batch_acceptance_workflow.sh
 wasm-port/tests/ui/node/verify_ui_node_smokes.sh
 wasm-port/tests/sdk/node/verify_project_release_artifact_url_workflow.sh
 wasm-port/tests/host/verify_host_smokes.sh
@@ -166,6 +260,7 @@ opfs_session_docs_node_smoke=ok
 sim_configs_coverage_docs_node_smoke=ok
 host_runtime_boundary_docs_node_smoke=ok
 sdk_surface_node_smoke=ok
+project_batch_acceptance_workflow_node_smoke=ok
 project_release_artifact_url_workflow_node_smoke=ok
 ```

--- a/wasm-port/docs/real-browser-simulation-priority.md
+++ b/wasm-port/docs/real-browser-simulation-priority.md
@@ -0,0 +1,82 @@
+# Real Browser Simulation Priority
+
+This document is a standing project constraint for all work after 2026-06-16.
+
+## Primary Objective
+
+The first priority is to deliver a real browser CNC simulation page, not more
+project metadata or dashboard-only helpers. Future batches should prefer
+visible, interactive browser capability that moves the product toward an
+operator-usable CNC simulation surface.
+
+The target page must become a real CNC simulation page with:
+
+- a machine/session loader backed by the existing OPFS/session workflow;
+- a G-code program view backed by persisted or staged program text;
+- LinuxCNC-backed interpreter execution through the existing WASM SDK;
+- machine state panels for run status, active program, machine files, and
+  missing readiness;
+- a toolpath/preview area driven by LinuxCNC-produced interpreter/canonical
+  output or existing validated runtime events, not JavaScript-owned CNC
+  semantics;
+- browser smoke coverage that proves the page loads, renders nonempty runtime
+  state, and can run a representative LinuxCNC-backed program flow.
+
+The first implementation entry point is:
+
+```text
+runtime/ui/simulation/index.html
+```
+
+Its browser gate is:
+
+```bash
+wasm-port/tests/browser/verify_real_simulation_browser.sh
+```
+
+## Batch Priority
+
+Unless a user explicitly changes priority, choose work in this order:
+
+1. Real UI/browser simulation page capability.
+2. Browser workflow smoke for that simulation capability.
+3. UI APIs needed by the simulation page.
+4. OPFS/session integration needed by the simulation page.
+5. SDK/API helpers only when they directly unblock the simulation page.
+6. Documentation or release metadata only when it creates an executable gate or
+   protects the simulation-page direction.
+
+Every implementation batch still must produce at least one callable API,
+verifiable workflow, executable gate, or real UI/browser capability.
+
+## Boundary Rules
+
+The browser simulation page must not implement CNC semantics in JavaScript.
+G-code interpretation, canonical motion behavior, tool semantics, parameter
+semantics, kinematics, remap behavior, and planner behavior must remain owned by
+vendored LinuxCNC source and existing LinuxCNC-backed WASM C ABI boundaries.
+
+JavaScript/browser code may own:
+
+- layout and interaction state;
+- OPFS/session persistence;
+- file staging into the Emscripten filesystem;
+- calls into the SDK/WASM boundary;
+- rendering LinuxCNC-produced output, canonical events, and validated runtime
+  summaries;
+- non-CNC UI state such as selected file, active tab, viewport mode, and
+  validation messages.
+
+## Required Evidence
+
+The priority is enforced by:
+
+```bash
+wasm-port/tests/docs/node/verify_real_browser_simulation_priority_docs.sh
+wasm-port/tests/host/verify_host_smokes.sh
+wasm-port/tests/host/verify_project_release_gate.sh
+```
+
+The docs gate must verify that this priority document, the release handoff, the
+README, and `PROJECT_COMPLETION_TRACKER.md` all point future work toward a real
+browser CNC simulation page while preserving the LinuxCNC semantic boundary.