@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/themes/ramp.js

@@ -6,13 +6,13 @@
  * color, and none takes a *measurement*. Without a ramp the answer gets
  * computed outside the theme system — a script emits a hex, a template
  * branches `if ge .pct 80 … else if ge .pct 50 …` — and that color decision
- * can no longer transpose with the palette it was meant to belong to. A ramp
+ * can no longer adjust with the palette it was meant to belong to. A ramp
  * is the one function whose input is a number, so the decision stays inside.
  *
  * A threshold cascade is a ramp too: the same stops with the `step` ease hold
  * each color until the next position, which is exactly `≥ threshold → hotter`
  * written as data. [LAW:one-type-per-behavior] One primitive; the easing is a
- * value — any `Ease` from `core/easing`, the vocabulary every effect shares —
+ * value — any `Easing` from `core/easing`, the vocabulary every effect shares —
  * so a gradient and a cascade differ by one word, not by which function was
  * called. [LAW:dataflow-not-control-flow] `at` applies it unconditionally.
  *
@@ -21,7 +21,7 @@
  * 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
+ * far its colors 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]
@@ -53,7 +53,7 @@ import { tween } from "../core/tween.js";
 export class ColorRamp {
     ease;
     stops;
-    /** How far the colours have moved along the span, in spans, in [0, 1). */
+    /** How far the colors 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;
@@ -92,11 +92,11 @@ export class ColorRamp {
      * 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
+     * A scrolled ramp reads, inside its span, the color `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
+     * seamless when the first and last stops are one color; outside the span
+     * its end colors hold, however far it has scrolled. A rotated ramp turns
+     * the color read by `hue` at its own lightness and chroma. Unmoved, every
      * read keeps the exactness above.
      */
     at(value) {
@@ -112,7 +112,7 @@ export class ColorRamp {
         // 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. */
+    /** The color 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.
@@ -137,13 +137,13 @@ export class ColorRamp {
     /**
      * 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
+     * stop from then on, each color along the way the ramp's own. A color
      * 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
+     * host sampling once a second or sixty times reads the stop colors byte
      * for byte where `at` paints them.
      */
     over(seconds) {
@@ -159,7 +159,7 @@ export class ColorRamp {
      * [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`).
+     * (`gradient`, through `staticWhereUnchanged`).
      */
     moving(motion) {
         const still = Animation.constant(0);

package/dist/themes/registry.d.ts

@@ -11,15 +11,15 @@ export declare function listThemePalettes(): readonly ThemeName[];
  *
  * Synchronous: theme data is bundled at compile time via the data barrel,
  * so no I/O happens here. The Palette itself (which requires hex-parsing
- * ~150 vars into ColorRgba values) is constructed lazily on first request
- * and cached — subsequent calls for the same name return the same instance.
+ * ~150 vars into ColorRgba values) is cached on first request — subsequent
+ * calls for the same name return the same instance. `terminalThemes.ts` makes
+ * that request for every theme, on import.
  */
 export declare function getThemePalette(name: ThemeName): Palette;
 export declare function getThemePalette(name: string): Palette | null;
 /**
  * The eight base colors every theme must declare, and its ANSI table. Returned by
- * `getThemeBaseColors` for callers (notably `terminalThemes.ts`) that only
- * need the substrate and would otherwise fill the registry cache.
+ * `getThemeBaseColors` for callers that only need the substrate.
  */
 export interface ThemeBaseColors {
     readonly name: string;
@@ -35,9 +35,7 @@ export interface ThemeBaseColors {
     readonly ansi: ColorTable;
 }
 /**
- * Read just the eight base colors from a theme's data file. Cheap — parses
- * 8 hex strings, allocates no Palette, touches no cache. Use this when you
- * want a `TerminalTheme`-shaped substrate without forcing the full ~150-var
- * palette through the registry's hydration path.
+ * Read just the eight base colors and the ANSI table from a theme's data file.
+ * Parses 8 hex strings, allocates no Palette, touches no cache.
  */
 export declare function getThemeBaseColors(name: ThemeName): ThemeBaseColors;

package/dist/themes/registry.js

@@ -23,16 +23,14 @@ function isThemeName(name) {
     return Object.hasOwn(THEMES, name);
 }
 /**
- * Read just the eight base colors from a theme's data file. Cheap — parses
- * 8 hex strings, allocates no Palette, touches no cache. Use this when you
- * want a `TerminalTheme`-shaped substrate without forcing the full ~150-var
- * palette through the registry's hydration path.
+ * Read just the eight base colors and the ANSI table from a theme's data file.
+ * Parses 8 hex strings, allocates no Palette, touches no cache.
  */
 export function getThemeBaseColors(name) {
     const data = THEMES[name];
     const bg = parseHex(data.vars.background, data.name, "background");
-    // The colours `getThemePalette(name)` hands out for the same names: drawn on
-    // the theme's own background, as a Palette draws every colour it holds.
+    // The colors `getThemePalette(name)` hands out for the same names: drawn on
+    // the theme's own background, as a Palette draws every color it holds.
     const draw = drawnOn(data.name, bg);
     const base = (key) => draw(parseHex(data.vars[key], data.name, key));
     return {
@@ -59,7 +57,7 @@ function hydrate(data) {
     const stated = Object.entries(data.vars).map(([role, hex]) => [role, parseHex(hex, data.name, `var ${role}`)]);
     return buildPalette(data.name, data.dark, Object.fromEntries(stated));
 }
-// Theme data is authored, so a malformed colour names the theme and the key it
+// Theme data is authored, so a malformed color names the theme and the key it
 // sits under; the grammar itself is `parseHexColor`'s.
 function parseHex(value, theme, key) {
     try {
@@ -72,7 +70,7 @@ function parseHex(value, theme, key) {
     }
 }
 /**
- * An ANSI slot is a colour a terminal paints, never a blend, so it takes no
+ * An ANSI slot is a color a terminal paints, never a blend, so it takes no
  * alpha: `flattenAlpha` leaves a STANDARD spec alone and would pass one through.
  */
 function parseOpaqueHex(value, theme, key) {

package/dist/themes/terminalThemes.d.ts

@@ -3,17 +3,10 @@
  * matching `<NAME>` export here. There is no inline-only theme; the data
  * file is the single source of truth for every theme's hex values.
  *
- * Editing `data/<name>.ts` updates both the registry's palette (via
- * `getThemePalette(name)`) AND the matching `TerminalTheme` constant exported
- * below (via `getThemeBaseColors(name)`, which pulls just the 8 substrate
- * keys). The two views agree on those eight. Every other role of a
- * `TerminalTheme`'s palette is derived from them, so it is not the colour the
- * theme authored: read `getThemePalette` for that.
- *
- * [LAW:one-source-of-truth] Hex values live in `data/<name>.ts`. This
- * module is a derived view that builds a `TerminalTheme` from each
- * theme's eight base colors via `buildPalette` for the substrate palette,
- * and from the theme's own ANSI table for the sixteen named colours.
+ * [LAW:one-source-of-truth] Hex values live in `data/<name>.ts`, and a theme's
+ * name means one palette: a constant here holds the very `Palette`
+ * `getThemePalette(name)` returns, and takes the background and foreground off
+ * it, with the theme's sixteen named colors beside it.
  *
  * [LAW:one-type-per-behavior] Every theme has the same shape — name,
  * `dark` flag, full Palette in the registry, `TerminalTheme` constant

package/dist/themes/terminalThemes.js

@@ -3,17 +3,10 @@
  * matching `<NAME>` export here. There is no inline-only theme; the data
  * file is the single source of truth for every theme's hex values.
  *
- * Editing `data/<name>.ts` updates both the registry's palette (via
- * `getThemePalette(name)`) AND the matching `TerminalTheme` constant exported
- * below (via `getThemeBaseColors(name)`, which pulls just the 8 substrate
- * keys). The two views agree on those eight. Every other role of a
- * `TerminalTheme`'s palette is derived from them, so it is not the colour the
- * theme authored: read `getThemePalette` for that.
- *
- * [LAW:one-source-of-truth] Hex values live in `data/<name>.ts`. This
- * module is a derived view that builds a `TerminalTheme` from each
- * theme's eight base colors via `buildPalette` for the substrate palette,
- * and from the theme's own ANSI table for the sixteen named colours.
+ * [LAW:one-source-of-truth] Hex values live in `data/<name>.ts`, and a theme's
+ * name means one palette: a constant here holds the very `Palette`
+ * `getThemePalette(name)` returns, and takes the background and foreground off
+ * it, with the theme's sixteen named colors beside it.
  *
  * [LAW:one-type-per-behavior] Every theme has the same shape — name,
  * `dark` flag, full Palette in the registry, `TerminalTheme` constant
@@ -25,40 +18,31 @@
  * color primitives; nothing in `core/` imports back.
  */
 import { TerminalTheme } from "../core/color.js";
-import { buildPalette } from "./buildPalette.js";
-import { getThemeBaseColors } from "./registry.js";
-function defineTheme(d) {
-    return new TerminalTheme(d.bg, d.fg, d.ansi, buildPalette(d.name, d.dark, {
-        primary: d.primary,
-        secondary: d.secondary,
-        accent: d.accent,
-        success: d.success,
-        warning: d.warning,
-        error: d.error,
-        background: d.bg,
-        foreground: d.fg,
-    }));
+import { getThemeBaseColors, getThemePalette } from "./registry.js";
+function defineTheme(name) {
+    const palette = getThemePalette(name);
+    return new TerminalTheme(palette.get("background"), palette.get("foreground"), getThemeBaseColors(name).ansi, palette);
 }
-export const DEFAULT_TERMINAL_THEME = defineTheme(getThemeBaseColors("default"));
-export const SVG_EXPORT_THEME = defineTheme(getThemeBaseColors("svg-export"));
-export const MONOKAI = defineTheme(getThemeBaseColors("monokai"));
-export const NORD = defineTheme(getThemeBaseColors("nord"));
-export const GRUVBOX = defineTheme(getThemeBaseColors("gruvbox"));
-export const DRACULA = defineTheme(getThemeBaseColors("dracula"));
-export const TOKYO_NIGHT = defineTheme(getThemeBaseColors("tokyo-night"));
-export const FLEXOKI = defineTheme(getThemeBaseColors("flexoki"));
-export const CYBERPUNK = defineTheme(getThemeBaseColors("cyberpunk"));
-export const CATPPUCCIN_MOCHA = defineTheme(getThemeBaseColors("catppuccin-mocha"));
-export const CATPPUCCIN_LATTE = defineTheme(getThemeBaseColors("catppuccin-latte"));
-export const CATPPUCCIN_FRAPPE = defineTheme(getThemeBaseColors("catppuccin-frappe"));
-export const CATPPUCCIN_MACCHIATO = defineTheme(getThemeBaseColors("catppuccin-macchiato"));
-export const SOLARIZED_DARK = defineTheme(getThemeBaseColors("solarized-dark"));
-export const SOLARIZED_LIGHT = defineTheme(getThemeBaseColors("solarized-light"));
-export const ROSE_PINE = defineTheme(getThemeBaseColors("rose-pine"));
-export const ROSE_PINE_MOON = defineTheme(getThemeBaseColors("rose-pine-moon"));
-export const ROSE_PINE_DAWN = defineTheme(getThemeBaseColors("rose-pine-dawn"));
-export const ATOM_ONE_DARK = defineTheme(getThemeBaseColors("atom-one-dark"));
-export const ATOM_ONE_LIGHT = defineTheme(getThemeBaseColors("atom-one-light"));
-export const TEXTUAL_DARK = defineTheme(getThemeBaseColors("textual-dark"));
-export const TEXTUAL_LIGHT = defineTheme(getThemeBaseColors("textual-light"));
-export const TEXTUAL_ANSI = defineTheme(getThemeBaseColors("textual-ansi"));
+export const DEFAULT_TERMINAL_THEME = defineTheme("default");
+export const SVG_EXPORT_THEME = defineTheme("svg-export");
+export const MONOKAI = defineTheme("monokai");
+export const NORD = defineTheme("nord");
+export const GRUVBOX = defineTheme("gruvbox");
+export const DRACULA = defineTheme("dracula");
+export const TOKYO_NIGHT = defineTheme("tokyo-night");
+export const FLEXOKI = defineTheme("flexoki");
+export const CYBERPUNK = defineTheme("cyberpunk");
+export const CATPPUCCIN_MOCHA = defineTheme("catppuccin-mocha");
+export const CATPPUCCIN_LATTE = defineTheme("catppuccin-latte");
+export const CATPPUCCIN_FRAPPE = defineTheme("catppuccin-frappe");
+export const CATPPUCCIN_MACCHIATO = defineTheme("catppuccin-macchiato");
+export const SOLARIZED_DARK = defineTheme("solarized-dark");
+export const SOLARIZED_LIGHT = defineTheme("solarized-light");
+export const ROSE_PINE = defineTheme("rose-pine");
+export const ROSE_PINE_MOON = defineTheme("rose-pine-moon");
+export const ROSE_PINE_DAWN = defineTheme("rose-pine-dawn");
+export const ATOM_ONE_DARK = defineTheme("atom-one-dark");
+export const ATOM_ONE_LIGHT = defineTheme("atom-one-light");
+export const TEXTUAL_DARK = defineTheme("textual-dark");
+export const TEXTUAL_LIGHT = defineTheme("textual-light");
+export const TEXTUAL_ANSI = defineTheme("textual-ansi");

package/dist/widgets/button.d.ts

@@ -19,7 +19,7 @@ import { Segment } from "../core/segment.js";
 import type { RenderOptions } from "../core/protocol.js";
 import type { TerminalTheme } from "../core/color.js";
 import { ThemedWidget } from "./themed-widget.js";
-import type { KeyEvent, WidgetMouseEvent } from "./types.js";
+import type { WidgetKeyEvent, WidgetMouseEvent } from "./types.js";
 export type ButtonVariant = "default" | "primary" | "success" | "warning" | "danger";
 export interface ButtonOptions {
     label: string;
@@ -34,10 +34,10 @@ export declare class Button extends ThemedWidget {
     accessor label: string;
     accessor variant: ButtonVariant;
     constructor(options: ButtonOptions);
-    handleKey(event: KeyEvent): void;
+    handleKey(event: WidgetKeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
     setActive(value: boolean): void;
-    protected draw(_options: RenderOptions): Iterable<Segment>;
+    protected draw(options: RenderOptions): Iterable<Segment>;
     measure(_options: RenderOptions): {
         minimum: number;
         maximum: number;

package/dist/widgets/button.js

@@ -49,9 +49,9 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
+import { labeled } from "../core/orient.js";
 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";
 import { ThemedWidget } from "./themed-widget.js";
@@ -61,7 +61,7 @@ import { ink } from "./ink.js";
 //   hover       — full accent bg; pair with hoverFg, NOT with `fg`. The
 //                 text-* keys are mostly-accent and would clash on a full
 //                 accent bg.
-//   hoverFg     — WCAG-correct contrast colour (on-${accent}) for full bg.
+//   hoverFg     — WCAG-correct contrast color (on-${accent}) for full bg.
 const VARIANT_KEYS = {
     default: { bg: "surface", fg: "foreground", hover: "primary", hoverFg: "on-primary" },
     primary: { bg: "primary-muted", fg: "text-primary", hover: "primary", hoverFg: "on-primary" },
@@ -148,24 +148,24 @@ let Button = (() => {
         // --- Active mutator (the keyboard-activation microtask uses this) ---
         setActive(value) { this.active = value; }
         // --- Rendering ---
-        draw(_options) {
+        draw(options) {
             // [LAW:dataflow-not-control-flow] same segment count and width every state
             const focused = this.focused;
             const left = focused ? "[" : " ";
             const right = focused ? "]" : " ";
-            const text = `${left} ${this.label} ${right}`;
+            const drawn = (style) => labeled(`${left} `, this.label, ` ${right}`, style, options.textOrder);
             if (this.disabled) {
-                return [new Segment(text, new Style(this.disabledInk))];
+                return drawn(new Style(this.disabledInk));
             }
-            // Active and hover share the same colour pair (full accent bg + on-accent fg).
+            // Active and hover share the same color pair (full accent bg + on-accent fg).
             // Active is differentiated by bold, not by inverting fg/bg — inversion gives
             // mostly-accent text on mostly-bg-tinted background, which is unreadable for
             // accents whose contrast partner depends on luminance.
             const keys = VARIANT_KEYS[this.variant];
             if (this.active || this.hovered) {
-                return [new Segment(text, new Style({ ...ink(this.theme, keys.hoverFg, keys.hover), bold: this.active }))];
+                return drawn(new Style({ ...ink(this.theme, keys.hoverFg, keys.hover), bold: this.active }));
             }
-            return [new Segment(text, new Style(ink(this.theme, keys.fg, keys.bg)))];
+            return drawn(new Style(ink(this.theme, keys.fg, keys.bg)));
         }
         measure(_options) {
             // [LAW:one-source-of-truth] cellLen is the cell-width authority; .length

package/dist/widgets/checkbox.d.ts

@@ -14,7 +14,7 @@ import { Segment } from "../core/segment.js";
 import { type RenderOptions } from "../core/protocol.js";
 import type { TerminalTheme } from "../core/color.js";
 import { ThemedWidget } from "./themed-widget.js";
-import type { KeyEvent, WidgetMouseEvent } from "./types.js";
+import type { WidgetKeyEvent, WidgetMouseEvent } from "./types.js";
 export interface CheckboxOptions {
     label: string;
     checked?: boolean;
@@ -28,7 +28,7 @@ export declare class Checkbox extends ThemedWidget {
     accessor label: string;
     accessor checked: boolean;
     constructor(options: CheckboxOptions);
-    handleKey(event: KeyEvent): void;
+    handleKey(event: WidgetKeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
     protected draw(options: RenderOptions): Iterable<Segment>;
     measure(_options: RenderOptions): {

package/dist/widgets/checkbox.js

@@ -44,9 +44,9 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
+import { labeled } from "../core/orient.js";
 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";
 import { drawable } from "../core/protocol.js";
@@ -119,12 +119,12 @@ let Checkbox = (() => {
         // --- Rendering ---
         draw(options) {
             const indicator = this.checked ? drawable(options, "✓", "x") : " ";
-            const text = `[${indicator}] ${this.label}`;
+            const drawn = (style) => labeled(`[${indicator}] `, this.label, "", style, options.textOrder);
             if (this.disabled) {
-                return [new Segment(text, new Style(this.disabledInk))];
+                return drawn(new Style(this.disabledInk));
             }
             const colors = ink(this.theme, this.checked ? "text-primary" : "foreground", "background");
-            return [new Segment(text, new Style({ ...colors, underline: this.focused }))];
+            return drawn(new Style({ ...colors, underline: this.focused }));
         }
         measure(_options) {
             // [LAW:one-source-of-truth] cellLen — see button.ts.

package/dist/widgets/dropdown.d.ts

@@ -26,7 +26,7 @@ import { Segment } from "../core/segment.js";
 import { type RenderOptions } from "../core/protocol.js";
 import type { TerminalTheme } from "../core/color.js";
 import { ThemedWidget } from "./themed-widget.js";
-import type { KeyEvent, WidgetMouseEvent, WidgetFocusEvent, OverlayRenderable } from "./types.js";
+import type { WidgetKeyEvent, WidgetMouseEvent, WidgetFocusEvent, OverlayRenderable } from "./types.js";
 export interface DropdownOptions {
     options: string[];
     selectedIndex?: number;
@@ -50,12 +50,12 @@ export declare class Dropdown extends ThemedWidget implements OverlayRenderable
     }[];
     constructor(options: DropdownOptions);
     private clampIndex;
-    handleKey(event: KeyEvent): void;
+    handleKey(event: WidgetKeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
     handleFocus(event: WidgetFocusEvent): void;
     protected draw(options: RenderOptions): Iterable<Segment>;
     private headerText;
-    renderOverlay(_options: RenderOptions): Iterable<Segment> | null;
+    renderOverlay(options: RenderOptions): Iterable<Segment> | null;
     private renderNoMatchRow;
     private renderOptionRow;
     private maxLabelLen;

package/dist/widgets/dropdown.js

@@ -56,6 +56,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
+import { labeled } from "../core/orient.js";
 import { action } from "mobx";
 import { observableRef } from "./observable.js";
 import { Segment } from "../core/segment.js";
@@ -318,7 +319,7 @@ let Dropdown = (() => {
             const headerLabel = this.headerText(maxLabelLen, caret);
             return [
                 new Segment("[", baseStyle),
-                new Segment(`${headerLabel} ${arrowChar}`, baseStyle),
+                ...labeled("", headerLabel, ` ${arrowChar}`, baseStyle, options.textOrder),
                 new Segment("]", baseStyle),
             ];
         }
@@ -348,18 +349,19 @@ let Dropdown = (() => {
             const [filterText] = splitText(this.filter, asCellCol(filterRoom));
             return setCellSize(" " + filterText + caret, asCellCol(maxLabelLen));
         }
-        renderOverlay(_options) {
+        renderOverlay(options) {
             if (!this.expanded)
                 return null;
             const maxLabelLen = this.maxLabelLen();
             const fopts = this.filteredOptions;
             if (fopts.length === 0)
                 return this.renderNoMatchRow(maxLabelLen);
+            const order = options.textOrder;
             const segments = [];
             for (let i = 0; i < fopts.length; i++) {
                 if (i > 0)
                     segments.push(new Segment("\n"));
-                segments.push(...this.renderOptionRow(fopts[i], i, maxLabelLen));
+                segments.push(...this.renderOptionRow(fopts[i], i, maxLabelLen, order));
             }
             return segments;
         }
@@ -379,7 +381,7 @@ let Dropdown = (() => {
                 new Segment(" ", style),
             ];
         }
-        renderOptionRow(entry, fpos, maxLabelLen) {
+        renderOptionRow(entry, fpos, maxLabelLen, order) {
             // Row: "  " + label.padEnd(maxLabelLen) + "  "
             // Width = 1 + 1 + maxLabelLen + 1 + 1 = maxLabelLen + 4.
             // Overlay rows are unbracketed — selection/highlight are conveyed by bg
@@ -399,7 +401,7 @@ let Dropdown = (() => {
                         : new Style(ink(this.theme, "foreground", "surface"));
             return [
                 new Segment(" ", rowStyle),
-                new Segment(inner, rowStyle),
+                ...labeled("", inner, "", rowStyle, order),
                 new Segment(" ", rowStyle),
             ];
         }

package/dist/widgets/event-router.d.ts

@@ -5,13 +5,13 @@
  * It parses nothing and reads no terminal: `App` owns the one parser over its
  * host's input (`host/input`), and `WidgetApp` hands this what the app hears.
  */
-import { KeyEvent } from "./types.js";
+import { WidgetKeyEvent } from "./types.js";
 import type { FrameSource, KeyHandlerOptions } from "./types.js";
 import type { Unsubscribe } from "../core/subscription.js";
-import type { KeyPress } from "../host/input.js";
+import type { KeyEvent } from "../host/input.js";
 import type { AppMouseEvent } from "../host/app.js";
-import type { Wheel } from "../host/app.js";
-type KeyHandler = (event: KeyEvent) => void;
+import type { WheelEvent } from "../host/app.js";
+type KeyHandler = (event: WidgetKeyEvent) => void;
 export interface EventRouterOptions {
     source: FrameSource;
     /** Whether a left-button press focuses the widget under it before it hears the press. */
@@ -44,7 +44,7 @@ export declare class EventRouter {
     onKey(handler: KeyHandler, options?: KeyHandlerOptions): Unsubscribe;
     onMouse(handler: (event: AppMouseEvent) => void): Unsubscribe;
     /** Route a key the app heard. */
-    key(press: KeyPress): void;
+    key(press: KeyEvent): void;
     /** Route a pointer event the app heard. */
     mouse(event: AppMouseEvent): void;
     /**
@@ -53,7 +53,7 @@ export declare class EventRouter {
      * Whether one moved is the answer: with none, the app passes the wheel
      * outward.
      */
-    wheel({ x, y, lines }: Wheel): boolean;
+    wheel({ x, y, lines }: WheelEvent): boolean;
     private point;
     private dispatchKey;
     private dispatchMouse;

package/dist/widgets/event-router.js

@@ -5,7 +5,7 @@
  * It parses nothing and reads no terminal: `App` owns the one parser over its
  * host's input (`host/input`), and `WidgetApp` hands this what the app hears.
  */
-import { KeyEvent } from "./types.js";
+import { WidgetKeyEvent } from "./types.js";
 import { cellOf, drew, originOf, scrollTargetAt, widgetAt } from "./hit.js";
 export class EventRouter {
     source;
@@ -78,7 +78,7 @@ export class EventRouter {
     }
     /** Route a key the app heard. */
     key(press) {
-        this.dispatchKey(new KeyEvent(press, this.source.frameNow().time));
+        this.dispatchKey(new WidgetKeyEvent(press, this.source.frameNow().time));
     }
     /** Route a pointer event the app heard. */
     mouse(event) {

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

@@ -4,12 +4,12 @@
  * [LAW:dataflow-not-control-flow] focus transitions are observable state;
  * widgets react to focus/blur events, the manager never skips dispatch.
  */
-import type { InteractiveWidget, FocusManager, KeyEvent } from "./types.js";
+import type { InteractiveWidget, FocusManager, WidgetKeyEvent } 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[];
+    mounted(): 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. */
@@ -46,7 +46,7 @@ export declare class DefaultFocusManager implements FocusManager {
      */
     settle(): void;
     onChange(handler: (current: InteractiveWidget | null) => void): Unsubscribe;
-    handleKey(event: KeyEvent): void;
+    handleKey(event: WidgetKeyEvent): void;
     private step;
     private clear;
     private setFocus;

package/dist/widgets/focus-manager.js

@@ -90,10 +90,10 @@ let DefaultFocusManager = (() => {
             return this.view.onScreen().filter(takesFocus);
         }
         next() {
-            this.step(this.view.present());
+            this.step(this.view.mounted());
         }
         prev() {
-            this.step([...this.view.present()].reverse());
+            this.step([...this.view.mounted()].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`).
@@ -118,7 +118,7 @@ let DefaultFocusManager = (() => {
          */
         settle() {
             const current = this.currentWidget;
-            if (current && takesFocus(current) && this.view.present().includes(current))
+            if (current && takesFocus(current) && this.view.mounted().includes(current))
                 return;
             const first = this.widgets[0];
             if (first)

package/dist/widgets/index.d.ts

@@ -1,10 +1,10 @@
 export type { KeyHandlerPriority, KeyHandlerOptions, WidgetMouseEvent, WidgetFocusEvent, InteractiveWidget, OverlayRenderable, FocusManager, } from "./types.js";
-export { hasOverlay, KeyEvent } from "./types.js";
+export { hasOverlay, WidgetKeyEvent } from "./types.js";
 export { StaticItem } from "./static-item.js";
 export type { StaticItemOptions } from "./static-item.js";
 export { WidgetBase } from "./widget-base.js";
 export { WidgetApp } from "./widget-app.js";
-export type { WidgetAppOptions, WidgetPresence } from "./widget-app.js";
+export type { WidgetAppOptions, WidgetVisibility } from "./widget-app.js";
 export { Button } from "./button.js";
 export type { ButtonVariant, ButtonOptions } from "./button.js";
 export { Checkbox } from "./checkbox.js";

package/dist/widgets/index.js

@@ -1,4 +1,4 @@
-export { hasOverlay, KeyEvent } from "./types.js";
+export { hasOverlay, WidgetKeyEvent } from "./types.js";
 export { StaticItem } from "./static-item.js";
 export { WidgetBase } from "./widget-base.js";
 export { WidgetApp } from "./widget-app.js";

package/dist/widgets/ink.d.ts

@@ -1,8 +1,8 @@
 /**
- * ink — the colour pair a widget cell is drawn in: a foreground and the ground
+ * ink — the color pair a widget cell is drawn in: a foreground and the ground
  * it stands on, both from one theme's palette.
  *
- * A palette's colours are chosen against that palette's own background. A
+ * A palette's colors are chosen against that palette's own background. A
  * foreground drawn over whatever the terminal shows is readable only when the
  * terminal happens to match the theme — the default theme's white text
  * vanished into a light terminal. With both halves taken from the palette, a
@@ -12,7 +12,7 @@
  * [LAW:types-are-the-program] There is no call that takes a foreground alone,
  * so a widget cannot draw half a pair.
  * [LAW:single-enforcer] Every widget resolves palette roles here, and this is
- * where one that draws no colour (a theme's fully transparent "no background")
+ * where one that draws no color (a theme's fully transparent "no background")
  * is reported.
  */
 import { ColorSpec, type TerminalTheme } from "../core/color.js";