@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.3

package/src/styleModules.ts

@@ -23,19 +23,30 @@ export function rewriteCssUrls(fs: VirtualFileSystem, cssPath: string, css: stri
   });
 }
 
+/**
+ * A statement that puts `cssExpression` (JS source evaluating to a string) in a
+ * <style> tag keyed by `path`: re-evaluating the module replaces the tag's text
+ * instead of adding a second tag. Shared by stylesheets and component styles.
+ */
+export function injectStyleStatement(path: string, cssExpression: string): string {
+  const id = JSON.stringify(path);
+  return [
+    `{ let el = document.querySelector('style[data-bfwc=' + JSON.stringify(${id}) + ']');`,
+    `if (!el) { el = document.createElement('style'); el.setAttribute('data-bfwc', ${id}); document.head.appendChild(el); }`,
+    `el.textContent = ${cssExpression}; }`,
+  ].join('\n');
+}
+
 /**
  * The JS module for an imported stylesheet. `.module.css` exports an identity map
  * (class name → itself): real scoping needs the build API, so for now CSS Modules
  * render correctly as long as class names don't collide.
  */
 export function cssToModule(path: string, css: string): string {
-  const id = JSON.stringify(path);
   const exportsCssModule = /\.module\.css$/i.test(path);
   return [
     `const css = ${JSON.stringify(css)};`,
-    `let el = document.querySelector('style[data-bfwc=' + JSON.stringify(${id}) + ']');`,
-    `if (!el) { el = document.createElement('style'); el.setAttribute('data-bfwc', ${id}); document.head.appendChild(el); }`,
-    `el.textContent = css;`,
+    injectStyleStatement(path, 'css'),
     exportsCssModule
       ? `export default new Proxy({}, { get: (_, key) => typeof key === 'string' ? key : undefined });`
       : `export default css;`,

package/src/svelteCompiler.ts

@@ -0,0 +1,31 @@
+import type { ComponentCompiler } from './components.js';
+
+/**
+ * Svelte components through `svelte/compiler`. CSS is always compiled as
+ * `external` — Svelte scopes it with hashed class names — and handed back, so the
+ * dev server and the build each place it their own way.
+ *
+ * Svelte 5 strips `<script lang="ts">` itself. Svelte 4 needs a preprocessor for
+ * that, which this runtime does not run, so a TS component on Svelte 4 fails with
+ * the compiler's own message.
+ */
+export interface SvelteCompilerLike {
+  VERSION: string;
+  compile(
+    source: string,
+    options: { filename: string; generate: 'client'; css: 'external'; dev: boolean },
+  ): { js: { code: string }; css?: { code: string } | null };
+}
+
+export function createSvelteCompiler(svelte: SvelteCompilerLike): ComponentCompiler {
+  const major = Number.parseInt(svelte.VERSION, 10);
+  // Svelte 5 renamed the browser target from 'dom' to 'client'.
+  // Typed as Svelte 5's value; Svelte 4 receives its own spelling at runtime.
+  const generate = (major >= 5 ? 'client' : 'dom') as 'client';
+  return {
+    compile(source, { path, dev }) {
+      const result = svelte.compile(source, { filename: path, generate, css: 'external', dev });
+      return { code: result.js.code, loader: 'js', css: result.css?.code ?? '' };
+    },
+  };
+}

package/src/system/commands.ts

@@ -0,0 +1,72 @@
+/**
+ * Command lookup, shared by the kernel, the browser host and the shell:
+ * registered programs first (node, npm, jsh, coreutils), then a path or a
+ * `PATH`/`node_modules/.bin` lookup. A found file runs under `node` (a `.bin`
+ * shim runs its target directly) or, with a shell shebang, under `jsh`.
+ */
+import type { VirtualFileSystem } from '../vfs.js';
+import { dirname, extname, join, normalizePath } from '../paths.js';
+import { readBinLink } from '../installer/bins.js';
+import type { Program } from './types.js';
+
+export interface ResolvedCommand {
+  /** The registered program that will run (`node`, `jsh`, `ls`…). */
+  name: string;
+  program: Program;
+  args: string[];
+}
+
+/** Every `node_modules/.bin` from `cwd` up to the root, nearest first. */
+export function binDirectories(cwd: string): string[] {
+  const out: string[] = [];
+  for (let dir = normalizePath(cwd); ; dir = dirname(dir)) {
+    if (!dir.endsWith('/node_modules')) out.push(join(dir, 'node_modules/.bin'));
+    if (dir === '/') return out;
+  }
+}
+
+/** Find an executable file named `command` on PATH (then node_modules/.bin). */
+export function findExecutable(fs: VirtualFileSystem, command: string, cwd: string, env: Record<string, string | undefined>): string | undefined {
+  if (command.includes('/')) {
+    const path = command.startsWith('/') ? normalizePath(command) : join(cwd, command);
+    return fs.isFile(path) ? path : undefined;
+  }
+  const dirs = [...(env.PATH ?? '').split(':').filter(Boolean), ...binDirectories(cwd)];
+  for (const dir of dirs) {
+    const path = join(dir.startsWith('/') ? dir : join(cwd, dir), command);
+    if (fs.isFile(path)) return path;
+  }
+  return undefined;
+}
+
+/** How to run a script file: its interpreter and arguments. */
+export function interpreterFor(fs: VirtualFileSystem, path: string): { name: 'node' | 'jsh'; args: string[] } {
+  const target = readBinLink(fs, path);
+  if (target) return { name: 'node', args: [target] };
+  const firstLine = (fs.readText(path) ?? '').split('\n', 1)[0] ?? '';
+  if (/^#!.*\b(?:sh|bash|jsh|zsh|dash)\b/.test(firstLine)) return { name: 'jsh', args: [path] };
+  if (['.sh', '.bash'].includes(extname(path))) return { name: 'jsh', args: [path] };
+  return { name: 'node', args: [path] };
+}
+
+export function resolveCommand(
+  fs: VirtualFileSystem,
+  programs: Readonly<Record<string, Program>>,
+  command: string,
+  args: string[],
+  cwd: string,
+  env: Record<string, string | undefined>,
+): ResolvedCommand | undefined {
+  if (!command.includes('/') && Object.prototype.hasOwnProperty.call(programs, command)) {
+    return { name: command, program: programs[command]!, args };
+  }
+  const file = findExecutable(fs, command, cwd, env);
+  if (!file) return undefined;
+  const { name, args: lead } = interpreterFor(fs, file);
+  const program = programs[name];
+  return program ? { name, program, args: [...lead, ...args] } : undefined;
+}
+
+export function commandNotFound(command: string): Error {
+  return Object.assign(new Error(`spawn ${command} ENOENT`), { code: 'ENOENT', errno: -2, syscall: `spawn ${command}`, path: command });
+}

package/src/system/index.ts

@@ -0,0 +1,22 @@
+export { Kernel, DEFAULT_ENV } from './kernel.js';
+export type { KernelOptions, KernelSpawnOptions } from './kernel.js';
+export type { System, Program, ProgramContext, ProgramIO, TerminalPort, SpawnOptions, ChildHandle, HttpRequestData, HttpResponseData, HttpHandler } from './types.js';
+export { PortRegistry, parsePortPath } from './ports.js';
+export type { PortEvent } from './ports.js';
+export { runProgram, toWebContainerProcess, allocatePid } from './process.js';
+export type { WebContainerProcess, RunProgramOptions } from './process.js';
+export { resolveCommand, findExecutable, binDirectories, interpreterFor, commandNotFound } from './commands.js';
+export type { ResolvedCommand } from './commands.js';
+export { InputQueue, LineDiscipline, toTerminal } from './terminal.js';
+export { defaultPrograms } from './programs.js';
+export { startNode } from '../node/runtime.js';
+export type { NodeInstance, NodeOptions } from '../node/runtime.js';
+export { nodeProgram, parseNodeArgs } from '../node/program.js';
+export { esmToCjs, esmReady } from '../node/esm.js';
+export { NODE_VERSION } from '../node/process.js';
+export { shellProgram } from '../shell/program.js';
+export { Shell } from '../shell/exec.js';
+export type { ShellOptions, ShellIO, JobInput, ShellCommand } from '../shell/exec.js';
+export { parse as parseShell, ShellSyntaxError } from '../shell/parse.js';
+export { LineEditor } from '../shell/lineEditor.js';
+export { matchDevServer } from '../shell/devHandoff.js';

package/src/system/kernel.ts

@@ -0,0 +1,106 @@
+/**
+ * The in-process kernel: every program runs on the calling thread, sharing one
+ * VFS and one port registry. It is what the tests drive, and a host that does
+ * not need preemption (a CLI, a server-side sandbox) can use it as is. The
+ * browser runtime runs the same programs one-per-Worker instead, so a busy
+ * loop cannot freeze the page (see the browser package's node host).
+ */
+import { VirtualFileSystem } from '../vfs.js';
+import type { PackageCache } from '../installer/registry.js';
+import type { ChildHandle, HttpRequestData, HttpResponseData, Program, SpawnOptions, System } from './types.js';
+import { PortRegistry } from './ports.js';
+import { commandNotFound, resolveCommand } from './commands.js';
+import { runProgram, toWebContainerProcess, type WebContainerProcess } from './process.js';
+
+export interface KernelOptions {
+  fs?: VirtualFileSystem;
+  /** Programs by command name. The full set comes from `defaultPrograms()`. */
+  programs: Record<string, Program>;
+  fetch?: System['fetch'];
+  /** Base environment for every process. */
+  env?: Record<string, string>;
+  /** Where a browser reaches a server on `port`. Default `http://localhost:<port>/`. */
+  serverUrl?(port: number): string;
+  previewUrl?: string;
+  registry?: string;
+  packageCache?: PackageCache;
+}
+
+export interface KernelSpawnOptions extends SpawnOptions {
+  /** Kept for `@webcontainer/api` parity; output is always delivered. */
+  output?: boolean;
+}
+
+type ServerReadyListener = (port: number, url: string) => void;
+type PortListener = (port: number, type: 'open' | 'close', url: string) => void;
+
+export const DEFAULT_ENV: Record<string, string> = {
+  PATH: '/usr/local/bin:/usr/bin:/bin',
+  HOME: '/home/user',
+  USER: 'user',
+  SHELL: '/bin/jsh',
+  TERM: 'xterm-256color',
+  COLORTERM: 'truecolor',
+  LANG: 'en_US.UTF-8',
+  NODE_ENV: 'development',
+};
+
+export class Kernel {
+  readonly fs: VirtualFileSystem;
+  readonly ports = new PortRegistry();
+  readonly env: Record<string, string>;
+  private readonly serverReady = new Set<ServerReadyListener>();
+  private readonly portListeners = new Set<PortListener>();
+  private readonly system: System;
+
+  constructor(private readonly options: KernelOptions) {
+    this.fs = options.fs ?? new VirtualFileSystem();
+    this.env = { ...DEFAULT_ENV, ...options.env };
+    const serverUrl = (port: number) => options.serverUrl?.(port) ?? `http://localhost:${port}/`;
+    this.ports.watch(({ type, port }) => {
+      const url = serverUrl(port);
+      for (const l of this.portListeners) l(port, type, url);
+      if (type === 'open') for (const l of this.serverReady) l(port, url);
+    });
+    this.system = {
+      fs: this.fs,
+      fetch: options.fetch ?? ((input, init) => globalThis.fetch(input, init)),
+      spawn: (command, args, spawnOptions) => this.spawnChild(command, args, spawnOptions),
+      listen: (port, handler) => this.ports.listen(port, handler),
+      loopback: (port, request) => this.ports.request(port, request),
+      serverUrl,
+      announceServer: (port, url) => this.serverReady.forEach((l) => l(port, url)),
+      previewUrl: options.previewUrl,
+      registry: options.registry,
+      packageCache: options.packageCache,
+    };
+  }
+
+  /** Same shape as `WebContainer#spawn`. */
+  spawn(command: string, args: string[] | KernelSpawnOptions = [], options: KernelSpawnOptions = {}): WebContainerProcess {
+    if (!Array.isArray(args)) [options, args] = [args, []];
+    return toWebContainerProcess(this.spawnChild(command, args, options), !!options.terminal);
+  }
+
+  /** A child as a program's parent sees it — what `System.spawn` returns. */
+  spawnChild(command: string, args: string[] = [], options: SpawnOptions = {}): ChildHandle {
+    const cwd = options.cwd ?? '/';
+    const env = { ...this.env, ...options.env };
+    const resolved = resolveCommand(this.fs, this.options.programs, command, args, cwd, env);
+    if (!resolved) throw commandNotFound(command);
+    return runProgram({ program: resolved.program, args: resolved.args, system: this.system, cwd, env, terminal: options.terminal });
+  }
+
+  /** Send an HTTP request to a virtual server (what the preview service worker does in the browser). */
+  request(port: number, request: Partial<HttpRequestData> & { url: string }): Promise<HttpResponseData | undefined> {
+    return this.ports.request(port, { method: 'GET', headers: {}, body: null, ...request });
+  }
+
+  on(event: 'server-ready', listener: ServerReadyListener): () => void;
+  on(event: 'port', listener: PortListener): () => void;
+  on(event: 'server-ready' | 'port', listener: ServerReadyListener | PortListener): () => void {
+    const set = (event === 'server-ready' ? this.serverReady : this.portListeners) as Set<typeof listener>;
+    set.add(listener);
+    return () => set.delete(listener);
+  }
+}

package/src/system/ports.ts

@@ -0,0 +1,73 @@
+/**
+ * The virtual network: which handler serves which port. One registry per
+ * runtime (kernel or browser host), shared by every process in it, so a server
+ * in one process is reachable from another (`fetch('http://localhost:3000')`)
+ * and from the preview service worker (`/__bfwc/<id>/__port/3000/`).
+ */
+import type { HttpHandler, HttpRequestData, HttpResponseData } from './types.js';
+
+export interface PortEvent {
+  type: 'open' | 'close';
+  port: number;
+}
+
+const EPHEMERAL_START = 49152;
+
+export class PortRegistry {
+  private readonly handlers = new Map<number, HttpHandler>();
+  private readonly listeners = new Set<(event: PortEvent) => void>();
+  private nextEphemeral = EPHEMERAL_START;
+
+  listen(port: number, handler: HttpHandler): { port: number; close(): void } {
+    let actual = port;
+    if (!actual) {
+      while (this.handlers.has(this.nextEphemeral)) this.nextEphemeral++;
+      actual = this.nextEphemeral++;
+    }
+    if (this.handlers.has(actual)) {
+      throw Object.assign(new Error(`listen EADDRINUSE: address already in use :::${actual}`), { code: 'EADDRINUSE', errno: -98, syscall: 'listen', address: '::', port: actual });
+    }
+    this.handlers.set(actual, handler);
+    this.emit({ type: 'open', port: actual });
+    let open = true;
+    return {
+      port: actual,
+      close: () => {
+        if (!open || this.handlers.get(actual) !== handler) return;
+        open = false;
+        this.handlers.delete(actual);
+        this.emit({ type: 'close', port: actual });
+      },
+    };
+  }
+
+  has(port: number): boolean {
+    return this.handlers.has(port);
+  }
+
+  ports(): number[] {
+    return [...this.handlers.keys()].sort((a, b) => a - b);
+  }
+
+  /** Dispatch to the server on `port`; undefined when nothing listens there. */
+  async request(port: number, request: HttpRequestData): Promise<HttpResponseData | undefined> {
+    const handler = this.handlers.get(port);
+    return handler ? handler(request) : undefined;
+  }
+
+  watch(listener: (event: PortEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private emit(event: PortEvent): void {
+    for (const listener of this.listeners) listener(event);
+  }
+}
+
+/** `/__port/3000/api?x` → port 3000, path `/api`. Undefined for any other path. */
+export function parsePortPath(path: string): { port: number; path: string } | undefined {
+  const m = /^\/__port\/(\d{1,5})(\/.*)?$/.exec(path);
+  if (!m) return undefined;
+  return { port: Number(m[1]), path: m[2] ?? '/' };
+}

package/src/system/process.ts

@@ -0,0 +1,158 @@
+/**
+ * Running one program in-process: its stdin queue, TTY line discipline,
+ * output listeners and kill signal, packaged as a {@link ChildHandle}. The core
+ * kernel uses it for every process; the browser worker uses it for the one
+ * program it hosts. Also the WebContainer-shaped wrapper (`output`/`input`
+ * streams) that public `spawn` returns.
+ */
+import type { ChildHandle, Program, ProgramIO, SpawnOptions, System } from './types.js';
+import { InputQueue, LineDiscipline, toTerminal } from './terminal.js';
+
+let nextPid = 1000;
+
+export function allocatePid(): number {
+  return nextPid++;
+}
+
+export interface RunProgramOptions extends SpawnOptions {
+  program: Program;
+  args: string[];
+  system: System;
+  cwd: string;
+  env: Record<string, string>;
+  pid?: number;
+}
+
+/** Decode byte chunks without splitting multi-byte characters across writes. */
+function textSink(emit: (text: string) => void): (chunk: string | Uint8Array) => void {
+  const decoder = new TextDecoder();
+  return (chunk) => {
+    const text = typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+    if (text) emit(text);
+  };
+}
+
+export function runProgram(options: RunProgramOptions): ChildHandle {
+  const pid = options.pid ?? allocatePid();
+  const stdin = new InputQueue();
+  const stdoutListeners = new Set<(chunk: string) => void>();
+  const stderrListeners = new Set<(chunk: string) => void>();
+  const resizeListeners = new Set<(cols: number, rows: number) => void>();
+  const controller = new AbortController();
+  const emitOut = (text: string) => stdoutListeners.forEach((l) => l(text));
+  const emitErr = (text: string) => stderrListeners.forEach((l) => l(text));
+  let settled = false;
+  let forceExit: (code: number) => void = () => undefined;
+
+  const kill = (signal = 'SIGTERM') => {
+    if (settled) return;
+    if (!controller.signal.aborted) controller.abort(signal);
+    else if (signal === 'SIGKILL') forceExit(137);
+  };
+
+  const size = options.terminal ? { ...options.terminal } : undefined;
+  const discipline = size
+    ? new LineDiscipline({ echo: emitOut, deliver: (chunk) => stdin.push(chunk), signal: (name) => kill(name) })
+    : undefined;
+
+  const io: ProgramIO = {
+    stdout: textSink(emitOut),
+    stderr: textSink(emitErr),
+    onStdin: (listener) => stdin.subscribe(listener),
+    terminal: size && discipline
+      ? {
+          get cols() {
+            return size.cols;
+          },
+          get rows() {
+            return size.rows;
+          },
+          onResize(listener) {
+            resizeListeners.add(listener);
+            return () => resizeListeners.delete(listener);
+          },
+          setRawMode(raw) {
+            discipline.raw = raw;
+          },
+        }
+      : undefined,
+  };
+
+  const exit = new Promise<number>((resolve) => {
+    forceExit = (code) => {
+      settled = true;
+      resolve(code);
+    };
+    queueMicrotask(async () => {
+      let code: number;
+      try {
+        code = await options.program({ args: options.args, cwd: options.cwd, env: options.env, io, system: options.system, signal: controller.signal });
+      } catch (error) {
+        io.stderr(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+        code = 1;
+      }
+      settled = true;
+      resolve(code);
+    });
+  });
+
+  return {
+    pid,
+    onStdout(listener) {
+      stdoutListeners.add(listener);
+      return () => stdoutListeners.delete(listener);
+    },
+    onStderr(listener) {
+      stderrListeners.add(listener);
+      return () => stderrListeners.delete(listener);
+    },
+    write(data) {
+      if (discipline) discipline.input(data);
+      else stdin.push(data);
+    },
+    closeStdin: () => stdin.push(null),
+    kill,
+    resize(cols, rows) {
+      if (!size) return;
+      size.cols = cols;
+      size.rows = rows;
+      resizeListeners.forEach((l) => l(cols, rows));
+    },
+    exit,
+  };
+}
+
+/** The public process shape, deliberately the same as `@webcontainer/api`'s `WebContainerProcess`. */
+export interface WebContainerProcess {
+  /** stdout and stderr, interleaved as written (`\r\n` line endings when attached to a terminal). */
+  readonly output: ReadableStream<string>;
+  readonly input: WritableStream<string>;
+  readonly exit: Promise<number>;
+  kill(signal?: string): void;
+  resize(dimensions: { cols: number; rows: number } | number, rows?: number): void;
+}
+
+export function toWebContainerProcess(child: ChildHandle, terminal: boolean): WebContainerProcess {
+  const output = new ReadableStream<string>({
+    start(controller) {
+      const push = (chunk: string) => controller.enqueue(terminal ? toTerminal(chunk) : chunk);
+      child.onStdout(push);
+      child.onStderr(push);
+      void child.exit.then(() => controller.close());
+    },
+  });
+  const input = new WritableStream<string>({
+    write: (chunk) => child.write(chunk),
+    close: () => child.closeStdin(),
+  });
+  return {
+    output,
+    input,
+    exit: child.exit,
+    kill: (signal) => child.kill(signal),
+    resize(dimensions, rows) {
+      const size = typeof dimensions === 'number' ? { cols: dimensions, rows: rows ?? 24 } : dimensions;
+      child.resize?.(size.cols, size.rows);
+    },
+  };
+}

package/src/system/programs.ts

@@ -0,0 +1,31 @@
+/**
+ * The command table: every program a process can be. Hosts start from
+ * `defaultPrograms()` and may add or replace entries (a custom `git`, say).
+ *
+ * `npm`/`npx` live in the shell (they run scripts through it), so spawning them
+ * directly runs them through a one-shot shell; coreutils run standalone.
+ */
+import type { Program } from './types.js';
+import { nodeProgram } from '../node/program.js';
+import { shellProgram } from '../shell/program.js';
+import { COREUTILS } from '../shell/builtins.js';
+import { asProgram } from '../shell/context.js';
+
+const quote = (arg: string) => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`);
+
+function viaShell(command: string): Program {
+  return (ctx) => shellProgram({ ...ctx, args: ['-c', [command, ...ctx.args].map(quote).join(' ')] });
+}
+
+export function defaultPrograms(): Record<string, Program> {
+  const programs: Record<string, Program> = {
+    node: nodeProgram,
+    jsh: shellProgram,
+    sh: shellProgram,
+    bash: shellProgram,
+    npm: viaShell('npm'),
+    npx: viaShell('npx'),
+  };
+  for (const [name, command] of Object.entries(COREUTILS)) programs[name] = asProgram(command, name);
+  return programs;
+}

package/src/system/terminal.ts

@@ -0,0 +1,135 @@
+/**
+ * What a kernel's TTY layer does between xterm.js and a program:
+ *
+ * - InputQueue: stdin as a buffered stream of string chunks (data that arrives
+ *   before the program subscribes is kept, not dropped).
+ * - LineDiscipline: "cooked" mode — echo, backspace, Ctrl-U, Enter delivers the
+ *   line, Ctrl-C raises SIGINT, Ctrl-D is end-of-file. A program that calls
+ *   `setRawMode(true)` (the shell, prompts libraries) gets keystrokes untouched.
+ * - toTerminal: `\n` → `\r\n` on output (the TTY's ONLCR), since xterm.js
+ *   only moves to column 0 on `\r`.
+ */
+
+export class InputQueue {
+  private readonly buffered: Array<string | null> = [];
+  private readonly listeners = new Set<(chunk: string | null) => void>();
+  private ended = false;
+
+  private draining = false;
+
+  push(chunk: string | null): void {
+    if (this.ended) return;
+    if (chunk === null) this.ended = true;
+    this.buffered.push(chunk);
+    this.drain();
+  }
+
+  subscribe(listener: (chunk: string | null) => void): () => void {
+    this.listeners.add(listener);
+    this.drain();
+    return () => this.listeners.delete(listener);
+  }
+
+  /**
+   * Deliver on a microtask: a subscriber has always stored its unsubscribe
+   * function by then, and chunks stay buffered until someone is actually
+   * listening — one that leaves early does not take data with it.
+   */
+  private drain(): void {
+    if (this.draining || !this.listeners.size || !this.buffered.length) return;
+    this.draining = true;
+    queueMicrotask(() => {
+      this.draining = false;
+      while (this.buffered.length && this.listeners.size) {
+        const chunk = this.buffered.shift()!;
+        for (const listener of [...this.listeners]) listener(chunk);
+      }
+    });
+  }
+
+  /** Everything until end-of-file. */
+  readAll(): Promise<string> {
+    return new Promise((resolve) => {
+      let text = '';
+      const stop = this.subscribe((chunk) => {
+        if (chunk === null) {
+          stop();
+          resolve(text);
+        } else text += chunk;
+      });
+    });
+  }
+
+  get isEnded(): boolean {
+    return this.ended;
+  }
+}
+
+export function toTerminal(text: string): string {
+  return text.replace(/\r?\n/g, '\r\n');
+}
+
+export interface LineDisciplineOptions {
+  /** Echo to the terminal. */
+  echo(text: string): void;
+  /** A completed line (with its `\n`), or `null` for end-of-file. */
+  deliver(chunk: string | null): void;
+  /** Ctrl-C / Ctrl-\. */
+  signal(name: 'SIGINT' | 'SIGQUIT'): void;
+}
+
+export class LineDiscipline {
+  raw = false;
+  private line = '';
+
+  constructor(private readonly options: LineDisciplineOptions) {}
+
+  input(data: string): void {
+    if (this.raw) {
+      this.options.deliver(data);
+      return;
+    }
+    // Arrow keys and other escape sequences have no meaning in cooked mode.
+    const text = data.replace(/\x1b\[[0-9;]*[A-Za-z~]|\x1bO[A-Za-z]/g, '');
+    for (const ch of text) {
+      switch (ch) {
+        case '\r':
+        case '\n':
+          this.options.echo('\r\n');
+          this.options.deliver(this.line + '\n');
+          this.line = '';
+          break;
+        case '\x7f':
+        case '\b':
+          if (this.line) {
+            this.line = [...this.line].slice(0, -1).join('');
+            this.options.echo('\b \b');
+          }
+          break;
+        case '\x03':
+          this.options.echo('^C\r\n');
+          this.line = '';
+          this.options.signal('SIGINT');
+          break;
+        case '\x1c':
+          this.options.signal('SIGQUIT');
+          break;
+        case '\x04':
+          if (this.line) {
+            this.options.deliver(this.line);
+            this.line = '';
+          } else this.options.deliver(null);
+          break;
+        case '\x15':
+          this.options.echo('\b \b'.repeat([...this.line].length));
+          this.line = '';
+          break;
+        default:
+          if (ch >= ' ' || ch === '\t') {
+            this.line += ch;
+            this.options.echo(ch);
+          }
+      }
+    }
+  }
+}