@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/template-bindings/animation-funcs.js

@@ -4,13 +4,25 @@
  *
  * A host that builds its cells in templates — cc-candybar's statusline, say —
  * evaluates each template once per redraw and owns the clock that says when
- * that is. So the time is a capability the registration takes, the way
- * `richTextFuncs(drawnAt)` takes the drawn depth: `frameTime()` is read once
- * per call, when the template is evaluated, and nothing here reads a clock.
+ * that is. So the frame is a capability the registration takes, the way
+ * `richTextFuncs(drawnAt)` takes the drawn depth: `frame()` is read once per
+ * call, when the template is evaluated, and nothing here reads a clock.
  * [LAW:no-ambient-temporal-coupling] A host hands in the same `t` and gets
  * the same fragment back; a host that redraws once a second or sixty times
  * a second registers the same functions.
  *
+ * Every function draws its animation on a `Timeline` (`../core/timeline.ts`)
+ * the host hands in as a getter beside the time — playing from host time 0
+ * at rate 1, the host's own clock, when it hands none — so a daemon pauses,
+ * reverses, scrubs or speeds one session's animations by changing one value
+ * it holds, with nothing recompiled, as `paletteFuncs` follows a theme
+ * through its getter. The timeline is a map the drawing runs through, not a
+ * number the time is turned into first: a frame's stamp says when it changes
+ * on the host's clock, which only `Timeline.run` can carry it back onto —
+ * paused, never; backwards, at the hold it is about to drop under.
+ * [LAW:single-enforcer] `drawing` is the one place the time, the timeline
+ * and the reader's preference for motion are read, for every function.
+ *
  * `frames <seconds> <frame> <seconds> <frame> …` is a `FrameSequence`
  * (`renderables/frames.ts`) in a template: the frame in progress at the
  * moment, as a fragment at the width of the widest. Its frames arrive as
@@ -25,11 +37,49 @@
  * end, so the engine's `alternating` gate types every slot and lifts each
  * string frame to a fragment; the pairing — a trailing hold with no frame or
  * colour — is parsed in `pairs`, once. [LAW:types-are-the-program]
+ *
+ * The rest start at a moment the template names, on the timeline's clock —
+ * a field of the host's state, the moment a value changed — and each is the
+ * animation `Timeline.play(start)` runs, so a start is a timeline like any
+ * other and nothing here offsets a time by hand. `tween <seconds> <ease>
+ * <start> <from> <to>` is a number eased from one value to another and held
+ * (`core/tween.ts`), its ease spelled by name (`parseEase`); `loop <seconds>
+ * <start>` is the way through a period, 0 to 1 and round again — two
+ * cells started a step apart are a stagger. Each is a number, so it goes
+ * wherever a number goes: a colour tween is `ramp (tween …) "linear" 0 $from
+ * 1 $to` and a ramp scrolling is `ramp (loop …) …`, because `ColorRamp` is
+ * the one place two colours are blended and a colour tween is a two-stop
+ * ramp read over time (`ColorRamp.over`). [LAW:one-source-of-truth] A
+ * second blender here would be a second answer to what lies between two
+ * colours. `glyphs <name> <start> <fragment>` is the fragment through a
+ * glyph effect from the catalogue (`GLYPH_EFFECT_CATALOGUE`), at its
+ * defaults, before any render (`reglyphText`). Every argument list is an
+ * exact arity of typed slots, so a slot of the wrong kind fails at the gate.
+ *
+ * Every function says when what it drew changes, so a host paints a
+ * template while it moves and not after. `frames` and `glyphs` stamp the
+ * fragment they draw (`textFrameAt`), covering its own glyphs. A number or a
+ * colour carries no cells to stamp, so `tween`, `loop` and `stepped` tell
+ * their hold to the frame instead (`TemplateFrame.onHold`), as a placed
+ * animation of no cells does (`RenderOptions.onHold`). Nothing here claims
+ * a moment it does not know.
  */
