RFC: WebWorker interface via an N-API module

[matthargett]

Intent

Land the N‑API + underlying JS‑runtime updates needed to expose a WebWorker interface as an N‑API module, so the Factotum BabylonJS app can lift‑and‑shift from the browser/PWA into BabylonNative with minimal code change.

Why this matters

• Factotum's data pipeline was moved onto a Web Worker; on‑device that gave a ~10 fps uplift on Quest 1/2, Pico 4, and similar standalone headsets (pulling the pipeline off the render thread).
• To carry that architecture into BabylonNative, BabylonNative needs a Worker‑compatible surface — cleanest delivered as an N‑API module exposing the Worker interface (construct, postMessage, transferables, onmessage/onerror, terminate), backed by the runtime's threading/isolate model.
• Revenue imperative: in‑app purchases are broken/non‑existent for immersive PWAs on the Meta Horizon Store and Pico Store (even as of June 2026). Shipping as a native (BabylonNative) app is currently the only viable monetization path on those stores, so unblocking Factotum → BabylonNative is business‑critical for BabylonJS‑community devs whose complex BabylonJS apps depend on revenue (and storefront placement).

Why the N‑API track comes first

A Worker‑as‑N‑API‑module needs a solid, modern N‑API surface across the runtimes BabylonNative ships:

• N‑API conformance + cross‑engine parity (the Add N-API compliance tests BabylonJS/JsRuntimeHost#116 + v7 track) so addons behave the same on V8 / JSC / Chakra.
• A shared libnapi so in‑process addons resolve modules dynamically, allowing for less hacky build setups to exclude N-API plug-ins that aren't used and align to other runtimes (Build napi as a shared library on Android BabylonJS/JsRuntimeHost#183).
• On Android specifically, a JSC that can keep up (see the jsc‑android → Bun‑JSC RFC) — Worker payloads use modern JS (structured clone, BigInt, transferables) that 2019 JSC can't even parse.

Proposed shape (for discussion)

• An N‑API module exposing a Worker class: construct from a script/module; postMessage with structured‑clone + transferable ArrayBuffers; terminate; onmessage/onerror.
• Backed by a second runtime instance/isolate on a worker thread, with a thread‑safe channel (napi_threadsafe_function or equivalent).
• Reuse BabylonNative's existing JS dispatch / task‑runner where possible.

Open questions

• Per‑engine threading model (V8 isolate‑per‑worker; JSC JSContextGroup; Chakra runtime‑per‑worker) and which napi_* primitives we standardize on.
• Structured‑clone + transferable depth (ties into the v7 ArrayBuffer detach work).
• Lifecycle/GC ownership across the thread boundary.

Related N‑API track: BabylonJS#116, BabylonJS#183, BabylonJS#185 (+ the v7 work staged as fork PR #4).