@promptctl/rich-js 0.26.0 → 0.27.0

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 export { cellLen, setCellSize, splitText, chopCells, cellFit, graphemes, asCellCol, asCodePoint, } from "./core/cells.js";
 export type { CellCol, CodeUnit, CodePoint } from "./core/cells.js";
-export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, parseHexColor, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
+export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, type TerminalColors, parseRgbHex, parseRgbaHex, parseHexColor, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
 export type { ColorSystemName, DetectColorOptions, Destination, DestinationOptions } from "./core/color.js";
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
 export type { ThemeKey, OklchWeights } from "./core/oklch.js";
 export { Palette } from "./themes/palette.js";
+export type { AccentRole, BaseRole, PaletteRole, PaletteRoles, ShadedRole } from "./themes/palette.js";
 export { resolveColorRef, ColorRefError } from "./themes/colorRef.js";
 export { buildPalette } from "./themes/buildPalette.js";
-export type { BaseColors } from "./themes/buildPalette.js";
+export type { BaseColors, StatedRoles } from "./themes/buildPalette.js";
 export { DEFAULT_TERMINAL_THEME, MONOKAI, SVG_EXPORT_THEME, NORD, GRUVBOX, DRACULA, TOKYO_NIGHT, FLEXOKI, CYBERPUNK, CATPPUCCIN_MOCHA, CATPPUCCIN_LATTE, CATPPUCCIN_FRAPPE, CATPPUCCIN_MACCHIATO, SOLARIZED_DARK, SOLARIZED_LIGHT, ROSE_PINE, ROSE_PINE_MOON, ROSE_PINE_DAWN, ATOM_ONE_DARK, ATOM_ONE_LIGHT, TEXTUAL_DARK, TEXTUAL_LIGHT, TEXTUAL_ANSI, } from "./themes/terminalThemes.js";
 export { getThemePalette, listThemePalettes } from "./themes/registry.js";
 export type { ThemeName } from "./themes/registry.js";
@@ -33,7 +34,7 @@ export { Box } from "./core/box.js";
 export type { EdgeChars, ContentChars, RowLevel, SubstituteOptions } from "./core/box.js";
 export { ASCII, ASCII2, ASCII_DOUBLE_HEAD, SQUARE, SQUARE_DOUBLE_HEAD, MINIMAL, MINIMAL_HEAVY_HEAD, MINIMAL_DOUBLE_HEAD, SIMPLE, SIMPLE_HEAD, SIMPLE_HEAVY, HORIZONTALS, ROUNDED, HEAVY, HEAVY_EDGE, HEAVY_HEAD, DOUBLE, DOUBLE_EDGE, MARKDOWN, } from "./core/box.js";
 export { render, isRenderable, isMeasurable, withCellWidth, withBoundedWidth, insetHeight, stackedHeight, regionRows, fitHeight, getStyle, } from "./core/protocol.js";
-export type { RenderOptions, OverflowMethod, Height, Renderable, Measurable, Presence, StyleErrorHandler, FrameHost, } from "./core/protocol.js";
+export type { RenderOptions, OverflowMethod, Height, Renderable, Measurable, Presence, StyleErrorHandler, FrameHost, HostFrame, } from "./core/protocol.js";
 export type { Unsubscribe } from "./core/subscription.js";
 export { Measurement, measureRenderables } from "./core/measure.js";
 export { Span, RichText } from "./core/text.js";
