@textui/testing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Softov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @textui/testing
+
+A headless harness for TextUI applications. No terminal, no timers, no
+snapshots of a screen nobody looked at.
+
+```bash
+npm install --save-dev @textui/testing
+```
+
+```ts
+import { renderApp } from '@textui/testing';
+
+const t = await renderApp(<App />, { width: 80, height: 24 });
+
+expect(t.getByRole('button', { name: 'Save' }).focused).toBe(true);
+t.press('enter');
+await t.settle();
+expect(t.text()).toContain('Saved');
+```
+
+## Query by what it is, not where it is
+
+Every component declares a semantic role, so a test asks the way a person would
+- the Save button, the row labelled `api` - rather than by index into a tree
+that changes the moment the layout does.
+
+| | |
+|---|---|
+| `getByRole(role, { name })` | The one with that role and accessible name |
+| `getByLabel` / `getByText` | By label, or by rendered text |
+| `getByComponent(name)` | The escape hatch, when the role is not the point |
+| `text()`, `line(y)`, `lines()` | What is actually on the screen |
+| `tree()` | The instance tree, for when the pixels are not the question |
+
+An `Element` is a description - role, label, text, rect, focus, props - not a
+handle. You act on the application with keys, the way a person does.
+
+`get*` throws with the near misses listed; `query*` returns null.
+
+## Drive it, then let it settle
+
+`press('ctrl+s')`, `pressAll('down', 'down', 'enter')`, `type('hello')`, and
+`resize(w, h)`. Effects and re-renders are asynchronous, so `await t.settle()`
+is what separates "I sent the key" from "the screen caught up".
+
+## Test at two sizes
+
+A single fixed size skips every breakpoint and hides the layout break you were
+trying to catch. `resize` is cheap, and a loop over two sizes costs one line:
+
+```ts
+for (const size of [{ width: 100, height: 30 }, { width: 60, height: 18 }]) {
+  it(`fits at ${size.width}x${size.height}`, async () => { /* ... */ });
+}
+```
+
+## Runtime
+
+Depends on `@textui/core` and `@textui/terminal`. No `node:` imports - it runs
+on the virtual terminal, so there is no tty to have. Node 22+ and Bun.
+
+## Documentation
+
+<https://softov.github.io/textui/>

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+import type { CapabilityOverrides, ComponentDefinition, ComponentNode, Disposable, InspectorNode, KeyEvent, TextUIApp, ReactiveStore, SemanticRole, ThemeDefinition } from '@textui/core';
+import { strokeOf } from '@textui/core';
+import { type VirtualTerminalAdapter } from '@textui/terminal';
+/**
+ * The testing harness.
+ *
+ * It drives a real application against a virtual terminal, so what a test
+ * asserts is what a terminal would receive. Queries are semantic first -
+ * by role, by label, by text - because a test pinned to exact ANSI output
+ * fails on every legitimate change and passes on none of the interesting bugs.
+ * Snapshots are still here for when the layout itself is the thing under test.
+ */
+export interface RenderOptions {
+    width?: number;
+    height?: number;
+    theme?: string;
+    themes?: ThemeDefinition[];
+    shell?: string;
+    components?: ComponentDefinition[];
+    capabilities?: CapabilityOverrides;
+    locale?: string;
+    initialState?: Record<string, unknown>;
+    /** Register the shipped catalog. On by default. */
+    builtins?: boolean;
+    /**
+     * Run boot registration before the first frame.
+     *
+     * Mirrors the application's own `onBoot`, disposable and all - a harness
+     * whose boot contract is narrower than the real one is a harness that
+     * cannot test what the real one does.
+     */
+    onBoot?(app: TextUIApp): void | Disposable | Promise<void | Disposable>;
+    /** Encode frames to ANSI as a real terminal session would. Off by default. */
+    encode?: boolean;
+    /** Collect errors instead of printing them. On by default. */
+    captureErrors?: boolean;
+    /**
+     * Whether anything is allowed to move. On by default, and driven by hand -
+     * `advance` is the clock.
+     *
+     * Off is the reader who asked for stillness, and it is a behaviour worth
+     * testing rather than assuming: a component that animates has a second
+     * rendering nobody sees until somebody sets this.
+     */
+    animations?: boolean;
+}
+export interface QueryOptions {
+    /** Match the whole string rather than a substring. */
+    exact?: boolean;
+}
+export interface Element {
+    id: string;
+    component: string;
+    role?: string;
+    label?: string;
+    text?: string;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    focused: boolean;
+    props: Record<string, unknown>;
+    children: Element[];
+}
+export interface Harness {
+    readonly app: TextUIApp;
+    readonly store: ReactiveStore;
+    readonly terminal: VirtualTerminalAdapter;
+    /** The frame as plain text, trailing spaces trimmed. */
+    text(): string;
+    /** One row of the frame. */
+    line(y: number): string;
+    /** Every line, as an array. */
+    lines(): string[];
+    /** The encoded bytes written since the last `clearOutput`. */
+    output(): string;
+    clearOutput(): void;
+    /** The semantic tree, for structural assertions. */
+    tree(): InspectorNode | null;
+    getByRole(role: SemanticRole, options?: QueryOptions & {
+        name?: string;
+    }): Element;
+    queryByRole(role: SemanticRole, options?: QueryOptions & {
+        name?: string;
+    }): Element | null;
+    getAllByRole(role: SemanticRole): Element[];
+    getByLabel(label: string, options?: QueryOptions): Element;
+    queryByLabel(label: string, options?: QueryOptions): Element | null;
+    getByText(text: string, options?: QueryOptions): Element;
+    queryByText(text: string, options?: QueryOptions): Element | null;
+    getAllByText(text: string, options?: QueryOptions): Element[];
+    getByComponent(name: string): Element;
+    getAllByComponent(name: string): Element[];
+    /** True when the text appears anywhere in the frame. */
+    hasText(text: string): boolean;
+    /** Send one chord: `a`, `enter`, `ctrl+p`, `shift+tab`. */
+    press(chord: string): void;
+    /** Send several chords in order. */
+    pressAll(...chords: string[]): void;
+    /** Type a string, one key at a time. */
+    type(text: string): void;
+    paste(text: string): void;
+    click(x: number, y: number, button?: 'left' | 'middle' | 'right'): void;
+    /** Click the centre of an element. */
+    clickOn(element: Element): void;
+    moveMouse(x: number, y: number): void;
+    wheel(x: number, y: number, delta: number): void;
+    focusTerminal(focused: boolean): void;
+    /** Feed raw terminal bytes, exercising the decoder too. */
+    feed(data: string): void;
+    resize(width: number, height: number): void;
+    setCapabilities(overrides: CapabilityOverrides): void;
+    setTheme(id: string): void;
+    setShell(id: string): void;
+    /** Advance the animation clock and render. */
+    advance(ms: number): void;
+    /** Render now, outside the scheduler. */
+    flush(): void;
+    /** Let queued promises settle, then render. */
+    settle(): Promise<void>;
+    focused(): Element | null;
+    focus(id: string): void;
+    tab(): void;
+    shiftTab(): void;
+    errors(): {
+        context: string;
+        message: string;
+    }[];
+    stats(): {
+        renders: number;
+        runs: number;
+        instances: number;
+    };
+    unmount(): Promise<void>;
+}
+/** A harness that has already started. */
+export declare function render(node: ComponentNode, options?: RenderOptions): Promise<Harness>;
+/** Mount an application rather than a bare node. */
+export declare function renderApp(options?: RenderOptions & {
+    root?: ComponentNode;
+}): Promise<Harness>;
+/** `ctrl+shift+p`, `enter`, `a`. The inverse of `strokeOf`. */
+export declare function chordToEvents(chord: string): KeyEvent[];
+export { strokeOf };
+/**
+ * A stable text snapshot: the frame, with a ruler, so a diff shows which
+ * column moved rather than only that something did.
+ */
+export declare function snapshot(harness: Harness, options?: {
+    ruler?: boolean;
+}): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,314 @@
+import { WRITER_KEY, createApp, strokeOf, splitStroke, createBag } from '@textui/core';
+import { registerBuiltins } from '@textui/widgets';
+import { createVirtualTerminal, createWriter } from '@textui/terminal';
+/** A harness that has already started. */
+export async function render(node, options = {}) {
+    return mount({ ...options, root: node });
+}
+/** Mount an application rather than a bare node. */
+export async function renderApp(options = {}) {
+    return mount(options);
+}
+async function mount(options) {
+    const width = options.width ?? 80;
+    const height = options.height ?? 24;
+    const terminal = createVirtualTerminal({
+        width,
+        height,
+        capabilities: options.capabilities,
+        managed: false,
+    });
+    const errors = [];
+    const app = createApp({
+        terminal,
+        root: options.root,
+        // Only pass a theme when the caller named one, so a shell's own default
+        // still applies - passing 'dark' here would silently override it.
+        ...(options.theme ? { theme: options.theme } : {}),
+        themes: options.themes,
+        shell: options.shell ?? 'plain',
+        locale: options.locale,
+        animations: options.animations ?? true,
+        diagnostics: true,
+        session: { managed: false, altScreen: false, hideCursor: false },
+        onBoot: async (booted) => {
+            // Everything registered here comes back out when the app stops, which
+            // matters for a harness more than for an application: a test file
+            // mounts and unmounts dozens of times in one process.
+            const bag = createBag();
+            if (options.builtins !== false)
+                bag.add(registerBuiltins(booted));
+            if (options.components)
+                bag.add(booted.components.registerMany(options.components));
+            if (options.initialState) {
+                booted.store.batch(() => {
+                    for (const [path, value] of Object.entries(options.initialState)) {
+                        booted.store.set((path.startsWith('$/') ? path : `$/${path}`), value);
+                    }
+                });
+            }
+            const booted_ = await options.onBoot?.(booted);
+            if (booted_)
+                bag.add(booted_);
+            return bag;
+        },
+    });
+    if (options.encode) {
+        app.services.provide(WRITER_KEY, createWriter(terminal.capabilities()));
+    }
+    app.store.subscribe('$/modus/diagnostics/errors', (value) => {
+        const list = Array.isArray(value) ? value : [];
+        errors.length = 0;
+        for (const entry of list) {
+            errors.push(entry);
+        }
+    }, { subtree: true });
+    await app.start();
+    app.flush();
+    return createHarness(app, terminal, errors);
+}
+function createHarness(app, terminal, errors) {
+    const flush = () => app.flush();
+    const collect = (predicate) => {
+        const tree = app.inspect();
+        if (!tree)
+            return [];
+        const found = [];
+        const walk = (node) => {
+            if (predicate(node))
+                found.push(toElement(node));
+            for (const child of node.children)
+                walk(child);
+        };
+        walk(tree);
+        return found;
+    };
+    const textOf = (node) => {
+        const parts = [];
+        const walk = (n) => {
+            if (typeof n.text === 'string')
+                parts.push(n.text);
+            for (const child of n.children)
+                walk(child);
+        };
+        walk(node);
+        return parts.join(' ');
+    };
+    const matches = (haystack, needle, exact) => {
+        if (haystack === undefined)
+            return false;
+        return exact ? haystack === needle : haystack.includes(needle);
+    };
+    const require1 = (found, what) => {
+        if (found.length === 0) {
+            throw new Error(`[textui/testing] no element matching ${what}\n\n${app.buffer().toText()}`);
+        }
+        if (found.length > 1) {
+            const list = found.map((e) => `  <${e.component}> ${e.label ?? e.text ?? ''}`).join('\n');
+            throw new Error(`[textui/testing] ${found.length} elements match ${what}; narrow the query\n${list}`);
+        }
+        return found[0];
+    };
+    const sendKey = (chord) => {
+        for (const event of chordToEvents(chord))
+            app.handleInput(event);
+        flush();
+    };
+    return {
+        app,
+        store: app.store,
+        terminal,
+        text: () => app.buffer().toText(),
+        line: (y) => app.buffer().toText().split('\n')[y] ?? '',
+        lines: () => app.buffer().toText().split('\n'),
+        output: () => terminal.output(),
+        clearOutput: () => terminal.clearOutput(),
+        tree: () => app.inspect(),
+        getByRole(role, options = {}) {
+            const found = collect((n) => n.role === role && (options.name === undefined || matches(n.label ?? textOf(n), options.name, options.exact)));
+            return require1(found, `role "${role}"${options.name ? ` named "${options.name}"` : ''}`);
+        },
+        queryByRole(role, options = {}) {
+            const found = collect((n) => n.role === role && (options.name === undefined || matches(n.label ?? textOf(n), options.name, options.exact)));
+            return found[0] ?? null;
+        },
+        getAllByRole: (role) => collect((n) => n.role === role),
+        getByLabel(label, options = {}) {
+            return require1(collect((n) => matches(n.label, label, options.exact)), `label "${label}"`);
+        },
+        queryByLabel(label, options = {}) {
+            return collect((n) => matches(n.label, label, options.exact))[0] ?? null;
+        },
+        getByText(text, options = {}) {
+            return require1(collect((n) => matches(n.text, text, options.exact)), `text "${text}"`);
+        },
+        queryByText(text, options = {}) {
+            return collect((n) => matches(n.text, text, options.exact))[0] ?? null;
+        },
+        getAllByText: (text, options = {}) => collect((n) => matches(n.text, text, options.exact)),
+        getByComponent(name) {
+            return require1(collect((n) => n.component === name), `component <${name}>`);
+        },
+        getAllByComponent: (name) => collect((n) => n.component === name),
+        hasText: (text) => app.buffer().toText().includes(text),
+        press: sendKey,
+        pressAll(...chords) {
+            for (const chord of chords)
+                sendKey(chord);
+        },
+        type(text) {
+            for (const char of [...text]) {
+                app.handleInput({
+                    type: 'key', name: char, char, raw: char,
+                    ctrl: false, alt: false, meta: false,
+                    shift: char !== char.toLowerCase(),
+                    handled: false,
+                });
+            }
+            flush();
+        },
+        paste(text) {
+            app.handleInput({ type: 'paste', text, handled: false });
+            flush();
+        },
+        click(x, y, button = 'left') {
+            app.handleInput({ type: 'mouse', action: 'down', button, x, y, ctrl: false, alt: false, shift: false, handled: false });
+            app.handleInput({ type: 'mouse', action: 'up', button, x, y, ctrl: false, alt: false, shift: false, handled: false });
+            flush();
+        },
+        clickOn(element) {
+            const rect = element.rect;
+            if (!rect)
+                throw new Error(`[textui/testing] <${element.component}> has no bounds to click`);
+            this.click(rect.x + Math.floor(rect.width / 2), rect.y + Math.floor(rect.height / 2));
+        },
+        moveMouse(x, y) {
+            app.handleInput({ type: 'mouse', action: 'move', button: 'none', x, y, ctrl: false, alt: false, shift: false, handled: false });
+            flush();
+        },
+        wheel(x, y, delta) {
+            app.handleInput({ type: 'mouse', action: 'wheel', button: 'none', x, y, wheel: delta, ctrl: false, alt: false, shift: false, handled: false });
+            flush();
+        },
+        focusTerminal(focused) {
+            app.handleInput({ type: 'terminal-focus', focused });
+            flush();
+        },
+        feed(data) {
+            terminal.feed(data);
+            flush();
+        },
+        resize(width, height) {
+            terminal.resize(width, height);
+            flush();
+        },
+        setCapabilities(overrides) {
+            app.setCapabilityOverrides(overrides);
+            flush();
+        },
+        setTheme(id) {
+            app.setTheme(id);
+            flush();
+        },
+        setShell(id) {
+            app.setShell(id);
+            flush();
+        },
+        advance(ms) {
+            app.animation.advance(ms);
+            flush();
+        },
+        flush,
+        async settle() {
+            // Two turns: one for the promise that is pending, one for whatever it
+            // schedules. Anything deeper is a test that should await explicitly.
+            await Promise.resolve();
+            await new Promise((resolve) => setImmediate(resolve));
+            // And one turn of the clock, which is the one that waits for the disk.
+            //
+            // `setImmediate` runs in the check phase, and the loop never blocks to
+            // get there - so a run of settles is a spin, costing microseconds and
+            // giving a `stat` or a `readdir` no opportunity to come back. Tests wait
+            // by counting settles, so the budget ends up denominated in turns of the
+            // loop while the thing being waited for is denominated in milliseconds:
+            // they pass on an idle machine and fail on a busy one, which is the
+            // shape of every flake this helper has produced. A pending timer makes
+            // the poll phase block, and pending I/O lands.
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            flush();
+        },
+        focused() {
+            const id = app.focus.focused();
+            if (!id)
+                return null;
+            const found = collect((n) => n.focused === true);
+            return found[0] ?? null;
+        },
+        focus(id) {
+            app.focus.focus(id);
+            flush();
+        },
+        tab: () => sendKey('tab'),
+        shiftTab: () => sendKey('shift+tab'),
+        errors: () => [...errors],
+        stats: () => app.stats(),
+        async unmount() {
+            await app.stop();
+            app.dispose();
+        },
+    };
+}
+function toElement(node) {
+    return {
+        id: node.id,
+        component: node.component,
+        role: node.role,
+        label: node.label,
+        text: node.text,
+        rect: node.rect,
+        focused: node.focused === true,
+        props: node.props,
+        children: node.children.map(toElement),
+    };
+}
+/** `ctrl+shift+p`, `enter`, `a`. The inverse of `strokeOf`. */
+export function chordToEvents(chord) {
+    return chord
+        .trim()
+        .split(/\s+/)
+        .map((stroke) => {
+        // The registry's parser, not a second one: a chord pressed here has to
+        // produce the stroke the registry stored it under, or a binding that
+        // works in a terminal fails in a test and nobody can tell which is right.
+        const { mods: names, key } = splitStroke(stroke);
+        const mods = new Set(names);
+        // `space` is named and printable at once - the decoder emits both, and a
+        // press that gave only the name could not be typed into a field.
+        const char = key === 'space' ? ' ' : ([...key].length === 1 ? key : undefined);
+        return {
+            type: 'key',
+            name: key,
+            char,
+            ctrl: mods.has('ctrl') || mods.has('control'),
+            alt: mods.has('alt') || mods.has('option'),
+            shift: mods.has('shift'),
+            meta: mods.has('meta') || mods.has('cmd') || mods.has('super'),
+            raw: stroke,
+            handled: false,
+        };
+    });
+}
+export { strokeOf };
+/**
+ * A stable text snapshot: the frame, with a ruler, so a diff shows which
+ * column moved rather than only that something did.
+ */
+export function snapshot(harness, options = {}) {
+    const lines = harness.lines();
+    if (!options.ruler)
+        return lines.join('\n');
+    const width = Math.max(0, ...lines.map((l) => l.length));
+    const tens = Array.from({ length: width }, (_, i) => (i % 10 === 0 ? String((i / 10) % 10) : ' ')).join('');
+    const ones = Array.from({ length: width }, (_, i) => String(i % 10)).join('');
+    return [tens, ones, ...lines].join('\n');
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@textui/testing",
+  "version": "0.1.0",
+  "description": "Headless testing harness for TextUI - semantic queries, input, resizing, time",
+  "keywords": [
+    "terminal",
+    "tui",
+    "testing",
+    "test-harness",
+    "headless",
+    "vitest",
+    "snapshot"
+  ],
+  "homepage": "https://softov.github.io/textui/",
+  "bugs": {
+    "url": "https://github.com/softov/textui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/softov/textui.git",
+    "directory": "packages/testing"
+  },
+  "license": "MIT",
+  "author": "Softov <softov@brbyte.com>",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@textui/widgets": "^0.1.0",
+    "@textui/terminal": "^0.1.0",
+    "@textui/core": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,504 @@
+import type {
+  CapabilityOverrides,
+  ComponentDefinition,
+  ComponentNode,
+  Disposable,
+  InspectorNode,
+  KeyEvent,
+  TextUIApp,
+  ReactiveStore,
+  SemanticRole,
+  ThemeDefinition,
+} from '@textui/core';
+import { WRITER_KEY, createApp, strokeOf, splitStroke, type App, createBag } from '@textui/core';
+import { registerBuiltins } from '@textui/widgets';
+import { createVirtualTerminal, createWriter, type VirtualTerminalAdapter } from '@textui/terminal';
+
+/**
+ * The testing harness.
+ *
+ * It drives a real application against a virtual terminal, so what a test
+ * asserts is what a terminal would receive. Queries are semantic first -
+ * by role, by label, by text - because a test pinned to exact ANSI output
+ * fails on every legitimate change and passes on none of the interesting bugs.
+ * Snapshots are still here for when the layout itself is the thing under test.
+ */
+
+export interface RenderOptions {
+  width?: number;
+  height?: number;
+  theme?: string;
+  themes?: ThemeDefinition[];
+  shell?: string;
+  components?: ComponentDefinition[];
+  capabilities?: CapabilityOverrides;
+  locale?: string;
+  initialState?: Record<string, unknown>;
+  /** Register the shipped catalog. On by default. */
+  builtins?: boolean;
+  /**
+   * Run boot registration before the first frame.
+   *
+   * Mirrors the application's own `onBoot`, disposable and all - a harness
+   * whose boot contract is narrower than the real one is a harness that
+   * cannot test what the real one does.
+   */
+  onBoot?(app: TextUIApp): void | Disposable | Promise<void | Disposable>;
+  /** Encode frames to ANSI as a real terminal session would. Off by default. */
+  encode?: boolean;
+  /** Collect errors instead of printing them. On by default. */
+  captureErrors?: boolean;
+  /**
+   * Whether anything is allowed to move. On by default, and driven by hand -
+   * `advance` is the clock.
+   *
+   * Off is the reader who asked for stillness, and it is a behaviour worth
+   * testing rather than assuming: a component that animates has a second
+   * rendering nobody sees until somebody sets this.
+   */
+  animations?: boolean;
+}
+
+export interface QueryOptions {
+  /** Match the whole string rather than a substring. */
+  exact?: boolean;
+}
+
+export interface Element {
+  id: string;
+  component: string;
+  role?: string;
+  label?: string;
+  text?: string;
+  rect?: { x: number; y: number; width: number; height: number };
+  focused: boolean;
+  props: Record<string, unknown>;
+  children: Element[];
+}
+
+export interface Harness {
+  readonly app: TextUIApp;
+  readonly store: ReactiveStore;
+  readonly terminal: VirtualTerminalAdapter;
+
+  // --- output ---
+  /** The frame as plain text, trailing spaces trimmed. */
+  text(): string;
+  /** One row of the frame. */
+  line(y: number): string;
+  /** Every line, as an array. */
+  lines(): string[];
+  /** The encoded bytes written since the last `clearOutput`. */
+  output(): string;
+  clearOutput(): void;
+  /** The semantic tree, for structural assertions. */
+  tree(): InspectorNode | null;
+
+  // --- queries ---
+  getByRole(role: SemanticRole, options?: QueryOptions & { name?: string }): Element;
+  queryByRole(role: SemanticRole, options?: QueryOptions & { name?: string }): Element | null;
+  getAllByRole(role: SemanticRole): Element[];
+  getByLabel(label: string, options?: QueryOptions): Element;
+  queryByLabel(label: string, options?: QueryOptions): Element | null;
+  getByText(text: string, options?: QueryOptions): Element;
+  queryByText(text: string, options?: QueryOptions): Element | null;
+  getAllByText(text: string, options?: QueryOptions): Element[];
+  getByComponent(name: string): Element;
+  getAllByComponent(name: string): Element[];
+  /** True when the text appears anywhere in the frame. */
+  hasText(text: string): boolean;
+
+  // --- input ---
+  /** Send one chord: `a`, `enter`, `ctrl+p`, `shift+tab`. */
+  press(chord: string): void;
+  /** Send several chords in order. */
+  pressAll(...chords: string[]): void;
+  /** Type a string, one key at a time. */
+  type(text: string): void;
+  paste(text: string): void;
+  click(x: number, y: number, button?: 'left' | 'middle' | 'right'): void;
+  /** Click the centre of an element. */
+  clickOn(element: Element): void;
+  moveMouse(x: number, y: number): void;
+  wheel(x: number, y: number, delta: number): void;
+  focusTerminal(focused: boolean): void;
+  /** Feed raw terminal bytes, exercising the decoder too. */
+  feed(data: string): void;
+
+  // --- environment ---
+  resize(width: number, height: number): void;
+  setCapabilities(overrides: CapabilityOverrides): void;
+  setTheme(id: string): void;
+  setShell(id: string): void;
+
+  // --- time ---
+  /** Advance the animation clock and render. */
+  advance(ms: number): void;
+  /** Render now, outside the scheduler. */
+  flush(): void;
+  /** Let queued promises settle, then render. */
+  settle(): Promise<void>;
+
+  // --- focus ---
+  focused(): Element | null;
+  focus(id: string): void;
+  tab(): void;
+  shiftTab(): void;
+
+  // --- diagnostics ---
+  errors(): { context: string; message: string }[];
+  stats(): { renders: number; runs: number; instances: number };
+
+  unmount(): Promise<void>;
+}
+
+/** A harness that has already started. */
+export async function render(
+  node: ComponentNode,
+  options: RenderOptions = {},
+): Promise<Harness> {
+  return mount({ ...options, root: node });
+}
+
+/** Mount an application rather than a bare node. */
+export async function renderApp(
+  options: RenderOptions & { root?: ComponentNode } = {},
+): Promise<Harness> {
+  return mount(options);
+}
+
+async function mount(options: RenderOptions & { root?: ComponentNode }): Promise<Harness> {
+  const width = options.width ?? 80;
+  const height = options.height ?? 24;
+
+  const terminal = createVirtualTerminal({
+    width,
+    height,
+    capabilities: options.capabilities,
+    managed: false,
+  });
+
+  const errors: { context: string; message: string }[] = [];
+
+  const app = createApp({
+    terminal,
+    root: options.root,
+    // Only pass a theme when the caller named one, so a shell's own default
+    // still applies - passing 'dark' here would silently override it.
+    ...(options.theme ? { theme: options.theme } : {}),
+    themes: options.themes,
+    shell: options.shell ?? 'plain',
+    locale: options.locale,
+    animations: options.animations ?? true,
+    diagnostics: true,
+    session: { managed: false, altScreen: false, hideCursor: false },
+    onBoot: async (booted) => {
+      // Everything registered here comes back out when the app stops, which
+      // matters for a harness more than for an application: a test file
+      // mounts and unmounts dozens of times in one process.
+      const bag = createBag();
+      if (options.builtins !== false) bag.add(registerBuiltins(booted));
+      if (options.components) bag.add(booted.components.registerMany(options.components));
+      if (options.initialState) {
+        booted.store.batch(() => {
+          for (const [path, value] of Object.entries(options.initialState as object)) {
+            booted.store.set((path.startsWith('$/') ? path : `$/${path}`) as `$/${string}`, value);
+          }
+        });
+      }
+      const booted_ = await options.onBoot?.(booted);
+      if (booted_) bag.add(booted_);
+      return bag;
+    },
+  });
+
+  if (options.encode) {
+    app.services.provide(WRITER_KEY, createWriter(terminal.capabilities()));
+  }
+
+  app.store.subscribe(
+    '$/modus/diagnostics/errors',
+    (value) => {
+      const list = Array.isArray(value) ? value : [];
+      errors.length = 0;
+      for (const entry of list) {
+        errors.push(entry as { context: string; message: string });
+      }
+    },
+    { subtree: true },
+  );
+
+  await app.start();
+  app.flush();
+
+  return createHarness(app as App, terminal, errors);
+}
+
+function createHarness(
+  app: App,
+  terminal: VirtualTerminalAdapter,
+  errors: { context: string; message: string }[],
+): Harness {
+  const flush = (): void => app.flush();
+
+  const collect = (predicate: (node: InspectorNode) => boolean): Element[] => {
+    const tree = app.inspect();
+    if (!tree) return [];
+    const found: Element[] = [];
+    const walk = (node: InspectorNode): void => {
+      if (predicate(node)) found.push(toElement(node));
+      for (const child of node.children) walk(child);
+    };
+    walk(tree);
+    return found;
+  };
+
+  const textOf = (node: InspectorNode): string => {
+    const parts: string[] = [];
+    const walk = (n: InspectorNode): void => {
+      if (typeof n.text === 'string') parts.push(n.text);
+      for (const child of n.children) walk(child);
+    };
+    walk(node);
+    return parts.join(' ');
+  };
+
+  const matches = (haystack: string | undefined, needle: string, exact?: boolean): boolean => {
+    if (haystack === undefined) return false;
+    return exact ? haystack === needle : haystack.includes(needle);
+  };
+
+  const require1 = (found: Element[], what: string): Element => {
+    if (found.length === 0) {
+      throw new Error(
+        `[textui/testing] no element matching ${what}\n\n${app.buffer().toText()}`,
+      );
+    }
+    if (found.length > 1) {
+      const list = found.map((e) => `  <${e.component}> ${e.label ?? e.text ?? ''}`).join('\n');
+      throw new Error(
+        `[textui/testing] ${found.length} elements match ${what}; narrow the query\n${list}`,
+      );
+    }
+    return found[0] as Element;
+  };
+
+  const sendKey = (chord: string): void => {
+    for (const event of chordToEvents(chord)) app.handleInput(event);
+    flush();
+  };
+
+  return {
+    app,
+    store: app.store,
+    terminal,
+
+    text: () => app.buffer().toText(),
+    line: (y) => app.buffer().toText().split('\n')[y] ?? '',
+    lines: () => app.buffer().toText().split('\n'),
+    output: () => terminal.output(),
+    clearOutput: () => terminal.clearOutput(),
+    tree: () => app.inspect(),
+
+    getByRole(role, options = {}) {
+      const found = collect((n) =>
+        n.role === role && (options.name === undefined || matches(n.label ?? textOf(n), options.name, options.exact)));
+      return require1(found, `role "${role}"${options.name ? ` named "${options.name}"` : ''}`);
+    },
+    queryByRole(role, options = {}) {
+      const found = collect((n) =>
+        n.role === role && (options.name === undefined || matches(n.label ?? textOf(n), options.name, options.exact)));
+      return found[0] ?? null;
+    },
+    getAllByRole: (role) => collect((n) => n.role === role),
+
+    getByLabel(label, options = {}) {
+      return require1(collect((n) => matches(n.label, label, options.exact)), `label "${label}"`);
+    },
+    queryByLabel(label, options = {}) {
+      return collect((n) => matches(n.label, label, options.exact))[0] ?? null;
+    },
+
+    getByText(text, options = {}) {
+      return require1(collect((n) => matches(n.text, text, options.exact)), `text "${text}"`);
+    },
+    queryByText(text, options = {}) {
+      return collect((n) => matches(n.text, text, options.exact))[0] ?? null;
+    },
+    getAllByText: (text, options = {}) => collect((n) => matches(n.text, text, options.exact)),
+
+    getByComponent(name) {
+      return require1(collect((n) => n.component === name), `component <${name}>`);
+    },
+    getAllByComponent: (name) => collect((n) => n.component === name),
+
+    hasText: (text) => app.buffer().toText().includes(text),
+
+    press: sendKey,
+    pressAll(...chords) {
+      for (const chord of chords) sendKey(chord);
+    },
+    type(text) {
+      for (const char of [...text]) {
+        app.handleInput({
+          type: 'key', name: char, char, raw: char,
+          ctrl: false, alt: false, meta: false,
+          shift: char !== char.toLowerCase(),
+          handled: false,
+        });
+      }
+      flush();
+    },
+    paste(text) {
+      app.handleInput({ type: 'paste', text, handled: false });
+      flush();
+    },
+    click(x, y, button = 'left') {
+      app.handleInput({ type: 'mouse', action: 'down', button, x, y, ctrl: false, alt: false, shift: false, handled: false });
+      app.handleInput({ type: 'mouse', action: 'up', button, x, y, ctrl: false, alt: false, shift: false, handled: false });
+      flush();
+    },
+    clickOn(element) {
+      const rect = element.rect;
+      if (!rect) throw new Error(`[textui/testing] <${element.component}> has no bounds to click`);
+      this.click(rect.x + Math.floor(rect.width / 2), rect.y + Math.floor(rect.height / 2));
+    },
+    moveMouse(x, y) {
+      app.handleInput({ type: 'mouse', action: 'move', button: 'none', x, y, ctrl: false, alt: false, shift: false, handled: false });
+      flush();
+    },
+    wheel(x, y, delta) {
+      app.handleInput({ type: 'mouse', action: 'wheel', button: 'none', x, y, wheel: delta, ctrl: false, alt: false, shift: false, handled: false });
+      flush();
+    },
+    focusTerminal(focused) {
+      app.handleInput({ type: 'terminal-focus', focused });
+      flush();
+    },
+    feed(data) {
+      terminal.feed(data);
+      flush();
+    },
+
+    resize(width, height) {
+      terminal.resize(width, height);
+      flush();
+    },
+    setCapabilities(overrides) {
+      app.setCapabilityOverrides(overrides);
+      flush();
+    },
+    setTheme(id) {
+      app.setTheme(id);
+      flush();
+    },
+    setShell(id) {
+      app.setShell(id);
+      flush();
+    },
+
+    advance(ms) {
+      app.animation.advance(ms);
+      flush();
+    },
+    flush,
+    async settle() {
+      // Two turns: one for the promise that is pending, one for whatever it
+      // schedules. Anything deeper is a test that should await explicitly.
+      await Promise.resolve();
+      await new Promise((resolve) => setImmediate(resolve));
+      // And one turn of the clock, which is the one that waits for the disk.
+      //
+      // `setImmediate` runs in the check phase, and the loop never blocks to
+      // get there - so a run of settles is a spin, costing microseconds and
+      // giving a `stat` or a `readdir` no opportunity to come back. Tests wait
+      // by counting settles, so the budget ends up denominated in turns of the
+      // loop while the thing being waited for is denominated in milliseconds:
+      // they pass on an idle machine and fail on a busy one, which is the
+      // shape of every flake this helper has produced. A pending timer makes
+      // the poll phase block, and pending I/O lands.
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      flush();
+    },
+
+    focused() {
+      const id = app.focus.focused();
+      if (!id) return null;
+      const found = collect((n) => n.focused === true);
+      return found[0] ?? null;
+    },
+    focus(id) {
+      app.focus.focus(id);
+      flush();
+    },
+    tab: () => sendKey('tab'),
+    shiftTab: () => sendKey('shift+tab'),
+
+    errors: () => [...errors],
+    stats: () => app.stats(),
+
+    async unmount() {
+      await app.stop();
+      app.dispose();
+    },
+  };
+}
+
+function toElement(node: InspectorNode): Element {
+  return {
+    id: node.id,
+    component: node.component,
+    role: node.role,
+    label: node.label,
+    text: node.text,
+    rect: node.rect,
+    focused: node.focused === true,
+    props: node.props,
+    children: node.children.map(toElement),
+  };
+}
+
+/** `ctrl+shift+p`, `enter`, `a`. The inverse of `strokeOf`. */
+export function chordToEvents(chord: string): KeyEvent[] {
+  return chord
+    .trim()
+    .split(/\s+/)
+    .map((stroke) => {
+      // The registry's parser, not a second one: a chord pressed here has to
+      // produce the stroke the registry stored it under, or a binding that
+      // works in a terminal fails in a test and nobody can tell which is right.
+      const { mods: names, key } = splitStroke(stroke);
+      const mods = new Set(names);
+      // `space` is named and printable at once - the decoder emits both, and a
+      // press that gave only the name could not be typed into a field.
+      const char = key === 'space' ? ' ' : ([...key].length === 1 ? key : undefined);
+
+      return {
+        type: 'key' as const,
+        name: key,
+        char,
+        ctrl: mods.has('ctrl') || mods.has('control'),
+        alt: mods.has('alt') || mods.has('option'),
+        shift: mods.has('shift'),
+        meta: mods.has('meta') || mods.has('cmd') || mods.has('super'),
+        raw: stroke,
+        handled: false,
+      };
+    });
+}
+
+export { strokeOf };
+
+/**
+ * A stable text snapshot: the frame, with a ruler, so a diff shows which
+ * column moved rather than only that something did.
+ */
+export function snapshot(harness: Harness, options: { ruler?: boolean } = {}): string {
+  const lines = harness.lines();
+  if (!options.ruler) return lines.join('\n');
+
+  const width = Math.max(0, ...lines.map((l) => l.length));
+  const tens = Array.from({ length: width }, (_, i) => (i % 10 === 0 ? String((i / 10) % 10) : ' ')).join('');
+  const ones = Array.from({ length: width }, (_, i) => String(i % 10)).join('');
+  return [tens, ones, ...lines].join('\n');
+}