按建议，继续完成后续工作

结论：已新增 OPFS session snapshot store，提供通用 JSON 包络、格式校验和保存/读取往返验证；该层只处理 host-side 持久化，不定义 CNC 机床状态语义。

wasm-port/docs/compatibility-validation.md

@@ -69,7 +69,8 @@ with a Node mock of the browser File System Access handles. It covers nested
 directory creation, text save/load, missing file behavior, invalid relative
 paths, unavailable OPFS storage, and the host-side OPFS path model for INI,
 tool table, parameter, G-code, preview-cache, and session-snapshot storage
-targets.
+targets. It also validates the host-side session snapshot JSON envelope and
+round-trip store without defining CNC machine-state semantics.
 
 The browser smoke script serves `wasm-port/` over localhost and runs Chromium
 headless against a test page that imports the JS SDK, loads the INI WASM
@@ -126,7 +127,7 @@ The validation fails if:
 | Harness | Purpose |
 | --- | --- |
 | `tests/wasm/node/verify_ini_wasm.sh` | Validates the browser-facing INI WASM module can be built from vendored LinuxCNC `inifile.cc`, loaded through the JS SDK in Node, and queried through the exported C ABI. |
-| `tests/opfs/node/verify_file_service.sh` | Validates the host-owned OPFS text-file adapter and path model used by the browser INI panel without moving file persistence into the WASM core. |
+| `tests/opfs/node/verify_file_service.sh` | Validates the host-owned OPFS text-file adapter, path model, and session snapshot store used by the browser INI panel without moving file persistence into the WASM core. |
 | `tests/browser/verify_ini_panel_browser.sh` | Validates the INI SDK, WASM module loading, and OPFS text-file round trip in a real browser runtime. |
 | `tests/host/verify_host_smokes.sh` | Runs the current host-side Node, WASM, OPFS, and browser smoke validation with a single INI WASM build. |
 

wasm-port/docs/drift-report.md

@@ -42,7 +42,7 @@ semantic rewrites:
 | Kinematics component lifecycle | Kinematics modules are initialized through LinuxCNC module entry points where native runtime probes exist, while HAL component init/ready/exit, HAL pin allocation, and RTAPI module metadata are handled by standalone shims. |
 | Go math C/C++ linkage | `genserkins` runtime probing compiles vendored `gomath.c` through a narrow C++ wrapper so LinuxCNC `genserfuncs.c` can link to the upstream Go math symbols without editing vendored source. |
 | Switchkins iterative forward | `genhexkins` runtime probing follows LinuxCNC switchkins iterative-forward behavior, including the first-call warmup path before asserting roundtrip convergence. |
-| Browser storage | OPFS remains outside the native core; `runtime/opfs/file-service.js` owns browser text-file persistence and `runtime/opfs/path-model.js` owns host-side storage paths for INI, tool table, parameter, G-code, preview-cache, and session-snapshot content. |
+| Browser storage | OPFS remains outside the native core; `runtime/opfs/file-service.js` owns browser text-file persistence, `runtime/opfs/path-model.js` owns host-side storage paths for INI, tool table, parameter, G-code, preview-cache, and session-snapshot content, and `runtime/opfs/snapshot-store.js` owns generic JSON session snapshot persistence. |
 
 ## Enforced Non-Drift Rules
 
@@ -61,8 +61,8 @@ semantic rewrites:
 - JS SDK validation is currently limited to the INI WASM wrapper around
   vendored LinuxCNC `inifile.cc`.
 - OPFS validation covers a Node mock of the file-service adapter, the
-  host-side path model, and a Chromium localhost round trip for INI text-file
-  persistence.
+  host-side path model, generic session snapshot storage, and a Chromium
+  localhost round trip for INI text-file persistence.
 - Host-side smoke validation is aggregated by
   `tests/host/verify_host_smokes.sh` so Node, WASM, OPFS, and browser checks
   run from one command.

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

@@ -51,7 +51,7 @@ Current validation is intentionally mechanical:
 
 | Dependency | LinuxCNC files that expose it | Standalone treatment |
 | --- | --- | --- |
-| Native file IO | `inifile.cc`, `rs274ngc_pre.cc`, parameter file paths | Allowed in native probes; browser OPFS remains a host-side adapter under `runtime/opfs/`, with path ownership in `runtime/opfs/path-model.js` |
+| Native file IO | `inifile.cc`, `rs274ngc_pre.cc`, parameter file paths | Allowed in native probes; browser OPFS remains a host-side adapter under `runtime/opfs/`, with path ownership in `runtime/opfs/path-model.js` and generic snapshot persistence in `runtime/opfs/snapshot-store.js` |
 | RTAPI | `rtapi_*.h`, TP, posemath, motion headers | Minimal standalone shim in `runtime/core/shims/rtapi.h` |
 | NML transport | `emc.hh`, motion/NML type headers | Transport is not ported; only the status/type edges needed by vendored compute code are exposed through standalone shims and probes |
 | HAL runtime | named parameter lookup, kinematics component lifecycle, and runtime status edges | Standalone HAL adapter under `runtime/core/linuxcnc_wrap/` |
@@ -74,6 +74,8 @@ Current validation is intentionally mechanical:
 - OPFS persistence is connected to the INI panel through the host-side
   `runtime/opfs/file-service.js` adapter. `runtime/opfs/path-model.js` now
   defines paths for INI, tool table, parameter file, G-code program,
-  preview-cache, and session-snapshot targets; semantic loading for tool
-  tables, parameter files, and G-code programs remains future work.
+  preview-cache, and session-snapshot targets. `runtime/opfs/snapshot-store.js`
+  adds a generic JSON session snapshot envelope; semantic loading for tool
+  tables, parameter files, G-code programs, and machine-state restoration
+  remains future work.
 - Native LinuxCNC GUI code remains out of scope for implementation.

