补充 project release handoff 文档

wasm-port/README.md

@@ -2,6 +2,41 @@
 
 This directory is the standalone workspace for the WASM-based simulation port.
 
+## Current Release Handoff
+
+Start from `docs/project-release-handoff.md` for the current project-level
+handoff. It links the browser/UI workflow surface, SDK surface,
+OPFS/session persistence scope, sim-config coverage baseline, blocked
+host/runtime families, source reuse rules, drift rules, and acceptance tracker.
+
+The minimum release validation commands for the current scope are:
+
+```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
+```
+
+Expected handoff smoke outputs include:
+
+```text
+project_release_handoff_docs_node_smoke=ok
+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
+host_wasm_opfs_browser_smokes=ok
+```
+
+Browser/UI entry points are documented in `docs/panel-entry.md`. Stable SDK
+imports are documented in `runtime/sdk/README.md` and should come from
+`runtime/sdk/src/index.js`.
+
 Rules:
 
 1. `linuxcnc/` is treated as the upstream source tree.
@@ -136,6 +171,8 @@ Sim-config inventory coverage and release-gate handoff is documented in
 `docs/sim-configs-coverage-handoff.md`.
 Host/runtime boundary release-gate handoff is documented in
 `docs/host-runtime-boundary-handoff.md`.
+Project-level release acceptance and next-maintainer handoff is documented in
+`docs/project-release-handoff.md`.
 
 The presence of this directory means the port is managed independently of the
 native LinuxCNC tree even though LinuxCNC remains the semantic source of truth.

wasm-port/docs/drift-report.md

@@ -6,6 +6,10 @@ As of the current upstream baseline, no byte-level drift is allowed between
 files listed in `tools/source-manifest.txt` and the matching files under
 `../linuxcnc/`.
 