@@ -67,7 +68,7 @@ export type { AttributeLoopName, Blink, ColorStep, Curve, EffectTarget, Field, L
 export { crossfade, wipe } from "./renderables/change.js";
 export type { Between, Change } from "./renderables/change.js";
 export { lifecycle, throughColors, throughGlyphs } from "./renderables/lifecycle.js";
-export type { Lifecycle, LifecycleOptions, Veil } from "./renderables/lifecycle.js";
+export type { Half, Lifecycle, LifecycleOptions } from "./renderables/lifecycle.js";
 export { scroll } from "./renderables/scroll.js";
 export type { ScrollOptions } from "./renderables/scroll.js";
 export { GlyphEffected } from "./renderables/glyph-effect.js";

package/dist/renderables/effect.d.ts

@@ -71,7 +71,7 @@
 import { type Anchor } from "../core/anchor.js";
 import { Animation } from "../core/animation.js";
 import type { Hold } from "../core/style.js";
-import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js";
+import { ColorDepth, type ColorRgba, type TerminalColors } from "../core/color.js";
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 import { type Attributes } from "../core/style.js";
@@ -194,7 +194,7 @@ export interface Drawn {
     /** The depth the frame is written at: below truecolor a moved colour lands on a palette colour. */
     readonly depth: ColorDepth;
     /** The terminal the frame is drawn on. */
-    readonly theme: TerminalTheme;
+    readonly theme: TerminalColors;
 }
 /** What an effect does to the cells of one frame: each cell's look and where it is in, its look out. Return `look` to leave a cell be. */
 export type EffectFrame = (look: CellLook, cell: EffectCell) => CellLook;
@@ -224,7 +224,7 @@ export interface EffectedOptions {
      * drawn in, and the sixteen an ANSI colour names. The terminal's own palette
      * is never queried, so the caller says what it is.
      */
-    readonly theme: TerminalTheme;
+    readonly theme: TerminalColors;
 }
 /** A frame an effect drew at a moment, and the hold the effect says it is in there. */
 export interface Moved {
@@ -243,7 +243,7 @@ export declare class Recolored implements Renderable, Measurable {
     readonly effect: Effect;
     readonly t: number;
     readonly key: string;
-    readonly theme: TerminalTheme;
+    readonly theme: TerminalColors;
     constructor(renderable: Renderable, effect: Effect, options: EffectedOptions & {
         readonly t: number;
     });
@@ -287,7 +287,7 @@ export declare class Effected implements Animation<Renderable> {
     readonly renderable: Renderable;
     readonly effect: Effect;
     readonly key: string;
-    readonly theme: TerminalTheme;
+    readonly theme: TerminalColors;
     constructor(renderable: Renderable, effect: Effect, options: EffectedOptions);
     /** The element through the effect at `t`, unstamped. */
     at(t: number): Recolored;
@@ -308,7 +308,7 @@ export declare class Effected implements Animation<Renderable> {
      * [LAW:one-source-of-truth] Read through `movedSpecs`, the one writer a
      * moved slot is written with.
      */
-    static shows(pair: Pair, to: CellColors, depth: ColorDepth, theme: TerminalTheme): CellColors;
+    static shows(pair: Pair, to: CellColors, depth: ColorDepth, theme: TerminalColors): CellColors;
 }
 /**
  * A cell's seed: FNV-1a of the element's key and the cell's position, scaled
@@ -355,7 +355,7 @@ export declare function confined(effect: Effect, ...owners: readonly object[]):
  * as `Effected` measures its child for every frame. Measure an element's
  * output under an effect to read the contrast its words are left at.
  */
-export declare function drawnOf(segments: Iterable<Segment>, depth: ColorDepth, theme: TerminalTheme): Drawn;
+export declare function drawnOf(segments: Iterable<Segment>, depth: ColorDepth, theme: TerminalColors): Drawn;
 /**
  * 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`

package/dist/renderables/effects.js

@@ -675,7 +675,7 @@ export class Transition {
         this.schedule = schedule;
     }
     done(t) {
-        return this.schedule.nextChange(t) === Number.POSITIVE_INFINITY;
+        return Animation.done(this.schedule, t);
     }
 }
 /**
@@ -685,8 +685,13 @@ export class Transition {
  * glyph effect (`./glyph-effects.ts`) alike.
  */
 export function transition(seconds, effect) {
-    // Moving every frame until `seconds`, then never: the sequence carries the switch.
-    const schedule = Animation.sequence(Animation.continuous(() => undefined), seconds, Animation.constant(undefined));
+    // Moving every frame until `seconds`, then never: the sequence carries the switch. [LAW:one-source-of-truth]
+    // Reduced, a one-shot cuts from its start to its end at 0, and its schedule says so too, the one word on
+    // when the reduced frames change, so a half that lends this schedule to its frames tells the same hold.
+    const schedule = Animation.of({
+        ...Animation.sequence(Animation.continuous(() => undefined), seconds, Animation.constant(undefined)),
+        reduced: () => Animation.cut(undefined, undefined),
+    });
     const ran = new Transition((drawn) => {
         const moving = effect(drawn);
         return Animation.of({

package/dist/renderables/lifecycle.d.ts

@@ -10,27 +10,32 @@
  * 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
+ * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each 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.
+ * 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,25 +45,30 @@
 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;
+export type Half = (element: Renderable, key: string) => Animation<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 declare function throughColors(transition: Transition, theme: TerminalTheme): 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>;
+    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,32 @@
  * 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
+ * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each 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.
+ * 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 +45,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";
+import { Effected } from "./effect.js";
+import { GlyphEffected } 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 }));
+    return (element, key) => scheduled(new Effected(element, transition.effect, { key, theme }), 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 +77,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, theme) 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 +129,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 +166,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);
         },
     });
 }

package/dist/renderables/live.d.ts

@@ -26,7 +26,7 @@
  */
 import { type Clock } from "../core/clock.js";
 import { Console } from "../core/console.js";
-import { type FrameHost } from "../core/protocol.js";
+import { type HostFrame, type FrameHost } from "../core/protocol.js";
 import { Timeline } from "../core/timeline.js";
 import { type View } from "../core/view.js";
 export interface LiveOptions {
@@ -79,8 +79,8 @@ export declare class Live implements FrameHost {
     get clock(): Clock;
     /** The map from the clock to the time the view is drawn for. */
     get timeline(): Timeline;
-    /** The time a frame drawn now is drawn for: the clock's now, through the timeline. */
-    get frameTime(): number;
+    /** The frame this Live draws now (`FrameHost`): the clock's now, through the timeline, on a frame it is the host of. */
+    frameNow(): HostFrame;
     private _time;
     /**
      * Replace the timeline and draw the frame for the time it now maps the

package/dist/renderables/live.js

@@ -30,7 +30,7 @@ import { Segment } from "../core/segment.js";
 import { FinalFramePainter, SurfacePainter } from "../core/paint.js";
 import { fitHeight, render } from "../core/protocol.js";
 import { Timeline } from "../core/timeline.js";
-import { drawView, frameTime, hostView, undrawn } from "../core/view.js";
+import { drawView, frameNow, hostView, undrawn } from "../core/view.js";
 import { State } from "../core/state.js";
 // Nothing: what a Live made with no view draws until `update` gives it one.
 const NOTHING = { render: () => [] };
@@ -89,9 +89,9 @@ export class Live {
     get timeline() {
         return this._timeline.get();
     }
-    /** The time a frame drawn now is drawn for: the clock's now, through the timeline. */
-    get frameTime() {
-        return frameTime(this._time());
+    /** The frame this Live draws now (`FrameHost`): the clock's now, through the timeline, on a frame it is the host of. */
+    frameNow() {
+        return frameNow(this, this._time());
     }
     _time() {
         return { now: this._clock.now(), epoch: this._epoch, timeline: this._timeline.get() };

package/dist/renderables/progress.d.ts

@@ -7,7 +7,7 @@ import { Console } from "../core/console.js";
 import type { Style } from "../core/style.js";
 import type { Clock } from "../core/clock.js";
 import { type ColumnOptions } from "./table.js";
-import type { FrameHost, Renderable, RenderOptions } from "../core/protocol.js";
+import type { HostFrame, FrameHost, Renderable, RenderOptions } from "../core/protocol.js";
 import { Animation } from "../core/animation.js";
 import type { Timing } from "../core/easing.js";
 export interface TaskOptions {
@@ -156,7 +156,7 @@ export declare class MofNCompleteColumn implements ProgressColumn {
 }
 /**
  * How a `Progress` is set up. It is drawn by one host, and every time it
- * keeps or draws at is that host's `frameTime`: by its own `Live`, which the
+ * keeps or draws at is that host's `frameNow()`: by its own `Live`, which the
  * options for that `Live` configure, or, given `drawnBy`, by another host —
  * which then does all the drawing, so none of them apply.
  */
@@ -185,7 +185,7 @@ interface OwnLiveOptions {
 interface DrawnByOptions {
     /**
      * The host — a `Live`, an `App` — whose frames this `Progress` is drawn in:
-     * tasks are timed by its `frameTime`, so they hold while its timeline is
+     * tasks are timed by its `frameNow()`, so they hold while its timeline is
      * paused and run back while it is reversed. Drawn in any other host's
      * frame, the `Progress` throws.
      */
@@ -207,6 +207,13 @@ export declare class Progress implements Renderable {
     constructor(...columns: (ProgressColumn | ProgressOptions)[]);
     /** The console its own `Live` prints above the bars through. */
     get console(): Console;
+    /**
+     * The frame its host draws now (`FrameHost.frameNow`): what a print of
+     * this display is drawn in — `console.print(progress, { frame:
+     * progress.frameNow() })` — so a still of it is drawn for a moment on the
+     * clock its tasks are timed on, the one the program asked at.
+     */
+    frameNow(): HostFrame;
     /** Rich's `Progress.finished`: every task finished, and so true with none. */
     get finished(): boolean;
     static getDefaultColumns(): ProgressColumn[];
@@ -224,7 +231,7 @@ export declare class Progress implements Renderable {
     refresh(): void;
     private _ownLive;
     render(options: RenderOptions): Iterable<Segment>;
-    private _framed;
+    private _ownFrame;
     private _table;
 }
 export declare function track<T>(iterable: Iterable<T>, options?: {

package/dist/renderables/progress.js

@@ -321,9 +321,20 @@ export class Progress {
     get console() {
         return this._ownLive("console").console;
     }
+    /**
+     * The frame its host draws now (`FrameHost.frameNow`): what a print of
+     * this display is drawn in — `console.print(progress, { frame:
+     * progress.frameNow() })` — so a still of it is drawn for a moment on the
+     * clock its tasks are timed on, the one the program asked at.
+     */
+    frameNow() {
+        return this._host.frameNow();
+    }
     /** Rich's `Progress.finished`: every task finished, and so true with none. */
     get finished() {
-        return this._tasks.get().every((task) => finished(taskAt(task.get(), this._host.frameTime)));
+        // [LAW:one-source-of-truth] One moment, so every task is judged at it.
+        const now = this._host.frameNow().time;
+        return this._tasks.get().every((task) => finished(taskAt(task.get(), now)));
     }
     static getDefaultColumns() {
         return [
@@ -342,7 +353,7 @@ export class Progress {
             completed: 0,
             fill: Animation.constant(0),
             visible: options?.visible !== false,
-            startTime: options?.start === false ? undefined : this._host.frameTime,
+            startTime: options?.start === false ? undefined : this._host.frameNow().time,
             finishedAt: undefined,
             samples: [],
         }));
@@ -364,7 +375,7 @@ export class Progress {
         const completed = options.completed === undefined
             ? finiteCount("completed + advance", task.completed + advance)
             : finiteCount("completed", options.completed);
-        const now = this._host.frameTime;
+        const now = this._host.frameNow().time;
         const reached = task.startTime !== undefined && task.total !== undefined && completed >= task.total;
         held.set({
             ...task,
@@ -385,7 +396,7 @@ export class Progress {
         const held = this._task(taskId);
         // Rich's `start_task`: a task already running keeps the time it started.
         if (held)
-            held.set({ ...held.get(), startTime: held.get().startTime ?? this._host.frameTime });
+            held.set({ ...held.get(), startTime: held.get().startTime ?? this._host.frameNow().time });
     }
     start() {
         this._ownLive("start").start();
@@ -410,23 +421,24 @@ export class Progress {
         return this._live;
     }
     *render(options) {
-        const framed = this._framed(options);
-        yield* render(this._table(framed.frame.time), framed);
+        yield* render(this._table(this._ownFrame(options).time), options);
     }
-    // Inside a frame, the time its host read for it: a second read here would
-    // land a moving bar's stamp a hair after the frame, a moment the host takes
-    // for one still to come. A frame is only ever this display's host's,
-    // because the tasks were stamped on that host's time and a frame of any
-    // other is drawn for a moment on a different clock. A print is drawn for no
-    // moment, so it is drawn in a frame for the one the program asks at, read
-    // as `updateTask` reads it, and every bar and spinner placed in the table
-    // draws at that moment too. [LAW:one-source-of-truth]
-    _framed(options) {
+    // The frame this display is drawn in, which is only ever its host's: the
+    // tasks were stamped on that host's time, and a frame of any other host is
+    // drawn for a moment on a different clock. A render reads no clock, so a
+    // print names its frame (`frameNow`, `PrintOptions.frame`): drawn for no
+    // moment — 0, as everything else is — every task would read as not yet
+    // started, so that print is refused with the call that draws it right.
+    // [LAW:parse-dont-validate] [LAW:no-silent-failure]
+    _ownFrame(options) {
         const { frame } = options;
-        if (frame !== undefined && frame.host !== this._host) {
+        if (frame === undefined) {
+            throw new Error("a Progress is drawn for a moment on its host's clock, and this print named none; print it in its frame: console.print(progress, { frame: progress.frameNow() })");
+        }
+        if (frame.host !== this._host) {
             throw new Error("a Progress was drawn in a frame of a host other than its own; give it that host as `drawnBy`");
         }
-        return { ...options, frame: frame ?? { time: this._host.frameTime, host: this._host } };
+        return frame;
     }
     // Rich's `make_tasks_table`: each column laid out as it says, at `now` on
     // this display's clock.