@promptctl/rich-js 0.17.0 → 0.18.1

package/dist/renderables/table.js

@@ -6,48 +6,9 @@ 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 { renderMarkup } from "../core/markup.js";
+import { embed, embeddedText } from "./embed.js";
 import { normalizePadding } from "./padding.js";
 import { getStyle, withBoundedWidth, withCellWidth } from "../core/protocol.js";
-/**
- * The one crossing where caller text becomes styled table content.
- *
- * Cells, headers, footers, the title and the caption each used to build their
- * own `RichText` straight from the constructor — which does not parse markup —
- * so the markup rule had five homes and was absent from all five, and
- * `[red]Solo[/red]` reached the terminal with its tags intact.
- * [LAW:single-enforcer]
- *
- * Parsing is unconditional because that is what the reference does rather than
- * because it is the simpler branch: Rich's `Console.__init__` declares
- * `markup: bool = True`, and all five positions reach the wire through Rich's
- * own `render_str`. A table-level opt-out would be a mode with no reference
- * behaviour to define. [LAW:no-mode-explosion]
- *
- * `end` is cleared on both arms, not passed in, because a table cell is a
- * fragment rather than a line — the same two steps Rich takes for a printed
- * string. The `RichText` arm copies first: clearing in place would reach back
- * into the caller's object.
- */
-function toCellText(content) {
-    const text = content instanceof RichText ? content.copy() : renderMarkup(String(content ?? ""));
-    text.end = "";
-    return text;
-}
-function toRenderable(content) {
-    // [LAW:single-enforcer] `toCellText` is the one place that clears a cell's
-    // `end` — route a directly-passed `RichText` through it rather than letting
-    // it leave via the passthrough arm below untouched (rich-text-5ai code
-    // review): the passthrough exists for a genuine non-text `Renderable` (a
-    // nested `Panel` or `Table`), which carries no `end` to clear.
-    if (content instanceof RichText) {
-        return toCellText(content);
-    }
-    if (typeof content === "object" && content !== null && "render" in content) {
-        return content;
-    }
-    return toCellText(content);
-}
 /** A `want` no budget can satisfy: the column takes every cell its weight earns. */
 const UNBOUNDED = Number.MAX_SAFE_INTEGER;
 /**
@@ -57,6 +18,8 @@ const UNBOUNDED = Number.MAX_SAFE_INTEGER;
  * every other elastic column in the table.
  */
 const demandCells = (n) => Math.min(cells(n), UNBOUNDED);
