@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/renderables/prompt.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Prompt — interactive prompts for user input, Rich's `rich/prompt.py`.
+ *
+ * [LAW:locality-or-seam] The renderable owns prompt logic (display, parsing the
+ * answer, choice checking, default fallback, the retry loop and the message
+ * each rejected answer prints) — but not where the answer comes from. The
+ * input source is a required `PromptInput` capability passed at the call site.
+ * Node consumers pass `nodeAsk` from `@promptctl/rich-js/node/prompt`; tests
+ * pass a fake; the browser bundle gets the classes without dragging
+ * `node:readline` into the main barrel.
+ *
+ * [LAW:types-are-the-program] The `input: PromptInput` parameter is
+ * positional and required on every `*.ask()` static — not an optional in
+ * `PromptOptions`. The previous shape allowed `Prompt.ask("name?")` at the
+ * type level and threw at runtime; the new shape makes the missing-capability
+ * state unrepresentable to TS callers.
+ *
+ * A trust-boundary `typeof === "function"` check remains because the public
+ * API surface is reachable from JS (no compile-time types) and from
+ * `any`-typed TS callers. The check makes the failure *diagnostic* (points
+ * the caller at the node helper), not gatekeep-against-bugs — TS users
+ * never see it because the type already forbids the bad state.
+ */
+import { Console } from "../core/console.js";
+import { RichText } from "../core/text.js";
+/**
+ * Input capability: receives the prompt to show — styled text, ending in the
+ * `": "` the answer is typed after — and the `Console` the prompt was asked
+ * on, and resolves with the raw user response. Implementations decide where
+ * the input comes from (stdin readline, network, in-memory queue, etc.); the
+ * console is what the prompt is drawn with, as Rich's `Console.input` draws
+ * it — its theme, its colours, the target it writes to.
+ *
+ * [LAW:effects-at-boundaries] The prompt arrives as a `RichText`, not bytes:
+ * encoding it is the console's job, and the console arrives with it.
+ */
+export type PromptInput = (prompt: RichText, console: Console) => Promise<string>;
+export interface PromptOptions<T> {
+    default?: T;
+    choices?: readonly string[];
+    caseSensitive?: boolean;
+    showChoices?: boolean;
+    showDefault?: boolean;
+    /**
+     * The console the prompt is drawn with and its invalid-answer messages are
+     * printed on — Rich's `console=`. Default: a new `Console`, made when the
+     * prompt is asked.
+     */
+    console?: Console;
+}
+/**
+ * Confirm's options. Its two choices are the yes answer and the no answer, in
+ * that order, and an answer matches one in any letter case — Rich's `Confirm`,
+ * which takes no `case_sensitive`, but where Rich lowercases only the answer
+ * and so can never match a choice spelled with a capital.
+ */
+export interface ConfirmOptions extends Omit<PromptOptions<boolean>, "choices" | "caseSensitive"> {
+    choices?: readonly [yes: string, no: string];
+}
+export declare class Prompt {
+    static ask(promptText: string, input: PromptInput, options?: PromptOptions<string>): Promise<string>;
+}
+export declare class IntPrompt {
+    static ask(promptText: string, input: PromptInput, options?: PromptOptions<number>): Promise<number>;
+}
+export declare class FloatPrompt {
+    static ask(promptText: string, input: PromptInput, options?: PromptOptions<number>): Promise<number>;
+}
+export declare class Confirm {
+    static ask(promptText: string, input: PromptInput, options?: ConfirmOptions): Promise<boolean>;
+}

package/dist/renderables/prompt.js

