@promptctl/rich-js 0.25.2 → 0.27.0

package/dist/themes/transpose.d.ts

@@ -17,10 +17,10 @@
  * `ThemeKey` to apply (data), not *whether* to apply one (branch).
  *
  * [LAW:one-source-of-truth] Anchor classification lives only in
- * `ANCHORED_ROOTS` below. The buildPalette derivation guarantees every
- * variant of a semantic root shares the root as its hyphen prefix
- * (`error`, `error-darken-1`, `error-lighten-2`, ...), so one set covers
- * the whole family.
+ * `ANCHORED_ROOTS` below. Every variant of a semantic root carries the root
+ * as its first hyphen segment (`error`, `error-darken-1`, `error-muted`, ...)
+ * or after a `text-` or `on-` that draws on it (`text-error`, `on-error`), so
+ * one set covers the whole family.
  *
  * [LAW:one-way-deps] Imports flow `core/oklch → themes/transpose`;
  * nothing in core/ depends back on this file.
@@ -54,12 +54,7 @@ export declare function isAnchored(varName: string): boolean;
  * lightness shifts, mirror-inversions, hue rotations that don't touch L,
  * and combinations of all three. [LAW:types-are-the-program]
  *
- * The transposing path throws if the palette has no `background` var (the
- * `dark`-flag derivation has nothing to read). Failing loudly is preferred
- * over a silent fallback because the alternative — trusting the source
- * `palette.dark` after an arbitrary L-transform — produces flags that lie.
- * The identity fast-path is exempt: it preserves the source `dark` flag
- * verbatim (no derivation), so it needs no `background` and never throws.
+ * The identity fast-path preserves the source `dark` flag verbatim.
  *
  * @param name Optional override for the resulting palette name. Defaults
  *   to the source palette's name. Callers building a family of transposed

package/dist/themes/transpose.js

@@ -17,15 +17,16 @@
  * `ThemeKey` to apply (data), not *whether* to apply one (branch).
  *
  * [LAW:one-source-of-truth] Anchor classification lives only in
- * `ANCHORED_ROOTS` below. The buildPalette derivation guarantees every
- * variant of a semantic root shares the root as its hyphen prefix
- * (`error`, `error-darken-1`, `error-lighten-2`, ...), so one set covers
- * the whole family.
+ * `ANCHORED_ROOTS` below. Every variant of a semantic root carries the root
+ * as its first hyphen segment (`error`, `error-darken-1`, `error-muted`, ...)
+ * or after a `text-` or `on-` that draws on it (`text-error`, `on-error`), so
+ * one set covers the whole family.
  *
  * [LAW:one-way-deps] Imports flow `core/oklch → themes/transpose`;
  * nothing in core/ depends back on this file.
  */
 import { Oklch, isIdentityKey } from "../core/oklch.js";
