@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/renderables/traceback.d.ts

@@ -1,7 +1,7 @@
 /**
  * Traceback — renders error tracebacks with formatting.
  *
- * [LAW:effects-at-boundaries] Pure rendering: an `Error` in, `Segment`s out.
+ * [LAW:effects-at-boundaries] Pure rendering: a caught value in, `Segment`s out.
  * Installing this as the process-wide crash handler touches `process.on` and
  * `process.exit`, so that lives behind the node seam as `installTraceback` in
  * `src/node/traceback.ts` — which is what keeps this module, and therefore the
@@ -22,10 +22,11 @@ export interface TracebackOptions {
     maxFrames?: number;
 }
 export declare class Traceback implements Renderable {
-    readonly error: Error;
+    /** What was caught, as it was handed in. */
+    readonly error: unknown;
     readonly maxFrames: number;
     readonly suppress: string[];
-    constructor(error: Error, options?: TracebackOptions);
+    private readonly caught;
+    constructor(error: unknown, options?: TracebackOptions);
     render(options: RenderOptions): Iterable<Segment>;
-    private _renderFrame;
 }

package/dist/renderables/traceback.js

@@ -1,7 +1,7 @@
 /**
  * Traceback — renders error tracebacks with formatting.
  *
- * [LAW:effects-at-boundaries] Pure rendering: an `Error` in, `Segment`s out.
+ * [LAW:effects-at-boundaries] Pure rendering: a caught value in, `Segment`s out.
  * Installing this as the process-wide crash handler touches `process.on` and
  * `process.exit`, so that lives behind the node seam as `installTraceback` in
  * `src/node/traceback.ts` — which is what keeps this module, and therefore the
@@ -16,93 +16,264 @@
  * sized and coloured a source-code excerpt this renderer does not produce.
  */
 import { Segment } from "../core/segment.js";
