@promptctl/rich-js 0.28.0 → 0.29.0

package/dist/renderables/effects.d.ts

@@ -2,21 +2,21 @@
  * The effect catalogue: shimmer, pulse, sparkle and wheel, which loop for as
  * long as they are drawn, fade-in and dissolve-out, which run once and are
  * done, a blink and a bold pulse, which move an attribute on a beat, and a
- * gradient, which lays a colour ramp across an element and may move it. Each is an `Effect` for `Effected` (`./effect.ts`); the defaults
+ * gradient, which lays a color ramp across an element and may move it. Each is an `Effect` for `Effected` (`./effect.ts`); the defaults
  * in `EFFECT_CURVES` are the ones signed off by eye in the effects-feel demo
  * (`npm run effects-feel`), at 30 fps and at one frame a second, and
  * `EFFECT_CATALOGUE` makes every one of them at those, by name, one way.
  *
  * Each effect is something a first-time observer already knows from life —
- * a slow glow, sunlight moving on water, the colours of daylight, fireflies, ink
+ * a slow glow, sunlight moving on water, the colors of daylight, fireflies, ink
  * blooming in water, mist lifting — because a motion the eye recognises
  * reads as calm and alive, where a motion it has to learn reads as a widget.
  * One effect here is not ambience but a signal, and keeps none of this on
- * purpose: `steppedInk` steps its ink through colours on a beat, the news
+ * purpose: `steppedInk` steps its ink through colors on a beat, the news
  * that something is at its limit, and jumps from slot to slot where the
  * loops hold still. Nor is `gradient` a light: it paints an ink rather than
  * lighting it, so it may darken one, and a ramp scrolled across it jumps
- * where the ramp wraps unless its ends are one colour. Of the list below it
+ * where the ramp wraps unless its ends are one color. Of the list below it
  * keeps the words. What makes the loops' motions familiar is what every
  * curve of theirs keeps:
  *
@@ -32,13 +32,13 @@
  *   filaments, fronts — never per-cell static.
  * - Light only ever lights, and never takes the words away. Ink and the
  *   fill under it both move toward the light and never darken, each by its
- *   own share: the share a colour can take while every cell it is drawn in
+ *   own share: the share a color can take while every cell it is drawn in
  *   still reads at its resting contrast or WCAG AA, whichever is lower. A
  *   cell with contrast to spare glows brightly; one with none barely moves.
  * - Elements are apart. Each sits at its own `z` in the noise, so two
  *   elements under one effect do not move in lockstep.
  *
- * Colour moves are in OKLCH, where equal steps look equal. A curve's `ease`
+ * Color moves are in OKLCH, where equal steps look equal. A curve's `ease`
  * maps its intensity in [0, 1] — how strongly the effect acts on a cell at a
  * moment — onto its swing, for the loops and the transitions alike.
  *
@@ -52,11 +52,11 @@
  */
 import { Animation } from "../core/animation.js";
 import { ColorRgba } from "../core/color.js";
-import { type Beat, type Timing } from "../core/easing.js";
+import { type StepSequence, type Timing } from "../core/easing.js";
 import type { ColorRamp } from "../themes/ramp.js";
 import { type CellAttributes, type Drawn, type Effect, type EffectCell } from "./effect.js";
-/** What a loop does to one colour at strength `w` in [0, 1]: at 0, nothing. */
-export type Touch = (color: ColorRgba, w: number) => ColorRgba;
+/** What a loop does to one color at strength `w` in [0, 1]: at 0, nothing. */
+export type ColorModifier = (color: ColorRgba, w: number) => ColorRgba;
 /**
  * How strongly a loop acts at a moment `t` on each cell of a frame drawing
  * what `Drawn` says, in [0, 1]; `onColors` holds a field outside it to it.
@@ -64,51 +64,51 @@ export type Touch = (color: ColorRgba, w: number) => ColorRgba;
  * then every cell is asked.
  */
 export type Field = (t: number, drawn: Drawn) => (cell: EffectCell) => number;
