picopilot 0.1.4 → 0.2.0

package/dist/engine/pico8/cleanup.js

@@ -0,0 +1,74 @@
+/**
+ * Kill-on-abort for child processes picopilot owns while a run is in flight
+ * (the PICO-8 process group, a private Xvfb). Normal endings (sentinel,
+ * backstop, crash) are handled by the run itself; this covers picopilot being
+ * stopped mid-run: `process.exit`, an uncaught throw, or SIGINT / SIGTERM /
+ * SIGHUP sent to picopilot alone (an agent harness or `timeout` killing it).
+ * Without it, a detached PICO-8 or an Xvfb would outlive picopilot.
+ *
+ * `kill` must be synchronous (it runs inside an `exit` handler). On a signal,
+ * the hook kills, then re-raises the signal with picopilot's handler removed so
+ * the default behaviour (terminate) still happens, unless some other listener
+ * owns that signal (an MCP server, a test runner), which then decides.
+ */
+const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * The kill functions of every run in flight. ONE listener per event serves them
+ * all (installed while the set is non-empty), so many concurrent runs (an MCP
+ * server) never trip Node's MaxListeners warning.
+ */
+const pending = new Set();
+const signalHandlers = new Map();
+function killAll() {
+    for (const kill of [...pending]) {
+        pending.delete(kill);
+        try {
+            kill();
+        }
+        catch {
+            // best effort: the process may already be gone
+        }
+    }
+}
+function onExit() {
+    killAll();
+}
+function install() {
+    process.on('exit', onExit);
+    for (const signal of SIGNALS) {
+        const handler = () => {
+            killAll();
+            uninstall();
+            // Re-raise for the default behaviour (terminate) unless another listener
+            // (an MCP server, a test runner) owns this signal.
+            if (process.listenerCount(signal) === 0) {
+                process.kill(process.pid, signal);
+            }
+        };
+        signalHandlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+}
+function uninstall() {
+    process.removeListener('exit', onExit);
+    for (const [signal, handler] of signalHandlers) {
+        process.removeListener(signal, handler);
+    }
+    signalHandlers.clear();
+}
+/** Registers `kill` to run if picopilot exits or is signalled; returns the disposer. */
+export function killOnAbort(kill) {
+    let entry = () => kill();
+    if (pending.size === 0)
+        install();
+    pending.add(entry);
+    return () => {
+        if (entry === undefined)
+            return;
+        pending.delete(entry);
+        entry = undefined;
+        if (pending.size === 0)
+            uninstall();
+    };
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/engine/pico8/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../../src/engine/pico8/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,OAAO,GAA8B,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAE3E;;;;GAIG;AACH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAc,CAAC;AACtC,MAAM,cAAc,GAAG,IAAI,GAAG,EAA8B,CAAC;AAE7D,SAAS,OAAO;IACf,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC;YACJ,IAAI,EAAE,CAAC;QACR,CAAC;QAAC,MAAM,CAAC;YACR,+CAA+C;QAChD,CAAC;IACF,CAAC;AACF,CAAC;AAED,SAAS,MAAM;IACd,OAAO,EAAE,CAAC;AACX,CAAC;AAED,SAAS,OAAO;IACf,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,GAAG,EAAE;YACpB,OAAO,EAAE,CAAC;YACV,SAAS,EAAE,CAAC;YACZ,yEAAyE;YACzE,mDAAmD;YACnD,IAAI,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACnC,CAAC;QACF,CAAC,CAAC;QACF,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,CAAC;AACF,CAAC;AAED,SAAS,SAAS;IACjB,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,cAAc,EAAE,CAAC;QAChD,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IACD,cAAc,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC3C,IAAI,KAAK,GAA6B,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;IACnD,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnB,OAAO,GAAG,EAAE;QACX,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtB,KAAK,GAAG,SAAS,CAAC;QAClB,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,SAAS,EAAE,CAAC;IACrC,CAAC,CAAC;AACH,CAAC"}

package/dist/engine/pico8/display.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The DISPLAY MODE seam (ADR-0017): how a PICO-8 `-run` session (a real
+ * audio+video session, today only the audio-record path) gets a display on a
+ * machine that may have none (a server, CI, an agent sandbox).
+ *
+ * - `native`: spawn PICO-8 as-is (it uses whatever DISPLAY/WAYLAND_DISPLAY the
+ *   caller has, or fails to open a window if there is none).
+ * - `xvfb`:   always run a `-run` session on a private virtual X display.
+ * - `auto`:   the default. Use a virtual display only when the session needs one
+ *   and none is available (no DISPLAY and no WAYLAND_DISPLAY); otherwise native.
+ *
+ * Headless `-x` passes (run screenshots, playtest, export, the label capture)
+ * never need a display, so they never consult this module and never pay the
+ * Xvfb startup cost.
+ *
+ * The virtual display prefers spawning `Xvfb -displayfd <fd>` directly: the X
+ * server picks a free display number itself and writes it back on the fd, so
+ * parallel runs never race for a fixed `:99`. When only the Debian `xvfb-run`
+ * script exists, it is the fallback (it wraps the PICO-8 command instead).
+ * Either way the virtual display lives exactly as long as the run.
+ */
+/** The three display modes. `auto` is the default. */
+export declare const DISPLAY_MODES: readonly ["auto", "xvfb", "native"];
+/** A display mode: how a `-run` session gets a display (see the module doc). */
+export type DisplayMode = (typeof DISPLAY_MODES)[number];
+/** The default display mode when no flag, env var or config sets one. */
+export declare const DEFAULT_DISPLAY_MODE: DisplayMode;
+/** The env var that sets the display mode (below the `--display` flag, above picopilot.json). */
+export declare const DISPLAY_ENV_VAR: "PICOPILOT_DISPLAY";
+/** The top-level picopilot.json key that sets the display mode (lowest precedence). */
+export declare const DISPLAY_CONFIG_KEY: "display";
+/** Whether `value` names a valid {@link DisplayMode}. */
+export declare function isDisplayMode(value: unknown): value is DisplayMode;
+/** The outcome of {@link resolveDisplayMode}: a mode and where it came from, or an invalid value. */
+export type DisplayModeResolution = {
+    readonly ok: true;
+    readonly mode: DisplayMode;
+    readonly source: 'flag' | 'env' | 'config' | 'default';
+} | {
+    readonly ok: false;
+    readonly source: 'flag' | 'env' | 'config';
+    readonly value: string;
+};
+/**
+ * Resolves the display mode with the precedence `flag > env > config > default`
+ * (the same order every picopilot setting uses). An empty/whitespace value is
+ * treated as unset; an unknown value is reported (never silently ignored), so a
+ * typo like `PICOPILOT_DISPLAY=xfvb` is a visible error rather than `auto`.
+ */
+export declare function resolveDisplayMode(sources: {
+    readonly flag?: unknown;
+    readonly env?: unknown;
+    readonly config?: unknown;
+}): DisplayModeResolution;
+/** Whether the environment already offers a display (X11 `DISPLAY` or a Wayland socket). */
+export declare function hasNativeDisplay(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether a `-run` session in this `mode` + `env` should run on a virtual
+ * display: always for `xvfb`, never for `native`, and for `auto` only when
+ * there is no native display.
+ */
+export declare function needsVirtualDisplay(mode: DisplayMode, env: NodeJS.ProcessEnv): boolean;
+/**
+ * Finds an executable the way a shell would: a name containing `/` is checked
+ * as a path, anything else is searched on `env.PATH`. Returns the resolved path,
+ * or `undefined`. Pure lookup (no spawn), so it is cheap enough for `doctor` and
+ * for the failure path.
+ */
+export declare function findExecutable(name: string, env: NodeJS.ProcessEnv): string | undefined;
+/** Which virtual-display backend this machine offers, if any (direct Xvfb is preferred). */
+export type VirtualDisplayBackend = 'Xvfb' | 'xvfb-run';
+/** Detects the best available virtual-display backend on `env.PATH`. */
+export declare function detectVirtualDisplayBackend(env: NodeJS.ProcessEnv, find?: (name: string, env: NodeJS.ProcessEnv) => string | undefined): VirtualDisplayBackend | undefined;
+/** The remedy a `display-unavailable` error names. */
+export declare const DISPLAY_REMEDY: "install Xvfb (Debian/Ubuntu: apt install xvfb; Fedora: dnf install xorg-x11-server-Xvfb; NixOS: add xvfb-run or xorg.xvfb), or run under a desktop session (DISPLAY or WAYLAND_DISPLAY set)";
+/**
+ * The structured "this session needs a display and there is none" failure
+ * (mirrors {@link import('./adapter.js').Pico8NotFound}). `detail` says what was
+ * tried (Xvfb missing, or Xvfb failed to start and why).
+ */
+export interface DisplayUnavailable {
+    readonly ok: false;
+    readonly reason: 'display-unavailable';
+    readonly remedy: typeof DISPLAY_REMEDY;
+    readonly detail: string;
+}
+/** Builds a {@link DisplayUnavailable} value. */
+export declare function displayUnavailable(detail: string): DisplayUnavailable;
+/**
+ * A running virtual display, scoped to ONE PICO-8 session. `env` holds the
+ * variables the child must see (DISPLAY for direct Xvfb); `wrap` rewrites the
+ * PICO-8 command (identity for direct Xvfb, `xvfb-run -a ...` for the fallback);
+ * `stop` tears the X server down and is idempotent.
+ */
+export interface VirtualDisplay {
+    readonly backend: VirtualDisplayBackend;
+    readonly env: Readonly<Record<string, string>>;
+    wrap(file: string, args: string[]): {
+        file: string;
+        args: string[];
+    };
+    stop(): Promise<void>;
+}
+/**
+ * A spawned Xvfb process, abstracted so tests inject a fake. `onDisplayFd`
+ * delivers what the server writes on its `-displayfd` pipe (the display number
+ * followed by a newline); `onExit` fires when it exits; `kill` sends a signal.
+ */
+export interface XvfbProcess {
+    readonly pid: number | undefined;
+    onDisplayFd(cb: (chunk: string) => void): void;
+    onStderr(cb: (chunk: string) => void): void;
+    onExit(cb: (code: number | null) => void): void;
+    onError(cb: (err: NodeJS.ErrnoException) => void): void;
+    kill(signal: NodeJS.Signals): void;
+}
+/** The Xvfb spawn seam: tests pass a fake that writes a display number (or never does). */
+export type XvfbSpawner = (file: string, args: string[], env: NodeJS.ProcessEnv) => XvfbProcess;
+/**
+ * The real {@link XvfbSpawner}: stdio `[ignore, ignore, pipe, pipe]` so fd 3 is
+ * the display-number pipe. NOT detached, so a terminal Ctrl-C reaches it with
+ * the rest of picopilot's process group.
+ */
+export declare const spawnXvfb: XvfbSpawner;
+/** Dependencies for {@link startVirtualDisplay}, injectable for tests. */
+export interface VirtualDisplayDeps {
+    /** Locates `Xvfb` / `xvfb-run` (defaults to a PATH search). */
+    readonly find?: (name: string, env: NodeJS.ProcessEnv) => string | undefined;
+    /** Spawns Xvfb (defaults to {@link spawnXvfb}). */
+    readonly spawnXvfb?: XvfbSpawner;
+    /** How long to wait for Xvfb to report its display number (ms). */
+    readonly startTimeoutMs?: number;
+    /** How long to wait after SIGTERM before SIGKILL on stop (ms). */
+    readonly stopGraceMs?: number;
+}
+/**
+ * Starts a private virtual display for one PICO-8 session. Prefers `Xvfb
+ * -displayfd` (no fixed display number, so parallel runs never collide), falls
+ * back to wrapping the command in `xvfb-run -a`, and resolves the structured
+ * {@link DisplayUnavailable} when neither exists or Xvfb fails to start. Never
+ * throws. The returned display MUST be stopped by the caller (the shell adapter
+ * does it in a `finally`); a kill-on-abort hook also kills a direct Xvfb so an
+ * abrupt picopilot exit or signal never leaves one behind.
+ */
+export declare function startVirtualDisplay(env: NodeJS.ProcessEnv, deps?: VirtualDisplayDeps): Promise<{
+    ok: true;
+    display: VirtualDisplay;
+} | DisplayUnavailable>;
+//# sourceMappingURL=display.d.ts.map

package/dist/engine/pico8/display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../../../src/engine/pico8/display.ts"],"names":[],"mappings":"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"}

package/dist/engine/pico8/display.js

@@ -0,0 +1,311 @@
+/**
+ * The DISPLAY MODE seam (ADR-0017): how a PICO-8 `-run` session (a real
+ * audio+video session, today only the audio-record path) gets a display on a
+ * machine that may have none (a server, CI, an agent sandbox).
+ *
+ * - `native`: spawn PICO-8 as-is (it uses whatever DISPLAY/WAYLAND_DISPLAY the
+ *   caller has, or fails to open a window if there is none).
+ * - `xvfb`:   always run a `-run` session on a private virtual X display.
+ * - `auto`:   the default. Use a virtual display only when the session needs one
+ *   and none is available (no DISPLAY and no WAYLAND_DISPLAY); otherwise native.
+ *
+ * Headless `-x` passes (run screenshots, playtest, export, the label capture)
+ * never need a display, so they never consult this module and never pay the
+ * Xvfb startup cost.
+ *
+ * The virtual display prefers spawning `Xvfb -displayfd <fd>` directly: the X
+ * server picks a free display number itself and writes it back on the fd, so
+ * parallel runs never race for a fixed `:99`. When only the Debian `xvfb-run`
+ * script exists, it is the fallback (it wraps the PICO-8 command instead).
+ * Either way the virtual display lives exactly as long as the run.
+ */
+import { spawn } from 'node:child_process';
+import { accessSync, constants, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { killOnAbort } from './cleanup.js';
+/** The three display modes. `auto` is the default. */
+export const DISPLAY_MODES = ['auto', 'xvfb', 'native'];
+/** The default display mode when no flag, env var or config sets one. */
+export const DEFAULT_DISPLAY_MODE = 'auto';
+/** The env var that sets the display mode (below the `--display` flag, above picopilot.json). */
+export const DISPLAY_ENV_VAR = 'PICOPILOT_DISPLAY';
+/** The top-level picopilot.json key that sets the display mode (lowest precedence). */
+export const DISPLAY_CONFIG_KEY = 'display';
+/** Whether `value` names a valid {@link DisplayMode}. */
+export function isDisplayMode(value) {
+    return (typeof value === 'string' &&
+        DISPLAY_MODES.includes(value));
+}
+/**
+ * Resolves the display mode with the precedence `flag > env > config > default`
+ * (the same order every picopilot setting uses). An empty/whitespace value is
+ * treated as unset; an unknown value is reported (never silently ignored), so a
+ * typo like `PICOPILOT_DISPLAY=xfvb` is a visible error rather than `auto`.
+ */
+export function resolveDisplayMode(sources) {
+    const ordered = [
+        ['flag', sources.flag],
+        ['env', sources.env],
+        ['config', sources.config],
+    ];
+    for (const [source, raw] of ordered) {
+        if (raw === undefined || raw === null)
+            continue;
+        const value = String(raw).trim();
+        if (value.length === 0)
+            continue;
+        if (isDisplayMode(value))
+            return { ok: true, mode: value, source };
+        return { ok: false, source, value };
+    }
+    return { ok: true, mode: DEFAULT_DISPLAY_MODE, source: 'default' };
+}
+/** Whether the environment already offers a display (X11 `DISPLAY` or a Wayland socket). */
+export function hasNativeDisplay(env) {
+    const set = (v) => v !== undefined && v.trim() !== '';
+    return set(env.DISPLAY) || set(env.WAYLAND_DISPLAY);
+}
+/**
+ * Whether a `-run` session in this `mode` + `env` should run on a virtual
+ * display: always for `xvfb`, never for `native`, and for `auto` only when
+ * there is no native display.
+ */
+export function needsVirtualDisplay(mode, env) {
+    if (mode === 'xvfb')
+        return true;
+    if (mode === 'native')
+        return false;
+    return !hasNativeDisplay(env);
+}
+/**
+ * Finds an executable the way a shell would: a name containing `/` is checked
+ * as a path, anything else is searched on `env.PATH`. Returns the resolved path,
+ * or `undefined`. Pure lookup (no spawn), so it is cheap enough for `doctor` and
+ * for the failure path.
+ */
+export function findExecutable(name, env) {
+    const isExec = (p) => {
+        try {
+            if (!statSync(p).isFile())
+                return false;
+            accessSync(p, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (name.includes('/'))
+        return isExec(name) ? name : undefined;
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        if (dir === '')
+            continue;
+        const candidate = join(dir, name);
+        if (isExec(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Detects the best available virtual-display backend on `env.PATH`. */
+export function detectVirtualDisplayBackend(env, find = findExecutable) {
+    if (find('Xvfb', env) !== undefined)
+        return 'Xvfb';
+    if (find('xvfb-run', env) !== undefined)
+        return 'xvfb-run';
+    return undefined;
+}
+/** The remedy a `display-unavailable` error names. */
+export const DISPLAY_REMEDY = 'install Xvfb (Debian/Ubuntu: apt install xvfb; Fedora: dnf install xorg-x11-server-Xvfb; NixOS: add xvfb-run or xorg.xvfb), or run under a desktop session (DISPLAY or WAYLAND_DISPLAY set)';
+/** Builds a {@link DisplayUnavailable} value. */
+export function displayUnavailable(detail) {
+    return {
+        ok: false,
+        reason: 'display-unavailable',
+        remedy: DISPLAY_REMEDY,
+        detail,
+    };
+}
+/** The fd number Xvfb writes its display number to (`-displayfd 3`). */
+const DISPLAY_FD = 3;
+/** The screen geometry for the virtual display (PICO-8's default window fits easily). */
+const XVFB_SCREEN = '640x540x24';
+/**
+ * The real {@link XvfbSpawner}: stdio `[ignore, ignore, pipe, pipe]` so fd 3 is
+ * the display-number pipe. NOT detached, so a terminal Ctrl-C reaches it with
+ * the rest of picopilot's process group.
+ */
+export const spawnXvfb = (file, args, env) => {
+    const child = spawn(file, args, {
+        env,
+        stdio: ['ignore', 'ignore', 'pipe', 'pipe'],
+    });
+    const fd = child.stdio[DISPLAY_FD];
+    fd?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    return {
+        pid: child.pid,
+        onDisplayFd(cb) {
+            fd?.on('data', cb);
+        },
+        onStderr(cb) {
+            child.stderr?.on('data', cb);
+        },
+        onExit(cb) {
+            child.on('exit', cb);
+        },
+        onError(cb) {
+            child.on('error', cb);
+        },
+        kill(signal) {
+            try {
+                child.kill(signal);
+            }
+            catch {
+                // already gone
+            }
+        },
+    };
+};
+/** The default time Xvfb gets to come up before the start is declared failed. */
+const DEFAULT_XVFB_START_TIMEOUT_MS = 10_000;
+/** The default time Xvfb gets to exit on SIGTERM before SIGKILL. */
+const DEFAULT_XVFB_STOP_GRACE_MS = 2_000;
+/**
+ * Starts a private virtual display for one PICO-8 session. Prefers `Xvfb
+ * -displayfd` (no fixed display number, so parallel runs never collide), falls
+ * back to wrapping the command in `xvfb-run -a`, and resolves the structured
+ * {@link DisplayUnavailable} when neither exists or Xvfb fails to start. Never
+ * throws. The returned display MUST be stopped by the caller (the shell adapter
+ * does it in a `finally`); a kill-on-abort hook also kills a direct Xvfb so an
+ * abrupt picopilot exit or signal never leaves one behind.
+ */
+export async function startVirtualDisplay(env, deps = {}) {
+    const find = deps.find ?? findExecutable;
+    const xvfb = find('Xvfb', env);
+    if (xvfb !== undefined) {
+        return startDirectXvfb(xvfb, env, deps);
+    }
+    const xvfbRun = find('xvfb-run', env);
+    if (xvfbRun !== undefined) {
+        return { ok: true, display: xvfbRunDisplay(xvfbRun) };
+    }
+    return displayUnavailable('there is no display (DISPLAY and WAYLAND_DISPLAY are unset) and neither Xvfb nor xvfb-run is on PATH to provide a virtual one');
+}
+/**
+ * The `xvfb-run` fallback: no server to manage here, the script starts Xvfb,
+ * runs the command with DISPLAY set, and kills Xvfb when the command exits. The
+ * whole thing runs in PICO-8's process group, so the adapter's group kill
+ * (sentinel / backstop) takes Xvfb down with it.
+ */
+function xvfbRunDisplay(xvfbRun) {
+    return {
+        backend: 'xvfb-run',
+        env: {},
+        wrap(file, args) {
+            return {
+                file: xvfbRun,
+                args: [
+                    '-a',
+                    '-s',
+                    `-screen 0 ${XVFB_SCREEN} -nolisten tcp`,
+                    file,
+                    ...args,
+                ],
+            };
+        },
+        async stop() { },
+    };
+}
+/** Starts `Xvfb -displayfd 3` and waits for it to report the display number it picked. */
+function startDirectXvfb(file, env, deps) {
+    const spawner = deps.spawnXvfb ?? spawnXvfb;
+    const startTimeoutMs = deps.startTimeoutMs ?? DEFAULT_XVFB_START_TIMEOUT_MS;
+    const stopGraceMs = deps.stopGraceMs ?? DEFAULT_XVFB_STOP_GRACE_MS;
+    const args = [
+        '-displayfd',
+        String(DISPLAY_FD),
+        '-screen',
+        '0',
+        XVFB_SCREEN,
+        '-nolisten',
+        'tcp',
+    ];
+    return new Promise((resolve) => {
+        let exited = false;
+        let settled = false;
+        let fdText = '';
+        let stderr = '';
+        const exitWaiters = [];
+        let timer;
+        const proc = spawner(file, args, env);
+        // Safety net: if picopilot exits or is signalled mid-run, kill the server
+        // synchronously so no stray Xvfb is left behind.
+        const disposeAbort = killOnAbort(() => proc.kill('SIGKILL'));
+        const stop = () => {
+            disposeAbort();
+            if (exited)
+                return Promise.resolve();
+            return new Promise((done) => {
+                exitWaiters.push(done);
+                proc.kill('SIGTERM');
+                const hard = setTimeout(() => {
+                    if (!exited)
+                        proc.kill('SIGKILL');
+                }, stopGraceMs);
+                exitWaiters.push(() => clearTimeout(hard));
+            });
+        };
+        const fail = (detail) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            void stop().then(() => resolve(displayUnavailable(detail)));
+        };
+        proc.onExit(() => {
+            exited = true;
+            for (const w of exitWaiters.splice(0))
+                w();
+            if (!settled) {
+                disposeAbort();
+                fail(`Xvfb exited before reporting a display${stderrTail(stderr)}`);
+            }
+        });
+        proc.onError((err) => {
+            exited = true;
+            for (const w of exitWaiters.splice(0))
+                w();
+            fail(`Xvfb failed to start (${err.code ?? err.message})`);
+        });
+        proc.onStderr((chunk) => {
+            stderr += chunk;
+        });
+        proc.onDisplayFd((chunk) => {
+            if (settled)
+                return;
+            fdText += chunk;
+            const m = /^\s*(\d+)\s*\n/.exec(fdText);
+            if (m === null)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const display = `:${m[1]}`;
+            resolve({
+                ok: true,
+                display: {
+                    backend: 'Xvfb',
+                    env: { DISPLAY: display },
+                    wrap: (f, a) => ({ file: f, args: a }),
+                    stop,
+                },
+            });
+        });
+        timer = setTimeout(() => fail(`Xvfb did not report a display within ${startTimeoutMs}ms${stderrTail(stderr)}`), startTimeoutMs);
+    });
+}
+/** The last few lines of Xvfb's stderr, as a `: ...` suffix (or empty). */
+function stderrTail(stderr) {
+    const lines = stderr.trim().split('\n').filter(Boolean).slice(-3);
+    return lines.length === 0 ? '' : `: ${lines.join(' | ')}`;
+}
+//# sourceMappingURL=display.js.map

package/dist/engine/pico8/display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.js","sourceRoot":"","sources":["../../../src/engine/pico8/display.ts"],"names":[],"mappings":"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"}

package/dist/engine/pico8/drive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../../src/engine/pico8/drive.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../../src/engine/pico8/drive.ts"],"names":[],"mappings":"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"}

package/dist/engine/pico8/drive.js

@@ -353,13 +353,39 @@ export function resolveIncludes(lua, readInclude, seen = new Set()) {
         const path = m[1];
         if (seen.has(path))
             return line; // cycle guard: leave it
-        const content = readInclude(path);
-        if (content === undefined)
+        // `#include other.p8` takes that cart's code, `other.p8:n` only tab n.
+        const p8 = /^(.+\.p8)(?::(\d+))?$/i.exec(path);
+        const raw = readInclude(p8 !== null ? p8[1] : path);
+        if (raw === undefined)
             return line; // unreadable: leave verbatim
+        const content = p8 !== null ? p8Code(raw, p8[2]) : raw;
+        if (content === undefined)
+            return line;
         return resolveIncludes(content, readInclude, new Set([...seen, path]));
     })
         .join('\n');
 }
+/**
+ * The code an `#include` of a `.p8` cart pulls in: its `__lua__` section, or
+ * only tab `tab` (tabs are separated by `-->8` lines). `undefined` when the
+ * text does not parse as a cart or the tab does not exist.
+ */
+function p8Code(cartText, tab) {
+    let lua;
+    try {
+        lua = Cart.parse(cartText).getSection('lua');
+    }
+    catch {
+        return undefined;
+    }
+    if (lua === undefined)
+        return undefined;
+    const body = lua.replace(/\n$/, '');
+    if (tab === undefined)
+        return body;
+    const tabs = body.split(/\r?\n-->8\r?\n/);
+    return tabs[Number(tab)];
+}
 /** The default base filename SHOT names each screenshot (`play0.png`, ...). */
 export const SHOT_BASENAME = 'play';
 /**