@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/widgets/toggle.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Toggle widget — on/off switch with label and variant colour.
+ * [LAW:dataflow-not-control-flow] one Segment of fixed width every render;
+ * indicator and palette keys come from observable state via lookup tables.
+ * [LAW:one-type-per-behavior] shared infrastructure inherited from WidgetBase.
+ *
+ * Visual states:
+ *   off       — "[OFF] label" with muted variant background
+ *   on        — "[ON]  label" with full variant accent background
+ *   focused   — underline on the segment (no width change)
+ *   disabled  — dimmed
+ */
+import { Segment } from "../core/segment.js";
+import type { RenderOptions } from "../core/protocol.js";
+import type { TerminalTheme } from "../core/color.js";
+import { WidgetBase } from "./widget-base.js";
+import type { KeyEvent, WidgetMouseEvent } from "./types.js";
+export type ToggleVariant = "default" | "primary" | "success" | "warning" | "danger";
+export interface ToggleOptions {
+    label: string;
+    on?: boolean;
+    id?: string;
+    disabled?: boolean;
+    theme?: TerminalTheme;
+    variant?: ToggleVariant;
+}
+export declare class Toggle extends WidgetBase {
+    readonly id: string;
+    readonly focusable = true;
+    accessor label: string;
+    accessor on: boolean;
+    accessor variant: ToggleVariant;
+    private accessor _theme;
+    constructor(options: ToggleOptions);
+    setTheme(theme: TerminalTheme): void;
+    handleKey(event: KeyEvent): void;
+    handleMouse(event: WidgetMouseEvent): void;
+    protected draw(_options: RenderOptions): Iterable<Segment>;
+    measure(_options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    private resolvePalette;
+}

package/dist/widgets/toggle.js

@@ -0,0 +1,180 @@
+/**
+ * Toggle widget — on/off switch with label and variant colour.
+ * [LAW:dataflow-not-control-flow] one Segment of fixed width every render;
+ * indicator and palette keys come from observable state via lookup tables.
+ * [LAW:one-type-per-behavior] shared infrastructure inherited from WidgetBase.
+ *
+ * Visual states:
+ *   off       — "[OFF] label" with muted variant background
+ *   on        — "[ON]  label" with full variant accent background
+ *   focused   — underline on the segment (no width change)
+ *   disabled  — dimmed
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { observable, action, observableRef } from "mobx";
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import { ColorSpec } from "../core/color.js";
+import { cellLen } from "../core/cells.js";
+import { DEFAULT_TERMINAL_THEME } from "../themes/terminalThemes.js";
+import { WidgetBase } from "./widget-base.js";
+// onFg uses on-${accent} (WCAG-correct contrast, picked once at palette
+// build time) so the ON state stays readable on a full accent bg. Earlier
+// versions used text-${accent} here, which is mostly-accent and clashed
+// with the same accent as background. offFg keeps text-${accent} because
+// offBg is mostly-bg-tinted and the contrast holds.
+const VARIANT_KEYS = {
+    default: { onBg: "primary", onFg: "on-primary", offBg: "surface", offFg: "foreground" },
+    primary: { onBg: "primary", onFg: "on-primary", offBg: "primary-muted", offFg: "text-primary" },
+    success: { onBg: "success", onFg: "on-success", offBg: "success-muted", offFg: "text-success" },
+    warning: { onBg: "warning", onFg: "on-warning", offBg: "warning-muted", offFg: "text-warning" },
+    danger: { onBg: "error", onFg: "on-error", offBg: "error-muted", offFg: "text-error" },
+};
+let Toggle = (() => {
+    let _classSuper = WidgetBase;
+    let _instanceExtraInitializers = [];
+    let _label_decorators;
+    let _label_initializers = [];
+    let _label_extraInitializers = [];
+    let _on_decorators;
+    let _on_initializers = [];
+    let _on_extraInitializers = [];
+    let _variant_decorators;
+    let _variant_initializers = [];
+    let _variant_extraInitializers = [];
+    let __theme_decorators;
+    let __theme_initializers = [];
+    let __theme_extraInitializers = [];
+    let _setTheme_decorators;
+    let _handleKey_decorators;
+    let _handleMouse_decorators;
+    return class Toggle extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _label_decorators = [observable];
+            _on_decorators = [observable];
+            _variant_decorators = [observableRef];
+            __theme_decorators = [observableRef];
+            _setTheme_decorators = [action];
+            _handleKey_decorators = [action];
+            _handleMouse_decorators = [action];
+            __esDecorate(this, null, _label_decorators, { kind: "accessor", name: "label", static: false, private: false, access: { has: obj => "label" in obj, get: obj => obj.label, set: (obj, value) => { obj.label = value; } }, metadata: _metadata }, _label_initializers, _label_extraInitializers);
+            __esDecorate(this, null, _on_decorators, { kind: "accessor", name: "on", static: false, private: false, access: { has: obj => "on" in obj, get: obj => obj.on, set: (obj, value) => { obj.on = value; } }, metadata: _metadata }, _on_initializers, _on_extraInitializers);
+            __esDecorate(this, null, _variant_decorators, { kind: "accessor", name: "variant", static: false, private: false, access: { has: obj => "variant" in obj, get: obj => obj.variant, set: (obj, value) => { obj.variant = value; } }, metadata: _metadata }, _variant_initializers, _variant_extraInitializers);
+            __esDecorate(this, null, __theme_decorators, { kind: "accessor", name: "_theme", static: false, private: false, access: { has: obj => "_theme" in obj, get: obj => obj._theme, set: (obj, value) => { obj._theme = value; } }, metadata: _metadata }, __theme_initializers, __theme_extraInitializers);
+            __esDecorate(this, null, _setTheme_decorators, { kind: "method", name: "setTheme", static: false, private: false, access: { has: obj => "setTheme" in obj, get: obj => obj.setTheme }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _handleKey_decorators, { kind: "method", name: "handleKey", static: false, private: false, access: { has: obj => "handleKey" in obj, get: obj => obj.handleKey }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _handleMouse_decorators, { kind: "method", name: "handleMouse", static: false, private: false, access: { has: obj => "handleMouse" in obj, get: obj => obj.handleMouse }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        id = __runInitializers(this, _instanceExtraInitializers);
+        focusable = true;
+        #label_accessor_storage = __runInitializers(this, _label_initializers, void 0);
+        get label() { return this.#label_accessor_storage; }
+        set label(value) { this.#label_accessor_storage = value; }
+        #on_accessor_storage = (__runInitializers(this, _label_extraInitializers), __runInitializers(this, _on_initializers, void 0));
+        get on() { return this.#on_accessor_storage; }
+        set on(value) { this.#on_accessor_storage = value; }
+        #variant_accessor_storage = (__runInitializers(this, _on_extraInitializers), __runInitializers(this, _variant_initializers, void 0));
+        get variant() { return this.#variant_accessor_storage; }
+        set variant(value) { this.#variant_accessor_storage = value; }
+        #_theme_accessor_storage = (__runInitializers(this, _variant_extraInitializers), __runInitializers(this, __theme_initializers, void 0));
+        // [LAW:types-are-the-program] @observableRef so setTheme() triggers a
+        // re-render — see slider.ts.
+        get _theme() { return this.#_theme_accessor_storage; }
+        set _theme(value) { this.#_theme_accessor_storage = value; }
+        constructor(options) {
+            super();
+            __runInitializers(this, __theme_extraInitializers);
+            this.id = options.id ?? `toggle-${options.label.toLowerCase().replace(/\s+/g, "-")}`;
+            this.label = options.label;
+            this.on = options.on ?? false;
+            this.variant = options.variant ?? "default";
+            this.disabled = options.disabled ?? false;
+            this._theme = options.theme ?? DEFAULT_TERMINAL_THEME;
+        }
+        setTheme(theme) { this._theme = theme; }
+        // --- Event handlers ---
+        handleKey(event) {
+            if (this.disabled)
+                return;
+            if (event.key === "space") {
+                this.on = !this.on;
+                this.emitChange();
+                event.stop();
+                return;
+            }
+            if (event.key === "enter") {
+                this.emitSubmit();
+                event.stop();
+            }
+        }
+        handleMouse(event) {
+            if (this.disabled)
+                return;
+            // A release that dragged off the toggle cancels the press.
+            if (event.type === "mouse_up" && event.over) {
+                this.on = !this.on;
+                this.emitChange();
+            }
+        }
+        // --- Rendering ---
+        draw(_options) {
+            // Both indicators are exactly 5 cells: "[ON] " and "[OFF]".
+            const indicator = this.on ? "[ON] " : "[OFF]";
+            const text = `${indicator} ${this.label}`;
+            if (this.disabled) {
+                return [new Segment(text, new Style({ color: "#666666", bgcolor: "#333333", dim: true }))];
+            }
+            const keys = VARIANT_KEYS[this.variant];
+            const fg = this.resolvePalette(this.on ? keys.onFg : keys.offFg);
+            const bg = this.resolvePalette(this.on ? keys.onBg : keys.offBg);
+            return [new Segment(text, new Style({ color: fg, bgcolor: bg, underline: this.focused }))];
+        }
+        measure(_options) {
+            // [LAW:one-source-of-truth] cellLen — see button.ts.
+            const width = 5 + 1 + cellLen(this.label);
+            return { minimum: width, maximum: width };
+        }
+        // --- Palette resolution ---
+        resolvePalette(key) {
+            const rgba = this._theme.palette.get(key);
+            // [LAW:no-defensive-null-guards] palette must contain all keys; missing is a construction bug.
+            return ColorSpec.fromRgba(rgba);
+        }
+    };
+})();
+export { Toggle };

package/dist/widgets/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Interactive widget event types and core interfaces.
+ * [LAW:one-source-of-truth] These types are the single authority for the widget contract.
+ * Widgets are MobX-observable state machines that implement Renderable,
+ * producing Segment[] from current state. They have no knowledge of stdin,
+ * terminal escape sequences, or their host environment.
+ */
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Segment } from "../core/segment.js";
+import type { Unsubscribe } from "../core/subscription.js";
+export interface KeyEventInit {
+    key: string;
+    character: string;
+    shift: boolean;
+    ctrl: boolean;
+    meta: boolean;
+}
+export declare class KeyEvent {
+    readonly key: string;
+    readonly character: string;
+    readonly shift: boolean;
+    readonly ctrl: boolean;
+    readonly meta: boolean;
+    private _stopped;
+    constructor(init: KeyEventInit);
+    get stopped(): boolean;
+    stop(): void;
+}
+export type KeyHandlerPriority = "high" | "normal";
+export interface KeyHandlerOptions {
+    priority?: KeyHandlerPriority;
+}
+export type ScreenMouseEvent = {
+    [T in MouseEventType]: MouseEventOf<T>;
+}[MouseEventType];
+type MouseEventType = "mouse_down" | "mouse_up" | "mouse_move" | "scroll_up" | "scroll_down";
+interface MouseEventOf<Type extends string> {
+    type: Type;
+    x: number;
+    y: number;
+    button: number;
+    shift: boolean;
+    ctrl: boolean;
+}
+export interface WidgetMouseEvent extends MouseEventOf<"mouse_down" | "mouse_up" | "mouse_move"> {
+    over: boolean;
+}
+export interface WidgetFocusEvent {
+    type: "focus" | "blur";
+}
+export interface InteractiveWidget extends Renderable, Measurable {
+    readonly id: string;
+    readonly focusable: boolean;
+    focused: boolean;
+    hovered: boolean;
+    active: boolean;
+    disabled: boolean;
+    handleKey(event: KeyEvent): void;
+    handleMouse(event: WidgetMouseEvent): void;
+    handleFocus(event: WidgetFocusEvent): void;
+    focus(): void;
+    blur(): void;
+    setDisabled(value: boolean): void;
+    setHovered(value: boolean): void;
+    onChange(handler: (widget: InteractiveWidget) => void): Unsubscribe;
+    onSubmit(handler: (widget: InteractiveWidget) => void): Unsubscribe;
+}
+export interface OverlayRenderable {
+    renderOverlay(options: RenderOptions): Iterable<Segment> | null;
+}
+export declare function hasOverlay(value: object): value is OverlayRenderable;
+export interface FocusManager {
+    readonly current: InteractiveWidget | null;
+    /** The widgets Tab moves between, in the order it moves. */
+    readonly widgets: readonly InteractiveWidget[];
+    next(): void;
+    prev(): void;
+    focus(widget: InteractiveWidget): void;
+    handleKey(event: KeyEvent): void;
+    onChange(handler: (current: InteractiveWidget | null) => void): Unsubscribe;
+}
+export interface FrameSource {
+    readonly focusManager: FocusManager;
+    readonly frame: readonly (readonly Segment[])[];
+    refresh(): void;
+}
+export {};