@@ -0,0 +1,165 @@
+/**
+ * Prompt — interactive prompts for user input, Rich's `rich/prompt.py`.
+ *
+ * [LAW:locality-or-seam] The renderable owns prompt logic (display, parsing the
+ * answer, choice checking, default fallback, the retry loop and the message
+ * each rejected answer prints) — but not where the answer comes from. The
+ * input source is a required `PromptInput` capability passed at the call site.
+ * Node consumers pass `nodeAsk` from `@promptctl/rich-js/node/prompt`; tests
+ * pass a fake; the browser bundle gets the classes without dragging
+ * `node:readline` into the main barrel.
+ *
+ * [LAW:types-are-the-program] The `input: PromptInput` parameter is
+ * positional and required on every `*.ask()` static — not an optional in
+ * `PromptOptions`. The previous shape allowed `Prompt.ask("name?")` at the
+ * type level and threw at runtime; the new shape makes the missing-capability
+ * state unrepresentable to TS callers.
+ *
+ * A trust-boundary `typeof === "function"` check remains because the public
+ * API surface is reachable from JS (no compile-time types) and from
+ * `any`-typed TS callers. The check makes the failure *diagnostic* (points
+ * the caller at the node helper), not gatekeep-against-bugs — TS users
+ * never see it because the type already forbids the bad state.
+ */
+import { Console } from "../core/console.js";
+import { renderMarkup } from "../core/markup.js";
+import { RichText } from "../core/text.js";
+/** An answer the prompt refused, and the markup it prints before asking again — Rich's `InvalidResponse`. */
+class InvalidResponse {
+    message;
+    constructor(message) {
+        this.message = message;
+    }
+}
+const ILLEGAL_CHOICE = new InvalidResponse("[prompt.invalid.choice]Please select one of the available options");
+// The prompt as Rich's `make_prompt` draws it: the caller's markup, then each
+// hint appended as plain text — never read as markup, so `[y/n]` is drawn and
+// not parsed as a tag — then the suffix.
+function makePrompt(promptText, kind, options) {
+    const prompt = new RichText("", { style: "prompt", end: "" }).append(renderMarkup(promptText));
+    // Rich's `if self.show_choices and self.choices`: an empty list draws no hint.
+    if (options.showChoices !== false && kind.choices !== undefined && kind.choices.length > 0) {
+        prompt.append(" ").append(`[${kind.choices.join("/")}]`, "prompt.choices");
+    }
+    if (options.showDefault !== false && options.default !== undefined) {
+        prompt.append(" ").append(`(${kind.renderDefault(options.default)})`, "prompt.default");
+    }
+    return prompt.append(": ");
+}
+// Rich's `PromptBase.__call__`: ask, return the default for an empty answer —
+// the answer as typed, so one of spaces is processed rather than defaulted —
+// and otherwise process it, printing why it was refused and asking again.
+async function run(promptText, input, kind, options) {
+    // [LAW:single-enforcer] Trust-boundary validation for non-TS callers
+    // (JS, or TS with `any` laundering). TS callers can't reach this branch
+    // because `PromptInput` is required at every static `.ask`. The message
+    // points at the node helper rather than letting the call site die with
+    // a generic `TypeError: input is not a function`.
+    if (typeof input !== "function") {
+        throw new TypeError("Prompt: `input` must be a `PromptInput` function. Pass `nodeAsk` from " +
+            "`@promptctl/rich-js/node/prompt` for Node, or supply a custom " +
+            "`PromptInput` for tests/browsers.");
+    }
+    const console = options.console ?? new Console();
+    const prompt = makePrompt(promptText, kind, options);
+    while (true) {
+        // A copy, because a `RichText` is mutable and the same prompt is asked
+        // again on every retry.
+        const answer = await input(prompt.copy(), console);
+        if (answer === "" && options.default !== undefined)
+            return options.default;
+        const value = kind.process(answer);
+        if (!(value instanceof InvalidResponse))
+            return value;
+        // The message is this module's markup, read as markup whatever the
+        // console's own `markup` setting.
+        console.print(renderMarkup(value.message));
+    }
+}
+/**
+ * Rich's `PromptBase.process_response`: the stripped answer converted, then
+ * checked against the choices — when there are any — and the value of the
+ * choice it matched returned, so a case-insensitive match answers with the
+ * choice as written. An answer that neither converts nor matches is refused
+ * for not converting, the check Rich makes first.
+ */
+function responseKind(convert, invalid, options) {
+    const choices = options.choices;
+    const caseSensitive = options.caseSensitive !== false;
+    const matches = (choice, value) => caseSensitive ? choice === value : choice.toLowerCase() === value.toLowerCase();
+    return {
+        choices,
+        renderDefault: String,
+        process(answer) {
+            const value = answer.trim();
+            // [LAW:dataflow-not-control-flow] With no choices every answer is its
+            // own choice. A choice matched is the answer but for letter case, which
+            // no number grammar here reads, so it converts exactly when the answer does.
+            const choice = choices === undefined ? value : choices.find((c) => matches(c, value));
+            const converted = convert(choice ?? value);
+            if (converted === undefined)
+                return invalid;
+            return choice === undefined ? ILLEGAL_CHOICE : converted;
+        },
+    };
+}
+/** Python's `int()` over a string: a sign, then digits, any two of which may have one `_` between them. */
+const INTEGER = /^[+-]?\d(?:_?\d)*$/;
+const DIGITS = String.raw `\d(?:_?\d)*`;
+/** Python's `float()` over a string: a decimal with an optional exponent, or `inf`, `infinity` or `nan`, in any case. */
+const FLOAT = new RegExp(String.raw `^[+-]?(?:(?:${DIGITS}(?:\.(?:${DIGITS})?)?|\.${DIGITS})(?:e[+-]?${DIGITS})?|inf(?:inity)?|nan)$`, "i");
+/**
+ * The integer an answer spells, as Python's `int()` reads it, or none. One a
+ * `number` cannot hold exactly is none: Python's int is unbounded and a
+ * rounded value is not the number typed, so it is refused rather than changed.
+ */
+function pythonInt(value) {
+    if (!INTEGER.test(value))
+        return undefined;
+    // `+ 0` folds `-0` into 0: Python has no negative integer zero.
+    const integer = Number(value.replaceAll("_", "")) + 0;
+    return Number.isSafeInteger(integer) ? integer : undefined;
+}
+/** The number an answer spells, as Python's `float()` reads it, or none. */
+function pythonFloat(value) {
+    if (!FLOAT.test(value))
+        return undefined;
+    return Number(value.replaceAll("_", "").toLowerCase().replace(/inf(inity)?$/, "Infinity"));
+}
+// --- Prompt ---
+export class Prompt {
+    static ask(promptText, input, options = {}) {
+        // Rich's base message, which a string prompt never prints: every answer converts.
+        const kind = responseKind((value) => value, new InvalidResponse("[prompt.invalid]Please enter a valid value"), options);
+        return run(promptText, input, kind, options);
+    }
+}
+export class IntPrompt {
+    static ask(promptText, input, options = {}) {
+        const kind = responseKind(pythonInt, new InvalidResponse("[prompt.invalid]Please enter a valid integer number"), options);
+        return run(promptText, input, kind, options);
+    }
+}
+export class FloatPrompt {
+    static ask(promptText, input, options = {}) {
+        const kind = responseKind(pythonFloat, new InvalidResponse("[prompt.invalid]Please enter a number"), options);
+        return run(promptText, input, kind, options);
+    }
+}
+const CONFIRM_INVALID = new InvalidResponse("[prompt.invalid]Please enter Y or N");
+export class Confirm {
+    static ask(promptText, input, options = {}) {
+        const [yes, no] = options.choices ?? ["y", "n"];
+        const kind = {
+            choices: [yes, no],
+            renderDefault: (value) => (value ? yes : no),
+            process(answer) {
+                const value = answer.trim().toLowerCase();
+                if (value === yes.toLowerCase())
+                    return true;
+                return value === no.toLowerCase() ? false : CONFIRM_INVALID;
+            },
+        };
+        return run(promptText, input, kind, options);
+    }
+}

