# @nibling/kernel

The `nib` prefix on its error codes, worker names, and internals comes from
node-in-browser, the project's original inspiration.

A browser-run Node.js-compatible runtime. JavaScript runs in the browser's own
engine; the parts of Node the browser can't express fall through to a small WASM
residue. **Browser-first is a precedence rule:** for every Node API, use a
browser-native primitive when it can meet Node's behavior (OPFS, WebCrypto,
TextEncoder/Decoder, Web Streams, Workers); compile to WASM only what's left.

Not affiliated with and not derived from StackBlitz WebContainers — the
architecture is our own (see `DESIGN.md`).

## Use it with Vite

```ts
// vite.config.ts
import nib from "@nibling/kernel/vite";
export default defineConfig({ plugins: [nib()] });
```

```ts
import { getKernel } from "@nibling/kernel";
import app from "./examples/express?nib";      // a dir with package.json + installed node_modules

const runtime = await getKernel();             // one per page; survives HMR
const { root } = await runtime.mount(app);
runtime.exec(`${root}/${app.entry}`, { cwd: root });
iframe.src = await runtime.waitForPort(3000);
```

`nib()` sets COOP/COEP on your pages in `vite dev` and `vite preview`, serves the runtime
at `<base>__nib/<version>/` and its Service Worker at `<base>nib-sw.js`, and points the
`@nibling/kernel` import at them, so `getKernel()` needs no options. A `<dir>?nib` import
is a snapshot of that directory, described by its metadata (`{ src, root, entry, kind,
files, bytes }`), never its contents. In dev, edits under it reach the running guest
without a page reload. `vite build` emits the same layout plus a `_headers` for Netlify
and Cloudflare; on another host, `nib({ host: "none" })` prints the headers to set.
`pages: ["/playground/**"]` limits COOP/COEP to the pages that boot the runtime (COOP
breaks OAuth and payment popups). For the `?nib` types, declare the module:

```ts
declare module "*?nib" {
  const app: import("@nibling/kernel").NibApp;
  export default app;
}
```

## Architecture in one paragraph

One **kernel worker** owns the filesystem and process table (the only writer);
**runtime workers** run user JS and reach the kernel through a typed syscall
table over a sync mailbox (`SharedArrayBuffer` + `Atomics.wait`), which is what
makes `require()` and `readFileSync()` honestly synchronous without blocking the
page. Node's event loop is emulated one callback per browser task with native
microtask checkpoints. The WASM residue is derived from the browser-first
precedence table, not designed top-down.

## Status: step 1 ✅ · resolver v2 ✅ · ESM (step 6, early) ✅ · TypeScript stripping ✅ · node:http ✅ · Hono from npm ✅ · event loop + process (step 3, partial) ✅ · Express 5 from npm ✅ · static files ✅ · slopbox shell ✅ · zlib + Buffer on browser codecs ✅ · stdin, signals, ptys + readline ✅ · slopbox terminal pane ✅ · WebSockets to guest servers ✅ · worker_threads + esbuild-wasm ✅ · Vite dev server ✅ · npm install from a lockfile ✅ · npm install from package.json ✅ · guest `npm install`/`ci`/`uninstall` ✅ · guest `npm run`/`exec` and npx ✅ · slopbox bash Shell tab ✅

`DESIGN.md §Build order` tracks the milestones. Done so far:

- [x] kernel worker + runtime worker, in-memory FS, typed syscall table, sync mailbox
- [x] CJS `require` of local files, `node:fs` via the builtin registry
- [x] demo page boots a runtime, runs a main that requires a local module, exits 0
- [x] missing module → `Cannot find module`, exit 1
- [x] no cross-origin isolation → `IsolationError` (no silent degraded mode)
- [x] resolver v2: `node_modules` walk, `package.json` `exports` (conditions + wildcard
      patterns), `main` fallback, self-reference, nearest-`type` format detection; with no
      `type`, a `.js`/`.ts` with module syntax (import/export, `import.meta`, top-level
      await) loads as ESM with Node's `MODULE_TYPELESS_PACKAGE_JSON` warning, once per
      package.json and never under node_modules
