@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 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, 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 { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, type TerminalColors, parseRgbHex, parseRgbaHex, parseHexColor, blendRgb, resolveColorSystem, detectColorSystem, resolveOutputTarget, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
+export type { ColorSystemName, DetectColorOptions, OutputTarget, DestinationOptions } from "./core/color.js";
+export type { TextOrder } from "./core/text-order.js";
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
-export type { ThemeKey, OklchWeights } from "./core/oklch.js";
+export type { ColorAdjustment, 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";
@@ -12,21 +13,21 @@ 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";
-export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "./themes/transpose.js";
-export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
+export { adjustPalette, adjustmentForRoot, isHueLocked, HUE_LOCKED_ROOTS, } from "./themes/adjust.js";
+export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureMinimumDelta, compositedColor, } from "./themes/colorMath.js";
 export { ColorRamp } from "./themes/ramp.js";
 export type { ColorStop, RampMotion } from "./themes/ramp.js";
-export { EASES, Phase, beat, cubicBezier, parseEase, spring, steps } from "./core/easing.js";
-export type { Beat, Ease, SpringOptions, StepPosition, Timing } from "./core/easing.js";
+export { EASES, WrapMode, stepSequence, cubicBezier, parseEasing, spring, steps } from "./core/easing.js";
+export type { StepSequence, Easing, SpringOptions, StepPosition, Timing } from "./core/easing.js";
 export { Animation } from "./core/animation.js";
-export type { Timed } from "./core/animation.js";
+export type { Reads, Behavior } from "./core/animation.js";
 export { tween } from "./core/tween.js";
 export { Timeline } from "./core/timeline.js";
 export type { View } from "./core/view.js";
 export { frameRate, systemClock } from "./core/clock.js";
 export type { Clock, FrameRate } from "./core/clock.js";
 export { Style, StyleSyntaxError, StyleStack, Theme, NULL_STYLE, DEFAULT_STYLES, } from "./core/style.js";
-export type { Attributes, Hold, StyleOptions, TextStyle, LayeredStyle } from "./core/style.js";
+export type { Attributes, ValidityInterval, StyleOptions, TextStyle, LayeredStyle } from "./core/style.js";
 export { Segment, ControlType, } from "./core/segment.js";
 export type { ControlCode } from "./core/segment.js";
 export type { Anchor } from "./core/anchor.js";
@@ -34,13 +35,13 @@ 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, HostFrame, } from "./core/protocol.js";
+export type { RenderOptions, OverflowMethod, Height, Renderable, Measurable, Visibility, 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";
 export type { RichTextOptions } from "./core/text.js";
-export { Strip, CellJoiner, SEAM_MIN_DELTA_E, SEAMS, CAPS, JOINERS, joinerNamed, gradientSeam, } from "./core/strip.js";
-export type { StyledRenderable, Joiner, JoinContext, JoinSeam, JoinCaps, SeamForm, CapsForm, SeamCell, JoinCell, CellColor, Paint, JoinerSpec, } from "./core/strip.js";
+export { Strip, CellSeparator, SEAM_MIN_DELTA_E, SEPARATORS, END_CAPS, SEPARATOR_STYLES, separatorNamed, gradientSeam, } from "./core/strip.js";
+export type { StyledRenderable, Separator, JoinContext, SeparatorSeam, EndCaps, SeamForm, CapsForm, SeamCell, JoinCell, CellColor, Paint, SeparatorSpec, } from "./core/strip.js";
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 export type { RenderToStringOptions } from "./core/render.js";
 export { OSC8, osc8Sequences } from "./core/osc8.js";
@@ -63,8 +64,8 @@ export type { Env } from "./core/env.js";
 export { Constrain } from "./renderables/constrain.js";
 export { Effected, confined, drawnOf } from "./renderables/effect.js";
 export type { CellAttributes, CellColors, CellLook, Drawn, Effect, EffectCell, EffectedOptions, EffectFrame, ListedCell, Pair, Placed } from "./renderables/effect.js";
-export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, onBeat, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
-export type { AttributeLoopName, Blink, ColorStep, Curve, EffectTarget, Field, Loop, LoopName, Touch, Transition, TransitionName } from "./renderables/effects.js";
+export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, sampleAndHold, layered, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
+export type { AttributeLoopName, Blink, ColorStep, Curve, EffectTarget, Field, Loop, LoopName, ColorModifier, Transition, TransitionName } from "./renderables/effects.js";
 export { crossfade, wipe } from "./renderables/change.js";
 export type { Between, Change } from "./renderables/change.js";
 export { lifecycle, throughColors, throughGlyphs } from "./renderables/lifecycle.js";
@@ -73,8 +74,8 @@ export { scroll } from "./renderables/scroll.js";
 export type { ScrollOptions } from "./renderables/scroll.js";
 export { GlyphEffected } from "./renderables/glyph-effect.js";
 export type { DrawnGlyphs, GlyphCell, GlyphEffect, GlyphEffectedOptions, GlyphFrame } from "./renderables/glyph-effect.js";
-export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-effects.js";
-export type { CaseWave, GlyphLoopName, GlyphTransition, GlyphTransitionName, Particles } from "./renderables/glyph-effects.js";
+export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, marchingAnts, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-effects.js";
+export type { CaseWave, GlyphLoopName, GlyphTransition, GlyphTransitionName, MarchingAnts, Particles } from "./renderables/glyph-effects.js";
 export { Align } from "./renderables/align.js";
 export type { Alignment } from "./core/place.js";
 export { Padding } from "./renderables/padding.js";

package/dist/index.js

@@ -1,17 +1,17 @@
 // Core primitives
 export { cellLen, setCellSize, splitText, chopCells, cellFit, graphemes, asCellCol, asCodePoint, } 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";
-// Perceptually-uniform color space (manipulation, transposition).
+export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, parseHexColor, blendRgb, resolveColorSystem, detectColorSystem, resolveOutputTarget, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
+// Perceptually-uniform color space (manipulation, adjustment).
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
 // Themes — semantic palettes (distinct from ColorTable quantization LUTs)
 export { Palette } from "./themes/palette.js";
-// The one checkpoint turning an author-written colour string — a palette
-// variable name or a `#RRGGBB` literal — into a colour. [LAW:parse-dont-validate]
+// The one checkpoint turning an author-written color string — a palette
+// variable name or a `#RRGGBB` literal — into a color. [LAW:parse-dont-validate]
 export { resolveColorRef, ColorRefError } from "./themes/colorRef.js";
 export { buildPalette } 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 { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "./themes/transpose.js";
+export { adjustPalette, adjustmentForRoot, isHueLocked, HUE_LOCKED_ROOTS, } from "./themes/adjust.js";
 // WCAG contrast toolkit — accessibility-aware color for styled output.
 // `ensureContrast` keeps a color's hue and only slides its OKLCH lightness to
 // meet the ratio, so themed text stays themed; `contrastFor` picks black/white
@@ -21,7 +21,7 @@ export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "
 // reaches for to tint a resolved color against itself (e.g. a focused-while-open
 // menu cell lightening its inherited background) without re-deriving from a
 // palette name. Negative levels invert (lighten(c,-n) === darken(c,n)).
-export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
+export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureMinimumDelta, compositedColor, } from "./themes/colorMath.js";
 // A number → a color through ordered stops, interpolated in OKLCH — the one
 // color operation whose input is a measurement rather than a color, so a
 // gradient (or, with the `step` ease, a threshold cascade) stays inside the
@@ -29,7 +29,7 @@ export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureC
 export { ColorRamp } from "./themes/ramp.js";
 // Progress in [0, 1]: phases turn seconds into it, eases reshape it. One
 // vocabulary for ramps and time-based effects alike, CSS's names throughout.
-export { EASES, Phase, beat, cubicBezier, parseEase, spring, steps } from "./core/easing.js";
+export { EASES, WrapMode, stepSequence, cubicBezier, parseEasing, spring, steps } from "./core/easing.js";
 // A value for a time, and when it next changes: the one type every kind of
 // motion is an instance of — beats, frame sequences, spinners, effects.
 export { Animation } from "./core/animation.js";
@@ -52,8 +52,8 @@ export { render, isRenderable, isMeasurable, withCellWidth, withBoundedWidth, in
 export { Measurement, measureRenderables } from "./core/measure.js";
 // Text
 export { Span, RichText } from "./core/text.js";
-// Strip + Joiner
-export { Strip, CellJoiner, SEAM_MIN_DELTA_E, SEAMS, CAPS, JOINERS, joinerNamed, gradientSeam, } from "./core/strip.js";
+// Strip + Separator
+export { Strip, CellSeparator, SEAM_MIN_DELTA_E, SEPARATORS, END_CAPS, SEPARATOR_STYLES, separatorNamed, gradientSeam, } from "./core/strip.js";
 // renderToString — stateless one-shot emission
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 // OSC 8 hyperlink wire grammar — for consumers that read rendered bytes back
@@ -79,12 +79,12 @@ export { Console } from "./core/console.js";
 // Renderables
 export { Constrain } from "./renderables/constrain.js";
 export { Effected, confined, drawnOf } from "./renderables/effect.js";
-export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, onBeat, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
+export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, sampleAndHold, layered, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
 export { crossfade, wipe } from "./renderables/change.js";
 export { lifecycle, throughColors, throughGlyphs } from "./renderables/lifecycle.js";
 export { scroll } from "./renderables/scroll.js";
 export { GlyphEffected } from "./renderables/glyph-effect.js";
-export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-effects.js";
+export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, marchingAnts, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-effects.js";
 export { Align } from "./renderables/align.js";
 export { Padding } from "./renderables/padding.js";
 export { Viewport, ViewportPerKey, SCROLLBAR } from "./renderables/viewport.js";

package/dist/node/prompt.d.ts

@@ -16,7 +16,7 @@
  * The prompt is printed by the `Console` it was asked on — the app's, when it
  * passed one as `console`, a new default one otherwise — and then a line is
  * read, as Rich's `Console.input` prints its prompt and calls `input()`. So
- * the prompt is coloured exactly as that console's own output would be and
+ * the prompt is colored exactly as that console's own output would be and
  * goes to its target: a console on stderr asks on stderr, beside the
  * invalid-answer messages it prints. It goes as one logical line, never broken
  * at the console's width: the terminal wraps it at whatever width it has.

package/dist/node/prompt.js

@@ -16,7 +16,7 @@
  * The prompt is printed by the `Console` it was asked on — the app's, when it
  * passed one as `console`, a new default one otherwise — and then a line is
  * read, as Rich's `Console.input` prints its prompt and calls `input()`. So
- * the prompt is coloured exactly as that console's own output would be and
+ * the prompt is colored exactly as that console's own output would be and
  * goes to its target: a console on stderr asks on stderr, beside the
  * invalid-answer messages it prints. It goes as one logical line, never broken
  * at the console's width: the terminal wraps it at whatever width it has.

package/dist/node/terminal-host.d.ts

@@ -88,7 +88,7 @@ export interface NodeTerminalHostOptions {
      */
     stdout?: NodeWritable;
     /**
-     * The environment colour detection reads. Defaults to `process.env`; tests
+     * The environment color detection reads. Defaults to `process.env`; tests
      * pass a fixed map so what the host reports does not depend on the shell
      * that ran them.
      */

package/dist/node/traceback.js

@@ -77,8 +77,8 @@ export function installTraceback(options) {
         crashing = true;
         // [LAW:effects-at-boundaries] Render to a string first, then perform one
         // write. `beginCapture` redirects the console's sink without setting
-        // `file:`, so stderr's TTY status still drives colour depth — a `file:`
-        // sink would report `isTTY === false` and silently strip colour.
+        // `file:`, so stderr's TTY status still drives color depth — a `file:`
+        // sink would report `isTTY === false` and silently strip color.
         const out = new Console({ stderr: true });
         out.beginCapture();
         out.print(new Traceback(reason, options));

package/dist/renderables/change.d.ts

@@ -21,14 +21,12 @@
  * frame to the next, so the same `t` draws the same bytes at any frame rate.
  */
 import { Animation } from "../core/animation.js";
-import type { TerminalTheme } from "../core/color.js";
 import type { Renderable } from "../core/protocol.js";
 import { type Curve, type Transition } from "./effects.js";
-/** What a change is between: the renderable drawn until now, the one drawn from now on, and the terminal whose ground the change passes through. */
+/** What a change is between: the renderable drawn until now and the one drawn from now on. */
 export interface Between {
     readonly from: Renderable;
     readonly to: Renderable;
-    readonly theme: TerminalTheme;
 }
 /** A change from one renderable to another: what it draws at each moment, from `t = 0` on its own clock. */
 export type Change = (between: Between) => Animation<Renderable>;

package/dist/renderables/change.js

@@ -25,14 +25,14 @@ import { Measurement } from "../core/measure.js";
 import { render } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 import { Recolored } from "./effect.js";
-import { requireCurve, transition, veiled } from "./effects.js";
+import { requireCurve, transition, mask } from "./effects.js";
 const clamp01 = (x) => Math.min(1, Math.max(0, x));
 /** How much of a cell `p` of the way through a change shows: all of it at either end, none at the half, where the old gives way to the new. */
 const shows = (p) => Math.abs(2 * p - 1);
 /** The change over `curve`, each cell as far through it as `progress` says. */
 function change(curve, progress) {
     requireCurve(curve);
-    return transition(curve.seconds, ({ from, to, theme }) => Animation.sequence(Animation.continuous((t) => new ChangeFrame(from, to, theme, progress, t, curve.swing)), curve.seconds, Animation.constant(to)));
+    return transition(curve.seconds, ({ from, to }) => Animation.sequence(Animation.continuous((t) => new ChangeFrame(from, to, progress, t, curve.swing)), curve.seconds, Animation.constant(to)));
 }
 /** A crossfade: the old renderable fades to the terminal's ground and the new one rises from it, every cell together, over `curve`. */
 export function crossfade(curve) {
@@ -61,14 +61,12 @@ export function wipe(curve, edge = WIPE_EDGE) {
 class ChangeFrame {
     from;
     to;
-    theme;
     progress;
     t;
     swing;
-    constructor(from, to, theme, progress, t, swing) {
+    constructor(from, to, progress, t, swing) {
         this.from = from;
         this.to = to;
-        this.theme = theme;
         this.progress = progress;
         this.t = t;
         this.swing = swing;
@@ -86,9 +84,9 @@ class ChangeFrame {
             ...splice(Segment.adjustLineLength(before[row] ?? [], lengths[row]), line, (col) => at(row, col) >= 0.5),
             ...(row < after.length - 1 || ended ? [Segment.line()] : []),
         ]);
-        // The frame says nothing of when it changes: the change's own animation says it moves every frame.
-        const veil = veiled(() => (cell) => shows(at(cell.row, cell.col)), this.swing);
-        return render(new Recolored({ render: () => rows }, veil, { t: this.t, key: "change", theme: this.theme }), options);
+        // The change's own animation says it moves every frame, and reads nothing this frame tells.
+        const veil = mask(() => (cell) => shows(at(cell.row, cell.col)), this.swing);
+        return render(new Recolored({ render: () => rows }, veil, { t: this.t, key: "change" }), options);
     }
     measure(options) {
         return Measurement.get(options, this.to);

package/dist/renderables/effect.d.ts

@@ -1,5 +1,5 @@
 /**
- * Effected — a renderable whose finished cells' looks — colours and text
+ * Effected — a renderable whose finished cells' looks — colors and text
  * attributes — pass through an effect at a moment `t`.
  *
  * An effect is, for what an element draws in a frame, an `Animation`
@@ -11,26 +11,27 @@
  * 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 — and for a strip's join cells painted from the items beside
- * them, which are no one's to paint: a seam's colours are its neighbours'
+ * them, which are no one's to paint: a seam's colors are its neighbours'
  * edges, so once the effect has painted every other cell, each such cell is
  * resolved again from the cells beside it as the effect left them
  * (`JoinedCell`, `../core/strip.ts`), the way the joiner drew it. 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.
+ * [LAW:one-type-per-behavior]; two effects stack as layers of one effect
+ * (`layered`, `./effects.ts`), each moving what the last left and recognising
+ * a cell by what the element drew (`EffectCell.pair`), or by nesting one
+ * wrapper in another, which measures the inner one's output instead.
  *
- * 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`,
+ * A cell's look is one value, its colors and its attributes together
+ * (`CellLook`), rather than an attribute stage beside the color one, so
+ * everything that takes an `Effect` — `confined`, `sampleAndHold`,
  * `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.
+ * a color on screen is in, and a swap of the two is already a color 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
+ * and the colors of its words — is measured here, in the render, off the
  * same reading of each segment its cells are drawn from, and handed to the
  * effect once a frame. It is what an effect keeping words legible is settled
  * against (`onColors`, `./effects.ts`), so no caller derives it a second time
@@ -50,18 +51,18 @@
  *   to the effect and is never cut, and a run cut out of a segment keeps that
  *   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`,
+ * - A cell whose colors come back unchanged keeps its original `ColorSpec`,
  *   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 or the attributes change, so two colours that land on one index
+ *   colors or the attributes change, so two colors that land on one index
  *   are one run.
- * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
+ * - New colors 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`) no style is written at all,
+ * - With no color 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.
  *
@@ -69,16 +70,15 @@
  * what the child drew, so a sweep crosses the element, not the screen.
  */
 import { type Anchor } from "../core/anchor.js";
-import { Animation } from "../core/animation.js";
-import type { Hold } from "../core/style.js";
+import { Animation, type Reads, type Shown } from "../core/animation.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";
+import { type Attributes, type ValidityInterval } from "../core/style.js";
 /**
  * A cell's foreground and background as they appear on screen — the glyph's
- * colour and the colour behind it — which are the colours an effect moves.
- * Under `reverse` they are the style's two colours swapped.
+ * color and the color behind it — which are the colors an effect moves.
+ * Under `reverse` they are the style's two colors swapped.
  */
 export interface CellColors {
     readonly fg: ColorRgba;
@@ -90,7 +90,7 @@ export interface CellColors {
  * one lets a style laid beneath show through, as it does undrawn.
  */
 export type CellAttributes = Omit<Attributes, "reverse">;
-/** What an effect moves in a cell: its colours as the screen shows them, and its attributes. */
+/** What an effect moves in a cell: its colors as the screen shows them, and its attributes. */
 export interface CellLook extends CellColors {
     readonly attributes: CellAttributes;
 }
@@ -98,37 +98,36 @@ export interface CellLook extends CellColors {
  * Where a cell is in the output of the renderable an effect wraps, its seed:
  * a number in [0, 1) that is the same for that cell on every frame, for an
  * effect that varies cell by cell (a per-cell offset in time, a sparkle) —
- * and which of its on-screen colours are the terminal's.
+ * and what the element drew it in.
  */
 export interface EffectCell {
     readonly row: number;
     readonly col: number;
     readonly seed: number;
     /**
-     * Whether the glyph's colour and the colour behind it, as the screen shows
-     * them, are the terminal's own: a slot the element's style leaves unset or
-     * sets to `default`. Such a colour is resolved through the theme, so its
-     * hex can equal one the element wrote; this is what tells them apart.
+     * The ink and ground the element drew the cell in: what the cell is, where
+     * the `CellLook` beside it is what is there now. Under one effect they are
+     * the same colors; under `layered` (`./effects.ts`) the look is what the
+     * layers beneath left, so an effect recognises a cell by its pair and moves
+     * its look. [LAW:one-source-of-truth] A pair's `terminal` is what tells a
+     * color the terminal resolved from one the element wrote at the same hex.
      */
-    readonly terminal: {
-        readonly fg: boolean;
-        readonly bg: boolean;
-    };
-    /** Whether the cell's style swaps its two slots, as `Pair.reverse` says: with `colors` and `terminal`, the cell's `Pair`. */
-    readonly reverse: boolean;
+    readonly pair: Pair;
     /**
      * Who drew the cell, and where it sits in their output, as
      * `Segment.anchorAt` reads it off a frame: what tells one owner's cells
-     * from another's when their colours are alike (`confined`).
+     * from another's when their colors are alike (`confined`).
      */
     readonly anchor: Anchor | undefined;
+    /** The drawing of a box the cell is the frame of (`Style.boxFrame`), or none. */
+    readonly boxFrame: object | undefined;
 }
-/** Where a cell sits and who drew it: an `EffectCell` before it has a seed or colours. */
-export type Placed = Pick<EffectCell, "row" | "col" | "anchor">;
+/** Where a cell sits and who drew it: an `EffectCell` before it has a seed or colors. */
+export type Placed = Pick<EffectCell, "row" | "col" | "anchor" | "boxFrame">;
 /**
  * A cell as `Drawn.all` lists it: where it sits and who drew it, the
  * columns its glyph takes, its ink and ground as the screen shows them, and
- * whether a strip's joiner drew it — a seam, no item's, whose colours are its
+ * whether a strip's joiner drew it — a seam, no item's, whose colors are its
  * neighbours' edges. Each is read off the one look and the one walk the cell
  * is later handed with, so an effect that groups cells into the runs they
  * are drawn in — `wheel`'s segments — reads what the frame hands, never a
@@ -145,10 +144,19 @@ export interface ListedCell extends Placed {
  * is handed for that cell.
  */
 export interface Pair extends CellColors {
-    readonly terminal: EffectCell["terminal"];
+    /**
+     * Whether the glyph's color and the color behind it, as the screen shows
+     * them, are the terminal's own: a slot the element's style leaves unset or
+     * sets to `default`. Such a color is resolved through the terminal, so its
+     * hex can equal one the element wrote; this is what tells them apart.
+     */
+    readonly terminal: {
+        readonly fg: boolean;
+        readonly bg: boolean;
+    };
     /**
      * Whether the ink is written in the style's ground slot and the ground in
-     * its ink slot. Below truecolor the slot decides what a moved colour can
+     * its ink slot. Below truecolor the slot decides what a moved color can
      * land on: a slot set to `default` draws the terminal's foreground in one
      * and its background in the other.
      */
@@ -156,7 +164,7 @@ export interface Pair extends CellColors {
 }
 /**
  * What the element an effect wraps draws in one frame: the cells the effect
- * is handed, and the colours the element draws its words in, as the screen
+ * is handed, and the colors the element draws its words in, as the screen
  * shows them — what an effect that must keep the words legible is measured
  * against. A word cell is one whose glyph is not blank and that a strip's
  * joiner did not draw (`JOIN`): a seam's ink is the fill beside it, not words.
@@ -187,14 +195,14 @@ export interface Drawn {
     cells(): readonly ListedCell[];
     /** Every distinct ink and ground of a word cell. */
     readonly pairs: readonly Pair[];
-    /** The colours the element sets itself in its word cells, by hex: never the terminal's, whatever its hex. */
+    /** The colors the element sets itself in its word cells, by hex: never the terminal's, whatever its hex. */
     readonly colors: ReadonlySet<string>;
     /** Of `colors`, the ones a word cell has for its ground. */
     readonly fills: ReadonlySet<string>;
-    /** The depth the frame is written at: below truecolor a moved colour lands on a palette colour. */
+    /** The depth the frame is written at: below truecolor a moved color lands on a palette color. */
     readonly depth: ColorDepth;
     /** The terminal the frame is drawn on. */
-    readonly theme: TerminalColors;
+    readonly terminal: 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;
@@ -204,13 +212,14 @@ export type EffectFrame = (look: CellLook, cell: EffectCell) => CellLook;
  * frame by the shape of the call, never by a cache asking whether this cell's
  * frame is the last one's.
  *
- * Its `nextChange` is when the frame next changes: a stepped effect its next
+ * Its `validUntil` is when the frame next changes: a stepped effect its next
  * step's start, a transition `t` until it is done and `Infinity` after, a
- * loop that holds every cell still at the frame's depth `Infinity` there, and
- * a loop that moves `t` (`Animation.continuous`). [LAW:types-are-the-program]
- * The answer is a fact about the frame, so the animation is made from
- * everything the frame is drawn from; one made from `t` alone could not say
- * that a frame is still because of its depth.
+ * loop that holds every cell still, at the frame's depth or with nothing in
+ * it to move, `Infinity` there, and a loop that moves `t`
+ * (`Animation.continuous`). [LAW:types-are-the-program] The answer is a fact
+ * about the frame, so the animation is made from everything the frame is drawn
+ * from; one made from `t` alone could not say that a frame is still because of
+ * its depth.
  */
 export type Effect = (drawn: Drawn) => Animation<EffectFrame>;
 export interface EffectedOptions {
@@ -219,37 +228,30 @@ export interface EffectedOptions {
      * not twinkle in lockstep. The same key gives the same seeds on every frame.
      */
     readonly key: string;
-    /**
-     * The terminal the frame is drawn on: the colours a cell that sets none is
-     * 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: TerminalColors;
-}
-/** A frame an effect drew at a moment, and the hold the effect says it is in there. */
-export interface Moved {
-    readonly segments: Iterable<Segment>;
-    readonly hold: Hold;
 }
+/**
+ * The hold an effect drawn at `t` tells: its animation's there, or held for
+ * good over no cell, since it changes how cells look and never which exist.
+ * What drew none says for itself when it will (a lifecycle not yet entered).
+ */
+export declare function validityOver(anyCell: boolean, shown: Shown<unknown>, t: number): ValidityInterval;
 /**
  * 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]
+ * with its cells' looks passed through `effect` at `t`. Its cells say nothing
+ * of when that changes, since `t` is not the frame's clock: it tells the hold
+ * it drew in (`RenderOptions.onReads`), and whatever placed the animation
+ * carries that onto the frame's and stamps it. [LAW:one-type-per-behavior]
  */
 export declare class Recolored implements Renderable, Measurable {
     readonly renderable: Renderable;
     readonly effect: Effect;
-    readonly t: number;
+    private readonly _t;
     readonly key: string;
-    readonly theme: TerminalColors;
     constructor(renderable: Renderable, effect: Effect, options: EffectedOptions & {
         readonly t: number;
     });
     render(options: RenderOptions): Iterable<Segment>;
-    /** The frame the effect draws at `t`, and the hold it says that is in. */
-    moved(options: RenderOptions): Moved;
     private _recolored;
     /** `segment`'s cells drawn in the looks the effect painted them. */
     private _repainted;
@@ -266,7 +268,7 @@ export declare class Recolored implements Renderable, Measurable {
         maximum: number;
     };
     /**
-     * The specs that draw a cell's slot colours `to` where the segment drew
+     * The specs that draw a cell's slot colors `to` where the segment drew
      * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
      * in, the rest as `wire` wrote them.
      */
@@ -275,24 +277,22 @@ export declare class Recolored implements Renderable, Measurable {
 /**
  * `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.
+ * renderable goes. An `Effect` is made from what the element draws, so with
+ * nothing drawn its answer to when it changes is `t`, at every time: early,
+ * never false. Placed, on its own or as a part of any combinator, it says
+ * exactly: the frame's drawing told the effect's hold at that time and the
+ * output's depth (`Reads`), so at a depth that shows no motion a loop says it
+ * never changes there and the host sleeps.
  */
 export declare class Effected implements Animation<Renderable> {
     readonly renderable: Renderable;
     readonly effect: Effect;
     readonly key: string;
-    readonly theme: TerminalColors;
     constructor(renderable: Renderable, effect: Effect, options: EffectedOptions);
     /** The element through the effect at `t`, unstamped. */
     at(t: number): Recolored;
-    nextChange(t: number): number;
-    lastChange(t: number): number;
+    validUntil(t: number, moves?: Reads): number;
+    validFrom(t: number, moves?: Reads): number;
     /** The element under the effect with its motion taken out. */
     reduced(): Effected;
     /** Drawn at the frame's time, its cells stamped with the effect's exact hold there. */
@@ -302,17 +302,17 @@ export declare class Effected implements Animation<Renderable> {
         maximum: number;
     };
     /**
-     * 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
-     * moving a pair's colours leaves its words reading in.
+     * The colors the screen shows for `pair` once it is drawn moved to `to`,
+     * both as the screen shows them, at `depth` on `terminal`: what an effect
+     * moving a pair's colors leaves its words reading in.
      * [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: TerminalColors): CellColors;
+    static shows(pair: Pair, to: CellColors, depth: ColorDepth, terminal: TerminalColors): CellColors;
 }
 /**
  * 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
+ * into [0, 1). [LAW:one-source-of-truth] One rule for a color effect's seeds
  * and a glyph effect's, so one element under both twinkles from one seed.
  */
 export declare function cellSeed(key: string, row: number, col: number): number;
@@ -329,13 +329,13 @@ export interface WalkedGlyph {
  * 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`)
+ * render hands a color effect, and what a glyph effect (`./glyph-effect.ts`)
  * is handed are all read off it.
  */
 export declare function walkGlyphs(segments: readonly Segment[]): (readonly WalkedGlyph[])[];
 /**
  * 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
+ * The one test, so the words a color effect lights are the words a glyph
  * effect (`./glyph-effects.ts`) scrambles and its particles pass behind.
  */
 export declare function inked(text: string): boolean;
@@ -351,11 +351,12 @@ export declare function inked(text: string): boolean;
  */
 export declare function confined(effect: Effect, ...owners: readonly object[]): Effect;
 /**
- * What `segments`, drawn at `depth` on `theme`, draw their words in, measured
- * 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.
+ * What `segments`, drawn at `depth` on `terminal`, draw their words in, measured
+ * as `Effected` measures its child for every frame, so `options.terminal` means
+ * here what it means on a 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: TerminalColors): Drawn;
+export declare function drawnOf(segments: Iterable<Segment>, depth: ColorDepth, terminal?: 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`