@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.4

package/src/node/inspect.ts

@@ -0,0 +1,166 @@
+/**
+ * `util.inspect` and `util.format` — what `console.log` prints in Node. Close to
+ * Node's output for the common shapes (nested objects to depth 2, arrays, Map,
+ * Set, errors with stacks, Buffers, circular references); colours are ignored.
+ */
+
+export const inspectCustom = Symbol.for('nodejs.util.inspect.custom');
+
+export interface InspectOptions {
+  depth?: number | null;
+  colors?: boolean;
+  compact?: boolean | number;
+  breakLength?: number;
+  showHidden?: boolean;
+  sorted?: boolean;
+}
+
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+
+function quote(s: string): string {
+  const q = s.includes("'") && !s.includes('"') ? '"' : "'";
+  return q + s.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(new RegExp(q, 'g'), '\\' + q) + q;
+}
+
+function formatKey(key: string | symbol): string {
+  if (typeof key === 'symbol') return `[${key.toString()}]`;
+  return IDENT.test(key) ? key : quote(key);
+}
+
+function wrap(open: string, items: string[], close: string, breakLength: number, indent: string): string {
+  if (!items.length) return `${open}${close}`;
+  const single = `${open} ${items.join(', ')} ${close}`;
+  if (single.length + indent.length <= breakLength && !items.some((i) => i.includes('\n'))) return single;
+  const inner = indent + '  ';
+  return `${open}\n${items.map((i) => inner + i).join(',\n')}\n${indent}${close}`;
+}
+
+function constructorName(value: object): string | undefined {
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null) return '[Object: null prototype]';
+  const name = proto?.constructor?.name;
+  return name && name !== 'Object' ? name : undefined;
+}
+
+export function inspect(value: unknown, options: InspectOptions = {}): string {
+  const depth = options.depth === null ? Infinity : options.depth ?? 2;
+  const breakLength = options.breakLength ?? 80;
+  const seen: object[] = [];
+
+  const fmt = (v: unknown, level: number, indent: string, nested: boolean): string => {
+    switch (typeof v) {
+      case 'string': return nested ? quote(v) : v;
+      case 'number': return Object.is(v, -0) ? '-0' : String(v);
+      case 'bigint': return `${v}n`;
+      case 'boolean': return String(v);
+      case 'undefined': return 'undefined';
+      case 'symbol': return v.toString();
+      case 'function': {
+        const name = v.name ? `: ${v.name}` : ' (anonymous)';
+        const kind = /^class\s/.test(Function.prototype.toString.call(v)) ? 'class' : 'Function';
+        const keys = Object.keys(v);
+        const base = kind === 'class' ? `[class ${v.name || '(anonymous)'}]` : `[${kind}${name}]`;
+        if (!keys.length || level > depth) return base;
+        return wrap(`${base} {`, keys.map((k) => `${formatKey(k)}: ${fmt((v as any)[k], level + 1, indent + '  ', true)}`), '}', breakLength, indent);
+      }
+    }
+    if (v === null) return 'null';
+    const obj = v as Record<string | symbol, unknown>;
+    const custom = obj[inspectCustom];
+    if (typeof custom === 'function') {
+      const result = custom.call(obj, depth - level, { ...options, stylize: (s: string) => s }, inspect);
+      return typeof result === 'string' ? result : fmt(result, level, indent, nested);
+    }
+    if (seen.includes(obj)) return '[Circular *1]';
+    if (v instanceof Error) {
+      const stack = v.stack && v.stack.includes(v.message) ? v.stack : `${v.name}: ${v.message}${v.stack ? '\n' + v.stack.split('\n').slice(1).join('\n') : ''}`;
+      const extra = Object.keys(v).filter((k) => k !== 'stack' && k !== 'message');
+      if (!extra.length || level > depth) return stack;
+      seen.push(obj);
+      const out = wrap(`${stack} {`, extra.map((k) => `${formatKey(k)}: ${fmt(obj[k], level + 1, indent + '  ', true)}`), '}', breakLength, indent);
+      seen.pop();
+      return out;
+    }
+    if (v instanceof Date) return Number.isNaN(v.getTime()) ? 'Invalid Date' : v.toISOString();
+    if (v instanceof RegExp) return String(v);
+    if (v instanceof Promise) return 'Promise { <pending> }';
+    if (v instanceof WeakMap) return 'WeakMap { <items unknown> }';
+    if (v instanceof WeakSet) return 'WeakSet { <items unknown> }';
+    if (ArrayBuffer.isView(v) && !(v instanceof DataView)) {
+      const bytes = v as unknown as ArrayLike<number> & { constructor: { name: string } };
+      if (bytes.constructor.name === 'Buffer') {
+        const hex = Array.from(bytes as Uint8Array).slice(0, 50).map((b) => b.toString(16).padStart(2, '0'));
+        return `<Buffer${hex.length ? ' ' + hex.join(' ') : ''}${bytes.length > 50 ? ` ... ${bytes.length - 50} more bytes` : ''}>`;
+      }
+      return `${bytes.constructor.name}(${bytes.length}) [ ${Array.from(bytes).slice(0, 100).join(', ')} ]`;
+    }
+    if (level > depth) {
+      if (Array.isArray(v)) return '[Array]';
+      return `[${constructorName(obj) ?? 'Object'}]`;
+    }
+
+    seen.push(obj);
+    const next = (x: unknown) => fmt(x, level + 1, indent + '  ', true);
+    let out: string;
+    if (Array.isArray(v)) {
+      const items = v.slice(0, 100).map(next);
+      if (v.length > 100) items.push(`... ${v.length - 100} more items`);
+      for (const k of Object.keys(v)) if (!/^\d+$/.test(k)) items.push(`${formatKey(k)}: ${next(obj[k])}`);
+      const prefix = constructorName(obj) && constructorName(obj) !== 'Array' ? `${constructorName(obj)}(${v.length}) ` : '';
+      out = wrap(`${prefix}[`, items, ']', breakLength, indent);
+    } else if (v instanceof Map) {
+      out = wrap(`Map(${v.size}) {`, [...v].map(([k, val]) => `${next(k)} => ${next(val)}`), '}', breakLength, indent);
+    } else if (v instanceof Set) {
+      out = wrap(`Set(${v.size}) {`, [...v].map(next), '}', breakLength, indent);
+    } else {
+      const keys: Array<string | symbol> = [...Object.keys(obj), ...Object.getOwnPropertySymbols(obj).filter((s) => Object.getOwnPropertyDescriptor(obj, s)?.enumerable)];
+      if (options.sorted) keys.sort();
+      const items = keys.map((k) => {
+        const desc = Object.getOwnPropertyDescriptor(obj, k);
+        const shown = desc && (desc.get || desc.set) ? (desc.get && desc.set ? '[Getter/Setter]' : desc.get ? '[Getter]' : '[Setter]') : next(obj[k]);
+        return `${formatKey(k)}: ${shown}`;
+      });
+      const name = constructorName(obj);
+      const tag = (obj as { [Symbol.toStringTag]?: string })[Symbol.toStringTag];
+      const prefix = name ? `${name}${tag && tag !== name ? ` [${tag}]` : ''} ` : tag ? `Object [${tag}] ` : '';
+      out = items.length || !prefix ? wrap(`${prefix}{`, items, '}', breakLength, indent) : `${prefix}{}`;
+    }
+    seen.pop();
+    return out;
+  };
+
+  return fmt(value, 0, '', false);
+}
+inspect.custom = inspectCustom;
+inspect.defaultOptions = { depth: 2 } as InspectOptions;
+
+/** printf-style `util.format`: %s %d %i %f %j %o %O %c %%. */
+export function format(...args: unknown[]): string {
+  const [first, ...rest] = args;
+  if (typeof first !== 'string') return args.map((a) => inspect(a)).join(' ');
+  let i = 0;
+  let out = first.replace(/%([sdifjoOc%])/g, (match, spec: string) => {
+    if (spec === '%') return '%';
+    if (i >= rest.length) return match;
+    const arg = rest[i++];
+    switch (spec) {
+      case 's': return typeof arg === 'string' ? arg : typeof arg === 'bigint' ? `${arg}n` : typeof arg === 'object' && arg !== null ? inspect(arg, { depth: 1 }) : String(arg);
+      case 'd': return typeof arg === 'bigint' ? `${arg}n` : String(Number(arg));
+      case 'i': return typeof arg === 'bigint' ? `${arg}n` : String(parseInt(String(arg), 10));
+      case 'f': return String(parseFloat(String(arg)));
+      case 'j':
+        try {
+          return JSON.stringify(arg);
+        } catch {
+          return '[Circular]';
+        }
+      case 'c': return '';
+      default: return inspect(arg, { depth: spec === 'o' ? 4 : 2 });
+    }
+  });
+  for (; i < rest.length; i++) {
+    const arg = rest[i];
+    out += ' ' + (typeof arg === 'string' ? arg : inspect(arg));
+  }
+  return out;
+}