-import { beat } from "../core/easing.js";
-import { FrameSequence, frameAt } from "../renderables/frames.js";
+import { Animation, frameTimeOf, holdOf, shownAt } from "../core/animation.js";
+import { Phase, beat, finiteTime, parseEase } from "../core/easing.js";
+import { Timeline } from "../core/timeline.js";
+import { tween } from "../core/tween.js";
+import { cellSeed } from "../renderables/effect.js";
+import { reglyphText } from "../renderables/glyph-effect.js";
+import { GLYPH_EFFECT_CATALOGUE } from "../renderables/glyph-effects.js";
+import { FrameSequence, textFrameAt } from "../renderables/frames.js";
 import { asColor } from "./color-funcs.js";
 import { asFragment } from "./helpers.js";
+/** The frame a renderable is drawn in, as the frame a template it evaluates there is drawn for. */
+export function templateFrame(options) {
+    return { time: frameTimeOf(options), onHold: options.onHold, reducedMotion: options.reducedMotion, asciiOnly: options.asciiOnly };
+}
+/** The host's own clock as a timeline: host time 0 at animation time 0, at rate 1. */
+const HOST_CLOCK = Timeline.play(0);
 /**
  * The `(seconds, value)` pairs a call spells, each value read through
  * `value`. The gate has typed every even slot as a float and every odd one
@@ -54,17 +104,59 @@ function pairs(what, tail, value) {
     return paired;
 }
 /**
- * Register `frames` and `stepped`, each drawn for the moment `frameTime`
- * reports when the template is evaluated: seconds on the host's own
- * timeline, from whatever zero it counts from. The functions exist whatever
- * `frameTime` returns, so a template compiles once and is evaluated at every
- * moment the host draws.
+ * Every glyph effect in the catalogue by the name a template spells it
+ * with, a transition as the effect it runs. [LAW:types-are-the-program]
+ * Keyed by both name types, so a name added to the catalogue does not
+ * compile until it is spelled here too.
+ */
+const GLYPH_EFFECTS = {
+    ...GLYPH_EFFECT_CATALOGUE.loops,
+    typewriter: (element) => GLYPH_EFFECT_CATALOGUE.transitions.typewriter(element).effect,
+    scramble: (element) => GLYPH_EFFECT_CATALOGUE.transitions.scramble(element).effect,
+    backspace: (element) => GLYPH_EFFECT_CATALOGUE.transitions.backspace(element).effect,
+    scrambleOut: (element) => GLYPH_EFFECT_CATALOGUE.transitions.scrambleOut(element).effect,
+};
+/**
+ * The gate a spelled glyph effect crosses: the name in, the effect's maker
+ * out, or a refusal naming every legal one. [LAW:parse-dont-validate]
+ */
+function glyphEffect(name) {
+    if (!Object.hasOwn(GLYPH_EFFECTS, name)) {
+        throw new RangeError(`unknown glyph effect ${JSON.stringify(name)}; expected one of ${Object.keys(GLYPH_EFFECTS).map((n) => JSON.stringify(n)).join(", ")}`);
+    }
+    return GLYPH_EFFECTS[name];
+}
+/**
+ * Register `frames`, `stepped`, `tween`, `loop` and `glyphs`, each drawn for
+ * the frame `frame` reports when the template is evaluated — its time in
+ * seconds, from whatever zero the host counts from — through
+ * `options.timeline`, and each telling that frame when what it drew changes.
+ * The functions exist whatever `frame` returns, so a template compiles once
+ * and is evaluated at every moment the host draws. In a frame that says
+ * `reducedMotion` each draws its animation reduced (`Animation.reduced`): a
+ * loop at its start, a one-shot cut from where it starts to where it arrives
+ * when it starts.
  */