package/dist/renderables/ratio.d.ts

@@ -0,0 +1,123 @@
+import type { CellCol } from "../core/cells.js";
+/**
+ * Rich's `_ratio.py`: integer totals split into parts by ratio, in exact
+ * arithmetic, each by the reference's own rounding.
+ *
+ * The rounding is the reference's and is kept for that reason alone. A
+ * largest-remainder split is fairer, and it is a different answer: 17 cells
+ * over ratios 2 and 1 are 12 + 5 by `ratioDistribute` and 11 + 6 by largest
+ * remainder, and 5 cells at 1:1 are 2 + 3 by `ratioResolve` and 3 + 2 by
+ * largest remainder with ties to the left. A renderable that splits by any
+ * other rule cannot print the bytes Rich prints for the same call.
+ *
+ * The arithmetic is the reference's too: Python's integers and `Fraction`s are
+ * exact at any size, and a double's `ratio * remaining` rounds once it passes
+ * 2^53, so the parts stopped summing to the total near
+ * `Number.MAX_SAFE_INTEGER`.
+ */
+/**
+ * Rich's `ratio_distribute`: each part the ceiling of its share of what the
+ * parts before it left, and never below its minimum, so the rounding lands on
+ * the leftmost parts. Given `minimums`, a part whose minimum is 0 takes no
+ * share, as the reference zeroes its ratio first. The parts sum to the total
+ * whenever the minimums leave room; a minimum that does not fit is paid anyway,
+ * as the reference pays it, and the parts then overrun the total. The ratios
+ * are weights in one exact proportion (`exactWeights`), so a fractional one
+ * divides as it reads, where the reference takes only whole ones.
+ */
+export declare function ratioDistribute(total: number, ratios: readonly number[], minimums?: readonly number[]): number[];
+/**
+ * Rich's `ratio_reduce`: `total` taken back from `values` by ratio, each part
+ * giving up at most its `maximum`, and a part whose maximum is 0 giving up
+ * nothing, as the reference zeroes its ratio first. Each part gives up its
+ * share of what the parts before it left, rounded half to even as Python's
+ * `round` is, so 9 at 1:1 is 4 + 5. A part held to its maximum leaves the rest
+ * to the parts after it; when they cannot take it all, less than `total` is
+ * taken back, as in the reference.
+ */
+export declare function ratioReduce(total: number, ratios: readonly number[], maximums: readonly number[], values: readonly number[]): number[];
+declare const _weight: unique symbol;
+/** A share weight: positive and finite, or 0 for a part that does not grow. */
+export type Weight = number & {
+    readonly [_weight]: true;
+};
+/**
+ * A share weight, not a cell count: fractions divide space meaningfully, so
+ * this parses where `cellCount` would floor. A weight that cannot name a share
+ * — negative, NaN, infinite — reads as zero, which already means "this part
+ * does not grow" and is set aside before any division.
+ */
+export declare function shareWeight(ratio: number): Weight;
+/**
+ * One region a `ratioResolve` total is split into: a declared `size`, or —
+ * undefined — a share by `ratio`, never below `minimumSize`. A `ratio` of 0 is
+ * a part that does not grow and takes its `minimumSize`.
+ */
+export interface Edge {
+    readonly size: CellCol | undefined;
+    readonly ratio: Weight;
+    readonly minimumSize: CellCol;
+}
+/**
+ * Rich's `ratio_resolve`: `total` cells split across `edges`, the declared
+ * sizes paid first and what is left shared by ratio.
+ *
+ * A growing edge whose share would not reach its `minimumSize` is paid that
+ * minimum and the rest are shared again without it, one edge at a time, first
+ * in order first. The shares then round by carrying each fraction into the edge
+ * after it, so they sum to what was left and the spare cells land on the
+ * rightmost edges: 5 cells at 1:1 are 2 + 3.
+ *
+ * Three departures, all the port's, not the reference's. Nothing is paid past
+ * what `total` still holds: Rich hands every edge its minimum even when that
+ * overruns the total and leaves the overflow for the screen to clip; here an
+ * edge is paid out of what is left, so the parts never sum past `total` and two
+ * panes of a layout asked to fit one cell cannot merge into a two-cell row. And
+ * a declared `size` of 0 is a pane of no cells, where Rich's `edge.size or
+ * None` reads it as undeclared and lets the pane grow. And a `ratio` of 0 is
+ * paid its minimum before any share is cut, where Rich keeps it among the
+ * growing parts and counts it as 1 in the sum (`edge.ratio or 1`), which thins
+ * every other share and can leave cells unassigned.
+ */
+export declare function ratioResolve(total: number, edges: readonly Edge[]): number[];
+/**
+ * A `total` at which `ratioResolve` gives every growing edge at least
+ * `wants[i]` cells, and every other edge its declared size or minimum.
+ *
+ * [LAW:one-source-of-truth] It inverts the split above and sits beside it for
+ * that reason. A growing edge is never handed less than the floor of its share,
+ * `total * ratio / totalRatio`, because the running total it is carved from
+ * floors once on each side. So a budget at which every share's floor reaches
+ * its want is enough, and one budget serves them all: the row needs the largest
+ * such demand, never their total.
+ *
+ * Enough, and not always the least. Carried rounding hands spare cells to the
+ * right, so "left" and "right" at 1:1 fit in 9, as 4 + 5, where this answers
+ * 10. The least total is no closed formula's answer — an edge's cells are not
+ * monotone in the total — and searching for it costs a split per cell climbed,
+ * a climb that grows with how far apart the ratios are. The spare cells are
+ * cheaper.
+ *
+ * At that budget every share already covers its edge's minimum — the want
+ * includes it — so the re-share pass pays at most an edge whose share is
+ * exactly that minimum, which leaves every other share where it was. A want is
+ * whole cells, a fraction rounded up; an unbounded one, a pane with no width of
+ * its own offered all of it, is an unbounded budget, given before the exact
+ * arithmetic, which has no infinity.
+ */
+export declare function ratioBudget(edges: readonly Edge[], wants: readonly number[]): number;
+/**
+ * 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:
+ * each caller parses its weights finite first, and this is the loud end of
+ * that.
+ *
+ * The common exponent is accumulated rather than spread into `Math.max`: a
+ * layout holds as many panes as its caller made, and one argument per pane
+ * overruns the engine's argument limit.
+ */
+export declare function exactWeights(weights: readonly number[]): bigint[];
+export {};

