@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/widgets/event-router.js

@@ -0,0 +1,629 @@
+/**
+ * EventRouter — parses raw stdin into KeyEvent / ScreenMouseEvent values
+ * and dispatches them to widgets via a FocusManager and the frame on screen.
+ *
+ * It reads the terminal and never sets it up: raw mode and mouse tracking are
+ * the runtime's (`App`), which undoes them on every path out.
+ *
+ * [LAW:single-enforcer] ANSI escape parsing lives only here — widgets never
+ * see raw bytes. One parser, one dispatch surface.
+ *
+ * [LAW:dataflow-not-control-flow] The same parse pipeline runs for every
+ * input chunk: append → consume one event at a time until the buffer can't
+ * yield more. The byte's value, not a side-mode, decides which event is
+ * emitted. There is no "are we mid-sequence" mode flag — the buffer head
+ * carries all the state we need.
+ *
+ * Lone-ESC handling: a bare `\x1b` is ambiguous (escape key vs. start of a
+ * CSI sequence). When the buffer is drained but ends with a lone ESC, the
+ * router defers emission via setTimeout(0). The next chunk cancels the timer
+ * if it extends the sequence. Tests can call `flush()` to drain synchronously.
+ */
+import { KeyEvent } from "./types.js";
+import { drew, originOf, scrollTargetAt, widgetAt } from "./hit.js";
+// Single-byte → key name table for the trivial cases.
+const SINGLE_BYTE_KEYS = {
+    0x09: "tab",
+    0x0a: "enter",
+    0x0d: "enter",
+    0x1b: "escape",
+    0x08: "backspace",
+    0x7f: "backspace",
+    0x20: "space",
+};
+// Final-byte → key name for the simple `ESC[<X>` arrow / nav forms.
+const CSI_LETTER_KEYS = {
+    A: "up",
+    B: "down",
+    C: "right",
+    D: "left",
+    H: "home",
+    F: "end",
+    Z: "tab", // shift+tab encodes as ESC[Z
+};
+// `ESC[<n>~` numeric forms for navigation / function keys.
+const CSI_TILDE_KEYS = {
+    "1": "home",
+    "2": "insert",
+    "3": "delete",
+    "4": "end",
+    "5": "pageup",
+    "6": "pagedown",
+    "7": "home",
+    "8": "end",
+    "11": "f1",
+    "12": "f2",
+    "13": "f3",
+    "14": "f4",
+    "15": "f5",
+    "17": "f6",
+    "18": "f7",
+    "19": "f8",
+    "20": "f9",
+    "21": "f10",
+    "23": "f11",
+    "24": "f12",
+};
+// SS3 form `ESC O X` for F1–F4 (and arrow keys on some terminals).
+const SS3_KEYS = {
+    P: "f1",
+    Q: "f2",
+    R: "f3",
+    S: "f4",
+    A: "up",
+    B: "down",
+    C: "right",
+    D: "left",
+    H: "home",
+    F: "end",
+};
+const ESC = 0x1b;
+const LBRACKET = 0x5b; // [
+const LANGLE = 0x3c; // <
+const O_BYTE = 0x4f; // O
+const M_UPPER = 0x4d; // M
+const M_LOWER = 0x6d; // m
+// [LAW:single-enforcer] Shared encode/decode singletons. The parser
+// receives `Uint8Array | string` from the host and walks bytes through
+// its state machine; conversion happens at the two boundaries (string
+// input → bytes via TextEncoder; printable-byte run → JS string via
+// TextDecoder) and only there. Module-level instances keep the seam
+// allocation-free and runtime-agnostic — both APIs are universal across
+// node and browser.
+const UTF8_ENCODER = new TextEncoder();
+const UTF8_DECODER = new TextDecoder("utf-8");
+const ASCII_DECODER = new TextDecoder("ascii");
+const EMPTY_BYTES = new Uint8Array(0);
+// Concatenate two byte arrays into a fresh Uint8Array. Replaces
+// `Buffer.concat([...])` so the parser holds no node-specific globals.
+function concatBytes(a, b) {
+    if (a.length === 0)
+        return b;
+    if (b.length === 0)
+        return a;
+    const merged = new Uint8Array(a.length + b.length);
+    merged.set(a, 0);
+    merged.set(b, a.length);
+    return merged;
+}
+export class EventRouter {
+    source;
+    host;
+    // [LAW:types-are-the-program] The parse buffer is `Uint8Array`, not
+    // `Buffer` — node's Buffer extends Uint8Array, so Buffer chunks from
+    // process.stdin satisfy this type and the parser still works on node,
+    // while a browser host can emit native Uint8Array without the runtime
+    // depending on a Buffer global polyfill.
+    buffer = EMPTY_BYTES;
+    running = false;
+    dataUnsubscribe;
+    // [LAW:types-are-the-program] `setTimeout`/`clearTimeout` are universal
+    // across node and browser; `setImmediate` is node-only. Same one-macrotask
+    // semantics for our purpose (defer until current sync work + queued
+    // microtasks drain), without forcing a `setImmediate` polyfill on the
+    // browser host.
+    escTimer;
+    // [LAW:single-enforcer] Drag capture lives only here. A mouse_down's
+    // target is recorded; mouse_move/mouse_up between then and the next
+    // mouse_up route to it unconditionally and relative to where it is painted
+    // (`relocate`), so a drag past the widget's edge still drives its state
+    // (Slider's _dragging) and reports a column outside it. Cleared on the next
+    // mouse_up.
+    captured = null;
+    // Where the terminal last reported the pointer, and the widget under it on
+    // the frame on screen — the one widget `hovered` is true on.
+    pointer = null;
+    hoveredWidget = null;
+    // [LAW:dataflow-not-control-flow] Ordered chain; the dispatcher walks it
+    // in priority tiers and stops as soon as some participant calls
+    // `event.stop()`. Insertion order is preserved within each tier.
+    keyChain = [];
+    mouseHandlers = new Set();
+    constructor(options) {
+        this.source = options.source;
+        this.host = options.host;
+        // [LAW:single-enforcer] FocusManager owns Tab/Shift+Tab traversal —
+        // register it as a normal-priority handler so it participates in the
+        // chain. This MUST be the first registration so it lands ahead of any
+        // user-added normal handlers; widgets that want to suppress traversal
+        // call `event.stop()` from their own handleKey and FocusManager
+        // never runs for that event.
+        this.onKey((event) => this.source.focusManager.handleKey(event));
+    }
+    // --- Lifecycle ---
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Subscribing starts the underlying stream flowing on node, and is all
+        // it takes on a transport with no paused mode.
+        this.dataUnsubscribe = this.host.onData((chunk) => this.feed(chunk));
+    }
+    stop() {
+        if (this.running) {
+            this.running = false;
+            if (this.dataUnsubscribe) {
+                this.dataUnsubscribe();
+                this.dataUnsubscribe = undefined;
+            }
+        }
+        // [LAW:one-source-of-truth] Per-session state belongs to one session.
+        // stop() leaves the router in the same shape a fresh construction
+        // would: empty parse buffer, no captured widget, nothing hovered, no
+        // pending ESC timer.
+        // All cleanup is outside the `running` guard because feed() can arm
+        // escTimer (and grow buffer) even when running is false — without
+        // those, a pre-start feed could leave a deferred escape firing into
+        // the next session. Clearing already-empty state is a no-op so this
+        // stays safe on repeated stop().
+        if (this.escTimer) {
+            clearTimeout(this.escTimer);
+            this.escTimer = undefined;
+        }
+        this.buffer = EMPTY_BYTES;
+        this.captured = null;
+        this.pointer = null;
+        this.hover(null);
+    }
+    /**
+     * Read hover again off the frame just painted: under a pointer that has not
+     * moved, a widget may have gone, moved, or arrived.
+     *
+     * [LAW:one-source-of-truth] Hover is the widget under the pointer on the
+     * frame on screen, so it is re-read whenever either one changes.
+     */
+    framePainted() {
+        const hit = this.pointer && widgetAt(this.source.frame, this.pointer.x, this.pointer.y);
+        this.hover(hit ? hit.widget : null);
+    }
+    // --- External hooks ---
+    onKey(handler, options) {
+        const entry = {
+            handler,
+            priority: options?.priority ?? "normal",
+        };
+        this.keyChain.push(entry);
+        return () => {
+            const idx = this.keyChain.indexOf(entry);
+            if (idx !== -1)
+                this.keyChain.splice(idx, 1);
+        };
+    }
+    onMouse(handler) {
+        this.mouseHandlers.add(handler);
+        return () => this.mouseHandlers.delete(handler);
+    }
+    // --- Test / advanced API ---
+    /** Feed a chunk of bytes (or a string of bytes) into the parser. */
+    feed(chunk) {
+        const next = typeof chunk === "string" ? UTF8_ENCODER.encode(chunk) : chunk;
+        this.buffer = concatBytes(this.buffer, next);
+        if (this.escTimer) {
+            clearTimeout(this.escTimer);
+            this.escTimer = undefined;
+        }
+        this.drain();
+        // [LAW:dataflow-not-control-flow] If a lone ESC remains, defer emission
+        // until the next macrotask so a follow-up chunk can extend it. The
+        // explicit `0` is structural deferral, not a throttle — it just lets
+        // the current sync work + queued microtasks drain before flushing.
+        if (this.buffer.length === 1 && this.buffer[0] === ESC) {
+            this.escTimer = setTimeout(() => {
+                this.escTimer = undefined;
+                this.flush();
+            }, 0);
+        }
+    }
+    /** Force any pending lone ESC out of the buffer. */
+    flush() {
+        if (this.escTimer) {
+            clearTimeout(this.escTimer);
+            this.escTimer = undefined;
+        }
+        if (this.buffer.length > 0 && this.buffer[0] === ESC && this.buffer.length === 1) {
+            this.buffer = this.buffer.subarray(1);
+            this.dispatchKey(new KeyEvent({ key: "escape", character: "", shift: false, ctrl: false, meta: false }));
+        }
+    }
+    // --- Internals ---
+    drain() {
+        while (this.buffer.length > 0) {
+            const result = this.consumeOne(this.buffer);
+            if (result.kind === "incomplete")
+                return;
+            this.buffer = this.buffer.subarray(result.bytes);
+            if (result.kind === "key")
+                this.dispatchKey(result.event);
+            else if (result.kind === "mouse")
+                this.dispatchMouse(result.event);
+            // skip → drop bytes silently
+        }
+    }
+    consumeOne(buf) {
+        const b0 = buf[0];
+        if (b0 === ESC)
+            return this.consumeEscape(buf);
+        // Ctrl+C
+        if (b0 === 0x03) {
+            return {
+                kind: "key",
+                bytes: 1,
+                event: new KeyEvent({ key: "c", character: "", shift: false, ctrl: true, meta: false }),
+            };
+        }
+        // Named single-byte keys (tab/enter/space/backspace).
+        const named = SINGLE_BYTE_KEYS[b0];
+        if (named && named !== "escape") {
+            return {
+                kind: "key",
+                bytes: 1,
+                event: new KeyEvent({
+                    key: named,
+                    character: named === "space" ? " " : "",
+                    shift: false,
+                    ctrl: false,
+                    meta: false,
+                }),
+            };
+        }
+        // Ctrl+letter (Ctrl+A=0x01 .. Ctrl+Z=0x1a), excluding the bytes already
+        // claimed by SINGLE_BYTE_KEYS above (tab=0x09, enter=0x0a/0x0d, backspace=0x08).
+        if (b0 < 0x20) {
+            const letter = String.fromCharCode(b0 + 0x60); // 0x01 → 'a'
+            return {
+                kind: "key",
+                bytes: 1,
+                event: new KeyEvent({ key: letter, character: "", shift: false, ctrl: true, meta: false }),
+            };
+        }
+        // Printable ASCII / start of a UTF-8 multibyte character.
+        return this.consumePrintable(buf);
+    }
+    consumePrintable(buf) {
+        const b0 = buf[0];
+        let len = 1;
+        if (b0 >= 0xc0 && b0 < 0xe0)
+            len = 2;
+        else if (b0 >= 0xe0 && b0 < 0xf0)
+            len = 3;
+        else if (b0 >= 0xf0)
+            len = 4;
+        if (buf.length < len)
+            return { kind: "incomplete" };
+        const character = UTF8_DECODER.decode(buf.subarray(0, len));
+        return {
+            kind: "key",
+            bytes: len,
+            event: new KeyEvent({
+                key: character.toLowerCase(),
+                character,
+                shift: character.length === 1 && character !== character.toLowerCase(),
+                ctrl: false,
+                meta: false,
+            }),
+        };
+    }
+    consumeEscape(buf) {
+        if (buf.length === 1)
+            return { kind: "incomplete" };
+        const b1 = buf[1];
+        // ESC [ ... → CSI
+        if (b1 === LBRACKET)
+            return this.consumeCSI(buf);
+        // ESC O X → SS3 (F1–F4 / arrows on some terms)
+        if (b1 === O_BYTE)
+            return this.consumeSS3(buf);
+        // ESC ESC → escape key (some terminals double-send). Consume BOTH bytes
+        // so the user sees one escape event, not two. Without this, the second
+        // ESC remained in the buffer and produced a second escape via the
+        // lone-ESC flush path.
+        if (b1 === ESC) {
+            return {
+                kind: "key",
+                bytes: 2,
+                event: new KeyEvent({ key: "escape", character: "", shift: false, ctrl: false, meta: false }),
+            };
+        }
+        // ESC <named> / ESC <printable> → Alt-modified key.
+        // Terminals encode Alt+<key> as the literal byte preceded by ESC, so
+        // `ESC b` is Alt+B, `ESC <0x7f>` is Alt+Backspace, `ESC <0x20>` is
+        // Alt+Space, etc. The router surfaces this as `{ key, meta: true }` —
+        // matching the shape used for Ctrl-modified keys, so handlers can
+        // branch on `event.meta` without parsing escape sequences themselves.
+        //
+        // [LAW:one-source-of-truth] Named single-byte keys (space, tab,
+        // enter, backspace) use the SAME canonical key names on the Alt path
+        // as on the non-Alt path. Without this, `Alt+Space` decoded as
+        // `key: " "` while a bare space decoded as `key: "space"`, so a
+        // handler couldn't match Alt+Space via `event.key === "space" &&
+        // event.meta`. Routing through SINGLE_BYTE_KEYS first preserves the
+        // canonical naming.
+        //
+        // [LAW:one-source-of-truth] Modifier decoding for *all* navigation keys
+        // lives in this file: CSI param-style modifiers (e.g. `ESC[1;3D` for
+        // Alt+Left) flow through `decodeModifier`, and ESC-prefixed Alt forms
+        // flow through this branch. Widgets read `event.meta` and never re-parse.
+        const namedAlt = SINGLE_BYTE_KEYS[b1];
+        if (namedAlt && namedAlt !== "escape") {
+            return {
+                kind: "key",
+                bytes: 2,
+                event: new KeyEvent({
+                    key: namedAlt,
+                    character: "",
+                    shift: false,
+                    ctrl: false,
+                    meta: true,
+                }),
+            };
+        }
+        if (b1 >= 0x20 && b1 <= 0x7e) {
+            const ch = String.fromCharCode(b1);
+            return {
+                kind: "key",
+                bytes: 2,
+                event: new KeyEvent({
+                    key: ch.toLowerCase(),
+                    character: "",
+                    shift: ch !== ch.toLowerCase(),
+                    ctrl: false,
+                    meta: true,
+                }),
+            };
+        }
+        // Truly unrecognised follow-up byte → treat the ESC as a lone escape
+        // and re-process from b1 on the next pass.
+        return {
+            kind: "key",
+            bytes: 1,
+            event: new KeyEvent({ key: "escape", character: "", shift: false, ctrl: false, meta: false }),
+        };
+    }
+    consumeSS3(buf) {
+        if (buf.length < 3)
+            return { kind: "incomplete" };
+        const final = String.fromCharCode(buf[2]);
+        const name = SS3_KEYS[final];
+        if (!name)
+            return { kind: "skip", bytes: 3 };
+        return {
+            kind: "key",
+            bytes: 3,
+            event: new KeyEvent({ key: name, character: "", shift: false, ctrl: false, meta: false }),
+        };
+    }
+    consumeCSI(buf) {
+        // buf starts with ESC [
+        const next = buf[2];
+        if (next === undefined)
+            return { kind: "incomplete" };
+        // X10 mouse: ESC [ M b x y  (3 raw bytes after M)
+        if (next === M_UPPER) {
+            if (buf.length < 6)
+                return { kind: "incomplete" };
+            const cb = buf[3] - 32;
+            const col = buf[4] - 32 - 1;
+            const row = buf[5] - 32 - 1;
+            return { kind: "mouse", bytes: 6, event: decodeMouseFromCb(cb, col, row, true) };
+        }
+        // SGR mouse: ESC [ < cb ; x ; y M|m
+        if (next === LANGLE) {
+            // Find terminator M or m.
+            for (let i = 3; i < buf.length; i++) {
+                const b = buf[i];
+                if (b === M_UPPER || b === M_LOWER) {
+                    const params = ASCII_DECODER.decode(buf.subarray(3, i));
+                    const parts = params.split(";");
+                    if (parts.length !== 3)
+                        return { kind: "skip", bytes: i + 1 };
+                    const cb = parseInt(parts[0], 10);
+                    const col = parseInt(parts[1], 10) - 1;
+                    const row = parseInt(parts[2], 10) - 1;
+                    if (Number.isNaN(cb) || Number.isNaN(col) || Number.isNaN(row)) {
+                        return { kind: "skip", bytes: i + 1 };
+                    }
+                    return {
+                        kind: "mouse",
+                        bytes: i + 1,
+                        event: decodeMouseFromCb(cb, col, row, b === M_UPPER),
+                    };
+                }
+            }
+            return { kind: "incomplete" };
+        }
+        // Generic CSI: collect parameter / intermediate bytes until a final byte
+        // in the range 0x40–0x7e is found.
+        let params = "";
+        for (let i = 2; i < buf.length; i++) {
+            const b = buf[i];
+            if (b >= 0x40 && b <= 0x7e) {
+                const final = String.fromCharCode(b);
+                return decodeCSI(params, final, i + 1);
+            }
+            params += String.fromCharCode(b);
+        }
+        return { kind: "incomplete" };
+    }
+    // --- Dispatch ---
+    // [LAW:dataflow-not-control-flow] Three-stage walk; same shape every
+    // dispatch, only the event's `stopped` flag short-circuits later stages.
+    // The router holds NO key-specific policy — Tab semantics live entirely
+    // in FocusManager (registered as a normal-priority handler at construction).
+    dispatchKey(event) {
+        // [LAW:one-source-of-truth] Snapshot the chain once at the start of
+        // dispatch. A handler that unsubscribes itself (or another handler)
+        // splices the live keyChain and would shift indices under the running
+        // for-of loop, silently skipping the next handler. The snapshot
+        // freezes the participant set for this dispatch; later registrations
+        // join the chain for the next event, removals take effect after.
+        const chain = [...this.keyChain];
+        // Stage 1: high-priority handlers (global overrides like Ctrl+C).
+        for (const entry of chain) {
+            if (event.stopped)
+                return;
+            if (entry.priority === "high")
+                entry.handler(event);
+        }
+        if (event.stopped)
+            return;
+        // Stage 2: the focused widget.
+        this.source.focusManager.current?.handleKey(event);
+        if (event.stopped)
+            return;
+        // Stage 3: normal-priority handlers (FocusManager's Tab traversal,
+        // plus any app-registered fallbacks).
+        for (const entry of chain) {
+            if (event.stopped)
+                return;
+            if (entry.priority === "normal")
+                entry.handler(event);
+        }
+    }
+    dispatchMouse(event) {
+        for (const handler of this.mouseHandlers)
+            handler(event);
+        const frame = this.source.frame;
+        const hit = widgetAt(frame, event.x, event.y);
+        this.pointer = { x: event.x, y: event.y };
+        this.hover(hit?.widget ?? null);
+        // The wheel scrolls the innermost viewport under the pointer that can
+        // move, a line a notch, past any widget it shows there and whatever a
+        // drag captured. With none, nothing moved and there is nothing to paint.
+        if (event.type === "scroll_up" || event.type === "scroll_down") {
+            const lines = event.type === "scroll_down" ? 1 : -1;
+            const target = scrollTargetAt(frame, event.x, event.y, lines);
+            if (!target)
+                return;
+            target.scrollBy(lines);
+            this.source.refresh();
+            return;
+        }
+        // [LAW:dataflow-not-control-flow] Same pipeline every event; the
+        // capture value and event type pick the target. mouse_down opens a
+        // capture, mouse_up closes it, mouse_move in between routes to the
+        // captured widget regardless of pointer position. A hit's origin puts the
+        // pressed cell at its own column and row, so every delivery is the same
+        // subtraction.
+        const useCapture = event.type === "mouse_move" || event.type === "mouse_up";
+        const target = (useCapture && this.captured ? relocate(frame, this.captured) : null) ??
+            (hit ? { widget: hit.widget, originX: event.x - hit.col, originY: event.y - hit.row } : null);
+        target?.widget.handleMouse({
+            ...event,
+            x: event.x - target.originX,
+            y: event.y - target.originY,
+            over: drew(frame, target.widget, event.x, event.y),
+        });
+        if (event.type === "mouse_down")
+            this.captured = target;
+        else if (event.type === "mouse_up")
+            this.captured = null;
+    }
+    // [LAW:single-enforcer] The canonical setter on the widget is the only
+    // writer of `hovered`; this is the only caller, and only on a change.
+    hover(widget) {
+        if (widget === this.hoveredWidget)
+            return;
+        this.hoveredWidget?.setHovered(false);
+        widget?.setHovered(true);
+        this.hoveredWidget = widget;
+    }
+}
+// --- Helpers ---
+// [LAW:one-source-of-truth] A captured widget's origin is read off the frame
+// just painted, so a drag follows the widget if it moved since the press; one
+// no longer painted is where the press found it.
+function relocate(frame, target) {
+    const origin = originOf(frame, target.widget);
+    return origin ? { widget: target.widget, originX: origin.x, originY: origin.y } : target;
+}
+function decodeMouseFromCb(cb, x, y, isPress) {
+    const isMotion = (cb & 32) !== 0;
+    const isScroll = (cb & 64) !== 0;
+    const button = cb & 3;
+    const shift = !!(cb & 4);
+    const ctrl = !!(cb & 16); // bit 16 = ctrl in xterm encoding
+    if (isScroll) {
+        const type = button === 0 ? "scroll_up" : "scroll_down";
+        return { type, x, y, button: 0, shift, ctrl };
+    }
+    if (isMotion) {
+        return { type: "mouse_move", x, y, button, shift, ctrl };
+    }
+    return {
+        type: isPress ? "mouse_down" : "mouse_up",
+        x,
+        y,
+        button,
+        shift,
+        ctrl,
+    };
+}
+function decodeCSI(params, final, bytes) {
+    // Handle modifier suffixes like `1;2A` (shift+up). We split params on `;`.
+    const parts = params.split(";");
+    const first = parts[0] ?? "";
+    const mod = parseInt(parts[1] ?? "", 10);
+    const { shift, ctrl, meta } = decodeModifier(mod);
+    if (final === "~") {
+        const name = CSI_TILDE_KEYS[first];
+        if (!name)
+            return { kind: "skip", bytes };
+        return {
+            kind: "key",
+            bytes,
+            event: new KeyEvent({ key: name, character: "", shift, ctrl, meta }),
+        };
+    }
+    const name = CSI_LETTER_KEYS[final];
+    if (!name)
+        return { kind: "skip", bytes };
+    // Special case: ESC[Z is shift+tab regardless of explicit modifier.
+    // [LAW:one-source-of-truth] `character` is the printable character the
+    // key would produce, or "" for non-printable / modifier-only events.
+    // The non-shifted tab path emits character: "" (Tab is named, not
+    // printed) — keep shift+tab consistent. Distinguish via key === "tab"
+    // + shift, not character.
+    if (final === "Z") {
+        return {
+            kind: "key",
+            bytes,
+            event: new KeyEvent({ key: "tab", character: "", shift: true, ctrl: false, meta: false }),
+        };
+    }
+    return {
+        kind: "key",
+        bytes,
+        event: new KeyEvent({ key: name, character: "", shift, ctrl, meta }),
+    };
+}
+function decodeModifier(mod) {
+    if (!Number.isFinite(mod) || mod <= 1) {
+        return { shift: false, ctrl: false, meta: false };
+    }
+    const bits = mod - 1;
+    return {
+        shift: (bits & 1) !== 0,
+        meta: (bits & 2) !== 0,
+        ctrl: (bits & 4) !== 0,
+    };
+}