+import { pattern } from "../core/pattern.js";
 import { Palette } from "./palette.js";
 /**
  * Semantic roots whose hue is locked under transposition. `error` must
@@ -43,9 +44,11 @@ export const ANCHORED_ROOTS = new Set([
     "success",
     "warning",
 ]);
+const DRAWN_ON = pattern(/^(?:text|on)-/);
 function rootOf(varName) {
-    const dash = varName.indexOf("-");
-    return dash === -1 ? varName : varName.slice(0, dash);
+    const role = varName.replace(DRAWN_ON, "");
+    const dash = role.indexOf("-");
+    return dash === -1 ? role : role.slice(0, dash);
 }
 /**
  * Whether a palette var's hue is locked under transposition. The single
@@ -68,12 +71,7 @@ export function isAnchored(varName) {
  * lightness shifts, mirror-inversions, hue rotations that don't touch L,
  * and combinations of all three. [LAW:types-are-the-program]
  *
- * The transposing path throws if the palette has no `background` var (the
- * `dark`-flag derivation has nothing to read). Failing loudly is preferred
- * over a silent fallback because the alternative — trusting the source
- * `palette.dark` after an arbitrary L-transform — produces flags that lie.
- * The identity fast-path is exempt: it preserves the source `dark` flag
- * verbatim (no derivation), so it needs no `background` and never throws.
+ * The identity fast-path preserves the source `dark` flag verbatim.
  *
  * @param name Optional override for the resulting palette name. Defaults
  *   to the source palette's name. Callers building a family of transposed
@@ -81,23 +79,14 @@ export function isAnchored(varName) {
  */
 export function transposePalette(palette, key, name) {
     if (isIdentityKey(key)) {
-        return new Palette(name ?? palette.name, palette.dark, palette.vars);
+        return new Palette(name ?? palette.name, palette.dark, palette.mapRoles((colour) => colour));
     }
     // Anchors share *everything except* hue with the user's key. They still
     // lightness-invert in a dark↔light flip; they still chroma-scale in a
     // saturation sweep — only their hue is held.
     const anchorKey = { ...key, hueShift: 0 };
-    const next = new Map();
-    for (const [varName, color] of palette.vars) {
-        const effective = isAnchored(varName) ? anchorKey : key;
-        next.set(varName, Oklch.fromRgba(color).applyKey(effective).toRgba());
-    }
-    const newBackground = next.get("background");
-    if (newBackground === undefined) {
-        throw new Error(`transposePalette: palette "${palette.name}" has no "background" ` +
-            `var; cannot derive the dark flag without a background color.`);
-    }
-    const newDark = Oklch.fromRgba(newBackground).l < 0.5;
+    const next = palette.mapRoles((colour, role) => Oklch.fromRgba(colour).applyKey(isAnchored(role) ? anchorKey : key).toRgba());
+    const newDark = Oklch.fromRgba(next.background).l < 0.5;
     return new Palette(name ?? palette.name, newDark, next);
 }
 /**

package/dist/widgets/event-router.js

@@ -78,7 +78,7 @@ export class EventRouter {
     }
     /** Route a key the app heard. */
     key(press) {
-        this.dispatchKey(new KeyEvent(press, this.source.frameTime));
+        this.dispatchKey(new KeyEvent(press, this.source.frameNow().time));
     }
     /** Route a pointer event the app heard. */
     mouse(event) {
@@ -173,7 +173,7 @@ export class EventRouter {
             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,
+            time: this.source.frameNow().time,
         });
         if (event.type === "mouse_down")
             this.captured = target;

package/dist/widgets/ink.d.ts