-/** A looping effect: what it does to a colour, and where and when, how strongly. */
+/** A looping effect: what it does to a color, and where and when, how strongly. */
 export interface Loop {
-    readonly touch: Touch;
+    readonly touch: ColorModifier;
     readonly field: Field;
 }
 /**
  * How much of `touch` each of `colors` (hex) can take: the largest share in
  * [0, 1] at which every pair `drawn` shows it in, touched at the same
  * strength, still reads at its resting contrast or `LEGIBLE`, whichever is
- * lower, in the colours `Effected` writes it in at `drawn`'s depth and terminal.
- * A colour in a pair but not in `colors` takes none, and so does one
+ * lower, in the colors `Effected` writes it in at `drawn`'s depth and terminal.
+ * A color in a pair but not in `colors` takes none, and so does one
  * the terminal supplies, whatever its hex, as in `onColors`. One of `colors`
  * no pair writes has nothing to be measured against, and takes it all.
  *
- * Colours are settled lightest first, each against every partner: one
+ * Colors are settled lightest first, each against every partner: one
  * already settled at its share, one not yet settled as it is. So the lighter
- * colour of a cell takes the light first and its darker partner spends
+ * color of a cell takes the light first and its darker partner spends
  * whatever contrast is left — pale lettering lifting off a dark fill gives
- * the fill room to glow — and a darker colour left as it is always holds,
+ * the fill room to glow — and a darker color left as it is always holds,
  * because its lighter partner was settled against exactly that.
  */
