@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/renderables/table.js

@@ -1,14 +1,16 @@
 /**
  * Table — tabular data with headers, borders, auto-sizing, and alignment.
  */
-import { cellLen, cellCount as cells } from "../core/cells.js";
+import { cellCount as cells } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
 import { NULL_STYLE } from "../core/style.js";
 import { HEAVY_HEAD } from "../core/box.js";
 import { RichText } from "../core/text.js";
-import { embed, embeddedText } from "./embed.js";
+import { EmbeddedText, embed, present } from "./embed.js";
 import { normalizePadding } from "./padding.js";
-import { getStyle, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { exactWeights, ratioDistribute, ratioReduce } from "./ratio.js";
+import { getStyle, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { Measurement } from "../core/measure.js";
 /** A `want` no budget can satisfy: the column takes every cell its weight earns. */
 const UNBOUNDED = Number.MAX_SAFE_INTEGER;
 /**
@@ -37,8 +39,7 @@ const blank = (n) => (n > 0 ? [new Segment(" ".repeat(n))] : []);
  * than an optimization: handing cells out one at a time made the iteration
  * count the width itself, which stalled on a very wide table and — since
  * `Infinity - 1 === Infinity` — never terminated at all for a `maxWidth` of
- * `Infinity` held open by a ratio column. Capping by want reaches that case in
- * one round.
+ * `Infinity`. Capping by want reaches that case in one round.
  *
  * The arithmetic is exact. A share's fraction is what decides who gets a
  * leftover cell, and in floating point two fractions that are equal — 6/14 and
@@ -98,24 +99,55 @@ function distribute(total, demands) {
     return granted;
 }
 /**
- * Weights as integers in one exact proportion. Each is read as the decimal it
- * prints as — the number its caller wrote, `0.1` rather than the binary double
- * nearest it — and all are scaled by the one power of ten that makes them
- * whole, so `0.1 : 0.3 : 1` is exactly `1 : 3 : 10`. A weight that does not
- * print as a decimal, `Infinity`, is refused by `BigInt` with a SyntaxError —
- * the loud end of what `demandCells` exists to prevent.
+ * `wants` cut back until they sum to `budget`, in the order the reference
+ * narrows a table wider than its width in `Table._calculate_column_widths`:
+ * first the widest `wrapable` columns, each round down to the next widest
+ * (`_collapse_widths`), and then, the last resort, the excess taken from every
+ * column evenly (`ratio_reduce(excess, [1] * n, widths, widths)`). Wants that
+ * fit come back as they are.
+ *
+ * A column's width is its want plus the `kept` cells — seat and padding — the
+ * table paid it first and it never gives up. One divergence: the reference's
+ * even cut runs once, and where a column too narrow to give its share leaves
+ * cells over, the table draws past its width. Here the cut repeats over the
+ * columns with cells left, so the table fits. Each round either fits or
+ * empties a column, so it ends.
  */
-function exactWeights(weights) {
-    const decimals = weights.map((weight) => {
-        const [digits = "", power = "0"] = String(weight).split("e");
-        const [whole = "", fraction = ""] = digits.split(".");
-        return { mantissa: BigInt(whole + fraction), exponent: fraction.length - Number(power) };
-    });
-    const common = Math.max(...decimals.map(({ exponent }) => exponent));
-    return decimals.map(({ mantissa, exponent }) => mantissa * 10n ** BigInt(common - exponent));
+function reduceToFit(budget, demands) {
+    let wants = demands.map(({ want }) => want);
+    const excess = () => wants.reduce((sum, want) => sum + want, 0) - budget;
+    for (let over = excess(); over > 0; over = excess()) {
+        // A column with nothing left to give, or that may not wrap, is out of the round.
+        const widths = wants.map((want, index) => (demands[index].wrapable && want > 0 ? demands[index].kept + want : 0));
+        const widest = Math.max(...widths);
+        if (widest === 0)
+            break;
+        const next = Math.max(...widths.map((width) => (width === widest ? 0 : width)));
+        wants = ratioReduce(over, widths.map((width) => (width === widest ? 1 : 0)), wants.map((want) => Math.min(over, widest - next, want)), wants);
+    }
+    for (let over = excess(); over > 0; over = excess()) {
+        wants = ratioReduce(over, wants.map(() => 1), wants, wants);
+    }
+    return wants;
+}
+/**
+ * The most padding every column can have alike: each side is granted
+ * `min(want, level)`, and `level` is the highest those grants fit `budget` at.
+ * A padding level is bought for every column at once or not at all, so a
+ * budget too small for everyone's padding leaves it uneven by no column.
+ */
+function padLevel(wants, budget) {
+    const sorted = [...wants].sort((a, b) => a - b);
+    let left = budget;
+    for (const [rank, want] of sorted.entries()) {
+        const sharing = sorted.length - rank;
+        if (want * sharing > left)
+            return Math.floor(left / sharing);
+        left -= want;
+    }
+    return sorted.at(-1) ?? 0;
 }
-function layoutTable(outerWidth, demands, padding, frame) {
-    const [, padRightWanted, , padLeftWanted] = padding;
+function layoutTable(outerWidth, demands, frame) {
     // Plain `number`, not the `CellCol` `cells` hands back: this budget is spent
     // down by arithmetic, and arithmetic on a branded type produces a number.
     let budget = cells(outerWidth);
@@ -143,32 +175,38 @@ function layoutTable(outerWidth, demands, padding, frame) {
         seats.push(seat);
     }
     const seated = seats.length;
-    // Padding is uniform across columns or it is not padding, so it is bought
-    // for every seated column at once and skipped entirely when only some could
-    // afford it.
-    const takePerColumn = (want) => {
-        const per = seated === 0
-            ? 0
-            : Math.min(Math.max(0, want), Math.floor(budget / seated));
-        budget -= per * seated;
-        return per;
+    // Padding is bought one side at a time, to one level across every seated
+    // column (`padLevel`), so no column is padded while another that wants the
+    // same padding goes without.
+    const seatedDemands = demands.slice(0, seated);
+    const takeLevelled = (wants) => {
+        const level = padLevel(wants, budget);
+        return wants.map((want) => take(Math.min(want, level)));
     };
-    const padLeft = takePerColumn(padLeftWanted);
-    const padRight = takePerColumn(padRightWanted);
+    const padLeft = takeLevelled(seatedDemands.map((demand) => demand.pad[0]));
+    const padRight = takeLevelled(seatedDemands.map((demand) => demand.pad[1]));
     // Reservations are paid in column order, each already holding the cell the
     // seating pass gave it. A budget too small to cover them all runs out
     // partway, which costs the trailing columns their width but never costs the
     // table its frame.
-    const seatedDemands = demands.slice(0, seated);
     const reserved = seatedDemands.map((demand, index) => take(demand.reserved - seats[index]));
-    // What is left to apportion is the rest of what each column wanted. A table
+    // What is left to apportion is the rest of what each column wanted: its
+    // minimum first, for every column, and only then the width past it. A table
     // whose columns all fit leaves this budget partly unspent.
-    const wanted = distribute(budget, seatedDemands.map((demand, index) => ({
-        want: Math.max(0, demand.want - seats[index] - reserved[index]),
+    const spent = (granted) => granted.reduce((sum, width) => sum + width, 0);
+    const base = seatedDemands.map((_, index) => seats[index] + reserved[index]);
+    const holding = (...passes) => base.map((start, index) => passes.reduce((sum, granted) => sum + granted[index], start));
+    const needed = reduceToFit(budget, seatedDemands.map((demand, index) => ({
+        want: Math.max(0, demand.minimum - base[index]),
+        kept: padLeft[index] + base[index] + padRight[index],
+        wrapable: demand.wrapable,
+    })));
+    const afterNeeded = holding(needed);
+    const beyond = distribute(budget - spent(needed), seatedDemands.map((demand, index) => ({
+        want: Math.max(0, demand.want - afterNeeded[index]),
         weight: demand.weight,
     })));
-    const spent = (granted) => granted.reduce((sum, cells) => sum + cells, 0);
-    const holding = (...passes) => seatedDemands.map((_, index) => passes.reduce((sum, granted) => sum + granted[index], seats[index] + reserved[index]));
+    const wanted = needed.map((width, index) => width + beyond[index]);
     // The unspent part goes first to the columns with nothing to size to, each
     // alike, up to its `fill` — the reference's `Measurement(1, max_width)`, a
     // maximum of the whole offer that no content measured.
@@ -177,23 +215,56 @@ function layoutTable(outerWidth, demands, padding, frame) {
         want: Math.max(0, demand.fill - afterWant[index]),
         weight: demand.fill > 0 ? 1 : 0,
     })));
-    // Then to the ratio columns, in proportion.
-    const shared = distribute(budget - spent(wanted) - spent(filled), seatedDemands.map((demand) => ({ want: UNBOUNDED, weight: demand.ratio })));
+    // Then to the ratio columns, by the reference's flexible split:
+    // `ratio_distribute(max_width - fixed_widths, ratios, flex_minimum)`. What
+    // is split is every cell the bounded columns leave, the cells the ratio
+    // columns already hold and their padding included, because Rich's widths
+    // are padded widths; each is held to at least its padding and its floor.
+    // The floor is the reference's `column.width or 1`, reading `minWidth`
+    // where there is no `width`, where the reference reads none and draws a
+    // `min_width=12` ratio column five cells wide.
+    // A ratio column is paid the rest of its part out of the budget, in column
+    // order, so a part the minimums push past what is left is cut there rather
+    // than drawn past the width.
+    const afterFill = holding(wanted, filled);
+    const flexible = seatedDemands.flatMap((demand, index) => (demand.ratio > 0 ? [index] : []));
+    const padded = (index, content) => padLeft[index] + content + padRight[index];
+    // `UNBOUNDED` holds an unbounded offer, as it does for the stretch below;
+    // it caps the whole split, so the total stays an integer a double holds.
+    const pool = budget - spent(wanted) - spent(filled);
+    let unshared = Math.min(pool, UNBOUNDED);
+    const parts = ratioDistribute(Math.min(pool + flexible.reduce((sum, index) => sum + padded(index, afterFill[index]), 0), UNBOUNDED), flexible.map((index) => seatedDemands[index].ratio), flexible.map((index) => padded(index, seatedDemands[index].want)));
+    const shared = seatedDemands.map(() => 0);
+    flexible.forEach((index, slot) => {
+        shared[index] = Math.min(Math.max(0, parts[slot] - padded(index, afterFill[index])), unshared);
+        unshared -= shared[index];
+    });
     // What the shares leave goes to the columns that stretch, by the width each
-    // already holds: its natural width, since nothing is left over while any
-    // column is short, or the cap a fill stopped at. The reference weighs by
-    // width too: `ratio_distribute(max_width - table_width, widths)`, though its
-    // widths count the padding. A table that does not expand stretches nothing,
-    // which is how it stays narrower than the width it was offered. The order is the reference's:
-    // Rich pads an expanding table only once `table_width < max_width`, never
-    // while it is collapsing a column.
+    // already holds with its padding: its natural width, since nothing is left
+    // over while any column is short, or the cap a fill stopped at. The split is
+    // the reference's `ratio_distribute(max_width - table_width, widths)`,
+    // rounding included; the columns it runs over are this port's. A table that
+    // does not expand has no column that stretches, and an empty list takes
+    // nothing, which is how it stays narrower than the width it was offered. The
+    // order is the reference's: Rich pads an expanding table only
+    // once `table_width < max_width`, never while it is collapsing a column.
     const held = holding(wanted, filled, shared);
-    const stretched = distribute(budget - spent(wanted) - spent(filled) - spent(shared), seatedDemands.map((demand, index) => ({
-        want: UNBOUNDED,
-        weight: demand.stretch ? held[index] : 0,
-    })));
-    const columns = held.map((cells, index) => cells + stretched[index]);
-    const cellWidths = columns.map((width) => padLeft + width + padRight);
+    const stretchers = seatedDemands.flatMap((demand, index) => (demand.stretch ? [index] : []));
+    const stretches = ratioDistribute(
+    // An unbounded offer is held to `UNBOUNDED`, this model's own infinity, as
+    // `demandCells` holds a want: `Infinity` is not an integer to split.
+    Math.min(budget - spent(wanted) - spent(filled) - spent(shared), UNBOUNDED), stretchers.map((index) => padded(index, held[index])));
+    // A table that does not fit gives back each column's `floor`: Rich
+    // re-measures a collapsed table's columns at the widths it gave them, and a
+    // column with nothing to draw measures 0 there however many cells the collapse
+    // left it. Those cells go unspent, as they do in Rich.
+    const natural = demands.reduce((sum, demand) => sum + demand.pad[0] + demand.want + demand.pad[1], frame.edge * 2 + Math.max(0, demands.length - 1) * frame.divider);
+    const squeezed = natural > outerWidth;
+    const columns = held.map((width, index) => squeezed ? width - Math.min(width, seatedDemands[index].floor) : width);
+    stretchers.forEach((index, slot) => {
+        columns[index] += stretches[slot];
+    });
+    const cellWidths = columns.map((width, index) => padded(index, width));
     return {
         edge,
         divider: frame.divider,
@@ -232,6 +303,7 @@ export class Column {
     ratio;
     noWrap;
     overflow;
+    highlight;
     _cells;
     constructor(options) {
         this.header = options?.header;
@@ -246,15 +318,15 @@ export class Column {
         this.ratio = options?.ratio;
         this.noWrap = options?.noWrap ?? false;
         this.overflow = options?.overflow ?? "ellipsis";
+        this.highlight = options?.highlight ?? false;
         this._cells = [];
     }
     /**
-     * The two stamped cells, parsed on assignment rather than at the constructor.
+     * The two stamped cells, stamped on assignment rather than at the constructor.
      * `Table.columns` hands out the live column and both fields are public, so a
      * constructor-only stamp held only until the first `columns[0].footer = mine`
-     * — which installed content that had parsed no markup, still carried its
-     * `end`, and was still owned by the caller, into a slot every reader below
-     * assumes `embeddedText` has been through. [LAW:parse-dont-validate] The setter
+     * — which installed content still owned by the caller into a slot every
+     * reader below assumes `embed` has been through. [LAW:parse-dont-validate] The setter
      * is the border, so the guarantee holds for the object's whole lifetime and
      * the constructor is one caller of it rather than the one place it is true.
      *
@@ -263,20 +335,20 @@ export class Column {
      * a column always has one and `show_footer` alone decides whether it is
      * drawn. Modelling the absence as `undefined` instead made "no column has a
      * footer" a state the render path could ask about — and it did, skipping the
-     * row a caller had asked for. `embeddedText` already maps nothing onto empty,
+     * row a caller had asked for. `embed` already maps nothing onto empty,
      * which is why the setters take `undefined` rather than defaulting around it.
      */
     get header() {
         return this._header;
     }
     set header(content) {
-        this._header = embeddedText(content);
+        this._header = embed(content);
     }
     get footer() {
         return this._footer;
     }
     set footer(content) {
-        this._footer = embeddedText(content);
+        this._footer = embed(content);
     }
     get flexible() {
         return columnShare(this) > 0;
@@ -291,11 +363,6 @@ export class Column {
     }
     copy() {
         const col = new Column({
-            // No `.copy()` here: the crossing the constructor routes through copies
-            // a `RichText` already, and a second copy is a second home for that rule.
-            // [LAW:single-enforcer]
-            header: this.header,
-            footer: this.footer,
             justify: this.justify,
             width: this.width,
             minWidth: this.minWidth,
@@ -303,10 +370,15 @@ export class Column {
             ratio: this.ratio,
             noWrap: this.noWrap,
             overflow: this.overflow,
+            highlight: this.highlight,
         });
         col.headerStyle = this.headerStyle;
         col.footerStyle = this.footerStyle;
         col.style = this.style;
+        // Shared, not copied, as a row's cells are: `embed` already copied a
+        // caller's `RichText`, and what it hands back is never changed.
+        col._header = this._header;
+        col._footer = this._footer;
         return col;
     }
 }
@@ -314,14 +386,16 @@ export class Table {
     _columns;
     _rows;
     box;
-    title;
-    caption;
+    _title;
+    _caption;
     expand;
     showHeader;
     showFooter;
     showLines;
     showEdge;
     padding;
+    collapsePadding;
+    padEdge;
     style;
     headerStyle;
     footerStyle;
@@ -333,14 +407,23 @@ export class Table {
     tableWidth;
     minWidth;
     rowStyles;
+    highlight;
+    get title() {
+        return this._title;
+    }
+    get caption() {
+        return this._caption;
+    }
     constructor(options) {
         this._columns = [];
         this._rows = [];
         this.box = options?.box !== undefined ? options.box : HEAVY_HEAD;
+        // An empty title draws no row, as the reference's `if self.title` draws
+        // none; markup that styles nothing is a title, and draws a blank one.
         const titleVal = options?.title;
-        this.title = titleVal !== undefined ? embeddedText(titleVal) : undefined;
+        this._title = present(titleVal) ? new EmbeddedText(titleVal) : undefined;
         const captionVal = options?.caption;
-        this.caption = captionVal !== undefined ? embeddedText(captionVal) : undefined;
+        this._caption = present(captionVal) ? new EmbeddedText(captionVal) : undefined;
         // A declared width is the table's size, not a ceiling on it: the
         // reference's `expand` is `self._expand or self.width is not None`, and a
         // port that sized to content inside it drew Rich code narrower than Rich.
@@ -350,6 +433,8 @@ export class Table {
         this.showLines = options?.showLines ?? false;
         this.showEdge = options?.showEdge !== false;
         this.padding = normalizePadding(options?.padding ?? [0, 1, 0, 1]);
+        this.collapsePadding = options?.collapsePadding ?? false;
+        this.padEdge = options?.padEdge ?? true;
         this.style = options?.style ?? NULL_STYLE;
         this.headerStyle = options?.headerStyle ?? "table.header";
         this.footerStyle = options?.footerStyle ?? "table.footer";
@@ -361,6 +446,7 @@ export class Table {
         this.tableWidth = options?.width;
         this.minWidth = options?.minWidth;
         this.rowStyles = options?.rowStyles ?? [];
+        this.highlight = options?.highlight ?? false;
     }
     get columns() {
         return this._columns;
@@ -369,7 +455,7 @@ export class Table {
         return this._rows.length;
     }
     addColumn(header, options) {
-        const col = new Column({ ...options, header: header ?? options?.header });
+        const col = new Column({ ...options, header: header ?? options?.header, highlight: options?.highlight ?? this.highlight });
         this._columns.push(col);
         return this;
     }
@@ -426,11 +512,12 @@ export class Table {
         const borderStyle = getStyle(options, this.style).add(getStyle(options, this.borderStyle));
         const border = borderStyle.isNull ? undefined : borderStyle;
         // The one division of the width every row below is measured against.
-        const geometry = this._geometry(this._outerWidth(options));
+        const outerWidth = this._outerWidth(options);
+        const geometry = this._geometry(options, outerWidth);
         const edge = geometry.edge === 1;
         // Title
-        if (this.title) {
-            yield* this._renderTitle(options, this.title, geometry.totalWidth, this.titleStyle, this.titleJustify);
+        if (this._title) {
+            yield* this._renderTitle(options, this._title, geometry.totalWidth, this.titleStyle, this.titleJustify);
         }
         // Top border
         if (box && this.showEdge) {
@@ -442,11 +529,16 @@ export class Table {
         const footerStyle = getStyle(options, this.footerStyle);
         const columnStyles = this._columns.map((c) => getStyle(options, c.style));
         const stripes = this.rowStyles.map((s) => getStyle(options, s));
+        // Each row's padding above and below, by where it stands among every row
+        // the table draws, header and footer included, as the reference counts them.
+        const firstBody = this.showHeader ? 1 : 0;
+        const lastRow = firstBody + this._rows.length + (this.showFooter ? 1 : 0) - 1;
+        const rowPadding = (position) => this._rowPadding(position === 0, position === lastRow);
         // Header row
         if (this.showHeader) {
             const headerCells = this._columns.map((c) => c.header);
             const headerStyles = this._columns.map((c) => headerStyle.add(getStyle(options, c.headerStyle)));
-            yield* this._renderRow(options, headerCells, headerStyles, NULL_STYLE, geometry, box, "head", border);
+            yield* this._renderRow(options, headerCells, headerStyles, NULL_STYLE, geometry, rowPadding(0), box, "head", border);
             // Header separator
             if (box) {
                 yield* box.getRow(geometry.cellWidths, "head", border, edge);
@@ -455,10 +547,10 @@ export class Table {
         // Data rows
         for (let rowIdx = 0; rowIdx < this._rows.length; rowIdx++) {
             const row = this._rows[rowIdx];
-            const rowCells = this._columns.map((_, colIdx) => row.cells[colIdx] ?? embeddedText(undefined));
+            const rowCells = this._columns.map((_, colIdx) => row.cells[colIdx] ?? new EmbeddedText(undefined));
             const rowStyle = stripes[rowIdx % stripes.length] ?? NULL_STYLE;
             const cellStyles = columnStyles.map((s) => s.add(rowStyle));
-            yield* this._renderRow(options, rowCells, cellStyles, rowStyle, geometry, box, "row", border);
+            yield* this._renderRow(options, rowCells, cellStyles, rowStyle, geometry, rowPadding(firstBody + rowIdx), box, "row", border);
             // Row separator
             const showSep = this.showLines || row.endSection;
             if (showSep && box && rowIdx < this._rows.length - 1) {
@@ -472,21 +564,21 @@ export class Table {
             }
             const footerCells = this._columns.map((c) => c.footer);
             const footerStyles = this._columns.map((c) => footerStyle.add(getStyle(options, c.footerStyle)));
-            yield* this._renderRow(options, footerCells, footerStyles, NULL_STYLE, geometry, box, "foot", border);
+            yield* this._renderRow(options, footerCells, footerStyles, NULL_STYLE, geometry, rowPadding(lastRow), box, "foot", border);
         }
         // Bottom border
         if (box && this.showEdge) {
             yield* box.getBottom(geometry.cellWidths, border, edge);
         }
         // Caption
-        if (this.caption) {
-            yield* this._renderTitle(options, this.caption, geometry.totalWidth, this.captionStyle, this.captionJustify);
+        if (this._caption) {
+            yield* this._renderTitle(options, this._caption, geometry.totalWidth, this.captionStyle, this.captionJustify);
         }
     }
     /**
      * [LAW:one-source-of-truth] Both ends of the range are widths the geometry
      * actually produced — the maximum from the demands as they stand, the
-     * minimum from the same layout with every column asking for a single cell.
+     * minimum from the same layout with every column asking for its minimum.
      * Neither end stretches or fills into an offer: both only spend cells an
      * offer happens to leave over, and a renderable reports the width its content
      * wants rather than the width it was offered. A declared `width` is not an
@@ -503,7 +595,7 @@ export class Table {
         const options = withCellWidth(rawOptions);
         const outerWidth = this._outerWidth(options);
         const frame = this._frame();
-        const demands = this._columnDemands();
+        const demands = this._columnDemands(options, outerWidth);
         // A declared width is the one stretch a measurement reports, because it is
         // a size the table was given rather than an offer it grew into — the
         // reference measures `self.width` as its maximum, so a `Panel` fitted round
@@ -514,30 +606,34 @@ export class Table {
         // back to the content, as an unbounded `expand` does.
         const declared = this.tableWidth === undefined
             ? undefined
-            : layoutTable(outerWidth, demands, this.padding, frame).totalWidth;
+            : layoutTable(outerWidth, demands, frame).totalWidth;
         const laidOut = declared !== undefined && declared < UNBOUNDED
             ? declared
-            : layoutTable(outerWidth, demands.map((demand) => ({ ...demand, fill: 0, stretch: false })), this.padding, frame).totalWidth;
+            : layoutTable(outerWidth, demands.map((demand) => ({ ...demand, fill: 0, stretch: false })), frame).totalWidth;
         // `UNBOUNDED` is this table's own infinity, so a layout that reached it has
         // no natural width to report — a column asked for every cell there is. Said
         // as the number, it escapes as a width a caller would try to draw:
         // `minWidth: Infinity` measured 18014398509481988 and rendered
         // `RangeError: Invalid string length` out of the top border.
         const maximum = laidOut >= UNBOUNDED ? Infinity : laidOut;
-        const tightest = layoutTable(outerWidth, demands.map((demand) => ({
-            reserved: 0,
-            want: Math.min(1, demand.want),
-            weight: 1,
-            fill: 0,
-            ratio: 0,
-            stretch: false,
-        })), this.padding, frame).totalWidth;
+        // The narrowest this table draws without cutting a cell is every column at
+        // its own minimum — the reference's sum of `_measure_column` minimums — so a
+        // parent squeezing it still leaves each figure whole. One divergence: a
+        // `noWrap` column's minimum is its whole line, where the reference measures
+        // its longest word and then never narrows it that far when it draws.
+        const tightest = layoutTable(outerWidth, demands.map((demand) => ({ ...demand, want: demand.minimum, fill: 0, ratio: 0, stretch: false })), frame).totalWidth;
         return {
             minimum: Math.min(maximum, Math.max(tightest, cells(this.minWidth ?? 0))),
             maximum,
         };
     }
     // --- Static ---
+    /**
+     * A table with no frame and no header, padded between its columns and never
+     * at its edges, so an expanded grid reaches both sides of its width. The
+     * reference's `grid` defaults, but for `padding`: Rich's is 0, which runs
+     * adjacent columns together, and this port's is one cell to the right.
+     */
     static grid(options) {
         return new Table({
             ...options,
@@ -545,6 +641,8 @@ export class Table {
             showHeader: false,
             showEdge: false,
             padding: options?.padding ?? [0, 1, 0, 0],
+            collapsePadding: options?.collapsePadding ?? true,
+            padEdge: options?.padEdge ?? false,
         });
     }
     // --- Private ---
@@ -569,8 +667,8 @@ export class Table {
     _outerWidth(options) {
         return Math.min(this.tableWidth === undefined ? options.maxWidth : cells(this.tableWidth), options.maxWidth);
     }
-    _geometry(outerWidth) {
-        return layoutTable(outerWidth, this._columnDemands(), this.padding, this._frame());
+    _geometry(options, outerWidth) {
+        return layoutTable(outerWidth, this._columnDemands(options, outerWidth), this._frame());
     }
     /**
      * [LAW:dataflow-not-control-flow] The three ways a column can be sized —
@@ -578,59 +676,122 @@ export class Table {
      * produce, and `expand` only in its `stretch`. They are resolved once, here, into uniform data, so
      * `layoutTable` runs the same apportionment for every table and no sizing
      * mode gets its own path through the width division.
+     *
+     * Cells are measured against the width left once the frame is paid, as the
+     * reference's `_measure_column` measures them. Padding and the floor are laid
+     * over whichever sizing the column has: they are the same for all three.
      */
-    _columnDemands() {
+    _columnDemands(options, outerWidth) {
+        const frame = this._frame();
+        const inner = {
+            ...options,
+            maxWidth: Math.max(0, outerWidth - frame.edge * 2 - frame.divider * Math.max(0, this._columns.length - 1)),
+        };
         return this._columns.map((col, index) => {
-            if (col.width !== undefined) {
-                // [LAW:single-enforcer] floored where it is parsed, the same rule
-                // `normalizePadding` applies to a negative padding side.
-                const declared = demandCells(col.width);
-                return { reserved: declared, want: declared, weight: 0, fill: 0, ratio: 0, stretch: false };
-            }
-            // A flexible column takes its share of whatever the bounded columns
-            // leave; every other column asks for its natural width, whether or not a
-            // neighbour is flexible. The split is the reference's —
-            // `fixed_widths = [0 if column.flexible else _range.maximum ...]` — with
-            // one divergence: Rich splits by ratio only when the table expands, and
-            // here a ratio is honoured either way. Its bounded part is its floor —
-            // the reference's `column.min_width or 1` — bid for in cells like any
-            // content column, so a squeezed table still pays a declared `minWidth`.
-            const share = columnShare(col);
-            if (share > 0) {
-                const floor = Math.max(1, demandCells(col.minWidth ?? 0));
-                return { reserved: 0, want: floor, weight: floor, fill: 0, ratio: share, stretch: false };
-            }
-            const widest = this._widestCell(col, index);
-            const natural = demandCells(this._bounded(col, widest ?? 1));
-            // `expand` is a stretch rather than a larger want: the column still
-            // competes for its natural width like any other, and only the cells left
-            // once every column has that are shared out. A larger want looks
-            // equivalent and is not — it lets a one-cell column claim cells while its
-            // neighbour is still truncated. The stretch weighs by width, so the
-            // widest column grows most, which is what keeps a `Progress` bar from
-            // getting no more of the slack than its percentage label.
-            //
-            // One deliberate divergence: Rich stretches declared-width columns as
-            // well, so `width: 6` under `expand` renders 21 cells wide — an option
-            // quietly meaning something else, the defect rich-justify-0cr exists to
-            // remove. A reservation's stretch is zero above.
-            //
-            // A column with no cell at all — no rows, and neither header nor footer
-            // drawn — has nothing to size to, which is not sizing to nothing. The
-            // reference measures it `Measurement(1, max_width)`: one cell of content,
-            // and a maximum of the whole offer, so a rowless table fills it. Reading
-            // "no cells" as zero sized it to a two-cell box instead. The one cell is
-            // its want, so a `minWidth` is paid like any column's, and the offer is
-            // its `fill`, held to its `maxWidth`.
+            const pad = this._columnPadding(index);
+            const sizing = this._columnSizing(col, index, inner);
+            const floor = pad[0] + sizing.want + pad[1] === 0 ? 1 : 0;
+            return { ...sizing, minimum: sizing.minimum + floor, want: sizing.want + floor, pad, floor };
+        });
+    }
+    _columnSizing(col, index, options) {
+        // A flexible column takes its share of whatever the bounded columns
+        // leave; every other column asks for its natural width, whether or not a
+        // neighbour is flexible. The split is the reference's —
+        // `fixed_widths = [0 if column.flexible else _range.maximum ...]` — with
+        // one divergence: Rich splits by ratio only when the table expands, and
+        // here a ratio is honoured either way. Its bounded part is its floor —
+        // the reference's `column.width or 1`, reading `minWidth` where there is
+        // no `width` — bid for in cells like any content column, so a squeezed
+        // table still pays it. A `width` beside a `ratio` is that floor, not a
+        // reservation, as the reference's `flex_minimum` reads it.
+        // [LAW:one-source-of-truth] `columnShare` decides first, so a column that
+        // `Column.flexible` calls elastic is one the division shares out.
+        const share = columnShare(col);
+        if (share > 0) {
+            const floor = Math.max(1, demandCells(col.width ?? col.minWidth ?? 0));
             return {
                 reserved: 0,
-                want: natural,
-                weight: natural,
-                fill: widest === undefined ? demandCells(this._bounded(col, UNBOUNDED)) : 0,
+                minimum: floor,
+                want: floor,
+                weight: floor,
+                fill: 0,
+                ratio: share,
+                stretch: false,
+                wrapable: col.width === undefined && !col.noWrap,
+            };
+        }
+        if (col.width !== undefined) {
+            // [LAW:single-enforcer] floored where it is parsed, the same rule
+            // `normalizePadding` applies to a negative padding side.
+            const declared = demandCells(col.width);
+            return {
+                reserved: declared,
+                minimum: declared,
+                want: declared,
+                weight: 0,
+                fill: 0,
                 ratio: 0,
-                stretch: this.expand,
+                stretch: false,
+                wrapable: false,
             };
-        });
+        }
+        const range = this._cellRange(col, index, options);
+        const natural = demandCells(this._bounded(col, range?.maximum ?? 1));
+        // `expand` is a stretch rather than a larger want: the column still
+        // competes for its natural width like any other, and only the cells left
+        // once every column has that are shared out. A larger want looks
+        // equivalent and is not — it lets a one-cell column claim cells while its
+        // neighbour is still truncated. The stretch weighs by width, so the
+        // widest column grows most, which is what keeps a `Progress` bar from
+        // getting no more of the slack than its percentage label.
+        //
+        // One deliberate divergence: Rich stretches declared-width columns as
+        // well, so `width: 6` under `expand` renders 21 cells wide — an option
+        // quietly meaning something else, the defect rich-justify-0cr exists to
+        // remove. A reservation's stretch is zero above.
+        //
+        // A column with no cell at all — no rows, and neither header nor footer
+        // drawn — has nothing to size to, which is not sizing to nothing. The
+        // reference measures it `Measurement(1, max_width)`: one cell of content,
+        // and a maximum of the whole offer, so a rowless table fills it. Reading
+        // "no cells" as zero sized it to a two-cell box instead. The one cell is
+        // its want, so a `minWidth` is paid like any column's, and the offer is
+        // its `fill`, held to its `maxWidth`.
+        //
+        // A column that may not wrap has no narrower width than its natural one
+        // that keeps its content whole — the reference leaves `no_wrap` columns out
+        // of the ones it collapses.
+        return {
+            reserved: 0,
+            minimum: col.noWrap ? natural : Math.min(natural, demandCells(this._bounded(col, range?.minimum ?? 1))),
+            want: natural,
+            weight: natural,
+            fill: range === undefined ? demandCells(this._bounded(col, UNBOUNDED)) : 0,
+            ratio: 0,
+            stretch: this.expand,
+            wrapable: !col.noWrap,
+        };
+    }
+    /**
+     * The padding either side of column `index`'s content, and above and below
+     * one row of cells: the reference's `get_padding`. `collapsePadding` lets a
+     * cell's left padding and its row's bottom padding merge into the padding
+     * beside and below them; `padEdge: false` drops every side that meets the
+     * table's edge. Each side is the configured padding unless one of those two
+     * reduces it.
+     */
+    _columnPadding(index) {
+        const [, right, , left] = this.padding;
+        const first = index === 0;
+        const last = index === this._columns.length - 1;
+        const collapsed = this.collapsePadding && !first ? Math.max(0, left - right) : left;
+        return [!this.padEdge && first ? 0 : collapsed, !this.padEdge && last ? 0 : right];
+    }
+    _rowPadding(first, last) {
+        const [top, , bottom] = this.padding;
+        const collapsed = this.collapsePadding && !last ? Math.max(0, top - bottom) : bottom;
+        return [!this.padEdge && first ? 0 : top, !this.padEdge && last ? 0 : collapsed];
     }
     /**
      * Every cell column `index` draws, in draw order.
@@ -647,31 +808,33 @@ export class Table {
         if (this.showHeader)
             yield col.header;
         for (const row of this._rows)
-            yield row.cells[index] ?? embeddedText(undefined);
+            yield row.cells[index] ?? new EmbeddedText(undefined);
         if (this.showFooter)
             yield col.footer;
     }
     /**
-     * The widest cell in a column, or `undefined` when the column has no cell to
-     * measure. Zero is a column whose cells draw nothing — a gutter asks for its
-     * padding and nothing else — and is not the same answer.
-     * [LAW:types-are-the-program]
+     * The widest any cell in a column draws, and the narrowest the column can be
+     * without cutting one — the reference's `_measure_column` — or `undefined`
+     * when the column has no cell to measure. Zero is a column whose cells draw
+     * nothing — a gutter asks for its padding and nothing else — and is not the
+     * same answer. [LAW:types-are-the-program]
      */
-    _widestCell(col, index) {
-        let widest;
+    _cellRange(col, index, options) {
+        let range;
         for (const cell of this._columnCells(col, index)) {
             // The stamped cell, so the width a column asks for is the width its text
             // will occupy — measuring the raw value sized this column to
             // `[red]Solo[/red]`, fifteen cells for four cells of text.
-            // [LAW:one-source-of-truth]
-            //
-            // A cell that draws itself is stringified rather than measured, which is
-            // a pre-existing gap: `_columnDemands` carries no `RenderOptions`, so
-            // `Measurement.get` is not reachable from here. It contributes a wrong
-            // non-zero width, and narrowing that is its own change.
-            widest = Math.max(widest ?? 0, cell instanceof RichText ? cellLen(cell.plain) : cellLen(String(cell)));
+            // [LAW:one-source-of-truth] Measured as the cell measures itself, so a
+            // multi-line cell asks for its widest line and a `Panel` for its frame;
+            // one that cannot measure itself asks for every cell there is, as in Rich.
+            const measured = Measurement.get(options, cell);
+            range = {
+                minimum: Math.max(range?.minimum ?? 0, measured.minimum),
+                maximum: Math.max(range?.maximum ?? 0, measured.maximum),
+            };
         }
-        return widest;
+        return range;
     }
     /**
      * A natural width held to the column's own `minWidth`/`maxWidth`.
@@ -684,7 +847,7 @@ export class Table {
     _bounded(col, natural) {
         return Math.min(Math.max(natural, cells(col.minWidth ?? 0)), cells(col.maxWidth ?? Infinity));
     }
-    *_renderRow(options, cells, styles, rowStyle, geometry, box, level, border) {
+    *_renderRow(options, cells, styles, rowStyle, geometry, [top, bottom], box, level, border) {
         const { padLeft, padRight, columns } = geometry;
         // [LAW:dataflow-not-control-flow] Header, body and footer share this path;
         // the level crosses as a value the box answers with glyphs, not a branch.
@@ -699,22 +862,36 @@ export class Table {
         // Render each cell onto the canvas the geometry gave its column. Columns
         // the width could not seat are absent from `columns` and so are never
         // rendered at all.
+        const paddedWidths = columns.map((cellWidth, index) => padLeft[index] + cellWidth + padRight[index]);
         const cellLines = columns.map((cellWidth, index) => {
             const col = this._columns[index];
             const cell = cells[index] ?? embed("");
             // The render's own options with the column's canvas laid over them, so a
-            // cell resolves its style names against the same theme as the table. The
-            // table owns the row's height: a cell inherits none, as the reference's
-            // `height=None` has it.
+            // cell resolves its style names against the same theme as the table. A
+            // table stacks its cells, so each is handed the table's rows as a
+            // ceiling, never a region to fill — the `Height` contract's
+            // `stackedHeight`, where the reference hands a cell `height=None`.
+            // Highlighted as its column says, Rich's `highlight=column.highlight`.
             const segs = [...cell.render({
                     ...options,
+                    highlight: col.highlight,
                     maxWidth: cellWidth,
                     justify: col.justify,
                     overflow: col.overflow,
                     noWrap: col.noWrap,
-                    height: undefined,
+                    height: stackedHeight(options.height),
                 })];
-            return Segment.splitAndCropLines(segs, cellWidth);
+            // The padding on every side is part of the cell, as the reference's
+            // `Padding` makes it: a content line sits between its left and right
+            // blanks, and a line above or below is one blank the cell's width.
+            const left = blank(padLeft[index]);
+            const right = blank(padRight[index]);
+            const padLine = () => blank(paddedWidths[index]);
+            return [
+                ...Array.from({ length: top }, padLine),
+                ...Segment.splitAndCropLines(segs, cellWidth).map((line) => [...left, ...line, ...right]),
+                ...Array.from({ length: bottom }, padLine),
+            ];
         });
         const maxLines = cellLines.reduce((most, lines) => Math.max(most, lines.length), 1);
         // How many blank lines stand above each cell's content. A header sits on
@@ -729,16 +906,15 @@ export class Table {
                 if (colIdx > 0 && divider) {
                     yield divider;
                 }
-                const cellWidth = columns[colIdx];
                 const style = styles[colIdx];
                 // A cell with fewer lines than the row contributes blanks, so every
                 // column spans the same number of rows and the frame stays rectangular.
-                const line = cellLines[colIdx][lineIdx - drop[colIdx]] ?? [new Segment(" ".repeat(cellWidth))];
+                const line = cellLines[colIdx][lineIdx - drop[colIdx]] ?? blank(paddedWidths[colIdx]);
                 // The cell's style is the base its content's own spans layer over, and
-                // it covers the whole cell — its left and right padding and its blank
-                // lines too, as the reference's does — so a background fills the column
-                // rather than sitting behind the text alone.
-                yield* Segment.applyStyle([...blank(padLeft), ...line, ...blank(padRight)], style.isNull ? undefined : style);
+                // it covers the whole cell — its padding and its blank lines too, as
+                // the reference's does — so a background fills the column rather than
+                // sitting behind the text alone.
+                yield* Segment.applyStyle(line, style.isNull ? undefined : style);
             }
             if (frame && geometry.edge === 1) {
                 yield new Segment(frame.right, border);
@@ -747,24 +923,25 @@ export class Table {
         }
     }
     *_renderTitle(options, text, tableWidth, ownStyle, justify) {
-        const style = getStyle(options, ownStyle);
-        const titleStyle = style.isNull ? undefined : style;
         // 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. Cleared on a copy rather than in place —
-        // the caller's text is theirs. [LAW:one-source-of-truth]
-        const source = text.copy();
-        source.justify = undefined;
+        // 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)`.
+        //
+        // The table's title style is the *base* a string title's own spans layer
+        // over, as `render_str(style=)` sets it: a `[red]` title inside an italic
+        // table title arrives as italic-red, and the line breaks and the `end` the
+        // text emits stay unstyled. A `RichText` title takes none of it, because
+        // the reference renders a `Text` title without the title style
+        // (rich-table-qj6i).
+        const source = text.text({ ...options, highlight: false }, getStyle(options, ownStyle));
         if (source.overflow === "ignore")
             source.overflow = undefined;
-        // The table's title style is the *base* the content's own spans layer over,
-        // which is what the reference emits: a `[red]` title inside an italic table
-        // title arrives as italic-red, not one or the other. Rendering `text.plain`
-        // here read the characters and dropped every span attached to them, so a
-        // styled title lost its styling and parsed markup silently did nothing.
         //
         // Rendered at the table's own width with nothing suppressed, because that
         // is what the reference hands its title: an annotation too wide for the
@@ -776,20 +953,19 @@ export class Table {
         // rules — that a wrap's trailing whitespace is not content to centre
         // around, that `left` fills the canvas and an unset justify does not — and
         // a second copy of those is a second answer waiting to disagree.
-        const rendered = [...source.render({
-                ...options,
-                maxWidth: tableWidth,
-                justify,
-                overflow: undefined,
-                noWrap: false,
-                height: undefined,
-            })];
-        // Every line the text has, because that is what the reference renders — a
-        // title of "one\ntwo" occupies two lines there. Taking only the first
-        // dropped the rest with no truncation mark.
-        for (const line of Segment.splitLines(rendered)) {
-            yield* Segment.applyStyle(line, titleStyle);
-            yield Segment.line();
-        }
+        //
+        // Yielded as the text emits it, every line and its own `end` included, as
+        // the reference's `console.render` yields it: a title of "one\ntwo" is two
+        // lines, and `end="!!"` runs on into the top border there too. Splitting
+        // and re-ending each line moved a non-newline `end` onto the title's own
+        // row, wider than the table.
+        yield* source.render({
+            ...options,
+            maxWidth: tableWidth,
+            justify,
+            overflow: undefined,
+            noWrap: false,
+            height: undefined,
+        });
     }
 }