@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/renderables/traceback.d.ts

@@ -16,16 +16,16 @@
  * 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";
+import { type Renderable, type RenderOptions } from "../core/protocol.js";
 export interface TracebackOptions {
-    suppress?: string[];
+    suppress?: readonly 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[];
+    readonly suppress: readonly string[];
     private readonly caught;
     constructor(error: unknown, options?: TracebackOptions);
     render(options: RenderOptions): Iterable<Segment>;

package/dist/renderables/traceback.js

@@ -18,7 +18,9 @@
 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";
+import { render } from "../core/protocol.js";
+import { paddedContentWidth } from "./padding.js";
+import { pattern } from "../core/pattern.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
@@ -140,13 +142,13 @@ function parseStack(stack, name, message) {
  * 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+(?!\())?(.*)$/;
+const V8_FRAME = pattern(/^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 = /^(?:[^@]*\*)?([^@]*)@(.*)$/;
+const AT_SIGN_FRAME = pattern(/^(?:[^@]*\*)?([^@]*)@(.*)$/);
 function parseFrame(text) {
     const v8 = V8_FRAME.exec(text);
     if (v8) {
@@ -187,9 +189,9 @@ function openingParen(body) {
  * the code to it (`file line 8 > eval:1:1`).
  */
 const LOCATIONS = [
-    /^eval at [^]*?\(([^()]+):(\d+):\d+\)/,
-    /^(.*?) line (\d+) > (?:eval|Function)/,
-    /^(.*?):(\d+)(?::\d+)?$/,
+    pattern(/^eval at [^]*?\(([^()]+):(\d+):\d+\)/),
+    pattern(/^(.*?) line (\d+) > (?:eval|Function)/),
+    pattern(/^(.*?):(\d+)(?::\d+)?$/),
 ];
 function locate(fn, location) {
     for (const shape of LOCATIONS) {
@@ -225,7 +227,7 @@ export class Traceback {
         // 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);
+        yield* render(header, 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);
@@ -253,10 +255,10 @@ export class Traceback {
         // 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));
+        const frameOptions = { ...options, maxWidth: paddedContentWidth(options.maxWidth, 2, 0) };
+        const indent = new Segment("  ");
         for (const entry of entries) {
-            for (const line of Segment.splitLines(entry.render({ ...options, maxWidth: contentWidth }))) {
+            for (const line of Segment.splitLines(render(entry, frameOptions))) {
                 yield indent;
                 yield* line;
                 yield Segment.line();

package/dist/renderables/tree.d.ts

@@ -13,13 +13,16 @@ export interface TreeOptions {
 }
 export declare class Tree implements Renderable, Measurable {
     readonly label: Renderable;
-    readonly children: Tree[];
-    expanded: boolean;
+    private readonly _children;
+    private readonly _expanded;
     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;
+    get children(): readonly Tree[];
+    get expanded(): boolean;
+    set expanded(value: boolean);
     render(rawOptions: RenderOptions): Iterable<Segment>;
     /**
      * The rows `render` and `measure` both read, entered in exactly one place so
@@ -29,7 +32,8 @@ export declare class Tree implements Renderable, Measurable {
      */
     private _walk;
     /**
-     * The tree walked into the rows it emits, one row per label, guides first.
+     * This node's subtree walked into the rows it emits, one row per label,
+     * guides first, each guide column counted from this node.
      *
      * [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
@@ -38,35 +42,34 @@ export declare class Tree implements Renderable, Measurable {
      * 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.
+     * this one recursion: each child's rows get a branch column of their own,
+     * settled below the first of them drawn, 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.
+     *
+     * The branch is chosen once every child is drawn: a subtree that draws no row
+     * takes no place among its siblings, so the last one that draws a row ends
+     * the branch, and the branch stands on a subtree's first drawn row — a child
+     * that drew nothing above children that did leaves them on its branch, not
+     * the sibling's before it. Rich chooses it from the children alone, and
+     * draws a fork over a last child that drew nothing — an element not yet
+     * arrived, or gone.
      */
     private _rows;
+    /** Each of this node's children walked into its rows, `columns` of guide before each child's own. */
+    private _subtrees;
     /**
-     * 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`.
+     * One row of the tree: each of the label's lines led by the guides.
      *
-     * [LAW:single-enforcer] Tree also owns its row boundaries here rather than
+     * [LAW:single-enforcer] Tree 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.
+     * that emits nothing — one left no column, say — has no 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.
+     * The node's 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,8 +5,9 @@ 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 { drawable, getStyle, render, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
 import { Measurement } from "../core/measure.js";
+import { ListState, State } from "../core/state.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: "    " };
@@ -28,21 +29,38 @@ 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);
 }
+/** A row a label is known to draw, unread. */
+const A_ROW = [[]];
+/** The cells a row with `columns` of guide leaves its label. */
+const labelRoom = (options, columns) => Math.max(0, options.maxWidth - columns * GUIDE_CELLS);
+/**
+ * `label` drawn in `width` cells, as both `render` and `measure` draw it, so
+ * whether it draws a row is answered once. Cropped, 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`.
+ */
+function drawLabel(options, label, width) {
+    const labelOptions = { ...options, highlight: false, maxWidth: width, height: stackedHeight(options.height) };
+    return Segment.cropLines(render(label, labelOptions), width);
+}
 /** How wide a label wants to be. */
 function labelWidth(options, label) {
     return Measurement.get(options, label).maximum;
 }
+/** Whether a row is drawn: a subtree with one takes a place among its siblings. */
+const isDrawn = (row) => row.lines.length > 0;
 export class Tree {
     label;
-    children;
-    expanded;
+    // Rich's Tree grows by `add` and is expanded or collapsed after it is built.
+    _children = new ListState();
+    _expanded;
     hideRoot;
     guideStyle;
     style;
     constructor(label, options) {
         this.label = embed(label);
-        this.children = [];
-        this.expanded = options?.expanded !== false;
+        this._expanded = new State(options?.expanded !== false);
         this.hideRoot = options?.hideRoot ?? false;
         this.guideStyle = options?.guide_style ?? NULL_STYLE;
         this.style = options?.style ?? NULL_STYLE;
@@ -53,13 +71,35 @@ export class Tree {
             style: options?.style,
             expanded: options?.expanded,
         });
-        this.children.push(child);
+        this._children.push(child);
         return child;
     }
+    get children() {
+        return this._children.get();
+    }
+    get expanded() {
+        return this._expanded.get();
+    }
+    set expanded(value) {
+        this._expanded.set(value);
+    }
     *render(rawOptions) {
         const options = withBoundedWidth(rawOptions, this);
-        for (const row of this._walk()) {
-            yield* this._renderRow(options, row);
+        const resolve = (styles) => Style.combine(styles.map((style) => getStyle(options, style)));
+        // [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.
+        //
+        // The guides are cropped by `cellFit`, the label by `drawLabel`. The
+        // node's style sits under the label's own, as Rich's `Styled` puts it, so
+        // markup in the label still wins.
+        const draw = (label, styles, columns) => Segment.splitLines(Segment.applyStyle(drawLabel(options, label, labelRoom(options, columns)), resolve(styles)));
+        for (const row of this._walk(draw)) {
+            yield* this._renderRow(options, resolve, row);
         }
     }
     /**
@@ -68,12 +108,14 @@ 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() {
-        const rows = [...this._rows([], [], [])];
-        return this.hideRoot ? rows.slice(1).map((row) => ({ ...row, guides: row.guides.slice(1) })) : rows;
+    _walk(draw) {
+        return this.hideRoot
+            ? this._subtrees(0, draw, [this.guideStyle], [this.style]).flat()
+            : this._rows(0, draw, [], []);
     }
     /**
-     * The tree walked into the rows it emits, one row per label, guides first.
+     * This node's subtree walked into the rows it emits, one row per label,
+     * guides first, each guide column counted from this node.
      *
      * [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
@@ -82,50 +124,54 @@ export class Tree {
      * 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.
+     * this one recursion: each child's rows get a branch column of their own,
+     * settled below the first of them drawn, 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.
+     *
+     * The branch is chosen once every child is drawn: a subtree that draws no row
+     * takes no place among its siblings, so the last one that draws a row ends
+     * the branch, and the branch stands on a subtree's first drawn row — a child
+     * that drew nothing above children that did leaves them on its branch, not
+     * the sibling's before it. Rich chooses it from the children alone, and
+     * draws a fork over a last child that drew nothing — an element not yet
+     * arrived, or gone.
      */
-    *_rows(guides, inheritedGuideStyles, inheritedStyles) {
+    _rows(columns, draw, 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);
-        }
+        const own = { guides: [], label: this.label, styles, lines: draw(this.label, styles, columns) };
+        const subtrees = this._subtrees(columns + 1, draw, guideStyles, styles);
+        const firsts = subtrees.map((rows) => rows.findIndex(isDrawn));
+        const last = firsts.reduce((found, first, i) => (first >= 0 ? i : found), -1);
+        const branched = subtrees.flatMap((rows, i) => {
+            const branch = i < last
+                ? { first: "fork", rest: "continue", styles: guideStyles }
+                : { first: "end", rest: "space", styles: guideStyles };
+            const settled = { ...branch, first: branch.rest };
+            return rows.map((row, r) => ({ ...row, guides: [r === firsts[i] ? branch : settled, ...row.guides] }));
+        });
+        return [own, ...branched];
+    }
+    /** Each of this node's children walked into its rows, `columns` of guide before each child's own. */
+    _subtrees(columns, draw, guideStyles, styles) {
+        const children = this.expanded ? this.children : [];
+        return children.map((child) => child._rows(columns, draw, 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`.
+     * One row of the tree: each of the label's lines led by the guides.
      *
-     * [LAW:single-enforcer] Tree also owns its row boundaries here rather than
+     * [LAW:single-enforcer] Tree 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.
+     * that emits nothing — one left no column, say — has no 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.
+     * The node's 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)));
+    *_renderRow(options, resolve, row) {
         const style = resolve(row.styles);
         const drawn = row.guides.map((guide) => {
             const guideStyle = resolve(guide.styles);
@@ -134,15 +180,7 @@ export class Tree {
                 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([]);
+        const lines = row.lines;
         for (let i = 0; i < lines.length; i++) {
             let left = options.maxWidth;
             for (let g = 0; g < row.guides.length; g++) {
@@ -164,10 +202,22 @@ export class Tree {
         // 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.
+        // offer came back unbounded. A row the walk does not draw wants nothing.
+        // A label that wants cells draws them, so only one that wants none can
+        // draw no row, and only that one is drawn to ask — in the one column it
+        // wants, as its row does, because under one column nothing draws. A label
+        // of no width that does draw is a blank row, as wide as its guides and that
+        // column: the width the tree, drawn at what this reports, hands it.
+        const widths = new Map();
+        const widthOf = (label) => {
+            const width = widths.get(label) ?? labelWidth(parsed, label);
+            widths.set(label, width);
+            return width;
+        };
+        const draw = (label, _styles, columns) => widthOf(label) > 0 ? A_ROW : Segment.splitLines(drawLabel(parsed, label, Math.min(labelRoom(parsed, columns), 1)));
         let natural = 0;
-        for (const row of this._walk()) {
-            natural = Math.max(natural, row.guides.length * GUIDE_CELLS + labelWidth(parsed, row.label));
+        for (const row of this._walk(draw).filter(isDrawn)) {
+            natural = Math.max(natural, row.guides.length * GUIDE_CELLS + Math.max(1, widthOf(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.d.ts

@@ -1,6 +1,10 @@
 /**
- * Viewport — a fixed number of rows onto a taller renderable, scrolled by an
- * offset that cannot leave the content.
+ * Viewport — a scroll position: a fixed number of rows onto taller content,
+ * scrolled by an offset that cannot leave it. It holds the position, not the
+ * content: content is drawn through it with `showing` (or `showingLines`), so
+ * a view rebuilt every frame keeps one viewport under content it builds anew.
+ * [LAW:one-source-of-truth] That is the one way to draw through it, so no
+ * viewport is built around content it never draws.
  *
  * 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
@@ -19,11 +23,18 @@
  * 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
+ * are called. Each queues a move, and the next render that draws the content
+ * 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.
  *
+ * A render changes nothing (`State`, `../core/state.ts`), so the render draws
+ * the offset it resolved without keeping it, and hands the keeping to its pass
+ * (`afterPass`): once the frame has been drawn whole, the offset, the rows and
+ * length it was clamped against, and the followed range become the viewport's,
+ * and the moves it resolved leave the queue. A measurement, which draws
+ * nothing anyone sees, keeps nothing.
+ *
  * 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
@@ -34,6 +45,24 @@
 import { Segment } from "../core/segment.js";
 import type { Style } from "../core/style.js";
 import type { Measurable, Renderable, RenderOptions, Scrollable } from "../core/protocol.js";
+/** Lines `start` up to but not including `end` of the content. */
+interface Range {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Content a viewport shows by the line: laid out at a width, it says how many
+ * lines it is and draws only the ones asked for. What a view too long to draw
+ * whole every frame — a textarea's rows — is shown as (`showingLines`).
+ */
+export interface Lines extends Measurable {
+    layout(options: RenderOptions): LaidLines;
+}
+/** Content laid out at one width: its length, and its lines `start` up to but not including `end`. */
+export interface LaidLines {
+    readonly length: number;
+    lines(start: number, end: number): Segment[][];
+}
 /** How one part of a scrollbar draws each row it covers. */
 export interface ScrollbarPart {
     readonly glyph: string;
@@ -60,22 +89,15 @@ export interface ViewportOptions {
     /** 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;
+export declare class Viewport implements Scrollable {
     readonly rows: number | undefined;
     readonly scrollbar: Scrollbar;
-    private _offset;
-    private _extent;
-    private _moves;
-    private _followed;
-    constructor(content: Renderable, options?: ViewportOptions);
+    private readonly _scroll;
+    private readonly _moves;
+    constructor(options?: ViewportOptions);
     /**
-     * The first content line the last render showed. A move requested since is
-     * not reflected until the next render resolves it.
+     * The first content line the last frame showed. A move requested since is
+     * not reflected until the next frame resolves it.
      */
     get offset(): number;
     /** Scroll so `line` is the first line shown. */
@@ -84,7 +106,7 @@ export declare class Viewport implements Renderable, Measurable, Scrollable {
     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
+     * queued so far leave it, against the rows and length the last frame
      * found.
      */
     canScrollBy(lines: number): boolean;
@@ -96,16 +118,30 @@ export declare class Viewport implements Renderable, Measurable, Scrollable {
      */
     ensureVisible(start: number, end: number): void;
     /**
-     * `ensureVisible(start, end)`, when the range differs from the one the last
-     * `follow` named. A view rebuilt every frame calls this in every frame with
-     * its selection's lines, and the selection is brought into view when it
-     * moves — not on every frame, which would undo on its very render each
-     * scroll the mouse wheel queues. A followed range the last render showed
-     * whole stays shown when the row count changes: the same lines can fall off
-     * the bottom of a viewport that got shorter. One the wheel had scrolled
-     * away from stays away.
+     * `content` shown through this viewport from its scroll position. What it
+     * draws is anchored to this viewport, so the wheel finds it.
+     *
+     * `follow` is the lines of `content` to keep in view — a selection's — and
+     * is brought into view with `ensureVisible` when it differs from the range
+     * the last frame followed: when the selection moves, not on every frame,
+     * which would undo on its very render each scroll the mouse wheel queues. A
+     * followed range the last frame showed whole stays shown when the row count
+     * changes: the same lines can fall off the bottom of a viewport that got
+     * shorter. One the wheel had scrolled away from stays away. Absent, the
+     * range last followed stands.
+     *
+     * [LAW:effects-at-boundaries] What a frame drawing it resolves becomes the
+     * viewport's once that frame has been drawn whole, so it may be built and
+     * drawn inside a render — `ListView` draws its items to learn their lines
+     * and shows them this way.
+     */
+    showing(content: Renderable, follow?: Range): Renderable & Measurable;
+    /**
+     * `content` shown through this viewport as `showing` shows a renderable,
+     * drawing only the lines the frame shows: a frame costs the rows in view,
+     * not the content's whole length.
      */
-    follow(start: number, end: number): void;
+    showingLines(content: Lines, follow?: Range): Renderable & Measurable;
     /**
      * The width its content renders at, out of `width`: what the scrollbar's
      * gutter leaves. Lines handed to `ensureVisible` are lines at this width.
@@ -113,18 +149,20 @@ export declare class Viewport implements Renderable, Measurable, Scrollable {
     contentWidth(width: number): number;
     /** The cells the scrollbar's gutter takes beside the content. */
     get gutter(): number;
-    render(rawOptions: RenderOptions): Iterable<Segment>;
+    /** The scroll, and the moves queued against it, as they stand. */
+    private asked;
     /**
-     * [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.
+     * The offset `settled` resolves, with the scroll it leaves kept once the frame
+     * is drawn and the `resolved` moves gone from the queue.
+     * [LAW:effects-at-boundaries] Kept once the frame is drawn, never while it is.
+     * The resolved moves leave by identity, not by count: another frame drawing
+     * this viewport in the same pass may already have taken them, and a move
+     * queued since stays.
      */
-    private resolve;
-    measure(rawOptions: RenderOptions): {
-        minimum: number;
-        maximum: number;
-    };
+    private keep;
+    /** `content`, laid out by `layout`, drawn from the scroll and the moves queued against it, with `follow` followed. */
+    private draw;
+    private measureOf;
 }
 /**
  * One viewport per thing a pane shows, named by a key. The same viewport comes
@@ -142,3 +180,4 @@ export declare class ViewportPerKey {
     of(key: string): Viewport;
     private fresh;
 }
+export {};