package/dist/widgets/focus-manager.d.ts

@@ -0,0 +1,45 @@
+/**
+ * FocusManager — which widget has focus, over the widgets on the frame.
+ * [LAW:one-source-of-truth] single authority for which widget has focus.
+ * [LAW:dataflow-not-control-flow] focus transitions are observable state;
+ * widgets react to focus/blur events, the manager never skips dispatch.
+ */
+import type { InteractiveWidget, FocusManager, KeyEvent } from "./types.js";
+import type { Unsubscribe } from "../core/subscription.js";
+export declare class DefaultFocusManager implements FocusManager {
+    private readonly onScreen;
+    accessor currentWidget: InteractiveWidget | null;
+    private readonly changeHandlers;
+    /**
+     * `onScreen` is the widgets on the frame on screen, in document order.
+     *
+     * [LAW:one-source-of-truth] It is asked every time rather than kept: a list
+     * of the widgets held here would be a second picture of the frame, and
+     * wrong from the next paint.
+     */
+    constructor(onScreen: () => readonly InteractiveWidget[]);
+    get current(): InteractiveWidget | null;
+    get widgets(): readonly InteractiveWidget[];
+    next(): void;
+    prev(): void;
+    focus(widget: InteractiveWidget): void;
+    /**
+     * Put focus where the frame just painted lets it rest: it stays on a widget
+     * the view drew (`drawn`) that can take it, and otherwise moves to the first
+     * one on screen that can, or to none.
+     *
+     * Drawn, not on screen: a widget cropped for the moment — the terminal
+     * shrank, a viewport scrolled, an overlay covers it — is still in the view,
+     * and keeps focus and whatever focus holds, like a half-typed filter.
+     *
+     * [LAW:single-enforcer] The one place focus follows the frame — onto the
+     * first widget when the app starts, off a widget that stopped being drawn
+     * or was disabled.
+     */
+    settle(drawn: readonly InteractiveWidget[]): void;
+    onChange(handler: (current: InteractiveWidget | null) => void): Unsubscribe;
+    handleKey(event: KeyEvent): void;
+    private clear;
+    private setFocus;
+    private emitChange;
+}