@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/renderables/traceback.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Traceback — renders error tracebacks with formatting.
+ *
+ * [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
+ * main barrel, importable in a browser.
+ *
+ * [LAW:types-are-the-program] `TracebackOptions` names only what the renderer
+ * reads. There is no `showLocals`: an `Error` carries a stack of locations and
+ * nothing of the values in scope at them. The one way to get those in node —
+ * an inspector session pausing on exceptions — would have to pause on every
+ * throw, caught ones included, to serve `new Traceback(caughtError)`, and it
+ * cannot exist in a browser at all. Nor is there a `width` or `theme`: those
+ * sized and coloured a source-code excerpt this renderer does not produce.
+ */
+import { Segment } from "../core/segment.js";
+import type { Renderable, RenderOptions } from "../core/protocol.js";
+export interface TracebackOptions {
+    suppress?: string[];
+    maxFrames?: number;
+}
+export declare class Traceback implements Renderable {
+    /** What was caught, as it was handed in. */
+    readonly error: unknown;
+    readonly maxFrames: number;
+    readonly suppress: string[];
+    private readonly caught;
+    constructor(error: unknown, options?: TracebackOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+}

package/dist/renderables/traceback.js

@@ -0,0 +1,279 @@
+/**
+ * Traceback — renders error tracebacks with formatting.
+ *
+ * [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
+ * main barrel, importable in a browser.
+ *
+ * [LAW:types-are-the-program] `TracebackOptions` names only what the renderer
+ * reads. There is no `showLocals`: an `Error` carries a stack of locations and
+ * nothing of the values in scope at them. The one way to get those in node —
+ * an inspector session pausing on exceptions — would have to pause on every
+ * throw, caught ones included, to serve `new Traceback(caughtError)`, and it
+ * cannot exist in a browser at all. Nor is there a `width` or `theme`: those
+ * sized and coloured a source-code excerpt this renderer does not produce.
+ */
+import { Segment } from "../core/segment.js";
+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 { 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 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 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 {
+            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();
+            }
+        }
+    }
+}
+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

