@promptctl/rich-js 0.19.0 → 0.20.0

package/dist/renderables/effect.d.ts

@@ -22,8 +22,9 @@
  *   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 as it was, so the
- *   identity effect is byte-identical. Neighbouring cells given equal colours
- *   stay one segment: a segment is cut only where the colours change.
+ *   identity effect is byte-identical. 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.
  * - 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
@@ -45,14 +46,25 @@ export interface CellColors {
     readonly bg: ColorRgba;
 }
 /**
- * Where a cell is in the output of the renderable an effect wraps, and its
- * seed: a number in [0, 1) that is the same for that cell on every frame, for
- * an effect that varies cell by cell (a per-cell offset in time, a sparkle).
+ * 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
+ * effect that varies cell by cell (a per-cell offset in time, a sparkle) —
+ * and which of its on-screen colours are the terminal's.
  */
 export interface EffectCell {
     readonly row: number;
     readonly col: number;
     readonly seed: number;
+    /**
+     * Whether the glyph's colour and the colour behind it, as the screen shows
+     * them, are the terminal's own: a slot the element's style leaves unset or
+     * sets to `default`. Such a colour is resolved through the theme, so its
+     * hex can equal one the element wrote; this is what tells them apart.
+     */
+    readonly terminal: {
+        readonly fg: boolean;
+        readonly bg: boolean;
+    };
 }
 /** A cell's colours at time `t`, in seconds. Return `colors` to leave it be. */
 export type Effect = (colors: CellColors, cell: EffectCell, t: number) => CellColors;
@@ -84,13 +96,16 @@ export declare class Effected implements Renderable, Measurable {
         maximum: number;
     };
     /**
-     * The style that draws a run's slot colours `to` where the segment drew
+     * The specs that draw a cell's slot colours `to` where the segment drew
      * `from` with `wire`: a slot the effect left alone keeps its written spec,
      * and a moved one is laid on what is beneath it — the ground on
      * `SURFACE_BLACK`, the glyph on that ground, as the writer lays any
      * translucent colour (`Style.drawnColors`) — then drawn in the colour nearest it at `depth`
-     * that the terminal shows (`ColorSpec.matchOn`), so a colour moved a little
-     * off a theme slot or the default colour is still drawn as that one.
+     * that the terminal shows (`ColorSpec.matchOn`). A move the depth cannot
+     * show is no move: where the written spec is as near the moved colour as
+     * that match, the slot keeps it, so below truecolor a colour moved a little
+     * off any colour it can write — a theme slot, the default colour, the cube —
+     * is still drawn as that one.
      */
     private respec;
     /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */

package/dist/renderables/effect.js

@@ -22,8 +22,9 @@
  *   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 as it was, so the
- *   identity effect is byte-identical. Neighbouring cells given equal colours
- *   stay one segment: a segment is cut only where the colours change.
+ *   identity effect is byte-identical. 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.
  * - 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
@@ -33,7 +34,7 @@
  * what the child drew, so a sweep crosses the element, not the screen.
  */
 import { cellLen, graphemes } from "../core/cells.js";
-import { ColorDepth, ColorSpec, SURFACE_BLACK } from "../core/color.js";
+import { ColorDepth, ColorSpec, SURFACE_BLACK, rgbDistance } from "../core/color.js";
 import { fnv1a } from "../core/fnv1a.js";
 import { Measurement } from "../core/measure.js";
 import { Segment } from "../core/segment.js";
