cnc_wams/wasm-port/runtime/sdk/README.md

LinuxCNC WASM SDK

This SDK exposes browser/Node JavaScript wrappers for standalone WASM modules built from vendored LinuxCNC source.

Boundary

The SDK is a host-boundary layer only. It may:

• load generated Emscripten modules;
• allocate and free C strings;
• write text files into the Emscripten filesystem;
• call exported C ABI functions;
• return LinuxCNC-produced text output to JavaScript callers.

The SDK must not implement G-code interpretation, canonical motion behavior, tool semantics, parameter semantics, kinematics, or planner behavior. Those behaviors must continue to come from vendored LinuxCNC source through the C ABI.

Entrypoints

Use src/index.js for stable imports:

import {
  analyzeIniRuntimeBoundaries,
  createIniPanelLaunchApiManifest,
  createIniPanelShellViewModel,
  createIniPanelShellWorkflowOverviewEmbeddingMountDomContract,
  createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness,
  createLinuxCncIniSdk,
  createLinuxCncInterpSdk,
  createMachineSessionSnapshotPayload,
  createSessionSnapshot,
  defaultMachinePaths,
  gcodeFilenameFromProgramPath,
  gcodeProgramPath,
  getOpfsRoot,
  isSupportedIniPanelLaunchApiManifest,
  loadMachineSessionFromOpfs,
  loadMachineSessionSnapshot,
  loadMachineTextFiles,
  loadMachineToolTableFromOpfs,
  loadTextFile,
  machineFilePaths,
  machineIniPath,
  mountIniPanelShellWorkflowOverviewEmbeddingMountState,
  normalizeOpfsPath,
  parameterFilePath,
  planIniFileContextStaging,
  planSimConfigStaging,
  readMachineSessionReadiness,
  renderIniPanelShellWorkflowOverviewEmbeddingMountState,
  restoreMachineParametersFromOpfs,
  saveMachineSessionSnapshot,
  saveMachineTextFiles,
  saveSessionSnapshot,
  saveTextFile,
  sessionSnapshotPath,
  toolTablePath,
  validateSessionSnapshot,
} from "./src/index.js";

createLinuxCncIniSdk() wraps the INI parser module built from vendored LinuxCNC inifile.cc and exposes getString() plus getBool(). Boolean conversion is performed by vendored LinuxCNC iniFindBool().

createLinuxCncInterpSdk() wraps the interpreter-core module built from vendored LinuxCNC RS274NGC sources and exposes:

• runProgram(programText)
• runProgramWithIni(programText, iniPath)
• runFile(path)
• runFileWithIni(path, iniPath)
• runFileWithIniContinueOnError(path, iniPath)
• runSimConfigProgram({ iniPath, programPath, files, executionMode })
• runFiveAxisRemapFile(path, iniPath)
• runRemapFile(path, iniPath)
• runRemapIoMdiSequence(iniPath)
• restoreParameters(path)
• saveParameters(path, values)
• loadToolTable(path, options)
• saveToolTable(path)
• writeTextFile(path, text)
• readTextFile(path)

loadToolTable() accepts { randomToolChanger: true } to select the LinuxCNC random-toolchanger branch before calling vendored tooldata_load(). The SDK only forwards that runtime boundary flag.

runFiveAxisRemapFile() is a narrow host boundary for vendored LinuxCNC sample-machine remap validation. Callers provide INI/remap/demo files in the WASM filesystem; the C ABI runs vendored LinuxCNC REMAP, O-word, file execution, and HAL adapter paths.

runRemapFile() is the generic remap-test equivalent for vendored LinuxCNC tests such as tests/remap/duplicate-o-word. It reads LinuxCNC INI SUBROUTINE_PATH and REMAP entries, then calls vendored LinuxCNC Interp::parse_remap(), open(), read(), and execute().

runRemapIoMdiSequence() is a narrow regression boundary for the NGC-only branch of vendored LinuxCNC tests/remap/remap-io/test-ngc.ini. The C ABI reads LinuxCNC REMAP entries, then feeds the upstream test driver's MDI command sequence into vendored Interp::execute(). JavaScript only copies the vendored INI/subroutine files into the WASM filesystem and forwards the INI path; it does not implement M62-M68, M66 input, or remap semantics.

runFileWithIni() is the plain interpreter-file equivalent for upstream tests that need LinuxCNC INI search paths, such as tests/interp/sub-call-from-sub. The C ABI reads LinuxCNC SUBROUTINE_PATH and then calls vendored Interp::open(), read(), and execute(); the SDK only copies files and forwards paths.