@@ -0,0 +1,76 @@
+/**
+ * Tree — hierarchical view with guide lines.
+ */
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import { RichText } from "../core/text.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export interface TreeOptions {
+    expanded?: boolean;
+    hideRoot?: boolean;
+    guide_style?: string | Style;
+    style?: string | Style;
+}
+export declare class Tree implements Renderable, Measurable {
+    readonly label: Renderable;
+    readonly children: Tree[];
+    expanded: boolean;
+    readonly hideRoot: boolean;
+    readonly guideStyle: string | Style;
+    readonly style: string | Style;
+    constructor(label: string | RichText | Renderable, options?: TreeOptions);
+    add(label: string | RichText | Renderable, options?: TreeOptions): Tree;
+    render(rawOptions: RenderOptions): Iterable<Segment>;
+    /**
+     * The rows `render` and `measure` both read, entered in exactly one place so
+     * the two cannot start the walk differently. A hidden root takes its own row
+     * 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.
+     */
+    private _walk;
+    /**
+     * The tree walked into the rows it emits, one row per label, guides first.
+     *
+     * [LAW:one-source-of-truth] The walk that decides which rows exist and what
+     * leads them is here and only here. `render` turns each row into segments and
+     * `measure` reads each row's width off the same sequence, so the two cannot
+     * come to disagree about how many rows there are or how wide the guides on
+     * them run — which they would the moment a second walk existed.
+     *
+     * [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. 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;
+    /**
+     * One row of the tree: its label in whatever width the guides left, each of
+     * the label's lines led by the guides.
+     *
+     * [LAW:single-enforcer] The row's width is divided in exactly one place, here.
+     * Before this, each call site emitted its guides and then handed the label
+     * `options` unchanged — the label was told it had the whole outer width while
+     * the guides had already spent four cells of it, so a tree at maxWidth 5
+     * emitted rows of 9. That is the same defect Panel and Table were fixed for,
+     * and the same fix: divide the requested width once and let every part read
+     * its share off the division. `options` arrives parsed from `render`.
+     *
+     * [LAW:single-enforcer] Tree also owns its row boundaries here rather than
+     * 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 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): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/tree.js

@@ -0,0 +1,177 @@
+/**
+ * Tree — hierarchical view with guide lines.
+ */
+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, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { Measurement } from "../core/measure.js";
+/** 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: "    " };
+/**
+ * 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) {
+    return Measurement.get(options, label).maximum;
+}
+export class Tree {
+    label;
+    children;
+    expanded;
+    hideRoot;
+    guideStyle;
+    style;
+    constructor(label, options) {
+        this.label = embed(label);
+        this.children = [];
+        this.expanded = options?.expanded !== false;
+        this.hideRoot = options?.hideRoot ?? false;
+        this.guideStyle = options?.guide_style ?? NULL_STYLE;
+        this.style = options?.style ?? NULL_STYLE;
+    }
+    add(label, options) {
+        const child = new Tree(label, {
+            guide_style: options?.guide_style,
+            style: options?.style,
+            expanded: options?.expanded,
+        });
+        this.children.push(child);
+        return child;
+    }
+    *render(rawOptions) {
+        const options = withBoundedWidth(rawOptions, this);
+        for (const row of this._walk()) {
+            yield* this._renderRow(options, row);
+        }
+    }
+    /**
+     * The rows `render` and `measure` both read, entered in exactly one place so
+     * the two cannot start the walk differently. A hidden root takes its own row
+     * 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() {
+        const rows = [...this._rows([], [], [])];
+        return this.hideRoot ? rows.slice(1).map((row) => ({ ...row, guides: row.guides.slice(1) })) : rows;
+    }
+    /**
+     * The tree walked into the rows it emits, one row per label, guides first.
+     *
+     * [LAW:one-source-of-truth] The walk that decides which rows exist and what
+     * leads them is here and only here. `render` turns each row into segments and
+     * `measure` reads each row's width off the same sequence, so the two cannot
+     * come to disagree about how many rows there are or how wide the guides on
+     * them run — which they would the moment a second walk existed.
+     *
+     * [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. 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(guides, inheritedGuideStyles, inheritedStyles) {
+        const styles = [...inheritedStyles, this.style];
+        yield { guides, label: this.label, styles };
+        const children = this.expanded ? this.children : [];
+        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
+                ? { first: "end", rest: "space", styles: guideStyles }
+                : { first: "fork", rest: "continue", styles: guideStyles };
+            yield* children[i]._rows([...above, branch], guideStyles, styles);
+        }
+    }
+    /**
+     * One row of the tree: its label in whatever width the guides left, each of
+     * the label's lines led by the guides.
+     *
+     * [LAW:single-enforcer] The row's width is divided in exactly one place, here.
+     * Before this, each call site emitted its guides and then handed the label
+     * `options` unchanged — the label was told it had the whole outer width while
+     * the guides had already spent four cells of it, so a tree at maxWidth 5
+     * emitted rows of 9. That is the same defect Panel and Table were fixed for,
+     * and the same fix: divide the requested width once and let every part read
+     * its share off the division. `options` arrives parsed from `render`.
+     *
+     * [LAW:single-enforcer] Tree also owns its row boundaries here rather than
+     * 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 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 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. 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 { 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, guideStyle);
+                left -= cellLen(piece);
+            }
+            yield* lines[i];
+            yield Segment.line();
+        }
+    }
+    measure(options) {
+        // The ceiling is parsed for the same reason the rows are: an unparsed NaN
+        // ceiling yields a range no parent layout can divide.
+        const parsed = withCellWidth(options);
+        const ceiling = parsed.maxWidth;
+        // The widest row the walk emits, not the offer. Reported as the offer, a
+        // tree told any parent that asked "I want all of it" — so `Panel` in fit
+        // 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()) {
+            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
+        // this tree turned out to want, or the floor would sit above its own ceiling.
+        return { minimum: Math.min(4, maximum), maximum };
+    }
+}

package/dist/renderables/viewport.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Viewport — a fixed number of rows onto a taller renderable, scrolled by an
+ * offset that cannot leave the content.
+ *
+ * Its rows, under the `Height` contract in `../core/protocol.ts`: the region's
+ * when it is given one; otherwise its own configured rows, or the content's
+ * full length when it has none, capped by any ceiling. It renders its content
+ * with no height, because the content's natural length is the scroll extent,
+ * and pads or crops what comes back to its rows — its rows are its own height,
+ * not a region someone else will shape.
+ *
+ * Its width is the width it is given, in both directions: each row is cropped
+ * or padded to it, so content that ignores its width cannot spill past the
+ * viewport's edge and the scrollbar, drawn in a gutter at that edge, lines up
+ * down every row. [LAW:dataflow-not-control-flow] A viewport with no scrollbar
+ * has a gutter zero cells wide, and every row takes the same path either way.
+ *
+ * [LAW:no-ambient-temporal-coupling] Neither half of what an offset is clamped
+ * against exists before a render: the rows come from the budget the render is
+ * handed, and the content's length from rendering it at the width it is handed.
+ * So `scrollTo`, `scrollBy` and `ensureVisible` do not move anything when they
+ * are called. Each queues a move, and the next render resolves the queue in
+ * call order, clamping after every move, against the rows and length that
+ * render found. Calling an operation before the first render, or three of them
+ * between two renders, is the same code path as calling one.
+ *
+ * Every cell of its rows, gutter included, is stamped as its own
+ * (`Segment.anchorLines`), around whatever anchors its content drew. So the
+ * composed frame names the viewport under any of its cells however deep it is
+ * nested, and a cell of a widget inside it names both: that is how the wheel
+ * finds the viewport to scroll. `canScrollBy` is how it passes over one that
+ * cannot move that way, to the viewport around it.
+ */
+import { Segment } from "../core/segment.js";
+import type { Style } from "../core/style.js";
+import type { Measurable, Renderable, RenderOptions, Scrollable } from "../core/protocol.js";
+/** How one part of a scrollbar draws each row it covers. */
+export interface ScrollbarPart {
+    readonly glyph: string;
+    /** A style, or a theme name resolved when the viewport renders. */
+    readonly style: string | Style;
+}
+/**
+ * The look of a scrollbar: the thumb, over the rows of the track that stand for
+ * the lines in view, and the track, over the rest. Its gutter is as wide as the
+ * wider of the two glyphs.
+ */
+export interface Scrollbar {
+    readonly thumb: ScrollbarPart;
+    readonly track: ScrollbarPart;
+}
+/** A heavy line for the thumb on a light line for the track. */
+export declare const SCROLLBAR: Scrollbar;
+export interface ViewportOptions {
+    /**
+     * The rows shown when the viewport is given no region. Absent, it shows the
+     * content's full length. A ceiling caps either.
+     */
+    rows?: number;
+    /** A scrollbar down the right edge. Absent, the content has the full width. */
+    scrollbar?: Scrollbar;
+}
+export declare class Viewport implements Renderable, Measurable, Scrollable {
+    /**
+     * What the viewport shows. Replace it to show new content from the same
+     * scroll position — a view rebuilt every frame keeps one `Viewport`.
+     */
+    content: Renderable;
+    readonly rows: number | undefined;
+    readonly scrollbar: Scrollbar;
+    private _offset;
+    private _extent;
+    private _moves;
+    constructor(content: Renderable, options?: ViewportOptions);
+    /**
+     * The first content line the last render showed. A move requested since is
+     * not reflected until the next render resolves it.
+     */
+    get offset(): number;
+    /** Scroll so `line` is the first line shown. */
+    scrollTo(line: number): void;
+    /** Scroll by `lines`: down when positive, up when negative. */
+    scrollBy(lines: number): void;
+    /**
+     * Whether `scrollBy(lines)` would move the viewport from where the moves
+     * queued so far leave it, against the rows and length the last render
+     * found.
+     */
+    canScrollBy(lines: number): boolean;
+    /**
+     * Scroll the least distance that shows lines `start` up to but not
+     * including `end` — lines of the content as it renders at the viewport's
+     * width, so an item that wraps spans more than one. A range already in view does not move; one taller than
+     * the viewport shows its first line at the top.
+     */
+    ensureVisible(start: number, end: number): void;
+    /**
+     * The width its content renders at, out of `width`: what the scrollbar's
+     * gutter leaves. Lines handed to `ensureVisible` are lines at this width.
+     */
+    contentWidth(width: number): number;
+    render(rawOptions: RenderOptions): Iterable<Segment>;
+    /**
+     * [LAW:one-source-of-truth] Where the queued moves leave the offset against
+     * `extent`: what a render commits, and what `canScrollBy` asks from.
+     * [LAW:dataflow-not-control-flow] The offset is re-clamped with or without
+     * queued moves: content that shrank since the last render pulls it back.
+     */
+    private resolve;
+    measure(rawOptions: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}