@promptctl/rich-js 0.26.0 → 0.28.0

package/dist/renderables/glyph-effect.js

@@ -51,44 +51,40 @@
  * Positions are the child's own: row and column count from the top-left of
  * what the child drew.
  */
-import { Animation, frameTimeOf, holdOf, shownAt, stampFrame } from "../core/animation.js";
+import { Animation, placedRender, shownAt } from "../core/animation.js";
 import { cellLen, graphemes } from "../core/cells.js";
 import { Measurement } from "../core/measure.js";
 import { render } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 import { finiteTime } from "../core/easing.js";
-import { stripControlChars } from "../core/text.js";
-import { cellSeed, walkGlyphs } from "./effect.js";
+import { sanitized } from "../core/text.js";
+import { cellSeed, holdOver, walkGlyphs } from "./effect.js";
 import { pattern } from "../core/pattern.js";
 /**
  * A `GlyphEffected` at `t`, or an element through a glyph effect at a time an
  * animation's `at` was handed: `renderable` with its cells' glyphs passed
- * through `effect` at `t`, saying nothing of when that changes, as a
- * `Recolored` is (`./effect.ts`). [LAW:one-type-per-behavior]
+ * through `effect` at `t`, telling the hold it drew in as a `Recolored` does
+ * (`RenderOptions.onMoved`, `./effect.ts`). [LAW:one-type-per-behavior]
  */
 export class Reglyphed {
     renderable;
     effect;
-    t;
+    _t;
     key;
     constructor(renderable, effect, options) {
         this.renderable = renderable;
         this.effect = effect;
-        this.t = finiteTime("GlyphEffected", options.t);
+        this._t = finiteTime("GlyphEffected", options.t);
         this.key = options.key;
     }
     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)];
         const { placed, cells } = placeGlyphs(segments, this.key);
         const animation = this.effect({ cells, asciiOnly: options.asciiOnly === true });
-        const frame = shownAt(animation, this.t, options);
+        const frame = shownAt(animation, this._t, options);
         const shown = showGlyphs(placed, frame.value);
