@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/core/memo.d.ts

@@ -12,8 +12,17 @@ export declare const MEMO_MAX = 4096;
  * be a pure function of `key`, so a value recomputed after a clear is the one
  * that was dropped.
  */
-export declare class Memo<V extends NonNullable<unknown>> {
+export declare class Memo<V extends NonNullable<unknown>, K extends string = string> {
     private readonly entries;
     get size(): number;
-    get(key: string, compute: (key: string) => V): V;
+    get(key: K, compute: (key: K) => V): V;
+}
+/**
+ * `Memo`'s contract for a key that is an object rather than a string: a
+ * value computed once per key, for as long as the key lives. Held weakly, so
+ * it needs no bound — a key a host stops holding takes its entry with it.
+ */
+export declare class WeakMemo<V extends NonNullable<unknown>, K extends object> {
+    private readonly entries;
+    get(key: K, compute: (key: K) => V): V;
 }

package/dist/core/memo.js

@@ -32,3 +32,19 @@ export class Memo {
         return value;
     }
 }
+/**
+ * `Memo`'s contract for a key that is an object rather than a string: a
+ * value computed once per key, for as long as the key lives. Held weakly, so
+ * it needs no bound — a key a host stops holding takes its entry with it.
+ */
+export class WeakMemo {
+    entries = new WeakMap();
+    get(key, compute) {
+        const remembered = this.entries.get(key);
+        if (remembered !== undefined)
+            return remembered;
+        const value = compute(key);
+        this.entries.set(key, value);
+        return value;
+    }
+}

package/dist/core/oklch.js

@@ -96,6 +96,11 @@ function inGamut(r, g, b) {
         g >= -GAMUT_EPS && g <= 1 + GAMUT_EPS &&
         b >= -GAMUT_EPS && b <= 1 + GAMUT_EPS);
 }
+/** Polar (C, h°) → OKLab (a, b): the one spelling `deltaE` measures by and `toRgba` draws by. */
+function labOf(c, h) {
+    const hRad = h * (Math.PI / 180);
+    return [c * Math.cos(hRad), c * Math.sin(hRad)];
+}
 // ---------------------------------------------------------------------------
 // Oklch — the value type.
 // ---------------------------------------------------------------------------
@@ -130,6 +135,7 @@ export class Oklch {
         if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) {
             throw new RangeError(`Oklch.alpha must be a finite number in [0,1]; got ${alpha}`);
         }