-export function animationFuncs(frameTime) {
+export function animationFuncs(frame, options = {}) {
+    const timeline = options.timeline ?? (() => HOST_CLOCK);
+    // `animation` on this call's timeline, and the time of `at`, the frame it
+    // is drawn in, read once a call so a value and its hold are one frame's.
+    const drawing = (what, animation, at) => [Timeline.run(timeline(), animation), finiteTime(what, at.time)];
+    // What a value animation shows now, under the reader's preference, its
+    // hold told to the frame: a value has no cells to carry it.
+    const now = (what, animation) => {
+        const at = frame();
+        const [drawn, t] = drawing(what, animation, at);
+        const shown = shownAt(drawn, t, at);
+        at.onHold?.(holdOf(shown, t));
+        return shown.value;
+    };
+    const startedAt = (start, animation) => Timeline.run(Timeline.play(start), animation);
     const framesFunc = {
         fn: ((...tail) => {
             const frames = pairs("frame", tail, asFragment).map(({ seconds, value }) => ({ seconds, text: value }));
-            return frameAt(new FrameSequence(frames), frameTime());
+            const at = frame();
+            return textFrameAt(...drawing("frames", new FrameSequence(frames), at), at);
         }),
         argTypes: ["float", "liftable"],
         arity: { kind: "alternating", minimum: 2 },
@@ -73,11 +165,37 @@ export function animationFuncs(frameTime) {
     const steppedFunc = {
         fn: ((...tail) => {
             const steps = pairs("color", tail, (v) => asColor(v, "stepped"));
-            return steps[beat(steps.map((step) => step.seconds)).at(frameTime())].value.hex;
+            return steps[now("stepped", beat(steps.map((step) => step.seconds)))].value.hex;
         }),
         argTypes: ["float", "string"],
         arity: { kind: "alternating", minimum: 2 },
         returnType: "string",
     };
-    return { frames: framesFunc, stepped: steppedFunc };
+    const tweenFunc = {
+        fn: ((seconds, ease, start, from, to) => now("tween", startedAt(start, tween(from, to, { seconds, ease: parseEase(ease) })))),
+        argTypes: ["float", "string", "float", "float", "float"],
+        arity: { kind: "exact" },
+        returnType: "float",
+    };
+    const loopFunc = {
+        fn: ((seconds, start) => now("loop", startedAt(start, Animation.continuous(Phase.loop(seconds))))),
+        argTypes: ["float", "float"],
+        arity: { kind: "exact" },
+        returnType: "float",
+    };
+    const glyphsFunc = {
+        fn: ((name, start, child) => {
+            const make = glyphEffect(name);
+            const fragment = asFragment(child);
+            // One text, one seed: the element is named by what it says.
+            const key = fragment.plain;
+            const at = frame();
+            const reglyphed = reglyphText(fragment, make({ z: cellSeed(key, 0, 0) }), { key, asciiOnly: at.asciiOnly === true });
+            return textFrameAt(...drawing("glyphs", startedAt(start, reglyphed), at), at);
+        }),
+        argTypes: ["string", "float", "liftable"],
+        arity: { kind: "exact" },
+        returnType: "T",
+    };
+    return { frames: framesFunc, stepped: steppedFunc, tween: tweenFunc, loop: loopFunc, glyphs: glyphsFunc };
 }

package/dist/template-bindings/index.d.ts

@@ -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)`
@@ -43,7 +43,7 @@ import type { RenderOptions } from "../core/protocol.js";
 import { type DrawnAt } from "./color-funcs.js";
 export { paletteFuncs } from "./palette-funcs.js";
 export { colorFuncs, readableOnFunc, type DrawnAt } from "./color-funcs.js";
-export { animationFuncs } from "./animation-funcs.js";
+export { animationFuncs, templateFrame, type AnimationFuncsOptions, type 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

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)`
@@ -45,7 +45,7 @@ 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

package/dist/themes/ramp.d.ts

@@ -20,9 +20,15 @@
  * theme colors passes through perceptually even steps rather than the muddy
  * midpoints of an sRGB blend.
  *
+ * 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`,
- * and for `over`, `core/animation` and `core/tween`; nothing here knows
- * what a palette is. Resolving stop *names* is the template binding's
+ * `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";
@@ -33,6 +39,19 @@ 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.
  *
@@ -51,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
@@ -67,8 +90,17 @@ 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
@@ -82,4 +114,15 @@ export declare class ColorRamp {
      * 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,14 +20,20 @@
  * theme colors passes through perceptually even steps rather than the muddy
  * midpoints of an sRGB blend.
  *
+ * 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`,
- * and for `over`, `core/animation` and `core/tween`; nothing here knows
- * what a palette is. Resolving stop *names* is the template binding's
+ * `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 { EASES } from "../core/easing.js";
-import { Oklch } from "../core/oklch.js";
+import { IDENTITY, Oklch } from "../core/oklch.js";
 import { tween } from "../core/tween.js";
 /**
  * An immutable ramp over stops sorted by position.
@@ -47,9 +53,15 @@ import { tween } from "../core/tween.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");
         }
@@ -79,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;
@@ -121,4 +151,31 @@ export class ColorRamp {
         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

@@ -12,6 +12,8 @@ export interface FocusView {
     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 view;