@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/renderables/traceback.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Traceback — renders error tracebacks with formatting.
+ *
+ * [LAW:effects-at-boundaries] Pure rendering: an `Error` 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 {
+    readonly error: Error;
+    readonly maxFrames: number;
+    readonly suppress: string[];
+    constructor(error: Error, options?: TracebackOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+    private _renderFrame;
+}

package/dist/renderables/traceback.js

@@ -0,0 +1,108 @@
+/**
+ * Traceback — renders error tracebacks with formatting.
+ *
+ * [LAW:effects-at-boundaries] Pure rendering: an `Error` 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 { 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),
+            });
+        }
+    }
+    return frames;
+}
+export class Traceback {
+    error;
+    maxFrames;
+    suppress;
+    constructor(error, options) {
+        this.error = error;
+        this.maxFrames = options?.maxFrames ?? 100;
+        this.suppress = options?.suppress ?? [];
+    }
+    *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) {
+            // 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);
+            }
+        }
+        else {
+            for (const frame of displayFrames) {
+                yield* this._renderFrame(frame, options);
+            }
+        }
+    }
+    *_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();
+    }
+}

package/dist/renderables/tree.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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.
+     */
+    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 does not add a blank one.
+     */
+    private _renderRow;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/tree.js

@@ -0,0 +1,150 @@
+/**
+ * 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, isMeasurable, 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;
+/**
+ * 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.
+ */
+function labelWidth(options, label) {
+    if (!isMeasurable(label))
+        return options.maxWidth;
+    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(options)) {
+            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(options) {
+        const rows = [...this._rows(drawable(options, UNICODE_GUIDES, ASCII_GUIDES, guideGlyphs), [], [])];
+        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.
+     */
+    *_rows(glyphs, guides, inherited) {
+        yield { guides, label: this.label };
+        const children = this.expanded ? this.children : [];
+        const styles = [...inherited, 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);
+        }
+    }
+    /**
+     * 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 does not add a blank one.
+     */
+    *_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));
+        // 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));
+        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));
+                if (piece.length > 0)
+                    yield new Segment(piece, styles[g]);
+                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(parsed)) {
+            const guideWidth = row.guides.reduce((sum, guide) => sum + cellLen(guide.first), 0);
+            natural = Math.max(natural, guideWidth + 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;
+    };
+}

package/dist/renderables/viewport.js