-import { Style } from "../core/style.js";
-import { getStyle } from "../core/protocol.js";
-function parseStack(error) {
-    const stack = error.stack ?? "";
-    const lines = stack.split("\n");
-    const frames = [];
-    for (const line of lines) {
-        // The two V8 frame shapes located by file:line:column: "at fn (file:…)"
-        // and "at file:…", either one prefixed "async " when the frame is an
-        // awaited call. The marker is not part of any name, so it is read and
-        // dropped; the lookahead keeps "at async (file:…)" — a function named
-        // `async` — a name.
-        const match = /^at\s+(?:async\s+(?!\())?(?:(.+?)\s+\()?(.+?):(\d+):\d+\)?/.exec(line.trim());
-        if (match) {
-            frames.push({
-                function: match[1] || undefined,
-                file: match[2],
-                line: parseInt(match[3], 10),
-            });
-        }
+import { RichText } from "../core/text.js";
+import { Pretty, UNSEEN_DATA_BOUNDS } from "../core/pretty.js";
+import { layoutPadding } from "./padding.js";
+/**
+ * [LAW:parse-dont-validate] The checkpoint between whatever a `catch` caught —
+ * JavaScript lets a program throw any value — and the report. Anything with a
+ * string `name` and a `message` is reported as the error it presents itself
+ * as: that is every native error from any realm, which `instanceof Error`
+ * would refuse for one from a `node:vm` context or an iframe, and any thrower
+ * shaped like one. A message that is not a string — a native error's, assigned
+ * after construction — is formatted by `Pretty` under the error's own name.
+ * Anything else is reported as the value it is, under `NonError`, formatted by
+ * `Pretty` so it reads the same in a browser as in node — with the frames of a
+ * stack it carries, when it carries one.
+ */
+function readCaught(value) {
+    const fields = readFields(value);
+    if (fields !== undefined && typeof fields.name === "string" && fields.hasMessage) {
+        const { name, message } = fields;
+        const text = typeof message === "string" ? message : undefined;
+        return {
+            name: name || "Error",
+            message: text === undefined
+                ? prettyMessage(message)
+                : () => new RichText(text, { style: "traceback.text", end: "" }),
+            frames: parseStack(fields.stack, name, text),
+        };
     }
-    return frames;
+    return { name: "NonError", message: prettyMessage(value), frames: parseStack(fields?.stack ?? "", undefined, undefined) };
+}
+/**
+ * The fields the report reads off a caught object, or `undefined` when it is
+ * not an object or reading them throws — a getter that throws, a `Proxy` whose
+ * trap does. Such a value is reported under `NonError`, where `Pretty` reads
+ * it again and marks the read that threw as `[Threw: …]`, so the fault stays
+ * in the report instead of taking the crash handler down with it.
+ */
+function readFields(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    try {
+        const record = value;
+        const stack = record.stack;
+        return {
+            name: record.name,
+            hasMessage: "message" in record,
+            message: record.message,
+            stack: typeof stack === "string" ? stack : "",
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function prettyMessage(value) {
+    const pretty = new Pretty(value, UNSEEN_DATA_BOUNDS);
+    return (options) => pretty.toText(options);
+}
+/** The first line V8 writes into an error's stack: `String(error)` at the throw. */
+function header(name, message) {
+    if (!name)
+        return message;
+    if (!message)
+        return name;
+    return `${name}: ${message}`;
+}
+/**
+ * Where the header that opens an error's stack ends, or `undefined` when the
+ * stack does not open with the header the error now has.
+ *
+ * V8 writes `String(error)`; node writes its own errors' code into the name
+ * there (`RangeError [ERR_X]: message`), so after the name may come one line of
+ * anything before `: ` and the message.
+ */
+function headerEnd(stack, name, message) {
+    const endsLine = (at) => at === stack.length || stack[at] === "\n";
+    const plain = header(name, message);
+    if (stack.startsWith(plain) && endsLine(plain.length))
+        return plain.length;
+    if (!name || !stack.startsWith(name))
+        return undefined;
+    const tail = `: ${message}`;
+    const at = stack.indexOf(tail, name.length);
+    if (at < 0 || stack.slice(name.length, at).includes("\n"))
+        return undefined;
+    return endsLine(at + tail.length) ? at + tail.length : undefined;
+}
+/**
+ * Whether a stack line is shaped as V8's header — a name, then `:` or nothing —
+ * rather than as a SpiderMonkey or JavaScriptCore frame, whose `@` comes before
+ * the first `:` of its location. Read by shape, not by the error's name,
+ * because the name may have been reassigned after V8 wrote the header too.
+ */
+function isHeaderShaped(line) {
+    const colon = line.indexOf(":");
+    return !(colon < 0 ? line : line.slice(0, colon)).includes("@");
+}
+/**
+ * The frames of a stack, in order.
+ *
+ * V8 opens a stack with the error's header, and a message can span lines that
+ * look like frames, so the header comes off first, as the exact text it is.
+ * When it does not open the stack, the message was reassigned after the throw
+ * and what precedes the first V8 frame is that stale header — all of it, when
+ * V8 recorded no frame, as under `Error.stackTraceLimit = 0`. SpiderMonkey and
+ * JavaScriptCore write no header, so a stack that opens with one of their
+ * frames is all frames. A value that is not an error has no name, so its stack is
+ * read from its first V8 frame, or whole when it has none.
+ */
+function parseStack(stack, name, message) {
+    const end = name !== undefined && message !== undefined ? headerEnd(stack, name, message) : undefined;
+    const lines = stack.slice(end ?? 0).split("\n").map((line) => line.trim()).filter((line) => line !== "");
+    if (end !== undefined)
+        return lines.map(parseFrame);
+    const firstV8 = lines.findIndex((line) => V8_FRAME.test(line));
+    if (firstV8 >= 0)
+        return lines.slice(firstV8).map(parseFrame);
+    return name !== undefined && lines[0] !== undefined && isHeaderShaped(lines[0]) ? [] : lines.map(parseFrame);
+}
+/**
+ * V8 writes `at [async] [fn (]location[)]`. The `async` marker is not part of
+ * any name, so it is read and dropped; the lookahead keeps `at async (…)` — a
+ * function named `async` — a name.
+ */
+const V8_FRAME = /^at\s+(?:async\s+(?!\())?(.*)$/;
+/**
+ * SpiderMonkey and JavaScriptCore write `[fn]@location`, Firefox prefixing an
+ * awaited call's name with a cause up to a `*` (`async*`, `promise callback*`),
+ * which is dropped as V8's `async` is.
+ */
+const AT_SIGN_FRAME = /^(?:[^@]*\*)?([^@]*)@(.*)$/;
+function parseFrame(text) {
+    const v8 = V8_FRAME.exec(text);
+    if (v8) {
+        const body = v8[1];
+        const open = openingParen(body);
+        return open > 0
+            ? locate(body.slice(0, open).trim() || undefined, body.slice(open + 1, -1))
+            : locate(undefined, body);
+    }
+    const atSign = AT_SIGN_FRAME.exec(text);
+    if (atSign)
+        return locate(atSign[1] || undefined, atSign[2]);
+    return { function: undefined, location: text, line: undefined };
+}
+/**
+ * Where the parenthesised location that closes a V8 frame opens, or -1 when
+ * the frame does not end in one. Matched from the end, because an eval
+ * frame's location nests parentheses: `eval (eval at f (file:8:22), …)`.
+ */
+function openingParen(body) {
+    if (!body.endsWith(")"))
+        return -1;
+    let depth = 0;
+    for (let i = body.length - 1; i >= 0; i--) {
+        if (body[i] === ")")
+            depth++;
+        else if (body[i] === "(" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+/**
+ * The shapes a location takes, each read as its file and line, first match
+ * wins. Code run by `eval` or `new Function` has no file of its own, so its
+ * frame is placed at the call that ran it, which is where the source is: V8
+ * nests that site inside the location (`eval at f (file:8:22), <anonymous>:1:1`,
+ * innermost first-parenthesised for an eval inside an eval), and Firefox appends
+ * the code to it (`file line 8 > eval:1:1`).
+ */
+const LOCATIONS = [
+    /^eval at [^]*?\(([^()]+):(\d+):\d+\)/,
+    /^(.*?) line (\d+) > (?:eval|Function)/,
+    /^(.*?):(\d+)(?::\d+)?$/,
+];
+function locate(fn, location) {
+    for (const shape of LOCATIONS) {
+        const match = shape.exec(location);
+        if (match)
+            return { function: fn, location: match[1], line: parseInt(match[2], 10) };
+    }
+    return { function: fn, location, line: undefined };
 }
 export class Traceback {
+    /** What was caught, as it was handed in. */
     error;
     maxFrames;
     suppress;
+    caught;
     constructor(error, options) {
         this.error = error;
+        this.caught = readCaught(error);
         this.maxFrames = options?.maxFrames ?? 100;
         this.suppress = options?.suppress ?? [];
     }
+    // [LAW:single-enforcer] The report is `RichText`, so fitting it to the width
+    // is the one fitting every text in the library gets: a line wider than the
+    // report wraps, and a location wider than the report folds across lines
+    // whole, as Rich's does. Written as bare segments, each line was cropped at
+    // the edge instead, and a frame lost its file and line to a long path.
     *render(options) {
-        const excTypeStyle = getStyle(options, "traceback.exc_type");
-        const textStyle = getStyle(options, "traceback.text");
-        // Error type and message
-        const errorName = this.error.name || "Error";
-        const errorMessage = this.error.message || "";
-        yield new Segment(errorName, excTypeStyle);
-        yield new Segment(": ");
-        yield new Segment(errorMessage, textStyle);
-        yield Segment.line();
-        yield Segment.line();
-        // Stack frames — suppressed frames show file/line only (not removed)
-        const frames = parseStack(this.error);
-        const filteredFrames = this.suppress.length > 0
-            ? frames.map((f) => ({
-                ...f,
-                suppressed: this.suppress.some((s) => f.file.includes(s)),
-            }))
-            : frames;
-        let displayFrames = filteredFrames;
-        if (this.maxFrames > 0 && displayFrames.length > this.maxFrames) {
+        const header = new RichText("", { end: "" });
+        const { name, message } = this.caught;
+        header.append(name, "traceback.exc_type");
+        header.append(": ");
+        // The message starts after the name, so a value `Pretty` lays out fits the
+        // width that is left on that line rather than overrunning it.
+        header.append(message({ ...options, maxWidth: Math.max(1, options.maxWidth - header.cellLength) }));
+        header.append("\n\n");
+        yield* header.render(options);
+        // A suppressed frame keeps its place and shows its file and line only: it
+        // is the same frame with no function name to show.
+        const frames = this.caught.frames.map((frame) => this.suppress.some((s) => frame.location.includes(s)) ? { ...frame, function: undefined } : frame);
+        // One entry per row of the frame block, so a report with no frames has no
+        // rows: empty text is one line, as in Rich, and a block built as one text
+        // drew a blank indented row under every frameless report.
+        let entries;
+        if (this.maxFrames > 0 && frames.length > this.maxFrames) {
             // Spend the budget exactly: the tail takes `maxFrames - head` rather than
             // a second `head`, so an odd budget shows every frame it counts, and it
             // slices from an index because `slice(-0)` is the whole array.
             const head = Math.floor(this.maxFrames / 2);
-            const first = displayFrames.slice(0, head);
-            const last = displayFrames.slice(displayFrames.length - (this.maxFrames - head));
-            const omitted = displayFrames.length - this.maxFrames;
-            for (const frame of first) {
-                yield* this._renderFrame(frame, options);
-            }
-            yield new Segment(`  ... ${omitted} frames omitted ...`, textStyle);
-            yield Segment.line();
-            for (const frame of last) {
-                yield* this._renderFrame(frame, options);
-            }
+            const omitted = frames.length - this.maxFrames;
+            entries = [
+                ...frames.slice(0, head).map(frameEntry),
+                new RichText(`... ${omitted} frames omitted ...`, { style: "traceback.text", end: "" }),
+                ...frames.slice(frames.length - (this.maxFrames - head)).map(frameEntry),
+            ];
         }
         else {
-            for (const frame of displayFrames) {
-                yield* this._renderFrame(frame, options);
+            entries = frames.map(frameEntry);
+        }
+        // The frames are one block set in from the report's edge, so a frame that
+        // wraps continues under itself instead of at the edge, where it read as a
+        // frame of its own. The width is divided as `Padding` divides it; the rows
+        // are not padded out on the right, as `Padding`'s are, because trailing
+        // blanks on every line of a crash report are bytes nobody asked for.
+        const { left, contentWidth } = layoutPadding(options.maxWidth, 2, 0);
+        const indent = new Segment(" ".repeat(left));
+        for (const entry of entries) {
+            for (const line of Segment.splitLines(entry.render({ ...options, maxWidth: contentWidth }))) {
+                yield indent;
+                yield* line;
+                yield Segment.line();
             }
         }
     }
-    *_renderFrame(frame, options) {
-        const pathStyle = Style.parse("dim");
-        const lineNoStyle = getStyle(options, "traceback.offset");
-        yield new Segment("  ");
-        // Spec: suppressed frames show file and line only — no function name
-        if (frame.function && !frame.suppressed) {
-            yield new Segment(frame.function, Style.parse("bold"));
-            yield new Segment(" ");
-        }
-        yield new Segment(frame.file, pathStyle);
-        yield new Segment(":");
-        yield new Segment(String(frame.line), lineNoStyle);
-        yield Segment.line();
+}
+function frameEntry(frame) {
+    const entry = new RichText("", { end: "" });
+    if (frame.function) {
+        entry.append(frame.function, "bold");
+        entry.append(" ");
+    }
+    entry.append(frame.location, "dim");
+    if (frame.line !== undefined) {
+        entry.append(":");
+        entry.append(String(frame.line), "traceback.offset");
     }
+    return entry;
 }

package/dist/renderables/tree.d.ts

@@ -39,7 +39,9 @@ export declare class Tree implements Renderable, Measurable {
      *
      * [LAW:dataflow-not-control-flow] Every node, at every depth, is walked by
      * this one recursion: its children get the columns above it, settled, plus a
-     * branch of their own, so no depth is drawn by a rule of its own.
+     * branch of their own, so no depth is drawn by a rule of its own. A node's
+     * style and its guide style are handed down the same way, as one more entry
+     * on the stack its ancestors built.
      */
     private _rows;
     /**
@@ -58,7 +60,13 @@ export declare class Tree implements Renderable, Measurable {
      * depending on label renderables to invent trailing newlines: the label's
      * output is cut into lines and every line ends where Tree ends it. A label
      * that emits nothing still holds its row, and one that ends in a newline of
-     * its own does not add a blank one.
+     * its own gets the blank row that line is, as in Rich — padded to the label's
+     * width when the label is justified.
+     *
+     * The node's style sits under the label's own, as Rich's `Styled` puts it, so
+     * markup in the label still wins; its background alone reaches under the
+     * guides, so a row with a background is filled from its first guide to the
+     * end of its label.
      */
     private _renderRow;
     measure(options: RenderOptions): {

package/dist/renderables/tree.js

@@ -5,25 +5,31 @@ import { Segment } from "../core/segment.js";
 import { cellFit, cellLen, asCellCol } from "../core/cells.js";
 import { Style, NULL_STYLE } from "../core/style.js";
 import { embed } from "./embed.js";
-import { drawable, getStyle, isMeasurable, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { drawable, getStyle, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
 import { Measurement } from "../core/measure.js";
-const UNICODE_GUIDES = {
-    fork: { first: "├── ", rest: "│   " },
-    end: { first: "└── ", rest: "    " },
-};
-const ASCII_GUIDES = {
-    fork: { first: "+-- ", rest: "|   " },
-    end: { first: "`-- ", rest: "    " },
-};
-const guideGlyphs = ({ fork, end }) => fork.first + fork.rest + end.first + end.rest;
+/** Every glyph of every set is this wide, so a row's guides are as wide however they are drawn. */
+const GUIDE_CELLS = 4;
+const LIGHT_GUIDES = { fork: "├── ", end: "└── ", continue: "│   ", space: "    " };
+const HEAVY_GUIDES = { fork: "┣━━ ", end: "┗━━ ", continue: "┃   ", space: "    " };
+const DOUBLE_GUIDES = { fork: "╠══ ", end: "╚══ ", continue: "║   ", space: "    " };
+const ASCII_GUIDES = { fork: "+-- ", end: "`-- ", continue: "|   ", space: "    " };
 /**
- * How wide a label wants to be. A label with no `measure` cannot say, and the
- * offer is the honest stand-in — including when the offer is unbounded, which
- * is where `withBoundedWidth` reports it rather than guessing a number.
+ * The guide attributes a glyph set stands for, switched off on the guide itself
+ * as Rich's `remove_guide_styles` does: a bold guide is drawn heavy, not bold.
  */
+const REMOVE_GUIDE_STYLES = new Style({ bold: false, underline2: false });
+const guideGlyphs = (glyphs) => Object.values(glyphs).join("");
+/**
+ * The glyphs a column of guide is drawn with, read off its resolved guide style
+ * as Rich does: heavy when bold, double when underline2, light otherwise — and
+ * ASCII whenever the terminal cannot draw the chosen set.
+ */
+function glyphsFor(options, style) {
+    const weight = style.bold === true ? HEAVY_GUIDES : style.underline2 === true ? DOUBLE_GUIDES : LIGHT_GUIDES;
+    return drawable(options, weight, ASCII_GUIDES, guideGlyphs);
+}
+/** How wide a label wants to be. */
 function labelWidth(options, label) {
-    if (!isMeasurable(label))
-        return options.maxWidth;
     return Measurement.get(options, label).maximum;
 }
 export class Tree {
@@ -52,7 +58,7 @@ export class Tree {
     }
     *render(rawOptions) {
         const options = withBoundedWidth(rawOptions, this);
-        for (const row of this._walk(options)) {
+        for (const row of this._walk()) {
             yield* this._renderRow(options, row);
         }
     }
@@ -62,8 +68,8 @@ export class Tree {
      * and the column its children hang from with it, as Rich does — its children
      * stand at the left edge, and its guide style still reaches their guides.
      */
-    _walk(options) {
-        const rows = [...this._rows(drawable(options, UNICODE_GUIDES, ASCII_GUIDES, guideGlyphs), [], [])];
+    _walk() {
+        const rows = [...this._rows([], [], [])];
         return this.hideRoot ? rows.slice(1).map((row) => ({ ...row, guides: row.guides.slice(1) })) : rows;
     }
     /**
@@ -77,16 +83,21 @@ export class Tree {
      *
      * [LAW:dataflow-not-control-flow] Every node, at every depth, is walked by
      * this one recursion: its children get the columns above it, settled, plus a
-     * branch of their own, so no depth is drawn by a rule of its own.
+     * branch of their own, so no depth is drawn by a rule of its own. A node's
+     * style and its guide style are handed down the same way, as one more entry
+     * on the stack its ancestors built.
      */
-    *_rows(glyphs, guides, inherited) {
-        yield { guides, label: this.label };
+    *_rows(guides, inheritedGuideStyles, inheritedStyles) {
+        const styles = [...inheritedStyles, this.style];
+        yield { guides, label: this.label, styles };
         const children = this.expanded ? this.children : [];
-        const styles = [...inherited, this.guideStyle];
+        const guideStyles = [...inheritedGuideStyles, this.guideStyle];
         const above = guides.map((guide) => ({ ...guide, first: guide.rest }));
         for (let i = 0; i < children.length; i++) {
-            const branch = i === children.length - 1 ? glyphs.end : glyphs.fork;
-            yield* children[i]._rows(glyphs, [...above, { ...branch, styles }], styles);
+            const branch = i === children.length - 1
+                ? { first: "end", rest: "space", styles: guideStyles }
+                : { first: "fork", rest: "continue", styles: guideStyles };
+            yield* children[i]._rows([...above, branch], guideStyles, styles);
         }
     }
     /**
@@ -105,23 +116,40 @@ export class Tree {
      * depending on label renderables to invent trailing newlines: the label's
      * output is cut into lines and every line ends where Tree ends it. A label
      * that emits nothing still holds its row, and one that ends in a newline of
-     * its own does not add a blank one.
+     * its own gets the blank row that line is, as in Rich — padded to the label's
+     * width when the label is justified.
+     *
+     * The node's style sits under the label's own, as Rich's `Styled` puts it, so
+     * markup in the label still wins; its background alone reaches under the
+     * guides, so a row with a background is filled from its first guide to the
+     * end of its label.
      */
     *_renderRow(options, row) {
-        const styles = row.guides.map((guide) => Style.combine(guide.styles.map((style) => getStyle(options, style))));
-        const width = Math.max(0, options.maxWidth - row.guides.reduce((sum, guide) => sum + cellLen(guide.first), 0));
+        const resolve = (styles) => Style.combine(styles.map((style) => getStyle(options, style)));
+        const style = resolve(row.styles);
+        const drawn = row.guides.map((guide) => {
+            const guideStyle = resolve(guide.styles);
+            return {
+                glyphs: glyphsFor(options, guideStyle),
+                style: style.backgroundStyle.add(guideStyle).add(REMOVE_GUIDE_STYLES),
+            };
+        });
+        const width = Math.max(0, options.maxWidth - row.guides.length * GUIDE_CELLS);
         // The guides are cropped by `cellFit`; the label is cropped too, so a label
         // that ignores the width it is handed cannot push the row past the offer the
-        // guides were fitted into.
-        const lines = Segment.splitLines(Segment.cropLines(row.label.render({ ...options, maxWidth: width, height: stackedHeight(options.height) }), width));
+        // guides were fitted into. No highlighter: a label is drawn plain, as
+        // Rich's `Tree` hands its labels `highlight=False`.
+        const labelOptions = { ...options, highlight: false, maxWidth: width, height: stackedHeight(options.height) };
+        const lines = Segment.splitLines(Segment.applyStyle(Segment.cropLines(row.label.render(labelOptions), width), style));
         if (lines.length === 0)
             lines.push([]);
         for (let i = 0; i < lines.length; i++) {
             let left = options.maxWidth;
             for (let g = 0; g < row.guides.length; g++) {
-                const piece = cellFit(i === 0 ? row.guides[g].first : row.guides[g].rest, asCellCol(left));
+                const { glyphs, style: guideStyle } = drawn[g];
+                const piece = cellFit(glyphs[i === 0 ? row.guides[g].first : row.guides[g].rest], asCellCol(left));
                 if (piece.length > 0)
-                    yield new Segment(piece, styles[g]);
+                    yield new Segment(piece, guideStyle);
                 left -= cellLen(piece);
             }
             yield* lines[i];
@@ -138,9 +166,8 @@ export class Tree {
         // mode drew a 40-cell frame around nine cells of tree, and an unbounded
         // offer came back unbounded.
         let natural = 0;
-        for (const row of this._walk(parsed)) {
-            const guideWidth = row.guides.reduce((sum, guide) => sum + cellLen(guide.first), 0);
-            natural = Math.max(natural, guideWidth + labelWidth(parsed, row.label));
+        for (const row of this._walk()) {
+            natural = Math.max(natural, row.guides.length * GUIDE_CELLS + labelWidth(parsed, row.label));
         }
         const maximum = Math.min(natural, ceiling);
         // A row is its guides plus at least one cell of label — but never more than

package/dist/renderables/viewport.js

@@ -35,7 +35,7 @@ import { Segment } from "../core/segment.js";
 import { Measurement } from "../core/measure.js";
 import { cellCount, cellLen } from "../core/cells.js";
 import { NULL_STYLE } from "../core/style.js";
-import { drawable, fitHeight, getStyle, isMeasurable, regionRows, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+import { drawable, fitHeight, getStyle, regionRows, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
 /** A heavy line for the thumb on a light line for the track. */
 export const SCROLLBAR = {
     thumb: { glyph: "┃", style: "scrollbar.thumb" },
@@ -155,9 +155,7 @@ export class Viewport {
         const options = withCellWidth(rawOptions);
         const gutter = gutterWidth(this.scrollbar);
         const inner = { ...options, maxWidth: this.contentWidth(options.maxWidth) };
-        const content = isMeasurable(this.content)
-            ? Measurement.get(inner, this.content)
-            : new Measurement(Math.min(1, inner.maxWidth), inner.maxWidth);
+        const content = Measurement.get(inner, this.content);
         return new Measurement(content.minimum + gutter, content.maximum + gutter).withMaximum(options.maxWidth);
     }
 }

package/dist/template-bindings/color-funcs.d.ts

@@ -26,7 +26,7 @@
  *
  * ### The carrier is a hex string, deliberately
  *
- * A color crosses the template seam as `#RRGGBB`, not as an opaque object,
+ * A color crosses the template seam as `#RRGGBB` (or `#RRGGBBAA`), not as an opaque object,
  * for three reasons:
  *
  * 1. **The type separates.** `"string"` is the strictest arg slot the template
@@ -56,12 +56,34 @@
  * the full color vocabulary by feeding it hex literals. [LAW:one-way-deps]
  */
 import type { FuncMap, TemplateFunc } from "@promptctl/go-template-js";
-import { ColorDepth } from "../core/color.js";
+import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js";
 /**
- * The `readableOn` binding, measuring at the depth `drawnAt` names when it is
- * evaluated — a consumer that renders at a per-call depth registers its own.
+ * A colour the colour functions can compute with. A fully transparent one — a
+ * theme's "no background", `#00000000` — has no colour of its own: what shows
+ * through it is whatever surface it lands on, which a template cannot know.
+ * Darkening, mixing or contrasting it would answer for a surface nobody named,
+ * so it is refused here, for every colour function and every `ramp` stop.
+ * [LAW:single-enforcer]
  */
-export declare const readableOnFunc: (drawnAt: () => ColorDepth) => TemplateFunc;
+export declare function computable(colour: ColorRgba, func: string, written: string): ColorRgba;
+/**
+ * Where `readableOn`'s text will be drawn: the depth the output is encoded at,
+ * and the terminal that draws it when that is known. At sixteen colours a
+ * terminal paints each slot in its own theme's colour, so the floor is measured
+ * in `terminal`'s sixteen; without one, in the VGA defaults (the Windows
+ * console's at `WINDOWS`). Both are facts about the one place the text lands,
+ * so they arrive together.
+ */
+export interface DrawnAt {
+    readonly depth: ColorDepth;
+    readonly terminal?: TerminalTheme;
+}
+/**
+ * The `readableOn` binding, measuring where `drawnAt` says the text lands when
+ * it is evaluated — a consumer that renders to a per-call destination
+ * registers its own.
+ */
+export declare const readableOnFunc: (drawnAt: () => DrawnAt) => TemplateFunc;
 /**
  * The palette-free color vocabulary: every function takes colors and returns a
  * color, so they compose by nesting.
@@ -80,8 +102,8 @@ export declare const readableOnFunc: (drawnAt: () => ColorDepth) => TemplateFunc
  * Pair with `paletteFuncs()` to name colors from a theme, and with
  * `richTextStyleFuncs()`'s `fg`/`bg` to paint them onto text.
  *
- * @param drawnAt the depth the terminal will draw at, read on every
- *   `readableOn` evaluation so a host that learns its depth per render passes
- *   one getter; defaults to truecolor.
+ * @param drawnAt where the text will be drawn — the depth, and the terminal
+ *   when known — read on every `readableOn` evaluation so a host that learns
+ *   its destination per render passes one getter; defaults to truecolor.
  */
-export declare function colorFuncs(drawnAt?: () => ColorDepth): FuncMap;
+export declare function colorFuncs(drawnAt?: () => DrawnAt): FuncMap;