@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/renderables/effect.d.ts

@@ -1,30 +1,42 @@
 /**
- * Effected — a renderable whose finished cells' colours pass through an
- * effect at a moment `t`.
+ * Effected — a renderable whose finished cells' looks — colours and text
+ * attributes — pass through an effect at a moment `t`.
  *
- * An effect is one pure function in two stages: a time and what the element
- * draws in that frame in, a function of the frame out; and into that, a
- * cell's colours and where the cell is, the cell's new colours out. Whatever
- * holds for the whole frame is worked out in the first stage, once, and every
- * cell of the frame is handed to the second, but for those a wrapper keeps
- * back: `confined` hands over only the cells its owners drew, so a second
- * stage never counts on seeing them all. Shimmer, pulse, fade and
- * dissolve are all this one shape, differing by what the function does with
- * its inputs [LAW:one-type-per-behavior]; two effects stack by nesting one
+ * An effect is, for what an element draws in a frame, an `Animation`
+ * (`core/animation.ts`) of what is done to its cells: its value at `t` is a
+ * function from a cell's look and where the cell is to the cell's new look
+ * (`EffectFrame`), and it says when that next changes as every
+ * animation does. Whatever holds for the whole frame is worked out once, in
+ * the effect and its `at(t)`, and every cell of the frame is handed to the
+ * function `at(t)` returns, but for those a wrapper keeps back: `confined`
+ * hands over only the cells its owners drew, so an effect never counts on
+ * seeing them all. Shimmer, pulse, fade, dissolve and a blinking attribute
+ * are all this one shape, differing by what the function does with its
+ * inputs [LAW:one-type-per-behavior]; two effects stack by nesting one
  * wrapper in another, which is the same as calling one after the other but
  * for what the outer one measures: the inner one's output.
  *
- * What the element draws (`Drawn`) — the cells the second stage will be
- * handed, and the colours of its words — is measured here, in the render, off
- * the same reading of each segment its cells are drawn from, and handed to the
- * effect's first stage, once a frame. It is what an effect keeping words legible is
- * settled against (`onColors`, `./effects.ts`), so no caller derives it a
- * second time from a render of its own.
+ * A cell's look is one value, its colours and its attributes together
+ * (`CellLook`), rather than an attribute stage beside the colour one, so
+ * everything that takes an `Effect` — `confined`, `onBeat`,
+ * `Animation.all`, nesting over a glyph effect — takes one that moves
+ * attributes with no second copy of itself. `reverse` is the one attribute
+ * a look leaves out (`CellAttributes`): it decides which of a style's slots
+ * a colour on screen is in, and a swap of the two is already a colour move.
  *
- * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
- * clock read. Whoever draws frames builds the view for each frame's `t`, so
- * the same `t` always draws the same bytes, at 30 frames a second or one
- * every two seconds.
+ * What the element draws (`Drawn`) — the cells the effect will be handed,
+ * and the colours of its words — is measured here, in the render, off the
+ * same reading of each segment its cells are drawn from, and handed to the
+ * effect once a frame. It is what an effect keeping words legible is settled
+ * against (`onColors`, `./effects.ts`), so no caller derives it a second time
+ * from a render of its own.
+ *
+ * An `Effected` is the element under its effect over time: an
+ * `Animation<Renderable>`, placed wherever a renderable goes and drawn at
+ * the time of the frame it is drawn in. Its value at `t` is the element
+ * through the effect at `t` (`Recolored`). [LAW:no-ambient-temporal-coupling]
+ * The time is the frame's, never a clock read, so the same time always draws
+ * the same bytes, at 30 frames a second or one every two seconds.
  *
  * What an effect may not do is the contract this module holds:
  *
@@ -34,25 +46,30 @@
  *   segment's link and meta and carries its anchor shifted to the run's first
  *   cell (`Style.shiftedBy`), so hit testing still finds the owner.
  * - A cell whose colours come back unchanged keeps its original `ColorSpec`,
- *   and a segment whose every cell is unchanged is yielded with its look as
- *   it was, so the identity effect is byte-identical; what it gains is when
- *   the frame next changes (`Style.nextChange`), which writes no byte.
+ *   one whose attributes come back as its style set them keeps them, and a
+ *   segment whose every cell is unchanged is yielded with its look as
+ *   it was, so the identity effect is byte-identical; what an `Effected` gains is when
+ *   the frame next changes (`Style.hold`), which writes no byte.
  *   Neighbouring cells the output depth
  *   writes alike stay one segment: a segment is cut only where the written
- *   colours change, so two colours that land on one index are one run.
+ *   colours or the attributes change, so two colours that land on one index
+ *   are one run.
  * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
  *   string, so no frame adds an entry to a parse cache.
- * - With no colour output (`colorSystem: null`) there is nothing for an
- *   effect to change, and the child's segments pass through untouched.
+ * - With no colour output (`colorSystem: null`) no style is written at all,
+ *   attributes included, so there is nothing for an effect to change, and
+ *   the child's segments pass through untouched.
  *
  * Positions are the child's own: row and column count from the top-left of
  * what the child drew, so a sweep crosses the element, not the screen.
  */
 import { type Anchor } from "../core/anchor.js";