@@ -11,12 +11,13 @@
  *
  * [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 keys here, and this is
- * where a key the palette lacks, or one that draws no colour (a theme's
- * fully transparent "no background"), is reported.
+ * [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")
+ * is reported.
  */
 import { ColorSpec, type TerminalTheme } from "../core/color.js";
-export declare function ink(theme: TerminalTheme, fg: string, bg: string): {
+import type { PaletteRole } from "../themes/palette.js";
+export declare function ink(theme: TerminalTheme, fg: PaletteRole, bg: PaletteRole): {
     color: ColorSpec;
     bgcolor: ColorSpec;
 };

package/dist/widgets/ink.js

@@ -11,21 +11,18 @@
  *
  * [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 keys here, and this is
- * where a key the palette lacks, or one that draws no colour (a theme's
- * fully transparent "no background"), is reported.
+ * [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")
+ * is reported.
  */
 import { ColorSpec } from "../core/color.js";
 export function ink(theme, fg, bg) {
     return { color: paletteColor(theme, fg), bgcolor: paletteColor(theme, bg) };
 }
-function paletteColor(theme, key) {
-    const rgba = theme.palette.get(key);
-    if (rgba === undefined) {
-        throw new RangeError(`palette ${JSON.stringify(theme.palette.name)} has no ${JSON.stringify(key)}`);
-    }
+function paletteColor(theme, role) {
+    const rgba = theme.palette.get(role);
     if (rgba.alpha === 0) {
-        throw new RangeError(`palette ${JSON.stringify(theme.palette.name)}: ${JSON.stringify(key)} is fully transparent, so it cannot be half of a widget's colour pair`);
+        throw new RangeError(`palette ${JSON.stringify(theme.palette.name)}: ${JSON.stringify(role)} is fully transparent, so it cannot be half of a widget's colour pair`);
     }
     return ColorSpec.fromRgba(rgba);
 }

package/dist/widgets/text-input.d.ts

@@ -198,7 +198,7 @@ export declare class TextInput extends ThemedWidget {
     readonly focusable = true;
     private accessor _value;
     private accessor _cursor;
-    private accessor _blinkFrom;
+    private accessor _blink;
     get value(): string;
     set value(v: string);
     get cursorPosition(): CodePoint;

package/dist/widgets/text-input.js

@@ -107,7 +107,7 @@ import { Viewport } from "../renderables/viewport.js";
 import { Animation } from "../core/animation.js";
 import { beat } from "../core/easing.js";
 import { Timeline } from "../core/timeline.js";
-import { holdOf, shownAt, stampFrame } from "../core/animation.js";
+import { placed } from "../core/animation.js";
 import { levelOf } from "../core/anchor.js";
 import { ThemedWidget } from "./themed-widget.js";
 import { ink } from "./ink.js";
@@ -244,8 +244,24 @@ function wordSpan(clusters, skipped, taken) {
  * for the next, on a `beat`. A loop, so with its motion taken out it holds lit.
  */
 const CARET_BLINK = Animation.map(beat([0.5, 0.5]), (hold) => hold === 0);
-/** The caret of a frame drawn for no moment — a `print` — which nothing moves: lit, and never changing. */
-const CARET_UNTIMED = { lit: true, hold: { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY } };
+/**
+ * The caret's blink restarted at `from`, as one animation of the frame's
+ * time: `CARET_BLINK` run forward from `from` at and after it, and backward
+ * from it before, so a timeline played backwards also finds the caret lit
+ * just after a key. Each answer is the run the time falls in, bounded at
+ * `from` where the runs meet — early where it must guess, never late. A
+ * function of `from` alone, so the frame hands it its time (`placed`).
+ */
+function caretBlink(from) {
+    const forward = Timeline.run(Timeline.play(from, 1), CARET_BLINK);
+    const backward = Timeline.run(Timeline.play(from, -1), CARET_BLINK);
+    return Animation.of({
+        at: (t) => (t >= from ? forward : backward).at(t),
+        nextChange: (t) => (t >= from ? forward.nextChange(t) : Math.min(backward.nextChange(t), from)),
+        lastChange: (t) => (t >= from ? Math.max(forward.lastChange(t), from) : backward.lastChange(t)),
+        reduced: () => CARET_BLINK.reduced(),
+    });
+}
 let TextInput = (() => {
     let _classSuper = ThemedWidget;
     let _instanceExtraInitializers = [];
@@ -255,9 +271,9 @@ let TextInput = (() => {
     let __cursor_decorators;
     let __cursor_initializers = [];
     let __cursor_extraInitializers = [];
-    let __blinkFrom_decorators;
-    let __blinkFrom_initializers = [];
-    let __blinkFrom_extraInitializers = [];
+    let __blink_decorators;
+    let __blink_initializers = [];
+    let __blink_extraInitializers = [];
     let _placeholder_decorators;
     let _placeholder_initializers = [];
     let _placeholder_extraInitializers = [];
@@ -298,7 +314,7 @@ let TextInput = (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             __value_decorators = [observableRef];
             __cursor_decorators = [observableRef];
-            __blinkFrom_decorators = [observableRef];
+            __blink_decorators = [observableRef];
             _placeholder_decorators = [observableRef];
             _indicatorStyleOverride_decorators = [observableRef];
             _cursorStyleOverride_decorators = [observableRef];
@@ -328,7 +344,7 @@ let TextInput = (() => {
             __insertText_decorators = [action];
             __esDecorate(this, null, __value_decorators, { kind: "accessor", name: "_value", static: false, private: false, access: { has: obj => "_value" in obj, get: obj => obj._value, set: (obj, value) => { obj._value = value; } }, metadata: _metadata }, __value_initializers, __value_extraInitializers);
             __esDecorate(this, null, __cursor_decorators, { kind: "accessor", name: "_cursor", static: false, private: false, access: { has: obj => "_cursor" in obj, get: obj => obj._cursor, set: (obj, value) => { obj._cursor = value; } }, metadata: _metadata }, __cursor_initializers, __cursor_extraInitializers);
-            __esDecorate(this, null, __blinkFrom_decorators, { kind: "accessor", name: "_blinkFrom", static: false, private: false, access: { has: obj => "_blinkFrom" in obj, get: obj => obj._blinkFrom, set: (obj, value) => { obj._blinkFrom = value; } }, metadata: _metadata }, __blinkFrom_initializers, __blinkFrom_extraInitializers);
+            __esDecorate(this, null, __blink_decorators, { kind: "accessor", name: "_blink", static: false, private: false, access: { has: obj => "_blink" in obj, get: obj => obj._blink, set: (obj, value) => { obj._blink = value; } }, metadata: _metadata }, __blink_initializers, __blink_extraInitializers);
             __esDecorate(this, null, _placeholder_decorators, { kind: "accessor", name: "placeholder", static: false, private: false, access: { has: obj => "placeholder" in obj, get: obj => obj.placeholder, set: (obj, value) => { obj.placeholder = value; } }, metadata: _metadata }, _placeholder_initializers, _placeholder_extraInitializers);
             __esDecorate(this, null, _indicatorStyleOverride_decorators, { kind: "accessor", name: "indicatorStyleOverride", static: false, private: false, access: { has: obj => "indicatorStyleOverride" in obj, get: obj => obj.indicatorStyleOverride, set: (obj, value) => { obj.indicatorStyleOverride = value; } }, metadata: _metadata }, _indicatorStyleOverride_initializers, _indicatorStyleOverride_extraInitializers);
             __esDecorate(this, null, _cursorStyleOverride_decorators, { kind: "accessor", name: "cursorStyleOverride", static: false, private: false, access: { has: obj => "cursorStyleOverride" in obj, get: obj => obj.cursorStyleOverride, set: (obj, value) => { obj.cursorStyleOverride = value; } }, metadata: _metadata }, _cursorStyleOverride_initializers, _cursorStyleOverride_extraInitializers);
@@ -366,13 +382,12 @@ let TextInput = (() => {
         #_cursor_accessor_storage = (__runInitializers(this, __value_extraInitializers), __runInitializers(this, __cursor_initializers, void 0));
         get _cursor() { return this.#_cursor_accessor_storage; }
         set _cursor(value) { this.#_cursor_accessor_storage = value; }
-        #_blinkFrom_accessor_storage = (__runInitializers(this, __cursor_extraInitializers), __runInitializers(this, __blinkFrom_initializers, 0));
-        // When the field last took focus, a click, or a key it handled, on the
-        // frame's clock (each event's `time`): where the caret's blink restarts.
-        // The blink itself is a function of this and the time a frame is drawn
-        // for, so nothing about it is kept.
-        get _blinkFrom() { return this.#_blinkFrom_accessor_storage; }
-        set _blinkFrom(value) { this.#_blinkFrom_accessor_storage = value; }
+        #_blink_accessor_storage = (__runInitializers(this, __cursor_extraInitializers), __runInitializers(this, __blink_initializers, caretBlink(0)));
+        // The caret's blink, restarted (`caretBlink`) when the field last took
+        // focus, a click, or a key it handled, at that event's `time` on the
+        // frame's clock. Built at the event, so a frame only reads it.
+        get _blink() { return this.#_blink_accessor_storage; }
+        set _blink(value) { this.#_blink_accessor_storage = value; }
         // [LAW:single-enforcer] Every write to either half of the pair passes
         // `graphemeBoundary`, so the cursor is a cluster boundary inside `value`
         // whoever set it last — a caller replacing `value`, a click, an insert that
@@ -388,7 +403,7 @@ let TextInput = (() => {
         }
         get cursorPosition() { return this._cursor; }
         set cursorPosition(p) { this._cursor = graphemeBoundary(this._value, p); }
-        #placeholder_accessor_storage = (__runInitializers(this, __blinkFrom_extraInitializers), __runInitializers(this, _placeholder_initializers, void 0));
+        #placeholder_accessor_storage = (__runInitializers(this, __blink_extraInitializers), __runInitializers(this, _placeholder_initializers, void 0));
         get placeholder() { return this.#placeholder_accessor_storage; }
         set placeholder(value) { this.#placeholder_accessor_storage = value; }
         _maxLength = __runInitializers(this, _placeholder_extraInitializers);
@@ -468,7 +483,7 @@ let TextInput = (() => {
             this._edit(event);
             if (!event.stopped)
                 return;
-            this._blinkFrom = event.time;
+            this._blink = caretBlink(event.time);
             // An edit on the cursor's row moves no followed range, so the row is
             // brought into view here too: typing after the wheel scrolled away scrolls
             // back. The rows are the edited value's, at the width last drawn.
@@ -479,7 +494,7 @@ let TextInput = (() => {
         }
         handleFocus(event) {
             super.handleFocus(event);
-            this._blinkFrom = event.time;
+            this._blink = caretBlink(event.time);
         }
         _edit(event) {
             if (this.disabled)
@@ -653,7 +668,7 @@ let TextInput = (() => {
                 return;
             if (event.type !== "mouse_down")
                 return;
-            this._blinkFrom = event.time;
+            this._blink = caretBlink(event.time);
             // [LAW:no-silent-failure] Every cell the field draws carries its frame's
             // layout, so a press without one did not come off a frame it drew.
             const layout = layoutOn(event.cell);
@@ -1091,20 +1106,14 @@ let TextInput = (() => {
             return { lines: withArrows, layout: { drawn, kind: "rows", rows: visualRows, offset } };
         }
         // The caret's cell for the frame `options` draws: the blink restarted at the
-        // last touch, sampled at the frame's time (`shownAt`, so under reduced
-        // motion it holds lit). It runs away from the restart in either direction
-        // of time, so a timeline played backwards also finds it lit just after a
-        // key. Lit, the cell is the cursor's; dark, it is drawn as the
-        // text around it, since the cursor is a colour pair and no attribute hides
-        // it. The cell says when it next flips, which is when a host draws again.
+        // last touch, placed as every animation is (`placed`), so it draws at the
+        // frame's time, holds lit under reduced motion, and the cell says when it
+        // next flips, which is when a host draws again. A print, drawn for no
+        // moment, draws it at 0 like any placed animation. Lit, the cell is the
+        // cursor's; dark, it is drawn as the text around it, since the cursor is a
+        // colour pair and no attribute hides it.
         _caret(at, cursorStyle, contentStyle, options) {
-            const { frame } = options;
-            const blink = (time) => {
-                const shown = shownAt(Timeline.run(Timeline.play(this._blinkFrom, time < this._blinkFrom ? -1 : 1), CARET_BLINK), time, options);
-                return { lit: shown.value, hold: holdOf(shown, time) };
-            };
-            const { lit, hold } = frame === undefined ? CARET_UNTIMED : blink(frame.time);
-            return stampFrame([new Segment(at, lit ? cursorStyle : contentStyle)], hold);
+            return placed(this._blink, options, (lit) => [new Segment(at, lit ? cursorStyle : contentStyle)]);
         }
         // Whether `rows` visual rows draw a scroll arrow in the last cell of a row.
         _drawsArrows(rows) {

package/dist/widgets/types.d.ts

@@ -5,7 +5,7 @@
  * producing Segment[] from current state. They have no knowledge of stdin,
  * terminal escape sequences, or their host environment.
  */
-import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { HostFrame, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 import type { Segment } from "../core/segment.js";
 import type { Anchor } from "../core/anchor.js";
 import type { Unsubscribe } from "../core/subscription.js";
@@ -71,6 +71,6 @@ export interface FocusManager {
 export interface FrameSource {
     readonly focusManager: FocusManager;
     readonly frame: readonly (readonly Segment[])[];
-    readonly frameTime: number;
+    frameNow(): HostFrame;
     refresh(): void;
 }

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

@@ -26,7 +26,7 @@
  * hear the input.
  */
 import { Segment } from "../core/segment.js";
-import type { FrameHost, Presence } from "../core/protocol.js";
+import type { HostFrame, FrameHost, Presence } from "../core/protocol.js";
 import type { Unsubscribe } from "../core/subscription.js";
 import type { Clock, FrameRate } from "../core/clock.js";
 import type { Timeline } from "../core/timeline.js";
@@ -72,8 +72,8 @@ export declare class WidgetApp implements FrameSource, FrameHost {
     private get widgets();
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame(): readonly (readonly Segment[])[];
-    /** The time a frame drawn now is drawn for, as `App.frameTime` reads it. */
-    get frameTime(): number;
+    /** The frame this app draws now (`FrameHost`): the App's time, on a frame this app is the host of, as its frames say. */
+    frameNow(): HostFrame;
     /**
      * Take the terminal, paint the first frame, and route input to its widgets
      * until the app stops — `App.run`, with the input.

package/dist/widgets/widget-app.js

@@ -50,7 +50,7 @@ export class WidgetApp {
         // The view is drawn inside `compose`, where what it reads is tracked —
         // a function view asked there too — and when it changes is its own to
         // say, as it would be to the App.
-        // Its frames are its own, drawn for its `frameTime`: what draws in them
+        // Its frames are its own, drawn for its `frameNow()`: what draws in them
         // is told this app is the host, not the App it paints through, so
         // `drawnBy: widgetApp` names the host its frames carry.
         this.app = new App({
@@ -65,7 +65,7 @@ export class WidgetApp {
                 const owners = ownersOn(this.app.frame);
                 return this.widgets.filter((widget) => owners.has(widget));
             },
-            frameTime: () => this.frameTime,
+            frameTime: () => this.frameNow().time,
         });
         this.focusManager = this.focus;
         this.router = new EventRouter({ source: this, focusOnClick });
@@ -118,9 +118,9 @@ export class WidgetApp {
     get frame() {
         return this.app.frame;
     }
-    /** The time a frame drawn now is drawn for, as `App.frameTime` reads it. */
-    get frameTime() {
-        return this.app.frameTime;
+    /** The frame this app draws now (`FrameHost`): the App's time, on a frame this app is the host of, as its frames say. */
+    frameNow() {
+        return { time: this.app.frameNow().time, host: this };
     }
     /**
      * Take the terminal, paint the first frame, and route input to its widgets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.25.2",
+  "version": "0.27.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",