+The project-level release handoff in `docs/project-release-handoff.md` includes
+this drift report in the final acceptance path alongside source reuse,
+OPFS/session, sim-config coverage, host/runtime boundary, SDK, and UI docs.
+
 The enforced upstream baseline is:
 
 ```text

wasm-port/docs/panel-entry.md

@@ -2,6 +2,12 @@
 
 This page is the short entry map for the INI panel UI shell.
 
+For the project-level acceptance path that references this UI surface, start
+with `docs/project-release-handoff.md`. Stable SDK imports for external callers
+are documented in `runtime/sdk/README.md` and should come from
+`runtime/sdk/src/index.js`. The workflow overview embedding helpers below are
+the read-only external-shell path for embedding and mounting overview state.
+
 ## Shell Module
 
 Use the shell-facing module when an outer UI needs entry links or a read-only
@@ -428,3 +434,7 @@ read-only readiness snapshot for the embedded panel API and first control view.
 The entry shell only links pages and renders already-observed panel state. It
 does not parse G-code, infer canonical events, or implement LinuxCNC-owned
 tool, parameter, planner, or kinematics behavior.
+
+Release validation for this surface is covered by `verify_ui_node_smokes.sh`,
+`verify_ini_panel_browser.sh`, and the project handoff docs smoke
+`verify_project_release_handoff_docs.sh`.

wasm-port/docs/project-release-handoff.md

@@ -0,0 +1,124 @@
+# Project release handoff
+
+This is the short project-level handoff for the current LinuxCNC WASM/browser
+port scope. It points a new maintainer to the supported workflow surfaces, the
+required release gates, and the boundaries that must remain blocked until real
+LinuxCNC-owned runtime proof exists.
+
+## Start here
+
+Use these documents as the current handoff set:
+
+- `README.md` for the workspace layout and release validation commands.
+- `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/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
+  reuse and non-drift rules.
+- `../PROJECT_COMPLETION_TRACKER.md` for project-level acceptance tracking.
+
+Old turn logs `text1.txt` through `text13.txt` are historical context. Current
+continuation records are in `../text14.txt`.
+
+## Supported current workflows
+
+- 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
+  `docs/panel-entry.md`, including workflow overview embedding mount DOM
+  contract/readiness/renderer/wrapper helpers.
+- SDK callers should import stable helpers from `runtime/sdk/src/index.js`.
+- OPFS/session persistence is host-side storage glue. Parameter and tool-table
+  behavior still comes from the LinuxCNC-backed interpreter SDK calls.
+- Sim-config inventory promotion remains evidence-driven and must keep
+  `unexpected_fail=0`.
+
+## Required release gates
+
+Run these before claiming the current scope is release-ready:
+
+```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
+```
+
+The host aggregate gate includes SDK, OPFS, docs, UI Node, WASM Node, and
+browser smoke coverage. A passing aggregate ends with:
+
+```text
+host_wasm_opfs_browser_smokes=ok
+```
+
+## Expected baseline outputs
+
+The current sim-config inventory release baseline is:
+
+```text
+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
+```
+
+The expected docs and SDK smoke outputs include:
+
+```text
+project_release_handoff_docs_node_smoke=ok
+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
+```
+
+The expected browser INI panel smoke outputs include:
+
+```text
+browser_ini_opfs_smoke=ok
+browser_ini_control_page_smoke=ok
+browser_ini_launch_smoke=ok
+browser_ini_workflow_overview_smoke=ok
+browser_ini_shell_integration_workflow_smoke=ok
+```
+
+## Blocked runtime families
+
+These runtime families remain blocked:
+
+- `L4-USER-M-PROCESS`
+- `L4-TOOL-DB`
+- `L4-PYTHON-REMAP`
+
+Do not promote them from skipped/blocked state without LinuxCNC-owned native
+runtime proof followed by Node/WASM and browser/host validation. The opt-in
+runtime probes are documented in `docs/host-runtime-boundary-handoff.md`; they
+must not be run on hosts that do not provide the required LinuxCNC runtime.
+
+## Acceptance checklist
+
+- `git diff --check` passes.
+- Vendor sync and standalone CNC semantic guards pass.
+- Interpreter WASM Node smoke passes.
+- Sim-config inventory has `unexpected_fail=0`.
+- UI Node smoke passes.
+- Browser INI panel smoke passes.
+- Host aggregate smoke passes.
+- SDK exports match `runtime/sdk/README.md`.
+- `docs/panel-entry.md` documents the external shell workflow surface.
+- OPFS/session, sim-config coverage, host/runtime boundary, source reuse, and
+  drift docs all point to the current validation gates.
+- Blocked runtime families remain documented and are not falsely promoted.
+
+## Next maintainer rule
+
+Add new CNC behavior only by reusing vendored LinuxCNC source or a documented
+runtime-edge adapter. JavaScript may stage files, mount UI state, manage OPFS,
+load WASM modules, and call C ABI functions; it must not implement G-code,
+tool, parameter, planner, kinematics, remap, or canonical motion semantics.

wasm-port/docs/source-reuse-map.md

@@ -29,6 +29,11 @@ Current validation is intentionally mechanical:
   documented Python/remap runtime-edge stubs in
   `runtime/core/linuxcnc_wrap/linuxcnc_interp_edge_stubs.cpp`.
 
+The project-level release handoff in `docs/project-release-handoff.md` links
+this source reuse map to the README, panel entry documentation, SDK surface,
+OPFS/session release gate, sim-config coverage gate, host/runtime blocked
+families, and drift report.
+
 ## Reuse Matrix
 
 | Capability | LinuxCNC source files | Port classification | Standalone boundary | Current validation |