runSimConfigProgram() is a convenience host boundary for representative LinuxCNC configs/sim programs. Callers provide { path, text, executable } file entries, an INI path, and a program path. The SDK writes those text files into the Emscripten filesystem, applies executable bits for user M-code files, then forwards to runFileWithIni() by default or to runFiveAxisRemapFile() when executionMode: "fiveAxisRemap" is explicitly requested.

planIniFileContextStaging() is the generic file-staging planner for LinuxCNC INI-driven interpreter runs. Callers provide vendored source-manifest text, a source root, an INI file name, INI text, and a target WASM directory. The planner reads only INI file references and the manifest, then returns the INI, [DISPLAY]OPEN_FILE, [EMCIO]TOOL_TABLE, [RS274NGC]PARAMETER_FILE, [RS274NGC]SUBROUTINE_PATH, [RS274NGC]USER_M_PATH, and remap-NGC files that should be copied into the Emscripten filesystem. Each planned file includes sourceRel, wasmPath, the legacy alias path, and executable. It does not implement G-code, tool, parameter, remap, or user-M semantics.

planSimConfigStaging() is the companion convenience wrapper for representative LinuxCNC configs/sim programs. Callers provide the vendored source manifest text, machine relative path, INI file name, and INI text. It uses planIniFileContextStaging() with a configs/sim/<machine> source root and configs/sim upward-search boundary.

analyzeIniRuntimeBoundaries() is a host-boundary classifier for LinuxCNC INI-driven runs. It reads INI text plus optional execution text and manifest text, then reports declared HAL, UI, HALUI MDI, Python, tool-database, and external user-M process dependencies. User-M accounting is per execution code: executionCodes lists M100..M199 codes seen in the supplied execution text, while unstagedExecutionCodes lists the subset not backed by vendored USER_M_PATH files. Python accounting keeps UI/DB references separate from Python remap runtime references, so a UI handler or DB program does not imply Python-remap coverage. It also returns the currently recommended Layer 4 blocked kind for hard process boundaries such as L4-TOOL-DB and L4-USER-M-PROCESS. The classifier is policy/accounting only: it does not execute HAL, task, UI, Python, user-M, or tool-database behavior and does not change interpreter semantics.

runFileWithIniContinueOnError() uses the same LinuxCNC-backed file execution path but keeps the runner loop going after LinuxCNC reports an error, matching upstream rs274 -n 0 regression tests such as tests/interp/oword-unwind. It does not implement or reinterpret LinuxCNC error semantics.

OPFS/session persistence exports

The SDK entrypoint re-exports the OPFS/session persistence helpers used by the browser panel so external callers can stage the same files without importing private module paths:

• getOpfsRoot(), saveTextFile(), and loadTextFile() for browser OPFS text persistence.
• machineIniPath(), toolTablePath(), parameterFilePath(), gcodeProgramPath(), sessionSnapshotPath(), defaultMachinePaths(), and normalizeOpfsPath() for stable OPFS path construction.
• createMachineSessionSnapshotPayload(), createSessionSnapshot(), saveSessionSnapshot(), saveMachineSessionSnapshot(), loadMachineSessionSnapshot(), and validateSessionSnapshot() for session snapshot persistence.
• machineFilePaths(), saveMachineTextFiles(), loadMachineTextFiles(), and gcodeFilenameFromProgramPath() for machine-file and G-code file helpers.
• readMachineSessionReadiness() for checking persisted INI, parameter, tool-table, optional G-code, and optional session snapshot files before loading a session.
• restoreMachineParametersFromOpfs(), loadMachineToolTableFromOpfs(), and loadMachineSessionFromOpfs() for loading OPFS machine state into the LinuxCNC-backed interpreter SDK.

These helpers only move and validate host files. Parameter and tool-table effects still come from the LinuxCNC-backed interpreter SDK methods they call.

INI panel shell handoff exports

The SDK entrypoint also re-exports the stable INI panel shell handoff surface for external browser shells:

• createIniPanelLaunchApiManifest() and isSupportedIniPanelLaunchApiManifest() for launch API negotiation.
• createIniPanelShellViewModel() for a complete read-only shell integration bundle.
• createIniPanelShellWorkflowOverviewEmbeddingMountDomContract() and createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness() for workflow overview embedding mount DOM checks.
• renderIniPanelShellWorkflowOverviewEmbeddingMountState() for rendering a mount render-state into caller-owned DOM.
• mountIniPanelShellWorkflowOverviewEmbeddingMountState() for a non-throwing workflow overview embedding mount wrapper that returns structured blocked results when DOM nodes are missing.

The workflow overview embedding helpers are UI/runtime boundary helpers only. They render status and rows already produced by the shell view-model; they do not parse G-code, execute action plans, or implement CNC semantics.