+/** `n` cells of padding, as nothing at all when `n` is zero. */
+const blank = (n) => (n > 0 ? [new Segment(" ".repeat(n))] : []);
 /**
  * Hand out `total` cells across `demands`, weighted, and never past a demand's
  * `want`.
@@ -76,47 +39,81 @@ const demandCells = (n) => Math.min(cells(n), UNBOUNDED);
  * `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.
+ *
+ * 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
+ * 6/14 for 16 cells over weights 3 and 10 — come out 0.4285714285714284 and
+ * 0.4285714285714288, so the tie went wherever the rounding error pointed.
+ * The weights are read as whole numbers in one proportion (`exactWeights`) and
+ * everything after is integer division.
  */
 function distribute(total, demands) {
     const granted = demands.map(() => 0);
-    let open = demands
-        .map((_, index) => index)
-        .filter((index) => demands[index].weight > 0 && demands[index].want > 0);
-    let remaining = Math.max(0, total);
-    const weightOf = (indices) => indices.reduce((sum, index) => sum + demands[index].weight, 0);
-    while (open.length > 0 && remaining > 0) {
-        const weightSum = weightOf(open);
-        const capped = open.filter((index) => (remaining * demands[index].weight) / weightSum >= demands[index].want);
+    const bidders = demands.flatMap((demand, index) => demand.weight > 0 && demand.want > 0 ? [{ index, demand }] : []);
+    const weights = exactWeights(bidders.map(({ demand }) => demand.weight));
+    let open = bidders.map(({ index, demand }, slot) => ({
+        index,
+        want: BigInt(demand.want),
+        weight: weights[slot],
+    }));
+    const sum = (values) => values.reduce((acc, value) => acc + value, 0n);
+    // A budget past every open want grants each its want either way, and that
+    // bound is what keeps an unbounded offer — `Infinity` is a legal outer width
+    // — out of integer arithmetic that cannot hold it.
+    const wantSum = sum(open.map(({ want }) => want));
+    let remaining = total >= wantSum ? wantSum : BigInt(Math.max(0, total));
+    while (open.length > 0 && remaining > 0n) {
+        const weightSum = sum(open.map(({ weight }) => weight));
+        const capped = open.filter(({ want, weight }) => remaining * weight >= want * weightSum);
         if (capped.length === 0)
             break;
-        for (const index of capped) {
-            granted[index] = demands[index].want;
-            remaining -= demands[index].want;
+        for (const { index, want } of capped) {
+            granted[index] = Number(want);
+            remaining -= want;
         }
-        open = open.filter((index) => !capped.includes(index));
+        open = open.filter((bid) => !capped.includes(bid));
     }
-    if (open.length > 0 && remaining > 0) {
-        const weightSum = weightOf(open);
-        const shares = open.map((index) => (remaining * demands[index].weight) / weightSum);
-        const whole = shares.map(Math.floor);
-        let residue = remaining - whole.reduce((sum, cells) => sum + cells, 0);
+    if (open.length > 0 && remaining > 0n) {
+        const weightSum = sum(open.map(({ weight }) => weight));
+        const products = open.map(({ weight }) => remaining * weight);
+        const whole = products.map((product) => product / weightSum);
+        const fraction = products.map((product) => product % weightSum);
+        let residue = remaining - sum(whole);
         // The cells the shares left as fractions go to the largest fraction first,
         // ties to the leftmost column, so the total lands exactly on `remaining`.
+        // `Number` of a nonzero difference is never 0, so the sign is exact.
         const byFraction = open
             .map((_, slot) => slot)
-            .sort((a, b) => shares[b] - whole[b] - (shares[a] - whole[a]) || a - b);
+            .sort((a, b) => Number(fraction[b] - fraction[a]) || a - b);
         for (const slot of byFraction) {
-            if (residue <= 0)
+            if (residue <= 0n)
                 break;
             whole[slot]++;
             residue--;
         }
-        open.forEach((index, slot) => {
-            granted[index] = whole[slot];
+        open.forEach(({ index }, slot) => {
+            granted[index] = Number(whole[slot]);
         });
     }
     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.
+ */
+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 layoutTable(outerWidth, demands, padding, frame) {
     const [, padRightWanted, , padLeftWanted] = padding;
     // Plain `number`, not the `CellCol` `cells` hands back: this budget is spent
@@ -170,12 +167,32 @@ function layoutTable(outerWidth, demands, padding, frame) {
         want: Math.max(0, demand.want - seats[index] - reserved[index]),
         weight: demand.weight,
     })));
-    // The unspent part goes to the columns by their stretch. 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.
-    const stretched = distribute(budget - wanted.reduce((sum, cells) => sum + cells, 0), seatedDemands.map((demand) => ({ want: UNBOUNDED, weight: demand.stretch })));
-    const columns = wanted.map((cells, index) => seats[index] + reserved[index] + cells + stretched[index]);
+    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]));
+    // 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.
+    const afterWant = holding(wanted);
+    const filled = distribute(budget - spent(wanted), seatedDemands.map((demand, index) => ({
+        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 })));
+    // 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.
+    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);
     return {
         edge,
@@ -189,6 +206,19 @@ function layoutTable(outerWidth, demands, padding, frame) {
             cellWidths.reduce((sum, width) => sum + width, 0),
     };
 }