package/dist/renderables/ratio.js

@@ -0,0 +1,213 @@
+/**
+ * Rich's `_ratio.py`: integer totals split into parts by ratio, in exact
+ * arithmetic, each by the reference's own rounding.
+ *
+ * The rounding is the reference's and is kept for that reason alone. A
+ * largest-remainder split is fairer, and it is a different answer: 17 cells
+ * over ratios 2 and 1 are 12 + 5 by `ratioDistribute` and 11 + 6 by largest
+ * remainder, and 5 cells at 1:1 are 2 + 3 by `ratioResolve` and 3 + 2 by
+ * largest remainder with ties to the left. A renderable that splits by any
+ * other rule cannot print the bytes Rich prints for the same call.
+ *
+ * The arithmetic is the reference's too: Python's integers and `Fraction`s are
+ * exact at any size, and a double's `ratio * remaining` rounds once it passes
+ * 2^53, so the parts stopped summing to the total near
+ * `Number.MAX_SAFE_INTEGER`.
+ */
+/**
+ * Rich's `ratio_distribute`: each part the ceiling of its share of what the
+ * parts before it left, and never below its minimum, so the rounding lands on
+ * the leftmost parts. Given `minimums`, a part whose minimum is 0 takes no
+ * share, as the reference zeroes its ratio first. The parts sum to the total
+ * whenever the minimums leave room; a minimum that does not fit is paid anyway,
+ * as the reference pays it, and the parts then overrun the total. The ratios
+ * are weights in one exact proportion (`exactWeights`), so a fractional one
+ * divides as it reads, where the reference takes only whole ones.
+ */
+export function ratioDistribute(total, ratios, minimums) {
+    const weights = exactWeights(minimums === undefined ? ratios : ratios.map((ratio, index) => (minimums[index] > 0 ? ratio : 0)));
+    let totalRatio = weights.reduce((sum, ratio) => sum + ratio, 0n);
+    let remaining = BigInt(total);
+    return weights.map((ratio, index) => {
+        // A zero ratio sum is the reference's `else` arm: whatever is left goes to
+        // the part at hand, so the total is still handed out in full.
+        const share = totalRatio > 0n ? ceilDiv(ratio * remaining, totalRatio) : remaining;
+        const minimum = BigInt(minimums?.[index] ?? 0);
+        const part = share > minimum ? share : minimum;
+        totalRatio -= ratio;
+        remaining -= part;
+        return Number(part);
+    });
+}
+/**
+ * Rich's `ratio_reduce`: `total` taken back from `values` by ratio, each part
+ * giving up at most its `maximum`, and a part whose maximum is 0 giving up
+ * nothing, as the reference zeroes its ratio first. Each part gives up its
+ * share of what the parts before it left, rounded half to even as Python's
+ * `round` is, so 9 at 1:1 is 4 + 5. A part held to its maximum leaves the rest
+ * to the parts after it; when they cannot take it all, less than `total` is
+ * taken back, as in the reference.
+ */
+export function ratioReduce(total, ratios, maximums, values) {
+    const weights = exactWeights(ratios.map((ratio, index) => (maximums[index] > 0 ? ratio : 0)));
+    let totalRatio = weights.reduce((sum, ratio) => sum + ratio, 0n);
+    let remaining = BigInt(total);
+    return weights.map((ratio, index) => {
+        if (ratio === 0n)
+            return values[index];
+        const share = roundDiv(ratio * remaining, totalRatio);
+        const maximum = BigInt(maximums[index]);
+        const given = share < maximum ? share : maximum;
+        remaining -= given;
+        totalRatio -= ratio;
+        return values[index] - Number(given);
+    });
+}
+/** Python's `round(a / b)` for a positive `b`: the nearest integer, a tie to the even one. */
+function roundDiv(a, b) {
+    const floor = a / b - (a % b < 0n ? 1n : 0n);
+    const twice = 2n * (a - floor * b);
+    return twice > b || (twice === b && floor % 2n !== 0n) ? floor + 1n : floor;
+}
+/** Python's `ceil(a / b)` for a positive `b`: `BigInt` division truncates toward zero, which is the ceiling for a negative `a`. */
+function ceilDiv(a, b) {
+    const quotient = a / b;
+    return a % b > 0n ? quotient + 1n : quotient;
+}
+/**
+ * A share weight, not a cell count: fractions divide space meaningfully, so
+ * this parses where `cellCount` would floor. A weight that cannot name a share
+ * — negative, NaN, infinite — reads as zero, which already means "this part
+ * does not grow" and is set aside before any division.
+ */
+export function shareWeight(ratio) {
+    return (Number.isFinite(ratio) && ratio > 0 ? ratio : 0);
+}
+/** Whether an edge takes a share by ratio; one that does not is paid `size ?? minimumSize`. */
+const grows = (edge) => edge.size === undefined && edge.ratio !== 0;
+/**
+ * Rich's `ratio_resolve`: `total` cells split across `edges`, the declared
+ * sizes paid first and what is left shared by ratio.
+ *
+ * A growing edge whose share would not reach its `minimumSize` is paid that
+ * minimum and the rest are shared again without it, one edge at a time, first
+ * in order first. The shares then round by carrying each fraction into the edge
+ * after it, so they sum to what was left and the spare cells land on the
+ * rightmost edges: 5 cells at 1:1 are 2 + 3.
+ *
+ * Three departures, all the port's, not the reference's. Nothing is paid past
+ * what `total` still holds: Rich hands every edge its minimum even when that
+ * overruns the total and leaves the overflow for the screen to clip; here an
+ * edge is paid out of what is left, so the parts never sum past `total` and two
+ * panes of a layout asked to fit one cell cannot merge into a two-cell row. And
+ * a declared `size` of 0 is a pane of no cells, where Rich's `edge.size or
+ * None` reads it as undeclared and lets the pane grow. And a `ratio` of 0 is
+ * paid its minimum before any share is cut, where Rich keeps it among the
+ * growing parts and counts it as 1 in the sum (`edge.ratio or 1`), which thins
+ * every other share and can leave cells unassigned.
+ */
+export function ratioResolve(total, edges) {
+    const sizes = edges.map(() => 0);
+    let remaining = total;
+    const pay = (index, cells) => {
+        sizes[index] = Math.min(cells, remaining);
+        remaining -= sizes[index];
+    };
+    const growing = [];
+    edges.forEach((edge, index) => {
+        if (grows(edge))
+            growing.push(index);
+        else
+            pay(index, edge.size ?? edge.minimumSize);
+    });
+    const weights = exactWeights(growing.map((index) => edges[index].ratio));
+    let open = growing.map((index, slot) => ({
+        index,
+        weight: weights[slot],
+        minimum: BigInt(edges[index].minimumSize),
+    }));
+    // `remaining * weight / sum` is the edge's share; compared across the
+    // division so the test is exact. A budget already spent fails every edge's
+    // test, which pays each its minimum out of nothing — zero, the clip above.
+    let sum = open.reduce((acc, { weight }) => acc + weight, 0n);
+    const firstShort = () => open.find(({ weight, minimum }) => BigInt(remaining) * weight <= minimum * sum);
+    for (let short = firstShort(); short !== undefined; short = firstShort()) {
+        pay(short.index, Number(short.minimum));
+        sum -= short.weight;
+        open = open.filter((edge) => edge !== short);
+    }
+    // Carrying each edge's fraction into the next is the same as flooring the
+    // running total of the shares: an edge gets the whole cells its share moves
+    // that running total across.
+    const budget = BigInt(remaining);
+    let weightSoFar = 0n;
+    let cellsSoFar = 0n;
+    for (const { index, weight } of open) {
+        const before = cellsSoFar;
+        weightSoFar += weight;
+        cellsSoFar = (budget * weightSoFar) / sum;
+        sizes[index] = Number(cellsSoFar - before);
+    }
+    return sizes;
+}
+/**
+ * A `total` at which `ratioResolve` gives every growing edge at least
+ * `wants[i]` cells, and every other edge its declared size or minimum.
+ *
+ * [LAW:one-source-of-truth] It inverts the split above and sits beside it for
+ * that reason. A growing edge is never handed less than the floor of its share,
+ * `total * ratio / totalRatio`, because the running total it is carved from
+ * floors once on each side. So a budget at which every share's floor reaches
+ * its want is enough, and one budget serves them all: the row needs the largest
+ * such demand, never their total.
+ *
+ * Enough, and not always the least. Carried rounding hands spare cells to the
+ * right, so "left" and "right" at 1:1 fit in 9, as 4 + 5, where this answers
+ * 10. The least total is no closed formula's answer — an edge's cells are not
+ * monotone in the total — and searching for it costs a split per cell climbed,
+ * a climb that grows with how far apart the ratios are. The spare cells are
+ * cheaper.
+ *
+ * At that budget every share already covers its edge's minimum — the want
+ * includes it — so the re-share pass pays at most an edge whose share is
+ * exactly that minimum, which leaves every other share where it was. A want is
+ * whole cells, a fraction rounded up; an unbounded one, a pane with no width of
+ * its own offered all of it, is an unbounded budget, given before the exact
+ * arithmetic, which has no infinity.
+ */
+export function ratioBudget(edges, wants) {
+    const growing = edges.flatMap((edge, index) => (grows(edge) ? [index] : []));
+    const owed = growing.map((index) => Math.ceil(Math.max(edges[index].minimumSize, wants[index])));
+    if (!owed.every(Number.isFinite))
+        return Infinity;
+    const weights = exactWeights(growing.map((index) => edges[index].ratio));
+    const sum = weights.reduce((acc, weight) => acc + weight, 0n);
+    const pinned = edges.reduce((acc, edge) => acc + (grows(edge) ? 0 : (edge.size ?? edge.minimumSize)), 0);
+    const budget = owed.reduce((most, cells, slot) => {
+        const need = ceilDiv(BigInt(cells) * sum, weights[slot]);
+        return need > most ? need : most;
+    }, 0n);
+    return pinned + Number(budget);
+}
+/**
+ * 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:
+ * each caller parses its weights finite first, and this is the loud end of
+ * that.
+ *
+ * The common exponent is accumulated rather than spread into `Math.max`: a
+ * layout holds as many panes as its caller made, and one argument per pane
+ * overruns the engine's argument limit.
+ */
+export 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 = decimals.reduce((most, { exponent }) => Math.max(most, exponent), 0);
+    return decimals.map(({ mantissa, exponent }) => mantissa * 10n ** BigInt(common - exponent));
+}

package/dist/renderables/rule.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Rule — a horizontal divider line, optionally with a centered title.
+ */
+import { Segment } from "../core/segment.js";
+import type { RichText } from "../core/text.js";
+import { Style } from "../core/style.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export type RuleAlign = "left" | "center" | "right";
+export interface RuleOptions {
+    characters?: string;
+    align?: RuleAlign;
+    style?: string | Style;
+}
+export declare class Rule implements Renderable, Measurable {
+    readonly title: string | RichText | undefined;
+    readonly characters: string;
+    readonly align: RuleAlign;
+    readonly style: string | Style;
+    private readonly _label;
+    constructor(title?: string | RichText, options?: RuleOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(_options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}