@promptctl/rich-js 0.19.0 → 0.21.0

package/dist/renderables/flexStrip.d.ts

@@ -17,7 +17,7 @@
  */
 import { Segment } from "../core/segment.js";
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
-import type { Joiner, StyledRenderable } from "../core/strip.js";
+import { type Joiner, type StyledRenderable } from "../core/strip.js";
 export type FlexAlign = "left" | "center" | "right" | "justify";
 export interface FlexStripOptions<T extends StyledRenderable> {
     /** Joiner used between items within a line, and at line endpoints. */

package/dist/renderables/flexStrip.js

@@ -16,6 +16,7 @@
  * FlexStrip reuses it verbatim. There is no second concept of "join."
  */
 import { Segment } from "../core/segment.js";
+import { drawItem, drawJoin } from "../core/strip.js";
 function renderToBlock(r, options) {
     const segments = [...r.render(options)];
     let width = 0;
@@ -63,10 +64,10 @@ export class FlexStrip {
         const joiner = this.joiner;
         // Pre-render every item and every joiner form we might need. Doing this
         // up-front turns packing into a pure data computation over widths.
-        const itemBlocks = items.map((it) => renderToBlock(it, options));
-        const startCap = (i) => joiner ? renderToBlock(joiner.join(null, items[i]), options) : EMPTY_BLOCK;
-        const endCap = (i) => joiner ? renderToBlock(joiner.join(items[i], null), options) : EMPTY_BLOCK;
-        const midJoin = (i, j) => joiner ? renderToBlock(joiner.join(items[i], items[j]), options) : EMPTY_BLOCK;
+        const itemBlocks = items.map((it) => renderToBlock(drawItem(it), options));
+        const startCap = (i) => joiner ? renderToBlock(drawJoin(joiner, null, items[i], { index: i }), options) : EMPTY_BLOCK;
+        const endCap = (i) => joiner ? renderToBlock(drawJoin(joiner, items[i], null, { index: i + 1 }), options) : EMPTY_BLOCK;
+        const midJoin = (i, j) => joiner ? renderToBlock(drawJoin(joiner, items[i], items[j], { index: j }), options) : EMPTY_BLOCK;
         const lines = [];
         let line = null;
         const gapBlock = gap > 0
@@ -177,23 +178,23 @@ export class FlexStrip {
         for (let i = 0; i < items.length; i++) {
             const itemWidth = renderToBlock(items[i], options).width;
             const sc = this.joiner
-                ? renderToBlock(this.joiner.join(null, items[i]), options).width
+                ? renderToBlock(drawJoin(this.joiner, null, items[i], { index: i }), options).width
                 : 0;
             const ec = this.joiner
-                ? renderToBlock(this.joiner.join(items[i], null), options).width
+                ? renderToBlock(drawJoin(this.joiner, items[i], null, { index: i + 1 }), options).width
                 : 0;
             minimum = Math.max(minimum, itemWidth + sc + ec);
             maximum += itemWidth;
             if (i > 0) {
                 maximum += this.gap * 2;
                 if (this.joiner) {
-                    maximum += renderToBlock(this.joiner.join(items[i - 1], items[i]), options).width;
+                    maximum += renderToBlock(drawJoin(this.joiner, items[i - 1], items[i], { index: i }), options).width;
                 }
             }
         }
         if (this.joiner) {
-            maximum += renderToBlock(this.joiner.join(null, items[0]), options).width;
-            maximum += renderToBlock(this.joiner.join(items[items.length - 1], null), options).width;
+            maximum += renderToBlock(drawJoin(this.joiner, null, items[0], { index: 0 }), options).width;
+            maximum += renderToBlock(drawJoin(this.joiner, items[items.length - 1], null, { index: items.length }), options).width;
         }
         return { minimum, maximum };
     }

package/dist/renderables/list-view.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ListView — items stacked down a `Viewport`, scrolled to keep the selected
+ * one in view. `moveSelection` (core/selection) is the cursor that picks it.
+ *
+ * An item can wrap, so the lines the selected one covers exist only at the
+ * width it is drawn at, which a render is handed and whoever builds the frame
+ * is not. So the items are drawn here, at the viewport's content width and
+ * with no height — the lines the viewport scrolls — and the viewport is handed
+ * those lines and the selected item's range.
+ * [LAW:single-enforcer] Where the window sits is the viewport's call; this
+ * only says which lines the selection is.
+ *
+ * The viewport is handed in rather than made here: the scroll position lives
+ * in it, and a frame rebuilt on every key would otherwise start each one at
+ * the top. The pieces stay apart — a cursor, a viewport, a list drawn through
+ * it — so a consumer can take one without the others.
+ */
+import { Segment } from "../core/segment.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import type { Viewport } from "./viewport.js";
+export interface ListViewOptions {
+    /** Blank lines between one item and the next. Absent, none. */
+    gap?: number;
+    /**
+     * Lines kept in view above and below the selected item, where the list has
+     * them: the neighbour a cursor is about to move onto. Absent, none.
+     */
+    context?: number;
+}
+export declare class ListView implements Renderable, Measurable {
+    readonly viewport: Viewport;
+    readonly items: readonly Renderable[];
+    readonly selected: number;
+    readonly gap: number;
+    readonly context: number;
+    constructor(viewport: Viewport, items: readonly Renderable[], selected: number, options?: ListViewOptions);
+    render(rawOptions: RenderOptions): Iterable<Segment>;
+    measure(rawOptions: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/list-view.js

@@ -0,0 +1,78 @@
+/**
+ * ListView — items stacked down a `Viewport`, scrolled to keep the selected
+ * one in view. `moveSelection` (core/selection) is the cursor that picks it.
+ *
+ * An item can wrap, so the lines the selected one covers exist only at the
+ * width it is drawn at, which a render is handed and whoever builds the frame
+ * is not. So the items are drawn here, at the viewport's content width and
+ * with no height — the lines the viewport scrolls — and the viewport is handed
+ * those lines and the selected item's range.
+ * [LAW:single-enforcer] Where the window sits is the viewport's call; this
+ * only says which lines the selection is.
+ *
+ * The viewport is handed in rather than made here: the scroll position lives
+ * in it, and a frame rebuilt on every key would otherwise start each one at
+ * the top. The pieces stay apart — a cursor, a viewport, a list drawn through
+ * it — so a consumer can take one without the others.
+ */
+import { Segment } from "../core/segment.js";
+import { Measurement, measureRenderables } from "../core/measure.js";
+import { withBoundedWidth, withCellWidth } from "../core/protocol.js";
+function lineCount(name, value) {
+    if (!Number.isInteger(value) || value < 0)
+        throw new RangeError(`ListView: ${name} ${value} is not a whole number of lines`);
+    return value;
+}
+export class ListView {
+    viewport;
+    items;
+    selected;
+    gap;
+    context;
+    constructor(viewport, items, selected, options = {}) {
+        this.viewport = viewport;
+        this.items = items;
+        this.selected = selected;
+        this.gap = lineCount("gap", options.gap ?? 0);
+        this.context = lineCount("context", options.context ?? 0);
+        // An empty list's selection is 0: there is nothing for it to name.
+        if (!Number.isInteger(selected) || selected < 0 || selected >= Math.max(1, items.length)) {
+            throw new RangeError(`ListView: selected ${selected} is not an index of ${items.length} items`);
+        }
+    }
+    *render(rawOptions) {
+        const bounded = withBoundedWidth(rawOptions, this);
+        const { height: _height, ...rest } = bounded;
+        const options = { ...rest, maxWidth: this.viewport.contentWidth(rest.maxWidth) };
+        const gap = Array.from({ length: this.gap }, () => []);
+        const drawn = this.items.map((item) => Segment.splitLines(item.render(options)));
+        // The gap sits between items, so every item before the selected one
+        // brings its lines and one gap.
+        const start = drawn.slice(0, this.selected).reduce((total, item) => total + item.length + this.gap, 0);
+        const end = start + (drawn[this.selected]?.length ?? 0);
+        const lines = drawn.flatMap((item, i) => (i === 0 ? item : [...gap, ...item]));
+        this.viewport.content = {
+            *render() {
+                for (const line of lines) {
+                    yield* line;
+                    yield Segment.line();
+                }
+            },
+        };
+        // A range reaching past either end is clamped by the viewport, which holds
+        // its offset to the lines that exist. Followed, not ensured: the wheel can
+        // scroll away from the selection until the selection moves.
+        this.viewport.follow(start - this.context, end + this.context);
+        yield* this.viewport.render(bounded);
+    }
+    measure(rawOptions) {
+        // Stacked, the items are as wide as the widest of them, plus whatever
+        // gutter the viewport's scrollbar takes. `withCellWidth` and not
+        // `withBoundedWidth`: the bounded parse asks this very method.
+        const options = withCellWidth(rawOptions);
+        const contentWidth = this.viewport.contentWidth(options.maxWidth);
+        const gutter = this.viewport.gutter;
+        const items = measureRenderables({ ...options, maxWidth: contentWidth }, this.items);
+        return new Measurement(items.minimum + gutter, items.maximum + gutter).withMaximum(options.maxWidth);
+    }
+}

package/dist/renderables/progress.d.ts

@@ -29,6 +29,11 @@ export interface Task {
     visible: boolean;
     /** When the task started, in seconds on its `Progress`'s clock; undefined until it has. */
     startTime: number | undefined;
+    /**
+     * Rich's `Task.get_time()`: the moment the frame being drawn is drawn at, in
+     * seconds on its `Progress`'s clock, so a column animates without reading one.
+     */
+    time: number;
     /**
      * Rich's `Task.elapsed`: seconds since the task started, as of the frame
      * being drawn — `Progress` reads its clock once a frame and hands columns
@@ -77,6 +82,7 @@ export declare class BarColumn implements ProgressColumn {
     readonly barWidth: number;
     readonly tableColumn: ColumnOptions;
     constructor(barWidth?: number);
+    /** Rich's `BarColumn`: a task not yet started, or with no total to fill toward, pulses. */
     render(task: Task): ProgressBar;
 }
 /**

package/dist/renderables/progress.js

@@ -82,11 +82,14 @@ export class BarColumn {
     constructor(barWidth) {
         this.barWidth = barWidth ?? 40;
     }
+    /** Rich's `BarColumn`: a task not yet started, or with no total to fill toward, pulses. */
     render(task) {
+        const pulsing = task.startTime === undefined || task.total === undefined;
         return new ProgressBar({
             total: task.total ?? 100,
             completed: task.completed,
             width: this.barWidth,
+            pulse: pulsing ? { t: task.time } : undefined,
         });
     }
 }
@@ -283,10 +286,13 @@ export class Progress {
         const task = this._tasks.get(taskId);
         if (!task)
             return;
-        // Rich's order, `completed` then `advance`, checked whole before any field
-        // is written, so a refused update leaves the task as it was.
+        // Rich's order: `advance` is added, then a given `completed` overwrites it,
+        // so `completed` wins when both come. Checked whole before any field is
+        // written, so a refused update leaves the task as it was.
         const advance = finiteCount("advance", options.advance ?? 0);
-        const completed = finiteCount("completed", (options.completed ?? task.completed) + advance);
+        const completed = options.completed === undefined
+            ? finiteCount("completed + advance", task.completed + advance)
+            : finiteCount("completed", options.completed);
         const now = this._clock.now();
         recordSample(task.samples, now, completed - task.completed);
         task.completed = completed;
@@ -326,7 +332,7 @@ export class Progress {
             table.addColumn(undefined, col.tableColumn);
         }
         // [LAW:effects-at-boundaries] One read of the clock a frame, handed to
-        // every column as the task's `elapsed`.
+        // every column as the task's `time` and `elapsed`.
         const now = this._clock.now();
         for (const { samples, ...state } of this._tasks.values()) {
             if (!state.visible)
@@ -335,6 +341,7 @@ export class Progress {
             const started = startTime !== undefined;
             const task = {
                 ...state,
+                time: now,
                 elapsed: started ? now - startTime : undefined,
                 speed: started ? sampleSpeed(samples) : undefined,
             };

package/dist/renderables/progressBar.d.ts

@@ -8,7 +8,15 @@ export interface ProgressBarOptions {
     total?: number;
     completed?: number;
     width?: number;
-    pulse?: boolean;
+    /**
+     * Rich's pulse, for work whose end is not known, drawn as it is `t` seconds
+     * into whoever draws the frames' clock: the whole bar in its back style,
+     * with the library's `shimmer` carrying `bar.pulse` light along it. Without
+     * it, the bar shows `completed` of `total`.
+     */
+    pulse?: {
+        readonly t: number;
+    };
     style?: string | Style;
     completeStyle?: string | Style;
     finishedStyle?: string | Style;
@@ -17,12 +25,24 @@ export declare class ProgressBar implements Renderable, Measurable {
     total: number;
     completed: number;
     readonly width: number | undefined;
-    readonly pulse: boolean;
+    readonly pulse: {
+        readonly t: number;
+    } | undefined;
     readonly style: string | Style;
     readonly completeStyle: string | Style;
     readonly finishedStyle: string | Style;
     constructor(options?: ProgressBarOptions);
     render(options: RenderOptions): Iterable<Segment>;
+    /**
+     * The shimmer over this bar's back colour as `Effected` sees it drawn at
+     * `depth`, toward `bar.pulse`. A bar has no words to keep legible, so its
+     * back takes the whole of the light.
+     */
+    private pulseEffect;
+    /** Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and a total of zero is a bar already full. */
+    private completeHalves;
+    /** The bar `width` cells wide with `completeHalves` half cells filled, the rest in `back`. */
+    private track;
     /** A width given is the bar's exact width, as Rich measures it; one left open fills what it is offered, down to 4. */
     measure(options: RenderOptions): {
         minimum: number;

package/dist/renderables/progressBar.js

@@ -2,13 +2,25 @@
  * ProgressBar — a visual progress bar rendered with block characters.
  */
 import { cellCount } from "../core/cells.js";
+import { ColorDepth, ColorRgba, ColorSpec, resolveTerminal } from "../core/color.js";
 import { Segment } from "../core/segment.js";
-import { NULL_STYLE } from "../core/style.js";
+import { Style } from "../core/style.js";
 import { drawable, getStyle } from "../core/protocol.js";
+import { Effected } from "./effect.js";
+import { EFFECT_CURVES, atShares, shimmer } from "./effects.js";
 const BAR = "━";
 const ASCII_BAR = "-";
 const HALF_BAR_RIGHT = "╸";
 const HALF_BAR_LEFT = "╺";
+/**
+ * The pulse's shimmer: the signed-off ease and swing, at a period that carries
+ * the light along a bar at about Rich's pace, and a band reaching half Rich's
+ * `PULSE_SIZE` of 20 cells either side of its centre.
+ */
+const PULSE_CURVE = { ...EFFECT_CURVES.shimmer, seconds: 5 };
+const PULSE_REACH = 10;
+/** Rich's pulse back where the back style names no colour. */
+const PULSE_BACK = ColorSpec.fromRgba(new ColorRgba(0, 0, 0));
 export class ProgressBar {
     total;
     completed;
@@ -21,8 +33,8 @@ export class ProgressBar {
         this.total = options?.total ?? 100;
         this.completed = options?.completed ?? 0;
         this.width = options?.width;
-        this.pulse = options?.pulse ?? false;
-        this.style = options?.style ?? NULL_STYLE;
+        this.pulse = options?.pulse;
+        this.style = options?.style ?? "bar.back";
         this.completeStyle = options?.completeStyle ?? "bar.complete";
         this.finishedStyle = options?.finishedStyle ?? "bar.finished";
     }
@@ -30,15 +42,48 @@ export class ProgressBar {
         // Never wider than offered, as Rich's `min(self.width or max_width, max_width)`.
         // [LAW:parse-dont-validate] parsed as a cell count, so a negative width draws nothing, as Python's `"━" * -2` is "".
         const width = cellCount(Math.min(this.width || options.maxWidth, options.maxWidth));
-        // Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and
-        // a total of zero is a bar already full.
+        if (this.pulse === undefined) {
+            yield* this.track(options, width, this.completeHalves(width), getStyle(options, this.style));
+            return;
+        }
+        const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
+        // Rich's pulse resolves its colours on the terminal a depth assumes, as
+        // `get_truecolor` does with no theme; so does this.
+        const theme = resolveTerminal(undefined, depth);
+        // Rich writes the pulse's back as a colour of its own, black where the
+        // back style names none, so the light always has the bar's colour to fall
+        // on: one the terminal supplies takes no light.
+        const style = getStyle(options, this.style);
+        const ink = style.color?.isDefault === false ? style.color : ColorSpec.fromRgba((style.color ?? PULSE_BACK).getTruecolor(theme, true));
+        const back = style.add(Style.fromColor(ink));
+        // [LAW:no-ambient-temporal-coupling] The moment is the caller's; the bar
+        // only says what it looks like then. An empty track, lit by the shimmer.
+        const track = { render: (o) => this.track(o, width, 0, back) };
+        yield* new Effected(track, this.pulseEffect(options, back, width, depth, theme), { t: this.pulse.t, key: "progress-bar", theme }).render(options);
+    }
+    /**
+     * The shimmer over this bar's back colour as `Effected` sees it drawn at
+     * `depth`, toward `bar.pulse`. A bar has no words to keep legible, so its
+     * back takes the whole of the light.
+     */
+    pulseEffect(options, back, width, depth, theme) {
+        const ink = back.drawnColors(depth).color ?? ColorSpec.default();
+        const glow = getStyle(options, "bar.pulse").drawnColors(depth).color ?? ColorSpec.default();
+        const loop = shimmer(PULSE_CURVE, width, PULSE_REACH, glow.getTruecolor(theme, true), 0);
+        const whole = new Map([[ink.getTruecolor(theme, true).hex, 1]]);
+        return atShares(loop, () => whole);
+    }
+    /** Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and a total of zero is a bar already full. */
+    completeHalves(width) {
         const completed = Math.min(this.total, Math.max(0, this.completed));
-        const completeHalves = this.total ? Math.trunc((width * 2 * completed) / this.total) : width * 2;
+        return this.total ? Math.trunc((width * 2 * completed) / this.total) : width * 2;
+    }
+    /** The bar `width` cells wide with `completeHalves` half cells filled, the rest in `back`. */
+    *track(options, width, completeHalves, back) {
         const barCount = Math.floor(completeHalves / 2);
         const halfBarCount = completeHalves % 2;
         const isFinished = this.completed >= this.total;
         const fill = getStyle(options, isFinished ? this.finishedStyle : this.completeStyle);
-        const back = getStyle(options, this.style);
         const fillStyle = fill.isNull ? undefined : fill;
         const backStyle = back.isNull ? undefined : back;
         const bar = drawable(options, BAR, ASCII_BAR);

package/dist/renderables/rule.d.ts

@@ -2,8 +2,8 @@
  * Rule — a horizontal divider line, optionally with a centered title.
  */
 import { Segment } from "../core/segment.js";
-import type { RichText } from "../core/text.js";
-import { Style } from "../core/style.js";
+import { type RichText } from "../core/text.js";
+import type { Style } from "../core/style.js";
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 export type RuleAlign = "left" | "center" | "right";
 export interface RuleOptions {

package/dist/renderables/rule.js

@@ -3,8 +3,8 @@
  */
 import { asCellCol, cellLen, setCellSize } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
-import { NULL_STYLE } from "../core/style.js";
-import { drawable, getStyle } from "../core/protocol.js";
+import { resolveStyle } from "../core/text.js";
+import { drawable } from "../core/protocol.js";
 import { cutLabel, drawLabel, inlineLabel } from "./embed.js";
 const ASCII_RULE_CHAR = "-";
 const DEFAULT_RULE_CHAR = "\u2500"; // ─
@@ -29,12 +29,14 @@ export class Rule {
         this._label = inlineLabel(title);
         this.characters = chars;
         this.align = align ?? "center";
-        this.style = options?.style ?? NULL_STYLE;
+        this.style = options?.style ?? "rule.line";
     }
     *render(options) {
         const maxWidth = options.maxWidth;
         const ruleChar = drawable(options, this.characters, ASCII_RULE_CHAR);
-        const style = getStyle(options, this.style);
+        // [LAW:single-enforcer] Resolved as Rich resolves the span it appends the
+        // line in: a name the theme lacks draws unstyled rather than throwing.
+        const style = resolveStyle(options, this.style);
         const ruleStyle = style.isNull ? undefined : style;
         const line = (width) => new Segment(repeatToWidth(ruleChar, width), ruleStyle);
         // Rich's `required_space`: a centred title keeps a rule cell and a space
@@ -46,20 +48,20 @@ export class Rule {
             yield Segment.line();
             return;
         }
-        const text = this._label.text(options);
+        // Rich's `render_str(title, style="rule.text")`: the title is read in its
+        // own style and set beside the line, never in the line's style.
+        const text = this._label.text(options, "rule.text");
         cutLabel(text, room, drawable(options, "\u2026", "."));
-        const title = drawLabel(text, options, ruleStyle);
+        const title = drawLabel(text, options, undefined);
         const titleWidth = Segment.getLineLength(title);
         // As Rich lays the line out: the gaps of a centred title are the rule's,
         // styled with it; an aligned title's one gap is unstyled.
         switch (this.align) {
             case "center": {
                 const left = Math.floor((maxWidth - titleWidth) / 2) - 1;
-                yield line(left);
-                yield new Segment(" ", ruleStyle);
+                yield new Segment(`${repeatToWidth(ruleChar, left)} `, ruleStyle);
                 yield* title;
-                yield new Segment(" ", ruleStyle);
-                yield line(maxWidth - left - titleWidth - 2);
+                yield new Segment(` ${repeatToWidth(ruleChar, maxWidth - left - titleWidth - 2)}`, ruleStyle);
                 break;
             }
             case "left":

package/dist/renderables/table.js

@@ -924,12 +924,11 @@ export class Table {
     }
     *_renderTitle(options, text, tableWidth, ownStyle, justify) {
         // The table owns the canvas; the caller's text still says how it meets the
-        // edge. A `RichText`'s own `justify` and `overflow` outrank the options
-        // `render` is handed, so `titleJustify` would lose to a property the caller
-        // may not know it set, and an `"ignore"` title would have no edge and run
-        // straight through the frame. Every other method, and `noWrap`, cuts within
-        // the bound, so those stay theirs. `text` hands back a copy to clear them
-        // on. [LAW:one-source-of-truth]
+        // edge. A `RichText`'s own `justify` outranks `titleJustify`, as a `Text`'s
+        // does in the reference (rich-table-qj6i.kpp). Its own `overflow` does too,
+        // but for `"ignore"`: that title would have no edge and run straight
+        // through the frame. Every other method, and `noWrap`, cuts within the
+        // bound, so those stay theirs. `text` hands back a copy to clear it on.
         //
         // Never highlighted, and markup as the console says: Rich draws a title
         // and caption through `render_str(highlight=False)`.
@@ -941,7 +940,6 @@ export class Table {
         // the reference renders a `Text` title without the title style
         // (rich-table-qj6i).
         const source = text.text({ ...options, highlight: false }, getStyle(options, ownStyle));
-        source.justify = undefined;
         if (source.overflow === "ignore")
             source.overflow = undefined;
         //

package/dist/renderables/viewport.d.ts

@@ -71,6 +71,7 @@ export declare class Viewport implements Renderable, Measurable, Scrollable {
     private _offset;
     private _extent;
     private _moves;
+    private _followed;
     constructor(content: Renderable, options?: ViewportOptions);
     /**
      * The first content line the last render showed. A move requested since is
@@ -94,11 +95,24 @@ export declare class Viewport implements Renderable, Measurable, Scrollable {
      * the viewport shows its first line at the top.
      */
     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.
+     */
+    follow(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;
+    /** The cells the scrollbar's gutter takes beside the content. */
+    get gutter(): number;
     render(rawOptions: RenderOptions): Iterable<Segment>;
     /**
      * [LAW:one-source-of-truth] Where the queued moves leave the offset against
@@ -112,3 +126,19 @@ export declare class Viewport implements Renderable, Measurable, Scrollable {
         maximum: number;
     };
 }
+/**
+ * One viewport per thing a pane shows, named by a key. The same viewport comes
+ * back while the key holds, so its scroll position does too; a new key gets a
+ * fresh one, so a new subject opens at its top rather than wherever the last
+ * one was left. A frame is rebuilt on every key press and a scroll position is
+ * a viewport's, so this is what outlives the frame for a pane whose subject
+ * changes under it.
+ */
+export declare class ViewportPerKey {
+    private readonly options;
+    private held;
+    constructor(options?: ViewportOptions);
+    /** The viewport for `key`: the held one while the key holds, a fresh one otherwise. */
+    of(key: string): Viewport;
+    private fresh;
+}

package/dist/renderables/viewport.js

@@ -58,6 +58,8 @@ export class Viewport {
     // Nothing rendered, nothing shown: no move can take until the first render.
     _extent = { rows: 0, lines: 0 };
     _moves = [];
+    // No range followed yet: NaN equals nothing, so the first `follow` moves.
+    _followed = { start: NaN, end: NaN, rows: NaN };
     constructor(content, options = {}) {
         this.content = content;
         this.rows = options.rows;
@@ -96,20 +98,47 @@ export class Viewport {
     ensureVisible(start, end) {
         this._moves.push((offset, { rows }) => Math.min(start, Math.max(offset, end - rows)));
     }
+    /**
+     * `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.
+     */
+    follow(start, end) {
+        if (start === this._followed.start && end === this._followed.end)
+            return;
+        this._followed = { start, end, rows: NaN };
+        this.ensureVisible(start, end);
+    }
     /**
      * 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));
+        return cellCount(width - this.gutter);
+    }
+    /** The cells the scrollbar's gutter takes beside the content. */
+    get gutter() {
+        return gutterWidth(this.scrollbar);
     }
     *render(rawOptions) {
         const { height, ...options } = withBoundedWidth(rawOptions, this);
-        const gutter = gutterWidth(this.scrollbar);
+        const gutter = this.gutter;
         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 };
+        const followed = this._followed;
+        const wasShown = followed.start >= this._offset && followed.end <= this._offset + this._extent.rows;
         this._extent = extent;
+        if (!Number.isNaN(followed.rows) && followed.rows !== extent.rows && wasShown) {
+            this.ensureVisible(followed.start, followed.end);
+        }
+        if (!Number.isNaN(followed.start))
+            this._followed = { ...followed, rows: extent.rows };
         this._offset = this.resolve(extent);
         this._moves = [];
         const shown = fitHeight(lines.slice(this._offset, this._offset + extent.rows), { rows: extent.rows, exact: true });
@@ -153,12 +182,39 @@ export class Viewport {
         // `withBoundedWidth`: the bounded parse asks this very method for the
         // natural width.
         const options = withCellWidth(rawOptions);
-        const gutter = gutterWidth(this.scrollbar);
+        const gutter = this.gutter;
         const inner = { ...options, maxWidth: this.contentWidth(options.maxWidth) };
         const content = Measurement.get(inner, this.content);
         return new Measurement(content.minimum + gutter, content.maximum + gutter).withMaximum(options.maxWidth);
     }
 }
+/**
+ * One viewport per thing a pane shows, named by a key. The same viewport comes
+ * back while the key holds, so its scroll position does too; a new key gets a
+ * fresh one, so a new subject opens at its top rather than wherever the last
+ * one was left. A frame is rebuilt on every key press and a scroll position is
+ * a viewport's, so this is what outlives the frame for a pane whose subject
+ * changes under it.
+ */
+export class ViewportPerKey {
+    options;
+    held;
+    constructor(options = {}) {
+        this.options = options;
+        this.held = { key: "", viewport: this.fresh() };
+    }
+    /** The viewport for `key`: the held one while the key holds, a fresh one otherwise. */
+    of(key) {
+        if (key !== this.held.key)
+            this.held = { key, viewport: this.fresh() };
+        return this.held.viewport;
+    }
+    fresh() {
+        // Empty until a view hands it content: the content is built where the frame is.
+        return new Viewport(EMPTY, this.options);
+    }
+}
+const EMPTY = { *render() { } };
 const scrollbarGlyphs = ({ thumb, track }) => thumb.glyph + track.glyph;
 /** `scrollbar` in its own styles, drawn in ASCII. */
 function asciiScrollbar({ thumb, track }) {