@textui/core 0.1.0

package/dist/app/app.js

@@ -0,0 +1,980 @@
+import { Buffer } from '../render/buffer.js';
+import { diffFrame } from '../render/diff.js';
+import { layout } from '../render/layout.js';
+import { buildBoxes, paintTree } from '../runtime/paint.js';
+import { collectEffects, disposeTree, renderTree } from '../runtime/reconcile.js';
+import { flushMeasures, focusScopeOf } from '../runtime/hooks.js';
+import { walkInstances } from '../runtime/instance.js';
+import { serviceKey } from '../types/services.js';
+import { createStore } from '../core/store.js';
+import { createEvents } from '../core/events.js';
+import { createWhen } from '../core/when.js';
+import { createComponents } from '../core/components.js';
+import { createServices } from '../core/services.js';
+import { createCommands } from '../core/commands.js';
+import { createKeybindings } from '../core/keybindings.js';
+import { createFocus } from '../core/focus.js';
+import { createLayers } from '../core/layers.js';
+import { createAnimation } from '../core/animation.js';
+import { createI18n } from '../core/i18n.js';
+import { createSurfaces, createLayouts, createShells } from '../core/surfaces.js';
+import { createNavigation } from '../core/navigation.js';
+import { SCREEN_COMPONENTS } from '../ui/screen.js';
+import { createResources } from '../core/resources.js';
+import { createSyntax } from '../core/syntax.js';
+import { createManifests } from '../core/manifest.js';
+import { createThemes } from '../themes/registry.js';
+import { PRIMITIVES } from '../ui/primitives.js';
+import { ZERO_EDGES } from '../types/geometry.js';
+import { createBag } from '../util/disposable.js';
+/**
+ * The application.
+ *
+ * Everything here is wiring: registries in, a frame loop, input routed to
+ * focus and commands, and deterministic teardown. The interesting decisions
+ * live in the pieces this assembles - what makes an app an app is that it owns
+ * a terminal and a clock.
+ */
+const FRAME_BUDGET_MS = 8;
+/** The mount key an app's `root` option is opened under. */
+const ROOT_KEY = 'root';
+const SCREEN_KEY = 'screen';
+/** Render/layout passes per frame. Measurement needs a second one. */
+const MAX_LAYOUT_PASSES = 3;
+export class App {
+    options;
+    store;
+    events;
+    when;
+    components;
+    themes;
+    services;
+    i18n;
+    layouts;
+    shells;
+    animation;
+    focus;
+    layers;
+    commands;
+    keybindings;
+    resources;
+    syntax;
+    surfaces;
+    screens;
+    manifest;
+    terminal;
+    buffer_;
+    /** The mount holding the top of the screen stack, while there is one. */
+    screenMount = null;
+    root = null;
+    frameScheduled = false;
+    frameTimer = null;
+    running_ = false;
+    disposed = false;
+    themeId;
+    shellId;
+    resolvedTheme;
+    bag = createBag();
+    hovered = null;
+    /** Focus registrations created from `focusable` props, by focus id. */
+    declaredFocus = new Map();
+    lastFrame = null;
+    renderCount = 0;
+    runtime;
+    constructor(options = {}) {
+        this.options = options;
+        // Construction order is dependency order, and the comment is here because
+        // reordering these lines silently breaks the app rather than failing to
+        // compile: several of them capture `this` in closures.
+        this.store = createStore();
+        this.events = createEvents();
+        this.when = createWhen(this.store);
+        this.components = createComponents();
+        this.themes = createThemes(options.themes);
+        this.services = createServices();
+        this.i18n = createI18n(options.locale ?? 'en');
+        this.layouts = createLayouts();
+        this.shells = createShells();
+        this.animation = createAnimation({
+            enabled: options.animations ?? true,
+            maxFps: options.maxFps ?? 30,
+        });
+        // Focus is published, not just held. A pane that wants to say "you are in
+        // here" would otherwise have to become a focusable itself just to be told
+        // when focus moved - which costs a tab stop for something that is not a
+        // control, and makes tabbing into a pane take two presses.
+        this.focus = createFocus(() => {
+            const id = this.focus.focused();
+            this.store.set('$/focus/id', id);
+            this.store.set('$/focus/scope', id ? this.focus.scopeOf(id) : null);
+            this.requestRender();
+        });
+        this.layers = createLayers(() => this.requestRender());
+        this.commands = createCommands({
+            store: this.store,
+            when: this.when,
+            app: () => this,
+            onError: (err, ctx) => this.handleError(err, ctx),
+        });
+        this.keybindings = createKeybindings({
+            when: this.when,
+            commands: this.commands,
+            activeScopes: () => this.focus.chain(),
+            onError: (err, ctx) => this.handleError(err, ctx),
+        });
+        this.resources = createResources({ components: this.components, when: this.when });
+        this.syntax = createSyntax({
+            kindMatches: (kind, ancestor) => this.resources.kindMatches(kind, ancestor),
+            onError: (err, ctx) => this.handleError(err, ctx),
+        });
+        this.surfaces = createSurfaces({
+            store: this.store,
+            when: this.when,
+            resources: () => this.resources,
+            onChange: () => this.requestRender(),
+        });
+        this.screens = createNavigation({
+            store: this.store,
+            focus: this.focus,
+            onChange: () => this.requestRender(),
+            mount: (entry) => this.mountScreen(entry),
+        });
+        this.manifest = createManifests(this);
+        if (!options.terminal)
+            this.requireTerminal();
+        this.terminal = options.terminal;
+        this.components.registerMany(PRIMITIVES);
+        // Registered here rather than by `registerBuiltins`, because an
+        // application that never registers the catalog can still navigate.
+        this.components.registerMany(SCREEN_COMPONENTS);
+        this.themeId = options.theme ?? 'dark';
+        this.shellId = options.shell ?? 'plain';
+        const size = this.terminal.size();
+        this.buffer_ = new Buffer(size.width, size.height);
+        this.resolvedTheme = this.themes.resolve(this.themeId, this.terminal.capabilities());
+        this.store.onError = (err, ctx) => this.handleError(err, ctx);
+        this.events.onError = (err, ctx) => this.handleError(err, ctx);
+        this.publishEnvironment();
+        this.runtime = {
+            store: this.store,
+            events: this.events,
+            when: this.when,
+            components: this.components,
+            services: this.services,
+            focus: this.focus,
+            layers: this.layers,
+            animation: this.animation,
+            i18n: this.i18n,
+            theme: () => this.resolvedTheme,
+            capabilities: () => this.terminal.capabilities(),
+            size: () => this.terminal.size(),
+            execute: (id, args) => this.commands.execute(id, args),
+            emit: (path, payload) => this.events.emit(path, payload),
+            requestRender: () => this.requestRender(),
+            app: () => this,
+            onError: (err, ctx) => this.handleError(err, ctx),
+        };
+    }
+    requireTerminal() {
+        throw new Error('[textui] createApp needs a terminal adapter - pass one from @textui/terminal');
+    }
+    // ------------------------------------------------------------ environment
+    get capabilities() {
+        return this.terminal.capabilities();
+    }
+    get theme() {
+        return this.resolvedTheme;
+    }
+    get size() {
+        return this.terminal.size();
+    }
+    get running() {
+        return this.running_;
+    }
+    publishEnvironment() {
+        const size = this.terminal.size();
+        this.store.batch(() => {
+            this.store.set('$/modus/size', size);
+            this.store.set('$/modus/capabilities', this.terminal.capabilities());
+            this.store.set('$/modus/theme', this.themeId);
+            this.store.set('$/modus/locale', this.i18n.locale);
+            this.store.set('$/layout/shell', this.shellId);
+            // Named breakpoints, so a `when` clause reads well.
+            this.store.set('$/modus/class', size.width < 60 ? 'narrow' : size.width < 100 ? 'medium' : 'wide');
+        });
+    }
+    setTheme(id) {
+        if (!this.themes.get(id)) {
+            throw new Error(`[textui] no theme registered as "${id}"`);
+        }
+        this.themeId = id;
+        this.resolvedTheme = this.themes.resolve(id, this.terminal.capabilities());
+        this.store.set('$/modus/theme', id);
+        this.buffer_.invalidate();
+        this.requestRender(true);
+    }
+    setShell(id) {
+        if (!this.shells.get(id)) {
+            throw new Error(`[textui] no shell registered as "${id}"`);
+        }
+        this.shellId = id;
+        this.store.set('$/layout/shell', id);
+        const shell = this.shells.get(id);
+        if (shell?.theme && this.themes.get(shell.theme))
+            this.setTheme(shell.theme);
+        this.buffer_.invalidate();
+        this.requestRender(true);
+    }
+    activeShell() {
+        return this.shellId;
+    }
+    setCapabilityOverrides(overrides) {
+        this.terminal.setCapabilityOverrides(overrides);
+        this.resolvedTheme = this.themes.resolve(this.themeId, this.terminal.capabilities());
+        this.publishEnvironment();
+        this.buffer_.invalidate();
+        this.requestRender(true);
+    }
+    // ------------------------------------------------------------- lifecycle
+    async start() {
+        if (this.running_)
+            return;
+        // A boot that hands back a disposable is asking for its registrations to
+        // come out again when the app stops, which is what `stop()` already does
+        // to everything else in the bag.
+        const booted = await this.options.onBoot?.(this);
+        if (booted)
+            this.bag.add(booted);
+        await this.store.hydrate();
+        // `root` is a mount like any other, so the shell arranges it, the layouts
+        // apply to it, and everything that reads the surface registry sees it.
+        if (this.options.root && this.shells.get(this.shellId)) {
+            this.surfaces.open({ surface: 'main', key: ROOT_KEY, target: this.options.root });
+        }
+        // A shell may prefer a theme it was designed against. An explicit theme in
+        // the options always wins - the shell only fills in a default.
+        if (!this.options.theme) {
+            const shellTheme = this.shells.get(this.shellId)?.theme;
+            if (shellTheme && this.themes.get(shellTheme))
+                this.setTheme(shellTheme);
+        }
+        const caps = this.terminal.capabilities();
+        await this.terminal.acquire({
+            managed: true,
+            altScreen: true,
+            hideCursor: true,
+            paste: caps.paste,
+            mouse: caps.mouse,
+            wheel: caps.wheel,
+            focusEvents: caps.focusEvents,
+            enhancedKeys: caps.kittyKeyboard,
+            ...this.options.session,
+        });
+        this.bag.add(this.terminal.onInput((event) => this.handleInput(event)));
+        this.bag.add(this.terminal.onResize((size) => this.handleResize(size)));
+        this.running_ = true;
+        this.publishEnvironment();
+        this.renderFrame();
+    }
+    async stop() {
+        if (!this.running_)
+            return;
+        this.running_ = false;
+        if (this.frameTimer)
+            clearTimeout(this.frameTimer);
+        this.frameTimer = null;
+        this.frameScheduled = false;
+        this.bag.dispose();
+        this.bag = createBag();
+        for (const entry of this.declaredFocus.values())
+            entry.dispose();
+        this.declaredFocus.clear();
+        // The terminal goes back first, before anything a component wrote to run
+        // on its way out.
+        //
+        // Disposing the tree runs every effect cleanup, and a cleanup that prints
+        // - which is how anyone debugs one - was printing into the alternate
+        // screen, which the terminal discards the moment we leave it. The log ran,
+        // did what it was told, and vanished. Releasing first puts the ordinary
+        // screen back, so `console.log` in a cleanup lands where a person can read
+        // it. A cleanup that paints instead is painting into a screen that is
+        // already gone either way.
+        await this.terminal.release();
+        if (this.root) {
+            disposeTree(this.root);
+            this.root = null;
+        }
+        for (const scope of this.options.clearOnStop ?? [])
+            this.store.clearScope(scope);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        void this.stop();
+        this.animation.dispose();
+        this.layers.dispose();
+        this.events.dispose();
+        this.store.dispose();
+        this.terminal.dispose();
+    }
+    /**
+     * Swap the root node for another.
+     *
+     * Two paths, because there are two ways a root reaches the screen. With a
+     * shell registered it is a mount like any other and the surface registry
+     * owns it; with no shell at all - which is every application built out of
+     * primitives and nothing else - `rootNode` wraps `options.root` directly and
+     * the registry is never consulted. Setting one and not the other works in
+     * exactly half of the programs that can exist.
+     */
+    setRoot(node) {
+        this.options = { ...this.options, root: node };
+        if (this.shells.get(this.shellId)) {
+            this.surfaces.open({ surface: 'main', key: ROOT_KEY, target: node });
+        }
+        this.requestRender(true);
+    }
+    // ---------------------------------------------------------------- frames
+    requestRender(force = false) {
+        if (force && this.root) {
+            walkInstances(this.root, (i) => {
+                i.dirty = true;
+                i.childDirty = true;
+            });
+        }
+        if (!this.running_ || this.frameScheduled)
+            return;
+        this.frameScheduled = true;
+        // Coalesce a burst of state changes into one frame, and never render
+        // faster than the animation driver's ceiling.
+        const delay = Math.max(0, Math.floor(1000 / Math.max(1, this.animation.maxFps)) - FRAME_BUDGET_MS);
+        this.frameTimer = setTimeout(() => {
+            this.frameTimer = null;
+            this.frameScheduled = false;
+            this.renderFrame();
+        }, delay);
+        this.frameTimer.unref?.();
+    }
+    flush() {
+        if (this.frameTimer) {
+            clearTimeout(this.frameTimer);
+            this.frameTimer = null;
+        }
+        this.frameScheduled = false;
+        this.renderFrame();
+    }
+    /**
+     * The tree the frame renders: the shell, always, when one is registered.
+     *
+     * `root` is an alternative to *screens*, not to the shell - it is mounted
+     * into `main` at boot. Returning it here instead meant an application built
+     * that way had no shell at all: no canvas background (so a light theme left
+     * the terminal's own dark one behind and only dialogs looked light), no
+     * status surface, no toast host, and `setShell` did nothing.
+     */
+    /**
+     * Put the current screen into its surface.
+     *
+     * A screen is a mount like `root` is a mount: the shell arranges it, the
+     * layouts apply to it, and anything reading the surface registry sees it.
+     * Only the top of the stack is mounted - what a screen underneath keeps is
+     * its store scope, if it asked to, and not its instances.
+     *
+     * Parameters arrive as props. A screen that wants them deeper than its own
+     * signature reads `$/layout/screen/params` instead of forwarding them.
+     */
+    mountScreen(entry) {
+        this.screenMount?.dispose();
+        this.screenMount = null;
+        if (!entry)
+            return;
+        const def = this.screens.get(entry.id);
+        if (!def)
+            return;
+        const node = typeof def.component === 'string'
+            ? { component: def.component, ...(entry.params ?? {}) }
+            : { ...def.component, ...(entry.params ?? {}) };
+        this.screenMount = this.surfaces.open({
+            surface: def.surface ?? 'main',
+            key: `${SCREEN_KEY}:${entry.id}`,
+            target: { component: 'Screen', screenId: entry.id, children: [node] },
+            ...(def.display ? { display: def.display } : {}),
+        });
+    }
+    rootNode() {
+        const shell = this.shells.get(this.shellId);
+        if (shell)
+            return { component: shell.component };
+        // No shell registered at all: draw `root` on a themed canvas, so an
+        // application that registers nothing but primitives still works.
+        if (this.options.root) {
+            return {
+                component: 'box',
+                width: '100%',
+                height: '100%',
+                direction: 'column',
+                bg: 'canvas',
+                children: this.options.root,
+            };
+        }
+        return {
+            component: 'text',
+            content: `[textui] no shell registered as "${this.shellId}"`,
+            fg: 'danger',
+        };
+    }
+    /**
+     * Layers are composed at the root rather than inside the tree, so an overlay
+     * is never clipped by whatever opened it.
+     */
+    /**
+     * The root node: the shell, plus whatever is on the layers above it.
+     *
+     * The wrapper is unconditional, and that matters more than it looks. If the
+     * root were the bare shell whenever no layer is open, then opening the first
+     * toast would change the root's component - and a changed root is a full
+     * unmount and remount, so every screen would lose its state the moment
+     * anything notified it of anything. One shape, always.
+     */
+    composeRoot() {
+        const entries = this.layers.entries().filter((e) => e.layer !== 'base');
+        const base = this.rootNode();
+        const children = [
+            { component: 'box', key: '__base__', position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, children: base },
+        ];
+        const scrim = entries.find((e) => e.scrim);
+        if (scrim) {
+            children.push({
+                component: 'box',
+                key: '__scrim__',
+                position: 'absolute',
+                top: 0, left: 0, right: 0, bottom: 0,
+                // Washed, not covered: the screen behind a modal recedes and stays
+                // readable, instead of becoming a rectangle of nothing.
+                scrim: true,
+                zIndex: 50,
+            });
+        }
+        for (const entry of entries)
+            children.push(this.layerNode(entry));
+        return {
+            component: 'box',
+            key: '__root__',
+            width: '100%',
+            height: '100%',
+            children,
+        };
+    }
+    layerNode(entry) {
+        const size = this.terminal.size();
+        const position = entry.position ?? { kind: 'center' };
+        const zIndex = entry.layer === 'notification' ? 200 : entry.layer === 'modal' ? 100 : 60;
+        // Every layer gets a focus scope, so `trapFocus` is a fact rather than a
+        // flag. Without it a layer assembled from plain nodes cannot trap, and tab
+        // leaves the open thing on the first press.
+        const scoped = {
+            component: 'LayerScope',
+            scopeId: entry.id,
+            trap: entry.trapFocus === true,
+            children: entry.node,
+        };
+        const wrap = (style) => ({
+            component: 'box',
+            key: entry.id,
+            position: 'absolute',
+            zIndex,
+            children: scoped,
+            ...style,
+        });
+        switch (position.kind) {
+            case 'center':
+                // Centring without knowing the child's size means centring the band it
+                // sits in and letting the child align itself inside.
+                return wrap({
+                    top: 0, left: 0, right: 0, bottom: 0,
+                    align: 'center', justify: 'center',
+                });
+            case 'screen':
+                return wrap({
+                    top: position.rect.y ?? 0,
+                    left: position.rect.x ?? 0,
+                    ...(position.rect.width !== undefined ? { width: position.rect.width } : {}),
+                    ...(position.rect.height !== undefined ? { height: position.rect.height } : {}),
+                });
+            case 'point':
+                return wrap({ top: position.y, left: position.x });
+            case 'anchor': {
+                const rect = this.rectOf(position.targetId);
+                if (!rect)
+                    return wrap({ top: 0, left: 0 });
+                const offset = position.offset ?? 0;
+                const align = position.align ?? 'start';
+                if (position.side === 'bottom') {
+                    return wrap({ top: rect.y + rect.height + offset, left: alignX(rect, align) });
+                }
+                if (position.side === 'top') {
+                    return wrap({ bottom: Math.max(0, size.height - rect.y + offset), left: alignX(rect, align) });
+                }
+                if (position.side === 'right') {
+                    return wrap({ top: rect.y, left: rect.x + rect.width + offset });
+                }
+                return wrap({ top: rect.y, right: Math.max(0, size.width - rect.x + offset) });
+            }
+            default:
+                return wrap({ top: 0, left: 0 });
+        }
+    }
+    rectOf(focusId) {
+        const order = this.focus.order();
+        if (!order.includes(focusId) && this.focus.focused() !== focusId) {
+            // The target may be non-tabbable but still registered.
+        }
+        let found = null;
+        if (this.root) {
+            walkInstances(this.root, (instance) => {
+                if (found)
+                    return;
+                if (instance.props.id === focusId && instance.box)
+                    found = instance.box.rect;
+            });
+        }
+        return found;
+    }
+    stateOf(instance) {
+        const id = typeof instance.props.id === 'string' ? instance.props.id : instance.id;
+        const focusedId = this.focus.focused();
+        return {
+            focused: focusedId === id || focusedId === `${instance.id}:focus`,
+            hovered: this.hovered === id,
+            active: false,
+            selected: instance.props.selected === true,
+            disabled: instance.props.disabled === true,
+        };
+    }
+    renderFrame() {
+        if (!this.running_ || this.disposed)
+            return;
+        const size = this.terminal.size();
+        if (size.width !== this.buffer_.width || size.height !== this.buffer_.height) {
+            this.buffer_.resize(size.width, size.height);
+        }
+        const env = {
+            theme: this.resolvedTheme,
+            capabilities: this.terminal.capabilities(),
+            stateOf: (instance) => this.stateOf(instance),
+        };
+        const node = this.composeRoot();
+        const viewport = { x: 0, y: 0, width: size.width, height: size.height };
+        // Render, lay out, and hand every measured component its rect, then do it
+        // again if anything changed as a result. Two things change: a component
+        // that sized itself from its new rect, and an effect that ran during the
+        // pass - `autoFocus` is the one that shows, because painting before it
+        // lands means one frame of a dialog whose default button is not lit.
+        //
+        // Twice is the steady state; the bound is there for the pathological case
+        // where two of them chase each other.
+        for (let pass = 0; pass < MAX_LAYOUT_PASSES; pass++) {
+            try {
+                this.root = renderTree(this.runtime, this.root, node, {
+                    diagnostics: this.options.diagnostics,
+                });
+            }
+            catch (err) {
+                this.handleError(err, 'render');
+                return;
+            }
+            const effects = collectEffects(this.root);
+            for (const effect of effects)
+                effect();
+            const boxes = buildBoxes(this.root, env);
+            const rootBox = {
+                style: { direction: 'column' },
+                borderEdges: ZERO_EDGES,
+                children: boxes,
+                rect: { ...viewport },
+                content: { ...viewport },
+            };
+            layout(rootBox, viewport);
+            const remeasured = flushMeasures();
+            if (!remeasured && !this.isDirty())
+                break;
+        }
+        if (!this.root)
+            return;
+        this.syncDeclaredFocusables();
+        this.updateFocusRects();
+        // Once. There were two, the first blanking to palette 0 and the second to
+        // the default background over the top of it - a whole extra pass over
+        // every cell on screen, every frame, with nothing to show for it.
+        this.buffer_.clear();
+        paintTree(this.buffer_, this.root, env, viewport);
+        const frame = diffFrame(this.buffer_, this.cursorPosition());
+        this.buffer_.commit();
+        this.lastFrame = frame;
+        this.renderCount++;
+        this.emitFrame(frame);
+        // An effect may have marked something dirty; give it the next frame.
+        if (this.isDirty())
+            this.requestRender();
+    }
+    /** Overridden by the test harness, which has no bytes to write. */
+    emitFrame(frame) {
+        const writer = this.services.get(WRITER_KEY);
+        if (!writer)
+            return;
+        const data = writer.write(frame);
+        if (data !== '') {
+            this.terminal.write(data);
+            void this.terminal.flush();
+        }
+    }
+    cursorPosition() {
+        const focused = this.focus.focused();
+        if (!focused || !this.root)
+            return null;
+        let position = null;
+        walkInstances(this.root, (instance) => {
+            if (position)
+                return;
+            const cursor = instance.props.cursor;
+            if (!cursor || !instance.box)
+                return;
+            const id = typeof instance.props.id === 'string' ? instance.props.id : instance.id;
+            if (id !== focused && `${instance.id}:focus` !== focused)
+                return;
+            const offset = typeof cursor === 'number' ? cursor : 0;
+            position = {
+                x: instance.box.content.x + offset,
+                y: instance.box.content.y,
+                visible: true,
+            };
+        });
+        return position;
+    }
+    /**
+     * `focusable` and `onKey` are props on every node, so a plain `box` can take
+     * focus without a hook. Those declarations are reconciled here rather than
+     * during render, because a node that has gone away must lose its
+     * registration - and only the render pass knows which are still mounted.
+     */
+    syncDeclaredFocusables() {
+        if (!this.root)
+            return;
+        const seen = new Set();
+        walkInstances(this.root, (instance) => {
+            if (instance.props.focusable !== true)
+                return;
+            const id = typeof instance.props.id === 'string' ? instance.props.id : instance.id;
+            seen.add(id);
+            const onKey = typeof instance.props.onKey === 'function'
+                ? instance.props.onKey
+                : undefined;
+            const options = {
+                id,
+                disabled: instance.props.disabled === true,
+                skipTab: instance.props.skipTab === true,
+                global: instance.props.global === true,
+                order: typeof instance.props.order === 'number' ? instance.props.order : undefined,
+                scopeId: typeof instance.props.focusScope === 'string'
+                    ? instance.props.focusScope
+                    : focusScopeOf(instance),
+                onKey,
+                rect: instance.box?.rect,
+            };
+            const existing = this.declaredFocus.get(id);
+            if (existing && existing.instanceId === instance.id) {
+                this.focus.update(id, options);
+                return;
+            }
+            // A hook already owns this id: `useFocus` registered it and `useInput`
+            // put a handler on it. Registering over the top would replace that
+            // handler with this node's - usually with nothing - and the control
+            // would keep its focus ring while silently ignoring every key.
+            if (!existing && this.focus.has(id)) {
+                const { onKey: _declared, ...rest } = options;
+                this.focus.update(id, onKey ? { ...rest, onKey } : rest);
+                return;
+            }
+            existing?.dispose();
+            this.declaredFocus.set(id, {
+                instanceId: instance.id,
+                dispose: this.focus.register(options).dispose,
+            });
+            if (instance.props.autoFocus === true && this.focus.focused() === null) {
+                this.focus.focus(id);
+            }
+        });
+        for (const [id, entry] of this.declaredFocus) {
+            if (seen.has(id))
+                continue;
+            entry.dispose();
+            this.declaredFocus.delete(id);
+        }
+    }
+    updateFocusRects() {
+        if (!this.root)
+            return;
+        walkInstances(this.root, (instance) => {
+            if (!instance.box)
+                return;
+            const id = typeof instance.props.id === 'string' ? instance.props.id : null;
+            if (id)
+                this.focus.setRect(id, instance.box.rect);
+            this.focus.setRect(`${instance.id}:focus`, instance.box.rect);
+        });
+    }
+    isDirty() {
+        const root = this.root;
+        return root ? root.dirty || root.childDirty : false;
+    }
+    buffer() {
+        return this.buffer_;
+    }
+    frame() {
+        return this.lastFrame;
+    }
+    // ----------------------------------------------------------------- input
+    /**
+     * Input is processed one event at a time, and the tree is re-rendered
+     * between events rather than once at the end of the batch.
+     *
+     * This matters more than it looks. A terminal delivers several keystrokes in
+     * a single read, and a handler closes over the props from its last render -
+     * so without settling in between, typing "ab" quickly makes the handler for
+     * "b" see the state from before "a", and the character is lost. Rendering
+     * per key is what every terminal application does, and the frame diff makes
+     * it cheap.
+     */
+    handleInput(event) {
+        // A handler that throws must not take the process with it. The screen is
+        // the output, so an uncaught error from a keystroke exits to a shell with
+        // a stack trace and no application - which is a worse answer than any
+        // wrong frame. It goes in the diagnostics like every other error.
+        try {
+            this.dispatchInput(event);
+        }
+        catch (err) {
+            this.handleError(err, `input:${event.type}`);
+        }
+        if (this.running_ && this.isDirty())
+            this.renderFrame();
+    }
+    dispatchInput(event) {
+        switch (event.type) {
+            case 'key':
+                this.handleKey(event);
+                break;
+            case 'mouse':
+                this.handleMouse(event);
+                break;
+            case 'paste':
+                this.events.emit('@/input/paste', event.text);
+                this.focus.dispatch({
+                    type: 'key', name: 'paste', char: event.text, raw: event.text,
+                    ctrl: false, alt: false, shift: false, meta: false, handled: false,
+                });
+                break;
+            case 'terminal-focus':
+                this.store.set('$/modus/focused', event.focused);
+                break;
+            case 'resize':
+                this.handleResize({ width: event.width, height: event.height });
+                break;
+        }
+    }
+    /**
+     * Order matters. A focused text field must see a plain character before any
+     * keybinding does, or typing "q" in a search box quits the application. So
+     * the focused node gets first refusal, then chords, then global handlers.
+     */
+    handleKey(event) {
+        /*
+         * Every key, before anything decides what to do with it.
+         *
+         * "My binding does not fire" has two very different answers - the key
+         * never arrived, or something upstream took it - and from inside a
+         * full-screen application they look identical. A terminal that keeps
+         * `ctrl+s` for flow control, or an editor hosting the terminal that keeps
+         * it for itself, is invisible until the log can be asked whether the key
+         * was ever seen. `@/input/paste` was already here; this is the other half.
+         */
+        this.events.emit('@/input/key', {
+            name: event.name,
+            ...(event.ctrl ? { ctrl: true } : {}),
+            ...(event.alt ? { alt: true } : {}),
+            ...(event.shift ? { shift: true } : {}),
+            ...(event.meta ? { meta: true } : {}),
+        });
+        const focusedNode = this.focus.focused();
+        if (focusedNode && this.focus.dispatch(event)) {
+            this.requestRender();
+            return;
+        }
+        if (this.keybindings.handle(event) !== 'unhandled') {
+            this.requestRender();
+            return;
+        }
+        // Escape closes the topmost dismissible layer, when nothing else took it.
+        if (event.name === 'escape') {
+            const top = this.layers.topmostDismissible();
+            if (top) {
+                this.layers.close(top.id, 'escape');
+                return;
+            }
+        }
+        if (event.name === 'tab') {
+            this.focus.move(event.shift ? 'previous' : 'next');
+            return;
+        }
+        if (!focusedNode && this.focus.dispatch(event))
+            this.requestRender();
+    }
+    handleMouse(event) {
+        const hit = this.focus.at(event.x, event.y);
+        if (event.action === 'move') {
+            if (hit !== this.hovered) {
+                this.hovered = hit;
+                this.requestRender();
+            }
+            return;
+        }
+        if (event.action === 'down' && hit)
+            this.focus.focus(hit);
+        if (this.root) {
+            this.dispatchMouse(this.root, event);
+        }
+        this.requestRender();
+    }
+    /** Innermost box under the pointer first, then outward. */
+    dispatchMouse(instance, event) {
+        for (let i = instance.children.length - 1; i >= 0; i--) {
+            const child = instance.children[i];
+            if (this.dispatchMouse(child, event))
+                return true;
+        }
+        const box = instance.box;
+        if (!box)
+            return false;
+        const { x, y, width, height } = box.rect;
+        if (event.x < x || event.x >= x + width || event.y < y || event.y >= y + height)
+            return false;
+        const onMouse = instance.props.onMouse;
+        if (typeof onMouse === 'function' && onMouse(event) === true) {
+            return true;
+        }
+        if (event.action === 'down' && event.button === 'left') {
+            const onClick = instance.props.onClick;
+            if (typeof onClick === 'function') {
+                onClick(event);
+                return true;
+            }
+        }
+        return false;
+    }
+    handleResize(size) {
+        this.buffer_.resize(size.width, size.height);
+        this.buffer_.invalidate();
+        this.publishEnvironment();
+        this.requestRender(true);
+    }
+    // ------------------------------------------------------------- shortcuts
+    open = (mount) => this.surfaces.open(mount);
+    openResource = (uri, options) => this.surfaces.openResource(uri, options);
+    /**
+     * Fan an adapter out across the registries it touches, and hand back one
+     * disposable for the lot. Order matters: kinds first, so a viewer registered
+     * for `file.data.json` has something to match before anything is classified.
+     */
+    registerAdapter(adapter) {
+        const bag = createBag();
+        for (const kind of adapter.kinds ?? [])
+            bag.add(this.resources.registerKind(kind));
+        for (const provider of adapter.providers ?? [])
+            bag.add(this.resources.registerProvider(provider));
+        for (const component of adapter.components ?? [])
+            bag.add(this.components.register(component));
+        for (const highlighter of adapter.highlighters ?? [])
+            bag.add(this.syntax.register(highlighter));
+        for (const viewer of adapter.viewers ?? [])
+            bag.add(this.resources.registerViewer(viewer));
+        for (const editor of adapter.editors ?? [])
+            bag.add(this.resources.registerEditor(editor));
+        for (const action of adapter.actions ?? [])
+            bag.add(this.resources.registerAction(action));
+        for (const command of adapter.commands ?? [])
+            bag.add(this.commands.register(command));
+        for (const binding of adapter.keybindings ?? [])
+            bag.add(this.keybindings.register(binding));
+        const extra = adapter.register?.(this);
+        if (extra)
+            bag.add(extra);
+        this.bag.add(bag);
+        return bag;
+    }
+    execute = (id, args, source) => this.commands.execute(id, args, source);
+    // ------------------------------------------------------------- inspector
+    inspect() {
+        if (!this.root)
+            return null;
+        return describe(this.root, this.focus.focused());
+    }
+    stats() {
+        let instances = 0;
+        if (this.root)
+            walkInstances(this.root, () => { instances++; });
+        return {
+            renders: this.renderCount,
+            runs: this.lastFrame?.runs.length ?? 0,
+            instances,
+        };
+    }
+    handleError(err, context) {
+        const message = err instanceof Error ? err.stack ?? err.message : String(err);
+        this.store.collection('$/modus/diagnostics/errors').append({
+            context,
+            message,
+            at: Date.now(),
+        });
+        this.store.collection('$/modus/diagnostics/errors').cap(50);
+        if (!this.options.diagnostics) {
+            console.error(`[textui] ${context}`, err);
+        }
+    }
+}
+function alignX(rect, align) {
+    if (align === 'center')
+        return rect.x + Math.floor(rect.width / 2);
+    if (align === 'end')
+        return rect.x + rect.width;
+    return rect.x;
+}
+function describe(instance, focused) {
+    const props = {};
+    for (const [k, v] of Object.entries(instance.props)) {
+        if (k === 'children')
+            continue;
+        props[k] = typeof v === 'function' ? '[function]' : v;
+    }
+    const id = typeof instance.props.id === 'string' ? instance.props.id : instance.id;
+    const content = instance.props.content;
+    return {
+        id: instance.id,
+        component: instance.component,
+        key: instance.key,
+        rect: instance.box?.rect,
+        props,
+        role: typeof instance.props.role === 'string' ? instance.props.role : undefined,
+        label: typeof instance.props.label === 'string' ? instance.props.label : undefined,
+        text: typeof content === 'string' ? content : undefined,
+        focusable: instance.props.focusable === true,
+        focused: focused === id || focused === `${instance.id}:focus`,
+        renderReason: instance.renderReason,
+        bindings: instance.reads.size > 0 ? [...instance.reads] : undefined,
+        children: instance.children.map((child) => describe(child, focused)),
+    };
+}
+export const WRITER_KEY = serviceKey('textui.writer');
+export function createApp(options = {}) {
+    return new App(options);
+}