From 1bfb7426d4925090b5b8e93aa401f68d5231dcf7 Mon Sep 17 00:00:00 2001
From: cnc <cnc@localhost>
Date: Thu, 4 Jun 2026 16:45:01 +0800
Subject: [PATCH] =?UTF-8?q?=E5=8F=82=E8=80=83=E6=89=80=E6=9C=89=E5=88=86?=
 =?UTF-8?q?=E7=BB=84=EF=BC=8C=E5=AE=8C=E6=88=90=E5=B0=BD=E9=87=8F=E5=A4=9A?=
 =?UTF-8?q?=E7=9A=84=E5=86=85=E5=AE=B9=E3=80=82=E7=A6=81=E6=AD=A2=E9=A1=BA?=
 =?UTF-8?q?=E6=89=8B=E6=89=A9=E5=8A=9F=E8=83=BD=20smoke=EF=BC=9A=E9=94=81?=
 =?UTF-8?q?=E5=AE=9A=E6=B5=8F=E8=A7=88=E5=99=A8=E5=BA=94=E7=94=A8=E6=BA=90?=
 =?UTF-8?q?=E7=A0=81=E6=98=A0=E5=B0=84=E7=BB=93=E8=AE=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 check-linuxcnc-browser-app-source-map.sh | 102 +++++++++++++++++++++++
 docs/linuxcnc-browser-app-source-map.md  |  50 +++++++++++
 test-all-native.sh                       |   6 ++
 test-linuxcnc-source-link.sh             |   1 +
 test-native.sh                           |   1 +
 5 files changed, 160 insertions(+)
 create mode 100755 check-linuxcnc-browser-app-source-map.sh
 create mode 100644 docs/linuxcnc-browser-app-source-map.md