-export declare function shares({ pairs, depth, terminal }: Drawn, colors: ReadonlySet<string>, touch: Touch): Map<string, number>;
+export declare function shares({ pairs, depth, terminal }: Drawn, colors: ReadonlySet<string>, touch: ColorModifier): Map<string, number>;
 /**
- * A loop as an `Effect` on the element's own colours, by hex, wherever a cell
+ * A loop as an `Effect` on the element's own colors, by hex, wherever a cell
  * shows them, each touched at its share of the cell's strength: the share
  * `shares` settles for it against the pairs the element draws its words in
  * (`Drawn`), touched as `Effected` writes them at the frame's depth — at 256
- * colours a touched colour lands on a colour the slot can write, and the
- * contrast it spends is that colour's; on a sixteen-colour terminal nothing
- * moves (`stillWhereNothingMoves`). `colors` are the ones lit, by default every colour the element
+ * colors a touched color lands on a color the slot can write, and the
+ * contrast it spends is that color's; on a sixteen-color terminal nothing
+ * moves (`staticWhereUnchanged`). `colors` are the ones lit, by default every color the element
  * sets itself. A powerline strip's fill is the ground of its cells and the
  * ink of the seam glyphs between them, so the arrow moves with the cell it
- * points out of. A colour the terminal supplies (`Pair.terminal`) is
+ * points out of. A color the terminal supplies (`Pair.terminal`) is
  * not the element's, whatever its hex, and takes no share.
  *
- * Settling shares is costly, so it is done once for each set of colours an
+ * Settling shares is costly, so it is done once for each set of colors an
  * element draws: make the effect once and draw it in every frame, and a frame
  * drawing what an earlier one drew costs no settling.
  */
 export declare function onColors(loop: Loop, colors?: ReadonlySet<string>): Effect;
 /**
- * A ramp laid across the element: each lit cell's ink is the colour `ramp`
+ * A ramp laid across the element: each lit cell's ink is the color `ramp`
  * shows at `t` at the cell's column, the element's leftmost cell reading
  * the ramp's first stop and its rightmost its last, each at its cell's
- * centre — or, where that colour would not read on the cell's ground, the
+ * centre — or, where that color would not read on the cell's ground, the
  * nearest that does (`legibleInks`, as `steppedInk` writes its steps). A
  * ramp that moves (`ColorRamp.moving`) scrolls along the element and turns
  * its hues, and the frame changes when the ramp does — every frame for a
@@ -116,20 +116,20 @@ export declare function onColors(loop: Loop, colors?: ReadonlySet<string>): Effe
  * `Animation.constant(ramp)`. Lit cells are those whose ink is one of
  * `colors`, named as a style names them (`"#a6e3a1"`, `"bright_green"`),
  * opaque, and matched as the screen shows them at the frame's depth — so
- * below truecolor every ink that lands on the same palette colour is lit —
- * by default every colour the element sets itself — never an ink the terminal supplies: a
- * rule's line by its colour and not its title, a panel's border and not its
+ * below truecolor every ink that lands on the same palette color is lit —
+ * by default every color the element sets itself — never an ink the terminal supplies: a
+ * rule's line by its color and not its title, a panel's border and not its
  * body. The element is where its frame lists
  * cells, as the fireflies read it, so a padded or confined element has the
- * ramp across what it shows. On a sixteen-colour terminal nothing moves
- * (`stillWhereNothingMoves`): a gradient there is jumps between slots, and the cells
+ * ramp across what it shows. On a sixteen-color terminal nothing moves
+ * (`staticWhereUnchanged`): a gradient there is jumps between slots, and the cells
  * hold as drawn.
  */
 export declare function gradient(ramp: Animation<ColorRamp>, colors?: readonly string[]): Effect;
 /**
- * A loop as an `Effect` on colours by hex, each touched at the share
+ * A loop as an `Effect` on colors by hex, each touched at the share
  * `share` gives it of the cell's strength in a frame drawing what `Drawn`
- * says; a colour it gives none, and one the terminal supplies, stays as it is.
+ * says; a color it gives none, and one the terminal supplies, stays as it is.
  */
 export declare function atShares(loop: Loop, share: (drawn: Drawn) => ReadonlyMap<string, number>): Effect;
 /**
@@ -154,38 +154,38 @@ export declare function requireZ(what: string, z: number): void;
 /**
  * Each effect's curve as it was signed off. Every loop's period is a prime
  * number of seconds, so no two loops come back into step within a sitting.
- * The periods are long on purpose: at one frame a second a loop's colour
+ * The periods are long on purpose: at one frame a second a loop's color
  * moves by no more than a just-noticeable step from one frame to the next.
  */
 export declare const EFFECT_CURVES: {
     readonly shimmer: {
         readonly seconds: 109;
-        readonly ease: import("../core/easing.js").Ease;
+        readonly ease: import("../core/easing.js").Easing;
         readonly swing: 0.9;
     };
     readonly pulse: {
         readonly seconds: 43;
-        readonly ease: import("../core/easing.js").Ease;
+        readonly ease: import("../core/easing.js").Easing;
         readonly swing: 0.85;
     };
     readonly sparkle: {
         readonly seconds: 139;
-        readonly ease: import("../core/easing.js").Ease;
+        readonly ease: import("../core/easing.js").Easing;
         readonly swing: 0.95;
     };
     readonly wheel: {
         readonly seconds: 907;
-        readonly ease: import("../core/easing.js").Ease;
+        readonly ease: import("../core/easing.js").Easing;
         readonly swing: 1;
     };
     readonly fade: {
         readonly seconds: 20;
-        readonly ease: import("../core/easing.js").Ease;
+        readonly ease: import("../core/easing.js").Easing;
         readonly swing: 1;
     };
     readonly dissolve: {
         readonly seconds: 30;
-        readonly ease: import("../core/easing.js").Ease;
+        readonly ease: import("../core/easing.js").Easing;
         readonly swing: 1;
     };
 };
