@promptctl/rich-js 0.23.0 → 0.24.1

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,170 @@ 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
+ * the period, into [0, period), before zero too. [LAW:single-enforcer] The
+ * one wrap `Phase.loop` and `beat` both read time through, so a `t` that is
+ * not a finite number of seconds fails here, loudly, and nowhere else. A
+ * `t` at or past zero is `t % period` alone, which is exact; only a negative
+ * `t` is carried up by a period, so a boundary a host samples exactly lands
+ * on the pass that begins there, and the answer is always under the period.
+ */
+function wrapSeconds(what, t, period) {
+    if (!Number.isFinite(t))
+        throw new RangeError(`${what} needs a finite t, got ${t}`);
+    const into = t % period;
+    if (into >= 0)
+        return into;
+    // A negative epsilon carried up rounds to the period itself; that is the
+    // start of the next pass, never a point past the end of this one.
+    const carried = into + period;
+    return carried >= period ? 0 : carried;
+}
+/**
+ * The float after `x`: one ulp up, away from zero for a positive `x` and
+ * toward it for a negative one, read through the bits of the double.
+ */
+function nextUp(x) {
+    if (x === 0)
+        return Number.MIN_VALUE;
+    DOUBLE[0] = x;
+    BITS[0] = BITS[0] + (x > 0 ? 1n : -1n);
+    return DOUBLE[0];
+}
+const DOUBLE = new Float64Array(1);
+const BITS = new BigUint64Array(DOUBLE.buffer);
+/** 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)
+        throw new RangeError("a beat needs at least one hold");
+    holds.forEach((hold, i) => positiveSeconds(`beat hold ${i}`, hold));
+    const period = holds.reduce((sum, hold) => sum + hold, 0);
+    // Where each hold begins, in seconds into the period: the unit
+    // `wrapSeconds` answers in, so the sum a boundary sits at is the number
+    // the wrap of a `t` on that boundary produces, and the hold that begins
+    // there is the one in progress, at any rate the host samples.
+    const starts = [];
+    let elapsed = 0;
+    for (const hold of holds) {
+        starts.push(elapsed);
+        elapsed += hold;
+    }
+    // A copy, and the one `at` walks: what `at` and `period` were built from
+    // stays what `holds` says whatever the caller does to its array.
+    const own = [...holds];
+    // The last hold whose start the time has reached. The first starts at
+    // 0, so the walk always stops, and its length is the count of holds,
+    // never a function of `t`.
+    const index = (into) => {
+        let i = own.length - 1;
+        while (starts[i] > into)
+            i--;
+        return i;
+    };
+    // Where hold `i` of pass `pass` begins: the pass's start plus the hold's,
+    // two integers and two constants, so every `t` in the hold builds the one
+    // float. That sum can land an ulp or two under the boundary when the holds
+    // are not exact in binary — a tenth of a second is not — and `at` would
+    // 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) => 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.
+    const pass = (t, into) => Math.round((t - into) / period);
+    return {
+        holds: own,
+        period,
+        at(t) {
+            return index(wrapSeconds("Beat.at", t, period));
+        },
+        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.
+        nextChange(t) {
+            const into = wrapSeconds("Beat.nextChange", t, period);
+            const i = index(into);
+            const last = i === own.length - 1;
+            return boundary("Beat.nextChange", pass(t, into) + (last ? 1 : 0), last ? 0 : i + 1, t);
+        },
+    };
 }
 /** The three phase shapes. Each takes seconds and returns a `Phase`. */
 export const Phase = {
@@ -160,7 +498,7 @@ export const Phase = {
     /** 0 → 1 every `period` seconds, wrapping back to 0; negative `t` wraps too. */
     loop(period) {
         positiveSeconds("Phase.loop period", period);
-        return (t) => (((t % period) + period) % period) / period;
+        return (t) => wrapSeconds("Phase.loop", t, period) / period;
     },
     /** 0 → 1 → 0 every `period` seconds: there in the first half, back in the second. */
     pingPong(period) {

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. */

package/dist/core/protocol.d.ts

@@ -3,7 +3,7 @@
  * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
  */
 import type { Segment } from "./segment.js";
-import { type Style, type StyleSyntaxError, type Theme } from "./style.js";
+import { Style, type StyleSyntaxError, type Theme } from "./style.js";
 import { ColorDepth } from "./color.js";
 import type { Highlighter } from "./highlighter.js";
 /**
@@ -87,15 +87,21 @@ export interface RenderOptions {
      */
     onStyleError?: StyleErrorHandler;
     /**
-     * Told of each owner that stamps its output (`core/anchor`) as it starts to
-     * render, so the calls arrive in document order: a container's children in
-     * the order it renders them, an owner before the owners nested in it. A
-     * container forwards it by passing its options on, which every container
-     * does. An owner rendered twice is told twice. A render made to measure is
-     * not drawing and is not told (`measuring`).
+     * Told of every renderable `render` is asked for, as it is asked, so the
+     * calls arrive in document order: a container before what it holds, its
+     * contents in the order it renders them. `"drawn"` is a renderable drawn at
+     * the width it was handed; `"held"` is one handed no column, which is still
+     * in the view but has nothing drawn for it (`render`). A renderable rendered
+     * twice is told twice. A render made to measure is not drawing and is not
+     * told (`measuring`).
      */
-    onDraw?: (owner: object) => void;
+    onPresent?: (renderable: Renderable, presence: Presence) => void;
 }
+/**
+ * Whether a renderable the view holds was drawn, or held: in the view, handed
+ * no column, and so not drawn (`render`).
+ */
+export type Presence = "drawn" | "held";
 /** Whether `text` is all ASCII — what an `asciiOnly` output can draw. */
 export declare const isAscii: (text: string) => boolean;
 /**
@@ -210,7 +216,10 @@ export declare function getStyle(options: RenderOptions, style: string | Style):
  * every bundled theme. So where the depth would turn a fixed colour of the
  * pair into a slot, the pair is dropped and the run is drawn on the
  * terminal's own foreground and background, which its theme does make
- * readable; its attributes still set it apart. A style whose colours are
+ * readable; its attributes still set it apart. Both are named, not left
+ * unset, so the colour of whatever the run sits in — a quote, a link — does
+ * not show through: Rich's code keeps its own colours inside a quote, and the
+ * terminal's are the ones it keeps here. A style whose colours are
  * slots already (`white on blue`), or that paints no ground (`bold magenta`),
  * was written for the terminal's own colours and is drawn as written. Rich
  * draws a highlighted line number the same way below 256 colours
@@ -238,6 +247,40 @@ export declare function groundedStyle(options: RenderOptions, style: Style): Sty
  * ignored the request and emitted its full natural width.
  */
 export declare function withCellWidth(options: RenderOptions): RenderOptions;
+/** Under one column there is nothing to draw, or to measure. */
+export declare function drawsNothing(options: {
+    readonly maxWidth: number;
+}): boolean;
+/**
+ * `renderable` drawn under `options`: Rich's `Console.render`, which every
+ * renderable there is drawn through, so under one column nothing is.
+ *
+ * [LAW:single-enforcer] The one place that rule is kept. Every call of a
+ * `Renderable`'s `render` in `src/` goes through here — a container drawing
+ * its child, a renderable drawing the text it built, a host drawing a frame —
+ * and `test/seam/render-calls.test.ts` fails on one that does not. Before
+ * this, each container asked `drawsNothing` itself, and the ones that forgot
+ * drew a child handed no column anyway.
+ *
+ * It is also the one reporter of what the view holds (`onPresent`). Under one
+ * column a renderable is held, not drawn: what it holds (`Composite`) is
+ * walked and reported held in turn, and nothing renders, so no renderable
+ * that keeps state while it renders — a `Viewport`'s offset, a `TextInput`'s
+ * scroll window — ever commits it at a width that is not shown. The walk runs
+ * whether or not anyone listens. Drawing the squeezed subtree at one column
+ * instead, and dropping what it drew, did commit that state.
+ */
+export declare function render(renderable: Renderable, options: RenderOptions): Iterable<Segment>;
+/**
+ * `options` as a measurement is asked with. A `measure` that renders to learn
+ * its shape draws nothing on the frame, so it reports nothing to `onPresent` —
+ * one that did would put a widget in the view at the moment a container
+ * measured it, and keep one the frame then cropped away.
+ *
+ * [LAW:single-enforcer] Every measurement starts here: `Measurement.get` and
+ * `withBoundedWidth` ask through it, and each `measure` passes it on.
+ */
+export declare function measuring(options: RenderOptions): RenderOptions;
 /**
  * The options a renderable should *lay out against*: `withCellWidth`, with an
  * unbounded offer resolved to the renderable's own natural width.
@@ -273,16 +316,6 @@ export declare function withCellWidth(options: RenderOptions): RenderOptions;
  * rather than zero, and saying so names the cause — where `String.repeat` and
  * `new Array` only ever name their own argument.
  */
-/**
- * `options` as a measurement is asked with. A `measure` that renders to learn
- * its shape draws nothing on the frame, so it reports no owner to `onDraw` —
- * one that did would put a widget in document order at the moment a
- * container measured it, and keep one the frame then cropped away.
- *
- * [LAW:single-enforcer] Every measurement starts here: `Measurement.get` and
- * `withBoundedWidth` ask through it, and each `measure` passes it on.
- */
-export declare function measuring(options: RenderOptions): RenderOptions;
 export declare function withBoundedWidth(options: RenderOptions, self: Measurable): RenderOptions;
 export interface Renderable {
     render(options: RenderOptions): Iterable<Segment>;
@@ -293,6 +326,26 @@ export interface Measurable {
         maximum: number;
     };
 }
+/**
+ * A container: a renderable that draws other renderables. `contents` is what
+ * its `render` hands to `render`, in that order where the order is not a
+ * width's, decided as the render decides it — and so it is how a container
+ * handed no column still reports what it holds (`render`). It takes no
+ * options: what a container holds may depend on its state (a hidden `Layout`
+ * holds nothing) but never on a width, because under one column there is none.
+ * It commits no state, and yields only renderables: text a container builds
+ * from a string it holds holds nothing.
+ *
+ * [LAW:one-source-of-truth] A second description of each container's
+ * traversal, so `test/renderables/contents.test.ts` holds every exported
+ * renderable's `contents` to what its `render` reports.
+ *
+ * A consumer's container that does not implement it reports nothing it holds
+ * while it is handed no column.
+ */
+export interface Composite {
+    contents(): Iterable<Renderable>;
+}
 /**
  * What the wheel scrolls: an owner of anchors on the frame (`./anchor.ts`)
  * that moves by lines. `canScrollBy` says whether `scrollBy` with the same
@@ -305,3 +358,4 @@ export interface Scrollable {
 export declare function isRenderable(obj: unknown): obj is Renderable;
 export declare function isMeasurable(obj: unknown): obj is Measurable;
 export declare function isScrollable(obj: object): obj is Scrollable;
+export declare function isComposite(obj: object): obj is Composite;