@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/renderables/effect.js

@@ -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,22 +46,25 @@
  *   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 { drawnBy, shiftAnchor } from "../core/anchor.js";
-import { Animation } from "../core/animation.js";
+import { Animation, frameTimeOf, holdOf, shownAt, stampFrame } from "../core/animation.js";
 import { cellLen, graphemes } from "../core/cells.js";
 import { ColorDepth, ColorSpec, SURFACE_BLACK } from "../core/color.js";
 import { fnv1a } from "../core/fnv1a.js";
@@ -59,8 +72,18 @@ import { Measurement } from "../core/measure.js";
 import { render } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 import { JOIN, colorsOwnedBy } from "../core/strip.js";
-import { Style } from "../core/style.js";
-export class Effected {
+import { ATTRIBUTE_NAMES, Style } from "../core/style.js";
+import { finiteTime } from "../core/easing.js";
+/** What drew nothing the effect can change: held forever, as far as the effect says. */
+const UNMOVED = { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY };
+/**
+ * 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 class Recolored {
     renderable;
     effect;
     t;
@@ -69,25 +92,20 @@ export class Effected {
     constructor(renderable, effect, options) {
         this.renderable = renderable;
         this.effect = effect;
-        if (!Number.isFinite(options.t)) {
-            throw new RangeError(`Effected needs a finite t, got ${options.t}`);
-        }
-        this.t = options.t;
+        this.t = finiteTime("Effected", options.t);
         this.key = options.key;
         this.theme = options.theme;
     }
     render(options) {
+        return this.moved(options).segments;
+    }
+    /** The frame the effect draws at `t`, and the hold it says that is in. */
+    moved(options) {
         const segments = render(this.renderable, options);
         // With no colour output nothing the effect does is written, so the child
         // is what is shown, and it changes when the child says it does.
         if (options.colorSystem === null)
-            return segments;
-        return this._moved(segments, options);
-    }
-    *contents() {
-        yield this.renderable;
-    }
-    *_moved(segments, options) {
+            return { segments, hold: UNMOVED };
         // No depth named is no downgrade, as `drawnColors` reads it.
         const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
         // [LAW:one-source-of-truth] The frame is measured before any cell is
@@ -96,9 +114,8 @@ export class Effected {
         const looked = looks(segments, depth, this.theme);
         const walked = walk(looked);
         const animation = this.effect(measured(looked, () => walked, depth, this.theme));
-        // What the effect draws at `t` is drawn until its next change, and the
-        // cells say so, under whatever the child already said (the sooner wins).
-        yield* Segment.applyStyle(this._recolored(walked, animation.at(this.t), depth), new Style({ nextChange: animation.nextChange(this.t) }));
+        const shown = shownAt(animation, this.t, options);
+        return { segments: this._recolored(walked, shown.value, depth), hold: holdOf(shown, this.t) };
     }
     *_recolored(walked, frame, depth) {
         for (const { segment, look, glyphs } of walked) {
@@ -106,35 +123,38 @@ export class Effected {
                 yield segment;
                 continue;
             }
-            const { style: base, wire, slots, pair } = look;
+            const { style: base, wire, slots, pair, attributes } = look;
             const { terminal } = pair;
-            const from = { fg: pair.fg, bg: pair.bg };
+            const from = { fg: pair.fg, bg: pair.bg, attributes };
             // [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.
+            // writes and on its attributes, so two truecolors landing on one index
+            // stay one run. A cell the effect gave its neighbour's look is drawn as
+            // that neighbour was.
             const runs = [];
             for (const { glyph, cell } of glyphs) {
+                const moved = cell === undefined ? from : returned(frame(from, { ...cell, seed: cellSeed(this.key, cell.row, cell.col), terminal, reverse: pair.reverse }));
                 // Back from the screen to the style's slots: the same swap undoes itself.
-                const colors = cell === undefined ? slots : onScreen(frame(from, { ...cell, seed: this.seed(cell.row, cell.col), terminal, reverse: pair.reverse }), pair.reverse);
+                const colors = onScreen(moved, pair.reverse);
                 const last = runs[runs.length - 1];
                 const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
-                if (last !== undefined && writesAlike(last.drawn, writes)) {
+                if (last !== undefined && writesAlike(last.drawn, writes) && sameAttributes(last.attributes, moved.attributes)) {
                     last.text += glyph;
                     last.cells += cellLen(glyph);
                     last.colors = colors;
                 }
                 else {
-                    runs.push({ text: glyph, cells: cellLen(glyph), colors, drawn: writes });
+                    runs.push({ text: glyph, cells: cellLen(glyph), colors, attributes: moved.attributes, drawn: writes });
                 }
             }
-            if (runs.every((run) => writesAlike(run.drawn, wire))) {
+            if (runs.every((run) => writesAlike(run.drawn, wire) && sameAttributes(run.attributes, attributes))) {
                 yield segment;
                 continue;
             }
             let offset = 0;
             for (const run of runs) {
-                const shifted = base.shiftedBy(offset);
+                const placed = base.shiftedBy(offset);
+                const shifted = sameAttributes(run.attributes, attributes) ? placed : placed.withAttributes(cellAttributes(run.attributes));
                 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;
@@ -144,6 +164,61 @@ export class Effected {
     measure(options) {
         return Measurement.get(options, this.renderable);
     }
+    /**
+     * 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.
+     */
+    respec(wire, from, to, depth) {
+        const moved = movedSpecs(from, to, depth, this.theme);
+        return { color: moved.fg ?? wire.color, bgcolor: moved.bg ?? wire.bgcolor };
+    }
+}
+/**
+ * `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 class Effected {
+    renderable;
+    effect;
+    key;
+    theme;
+    constructor(renderable, effect, options) {
+        this.renderable = renderable;
+        this.effect = effect;
+        this.key = options.key;
+        this.theme = options.theme;
+    }
+    /** The element through the effect at `t`, unstamped. */
+    at(t) {
+        return new Recolored(this.renderable, this.effect, { t, key: this.key, theme: this.theme });
+    }
+    nextChange(t) {
+        return t;
+    }
+    lastChange(t) {
+        return t;
+    }
+    /** The element under the effect with its motion taken out. */
+    reduced() {
+        const { effect } = this;
+        return new Effected(this.renderable, (drawn) => effect(drawn).reduced(), this);
+    }
+    /** Drawn at the frame's time, its cells stamped with the effect's exact hold there. */
+    render(options) {
+        const { segments, hold } = this.at(frameTimeOf(options)).moved(options);
+        return stampFrame(segments, hold);
+    }
+    measure(options) {
+        return Measurement.get(options, this.renderable);
+    }
     /**
      * 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
@@ -156,19 +231,14 @@ export class Effected {
         const moved = movedSpecs(from, onScreen(to, pair.reverse), depth, theme);
         return onScreen({ fg: moved.fg?.getTruecolor(theme, true) ?? from.fg, bg: moved.bg?.getTruecolor(theme, false) ?? from.bg }, pair.reverse);
     }
-    /**
-     * 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.
-     */
-    respec(wire, from, to, depth) {
-        const moved = movedSpecs(from, to, depth, this.theme);
-        return { color: moved.fg ?? wire.color, bgcolor: moved.bg ?? wire.bgcolor };
-    }
-    /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
-    seed(row, col) {
-        return Number.parseInt(fnv1a(`${this.key}:${row}:${col}`), 16) / 0x1_0000_0000;
-    }
+}
+/**
+ * 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 function cellSeed(key, row, col) {
+    return Number.parseInt(fnv1a(`${key}:${row}:${col}`), 16) / 0x1_0000_0000;
 }
 const DEFAULT = ColorSpec.default();
 /** Each of `segments` with how it is drawn at `depth` on `theme`; a control segment draws nothing. */
@@ -181,34 +251,48 @@ function looks(segments, depth, theme) {
         const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(theme, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(theme, false) };
         const reverse = style.reverse === true;
         const terminal = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, reverse);
-        return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, reverse), terminal, reverse } } };
+        return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, reverse), terminal, reverse }, attributes: cellAttributes(style) } };
     });
 }
 /**
- * Each glyph of `looked`, 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.
- * [LAW:one-source-of-truth] The one walk: what `Drawn.cells` lists and what
- * the render hands the effect are read off it.
+ * 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.
  */