-        const changed = segments.map((segment, i) => shown[i].every((text, j) => text === placed[i][j].glyph) ? segment : new Segment(shown[i].join(""), segment.style));
-        return { segments: changed, hold: holdOf(frame, this.t) };
+        options.onMoved?.(this._t, this.key, holdOver(cells.length > 0, frame, this._t));
+        return segments.map((segment, i) => (shown[i].every((text, j) => text === placed[i][j].glyph) ? segment : new Segment(shown[i].join(""), segment.style)));
     }
     measure(options) {
         return Measurement.get(options, this.renderable);
@@ -96,9 +92,10 @@ export class Reglyphed {
 }
 /**
  * `renderable` under a glyph effect over time, an `Animation<Renderable>`
- * as an `Effected` is (`./effect.ts`): its own answer is `t`, and placed,
- * its cells carry the glyph effect's exact hold at the frame's time and the
- * output's `asciiOnly`, under whatever the element already said.
+ * as an `Effected` is (`./effect.ts`): with nothing drawn its answer is `t`,
+ * and placed, on its own or as a part of any combinator, it says the glyph
+ * effect's exact hold at that time and the output's `asciiOnly`, which the
+ * frame's drawing told (`Moves`).
  */
 export class GlyphEffected {
     renderable;
@@ -113,11 +110,11 @@ export class GlyphEffected {
     at(t) {
         return new Reglyphed(this.renderable, this.effect, { t, key: this.key });
     }
-    nextChange(t) {
-        return t;
+    nextChange(t, moves) {
+        return moves?.(t, this.key)?.nextChange ?? t;
     }
-    lastChange(t) {
-        return t;
+    lastChange(t, moves) {
+        return moves?.(t, this.key)?.lastChange ?? t;
     }
     /** The element under the glyph effect with its motion taken out. */
     reduced() {
@@ -126,8 +123,7 @@ export class GlyphEffected {
     }
     /** Drawn at the frame's time, its cells stamped with the glyph effect's exact hold there. */
     render(options) {
-        const { segments, hold } = this.at(frameTimeOf(options)).moved(options);
-        return stampFrame(segments, hold);
+        return placedRender(this, options);
     }
     measure(options) {
         return Measurement.get(options, this.renderable);
@@ -161,7 +157,7 @@ function showGlyphs(placed, frame) {
  * its every style and span, each moved to where its glyphs now sit, and a
  * frame that changes nothing hands the text back as it was. What it says of
  * when it changes is the effect's, unstamped: whoever draws it at a time
- * stamps it (`textFrameAt`).
+ * stamps it (`placed`), or marks it for the engine to (the template `glyphs`).
  */
 export function reglyphText(text, effect, options) {
     const { placed, cells } = placeGlyphs([new Segment(text.plain)], options.key);
@@ -193,7 +189,7 @@ function rewritten(text, glyphs, shown) {
         result.stylize(span.style, moved(span.start), moved(span.end));
     return result;
 }
-/** Line breaks and tabs, which `stripControlChars` leaves for a text's own lines and which no cell may hold. */
+/** Line breaks and tabs, which `sanitized` leaves for a text's own lines and which no cell may hold. */
 const BREAKS = pattern(/[\n\t]/);
 /**
  * What `frame` shows in `cell`, held to the contract: as many cells wide as
@@ -205,7 +201,7 @@ function shows(frame, cell) {
     const text = frame(cell);
     if (text === cell.glyph)
         return text;
-    if (cellLen(text) !== cellLen(cell.glyph) || BREAKS.test(text) || stripControlChars(text) !== text) {
+    if (cellLen(text) !== cellLen(cell.glyph) || BREAKS.test(text) || sanitized(text) !== text) {
         throw new RangeError(`a glyph effect turned ${JSON.stringify(cell.glyph)} at row ${cell.row}, column ${cell.col} into ${JSON.stringify(text)}: ` +
             `it must be ${cellLen(cell.glyph)} cell(s) wide, with no line break or control character`);
     }
@@ -218,18 +214,24 @@ function shows(frame, cell) {
  * wide as its glyph is `shows`'s check; this is the half no one cell can
  * see — a trailing zero-width joiner that fuses with the next emoji, or a
  * leading combining mark that draws on the glyph before it, is right alone
- * and wrong beside its neighbour. Only a changed text is asked, so a child
- * that splits a cluster across its own segments is drawn as it drew it.
+ * and wrong beside its neighbour. Only a join the effect made is asked, seam
+ * by seam, so a child that splits a cluster across its own segments is drawn
+ * as it drew it, whatever becomes of the glyph its mark sits on.
  */
 function standsApart(placed, shown) {
-    // A line break is no cell, and nothing joins across it.
-    const beside = (j) => (placed[j]?.cell === undefined ? "" : shown[j]);
+    const fuse = (left, right) => graphemes(left + right).length < graphemes(left).length + graphemes(right).length;
+    // Whether the text at `i` fuses across its left seam and across its right.
+    const seams = (texts, i) => {
+        // A line break is no cell, and nothing joins across it.
+        const beside = (j) => (placed[j]?.cell === undefined ? "" : texts(j));
+        const [before, text, after] = [beside(i - 1), texts(i), beside(i + 1)];
+        return [fuse(before, text + after), fuse(before + text, after)];
+    };
     shown.forEach((text, i) => {
         const { glyph, cell } = placed[i];
         if (cell === undefined || text === glyph)
             return;
-        const [before, after] = [beside(i - 1), beside(i + 1)];
-        if (graphemes(before + text + after).length !== graphemes(before).length + graphemes(text).length + graphemes(after).length) {
+        if (seams((j) => shown[j], i).some((fused, seam) => fused && !seams((j) => placed[j].glyph, i)[seam])) {
             throw new RangeError(`a glyph effect turned ${JSON.stringify(glyph)} at row ${cell.row}, column ${cell.col} into ${JSON.stringify(text)}, ` +
                 `which joins the cell beside it into one character`);
         }

package/dist/renderables/glyph-effects.d.ts

@@ -1,11 +1,12 @@
 /**
  * The glyph effect catalogue: a typewriter and a scramble, which run once and
  * are done, each with its way out for an element leaving (`backspace`,
- * `scrambleOut`), and a wave of case changes, rain and stars, which loop for as
- * long as they are drawn. Each is a `GlyphEffect` for `GlyphEffected`
- * (`./glyph-effect.ts`), built as the colour catalogue's are
- * (`./effects.ts`): one function each over the one shape, made by name, one
- * way, at the defaults in `GLYPH_DEFAULTS` (`GLYPH_EFFECT_CATALOGUE`).
+ * `scrambleOut`), and a wave of case changes, rain, stars and marching ants,
+ * which loop for as long as they are drawn. Each is a `GlyphEffect` for
+ * `GlyphEffected` (`./glyph-effect.ts`), built as the colour catalogue's are
+ * (`./effects.ts`): one function each over the one shape, at the defaults in
+ * `GLYPH_DEFAULTS`. `GLYPH_EFFECT_CATALOGUE` makes by name those a template's
+ * `glyphs` takes.
  *
  * Where a colour loop glides, a glyph cannot: a cell shows one glyph or
  * another, so every loop here moves in steps, on a `beat`, and says when its
@@ -90,11 +91,25 @@ export interface Particles {
  * row a step, and one that holds still draws a fresh field each life.
  */
 export declare function particles(spec: Particles, z: number): GlyphEffect;
-/** The names of the glyph effects that loop. */
+/** How ants march: a step, in seconds, for the gaps to move one cell, and the most cells a gap may be from the next. */
+export interface MarchingAnts {
+    readonly step: number;
+    readonly every: number;
+}
+/**
+ * Marching ants: gaps blanked round each box the element draws, spaced as
+ * evenly as the ring allows and never more than `every` cells apart, walking
+ * one cell clockwise a `step`. The whole pattern turns, so a ring that `every`
+ * does not divide closes with no seam at its corner. The ring is whatever the box
+ * is (`Box.frame`), at any width and beside a title. A ring may draw blanks and
+ * they keep the count, but an element with no ink on any ring never changes.
+ */
+export declare function marchingAnts({ step, every }: MarchingAnts): GlyphEffect;
+/** The names a template's `glyphs` takes for an effect that loops. */
 export type GlyphLoopName = "wave" | "rain" | "stars";
-/** The names of the glyph effects that run once. */
+/** The names a template's `glyphs` takes for an effect that runs once. */
 export type GlyphTransitionName = "typewriter" | "scramble" | "backspace" | "scrambleOut";
-/** Each catalogue glyph effect's defaults, as first drawn in `examples/glyph-effects`. */
+/** Each glyph effect's defaults, as first drawn in `examples/glyph-effects`. */
 export declare const GLYPH_DEFAULTS: {
     readonly typewriter: {
         readonly seconds: 2;
@@ -132,6 +147,10 @@ export declare const GLYPH_DEFAULTS: {
         readonly drift: 0;
         readonly life: 1;
     };
+    readonly march: {
+        readonly step: 0.15;
+        readonly every: 3;
+    };
 };
 /**
  * Every glyph effect in the catalogue by name, each made the one way: for an

package/dist/renderables/glyph-effects.js

@@ -1,11 +1,12 @@
 /**
  * The glyph effect catalogue: a typewriter and a scramble, which run once and
  * are done, each with its way out for an element leaving (`backspace`,
- * `scrambleOut`), and a wave of case changes, rain and stars, which loop for as
- * long as they are drawn. Each is a `GlyphEffect` for `GlyphEffected`
- * (`./glyph-effect.ts`), built as the colour catalogue's are
- * (`./effects.ts`): one function each over the one shape, made by name, one
- * way, at the defaults in `GLYPH_DEFAULTS` (`GLYPH_EFFECT_CATALOGUE`).
+ * `scrambleOut`), and a wave of case changes, rain, stars and marching ants,
+ * which loop for as long as they are drawn. Each is a `GlyphEffect` for
+ * `GlyphEffected` (`./glyph-effect.ts`), built as the colour catalogue's are
+ * (`./effects.ts`): one function each over the one shape, at the defaults in
+ * `GLYPH_DEFAULTS`. `GLYPH_EFFECT_CATALOGUE` makes by name those a template's
+ * `glyphs` takes.
  *
  * Where a colour loop glides, a glyph cannot: a cell shows one glyph or
  * another, so every loop here moves in steps, on a `beat`, and says when its
@@ -50,6 +51,10 @@ function text(cells) {
     }
     return { length: place.size, place };
 }
+/** `n` wrapped into [0, `size`), for a count a timeline may run backwards past 0. */
+function wrapped(n, size) {
+    return ((n % size) + size) % size;
+}
 /** Of `n` cells, how many have arrived at eased progress `p`, an ease that overshoots held to the cells there are. */
 function arrived(n, p) {
     return Math.min(n, Math.max(0, Math.floor(n * p)));
@@ -200,7 +205,7 @@ export function caseWave({ step, width }, z) {
         const start = Math.floor(hash(z, 2.3) * span);
         return steps((s) => {
             // The column just past the band's right edge; it enters at the left.
-            const lead = (((s + start) % span) + span) % span;
+            const lead = wrapped(s + start, span);
             // A wide glyph is in the band if any of its columns is.
             return (cell) => (cell.col < lead && cell.col + cellLen(cell.glyph) > lead - width ? swapCase(cell.glyph) : cell.glyph);
         }, AS_WRITTEN);
@@ -250,7 +255,69 @@ export function particles(spec, z) {
         }, AS_WRITTEN);
     };
 }
-/** Each catalogue glyph effect's defaults, as first drawn in `examples/glyph-effects`. */
+/**
+ * Where each cell stands on the ring of the box frame that drew it, by
+ * `index`. A ring is the
+ * perimeter of the rectangle a frame's cells cover, read in the element's own
+ * rows and columns, so it is true wherever the box sits among them. A rule or
+ * divider inside that rectangle, as a table draws, is frame and no part of the
+ * ring, and a title set into the frame is no frame but keeps its places.
+ */
+function ringPlaces(cells) {
+    const frames = new Map();
+    for (const cell of cells) {
+        if (cell.boxFrame === undefined)
+            continue;
+        const ring = frames.get(cell.boxFrame);
+        if (ring === undefined)
+            frames.set(cell.boxFrame, [cell]);
+        else
+            ring.push(cell);
+    }
+    const places = new Map();
+    for (const ring of frames.values()) {
+        // Cells come in reading order, so the rows are the ring's two ends.
+        const [top, down] = [ring[0].row, ring[ring.length - 1].row - ring[0].row];
+        const left = ring.reduce((most, { col }) => Math.min(most, col), Infinity);
+        const across = ring.reduce((most, { col }) => Math.max(most, col), -Infinity) - left;
+        const size = Math.max(1, 2 * (across + down));
+        for (const cell of ring) {
+            const [y, x] = [cell.row - top, cell.col - left];
+            const place = y === 0 ? x : x === across ? across + y : y === down ? 2 * across + down - x : x === 0 ? 2 * (across + down) - y : undefined;
+            if (place !== undefined)
+                places.set(cell.index, { place, cells: size });
+        }
+    }
+    return places;
+}
+/**
+ * Marching ants: gaps blanked round each box the element draws, spaced as
+ * evenly as the ring allows and never more than `every` cells apart, walking
+ * one cell clockwise a `step`. The whole pattern turns, so a ring that `every`
+ * does not divide closes with no seam at its corner. The ring is whatever the box
+ * is (`Box.frame`), at any width and beside a title. A ring may draw blanks and
+ * they keep the count, but an element with no ink on any ring never changes.
+ */
+export function marchingAnts({ step, every }) {
+    positiveSeconds("marchingAnts step", step);
+    if (!(Number.isInteger(every) && every > 1))
+        throw new RangeError(`marchingAnts every must be a whole number of cells above 1, got ${every}`);
+    const steps = stepped(step);
+    return ({ cells }) => {
+        const places = ringPlaces(cells);
+        if (!cells.some((cell) => places.has(cell.index) && inked(cell.glyph)))
+            return Animation.constant(AS_WRITTEN);
+        return steps((s) => (cell) => {
+            const at = places.get(cell.index);
+            if (at === undefined)
+                return cell.glyph;
+            // Bresenham's line over the ring: of `cells` places, the `gaps` where a running count crosses a whole number.
+            const gaps = Math.ceil(at.cells / every);
+            return (wrapped(at.place - s, at.cells) * gaps) % at.cells < gaps ? blank(cell.glyph) : cell.glyph;
+        }, AS_WRITTEN);
+    };
+}
+/** Each glyph effect's defaults, as first drawn in `examples/glyph-effects`. */
 export const GLYPH_DEFAULTS = {
     typewriter: { seconds: 2, ease: EASES.linear },
     scramble: { seconds: 2.5, ease: EASES["ease-in"] },
@@ -259,6 +326,7 @@ export const GLYPH_DEFAULTS = {
     wave: { step: 0.06, width: 3 },
     rain: { glyphs: "│╎", ascii: "|:", density: 0.06, step: 0.08, drift: 1, life: Number.POSITIVE_INFINITY },
     stars: { glyphs: "·+*", ascii: ".+*", density: 0.04, step: 1.5, drift: 0, life: 1 },
+    march: { step: 0.15, every: 3 },
 };
 /**
  * Every glyph effect in the catalogue by name, each made the one way: for an

package/dist/renderables/lifecycle.d.ts

@@ -10,27 +10,31 @@
  * part of the drawing asks whether it is leaving. Telling it is a new value
  * (`leave`), as every `Timeline` operation is. [LAW:no-ambient-temporal-coupling]
  *
- * Each half is a `Transition` of a `Veil` on its own clock from 0, handed the time since
- * its moment, and its schedule carried onto the host's clock by
- * `Timeline.run` is that half's hold — every frame for a fade, once a hold
- * for one on a beat — so the transition's schedule, and `done` read off it,
- * stays the one rule for where a one-shot ends and when its frame changes,
- * and nothing here measures progress itself. The frames carry no word of
- * their own on when they change: placed, the lifecycle stamps them with its
- * hold at the frame's time (`placedRender`). The exit veils whatever the
- * arrival draws, so an element told to leave while it is still arriving leaves
- * from where it is, never shown whole first — though a colour exit is spread
- * over the cells each frame shows, so a cell the arrival adds can move one
- * already leaving back toward whole (`ownChange`, `./effects.ts`).
- * [LAW:dataflow-not-control-flow]
+ * Each half is a `Half`: handed the element, an `Animation<Renderable>` of
+ * it on the half's own clock from 0, in the shape of the library's other
+ * one-shot from renderables to an animation (`Change`, `./change.ts`). One
+ * value carries the half's frames and its holds, so neither is kept in
+ * agreement with the other by hand, and nothing here measures progress
+ * itself: a half's schedule carried onto the host's clock by `Timeline.run`
+ * is that half's hold — every frame for a fade, once a hold for one on a
+ * beat — and the moment it says it never changes again (`Animation.done`)
+ * is where the arrival ends and where the element is gone. The frames carry
+ * no word of their own on when they change: placed, the lifecycle stamps
+ * them with its hold at the frame's time (`placedRender`). The exit is
+ * drawn over whatever the arrival draws, so an element told to leave while
+ * it is still arriving leaves from where it is, never shown whole first —
+ * though a colour exit is spread over the cells each frame shows, so a cell
+ * the arrival adds can move one already leaving back toward whole
+ * (`ownChange`, `./effects.ts`). [LAW:dataflow-not-control-flow]
  *
  * A half draws the element through a colour transition (`throughColors`, a
- * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each lift binds
- * its transition to the one wrapper that draws it, and to what that wrapper
- * needs — a theme for colours, nothing for glyphs — so nothing here asks which
- * kind a half is, and a line can type itself in and dissolve out. An exit is
- * a transition that ends with nothing drawn — `dissolveOut`, `backspace`,
- * `scrambleOut` — so the element has already gone from sight when it is gone.
+ * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each binds its
+ * transition to the one wrapper that draws it, so nothing here asks which kind
+ * a half is, and a line can type itself in and dissolve out. A half
+ * written by hand is any function of that shape — an arrival that slides the
+ * element in, which no effect draws. An exit is a half that ends with nothing
+ * drawn — `dissolveOut`, `backspace`, `scrambleOut` — so the element has
+ * already gone from sight when it is gone.
  *
  * Gone is a fact the host reads (`gone(t)`) to drop the element, and from then
  * the lifecycle draws nothing and never changes, so a host still holding it
@@ -38,27 +42,31 @@
  * backwards — it draws nothing too, but is not gone.
  */
 import { Animation } from "../core/animation.js";
-import type { TerminalTheme } from "../core/color.js";
 import type { Renderable } from "../core/protocol.js";
-import { Transition } from "./effects.js";
+import type { Transition } from "./effects.js";
 import type { GlyphTransition } from "./glyph-effects.js";
 /**
- * An element drawn through one half of its lifecycle at `t`, the seconds since
- * that half began, its effect's seeds named by `key`, saying nothing of when
- * that changes — the half's schedule does, as a `Recolored`'s and a
- * `Reglyphed`'s frame say nothing.
+ * One half of an element's lifecycle: handed the element and `key`, which
+ * names it for the half's seeds, the element as the half draws it from
+ * `t = 0`, the moment the half began, on its own clock. Its holds are the
+ * half's own, whatever element it is handed, and it is done from the first
+ * moment it says it never changes again (`Animation.done`): an arrival is
+ * the element from then, and an exit is gone. A half that never ends is
+ * refused when the lifecycle is made: an `Effected` or `GlyphEffected`
+ * handed in bare is one, since its own word is "now" at every time;
+ * `throughColors` and `throughGlyphs` lend one the transition's schedule.
  */
-export type Veil = (element: Renderable, t: number, key: string) => Renderable;
-/** `transition`'s colours drawn over an element on `theme`, whose ground it arrives from and leaves to. */
-export declare function throughColors(transition: Transition, theme: TerminalTheme): Transition<Veil>;
+export type Half = (element: Renderable, key: string) => Animation<Renderable>;
+/** `transition`'s colours drawn over an element, arriving from and leaving to the ground of the terminal the frame is drawn on. */
+export declare function throughColors(transition: Transition): Half;
 /** `transition`'s glyphs drawn over an element, at every depth, with no colour too. */
-export declare function throughGlyphs(transition: GlyphTransition): Transition<Veil>;
+export declare function throughGlyphs(transition: GlyphTransition): Half;
 /** How an element arrives and leaves, and what it is named for their seeds. */
 export interface LifecycleOptions {
-    /** The half it arrives through — `throughColors(fadeIn(curve, z), theme)`. */
-    readonly enter: Transition<Veil>;
+    /** The half it arrives through — `throughColors(fadeIn(curve, z))`. */
+    readonly enter: Half;
     /** The half it leaves through — `throughGlyphs(scrambleOut(timing, z))`. */
-    readonly exit: Transition<Veil>;
+    readonly exit: Half;
     /** Names the element for both halves' seeds, as `Effected`'s and `GlyphEffected`'s key does. */
     readonly key: string;
 }

package/dist/renderables/lifecycle.js

@@ -10,27 +10,31 @@
  * part of the drawing asks whether it is leaving. Telling it is a new value
  * (`leave`), as every `Timeline` operation is. [LAW:no-ambient-temporal-coupling]
  *
- * Each half is a `Transition` of a `Veil` on its own clock from 0, handed the time since
- * its moment, and its schedule carried onto the host's clock by
- * `Timeline.run` is that half's hold — every frame for a fade, once a hold
- * for one on a beat — so the transition's schedule, and `done` read off it,
- * stays the one rule for where a one-shot ends and when its frame changes,
- * and nothing here measures progress itself. The frames carry no word of
- * their own on when they change: placed, the lifecycle stamps them with its
- * hold at the frame's time (`placedRender`). The exit veils whatever the
- * arrival draws, so an element told to leave while it is still arriving leaves
- * from where it is, never shown whole first — though a colour exit is spread
- * over the cells each frame shows, so a cell the arrival adds can move one
- * already leaving back toward whole (`ownChange`, `./effects.ts`).
- * [LAW:dataflow-not-control-flow]
+ * Each half is a `Half`: handed the element, an `Animation<Renderable>` of
+ * it on the half's own clock from 0, in the shape of the library's other
+ * one-shot from renderables to an animation (`Change`, `./change.ts`). One
+ * value carries the half's frames and its holds, so neither is kept in
+ * agreement with the other by hand, and nothing here measures progress
+ * itself: a half's schedule carried onto the host's clock by `Timeline.run`
+ * is that half's hold — every frame for a fade, once a hold for one on a
+ * beat — and the moment it says it never changes again (`Animation.done`)
+ * is where the arrival ends and where the element is gone. The frames carry
+ * no word of their own on when they change: placed, the lifecycle stamps
+ * them with its hold at the frame's time (`placedRender`). The exit is
+ * drawn over whatever the arrival draws, so an element told to leave while
+ * it is still arriving leaves from where it is, never shown whole first —
+ * though a colour exit is spread over the cells each frame shows, so a cell
+ * the arrival adds can move one already leaving back toward whole
+ * (`ownChange`, `./effects.ts`). [LAW:dataflow-not-control-flow]
  *
  * A half draws the element through a colour transition (`throughColors`, a
- * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each lift binds
- * its transition to the one wrapper that draws it, and to what that wrapper
- * needs — a theme for colours, nothing for glyphs — so nothing here asks which
- * kind a half is, and a line can type itself in and dissolve out. An exit is
- * a transition that ends with nothing drawn — `dissolveOut`, `backspace`,
- * `scrambleOut` — so the element has already gone from sight when it is gone.
+ * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each binds its
+ * transition to the one wrapper that draws it, so nothing here asks which kind
+ * a half is, and a line can type itself in and dissolve out. A half
+ * written by hand is any function of that shape — an arrival that slides the
+ * element in, which no effect draws. An exit is a half that ends with nothing
+ * drawn — `dissolveOut`, `backspace`, `scrambleOut` — so the element has
+ * already gone from sight when it is gone.
  *
  * Gone is a fact the host reads (`gone(t)`) to drop the element, and from then
  * the lifecycle draws nothing and never changes, so a host still holding it
@@ -40,20 +44,31 @@
 import { Animation } from "../core/animation.js";
 import { firstReaching } from "../core/easing.js";
 import { Timeline } from "../core/timeline.js";
-import { Recolored } from "./effect.js";
-import { Transition } from "./effects.js";
-import { Reglyphed } from "./glyph-effect.js";
-/** `transition`'s colours drawn over an element on `theme`, whose ground it arrives from and leaves to. */
-export function throughColors(transition, theme) {
-    return lift(transition, (element, t, key) => new Recolored(element, transition.effect, { t, key, theme }));
+import { Effected } from "./effect.js";
+import { GlyphEffected } from "./glyph-effect.js";
+/** `transition`'s colours drawn over an element, arriving from and leaving to the ground of the terminal the frame is drawn on. */
+export function throughColors(transition) {
+    return (element, key) => scheduled(new Effected(element, transition.effect, { key }), transition.schedule);
 }
 /** `transition`'s glyphs drawn over an element, at every depth, with no colour too. */
 export function throughGlyphs(transition) {
-    return lift(transition, (element, t, key) => new Reglyphed(element, transition.effect, { t, key }));
+    return (element, key) => scheduled(new GlyphEffected(element, transition.effect, { key }), transition.schedule);
 }
-/** [LAW:one-source-of-truth] A lifted half keeps its transition's schedule, so `done` and every hold are the transition's own. */
-function lift(transition, veil) {
-    return new Transition(veil, transition.schedule);
+/**
+ * `placed` — an element under a transition's effect — changing when
+ * `schedule`, the transition's own, says: its frames with the one word on
+ * when they change that the transition has and the wrapper lacks, whose own
+ * answer is "now" until it is drawn. [LAW:one-source-of-truth] Reduced,
+ * both are reduced together, as `onBeat` steps both: a one-shot's effect
+ * and its schedule each reduce to a cut at 0 (`transition`, `./effects.ts`).
+ */
+function scheduled(placed, schedule) {
+    return Animation.of({
+        at: (t) => placed.at(t),
+        nextChange: (t) => schedule.nextChange(t),
+        lastChange: (t) => schedule.lastChange(t),
+        reduced: () => scheduled(placed.reduced(), schedule.reduced()),
+    });
 }
 /** What an element draws before it entered and once it is gone: no cells, and no width. */
 const NOTHING = { render: () => [], measure: () => ({ minimum: 0, maximum: 0 }) };
@@ -61,26 +76,50 @@ const NOTHING = { render: () => [], measure: () => ({ minimum: 0, maximum: 0 })
 export function lifecycle(element, options, entered) {
     if (!Number.isFinite(entered))
         throw new RangeError(`lifecycle: entered must be a finite time, got ${entered}`);
-    return life(element, options, entered, Number.POSITIVE_INFINITY);
+    const { enter, exit, key } = options;
+    const arrival = ending(enter(element, key), "enter", key);
+    const departure = ending(exit(element, key), "exit", key);
+    return life(element, options, { arrival, arrived: doneAt(arrival, entered), departure }, entered, Number.POSITIVE_INFINITY);
 }
 /**
- * The first host moment `transition`, begun at host time `start`, is done:
- * its own `done` read on host time, never a sum `start + seconds`, which can
- * round to either side of it, as `Animation.sequence` carries its switch.
- * [LAW:single-enforcer] Since `x - start` never falls as `x` rises, a host time
- * is at or past this moment exactly when `done` holds there.
+ * The first host moment `half`, begun at host time `start`, is done: its own
+ * answer read on host time, never a sum `start + seconds`, which can round
+ * to either side of it, as `Animation.sequence` carries its switch.
+ * [LAW:single-enforcer] Since `x - start` never falls as `x` rises, a host
+ * time is at or past this moment exactly when `done` holds there. Done is
+ * for good, so a half done as it begins — the element at once — is done at
+ * `start`, and from a start it is not done at the walk is upward only: no
+ * half is asked about a time before it began.
  */
-function doneAt(transition, start) {
-    return Number.isFinite(start) ? firstReaching(start, (x) => transition.done(x - start)) : start;
+function doneAt(half, start) {
+    if (!Number.isFinite(start) || Animation.done(half, 0))
+        return start;
+    return firstReaching(start, (x) => Animation.done(half, x - start));
 }
-function life(element, options, entered, left) {
-    const { enter, exit, key } = options;
-    const arrived = doneAt(enter, entered);
-    const goneAt = doneAt(exit, left);
-    // The arrival's schedule on the host's clock: when its frame next changes, and since when it has been what it is.
-    const arriving = Timeline.run(Timeline.play(entered), enter.schedule);
+/**
+ * `half` over the element, asked where it ends on its own clock, or refused
+ * by its `role` and the element's `key` when it never does. [LAW:no-silent-failure]
+ * Kept, it would never arrive, or never be gone, and wake the host every frame
+ * for good; asked here, the refusal lands where the options were written and
+ * not at the first `leave`. A half on a beat that never ends is refused by the
+ * beat instead, where the walk asks it past what its holds resolve.
+ */
+function ending(half, role, key) {
+    if (doneAt(half, 0) === Number.POSITIVE_INFINITY) {
+        throw new RangeError(`lifecycle "${key}": the ${role} half never ends: its animation never says it has stopped changing (Animation.done). An Effected or GlyphEffected on its own does not; throughColors(transition) and throughGlyphs(transition) lend one the transition's schedule`);
+    }
+    return half;
+}
+function life(element, options, halves, entered, left) {
+    const { exit, key } = options;
+    const { arrival, arrived, departure } = halves;
+    // Where the exit is gone, and the exit's hold, are read off the exit over the element; the frame while
+    // leaving is the exit over what is shown, whose holds are the same by `Half`'s contract.
+    const goneAt = doneAt(departure, left);
+    // The arrival on the host's clock: when its frame next changes, and since when it has been what it is.
+    const arriving = Timeline.run(Timeline.play(entered), arrival);
     // What the element draws by `t` if it is not leaving: arriving through `enter`, then itself.
-    const shown = (t) => (t < arrived ? enter.effect(element, t - entered, key) : element);
+    const shown = (t) => (t < arrived ? arrival.at(t - entered) : element);
     const held = (schedule, t) => ({ last: schedule.lastChange(t), next: schedule.nextChange(t) });
     // [LAW:one-source-of-truth] Each phase's frame and its hold, side by side, so the two cannot disagree.
     // The frames say nothing of when they change — the hold does, stamped where the lifecycle is placed.
@@ -89,10 +128,10 @@ function life(element, options, entered, left) {
             return { frame: NOTHING, last: Number.NEGATIVE_INFINITY, next: entered };
         if (t >= goneAt)
             return { frame: NOTHING, last: goneAt, next: Number.POSITIVE_INFINITY };
-        // Leaving veils whatever arriving draws, so both schedules count; once arrived, the arrival's never changes again.
+        // Leaving is drawn over whatever arriving draws, so both schedules count; once arrived, the arrival's never changes again.
         if (t >= left) {
-            const leaving = Animation.all([arriving, Timeline.run(Timeline.play(left), exit.schedule)]);
-            return { frame: exit.effect(shown(t), t - left, key), ...held(leaving, t) };
+            const leaving = Animation.all([arriving, Timeline.run(Timeline.play(left), departure)]);
+            return { frame: exit(shown(t), key).at(t - left), ...held(leaving, t) };
         }
         if (t < arrived)
             return { frame: shown(t), ...held(arriving, t) };
@@ -126,7 +165,7 @@ function life(element, options, entered, left) {
                 throw new RangeError(`lifecycle: already told to leave at ${left}, told again at ${at}`);
             if (!(Number.isFinite(at) && at >= entered))
                 throw new RangeError(`lifecycle: leave must be a finite time from entered (${entered}) on, got ${at}`);
-            return life(element, options, entered, at);
+            return life(element, options, halves, entered, at);
         },
     });
 }