@promptctl/rich-js 0.20.0 → 0.22.0

package/dist/renderables/effects.d.ts

@@ -3,7 +3,8 @@
  * long as they are drawn, and fade-in and dissolve-out, which run once and
  * are done. 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.
+ * (`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
@@ -36,37 +37,35 @@
  * [LAW:no-ambient-temporal-coupling] No curve reads a clock; `t` is the
  * effect's argument, so the frame owner decides when to sample.
  *
- * Every import below names something the package exports, but for `noise`,
- * which the docs' effects playground page supplies itself: each of its
+ * Every import below names something the package exports, but for `noise`
+ * and `Memo`, which the docs' effects playground page supplies itself: each of its
  * cards runs this file's own declarations as the program a visitor edits
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
 import { ColorRgba } from "../core/color.js";
 import { type Ease } from "../core/easing.js";
-import type { CellColors, Effect, EffectCell } from "./effect.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 on a cell at a moment, in [0, 1]; `onColors` holds a field outside it to it. */
-export type Field = (cell: EffectCell, t: number) => number;
+/**
+ * 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.
+ */
+export type Field = (t: number) => (cell: EffectCell) => number;
 /** A looping effect: what it does to a colour, and where and when, how strongly. */
 export interface Loop {
     readonly touch: Touch;
     readonly field: Field;
 }
-/**
- * A cell's ink and ground as the screen shows them, and which of the two are
- * the terminal's: what an `Effect` is handed for that cell.
- */
-export interface Pair extends CellColors {
-    readonly terminal: EffectCell["terminal"];
-}
 /**
  * How much of `touch` each of `colors` (hex) can take: the largest share in
- * [0, 1] at which every pair in `pairs` that shows it, touched at the same
+ * [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. A colour in a pair but not in `colors` takes none, and so does one
+ * lower, in the colours `Effected` writes it in at `drawn`'s depth and theme.
+ * A colour 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 throws.
+ * no pair writes has nothing to be measured against, and takes it all.
  *
  * Colours are settled lightest first, each against every partner: one
  * already settled at its share, one not yet settled as it is. So the lighter
@@ -75,16 +74,30 @@ export interface Pair extends CellColors {
  * the fill room to glow — and a darker colour left as it is always holds,
  * because its lighter partner was settled against exactly that.
  */
-export declare function shares(pairs: readonly Pair[], colors: ReadonlySet<string>, touch: Touch): Map<string, number>;
+export declare function shares({ pairs, depth, theme }: Drawn, colors: ReadonlySet<string>, touch: Touch): Map<string, number>;
+/**
+ * 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
+ * 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
+ * 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
+ * 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 loop as an `Effect` on a subject's own colours, by hex, wherever a cell
- * shows them, each touched at its share of the cell's strength. 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 not the subject's, whatever
- * its hex, and takes no share.
+ * A loop as an `Effect` on colours 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.
  */
-export declare function onColors(share: ReadonlyMap<string, number>, loop: Loop): Effect;
+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. */
@@ -192,46 +205,46 @@ export declare function shimmer(curve: Curve, span: number, width: number, glow:
  */
 export declare function sparkle(curve: Curve, span: number, glow: ColorRgba, z: number): Loop;
 /**
- * How much of a 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. One
- * outside [0, 1] is held to it.
+ * 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.
  */
-export type Visibility = (cell: EffectCell, t: number) => number;
+export type Visibility = (t: number) => (cell: EffectCell) => number;
 /**
- * A cell mixed toward the terminal's `ground` 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 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.
+ * 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
+ * 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
+ * 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, ground: ColorRgba): Effect;
+export declare function veiled(visibility: Visibility, swing: number): Effect;
 /**
- * An effect that runs once: a fade-in or a dissolve-out from its start time
- * over its curve's `seconds`. `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.
+ * 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
+ * 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.
  */
 export interface Transition {
     readonly effect: Effect;
     done(t: number): boolean;
 }
 /**
- * Fade-in starting at `start`, as ink blooming in water: patches of the
- * element surface first and the rest follows outward from them, each cell
- * rising smoothly over its own part of the duration. Whole at
- * `start + seconds`.
+ * 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
+ * own part of the duration. Whole at `seconds`.
  */
-export declare function fadeIn(curve: Curve, start: number, z: number, ground: ColorRgba): Transition;
+export declare function fadeIn(curve: Curve, z: number): Transition;
 /**
- * Dissolve-out starting at `start`, as mist lifting: the element thins in
- * drifting patches, each cell fading smoothly over its own part of the
- * duration, until nothing is left at `start + seconds`. Mist does not lift
+ * Dissolve-out, as mist lifting: the element thins in drifting patches, each
+ * cell fading smoothly over its own part of the duration, until nothing is
+ * left at `seconds`. Mist does not lift
  * in one breath: towards the end, patches of what is left — the later a cell
  * goes, the likelier — rise back part way, as the last of it eddies, before
  * they thin away for good.
  */
-export declare function dissolveOut(curve: Curve, start: number, z: number, ground: ColorRgba): Transition;
+export declare function dissolveOut(curve: Curve, z: number): Transition;
 /**
  * Wheel, as the colour of daylight going round: every hue turning the whole
  * way round once a period — far too slowly to be seen moving, so a glance
@@ -247,6 +260,36 @@ export declare function dissolveOut(curve: Curve, start: number, z: number, grou
  * 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 `colors`, the element's own, never the terminal's.
+ * only happens to the element's own colours (`Drawn.colors`), never the
+ * terminal's.
+ */
+export declare function wheel(curve: Curve, z: number): 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.
  */
-export declare function wheel(curve: Curve, colors: ReadonlySet<string>, fills: ReadonlySet<string>, z: number): Effect;
+export interface EffectTarget {
+    readonly span: number;
+    readonly z: number;
+}
+/** The names of the effects that loop. */
+export type LoopName = "shimmer" | "pulse" | "sparkle" | "wheel";
+/** The names of the effects that run once. */
+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
+ * 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
+ * until it has an entry here making one. A picker walking a section's names
+ * offers an effect added here with no change of its own.
+ */
+export declare const EFFECT_CATALOGUE: {
+    readonly loops: Readonly<Record<LoopName, (element: EffectTarget, curve?: Curve) => Effect>>;
+    readonly transitions: Readonly<Record<TransitionName, (element: EffectTarget, curve?: Curve) => Transition>>;
+};