diff --git a/check-linuxcnc-browser-app-source-map.sh b/check-linuxcnc-browser-app-source-map.sh
new file mode 100755
index 0000000..bb54b39
--- /dev/null
+++ b/check-linuxcnc-browser-app-source-map.sh
@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+# LinuxCNC source basis: this guard ties the browser app entry point to
+# LinuxCNC RS274 parameter-file defaults, rs274ngc_pre.cc restore/save/read
+# file semantics, and the existing OPFS-backed wasm-core bridge. It validates
+# app integration policy only; it does not add CNC behavior or expand smoke
+# parsing.
+linuxcnc_root=${LINUXCNC_ROOT:-../linuxcnc}
+linuxcnc_root=$(cd "$linuxcnc_root" && pwd)
+
+grep -F '#define RS274NGC_PARAMETER_FILE_NAME_DEFAULT "rs274ngc.var"' \
+    "$linuxcnc_root/src/emc/rs274ngc/interp_internal.hh" >/dev/null
+grep -F '#define RS274NGC_PARAMETER_FILE_BACKUP_SUFFIX ".bak"' \
+    "$linuxcnc_root/src/emc/rs274ngc/interp_internal.hh" >/dev/null
+grep -F 'int Interp::restore_parameters(const char *filename)' \
+    "$linuxcnc_root/src/emc/rs274ngc/rs274ngc_pre.cc" >/dev/null
+grep -F 'int Interp::save_parameters(const char *filename,' \
+    "$linuxcnc_root/src/emc/rs274ngc/rs274ngc_pre.cc" >/dev/null
+grep -F 'std::string tempfile = std::string(filename) + ".new";' \
+    "$linuxcnc_root/src/emc/rs274ngc/rs274ngc_pre.cc" >/dev/null
+grep -F '+ RS274NGC_PARAMETER_FILE_BACKUP_SUFFIX;' \
+    "$linuxcnc_root/src/emc/rs274ngc/rs274ngc_pre.cc" >/dev/null
+grep -F 'read_text(command, _setup.file_pointer, _setup.linetext,' \
+    "$linuxcnc_root/src/emc/rs274ngc/rs274ngc_pre.cc" >/dev/null
+
+grep -F 'LinuxCNC browser app source map' docs/linuxcnc-browser-app-source-map.md >/dev/null
+grep -F 'must not add CNC behavior' docs/linuxcnc-browser-app-source-map.md >/dev/null
+grep -F 'must not expand the temporary smoke parser' docs/linuxcnc-browser-app-source-map.md >/dev/null
+grep -F '`RS274NGC_PARAMETER_FILE_NAME_DEFAULT` as `rs274ngc.var`' \
+    docs/linuxcnc-browser-app-source-map.md >/dev/null
+grep -F '`parseFileWithParameterFile(programPath, parameterPath, "linuxcnc", ...)`' \
+    docs/linuxcnc-browser-app-source-map.md >/dev/null
+
+grep -F '<script type="module" src="/src/app.js"></script>' web/index.html >/dev/null
+grep -F '<option value="linuxcnc-rs274">LINUXCNC</option>' web/index.html >/dev/null
+if [[ "$(grep -Fc '<option value=' web/index.html)" -ne 1 ]]; then
+    echo "browser app backend selector must expose only the LinuxCNC RS274 backend" >&2
+    exit 1
+fi
+
+grep -F 'import { createWasmSimulator } from "./wasm-core.js";' web/src/app.js >/dev/null
+grep -F 'const programPath = "programs/current.ngc";' web/src/app.js >/dev/null
+grep -F 'const linuxCncParameterFileName = "rs274ngc.var";' web/src/app.js >/dev/null
+grep -F 'const parameterPath = `parameters/${linuxCncParameterFileName}`;' web/src/app.js >/dev/null
+grep -F 'const linuxCncBackend = "linuxcnc-rs274";' web/src/app.js >/dev/null
+grep -F 'const opfsOptions = { required: true, mountPoint: "/cnc", workspacePath: "cnc-simulator" };' \
+    web/src/app.js >/dev/null
+grep -F 'simulatorPromise = createWasmSimulator({' web/src/app.js >/dev/null
+grep -F 'opfs: opfsOptions,' web/src/app.js >/dev/null
+grep -F 'OPFS workspace is required for browser program parsing' web/src/app.js >/dev/null
+grep -F 'await simulator.fs.opfs.writeFile(programPath, elements.input.value);' web/src/app.js >/dev/null
+grep -F 'const events = await simulator.parseFileWithParameterFile(programPath, parameterPath, "linuxcnc", parseOptions);' \
+    web/src/app.js >/dev/null
+grep -F 'elements.backendSelect.value = linuxCncBackend;' web/src/app.js >/dev/null
+grep -F 'globalThis.__cncSimulatorForTest = simulatorPromise;' web/src/app.js >/dev/null
+
+grep -F 'app frame did not persist current program into OPFS' \
+    web/test-browser-wasm-smoke-app-sections.js >/dev/null
+grep -F 'app frame did not persist LinuxCNC parameter state into OPFS' \
+    web/test-browser-wasm-smoke-app-sections.js >/dev/null
+grep -F 'app frame did not persist LinuxCNC parameter backup into OPFS' \
+    web/test-browser-wasm-smoke-app-sections.js >/dev/null
+grep -F 'OPFS PROGRAM RESTORED' web/test-browser-wasm-smoke-app-sections.js >/dev/null
+grep -F 'app frame did not reload LinuxCNC parameter state from OPFS after reload' \
+    web/test-browser-wasm-smoke-app-sections.js >/dev/null
+
+if grep -R -n -E 'localStorage|sessionStorage|indexedDB|showOpenFilePicker|showSaveFilePicker|showDirectoryPicker|webkitRequestFileSystem|FileReader' web/src; then
+    echo "browser app/wasm code must not add filesystem persistence outside OPFS" >&2
+    exit 1
+fi
+
+python3 - <<'PY'
+from pathlib import Path
+
+source_map = Path("docs/linuxcnc-browser-app-source-map.md").read_text(encoding="utf-8")
+for entry in [
+    "web/index.html",
+    "web/src/app.js",
+    "web/test-browser-wasm-smoke-app-sections.js",
+]:
+    if f"| `{entry}` |" not in source_map:
+        raise SystemExit(f"docs/linuxcnc-browser-app-source-map.md missing app entry: {entry}")
+
+for phrase in [
+    "must not add CNC behavior",
+    "must not expand the temporary smoke parser",
+    "existing `createWasmSimulator()` OPFS API",
+    "programs/current.ngc",
+    "parameters/rs274ngc.var",
+    "visible backend selector must stay limited",
+    "./check-linuxcnc-browser-app-source-map.sh",
+]:
+    if phrase not in source_map:
+        raise SystemExit(f"docs/linuxcnc-browser-app-source-map.md missing boundary phrase: {phrase}")
+
+app = Path("web/src/app.js").read_text(encoding="utf-8")
+if "parse(" in app.replace("parseProgram", ""):
+    raise SystemExit("browser app should route program execution through parseFileWithParameterFile, not direct parse")
+PY
diff --git a/docs/linuxcnc-browser-app-source-map.md b/docs/linuxcnc-browser-app-source-map.md
new file mode 100644
index 0000000..e827488
--- /dev/null
+++ b/docs/linuxcnc-browser-app-source-map.md
@@ -0,0 +1,50 @@
+# LinuxCNC browser app source map
+
+This map records the source basis and boundaries for the browser application
+entry point. It is an app/bridge guard only; it must not add CNC behavior and
+must not expand the temporary smoke parser.
+
+## LinuxCNC Source Basis
+
+- `src/emc/rs274ngc/interp_internal.hh` defines
+  `RS274NGC_PARAMETER_FILE_NAME_DEFAULT` as `rs274ngc.var`.
+- `src/emc/rs274ngc/interp_internal.hh` defines
+  `RS274NGC_PARAMETER_FILE_BACKUP_SUFFIX` as `.bak`.
+- `src/emc/rs274ngc/rs274ngc_pre.cc` restores parameter files through
+  `Interp::restore_parameters()`.
+- `src/emc/rs274ngc/rs274ngc_pre.cc` saves parameter files through
+  `Interp::save_parameters()`, including `filename + ".new"` and
+  `filename + ".bak"` behavior.
+- `src/emc/rs274ngc/rs274ngc_pre.cc` reads program blocks through `read_text()`
+  after the browser bridge mirrors the OPFS program into the WASM filesystem.
+
+## App Coverage
+
+| Entry | Boundary |
+| --- | --- |
+| `web/index.html` | Loads the browser app module and exposes only the LinuxCNC backend selector. |
+| `web/src/app.js` | Creates a required OPFS-backed simulator workspace and parses browser programs with a LinuxCNC parameter file. |
+| `web/test-browser-wasm-smoke-app-sections.js` | Verifies app-level OPFS program save, parameter save, parameter backup, and reload behavior. |
+
+## Boundaries
+
+- The app must use the existing `createWasmSimulator()` OPFS API; it must not
+  add browser filesystem persistence outside OPFS.
+- The app must persist the current program at `programs/current.ngc`.
+- The app must persist LinuxCNC parameter state at `parameters/rs274ngc.var`.
+- The app must require OPFS for browser program parsing and call
+  `parseFileWithParameterFile(programPath, parameterPath, "linuxcnc", ...)`.
+- The visible backend selector must stay limited to the LinuxCNC RS274 backend.
+
+## Checks
+
+Run:
+
+```bash
+./check-linuxcnc-browser-app-source-map.sh
+./test-native.sh
+./test-linuxcnc-source-link.sh
+```
+
+`check-linuxcnc-browser-app-source-map.sh` keeps this document, LinuxCNC source
+anchors, app OPFS paths, app parse routing, and app smoke coverage synchronized.
diff --git a/test-all-native.sh b/test-all-native.sh
index 581e2e9..9eec114 100755
--- a/test-all-native.sh
+++ b/test-all-native.sh
@@ -156,6 +156,9 @@ grep -F './check-linuxcnc-wasm-smoke-source-map.sh' test-linuxcnc-source-link.sh
 grep -F 'LinuxCNC source basis: this guard ties native/source-link/WASM build entry' check-linuxcnc-build-source-map.sh >/dev/null
 grep -F './check-linuxcnc-build-source-map.sh' test-native.sh >/dev/null
 grep -F './check-linuxcnc-build-source-map.sh' test-linuxcnc-source-link.sh >/dev/null