wasm-port/runtime/opfs/snapshot-store.js

@@ -0,0 +1,63 @@
+import { loadTextFile, saveTextFile } from "./file-service.js";
+import { sessionSnapshotPath } from "./path-model.js";
+
+export const SESSION_SNAPSHOT_FORMAT = "linuxcnc-wasm-session-snapshot";
+export const SESSION_SNAPSHOT_VERSION = 1;
+
+function assertPlainObject(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a plain object.`);
+  }
+}
+
+export function createSessionSnapshot(sessionId, payload, options = {}) {
+  sessionSnapshotPath(sessionId, options.filename);
+  assertPlainObject(payload, "snapshot payload");
+  if (options.metadata !== undefined) {
+    assertPlainObject(options.metadata, "snapshot metadata");
+  }
+
+  return {
+    format: SESSION_SNAPSHOT_FORMAT,
+    version: SESSION_SNAPSHOT_VERSION,
+    sessionId,
+    createdAt: options.createdAt ?? new Date().toISOString(),
+    metadata: options.metadata ?? {},
+    payload,
+  };
+}
+
+export function validateSessionSnapshot(snapshot, sessionId) {
+  assertPlainObject(snapshot, "session snapshot");
+  if (snapshot.format !== SESSION_SNAPSHOT_FORMAT) {
+    throw new Error(`Unsupported session snapshot format: ${snapshot.format}`);
+  }
+  if (snapshot.version !== SESSION_SNAPSHOT_VERSION) {
+    throw new Error(`Unsupported session snapshot version: ${snapshot.version}`);
+  }
+  if (snapshot.sessionId !== sessionId) {
+    throw new Error(`Session snapshot id mismatch: ${snapshot.sessionId}`);
+  }
+  assertPlainObject(snapshot.metadata, "snapshot metadata");
+  assertPlainObject(snapshot.payload, "snapshot payload");
+  return snapshot;
+}
+
+export async function saveSessionSnapshot(sessionId, payload, options = {}) {
+  const snapshot = createSessionSnapshot(sessionId, payload, options);
+  const path = sessionSnapshotPath(sessionId, options.filename);
+  await saveTextFile(path, `${JSON.stringify(snapshot, null, 2)}\n`, options.storage);
+  return snapshot;
+}
+
+export async function loadSessionSnapshot(sessionId, options = {}) {
+  const path = sessionSnapshotPath(sessionId, options.filename);
+  const text = await loadTextFile(path, options.storage);
+  let snapshot;
+  try {
+    snapshot = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`Invalid session snapshot JSON: ${error.message}`);
+  }
+  return validateSessionSnapshot(snapshot, sessionId);
+}

wasm-port/tests/opfs/node/verify_file_service.mjs

@@ -15,6 +15,12 @@ import {
   sessionSnapshotPath,
   toolTablePath,
 } from "../../../runtime/opfs/path-model.js";
+import {
+  createSessionSnapshot,
+  loadSessionSnapshot,
+  saveSessionSnapshot,
+  validateSessionSnapshot,
+} from "../../../runtime/opfs/snapshot-store.js";
 
 class MockFileHandle {
   constructor(name) {
@@ -86,6 +92,26 @@ assert.deepEqual(defaultMachinePaths("xyzab-tdr"), {
   parameters: "linuxcnc/machines/xyzab-tdr/linuxcnc.var",
 });
 
+const snapshotPayload = {
+  files: {
+    ini: machineIniPath("xyzab-tdr"),
+    toolTable: toolTablePath("xyzab-tdr"),
+  },
+};
+const snapshot = createSessionSnapshot("session-1", snapshotPayload, {
+  createdAt: "2026-06-08T00:00:00.000Z",
+  metadata: { source: "node-smoke" },
+});
+assert.deepEqual(snapshot, {
+  format: "linuxcnc-wasm-session-snapshot",
+  version: 1,
+  sessionId: "session-1",
+  createdAt: "2026-06-08T00:00:00.000Z",
+  metadata: { source: "node-smoke" },
+  payload: snapshotPayload,
+});
+assert.equal(validateSessionSnapshot(snapshot, "session-1"), snapshot);
+
 await saveTextFile(
   "linuxcnc/machines/xyzab.ini",
   "[EMC]\nMACHINE = opfs-smoke\n",
@@ -96,6 +122,13 @@ assert.equal(
   "[EMC]\nMACHINE = opfs-smoke\n",
 );
 
+await saveSessionSnapshot("session-1", snapshotPayload, {
+  storage,
+  createdAt: "2026-06-08T00:00:00.000Z",
+  metadata: { source: "node-smoke" },
+});
+assert.deepEqual(await loadSessionSnapshot("session-1", { storage }), snapshot);
+
 await assert.rejects(
   () => loadTextFile("linuxcnc/machines/missing.ini", storage),
   /missing file/,
@@ -108,6 +141,15 @@ assert.throws(
   () => machineIniPath("../escape"),
   /Invalid machine id/,
 );
+await saveTextFile(sessionSnapshotPath("bad-json"), "{", storage);
+await assert.rejects(
+  () => loadSessionSnapshot("bad-json", { storage }),
+  /Invalid session snapshot JSON/,
+);
+await assert.rejects(
+  () => loadSessionSnapshot("missing-session", { storage }),
+  /missing directory|missing file/,
+);
 await assert.rejects(
   () => getOpfsRoot({}),
   /OPFS is not available/,