+import { Animation } from "../core/animation.js";
+import type { Hold } from "../core/style.js";
 import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js";
-import type { Beat } from "../core/easing.js";
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
+import { type Attributes } from "../core/style.js";
 /**
  * A cell's foreground and background as they appear on screen — the glyph's
  * colour and the colour behind it — which are the colours an effect moves.
@@ -62,6 +79,16 @@ export interface CellColors {
     readonly fg: ColorRgba;
     readonly bg: ColorRgba;
 }
+/**
+ * The text attributes an effect moves: every one a style sets but
+ * `reverse`, each on, off or unset as the cell's style has it. An unset
+ * one lets a style laid beneath show through, as it does undrawn.
+ */
+export type CellAttributes = Omit<Attributes, "reverse">;
+/** What an effect moves in a cell: its colours as the screen shows them, and its attributes. */
+export interface CellLook extends CellColors {
+    readonly attributes: CellAttributes;
+}
 /**
  * Where a cell is in the output of the renderable an effect wraps, its seed:
  * a number in [0, 1) that is the same for that cell on every frame, for an
@@ -119,7 +146,7 @@ export interface Drawn {
     /**
      * Every cell the element shows something in this frame — a glyph, a
      * ground that is not the terminal's, or a line its style draws — where it
-     * sits and who drew it, listed before the second stage is handed any: what
+     * sits and who drew it, listed before the effect is handed any: what
      * an effect spread over the element — a transition, which has its last cell
      * settle as it ends — is spread over. A blank cell on the terminal's ground
      * that draws no line is handed but not listed, since nothing in it shows.
@@ -138,45 +165,24 @@ export interface Drawn {
     /** The terminal the frame is drawn on. */
     readonly theme: TerminalTheme;
 }
+/** What an effect does to the cells of one frame: each cell's look and where it is in, its look out. Return `look` to leave a cell be. */
+export type EffectFrame = (look: CellLook, cell: EffectCell) => CellLook;
 /**
- * The frame at time `t`, in seconds, whose element draws `drawn`: each cell's
- * colours in that frame. Return `colors` to leave a cell be.
- * [LAW:types-are-the-program] Per-frame work is the outer stage, so it runs
- * once a frame by the shape of the call, never by a cache asking whether this
- * cell's frame is the last one's.
+ * For an element drawing `drawn`, the animation of what is done to its cells.
+ * [LAW:types-are-the-program] Per-frame work is `at(t)`, so it runs once a
+ * frame by the shape of the call, never by a cache asking whether this cell's
+ * frame is the last one's.
  *
- * An effect that knows when its frame next changes says so in `nextChange`,
- * asked with the same `t` and `drawn` its first stage is: a stepped one its
- * next step's start, a transition `t` until it is done and `Infinity` after,
- * a loop that holds every cell still at the frame's depth `Infinity` there.
- * [LAW:types-are-the-program] The answer is a fact about the frame, so it is
- * asked with everything the frame is drawn from; an answer asked with `t`
- * alone could not say that a frame is still because of its depth. A plain
- * function is an effect that moves every frame, and answers `t`
- * (`nextChangeOf`): the one true answer for a frame nothing has promised to
- * hold, so a loop needs no second shape.
- */
-export interface Effect {
-    (t: number, drawn: Drawn): (colors: CellColors, cell: EffectCell) => CellColors;
-    /** When the frame drawn at `t` of `drawn` next changes, in seconds on `t`'s timeline, never before `t`; absent, every frame. */
-    readonly nextChange?: (t: number, drawn: Drawn) => number;
-}
-/**
- * When `effect`'s frame at `t` of `drawn` next changes: what it says, or `t`
- * for an effect that says nothing. [LAW:single-enforcer] The one reading of
- * an absent `nextChange`, so no caller holds its own default.
- */
-export declare function nextChangeOf(effect: Effect, t: number, drawn: Drawn): number;
-/**
- * An effect drawing as `effect` does, with `nextChange` as its answer to when
- * its frame next changes, in place of whatever `effect` answered; `effect`
- * itself is left as it was. A composer whose answer depends on the inner
- * effect's reads it with `nextChangeOf`, as `onBeat` and `confined` do.
+ * Its `nextChange` is when the frame next changes: a stepped effect its next
+ * step's start, a transition `t` until it is done and `Infinity` after, a
+ * loop that holds every cell still at the frame's depth `Infinity` there, and
+ * a loop that moves `t` (`Animation.continuous`). [LAW:types-are-the-program]
+ * The answer is a fact about the frame, so the animation is made from
+ * everything the frame is drawn from; one made from `t` alone could not say
+ * that a frame is still because of its depth.
  */