- [x] `writeFileSync` round-trip through the mailbox
- [x] **SW routing probe: PASS in Chromium for direct AND nested workers**
- [x] **Guest ESM via the browser's native linker** over the SW virtual origin:
      specifier rewriting in the kernel (es-module-lexer), builtin + CJS facades sharing
      `require.cache`, `import.meta.url` = `file:///app/...`, live-binding cycles for free.
      Dynamic `import()` from ESM and CJS (computed specifiers included) goes through the same
      resolver and keeps the process alive until it settles; a missing target rejects with
      `ERR_MODULE_NOT_FOUND`.
- [x] **TypeScript via type stripping** (Node's strip-only contract, `@swc/wasm-typescript`
      — the engine Node's amaro wraps): `.ts` follows nearest `type` (and is syntax-detected on its stripped source when there is none), `.mts`/`.mts` → ESM,
      `.cts` → CJS; `import type` erased *before* resolution; no extension rewriting; `.tsx`
      and enums refused with Node's own error codes; node_modules `.ts` refused
      (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`); engine failure is contained (plain JS
      keeps running).
- [x] **Guest `node:http` servers over the SW virtual origin**: `createServer().listen(port)` in
      CJS or ESM, `runtime.waitForPort(port)` → `/~/@<host>/http/<port>/`, an `<iframe>` renders the guest's
      response; buffered request/response bodies, Node's `EADDRINUSE` error event, 502 when
      nothing listens, `server.close()` lets the process exit 0. Absolute-path requests from
      the guest's pages and workers (`/app.js`, `fetch("/api")`, `<a href="/about">`, form
      posts) route to the guest by requesting client, so multi-file apps work unprefixed.
- [x] **Uncaught errors are fatal, as in Node** (DESIGN §Event loop table): a throw from any
      loop callback, an error escaping to the worker, or an unhandled rejection prints to
      stderr and exits 1. A guest server that crashes frees its port, and the request it was
      serving gets a 502 instead of waiting out the bridge timeout. `uncaughtException` and
      `unhandledRejection` listeners keep the process running, as in Node.
- [x] **An unmodified Hono app from npm** (`hono` + `@hono/node-server`, pinned by
      `demo/apps/hono/package-lock.json`) renders in the iframe, echoes JSON, returns a
      `ReadableStream` body, and serves Hono's 404. `npm run fixtures` installs each
      `demo/apps/<name>` and snapshots it (node_modules included) with
      `scripts/snapshot.mjs` into a binary `.snap` for `runtime.mountSnapshot`. New builtins: `node:events` (Node's
      function-constructor shape), `Buffer` (global and `node:buffer`), `node:stream`
      (`Readable` with `toWeb`/`fromWeb`), and `node:http2` (imports link; factories refuse).
      `IncomingMessage` is a `Readable`, and each request has a virtual socket.
- [x] **Node's event loop and `process` lifecycle** (step 3, partial), checked against golden
      traces recorded from Node v24.16 (`node scripts/golden.mjs`): guest timers and
      `setImmediate` live in the loop and keep the process alive (`ref`/`unref`/`refresh`,
      `node:timers`, `node:timers/promises`); one callback per browser task, so microtasks
      drain between callbacks; CJS nextTick-before-promise order; `process` is a global
      EventEmitter in CJS and ESM with `beforeExit`/`exit`/`exitCode`, `process.stdout`/`stderr`,
      `hrtime()`, `cwd()`/`chdir()` and `emitWarning`.
- [x] **An unmodified Express 5 app from npm** (`express` 5.3.0, pinned by
      `demo/apps/express/package-lock.json`) runs with `NODE_ENV=production`: HTML, JSON
      params and query, `express.json()` bodies, finalhandler's 404 and 500 pages. Status,
      content-type, ETag, content-length, x-powered-by and body equal what real Node answers,
      recorded by `node scripts/golden.mjs` (tests/goldens/http). New builtins, each checked against a Node
      golden: `node:util` (`inspect`/`format`, which `console` now prints through),
      `node:path`, `node:url` (legacy `parse`/`format`), `node:querystring`,
      `node:string_decoder`, `node:crypto` (synchronous md5/sha1/sha256/sha512 hashing and
      HMAC, WebCrypto randomness), `node:async_hooks`, `node:net` (address predicates),
      `node:tty`, plus `Readable.pipe`/`unpipe`. `node:zlib`, `node:https` and the socket
      half of `node:net` load and refuse with `ERR_NIB_UNSUPPORTED`.
- [x] **Static files through each framework's own middleware.** Express serves
      `public/` with `express.static` and Hono with `@hono/node-server`'s `serveStatic`; a
      stylesheet, a JSON file and a PNG, plus HEAD, a conditional GET (304), a ranged GET
      (206) and a missing asset, match real Node byte for byte, ETag and Last-Modified
      included. Snapshots (version 3, a binary `.snap`) keep app assets and every file's
      mtime, and `runtime.mountSnapshot(buffer)` seeds both. `node:fs` gains `fs.Stats`, callback forms
      completing in the poll phase (`stat`, `lstat`, `fstat`, `open`, `read`, `close`,
      `readFile`, `readdir`, `access`, `exists`, `realpath`), `fs.promises` and
      `node:fs/promises`, the matching sync forms, `fs.createReadStream`/`fs.ReadStream`,
      `fs.constants`, and Node's error messages, each checked against a Node golden.
- [x] **slopbox, a local shell for snapshot apps** (`examples/slopbox`): a catalog from
      `dist/fixtures/index.json`, one runtime per page running the chosen app with
      `NODE_ENV=production`, a console, and a supervisor that restarts crashes with backoff.
      Built on the public host API, which gained `runtime.onListening`/`runtime.onUnlistening` (apps
      choose their own port) and `proc.kill()` (restart a live app).
- [x] **zlib and Buffer encodings on the browser's own codecs.** `node:zlib`'s gzip,
      deflate and deflate-raw run on CompressionStream/DecompressionStream: the async
      convenience forms, `createGzip` and the other Transform streams, unzip's
      gzip-or-zlib detection, Node's error messages and codes, and `crc32`. Brotli, zstd and
      the `*Sync` forms refuse. `stream.Transform` follows Node's event order. Buffer's
      base64, base64url and hex use `Uint8Array.fromBase64`/`toHex` and friends, falling
      back to a lenient decoder for the inputs Node accepts and they reject. An Express
      request with a gzipped JSON body echoes what Node echoes. Each is checked against a
      Node golden; `DESIGN.md` §Browser-native audit lists what each Node concern rides on.
- [x] **stdin, signals and terminals.** `process.stdin` over a pipe with Node's liveness
      rules, and `proc.stdin` on the host. `process.kill`, `process.on("SIGINT")` and
      default actions, with `proc.kill(signal)`: a listener takes the signal, otherwise the
      default action applies, and SIGKILL always terminates. `exec(entry, { pty })` runs a
      process on a kernel pty with a line discipline (canonical editing, ^C/^\ signals, ^D
      EOF, echo, CR/NL mapping), raw mode, `tty.ReadStream`/`tty.WriteStream` with
      `columns`, `rows`, colour depth and `'resize'`. `node:readline` is ported from Node
      v24.16 (see `LICENSE-node`). No job control: stop signals continue at once.
- [x] **slopbox terminal pane.** Apps marked `"slopbox": { "kind": "cli" }` run on a pty
      in an xterm pane that fits the stage, follows the colour scheme and forwards
      keystrokes and resizes. `demo/apps/clack` is a real `@clack/prompts` CLI.
- [x] **One Service Worker, many host pages.** Every `/~/` URL names the page that booted
      its runtime (`/~/@<host>/...`), so pages on one origin each reach their own runtime,
      and a closed page's URL answers 502 naming its token. When the browser stops the idle
      SW, it asks each open page to register again on restart, so running apps keep
      answering and loading modules without a reload.
- [x] **No half-working boot.** `boot()` throws a named error instead of running CJS alone
      when Service Workers are unavailable (`ServiceWorkerUnavailableError`), when the page
      never comes under the runtime's worker (`ServiceWorkerUncontrolledError`; a hard
      reload is recovered by asking the worker to claim the page), when a narrower-scope
      worker controls it (`ServiceWorkerShadowedError`), when the site already has another
      worker at scope `/` (`ServiceWorkerConflictError`, which names the `importScripts()` fix),
      or when registering its own worker fails or never becomes active
      (`ServiceWorkerRegisterError`). Every boot error carries a stable `code` (`ERR_NIB_*`).
      A site worker that applies the `importScripts()` fix answers the runtime's ping, so
      `boot()` uses it as the runtime's worker instead of registering over it, and the site's
      own listeners keep running beside the runtime's.
      Setting `self.nibServiceWorker = { skipWaiting: false, claim: false }` before the
      `importScripts()` leaves updates to the site: a new version waits until the site calls
      `skipWaiting()`, and the runtime rebridges its pages when that version activates.
- [x] **Relocatable runtime.** `boot({ base, serviceWorker })` loads `kernel.js`, `runtime.js`
      and `swc.wasm` from `base` (default: host.js's own directory) and registers
      `serviceWorker` (default: `sw.js` in `base`) at scope `/`. A worker script outside the
      origin root needs `Service-Worker-Allowed: /`. `tests/relocated.spec.ts` boots from
      `/__nib/0.0.0/` with a root `/nib-sw.js` and checks that nothing loads from `/dist/`.
- [x] **WebSockets from app pages to guest servers.** A Service Worker cannot intercept a
      WebSocket, so guest documents get `/~/ws-shim.js` first in `<head>`. It replaces
      `window.WebSocket`: a URL on the page's own host opens a raw byte connection
      (a MessagePort the SW, host and kernel hand on to the runtime worker that owns the
      port) and speaks RFC 6455 over it; any other URL gets the native WebSocket. The guest
      sees `server.on("upgrade", (req, socket, head))` with a net.Socket-shaped Duplex, so
      libraries that implement the protocol themselves work: an unmodified `ws` server
      (`demo/apps/ws`, ws 8.22.0) matches what real Node's WebSocket client recorded
      (`node scripts/golden.mjs`, tests/goldens/ws), from text and binary echoes through a fragmented
      message, ping/pong, 16- and 64-bit frame lengths, both close directions and a crash
      (1006). An open socket keeps the process alive and survives the SW being stopped.
      New: `stream.Writable` and `stream.Duplex`, Buffer's numeric reads and writes,
      `buffer.isUtf8`, and a refusing `node:tls`, each checked against a Node golden.
- [x] **`node:worker_threads`, and an unmodified esbuild-wasm.** A `Worker` is a kernel
      thread in its parent's process (same pid, its own loop), started from a file, a
      `file:` URL, an ESM file or `eval: true` source. `workerData`, `postMessage` with
      transferred ArrayBuffers and MessagePorts, SharedArrayBuffer with `Atomics.wait`
      between threads, `MessageChannel`, `BroadcastChannel`, environment data, `terminate()`,
      `unref()`, the uncaught error as the parent's `'error'`, and worker stdout through the
      parent all match Node goldens. `receiveMessageOnPort` reads a port synchronously from
      a thread blocked in `Atomics.wait`. `child_process.spawn` runs `node <script>` as a
      child process with piped or inherited stdio; `node:os` and `node:module`'s
      `createRequire` are new. `demo/apps/esbuild` (esbuild-wasm 0.28.2) runs
      `transformSync`, `buildSync`, `transform` and `build` over files in the VFS and
      prints what Node prints. Snapshots now keep `.wasm` files and shebang scripts in
      `node_modules`. `SHARE_ENV`, `exec`, `fork` and the sync child forms refuse.
- [x] **The real Vite 7 dev server.** `demo/apps/vite` (vite 7.3.7, @vitejs/plugin-react
      5.2.0, React 19.2) starts Vite through `createServer().listen()`, and slopbox frames
      it: the page renders `App.jsx` through Babel and React Refresh, its CSS applies,
      and `/@vite/client` logs `[vite] connected.` over a WebSocket through the shim.
      npm `overrides` swap the native packages for their WebAssembly builds
      (`esbuild` → `esbuild-wasm` 0.27.7, `rollup` → `@rollup/wasm-node` 4.65.1), so no
      `.node` addon loads. The served `index.html` equals what real Node serves. An app's
      `"slopbox": { "env" }` replaces slopbox's `NODE_ENV=production` default; the Vite
      app passes `{}`, so Vite picks development itself, as its CLI does. New:
      package.json `imports` (`#` specifiers) and the `module-sync` condition; fs writes
      in callback, promise and sync forms (`writeFile`, `appendFile`, `mkdir` with
      Node's `mkdir -p` result, `rm`, `rmdir`, `rename`, `unlink`, `copyFile`,
      `mkdtemp`, `write`); `fs.watch` with Linux inotify semantics; `node:assert`,
      `node:dns` (`lookup` of localhost and IP literals), `node:perf_hooks` and `node:v8`;
      CJS require cycles that see partial exports, as in Node. Each is checked against a
      Node golden, except `fs.watch`, whose expected events are derived from Linux
      because the oracle runs on macOS. HMR edits are next.
- [x] **npm install from a lockfile, in the browser.** `runtime.install({ cwd })` reads
      `package-lock.json` (v2/v3), fetches each tarball from its `resolved` URL, checks
      its `integrity` and keeps the package unpacked in Cache Storage, which every page on
      the origin shares, so a later install of the same lockfile fetches, gunzips and
      untars nothing; a stored package is used only when the lockfile's `integrity` names
      the hash it was checked against. The store deletes its least recently used packages
      past 500 MB.
      Packages whose `os`/`cpu`/`libc` exclude a glibc linux x64 are skipped, as npm
      skips them, and a bundled dependency comes out of its bundler's tarball. The tree
      it writes equals what `npm ci` wrote for every fixture's `.snap`, file for file,
      except where the platform differs (vite takes the linux lzma binding and drops
      fsevents). Hono installs in about 0.15 s cold and 10 ms warm, Vite in 0.6–1.3 s cold
      and 60 ms warm. `npm run fixtures` also writes each app without `node_modules` as
      `<name>.src.snap`, the same v3 format. Each package's bins link from
      `node_modules/.bin` as `npm ci` links them, by name and target, so
      `node node_modules/.bin/esbuild` runs. slopbox installs each app this way instead
      of mounting a `node_modules` snapshot: from page load to a rendered app on a local
      server, Hono takes about 0.45 s cold and 0.15 s warm, Vite 2.4 s cold and 1.2 s
      warm. Install scripts do not run yet.
- [x] **Directories kept across page loads.** `runtime.persist({ key, paths })` restores
      the directories saved under `key` and returns `save()`, which saves them again.
      The kernel reads and writes the files, with their symlinks and mtimes, in Cache
      Storage under a 100 MB budget of its own. slopbox keeps the vite app's
      `node_modules/.vite` under the app's name and lockfile hash, so a second visit
      skips Vite's dependency optimizer.
- [x] **npm install from package.json, in the browser.** `runtime.install()` resolves what
      `package.json` asks for that the lockfile (if any) does not satisfy, as npm
      11.7's arborist places it (hoisting, dedupe, peers, ERESOLVE, overrides, `npm:`
      aliases), from registry metadata kept in Cache Storage for the registry's max-age, and writes
      `package-lock.json` byte for byte as npm writes it. A lockfile that already
      satisfies package.json is installed as it is and not rewritten. Checked against
      real npm's lockfile for hono, express, a peer/override/alias case, a stale
      lockfile and a set of hand-built registries, in Node and in the browser.
- [x] **A guest `npm` command: install, ci and uninstall.** Guest code runs
      `child_process.spawn("npm", ["install", "zod"])`, and the host runs
      `runtime.exec("/usr/local/bin/npm", { argv: ["install", "zod"] })`. Both run the same
      script, which the kernel seeds at `/usr/local/lib/node_modules/npm/bin/npm-cli.js`.
      The command edits package.json as npm 11.7 does: `^` on the version installed, a
      range kept when `^` would widen it, `-E`, `-D`, `-O`, `--no-save`, moves between
      maps, sorted maps, and the file's indent and newline. `npm ci` refuses a lockfile
      that package.json has outgrown. The command prints npm's summary (`added 2 packages
      in 1s`), its `npm warn` and `npm error` lines, and its exit codes. The install runs
      in the kernel, which keeps answering other processes while it waits on the
      registry. Checked against real npm for 27 commands over one fake registry: exit
      status, stdout and stderr, package.json, package-lock.json and node_modules.
- [x] **`npm run`, `npm exec` and npx, with no shell.** `npm run build`, `npm test` and
      `npm start` run a script with its pre and post scripts, npm's banner and the
      environment npm gives it (`npm_lifecycle_event`, `npm_package_*`, PATH with each
      `node_modules/.bin`). A script runs if it is simple commands joined by `&&`, `||`
      and `;`, each `node` or a bin, with sh's quoting, `NAME=value` prefixes and `$NAME`.
      Anything else needs a shell and fails with `ENOTSUP` naming what it met. The
      script's exit code is npm's, and SIGINT and SIGTERM reach it. `npx hello` runs a
      local bin, or installs the package into `~/.npm/_npx/<hash>` and runs it from
      there. Checked against real npm for 17 commands: exit status, stdout, stderr and
      the npx cache.
- [x] **Symlinks.** `fs.symlink`, `readlink`, `lstat` and `Dirent.isSymbolicLink()` in
      every form, with paths walked as Linux walks them: relative targets from the
      link's directory, `..` after a link from where it points, `ELOOP` after 40 hops.
      `realpath` resolves links, and `require` and `import` load a module from its real
      path, so a package reached through two links loads once and `node <link>` runs
      the target. Checked against Node goldens; `runtime.fs` gains `symlink` and `readlink`.
- [x] **Page-level API for the Vite plugin.** `configure()` sets page-wide boot defaults,
      `getKernel()` is a page singleton shared across HMR and duplicate package copies
      (`ERR_NIB_KERNEL_EXISTS` on conflicting options), `runtime.mount()` seeds from a `.snap`
      URL, buffer or `NibApp` and returns its root (`{ replace: true }` first prunes the
      root down to the snapshot's files), and `runtime.applyFiles()` writes and
      deletes files that a running guest's `fs.watch` sees (`tests/api.spec.ts`).
- [x] **Vite plugin, dev server.** `nib()` (`src/vite/index.ts`) isolates `pages`, serves the
      runtime at `<base>__nib/<version>/` and the SW at `<base>nib-sw.js`, and resolves
      `@nibling/kernel` to a pre-configured host; `<dir>?nib` exports a `NibApp` whose edits
      reach the running guest over HMR without a page reload (`tests/vite-plugin.spec.ts`).
- [x] **Vite plugin, build and preview.** `vite build` emits the runtime unhashed at
      `__nib/<version>/`, `nib-sw.js` at the root of `base`, each `?nib` snapshot as a
      hashed `.snap`, and a `_headers` for Netlify and Cloudflare (`host: "none"`
      prints the headers instead); `vite preview` serves the build isolated. Built URLs
      are relative to their chunk, so a `./` base works too (`tests/vite-plugin.spec.ts`).
      It ships as `@nibling/kernel/vite` (peer `vite >=6`); `npm run pack:check` runs
      `vite build` against the installed tarball.

Next: Vite HMR (an edit in the VFS reaching the page as a hot update); fs follow-ups
(`createWriteStream`, `fs.watchFile`, recursive watches); http follow-ups
(streaming responses, the `http.request` client, https, `fetch` interception); the rest
of step 2 (`fork` IPC, `spawnSync`); step 4 (OPFS persistence); step 5 (WASM residue:
sync hashing, sync zlib).

## Run it

```sh
npm install
npm run build          # esbuild → dist/runtime/ + dist/types/ (shipped), dist/demo/ (demo-only)
npm run serve          # http://localhost:8931/demo/index.html (COOP/COEP + CSP)
npm run fixtures       # npm ci each demo/apps/<name>, snapshot to dist/fixtures/<name>.snap (+ <name>.src.snap without node_modules) + index.json
npm test               # build + fixtures + Playwright acceptance tests
PORT=8942 npm test     # from another worktree: the suite starts its own server; PW_REUSE_SERVER=1 reuses a running one
TARBALLS_OFFLINE=1 npm test   # after one online run: registry tarballs come only from tests/fixtures/tarballs
npm run typecheck
npm run pack:check     # pack, assert the tarball file list, install it into a scratch consumer, type-check + resolve
node scripts/golden.mjs [--check] [target…]   # re-record tests/goldens (guests/, http/, ws/) under the pinned Node; exit 1 on drift
node scripts/golden.mjs --check --node=<bin>   # the same against a candidate Node, without moving the pin
node scripts/golden.mjs --write [target…]      # re-record; a new guest takes --stdin=<JSON> --deps=a,b
node scripts/surface.mjs record [--node=<bin>] # every builtin's API surface → compat/node-<version>.json
node scripts/surface.mjs delta <from> <to>      # what a Node release added/changed/removed, from two records
node scripts/surface.mjs baseline               # rewrite compat/divergences.json from the last surface spec run
node scripts/bump-node.mjs <version>            # move the pin to <version>, re-record the manifest and goldens under it
node scripts/node-releases.mjs [--index=<file>] [--json] [extraMajor…]   # newest LTS per tracked major vs. the pin
node scripts/node-release-check.mjs [version] [--report=<path>]          # fetch + surface delta + golden --check for a candidate
```

Goldens and surface records refuse to run on any Node but the repo's `.node-version`.
`tests/surface.spec.ts` requires every path in the pinned record to exist in the
kernel with the same kind, or to be listed in `compat/divergences.json` with a tagged reason
(`todo`, `refuse`, `internal`, `deprecated`, `accepted`; the spec's header defines them);
it also fails on entries the kernel has since satisfied. To vet a new Node minor,
record it with `--node`, read `delta`, then implement or list each new path; and run
`golden.mjs --check --node=<bin>` for behavior changes the surface can't see.

slopbox, the catalog shell for these demo apps, is its own package now: see
`examples/slopbox` (`pnpm --filter @nibling/example-slopbox serve`, on :8932, and
`.../screenshot-slopbox.mjs <outDir>` for its screenshots).

- `/demo/index.html` — CJS main: `require('node:fs')`, bare packages via `exports`
  (`leftpad`) and `main` fallback (`shouty`), plus a `writeFileSync` round-trip
- `/demo/esm.html` — guest ESM: `import fs from 'node:fs'`, ESM graph, CJS via facade,
  bare package, `import.meta.url` — the browser's linker does cycles/live bindings
- `/demo/esm-cycle.html` — live-binding cycle proof (native linking, no emulation)
- `/demo/ts.html` — TypeScript via type stripping: `.mts`/`.ts`, `import type` erased before
  resolution, CJS `.ts` through the facade, Node's refusal codes for `.tsx`/enums
- `/demo/ts-noengine.html` — engine failure containment: plain JS keeps running, `.ts` fails
  with `ERR_NIB_TS_ENGINE`
- `/demo/http.html` — guest `node:http` server on port 3000 rendered in an iframe; `GET /bye`
  closes it and the process exits 0; `?esm` runs the `import http from "node:http"` variant
- `/demo/hono.html` — an unmodified Hono app from npm, mounted from its snapshot
  (`npm run fixtures` → `dist/fixtures/hono.snap` → `runtime.mountSnapshot`), rendered in an
  iframe, with `public/` under `/static/` through `serveStatic`
- `/demo/express.html` — an unmodified Express 5 app from npm, mounted from its snapshot
  (`dist/fixtures/express.snap`) and run with `NODE_ENV=production`, rendered in an iframe
  whose stylesheet comes from `express.static`
- `/demo/ws.html` — an unmodified `ws` WebSocketServer on a node:http server; its page
  opens WebSockets through the shim and renders the exchange (`?crash` runs it through to
  the crash the spec records, `?manual` leaves the sockets to the caller)
- **slopbox** — lists the demo apps (Clack, Crashy, esbuild-wasm, Express, Hono, Vite + React, WebSocket); choosing one
  loads `?app=<name>`, which boots a runtime, mounts the app's own files
  (`<name>.src.snap`), installs `node_modules` from its lockfile, runs the entry and frames
  the first port it listens on. Toolbar: reload the frame, restart the process, open the app
  in a new tab (works while the shell tab stays open, since it hosts the runtime). A crash
  restarts after 250 ms, 1 s, 4 s; a fourth crash within 30 s stops in `failed` with a
  Restart button. `?backoff=0,0,0` replaces the delays (the tests use it). `demo/apps/crashy`
  is a dependency-free server whose page crashes it or exits it cleanly. A CLI app
  (`"slopbox": { "kind": "cli" }` in its `package.json`, like `demo/apps/clack`) runs on a
  pty in a terminal pane instead of the frame: exit 0 stops in `done` with Run again, and a
  non-zero exit restarts as a crash does. A **Shell** tab next to **Console** (both server
  and CLI apps get it) is a bash prompt — bashkit — on the app's own VFS, where `node`,
  `npm` and `npx` run real processes in the same runtime; it loads lazily, only once the
  tab is first chosen, and becomes usable once the app's files are mounted. The slopbox
  page alone allows inline styles, because xterm injects `<style>` elements. slopbox is its
  own package, `examples/slopbox` (`@nibling/example-slopbox`), not part of this one —
  see its README. `tests/vite.spec.ts` and `tests/sw-shadow.spec.ts` here instead use a
  minimal single-app runner, `/demo/app.html?app=<name>`, that boots one fixture the same
  way with no catalog, terminal or shell
- `/demo/missing.html` — missing-module error path, exit 1
- `/demo/not-exported.html` — `exports` package boundary, exit 1
- `/demo/sw-probe/` — does a SW intercept worker module imports — direct and nested? Its worker is
  scoped to `/demo/sw-probe/` so it never controls another page (see DESIGN on shadowed workers)
- `/demo/harness.html` — **the IDE-ish face**: VS Code-style Explorer (collapsible tree with
  extension-colored icons, context menu), editor tabs with dirty indicators + line gutter,
  bottom OUTPUT panel running guests, full VFS CRUD through `runtime.fs` — guest writes appear in
  the tree live via `onFsChanged`, and page edits are visible to guests
- `/demo/no-coi.html` — served *without* COOP/COEP on purpose: `boot()` must refuse

## Layout

```
src/host/      page API: boot(), Kernel, exec() — the only public surface
src/kernel/    worker: sole FS/process owner, syscall dispatch, resolver
src/runtime/   worker: user JS, event loop, CJS loader, builtin registry
src/shared/    wire protocol + sync mailbox (both sides import; never exported)
src/sw/        Service Worker: the /~/ virtual origin, app routing, raw connections
src/shim/      the WebSocket shim the SW serves into guest documents (RFC 6455 client)
demo/          browser entrypoints (import map maps @nibling/kernel → dist/runtime/host.js)
tests/         Playwright acceptance proofs, one suite per build step
```

Note on import maps: they're document-scoped, so they wire the *page's* bare
specifiers (`@nibling/kernel`). Guest `node:*` imports resolve through the
runtime's builtin registry (`src/runtime/builtins.ts`) — the same role, inside
the worker realm. Guest ESM gets the browser's native linker via a Service
Worker virtual origin in step 6.

## License

MIT (see `LICENSE`). The files derived from Node.js keep the Node.js license (`LICENSE-node`).