package/dist/widgets/types.js

@@ -0,0 +1,30 @@
+/**
+ * Interactive widget event types and core interfaces.
+ * [LAW:one-source-of-truth] These types are the single authority for the widget contract.
+ * Widgets are MobX-observable state machines that implement Renderable,
+ * producing Segment[] from current state. They have no knowledge of stdin,
+ * terminal escape sequences, or their host environment.
+ */
+export class KeyEvent {
+    key;
+    character;
+    shift;
+    ctrl;
+    meta;
+    _stopped = false;
+    constructor(init) {
+        this.key = init.key;
+        this.character = init.character;
+        this.shift = init.shift;
+        this.ctrl = init.ctrl;
+        this.meta = init.meta;
+    }
+    get stopped() { return this._stopped; }
+    // Claim this key. Halts further chain dispatch — no high/normal handler
+    // and no focused-widget handler downstream of the caller will see it.
+    stop() { this._stopped = true; }
+}
+export function hasOverlay(value) {
+    return ("renderOverlay" in value &&
+        typeof value.renderOverlay === "function");
+}

package/dist/widgets/widget-app.d.ts

@@ -0,0 +1,63 @@
+/**
+ * WidgetApp — an `App` whose view has widgets in it: keys reach the focused
+ * widget, the pointer reaches the widget that drew the cell under it, and a
+ * change to anything a frame read paints the next one.
+ *
+ * A widget goes wherever a renderable goes — in a `Panel`, a `Layout` pane, a
+ * `Table` cell — and nothing lays it out a second time. Everything added here
+ * reads the frame the view drew:
+ *
+ * - Focus moves in document order: the order widgets start to render in
+ *   (`RenderOptions.onDraw`), among those with a cell on the frame on screen.
+ *   Not reading order — in a `Layout` split into columns, reading order
+ *   zigzags between the columns row by row.
+ * - Overlays are painted over the view's frame, in document order, directly
+ *   below their owner's footprint (`OverlayRenderable`). Paint order is the
+ *   z-order: a later overlay covers an earlier one.
+ * - A pointer event goes to the innermost widget that drew the cell under it
+ *   (`widgetAt`), in that widget's own coordinates; the wheel goes to the
+ *   innermost `Viewport` that can move (`scrollTargetAt`).
+ *
+ * [LAW:locality-or-seam] `App` knows nothing of widgets — `host/` depends on
+ * `core/` alone — and this reaches it only through the seams it already has:
+ * the view is a renderable, and `onPaint` hears the frame.
+ */
+import { Segment } from "../core/segment.js";
+import type { Unsubscribe } from "../core/subscription.js";
+import { type AppOptions, type AppPhase } from "../host/app.js";
+import type { FocusManager, FrameSource, KeyEvent, KeyHandlerOptions, ScreenMouseEvent } from "./types.js";
+export declare class WidgetApp implements FrameSource {
+    readonly focusManager: FocusManager;
+    private readonly focus;
+    private readonly app;
+    private readonly router;
+    private readonly reaction;
+    private drawn;
+    constructor(options: AppOptions);
+    get phase(): AppPhase;
+    /** The rows on screen now, as painted: what a pointer event lands on. */
+    get frame(): readonly (readonly Segment[])[];
+    /**
+     * Take the terminal, paint the first frame, and route input to its widgets
+     * until the app stops — `App.run`, with the input.
+     */
+    run(): Promise<void>;
+    stop(): void;
+    fail(error: unknown): void;
+    /**
+     * Paint the next frame, as `App.refresh` does. A change to an observable
+     * the view read needs none; one no observable carries — a `Viewport`
+     * scrolled from a key handler — does.
+     */
+    refresh(): void;
+    suspend(): Promise<void>;
+    /**
+     * Hear every key. A `high` handler hears it before the focused widget, a
+     * `normal` one after it — and after Tab has moved focus — and a handler
+     * that calls `event.stop()` ends the key there.
+     */
+    onKey(handler: (event: KeyEvent) => void, options?: KeyHandlerOptions): Unsubscribe;
+    /** Hear every pointer event, in terminal cells, before any widget does. */
+    onMouse(handler: (event: ScreenMouseEvent) => void): Unsubscribe;
+    private compose;
+}

