@promptctl/rich-js 0.24.0 → 0.24.1

package/dist/core/easing.d.ts

@@ -1,6 +1,7 @@
 /**
- * Easing and phase: the one vocabulary for "how far along" — every function
- * here returns progress in [0, 1].
+ * Easing and phase: the one vocabulary for "how far along" — a time in
+ * seconds becomes progress in [0, 1], and an ease reshapes that progress,
+ * usually but not always within [0, 1].
  *
  * Two kinds of curve, composed as `ease(phase(t))`:
  *
@@ -13,20 +14,31 @@
  *   built-ins are CSS's easing functions (CSS Easing Functions Level 1):
  *   `linear`, `cubic-bezier()` with its named curves, and `steps()` with its
  *   jump terms, plus `sine` for pulses — a half-cosine, so a `pingPong`
- *   through it brightens and dims with no corner at either end.
+ *   through it brightens and dims with no corner at either end — and the
+ *   physics-flavoured curves a cursor snapping, a counter settling or a
+ *   panel sliding in want: `spring`, a damped harmonic oscillator released
+ *   toward its rest, which is the one of them with parameters and so the one
+ *   that also says how long it takes; `bounce`, `back-in`, `back-out` and
+ *   `elastic`, Robert Penner's curves at the constants every animation
+ *   library since has shipped. An ease that leaves [0, 1] — a spring or a
+ *   back curve overshooting its rest — is still an ease: a `ColorRamp` holds
+ *   its end colours where it does, and an effect's `Curve` saturates at its
+ *   swing, so the overshoot is read by what can show it (a position, a
+ *   count) and clipped by what cannot.
  *
  * [LAW:no-ambient-temporal-coupling] Nothing here reads a clock. `t` is an
  * argument; whoever draws frames owns the clock and samples these at
  * whatever rate it likes, so the same `t` always gives the same progress.
  *
  * [LAW:one-type-per-behavior] An ease is a plain function value. CSS's named
- * curves are four instances of `cubicBezier`, not four implementations, and
- * `ColorRamp` and every effect take the same `Ease`.
+ * curves are four instances of `cubicBezier`, not four implementations, the
+ * spring in `EASES` is one `spring()`, and `ColorRamp` and every effect take
+ * the same `Ease`.
  *
  * Tier 0 of `src/core/`: imports nothing, so `themes/` and every later
  * `core/` module reach it downhill. [LAW:one-way-deps]
  */
-/** Progress in, progress out: a reshaping of [0, 1]. */
+/** Progress in [0, 1] in, progress out: a reshaping of [0, 1] that may leave it, as a spring overshooting its rest does. */
 export type Ease = (x: number) => number;
 /** Time in seconds (plus any per-cell offset) in, progress in [0, 1] out. */
 export type Phase = (t: number) => number;
@@ -51,11 +63,66 @@ export type StepPosition = "jump-start" | "jump-end" | "jump-none" | "jump-both"
  * the very end.
  */
 export declare function steps(n: number, position?: StepPosition): Ease;
