@promptctl/rich-js 0.24.1 → 0.25.1

package/dist/renderables/frames.d.ts

@@ -7,37 +7,33 @@
  * (`./effect.ts`: "It changes how cells look, never which cells exist or who
  * drew them"). A frame is the other kind of motion — what the element shows
  * changes — so it is its own primitive and not a wider `Effect`, and the two
- * compose by nesting: `new Effected(new Frames(…), …)` lights whichever frame
- * is up.
+ * compose by nesting: `new Effected(sequence, …)` lights whichever frame is
+ * up.
  *
- * [LAW:no-ambient-temporal-coupling] `t` is an argument, as
- * `Effected`'s is, never a clock read: whoever draws frames hands each one
- * its time (`core/clock.ts`), so the same `t` draws the same bytes at one
+ * [LAW:no-ambient-temporal-coupling] `t` is the frame's time, never a
+ * clock read: whoever draws frames hands each one its time
+ * (`RenderOptions.frame`), so the same `t` draws the same bytes at one
  * redraw a second or sixty. The host's rate is the host's. At sixty a frame
  * shows for exactly its hold; at one a second a hold shorter than a second is
  * skipped and a period of whole seconds freezes on one frame, and nothing
  * here adapts to that — the beat is `core/easing.ts`'s, the one timing
  * vocabulary, and a draw costs the same at `t = 0` and `t = 10⁶`.
  *
- * The sequence and the moment are two values, because only one of them
- * changes from frame to frame. A `FrameSequence` is the frames prepared once
- * — the beat, the one width, each frame set into a line and padded — and an
- * `Animation` of the frame shown (`core/animation.ts`); a `Frames` is that
- * sequence at a `t`, whose work is one frame's — finding which, and copying
- * it: a host holds the sequence and asks it for a frame, as `Spinner` holds
- * its two, so a draw costs the same over ninety frames as over one. The
- * sequence is a value the host keeps, not a memo here: nothing is looked up
- * by key.
+ * A `FrameSequence` is the frames prepared once — the beat, the one width,
+ * each frame set into a line and padded — and an `Animation` of the frame
+ * shown (`core/animation.ts`), placed like any other: drawn, its work is one
+ * frame's — finding which, and copying it — so a draw costs the same over
+ * ninety frames as over one. The sequence is a value its holder keeps, as
+ * `Spinner` holds its two, not a memo here: nothing is looked up by key.
  *
- * The frame drawn is drawn until the next begins, and its cells say so: they
- * are stamped with the sequence's `nextChange` (`Style.nextChange`), which
- * rides up through every container to whoever holds the composed frame
+ * The frame drawn is drawn until the next begins, and its cells say so: a
+ * placed sequence stamps them with its hold (`Style.hold`,
+ * `placedRender` in `core/animation.ts`), which rides up
+ * through every container to whoever holds the composed frame
  * (`Segment.nextChange`), so a host drawing at `t` knows when to draw again,
  * and one drawing slower than the frames turn can see that it is skipping
- * them. The stamp is put on by whoever draws the frame at a host time
- * (`frameAt`) — a `Frames`, a `Spinner`, the template `frames` function —
- * and the sequence's `at` hands over the frame alone, because the time a
- * sequence is asked for may be one a `Timeline` mapped from the host's.
+ * them. Nothing an animation's `at` returns carries a stamp of its own: the
+ * stamp is put on where the frame's time is known.
  *
  * Every frame is drawn at one width, the widest frame's, each padded on the
  * right to it, so whatever sits beside the frames never moves as they turn;
@@ -48,11 +44,11 @@
  * binding has no console for, so the frame arrives read, as a `Group`'s
  * children do.
  */
-import type { Animation } from "../core/animation.js";
+import { Animation } from "../core/animation.js";
 import { type Beat } from "../core/easing.js";
-import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import type { Motion, RenderOptions } from "../core/protocol.js";
 import type { Segment } from "../core/segment.js";
-import type { RichText } from "../core/text.js";
+import { RichText } from "../core/text.js";
 /** One frame: what it shows, and how long it is held, in seconds. */
 export interface Frame {
     readonly text: RichText;
@@ -69,7 +65,7 @@ export declare class FrameSequence implements Animation<RichText> {
     /**
      * The frame in progress at `t`, at `width` cells, ending no line: a copy,
      * the caller's to change, carrying no word on when it changes — that is
-     * `frameAt`'s, stamped by whoever draws it at a host time. `beat.at`
+     * stamped where it is placed, at the frame's time. `beat.at`
      * refuses a `t` that is not finite.
      */
     at(t: number): RichText;
@@ -77,40 +73,25 @@ export declare class FrameSequence implements Animation<RichText> {
     nextChange(t: number): number;
     /** When the frame in progress at `t` began: the beat's answer. */
     lastChange(t: number): number;
-}
-/**
- * The frame `animation` shows at host time `t`, its every cell — padding
- * included, so a blank frame among drawn ones still turns — stamped with when
- * it gives way to the next, `animation.nextChange(t)`. [LAW:one-source-of-truth]
- * The stamp is that one answer carried on the cells (`Segment.nextChange`),
- * so a container holding the frame passes it up without asking the
- * animation; and it is put on here, where the host's time is known, and not
- * in the animation's `at`, whose own time a `Timeline` or an
- * `Animation.sequence` may have mapped from the host's — a stamp made there
- * would be a moment on a clock the host cannot read. A copy is stamped, the
- * caller's to change: an animation may hand back the one `RichText` it
- * holds, as `Animation.constant` does, and a stamp on that would outlive
- * the draw it was true for.
- */
-export declare function frameAt(animation: Animation<RichText>, t: number): RichText;
-export interface FramesOptions {
-    /** The moment to draw, in seconds. */
-    readonly t: number;
-}
-/** A sequence's frame in progress at one moment, as a renderable. */
-export declare class Frames implements Renderable, Measurable {
-    readonly sequence: FrameSequence;
-    readonly t: number;
-    private readonly _shown;
-    constructor(sequence: FrameSequence, options: FramesOptions);
+    /** The frames with their motion taken out: the beat's first frame, held, a copy as `at`'s is. */
+    reduced(): Animation<RichText>;
     render(options: RenderOptions): Iterable<Segment>;
     /**
-     * One width both ways: a frame is one picture, never wrapped apart at a
-     * space or narrowed as the frames turn. Fitting it to the room is
-     * `Measurement.get`'s, as for every measurable.
+     * One width both ways, the same for every frame and reduced or not: a frame
+     * is one picture, never wrapped apart at a space or narrowed as the frames
+     * turn. Fitting it to the room is `Measurement.get`'s, as for every measurable.
      */
     measure(): {
         minimum: number;
         maximum: number;
     };
 }
+/**
+ * The text frame `animation` shows at host time `t` under `motion`
+ * (`shownAt`), copied and stamped with the hold it is in there: what the
+ * template `frames` and `glyphs` functions, which know the reader's
+ * preference before any render, splice into a line. The stamp is on the
+ * base style, which an empty text still draws as its one piece of no width,
+ * and on a copy, since an animation may hand back the one `RichText` it holds.
+ */
+export declare function textFrameAt(animation: Animation<RichText>, t: number, motion: Motion): RichText;

package/dist/renderables/frames.js

@@ -7,37 +7,33 @@
  * (`./effect.ts`: "It changes how cells look, never which cells exist or who
  * drew them"). A frame is the other kind of motion — what the element shows
  * changes — so it is its own primitive and not a wider `Effect`, and the two
- * compose by nesting: `new Effected(new Frames(…), …)` lights whichever frame
- * is up.
+ * compose by nesting: `new Effected(sequence, …)` lights whichever frame is
+ * up.
  *
- * [LAW:no-ambient-temporal-coupling] `t` is an argument, as
- * `Effected`'s is, never a clock read: whoever draws frames hands each one
- * its time (`core/clock.ts`), so the same `t` draws the same bytes at one
+ * [LAW:no-ambient-temporal-coupling] `t` is the frame's time, never a
+ * clock read: whoever draws frames hands each one its time
+ * (`RenderOptions.frame`), so the same `t` draws the same bytes at one
  * redraw a second or sixty. The host's rate is the host's. At sixty a frame
  * shows for exactly its hold; at one a second a hold shorter than a second is
  * skipped and a period of whole seconds freezes on one frame, and nothing
  * here adapts to that — the beat is `core/easing.ts`'s, the one timing
  * vocabulary, and a draw costs the same at `t = 0` and `t = 10⁶`.
  *
- * The sequence and the moment are two values, because only one of them
- * changes from frame to frame. A `FrameSequence` is the frames prepared once
- * — the beat, the one width, each frame set into a line and padded — and an
- * `Animation` of the frame shown (`core/animation.ts`); a `Frames` is that
- * sequence at a `t`, whose work is one frame's — finding which, and copying
- * it: a host holds the sequence and asks it for a frame, as `Spinner` holds
- * its two, so a draw costs the same over ninety frames as over one. The
- * sequence is a value the host keeps, not a memo here: nothing is looked up
- * by key.
+ * A `FrameSequence` is the frames prepared once — the beat, the one width,
+ * each frame set into a line and padded — and an `Animation` of the frame
+ * shown (`core/animation.ts`), placed like any other: drawn, its work is one
+ * frame's — finding which, and copying it — so a draw costs the same over
+ * ninety frames as over one. The sequence is a value its holder keeps, as
+ * `Spinner` holds its two, not a memo here: nothing is looked up by key.
  *
- * The frame drawn is drawn until the next begins, and its cells say so: they
- * are stamped with the sequence's `nextChange` (`Style.nextChange`), which
- * rides up through every container to whoever holds the composed frame
+ * The frame drawn is drawn until the next begins, and its cells say so: a
+ * placed sequence stamps them with its hold (`Style.hold`,
+ * `placedRender` in `core/animation.ts`), which rides up
+ * through every container to whoever holds the composed frame
  * (`Segment.nextChange`), so a host drawing at `t` knows when to draw again,
  * and one drawing slower than the frames turn can see that it is skipping
- * them. The stamp is put on by whoever draws the frame at a host time
- * (`frameAt`) — a `Frames`, a `Spinner`, the template `frames` function —
- * and the sequence's `at` hands over the frame alone, because the time a
- * sequence is asked for may be one a `Timeline` mapped from the host's.
+ * them. Nothing an animation's `at` returns carries a stamp of its own: the
+ * stamp is put on where the frame's time is known.
  *
  * Every frame is drawn at one width, the widest frame's, each padded on the
  * right to it, so whatever sits beside the frames never moves as they turn;
@@ -48,9 +44,9 @@
  * binding has no console for, so the frame arrives read, as a `Group`'s
  * children do.
  */
+import { Animation, holdOf, placedRender, shownAt, stamp } from "../core/animation.js";
 import { beat } from "../core/easing.js";
-import { render } from "../core/protocol.js";
-import { Style } from "../core/style.js";
+import { layerStyle } from "../core/style.js";
 import { setIntoLine } from "./embed.js";
 /** A sequence of frames prepared to be drawn: built once, asked for the frame at a time. */
 export class FrameSequence {
@@ -67,7 +63,7 @@ export class FrameSequence {
         this.width = Math.max(...widths);
         this._shown = texts.map((text, i) => {
             // One picture: a slot narrower than the frame crops it, never folds
-            // or wraps it onto a second line, which `Frames.measure` says it cannot take.
+            // or wraps it onto a second line, which `measure` says it cannot take.
             text.noWrap = true;
             text.overflow = "crop";
             return text.padRight(this.width - widths[i]);
@@ -76,7 +72,7 @@ export class FrameSequence {
     /**
      * The frame in progress at `t`, at `width` cells, ending no line: a copy,
      * the caller's to change, carrying no word on when it changes — that is
-     * `frameAt`'s, stamped by whoever draws it at a host time. `beat.at`
+     * stamped where it is placed, at the frame's time. `beat.at`
      * refuses a `t` that is not finite.
      */
     at(t) {
@@ -90,44 +86,33 @@ export class FrameSequence {
     lastChange(t) {
         return this.beat.lastChange(t);
     }
-}
-/**
- * The frame `animation` shows at host time `t`, its every cell — padding
- * included, so a blank frame among drawn ones still turns — stamped with when
- * it gives way to the next, `animation.nextChange(t)`. [LAW:one-source-of-truth]
- * The stamp is that one answer carried on the cells (`Segment.nextChange`),
- * so a container holding the frame passes it up without asking the
- * animation; and it is put on here, where the host's time is known, and not
- * in the animation's `at`, whose own time a `Timeline` or an
- * `Animation.sequence` may have mapped from the host's — a stamp made there
- * would be a moment on a clock the host cannot read. A copy is stamped, the
- * caller's to change: an animation may hand back the one `RichText` it
- * holds, as `Animation.constant` does, and a stamp on that would outlive
- * the draw it was true for.
- */
-export function frameAt(animation, t) {
-    return animation.at(t).copy().stylize(new Style({ nextChange: animation.nextChange(t) }));
-}
-/** A sequence's frame in progress at one moment, as a renderable. */
-export class Frames {
-    sequence;
-    t;
-    // The frame `t` lands on, found once, here, so a bad time fails at construction.
-    _shown;
-    constructor(sequence, options) {
-        this.sequence = sequence;
-        this.t = options.t;
-        this._shown = frameAt(sequence, options.t);
+    /** The frames with their motion taken out: the beat's first frame, held, a copy as `at`'s is. */
+    reduced() {
+        return Animation.map(this.beat.reduced(), (i) => this._shown[i].copy());
     }
     render(options) {
-        return render(this._shown, options);
+        return placedRender(this, options);
     }
     /**
-     * One width both ways: a frame is one picture, never wrapped apart at a
-     * space or narrowed as the frames turn. Fitting it to the room is
-     * `Measurement.get`'s, as for every measurable.
+     * One width both ways, the same for every frame and reduced or not: a frame
+     * is one picture, never wrapped apart at a space or narrowed as the frames
+     * turn. Fitting it to the room is `Measurement.get`'s, as for every measurable.
      */
     measure() {
-        return { minimum: this.sequence.width, maximum: this.sequence.width };
+        return { minimum: this.width, maximum: this.width };
     }
 }
+/**
+ * The text frame `animation` shows at host time `t` under `motion`
+ * (`shownAt`), copied and stamped with the hold it is in there: what the
+ * template `frames` and `glyphs` functions, which know the reader's
+ * preference before any render, splice into a line. The stamp is on the
+ * base style, which an empty text still draws as its one piece of no width,
+ * and on a copy, since an animation may hand back the one `RichText` it holds.
+ */
+export function textFrameAt(animation, t, motion) {
+    const shown = shownAt(animation, t, motion);
+    const stamped = shown.value.copy();
+    stamped.style = layerStyle(stamped.style, stamp(holdOf(shown, t)));
+    return stamped;
+}

package/dist/renderables/glyph-effect.d.ts

@@ -0,0 +1,158 @@
+/**
+ * GlyphEffected — a renderable whose finished cells' glyphs pass through a
+ * glyph effect at a moment `t`: the glyph half of `Effected` (`./effect.ts`),
+ * built to its contract.
+ *
+ * A glyph effect is the colour effect's two-stage shape with a glyph where
+ * the colours were: for the cells an element draws in a frame, an
+ * `Animation` (`../core/animation.ts`) of what is done to them. The first
+ * stage is handed every cell once a frame (`GlyphCell`), blanks included —
+ * rain and stars live there — and whether the output draws ASCII alone
+ * (`DrawnGlyphs`), and works out what holds for the whole frame:
+ * how many cells are typed, where a band is. The second, the function
+ * `at(t)` returns, maps each cell to the text it shows. A typewriter, a
+ * scramble, a wave of case changes and particles on blank cells are all this
+ * one shape (`./glyph-effects.ts`) [LAW:one-type-per-behavior].
+ *
+ * Colour and glyph are not two kinds of animation: each is an `Animation` of
+ * a per-cell map, and they differ only in what a cell is mapped to. The
+ * wrappers are two because the stages are handed different facts. A colour
+ * effect is settled against the depth, the terminal and the colours of the
+ * words (`Drawn`), and with no colour output there is nothing for it to
+ * change. A glyph effect needs none of that, and is written at every depth,
+ * with no colour too. Over one element the two compose by nesting:
+ * `new Effected(new GlyphEffected(child, glyphs, …), colours, …)` moves the
+ * colours of the glyphs the glyph effect left, since each wrapper measures
+ * what its child drew.
+ *
+ * A `GlyphEffected` is the element under its glyph effect over time, an
+ * `Animation<Renderable>` placed as an `Effected` is, its value at `t` the
+ * element through the effect at `t` (`Reglyphed`).
+ * [LAW:no-ambient-temporal-coupling] The time is the frame's, never a clock
+ * read, so the same time draws the same bytes at any frame rate.
+ *
+ * What a glyph effect may not do is the contract this module holds:
+ *
+ * - It changes what a cell shows, never which cells exist, where they are or
+ *   who drew them. The text it returns for a cell is exactly as many cells
+ *   wide (`cellLen`), carries no line break or control character, and does
+ *   not join the cell beside it into one grapheme cluster, or the render
+ *   throws naming the cell [LAW:single-enforcer]. So what sits beside the
+ *   element never moves, and a wide glyph is changed whole — blanked as two
+ *   spaces, scrambled as two one-cell glyphs — never cut.
+ * - A segment whose every glyph comes back as it was is yielded as it was,
+ *   so the identity effect is byte-identical. A changed segment keeps its
+ *   style whole, link, meta and anchor included; no cell has moved, so the
+ *   anchor's offsets are still true and hit testing still finds the owner.
+ * - Placed as a `GlyphEffected`, every cell carries the hold the frame is in
+ *   (`Style.hold`), under whatever the child said,
+ *   as under `Effected`; drawn as a `Reglyphed`, a value, none.
+ *
+ * Positions are the child's own: row and column count from the top-left of
+ * what the child drew.
+ */
+import { Animation } from "../core/animation.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import { Segment } from "../core/segment.js";
+import { type RichText } from "../core/text.js";
+import { type Moved, type Placed } from "./effect.js";
+/**
+ * A cell of the element a glyph effect wraps: the glyph it shows, where it
+ * sits and who drew it, its place in reading order among the cells handed
+ * (`DrawnGlyphs.cells[index]` is this cell), and its seed, a number in [0, 1) that is the
+ * same for that cell on every frame, as an `EffectCell`'s is.
+ */
+export interface GlyphCell extends Placed {
+    readonly glyph: string;
+    readonly index: number;
+    readonly seed: number;
+}
+/** What a glyph effect does to the cells of one frame: a cell in, the text it shows out, as many cells wide. Return `cell.glyph` to leave it be. */
+export type GlyphFrame = (cell: GlyphCell) => string;
+/**
+ * What the element a glyph effect wraps draws in one frame, and on what: the
+ * glyph half of `Drawn`.
+ */
+export interface DrawnGlyphs {
+    /** Every cell, in reading order; a line break is no cell. */
+    readonly cells: readonly GlyphCell[];
+    /**
+     * Whether the output draws ASCII alone (`RenderOptions.asciiOnly`). A glyph
+     * the effect chooses itself, rather than one the element drew, goes through
+     * `drawable` against it, as every glyph the library chooses does.
+     */
+    readonly asciiOnly: boolean;
+}
+/**
+ * For an element drawing `drawn`, the animation of what is done to its
+ * glyphs. Its `nextChange` is when the frame next changes, as an `Effect`'s is.
+ */
+export type GlyphEffect = (drawn: DrawnGlyphs) => Animation<GlyphFrame>;
+export interface GlyphEffectedOptions {
+    /** Names the element for its seeds, as `EffectedOptions.key` does; under both wrappers, one key gives one seed a cell. */
+    readonly key: string;
+}
+/**
+ * A `GlyphEffected` at `t`, or an element through a glyph effect at a time an
+ * animation's `at` was handed: `renderable` with its cells' glyphs passed
+ * through `effect` at `t`, saying nothing of when that changes, as a
+ * `Recolored` is (`./effect.ts`). [LAW:one-type-per-behavior]
+ */
+export declare class Reglyphed implements Renderable, Measurable {
+    readonly renderable: Renderable;
+    readonly effect: GlyphEffect;
+    readonly t: number;
+    readonly key: string;
+    constructor(renderable: Renderable, effect: GlyphEffect, options: GlyphEffectedOptions & {
+        readonly t: number;
+    });
+    render(options: RenderOptions): Iterable<Segment>;
+    /** The frame the effect draws at `t`, and the hold it says that is in. */
+    moved(options: RenderOptions): Moved;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}
+/**
+ * `renderable` under a glyph effect over time, an `Animation<Renderable>`
+ * as an `Effected` is (`./effect.ts`): its own answer is `t`, and placed,
+ * its cells carry the glyph effect's exact hold at the frame's time and the
+ * output's `asciiOnly`, under whatever the element already said.
+ */
+export declare class GlyphEffected implements Animation<Renderable> {
+    readonly renderable: Renderable;
+    readonly effect: GlyphEffect;
+    readonly key: string;
+    constructor(renderable: Renderable, effect: GlyphEffect, options: GlyphEffectedOptions);
+    /** The element through the glyph effect at `t`, unstamped. */
+    at(t: number): Reglyphed;
+    nextChange(t: number): number;
+    lastChange(t: number): number;
+    /** The element under the glyph effect with its motion taken out. */
+    reduced(): GlyphEffected;
+    /** Drawn at the frame's time, its cells stamped with the glyph effect's exact hold there. */
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}
+/**
+ * `text` with its glyphs passed through `effect`, before any render: the
+ * glyph half of a template fragment (`../template-bindings/animation-funcs.ts`),
+ * which is spliced into a line and drawn under a theme it does not know yet,
+ * so it cannot be rendered to cells first as `Reglyphed` renders its child.
+ * The cells are the text's own lines, at its own columns; the contract is
+ * the one `Reglyphed` is held to, through the same checks, over the text's
+ * own glyphs: a neighbour spliced beside it later, a combining mark leading
+ * the next fragment say, is outside what either check can see. The text keeps
+ * its every style and span, each moved to where its glyphs now sit, and a
+ * frame that changes nothing hands the text back as it was. What it says of
+ * when it changes is the effect's, unstamped: whoever draws it at a time
+ * stamps it (`textFrameAt`).
+ */
+export declare function reglyphText(text: RichText, effect: GlyphEffect, options: {
+    readonly key: string;
+    readonly asciiOnly: boolean;
+}): Animation<RichText>;