@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 #

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

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 Pages; 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:

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:

• kernel worker + runtime worker, in-memory FS, typed syscall table, sync mailbox
• CJS require of local files, node:fs via the builtin registry
• demo page boots a runtime, runs a main that requires a local module, exits 0
• missing module → Cannot find module, exit 1
• no cross-origin isolation → IsolationError (no silent degraded mode)
• 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
• writeFileSync round-trip through the mailbox
• SW routing probe: PASS in Chromium for direct AND nested workers
• 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.
• 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).
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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).
• 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.
• 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.
• 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.
• 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.
• 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.
• 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/.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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).
• 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).
• 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 Pages (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 #

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).