@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/template-bindings/index.js

@@ -14,10 +14,10 @@
  * - `paletteFuncs(getPalette)` — `color` and `ramp`, the two functions that
  *   resolve a palette name. This is the *only* registration that knows a
  *   palette exists. [LAW:one-way-deps]
- * - `animationFuncs(frameTime)` — `frames` and `stepped`, a fragment and a
- *   colour drawn for a moment. It is the only registration that knows the
- *   template is evaluated at a time, and the time is the host's to hand in
- *   (`./animation-funcs.ts`).
+ * - `animationFuncs(frame)` — `frames`, `stepped`, `tween`, `loop` and
+ *   `glyphs`, drawn for a moment on a timeline. It is the only registration
+ *   that knows the template is evaluated at a time, and the time and the
+ *   timeline are the host's to hand in (`./animation-funcs.ts`).
  *
  * `createRichTextEngine()` wires up `richTextFuncs()` only — it cannot supply a
  * palette. Consumers that name theme colours call `paletteFuncs(getPalette)`
@@ -40,11 +40,12 @@ import { createEngine } from "@promptctl/go-template-js";
 import { RichText } from "../core/text.js";
 import { Style } from "../core/style.js";
 import { Segment } from "../core/segment.js";
+import { render } from "../core/protocol.js";
 import { richTextStyleFuncs } from "./style-funcs.js";
 import { colorFuncs } from "./color-funcs.js";
 export { paletteFuncs } from "./palette-funcs.js";
 export { colorFuncs, readableOnFunc } from "./color-funcs.js";
-export { animationFuncs } from "./animation-funcs.js";
+export { animationFuncs, templateFrame } from "./animation-funcs.js";
 /**
  * Funcs registered by the rich-js binding — the colour sinks, the palette-free
  * colour math, text attributes, and the `link` cell-splitter. Nothing here
@@ -131,7 +132,7 @@ export function renderTemplate(engine, source, scope = {}, options) {
     catch (e) {
         return [new Segment(errorLine(e, maxWidth), safeErrorStyle(errorStyle))];
     }
-    return Array.from(text.render({ isTerminal: true, ...renderOptions, maxWidth }));
+    return Array.from(render(text, { isTerminal: true, ...renderOptions, maxWidth }));
 }
 /**
  * A caught error as the one line `renderTemplate` promises. The summary is the

package/dist/themes/ramp.d.ts

@@ -20,17 +20,38 @@
  * theme colors passes through perceptually even steps rather than the muddy
  * midpoints of an sRGB blend.
  *
- * [LAW:one-way-deps] Imports `core/color`, `core/easing` and `core/oklch`
- * only; nothing here knows what a palette is. Resolving stop *names* is the template binding's
+ * A ramp also carries how far it has been moved: `scroll`, in spans, how
+ * far its colours have travelled along it, and `hue`, in turns, how far
+ * they are rotated round the OKLCH hue circle. A moved ramp is still a
+ * `ColorRamp`, so anything that reads a ramp reads a moving one frame by
+ * frame (`moving`) with nothing new to learn. [LAW:one-type-per-behavior]
+ *
+ * [LAW:one-way-deps] Imports `core/color`, `core/easing`, `core/oklch`,
+ * `core/animation` for `over` and `moving`, and `core/tween` for `over`; nothing
+ * here knows what a palette is. Resolving stop *names* is the template binding's
  * job (`paletteFuncs`), which hands this module resolved colors.
  */
+import { Animation } from "../core/animation.js";
 import type { ColorRgba } from "../core/color.js";
-import type { Ease } from "../core/easing.js";
+import { type Ease } from "../core/easing.js";
 /** One stop: the color the ramp is exactly `color` at position `at`. */
 export interface ColorStop {
     readonly at: number;
     readonly color: ColorRgba;
 }