package/dist/widgets/widget-app.js

@@ -0,0 +1,199 @@
+/**
+ * WidgetApp — an `App` whose view has widgets in it: keys reach the focused
+ * widget, the pointer reaches the widget that drew the cell under it, and a
+ * change to anything a frame read paints the next one.
+ *
+ * A widget goes wherever a renderable goes — in a `Panel`, a `Layout` pane, a
+ * `Table` cell — and nothing lays it out a second time. Everything added here
+ * reads the frame the view drew:
+ *
+ * - Focus moves in document order: the order widgets start to render in
+ *   (`RenderOptions.onDraw`), among those with a cell on the frame on screen.
+ *   Not reading order — in a `Layout` split into columns, reading order
+ *   zigzags between the columns row by row.
+ * - Overlays are painted over the view's frame, in document order, directly
+ *   below their owner's footprint (`OverlayRenderable`). Paint order is the
+ *   z-order: a later overlay covers an earlier one.
+ * - A pointer event goes to the innermost widget that drew the cell under it
+ *   (`widgetAt`), in that widget's own coordinates; the wheel goes to the
+ *   innermost `Viewport` that can move (`scrollTargetAt`).
+ *
+ * [LAW:locality-or-seam] `App` knows nothing of widgets — `host/` depends on
+ * `core/` alone — and this reaches it only through the seams it already has:
+ * the view is a renderable, and `onPaint` hears the frame.
+ */
+import { Reaction } from "mobx";
+import { Segment } from "../core/segment.js";
+import { App } from "../host/app.js";
+import { DefaultFocusManager } from "./focus-manager.js";
+import { EventRouter } from "./event-router.js";
+import { footprintOf, ownersOn } from "./hit.js";
+import { hasOverlay } from "./types.js";
+import { WidgetBase } from "./widget-base.js";
+export class WidgetApp {
+    focusManager;
+    focus;
+    app;
+    router;
+    // Paints the next frame when anything the last one read changes.
+    reaction;
+    // The widgets the view drew for the frame on screen, in document order.
+    drawn = [];
+    constructor(options) {
+        const { view } = options;
+        this.reaction = new Reaction("WidgetApp", () => this.app.refresh());
+        const root = { render: (renderOptions) => this.compose(view, renderOptions) };
+        this.app = new App({ ...options, view: () => root });
+        this.focus = new DefaultFocusManager(() => {
+            const owners = ownersOn(this.app.frame);
+            return this.drawn.filter((widget) => owners.has(widget));
+        });
+        this.focusManager = this.focus;
+        this.router = new EventRouter({ source: this, host: options.host });
+        this.app.onPaint(() => {
+            this.focus.settle(this.drawn);
+            this.router.framePainted();
+        });
+        // [LAW:single-enforcer] `settle` judges every focus move, so every move
+        // paints — including one onto a widget no frame has read yet.
+        this.focus.onChange(() => this.app.refresh());
+    }
+    get phase() {
+        return this.app.phase;
+    }
+    /** The rows on screen now, as painted: what a pointer event lands on. */
+    get frame() {
+        return this.app.frame;
+    }
+    /**
+     * Take the terminal, paint the first frame, and route input to its widgets
+     * until the app stops — `App.run`, with the input.
+     */
+    async run() {
+        // App refuses a second run; this one must not end the input of the first.
+        if (this.app.phase !== "idle")
+            return this.app.run();
+        // Listening before the app starts, so a first frame that throws — and
+        // stops the host — is not followed by a subscription that restarts it.
+        this.router.start();
+        const running = this.app.run();
+        try {
+            await running;
+        }
+        finally {
+            this.router.stop();
+            this.reaction.dispose();
+        }
+    }
+    stop() {
+        this.app.stop();
+    }
+    fail(error) {
+        this.app.fail(error);
+    }
+    /**
+     * Paint the next frame, as `App.refresh` does. A change to an observable
+     * the view read needs none; one no observable carries — a `Viewport`
+     * scrolled from a key handler — does.
+     */
+    refresh() {
+        this.app.refresh();
+    }
+    suspend() {
+        return this.app.suspend();
+    }
+    /**
+     * Hear every key. A `high` handler hears it before the focused widget, a
+     * `normal` one after it — and after Tab has moved focus — and a handler
+     * that calls `event.stop()` ends the key there.
+     */
+    onKey(handler, options) {
+        return this.router.onKey(handler, options);
+    }
+    /** Hear every pointer event, in terminal cells, before any widget does. */
+    onMouse(handler) {
+        return this.router.onMouse(handler);
+    }
+    compose(view, options) {
+        const drawn = new Set();
+        // [LAW:parse-dont-validate] An owner is any object; only a `WidgetBase`
+        // reports itself as a widget, so this is where `object` becomes one.
+        const onDraw = (owner) => {
+            if (owner instanceof WidgetBase)
+                drawn.add(owner);
+        };
+        // The view, its render and the overlays are all tracked, so an observable
+        // any of them reads — a label, `focused`, the state that picks what the
+        // view shows — paints the next frame when it changes.
+        // An overlay reports what it draws too: a widget in it is on the frame,
+        // and visiting `drawn` in insertion order paints its overlay in turn.
+        const render = { ...options, onDraw };
+        const lines = tracked(this.reaction, () => {
+            const base = Segment.splitLines(view().render(render));
+            for (const widget of drawn)
+                paintOverlay(base, widget, render);
+            return base;
+        });
+        this.drawn = [...drawn];
+        return lines.flatMap((line) => [...line, Segment.line()]);
+    }
+}
+/**
+ * `fn`, with every observable it reads subscribed to by `reaction`.
+ *
+ * [LAW:no-silent-failure] mobx reports an error thrown inside `track` and
+ * carries on, which would paint an empty frame for a view that threw. The
+ * error is carried out instead, and fails the app as `App` fails on any frame
+ * that throws.
+ */
+function tracked(reaction, fn) {
+    // Written inside `track`, which the compiler cannot see run.
+    let outcome = {
+        ok: false,
+        error: new Error("WidgetApp: a frame drawn after the app stopped"),
+    };
+    reaction.track(() => {
+        try {
+            outcome = { ok: true, value: fn() };
+        }
+        catch (error) {
+            outcome = { ok: false, error };
+        }
+    });
+    if (!outcome.ok)
+        throw outcome.error;
+    return outcome.value;
+}
+/**
+ * Paint `widget`'s overlay over `lines`, below its footprint and at the column
+ * of its row 0, each overlay row stamped as the widget's row below its last —
+ * so a click there reaches the widget, in its own coordinates. A widget whose
+ * row 0 is not on the frame has nowhere to hang an overlay, and paints none.
+ */
+function paintOverlay(lines, widget, options) {
+    if (!hasOverlay(widget))
+        return;
+    const at = footprintOf(lines, widget);
+    if (!at)
+        return;
+    // An overlay floats over the frame; no region holds it.
+    const overlay = widget.renderOverlay({ ...options, height: undefined });
+    if (overlay === null)
+        return;
+    const width = Math.max(0, options.maxWidth - at.x);
+    const rows = Segment.anchorLines(Segment.splitLines(overlay), widget, at.rows).map((line) => Segment.adjustLineLength(line, width, undefined, false));
+    paintLines(lines, rows, at.x, at.y + at.rows);
+}
+// Paint `rows` into `lines` with its top-left cell at (x, y), growing `lines`
+// as needed; each painted cell replaces the one beneath it.
+function paintLines(lines, rows, x, y) {
+    while (lines.length < y + rows.length)
+        lines.push([]);
+    rows.forEach((source, i) => {
+        const row = lines[y + i];
+        // Padded to `x`, so a row that ends short of the overlay still reaches it.
+        const gap = Math.max(0, x - Segment.getLineLength(row));
+        const [before = [], , after = []] = Segment.divide([...row, new Segment(" ".repeat(gap))], [x, x + Segment.getLineLength(source)]);
+        lines[y + i] = [...before, ...source, ...after];
+    });
+}