-function walk(looked) {
+export function walkGlyphs(segments) {
     let row = 0;
     let col = 0;
-    return looked.map(({ segment, look }) => {
-        if (look === undefined)
-            return { segment, look, glyphs: [] };
-        const anchor = look.style.anchor;
+    return segments.map((segment) => {
+        if (segment.isControl)
+            return [];
+        const anchor = segment.style?.anchor;
         // Cells into the segment, as `base.shiftedBy` counts them in the render.
         let into = 0;
-        const glyphs = [...graphemes(segment.text)].map((glyph) => {
+        return [...graphemes(segment.text)].map((glyph) => {
             const cell = glyph === "\n" ? undefined : { row, col, anchor: anchor && shiftAnchor(anchor, into) };
             [row, col] = glyph === "\n" ? [row + 1, 0] : [row, col + cellLen(glyph)];
             into += cellLen(glyph);
             return { glyph, cell };
         });
-        return { segment, look, glyphs };
     });
 }
+/**
+ * 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 function inked(text) {
+    return text.trim() !== "";
+}
+/** `looked` with each segment's glyphs placed, by the one walk. */
+function walk(looked) {
+    const placed = walkGlyphs(looked.map(({ segment }) => segment));
+    return looked.map((item, i) => ({ ...item, glyphs: placed[i] }));
+}
 /** Whether `style` draws in its ink on a blank glyph: a line under, through or over it, or a frame round it. */
 function drawsLines(style) {
     return [style.underline, style.underline2, style.strike, style.overline, style.frame, style.encircle].some((on) => on === true);
@@ -227,9 +311,9 @@ function measured(looked, walked, depth, theme) {
             return [];
         // A blank glyph shows its ground, and any line its style draws in its ink.
         const blankShows = look.pair.bg.hex !== ground || drawsLines(look.style);
-        return glyphs.flatMap(({ glyph, cell }) => (cell !== undefined && (glyph.trim() !== "" || blankShows) ? [cell] : []));
+        return glyphs.flatMap(({ glyph, cell }) => (cell !== undefined && (inked(glyph) || blankShows) ? [cell] : []));
     });
-    const words = looked.flatMap(({ segment, look }) => (look !== undefined && segment.text.trim() !== "" && !drawnBy(look.style.anchor, JOIN) ? [look.pair] : []));
+    const words = looked.flatMap(({ segment, look }) => (look !== undefined && inked(segment.text) && !drawnBy(look.style.anchor, JOIN) ? [look.pair] : []));
     const pairs = [...new Map(words.map((pair) => [`${pair.fg.hex}/${pair.bg.hex}/${pair.terminal.fg}/${pair.terminal.bg}/${pair.reverse}`, pair])).values()];
     // [LAW:one-source-of-truth] A slot the terminal fills is no colour of the element's, whatever its hex.
     const own = (slot) => pairs.flatMap((pair) => (pair.terminal[slot] ? [] : [pair[slot].hex]));
@@ -242,44 +326,6 @@ function measured(looked, walked, depth, theme) {
         theme,
     };
 }
-/**
- * `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.
- */
-export function onBeat(effect, beat) {
-    return (drawn) => {
-        const sampled = effect(drawn);
-        return {
-            at: (t) => sampled.at(beat.lastChange(t)),
-            nextChange(t) {
-                const moved = sampled.nextChange(beat.lastChange(t));
-                if (moved === Number.POSITIVE_INFINITY)
-                    return moved;
-                const end = beat.nextChange(t);
-                // The hold boundaries after `t` are `end`, then each hold's end in turn;
-                // the frame turns at the first one the effect has moved by.
-                return moved <= end ? end : beat.lastChange(moved) === moved ? moved : beat.nextChange(moved);
-            },
-            // The frame held now began at this hold's start at the latest: an early
-            // answer where the effect had not moved by it, which the contract allows.
-            lastChange: (t) => beat.lastChange(t),
-        };
-    };
-}
 /**
  * `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
@@ -299,12 +345,13 @@ export function confined(effect, ...owners) {
     // The frame as the effect sees it: the owners' cells alone. [LAW:one-source-of-truth] One narrowing, handed to both stages.
     const owned = (drawn) => ({ ...drawn, cells: () => drawn.cells().filter((cell) => any(ownedOf(cell))) });
     // The owners' cells change when the effect's frame does.
-    return (drawn) => Animation.map(effect(owned(drawn)), (frame) => (colors, cell) => {
+    return (drawn) => Animation.map(effect(owned(drawn)), (frame) => (look, cell) => {
         const owns = ownedOf(cell);
         if (!any(owns))
-            return colors;
-        const moved = frame(colors, cell);
-        return { fg: owns.fg ? moved.fg : colors.fg, bg: owns.bg ? moved.bg : colors.bg };
+            return look;
+        const moved = frame(look, cell);
+        // An attribute is drawn on the glyph, in its ink, so it moves with whoever owns the ink.
+        return { fg: owns.fg ? moved.fg : look.fg, bg: owns.bg ? moved.bg : look.bg, attributes: owns.fg ? moved.attributes : look.attributes };
     });
 }
 /**
@@ -351,6 +398,32 @@ function slotWritesAlike(a, b, foreground) {
 function written(spec, foreground) {
     return spec?.getAnsiCodes(foreground).join(";") ?? "";
 }
+/**
+ * The look a frame returned, refused at once when it carries no attributes.
+ * [LAW:no-silent-failure] A frame written before an effect moved attributes
+ * returns `{ fg, bg }`, and the effects playground runs a visitor's frame with
+ * its types stripped, not checked; unrefused, it fails as a TypeError in run
+ * merging that names neither the frame nor the contract.
+ */
+function returned(look) {
+    if (look.attributes === undefined) {
+        throw new TypeError("an effect frame returns the look it was handed with its changes, { ...look, fg, bg }: this one returned no attributes");
+    }
+    return look;
+}
+/** The attributes a look carries: `ATTRIBUTE_NAMES` but `reverse`. */
+const MOVED = ATTRIBUTE_NAMES.filter((name) => name !== "reverse");
+/**
+ * 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 function cellAttributes(of) {
+    return Object.fromEntries(MOVED.map((name) => [name, of[name]]));
+}
+function sameAttributes(a, b) {
+    return a === b || MOVED.every((name) => a[name] === b[name]);
+}
 function sameColors(a, b) {
     return sameColor(a.fg, b.fg) && sameColor(a.bg, b.bg);
 }

package/dist/renderables/effects.d.ts

@@ -1,7 +1,8 @@
 /**
  * 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
+ * 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
  * 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.
@@ -13,7 +14,10 @@
  * 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
+ * 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
+ * keeps the words. What makes the loops' motions familiar is what every
  * curve of theirs keeps:
  *
  * - Nothing jumps. Every curve is continuous in time, built from smooth
@@ -46,9 +50,11 @@
  * cards runs this file's own declarations as the program a visitor edits
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
+import { Animation } from "../core/animation.js";
 import { ColorRgba } from "../core/color.js";
-import { type Timing } from "../core/easing.js";
-import { type Drawn, type Effect, type EffectCell } from "./effect.js";
+import { type Beat, 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;
 /**
@@ -98,6 +104,28 @@ export declare function shares({ pairs, depth, theme }: Drawn, colors: ReadonlyS
  * 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`
+ * 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
+ * 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
+ * loop, never again once a tween settles; a still one is
+ * `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
+ * 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
+ * (`stillOnSlots`): 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
  * `share` gives it of the cell's strength in a frame drawing what `Drawn`
@@ -115,6 +143,14 @@ 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;
 }
+/** Throws, naming the field, unless `curve` has a positive, finite `seconds` and a `swing` in [0, 1]. */
+export declare function requireCurve(curve: Curve): void;
+/**
+ * Throws, naming `what`, unless `z` is a finite place in the noise. Noise at
+ * a place that is not a number is not a number, which no effect could tell
+ * from a dim cell or an empty sky. [LAW:no-silent-failure]
+ */
+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.
@@ -241,13 +277,48 @@ 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]
+ *
+ * `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.
+ * [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.
  */
-export interface Transition {
-    readonly effect: Effect;
+export declare class Transition<E = Effect> {
+    readonly effect: E;
+    readonly schedule: Animation<unknown>;
+    constructor(effect: E, schedule: Animation<unknown>);
     done(t: number): boolean;
 }
+/**
+ * `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
+ * 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
+ * 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
+ * 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.
+ *
+ * A transition steps the same way, its schedule with it, so a fade-in on a
+ * 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>;
 /**
  * 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
@@ -307,7 +378,8 @@ export interface ColorStep {
  * 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
+ * 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
  * 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.
@@ -315,9 +387,47 @@ export interface ColorStep {
  * nothing here reads a clock.
  */
 export declare function steppedInk(steps: readonly ColorStep[]): Effect;
+/**
+ * A text attribute turned on and off on a beat: each pass, the cell as its
+ * element drew it for `off` seconds, then with `attribute` on for `on`.
+ */
+export interface Blink {
+    readonly attribute: keyof CellAttributes;
+    readonly off: number;
+    readonly on: number;
+}
+/**
+ * `spec.attribute` blinking: off, the cell as drawn, so that hold's frame is
+ * the identity and writes the element's own bytes; on, the attribute set.
+ * It changes when its beat does, at a hold's end, and never between.
+ * A blink and a bold pulse are this one function at two specs
+ * (`ATTRIBUTE_DEFAULTS`) [LAW:one-type-per-behavior].
+ */
+export declare function blink({ attribute, off, on }: Blink): Effect;
+/** The names of the effects that move an attribute. */
+export type AttributeLoopName = "blink" | "boldPulse";
+/**
+ * Each attribute effect's spec: a blink hides the words for half of each
+ * second, as a terminal's own blink does, and a bold pulse holds them bold
+ * for the last three tenths of each second.
+ */
+export declare const ATTRIBUTE_DEFAULTS: {
+    readonly blink: {
+        readonly attribute: "conceal";
+        readonly off: 0.5;
+        readonly on: 0.5;
+    };
+    readonly boldPulse: {
+        readonly attribute: "bold";
+        readonly off: 0.7;
+        readonly on: 0.3;
+    };
+};
 /**
  * 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
+ * the noise, so two elements under one effect drawn from noise do not move in
+ * lockstep. An effect on a beat alone (a blink) draws no noise, and keeps
+ * every element in step, as a terminal's own blink does. How
  * wide the element is, the effect reads off each frame (`Drawn.cells`).
  */
 export interface EffectTarget {
@@ -341,4 +451,5 @@ export type TransitionName = "fade" | "dissolve";
 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>>;
+    readonly attributes: Readonly<Record<AttributeLoopName, (element: EffectTarget) => Effect>>;
 };