+/**
+ * A spring's physics: the mass on it, the stiffness of its coil and the
+ * damping it moves against, in the units every animation library spells them
+ * in (React Spring, Framer Motion), whose defaults these are — a spring that
+ * overshoots once and settles in about a second and a quarter.
+ */
+export interface SpringOptions {
+    /** The restoring force per unit of displacement; stiffer swings faster and settles in about the same time, since the decay is the damping's over the mass's. Positive. Defaults to 100. */
+    readonly stiffness?: number;
+    /** The force against the motion per unit of velocity; more settles sooner and overshoots less. Positive. Defaults to 10. */
+    readonly damping?: number;
+    /** What the spring moves; heavier is slower and overshoots further. Positive. Defaults to 1. */
+    readonly mass?: number;
+}
+/**
+ * An ease over a duration: CSS's timing function and duration as one value,
+ * the whole of what a one-shot move needs to know about time — a tween's
+ * (`./tween.ts`), a `spring()`'s, and the part of an effect's `Curve` that
+ * is not its swing. `Phase.once(start, seconds)` through `ease` is the move
+ * on a timeline. [LAW:one-type-per-behavior] One shape, so a spring is handed
+ * to a tween as it is, and a curve written for an effect times a tween.
+ */
+export interface Timing {
+    /** How the move is shaped, as progress in to progress out. */
+    readonly ease: Ease;
+    /** How long the move takes, in seconds. */
+    readonly seconds: number;
+}
+/**
+ * How close to its rest a spring must come to count as settled: one part in a
+ * thousand of the way it moves, under a colour channel's step (1/255) and
+ * under any cell, so what rounds the spring's value to show it draws the rest
+ * from there on.
+ */
+export declare const SPRING_REST = 0.001;
+/**
+ * A damped harmonic oscillator, `m·x″ = −k·x − c·x′`, released at rest one
+ * unit from its equilibrium: the spring every animation library means. Its
+ * progress at `s` seconds is `1 − displacement(s)`, the closed-form solution
+ * of that equation in the regime its damping ratio `ζ = c / 2√(k·m)` puts it
+ * in — ringing past its rest for `ζ < 1`, creeping up to it for `ζ ≥ 1` — and
+ * its `seconds` is its settling time: the first moment after which the
+ * displacement stays within `SPRING_REST`, found once here by `crossing` on
+ * the bracket each regime knows its last crossing lies in, so a sample costs
+ * an exponential and a cosine whatever `x` is. [LAW:no-ambient-temporal-coupling]
+ *
+ * The ease is exactly 1 at `x = 1` (`settled`): settled means at rest. The
+ * `seconds` are the spring's to say, not the caller's: how long it rings is
+ * a fact about its physics, which is why this is the one ease that comes as
+ * a `Timing` — released at rest a unit from where it is going, at 1 when it
+ * has settled there.
+ */
+export declare function spring(options?: SpringOptions): Timing;
 /**
  * Every built-in ease by the name a template spells it with — CSS's keyword
  * names, plus `sine`, plus `step`: the spelling `ColorRamp` used before this
  * vocabulary existed, kept so every template written against it renders the
- * same. It is CSS's `step-end`, the same function value.
+ * same. It is CSS's `step-end`, the same function value. Then the
+ * physics-flavoured curves: `spring` is the default `spring()`, whose
+ * `seconds` are `DEFAULT_SPRING`'s; the rest are Penner's at his constants.
  */
 export declare const EASES: {
     readonly linear: Ease;
@@ -67,6 +134,11 @@ export declare const EASES: {
     readonly "step-end": Ease;
     readonly step: Ease;
     readonly sine: Ease;
+    readonly spring: Ease;
+    readonly bounce: Ease;
+    readonly "back-in": Ease;
+    readonly "back-out": Ease;
+    readonly elastic: Ease;
 };
 export type EaseName = keyof typeof EASES;
 /**
@@ -75,6 +147,8 @@ export type EaseName = keyof typeof EASES;
  * Unknown names throw naming every legal one. [LAW:no-silent-failure]
  */
 export declare function parseEase(name: string): Ease;
+/** Throws, naming `what`, unless `seconds` is a positive, finite number of seconds. */
+export declare function positiveSeconds(what: string, seconds: number): void;
 /**
  * A beat: holds of given lengths in seconds, played in order and looped, the
  * way the frames of an animation are each held and then replaced. `at(t)` is
@@ -94,16 +168,42 @@ export interface Beat {
      * When the hold in progress at `t` began, in seconds on `t`'s own
      * timeline: what a sample-and-hold on this beat reads at `t`. Every `t`
      * inside one hold of one pass answers the same number, to the bit, so an
-     * effect handed it draws the same frame throughout.
+     * effect handed it draws the same frame throughout. With `nextChange`,
+     * the two ends of the hold, as every `Animation` answers them.
      */
-    start(t: number): number;
+    lastChange(t: number): number;
     /**
      * When the hold in progress at `t` ends, in seconds on `t`'s own timeline:
      * the start of the next hold, the first moment `at` places in it, so it is
      * always after `t`. What is drawn on this beat at `t` is drawn until then.
+     * With `at`, this makes a beat an `Animation` of the hold in progress
+     * (`./animation.ts`).
      */
-    end(t: number): number;
+    nextChange(t: number): number;
 }