+grep -F 'LinuxCNC source basis: this guard ties the browser app entry point' check-linuxcnc-browser-app-source-map.sh >/dev/null
+grep -F './check-linuxcnc-browser-app-source-map.sh' test-native.sh >/dev/null
+grep -F './check-linuxcnc-browser-app-source-map.sh' test-linuxcnc-source-link.sh >/dev/null
 grep -F 'LinuxCNC source basis: this guard ties the documented WASM blocker map' check-linuxcnc-wasm-blockers-source-map.sh >/dev/null
 grep -F 'LinuxCNC source basis: this guard ties the documented wasm-safe shim map' check-linuxcnc-wasm-shims-source-map.sh >/dev/null
 grep -F 'LinuxCNC source basis: the cached input checker keys check-linuxcnc-inputs.sh' check-linuxcnc-inputs-cached.sh >/dev/null
@@ -242,6 +245,9 @@ grep -F 'Generated switchkins config smoke cases must continue to come from' doc
 grep -F 'LinuxCNC build source map' docs/linuxcnc-build-source-map.md >/dev/null
 grep -F 'Default WASM manifest partition must remain 26 wasm-safe `core` sources' docs/linuxcnc-build-source-map.md >/dev/null
 grep -F '`build-wasm.sh` must configure with `CNC_SIM_ENABLE_SMOKE_BACKEND=OFF`' docs/linuxcnc-build-source-map.md >/dev/null
