# ADR 0013: WebAssembly stand-ins for native toolchain packages

- **Status:** accepted (2026-10-21); extended to rolldown and lightningcss (2026-10-22) and Tailwind's oxide (2026-10-22)
- **Context:** Native addons and binaries are a v1 non-goal. The golden template
  is a stock Vite + React project, and Vite depends on two native packages:
  - **esbuild:** a Go binary, spawned as a child process.
  - **rollup:** a Rust addon, loaded with `require('…/rollup.linux-x64-gnu.node')`.

  npm installs the platform build of each, and neither can run in ClientVM. Both projects also
  publish official WebAssembly builds with the same interface: `esbuild-wasm` (the same CLI and
  service protocol) and `@rollup/wasm-node` (the same binding exports). Asking agents to add
  `overrides` to every project would make ClientVM projects differ from normal ones.
- **Decision:**
  - When a stock project reaches for one of these native parts, ClientVM uses the matching
    WebAssembly build of the **same version** instead. It fetches that build from the registry on
    first use, checks it against the registry's published integrity, and unpacks it into
    `/usr/local/lib/clientvm/standins/<name>@<version>`.
  - **esbuild:** the default environment sets `ESBUILD_BINARY_PATH` to
    `/usr/local/lib/clientvm/bin/esbuild`. esbuild's install script and runtime both honor this
    variable. The file is a marker for the `clientvm-esbuild` runtime, which runs esbuild-wasm on
    the node runtime. It takes the version from `--service=<version>`, which esbuild's JS API
    passes, or else from the nearest `node_modules/esbuild`.
  - **rollup:** the CommonJS loader's `.node` handler asks the stand-in table before it fails
    with `ERR_DLOPEN_FAILED`. A rollup binding gets `@rollup/wasm-node`'s `dist/native.js`.
    `require()` is synchronous, so this download uses synchronous XHR, which dedicated workers
    allow.
  - **lightningcss** (Vite 8's CSS minifier): its `.node` binding gets `lightningcss-wasm`'s
    `wasm-node.cjs`, the synchronous Node build with the same exports.
  - **rolldown** (Vite 7+): its loader falls back to `require('@rolldown/binding-wasm32-wasi')`
    when the platform binding fails. That package is not among rolldown's dependencies, so the
    CommonJS resolver, when it cannot find it from inside rolldown, resolves it to the stand-in.
    It is napi-rs's WASI build: it needs `node:wasi` (ClientVM implements preview1 over the
    instance's `fs`) and `worker_threads` carrying a shared `WebAssembly.Memory` (rolldown's
    async work runs on a pool of four threads).
  - **Tailwind CSS 4's oxide** (`@tailwindcss/oxide`, the class scanner): the same fallback, to
    `@tailwindcss/oxide-wasm32-wasi`. That package declares `"cpu": ["wasm32"]`, so its npm
    install passes `--force` (into an empty staging directory, where it skips only that check).
    Its WASI build has an upstream bug: a rescan reports no changed files, on real Node too, so
    the dev server never picked up new classes. The install adds a small `clientvm-scanner.cjs`
    as the package's `main`: each `scan()` uses a fresh Scanner and returns every candidate seen
    so far, as the native build does.
  - WASI thread pools spawn worker threads and then block on shared memory until they start.
    A `worker_threads.Worker` therefore makes its own MessageChannel, posts `init` on it at once,
    and hands the child's end to the kernel with the spawn request (`threadPort`), so a thread
    starts without waiting for its parent's event loop.
  - Stand-ins with dependencies (rolldown's needs `@napi-rs/wasm-runtime` and `@emnapi/*`;
    lightningcss-wasm needs `napi-wasm`) are installed by running npm in the instance, into
    `standins/<name>@<version>/node_modules`. `@emnapi/*` ship only ES modules but are loaded with
    `require()`, which ClientVM cannot do for ES modules, so the install rewrites the ES modules of
    `"type": "module"` packages in that tree as CommonJS (`module/esm-to-cjs.ts`, static modules
    only).
  - A WASI binding and `@napi-rs/wasm-runtime` must share one `@emnapi/*`. rolldown 1.2.15's
    binding pins emnapi 2.0.0-alpha.5, outside wasm-runtime's peer range, so npm nests it under
    the binding and hoists 1.x; mixed, loading fails (`this.bridge.setLastError is not a
    function`, on Node too). The install removes the binding's nested `@emnapi/*` copies that are
    also hoisted, and a lookup repairs stand-ins installed before that (2026-11-02).
  - The table is deliberately short: only packages whose authors publish a drop-in WebAssembly
    build. Other native addons still fail with `ERR_DLOPEN_FAILED`.
- **Consequences:**
  - A stock Vite 6 project installs, serves with HMR, and builds without changes. The first use
    of each stand-in costs a download: about 4 MB for esbuild-wasm and 1.5 MB for
    @rollup/wasm-node.
  - npm still downloads the unused native optional dependencies, such as `@esbuild/linux-x64`
    (about 10 MB), because `process.platform`/`arch` report linux/x64.
  - `env` shows `ESBUILD_BINARY_PATH`. A project that sets its own value takes precedence.
  - The integrity of a stand-in comes from the registry's own metadata, not from a value pinned
    in ClientVM as npm's is (ADR 0012). It is as trustworthy as the registry over TLS, which is
    the same trust `npm install` already places in it.
  - A stock Vite 8 project (rolldown, lightningcss) installs, serves with HMR and builds without
    changes. The first use costs about 11 MB for rolldown's WebAssembly build and 16 MB for
    lightningcss's, plus an npm run; the WebAssembly memory for rolldown is a 1 GiB (initial)
    shared reservation, as on Node.
  - Tailwind 4 with Vite 8 works unchanged (dev server picking up new classes, `vite build`).
    Each rescan is a full scan of the sources, which is fast for agent-sized projects.
  - These npm-installed stand-ins need the registry at first use through npm, not a single
    fetch. A transient npm failure (network, timeout, 5xx) is retried twice, after 1 s and 3 s,
    with a warning; after that, or offline, npm's error is followed by the native-binding error.