+/**
+ * The first float from `sum` up at which `reached` holds: a time built as a
+ * sum to land on a boundary — where a hold begins, where an animation's next
+ * part changes — that rounding put an ulp or two under it, walked up to the
+ * first moment on the far side. [LAW:single-enforcer] The one walk, so every
+ * boundary a time is carried onto is the moment the change shows, to the
+ * float. A walk longer than rounding can cost throws `finer()`'s message: the
+ * boundary is narrower than the floats around it are apart.
+ */
+export declare function walkUp(sum: number, reached: (x: number) => boolean, finer: () => string): number;
+/**
+ * The least float at which `reached` holds, `reached` being false up to some
+ * float and true from it on, found from `near`, a guess at it on either
+ * side. Where `walkUp` carries a sum onto a boundary on its own clock, and
+ * an ulp or two is all rounding can cost, this carries a moment across
+ * clocks (`./timeline.ts`): a host float is a step of `rate` on the
+ * animation's clock, so the host floats between the guess and the first one
+ * past the boundary are as many as the two clocks' resolutions are apart,
+ * which no cap bounds and is no error. The bracket is found by doubling the
+ * step out from `near`, and halved to two adjacent floats, so the answer is
+ * exact to the float and the cost is logarithmic in that distance.
+ */
+export declare function firstReaching(near: number, reached: (x: number) => boolean): number;
 /** `holds` as a `Beat`; a beat with no hold, or a hold that is not a positive number of seconds, throws. */
 export declare function beat(holds: readonly number[]): Beat;
 /** The three phase shapes. Each takes seconds and returns a `Phase`. */

package/dist/core/easing.js

@@ -1,6 +1,7 @@
 /**
- * Easing and phase: the one vocabulary for "how far along" — every function
- * here returns progress in [0, 1].
+ * Easing and phase: the one vocabulary for "how far along" — a time in
+ * seconds becomes progress in [0, 1], and an ease reshapes that progress,
+ * usually but not always within [0, 1].
  *
  * Two kinds of curve, composed as `ease(phase(t))`:
  *
@@ -13,15 +14,26 @@
  *   built-ins are CSS's easing functions (CSS Easing Functions Level 1):
  *   `linear`, `cubic-bezier()` with its named curves, and `steps()` with its
  *   jump terms, plus `sine` for pulses — a half-cosine, so a `pingPong`
- *   through it brightens and dims with no corner at either end.
+ *   through it brightens and dims with no corner at either end — and the
+ *   physics-flavoured curves a cursor snapping, a counter settling or a
+ *   panel sliding in want: `spring`, a damped harmonic oscillator released
+ *   toward its rest, which is the one of them with parameters and so the one
+ *   that also says how long it takes; `bounce`, `back-in`, `back-out` and
+ *   `elastic`, Robert Penner's curves at the constants every animation
+ *   library since has shipped. An ease that leaves [0, 1] — a spring or a
+ *   back curve overshooting its rest — is still an ease: a `ColorRamp` holds
+ *   its end colours where it does, and an effect's `Curve` saturates at its
+ *   swing, so the overshoot is read by what can show it (a position, a
+ *   count) and clipped by what cannot.
  *
  * [LAW:no-ambient-temporal-coupling] Nothing here reads a clock. `t` is an
  * argument; whoever draws frames owns the clock and samples these at
  * whatever rate it likes, so the same `t` always gives the same progress.
  *
  * [LAW:one-type-per-behavior] An ease is a plain function value. CSS's named
- * curves are four instances of `cubicBezier`, not four implementations, and
- * `ColorRamp` and every effect take the same `Ease`.
+ * curves are four instances of `cubicBezier`, not four implementations, the
+ * spring in `EASES` is one `spring()`, and `ColorRamp` and every effect take
+ * the same `Ease`.
  *
  * Tier 0 of `src/core/`: imports nothing, so `themes/` and every later
  * `core/` module reach it downhill. [LAW:one-way-deps]
@@ -79,7 +91,7 @@ export function cubicBezier(x1, y1, x2, y2) {
         }
         return s;
     };
-    return (x) => yAt(solve(Math.min(1, Math.max(0, x))));
+    return settled((p) => yAt(solve(p)));
 }
 /**
  * CSS `steps(n, position)`: progress held flat in `n` equal intervals, jumping
@@ -103,22 +115,183 @@ export function steps(n, position = "jump-end") {
         "jump-none": n - 1,
     }[position];
     const lift = jumpsAtStart ? 1 : 0;
-    return (x) => {
-        const p = Math.min(1, Math.max(0, x));
-        return Math.min(jumps, Math.floor(p * n) + lift) / jumps;
-    };
+    return settled((p) => Math.min(jumps, Math.floor(p * n) + lift) / jumps);
 }
+/**
+ * The curve `shape` over [0, 1) as an ease that has arrived: its argument
+ * held to [0, 1], and exactly 1 at 1. Every built-in ease is one, so the two
+ * halves of the `Ease` contract — an argument in [0, 1], the end landed on —
+ * are enforced here and nowhere else. [LAW:single-enforcer] The end matters
+ * because a curve is 1 at its end only in the limit or up to a rounding — a
+ * spring settles to within `SPRING_REST`, the elastic's ringing never quite
+ * stops, a back curve's cubic or a bezier's Newton step lands an ulp off —
+ * and a count or a width eased by it must land on its target, not a
+ * thousandth or an ulp short.
+ */
+const settled = (shape) => (x) => {
+    const p = Math.min(1, Math.max(0, x));
+    return p === 1 ? 1 : shape(p);
+};
 /** The identity ease: progress unchanged. */
