@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/measure.js

@@ -1,7 +1,7 @@
 /**
  * Measurement — min/max cell width calculation for renderables.
  */
-import { measuring } from "./protocol.js";
+import { isMeasurable, measuring } from "./protocol.js";
 export class Measurement {
     minimum;
     maximum;
@@ -40,20 +40,25 @@ export class Measurement {
     clamp(minWidth, maxWidth) {
         return new Measurement(Math.min(Math.max(this.minimum, minWidth), maxWidth), Math.min(Math.max(this.maximum, minWidth), maxWidth));
     }
-    // [LAW:single-enforcer] Single entry point for measuring a Measurable
-    static get(options, measurable) {
+    // [LAW:single-enforcer] Single entry point for measuring a renderable. One
+    // that cannot measure itself asks for the whole offer, as the reference's
+    // `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)
             return new Measurement(0, 0);
-        const { minimum, maximum } = measurable.measure(measuring(options));
+        if (!isMeasurable(renderable))
+            return new Measurement(0, options.maxWidth);
+        const { minimum, maximum } = renderable.measure(measuring(options));
         return new Measurement(minimum, Math.min(maximum, options.maxWidth)).normalize();
     }
 }
-export function measureRenderables(options, measurables) {
-    if (measurables.length === 0)
+export function measureRenderables(options, renderables) {
+    if (renderables.length === 0)
         return new Measurement(0, 0);
     let minOfAll = 0;
     let maxOfAll = 0;
-    for (const m of measurables) {
+    for (const m of renderables) {
         const measurement = Measurement.get(options, m);
         minOfAll = Math.max(minOfAll, measurement.minimum);
         maxOfAll = Math.max(maxOfAll, measurement.maximum);

package/dist/core/memo.d.ts

@@ -0,0 +1,19 @@
+/**
+ * memo — a string-keyed memo with a size bound: the one cache shape for a
+ * pure computation whose keys a long-running host derives without end. A
+ * statusline daemon redrawing a time-varying colour parses a new hex string,
+ * matches a new RGB triple, measures a new cell, on every frame; a memo that
+ * never evicts grows by one entry per frame for the life of the process.
+ */
+export declare const MEMO_MAX = 4096;
+/**
+ * `get(key, compute)` returns the value remembered for `key`, computing and
+ * remembering it on a miss. Holds at most `MEMO_MAX` entries. `compute` must
+ * be a pure function of `key`, so a value recomputed after a clear is the one
+ * that was dropped.
+ */
+export declare class Memo<V extends NonNullable<unknown>> {
+    private readonly entries;
+    get size(): number;
+    get(key: string, compute: (key: string) => V): V;
+}

package/dist/core/memo.js

@@ -0,0 +1,34 @@
+/**
+ * memo — a string-keyed memo with a size bound: the one cache shape for a
+ * pure computation whose keys a long-running host derives without end. A
+ * statusline daemon redrawing a time-varying colour parses a new hex string,
+ * matches a new RGB triple, measures a new cell, on every frame; a memo that
+ * never evicts grows by one entry per frame for the life of the process.
+ */
+// [LAW:single-enforcer] The one size policy for every memo in the library.
+// Clearing at the cap rather than evicting least-recently-used: a refill costs
+// one recomputation per key, and a clear needs no bookkeeping on the hit path.
+export const MEMO_MAX = 4096;
+/**
+ * `get(key, compute)` returns the value remembered for `key`, computing and
+ * remembering it on a miss. Holds at most `MEMO_MAX` entries. `compute` must
+ * be a pure function of `key`, so a value recomputed after a clear is the one
+ * that was dropped.
+ */
+export class Memo {
+    entries = new Map();
+    get size() {
+        return this.entries.size;
+    }
+    get(key, compute) {
+        const remembered = this.entries.get(key);
+        if (remembered !== undefined)
+            return remembered;
+        // Computed before the clear, so a compute that throws costs no entries.
+        const value = compute(key);
+        if (this.entries.size >= MEMO_MAX)
+            this.entries.clear();
+        this.entries.set(key, value);
+        return value;
+    }
+}

package/dist/core/noise.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Gradient noise, the texture every effect in `renderables/effects` is drawn
+ * from. Ken Perlin's improved noise (2002): a smooth pseudo-random
+ * field over space and time, continuous in its first and second derivatives,
+ * so a cell sampled a moment later has moved a little, never jumped. Things
+ * the eye knows as alive — water, wind, breath, a glow — vary like this:
+ * coherent nearby, uncorrelated far apart, never repeating exactly.
+ *
+ * [LAW:no-ambient-temporal-coupling] A pure function of its coordinates; time
+ * is one of them. The permutation is fixed, so a moment draws the same frame
+ * on every run.
+ *
+ * Tier 0 of `src/core/`: imports nothing. Not part of the package's surface;
+ * the effects playground reaches it as source.
+ */
+/** Noise at (x, y, z), in about [-1, 1]; zero at every integer lattice point. */
+export declare function noise(x: number, y: number, z: number): number;
+/**
+ * Fractal Brownian motion: `octaves` layers of noise, each twice the
+ * frequency and half the amplitude of the last, scaled back into about
+ * [-1, 1]. One layer is a soft swell; three is a swell with detail on it.
+ */
+export declare function fbm(x: number, y: number, z: number, octaves: number): number;
+/**
+ * A pseudo-random number in [0, 1) for the `n`th of something — a breath, a
+ * gust — uncorrelated with the `n ± 1`th, where `noise` would make
+ * neighbours alike. The classic shader hash: the fraction of a large sine.
+ */
+export declare function hash(n: number, z: number): number;
+/** Hermite smoothstep from `a` to `b`, clamped to [0, 1]. */
+export declare function smoothstep(a: number, b: number, x: number): number;

package/dist/core/noise.js

@@ -0,0 +1,94 @@
+/**
+ * Gradient noise, the texture every effect in `renderables/effects` is drawn
+ * from. Ken Perlin's improved noise (2002): a smooth pseudo-random
+ * field over space and time, continuous in its first and second derivatives,
+ * so a cell sampled a moment later has moved a little, never jumped. Things
+ * the eye knows as alive — water, wind, breath, a glow — vary like this:
+ * coherent nearby, uncorrelated far apart, never repeating exactly.
+ *
+ * [LAW:no-ambient-temporal-coupling] A pure function of its coordinates; time
+ * is one of them. The permutation is fixed, so a moment draws the same frame
+ * on every run.
+ *
+ * Tier 0 of `src/core/`: imports nothing. Not part of the package's surface;
+ * the effects playground reaches it as source.
+ */
+/** Ken Perlin's reference permutation, doubled so a lookup never wraps. */
+const P = (() => {
+    const base = [
+        151, 160, 137, 91, 90, 15, 131, 13, 201, 95, 96, 53, 194, 233, 7, 225, 140, 36, 103, 30, 69, 142, 8, 99, 37, 240, 21, 10,
+        23, 190, 6, 148, 247, 120, 234, 75, 0, 26, 197, 62, 94, 252, 219, 203, 117, 35, 11, 32, 57, 177, 33, 88, 237, 149, 56, 87,
+        174, 20, 125, 136, 171, 168, 68, 175, 74, 165, 71, 134, 139, 48, 27, 166, 77, 146, 158, 231, 83, 111, 229, 122, 60, 211,
+        133, 230, 220, 105, 92, 41, 55, 46, 245, 40, 244, 102, 143, 54, 65, 25, 63, 161, 1, 216, 80, 73, 209, 76, 132, 187, 208,
+        89, 18, 169, 200, 196, 135, 130, 116, 188, 159, 86, 164, 100, 109, 198, 173, 186, 3, 64, 52, 217, 226, 250, 124, 123, 5,
+        202, 38, 147, 118, 126, 255, 82, 85, 212, 207, 206, 59, 227, 47, 16, 58, 17, 182, 189, 28, 42, 223, 183, 170, 213, 119,
+        248, 152, 2, 44, 154, 163, 70, 221, 153, 101, 155, 167, 43, 172, 9, 129, 22, 39, 253, 19, 98, 108, 110, 79, 113, 224, 232,
+        178, 185, 112, 104, 218, 246, 97, 228, 251, 34, 242, 193, 238, 210, 144, 12, 191, 179, 162, 241, 81, 51, 145, 235, 249,
+        14, 239, 107, 49, 192, 214, 31, 181, 199, 106, 157, 184, 84, 204, 176, 115, 121, 50, 45, 127, 4, 150, 254, 138, 236, 205,
+        93, 222, 114, 67, 29, 24, 72, 243, 141, 128, 195, 78, 66, 215, 61, 156, 180,
+    ];
+    return [...base, ...base];
+})();
+/** Quintic smoothstep: zero first and second derivative at 0 and 1. */
+const fade = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+const lerp = (a, b, t) => a + t * (b - a);
+/** The dot of one of twelve edge gradients, picked by `hash`, with (x, y, z). */
+function grad(hash, x, y, z) {
+    const h = hash & 15;
+    const u = h < 8 ? x : y;
+    const v = h < 4 ? y : h === 12 || h === 14 ? x : z;
+    return ((h & 1) === 0 ? u : -u) + ((h & 2) === 0 ? v : -v);
+}
+/** Noise at (x, y, z), in about [-1, 1]; zero at every integer lattice point. */
+export function noise(x, y, z) {
+    const fx = Math.floor(x);
+    const fy = Math.floor(y);
+    const fz = Math.floor(z);
+    const X = fx & 255;
+    const Y = fy & 255;
+    const Z = fz & 255;
+    x -= fx;
+    y -= fy;
+    z -= fz;
+    const u = fade(x);
+    const v = fade(y);
+    const w = fade(z);
+    const A = P[X] + Y;
+    const AA = P[A] + Z;
+    const AB = P[A + 1] + Z;
+    const B = P[X + 1] + Y;
+    const BA = P[B] + Z;
+    const BB = P[B + 1] + Z;
+    return lerp(lerp(lerp(grad(P[AA], x, y, z), grad(P[BA], x - 1, y, z), u), lerp(grad(P[AB], x, y - 1, z), grad(P[BB], x - 1, y - 1, z), u), v), lerp(lerp(grad(P[AA + 1], x, y, z - 1), grad(P[BA + 1], x - 1, y, z - 1), u), lerp(grad(P[AB + 1], x, y - 1, z - 1), grad(P[BB + 1], x - 1, y - 1, z - 1), u), v), w);
+}
+/**
+ * Fractal Brownian motion: `octaves` layers of noise, each twice the
+ * frequency and half the amplitude of the last, scaled back into about
+ * [-1, 1]. One layer is a soft swell; three is a swell with detail on it.
+ */
+export function fbm(x, y, z, octaves) {
+    let sum = 0;
+    let amplitude = 1;
+    let total = 0;
+    for (let i = 0; i < octaves; i++) {
+        const f = 2 ** i;
+        sum += amplitude * noise(x * f, y * f, z * f);
+        total += amplitude;
+        amplitude /= 2;
+    }
+    return sum / total;
+}
+/**
+ * A pseudo-random number in [0, 1) for the `n`th of something — a breath, a
+ * gust — uncorrelated with the `n ± 1`th, where `noise` would make
+ * neighbours alike. The classic shader hash: the fraction of a large sine.
+ */
+export function hash(n, z) {
+    const x = Math.sin(n * 12.9898 + z * 78.233) * 43758.5453;
+    return x - Math.floor(x);
+}
+/** Hermite smoothstep from `a` to `b`, clamped to [0, 1]. */
+export function smoothstep(a, b, x) {
+    const t = Math.min(1, Math.max(0, (x - a) / (b - a)));
+    return t * t * (3 - 2 * t);
+}

package/dist/core/osc8.d.ts

@@ -2,7 +2,7 @@
  * The OSC 8 hyperlink wire grammar — which bytes may not appear inside a
  * link, how a link becomes bytes, and how bytes are read back as a link.
  *
- * [LAW:one-source-of-truth] The producer (`segmentsToString`, the one encoder
+ * [LAW:one-source-of-truth] The producer (`segmentToString`, the one encoder
  * every link reaches the wire through) opens a link with `osc8Open` and closes
  * it with `OSC8_CLOSE`; every consumer that reads rendered bytes (a width measure, a
  * test extracting URLs) matches them with `OSC8`; the data-model boundary
@@ -10,16 +10,16 @@
  * terminator set below, so the bytes a sanitizer removes and the bytes a
  * reader stops at cannot disagree.
  *
- * [LAW:locality-or-seam] This module depends on nothing; every consumer
+ * [LAW:locality-or-seam] This module depends only on `fnv1a`; every consumer
  * imports downward.
  *
  * The `id=` parameter is what makes one link hover as one link. A terminal
  * treats cells as the same hyperlink when they share BOTH the URI and the id
  * (the OSC 8 spec, and VTE / iTerm2 / kitty / WezTerm alike); without an id,
- * each open sequence is its own link. The coalescer can only share one OSC 8
- * pair across a run of identical SGR, so a link whose text changes style
- * mid-span — a bold glyph beside plain text, a padded cell — is emitted as
- * several pairs, and would highlight piecewise on hover.
+ * each open sequence is its own link. The encoder writes one OSC 8 pair per
+ * segment, as the reference does, so a link whose text spans several segments
+ * — a bold glyph beside plain text, a padded cell — is emitted as several
+ * pairs, and would highlight piecewise on hover.
  *
  * [LAW:types-are-the-program] The id is a pure function of the URI, so the
  * byte stream stays a pure function of (style, text, destination): no counter,

package/dist/core/osc8.js

@@ -2,7 +2,7 @@
  * The OSC 8 hyperlink wire grammar — which bytes may not appear inside a
  * link, how a link becomes bytes, and how bytes are read back as a link.
  *
- * [LAW:one-source-of-truth] The producer (`segmentsToString`, the one encoder
+ * [LAW:one-source-of-truth] The producer (`segmentToString`, the one encoder
  * every link reaches the wire through) opens a link with `osc8Open` and closes
  * it with `OSC8_CLOSE`; every consumer that reads rendered bytes (a width measure, a
  * test extracting URLs) matches them with `OSC8`; the data-model boundary
@@ -10,16 +10,16 @@
  * terminator set below, so the bytes a sanitizer removes and the bytes a
  * reader stops at cannot disagree.
  *
- * [LAW:locality-or-seam] This module depends on nothing; every consumer
+ * [LAW:locality-or-seam] This module depends only on `fnv1a`; every consumer
  * imports downward.
  *
  * The `id=` parameter is what makes one link hover as one link. A terminal
  * treats cells as the same hyperlink when they share BOTH the URI and the id
  * (the OSC 8 spec, and VTE / iTerm2 / kitty / WezTerm alike); without an id,
- * each open sequence is its own link. The coalescer can only share one OSC 8
- * pair across a run of identical SGR, so a link whose text changes style
- * mid-span — a bold glyph beside plain text, a padded cell — is emitted as
- * several pairs, and would highlight piecewise on hover.
+ * each open sequence is its own link. The encoder writes one OSC 8 pair per
+ * segment, as the reference does, so a link whose text spans several segments
+ * — a bold glyph beside plain text, a padded cell — is emitted as several
+ * pairs, and would highlight piecewise on hover.
  *
  * [LAW:types-are-the-program] The id is a pure function of the URI, so the
  * byte stream stays a pure function of (style, text, destination): no counter,
@@ -30,6 +30,7 @@
  * different URIs merges nothing — the URIs still differ — so a 32-bit hash is
  * exact, not approximate.
  */
+import { fnv1a } from "./fnv1a.js";
 /**
  * The bytes that prematurely terminate an OSC 8 sequence: ESC (`\x1b`, which
  * begins ST `ESC \`), BEL (`\x07`), and the 8-bit ST (`\x9c`).
@@ -40,20 +41,6 @@ const TERMINATOR_RE = new RegExp(`[${TERMINATORS}]`, "g");
 export function stripOscTerminators(url) {
     return url.replace(TERMINATOR_RE, "");
 }
-const utf8 = new TextEncoder();
-/**
- * FNV-1a, 32-bit, over the URL's UTF-8 bytes, as 8 lowercase hex digits — a
- * legal `id=` value (no `:`/`;`). UTF-8 rather than UTF-16 code units, so any
- * other runtime computing standard FNV-1a over the same URL gets the same id.
- */
-function linkId(url) {
-    let h = 0x811c9dc5;
-    for (const byte of utf8.encode(url)) {
-        h ^= byte;
-        h = Math.imul(h, 0x01000193);
-    }
-    return (h >>> 0).toString(16).padStart(8, "0");
-}
 /**
  * The bytes that open a hyperlink to `url`.
  *
@@ -64,7 +51,8 @@ function linkId(url) {
  */
 export function osc8Open(url) {
     const clean = stripOscTerminators(url);
-    return `\x1b]8;id=${linkId(clean)};${clean}\x1b\\`;
+    // Hex digits are a legal `id=` value: no `:` or `;`.
+    return `\x1b]8;id=${fnv1a(clean)};${clean}\x1b\\`;
 }
 /** The bytes that close the current hyperlink. */
 export const OSC8_CLOSE = "\x1b]8;;\x1b\\";

package/dist/core/paint.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Painting frames over one another on a terminal: the bytes that take it,
+ * paint each frame over the last one in place, and hand it back — and, on an
+ * output that is not a terminal, the one frame that is left when it is handed
+ * back.
+ *
+ * [LAW:one-source-of-truth] Where the cursor rests between frames, and how
+ * many rows the next paint goes back over, is one fact, and a `SurfacePainter`
+ * is its only owner: `App` holds one, and so does `Live` on a terminal, so
+ * they cannot disagree about it. They once did: `Live` wrote a newline after its last row, and on a
+ * frame as tall as the terminal that newline scrolled the screen, so every
+ * refresh left the frame's top row behind in scrollback. The cursor rests on
+ * the last row, and the newline that ends it is written once, when the frame
+ * is handed back.
+ */
+import type { Destination } from "./color.js";
+import type { Height } from "./protocol.js";
+import { Segment } from "./segment.js";
+/**
+ * Where a frame is painted. `alternate` is the whole terminal, in the
+ * alternate screen buffer, so the rows printed before it are there again when
+ * it is handed back. `inline` starts at the cursor's line, as tall as the
+ * frame, and stays on the terminal when it is handed back.
+ */
+export type Surface = "alternate" | "inline";
+/** The terminal a frame is painted on, in cells. */
+export interface Screen {
+    readonly rows: number;
+    readonly cols: number;
+}
+/**
+ * A frame not yet drawn: the painter calls it when it is about to put the
+ * frame on the output, so one that never shows a frame never pays to draw it.
+ */
+export type FrameSource = () => Segment[][];
+/**
+ * What paints a run of frames on an output, from `take` to `handBack`.
+ */
+export interface Painter {
+    /** The budget a frame renders under, on a screen `screenRows` tall. */
+    height(screenRows: number): Height;
+    /** Take the output. */
+    take(): void;
+    /**
+     * Paint `frame` over the last frame. `frame` is already shaped to its
+     * height by whoever set its budget. An empty frame erases the last one.
+     */
+    paint(frame: FrameSource, screen: Screen, destination: Destination): void;
+    /**
+     * The bytes that write `text` while `frame` is the frame standing on the
+     * output, for the caller to write in one piece.
+     */
+    around(text: string, frame: FrameSource, screen: Screen, destination: Destination): string;
+    /** Hand the output back. The next `take` starts from wherever it then is. */
+    handBack(): void;
+}
+/**
+ * Paints frames on one surface of a terminal. It holds the last frame's own
+ * rows on the terminal — what the next paint goes back over — from `take` to
+ * `handBack`.
+ */
+export declare class SurfacePainter implements Painter {
+    private readonly write;
+    private readonly geometry;
+    private rows;
+    constructor(surface: Surface, write: (bytes: string) => void);
+    height(screenRows: number): Height;
+    /** Take the terminal: the surface entered, the cursor hidden. */
+    take(): void;
+    /**
+     * Paint `frame` over the last frame, leaving the cursor on its last row,
+     * and return it as painted. No row is wider than the screen, since one that
+     * soft-wrapped would push every row below it down a row the next paint does
+     * not go back over.
+     */
+    paint(frame: FrameSource, screen: Screen, destination: Destination): Segment[][];
+    /**
+     * The frame erased, `text` written, and `frame` painted again on the line
+     * under it — in one string, so no terminal ever shows the frame gone. The
+     * frame fills whole lines, so text that stops mid-line is ended before it.
+     */
+    around(text: string, frame: FrameSource, screen: Screen, destination: Destination): string;
+    private over;
+    /**
+     * Hand the terminal back: style reset, then the cursor shown on the
+     * program's next line, the surface left.
+     */
+    handBack(): void;
+}
+/**
+ * Paints on an output that is not a terminal — a file, a pipe, a CI log — as
+ * Rich's `Live` does: nothing while the frames change, since every one would
+ * stay there for good with the escape sequences that move over it as literal
+ * bytes, and the last frame once, printed as plain lines through `print`, when
+ * the output is handed back. What is written around the frame goes out as it
+ * was given. No frame is drawn but the one handed back.
+ */
+export declare class FinalFramePainter implements Painter {
+    private readonly print;
+    private last;
+    constructor(print: (frame: Segment[][]) => void);
+    height(screenRows: number): Height;
+    take(): void;
+    paint(frame: FrameSource): void;
+    around(text: string): string;
+    handBack(): void;
+}

package/dist/core/paint.js

@@ -0,0 +1,161 @@
+/**
+ * Painting frames over one another on a terminal: the bytes that take it,
+ * paint each frame over the last one in place, and hand it back — and, on an
+ * output that is not a terminal, the one frame that is left when it is handed
+ * back.
+ *
+ * [LAW:one-source-of-truth] Where the cursor rests between frames, and how
+ * many rows the next paint goes back over, is one fact, and a `SurfacePainter`
+ * is its only owner: `App` holds one, and so does `Live` on a terminal, so
+ * they cannot disagree about it. They once did: `Live` wrote a newline after its last row, and on a
+ * frame as tall as the terminal that newline scrolled the screen, so every
+ * refresh left the frame's top row behind in scrollback. The cursor rests on
+ * the last row, and the newline that ends it is written once, when the frame
+ * is handed back.
+ */
+import { segmentsToString } from "./render.js";
+import { Segment } from "./segment.js";
+const GEOMETRY = {
+    alternate: {
+        exact: true,
+        enter: "\x1b[?1049h",
+        // Leaving the buffer puts back the cursor the program had.
+        leave: "\x1b[?1049l",
+        home: () => "\x1b[H",
+        // The frame is every row of the screen, so there is nothing left under it
+        // — and after the terminal shrinks, painting the old count would scroll.
+        painted: (frameRows) => frameRows,
+        below: () => "",
+    },
+    inline: {
+        exact: false,
+        enter: "",
+        leave: "",
+        // After N rows written with N-1 newlines between them, the cursor is on
+        // the last. `ESC[0A` still moves a row on some terminals, so a one-row
+        // frame has no move at all.
+        home: (rows) => (rows > 1 ? `\x1b[${rows - 1}A` : ""),
+        // A shorter frame blanks the rows the last one left below it, as far as
+        // the screen still reaches after a shrink.
+        painted: (frameRows, lastRows, screenRows) => Math.max(frameRows, Math.min(lastRows, screenRows)),
+        // Where the program's next line belongs.
+        below: (rows) => (rows > 0 ? "\n" : ""),
+    },
+};
+// Each row starts at its line's first cell and is erased as it is reached,
+// rather than the frame cleared first, so no blank screen shows between two
+// frames. The erase leads its row: after a row that fills the width, the
+// cursor sits on its last cell, and an erase there would take it.
+const ROW_START = "\r\x1b[2K";
+// A frame's bytes between these two are shown at once: a terminal that has
+// synchronized output (DEC private mode 2026 — iTerm2, kitty, WezTerm,
+// Ghostty, foot, Windows Terminal …) holds the screen until the frame has
+// fully arrived, so a repaint can never show a row erased and not yet
+// redrawn. Thirty full-screen repaints a second show exactly that on a
+// terminal that paints whenever bytes land, as a flicker over the whole
+// frame. A terminal without the mode ignores both sequences.
+const SYNC_START = "\x1b[?2026h";
+const SYNC_END = "\x1b[?2026l";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const RESET_STYLE = "\x1b[0m";
+const fitRows = (frame, screen) => frame.map((line) => Segment.adjustLineLength(line, screen.cols, undefined, false));
+/**
+ * Paints frames on one surface of a terminal. It holds the last frame's own
+ * rows on the terminal — what the next paint goes back over — from `take` to
+ * `handBack`.
+ */
+export class SurfacePainter {
+    write;
+    geometry;
+    rows = 0;
+    constructor(surface, write) {
+        this.write = write;
+        this.geometry = GEOMETRY[surface];
+    }
+    height(screenRows) {
+        return { rows: screenRows, exact: this.geometry.exact };
+    }
+    /** Take the terminal: the surface entered, the cursor hidden. */
+    take() {
+        this.write(this.geometry.enter + HIDE_CURSOR);
+    }
+    /**
+     * Paint `frame` over the last frame, leaving the cursor on its last row,
+     * and return it as painted. No row is wider than the screen, since one that
+     * soft-wrapped would push every row below it down a row the next paint does
+     * not go back over.
+     */
+    paint(frame, screen, destination) {
+        const rows = fitRows(frame(), screen);
+        this.write(SYNC_START + this.over(rows, screen, destination) + SYNC_END);
+        return rows;
+    }
+    /**
+     * The frame erased, `text` written, and `frame` painted again on the line
+     * under it — in one string, so no terminal ever shows the frame gone. The
+     * frame fills whole lines, so text that stops mid-line is ended before it.
+     */
+    around(text, frame, screen, destination) {
+        // Drawn before `over` moves the row count, so a frame that throws leaves
+        // the painter matching the terminal it left untouched.
+        const rows = fitRows(frame(), screen);
+        const erase = this.over([], screen, destination);
+        const ended = text.endsWith("\n") ? text : `${text}\n`;
+        // One synchronized block around all three, so the terminal is released
+        // only once the frame is back.
+        return SYNC_START + erase + ended + this.over(rows, screen, destination) + SYNC_END;
+    }
+    // The bytes that paint `rows` over the last frame. They go out in one
+    // string, so whatever takes the last frame away arrives with the new one.
+    over(rows, screen, destination) {
+        const painted = this.geometry.painted(rows.length, this.rows, screen.rows);
+        const body = Array.from({ length: painted }, (_, row) => ROW_START + segmentsToString(rows[row] ?? [], destination)).join("\n");
+        // Rows blanked below the frame are not the frame's: the cursor goes back
+        // up to its last row, so the next frame and the program's next line start
+        // from the frame's own height.
+        const blanked = painted - Math.max(rows.length, 1);
+        const back = blanked > 0 ? `\x1b[${blanked}A` : "";
+        const bytes = this.geometry.home(this.rows) + body + back;
+        this.rows = rows.length;
+        return bytes;
+    }
+    /**
+     * Hand the terminal back: style reset, then the cursor shown on the
+     * program's next line, the surface left.
+     */
+    handBack() {
+        this.write(RESET_STYLE + SHOW_CURSOR + this.geometry.below(this.rows) + this.geometry.leave);
+        this.rows = 0;
+    }
+}
+/**
+ * Paints on an output that is not a terminal — a file, a pipe, a CI log — as
+ * Rich's `Live` does: nothing while the frames change, since every one would
+ * stay there for good with the escape sequences that move over it as literal
+ * bytes, and the last frame once, printed as plain lines through `print`, when
+ * the output is handed back. What is written around the frame goes out as it
+ * was given. No frame is drawn but the one handed back.
+ */
+export class FinalFramePainter {
+    print;
+    last = () => [];
+    constructor(print) {
+        this.print = print;
+    }
+    height(screenRows) {
+        return { rows: screenRows, exact: false };
+    }
+    take() { }
+    paint(frame) {
+        this.last = frame;
+    }
+    around(text) {
+        return text;
+    }
+    handBack() {
+        const frame = this.last;
+        this.last = () => [];
+        this.print(frame());
+    }
+}

package/dist/core/place.d.ts

@@ -18,7 +18,7 @@
  * interface. [LAW:one-source-of-truth]
  */
 import { Segment } from "./segment.js";
-import { type Renderable, type RenderOptions } from "./protocol.js";
+import type { Renderable, RenderOptions } from "./protocol.js";
 export type Alignment = "left" | "center" | "right";
 /**
  * `renderable`'s lines, the block they form placed by `align` in

package/dist/core/place.js

@@ -19,7 +19,6 @@
  */
 import { Segment } from "./segment.js";
 import { Measurement } from "./measure.js";
-import { isMeasurable } 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.
@@ -36,11 +35,10 @@ const PADS = {
  * its full width, for whatever holds it to crop or keep.
  */
 export function placeBlock(renderable, align, options) {
-    // A renderable that cannot say how wide it wants to be is offered all of it,
-    // and the block is then only as wide as what it actually drew.
-    const width = isMeasurable(renderable)
-        ? Measurement.get(options, renderable).maximum
-        : options.maxWidth;
+    // A renderable that cannot say how wide it wants to be is offered all of it
+    // (`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 [blockWidth, height] = Segment.getShape(drawn);
     const [left, right] = PADS[align](Math.max(0, options.maxWidth - blockWidth));