+/**
+ * The share of the leftover width a column's `ratio` claims: the ratio when it
+ * is positive, else 0 — a zero, negative or NaN ratio claims none, and the
+ * column sizes to its content. A proportion rather than a count of cells, so it
+ * is never floored: `ratio: 0.5` beside `ratio: 1` takes a third, where flooring
+ * it to 0 once starved it to a single `…`. Finite, for the reason `demandCells`
+ * is.
+ *
+ * [LAW:one-source-of-truth] `Column.flexible` is this asked as a yes/no, so the
+ * width division and the public flag cannot disagree about which columns are
+ * elastic.
+ */
+const columnShare = (col) => col.ratio !== undefined && col.ratio > 0 ? Math.min(col.ratio, UNBOUNDED) : 0;
 export class Column {
     _header;
     _footer;
@@ -224,7 +254,7 @@ export class Column {
      * 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 `toCellText` has been through. [LAW:parse-dont-validate] The setter
+     * assumes `embeddedText` 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.
      *
@@ -233,23 +263,23 @@ 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. `toCellText` already maps nothing onto empty,
+     * row a caller had asked for. `embeddedText` 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 = toCellText(content);
+        this._header = embeddedText(content);
     }
     get footer() {
         return this._footer;
     }
     set footer(content) {
-        this._footer = toCellText(content);
+        this._footer = embeddedText(content);
     }
     get flexible() {
-        return this.ratio !== undefined && this.ratio > 0;
+        return columnShare(this) > 0;
     }
     /** @internal */
     addCell(cell) {
@@ -308,10 +338,13 @@ export class Table {
         this._rows = [];
         this.box = options?.box !== undefined ? options.box : HEAVY_HEAD;
         const titleVal = options?.title;
-        this.title = titleVal !== undefined ? toCellText(titleVal) : undefined;
+        this.title = titleVal !== undefined ? embeddedText(titleVal) : undefined;
         const captionVal = options?.caption;
-        this.caption = captionVal !== undefined ? toCellText(captionVal) : undefined;
-        this.expand = options?.expand ?? false;
+        this.caption = captionVal !== undefined ? 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.
+        this.expand = (options?.expand ?? false) || options?.width !== undefined;
         this.showHeader = options?.showHeader !== false;
         this.showFooter = options?.showFooter ?? false;
         this.showLines = options?.showLines ?? false;
@@ -360,7 +393,7 @@ export class Table {
         //
         // Ahead of the column loop: a cell that throws must leave no phantom column
         // behind. [LAW:no-ambient-temporal-coupling]
-        const resolved = cells.map(toRenderable);
+        const resolved = cells.map(embed);
         // Auto-create columns if needed
         while (this._columns.length < resolved.length) {
             this.addColumn();
@@ -385,9 +418,12 @@ export class Table {
         // lacking a header should. [LAW:dataflow-not-control-flow] Both run every
         // render and each returns the receiver when it has nothing to change, so
         // the flags arrive as values rather than as branches around a step.
-        const drawable = this.box?.substitute({ asciiOnly: options.asciiOnly });
-        const box = (this.showHeader ? drawable : drawable?.plainHeaded()) ?? null;
-        const borderStyle = getStyle(options, this.borderStyle);
+        const frame = this.box?.substitute(options);
+        const box = (this.showHeader ? frame : frame?.plainHeaded()) ?? null;
+        // The table's own `style` is the base its border style layers over, and
+        // that is all it styles: the reference reads it as `table_style` for the
+        // frame and nowhere else, so a cell is untouched by it.
+        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));
@@ -400,10 +436,17 @@ export class Table {
         if (box && this.showEdge) {
             yield* box.getTop(geometry.cellWidths, border, edge);
         }
+        // Every style a cell is drawn with, resolved once per render rather than
+        // once per cell, as the reference's `_get_cells` does per column.
+        const headerStyle = getStyle(options, this.headerStyle);
+        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));
         // Header row
         if (this.showHeader) {
             const headerCells = this._columns.map((c) => c.header);
-            yield* this._renderRow(options, headerCells, geometry, box, "head", border, this.headerStyle);
+            const headerStyles = this._columns.map((c) => headerStyle.add(getStyle(options, c.headerStyle)));
+            yield* this._renderRow(options, headerCells, headerStyles, NULL_STYLE, geometry, box, "head", border);
             // Header separator
             if (box) {
                 yield* box.getRow(geometry.cellWidths, "head", border, edge);
@@ -412,11 +455,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] ?? toCellText(undefined));
-            const rowStyle = this.rowStyles.length > 0
-                ? this.rowStyles[rowIdx % this.rowStyles.length]
-                : NULL_STYLE;
-            yield* this._renderRow(options, rowCells, geometry, box, "row", border, rowStyle);
+            const rowCells = this._columns.map((_, colIdx) => row.cells[colIdx] ?? 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);
             // Row separator
             const showSep = this.showLines || row.endSection;
             if (showSep && box && rowIdx < this._rows.length - 1) {
@@ -429,7 +471,8 @@ export class Table {
                 yield* box.getRow(geometry.cellWidths, "foot", border, edge);
             }
             const footerCells = this._columns.map((c) => c.footer);
-            yield* this._renderRow(options, footerCells, geometry, box, "foot", border, this.footerStyle);
+            const footerStyles = this._columns.map((c) => footerStyle.add(getStyle(options, c.footerStyle)));
+            yield* this._renderRow(options, footerCells, footerStyles, NULL_STYLE, geometry, box, "foot", border);
         }
         // Bottom border
         if (box && this.showEdge) {
@@ -444,11 +487,13 @@ export class Table {
      * [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.
-     * Neither end stretches: a stretch only spends cells an offer happens to
-     * leave over, and a renderable reports the width its content wants rather
-     * than the width it was offered. Letting it in made an expanding table
-     * measure `Infinity` against an unbounded offer, where `withBoundedWidth`
-     * needs a natural width to fall back on.
+     * 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
+     * offer, and the maximum reports it. Letting either in made the table measure
+     * `Infinity` against an unbounded offer, where `withBoundedWidth` needs a
+     * natural width to fall back on — an expanding table, and an empty
+     * `Table.grid()`.
      * Neither can exceed the width offered and the tighter request cannot exceed
      * the looser one, so the range cannot invert. Deriving the minimum from raw
      * column and padding counts instead is what used to return
@@ -459,7 +504,20 @@ export class Table {
         const outerWidth = this._outerWidth(options);
         const frame = this._frame();
         const demands = this._columnDemands();
-        const laidOut = layoutTable(outerWidth, demands.map((demand) => ({ ...demand, stretch: 0 })), this.padding, frame).totalWidth;
+        // 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
+        // a table declared at 40 is 44 wide there, not the table's content width.
+        // It is laid out exactly as `render` lays it out, so the two cannot report
+        // different widths; a declared width with nothing bounding it
+        // (`width: Infinity` at an unbounded offer) has no size to report and falls
+        // back to the content, as an unbounded `expand` does.
+        const declared = this.tableWidth === undefined
+            ? undefined
+            : layoutTable(outerWidth, demands, this.padding, frame).totalWidth;
+        const laidOut = declared !== undefined && declared < UNBOUNDED
+            ? declared
+            : layoutTable(outerWidth, demands.map((demand) => ({ ...demand, fill: 0, stretch: false })), this.padding, 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:
@@ -470,10 +528,12 @@ export class Table {
             reserved: 0,
             want: Math.min(1, demand.want),
             weight: 1,
-            stretch: 0,
+            fill: 0,
+            ratio: 0,
+            stretch: false,
         })), this.padding, frame).totalWidth;
         return {
-            minimum: Math.min(maximum, Math.max(tightest, this.minWidth ?? 0)),
+            minimum: Math.min(maximum, Math.max(tightest, cells(this.minWidth ?? 0))),
             maximum,
         };
     }
@@ -520,35 +580,56 @@ export class Table {
      * mode gets its own path through the width division.
      */
     _columnDemands() {
-        // A ratio on any column makes every non-fixed column elastic: a ratio
-        // expresses a split of the whole width, so a column that declares none
-        // still holds a share of it (1).
-        const elastic = this._columns.some((col) => col.flexible);
         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, stretch: 0 };
+                return { reserved: declared, want: declared, weight: 0, fill: 0, ratio: 0, stretch: false };
             }
-            if (elastic) {
-                return { reserved: 0, want: UNBOUNDED, weight: demandCells(col.ratio ?? 1), stretch: 0 };
+            // 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 natural = demandCells(this._naturalWidth(col, index));
+            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 is the natural width, so the
+            // 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. The reference
-            // weighs by width too: `ratio_distribute(max_width - table_width, widths)`.
+            // 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.
-            return { reserved: 0, want: natural, weight: natural, stretch: this.expand ? natural : 0 };
+            //
+            // 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`.
+            return {
+                reserved: 0,
+                want: natural,
+                weight: natural,
+                fill: widest === undefined ? demandCells(this._bounded(col, UNBOUNDED)) : 0,
+                ratio: 0,
+                stretch: this.expand,
+            };
         });
     }
     /**
@@ -566,17 +647,18 @@ export class Table {
         if (this.showHeader)
             yield col.header;
         for (const row of this._rows)
-            yield row.cells[index] ?? toCellText(undefined);
+            yield row.cells[index] ?? embeddedText(undefined);
         if (this.showFooter)
             yield col.footer;
     }
     /**
-     * The widest cell in a column, bounded by its own `minWidth`/`maxWidth`.
-     * Zero for a column that draws nothing — a gutter asks for its padding and
-     * nothing else.
+     * 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]
      */
-    _naturalWidth(col, index) {
-        let natural = 0;
+    _widestCell(col, index) {
+        let widest;
         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
@@ -587,26 +669,39 @@ export class Table {
             // 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.
-            natural = Math.max(natural, cell instanceof RichText ? cellLen(cell.plain) : cellLen(String(cell)));
+            widest = Math.max(widest ?? 0, cell instanceof RichText ? cellLen(cell.plain) : cellLen(String(cell)));
         }
-        if (col.minWidth !== undefined)
-            natural = Math.max(natural, col.minWidth);
-        if (col.maxWidth !== undefined)
-            natural = Math.min(natural, col.maxWidth);
-        return natural;
+        return widest;
+    }
+    /**
+     * A natural width held to the column's own `minWidth`/`maxWidth`.
+     *
+     * A bound is a count of cells, read by the rule every width is read by: NaN
+     * and a negative are zero cells, so a NaN floor bounds nothing and a NaN
+     * ceiling is a ceiling of zero, as `width: NaN` is. A bare `Math.max` returns
+     * NaN instead, and the column vanishes. [LAW:one-source-of-truth]
+     */
+    _bounded(col, natural) {
+        return Math.min(Math.max(natural, cells(col.minWidth ?? 0)), cells(col.maxWidth ?? Infinity));
     }
-    *_renderRow(options, cells, geometry, box, level, border, ownStyle) {
+    *_renderRow(options, cells, styles, rowStyle, geometry, box, level, border) {
         const { padLeft, padRight, columns } = geometry;
-        const rowStyle = getStyle(options, ownStyle);
         // [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.
         const frame = box?.getContentChars(level);
+        // A divider drawn in blanks is part of the row's stripe, so it carries the
+        // row's background under the border's own style; one drawn in ink is the
+        // frame's alone. Header and footer rows have no row style, as in the
+        // reference, so their dividers are the border's either way.
+        const divider = frame && (frame.vertical.trim() === ""
+            ? new Segment(frame.vertical, rowStyle.backgroundStyle.add(border))
+            : new Segment(frame.vertical, border));
         // 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 cellLines = columns.map((cellWidth, index) => {
             const col = this._columns[index];
-            const cell = cells[index] ?? toRenderable("");
+            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
@@ -618,29 +713,32 @@ export class Table {
                     overflow: col.overflow,
                     noWrap: col.noWrap,
                     height: undefined,
-                    maxHeight: undefined,
                 })];
-            const lines = Segment.splitLines(segs).map((line) => Segment.adjustLineLength(line, cellWidth));
-            return lines.length > 0 ? lines : [[new Segment(" ".repeat(cellWidth))]];
+            return Segment.splitAndCropLines(segs, cellWidth);
         });
         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
+        // the row's floor, so its column labels line up over the data, and every
+        // other row starts at the top — the reference forces both.
+        const drop = cellLines.map((lines) => (level === "head" ? maxLines - lines.length : 0));
         for (let lineIdx = 0; lineIdx < maxLines; lineIdx++) {
             if (frame && geometry.edge === 1) {
                 yield new Segment(frame.left, border);
             }
             for (let colIdx = 0; colIdx < columns.length; colIdx++) {
-                if (colIdx > 0 && frame) {
-                    yield new Segment(frame.vertical, border);
+                if (colIdx > 0 && divider) {
+                    yield divider;
                 }
                 const cellWidth = columns[colIdx];
-                if (padLeft > 0)
-                    yield new Segment(" ".repeat(padLeft));
-                // A cell that ran out of lines contributes blanks, so every column
-                // spans the same number of rows and the frame stays rectangular.
-                const line = cellLines[colIdx][lineIdx] ?? [new Segment(" ".repeat(cellWidth))];
-                yield* rowStyle.isNull ? line : Segment.applyStyle(line, rowStyle);
-                if (padRight > 0)
-                    yield new Segment(" ".repeat(padRight));
+                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))];
+                // 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);
             }
             if (frame && geometry.edge === 1) {
                 yield new Segment(frame.right, border);
@@ -652,15 +750,16 @@ export class Table {
         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 `noWrap` outrank the options
+        // 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 a `noWrap` title would leave at its natural width
-        // and run straight through the frame. `overflow` stays theirs: every method
-        // cuts within a bound it cannot lift, so none can escape. Cleared on a copy
-        // rather than in place — the caller's text is theirs. [LAW:one-source-of-truth]
+        // 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;
-        source.noWrap = false;
+        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`
@@ -684,7 +783,6 @@ export class Table {
                 overflow: undefined,
                 noWrap: false,
                 height: undefined,
-                maxHeight: 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