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/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-mirror-sections.js	Verifies OPFS/WASM mirror persistence used by source-backed file parsing and parameter movement.
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.
• 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.

Checks

Run:

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

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