@@ -78,40 +79,44 @@ export class Effected {
             const wire = base.drawnColors(options.colorSystem ?? undefined);
             const ink = (wire.color ?? DEFAULT).getTruecolor(this.theme, true);
             const paper = (wire.bgcolor ?? DEFAULT).getTruecolor(this.theme, false);
-            const from = onScreen({ fg: ink, bg: paper }, base);
-            // Each grapheme's colours, merged into runs of equal colours as they
-            // come; `undefined` is a run left as the segment drew it.
+            const slots = { fg: ink, bg: paper };
+            const from = onScreen(slots, base);
+            const terminal = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, base);
+            // [LAW:one-source-of-truth] A run is cells the wire writes alike: each
+            // cell is drawn at the output depth first and merged on the colours that
+            // writes, so two truecolors landing on one index stay one run. A cell
+            // the effect gave its neighbour's colours is drawn as that neighbour was.
             const runs = [];
             for (const glyph of graphemes(segment.text)) {
-                let colors;
+                let colors = slots;
                 if (glyph === "\n") {
                     row++;
                     col = 0;
                 }
                 else {
-                    const to = this.effect(from, { row, col, seed: this.seed(row, col) }, this.t);
-                    colors = sameColors(to, from) ? undefined : to;
+                    // Back from the screen to the style's slots: the same swap undoes itself.
+                    colors = onScreen(this.effect(from, { row, col, seed: this.seed(row, col), terminal }, this.t), base);
                     col += cellLen(glyph);
                 }
                 const last = runs[runs.length - 1];
-                if (last !== undefined && sameRun(last.colors, colors)) {
+                const drawn = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
+                if (last !== undefined && writesAlike(last.drawn, drawn)) {
                     last.text += glyph;
                     last.cells += cellLen(glyph);
+                    last.colors = colors;
                 }
                 else {
-                    runs.push({ text: glyph, cells: cellLen(glyph), colors });
+                    runs.push({ text: glyph, cells: cellLen(glyph), colors, drawn });
                 }
             }
-            if (runs.every((run) => run.colors === undefined)) {
+            if (runs.every((run) => writesAlike(run.drawn, wire))) {
                 yield segment;
                 continue;
             }
             let offset = 0;
             for (const run of runs) {
                 const shifted = base.shiftedBy(offset);
-                // Back from the screen to the style's slots: the same swap undoes itself.
-                const slots = run.colors === undefined ? undefined : onScreen(run.colors, base);
-                const style = slots === undefined ? shifted : shifted.add(this.respec(wire, { fg: ink, bg: paper }, slots, depth));
+                const style = writesAlike(run.drawn, wire) ? shifted : shifted.add(Style.fromColor(run.drawn.color, run.drawn.bgcolor));
                 yield new Segment(run.text, style);
                 offset += run.cells;
             }
@@ -121,20 +126,26 @@ export class Effected {
         return Measurement.get(options, this.renderable);
     }
     /**
-     * The style that draws a run's slot colours `to` where the segment drew
+     * The specs that draw a cell's slot colours `to` where the segment drew
      * `from` with `wire`: a slot the effect left alone keeps its written spec,
      * and a moved one is laid on what is beneath it — the ground on
      * `SURFACE_BLACK`, the glyph on that ground, as the writer lays any
      * translucent colour (`Style.drawnColors`) — then drawn in the colour nearest it at `depth`
-     * that the terminal shows (`ColorSpec.matchOn`), so a colour moved a little
-     * off a theme slot or the default colour is still drawn as that one.
+     * that the terminal shows (`ColorSpec.matchOn`). A move the depth cannot
+     * show is no move: where the written spec is as near the moved colour as
+     * that match, the slot keeps it, so below truecolor a colour moved a little
+     * off any colour it can write — a theme slot, the default colour, the cube —
+     * is still drawn as that one.
      */
     respec(wire, from, to, depth) {
         // [LAW:one-source-of-truth] The writer's surface, so one translucent colour draws one way in a frame.
         const ground = to.bg.compositeOver(SURFACE_BLACK);
         const glyph = to.fg.compositeOver(ground);
-        const drawn = (spec, was, now, foreground) => sameColor(was, now) ? spec : ColorSpec.matchOn(now, depth, this.theme, foreground);
-        return Style.fromColor(drawn(wire.color, from.fg, glyph, true), drawn(wire.bgcolor, from.bg, ground, false));
+        const drawn = (spec, was, now, foreground) => {
+            const match = ColorSpec.matchOn(now, depth, this.theme, foreground);
+            return rgbDistance(was, now) <= rgbDistance(match.getTruecolor(this.theme, foreground), now) ? spec : match;
+        };
+        return { color: drawn(wire.color, from.fg, glyph, true), bgcolor: drawn(wire.bgcolor, from.bg, ground, false) };
     }
     /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
     seed(row, col) {
@@ -146,15 +157,26 @@ const DEFAULT = ColorSpec.default();
  * A style's colour slots as the screen shows them, or the reverse: `reverse`
  * swaps glyph and ground, and swapping twice is where you started.
  */
-function onScreen(colors, style) {
-    return style.reverse === true ? { fg: colors.bg, bg: colors.fg } : colors;
+function onScreen(slots, style) {
+    return style.reverse === true ? { fg: slots.bg, bg: slots.fg } : slots;
 }
-function sameColor(a, b) {
-    return a.red === b.red && a.green === b.green && a.blue === b.blue && a.alpha === b.alpha;
+/**
+ * Whether two cells' colours are written alike. A slot with no colour is not
+ * the default colour: it writes nothing, so a style a container lays beneath
+ * (`Segment.applyStyle`) still shows through it, where `39`/`49` would not.
+ */
+function writesAlike(a, b) {
+    return slotWritesAlike(a.color, b.color, true) && slotWritesAlike(a.bgcolor, b.bgcolor, false);
+}
+function slotWritesAlike(a, b, foreground) {
+    return a === b || written(a, foreground) === written(b, foreground);
+}
+function written(spec, foreground) {
+    return spec?.getAnsiCodes(foreground).join(";") ?? "";
 }
 function sameColors(a, b) {
     return sameColor(a.fg, b.fg) && sameColor(a.bg, b.bg);
 }
-function sameRun(a, b) {
-    return a === undefined || b === undefined ? a === b : sameColors(a, b);
+function sameColor(a, b) {
+    return a.red === b.red && a.green === b.green && a.blue === b.blue && a.alpha === b.alpha;
 }

package/dist/renderables/effects.d.ts

@@ -0,0 +1,252 @@
+/**
+ * The effect catalogue: shimmer, pulse, sparkle and wheel, which loop for as
+ * 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.
+ *
+ * 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
+ * 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:
+ *
+ * - 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
+ *   moves a little and at thirty it glides.
+ * - Nothing repeats exactly. Rhythms are perturbed by slow noise, and each
+ *   breath, firefly's flash and pass of light is an event of its own, with
+ *   its own strength and moment, the way no breath or gust is the last one
+ *   again. A weaker event is a shorter one, so its strength costs nothing
+ *   in smoothness.
+ * - Neighbours move together. Variation is spatially coherent — patches,
+ *   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
+ *   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`
+ * 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.
+ *
+ * [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
+ * 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";
+/** 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;
+/** 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
+ * 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
+ * the terminal supplies, whatever its hex, as in `onColors`. One of `colors`
+ * no pair writes has nothing to be measured against, and throws.
+ *
+ * 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
+ * colour 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,
+ * because its lighter partner was settled against exactly that.
+ */
+export declare function shares(pairs: readonly Pair[], colors: ReadonlySet<string>, touch: Touch): Map<string, number>;
+/**
+ * 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.
+ */
+export declare function onColors(share: ReadonlyMap<string, number>, loop: Loop): 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 far the move goes at full intensity, in [0, 1]; what 1 means is the effect's. */
+    readonly swing: number;
+}
+/**
+ * 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
+ * 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: Ease;
+        readonly swing: 0.9;
+    };
+    readonly pulse: {
+        readonly seconds: 43;
+        readonly ease: Ease;
+        readonly swing: 0.85;
+    };
+    readonly sparkle: {
+        readonly seconds: 139;
+        readonly ease: Ease;
+        readonly swing: 0.95;
+    };
+    readonly wheel: {
+        readonly seconds: 907;
+        readonly ease: Ease;
+        readonly swing: 1;
+    };
+    readonly fade: {
+        readonly seconds: 20;
+        readonly ease: Ease;
+        readonly swing: 1;
+    };
+    readonly dissolve: {
+        readonly seconds: 30;
+        readonly ease: Ease;
+        readonly swing: 1;
+    };
+};
+/** The lights the loops were signed off casting, warm as sunlight and fireflies are. */
+export declare const EFFECT_LIGHTS: {
+    readonly sun: ColorRgba;
+    readonly firefly: ColorRgba;
+};
+/** 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
+ * 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;
+/**
+ * Pulse, as a gentle glow on one element of a screen: the colours 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
+ * 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
+ * and behind its metronome and each beat goes a little deeper or shallower
+ * than the one before. A beat starts and ends in rest, so `t = 0` draws the
+ * element untouched.
+ */
+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
+ * 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
+ * for a while between, and the light is never gone for long. Each crosses at its own unhurried pace, drifting a little ahead
+ * and behind as it goes. Inside a band the light is a faint glow broken
+ * into a glitter path — bright filaments where two ripples cross — carried
+ * 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;
+/**
+ * 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,
+ * 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
+ * elsewhere. Each keeps its own irregular time, now and then letting a turn
+ * pass dark, so most moments a few are lit, at different brightnesses. Its
+ * light is a soft halo several cells wide, brightest where it is, so as it
+ * drifts the glow slides between cells rather than hopping. `seconds` is a firefly's
+ * 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;
+/**
+ * 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.
+ */
+export type Visibility = (cell: EffectCell, t: number) => 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.
+ */
+export declare function veiled(visibility: Visibility, swing: number, ground: ColorRgba): 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.
+ */
+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`.
+ */
+export declare function fadeIn(curve: Curve, start: number, z: number, ground: ColorRgba): 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
+ * 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;
+/**
+ * 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
+ * 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 fill of
+ * the element's own — one of `fills`, the colours it draws as a ground — and
+ * it turns at its own pace wherever it is drawn: as the ground of its cells,
+ * and as the ink of the seam glyph pointing out of it into the next, so a
+ * powerline cap keeps the colour 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; 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 `colors`, the element's own, never the terminal's.
+ */
+export declare function wheel(curve: Curve, colors: ReadonlySet<string>, fills: ReadonlySet<string>, z: number): Effect;