@@ -197,19 +197,19 @@ export declare const EFFECT_LIGHTS: {
 /** How far a shimmer's light reaches either side of its centre, in columns, as signed off. */
 export declare const SHIMMER_WIDTH = 24;
 /**
- * A colour under `glow`: the one way every light here falls. It moves `w` of
- * the way toward the light's colour, and never below its own lightness —
- * light can warm a colour and lift it, never darken it. A colour already
+ * A color under `glow`: the one way every light here falls. It moves `w` of
+ * the way toward the light's color, and never below its own lightness —
+ * light can warm a color and lift it, never darken it. A color already
  * lighter than the light only warms, and white, which has no warmer shade at
  * its lightness, stays white.
  */
-export declare function light(glow: ColorRgba): Touch;
+export declare function light(glow: ColorRgba): ColorModifier;
 /**
- * Pulse, as a gentle glow on one element of a screen: the colours handed to
+ * Pulse, as a gentle glow on one element of a screen: the colors handed to
  * it, an element's own, warm into `light` and settle back, over and over, the
  * way an indicator breathes while something is waiting. Swing: how far into
  * the light it goes at the top of a beat, 0–1. The element glows as one —
- * every cell it is drawn in at once — and the colours not handed to it, the
+ * every cell it is drawn in at once — and the colors not handed to it, the
  * rest of the screen, stay as they are, so what pulses is what was chosen.
  * Each element keeps a time of its own, a little quicker or slower than
  * another's by `z`, and no beat is quite the last: the rhythm wanders ahead
@@ -266,11 +266,11 @@ export type Visibility = (t: number, drawn: Drawn) => (cell: EffectCell) => numb
  * A cell mixed toward the ground of the terminal the frame is drawn on
  * (`Drawn.terminal`) by how hidden it is: its fill toward the ground, and its ink
  * toward that fill, so an element with fills of its own — a powerline strip —
- * arrives and leaves whole, fill and words together, never as bare coloured
+ * arrives and leaves whole, fill and words together, never as bare colored
  * blocks. Invisible is ink and fill equal to the ground. `swing` scales the
  * hiding — 1 reaches fully invisible. A cell wholly shown is returned as it was.
  */
-export declare function veiled(visibility: Visibility, swing: number): Effect;
+export declare function mask(visibility: Visibility, swing: number): Effect;
 /**
  * An effect that runs once: a fade-in or a dissolve-out over its curve's
  * `seconds` from `t = 0`, its own clock as every effect's is — the caller
@@ -281,8 +281,8 @@ export declare function veiled(visibility: Visibility, swing: number): Effect;
  * `schedule` is when its frame next changes on that clock, whatever the
  * element draws: what a caller drawing the transition inside an animation —
  * a lifecycle — says its frame does, since the frame it hands over carries
- * no word of its own (`stampFrame`, `../core/animation.ts`). Until done it changes
- * every frame, or on each hold of a beat (`onBeat`), and from then never.
+ * no word of its own (`stampValidityFrame`, `../core/animation.ts`). Until done it changes
+ * every frame, or on each hold of a beat (`sampleAndHold`), and from then never.
  * [LAW:one-source-of-truth] `done` is that schedule read as a fact — done
  * from the first moment it never changes again — so no transition carries
  * two answers to when it is over.
@@ -296,20 +296,20 @@ export declare class Transition<E = Effect> {
 /**
  * `effect` run once over `seconds` as a `Transition`: what it draws until it
  * is done, then held. [LAW:single-enforcer] The one rule for when a
- * transition is done and what it answers after, for a colour effect and a
+ * transition is done and what it answers after, for a color effect and a
  * glyph effect (`./glyph-effects.ts`) alike.
  */
 export declare function transition<D, F>(seconds: number, effect: (drawn: D) => Animation<F>): Transition<(drawn: D) => Animation<F>>;
 /**
  * `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
+ * progress began (`StepSequence.validFrom`), 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 (`Animation.onBeat`): an effect that moves
+ * sampled effect has moved by (`Animation.sampleAndHold`): an effect that moves
  * every frame turns the beat at the end of this hold, and one that is done
  * and says never leaves the beat saying never too.
  *
@@ -317,8 +317,8 @@ export declare function transition<D, F>(seconds: number, effect: (drawn: D) =>
  * beat arrives a hold at a time and is done at the first hold that starts
  * after it was: an element arriving through it wakes its host on the beats.
  */
-export declare function onBeat(effect: Effect, beat: Beat): Effect;
-export declare function onBeat<E extends (drawn: never) => Animation<unknown>>(transition: Transition<E>, beat: Beat): Transition<E>;
+export declare function sampleAndHold(effect: Effect, stepSequence: StepSequence): Effect;
+export declare function sampleAndHold<E extends (drawn: never) => Animation<unknown>>(transition: Transition<E>, stepSequence: StepSequence): Transition<E>;
 /**
  * Fade-in, as ink blooming in water: patches of the element surface first
  * and the rest follows outward from them, each cell rising smoothly over its
@@ -335,17 +335,17 @@ export declare function fadeIn(curve: Curve, z: number): Transition;
  */
 export declare function dissolveOut(curve: Curve, z: number): Transition;
 /**
- * Wheel, as the colour of daylight going round: every hue turning the whole
+ * WheelEvent, as the color of daylight going round: every hue turning the whole
  * way round once a period — far too slowly to be seen moving, so a glance
  * sees a steady palette and an hour's absence a different one — each
  * segment of the element at its own pace. Swing: how far the segments stray
  * from one another, 0–1, 1 being half a turn apart. A segment is a region
- * of adjacent cells of one colour of the element's own, carried as their
+ * of adjacent cells of one color of the element's own, carried as their
  * ground or, on the terminal's ground, as their ink (`segmentsOf`), and it
- * paces by where it sits, not by its colour: two
- * regions of one fill at two places turn apart, and each colour of the seam
- * a joiner drew between them turns with the region of that colour beside
- * it, so a powerline cap keeps the colour of the cell it caps. An ink that
+ * paces by where it sits, not by its color: two
+ * regions of one fill at two places turn apart, and each color of the seam
+ * a joiner drew between them turns with the region of that color beside
+ * it, so a powerline cap keeps the color of the cell it caps. An ink that
  * is no fill turns with the ground it sits on, so a cell's words and fill
  * turn together. A segment's stray is slow noise at its place, at
  * `STRAY_PERIODS` in time and `STRAY_SPREAD` across the element, so
@@ -354,28 +354,28 @@ export declare function dissolveOut(curve: Curve, z: number): Transition;
  * column moves its hue a little, and those it pushes along as little. Only the
  * stray reads the place: a place in the shared turn would jump a growing
  * run by `360·t·Δ/P`, without bound in `t`.
- * A colour keeps its luminance as it turns (`hueTurned`), so every pair of
- * words reads at the contrast it rested at; at 256 colours a turned colour
- * lands on a colour the depth writes, one that keeps every pair of words it
+ * A color keeps its luminance as it turns (`hueTurned`), so every pair of
+ * words reads at the contrast it rested at; at 256 colors a turned color
+ * lands on a color the depth writes, one that keeps every pair of words it
  * is drawn in at its floor (`floorOf`) — its resting contrast or WCAG AA,
  * whichever is lower — as `shares` keeps the light's (`turnedBounds`). The
- * turn only happens to the element's own colours (`Drawn.colors`), never the
- * terminal's. On a sixteen-colour terminal nothing turns (`stillWhereNothingMoves`).
+ * turn only happens to the element's own colors (`Drawn.colors`), never the
+ * terminal's. On a sixteen-color terminal nothing turns (`staticWhereUnchanged`).
  */
 export declare function wheel(curve: Curve, z: number): Effect;
 /**
  * Several effects on one element, as one effect: each layer is handed the look
  * the one before it left and the same cell, so later layers are on top, and each
  * recognises a cell by what the element drew (`EffectCell.pair`), never by the
- * colour it is handed. A hue a layer turned onto another of the element's
- * colours is not mistaken for it, and turns once. It changes when the soonest
+ * color it is handed. A hue a layer turned onto another of the element's
+ * colors is not mistaken for it, and turns once. It changes when the soonest
  * layer does, and with no layers it leaves every cell as drawn.
  *
  * Every word reads at its floor (`floorOf`), whatever the layers did and in
- * whatever order. Each loop proves that for colours as the element drew them,
- * and a colour another layer moved voids the proof: light lands at another
+ * whatever order. Each loop proves that for colors as the element drew them,
+ * and a color another layer moved voids the proof: light lands at another
  * luminance on a turned hue. So once the layers have moved a cell, its ground
- * lands where its inks can still read (`groundBounds`), a function of the colour
+ * lands where its inks can still read (`groundBounds`), a function of the color
  * alone so one fill stays one fill, and an ink that does not read on it slides
  * to the luminance that does, on the side of the ground it stands on while that
  * side has room. A layer that takes an ink across its ground crosses it here too:
@@ -385,7 +385,7 @@ export declare function wheel(curve: Curve, z: number): Effect;
  * it would be alone. A frame that takes a ground past its bounds is the one
  * exception, whatever its ink reads: a swap of ink and ground lands at the floor,
  * since a bound cannot ask what one cell's ink does without splitting a fill.
- * The floor outranks a colour being the terminal's: a terminal
+ * The floor outranks a color being the terminal's: a terminal
  * ink is moved here where a ground under it left it unreadable. The rule is the
  * same for one layer as for five: a veil (`veiled`, or a transition's `effect`)
  * stops at the floor here, so a transition goes in an `Effected` around this
@@ -398,23 +398,23 @@ export interface ColorStep {
     readonly seconds: number;
 }
 /**
- * A signal: every cell's ink stepping through `steps`' colours on a beat,
- * one colour a hold, looping, for the time it is handed — a gauge's
- * chevrons in bright changing colours. The ground is left as the cell draws
+ * A signal: every cell's ink stepping through `steps`' colors on a beat,
+ * one color a hold, looping, for the time it is handed — a gauge's
+ * chevrons in bright changing colors. The ground is left as the cell draws
  * it, and the words stay legible on it: each step's ink is written as the
- * colour nearest the step's (OKLab's ΔE) that the depth draws and that
+ * color nearest the step's (OKLab's ΔE) that the depth draws and that
  * reads on the cell's ground, as `Effected` writes it, at the cell's floor
  * (`floorOf`) — its resting contrast or `LEGIBLE`, whichever is lower, the
  * floor every loop here keeps. In truecolor that is the step itself, or its
  * hue and chroma at the lightness nearest it that reaches the floor
- * (`ensureContrast`, the one slide a template's `readableOn` makes too);
- * below truecolor, the nearest of the colours the depth has an index for, so on a
- * sixteen-colour terminal it steps from slot to slot, the one effect here
- * that does (`stillWhereNothingMoves`). A cell whose ground no offered colour reads
+ * (`ensureContrast`, the one slide a template's `ensureContrast` makes too);
+ * below truecolor, the nearest of the colors the depth has an index for, so on a
+ * sixteen-color terminal it steps from slot to slot, the one effect here
+ * that does (`staticWhereUnchanged`). A cell whose ground no offered color reads
  * on keeps the ink it rested in.
  *
  * The search is settled once for each ground and step — below truecolor,
- * which colours read on a ground once for that ground — so a frame
+ * which colors read on a ground once for that ground — so a frame
  * inside a step redoes none, and nor does a later pass of the beat: at sixty
  * frames a second a one-second step is sixty identical frames, and the
  * frame changes when the beat does: the signal is the beat mapped to inks.
@@ -476,7 +476,7 @@ export type TransitionName = "fade" | "dissolve";
  * Every effect in the catalogue by its name in `EFFECT_CURVES`, each made the
  * one way: for an element, at its signed-off curve unless handed another,
  * with the light and the width it was signed off with. A loop comes lit on
- * the element's own colours (`onColors`); a transition comes as itself, to
+ * the element's own colors (`onColors`); a transition comes as itself, to
  * be told when it is done. [LAW:types-are-the-program] Keyed by the two
  * name types, which `EFFECT_CURVES` is held to as well: a curve signed off
  * does not compile until it is named a loop or a transition, and then not