wasm-port/tests/docs/node/verify_project_release_handoff_docs.mjs

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "../../..");
+
+function literalRegExp(text) {
+  return new RegExp(text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+}
+
+const handoffText = readFileSync(resolve(root, "docs/project-release-handoff.md"), "utf8");
+const readmeText = readFileSync(resolve(root, "README.md"), "utf8");
+const panelEntryText = readFileSync(resolve(root, "docs/panel-entry.md"), "utf8");
+const sdkReadmeText = readFileSync(resolve(root, "runtime/sdk/README.md"), "utf8");
+const sourceReuseText = readFileSync(resolve(root, "docs/source-reuse-map.md"), "utf8");
+const driftText = readFileSync(resolve(root, "docs/drift-report.md"), "utf8");
+const hostSmokeText = readFileSync(resolve(root, "tests/host/verify_host_smokes.sh"), "utf8");
+const trackerText = readFileSync(resolve(root, "../PROJECT_COMPLETION_TRACKER.md"), "utf8");
+
+for (const phrase of [
+  "Project release handoff",
+  "docs/panel-entry.md",
+  "runtime/sdk/README.md",
+  "docs/opfs-session-persistence.md",
+  "docs/sim-configs-coverage-handoff.md",
+  "docs/host-runtime-boundary-handoff.md",
+  "docs/source-reuse-map.md",
+  "docs/drift-report.md",
+  "PROJECT_COMPLETION_TRACKER.md",
+  "runtime/sdk/src/index.js",
+  "workflow overview embedding mount DOM",
+  "verify_no_standalone_cnc_semantics.sh",
+  "verify_host_smokes.sh",
+  "host_wasm_opfs_browser_smokes=ok",
+  "sim_configs_wasm_node_inventory_unexpected_fail=0",
+  "browser_ini_shell_integration_workflow_smoke=ok",
+  "project_release_handoff_docs_node_smoke=ok",
+  "L4-USER-M-PROCESS",
+  "L4-TOOL-DB",
+  "L4-PYTHON-REMAP",
+]) {
+  assert.match(handoffText, literalRegExp(phrase));
+}
+
+for (const phrase of [
+  "docs/project-release-handoff.md",
+  "project_release_handoff_docs_node_smoke=ok",
+]) {
+  assert.match(readmeText, literalRegExp(phrase));
+  assert.match(hostSmokeText, literalRegExp("verify_project_release_handoff_docs.sh"));
+}
+
+for (const phrase of [
+  "docs/project-release-handoff.md",
+  "runtime/sdk/src/index.js",
+  "workflow overview embedding",
+]) {
+  assert.match(panelEntryText, literalRegExp(phrase));
+}
+
+for (const phrase of [
+  "OPFS/session persistence exports",
+  "INI panel shell handoff exports",
+]) {
+  assert.match(sdkReadmeText, literalRegExp(phrase));
+}
+
+assert.match(sourceReuseText, literalRegExp("docs/project-release-handoff.md"));
+assert.match(driftText, literalRegExp("docs/project-release-handoff.md"));
+assert.match(trackerText, /Documentation\/release gate/);
+assert.match(trackerText, /Final Acceptance Checklist/);
+
+console.log("project_release_handoff_docs_node_smoke=ok");

wasm-port/tests/docs/node/verify_project_release_handoff_docs.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+node "$ROOT_DIR/tests/docs/node/verify_project_release_handoff_docs.mjs"

wasm-port/tests/host/verify_host_smokes.sh

@@ -17,6 +17,7 @@ SKIP_TP_BUILD=1 "$ROOT_DIR/tests/wasm/node/verify_tp_wasm.sh"
 "$ROOT_DIR/tests/docs/node/verify_opfs_session_docs.sh"
 "$ROOT_DIR/tests/docs/node/verify_sim_configs_coverage_docs.sh"
 "$ROOT_DIR/tests/docs/node/verify_host_runtime_boundary_docs.sh"
+"$ROOT_DIR/tests/docs/node/verify_project_release_handoff_docs.sh"
 "$ROOT_DIR/tests/ui/node/verify_ui_node_smokes.sh"
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_ini_panel_browser.sh"
 SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_interp_browser.sh"