wasm-simulator/docs/linuxcnc-opfs-source-map.md

LinuxCNC OPFS source map

This map records the source basis for browser-side LinuxCNC parameter-file persistence. It is a policy and bridge map only; it must not add independent filesystem behavior or 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 implements Interp::restore_parameters() for parameter-file reads.
• src/emc/rs274ngc/rs274ngc_pre.cc implements Interp::save_parameters() for filename + ".new", backup, and replacement writes.
• src/emc/rs274ngc/rs274ngc_pre.cc unlinks filename + ".bak", links the previous parameter file to that backup path, then renames filename + ".new" over the configured parameter file.

OPFS Coverage

Entry	Boundary
web/src/wasm-core.js	Keeps LinuxCNC parameter restore/save bridge files under the OPFS workspace and cleans WASM scratch files.
web/src/wasm-core.d.ts	Exposes only the OPFS-backed workspace, directory, parameter-file, and mount/workspace option types used by the bridge.
web/src/app.js	Persists browser programs at programs/current.ngc and LinuxCNC parameters at parameters/rs274ngc.var.
web/test-browser-wasm-smoke-opfs-basic-sections.js	Verifies OPFS program file reads through LinuxCNC read_text() and rejects unsafe paths.
web/test-browser-wasm-smoke-opfs-parameter-sections.js	Verifies OPFS parameter restore, save, .new, .bak, failure, and stale-state semantics.
web/test-browser-wasm-smoke-opfs-workspace-sections.js	Aggregates OPFS basic, parameter, mirror, and directory checks under browser OPFS availability.
web/test-browser-wasm-smoke-opfs-mirror-sections.js	Verifies OPFS/WASM mirror persistence used by source-backed file parsing and parameter movement.
web/test-browser-wasm-smoke-opfs-directory-sections.js	Verifies OPFS directory persistence and WASM mirror refresh without polluting mirrors during metadata queries.
web/test-browser-wasm-smoke-opfs-policy-sections.js	Verifies OPFS workspace and mount policy, including the browser rule that OPFS cannot be disabled.
web/test-browser-wasm-smoke-app-sections.js	Verifies app-level OPFS program, parameter, backup, and reload behavior.

Browser Bridge Boundary

• web/src/wasm-core.js must keep LinuxCNC parameter persistence routed through an OPFS workspace.
• Browser contexts with OPFS support must not disable OPFS.
• OPFS workspace paths must remain relative paths inside the CNC workspace, and OPFS mount points must remain absolute paths inside the Emscripten filesystem.
• Browser app and wasm bridge code must not use Local Storage, IndexedDB, File Picker, Directory Picker, WebKit filesystem, or FileReader persistence paths for CNC programs, LinuxCNC parameter files, or mirrored workspace files.
• web/src/app.js must parse browser programs through parseFileWithParameterFile() so the program file and LinuxCNC parameter state both live under OPFS.
• test-native.sh, test-linuxcnc-source-link.sh, and build-wasm.sh must run ./check-linuxcnc-opfs-source-map.sh before consuming app-backed browser artifacts or source-linked LinuxCNC objects.
• The OPFS source-map guard validates LinuxCNC source-backed filesystem bridge policy only; it does not interpret G-code.

Checks

Run:

./check-linuxcnc-opfs-source-map.sh
./test-native.sh
./test-linuxcnc-source-link.sh
./build-wasm.sh

check-linuxcnc-opfs-source-map.sh keeps this document, the LinuxCNC source anchors, and the browser bridge guardrails synchronized.