@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/renderables/effects.d.ts

@@ -10,7 +10,11 @@
  * a slow glow, sunlight moving on water, the colours 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.
- * What makes those motions familiar is what every curve here keeps:
+ * 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
+ * that something is at its limit, and jumps from slot to slot where the
+ * loops hold still. What makes the loops' motions familiar is what every
+ * curve of theirs keeps:
  *
  * - Nothing jumps. Every curve is continuous in time, built from smooth
  *   noise (`core/noise.ts`) and smooth waveforms, so at one frame a second a cell
@@ -43,16 +47,17 @@
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
 import { ColorRgba } from "../core/color.js";
-import { type Ease } from "../core/easing.js";
+import { type Timing } from "../core/easing.js";
 import { 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;
 /**
- * How strongly a loop acts at a moment `t` on each cell, in [0, 1]; `onColors`
- * holds a field outside it to it. Staged as `Effect` is: what holds for the
- * whole moment is worked out once, then every cell is asked.
+ * 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.
+ * Staged as `Effect` is: what holds for the whole moment is worked out once,
+ * then every cell is asked.
  */
-export type Field = (t: number) => (cell: EffectCell) => number;
+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. */
 export interface Loop {
     readonly touch: Touch;
@@ -79,9 +84,10 @@ export declare function shares({ pairs, depth, theme }: Drawn, colors: ReadonlyS
  * A loop as an `Effect` on the element's own colours, 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 — below
- * truecolor a touched colour lands on a colour the slot can write, and the
- * contrast it spends is that colour's. `colors` are the ones lit, by default every colour the element
+ * (`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 (`stillOnSlots`). `colors` are the ones lit, by default every colour 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 (`EffectCell.terminal`) is
@@ -98,12 +104,14 @@ export declare function onColors(loop: Loop, colors?: ReadonlySet<string>): Effe
  * says; a colour 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;
-/** How the curves below are tuned: one period (or duration), ease and swing. */
-export interface Curve {
-    /** Seconds: a looping effect's period, a transition's duration. */
-    readonly seconds: number;
-    /** Intensity in [0, 1] to the fraction of `swing` applied. One that overshoots, as a CSS `cubic-bezier` may, saturates: an effect never acts past its swing. */
-    readonly ease: Ease;
+/**
+ * How the curves below are tuned: a `Timing` — seconds, a looping effect's
+ * period or a transition's duration, and an ease, intensity in [0, 1] to
+ * the fraction of `swing` applied; one that overshoots, as a CSS
+ * `cubic-bezier` may, saturates, since an effect never acts past its swing —
+ * and the swing itself.
+ */
+export interface Curve extends Timing {
     /** How far the move goes at full intensity, in [0, 1]; what 1 means is the effect's. */
     readonly swing: number;
 }
@@ -116,32 +124,32 @@ export interface Curve {
 export declare const EFFECT_CURVES: {
     readonly shimmer: {
         readonly seconds: 109;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 0.9;
     };
     readonly pulse: {
         readonly seconds: 43;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 0.85;
     };
     readonly sparkle: {
         readonly seconds: 139;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 0.95;
     };
     readonly wheel: {
         readonly seconds: 907;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 1;
     };
     readonly fade: {
         readonly seconds: 20;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 1;
     };
     readonly dissolve: {
         readonly seconds: 30;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 1;
     };
 };
@@ -177,8 +185,9 @@ export declare function pulse(curve: Curve, glow: ColorRgba, z: number): Loop;
 /**
  * Shimmer, as sunlight moving across water. Swing: how far into `light` the
  * brightest glint goes, 0–1. A soft band of light, `width` columns either
- * side of its centre, crosses columns 0 to `span`, entering and leaving
- * fully off the row, `STRIDE` columns in about three quarters of a period. Its passes
+ * side of its centre, crosses the element from the first column a frame
+ * lists (`Drawn.cells`) to the last, entering and leaving fully off it,
+ * `STRIDE` columns in about three quarters of a period. Its passes
  * come the way light comes and goes on water as clouds move: while the sun
  * is out they are bright and follow close on one another, one sometimes
  * catching the last; under cloud they thin to faint ones with the row still
@@ -188,11 +197,17 @@ export declare function pulse(curve: Curve, glow: ColorRgba, z: number): Loop;
  * on a slow current and re-forming as they go, so the glints dance while
  * the band glides. Before the first pass enters, the row is untouched.
  */
-export declare function shimmer(curve: Curve, span: number, width: number, glow: ColorRgba, z: number): Loop;
+export declare function shimmer(curve: Curve, width: number, glow: ColorRgba, z: number): Loop;
 /**
  * Sparkle, as fireflies. Swing: how far into the firefly's `light` a glow
- * goes at its brightest, 0–1. About one firefly to every eight columns of
- * `span`, each keeping near a home of its own. A firefly flashes — kindles,
+ * goes at its brightest, 0–1. Fireflies keep to a lattice laid from the
+ * element's first column and top row as a frame lists its cells
+ * (`Drawn.cells`): one every `PER` columns along a row of the lattice, a row
+ * of the lattice every `ROWS` rows, each firefly near a home of its own.
+ * The lattice does not hang on how wide or deep the element is, so one that
+ * grows or shrinks at its last column or bottom row moves no firefly; one
+ * whose first column moves, as centred words that change length do, carries
+ * its fireflies with it. A firefly flashes — kindles,
  * drifts a few cells glowing, slowing as it fades — then flies on in the
  * dark and flashes again somewhere a few cells off, the way fireflies at
  * dusk are seen: a short lit stroke, then gone, each time a little
@@ -203,13 +218,14 @@ export declare function shimmer(curve: Curve, span: number, width: number, glow:
  * turn: its brightest flash, rise and fall, takes `FLASH` of it, and a
  * dimmer one less.
  */
-export declare function sparkle(curve: Curve, span: number, glow: ColorRgba, z: number): Loop;
+export declare function sparkle(curve: Curve, glow: ColorRgba, z: number): Loop;
 /**
- * How much of each cell shows at `t`: 1 is the cell as drawn, 0 is the cell
- * gone to the terminal's ground. Read per cell, so cells can arrive or leave
- * apart, and staged as `Field` is. One outside [0, 1] is held to it.
+ * How much of each cell shows at `t` in a frame drawing what `Drawn` says: 1
+ * is the cell as drawn, 0 is the cell gone to the terminal's ground. Read per
+ * cell, so cells can arrive or leave apart, and staged as `Effect` is. One
+ * outside [0, 1] is held to it.
  */
-export type Visibility = (t: number) => (cell: EffectCell) => number;
+export type Visibility = (t: number, drawn: Drawn) => (cell: EffectCell) => number;
 /**
  * A cell mixed toward the ground of the terminal the frame is drawn on
  * (`Drawn.theme`) by how hidden it is: its fill toward the ground, and its ink
@@ -225,6 +241,8 @@ export declare function veiled(visibility: Visibility, swing: number): Effect;
  * draws it at the time since it began. `done(t)` is true from the moment
  * every cell has arrived or gone, so the caller knows when to stop drawing an
  * element that is leaving, or to drop the effect from one that has arrived.
+ * Until then the effect's frame changes every frame, and from then never:
+ * its `nextChange` is `done` read as a time. [LAW:one-source-of-truth]
  */
 export interface Transition {
     readonly effect: Effect;
@@ -259,19 +277,50 @@ export declare function dissolveOut(curve: Curve, z: number): Transition;
  * together; on the terminal's ground, a run of text's ink is a segment of
  * its own. A segment's stray is slow noise of its own, at `STRAY_PERIODS`,
  * so no two keep step, and the row never shows one spread of hues twice.
- * Lightness and chroma are kept, so the words read as they did; the turn
- * only happens to the element's own colours (`Drawn.colors`), never the
- * terminal's.
+ * 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
+ * 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 (`stillOnSlots`).
  */
 export declare function wheel(curve: Curve, z: number): Effect;
+/** One step of a signal: the ink it draws, and how long it is held, in seconds. */
+export interface ColorStep {
+    readonly color: ColorRgba;
+    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
+ * 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
+ * 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 (`stillOnSlots`). A cell whose ground no offered colour reads
+ * on keeps the ink it rested in.
+ *
+ * The search is settled once for each ink, ground and step, 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.
+ * [LAW:no-ambient-temporal-coupling] The beat is `core/easing.ts`'s, and
+ * nothing here reads a clock.
+ */
+export declare function steppedInk(steps: readonly ColorStep[]): Effect;
 /**
- * What a catalogue effect is made for: the element it is drawn on, as wide as
- * `span` columns — how far a shimmer crosses, how many fireflies keep to it —
- * and at `z` in the noise, so two elements under one effect do not move in
- * lockstep.
+ * What a catalogue effect is made for: the element it is drawn on, at `z` in
+ * the noise, so two elements under one effect do not move in lockstep. How
+ * wide the element is, the effect reads off each frame (`Drawn.cells`).
  */
 export interface EffectTarget {
-    readonly span: number;
     readonly z: number;
 }
 /** The names of the effects that loop. */