+        this.#lab = labOf(c, h);
     }
     /** sRGB → linear → OKLab → polar. Pure; no I/O, no allocation beyond the result. */
     static fromRgba(color) {
@@ -265,16 +271,21 @@ export class Oklch {
      * Symmetric and pure.
      */
     deltaE(other) {
-        const a = (this.h * Math.PI) / 180;
-        const b = (other.h * Math.PI) / 180;
-        return Math.hypot(this.l - other.l, this.c * Math.cos(a) - other.c * Math.cos(b), this.c * Math.sin(a) - other.c * Math.sin(b));
+        const [a, b] = this.#lab;
+        const [otherA, otherB] = other.#lab;
+        return Math.hypot(this.l - other.l, a - otherA, b - otherB);
     }
+    /**
+     * This colour's OKLab a and b, kept with it: a colour matched against a
+     * palette is measured against every entry, and each entry against every
+     * colour it is matched with, so the trigonometry is paid once a colour
+     * rather than once a comparison.
+     */
+    #lab;
     /** Linear-sRGB coordinates for an explicit (l, C, h). Pure; `toRgba` passes
      * already-normalized values so this never sees out-of-range inputs. */
     toLinearRgb(l, C, h) {
-        const hRad = h * (Math.PI / 180);
-        const aLab = C * Math.cos(hRad);
-        const bLab = C * Math.sin(hRad);
+        const [aLab, bLab] = labOf(C, h);
         const lCube = l + 0.3963377774 * aLab + 0.2158037573 * bLab;
         const mCube = l - 0.1055613458 * aLab - 0.0638541728 * bLab;
         const sCube = l - 0.0894841775 * aLab - 1.2914855480 * bLab;

package/dist/core/osc8.d.ts

@@ -49,7 +49,7 @@ export declare const OSC8_CLOSE = "\u001B]8;;\u001B\\";
  * on a close. To read bytes back use `osc8Sequences`; this pattern is exported
  * for composing into a larger one (a width measure's zero-width alternation).
  */
-export declare const OSC8: RegExp;
+export declare const OSC8: import("./pattern.js").Pattern;
 /** One OSC 8 sequence found in rendered bytes. A close has `uri === ""`. */
 export interface Osc8Sequence {
     /** Offset of the sequence in the scanned string. */

package/dist/core/osc8.js

@@ -31,15 +31,15 @@
  * exact, not approximate.
  */
 import { fnv1a } from "./fnv1a.js";
+import { pattern } from "./pattern.js";
 /**
  * The bytes that prematurely terminate an OSC 8 sequence: ESC (`\x1b`, which
  * begins ST `ESC \`), BEL (`\x07`), and the 8-bit ST (`\x9c`).
  */
 const TERMINATORS = "\\x1b\\x07\\x9c";
-const TERMINATOR_RE = new RegExp(`[${TERMINATORS}]`, "g");
 /** Remove every byte that could break a URL out of its OSC 8 wrap. */
 export function stripOscTerminators(url) {
-    return url.replace(TERMINATOR_RE, "");
+    return url.replace(new RegExp(`[${TERMINATORS}]`, "g"), "");
 }
 /**
  * The bytes that open a hyperlink to `url`.
@@ -62,14 +62,13 @@ export const OSC8_CLOSE = "\x1b]8;;\x1b\\";
  * on a close. To read bytes back use `osc8Sequences`; this pattern is exported
  * for composing into a larger one (a width measure's zero-width alternation).
  */
-export const OSC8 = new RegExp(`\\x1b\\]8;([^;${TERMINATORS}]*);([^${TERMINATORS}]*)(?:\\x1b\\\\|\\x07|\\x9c)`);
-const OSC8_SCAN = new RegExp(OSC8.source, "g");
+export const OSC8 = pattern(new RegExp(`\\x1b\\]8;([^;${TERMINATORS}]*);([^${TERMINATORS}]*)(?:\\x1b\\\\|\\x07|\\x9c)`));
 /**
  * Every OSC 8 sequence in `text`, in order — the typed way to read rendered
  * bytes back.
  */
 export function osc8Sequences(text) {
-    return [...text.matchAll(OSC8_SCAN)].map((m) => ({
+    return [...text.matchAll(new RegExp(OSC8.source, "g"))].map((m) => ({
         index: m.index,
         length: m[0].length,
         params: m[1],

package/dist/core/paint.d.ts

@@ -71,7 +71,8 @@ export declare class SurfacePainter implements Painter {
      * Paint `frame` over the last frame, leaving the cursor on its last row,
      * and return it as painted. No row is wider than the screen, since one that
      * soft-wrapped would push every row below it down a row the next paint does
-     * not go back over.
+     * not go back over. The rows returned are what `destination` shows
+     * (`shownOn`): under reduced motion, nothing in them blinks.
      */
     paint(frame: FrameSource, screen: Screen, destination: Destination): Segment[][];
     /**

package/dist/core/paint.js

@@ -13,7 +13,7 @@
  * the last row, and the newline that ends it is written once, when the frame
  * is handed back.
  */
-import { segmentsToString } from "./render.js";
+import { segmentsToString, shownOn } from "./render.js";
 import { Segment } from "./segment.js";
 const GEOMETRY = {
     alternate: {
@@ -84,10 +84,11 @@ export class SurfacePainter {
      * Paint `frame` over the last frame, leaving the cursor on its last row,
      * and return it as painted. No row is wider than the screen, since one that
      * soft-wrapped would push every row below it down a row the next paint does
-     * not go back over.
+     * not go back over. The rows returned are what `destination` shows
+     * (`shownOn`): under reduced motion, nothing in them blinks.
      */
     paint(frame, screen, destination) {
-        const rows = fitRows(frame(), screen);
+        const rows = fitRows(frame(), screen).map((row) => row.map((segment) => shownOn(segment, destination)));
         this.write(SYNC_START + this.over(rows, screen, destination) + SYNC_END);
         return rows;
     }

package/dist/core/pattern.d.ts

@@ -0,0 +1,21 @@
+/**
+ * pattern — `Pattern`: a regular expression held where every caller reaches
+ * it — module scope, a class static, a renderable's field — with no cursor
+ * for them to share.
+ *
+ * A `RegExp` carries `lastIndex`, and the `exec`, `test` and `replace` of a
+ * global or sticky one write it, so a global regex held at module scope is
+ * state that every caller moves. A regex with neither flag has a `lastIndex`
+ * that `exec`, `test`, `match`, `replace` and `split` never write. `pattern`
+ * is where that is checked: it refuses `g` and `y`, and hands back only
+ * those, with `source` and `flags` to compose it into another. A cursor — a
+ * sticky scan, a global replace — is made in the function that runs it, so
+ * each call owns its own.
+ */
+declare const PATTERN: unique symbol;
+/** A regex with no cursor: only `pattern` makes one. */
+export type Pattern = Pick<RegExp, "exec" | "test" | "source" | "flags" | typeof Symbol.match | typeof Symbol.replace | typeof Symbol.split> & {
+    readonly [PATTERN]: true;
+};
+export declare function pattern(re: RegExp): Pattern;
+export {};

package/dist/core/pattern.js

@@ -0,0 +1,21 @@
+/**
+ * pattern — `Pattern`: a regular expression held where every caller reaches
+ * it — module scope, a class static, a renderable's field — with no cursor
+ * for them to share.
+ *
+ * A `RegExp` carries `lastIndex`, and the `exec`, `test` and `replace` of a
+ * global or sticky one write it, so a global regex held at module scope is
+ * state that every caller moves. A regex with neither flag has a `lastIndex`
+ * that `exec`, `test`, `match`, `replace` and `split` never write. `pattern`
+ * is where that is checked: it refuses `g` and `y`, and hands back only
+ * those, with `source` and `flags` to compose it into another. A cursor — a
+ * sticky scan, a global replace — is made in the function that runs it, so
+ * each call owns its own.
+ */
+export function pattern(re) {
+    // [LAW:no-silent-failure] A held cursor is refused where it is made, not found later as a match that began mid-string.
+    if (re.global || re.sticky) {
+        throw new TypeError(`/${re.source}/${re.flags} keeps a cursor in lastIndex; make it in the function that runs it`);
+    }
+    return re;
+}

package/dist/core/pretty.js

@@ -18,10 +18,12 @@
  */
 import { asCellCol, cellColToCodeUnitOffset, cellLen, graphemes, splitAtCells } from "./cells.js";
 import { divideLine } from "./wrap.js";
+import { Memo } from "./memo.js";
 import { Segment } from "./segment.js";
 import { RichText, stripControlChars } from "./text.js";
 import { ReprHighlighter } from "./highlighter.js";
 import { drawable, render } from "./protocol.js";
+import { pattern } from "./pattern.js";
 const reprHighlighter = new ReprHighlighter();
 /**
  * What a value is bounded by when whoever formats it has not seen it:
@@ -453,7 +455,7 @@ const elided = (dropped) => dropped > 0 ? [{ head: `... +${dropped}`, join: "",
  * An index is at most 15 digits: every such literal is a safe integer and
  * names itself, where `99999999999999999999` would name `1e20`'s key.
  */
-const BARE_KEY = /^(?![^]*\p{Default_Ignorable_Code_Point})(?:[\p{ID_Start}$_][\p{ID_Continue}$]*|0|[1-9]\d{0,14})$/u;
+const BARE_KEY = pattern(/^(?![^]*\p{Default_Ignorable_Code_Point})(?:[\p{ID_Start}$_][\p{ID_Continue}$]*|0|[1-9]\d{0,14})$/u);
 /**
  * What Python's `str.isprintable` refuses \u2014 control, format, private-use,
  * unassigned, and every separator but the space \u2014 which Rich's repr escapes
@@ -461,9 +463,9 @@ const BARE_KEY = /^(?![^]*\p{Default_Ignorable_Code_Point})(?:[\p{ID_Start}$_][\
  * byte reaches the terminal as a control, and a format character hides or
  * reorders what is around it.
  */
-const UNPRINTABLE = /(?! )[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/gu;
+const unprintable = () => /(?! )[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/gu;
 /** `value` in double quotes, every character that does not print escaped. */
-const quoted = (value) => JSON.stringify(value).replace(UNPRINTABLE, (c) => {
+const quoted = (value) => JSON.stringify(value).replace(unprintable(), (c) => {
     const hex = c.codePointAt(0).toString(16).padStart(4, "0");
     return hex.length > 4 ? `\\u{${hex}}` : `\\u${hex}`;
 });
@@ -477,7 +479,7 @@ export class Pretty {
     indentGuides;
     highlighter;
     // [LAW:no-shared-mutable-globals] A private memo, written only by `_cutString`.
-    cutStrings = new Map();
+    cutStrings = new Memo();
     constructor(data, options) {
         this.data = data;
         this.indent = options?.indent ?? 4;
@@ -595,15 +597,12 @@ export class Pretty {
      * memoised per value.
      */
     _cutString(value, max) {
-        let cut = this.cutStrings.get(value);
-        if (cut === undefined) {
+        return this.cutStrings.get(value, () => {
             const clusters = graphemes(value);
-            cut = clusters.length <= max
+            return clusters.length <= max
                 ? quoted(value)
                 : quoted(clusters.slice(0, max).join("")) + `+${clusters.length - max}`;
-            this.cutStrings.set(value, cut);
-        }
-        return cut;
+        });
     }
     /**
      * A container, or the text standing in for one that is empty or past the

package/dist/core/protocol.d.ts

@@ -3,7 +3,7 @@
  * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
  */
 import type { Segment } from "./segment.js";
-import { Style, type StyleSyntaxError, type Theme } from "./style.js";
+import { Style, type Hold, type StyleSyntaxError, type Theme } from "./style.js";
 import { ColorDepth } from "./color.js";
 import type { Highlighter } from "./highlighter.js";
 /**
@@ -17,6 +17,15 @@ import type { Highlighter } from "./highlighter.js";
  * wrapping and leaves the edge, so a line too wide is cut by the method here.
  */
 export type OverflowMethod = "fold" | "crop" | "ellipsis" | "ignore";
+/**
+ * What draws frames — a `Live`, an `App` — as what draws in them sees it:
+ * the time a frame drawn now is drawn for, the host's clock read through its
+ * timeline for a view on it (`frameTime`, `./view.ts`). Not a `Clock`: under
+ * a paused timeline it holds, and under a reversed one it runs backwards.
+ */
+export interface FrameHost {
+    readonly frameTime: number;
+}
 export interface RenderOptions {
     /**
      * The cells this renderable may occupy. A count of cells, so a non-negative
@@ -68,8 +77,8 @@ export interface RenderOptions {
     highlighter?: Highlighter;
     /**
      * The depth the output will be encoded at, `null` when it carries no colour.
-     * A renderable choosing between two ways of drawing something — the strip's
-     * arrow or its divider — decides on the colours the terminal will draw at
+     * A renderable that measures what it draws — the strip's joiner, holding a
+     * seam's ink off its ground — measures the colours the terminal will draw at
      * this depth, which at 256 colours or fewer are not the colours it was
      * handed. Absent means truecolor.
      */
@@ -86,17 +95,52 @@ export interface RenderOptions {
      * the render strict: the error leaves `render`.
      */
     onStyleError?: StyleErrorHandler;
+    /**
+     * The reader asked for reduced motion — CSS's `prefers-reduced-motion`,
+     * which a terminal has no way to report, so a host is told. A renderable
+     * built for the time the host draws at draws every animation reduced, its
+     * motion taken out and its content kept on time (`shownAt`,
+     * `./view.ts`; `Animation.reduced`, `./animation.ts`). Absent,
+     * everything moves. Nothing here reads it from the environment.
+     */
+    reducedMotion?: boolean;
+    /**
+     * The frame being drawn: `time`, the moment it is drawn for, in seconds, on
+     * the clock its cells' `nextChange` stamps are read on, and `host`, the
+     * host drawing it, whose `frameTime` that moment was. It is how a
+     * renderable that lives across frames — a widget, a `Progress` — draws for
+     * the time without being rebuilt each frame with one, and without reading
+     * a clock. Absent, the frame is drawn for no moment — a `print` — and
+     * nothing drawn from it moves.
+     */
+    frame?: {
+        readonly time: number;
+        readonly host: FrameHost;
+    };
     /**
      * Told of every renderable `render` is asked for, as it is asked, so the
-     * calls arrive in document order: a container before what it holds, its
-     * contents in the order it renders them. `"drawn"` is a renderable drawn at
+     * calls arrive in document order: a container before what it holds, what
+     * it holds in the order it renders it. `"drawn"` is a renderable drawn at
      * the width it was handed; `"held"` is one handed no column, which is still
      * in the view but has nothing drawn for it (`render`). A renderable rendered
      * twice is told twice. A render made to measure is not drawing and is not
      * told (`measuring`).
      */
     onPresent?: (renderable: Renderable, presence: Presence) => void;
+    /**
+     * Told of a hold the frame is in that no cell of it may carry: an animation
+     * placed in the view reports its own, whether or not it drew a cell — one
+     * not yet entered draws none — and one a container crops away is still
+     * reported. It reaches whatever `frame` reaches, so a container that hands
+     * its child the frame's time hands back the child's hold with no word about
+     * either. [LAW:composability] Absent, nobody is listening. A measurement
+     * (`measuring`) and a held render (`holding`) tell too: what they find
+     * decides the frame's layout, so when it changes, the frame may.
+     */
+    onHold?: (hold: Hold) => void;
 }
+/** The one field of the render options that says whether the reader wants motion. */
+export type Motion = Pick<RenderOptions, "reducedMotion">;
 /**
  * Whether a renderable the view holds was drawn, or held: in the view, handed
  * no column, and so not drawn (`render`).
@@ -251,6 +295,39 @@ export declare function withCellWidth(options: RenderOptions): RenderOptions;
 export declare function drawsNothing(options: {
     readonly maxWidth: number;
 }): boolean;
+/**
+ * One render pass: the outermost `render` or `measure` call — a host's frame,
+ * a print — and every `next()` of what it returned, at any depth. Opaque: it
+ * is only an identity, which a `State` compares to say whether this pass made
+ * it.
+ */
+export interface Pass {
+    readonly __pass: unique symbol;
+}
+/**
+ * `handler` run as if between passes: a callback a render makes to user code to
+ * report something it met, such as `onStyleError`, is an event handler, and may
+ * write what one may — print to a console, set a `State` — as React lets an
+ * event handler set state.
+ */
+export declare function betweenPasses<T>(handler: () => T): T;
+/** The pass a render or measure in progress belongs to, or `undefined` between passes. */
+export declare function activePass(): Pass | undefined;
+/**
+ * `effect` run once the render pass in progress has drawn its last segment,
+ * between passes, where it may write what an event handler may: React's commit
+ * phase. A render that learns something only drawing can tell it — the lines
+ * content shown through a `Viewport` runs to at the width it was handed —
+ * draws from what it learned and hands the commit here, rather than writing it
+ * as it draws.
+ *
+ * Effects run in the order they were handed over, which is document order. A
+ * measurement commits nothing, and neither does a pass that throws or whose
+ * caller stops iterating it early: nobody saw what it drew. Outside a pass — a
+ * renderable's `render` called directly — there is nothing to wait for, and
+ * `effect` runs now.
+ */
+export declare function afterPass(effect: () => void): void;
 /**
  * `renderable` drawn under `options`: Rich's `Console.render`, which every
  * renderable there is drawn through, so under one column nothing is.
@@ -262,25 +339,30 @@ export declare function drawsNothing(options: {
  * this, each container asked `drawsNothing` itself, and the ones that forgot
  * drew a child handed no column anyway.
  *
+ * It is where a render pass is entered (`Pass`), so it is the one place a
+ * write during render is refused at: a `State` set in a pass that did not make
+ * it throws (`./state.ts`).
+ *
  * It is also the one reporter of what the view holds (`onPresent`). Under one
- * column a renderable is held, not drawn: what it holds (`Composite`) is
- * walked and reported held in turn, and nothing renders, so no renderable
- * that keeps state while it renders — a `Viewport`'s offset, a `TextInput`'s
- * scroll window — ever commits it at a width that is not shown. The walk runs
- * whether or not anyone listens. Drawing the squeezed subtree at one column
- * instead, and dropping what it drew, did commit that state.
+ * column a renderable is held: in the view, with nothing of it on the frame.
+ * It is drawn all the same and what it drew dropped (`holding`), so what a held
+ * container is reported holding is what it draws, under the options it hands
+ * each child — one description of a container's traversal, not a second
+ * kept beside it.
  */
 export declare function render(renderable: Renderable, options: RenderOptions): Iterable<Segment>;
 /**
- * `options` as a measurement is asked with. A `measure` that renders to learn
- * its shape draws nothing on the frame, so it reports nothing to `onPresent` —
- * one that did would put a widget in the view at the moment a container
- * measured it, and keep one the frame then cropped away.
+ * What `measurable` reports under `options`: asked in a render pass, as
+ * `render` draws in one, with `measuring`'s options.
  *
- * [LAW:single-enforcer] Every measurement starts here: `Measurement.get` and
- * `withBoundedWidth` ask through it, and each `measure` passes it on.
+ * [LAW:single-enforcer] Every call of a `Measurable`'s `measure` in `src/`
+ * goes through here, as every `render` goes through `render`;
+ * `test/seam/render-calls.test.ts` holds both.
  */
-export declare function measuring(options: RenderOptions): RenderOptions;
+export declare function measure(measurable: Measurable, options: RenderOptions): {
+    minimum: number;
+    maximum: number;
+};
 /**
  * The options a renderable should *lay out against*: `withCellWidth`, with an
  * unbounded offer resolved to the renderable's own natural width.
@@ -326,26 +408,6 @@ export interface Measurable {
         maximum: number;
     };
 }
-/**
- * A container: a renderable that draws other renderables. `contents` is what
- * its `render` hands to `render`, in that order where the order is not a
- * width's, decided as the render decides it — and so it is how a container
- * handed no column still reports what it holds (`render`). It takes no
- * options: what a container holds may depend on its state (a hidden `Layout`
- * holds nothing) but never on a width, because under one column there is none.
- * It commits no state, and yields only renderables: text a container builds
- * from a string it holds holds nothing.
- *
- * [LAW:one-source-of-truth] A second description of each container's
- * traversal, so `test/renderables/contents.test.ts` holds every exported
- * renderable's `contents` to what its `render` reports.
- *
- * A consumer's container that does not implement it reports nothing it holds
- * while it is handed no column.
- */
-export interface Composite {
-    contents(): Iterable<Renderable>;
-}
 /**
  * What the wheel scrolls: an owner of anchors on the frame (`./anchor.ts`)
  * that moves by lines. `canScrollBy` says whether `scrollBy` with the same
@@ -358,4 +420,3 @@ export interface Scrollable {
 export declare function isRenderable(obj: unknown): obj is Renderable;
 export declare function isMeasurable(obj: unknown): obj is Measurable;
 export declare function isScrollable(obj: object): obj is Scrollable;
-export declare function isComposite(obj: object): obj is Composite;