@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/renderables/progressBar.js

@@ -1,11 +1,26 @@
 /**
  * ProgressBar — a visual progress bar rendered with block characters.
  */
+import { cellCount } from "../core/cells.js";
+import { ColorDepth, ColorRgba, ColorSpec, resolveTerminal } from "../core/color.js";
 import { Segment } from "../core/segment.js";
-import { NULL_STYLE } from "../core/style.js";
+import { Style } from "../core/style.js";
 import { drawable, getStyle } from "../core/protocol.js";
+import { Effected } from "./effect.js";
+import { EFFECT_CURVES, onColors, shimmer } from "./effects.js";
 const BAR = "━";
 const ASCII_BAR = "-";
+const HALF_BAR_RIGHT = "╸";
+const HALF_BAR_LEFT = "╺";
+/**
+ * The pulse's shimmer: the signed-off ease and swing, at a period that carries
+ * the light along a bar at about Rich's pace, and a band reaching half Rich's
+ * `PULSE_SIZE` of 20 cells either side of its centre.
+ */
+const PULSE_CURVE = { ...EFFECT_CURVES.shimmer, seconds: 5 };
+const PULSE_REACH = 10;
+/** Rich's pulse back where the back style names no colour. */
+const PULSE_BACK = ColorSpec.fromRgba(new ColorRgba(0, 0, 0));
 export class ProgressBar {
     total;
     completed;
@@ -18,36 +33,76 @@ export class ProgressBar {
         this.total = options?.total ?? 100;
         this.completed = options?.completed ?? 0;
         this.width = options?.width;
-        this.pulse = options?.pulse ?? false;
-        this.style = options?.style ?? NULL_STYLE;
+        this.pulse = options?.pulse;
+        this.style = options?.style ?? "bar.back";
         this.completeStyle = options?.completeStyle ?? "bar.complete";
         this.finishedStyle = options?.finishedStyle ?? "bar.finished";
     }
-    get percentComplete() {
-        if (this.total <= 0)
-            return 0;
-        return Math.min(1, Math.max(0, this.completed / this.total));
-    }
     *render(options) {
-        const barWidth = this.width ?? Math.min(40, options.maxWidth);
-        const percent = this.percentComplete;
-        const isFinished = percent >= 1;
-        const filledWidth = Math.round(barWidth * percent);
-        const emptyWidth = barWidth - filledWidth;
+        // Never wider than offered, as Rich's `min(self.width or max_width, max_width)`.
+        // [LAW:parse-dont-validate] parsed as a cell count, so a negative width draws nothing, as Python's `"━" * -2` is "".
+        const width = cellCount(Math.min(this.width || options.maxWidth, options.maxWidth));
+        if (this.pulse === undefined) {
+            yield* this.track(options, width, this.completeHalves(width), getStyle(options, this.style));
+            return;
+        }
+        const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
+        // Rich's pulse resolves its colours on the terminal a depth assumes, as
+        // `get_truecolor` does with no theme; so does this.
+        const theme = resolveTerminal(undefined, depth);
+        // Rich writes the pulse's back as a colour of its own, black where the
+        // back style names none, so the light always has the bar's colour to fall
+        // on: one the terminal supplies takes no light.
+        const style = getStyle(options, this.style);
+        const ink = style.color?.isDefault === false ? style.color : ColorSpec.fromRgba((style.color ?? PULSE_BACK).getTruecolor(theme, true));
+        const back = style.add(Style.fromColor(ink));
+        // [LAW:no-ambient-temporal-coupling] The moment is the caller's; the bar
+        // only says what it looks like then. An empty track, lit by the shimmer.
+        const track = { render: (o) => this.track(o, width, 0, back) };
+        yield* new Effected(track, this.pulseEffect(options, back, width, depth, theme), { t: this.pulse.t, key: "progress-bar", theme }).render(options);
+    }
+    /**
+     * The shimmer over this bar's back colour as `Effected` sees it drawn at
+     * `depth`, toward `bar.pulse`. A bar has no words to keep legible, so its
+     * back takes the whole of the light.
+     */
+    pulseEffect(options, back, width, depth, theme) {
+        const ink = back.drawnColors(depth).color ?? ColorSpec.default();
+        const glow = getStyle(options, "bar.pulse").drawnColors(depth).color ?? ColorSpec.default();
+        const loop = shimmer(PULSE_CURVE, width, PULSE_REACH, glow.getTruecolor(theme, true), 0);
+        return onColors(new Map([[ink.getTruecolor(theme, true).hex, 1]]), loop);
+    }
+    /** Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and a total of zero is a bar already full. */
+    completeHalves(width) {
+        const completed = Math.min(this.total, Math.max(0, this.completed));
+        return this.total ? Math.trunc((width * 2 * completed) / this.total) : width * 2;
+    }
+    /** The bar `width` cells wide with `completeHalves` half cells filled, the rest in `back`. */
+    *track(options, width, completeHalves, back) {
+        const barCount = Math.floor(completeHalves / 2);
+        const halfBarCount = completeHalves % 2;
+        const isFinished = this.completed >= this.total;
         const fill = getStyle(options, isFinished ? this.finishedStyle : this.completeStyle);
-        const back = getStyle(options, this.style);
         const fillStyle = fill.isNull ? undefined : fill;
-        const bgStyle = back.isNull ? undefined : back;
+        const backStyle = back.isNull ? undefined : back;
         const bar = drawable(options, BAR, ASCII_BAR);
-        if (filledWidth > 0) {
-            yield new Segment(bar.repeat(filledWidth), fillStyle);
-        }
-        if (emptyWidth > 0) {
-            yield new Segment(bar.repeat(emptyWidth), bgStyle);
+        if (barCount)
+            yield new Segment(bar.repeat(barCount), fillStyle);
+        if (halfBarCount)
+            yield new Segment(drawable(options, HALF_BAR_RIGHT, " "), fillStyle);
+        // The back is drawn in colour alone, so an output with none leaves it blank.
+        if (options.colorSystem === null)
+            return;
+        let remaining = width - barCount - halfBarCount;
+        if (remaining && !halfBarCount && barCount) {
+            yield new Segment(drawable(options, HALF_BAR_LEFT, " "), backStyle);
+            remaining -= 1;
         }
+        if (remaining)
+            yield new Segment(bar.repeat(remaining), backStyle);
     }
-    measure(_options) {
-        const w = this.width ?? 40;
-        return { minimum: 4, maximum: w };
+    /** A width given is the bar's exact width, as Rich measures it; one left open fills what it is offered, down to 4. */
+    measure(options) {
+        return this.width === undefined ? { minimum: 4, maximum: options.maxWidth } : { minimum: this.width, maximum: this.width };
     }
 }

package/dist/renderables/prompt.d.ts

@@ -1,12 +1,13 @@
 /**
- * Prompt — interactive prompts for user input.
+ * Prompt — interactive prompts for user input, Rich's `rich/prompt.py`.
  *
- * [LAW:locality-or-seam] The renderable owns prompt logic (display, choice
- * validation, default fallback, retry loop) — 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: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
@@ -20,20 +21,41 @@
  * 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 rendered prompt string (always with a
- * trailing space appended by the renderable, so implementations should not
- * add their own), resolves with the raw user response. Implementations
- * decide where the input comes from (stdin readline, network, in-memory
- * queue, etc.).
+ * 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: string) => Promise<string>;
+export type PromptInput = (prompt: RichText, console: Console) => Promise<string>;
 export interface PromptOptions<T> {
     default?: T;
-    choices?: string[];
+    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>;
@@ -45,5 +67,5 @@ 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?: PromptOptions<boolean>): Promise<boolean>;
+    static ask(promptText: string, input: PromptInput, options?: ConfirmOptions): Promise<boolean>;
 }

package/dist/renderables/prompt.js

@@ -1,12 +1,13 @@
 /**
- * Prompt — interactive prompts for user input.
+ * Prompt — interactive prompts for user input, Rich's `rich/prompt.py`.
  *
- * [LAW:locality-or-seam] The renderable owns prompt logic (display, choice
- * validation, default fallback, retry loop) — 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: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
@@ -20,9 +21,35 @@
  * 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";
-// --- Base ---
-function ask(promptText, input) {
+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
@@ -33,93 +60,106 @@ function ask(promptText, input) {
             "`@promptctl/rich-js/node/prompt` for Node, or supply a custom " +
             "`PromptInput` for tests/browsers.");
     }
-    const rendered = renderMarkup(promptText);
-    return input(rendered.plain + " ");
+    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 async ask(promptText, input, options) {
-        const showDefault = options?.showDefault !== false;
-        const showChoices = options?.showChoices !== false;
-        let display = promptText;
-        if (showChoices && options?.choices) {
-            display += ` [${options.choices.join("/")}]`;
-        }
-        if (showDefault && options?.default !== undefined) {
-            display += ` (${options.default})`;
-        }
-        display += ":";
-        while (true) {
-            const answer = await ask(display, input);
-            const value = answer.trim();
-            if (value === "" && options?.default !== undefined) {
-                return options.default;
-            }
-            if (options?.choices) {
-                const caseSensitive = options.caseSensitive !== false;
-                const match = options.choices.find((c) => caseSensitive ? c === value : c.toLowerCase() === value.toLowerCase());
-                if (match)
-                    return match;
-                continue;
-            }
-            return value;
-        }
+    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 async ask(promptText, input, options) {
-        const showDefault = options?.showDefault !== false;
-        let display = promptText;
-        if (showDefault && options?.default !== undefined) {
-            display += ` (${options.default})`;
-        }
-        display += ":";
-        while (true) {
-            const answer = await ask(display, input);
-            const value = answer.trim();
-            if (value === "" && options?.default !== undefined) {
-                return options.default;
-            }
-            const num = parseInt(value, 10);
-            if (!isNaN(num) && String(num) === value)
-                return num;
-        }
+    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 async ask(promptText, input, options) {
-        const showDefault = options?.showDefault !== false;
-        let display = promptText;
-        if (showDefault && options?.default !== undefined) {
-            display += ` (${options.default})`;
-        }
-        display += ":";
-        while (true) {
-            const answer = await ask(display, input);
-            const value = answer.trim();
-            if (value === "" && options?.default !== undefined) {
-                return options.default;
-            }
-            const num = parseFloat(value);
-            if (!isNaN(num))
-                return num;
-        }
+    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 async ask(promptText, input, options) {
-        const defaultVal = options?.default;
-        const yesNo = defaultVal === true ? "Y/n" : defaultVal === false ? "y/N" : "y/n";
-        const display = `${promptText} [${yesNo}]:`;
-        while (true) {
-            const answer = await ask(display, input);
-            const value = answer.trim().toLowerCase();
-            if (value === "" && defaultVal !== undefined)
-                return defaultVal;
-            if (value === "y" || value === "yes")
-                return true;
-            if (value === "n" || value === "no")
-                return false;
-        }
+    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 {};