+grep -F 'LinuxCNC browser app source map' docs/linuxcnc-browser-app-source-map.md >/dev/null
+grep -F 'The app must persist the current program at `programs/current.ngc`.' docs/linuxcnc-browser-app-source-map.md >/dev/null
+grep -F 'The visible backend selector must stay limited to the LinuxCNC RS274 backend.' docs/linuxcnc-browser-app-source-map.md >/dev/null
 grep -F 'check-linuxcnc-switchkins-remap-table-cached.sh --cache-dir "$preflight_cache_dir" linuxcnc-kinematics-source-files.txt' test-native.sh >/dev/null
 grep -F 'check-linuxcnc-switchkins-remap-table-cached.sh --cache-dir "$preflight_cache_dir" linuxcnc-kinematics-source-files.txt' test-linuxcnc-source-link.sh >/dev/null
 grep -F 'check-linuxcnc-switchkins-remap-table-cached.sh --cache-dir "$preflight_cache_dir" linuxcnc-kinematics-source-files.txt' build-wasm.sh >/dev/null
diff --git a/test-linuxcnc-source-link.sh b/test-linuxcnc-source-link.sh
index c350022..2708d78 100755
--- a/test-linuxcnc-source-link.sh
+++ b/test-linuxcnc-source-link.sh
@@ -39,6 +39,7 @@ LINUXCNC_ROOT="$linuxcnc_root" ./check-linuxcnc-inputs-cached.sh --cache-dir "$p
 ./check-linuxcnc-switchkins-remap-source-map.sh
 ./check-linuxcnc-wasm-smoke-source-map.sh
 ./check-linuxcnc-build-source-map.sh
+./check-linuxcnc-browser-app-source-map.sh
 LINUXCNC_ROOT="$linuxcnc_root" ./check-linuxcnc-switchkins-remap-table-cached.sh --cache-dir "$preflight_cache_dir" linuxcnc-kinematics-source-files.txt
 # The LinuxCNC source-linked dump path is not concurrency-safe under parallel execution.
 exec 9>"${TMPDIR:-/tmp}/cnc_sim_rs274_source_link.lock"
diff --git a/test-native.sh b/test-native.sh
index d0db353..e8ea84f 100755
--- a/test-native.sh
+++ b/test-native.sh
@@ -40,6 +40,7 @@ preflight_cache_dir="$build_dir/preflight-cache"
 ./check-linuxcnc-switchkins-remap-source-map.sh
 ./check-linuxcnc-wasm-smoke-source-map.sh
 ./check-linuxcnc-build-source-map.sh
+./check-linuxcnc-browser-app-source-map.sh
 ./check-linuxcnc-switchkins-remap-table-cached.sh --cache-dir "$preflight_cache_dir" linuxcnc-kinematics-source-files.txt
 grep -F 'tooldata:src/emc/tooldata/tooldata_nml.cc:NML tool table backend selected by LinuxCNC TOOL_NML_FLAG' linuxcnc-rs274-source-files.txt >/dev/null
 grep -F 'tooldata:src/emc/tooldata/tool_mmap_read.cc:LinuxCNC tooldata mmap reader utility source from tooldata Submakefile' linuxcnc-rs274-source-files.txt >/dev/null