+/**
+ * How a ramp moves over time, each part an `Animation<number>` that is
+ * `Animation.constant(0)` when not given. `scroll` is in spans: at 1 the
+ * colours have travelled the whole way from the first stop to the last and
+ * wrapped back, so `Animation.continuous(Phase.loop(seconds))` scrolls once
+ * every `seconds`. `hue` is in turns, CSS's `turn`: at 1 every hue has gone
+ * once round the circle. A one-shot that settles is a `tween` to where it
+ * rests.
+ */
+export interface RampMotion {
+    readonly scroll?: Animation<number>;
+    readonly hue?: Animation<number>;
+}
 /**
  * An immutable ramp over stops sorted by position.
  *
@@ -49,7 +70,11 @@ export interface ColorStop {
 export declare class ColorRamp {
     readonly ease: Ease;
     readonly stops: readonly ColorStop[];
-    constructor(ease: Ease, stops: readonly ColorStop[]);
+    /** How far the colours have moved along the span, in spans, in [0, 1). */
+    readonly scroll: number;
+    /** How far every hue is rotated in OKLCH, in turns, in [0, 1). */
+    readonly hue: number;
+    constructor(ease: Ease, stops: readonly ColorStop[], scroll?: number, hue?: number);
     /**
      * The color at `value`. Below the first stop it is the first color; at or
      * above the last stop it is the last; between two stops the raw progress
@@ -65,6 +90,39 @@ export declare class ColorRamp {
      * `jump-start`/`jump-both` steps, which jump at the start of the interval as
      * CSS defines them. An ease that overshoots [0, 1] holds the end colors
      * where it does: a ramp never paints outside its stops.
+     *
+     * A scrolled ramp reads, inside its span, the colour `scroll` spans behind
+     * `value`, wrapped back round the span as a repeating gradient does —
+     * seamless when the first and last stops are one colour; outside the span
+     * its end colours hold, however far it has scrolled. A rotated ramp turns
+     * the colour read by `hue` at its own lightness and chroma. Unmoved, every
+     * read keeps the exactness above.
      */
     at(value: number): ColorRgba;
+    /** The colour at `value` with the ramp unmoved: the stops and the ease alone. */
+    private unmoved;
+    /**
+     * This ramp read over time: its span of positions, from the first stop's
+     * to the last's, crossed at a steady rate in `seconds` and held at the last
+     * stop from then on, each colour along the way the ramp's own. A colour
+     * tween is a two-stop ramp over its seconds — the ramp's ease shaping the
+     * move, so `new ColorRamp(ease, [{ at: 0, color: a }, { at: 1, color: b
+     * }]).over(seconds)` is `a` eased to `b` — and a ramp of more stops over
+     * time is a sweep through all of them. [LAW:one-source-of-truth] The
+     * blending is `at`'s; what time adds is `tween`'s (`core/tween.ts`), so a
+     * host sampling once a second or sixty times reads the stop colours byte
+     * for byte where `at` paints them.
+     */
+    over(seconds: number): Animation<ColorRgba>;
+    /**
+     * This ramp moving: at `t`, scrolled by `motion.scroll` and rotated by
+     * `motion.hue` at `t`, on top of however far it was already moved, and
+     * changing when either does — so a loop moves every frame and a ramp a
+     * tween settles never changes again once it arrives.
+     * [LAW:one-source-of-truth] When it next changes is `Animation.all`'s
+     * answer over the two parts; nothing here says it a second time. Whether
+     * the depth it is drawn at can show the move is decided where it is drawn
+     * (`gradient`, through `stillOnSlots`).
+     */
+    moving(motion: RampMotion): Animation<ColorRamp>;
 }

package/dist/themes/ramp.js

@@ -20,11 +20,21 @@
  * theme colors passes through perceptually even steps rather than the muddy
  * midpoints of an sRGB blend.
  *
- * [LAW:one-way-deps] Imports `core/color`, `core/easing` and `core/oklch`
- * only; nothing here knows what a palette is. Resolving stop *names* is the template binding's
+ * A ramp also carries how far it has been moved: `scroll`, in spans, how
+ * far its colours have travelled along it, and `hue`, in turns, how far
+ * they are rotated round the OKLCH hue circle. A moved ramp is still a
+ * `ColorRamp`, so anything that reads a ramp reads a moving one frame by
+ * frame (`moving`) with nothing new to learn. [LAW:one-type-per-behavior]
+ *
+ * [LAW:one-way-deps] Imports `core/color`, `core/easing`, `core/oklch`,
+ * `core/animation` for `over` and `moving`, and `core/tween` for `over`; nothing
+ * here knows what a palette is. Resolving stop *names* is the template binding's
  * job (`paletteFuncs`), which hands this module resolved colors.
  */