@@ -0,0 +1,198 @@
+/**
+ * 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 { 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";
+/** A heavy line for the thumb on a light line for the track. */
+export const SCROLLBAR = {
+    thumb: { glyph: "┃", style: "scrollbar.thumb" },
+    track: { glyph: "│", style: "scrollbar.track" },
+};
+/** The absence of a scrollbar, as a gutter zero cells wide. */
+const NO_SCROLLBAR = {
+    thumb: { glyph: "", style: NULL_STYLE },
+    track: { glyph: "", style: NULL_STYLE },
+};
+export class Viewport {
+    /**
+     * What the viewport shows. Replace it to show new content from the same
+     * scroll position — a view rebuilt every frame keeps one `Viewport`.
+     */
+    content;
+    rows;
+    scrollbar;
+    _offset = 0;
+    // Nothing rendered, nothing shown: no move can take until the first render.
+    _extent = { rows: 0, lines: 0 };
+    _moves = [];
+    constructor(content, options = {}) {
+        this.content = content;
+        this.rows = options.rows;
+        this.scrollbar = options.scrollbar ?? NO_SCROLLBAR;
+    }
+    /**
+     * The first content line the last render showed. A move requested since is
+     * not reflected until the next render resolves it.
+     */
+    get offset() {
+        return this._offset;
+    }
+    /** Scroll so `line` is the first line shown. */
+    scrollTo(line) {
+        this._moves.push(() => line);
+    }
+    /** Scroll by `lines`: down when positive, up when negative. */
+    scrollBy(lines) {
+        this._moves.push((offset) => offset + lines);
+    }
+    /**
+     * 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) {
+        const offset = this.resolve(this._extent);
+        return clampOffset(offset + lines, this._extent) !== offset;
+    }
+    /**
+     * 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, end) {
+        this._moves.push((offset, { rows }) => Math.min(start, Math.max(offset, end - rows)));
+    }
+    /**
+     * 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) {
+        return cellCount(width - gutterWidth(this.scrollbar));
+    }
+    *render(rawOptions) {
+        const { height, ...options } = withBoundedWidth(rawOptions, this);
+        const gutter = gutterWidth(this.scrollbar);
+        const contentWidth = this.contentWidth(options.maxWidth);
+        const lines = Segment.splitLines(this.content.render({ ...options, maxWidth: contentWidth }));
+        const extent = { rows: viewRows(height, this.rows, lines.length), lines: lines.length };
+        this._extent = extent;
+        this._offset = this.resolve(extent);
+        this._moves = [];
+        const shown = fitHeight(lines.slice(this._offset, this._offset + extent.rows), { rows: extent.rows, exact: true });
+        // [LAW:no-ambient-temporal-coupling] The thumb is drawn from the offset
+        // this render just resolved, not from `offset` as it stood before it.
+        const thumb = thumbRows(extent, this._offset);
+        // The content's cells and the gutter's drawn cells sum to the offer: a
+        // gutter wider than the whole offer is drawn cropped to it.
+        const drawn = Math.min(gutter, options.maxWidth);
+        // The style reaches the padding too, so a glyph narrower than the gutter
+        // still fills its cell with its part's background.
+        const cell = ({ glyph, style }) => {
+            const resolved = getStyle(options, style);
+            return Segment.adjustLineLength([new Segment(glyph, resolved)], drawn, resolved);
+        };
+        // The gutter keeps the chosen scrollbar's width, so an ASCII stand-in
+        // padded into it leaves the content where `contentWidth` said it would be.
+        const bar = drawable(options, this.scrollbar, asciiScrollbar(this.scrollbar), scrollbarGlyphs);
+        const thumbCell = cell(bar.thumb);
+        const trackCell = cell(bar.track);
+        const rows = shown.map((line, row) => [
+            ...Segment.adjustLineLength(line, contentWidth),
+            ...(row >= thumb.start && row < thumb.end ? thumbCell : trackCell),
+        ]);
+        for (const line of Segment.anchorLines(rows, this)) {
+            yield* line;
+            yield Segment.line();
+        }
+    }
+    /**
+     * [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.
+     */
+    resolve(extent) {
+        return this._moves.reduce((offset, move) => clampOffset(move(offset, extent), extent), clampOffset(this._offset, extent));
+    }
+    measure(rawOptions) {
+        // Its width is its content's and its gutter's. `withCellWidth` and not
+        // `withBoundedWidth`: the bounded parse asks this very method for the
+        // natural width.
+        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);
+        return new Measurement(content.minimum + gutter, content.maximum + gutter).withMaximum(options.maxWidth);
+    }
+}
+const scrollbarGlyphs = ({ thumb, track }) => thumb.glyph + track.glyph;
+/** `scrollbar` in its own styles, drawn in ASCII. */
+function asciiScrollbar({ thumb, track }) {
+    return { thumb: { ...thumb, glyph: "#" }, track: { ...track, glyph: "|" } };
+}
+/** The cells a scrollbar's gutter takes from the content: its wider glyph. */
+function gutterWidth({ thumb, track }) {
+    return Math.max(cellLen(thumb.glyph), cellLen(track.glyph));
+}
+/**
+ * The rows of the track the thumb covers, from `start` up to but not including
+ * `end`: its length is the share of the content in view, and its position the
+ * share of the scroll travelled. Content that fits fills the track.
+ *
+ * An end of the track means an end of the content. Rounded alone, the position
+ * reached the bottom while lines were still hidden below — at 10 rows of 20
+ * lines, offset 9 rounds onto the last position. So an offset short of an end
+ * is held one row off it, wherever the track has a row between its ends.
+ */
+function thumbRows({ rows, lines }, offset) {
+    const size = Math.min(rows, Math.max(1, Math.round((rows * rows) / Math.max(lines, rows, 1))));
+    const travel = rows - size;
+    const last = Math.max(1, lines - rows);
+    const proportional = Math.round((offset * travel) / last);
+    const start = Math.max(Math.min(proportional, travel - Math.min(last - offset, 1)), Math.min(offset, 1, travel));
+    return { start, end: start + size };
+}
+/** The rows a viewport shows, from its budget, its own configured rows, and its content's length. */
+function viewRows(height, rows, lines) {
+    return regionRows(height) ?? cellCount(Math.min(rows ?? lines, height?.rows ?? Infinity));
+}
+/** An offset held to the lines that exist: never above the first, never past the last full view. */
+function clampOffset(offset, { rows, lines }) {
+    return cellCount(Math.min(offset, lines - rows));
+}