@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/renderables/columns.js

@@ -0,0 +1,152 @@
+/**
+ * Columns — arranges renderables in a multi-column layout.
+ */
+import { Segment } from "../core/segment.js";
+import { Measurement } from "../core/measure.js";
+import { isMeasurable, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { cellCount } from "../core/cells.js";
+import { embed } from "./embed.js";
+export class Columns {
+    renderables;
+    expand;
+    equal;
+    colWidth;
+    columnFirst;
+    gutterWidth;
+    constructor(items, options) {
+        this.renderables = items ? [...items].map(embed) : [];
+        this.expand = options?.expand ?? false;
+        this.equal = options?.equal ?? false;
+        // A declared column width is a cell count like any other, and it reaches
+        // the layout without passing through `withCellWidth`, which parses only
+        // what the *caller of render* supplied. Left raw, `width: NaN` made
+        // `Math.max(1, NaN)` a NaN column count and `new Array` threw `Invalid
+        // array length` before a single column was laid out. Absence is preserved
+        // rather than parsed: `undefined` selects auto-fit, and `cellCount` would
+        // read it as a declared zero.
+        this.colWidth = options?.width === undefined ? undefined : cellCount(options.width);
+        this.columnFirst = options?.columnFirst ?? false;
+        this.gutterWidth = 2; // default gutter between columns
+    }
+    *render(rawOptions) {
+        const items = this.renderables;
+        if (items.length === 0)
+            return;
+        // The parsed options, not just a parsed local: `_divide` hands them to
+        // `Measurement.get`, and a raw NaN reaching it comes back as a NaN item
+        // width, then a NaN column count, then `Invalid array length` out of
+        // `new Array(numCols)` before a single column is laid out. An unbounded
+        // width reaches the same `new Array` by the same route, which is why the
+        // parse here is the bounded one.
+        const options = withBoundedWidth(rawOptions, this);
+        const { numCols, colWidths } = this._divide(options);
+        // Layout items into rows
+        const numRows = Math.ceil(items.length / numCols);
+        // [LAW:types-are-the-program] The element type is Renderable — any number
+        // of lines. Each grid cell renders to its full set of lines; an out-of-range
+        // slot (the last row is rarely full) is an empty cell. mergeHorizontal then
+        // stacks every row of every cell line-by-line, so multi-line children
+        // (Panels, Tables) compose instead of being truncated to their first row.
+        for (let row = 0; row < numRows; row++) {
+            const cells = colWidths.map((width, col) => {
+                const idx = this.columnFirst ? col * numRows + row : row * numCols + col;
+                const item = items[idx];
+                const lines = item === undefined
+                    ? []
+                    : Segment.splitLines([
+                        ...item.render({ ...options, maxWidth: width, height: stackedHeight(options.height) }),
+                    ]);
+                return { lines, width };
+            });
+            yield* Segment.mergeHorizontal(cells, this.gutterWidth);
+        }
+    }
+    /**
+     * The requested width divided into columns, once.
+     *
+     * [LAW:single-enforcer] The three modes disagree only about how many columns
+     * there are and how wide each one is, so they disagree in one place. `render`
+     * lays out against this division and `_naturalWidth` is the width at which it
+     * comes out as one row of every item.
+     */
+    _divide(options) {
+        const maxWidth = options.maxWidth;
+        const gutter = this.gutterWidth;
+        const declared = this._declaredWidth(options);
+        if (declared !== undefined) {
+            const numCols = Math.max(1, Math.floor((maxWidth + gutter) / (declared + gutter)));
+            return { numCols, colWidths: new Array(numCols).fill(declared) };
+        }
+        if (this.equal) {
+            const itemWidth = this._itemWidth(options);
+            const numCols = Math.max(1, Math.floor((maxWidth + gutter) / (itemWidth + gutter)));
+            const equalWidth = Math.floor((maxWidth - gutter * (numCols - 1)) / numCols);
+            return { numCols, colWidths: new Array(numCols).fill(equalWidth) };
+        }
+        // Auto: as many columns as the widest item fits into, capped at the item
+        // count. Sized from the content rather than from a flat four cells per
+        // column, because `_naturalWidth` below is the inverse of *this* expression
+        // and a constant has no inverse: six two-cell items reported a natural
+        // width of 22 and then wrapped into two rows at 22, since `floor(22 / 4)`
+        // is five columns no matter how narrow the items are.
+        const itemWidth = this._itemWidth(options);
+        const numCols = Math.min(this.renderables.length, Math.max(1, Math.floor((maxWidth + gutter) / (itemWidth + gutter))));
+        const colW = Math.floor((maxWidth - gutter * (numCols - 1)) / numCols);
+        return { numCols, colWidths: new Array(numCols).fill(colW) };
+    }
+    /**
+     * The widest any one item wants to be.
+     *
+     * An item that cannot measure itself wants the offer, which is what `Panel`,
+     * `Padding`, `Layout` and `Tree` all answer for the same case — and under an
+     * unbounded offer that is `Infinity`, so `withBoundedWidth` throws and says
+     * the request was unanswerable. Counting it as one cell instead reported a
+     * natural width of 1, which resolved an unbounded offer to a single column and
+     * cropped forty cells of content down to `"x"` with no error at all.
+     */
+    _itemWidth(options) {
+        let widest = 1;
+        for (const item of this.renderables) {
+            widest = Math.max(widest, isMeasurable(item)
+                ? Measurement.get(options, item).maximum
+                : options.maxWidth);
+        }
+        return widest;
+    }
+    /**
+     * The declared column width, bounded by the width offered.
+     *
+     * [LAW:single-enforcer] A declared width is what a column asks for, not what
+     * it takes — the contract `Table._outerWidth` keeps for a declared table
+     * width. Read by `_divide` for render and by `_naturalWidth` for measure, so
+     * the two answer from one number: laid out at the raw declared width, a
+     * six-cell column offered three emitted six-cell lines while `measure`
+     * reported three, and the terminal's soft wrap took the frame of everything
+     * printed after it.
+     */
+    _declaredWidth(options) {
+        return this.colWidth === undefined ? undefined : Math.min(this.colWidth, options.maxWidth);
+    }
+    /** The width at which every item sits on one row: n columns and the gutters between them. */
+    _naturalWidth(options) {
+        const count = this.renderables.length;
+        if (count === 0)
+            return 0;
+        const width = this._declaredWidth(options) ?? this._itemWidth(options);
+        return count * width + this.gutterWidth * (count - 1);
+    }
+    measure(rawOptions) {
+        // A floor of one cell is what Columns asks for; the ceiling is what it was
+        // offered, and the ceiling wins. Stated as a bare `minimum: 1`, a Columns
+        // measured into no width at all reported the range 1..0 — a floor above
+        // its own ceiling, which the parent that asked cannot divide.
+        //
+        // The ceiling is not the whole answer, though: reported as the offer alone,
+        // a Columns claimed every cell it was shown, so `Panel` in fit mode drew a
+        // 40-cell frame around five cells of content and an unbounded offer came
+        // back unbounded.
+        const parsed = withCellWidth(rawOptions);
+        const maximum = Math.min(this._naturalWidth(parsed), parsed.maxWidth);
+        return { minimum: Math.min(1, maximum), maximum };
+    }
+}

package/dist/renderables/constrain.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Constrain — wraps a renderable and constrains its maximum width.
+ */
+import { Segment } from "../core/segment.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export declare class Constrain implements Renderable, Measurable {
+    readonly renderable: Renderable;
+    readonly width: number | undefined;
+    constructor(renderable: Renderable, width?: number);
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/constrain.js

@@ -0,0 +1,37 @@
+/**
+ * Constrain — wraps a renderable and constrains its maximum width.
+ */
+import { Measurement } from "../core/measure.js";
+import { isMeasurable } from "../core/protocol.js";
+export class Constrain {
+    renderable;
+    width;
+    constructor(renderable, width) {
+        this.renderable = renderable;
+        this.width = width;
+    }
+    *render(options) {
+        // [LAW:dataflow-not-control-flow] Always compute constrainedWidth; undefined means no constraint
+        const constrainedWidth = this.width !== undefined
+            ? Math.min(this.width, options.maxWidth)
+            : options.maxWidth;
+        const innerOptions = {
+            ...options,
+            maxWidth: constrainedWidth,
+        };
+        yield* this.renderable.render(innerOptions);
+    }
+    measure(options) {
+        if (isMeasurable(this.renderable)) {
+            const measurement = Measurement.get(options, this.renderable);
+            const maxWidth = this.width !== undefined
+                ? Math.min(this.width, options.maxWidth)
+                : options.maxWidth;
+            return {
+                minimum: measurement.minimum,
+                maximum: Math.min(measurement.maximum, maxWidth),
+            };
+        }
+        return { minimum: 1, maximum: options.maxWidth };
+    }
+}

package/dist/renderables/embed.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one crossing where content a caller hands a renderable — a table cell, a
+ * panel's body, title or subtitle, a tree label, a column item, a layout pane,
+ * a rule's title — becomes something that renderable can lay out.
+ * [LAW:single-enforcer]
+ *
+ * Each of those sites used to build its own `RichText` straight from the
+ * constructor, which does not parse markup, so `[red]Solo[/red]` reached the
+ * terminal with its tags intact. Table cells were fixed on their own first; the
+ * rest kept the defect until the rule moved here.
+ *
+ * Markup is parsed because Rich parses it: every one of these positions
+ * reaches the wire through Rich's `render_str`, and a console's markup is on by
+ * default. Rich's `render_str` also honours `Console(markup=False)` and runs the
+ * console's highlighter; this crossing does neither, because the console's
+ * settings do not reach it (rich-markup-3sw).
+ *
+ * `end` is cleared because embedded text is a fragment rather than a printed
+ * line; left at the default `"\n"` it draws a trailing blank row. A `RichText`
+ * is copied first, since clearing in place would reach back into the caller's
+ * object.
+ */
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import { Segment } from "../core/segment.js";
+import type { Style } from "../core/style.js";
+import { RichText } from "../core/text.js";
+/**
+ * Caller content as the text an embedding site lays out, `end` cleared. A
+ * string is the only kind of content that can contain markup, so it is the only
+ * kind parsed; any other value is its `String` form as written, so an object's
+ * `[object Object]` is not eaten as a tag.
+ */
+export declare function embeddedText(content: unknown): RichText;
+/**
+ * Caller content as something an embedding site can render. A non-text
+ * `Renderable` (a nested `Panel` or `Table`) passes through: it carries no
+ * `end` to clear and no markup to parse. Everything else is `embeddedText`.
+ */
+export declare function embed(content: unknown): Renderable & Partial<Measurable>;
+/**
+ * Caller content set into a line it shares with other drawing — a panel's
+ * title or subtitle in its border, a rule's title — as one line of segments:
+ * a space either side, its own styles over `base`. The caller cuts it to the
+ * room it has with `Segment.adjustLineLength`, which is cell-aware.
+ *
+ * Content with no text is no label at all, not two spaces: an absent title, an
+ * empty string, an empty `RichText` and markup that styles nothing all draw
+ * the plain line, as Rich's do (an empty `Text` is falsy there).
+ */
+export declare function inlineLabel(content: unknown, options: RenderOptions, base: Style | undefined): Segment[];

package/dist/renderables/embed.js

@@ -0,0 +1,71 @@
+/**
+ * The one crossing where content a caller hands a renderable — a table cell, a
+ * panel's body, title or subtitle, a tree label, a column item, a layout pane,
+ * a rule's title — becomes something that renderable can lay out.
+ * [LAW:single-enforcer]
+ *
+ * Each of those sites used to build its own `RichText` straight from the
+ * constructor, which does not parse markup, so `[red]Solo[/red]` reached the
+ * terminal with its tags intact. Table cells were fixed on their own first; the
+ * rest kept the defect until the rule moved here.
+ *
+ * Markup is parsed because Rich parses it: every one of these positions
+ * reaches the wire through Rich's `render_str`, and a console's markup is on by
+ * default. Rich's `render_str` also honours `Console(markup=False)` and runs the
+ * console's highlighter; this crossing does neither, because the console's
+ * settings do not reach it (rich-markup-3sw).
+ *
+ * `end` is cleared because embedded text is a fragment rather than a printed
+ * line; left at the default `"\n"` it draws a trailing blank row. A `RichText`
+ * is copied first, since clearing in place would reach back into the caller's
+ * object.
+ */
+import { renderMarkup } from "../core/markup.js";
+import { Segment } from "../core/segment.js";
+import { RichText } from "../core/text.js";
+/**
+ * Caller content as the text an embedding site lays out, `end` cleared. A
+ * string is the only kind of content that can contain markup, so it is the only
+ * kind parsed; any other value is its `String` form as written, so an object's
+ * `[object Object]` is not eaten as a tag.
+ */
+export function embeddedText(content) {
+    const text = content instanceof RichText
+        ? content.copy()
+        : typeof content === "string"
+            ? renderMarkup(content)
+            : new RichText(String(content ?? ""));
+    text.end = "";
+    return text;
+}
+/**
+ * Caller content as something an embedding site can render. A non-text
+ * `Renderable` (a nested `Panel` or `Table`) passes through: it carries no
+ * `end` to clear and no markup to parse. Everything else is `embeddedText`.
+ */
+export function embed(content) {
+    if (!(content instanceof RichText) && typeof content === "object" && content !== null && "render" in content) {
+        return content;
+    }
+    return embeddedText(content);
+}
+/**
+ * Caller content set into a line it shares with other drawing — a panel's
+ * title or subtitle in its border, a rule's title — as one line of segments:
+ * a space either side, its own styles over `base`. The caller cuts it to the
+ * room it has with `Segment.adjustLineLength`, which is cell-aware.
+ *
+ * Content with no text is no label at all, not two spaces: an absent title, an
+ * empty string, an empty `RichText` and markup that styles nothing all draw
+ * the plain line, as Rich's do (an empty `Text` is falsy there).
+ */
+export function inlineLabel(content, options, base) {
+    // The label leaves at its natural width, `"ignore"`, because the caller does
+    // the cutting; the label's own overflow method would cut it first, and to a
+    // width no one measured. `"ignore"` also leaves it unjustified, so its spaces
+    // stay where `pad` put them.
+    const bare = embeddedText(content);
+    const text = bare.plain === "" ? bare : bare.pad(1);
+    text.overflow = "ignore";
+    return [...Segment.applyStyle(text.render(options), base)];
+}

package/dist/renderables/flexStrip.d.ts

@@ -0,0 +1,41 @@
+/**
+ * FlexStrip — wrap-to-width horizontal layout for `StyledRenderable` items.
+ *
+ * Pack as many items as fit on a line, then break and continue. Each line is
+ * an independent sub-strip: optional `Joiner` end-caps fire at every line
+ * boundary (not just the strip's first/last position), so a line break looks
+ * the same as an endpoint to the joiner. Composes with the Strip + Joiner
+ * primitive in `core/strip` — same `Joiner` protocol, no new join semantics.
+ *
+ * [LAW:dataflow-not-control-flow] The pack walk is the same shape every
+ * render: measure each item, render every joiner form (start-cap, end-cap,
+ * mid-join) up-front, then sweep items into lines. Line breaks are decided by
+ * width data, not by control-flow special cases.
+ *
+ * [LAW:one-source-of-truth] The Strip primitive owns the join protocol;
+ * FlexStrip reuses it verbatim. There is no second concept of "join."
+ */
+import { Segment } from "../core/segment.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Joiner, 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. */
+    joiner?: Joiner<T>;
+    /** Cells of horizontal space inserted on each side of an inter-item joiner (default 0). */
+    gap?: number;
+    /** Line alignment when packed items don't fill the available width (default "left"). */
+    align?: FlexAlign;
+}
+export declare class FlexStrip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable {
+    readonly items: readonly T[];
+    readonly joiner: Joiner<T> | undefined;
+    readonly gap: number;
+    readonly align: FlexAlign;
+    constructor(items: readonly T[], options?: FlexStripOptions<T>);
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/flexStrip.js

@@ -0,0 +1,200 @@
+/**
+ * FlexStrip — wrap-to-width horizontal layout for `StyledRenderable` items.
+ *
+ * Pack as many items as fit on a line, then break and continue. Each line is
+ * an independent sub-strip: optional `Joiner` end-caps fire at every line
+ * boundary (not just the strip's first/last position), so a line break looks
+ * the same as an endpoint to the joiner. Composes with the Strip + Joiner
+ * primitive in `core/strip` — same `Joiner` protocol, no new join semantics.
+ *
+ * [LAW:dataflow-not-control-flow] The pack walk is the same shape every
+ * render: measure each item, render every joiner form (start-cap, end-cap,
+ * mid-join) up-front, then sweep items into lines. Line breaks are decided by
+ * width data, not by control-flow special cases.
+ *
+ * [LAW:one-source-of-truth] The Strip primitive owns the join protocol;
+ * FlexStrip reuses it verbatim. There is no second concept of "join."
+ */
+import { Segment } from "../core/segment.js";
+function renderToBlock(r, options) {
+    const segments = [...r.render(options)];
+    let width = 0;
+    for (const s of segments)
+        width += s.cellLength;
+    return { segments, width };
+}
+const EMPTY_BLOCK = { segments: [], width: 0 };
+const PAD_LEFT_BY_ALIGN = {
+    left: () => 0,
+    justify: () => 0,
+    center: (spare) => Math.floor(spare / 2),
+    right: (spare) => spare,
+};
+function computePadLeft(align, spare) {
+    return PAD_LEFT_BY_ALIGN[align](spare);
+}
+// Return per-slot fill widths (length = itemCount - 1, possibly empty).
+// Non-justify cases produce all zeros — the emit loop runs the same way.
+function computeSlotFills(align, isFinalLine, spare, itemCount) {
+    const slots = Math.max(0, itemCount - 1);
+    const distribute = align === "justify" && !isFinalLine && slots > 0 && spare > 0;
+    const totalFill = distribute ? spare : 0;
+    const base = slots > 0 ? Math.floor(totalFill / slots) : 0;
+    const extra = totalFill - base * slots;
+    return Array.from({ length: slots }, (_, k) => base + (k < extra ? 1 : 0));
+}
+export class FlexStrip {
+    items;
+    joiner;
+    gap;
+    align;
+    constructor(items, options) {
+        this.items = items;
+        this.joiner = options?.joiner;
+        this.gap = options?.gap ?? 0;
+        this.align = options?.align ?? "left";
+    }
+    *render(options) {
+        const items = this.items;
+        if (items.length === 0)
+            return;
+        const maxWidth = Math.max(1, options.maxWidth);
+        const gap = this.gap;
+        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 lines = [];
+        let line = null;
+        const gapBlock = gap > 0
+            ? { segments: [new Segment(" ".repeat(gap))], width: gap }
+            : EMPTY_BLOCK;
+        for (let i = 0; i < items.length; i++) {
+            const item = itemBlocks[i];
+            if (line === null) {
+                const sc = startCap(i);
+                const ec = endCap(i);
+                const blocks = sc.width > 0 ? [sc, item] : [item];
+                const itemBlockIndices = [blocks.length - 1];
+                line = { blocks, width: sc.width + item.width, lastIndex: i, itemBlockIndices };
+                // Tentatively reserve space for the line's eventual end-cap by
+                // tracking it separately below — `line.width` is the open width
+                // (without end-cap). We test fit using width + endCap on each step.
+                // Always start a new line with at least the first item (overflow ok
+                // per ticket: graceful fallback when an item is wider than terminal).
+                // Stash end-cap for the close step.
+                line.endCap = ec;
+                continue;
+            }
+            const prev = line.lastIndex;
+            const mid = midJoin(prev, i);
+            const newEndCap = endCap(i);
+            const addCost = (gap > 0 ? gap : 0) + mid.width + (gap > 0 ? gap : 0) + item.width;
+            const closedWidthIfAdded = line.width + addCost + newEndCap.width;
+            if (closedWidthIfAdded <= maxWidth) {
+                if (gap > 0)
+                    line.blocks.push(gapBlock);
+                if (mid.width > 0)
+                    line.blocks.push(mid);
+                if (gap > 0)
+                    line.blocks.push(gapBlock);
+                line.blocks.push(item);
+                line.itemBlockIndices.push(line.blocks.length - 1);
+                line.width += addCost;
+                line.lastIndex = i;
+                line.endCap = newEndCap;
+            }
+            else {
+                // Close current line and start a new one with this item.
+                const closing = line.endCap;
+                if (closing.width > 0)
+                    line.blocks.push(closing);
+                line.width += closing.width;
+                lines.push(line);
+                const sc = startCap(i);
+                const ec = endCap(i);
+                const blocks = sc.width > 0 ? [sc, item] : [item];
+                const itemBlockIndices = [blocks.length - 1];
+                line = { blocks, width: sc.width + item.width, lastIndex: i, itemBlockIndices };
+                line.endCap = ec;
+            }
+        }
+        // Close final line. `line` is non-null here: the loop runs at least once
+        // (items.length > 0 was handled above).
+        const finalLine = line;
+        {
+            const closing = finalLine.endCap;
+            if (closing.width > 0)
+                finalLine.blocks.push(closing);
+            finalLine.width += closing.width;
+            lines.push(finalLine);
+        }
+        // [LAW:dataflow-not-control-flow] Single emission path for every line:
+        // emit pad, walk every block, optionally emit a per-slot fill before each
+        // non-first item. Variability lives in two precomputed value sequences
+        // (`padLeft` and `slotFills`); the emit loop has no per-mode branch.
+        //
+        // - `padLeft` pushes the line right by 0 (left/justify), spare/2 (center),
+        //   or full spare (right). Justify-on-final-line follows the left rule.
+        // - `slotFills[k]` is the cells of fill emitted before the (k+1)-th item.
+        //   Always 0 unless align=justify on a non-final line with ≥2 items.
+        //
+        // Putting the variability in data means the emit loop is the same shape
+        // every render, and "what happens between two items" can never accidentally
+        // become "what happens between joiner halves" — the data decides.
+        const align = this.align;
+        for (let li = 0; li < lines.length; li++) {
+            const ln = lines[li];
+            const isLast = li === lines.length - 1;
+            const spare = Math.max(0, maxWidth - ln.width);
+            const padLeft = computePadLeft(align, spare);
+            const slotFills = computeSlotFills(align, isLast, spare, ln.itemBlockIndices.length);
+            const itemRankOf = new Map();
+            ln.itemBlockIndices.forEach((blockIdx, rank) => itemRankOf.set(blockIdx, rank));
+            if (padLeft > 0)
+                yield new Segment(" ".repeat(padLeft));
+            for (let bi = 0; bi < ln.blocks.length; bi++) {
+                const rank = itemRankOf.get(bi);
+                if (rank !== undefined && rank > 0) {
+                    const fill = slotFills[rank - 1];
+                    if (fill > 0)
+                        yield new Segment(" ".repeat(fill));
+                }
+                yield* ln.blocks[bi].segments;
+            }
+            yield Segment.line();
+        }
+    }
+    measure(options) {
+        const items = this.items;
+        if (items.length === 0)
+            return { minimum: 0, maximum: 0 };
+        let minimum = 0;
+        let maximum = 0;
+        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
+                : 0;
+            const ec = this.joiner
+                ? renderToBlock(this.joiner.join(items[i], null), 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;
+                }
+            }
+        }
+        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;
+        }
+        return { minimum, maximum };
+    }
+}

package/dist/renderables/group.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Group — renders multiple renderables in sequence.
+ * No visual chrome — purely a container.
+ */
+import { Segment } from "../core/segment.js";
+import type { Renderable, RenderOptions } from "../core/protocol.js";
+export declare class Group implements Renderable {
+    readonly renderables: Renderable[];
+    constructor(...renderables: Renderable[]);
+    render(options: RenderOptions): Iterable<Segment>;
+}

package/dist/renderables/group.js

@@ -0,0 +1,17 @@
+/**
+ * Group — renders multiple renderables in sequence.
+ * No visual chrome — purely a container.
+ */
+import { stackedHeight } from "../core/protocol.js";
+export class Group {
+    renderables;
+    constructor(...renderables) {
+        this.renderables = renderables;
+    }
+    *render(options) {
+        const memberOptions = { ...options, height: stackedHeight(options.height) };
+        for (const renderable of this.renderables) {
+            yield* renderable.render(memberOptions);
+        }
+    }
+}