-import { Oklch } from "../core/oklch.js";
+import { Animation } from "../core/animation.js";
+import { EASES } from "../core/easing.js";
+import { IDENTITY, Oklch } from "../core/oklch.js";
+import { tween } from "../core/tween.js";
 /**
  * An immutable ramp over stops sorted by position.
  *
@@ -43,9 +53,15 @@ import { Oklch } from "../core/oklch.js";
 export class ColorRamp {
     ease;
     stops;
-    constructor(ease, stops) {
+    /** How far the colours have moved along the span, in spans, in [0, 1). */
+    scroll;
+    /** How far every hue is rotated in OKLCH, in turns, in [0, 1). */
+    hue;
+    constructor(ease, stops, scroll = 0, hue = 0) {
         this.ease = ease;
         this.stops = stops;
+        this.scroll = turnOf("scroll", scroll);
+        this.hue = turnOf("hue", hue);
         if (stops.length === 0) {
             throw new RangeError("a ColorRamp needs at least one stop");
         }
@@ -75,11 +91,29 @@ export class ColorRamp {
      * `jump-start`/`jump-both` steps, which jump at the start of the interval as
      * CSS defines them. An ease that overshoots [0, 1] holds the end colors
      * where it does: a ramp never paints outside its stops.
+     *
+     * A scrolled ramp reads, inside its span, the colour `scroll` spans behind
+     * `value`, wrapped back round the span as a repeating gradient does —
+     * seamless when the first and last stops are one colour; outside the span
+     * its end colours hold, however far it has scrolled. A rotated ramp turns
+     * the colour read by `hue` at its own lightness and chroma. Unmoved, every
+     * read keeps the exactness above.
      */
     at(value) {
         if (!Number.isFinite(value)) {
             throw new RangeError(`ColorRamp.at needs a finite value, got ${value}`);
         }
+        const first = this.stops[0].at;
+        const last = this.stops[this.stops.length - 1].at;
+        const span = last - first;
+        const inside = first <= value && value <= last;
+        const moved = inside ? value - this.scroll * span : value;
+        const read = this.unmoved(inside && moved < first ? moved + span : moved);
+        // Exact when unrotated: the OKLCH round trip can land a channel one off.
+        return this.hue === 0 ? read : Oklch.fromRgba(read).applyKey({ ...IDENTITY, hueShift: 360 * this.hue }).toRgba();
+    }
+    /** The colour at `value` with the ramp unmoved: the stops and the ease alone. */
+    unmoved(value) {
         const stops = this.stops;
         // The last stop at or below `value`; -1 when `value` is below them all.
         let lower = -1;
@@ -100,4 +134,48 @@ export class ColorRamp {
             return to.color;
         return Oklch.fromRgba(from.color).mix(Oklch.fromRgba(to.color), t).toRgba();
     }
+    /**
+     * This ramp read over time: its span of positions, from the first stop's
+     * to the last's, crossed at a steady rate in `seconds` and held at the last
+     * stop from then on, each colour along the way the ramp's own. A colour
+     * tween is a two-stop ramp over its seconds — the ramp's ease shaping the
+     * move, so `new ColorRamp(ease, [{ at: 0, color: a }, { at: 1, color: b
+     * }]).over(seconds)` is `a` eased to `b` — and a ramp of more stops over
+     * time is a sweep through all of them. [LAW:one-source-of-truth] The
+     * blending is `at`'s; what time adds is `tween`'s (`core/tween.ts`), so a
+     * host sampling once a second or sixty times reads the stop colours byte
+     * for byte where `at` paints them.
+     */
+    over(seconds) {
+        const first = this.stops[0].at;
+        const last = this.stops[this.stops.length - 1].at;
+        return Animation.map(tween(first, last, { seconds, ease: EASES.linear }), (value) => this.at(value));
+    }
+    /**
+     * This ramp moving: at `t`, scrolled by `motion.scroll` and rotated by
+     * `motion.hue` at `t`, on top of however far it was already moved, and
+     * changing when either does — so a loop moves every frame and a ramp a
+     * tween settles never changes again once it arrives.
+     * [LAW:one-source-of-truth] When it next changes is `Animation.all`'s
+     * answer over the two parts; nothing here says it a second time. Whether
+     * the depth it is drawn at can show the move is decided where it is drawn
+     * (`gradient`, through `stillOnSlots`).
+     */
+    moving(motion) {
+        const still = Animation.constant(0);
+        return Animation.map(Animation.all([motion.scroll ?? still, motion.hue ?? still]), ([scroll, hue]) => new ColorRamp(this.ease, this.stops, this.scroll + scroll, this.hue + hue));
+    }
+}
+/**
+ * `v` as a fraction of one turn, in [0, 1): a whole turn is no turn, and a
+ * negative one counts back from a whole turn. A value so close under a whole
+ * turn that the fraction rounds to it is the turn itself. [LAW:single-enforcer]
+ * The constructor reads both moves through here, so a non-finite one fails
+ * here, loudly, naming which.
+ */
+function turnOf(what, v) {
+    if (!Number.isFinite(v))
+        throw new RangeError(`ColorRamp ${what} must be finite, got ${v}`);
+    const into = v - Math.floor(v);
+    return into < 1 ? into : 0;
 }

package/dist/themes/registry.js

@@ -3,8 +3,11 @@ import { Palette, drawnOn } from "./palette.js";
 import { ACCENT_KEYS, accentText } from "./buildPalette.js";
 import { THEMES } from "./data/index.js";
 import { ANSI_SLOTS } from "./data/types.js";
+import { Memo } from "../core/memo.js";
 const THEME_NAMES = Object.freeze(Object.keys(THEMES).sort());
-const cache = new Map();
+// Fewer themes than a Memo holds, so it never clears and a name keeps one
+// Palette — test/themes/registry.test.ts holds that.
+const cache = new Memo();
 /**
  * Returns the static list of available theme names. Pure and synchronous.
  */
@@ -14,12 +17,7 @@ export function listThemePalettes() {
 export function getThemePalette(name) {
     if (!isThemeName(name))
         return null;
-    const cached = cache.get(name);
-    if (cached !== undefined)
-        return cached;
-    const palette = hydrate(THEMES[name]);
-    cache.set(name, palette);
-    return palette;
+    return cache.get(name, () => hydrate(THEMES[name]));
 }
 function isThemeName(name) {
     return Object.hasOwn(THEMES, name);

package/dist/widgets/button.js

@@ -49,7 +49,8 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { observable, action, observableRef } from "mobx";
+import { action } from "mobx";
+import { observableRef } from "./observable.js";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { cellLen } from "../core/cells.js";
@@ -83,7 +84,7 @@ let Button = (() => {
     return class Button extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-            _label_decorators = [observable];
+            _label_decorators = [observableRef];
             _variant_decorators = [observableRef];
             _handleKey_decorators = [action];
             _handleMouse_decorators = [action];

package/dist/widgets/checkbox.js

@@ -44,7 +44,8 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { observable, action } from "mobx";
+import { action } from "mobx";
+import { observableRef } from "./observable.js";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { cellLen } from "../core/cells.js";
@@ -65,8 +66,8 @@ let Checkbox = (() => {
     return class Checkbox extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-            _label_decorators = [observable];
-            _checked_decorators = [observable];
+            _label_decorators = [observableRef];
+            _checked_decorators = [observableRef];
             _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);

package/dist/widgets/dropdown.d.ts

@@ -37,7 +37,9 @@ export interface DropdownOptions {
 export declare class Dropdown extends ThemedWidget implements OverlayRenderable {
     readonly id: string;
     readonly focusable = true;
-    accessor options: string[];
+    private accessor _options;
+    get options(): readonly string[];
+    set options(options: readonly string[]);
     accessor selectedIndex: number;
     accessor expanded: boolean;
     accessor highlightedIndex: number;

package/dist/widgets/dropdown.js

@@ -56,7 +56,8 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { observable, action, observableShallow } from "mobx";
+import { action } from "mobx";
+import { observableRef } from "./observable.js";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { cellLen, setCellSize, splitText, asCellCol } from "../core/cells.js";
@@ -67,9 +68,9 @@ import { ink } from "./ink.js";
 let Dropdown = (() => {
     let _classSuper = ThemedWidget;
     let _instanceExtraInitializers = [];
-    let _options_decorators;
-    let _options_initializers = [];
-    let _options_extraInitializers = [];
+    let __options_decorators;
+    let __options_initializers = [];
+    let __options_extraInitializers = [];
     let _selectedIndex_decorators;
     let _selectedIndex_initializers = [];
     let _selectedIndex_extraInitializers = [];
@@ -88,15 +89,15 @@ let Dropdown = (() => {
     return class Dropdown extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-            _options_decorators = [observableShallow];
-            _selectedIndex_decorators = [observable];
-            _expanded_decorators = [observable];
-            _highlightedIndex_decorators = [observable];
-            _filter_decorators = [observable];
+            __options_decorators = [observableRef];
+            _selectedIndex_decorators = [observableRef];
+            _expanded_decorators = [observableRef];
+            _highlightedIndex_decorators = [observableRef];
+            _filter_decorators = [observableRef];
             _handleKey_decorators = [action];
             _handleMouse_decorators = [action];
             _handleFocus_decorators = [action];
-            __esDecorate(this, null, _options_decorators, { kind: "accessor", name: "options", static: false, private: false, access: { has: obj => "options" in obj, get: obj => obj.options, set: (obj, value) => { obj.options = value; } }, metadata: _metadata }, _options_initializers, _options_extraInitializers);
+            __esDecorate(this, null, __options_decorators, { kind: "accessor", name: "_options", static: false, private: false, access: { has: obj => "_options" in obj, get: obj => obj._options, set: (obj, value) => { obj._options = value; } }, metadata: _metadata }, __options_initializers, __options_extraInitializers);
             __esDecorate(this, null, _selectedIndex_decorators, { kind: "accessor", name: "selectedIndex", static: false, private: false, access: { has: obj => "selectedIndex" in obj, get: obj => obj.selectedIndex, set: (obj, value) => { obj.selectedIndex = value; } }, metadata: _metadata }, _selectedIndex_initializers, _selectedIndex_extraInitializers);
             __esDecorate(this, null, _expanded_decorators, { kind: "accessor", name: "expanded", static: false, private: false, access: { has: obj => "expanded" in obj, get: obj => obj.expanded, set: (obj, value) => { obj.expanded = value; } }, metadata: _metadata }, _expanded_initializers, _expanded_extraInitializers);
             __esDecorate(this, null, _highlightedIndex_decorators, { kind: "accessor", name: "highlightedIndex", static: false, private: false, access: { has: obj => "highlightedIndex" in obj, get: obj => obj.highlightedIndex, set: (obj, value) => { obj.highlightedIndex = value; } }, metadata: _metadata }, _highlightedIndex_initializers, _highlightedIndex_extraInitializers);
@@ -108,10 +109,14 @@ let Dropdown = (() => {
         }
         id = __runInitializers(this, _instanceExtraInitializers);
         focusable = true;
-        #options_accessor_storage = __runInitializers(this, _options_initializers, void 0);
-        get options() { return this.#options_accessor_storage; }
-        set options(value) { this.#options_accessor_storage = value; }
-        #selectedIndex_accessor_storage = (__runInitializers(this, _options_extraInitializers), __runInitializers(this, _selectedIndex_initializers, void 0));
+        #_options_accessor_storage = __runInitializers(this, __options_initializers, void 0);
+        get _options() { return this.#_options_accessor_storage; }
+        set _options(value) { this.#_options_accessor_storage = value; }
+        // A copy is held, so the caller changing the array it assigned changes
+        // nothing here: the labels change only by assignment, which repaints.
+        get options() { return this._options; }
+        set options(options) { this._options = [...options]; }
+        #selectedIndex_accessor_storage = (__runInitializers(this, __options_extraInitializers), __runInitializers(this, _selectedIndex_initializers, void 0));
         get selectedIndex() { return this.#selectedIndex_accessor_storage; }
         set selectedIndex(value) { this.#selectedIndex_accessor_storage = value; }
         #expanded_accessor_storage = (__runInitializers(this, _selectedIndex_extraInitializers), __runInitializers(this, _expanded_initializers, false));
@@ -140,7 +145,7 @@ let Dropdown = (() => {
             super(options.theme);
             __runInitializers(this, _filter_extraInitializers);
             this.id = options.id ?? `dropdown-${Math.random().toString(36).slice(2, 8)}`;
-            this.options = [...options.options];
+            this._options = [...options.options];
             // [LAW:types-are-the-program] selectedIndex must point to a valid
             // option (or be 0 for the empty-options case). Clamp at the trust
             // boundary so headerText / render / commit logic can all assume

package/dist/widgets/event-router.js

@@ -6,7 +6,7 @@
  * host's input (`host/input`), and `WidgetApp` hands this what the app hears.
  */
 import { KeyEvent } from "./types.js";
-import { drew, originOf, scrollTargetAt, widgetAt } from "./hit.js";
+import { cellOf, drew, originOf, scrollTargetAt, widgetAt } from "./hit.js";
 export class EventRouter {
     source;
     focusOnClick;
@@ -78,7 +78,7 @@ export class EventRouter {
     }
     /** Route a key the app heard. */
     key(press) {
-        this.dispatchKey(new KeyEvent(press));
+        this.dispatchKey(new KeyEvent(press, this.source.frameTime));
     }
     /** Route a pointer event the app heard. */
     mouse(event) {
@@ -172,6 +172,8 @@ export class EventRouter {
             x: event.x - target.originX,
             y: event.y - target.originY,
             over: drew(frame, target.widget, event.x, event.y),
+            cell: cellOf(frame, target.widget, event.x, event.y),
+            time: this.source.frameTime,
         });
         if (event.type === "mouse_down")
             this.captured = target;

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

@@ -6,18 +6,25 @@
  */
 import type { InteractiveWidget, FocusManager, KeyEvent } from "./types.js";
 import type { Unsubscribe } from "../core/subscription.js";
+/** What focus follows: the frame a `WidgetApp` just painted. */
+export interface FocusView {
+    /** Every widget the view holds, in document order, whether or not it has a cell on screen. */
+    present(): readonly InteractiveWidget[];
+    /** The widgets with a cell on the frame on screen, in document order. */
+    onScreen(): readonly InteractiveWidget[];
+    /** The time a frame drawn now is drawn for (`RenderOptions.frame`), which a focus change is stamped with. */
+    frameTime(): number;
+}
 export declare class DefaultFocusManager implements FocusManager {
-    private readonly onScreen;
+    private readonly view;
     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.
+     * [LAW:one-source-of-truth] The view 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[]);
+    constructor(view: FocusView);
     get current(): InteractiveWidget | null;
     get widgets(): readonly InteractiveWidget[];
     next(): void;
@@ -25,20 +32,22 @@ export declare class DefaultFocusManager implements FocusManager {
     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.
+     * the view holds (`present`) 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.
+     * In the view, not on screen: a widget cropped for the moment — the
+     * terminal shrank, a viewport scrolled, an overlay covers it, its container
+     * handed it no column — 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
+     * first widget when the app starts, off a widget that left the view
      * or was disabled.
      */
-    settle(drawn: readonly InteractiveWidget[]): void;
+    settle(): void;
     onChange(handler: (current: InteractiveWidget | null) => void): Unsubscribe;
     handleKey(event: KeyEvent): void;
+    private step;
     private clear;
     private setFocus;
     private emitChange;

package/dist/widgets/focus-manager.js

@@ -38,7 +38,8 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { action, observableRef } from "mobx";
+import { action } from "mobx";
+import { observableRef } from "./observable.js";
 let DefaultFocusManager = (() => {
     let _instanceExtraInitializers = [];
     let _currentWidget_decorators;
@@ -69,42 +70,30 @@ let DefaultFocusManager = (() => {
             __esDecorate(this, null, _setFocus_decorators, { kind: "method", name: "setFocus", static: false, private: false, access: { has: obj => "setFocus" in obj, get: obj => obj.setFocus }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        onScreen = __runInitializers(this, _instanceExtraInitializers);
+        view = __runInitializers(this, _instanceExtraInitializers);
         #currentWidget_accessor_storage = __runInitializers(this, _currentWidget_initializers, null);
         get currentWidget() { return this.#currentWidget_accessor_storage; }
         set currentWidget(value) { this.#currentWidget_accessor_storage = value; }
         changeHandlers = (__runInitializers(this, _currentWidget_extraInitializers), new Set());
         /**
-         * `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.
+         * [LAW:one-source-of-truth] The view 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) {
-            this.onScreen = onScreen;
+        constructor(view) {
+            this.view = view;
         }
         get current() {
             return this.currentWidget;
         }
         get widgets() {
-            return this.onScreen().filter(takesFocus);
+            return this.view.onScreen().filter(takesFocus);
         }
         next() {
-            const focusable = this.widgets;
-            if (focusable.length === 0)
-                return;
-            const currentIdx = this.currentWidget ? focusable.indexOf(this.currentWidget) : -1;
-            const nextIdx = (currentIdx + 1) % focusable.length;
-            this.setFocus(focusable[nextIdx]);
+            this.step(this.view.present());
         }
         prev() {
-            const focusable = this.widgets;
-            if (focusable.length === 0)
-                return;
-            const currentIdx = this.currentWidget ? focusable.indexOf(this.currentWidget) : -1;
-            const prevIdx = currentIdx <= 0 ? focusable.length - 1 : currentIdx - 1;
-            this.setFocus(focusable[prevIdx]);
+            this.step([...this.view.present()].reverse());
         }
         // A widget not on screen yet can take focus: an app that is about to show
         // it focuses it first, and the frame that shows it keeps it (`settle`).
@@ -115,20 +104,21 @@ let DefaultFocusManager = (() => {
         }
         /**
          * 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.
+         * the view holds (`present`) 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.
+         * In the view, not on screen: a widget cropped for the moment — the
+         * terminal shrank, a viewport scrolled, an overlay covers it, its container
+         * handed it no column — 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
+         * first widget when the app starts, off a widget that left the view
          * or was disabled.
          */
-        settle(drawn) {
+        settle() {
             const current = this.currentWidget;
-            if (current && takesFocus(current) && drawn.includes(current))
+            if (current && takesFocus(current) && this.view.present().includes(current))
                 return;
             const first = this.widgets[0];
             if (first)
@@ -154,6 +144,16 @@ let DefaultFocusManager = (() => {
             event.stop();
         }
         // --- Private ---
+        // To the first widget Tab moves between that follows the focused one in
+        // `order`, wrapping. It is found by its place in the view, not among those
+        // on screen, so Tab from a widget on no cell moves to its neighbour.
+        step(order) {
+            const tabbable = new Set(this.widgets);
+            const at = this.currentWidget ? order.indexOf(this.currentWidget) : -1;
+            const target = [...order.slice(at + 1), ...order.slice(0, at + 1)].find((widget) => tabbable.has(widget));
+            if (target)
+                this.setFocus(target);
+        }
         // No focus is where `settle` leaves an app with nothing to focus, and only
         // there: anywhere else the next frame would put focus back on the first
         // widget, so there is no public way in.
@@ -163,7 +163,7 @@ let DefaultFocusManager = (() => {
             // [LAW:single-enforcer] WidgetBase.focus()/blur() route through
             // handleFocus; calling it here as well would dispatch twice and run any
             // subclass side effect (e.g. Dropdown clearing its filter) twice.
-            this.currentWidget.blur();
+            this.currentWidget.blur(this.view.frameTime());
             this.currentWidget = null;
             this.emitChange();
         }
@@ -172,10 +172,11 @@ let DefaultFocusManager = (() => {
                 return;
             // [LAW:single-enforcer] focus()/blur() already dispatch handleFocus —
             // see clear() for the rationale.
+            const time = this.view.frameTime();
             if (this.currentWidget)
-                this.currentWidget.blur();
+                this.currentWidget.blur(time);
             this.currentWidget = widget;
-            widget.focus();
+            widget.focus(time);
             this.emitChange();
         }
         emitChange() {