-const linear = (x) => x;
+const linear = settled((p) => p);
 /** CSS `step-end`: 0 until the very end. */
 const stepEnd = steps(1, "jump-end");
 /** A half-cosine, flat at both ends: the curve a breathing pulse wants. */
-const sine = (x) => (1 - Math.cos(Math.PI * x)) / 2;
+const sine = settled((p) => (1 - Math.cos(Math.PI * p)) / 2);
+/**
+ * How close to its rest a spring must come to count as settled: one part in a
+ * thousand of the way it moves, under a colour channel's step (1/255) and
+ * under any cell, so what rounds the spring's value to show it draws the rest
+ * from there on.
+ */
+export const SPRING_REST = 0.001;
+const DEFAULT_SPRING = { stiffness: 100, damping: 10, mass: 1 };
+/**
+ * A damped harmonic oscillator, `m·x″ = −k·x − c·x′`, released at rest one
+ * unit from its equilibrium: the spring every animation library means. Its
+ * progress at `s` seconds is `1 − displacement(s)`, the closed-form solution
+ * of that equation in the regime its damping ratio `ζ = c / 2√(k·m)` puts it
+ * in — ringing past its rest for `ζ < 1`, creeping up to it for `ζ ≥ 1` — and
+ * its `seconds` is its settling time: the first moment after which the
+ * displacement stays within `SPRING_REST`, found once here by `crossing` on
+ * the bracket each regime knows its last crossing lies in, so a sample costs
+ * an exponential and a cosine whatever `x` is. [LAW:no-ambient-temporal-coupling]
+ *
+ * The ease is exactly 1 at `x = 1` (`settled`): settled means at rest. The
+ * `seconds` are the spring's to say, not the caller's: how long it rings is
+ * a fact about its physics, which is why this is the one ease that comes as
+ * a `Timing` — released at rest a unit from where it is going, at 1 when it
+ * has settled there.
+ */
+export function spring(options = {}) {
+    const { stiffness, damping, mass } = { ...DEFAULT_SPRING, ...options };
+    for (const [name, v] of [["stiffness", stiffness], ["damping", damping], ["mass", mass]])
+        positive(`spring ${name}`, v);
+    const w0 = Math.sqrt(stiffness / mass);
+    const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+    const decay = zeta * w0;
+    const { displacement, seconds } = zeta < 1 ? ringing(w0, zeta, decay) : creeping(w0, zeta, decay);
+    return { seconds, ease: settled((p) => 1 - displacement(p * seconds)) };
+}
+/**
+ * Where `|displacement|` falls through `SPRING_REST` between `lo` and `hi`,
+ * by bisection: the caller brackets the last such crossing, the displacement
+ * outside rest at `lo`, inside it at `hi` and falling in size between, and
+ * gets the settling time back to the bits 64 halvings leave.
+ * [LAW:single-enforcer] The one place the rest threshold is read against a
+ * motion.
+ */
+function crossing(displacement, lo, hi) {
+    for (let i = 0; i < 64; i++) {
+        const mid = (lo + hi) / 2;
+        if (Math.abs(displacement(mid)) > SPRING_REST)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return hi;
+}
+/**
+ * Underdamped: `e^(−ζω₀s)·(cos ω_d s + (ζω₀/ω_d) sin ω_d s)` at the damped
+ * frequency `ω_d = ω₀√(1 − ζ²)`. Released at rest, its velocity is
+ * `−(ω₀²/ω_d)·e^(−ζω₀s)·sin ω_d s`, so its extrema sit at `s_k = kπ/ω_d`,
+ * where `|displacement| = e^(−ζω₀·s_k)`, each the same fraction of the last.
+ * The first extremum inside rest is the `K` with `e^(−ζω₀·s_K) ≤ SPRING_REST`;
+ * the spring never leaves rest after it, and before it the displacement
+ * falls in size from the extremum at `s_(K−1)` to its zero at
+ * `(Kπ − atan(ω_d/ζω₀)) / ω_d`, so the settling time is the crossing in that
+ * bracket. The decay envelope control theory reads settling time off would
+ * put it later — by up to half a swing, and without bound as `ζ → 1` — so
+ * the true crossing is found instead, and `seconds` is continuous in `ζ`.
+ */
+function ringing(w0, zeta, decay) {
+    const wd = w0 * Math.sqrt(1 - zeta * zeta);
+    const ratio = decay / wd;
+    const displacement = (s) => Math.exp(-decay * s) * (Math.cos(wd * s) + ratio * Math.sin(wd * s));
+    const K = Math.ceil(Math.log(1 / SPRING_REST) / ((decay * Math.PI) / wd));
+    const extremum = ((K - 1) * Math.PI) / wd;
+    const zero = (K * Math.PI - Math.atan(1 / ratio)) / wd;
+    return { displacement, seconds: crossing(displacement, extremum, zero) };
+}
+/**
+ * Critically damped (`ζ = 1`): `e^(−ω₀s)·(1 + ω₀s)`. Overdamped (`ζ > 1`):
+ * two decaying exponentials at the rates `ζω₀ ∓ ω₀√(ζ² − 1)`, written as such
+ * rather than as `cosh + sinh` so neither grows before the other cancels it.
+ * Both only fall, so the settling time is the one crossing of `SPRING_REST`,
+ * bracketed between zero and a time the slower exponential alone puts it under.
+ */
+function creeping(w0, zeta, decay) {
+    const { displacement, far } = zeta === 1 ? critical(w0) : overdamped(w0, zeta, decay);
+    return { displacement, seconds: crossing(displacement, 0, far) };
+}
+/** `(1 + u)·e^(−u)` in `u = ω₀s`, which is under 10⁻³ from u ≈ 9.24. */
+function critical(w0) {
+    return { displacement: (s) => Math.exp(-w0 * s) * (1 + w0 * s), far: 10 / w0 };
+}
+/**
+ * The slower exponential alone bounds the sum, since the faster one's weight
+ * `1 − ratio` is negative. Its rate `ζω₀ − ω₀√(ζ² − 1)` is written as
+ * `ω₀ / (ζ + √(ζ² − 1))`, the same number without the subtraction, which for
+ * a large `ζ` cancels to zero and would make `far` infinite.
+ */
+function overdamped(w0, zeta, decay) {
+    const root = Math.sqrt(zeta * zeta - 1);
+    const wh = w0 * root;
+    const slow = w0 / (zeta + root);
+    const fast = decay + wh;
+    const ratio = decay / wh;
+    return {
+        displacement: (s) => ((1 + ratio) * Math.exp(-slow * s) + (1 - ratio) * Math.exp(-fast * s)) / 2,
+        far: Math.log((1 + ratio) / (2 * SPRING_REST)) / slow,
+    };
+}
+/**
+ * Robert Penner's bounce (his `easeOutBounce`): a ball dropped onto its rest,
+ * four parabolic arcs each a quarter the height of the last, the constants
+ * his and every library's since. Each arc is the same parabola,
+ * `7.5625·(x − centre)² + floor`, set over its own span of `x`; the spans
+ * are in elevenths of 2.75, where the first arc meets the ground.
+ */
+const BOUNCE_ARCS = [
+    { until: 1 / 2.75, centre: 0, floor: 0 },
+    { until: 2 / 2.75, centre: 1.5 / 2.75, floor: 0.75 },
+    { until: 2.5 / 2.75, centre: 2.25 / 2.75, floor: 0.9375 },
+    { until: Number.POSITIVE_INFINITY, centre: 2.625 / 2.75, floor: 0.984375 },
+];
+const bounce = settled((p) => {
+    // The last arc's `until` is unbounded, so an arc is always found.
+    const arc = BOUNCE_ARCS.find(({ until }) => p < until);
+    return 7.5625 * (p - arc.centre) ** 2 + arc.floor;
+});
+/**
+ * Penner's back curves: a cubic that pulls back past its start before going
+ * (`back-in`), or overshoots its end before settling (`back-out`), by his
+ * overshoot constant 1.70158 — about a tenth of the way. His `(c + 1)·x³ −
+ * c·x²` is written as `x³ + c·x²·(x − 1)`, the same cubic with the overshoot
+ * term a product that is exactly zero at both ends, so the curve starts on 0
+ * and lands on 1 to the bit.
+ */
+const BACK_OVERSHOOT = 1.70158;
+const backIn = settled((p) => p ** 3 + BACK_OVERSHOOT * p ** 2 * (p - 1));
+const backOut = settled((p) => {
+    const q = p - 1;
+    return 1 + q ** 3 + BACK_OVERSHOOT * q ** 2 * (q + 1);
+});
+/**
+ * Penner's elastic (his `easeOutElastic`): overshoots its end and rings back
+ * through it, with a period of 0.3 of the way under an amplitude of
+ * `2^(−10x)`, so each swing is `2^(−1.5)`, a little over a third, of the
+ * last — `2^(−10x)·sin((10x − 0.75)·2π/3) + 1`.
+ */
+const ELASTIC_PERIOD = (2 * Math.PI) / 3;
+const elastic = settled((p) => 2 ** (-10 * p) * Math.sin((10 * p - 0.75) * ELASTIC_PERIOD) + 1);
 /**
  * Every built-in ease by the name a template spells it with — CSS's keyword
  * names, plus `sine`, plus `step`: the spelling `ColorRamp` used before this
  * vocabulary existed, kept so every template written against it renders the
- * same. It is CSS's `step-end`, the same function value.
+ * same. It is CSS's `step-end`, the same function value. Then the
+ * physics-flavoured curves: `spring` is the default `spring()`, whose
+ * `seconds` are `DEFAULT_SPRING`'s; the rest are Penner's at his constants.
  */
 export const EASES = {
     linear,
@@ -130,6 +303,11 @@ export const EASES = {
     "step-end": stepEnd,
     step: stepEnd,
     sine,
+    spring: spring().ease,
+    bounce,
+    "back-in": backIn,
+    "back-out": backOut,
+    elastic,
 };
 /**
  * The gate a spelled ease crosses. [LAW:parse-dont-validate] — a name in, the
@@ -143,10 +321,14 @@ export function parseEase(name) {
     }
     return EASES[name];
 }
-function positiveSeconds(what, seconds) {
-    if (!Number.isFinite(seconds) || seconds <= 0) {
-        throw new RangeError(`${what} must be a positive number of seconds, got ${seconds}`);
-    }
+/** `v` is a positive, finite number, or this throws naming `what`; `unit` is the number's noun, as in `" of seconds"`. [LAW:single-enforcer] */
+function positive(what, v, unit = "") {
+    if (!(Number.isFinite(v) && v > 0))
+        throw new RangeError(`${what} must be a positive number${unit}, got ${v}`);
+}
+/** Throws, naming `what`, unless `seconds` is a positive, finite number of seconds. */
+export function positiveSeconds(what, seconds) {
+    positive(what, seconds, " of seconds");
 }
 /**
  * The seconds into the current pass of a `period` at `t`: `t` taken modulo
@@ -181,8 +363,70 @@ function nextUp(x) {
 }
 const DOUBLE = new Float64Array(1);
 const BITS = new BigUint64Array(DOUBLE.buffer);
-/** How many ulps the two roundings in `Beat.start`'s sum can put it under the hold's boundary; a walk past this is a hold too fine for the time. */
+/** How many ulps the roundings in a sum naming a boundary can put it under that boundary; a walk past this is a boundary finer than time resolves there. */
 const ULPS_OF_ROUNDING = 8;
+/**
+ * The first float from `sum` up at which `reached` holds: a time built as a
+ * sum to land on a boundary — where a hold begins, where an animation's next
+ * part changes — that rounding put an ulp or two under it, walked up to the
+ * first moment on the far side. [LAW:single-enforcer] The one walk, so every
+ * boundary a time is carried onto is the moment the change shows, to the
+ * float. A walk longer than rounding can cost throws `finer()`'s message: the
+ * boundary is narrower than the floats around it are apart.
+ */
+export function walkUp(sum, reached, finer) {
+    let x = sum;
+    for (let walked = 0; !reached(x); walked++) {
+        if (walked === ULPS_OF_ROUNDING)
+            throw new RangeError(finer());
+        x = nextUp(x);
+    }
+    return x;
+}
+/**
+ * The least float at which `reached` holds, `reached` being false up to some
+ * float and true from it on, found from `near`, a guess at it on either
+ * side. Where `walkUp` carries a sum onto a boundary on its own clock, and
+ * an ulp or two is all rounding can cost, this carries a moment across
+ * clocks (`./timeline.ts`): a host float is a step of `rate` on the
+ * animation's clock, so the host floats between the guess and the first one
+ * past the boundary are as many as the two clocks' resolutions are apart,
+ * which no cap bounds and is no error. The bracket is found by doubling the
+ * step out from `near`, and halved to two adjacent floats, so the answer is
+ * exact to the float and the cost is logarithmic in that distance.
+ */
+export function firstReaching(near, reached) {
+    // [LAW:no-silent-failure] A step out from an infinite guess is NaN, and a
+    // bracket of NaN never closes.
+    if (!Number.isFinite(near))
+        throw new RangeError(`firstReaching needs a finite guess, got ${near}`);
+    let lo = near;
+    let hi = near;
+    // Out from `near` until the bracket is `lo` short of the boundary and
+    // `hi` past it, within the finite floats: reached at the least of them,
+    // it is reached always; not reached at the greatest, never.
+    for (let step = nextUp(Math.abs(near)) - Math.abs(near); reached(lo); step *= 2) {
+        if (lo === -Number.MAX_VALUE)
+            return Number.NEGATIVE_INFINITY;
+        hi = lo;
+        lo = Math.max(near - step, -Number.MAX_VALUE);
+    }
+    for (let step = nextUp(Math.abs(near)) - Math.abs(near); !reached(hi); step *= 2) {
+        if (hi === Number.MAX_VALUE)
+            return Number.POSITIVE_INFINITY;
+        lo = hi;
+        hi = Math.min(near + step, Number.MAX_VALUE);
+    }
+    for (;;) {
+        const mid = lo + (hi - lo) / 2;
+        if (mid <= lo || mid >= hi)
+            return hi;
+        if (reached(mid))
+            hi = mid;
+        else
+            lo = mid;
+    }
+}
 /** `holds` as a `Beat`; a beat with no hold, or a hold that is not a positive number of seconds, throws. */
 export function beat(holds) {
     if (holds.length === 0)
@@ -218,18 +462,7 @@ export function beat(holds) {
     // then read it as the hold before, so it is walked up to the first float
     // `at` places in the hold. The walk is a function of the pass and the hold
     // alone, so every `t` in the hold still answers one float.
-    const boundary = (what, pass, i, t) => {
-        let began = pass * period + starts[i];
-        for (let walked = 0; index(wrapSeconds(what, began, period)) !== i; walked++) {
-            // The sum is off by the rounding of two operations, under the few
-            // ulps allowed here; a walk that long means the hold is narrower
-            // than the floats around `t` are apart, so no float starts it.
-            if (walked === ULPS_OF_ROUNDING)
-                throw new RangeError(`${what}: hold ${i} (${own[i]} s) is finer than time resolves near t = ${t}`);
-            began = nextUp(began);
-        }
-        return began;
-    };
+    const boundary = (what, pass, i, t) => walkUp(pass * period + starts[i], (began) => index(wrapSeconds(what, began, period)) === i, () => `${what}: hold ${i} (${own[i]} s) is finer than time resolves near t = ${t}`);
     // Which pass `t` is in, as a whole number: `t - into` is a whole number of
     // periods but for rounding, which `round` takes off; carrying `starts[i]`
     // out of `t` itself would leave each sample its own rounding.
@@ -240,16 +473,16 @@ export function beat(holds) {
         at(t) {
             return index(wrapSeconds("Beat.at", t, period));
         },
-        start(t) {
-            const into = wrapSeconds("Beat.start", t, period);
-            return boundary("Beat.start", pass(t, into), index(into), t);
+        lastChange(t) {
+            const into = wrapSeconds("Beat.lastChange", t, period);
+            return boundary("Beat.lastChange", pass(t, into), index(into), t);
         },
         // The next hold's start, in the next pass when this hold is the last.
-        end(t) {
-            const into = wrapSeconds("Beat.end", t, period);
+        nextChange(t) {
+            const into = wrapSeconds("Beat.nextChange", t, period);
             const i = index(into);
             const last = i === own.length - 1;
-            return boundary("Beat.end", pass(t, into) + (last ? 1 : 0), last ? 0 : i + 1, t);
+            return boundary("Beat.nextChange", pass(t, into) + (last ? 1 : 0), last ? 0 : i + 1, t);
         },
     };
 }

package/dist/core/json.js

@@ -8,6 +8,7 @@
  */
 import { RichText } from "./text.js";
 import { JSONHighlighter } from "./highlighter.js";
+import { render } from "./protocol.js";
 const highlighter = new JSONHighlighter();
 export class JSONRenderable {
     text;
@@ -45,7 +46,7 @@ export class JSONRenderable {
         return new JSONRenderable(text);
     }
     *render(options) {
-        yield* this.text.render(options);
+        yield* render(this.text, options);
     }
     measure(options) {
         return this.text.measure(options);

package/dist/core/measure.js

@@ -1,7 +1,7 @@
 /**
  * Measurement — min/max cell width calculation for renderables.
  */
-import { isMeasurable, measuring } from "./protocol.js";
+import { drawsNothing, isMeasurable, measuring } from "./protocol.js";
 export class Measurement {
     minimum;
     maximum;
@@ -45,7 +45,7 @@ export class Measurement {
     // `Measurement.get` answers for it — so under an unbounded offer it asks for
     // `Infinity`, and `withBoundedWidth` refuses rather than guessing a width.
     static get(options, renderable) {
-        if (options.maxWidth < 1)
+        if (drawsNothing(options))
             return new Measurement(0, 0);
         if (!isMeasurable(renderable))
             return new Measurement(0, options.maxWidth);

package/dist/core/place.js

@@ -19,6 +19,7 @@
  */
 import { Segment } from "./segment.js";
 import { Measurement } from "./measure.js";
+import { render } from "./protocol.js";
 // The share of the spare cells that goes on the left; the rest go on the right.
 // Right-alignment pads no right side at all, which is the reference's choice
 // and not a zero: a line that ends at the edge carries no trailing blanks.
@@ -39,7 +40,7 @@ export function placeBlock(renderable, align, options) {
     // (`Measurement.get` answers for it), and the block is then only as wide as
     // what it actually drew.
     const width = Measurement.get(options, renderable).maximum;
-    const drawn = Segment.splitLines(renderable.render({ ...options, maxWidth: width, height: undefined }));
+    const drawn = Segment.splitLines(render(renderable, { ...options, maxWidth: width, height: undefined }));
     const [blockWidth, height] = Segment.getShape(drawn);
     const [left, right] = PADS[align](Math.max(0, options.maxWidth - blockWidth));
     return Segment.setShape(drawn, blockWidth, height).map((line) => [...pad(left), ...line, ...pad(right)]);

package/dist/core/pretty.js

@@ -21,7 +21,7 @@ import { divideLine } from "./wrap.js";
 import { Segment } from "./segment.js";
 import { RichText, stripControlChars } from "./text.js";
 import { ReprHighlighter } from "./highlighter.js";
-import { drawable } from "./protocol.js";
+import { drawable, render } from "./protocol.js";
 const reprHighlighter = new ReprHighlighter();
 /**
  * What a value is bounded by when whoever formats it has not seen it:
@@ -491,7 +491,7 @@ export class Pretty {
     *render(options) {
         // `toText` has no `end`, for callers that set it inside a line; rendered,
         // a `Pretty` is a block of its own, as the reference's is.
-        yield* this.toText(options).render(options);
+        yield* render(this.toText(options), options);
         yield Segment.line();
     }
     /** The value laid out for `options.maxWidth` and highlighted: the text this renders. */