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

LinuxCNC WASM smoke source map

This map records the source basis and boundaries for the Node and browser WASM smoke wrappers. It is a smoke-test guard only; it must not add CNC behavior, must not expand the temporary smoke parser, and must keep browser filesystem persistence OPFS-only. In browser contexts, browser filesystem persistence OPFS-only is the required boundary.

LinuxCNC Source Basis

• src/emc/rs274ngc/rs274ngc_pre.cc provides Interp::ini_load(), Interp::restore_parameters(), Interp::save_parameters(), and read_text() behavior exercised by Node/browser bridge tests.
• src/emc/rs274ngc/rs274ngc_pre.cc saves parameters by writing filename + ".new", unlinking filename + ".bak", linking the previous file to filename + ".bak", and renaming the temporary file over the main file.
• src/emc/rs274ngc/interp_convert.cc provides convert_m() coverage for M66 waits and M68 analog output side effects used by generated remap cases.
• src/emc/nml_intf/canon.hh declares the WAIT() and SET_AUX_OUTPUT_VALUE() canon entry points surfaced through the event bridge.
• src/emc/kinematics/5axiskins.c, src/emc/kinematics/trtfuncs.c, src/emc/kinematics/xyzac-trt-kins.c, src/emc/kinematics/xyzbc-trt-kins.c, and src/emc/kinematics/userkfuncs.c provide the RTCP/kinematics inverse paths covered by WASM smoke tests.
• configs/sim/**.ini files and remap_subs/{428,429,430}remap.ngc sources generate web/public/linuxcnc_switchkins_remap_config_cases.json.

Smoke Coverage

Smoke entry	Boundary
test-web-wasm-node-smoke.sh	Runs the Node WASM wrapper with generated LinuxCNC switchkins cases and LinuxCNC-backed RTCP checks.
test-web-wasm-node-smoke.cjs	Exercises the C ABI, web/src/wasm-core.js, generated switchkins config cases, and source-backed kinematics events.
test-web-wasm-browser-smoke.sh	Runs browser checks after verifying copied WASM artifacts and smoke module structure.
web/test-browser-wasm-smoke-linuxcnc-sections.js	Exercises LinuxCNC browser parsing and generated switchkins cases without INI_FILE_NAME remap-load aliases.
web/test-browser-wasm-smoke-opfs-workspace-sections.js	Aggregates OPFS basic, parameter, mirror, and directory sections under browser OPFS availability.
web/test-browser-wasm-smoke-opfs-basic-sections.js	Exercises OPFS-backed program file reads through LinuxCNC read_text() and rejects unsafe paths.
web/test-browser-wasm-smoke-opfs-parameter-sections.js	Exercises LinuxCNC parameter restore/save/backup semantics through OPFS.
web/test-browser-wasm-smoke-opfs-mirror-sections.js	Exercises OPFS/WASM mirror persistence used by source-backed program parsing and parameter movement.
web/test-browser-wasm-smoke-opfs-directory-sections.js	Exercises OPFS directory persistence and WASM mirror refresh without filesystem persistence outside OPFS.
web/test-browser-wasm-smoke-opfs-policy-sections.js	Exercises browser OPFS workspace and mount policy, including the rule that OPFS cannot be disabled.
web/test-browser-wasm-smoke-app-sections.js	Verifies the browser app uses OPFS program and parameter persistence.

Boundaries

• Node smoke must leave OPFS disabled and must reject parseFile* methods that require an OPFS workspace.
• Browser smoke must keep program files, LinuxCNC parameter files, temporary .new files, and .bak backups under OPFS-backed storage.
• Generated switchkins config smoke cases must continue to come from web/public/linuxcnc_switchkins_remap_config_cases.json.
• The browser smoke shell guard also pins required section names for LinuxCNC browser parsing, OPFS workspace/policy/directory handling, OPFS parameter restore/save failure handling, and browser app OPFS reload coverage.
• Smoke wrappers must keep positive minimum coverage thresholds so accidental section loss is visible.
• test-native.sh, test-linuxcnc-source-link.sh, and build-wasm.sh must run ./check-linuxcnc-wasm-smoke-source-map.sh before consuming Node/browser WASM smoke coverage or browser artifacts.
• The WASM smoke source-map guard validates LinuxCNC source-backed smoke coverage only; it does not interpret G-code.

Checks

Run:

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

check-linuxcnc-wasm-smoke-source-map.sh keeps this document, LinuxCNC source anchors, smoke wrapper boundaries, OPFS-only policy, and generated switchkins case usage synchronized.