@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/node/terminal-host.d.ts

@@ -0,0 +1,113 @@
+/**
+ * node:terminal-host — the `TerminalHost` implementation backed by node's
+ * process streams.
+ *
+ * [LAW:locality-or-seam] The `TerminalHost` interface is the seam and lives
+ * in `host/terminal-host.ts`, importable anywhere. *This* file is one
+ * value satisfying that interface, and it reads `process.stdin` /
+ * `process.stdout`, so it is a node subpath:
+ *
+ *     import { NodeTerminalHost } from "@promptctl/rich-js/node/terminal-host";
+ *     const screen = new Screen(new NodeTerminalHost());
+ *
+ * The ambient `process` global is not an import, so it slips past the
+ * module-graph reasoning that keeps the main barrel browser-safe: reading
+ * `process.stdin` inside a constructor throws in a browser only when someone
+ * constructs it. Moving the class here makes the boundary structural — a
+ * browser bundle that never reaches for this subpath cannot reach the global
+ * either.
+ *
+ * [LAW:no-shared-mutable-globals] Which files may read the host, and what
+ * each takes off it, is `HOST_ACCESS` in `test/seam/ambient-process.ts` —
+ * this file's entry carries its `why`, and a test fails when anything joins
+ * the list. Deliberately not restated here: the sole-ownership sentence that
+ * used to stand in this spot is what that list replaced.
+ *
+ * So if you find yourself reaching for `process.stdin`, `process.stdout`, or
+ * `setRawMode` in the runtime or in a demo, take a `TerminalHost` parameter
+ * instead. The seam is already here.
+ */
+import type { DataHandler, ExitHandler, ResizeHandler, TerminalHost, TerminalSize } from "../host/terminal-host.js";
+import type { Unsubscribe } from "../core/subscription.js";
+/**
+ * Subset of NodeJS stream API the node host actually depends on. Tests
+ * construct a host over PassThrough / Writable mocks; production wires it
+ * to `process.stdin` / `process.stdout`.
+ */
+interface NodeReadable {
+    on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    off(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    setRawMode?(raw: boolean): unknown;
+    resume?(): unknown;
+    pause?(): unknown;
+    readonly isTTY?: boolean;
+}
+interface NodeWritable {
+    write(chunk: string | Uint8Array): unknown;
+    on(event: "resize", listener: () => void): unknown;
+    off(event: "resize", listener: () => void): unknown;
+    readonly columns?: number;
+    readonly rows?: number;
+    readonly isTTY?: boolean;
+}
+/**
+ * Subset of node's `process` the host hears the program end through and
+ * suspends it with. Tests pass an `EventEmitter` that records `kill`, because
+ * the real one would stop the test runner.
+ */
+interface NodeProcess {
+    readonly pid: number;
+    on(event: string, listener: () => void): unknown;
+    prependListener(event: string, listener: () => void): unknown;
+    off(event: string, listener: () => void): unknown;
+    listenerCount(event: string): number;
+    kill(pid: number, signal: NodeJS.Signals): unknown;
+}
+export interface NodeTerminalHostOptions {
+    /**
+     * Input stream. Defaults to `process.stdin` so production code does not
+     * have to construct one explicitly. Tests pass a `PassThrough`.
+     */
+    stdin?: NodeReadable;
+    /**
+     * Output stream. Defaults to `process.stdout` for the same reason.
+     * Tests pass a `Writable` mock.
+     */
+    stdout?: NodeWritable;
+    /**
+     * The environment colour detection reads. Defaults to `process.env`; tests
+     * pass a fixed map so what the host reports does not depend on the shell
+     * that ran them.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * What the host hears the program end through and suspends it with.
+     * Defaults to `process`; tests pass an emitter that records `kill`.
+     */
+    process?: NodeProcess;
+}
+export declare class NodeTerminalHost implements TerminalHost {
+    private readonly stdin;
+    private readonly stdout;
+    private readonly process;
+    readonly env: NodeJS.ProcessEnv;
+    private readonly dataHandlers;
+    private readonly resizeHandlers;
+    private dataListener;
+    private resizeListener;
+    private rawModeRequested;
+    constructor(options?: NodeTerminalHostOptions);
+    get isTTY(): boolean;
+    get writesToTerminal(): boolean;
+    write(data: Uint8Array | string): void;
+    size(): TerminalSize;
+    setRawMode(raw: boolean): void;
+    private applyRawMode;
+    onData(handler: DataHandler): Unsubscribe;
+    onResize(handler: ResizeHandler): Unsubscribe;
+    onExit(handler: ExitHandler): Unsubscribe;
+    suspend(): Promise<void>;
+    start(): void;
+    stop(): void;
+}
+export {};

package/dist/node/terminal-host.js

@@ -0,0 +1,227 @@
+/**
+ * node:terminal-host — the `TerminalHost` implementation backed by node's
+ * process streams.
+ *
+ * [LAW:locality-or-seam] The `TerminalHost` interface is the seam and lives
+ * in `host/terminal-host.ts`, importable anywhere. *This* file is one
+ * value satisfying that interface, and it reads `process.stdin` /
+ * `process.stdout`, so it is a node subpath:
+ *
+ *     import { NodeTerminalHost } from "@promptctl/rich-js/node/terminal-host";
+ *     const screen = new Screen(new NodeTerminalHost());
+ *
+ * The ambient `process` global is not an import, so it slips past the
+ * module-graph reasoning that keeps the main barrel browser-safe: reading
+ * `process.stdin` inside a constructor throws in a browser only when someone
+ * constructs it. Moving the class here makes the boundary structural — a
+ * browser bundle that never reaches for this subpath cannot reach the global
+ * either.
+ *
+ * [LAW:no-shared-mutable-globals] Which files may read the host, and what
+ * each takes off it, is `HOST_ACCESS` in `test/seam/ambient-process.ts` —
+ * this file's entry carries its `why`, and a test fails when anything joins
+ * the list. Deliberately not restated here: the sole-ownership sentence that
+ * used to stand in this spot is what that list replaced.
+ *
+ * So if you find yourself reaching for `process.stdin`, `process.stdout`, or
+ * `setRawMode` in the runtime or in a demo, take a `TerminalHost` parameter
+ * instead. The seam is already here.
+ */
+/**
+ * The events a program ends on without anyone having signalled it. `exit`
+ * is every orderly end, `process.exit` included. `uncaughtExceptionMonitor`
+ * is a crash, and node emits it ahead of every `uncaughtException` listener
+ * and ahead of its own report — so a terminal handed back here is handed back
+ * before any crash report prints, `installTraceback`'s included, whatever
+ * order the listeners were added in.
+ */
+const ENDINGS = ["exit", "uncaughtExceptionMonitor"];
+/** The signals that end a program from outside while it holds the terminal. */
+const TERMINATIONS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+export class NodeTerminalHost {
+    stdin;
+    stdout;
+    process;
+    env;
+    dataHandlers = new Set();
+    resizeHandlers = new Set();
+    dataListener;
+    resizeListener;
+    rawModeRequested = false;
+    constructor(options = {}) {
+        this.stdin = options.stdin ?? process.stdin;
+        this.stdout = options.stdout ?? process.stdout;
+        this.env = options.env ?? process.env;
+        this.process = options.process ?? process;
+    }
+    get isTTY() {
+        return !!this.stdin.isTTY && this.writesToTerminal;
+    }
+    get writesToTerminal() {
+        return !!this.stdout.isTTY;
+    }
+    write(data) {
+        this.stdout.write(data);
+    }
+    size() {
+        return {
+            cols: this.stdout.columns ?? DEFAULT_COLS,
+            rows: this.stdout.rows ?? DEFAULT_ROWS,
+        };
+    }
+    setRawMode(raw) {
+        this.rawModeRequested = raw;
+        this.applyRawMode(raw);
+    }
+    // [LAW:single-enforcer] One site decides what to do when toggling raw
+    // mode on the underlying transport fails. Both `setRawMode` (call from
+    // outside) and `stop` (cleanup) go through this helper so neither
+    // caller has to branch on capability or exception-handling.
+    //
+    // [LAW:dataflow-not-control-flow] Two shapes of "the transport can't do
+    // this" are absorbed identically: the optional chain handles "method
+    // missing" (non-TTY streams, PassThrough in tests); the try/catch
+    // handles "method exists but threw" (node's `setRawMode` throws on
+    // closed or non-TTY streams). Callers see neither shape — they always
+    // call `setRawMode(bool)`, and the host decides what's possible.
+    //
+    // The catch is silent because the only call sites are lifecycle
+    // transitions: if the stream is already gone, there is nothing
+    // semantically meaningful for the host to do, and surfacing the
+    // exception would only make teardown brittle without giving the caller
+    // a recovery path. The demos this replaces did `try { ... } catch {}`
+    // at every call site for exactly this reason — absorbing it once here
+    // means the pattern stops spreading.
+    applyRawMode(raw) {
+        try {
+            this.stdin.setRawMode?.(raw);
+        }
+        catch {
+            // Underlying stream couldn't honor the request (closed, no longer
+            // a TTY, etc.). Lifecycle continues.
+        }
+    }
+    onData(handler) {
+        this.dataHandlers.add(handler);
+        // [LAW:single-enforcer] One underlying `data` listener fans out to all
+        // subscribers — keeps stdin's flowing/paused state derivable from
+        // "any subscribers?" instead of from per-call ref-counts scattered
+        // through the runtime.
+        if (!this.dataListener) {
+            this.dataListener = (chunk) => {
+                for (const h of this.dataHandlers)
+                    h(chunk);
+            };
+            this.stdin.on("data", this.dataListener);
+            this.stdin.resume?.();
+        }
+        return () => {
+            this.dataHandlers.delete(handler);
+            if (this.dataHandlers.size === 0 && this.dataListener) {
+                this.stdin.off("data", this.dataListener);
+                this.dataListener = undefined;
+                // Returning stdin to paused state mirrors the symmetric "no
+                // subscribers → no flow" invariant. Without this, removing the
+                // last subscriber leaves stdin in flowing mode and the process
+                // hangs forever waiting for an event nobody is listening for.
+                this.stdin.pause?.();
+            }
+        };
+    }
+    onResize(handler) {
+        this.resizeHandlers.add(handler);
+        if (!this.resizeListener) {
+            this.resizeListener = () => {
+                const size = this.size();
+                for (const h of this.resizeHandlers)
+                    h(size);
+            };
+            this.stdout.on("resize", this.resizeListener);
+        }
+        return () => {
+            this.resizeHandlers.delete(handler);
+            if (this.resizeHandlers.size === 0 && this.resizeListener) {
+                this.stdout.off("resize", this.resizeListener);
+                this.resizeListener = undefined;
+            }
+        };
+    }
+    onExit(handler) {
+        const proc = this.process;
+        // [LAW:single-enforcer] Every path detaches every listener before the
+        // handler runs, which is what makes it run once: the second event of a
+        // crash — the monitor, then `exit` — finds nothing left to call.
+        const end = () => {
+            detach();
+            handler();
+        };
+        // A signal a program listens for no longer terminates it, so the
+        // listener owes the signal its outcome. Raised again once ours is gone,
+        // it terminates — unless the program listens for it too, in which case
+        // it was never going to, and that listener hears it next. Ours goes
+        // first and leaves before the rest are called: a listener keeping the
+        // same rule (`signal-exit`'s) then finds itself alone and raises it, where
+        // two that each counted the other would both have stood down.
+        const terminations = TERMINATIONS.map((signal) => {
+            const listener = () => {
+                end();
+                if (proc.listenerCount(signal) === 0)
+                    proc.kill(proc.pid, signal);
+            };
+            return { signal, listener };
+        });
+        const detach = () => {
+            for (const event of ENDINGS)
+                proc.off(event, end);
+            for (const { signal, listener } of terminations)
+                proc.off(signal, listener);
+        };
+        for (const event of ENDINGS)
+            proc.on(event, end);
+        for (const { signal, listener } of terminations)
+            proc.prependListener(signal, listener);
+        return detach;
+    }
+    // The shell's own job control: the signal Ctrl+Z would have sent outside
+    // raw mode, to the whole foreground job as the terminal sends it — a
+    // launcher (`npm run`, `sh -c`) waiting on this process stops too, so the
+    // shell sees the job stop and takes the terminal. A signal a process sends
+    // its own group is delivered before `kill` returns, so the process is
+    // stopped inside the call and running again when it returns: `fg` has
+    // continued it, or nothing was stopped at all — the kernel discards the
+    // signal in a job no shell controls, as it does Ctrl+Z's. Either way the
+    // terminal is the program's again.
+    suspend() {
+        this.process.kill(0, "SIGTSTP");
+        return Promise.resolve();
+    }
+    start() {
+        // No-op on node: stdin/stdout are always available. Lifecycle exists
+        // so `BrowserTerminalHost` can attach to the DOM here without the
+        // runtime branching on "do I need to start?"
+    }
+    stop() {
+        // [LAW:one-source-of-truth] Symmetric teardown: drop every subscriber
+        // and detach the underlying stream listeners. After stop(), the host
+        // is in the same shape a freshly-constructed one would be in. Calling
+        // stop() repeatedly is safe — the dataListener/resizeListener guards
+        // make later calls no-ops.
+        if (this.dataListener) {
+            this.stdin.off("data", this.dataListener);
+            this.dataListener = undefined;
+            this.stdin.pause?.();
+        }
+        if (this.resizeListener) {
+            this.stdout.off("resize", this.resizeListener);
+            this.resizeListener = undefined;
+        }
+        this.dataHandlers.clear();
+        this.resizeHandlers.clear();
+        if (this.rawModeRequested) {
+            this.applyRawMode(false);
+            this.rawModeRequested = false;
+        }
+    }
+}

package/dist/node/traceback.d.ts

@@ -0,0 +1,37 @@
+/**
+ * node:traceback — install `Traceback` as the process-wide crash renderer.
+ *
+ * [LAW:locality-or-seam] `process.on` / `process.exit` live only here, on the
+ * node side of the API boundary. The `Traceback` renderable itself is pure
+ * rendering and stays in the browser-safe barrel; installing it as a global
+ * handler is a node capability, so it is a node subpath:
+ *
+ *     import { installTraceback } from "@promptctl/rich-js/node/traceback";
+ *     installTraceback({ suppress: ["node_modules"] });
+ *
+ * [LAW:dataflow-not-control-flow] Every crash is reported from one channel,
+ * `uncaughtException`. An unhandled rejection is thrown into it rather than
+ * reported beside it, so both kinds of crash are literally one code path. No
+ * payload is trusted to be an `Error`: `@types/node` annotates
+ * `uncaughtException` with `Error`, but `throw "boom"` delivers the raw
+ * string, so the annotation is a claim about the common case rather than a
+ * guarantee. `report` takes `unknown`.
+ *
+ * [LAW:no-ambient-temporal-coupling] The one channel is also what puts the
+ * report after the terminal is handed back. A program holding the alternate
+ * screen restores it on `uncaughtExceptionMonitor` (`NodeTerminalHost.onExit`),
+ * which node emits ahead of every `uncaughtException` listener. Reported
+ * straight from `unhandledRejection`, a crash skips that phase: the report
+ * draws inside the alternate screen and vanishes with it when `exit` restores
+ * the terminal. Node's crash sequence owns the order, not the order in which
+ * `installTraceback` and a host happened to add their listeners.
+ */
+import type { TracebackOptions } from "../renderables/traceback.js";
+/**
+ * Register rich tracebacks for uncaught exceptions and unhandled rejections.
+ *
+ * Calling this more than once replaces the previous handler — the last call
+ * wins, options included — so a process always has exactly one rich crash
+ * renderer no matter how many entry points reach for it.
+ */
+export declare function installTraceback(options?: TracebackOptions): void;

package/dist/node/traceback.js

@@ -0,0 +1,134 @@
+/**
+ * node:traceback — install `Traceback` as the process-wide crash renderer.
+ *
+ * [LAW:locality-or-seam] `process.on` / `process.exit` live only here, on the
+ * node side of the API boundary. The `Traceback` renderable itself is pure
+ * rendering and stays in the browser-safe barrel; installing it as a global
+ * handler is a node capability, so it is a node subpath:
+ *
+ *     import { installTraceback } from "@promptctl/rich-js/node/traceback";
+ *     installTraceback({ suppress: ["node_modules"] });
+ *
+ * [LAW:dataflow-not-control-flow] Every crash is reported from one channel,
+ * `uncaughtException`. An unhandled rejection is thrown into it rather than
+ * reported beside it, so both kinds of crash are literally one code path. No
+ * payload is trusted to be an `Error`: `@types/node` annotates
+ * `uncaughtException` with `Error`, but `throw "boom"` delivers the raw
+ * string, so the annotation is a claim about the common case rather than a
+ * guarantee. `report` takes `unknown`.
+ *
+ * [LAW:no-ambient-temporal-coupling] The one channel is also what puts the
+ * report after the terminal is handed back. A program holding the alternate
+ * screen restores it on `uncaughtExceptionMonitor` (`NodeTerminalHost.onExit`),
+ * which node emits ahead of every `uncaughtException` listener. Reported
+ * straight from `unhandledRejection`, a crash skips that phase: the report
+ * draws inside the alternate screen and vanishes with it when `exit` restores
+ * the terminal. Node's crash sequence owns the order, not the order in which
+ * `installTraceback` and a host happened to add their listeners.
+ */
+import { inspect, types } from "node:util";
+import { Console } from "../core/console.js";
+import { Traceback } from "../renderables/traceback.js";
+/** A payload's own stack, when it carries one, or `""` when it does not. */
+function stackOf(reason) {
+    if (typeof reason !== "object" || reason === null)
+        return "";
+    if (!("stack" in reason))
+        return "";
+    return typeof reason.stack === "string" ? reason.stack : "";
+}
+/**
+ * [LAW:parse-dont-validate] The checkpoint between a crash payload, which node
+ * allows to be any value at all, and `Traceback`, which renders an `Error`.
+ * The return type is the proof: nothing downstream re-asks whether the payload
+ * was throwable, and no raw value can reach the renderable to have `.name` and
+ * `.message` read off it as `undefined`.
+ *
+ * The gate is `isNativeError`, not `instanceof Error`. An error thrown inside a
+ * `node:vm` context is a real error with real frames, but its prototype comes
+ * from that realm, so `instanceof` answers false and the frames would be
+ * discarded by the one component that exists to show them. `isNativeError`
+ * reads V8's internal error slot and is realm-independent.
+ *
+ * Whatever survives that gate is not an error, so it has no call site of its
+ * own; `stackOf` salvages a stack from a duck-typed thrower and otherwise
+ * leaves it empty rather than reporting the frames of this function, which
+ * point into rich-js and describe nothing about the fault. `inspect` renders
+ * every payload shape, including circular objects, where `String(reason)`
+ * would collapse them to `[object Object]`.
+ */
+function toError(reason) {
+    if (types.isNativeError(reason))
+        return reason;
+    const error = new Error(inspect(reason));
+    error.name = "NonError";
+    error.stack = stackOf(reason);
+    return error;
+}
+/**
+ * The handler currently registered, or a no-op standing in for "none yet".
+ *
+ * [LAW:no-shared-mutable-globals] The process listener registry is a shared
+ * global, so the handler installed into it gets a single owner here rather
+ * than a caller appending to it once per call. Holding the reference is what
+ * lets `installTraceback` replace rather than accumulate.
+ *
+ * [LAW:types-are-the-program] A no-op rather than `null`: `process.off` on an
+ * unregistered listener does nothing, so the first call needs no null check
+ * and no "have we installed yet" branch. There is no absent case to handle.
+ */
+let installed = () => { };
+/**
+ * An unhandled rejection, raised as the uncaught exception it becomes when
+ * nobody listens — its reason unwrapped, which node's own conversion would
+ * bury in a message for any reason that is not an `Error`. Raised once the
+ * rejection's other listeners have heard it: a throw inside the emit would
+ * end it before them.
+ */
+function escalate(reason) {
+    queueMicrotask(() => {
+        throw reason;
+    });
+}
+/**
+ * Register rich tracebacks for uncaught exceptions and unhandled rejections.
+ *
+ * Calling this more than once replaces the previous handler — the last call
+ * wins, options included — so a process always has exactly one rich crash
+ * renderer no matter how many entry points reach for it.
+ */
+export function installTraceback(options) {
+    // [LAW:no-ambient-temporal-coupling] "This process is already crashing" is
+    // lifecycle state with one owner, not a fact left to the interleaving of two
+    // writes. A cascade — cleanup code rejecting a promise while the first
+    // report is still draining — would otherwise start a second write and a
+    // second `process.exit(1)`, and whichever drained first would cut the other
+    // off mid-frame. The first crash is the fault and the rest is its wake, so
+    // one complete report of the fault beats two corrupt ones.
+    let crashing = false;
+    const report = (reason) => {
+        if (crashing)
+            return;
+        crashing = true;
+        // [LAW:effects-at-boundaries] Render to a string first, then perform one
+        // write. `beginCapture` redirects the console's sink without setting
+        // `file:`, so stderr's TTY status still drives colour depth — a `file:`
+        // sink would report `isTTY === false` and silently strip colour.
+        const out = new Console({ stderr: true });
+        out.beginCapture();
+        out.print(new Traceback(toError(reason), options));
+        // [LAW:no-silent-failure] Exit only once the bytes have drained. When
+        // stderr is a pipe (CI logs, `2>&1 | tee`), writes are asynchronous and
+        // an immediate `process.exit(1)` truncates the traceback at the pipe
+        // buffer — the longer the traceback, the more of it is lost, which is
+        // the reverse of what a crash report should do.
+        process.stderr.write(out.endCapture(), () => {
+            process.exit(1);
+        });
+    };
+    process.off("uncaughtException", installed);
+    process.off("unhandledRejection", escalate);
+    process.on("uncaughtException", report);
+    process.on("unhandledRejection", escalate);
+    installed = report;
+}

package/dist/renderables/align.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Align — wraps a renderable and places its output horizontally, as one block.
+ */
+import { Segment } from "../core/segment.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import { type Alignment } from "../core/place.js";
+export declare class Align implements Renderable, Measurable {
+    readonly renderable: Renderable;
+    readonly align: Alignment;
+    constructor(renderable: Renderable, align?: Alignment);
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/align.js

@@ -0,0 +1,33 @@
+/**
+ * Align — wraps a renderable and places its output horizontally, as one block.
+ */
+import { Segment } from "../core/segment.js";
+import { Measurement } from "../core/measure.js";
+import { isMeasurable, withBoundedWidth } from "../core/protocol.js";
+import { placeBlock } from "../core/place.js";
+export class Align {
+    renderable;
+    align;
+    constructor(renderable, align = "center") {
+        this.renderable = renderable;
+        this.align = align;
+    }
+    // [LAW:one-source-of-truth] `placeBlock` is the placement; `Console.print`'s
+    // `justify` uses the same one.
+    *render(options) {
+        for (const line of placeBlock(this.renderable, this.align, withBoundedWidth(options, this))) {
+            yield* line;
+            yield Segment.line();
+        }
+    }
+    measure(options) {
+        if (isMeasurable(this.renderable)) {
+            const measurement = Measurement.get(options, this.renderable);
+            return {
+                minimum: Math.max(1, measurement.minimum),
+                maximum: measurement.maximum,
+            };
+        }
+        return { minimum: 1, maximum: options.maxWidth };
+    }
+}

package/dist/renderables/columns.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Columns — arranges renderables in a multi-column layout.
+ */
+import { Segment } from "../core/segment.js";
+import type { PaddingDimensions } from "./padding.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export interface ColumnsOptions {
+    expand?: boolean;
+    equal?: boolean;
+    width?: number;
+    padding?: PaddingDimensions;
+    columnFirst?: boolean;
+}
+export declare class Columns implements Renderable, Measurable {
+    renderables: (Renderable & Partial<Measurable>)[];
+    readonly expand: boolean;
+    readonly equal: boolean;
+    readonly colWidth: number | undefined;
+    readonly columnFirst: boolean;
+    readonly gutterWidth: number;
+    constructor(items?: Iterable<unknown>, options?: ColumnsOptions);
+    render(rawOptions: RenderOptions): Iterable<Segment>;
+    /**
+     * The requested width divided into columns, once.
+     *
+     * [LAW:single-enforcer] The three modes disagree only about how many columns
+     * there are and how wide each one is, so they disagree in one place. `render`
+     * lays out against this division and `_naturalWidth` is the width at which it
+     * comes out as one row of every item.
+     */
+    private _divide;
+    /**
+     * The widest any one item wants to be.
+     *
+     * An item that cannot measure itself wants the offer, which is what `Panel`,
+     * `Padding`, `Layout` and `Tree` all answer for the same case — and under an
+     * unbounded offer that is `Infinity`, so `withBoundedWidth` throws and says
+     * the request was unanswerable. Counting it as one cell instead reported a
+     * natural width of 1, which resolved an unbounded offer to a single column and
+     * cropped forty cells of content down to `"x"` with no error at all.
+     */
+    private _itemWidth;
+    /**
+     * The declared column width, bounded by the width offered.
+     *
+     * [LAW:single-enforcer] A declared width is what a column asks for, not what
+     * it takes — the contract `Table._outerWidth` keeps for a declared table
+     * width. Read by `_divide` for render and by `_naturalWidth` for measure, so
+     * the two answer from one number: laid out at the raw declared width, a
+     * six-cell column offered three emitted six-cell lines while `measure`
+     * reported three, and the terminal's soft wrap took the frame of everything
+     * printed after it.
+     */
+    private _declaredWidth;
+    /** The width at which every item sits on one row: n columns and the gutters between them. */
+    private _naturalWidth;
+    measure(rawOptions: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}