@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/renderables/effect.d.ts

@@ -1,20 +1,28 @@
 /**
- * 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, 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 colours and where the cell is to the cell's new
- * colours (`EffectFrame`), and it says when that next changes as every
+ * 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 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 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.
+ * 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.
+ *
+ * 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.
  *
  * 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
@@ -23,10 +31,12 @@
  * against (`onColors`, `./effects.ts`), so no caller derives it a second time
  * from a render of its own.
  *
- * [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.
+ * 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:
  *
@@ -36,26 +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 { Composite, Measurable, Renderable, RenderOptions } from "../core/protocol.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.
@@ -65,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
@@ -141,8 +165,8 @@ 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 colours and where it is in, its colours out. Return `colors` to leave a cell be. */
-export type EffectFrame = (colors: CellColors, cell: EffectCell) => CellColors;
+/** 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;
 /**
  * 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
@@ -159,8 +183,6 @@ export type EffectFrame = (colors: CellColors, cell: EffectCell) => CellColors;
  */
 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.
@@ -173,21 +195,71 @@ export interface EffectedOptions {
      */
     readonly theme: TerminalTheme;
 }
-export declare class Effected implements Renderable, Measurable, Composite {
+/** 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>;
-    contents(): Iterable<Renderable>;
-    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
@@ -196,34 +268,34 @@ export declare class Effected implements Renderable, Measurable, Composite {
      * 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.lastChange`), 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.nextChange`). 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 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 onBeat(effect: Effect, beat: Beat): Effect;
+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
@@ -242,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;