package/src/node/loader.ts

@@ -0,0 +1,293 @@
+/**
+ * The module system: Node's `Module` with `_load`, `_resolveFilename`,
+ * `_extensions`, `_compile` and `require.cache` — the hooks tools monkeypatch
+ * (module-alias, pirates, require-in-the-middle) are real and are what
+ * `require` goes through.
+ *
+ * Every file runs inside the CommonJS wrapper; ES modules are rewritten to it
+ * first (esm.ts). The wrapper also receives this process's globals (`process`,
+ * `Buffer`, timers, `console`…) as parameters, so several runtimes can share
+ * one JS realm (tests, the in-process kernel) without touching `globalThis`.
+ */
+import type { VirtualFileSystem } from '../vfs.js';
+import { dirname, extname } from '../paths.js';
+import { esmToCjs, ESM_MARK, hasModuleSyntax, mayBeEsm } from './esm.js';
+import { findPackageScope, IMPORT_CONDITIONS, nodeModulePaths, REQUIRE_CONDITIONS, resolveNodeModule, type Resolution } from './resolve.js';
+
+export interface LoaderOptions {
+  fs: VirtualFileSystem;
+  isBuiltin(name: string): boolean;
+  /** A builtin's exports (`fs`, `path`…). `module` is answered by the loader itself. */
+  builtin(name: string): unknown;
+  /** Injected into every module's wrapper by name. */
+  globals: Record<string, unknown>;
+}
+
+export interface NodeModule {
+  id: string;
+  filename: string;
+  path: string;
+  exports: any;
+  loaded: boolean;
+  parent: NodeModule | null | undefined;
+  children: NodeModule[];
+  paths: string[];
+  require(id: string): any;
+  /** Top-level-await modules: settles when evaluation finishes. */
+  __tla?: Promise<unknown>;
+}
+
+const AsyncFunction = Object.getPrototypeOf(async () => undefined).constructor as FunctionConstructor;
+
+function stripShebang(source: string): string {
+  const text = source.charCodeAt(0) === 0xfeff ? source.slice(1) : source;
+  return text.startsWith('#!') ? '//' + text.slice(2) : text;
+}
+
+export function createModuleSystem(options: LoaderOptions) {
+  const { fs } = options;
+  const cache: Record<string, NodeModule> = Object.create(null);
+  const interop = new WeakMap<object, object>();
+  const globalNames = Object.keys(options.globals);
+  const globalValues = globalNames.map((n) => options.globals[n]);
+  let main: NodeModule | undefined;
+
+  function isEsmFile(filename: string, source: string): boolean {
+    const ext = extname(filename);
+    if (ext === '.mjs') return true;
+    if (ext === '.cjs') return false;
+    if (findPackageScope(fs, dirname(filename))?.pkg.type === 'module') return true;
+    // Node 22 "detect-module": ambiguous .js with import/export syntax is ESM.
+    return mayBeEsm(source) && hasModuleSyntax(source);
+  }
+
+  /** What `import` sees of a module: an ES module's own namespace, or `{ default: module.exports, ...named }`. */
+  function namespaceOf(exports: any): any {
+    if (exports && exports[ESM_MARK]) return exports;
+    if ((typeof exports !== 'object' && typeof exports !== 'function') || exports === null) return { default: exports };
+    let ns = interop.get(exports);
+    if (!ns) {
+      ns = Object.create(null) as object;
+      for (const key of Object.keys(exports)) if (key !== 'default') Object.defineProperty(ns, key, { enumerable: true, get: () => exports[key] });
+      Object.defineProperty(ns, 'default', { enumerable: true, value: exports });
+      interop.set(exports, ns);
+    }
+    return ns;
+  }
+
+  class Module implements NodeModule {
+    static _cache = cache;
+    static _pathCache = Object.create(null);
+    static builtinModules: string[] = [];
+    static globalPaths = ['/usr/local/lib/node'];
+    static Module = Module;
+    static _extensions: Record<string, (module: Module, filename: string) => void> = {
+      '.js'(module, filename) {
+        const source = fs.readText(filename) ?? '';
+        if (isEsmFile(filename, source)) module._compile(esmToCjs(stripShebang(source)), filename, true);
+        else module._compile(source, filename);
+      },
+      '.cjs'(module, filename) {
+        module._compile(fs.readText(filename) ?? '', filename);
+      },
+      '.mjs'(module, filename) {
+        module._compile(esmToCjs(stripShebang(fs.readText(filename) ?? '')), filename, true);
+      },
+      '.json'(module, filename) {
+        try {
+          module.exports = JSON.parse(stripShebang(fs.readText(filename) ?? ''));
+        } catch (error) {
+          (error as Error).message = `${filename}: ${(error as Error).message}`;
+          throw error;
+        }
+      },
+      '.node'(_module, filename) {
+        throw Object.assign(new Error(`Native addons cannot run in the browser: ${filename}`), { code: 'ERR_DLOPEN_FAILED' });
+      },
+    };
+
+    id: string;
+    filename: string;
+    path: string;
+    exports: any = {};
+    loaded = false;
+    children: NodeModule[] = [];
+    paths: string[];
+    __tla?: Promise<unknown>;
+
+    constructor(id = '', public parent: NodeModule | null | undefined = undefined) {
+      this.id = id;
+      this.filename = id;
+      this.path = dirname(id || '/');
+      this.paths = nodeModulePaths(this.path);
+      parent?.children.push(this);
+    }
+
+    static _resolveFilename(request: string, parent?: NodeModule, _isMain?: boolean, opts?: { paths?: string[]; conditions?: readonly string[] }): string {
+      const fromDir = parent?.filename ? dirname(parent.filename) : (options.globals.process as { cwd(): string } | undefined)?.cwd() ?? '/';
+      const resolution = resolveNodeModule(fs, request, fromDir, {
+        conditions: opts?.conditions ?? REQUIRE_CONDITIONS,
+        isBuiltin: options.isBuiltin,
+        from: parent?.filename,
+        paths: opts?.paths,
+      });
+      return 'builtin' in resolution ? `node:${resolution.builtin}` : resolution.path;
+    }
+
+    static _load(request: string, parent?: NodeModule, isMain = false): any {
+      const filename = Module._resolveFilename(request, parent, isMain);
+      return loadResolved(filename, parent, isMain).exports;
+    }
+
+    static _nodeModulePaths = nodeModulePaths;
+    static isBuiltin = (name: string) => options.isBuiltin(name.replace(/^node:/, ''));
+    static createRequire = (filename: string | URL) => {
+      const path = typeof filename === 'string' ? filename.replace(/^file:\/\//, '') : decodeURIComponent(filename.pathname);
+      return makeRequire(new Module(path.endsWith('/') ? path + '__entry.js' : path));
+    };
+    static wrap = (source: string) => `(function (exports, require, module, __filename, __dirname) { ${source}\n});`;
+    static wrapper = ['(function (exports, require, module, __filename, __dirname) { ', '\n});'];
+    static syncBuiltinESMExports = () => undefined;
+    static register = () => undefined;
+    static findSourceMap = () => undefined;
+    static runMain = () => undefined;
+
+    require(id: string): any {
+      if (typeof id !== 'string' || !id) throw new TypeError('The "id" argument must be a non-empty string');
+      return Module._load(id, this, false);
+    }
+
+    _compile(content: string, filename: string, esm = false): unknown {
+      const require = makeRequire(this);
+      const dir = dirname(filename);
+      const names = ['exports', 'require', 'module', '__filename', '__dirname', ...globalNames];
+      const values: unknown[] = [this.exports, require, this, filename, dir, ...globalValues];
+      if (esm) {
+        names.push('__bfwc_import', '__bfwc_dynamic', '__bfwc_meta', '__bfwc_esm', '__bfwc_star', '__bfwc_get');
+        values.push(...esmHelpers(this, filename));
+      }
+      const code = `${stripShebang(content)}\n//# sourceURL=${encodeURI('file://' + filename)}`;
+      let fn: (...args: unknown[]) => unknown;
+      try {
+        fn = new Function(...names, code) as typeof fn;
+      } catch (error) {
+        if (esm && error instanceof SyntaxError && /await/.test(error.message)) fn = new AsyncFunction(...names, code) as typeof fn;
+        else {
+          if (error instanceof Error) error.message = `${filename}: ${error.message}`;
+          throw error;
+        }
+      }
+      const result = fn.apply(this.exports, values);
+      if (result instanceof Promise) this.__tla = result;
+      return result;
+    }
+  }
+
+  function esmHelpers(module: Module, filename: string): unknown[] {
+    const load = (specifier: string): { exports: any; __tla?: Promise<unknown> } => {
+      let target: string;
+      try {
+        target = Module._resolveFilename(specifier, module, false, { conditions: REQUIRE_CONDITIONS });
+      } catch (error) {
+        // Prefer a package's CommonJS build (no transform, no binding snapshots);
+        // ESM-only packages resolve through the "import" condition instead.
+        if ((error as { code?: string }).code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') throw error;
+        target = Module._resolveFilename(specifier, module, false, { conditions: IMPORT_CONDITIONS });
+      }
+      return loadResolved(target, module, false);
+    };
+    const importSync = (specifier: string) => namespaceOf(load(specifier).exports);
+    const meta = {
+      url: 'file://' + filename,
+      filename,
+      dirname: dirname(filename),
+      resolve: (specifier: string) => {
+        const target = Module._resolveFilename(specifier, module, false, { conditions: IMPORT_CONDITIONS });
+        return target.startsWith('node:') ? target : 'file://' + target;
+      },
+    };
+    const define = (exports: any, getters: Record<string, () => unknown>) => {
+      Object.defineProperty(exports, '__esModule', { value: true });
+      Object.defineProperty(exports, ESM_MARK, { value: true });
+      for (const [name, get] of Object.entries(getters)) Object.defineProperty(exports, name, { enumerable: true, configurable: true, get });
+    };
+    const star = (exports: any, ns: any) => {
+      for (const key of Object.keys(ns)) {
+        if (key === 'default' || key === '__esModule' || Object.prototype.hasOwnProperty.call(exports, key)) continue;
+        Object.defineProperty(exports, key, { enumerable: true, configurable: true, get: () => ns[key] });
+      }
+    };
+    const get = (ns: any, key: string) => {
+      try {
+        return ns[key];
+      } catch {
+        return undefined; // a cyclic import read before the binding was initialised
+      }
+    };
+    const dynamic = async (specifier: string) => {
+      const loaded = load(String(specifier));
+      if (loaded.__tla) await loaded.__tla;
+      return namespaceOf(loaded.exports);
+    };
+    return [importSync, dynamic, meta, define, star, get];
+  }
+
+  function loadResolved(filename: string, parent: NodeModule | undefined, isMain: boolean): { exports: any } {
+    if (filename.startsWith('node:')) {
+      const name = filename.slice(5);
+      return { exports: name === 'module' ? Module : options.builtin(name) };
+    }
+    const cached = cache[filename];
+    if (cached) {
+      if (parent && !parent.children.includes(cached)) parent.children.push(cached);
+      return cached;
+    }
+    const module = new Module(filename, parent ?? null);
+    if (isMain) {
+      main = module;
+      module.id = '.';
+    }
+    cache[filename] = module;
+    try {
+      const handler = Module._extensions[extname(filename)] ?? Module._extensions['.js']!;
+      handler(module, filename);
+    } catch (error) {
+      delete cache[filename];
+      throw error;
+    }
+    module.loaded = true;
+    return module;
+  }
+
+  function makeRequire(module: Module) {
+    const require = ((id: string) => module.require(id)) as ((id: string) => any) & Record<string, any>;
+    const resolve = (request: string, opts?: { paths?: string[] }) => {
+      const target = Module._resolveFilename(request, module, false, opts);
+      return target.startsWith('node:') && !request.startsWith('node:') ? request : target;
+    };
+    resolve.paths = (request: string) => (options.isBuiltin(request) ? null : nodeModulePaths(module.path));
+    require.resolve = resolve;
+    require.cache = cache;
+    require.extensions = Module._extensions;
+    Object.defineProperty(require, 'main', { get: () => main, enumerable: true });
+    return require;
+  }
+
+  return {
+    Module,
+    cache,
+    /** Run `filename` as the main module. */
+    runMain(filename: string): NodeModule {
+      return loadResolved(filename, undefined, true) as NodeModule;
+    },
+    get main() {
+      return main;
+    },
+    createRequire: Module.createRequire,
+    resolve(request: string, fromDir: string): Resolution {
+      return resolveNodeModule(fs, request, fromDir, { conditions: REQUIRE_CONDITIONS, isBuiltin: options.isBuiltin });
+    },
+  };
+}
+
+export type ModuleSystem = ReturnType<typeof createModuleSystem>;

package/src/node/loop.ts

@@ -0,0 +1,193 @@
+/**
+ * Node's "the process exits when there is nothing left to do", recreated.
+ *
+ * A browser has no way to ask "is anything still pending?", so the runtime
+ * counts what Node would count: ref'd timers and intervals, listening servers,
+ * open watchers, a flowing stdin, child processes and in-flight requests
+ * (`hold()`). When the count reaches zero, an idle check runs on a later
+ * macrotask — after every pending microtask (promise chains, fs callbacks) has
+ * drained — and if still zero, the process exits.
+ *
+ * Timers are Node-shaped objects (`ref`/`unref`/`refresh`/`hasRef`), and errors
+ * thrown from any callback are routed to the process as uncaught exceptions.
+ */
+
+const realSetTimeout = globalThis.setTimeout.bind(globalThis);
+const realClearTimeout = globalThis.clearTimeout.bind(globalThis);
+const realSetInterval = globalThis.setInterval.bind(globalThis);
+const realClearInterval = globalThis.clearInterval.bind(globalThis);
+
+type Callback = (...args: any[]) => void;
+
+let nextTimerId = 1;
+
+export class Timeout {
+  readonly _id = nextTimerId++;
+  _ref = true;
+  _handle: ReturnType<typeof realSetTimeout> | undefined;
+  _destroyed = false;
+
+  constructor(
+    private readonly loop: EventLoop,
+    readonly _onTimeout: Callback,
+    readonly _idleTimeout: number,
+    private readonly args: unknown[],
+    readonly _repeat: boolean,
+  ) {}
+
+  ref(): this {
+    if (!this._ref && !this._destroyed) this.loop._refChanged(this, true);
+    this._ref = true;
+    return this;
+  }
+
+  unref(): this {
+    if (this._ref && !this._destroyed) this.loop._refChanged(this, false);
+    this._ref = false;
+    return this;
+  }
+
+  hasRef(): boolean {
+    return this._ref;
+  }
+
+  refresh(): this {
+    if (!this._destroyed) this.loop._arm(this);
+    return this;
+  }
+
+  close(): this {
+    this.loop.clear(this);
+    return this;
+  }
+
+  [Symbol.toPrimitive](): number {
+    return this._id;
+  }
+
+  _fire(): void {
+    this.loop._run(() => this._onTimeout(...this.args));
+  }
+}
+
+export interface EventLoopOptions {
+  /** Called once when nothing keeps the process alive. */
+  onIdle(): void;
+  /** An exception escaped a callback. */
+  onError(error: unknown): void;
+}
+
+export class EventLoop {
+  private holds = 0;
+  private readonly timers = new Map<number, Timeout>();
+  private refTimers = 0;
+  private checkScheduled = false;
+  private stopped = false;
+
+  constructor(private readonly options: EventLoopOptions) {}
+
+  /** Keep the process alive until the returned function is called (idempotent). */
+  hold(): () => void {
+    if (this.stopped) return () => undefined;
+    this.holds++;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.holds--;
+      this.scheduleCheck();
+    };
+  }
+
+  /** Run `fn` the way a callback from the loop runs: errors become uncaught exceptions. */
+  _run(fn: () => void): void {
+    if (this.stopped) return;
+    try {
+      fn();
+    } catch (error) {
+      this.options.onError(error);
+    }
+  }
+
+  get alive(): boolean {
+    return this.holds > 0 || this.refTimers > 0;
+  }
+
+  setTimeout = (fn: Callback, ms?: number, ...args: unknown[]): Timeout => this.add(fn, ms, args, false);
+  setInterval = (fn: Callback, ms?: number, ...args: unknown[]): Timeout => this.add(fn, ms, args, true);
+  setImmediate = (fn: Callback, ...args: unknown[]): Timeout => this.add(fn, 0, args, false);
+  clearTimeout = (timer: unknown): void => this.clear(timer);
+  clearInterval = (timer: unknown): void => this.clear(timer);
+  clearImmediate = (timer: unknown): void => this.clear(timer);
+
+  clear(timer: unknown): void {
+    const id = typeof timer === 'object' && timer ? (timer as Timeout)._id : Number(timer);
+    const t = this.timers.get(id);
+    if (!t) return;
+    this.disarm(t);
+    this.timers.delete(id);
+    t._destroyed = true;
+    if (t._ref) {
+      this.refTimers--;
+      this.scheduleCheck();
+    }
+  }
+
+  /** Has the loop been asked to check for idleness? Run the check after microtasks drain. */
+  scheduleCheck(): void {
+    if (this.checkScheduled || this.stopped) return;
+    this.checkScheduled = true;
+    // Two macrotask hops: a callback that schedules work via a just-resolved
+    // promise gets every chance to register a timer or hold first.
+    realSetTimeout(() => {
+      realSetTimeout(() => {
+        this.checkScheduled = false;
+        if (!this.alive && !this.stopped) this.options.onIdle();
+      }, 0);
+    }, 0);
+  }
+
+  /** Stop everything: the process has exited. */
+  stop(): void {
+    this.stopped = true;
+    for (const t of this.timers.values()) this.disarm(t);
+    this.timers.clear();
+  }
+
+  _refChanged(_t: Timeout, ref: boolean): void {
+    this.refTimers += ref ? 1 : -1;
+    if (!ref) this.scheduleCheck();
+  }
+
+  _arm(t: Timeout): void {
+    this.disarm(t);
+    const ms = Math.max(0, t._idleTimeout);
+    if (t._repeat) t._handle = realSetInterval(() => t._fire(), Math.max(1, ms));
+    else {
+      t._handle = realSetTimeout(() => {
+        this.timers.delete(t._id);
+        t._destroyed = true;
+        if (t._ref) this.refTimers--;
+        t._fire();
+        if (t._ref) this.scheduleCheck();
+      }, ms);
+    }
+  }
+
+  private add(fn: Callback, ms: number | undefined, args: unknown[], repeat: boolean): Timeout {
+    if (typeof fn !== 'function') throw new TypeError('The "callback" argument must be of type function');
+    const t = new Timeout(this, fn, Number.isFinite(ms) ? Number(ms) : 1, args, repeat);
+    if (this.stopped) return t;
+    this.timers.set(t._id, t);
+    this.refTimers++;
+    this._arm(t);
+    return t;
+  }
+
+  private disarm(t: Timeout): void {
+    if (t._handle === undefined) return;
+    if (t._repeat) realClearInterval(t._handle);
+    else realClearTimeout(t._handle);
+    t._handle = undefined;
+  }
+}