-export declare function withNextChange(effect: Effect, nextChange: (t: number, drawn: Drawn) => number): Effect;
+export type Effect = (drawn: Drawn) => Animation<EffectFrame>;
 export interface EffectedOptions {
-    /** The moment to draw, in seconds. */
-    readonly t: number;
     /**
      * Names the element for its seeds, so two elements showing the same text do
      * not twinkle in lockstep. The same key gives the same seeds on every frame.
@@ -189,20 +195,71 @@ export interface EffectedOptions {
      */
     readonly theme: TerminalTheme;
 }
-export declare class Effected implements Renderable, Measurable {
+/** A frame an effect drew at a moment, and the hold the effect says it is in there. */
+export interface Moved {
+    readonly segments: Iterable<Segment>;
+    readonly hold: Hold;
+}
+/**
+ * An `Effected` at `t`, or an element through an effect at a time an
+ * animation's `at` was handed — a lifecycle's time since it entered: `renderable`
+ * with its cells' looks passed through `effect` at `t`, saying nothing of
+ * when that changes, since whatever placed the animation stamps its hold.
+ * [LAW:one-type-per-behavior]
+ */
+export declare class Recolored implements Renderable, Measurable {
     readonly renderable: Renderable;
     readonly effect: Effect;
     readonly t: number;
     readonly key: string;
     readonly theme: TerminalTheme;
-    constructor(renderable: Renderable, effect: Effect, options: EffectedOptions);
+    constructor(renderable: Renderable, effect: Effect, options: EffectedOptions & {
+        readonly t: number;
+    });
     render(options: RenderOptions): Iterable<Segment>;
-    private _moved;
+    /** The frame the effect draws at `t`, and the hold it says that is in. */
+    moved(options: RenderOptions): Moved;
     private _recolored;
     measure(options: RenderOptions): {
         minimum: number;
         maximum: number;
     };
+    /**
+     * The specs that draw a cell's slot colours `to` where the segment drew
+     * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
+     * in, the rest as `wire` wrote them.
+     */
+    private respec;
+}
+/**
+ * `renderable` under `effect` over time: an `Animation<Renderable>` whose
+ * value at `t` is the element through the effect at `t`, placed wherever a
+ * renderable goes. Its own answer to when it changes is `t`, at every time:
+ * an `Effect` is made from what the element draws, so with nothing drawn
+ * nothing can say more — early, never false. Placed, it says exactly: its
+ * cells carry the effect's own hold at the frame's time and the output's
+ * depth (`stampFrame`), under whatever the element already said, so at a
+ * depth that shows no motion a loop says it never changes there and the
+ * host sleeps.
+ */
+export declare class Effected implements Animation<Renderable> {
+    readonly renderable: Renderable;
+    readonly effect: Effect;
+    readonly key: string;
+    readonly theme: TerminalTheme;
+    constructor(renderable: Renderable, effect: Effect, options: EffectedOptions);
+    /** The element through the effect at `t`, unstamped. */
+    at(t: number): Recolored;
+    nextChange(t: number): number;
+    lastChange(t: number): number;
+    /** The element under the effect with its motion taken out. */
+    reduced(): Effected;
+    /** Drawn at the frame's time, its cells stamped with the effect's exact hold there. */
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
     /**
      * The colours the screen shows for `pair` once it is drawn moved to `to`,
      * both as the screen shows them, at `depth` on `theme`: what an effect
@@ -211,34 +268,34 @@ export declare class Effected implements Renderable, Measurable {
      * moved slot is written with.
      */
     static shows(pair: Pair, to: CellColors, depth: ColorDepth, theme: TerminalTheme): CellColors;
-    /**
-     * The specs that draw a cell's slot colours `to` where the segment drew
-     * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
-     * in, the rest as `wire` wrote them.
-     */
-    private respec;
-    /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
-    private seed;
 }
 /**
- * `effect` sampled and held on `beat`: drawn at the moment the hold in
- * progress began (`Beat.start`), so within a hold every frame is the frame
- * at its start, and at each hold's start it moves on. A continuous effect
- * given a short curve becomes one that steps — a `wheel` turning a sixth of
- * a turn once a second — and at one redraw a second a hold shorter than a
- * second is skipped, as frames are. [LAW:no-ambient-temporal-coupling] The
- * held time is a function of `t`, so the same `t` draws the same bytes at
- * any rate. The frame next changes at a hold's start, and only one the
- * sampled effect has moved by: the first hold start at or after what it
- * answers for the frame held now (`Beat.end`). An effect that moves every
- * frame makes the beat's own answer, the end of this hold; one that is done
- * and says never leaves the beat saying never too, since the hold after this
- * one would draw the same frame. The answer is read off what the effect
- * says, never off a comparison of frames: an effect that steps and is back
- * on the same colour by the next hold still turns the beat there, an early
- * answer the contract allows.
+ * A cell's seed: FNV-1a of the element's key and the cell's position, scaled
+ * into [0, 1). [LAW:one-source-of-truth] One rule for a colour effect's seeds
+ * and a glyph effect's, so one element under both twinkles from one seed.
  */
-export declare function onBeat(effect: Effect, beat: Beat): Effect;
+export declare function cellSeed(key: string, row: number, col: number): number;
+/** A glyph of a segment, placed where its cell is drawn — or none for a newline, which is no cell. */
+export interface WalkedGlyph {
+    readonly glyph: string;
+    readonly cell: Placed | undefined;
+}
+/**
+ * Each glyph of each of `segments`, where its cell sits: rows and columns
+ * from the top-left of the output, a wide glyph one cell at its first
+ * column, and its anchor shifted to that column as `Style.shiftedBy` shifts
+ * a run's. A control segment draws nothing and has none.
+ * [LAW:one-source-of-truth] The one walk: what `Drawn.cells` lists, what the
+ * render hands a colour effect, and what a glyph effect (`./glyph-effect.ts`)
+ * is handed are all read off it.
+ */
+export declare function walkGlyphs(segments: readonly Segment[]): (readonly WalkedGlyph[])[];
+/**
+ * Whether `text` draws ink: anything but blanks. [LAW:one-source-of-truth]
+ * The one test, so the words a colour effect lights are the words a glyph
+ * effect (`./glyph-effects.ts`) scrambles and its particles pass behind.
+ */
+export declare function inked(text: string): boolean;
 /**
  * `effect` on the colours any of `owners` drew, itself or through an owner
  * nested in its output, and every other colour left as it is: one item of a
@@ -257,3 +314,9 @@ export declare function confined(effect: Effect, ...owners: readonly object[]):
  * output under an effect to read the contrast its words are left at.
  */
 export declare function drawnOf(segments: Iterable<Segment>, depth: ColorDepth, theme: TerminalTheme): Drawn;
+/**
+ * The attributes a look carries, read off anything that sets them — a
+ * `Style`, or a look a frame returned with more on it than `CellAttributes`
+ * names. [LAW:one-source-of-truth] The one place `reverse` is left out.
+ */
+export declare function cellAttributes(of: CellAttributes): CellAttributes;