package/dist/widgets/widget-base.d.ts

@@ -0,0 +1,40 @@
+/**
+ * WidgetBase — shared MobX observable foundation for interactive widgets.
+ * [LAW:one-type-per-behavior] All widgets share the same base; differences
+ * are in configuration and state, not in infrastructure.
+ *
+ * Reactive state is declared with TC39 decorators, which MobX 7 requires on
+ * `accessor` members. Each decorator registers its own member, so there is no
+ * makeObservable call and subclasses add observables the same way.
+ */
+import { Segment } from "../core/segment.js";
+import type { RenderOptions } from "../core/protocol.js";
+import type { InteractiveWidget, KeyEvent, WidgetMouseEvent, WidgetFocusEvent } from "./types.js";
+import type { Unsubscribe } from "../core/subscription.js";
+export declare abstract class WidgetBase implements InteractiveWidget {
+    abstract readonly id: string;
+    abstract readonly focusable: boolean;
+    accessor focused: boolean;
+    accessor hovered: boolean;
+    accessor active: boolean;
+    accessor disabled: boolean;
+    private readonly changeHandlers;
+    private readonly submitHandlers;
+    abstract handleKey(event: KeyEvent): void;
+    handleMouse(_event: WidgetMouseEvent): void;
+    handleFocus(event: WidgetFocusEvent): void;
+    focus(): void;
+    blur(): void;
+    setDisabled(value: boolean): void;
+    setHovered(value: boolean): void;
+    onChange(handler: (widget: InteractiveWidget) => void): Unsubscribe;
+    onSubmit(handler: (widget: InteractiveWidget) => void): Unsubscribe;
+    protected emitChange(): void;
+    protected emitSubmit(): void;
+    render(options: RenderOptions): Iterable<Segment>;
+    protected abstract draw(options: RenderOptions): Iterable<Segment>;
+    abstract measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}