@promptctl/rich-js 0.17.0 → 0.18.1

package/dist/renderables/traceback.js

@@ -23,16 +23,17 @@ function parseStack(error) {
     const lines = stack.split("\n");
     const frames = [];
     for (const line of lines) {
-        const trimmed = line.trim();
-        // Node.js format: "    at functionName (file:line:column)"
-        // or:            "    at file:line:column"
-        const match = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?/.exec(trimmed);
+        // 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),
-                column: parseInt(match[4], 10),
             });
         }
     }
@@ -100,10 +101,8 @@ export class Traceback {
             yield new Segment(" ");
         }
         yield new Segment(frame.file, pathStyle);
-        if (frame.line !== undefined) {
-            yield new Segment(":");
-            yield new Segment(String(frame.line), lineNoStyle);
-        }
+        yield new Segment(":");
+        yield new Segment(String(frame.line), lineNoStyle);
         yield Segment.line();
     }
 }

package/dist/renderables/tree.d.ts

@@ -21,6 +21,13 @@ export declare class Tree implements Renderable, Measurable {
     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.
      *
@@ -29,11 +36,15 @@ export declare class Tree implements Renderable, Measurable {
      * `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 guides, then its label in whatever width the
-     * guides left.
+     * 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
@@ -44,7 +55,10 @@ export declare class Tree implements Renderable, Measurable {
      * 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.
+     * 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): {

package/dist/renderables/tree.js

@@ -3,30 +3,19 @@
  */
 import { Segment } from "../core/segment.js";
 import { cellFit, cellLen, asCellCol } from "../core/cells.js";
-import { NULL_STYLE } from "../core/style.js";
-import { RichText } from "../core/text.js";
-import { getStyle, isMeasurable, withBoundedWidth, withCellWidth } from "../core/protocol.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";
-// Guide characters
-const GUIDE_BRANCH = "├── ";
-const GUIDE_LAST = "└── ";
-const GUIDE_VERT = "│   ";
-const GUIDE_SPACE = "    ";
-// ASCII fallback
-const GUIDE_BRANCH_ASCII = "+-- ";
-const GUIDE_LAST_ASCII = "+-- ";
-const GUIDE_VERT_ASCII = "|   ";
-function toRenderable(label) {
-    if (typeof label === "string")
-        return new RichText(label, { end: "" });
-    if (label instanceof RichText) {
-        // Ensure no trailing newline in tree labels
-        const copy = label.copy();
-        copy.end = "";
-        return copy;
-    }
-    return label;
-}
+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
@@ -45,7 +34,7 @@ export class Tree {
     guideStyle;
     style;
     constructor(label, options) {
-        this.label = toRenderable(label);
+        this.label = embed(label);
         this.children = [];
         this.expanded = options?.expanded !== false;
         this.hideRoot = options?.hideRoot ?? false;
@@ -63,10 +52,20 @@ export class Tree {
     }
     *render(rawOptions) {
         const options = withBoundedWidth(rawOptions, this);
-        for (const row of this._rows(options, [], !this.hideRoot)) {
+        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.
      *
@@ -75,41 +74,24 @@ export class Tree {
      * `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(options, prefixes, showLabel) {
-        const ascii = options.asciiOnly ?? false;
-        if (showLabel) {
-            yield { guides: prefixes, guideStyles: [this.guideStyle], label: this.label };
-        }
-        if (!this.expanded)
-            return;
-        for (let i = 0; i < this.children.length; i++) {
-            const child = this.children[i];
-            const isLast = i === this.children.length - 1;
-            const branch = ascii
-                ? (isLast ? GUIDE_LAST_ASCII : GUIDE_BRANCH_ASCII)
-                : (isLast ? GUIDE_LAST : GUIDE_BRANCH);
-            const continuation = ascii
-                ? (isLast ? GUIDE_SPACE : GUIDE_VERT_ASCII)
-                : (isLast ? GUIDE_SPACE : GUIDE_VERT);
-            // Child label with branch guide
-            yield {
-                guides: [...prefixes, branch],
-                guideStyles: [child.guideStyle, this.guideStyle],
-                label: child.label,
-            };
-            // Grandchildren with continuation prefix
-            if (child.expanded && child.children.length > 0) {
-                const grandPrefixes = [...prefixes, continuation];
-                for (let j = 0; j < child.children.length; j++) {
-                    yield* child.children[j]._rows(options, grandPrefixes, true);
-                }
-            }
+    *_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 guides, then its label in whatever width the
-     * guides left.
+     * 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
@@ -120,22 +102,31 @@ export class Tree {
      * 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.
+     * 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 guideStyle = row.guideStyles.map((style) => getStyle(options, style)).find((style) => !style.isNull);
-        let left = options.maxWidth;
-        for (const text of row.guides) {
-            const piece = cellFit(text, asCellCol(left));
-            if (piece.length > 0)
-                yield new Segment(piece, guideStyle);
-            left -= cellLen(piece);
+        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();
         }
-        // The guides above are cropped by `cellFit`; the label was not, so a label
-        // that ignores the width it is handed pushed the row past the offer the
-        // guides had just been fitted into.
-        yield* Segment.cropLines(row.label.render({ ...options, maxWidth: left }), left);
-        yield Segment.line();
     }
     measure(options) {
         // The ceiling is parsed for the same reason the rows are: an unparsed NaN
@@ -147,8 +138,8 @@ export class Tree {
         // mode drew a 40-cell frame around nine cells of tree, and an unbounded
         // offer came back unbounded.
         let natural = 0;
-        for (const row of this._rows(parsed, [], !this.hideRoot)) {
-            const guideWidth = row.guides.reduce((sum, text) => sum + cellLen(text), 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);

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));
+}

package/dist/template-bindings/color-funcs.js

@@ -77,20 +77,19 @@ function asColor(value, func) {
     }
     return parseHexColor(value);
 }
+// [LAW:single-enforcer] Every colour function is fixed-arity, so the engine's
+// arity gate refuses a missing or surplus argument before the body runs.
 function colorFunc(argTypes, fn) {
-    return { fn, argTypes, returnType: "string" };
+    return { fn, argTypes, arity: { kind: "exact" }, returnType: "string" };
 }
 /**
  * The gate every *numeric* argument crosses, with an optional inclusive range.
  *
- * [LAW:single-enforcer] One check for the whole family. The template engine
- * treats a trailing slot as variadic, so an under-supplied call
- * (`{{ darken "#102030" }}`) reaches the body with `undefined` rather than
- * failing at the gate. Without this, that `undefined` propagated into the color
- * math and surfaced as `ColorRgba.red must be an integer in [0, 255]; got NaN`
- * — loud, but pointing at a channel the author never wrote, three layers from
- * the missing argument. An error that does not locate its cause is barely
- * better than a silent one. [LAW:no-silent-failure]
+ * [LAW:single-enforcer] One check for every `"float"` slot. An `"int"` slot is
+ * a safe integer by the engine's gate and needs none, but a `"float"` slot admits
+ * NaN and Infinity (legitimate IEEE-754 values), which would otherwise surface
+ * as `ColorRgba.red must be an integer in [0, 255]; got NaN` — loud, but
+ * pointing at a channel the author never wrote. [LAW:no-silent-failure]
  */
 function asAmount(value, func, param, range) {
     const inRange = range === undefined || (value >= range.min && value <= range.max);
@@ -98,8 +97,7 @@ function asAmount(value, func, param, range) {
         const bound = range === undefined
             ? "a finite number"
             : `within ${range.min}..${range.max} (${range.note})`;
-        throw new RangeError(`${func}'s ${param} must be ${bound}, got ${value}` +
-            (value === undefined ? ` — ${func} takes it as its last argument` : ""));
+        throw new RangeError(`${func}'s ${param} must be ${bound}, got ${value}`);
     }
     return value;
 }
@@ -109,8 +107,8 @@ function asAmount(value, func, param, range) {
 // second one (colorMath's `lighten` is literally `darken(c, -levels)`). Both
 // names ship because "lighten by 2" and "darken by -2" are not equally
 // readable at a call site, and the operation is genuinely bidirectional.
-const darkenFunc = colorFunc(["string", "int"], ((hex, levels) => darken(asColor(hex, "darken"), asAmount(levels, "darken", "levels")).hex));
-const lightenFunc = colorFunc(["string", "int"], ((hex, levels) => darken(asColor(hex, "lighten"), -asAmount(levels, "lighten", "levels")).hex));
+const darkenFunc = colorFunc(["string", "int"], ((hex, levels) => darken(asColor(hex, "darken"), levels).hex));
+const lightenFunc = colorFunc(["string", "int"], ((hex, levels) => darken(asColor(hex, "lighten"), -levels).hex));
 // --- Blending ---
 //
 // [LAW:one-type-per-behavior] There is no separate `alphaBlend` binding.

package/dist/template-bindings/index.js

@@ -120,11 +120,13 @@ export function renderTemplate(engine, source, scope = {}, options) {
         return Array.from(rt.render({
             maxWidth: options?.maxWidth ?? 400,
             isTerminal: true,
-            encoding: "utf-8",
         }));
     }
     catch (e) {
-        return [new Segment(`[error: ${String(e).slice(0, 80)}]`, safeErrorStyle(options?.errorStyle))];
+        // An engine error's `message` is its one-line summary; `String(e)` adds a
+        // multi-line code frame, which would break this single segment across lines.
+        const summary = e instanceof Error ? e.message : String(e);
+        return [new Segment(`[error: ${summary.slice(0, 80)}]`, safeErrorStyle(options?.errorStyle))];
     }
 }
 // [LAW:single-enforcer] The error-path Style must not itself throw, or