@orkestrel/console 0.0.1

package/dist/src/core/index.d.cts

@@ -0,0 +1,2299 @@
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+
+/**
+ * Pad (or, when over budget, truncate) `text` to exactly `target` VISIBLE columns, positioning
+ * it by `alignment`. The width primitive the box / table renderers align every cell with.
+ *
+ * @remarks
+ * Measures with {@link width} (visible code points, ANSI-aware), so a styled string aligns by
+ * its visible content, not its escape codes. When `width(text) < target`, the deficit is added
+ * as spaces — all trailing (`left`), all leading (`right`), or split with the extra space on
+ * the right (`center`). When `width(text) > target`, the VISIBLE characters are sliced to
+ * `target` (a defensive guard — the renderers size columns to fit, so this is rarely hit; it
+ * slices the stripped text, so it never bisects an escape sequence into a broken half).
+ *
+ * @param text - The cell content (may be styled)
+ * @param target - The visible column count to fit `text` into
+ * @param alignment - Where to position `text` within the width; defaults to `left`
+ * @returns `text` fitted to exactly `target` visible columns
+ *
+ * @example
+ * ```ts
+ * align('hi', 5) // 'hi   '
+ * align('hi', 5, 'right') // '   hi'
+ * align('hi', 5, 'center') // ' hi  '
+ * ```
+ */
+export declare function align(text: string, target: number, alignment?: Alignment): string;
+
+/**
+ * Horizontal text alignment within a fixed-width cell — the conventional three-value set a
+ * {@link ColumnSpec} (and the box / separator title) aligns by. A value pair / set, not a
+ * binary toggle (§4.4), so it stays a union.
+ */
+export declare type Alignment = 'left' | 'center' | 'right';
+
+/**
+ * Matches any ANSI/VT escape sequence — CSI (SGR color/style plus cursor/erase/scroll,
+ * including colon-parameterized SGR), OSC / DCS / PM / APC / SOS string sequences
+ * (titles, hyperlinks, device strings), the `nF` charset-select family, and the
+ * two-byte `Fp` / `Fe` / `Fs` sequences (e.g. `ESC 7`, `ESC D`, `ESC c` RIS). Global, so
+ * `strip` removes every occurrence.
+ *
+ * @remarks
+ * A global `RegExp` carries a mutable `lastIndex`; a scan must build a FRESH `RegExp`
+ * from this one's `source` + `flags` rather than reuse this instance's `lastIndex`. This
+ * is the canonical definition, not a shared scanner. The alternation is ORDERED so the
+ * CSI / string-family arms (which can start with a byte a later single-byte arm would
+ * also match) win first; every arm uses disjoint, non-nested character classes, so the
+ * match is linear in input length — no catastrophic backtracking (ReDoS-safe) even on an
+ * adversarial run of digits inside an unterminated CSI. Built from `String.fromCharCode`
+ * so no control-character literal appears in a regex source (the codebase idiom).
+ */
+export declare const ANSI_PATTERN: RegExp;
+
+/**
+ * The cross-environment default {@link RendererInterface} — renders style DATA as ANSI
+ * SGR escape codes, exactly as `Scheduler` is the `setTimeout` default for its seam. It
+ * is the single styling output the whole console / terminal system uses in a terminal;
+ * the browser `%c` / CSS renderer (the C-f branch) implements the SAME contract over
+ * the SAME {@link Style}, so retargeting changes the renderer, never the style model.
+ *
+ * @remarks
+ * - **Style is DATA in, SGR string out.** It reads the style's `foreground` /
+ *   `background` / `attributes` and emits one `ESC[…m` sequence whose parameters are the
+ *   mapped SGR numbers (foreground 30–37 / 90–97, background 40–47 / 100–107, attributes
+ *   1 / 2 / 3 / 4 / 7 / 9), followed by `text`, terminated by the reset `ESC[0m`.
+ * - **Multiple attributes compose** — their codes join with `;` in a single sequence
+ *   (`ESC[1;4;31m` for bold + underline + red), so one open and one reset wrap the run.
+ * - **`default` and unset colors emit no code** — a `default` (or absent) `foreground` /
+ *   `background` leaves the terminal's own ink.
+ * - **The empty style and the empty string pass through** — when there is nothing to
+ *   apply (no colors, no attributes) or `text` is `''`, `text` is returned VERBATIM with
+ *   no escape codes, so an unstyled render never injects a stray reset.
+ * - **Stateless and event-free** — no fields, no events; safe to share one instance.
+ */
+export declare class ANSIRenderer implements RendererInterface {
+    #private;
+    /**
+     * Wrap `text` in the SGR codes for `style`. Returns `text` unchanged when the style
+     * is empty or `text` is `''`.
+     */
+    render(style: Style, text: string): string;
+}
+
+/**
+ * A text-style attribute — the six standard SGR text effects.
+ *
+ * @remarks
+ * Style as DATA: an `Attribute` is a name. The ANSI renderer maps each to its SGR
+ * on-code (`bold` → 1, `dim` → 2, `italic` → 3, `underline` → 4, `inverse` → 7,
+ * `strikethrough` → 9), composing several at once; a browser renderer maps the same
+ * names to CSS (`font-weight`, `font-style`, `text-decoration`, …).
+ */
+export declare type Attribute = 'bold' | 'dim' | 'italic' | 'underline' | 'inverse' | 'strikethrough';
+
+/**
+ * Each {@link Attribute}'s SGR "on" parameter — `bold` 1, `dim` 2, `italic` 3,
+ * `underline` 4, `inverse` 7, `strikethrough` 9. The renderer composes several by
+ * joining their codes with `;` in one SGR sequence.
+ */
+export declare const ATTRIBUTE_CODES: Readonly<Record<Attribute, number>>;
+
+/**
+ * Every {@link Attribute}, frozen — the attributes the styler exposes as chainable
+ * accessors. The source of truth for the attribute axis.
+ */
+export declare const ATTRIBUTES: readonly Attribute[];
+
+/**
+ * Each {@link Color}'s SGR BACKGROUND parameter — the 8 base colors at 40–47 and their
+ * bright variants at 100–107. `default` is intentionally absent (it emits no code).
+ */
+export declare const BACKGROUND_CODES: Readonly<Record<Exclude<Color, 'default'>, number>>;
+
+/**
+ * The default EMPTY-cell glyph {@link import('./helpers.js').renderBar} draws the remaining run of a
+ * progress bar with — the light-shade block `░` (U+2591). A single visible cell; a consumer overrides
+ * it via {@link import('./types.js').ProgressBarOptions}`.empty`.
+ */
+export declare const BAR_EMPTY = "\u2591";
+
+/**
+ * The default FILLED-cell glyph {@link import('./helpers.js').renderBar} draws the completed run of a
+ * progress bar with — the full block `█` (U+2588). A single visible cell; a consumer overrides it via
+ * {@link import('./types.js').ProgressBarOptions}`.fill`.
+ */
+export declare const BAR_FILL = "\u2588";
+
+/** The BEL control character (`U+0007`) that can terminate an OSC sequence. */
+export declare const BEL: string;
+
+/**
+ * The complete {@link BorderChars} junction set for each {@link BorderStyle} — the standard
+ * Unicode box-drawing glyphs at the four line weights. The renderers ({@link
+ * import('./helpers.js').renderBox} / {@link import('./helpers.js').renderTable}) look the
+ * style up here, so no glyph literal lives in a renderer. Deeply frozen.
+ *
+ * @remarks
+ * `round` shares `single`'s edges and tees — only its corners differ (the rounded `╭╮╰╯`).
+ */
+export declare const BORDER_CHARS: Readonly<Record<BorderStyle, BorderChars>>;
+
+/**
+ * One complete box-drawing junction set for a {@link BorderStyle} — every glyph the box /
+ * table renderers need to frame content and rule a table. Plain data (the value lives in
+ * {@link BORDER_CHARS}); the renderers read these so no glyph literal is hard-coded in a
+ * renderer.
+ *
+ * @remarks
+ * - `horizontal` / `vertical` — the edge run characters.
+ * - `topLeft` / `topRight` / `bottomLeft` / `bottomRight` — the four corners.
+ * - `cross` — the four-way `┼` junction (a table's interior grid crossing).
+ * - `teeDown` / `teeUp` / `teeRight` / `teeLeft` — the `┬` / `┴` / `├` / `┤` three-way
+ *   junctions where a separator meets an edge (a table's column separators at the top, the
+ *   header rule, and the bottom).
+ */
+export declare interface BorderChars {
+    readonly horizontal: string;
+    readonly vertical: string;
+    readonly topLeft: string;
+    readonly topRight: string;
+    readonly bottomLeft: string;
+    readonly bottomRight: string;
+    readonly cross: string;
+    readonly teeDown: string;
+    readonly teeUp: string;
+    readonly teeRight: string;
+    readonly teeLeft: string;
+}
+
+/**
+ * A box-drawing border style — the four standard Unicode line weights the renderers frame
+ * with. Each selects a full junction set in {@link BORDER_CHARS} (corners, edges, and the
+ * `T` / cross junctions a table needs). A named, fixed set (an external-spec value family),
+ * never a toggle — so it stays a union.
+ *
+ * @remarks
+ * `single` (`┌─┐`), `double` (`╔═╗`), `round` (`╭─╮` — single edges, rounded corners), and
+ * `heavy` (`┏━┓`). The renderer looks the style up in {@link BORDER_CHARS}; styling the
+ * border (a color) is a separate, orthogonal concern handled by the optional `styler`.
+ */
+export declare type BorderStyle = 'single' | 'double' | 'round' | 'heavy';
+
+/**
+ * Options for {@link import('./helpers.js').renderBox} — content framed in box-drawing
+ * characters.
+ *
+ * @remarks
+ * - `content` — the body text; embedded newlines split it into lines, each framed on its own
+ *   row. Every row is padded to the inner width measured by {@link import('./helpers.js').width}
+ *   (the VISIBLE width), so ANSI-styled content stays aligned inside the frame.
+ * - `title` — an optional caption embedded in the TOP border.
+ * - `padding` — horizontal cells of blank padding inside each vertical edge; defaults to
+ *   {@link DEFAULT_PADDING}.
+ * - `border` — the {@link BorderStyle}; defaults to {@link DEFAULT_BORDER} (`single`).
+ * - `width` — the total visible width of the box. When omitted, the box hugs its widest line
+ *   (plus padding + borders); when supplied, narrower lines pad out and the box is exactly
+ *   that wide (content wider than the budget is not truncated — `renderTable` is the
+ *   width-bounded renderer).
+ * - `styler` — colors the border (and title) when supplied; alignment is unaffected.
+ */
+export declare interface BoxOptions {
+    readonly content: string;
+    readonly title?: string;
+    readonly padding?: number;
+    readonly border?: BorderStyle;
+    readonly width?: number;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * An observable console interceptor (AGENTS §13) — it takes control of the global `console.*` on
+ * the READ side. While `active`, every configured `console.x` call is captured as a frozen
+ * {@link CapturedMessage}, buffered (total + by level, bounded), emitted on `capture`, and — per
+ * options — mirrored to the real console and/or forwarded to a {@link SinkInterface}.
+ *
+ * @remarks
+ * - **Snapshot-at-start (the no-capture-loop principle).** `start()` snapshots the CURRENT
+ *   `console[level]` for each configured {@link CaptureLevel}, then installs the wrappers. The
+ *   mirror writes through that snapshot — so our OWN console sink output (the Logger / Reporter,
+ *   which snapshot the real `console` at creation) is never recaptured: `Capture` catches
+ *   THIRD-PARTY `console.*`, not our writes. Create your loggers BEFORE installing a capture.
+ * - **Idempotent + PROCESS-GLOBAL + NON-REENTRANT.** `start()` while already `active` is a no-op
+ *   (never double-patches); `stop()` while inactive is a no-op. It patches the ONE global
+ *   `console`, so at most ONE capture may be active at a time — running two concurrently
+ *   interleaves their buffers and clobbers each other's restore.
+ * - **Bounded buffers.** `messages()` / `messages(level)` — the total buffer and each by-level
+ *   bucket are each capped at `limit`
+ *   (oldest dropped first), never unbounded — the same retention precedent as {@link Logger}.
+ * - **Lifecycle (§10).** `start` / `stop` toggle interception (emitting `start` / `stop`);
+ *   `destroy()` stops (restoring `console`) then destroys the emitter.
+ *
+ * @example
+ * ```ts
+ * const capture = new Capture({ levels: ['warn', 'error'], mirror: true })
+ * capture.start()
+ * console.warn('third-party noise') // captured AND mirrored to the real console
+ * capture.messages('warn') // [{ level: 'warn', text: 'third-party noise', time: … }]
+ * capture.stop() // console.warn restored
+ * ```
+ */
+export declare class Capture implements CaptureInterface {
+    #private;
+    constructor(options?: CaptureOptions);
+    get emitter(): EmitterInterface<CaptureEventMap>;
+    get active(): boolean;
+    start(): void;
+    stop(): void;
+    messages(): readonly CapturedMessage[];
+    messages(level: CaptureLevel): readonly CapturedMessage[];
+    clear(): void;
+    destroy(): void;
+}
+
+/**
+ * Each {@link CaptureLevel}'s {@link LogLevel} for the optional sink forward — the projection the
+ * Capture routes through when writing an intercepted call to a {@link
+ * import('./types.js').SinkInterface} (`sink.write(text, CAPTURE_LEVEL_MAP[level])`). `warn` /
+ * `error` / `debug` / `info` map to their matching {@link LogLevel}; `log` maps to `info` (a plain
+ * console log is informational — the default stream), so a stream-aware sink routes `warn` / `error`
+ * captures to the right stream. The source of truth for the capture-to-log projection.
+ */
+export declare const CAPTURE_LEVEL_MAP: Readonly<Record<CaptureLevel, LogLevel>>;
+
+/**
+ * Every {@link CaptureLevel}, frozen — the `console.*` methods a {@link
+ * import('./types.js').CaptureInterface} intercepts by default (and the source of truth for the
+ * capture-level axis; drives exhaustive tests). The universal console methods: `log`, `info`,
+ * `warn`, `error`, `debug`.
+ */
+export declare const CAPTURE_LEVELS: readonly CaptureLevel[];
+
+/**
+ * One captured console call — an immutable, serializable record of a single intercepted
+ * `console.*` invocation. A {@link CaptureInterface} builds one per call, freezes it, buffers it
+ * (total + by level), and emits it on `capture`; every consumer reads this exact shape.
+ *
+ * @remarks
+ * - `level` — the {@link CaptureLevel} naming which `console.x` was called.
+ * - `text` — the call's arguments stringified into one line (see
+ *   {@link import('./helpers.js').formatArgs}): an `Error` → `name: message`, a plain object →
+ *   circular-safe `JSON.stringify`, anything else → `String(arg)`, all space-joined.
+ * - `time` — the capture instant as epoch milliseconds (`Date.now()`); a plain number so the
+ *   record stays serializable (no `Date` to clone) and orderable — the same convention as
+ *   {@link LogRecord.time}.
+ * - The value is frozen at construction — a consumer reads it, never mutates it.
+ */
+export declare interface CapturedMessage {
+    readonly level: CaptureLevel;
+    readonly text: string;
+    readonly time: number;
+}
+
+/**
+ * The observable events a {@link CaptureInterface} emits (AGENTS §13).
+ *
+ * @remarks
+ * - `capture` — the core event: fires for EVERY intercepted `console.*` call (one per call,
+ *   while active), carrying the frozen {@link CapturedMessage}. The hook a live console viewer /
+ *   tee rides.
+ * - `start` / `stop` — the lifecycle signals: `start` fires when interception is installed (the
+ *   first `start()` on an inactive capture), `stop` when it is torn down (a `stop()` on an active
+ *   capture, and from `destroy()`); both are pure signals (empty tuples) so a consumer can mirror
+ *   the global-patch lifecycle (e.g. log that capture is engaged). They earn their place by
+ *   bracketing the process-global side effect a consumer needs to observe.
+ *
+ * Listener isolation is the emitter's (§13): a listener throw routes to the emitter's `error`
+ * handler, never onto this map — so a buggy `capture` listener can never perturb interception (or
+ * the underlying program's own `console.*` call). Declared as a `type` alias (not
+ * `interface extends EventMap`, §4.5): a type-literal satisfies the `EventMap` constraint
+ * structurally, whereas an interface lacks the index signature.
+ */
+export declare type CaptureEventMap = {
+    /** An intercepted `console.*` call — the frozen {@link CapturedMessage}. */
+    readonly capture: readonly [message: CapturedMessage];
+    /** Interception was installed (an inactive capture's `start()`). */
+    readonly start: readonly [];
+    /** Interception was torn down (an active capture's `stop()` / `destroy()`). */
+    readonly stop: readonly [];
+};
+
+/**
+ * An observable console interceptor (AGENTS §13) — it takes control of the global `console.*` on
+ * the READ side: while `active`, every configured `console.x` call is captured as a frozen
+ * {@link CapturedMessage}, buffered (total + by level, bounded), emitted on `capture`, and —
+ * per options — mirrored to the real console and/or forwarded to a {@link SinkInterface}.
+ *
+ * @remarks
+ * - **Snapshot-at-start.** `start()` snapshots the CURRENT `console[level]` for each configured
+ *   {@link CaptureLevel}, then installs the wrappers. The mirror writes through that snapshot, so
+ *   our OWN console sink output (the Logger / Reporter, which snapshot the real `console` at
+ *   creation) is never recaptured — `Capture` catches THIRD-PARTY `console.*`, not our writes
+ *   (the no-capture-loop principle). Create your loggers BEFORE installing a capture.
+ * - **Idempotent + non-reentrant.** `start()` while already `active` is a no-op (it never
+ *   double-patches), and `stop()` while inactive is a no-op. It is PROCESS-GLOBAL — it patches the
+ *   one global `console` — so at most ONE capture may be active at a time; running two
+ *   concurrently interleaves their buffers and clobbers each other's restore.
+ * - **Bounded buffers.** `messages()` returns a copy of the whole buffer (oldest first);
+ *   `messages(level)` a copy of one {@link CaptureLevel}'s bucket — each capped at `limit`
+ *   (oldest dropped first), never unbounded. `clear()` empties them (it does NOT stop interception).
+ * - **Lifecycle (§10).** `start` / `stop` toggle interception; `destroy()` stops (restoring
+ *   `console`) then destroys the emitter (its listeners go).
+ */
+export declare interface CaptureInterface {
+    readonly emitter: EmitterInterface<CaptureEventMap>;
+    /** Whether interception is currently installed (between `start()` and `stop()`). */
+    readonly active: boolean;
+    /** Snapshot the configured `console.*` and install the interceptors — a no-op when already `active`. */
+    start(): void;
+    /** Restore the snapshot-original `console.*` — a no-op when not `active`. */
+    stop(): void;
+    /** A copy of the whole captured buffer, oldest first (capped at `limit`). */
+    messages(): readonly CapturedMessage[];
+    /** A copy of the captured buffer for ONE {@link CaptureLevel}, oldest first (capped at `limit`). */
+    messages(level: CaptureLevel): readonly CapturedMessage[];
+    /** Drop every buffered message (total + by level); does NOT stop interception. */
+    clear(): void;
+    /** Tear down — `stop()` (restoring `console`) then destroy the emitter. */
+    destroy(): void;
+}
+
+/**
+ * One intercepted `console` method — the names a {@link CaptureInterface} patches and reports
+ * under. A fixed set keyed off the universal `console.*` methods (`console.log` / `info` / `warn`
+ * / `error` / `debug`); a named value family (it indexes {@link CAPTURE_LEVEL_MAP} to a
+ * {@link LogLevel} for the optional sink forward), never a binary toggle — so it stays a union.
+ *
+ * @remarks
+ * DISTINCT from {@link LogLevel}: a `CaptureLevel` names the ORIGINATING console method (which
+ * `console.x` was called), not a severity threshold — there is no ordering and no gating (every
+ * configured method is captured). `log` and `info` are separate methods (both default-stream),
+ * mapped to the sink's default / `info` stream respectively; `warn` / `error` / `debug` map to
+ * their matching {@link LogLevel}. The default configured set is {@link DEFAULT_CAPTURE_LEVELS}.
+ */
+export declare type CaptureLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+
+/**
+ * Options for `createCapture` / the {@link CaptureInterface} constructor.
+ *
+ * @remarks
+ * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the
+ *   {@link CaptureEventMap}, wired at construction (e.g. `{ capture: (m) => tee(m) }`).
+ * - `error` — the emitter's listener-error handler (§13); a listener throw routes here.
+ * - `levels` — which `console.*` methods to intercept; defaults to {@link DEFAULT_CAPTURE_LEVELS}
+ *   (all five). Only the listed methods are patched — an unlisted method is left untouched and
+ *   its calls pass through normally.
+ * - `mirror` — when `true`, each intercepted call is ALSO forwarded to the snapshot-original
+ *   `console` method, so the program's own console output still appears while being captured;
+ *   defaults to `false` (capture silently). Mirrors through the method snapshotted AT `start()`,
+ *   never the live (re-patched) one — no echo loop.
+ * - `sink` — an optional {@link SinkInterface} each intercepted call is also written to
+ *   (`sink.write(text, level)` with the {@link CaptureLevel} mapped to a {@link LogLevel} via
+ *   {@link CAPTURE_LEVEL_MAP}), to tee captured output into the logging pipeline / a file. Absent
+ *   ⇒ no forward.
+ * - `limit` — the bounded buffer cap: at most this many recent messages are retained per buffer
+ *   (the total buffer and EACH by-level bucket; oldest dropped first). Defaults to
+ *   {@link DEFAULT_CAPTURE_LIMIT}; never unbounded (a long capture can't grow without bound — the
+ *   same retention precedent as {@link LoggerInterface}).
+ */
+export declare interface CaptureOptions {
+    readonly on?: EmitterHooks<CaptureEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly levels?: readonly CaptureLevel[];
+    readonly mirror?: boolean;
+    readonly sink?: SinkInterface;
+    readonly limit?: number;
+}
+
+/**
+ * The structured outcome of {@link import('./factories.js').withCapture} — the wrapped function's
+ * own return `value` plus the {@link CapturedMessage}s intercepted while it ran.
+ *
+ * @remarks
+ * - `value` — whatever the wrapped `fn` returned (its `T`).
+ * - `messages` — the buffer captured during the run, oldest first (a copy; the capture is stopped
+ *   and discarded by the time this is returned).
+ */
+export declare interface CaptureResult<T> {
+    readonly value: T;
+    readonly messages: readonly CapturedMessage[];
+}
+
+/**
+ * The cell at `index` of a (possibly ragged) row — `''` when the row is shorter than the
+ * column count, so a short row pads out instead of throwing (the ragged-row guard
+ * {@link renderTable} reads every cell through).
+ *
+ * @param row - The row's cells
+ * @param index - The column index to read
+ * @returns The cell text, or `''` when the row has no cell at `index`
+ */
+export declare function cellAt(row: readonly string[], index: number): string;
+
+/**
+ * A named terminal color — the 8 standard base colors, their 8 bright variants, and
+ * `default` (the target's own default ink, emitting no color code).
+ *
+ * @remarks
+ * Style as DATA: a `Color` is a name, not an escape sequence. The renderer maps it to
+ * its target's codes — the ANSI renderer to SGR 30–37 / 90–97 (foreground) and 40–47 /
+ * 100–107 (background); a browser renderer maps the SAME names to CSS colors.
+ * `default` means "leave the target's default" and contributes no code.
+ */
+export declare type Color = 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white' | 'brightBlack' | 'brightRed' | 'brightGreen' | 'brightYellow' | 'brightBlue' | 'brightMagenta' | 'brightCyan' | 'brightWhite' | 'default';
+
+/**
+ * Every named {@link Color} except `default`, frozen — the colors the styler exposes as
+ * chainable accessors. The source of truth for the color axis; the styler drives its
+ * accessors from this array so the literals live in one place.
+ */
+export declare const COLORS: readonly Exclude<Color, 'default'>[];
+
+/**
+ * One column of a {@link TableOptions} — its header label and how its cells align.
+ *
+ * @remarks
+ * - `label` — the header text shown in the table's first row.
+ * - `align` — how this column's header and cells align within the column width; defaults to
+ *   {@link DEFAULT_ALIGN} (`left`). The column is sized to the widest VISIBLE content
+ *   (header or any cell, measured by {@link import('./helpers.js').width}), so a styled cell
+ *   never breaks the column.
+ */
+export declare interface ColumnSpec {
+    readonly label: string;
+    readonly align?: Alignment;
+}
+
+/**
+ * An error thrown by the console layer.
+ *
+ * @remarks
+ * Carries a {@link ConsoleErrorCode} and an optional `context` bag. Thrown for: an
+ * internal invariant violated at a defensive, structurally-unreachable guard
+ * (`INVARIANT`) — the one throw site in this codebase today.
+ */
+export declare class ConsoleError extends Error {
+    readonly code: ConsoleErrorCode;
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(code: ConsoleErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * A machine-readable error code for a {@link import('./errors.js').ConsoleError}.
+ *
+ * @remarks
+ * `INVARIANT` — an internal invariant / unreachable-guard was violated (a defensive
+ * check that should be structurally impossible to trip). The sole code today; §21
+ * forbids speculating a richer taxonomy before a second throw site exists.
+ */
+export declare type ConsoleErrorCode = 'INVARIANT';
+
+export declare type ConsoleMethod = (...args: unknown[]) => void;
+
+/**
+ * Matches every C0 control character EXCEPT `\t` / `\n` / `\r` (which are meaningful
+ * whitespace), plus DEL (`0x7F`) — the non-printing bytes {@link
+ * import('./helpers.js').stripControls} removes. Global, ASCII-only source (no raw
+ * control-character literal), so a scan builds a fresh `RegExp` the same way as
+ * {@link ANSI_PATTERN} to avoid a mutated `lastIndex`.
+ *
+ * @remarks
+ * Deliberately SEPARATE from {@link ANSI_PATTERN}: `strip()` must stay pure ANSI-escape
+ * removal (width / alignment computations depend on it leaving raw C0 bytes alone), while
+ * C0-stripping is an ADDITIONAL, orthogonal pass a non-TTY output sink applies on top.
+ */
+export declare const CONTROL_PATTERN: RegExp;
+
+/**
+ * Create the cross-environment default {@link RendererInterface} — the ANSI / SGR
+ * renderer that turns style DATA into terminal escape codes. The default behind
+ * {@link createStyler}; construct one directly to render a {@link import('./types.js').Style}
+ * without the fluent surface, or to share one instance across stylers.
+ *
+ * @returns A stateless ANSI {@link RendererInterface}
+ *
+ * @example
+ * ```ts
+ * import { createANSIRenderer } from '@src/core'
+ *
+ * const renderer = createANSIRenderer()
+ * renderer.render({ foreground: 'red', attributes: ['bold'] }, 'alert') // '\x1b[1;31malert\x1b[0m'
+ * ```
+ */
+export declare function createANSIRenderer(): RendererInterface;
+
+/**
+ * Create an observable {@link CaptureInterface} — console interception on the READ side. While
+ * `active`, every configured `console.*` call is captured as a frozen
+ * {@link import('./types.js').CapturedMessage}, buffered (total + by level, bounded), emitted on
+ * `capture`, and — per options — mirrored to the real console and/or forwarded to a
+ * {@link SinkInterface}.
+ *
+ * @param options - See {@link CaptureOptions}
+ * @returns A {@link CaptureInterface} (inactive until `start()`)
+ *
+ * @remarks
+ * - **Snapshot-at-start — no capture loop.** `start()` snapshots the CURRENT `console[level]` per
+ *   configured level, then patches; the mirror writes through that snapshot. Our OWN console sink
+ *   output (the Logger / Reporter, which snapshot `console` at creation) is never recaptured —
+ *   `Capture` catches THIRD-PARTY `console.*`, not our writes. Create your loggers FIRST.
+ * - **PROCESS-GLOBAL + NON-REENTRANT.** It patches the one global `console`, so at most ONE
+ *   capture may be active at a time; two concurrent captures interleave and clobber each other's
+ *   restore. Prefer {@link withCapture} for a scoped, self-restoring capture.
+ * - **Bounded.** `options.limit` (default {@link import('./constants.js').DEFAULT_CAPTURE_LIMIT})
+ *   caps both the total buffer and each by-level bucket; never unbounded.
+ *
+ * @example
+ * ```ts
+ * import { createCapture } from '@src/core'
+ *
+ * const capture = createCapture({ levels: ['warn', 'error'] })
+ * capture.start()
+ * console.error('boom') // captured, NOT mirrored (mirror defaults to false)
+ * capture.messages('error') // [{ level: 'error', text: 'boom', time: … }]
+ * capture.stop()
+ * ```
+ */
+export declare function createCapture(options?: CaptureOptions): CaptureInterface;
+
+/**
+ * Create the default {@link SinkInterface} — a console sink that routes by level and writes
+ * through the `console` methods SNAPSHOTTED at creation. The default output target behind
+ * {@link createLogger}.
+ *
+ * @returns A console {@link SinkInterface}
+ *
+ * @remarks
+ * - **Snapshotted — no capture loop.** It captures `console.log` / `console.warn` /
+ *   `console.error` AT CALL TIME and writes through those references. So when a later
+ *   `Capture` (C-d) PATCHES `console.*`, this sink still reaches the REAL streams — the
+ *   writer and the capturer never feed each other (the no-capture-loop principle). Create
+ *   the sink (or the logger) BEFORE installing a capture for this to hold.
+ * - **Routes by level.** `error` → the snapshotted `console.error`, `warn` →
+ *   `console.warn`, every other level → `console.log`. The `level` is supplied by the
+ *   logger; an omitted `level` goes to `console.log`.
+ *
+ * @example
+ * ```ts
+ * import { createConsoleSink } from '@src/core'
+ *
+ * const sink = createConsoleSink() // snapshots console.* now
+ * sink.write('boom', 'error') // → the real console.error, even after a later console patch
+ * ```
+ */
+export declare function createConsoleSink(): SinkInterface;
+
+/**
+ * Create an observable, leveled {@link LoggerInterface} — the entry point into structured
+ * logging. Each `debug` / `info` / `warn` / `error` call builds a frozen
+ * {@link import('./types.js').LogRecord}, gates it by severity, retains a bounded tail,
+ * ALWAYS emits it on `entry` (the transport seam), and — unless `silent` — writes a styled
+ * line to its sink.
+ *
+ * @param options - See {@link LoggerOptions}
+ * @returns A {@link LoggerInterface}
+ *
+ * @remarks
+ * - **Record + event = transport (§13).** Subscribe `logger.emitter.on('entry', …)` to tee
+ *   records to a file / JSON / remote transport; the event fires for every accepted record,
+ *   even when `silent` (silence suppresses only the SINK WRITE).
+ * - **Bounded retention.** `entries()` returns the recent records, capped at `options.limit`
+ *   (default {@link DEFAULT_LOG_LIMIT}); never unbounded.
+ * - **Sink + styler defaults.** `options.sink` defaults to {@link createConsoleSink} (the
+ *   snapshotted, level-routing console sink); `options.styler` to {@link createStyler} (ANSI).
+ *   Styling is orthogonal to level — a level only chooses a label color.
+ *
+ * @example
+ * ```ts
+ * import { createLogger } from '@src/core'
+ *
+ * const logger = createLogger({ name: 'http', level: 'info' })
+ * logger.info('request', { method: 'GET', path: '/' })
+ * logger.debug('verbose') // dropped — below the info threshold
+ * ```
+ */
+export declare function createLogger(options?: LoggerOptions): LoggerInterface;
+
+/**
+ * Create an event-free {@link LoggerManagerInterface} — a §9 registry of named loggers plus
+ * a convenience fan-out. It mints + stores {@link LoggerInterface}s keyed by name (its
+ * defaults flowing into each), looks them up, removes them, and broadcasts a one-off log to
+ * every registered logger.
+ *
+ * @param options - See {@link LoggerManagerOptions}
+ * @returns A {@link LoggerManagerInterface}
+ *
+ * @remarks
+ * - **Defaults flow in.** `options.level` / `sink` / `styler` / `limit` / `silent` are the
+ *   defaults flowed into every `register`ed logger unless that call's options override them.
+ * - **Event-free.** The manager carries NO emitter (each registered logger owns its own
+ *   observable `emitter`) — it is a pure registry.
+ *
+ * @example
+ * ```ts
+ * import { createLoggerManager } from '@src/core'
+ *
+ * const loggers = createLoggerManager({ level: 'warn' })
+ * loggers.register('http')
+ * loggers.register('db', { level: 'debug' }) // overrides the default
+ * loggers.warn('slow', { ms: 900 }) // fans out to both
+ * ```
+ */
+export declare function createLoggerManager(options?: LoggerManagerOptions): LoggerManagerInterface;
+
+/**
+ * Create an update-driven, observable {@link ProgressInterface} — a live progress bar. Each
+ * `update(current)` recomputes the bar, writes `\r` + bar to its sink, and emits `{ current, total }`
+ * on `update`; `complete` / `failure` commit a final line. The leading `\r` is the sink's to redraw on —
+ * a TTY sink (C-g) overwrites, a plain sink (C-f) degrades to a fresh line. NO self-timer — the caller
+ * drives the bar.
+ *
+ * @param options - See {@link ProgressOptions} (`total` is required)
+ * @returns A {@link ProgressInterface}
+ *
+ * @remarks
+ * - **Universal + update-driven.** Built on the one styler + the one sink (no `node:*`, no
+ *   `process.stdout`); progress advances only when the caller reports it. `current` is always clamped
+ *   to `[0, total]`. `options.sink` defaults to {@link createConsoleSink}, `options.styler` to
+ *   {@link createStyler} (ANSI).
+ * - **Observable (§13).** Subscribe `progress.emitter.on('update', …)` to mirror progress without a
+ *   terminal; `complete` signals a successful finish.
+ *
+ * @example
+ * ```ts
+ * import { createProgress } from '@src/core'
+ *
+ * const progress = createProgress({ total: 100, message: 'downloading' })
+ * progress.update(40)
+ * progress.complete('done')
+ * ```
+ */
+export declare function createProgress(options: ProgressOptions): ProgressInterface;
+
+/**
+ * Create a lean, event-free {@link ReporterInterface} — the entry point into narrative
+ * reporting. Each verb (`section` / `step` / `timing` / `status` / `table` / `tree` / `box` /
+ * `line` / `blank`) formats through the shared styler + the pure layout renderers and writes to
+ * the sink — human / build-run narration over the SAME substrate the logger uses.
+ *
+ * @param options - See {@link ReporterOptions}
+ * @returns A {@link ReporterInterface}
+ *
+ * @remarks
+ * - **One styler, one sink.** `options.styler` defaults to {@link createStyler} (ANSI) and
+ *   `options.sink` to {@link createConsoleSink} (the snapshotted, level-routing console sink) —
+ *   no second colorizer. A `status('error', …)` routes to the sink's error stream.
+ * - **Width-aware.** `options.width` (default {@link DEFAULT_WIDTH}) sizes `section` and a
+ *   `box` with no explicit width; the renderers align on VISIBLE width so styled content keeps
+ *   its columns.
+ * - **Event-free (§13).** The reporter carries no emitter — a pure formatting front-end, like
+ *   the renderers and `Scheduler`. Reach for a {@link createLogger} when you need observable,
+ *   leveled, transportable records instead.
+ *
+ * @example
+ * ```ts
+ * import { createReporter } from '@src/core'
+ *
+ * const reporter = createReporter()
+ * reporter.section('Build')
+ * reporter.step('bundling', { index: 2, total: 5 }) // [2/5] bundling
+ * reporter.status('success', 'built in 1.2s') // ✔ built in 1.2s
+ *
+ * // Disable color (a non-TTY) — every line is plain.
+ * const plain = createReporter({ styler: createStyler({ enabled: false }) })
+ * ```
+ */
+export declare function createReporter(options?: ReporterOptions): ReporterInterface;
+
+/**
+ * Create a self-driving, observable {@link SpinnerInterface} — a live activity spinner. `start()`
+ * arms a periodic timer that advances a glyph cycle, writing each `\r` + frame line to its sink and
+ * emitting it on `frame`; `success` / `failure` commit a final `✔` / `✖` line. The leading `\r` is the
+ * sink's to redraw on — a TTY sink (C-g) overwrites for a smooth animation, a plain sink (C-f)
+ * degrades to a fresh line.
+ *
+ * @param options - See {@link SpinnerOptions}
+ * @returns A {@link SpinnerInterface} (inactive until `start()`)
+ *
+ * @remarks
+ * - **Universal + leak-free.** Built on `setInterval` + the one styler + the one sink (no `node:*`,
+ *   no `process.stdout`); the timer is ALWAYS cleared on `success` / `failure` / `stop` / `destroy`, so
+ *   it never leaks. `start()` is idempotent (no second timer while `active`).
+ * - **Observable (§13).** Subscribe `spinner.emitter.on('frame', …)` to mirror the animation without
+ *   a terminal; `start` / `stop` bracket the timer lifecycle. `options.sink` defaults to
+ *   {@link createConsoleSink}, `options.styler` to {@link createStyler} (ANSI).
+ *
+ * @example
+ * ```ts
+ * import { createSpinner } from '@src/core'
+ *
+ * const spinner = createSpinner({ message: 'building' })
+ * spinner.start()
+ * spinner.success('built in 1.2s') // ✔ built in 1.2s — timer cleared, line committed
+ * ```
+ */
+export declare function createSpinner(options?: SpinnerOptions): SpinnerInterface;
+
+/**
+ * Create the fluent, composable {@link StylerInterface} — the consumer-facing styling
+ * API. It builds a {@link import('./types.js').Style} under the hood and renders it
+ * through a {@link RendererInterface} (the ANSI default), so `styler.red.bold('hi')`
+ * yields styled text. Chains are immutable, so a base styler is freely reusable.
+ *
+ * @param options - See {@link StylerOptions}
+ * @returns A base {@link StylerInterface}
+ *
+ * @remarks
+ * - `options.renderer` swaps the output target without touching the style model — pass a
+ *   browser `%c` / CSS renderer (the C-f branch) to retarget; defaults to the ANSI
+ *   renderer (the cross-environment default).
+ * - `options.enabled` is the no-color switch: when `false`, the styler returns text
+ *   VERBATIM (for a non-TTY, `NO_COLOR`, or piped output); defaults to `true`.
+ *
+ * @example
+ * ```ts
+ * import { createStyler } from '@src/core'
+ *
+ * const style = createStyler()
+ * style.red.bold('error') // bold red
+ * style.red(style.underline('link')) // composes either way
+ *
+ * // Disable for a non-TTY — every call returns its text unchanged.
+ * const plain = createStyler({ enabled: false })
+ * plain.green('ok') // 'ok'
+ * ```
+ */
+export declare function createStyler(options?: StylerOptions): StylerInterface;
+
+/** The Control Sequence Introducer (`ESC[`) that opens every SGR sequence. */
+export declare const CSI: string;
+
+/** The default cell {@link Alignment} a {@link import('./types.js').ColumnSpec} uses when none is given — `left`. */
+export declare const DEFAULT_ALIGN: Alignment;
+
+/**
+ * The default visible cell count of a progress-bar TRACK — the glyph run {@link
+ * import('./helpers.js').renderBar} fills (and a {@link import('./types.js').ProgressInterface} sizes
+ * its bar to). Thirty cells is a compact, terminal-friendly default; a consumer overrides it via
+ * `options.width`. Distinct from {@link DEFAULT_WIDTH} (the renderers' 80-column line width) — a bar
+ * track is one inline element, not a full-width rule.
+ */
+export declare const DEFAULT_BAR_WIDTH = 30;
+
+/** The default {@link BorderStyle} the box / table renderers frame with when none is given — `single`. */
+export declare const DEFAULT_BORDER: BorderStyle;
+
+/**
+ * The default set of {@link CaptureLevel}s a Capture patches when `options.levels` is omitted —
+ * all five universal `console.*` methods ({@link CAPTURE_LEVELS}). A consumer narrows it (e.g. just
+ * `['warn', 'error']`) via `options.levels`.
+ */
+export declare const DEFAULT_CAPTURE_LEVELS: readonly CaptureLevel[];
+
+/**
+ * The default bounded-buffer cap for a {@link import('./types.js').CaptureInterface} — at most this
+ * many recent {@link CapturedMessage}s are retained per buffer (the total buffer AND each by-level
+ * bucket; oldest dropped first). Capture retention is ALWAYS bounded so a long-running capture can
+ * never grow without bound (the same retention precedent as {@link DEFAULT_LOG_LIMIT}); a consumer
+ * overrides it via `options.limit`.
+ */
+export declare const DEFAULT_CAPTURE_LIMIT = 1000;
+
+/** The default {@link LogLevel} threshold a logger gates at when none is supplied — `info`. */
+export declare const DEFAULT_LOG_LEVEL: LogLevel;
+
+/**
+ * The default bounded-retention cap for a {@link import('./types.js').LoggerInterface} — at
+ * most this many recent records are kept (oldest dropped first). Retention is ALWAYS bounded
+ * (never the unbounded buffer scsr leaked); a consumer overrides it via `options.limit`.
+ */
+export declare const DEFAULT_LOG_LIMIT = 1000;
+
+/** The default horizontal padding inside a box's edges ({@link import('./helpers.js').renderBox}) — one cell. */
+export declare const DEFAULT_PADDING = 1;
+
+/**
+ * The default timer period in milliseconds between a {@link import('./types.js').SpinnerInterface}'s
+ * frames — the `setInterval` interval `start()` arms. Eighty milliseconds (≈12.5 frames/second) is
+ * the conventional spinner cadence: fast enough to read as motion, slow enough not to thrash a
+ * terminal. A consumer overrides it via `options.interval`.
+ */
+export declare const DEFAULT_SPINNER_INTERVAL = 80;
+
+/**
+ * The default visible column width for the width-aware renderers — the separator rule and a
+ * {@link import('./helpers.js').renderBox} with no explicit `width`, and the reporter's
+ * `section` rule. A sane terminal default (80 columns); a caller overrides it per-call or via
+ * {@link import('./types.js').ReporterOptions}`.width`.
+ */
+export declare const DEFAULT_WIDTH = 80;
+
+/**
+ * The EMPTY {@link Style} — no foreground, no background, no attributes — frozen. The
+ * neutral starting point a base styler builds from, and what a renderer passes through
+ * unchanged (it carries no codes). Deeply frozen, so it is safe to share as the base.
+ */
+export declare const EMPTY_STYLE: Style;
+
+/**
+ * The ESC control character (`U+001B`) that begins every ANSI escape sequence. Built
+ * with `String.fromCharCode` so no raw control character appears in source.
+ */
+export declare const ESC: string;
+
+/**
+ * Each {@link Color}'s SGR FOREGROUND parameter — the 8 base colors at 30–37 and their
+ * bright variants at 90–97. `default` is intentionally absent (it emits no code).
+ */
+export declare const FOREGROUND_CODES: Readonly<Record<Exclude<Color, 'default'>, number>>;
+
+/**
+ * Stringify a captured `console.*` argument list into ONE line — the text of a {@link
+ * import('./types.js').CapturedMessage}. Each argument is rendered by {@link stringifyValue} and
+ * the parts are space-joined, mirroring how a console concatenates its arguments.
+ *
+ * @remarks
+ * Total and never throws (it composes {@link stringifyValue}, which is total) — a `Capture` builds
+ * every message through this, so intercepting `console.*` can never crash the underlying program.
+ * An empty argument list yields `''` (an empty `console.log()` is captured as a blank line).
+ *
+ * @param args - The arguments a `console.*` method was called with
+ * @returns The arguments stringified and space-joined into one line
+ *
+ * @example
+ * ```ts
+ * formatArgs(['count', 3, { ok: true }]) // 'count 3 {"ok":true}'
+ * formatArgs([]) // ''
+ * ```
+ */
+export declare function formatArgs(args: readonly unknown[]): string;
+
+/**
+ * Format a millisecond duration as a compact human string — `…ms` below one second, `…s`
+ * (seconds to 2 decimal places) at or above one second. The timing rendering behind
+ * {@link import('./types.js').ReporterInterface.timing}.
+ *
+ * @remarks
+ * `999 → '999ms'`, `1000 → '1.00s'`, `1230 → '1.23s'` (the threshold is {@link SECOND_MS}).
+ * Pure and deterministic; kept a shared helper so the layout and the reporter stay decoupled.
+ *
+ * @param ms - The duration in milliseconds
+ * @returns The formatted duration (`'<n>ms'` or `'<n>s'`)
+ */
+export declare function formatDuration(ms: number): string;
+
+/**
+ * Format a {@link LogRecord} into a single styled line — the default human line layout a
+ * {@link import('./types.js').LoggerInterface} writes to its sink.
+ *
+ * @remarks
+ * Layout: `{time} {LEVEL} {[name]} {message}{ data}` — the ISO timestamp (dimmed), the
+ * upper-cased level label (colored by {@link LEVEL_COLORS} — styling ORTHOGONAL to level),
+ * the originating logger's `name` in brackets (omitted when absent), the message, and the
+ * structured `data` appended as compact JSON (omitted when absent / empty). Coloring flows
+ * through the injected `styler`, so a disabled styler yields a plain line and a browser
+ * `%c` styler (C-f) retargets it — the layout never changes. Pure: same record + styler →
+ * same line.
+ *
+ * @param record - The {@link LogRecord} to render
+ * @param styler - The {@link StylerInterface} the labels are colored through
+ * @returns The formatted, styled line (no trailing newline — the sink's target adds it)
+ *
+ * @example
+ * ```ts
+ * formatRecord({ level: 'warn', message: 'low disk', time: 0, name: 'fs' }, createStyler())
+ * // '<dim>1970-01-01T00:00:00.000Z</> <yellow>WARN</> [fs] low disk'
+ * ```
+ */
+export declare function formatRecord(record: LogRecord, styler: StylerInterface): string;
+
+/**
+ * Format a {@link LogRecord}'s `time` (epoch milliseconds) as an ISO-8601 timestamp string.
+ *
+ * @remarks
+ * Deterministic and serializable — `new Date(time).toISOString()`, e.g.
+ * `1716900000000 → '2024-05-28T12:40:00.000Z'`. The timestamp portion of the formatted log
+ * line; kept a pure helper so the line layout and the logger stay decoupled.
+ *
+ * @param time - Epoch milliseconds (a record's `time`)
+ * @returns The ISO-8601 timestamp
+ */
+export declare function formatTime(time: number): string;
+
+/**
+ * Narrow an unknown caught value to a {@link ConsoleError}.
+ *
+ * @param value - The value to test (typically a `catch` binding)
+ * @returns `true` when `value` is a {@link ConsoleError}
+ *
+ * @example
+ * ```ts
+ * try {
+ * 	createStyler().style
+ * } catch (error) {
+ * 	if (isConsoleError(error) && error.code === 'INVARIANT') report(error)
+ * }
+ * ```
+ */
+export declare function isConsoleError(value: unknown): value is ConsoleError;
+
+/**
+ * Each {@link LogLevel}'s default label {@link Color} — the level's VISUAL treatment, which
+ * is a styling choice ORTHOGONAL to the level itself (never a separate pseudo-level). The
+ * logger colors the level label through its styler with these; swapping a color never
+ * changes leveling. `debug` is cyan, `info` blue, `warn` yellow, `error` red.
+ *
+ * @remarks
+ * Excludes `default` so each value indexes a real styler accessor (the styler exposes a
+ * getter per non-`default` {@link Color}) — a level always renders in a concrete color.
+ */
+export declare const LEVEL_COLORS: Readonly<Record<LogLevel, Exclude<Color, 'default'>>>;
+
+/**
+ * Each {@link LogLevel}'s numeric SEVERITY — the ascending order the level gate compares
+ * through (`debug` 0 < `info` 1 < `warn` 2 < `error` 3). A record is kept when its level's
+ * severity is at or above the logger's threshold. The source of truth for level ordering.
+ */
+export declare const LEVEL_SEVERITY: Readonly<Record<LogLevel, number>>;
+
+/**
+ * Every {@link LogLevel}, in ascending severity order — the levels a logger exposes as
+ * methods and the manager fans out to. The source of truth for the level axis (drives
+ * exhaustive tests); aligned with {@link LEVEL_SEVERITY}.
+ */
+export declare const LEVELS: readonly LogLevel[];
+
+/**
+ * An observable, leveled logger (AGENTS §13) — the entry point into the structured-logging
+ * pipeline. Each `debug` / `info` / `warn` / `error` call builds a frozen {@link LogRecord},
+ * gates it by severity, retains a bounded tail of accepted records, ALWAYS emits it on
+ * `entry` (the transport seam), and — unless `silent` — formats it into a styled line and
+ * writes it to its {@link SinkInterface}.
+ *
+ * @remarks
+ * - **Record + event = transport (§13).** An accepted record is frozen and emitted on
+ *   `entry` BEFORE anything else observable — every file / JSON / remote transport rides
+ *   `emitter.on('entry')`. The event fires even when `silent`: silence suppresses only the
+ *   SINK WRITE, never the record or the event, so transports keep flowing.
+ * - **Leveled gate.** A record whose {@link LogLevel} is below the logger's `level` threshold
+ *   is dropped ENTIRELY — no record built past the level check, no event, no retention, no
+ *   write (see {@link meetsLevel}).
+ * - **Bounded retention.** Accepted records accrue in a ring capped at `limit` (default
+ *   {@link DEFAULT_LOG_LIMIT}); the oldest is dropped when full. `entries()` returns a copy,
+ *   oldest first; `clear()` empties it. NEVER unbounded (scsr's leak).
+ * - **Styled write, orthogonal to level.** The line ({@link formatRecord}) is colored through
+ *   the injected `styler` (the ANSI default, or a browser `%c` styler at C-f) — a level only
+ *   chooses a label color; styling is not a level. A disabled styler yields a plain line.
+ * - **Snapshotted sink.** The default {@link createConsoleSink} writes to the `console`
+ *   methods captured at creation, so a later `Capture` patching `console` can't loop the
+ *   sink's output back into itself.
+ *
+ * @example
+ * ```ts
+ * const logger = new Logger({ name: 'http', level: 'info' })
+ * logger.emitter.on('entry', (record) => archive(record)) // transport hook
+ * logger.info('request', { method: 'GET', path: '/' }) // styled line to the console sink
+ * logger.debug('verbose') // dropped — below the `info` threshold
+ * logger.entries() // [the info record]
+ * ```
+ */
+export declare class Logger implements LoggerInterface {
+    #private;
+    constructor(options?: LoggerOptions);
+    get emitter(): EmitterInterface<LoggerEventMap>;
+    get level(): LogLevel;
+    get name(): string | undefined;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    entries(): readonly LogRecord[];
+    clear(): void;
+    destroy(): void;
+}
+
+/**
+ * The observable events a {@link LoggerInterface} emits (AGENTS §13) — the transport seam.
+ *
+ * @remarks
+ * `entry` fires for EVERY accepted record (one that passed the level gate), carrying the
+ * frozen {@link LogRecord} — even when the logger is `silent` (silence suppresses only the
+ * SINK WRITE, never the event, so transports keep receiving records). Listener isolation is
+ * the emitter's (§13): a listener throw routes to the emitter's `error` handler, never onto
+ * this map — so a buggy transport can never perturb logging.
+ *
+ * Declared as a `type` alias (not `interface extends EventMap`, §4.5): a type-literal
+ * satisfies the `EventMap` constraint structurally, whereas an interface lacks the index signature.
+ */
+export declare type LoggerEventMap = {
+    /** A record was logged (passed the level gate) — the frozen {@link LogRecord}. */
+    readonly entry: readonly [record: LogRecord];
+};
+
+/**
+ * An observable, leveled logger — builds a frozen {@link LogRecord} per call, gates it by
+ * severity, retains a bounded tail, emits it on `entry`, and (unless silent) writes a
+ * styled line to its {@link SinkInterface}.
+ *
+ * @remarks
+ * - **Leveled.** Each of `debug` / `info` / `warn` / `error` builds a record at that
+ *   {@link LogLevel}; a record below the logger's `level` threshold is dropped entirely (no
+ *   event, no retention, no write).
+ * - **Transport seam (§13).** An accepted record ALWAYS fires `entry` (even when `silent`),
+ *   carrying the frozen {@link LogRecord} — the hook every file / JSON / remote transport rides.
+ * - **Bounded retention.** `entries()` returns the recent records, capped at `limit` (oldest
+ *   dropped first) — never an unbounded buffer. `clear()` empties it.
+ * - **Styled write.** Unless `silent`, the record is formatted (timestamp + level label +
+ *   `name` + message + trailing `data`) and colored through the injected `styler`, then
+ *   written to `sink`. Styling is orthogonal to level (the level only chooses a color).
+ * - **Lifecycle.** `destroy()` clears retention and destroys the emitter (its listeners go).
+ */
+export declare interface LoggerInterface {
+    readonly emitter: EmitterInterface<LoggerEventMap>;
+    readonly level: LogLevel;
+    readonly name?: string;
+    /** Log at `debug` — dropped unless the logger's `level` is `debug`. */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /** Log at `info`. */
+    info(message: string, data?: Record<string, unknown>): void;
+    /** Log at `warn`. */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /** Log at `error`. */
+    error(message: string, data?: Record<string, unknown>): void;
+    /** The bounded tail of recent {@link LogRecord}s, oldest first (capped at `limit`). */
+    entries(): readonly LogRecord[];
+    /** Drop every retained record (does not touch listeners). */
+    clear(): void;
+    /** Tear down — clear retention and destroy the emitter. */
+    destroy(): void;
+}
+
+/**
+ * An event-free registry of named {@link Logger}s plus a convenience fan-out — the §9
+ * manager over the logging layer (a registry, never observable itself; each {@link Logger}
+ * owns its own `emitter`).
+ *
+ * @remarks
+ * - **Registry (§9).** Loggers live in an insertion-ordered `Map` keyed by `name`.
+ *   `register(name, options?)` mints a {@link Logger} named `name` — the manager's default
+ *   `level` / `sink` / `styler` / `limit` / `silent` flow in unless `options` OVERRIDES them
+ *   (`name` is always the registry key, so any `options.name` is ignored) — stores it (a
+ *   re-`register` of the same name OVERWRITES, last write wins), and returns it. `count` is
+ *   the map size, `logger(name)` looks one up, `loggers()` lists them in insertion order.
+ * - **Removal (§9.2).** `remove()` clears ALL, `remove(name)` drops ONE (`true` if present),
+ *   `remove(names)` drops a batch (`true` if any was removed). `clear()` empties the registry.
+ *   (Removal does NOT `destroy` the returned loggers — a caller still holding one keeps using
+ *   it; the manager simply stops tracking it.)
+ * - **Fan-out.** `debug` / `info` / `warn` / `error(message, data?)` forward the one call to
+ *   EVERY registered logger; each gates / emits / writes per its own `level` and `sink`. A
+ *   fan-out over an empty registry is a no-op.
+ * - **Event-free.** No emitter, no events — the manager is a pure registry; observability is
+ *   per-{@link Logger}.
+ *
+ * @example
+ * ```ts
+ * const manager = new LoggerManager({ level: 'warn' })
+ * manager.register('http') // inherits the `warn` default
+ * manager.register('db', { level: 'debug' }) // overrides to `debug`
+ * manager.warn('slow', { ms: 900 }) // fans out to both loggers
+ * manager.count // 2
+ * ```
+ */
+export declare class LoggerManager implements LoggerManagerInterface {
+    #private;
+    constructor(options?: LoggerManagerOptions);
+    get count(): number;
+    register(name: string, options?: LoggerOptions): LoggerInterface;
+    logger(name: string): LoggerInterface | undefined;
+    loggers(): readonly LoggerInterface[];
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    remove(names: readonly string[]): boolean;
+    remove(name: string): boolean;
+    remove(): void;
+    clear(): void;
+}
+
+/**
+ * An event-free registry of named {@link LoggerInterface}s plus a convenience fan-out — the
+ * §9 manager over the logging layer. It mints + stores loggers keyed by `name`, looks them
+ * up, removes them, and broadcasts a one-off log to EVERY registered logger.
+ *
+ * @remarks
+ * - **Registry (§9).** `register(name, options?)` mints a {@link LoggerInterface} (named
+ *   `name`, the manager's defaults flowing in unless `options` overrides them), stores it
+ *   (a re-`register` of the same name OVERWRITES — last write wins), and returns it.
+ *   `logger(name)` looks one up; `loggers()` lists them in insertion order; `count` is the size.
+ * - **Removal (§9.2).** `remove()` clears ALL, `remove(name)` drops ONE, `remove(names)` drops
+ *   a batch (`true` when any was removed). `clear()` empties the registry.
+ * - **Fan-out.** `debug` / `info` / `warn` / `error(message, data?)` forward the call to every
+ *   registered logger (each gates / emits / writes per its own `level` and `sink`).
+ * - **Event-free.** No emitter, no events — each logger carries its own observability; the
+ *   manager is a pure registry.
+ */
+export declare interface LoggerManagerInterface {
+    readonly count: number;
+    register(name: string, options?: LoggerOptions): LoggerInterface;
+    logger(name: string): LoggerInterface | undefined;
+    loggers(): readonly LoggerInterface[];
+    /** Fan out a `debug` log to every registered logger. */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /** Fan out an `info` log to every registered logger. */
+    info(message: string, data?: Record<string, unknown>): void;
+    /** Fan out a `warn` log to every registered logger. */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /** Fan out an `error` log to every registered logger. */
+    error(message: string, data?: Record<string, unknown>): void;
+    remove(): void;
+    remove(name: string): boolean;
+    remove(names: readonly string[]): boolean;
+    clear(): void;
+}
+
+/**
+ * Options for `createLoggerManager` / the {@link LoggerManagerInterface} constructor.
+ *
+ * @remarks
+ * The manager is an event-free registry (§9) — it carries NO emitter of its own (each
+ * registered {@link LoggerInterface} owns its observable `emitter`). These options supply
+ * the DEFAULTS flowed into every logger the manager mints, unless a per-`register` override
+ * wins: `level` (default threshold), `sink` (shared output target), `styler` (shared
+ * coloring), `limit` (retention cap), and `silent`.
+ */
+export declare interface LoggerManagerOptions {
+    readonly level?: LogLevel;
+    readonly sink?: SinkInterface;
+    readonly styler?: StylerInterface;
+    readonly limit?: number;
+    readonly silent?: boolean;
+}
+
+/**
+ * Options for `createLogger` / the {@link LoggerInterface} constructor.
+ *
+ * @remarks
+ * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the
+ *   {@link LoggerEventMap}, wired at construction (e.g. `{ entry: (r) => sink2.write(...) }`).
+ * - `error` — the emitter's listener-error handler (§13); a listener throw routes here.
+ * - `level` — the severity THRESHOLD; records below it are dropped. Defaults to `info`.
+ * - `name` — the logger's name, stamped onto every {@link LogRecord} (`record.name`) and
+ *   shown in the formatted line. A manager registers each logger under its name.
+ * - `sink` — where formatted lines are written; defaults to
+ *   {@link import('./factories.js').createConsoleSink} (the snapshotted-console sink).
+ * - `styler` — the {@link StylerInterface} the line is colored through; defaults to
+ *   {@link import('./factories.js').createStyler} (ANSI). Styling is orthogonal to level.
+ * - `limit` — the bounded retention cap: at most this many recent records are kept
+ *   (oldest dropped first). Defaults to {@link DEFAULT_LOG_LIMIT}; never unbounded.
+ * - `silent` — when `true`, suppresses the SINK WRITE only; `entry` still fires and the
+ *   record is still retained. Defaults to `false`.
+ */
+export declare interface LoggerOptions {
+    readonly on?: EmitterHooks<LoggerEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly level?: LogLevel;
+    readonly name?: string;
+    readonly sink?: SinkInterface;
+    readonly styler?: StylerInterface;
+    readonly limit?: number;
+    readonly silent?: boolean;
+}
+
+/**
+ * The severity level of a {@link LogRecord} — one coherent, ascending-severity scale.
+ *
+ * @remarks
+ * Ordered least-to-most severe: `debug` < `info` < `warn` < `error`. A {@link LoggerInterface}
+ * gates by THRESHOLD — a record at or above the logger's `level` is kept (and written),
+ * one below it is dropped (see {@link LEVEL_SEVERITY} for the numeric order). A level is a
+ * level — its visual treatment (color) is a separate styling concern, NEVER a pseudo-level
+ * like `success` / `ready`.
+ */
+export declare type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * One immutable, serializable log entry — the universal record the whole logging system
+ * carries. A {@link LoggerInterface} builds one per call, freezes it, retains a bounded
+ * tail of them, and emits it on `entry`; every sink / transport consumes this exact shape.
+ *
+ * @remarks
+ * - `level` — the record's {@link LogLevel}.
+ * - `message` — the human message text.
+ * - `time` — the creation instant as epoch milliseconds (`Date.now()`); a plain number so
+ *   the record stays serializable (no `Date` to clone) and orderable.
+ * - `name` — the originating logger's `name`, when it has one (a manager-registered logger
+ *   is keyed by name; an anonymous logger omits it).
+ * - `data` — optional structured context (a flat `Record<string, unknown>`), absent when
+ *   no context was supplied. The top-level object is a FROZEN COPY taken at log time (a
+ *   later mutation of the caller's original object never reaches the retained record);
+ *   nested values remain BY REFERENCE (only the top level is copied + frozen).
+ * - The value is frozen at construction — a consumer reads it, never mutates it.
+ */
+export declare interface LogRecord {
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly time: number;
+    readonly name?: string;
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Whether a record at `level` passes a logger gated at `threshold` — i.e. its severity is
+ * at or above the threshold's.
+ *
+ * @remarks
+ * The level gate (AGENTS §5 — the comparison lives here, not inlined in the logger). Reads
+ * the ascending {@link LEVEL_SEVERITY} order: `meetsLevel('warn', 'error')` is `true`
+ * (error ≥ warn), `meetsLevel('warn', 'info')` is `false` (info < warn).
+ *
+ * @param threshold - The logger's configured minimum {@link LogLevel}
+ * @param level - The record's {@link LogLevel}
+ * @returns `true` when `level` is at least as severe as `threshold`
+ *
+ * @example
+ * ```ts
+ * meetsLevel('info', 'error') // true
+ * meetsLevel('error', 'warn') // false
+ * ```
+ */
+export declare function meetsLevel(threshold: LogLevel, level: LogLevel): boolean;
+
+/**
+ * Color `text` through `styler`, or return it verbatim when `styler` is `undefined` — the
+ * single optional-styling primitive every renderer applies to its border / title / connector
+ * glyphs (AGENTS §5 — the ONE styler seam, shared, never re-hand-rolled per renderer).
+ *
+ * @remarks
+ * The renderers all take an OPTIONAL `styler`: present ⇒ glyphs are colored, absent ⇒ plain.
+ * Folding that `styler === undefined ? text : styler(text)` ternary into one exported helper
+ * keeps the renderers terse and the styling decision in one tested place. A disabled styler
+ * (`enabled: false`) is still a styler — it returns its text verbatim — so passing one paints
+ * a no-op, exactly as omitting it does.
+ *
+ * @param styler - The {@link StylerInterface} to color with, or `undefined` for no styling
+ * @param text - The glyphs / text to color
+ * @returns `styler(text)` when a styler is given, else `text` unchanged
+ */
+export declare function paint(styler: StylerInterface | undefined, text: string): string;
+
+/**
+ * An update-driven, observable progress bar (AGENTS §13) — {@link update} recomputes the bar via
+ * {@link renderBar}, writes `\r` + bar to its {@link SinkInterface}, and emits the `{ current, total }`
+ * on `update`. The leading `\r` is what an overwrite-capable sink (the C-g TTY sink) redraws on; a
+ * plain sink (C-f) degrades to a fresh, non-overwriting line — the line-OVERWRITE is the SINK's job.
+ * UNIVERSAL — the one {@link StylerInterface} + the one {@link SinkInterface}, no `node:*`, no
+ * `process.stdout`. NO self-timer (unlike {@link import('./Spinner.js').Spinner}) — the caller drives it.
+ *
+ * @remarks
+ * - **Update-driven.** Each {@link update} clamps `current` to `[0, total]`, renders the bar (filled
+ *   to `current / total`, with the trailing `percent (current/total)` + message) via {@link renderBar},
+ *   emits `update`, and writes `'\r' + bar`. Progress advances only when the caller reports it.
+ * - **Outcome lines.** {@link complete} renders a FULL bar (`current = total`) + message, terminated by
+ *   a newline, emits a final `update` then `complete`, and marks `completed`. {@link failure} renders the
+ *   bar at its CURRENT fill + message + newline and routes to the sink's error stream (no `complete` —
+ *   the work did not finish). Both are terminal: a later {@link update} is ignored once `active` is false.
+ * - **Bounded.** `current` is always clamped to `[0, total]`; {@link completed} reports whether
+ *   {@link complete} has run; {@link active} is `true` until a {@link complete} / {@link failure}.
+ * - **Lifecycle (§10).** {@link destroy} destroys the emitter (there is no timer to clear).
+ *
+ * @example
+ * ```ts
+ * const progress = new Progress({ total: 100, message: 'downloading' })
+ * progress.update(40) // ████████████░░░░░░░░░░░░░░░░░░ 40% (40/100) downloading
+ * progress.update(80, 'almost there')
+ * progress.complete('done') // a full bar, committed with a newline
+ * ```
+ */
+export declare class Progress implements ProgressInterface {
+    #private;
+    constructor(options: ProgressOptions);
+    get emitter(): EmitterInterface<ProgressEventMap>;
+    get active(): boolean;
+    get completed(): boolean;
+    get current(): number;
+    get total(): number;
+    update(current: number, message?: string): void;
+    complete(message?: string): void;
+    failure(message?: string): void;
+    destroy(): void;
+}
+
+/**
+ * Options for the pure {@link import('./helpers.js').renderBar} renderer — a determinate progress
+ * bar string (`█████░░░░░ 50% (5/10)`), width-aware and styler-optional.
+ *
+ * @remarks
+ * - `current` / `total` — the filled fraction is `current / total`, clamped to `[0, total]` (a
+ *   `current` past `total` renders a full bar, a negative one an empty bar) — so a caller's overrun
+ *   never produces an over-long bar. A `total` of `0` (or below) renders a full bar (nothing to do).
+ * - `width` — the visible cell count of the bar TRACK (the glyph run between no brackets); defaults
+ *   to {@link DEFAULT_BAR_WIDTH}. The percentage + `(current/total)` count follow the track.
+ * - `fill` — the filled-cell glyph; defaults to {@link BAR_FILL} (`█`). `empty` — the empty-cell
+ *   glyph; defaults to {@link BAR_EMPTY} (`░`). Sized in VISIBLE columns ({@link
+ *   import('./helpers.js').width}), so a multi-cell glyph still yields a `width`-wide track.
+ * - `styler` — colors the FILLED run when supplied (the empty run + the trailing label stay plain);
+ *   the layout is identical with or without color, since the track is measured on visible width.
+ */
+export declare interface ProgressBarOptions {
+    readonly current: number;
+    readonly total: number;
+    readonly width?: number;
+    readonly fill?: string;
+    readonly empty?: string;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * The observable events a {@link ProgressInterface} emits (AGENTS §13).
+ *
+ * @remarks
+ * - `update` — the core event: fires on every `update(current)` (and on `complete` / `failure`),
+ *   carrying the `{ current, total }` progress (the clamped `current`). The hook a non-sink consumer
+ *   rides to observe progress without a terminal.
+ * - `complete` — the terminal signal: fires once from `complete()` (a successful finish), a pure
+ *   signal (empty tuple) so a consumer can observe the bar reaching its end. (`failure()` emits a final
+ *   `update` and routes its line to the error stream, but is NOT a `complete` — completion means the
+ *   work finished successfully.)
+ *
+ * Listener isolation is the emitter's (§13). Declared as a `type` alias (not
+ * `interface extends EventMap`, §4.5): a type-literal satisfies the `EventMap` constraint
+ * structurally, whereas an interface lacks the index signature.
+ */
+export declare type ProgressEventMap = {
+    /** Progress advanced — the clamped `{ current, total }` (fires on `update` and on `complete` / `failure`). */
+    readonly update: readonly [progress: {
+        readonly current: number;
+        readonly total: number;
+    }];
+    /** The bar reached its end via `complete()` (a successful finish). */
+    readonly complete: readonly [];
+};
+
+/**
+ * An update-driven, observable progress bar (AGENTS §13) — `update(current)` recomputes the bar via
+ * {@link import('./helpers.js').renderBar}, writes `\r` + bar to its {@link SinkInterface}, and emits
+ * the `{ current, total }` on `update`. The line-OVERWRITE is the sink's job (a TTY sink overwrites
+ * on the `\r`; a plain sink degrades to a fresh line). NO self-timer — the caller drives it.
+ *
+ * @remarks
+ * - **Update-driven.** Each `update(current, message?)` clamps `current` to `[0, total]`, renders
+ *   the bar (filled to `current / total`, with the trailing `percent (current/total)` + message),
+ *   emits `update`, and writes `'\r' + bar`. There is no internal timer (unlike {@link
+ *   SpinnerInterface}) — progress advances only when the caller reports it.
+ * - **Outcome lines.** `complete(message?)` renders a FULL bar (`current = total`) + message,
+ *   terminated by a newline, emits a final `update` then `complete`, and marks `completed`.
+ *   `failure(message?)` renders the bar at its CURRENT fill + message + newline and routes to the sink's
+ *   error stream (no `complete` — the work did not finish). Both are terminal: a later `update` after
+ *   a `complete` / `failure` is ignored (`active` is `false`).
+ * - **Bounded.** `current` is always clamped to `[0, total]`; `completed` reports whether
+ *   `complete()` has run; `active` is `true` until a `complete` / `failure`.
+ */
+export declare interface ProgressInterface {
+    readonly emitter: EmitterInterface<ProgressEventMap>;
+    /** Whether the bar is still advancing (before any `complete()` / `failure()`). */
+    readonly active: boolean;
+    /** Whether `complete()` has run (the bar finished successfully). */
+    readonly completed: boolean;
+    /** The current value, clamped to `[0, total]`. */
+    readonly current: number;
+    /** The target value the bar fills toward. */
+    readonly total: number;
+    /** Report progress: clamp `current`, re-render the bar, emit `update`, write `\r` + bar. Ignored once terminal. */
+    update(current: number, message?: string): void;
+    /** Finish successfully — render a FULL bar + newline, emit a final `update` then `complete`. */
+    complete(message?: string): void;
+    /** Finish unsuccessfully — render the bar at its current fill + newline to the error stream (no `complete`). */
+    failure(message?: string): void;
+    /** Tear down — destroy the emitter. */
+    destroy(): void;
+}
+
+/**
+ * Options for `createProgress` / the {@link ProgressInterface} constructor.
+ *
+ * @remarks
+ * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the
+ *   {@link ProgressEventMap}, wired at construction.
+ * - `error` — the emitter's listener-error handler (§13); a listener throw routes here.
+ * - `total` — the value `current` advances toward (the `100%` point); the only REQUIRED option.
+ * - `message` — text shown after the bar; defaults to `''`. Overridden per-`update` and by a
+ *   `complete` / `failure` argument.
+ * - `width` — the bar track's visible cell count, handed to {@link import('./helpers.js').renderBar};
+ *   defaults to {@link DEFAULT_BAR_WIDTH}.
+ * - `sink` — where each `\r` + bar line is written; defaults to
+ *   {@link import('./factories.js').createConsoleSink}. A TTY sink (C-g) overwrites on the `\r`.
+ * - `styler` — the {@link StylerInterface} the filled run is colored through; defaults to
+ *   {@link import('./factories.js').createStyler} (ANSI). The ONE styler the whole system shares.
+ */
+export declare interface ProgressOptions {
+    readonly on?: EmitterHooks<ProgressEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly total: number;
+    readonly message?: string;
+    readonly width?: number;
+    readonly sink?: SinkInterface;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * Render a determinate progress bar string — a filled / empty glyph track followed by the percentage
+ * and the `(current/total)` count (`█████░░░░░ 50% (5/10)`). Pure: same {@link ProgressBarOptions} →
+ * same string. The animation-layer sibling of the C-c `render*` renderers (box / table / tree /
+ * separator), shared so a {@link import('./types.js').ProgressInterface} and any direct caller draw
+ * the ONE bar — never a second, hand-rolled one (AGENTS §5; scsr shipped three).
+ *
+ * @remarks
+ * - **Fill fraction, clamped.** The filled cell count is `round((current / total) · width)` with
+ *   `current` clamped to `[0, total]`, so an overrun never over-fills and a negative never under-fills.
+ *   A `total <= 0` renders a FULL track (there is nothing to fill toward — the work is trivially done).
+ * - **Width-aware track.** The filled run is `fill` tiled to the filled cell count and the empty run
+ *   `empty` tiled to the remainder, each via {@link repeatTo} — so the TRACK is exactly `width` VISIBLE
+ *   columns even for a multi-cell glyph (its escape codes / extra cells never break the width).
+ * - **Styling.** `options.styler` colors the FILLED run only (the empty run + the trailing
+ *   `percent (count)` label stay plain), through {@link paint}; the layout is identical with or
+ *   without color, since the track is measured on visible width.
+ * - **Label.** The percentage is the rounded `current / total` (e.g. `50%`); the count is the CLAMPED
+ *   `current` over `total` (`(5/10)`), a single space separating the track, the percent, and the count.
+ *
+ * @param options - See {@link ProgressBarOptions}
+ * @returns The rendered bar line (no trailing newline)
+ *
+ * @example
+ * ```ts
+ * renderBar({ current: 5, total: 10, width: 10 }) // '█████░░░░░ 50% (5/10)'
+ * renderBar({ current: 10, total: 10, width: 4 }) // '████ 100% (10/10)'
+ * ```
+ */
+export declare function renderBar(options: ProgressBarOptions): string;
+
+/**
+ * Render `content` framed in box-drawing characters, optionally captioned, width-aware so
+ * styled content stays aligned inside the frame. Pure: same {@link BoxOptions} → same string.
+ *
+ * @remarks
+ * - **Lines.** `content` is split on `\n`; each line is padded (left-aligned) to the inner
+ *   width by {@link align} — measured on VISIBLE width, so a styled line never breaks the
+ *   right edge. The inner width is the widest line's visible width (or `width − borders −
+ *   2·padding` when an explicit `width` is given and is wider), plus `padding` blank cells
+ *   inside each {@link BorderChars.vertical} edge.
+ * - **Title.** An optional `title` is embedded in the TOP border (` title `), the remaining
+ *   top edge drawn as fill; a title wider than the inner width widens the box to fit it.
+ * - **Border + styling.** The {@link BorderStyle} (`options.border`, default
+ *   {@link DEFAULT_BORDER}) selects the glyph set from {@link BORDER_CHARS}; `options.styler`
+ *   colors the frame + title when given (content cells are written as supplied).
+ * - **Multi-line result.** Returns the box as `\n`-joined rows (top, one row per content line,
+ *   bottom) with no trailing newline.
+ *
+ * @param options - See {@link BoxOptions}
+ * @returns The framed box (multiple lines joined by `\n`)
+ */
+export declare function renderBox(options: BoxOptions): string;
+
+/**
+ * A swappable style renderer — the seam that turns style DATA into output for ONE
+ * target. The cross-environment default is the ANSI renderer (SGR escape codes); a
+ * browser `%c` / CSS renderer implements the SAME contract over the SAME {@link Style}
+ * model, so it drops in without touching the style data (the C-f browser branch).
+ */
+export declare interface RendererInterface {
+    /**
+     * Render `text` wrapped in the target codes for `style`. The EMPTY style (no colors,
+     * no attributes) and the empty string both return `text` unchanged — no wrapping.
+     */
+    render(style: Style, text: string): string;
+}
+
+/**
+ * Render a horizontal rule — an optional centered title embedded in a line of fill characters,
+ * to a fixed visible width. Pure: same {@link SeparatorOptions} → same string.
+ *
+ * @remarks
+ * - **Plain rule.** With no `title`, returns `fill` repeated to `width` visible columns.
+ * - **Titled rule.** With a `title`, centers ` title ` (one {@link SEPARATOR_TITLE_GAP} each
+ *   side) in the line, splitting the remaining fill between the two sides (the extra column,
+ *   when the remainder is odd, goes to the right). The visible width stays exactly `width`,
+ *   even when the title is styled (the title's escape codes don't count toward the budget) —
+ *   a title at least as wide as `width` yields just the gapped title (no fill).
+ * - **Styling.** When `options.styler` is given, the fill runs (and the embedded title) are
+ *   colored through it; the layout is identical with or without color, since width is measured
+ *   on the visible content (AGENTS — width-aware via {@link width}).
+ *
+ * @param options - See {@link SeparatorOptions}
+ * @returns The rule line (no trailing newline)
+ *
+ * @example
+ * ```ts
+ * renderSeparator({ width: 10 }) // '──────────'
+ * renderSeparator({ title: 'Build', width: 13 }) // '── Build ──'  (centered)
+ * ```
+ */
+export declare function renderSeparator(options: SeparatorOptions): string;
+
+/**
+ * Render a bordered grid of `columns` + `rows` with per-column alignment and width-aware
+ * column sizing. Pure: same {@link TableOptions} → same string.
+ *
+ * @remarks
+ * - **Column sizing — visible width.** Each column is sized to the widest VISIBLE width
+ *   ({@link width}) among its header label and its cells, so an already-styled cell never
+ *   breaks the column (its escape codes don't count toward the width).
+ * - **Ragged rows.** A row shorter than the column count is padded with empty cells; a longer
+ *   row is truncated to the column count — a ragged input never throws.
+ * - **Alignment.** Each cell is positioned by its column's {@link ColumnSpec.align} (default
+ *   {@link DEFAULT_ALIGN}) via {@link align}.
+ * - **Frame.** The {@link BorderStyle} (`options.border`, default {@link DEFAULT_BORDER})
+ *   draws the outer frame, the header rule (a `teeRight … cross … teeLeft` line), and the
+ *   `vertical` column separators; `options.styler` colors the frame + header labels when
+ *   given. Returns the table as `\n`-joined rows (top, header, rule, one row per data row,
+ *   bottom), no trailing newline.
+ *
+ * @param options - See {@link TableOptions}
+ * @returns The rendered table (multiple lines joined by `\n`)
+ */
+export declare function renderTable(options: TableOptions): string;
+
+/**
+ * Render a nested {@link TreeNode} tree with box-drawing connectors. Pure: same
+ * {@link TreeOptions} → same string.
+ *
+ * @remarks
+ * The `root` label is the unindented first line; its descendants are drawn beneath it with
+ * {@link TREE_CHARS} — `├─ ` before each child but the last, `└─ ` before the last, and the
+ * carried prefix using `│  ` under an ancestor that still has later siblings or `   ` under a
+ * last ancestor (so the guides line up exactly under the branch they descend from). Node
+ * labels are written as given (an already-styled label is honored); `options.styler` colors
+ * the connectors when supplied. Returns the tree as `\n`-joined lines, no trailing newline.
+ *
+ * @param options - See {@link TreeOptions}
+ * @returns The rendered tree (multiple lines joined by `\n`)
+ *
+ * @example
+ * ```ts
+ * renderTree({ root: { label: 'root', children: [{ label: 'a' }, { label: 'b' }] } })
+ * // root
+ * // ├─ a
+ * // └─ b
+ * ```
+ */
+export declare function renderTree(options: TreeOptions): string;
+
+/**
+ * Render the connector-prefixed lines for a {@link TreeNode} list — the recursive core
+ * behind {@link renderTree}. Each child is drawn as `prefix` + its connector (`├─ ` for
+ * any but the last, `└─ ` for the last) + its label, with its own descendants recursed
+ * beneath under the carried guide (`│  ` under a non-last node, `   ` under the last).
+ *
+ * @remarks
+ * A centralized, exported recursion branch (AGENTS §5) so it is directly testable and
+ * reusable outside {@link renderTree}'s top-level `root.label` framing.
+ *
+ * @param nodes - The sibling {@link TreeNode}s to render at this depth
+ * @param prefix - The guide/gap string carried in from the ancestor chain (`''` at the root)
+ * @param styler - The {@link StylerInterface} connectors are colored through, when supplied
+ * @returns The rendered lines for `nodes` and all their descendants
+ *
+ * @example
+ * ```ts
+ * renderTreeChildren([{ label: 'a' }, { label: 'b' }], '')
+ * // ['├─ a', '└─ b']
+ * ```
+ */
+export declare function renderTreeChildren(nodes: readonly TreeNode[], prefix: string, styler?: StylerInterface): readonly string[];
+
+/**
+ * Repeat `unit` until it fills exactly `count` VISIBLE columns, trimming a trailing partial
+ * unit so the run is never over-wide — the fill primitive the separator + box edges draw with.
+ *
+ * @remarks
+ * Counts in code points ({@link width}-consistent), so a multi-cell or astral `unit` is laid
+ * down whole and the result is sliced to exactly `count` visible columns. `count <= 0` (or an
+ * empty / zero-width `unit`) yields `''`.
+ *
+ * @param unit - The (possibly multi-character) fill unit
+ * @param count - The visible column count to fill
+ * @returns `unit` tiled to exactly `count` visible columns
+ *
+ * @example
+ * ```ts
+ * repeatTo('─', 4) // '────'
+ * repeatTo('=-', 5) // '=-=-='
+ * ```
+ */
+export declare function repeatTo(unit: string, count: number): string;
+
+/**
+ * A lean, event-free narrative reporter (AGENTS §13) — the composable verb set for human /
+ * build-run output. Each verb FORMATS its line through the shared {@link StylerInterface} and
+ * the pure layout renderers ({@link renderSeparator} / {@link renderBox} / {@link renderTable}
+ * / {@link renderTree}) and WRITES it to a {@link SinkInterface} — the SAME styler + sink
+ * substrate the logger uses, never a second colorizer.
+ *
+ * @remarks
+ * - **A SMALL set, not a grab-bag.** `section` / `step` / `timing` / `status` / `table` /
+ *   `tree` / `box` / `line` / `blank`. No spinner / bar (the animation chunk), no buffering /
+ *   capture (the capture chunk), no level retention (the logger). Just format + write.
+ * - **`status` is a narrative OUTCOME, not a log level.** Its {@link StatusLevel} (`success` /
+ *   `error` / `warn` / `info`) is distinct from {@link import('./types.js').LogLevel}: an icon
+ *   ({@link STATUS_ICONS}) + a color ({@link STATUS_COLORS}), with `error` routed to the sink's
+ *   error stream (the `level` hint forwarded to {@link SinkInterface.write}) — there is no
+ *   gating and no severity ordering.
+ * - **Width-aware.** `section` (and a `box` with no explicit `width`) lay out to the reporter's
+ *   `#width`; the renderers measure on VISIBLE width (ANSI-aware), so styled content aligns.
+ * - **Event-free (§13).** No `#emitter` — a pure formatting front-end with no observable
+ *   lifecycle (like the renderers and `Scheduler`). It is reusable and holds no per-call state.
+ *
+ * @example
+ * ```ts
+ * const reporter = new Reporter()
+ * reporter.section('Build')
+ * reporter.step('compiling', { index: 1, total: 3 }) //   [1/3] compiling
+ * reporter.timing('bundle', 1234) //   bundle … 1.23s
+ * reporter.status('success', 'done') //   ✔ done
+ * ```
+ */
+export declare class Reporter implements ReporterInterface {
+    #private;
+    constructor(options?: ReporterOptions);
+    section(title: string): void;
+    step(message: string, position?: StepPosition): void;
+    timing(label: string, ms: number): void;
+    status(level: StatusLevel, message: string): void;
+    table(options: TableOptions): void;
+    tree(options: TreeOptions): void;
+    box(options: BoxOptions): void;
+    line(text: string): void;
+    blank(count?: number): void;
+}
+
+/**
+ * A lean, event-free narrative reporter — the composable verb set for human / build-run
+ * output (sections, steps, timings, outcomes, tables, trees, boxes), formatting through the
+ * shared {@link StylerInterface} + layout renderers and writing to a {@link SinkInterface}.
+ *
+ * @remarks
+ * - **A SMALL composable set**, not a grab-bag: `section` / `step` / `timing` / `status` /
+ *   `table` / `tree` / `box` / `line` / `blank`. Coloring is the ONE styler; layout is the
+ *   pure renderers ({@link import('./helpers.js').renderSeparator} /
+ *   {@link import('./helpers.js').renderBox} / {@link import('./helpers.js').renderTable} /
+ *   {@link import('./helpers.js').renderTree}). No second colorizer, no spinner / bar (that
+ *   is the animation chunk), no buffering / capture (that is the capture chunk).
+ * - **`status` is a narrative outcome, not a log level.** Its {@link StatusLevel} is
+ *   `success` / `error` / `warn` / `info` (DISTINCT from {@link LogLevel}); `error` routes to
+ *   the sink's error stream.
+ * - **Event-free (§13).** No emitter — a pure formatting front-end. Each verb FORMATS then
+ *   WRITES immediately; there is no retained state worth observing.
+ */
+export declare interface ReporterInterface {
+    /** Write a titled separator block — a section heading framed by a horizontal rule. */
+    section(title: string): void;
+    /** Write a step line, optionally prefixed with its `[index/total]` {@link StepPosition}. */
+    step(message: string, position?: StepPosition): void;
+    /** Write a timing line — `label … 1.23s` (sub-second shown as `…ms`). */
+    timing(label: string, ms: number): void;
+    /** Write an icon + colored outcome line for `level` (`error` routes to the error stream). */
+    status(level: StatusLevel, message: string): void;
+    /** Render a {@link TableOptions} grid through {@link import('./helpers.js').renderTable} and write it. */
+    table(options: TableOptions): void;
+    /** Render a {@link TreeOptions} tree through {@link import('./helpers.js').renderTree} and write it. */
+    tree(options: TreeOptions): void;
+    /** Render a {@link BoxOptions} frame through {@link import('./helpers.js').renderBox} and write it. */
+    box(options: BoxOptions): void;
+    /** Write one raw line, colored through the styler if any styling is embedded — no prefix, no icon. */
+    line(text: string): void;
+    /** Write `count` blank lines (default `1`). */
+    blank(count?: number): void;
+}
+
+/**
+ * Options for {@link createReporter} / the {@link ReporterInterface} constructor.
+ *
+ * @remarks
+ * - `sink` — where every formatted line is written; defaults to
+ *   {@link import('./factories.js').createConsoleSink} (the snapshotted, level-routing console
+ *   sink) — the SAME seam the logger writes through. A `status('error', …)` passes the
+ *   `error` level so a stream-aware sink routes it to `stderr`.
+ * - `styler` — the {@link StylerInterface} every line is colored through; defaults to
+ *   {@link import('./factories.js').createStyler} (ANSI). The ONE styler the whole system
+ *   shares — no second colorizer. A disabled styler yields plain narration.
+ * - `width` — the default column width handed to the separator / box renderers (the section
+ *   rule, a `box` with no explicit width); defaults to {@link DEFAULT_WIDTH}.
+ *
+ * Event-free (§13): the reporter has no `on` / `error` — it is a formatting front-end with no
+ * observable lifecycle, so (like the renderers and `Scheduler`) it carries no emitter.
+ */
+export declare interface ReporterOptions {
+    readonly sink?: SinkInterface;
+    readonly styler?: StylerInterface;
+    readonly width?: number;
+}
+
+/** The full SGR reset sequence (`ESC[0m`) appended after a styled run. */
+export declare const RESET: string;
+
+/** The SGR RESET parameter (0) — terminates a styled run, clearing all colors and attributes. */
+export declare const RESET_CODE = 0;
+
+/**
+ * The number of milliseconds at or above which {@link import('./helpers.js').formatDuration}
+ * (and so `Reporter.timing`) switches from a `…ms` rendering to a `…s` (seconds, 2 d.p.)
+ * rendering — exactly one second.
+ */
+export declare const SECOND_MS = 1000;
+
+/** The default fill character {@link import('./helpers.js').renderSeparator} draws its rule with — `─`. */
+export declare const SEPARATOR_FILL = "\u2500";
+
+/**
+ * The single padding cell on each side of a separator's embedded title (` title `) — keeps the
+ * title from butting against the rule. One space.
+ */
+export declare const SEPARATOR_TITLE_GAP = " ";
+
+/**
+ * Options for {@link import('./helpers.js').renderSeparator} — a horizontal rule, optionally
+ * carrying a centered title.
+ *
+ * @remarks
+ * - `title` — text to embed in the rule (e.g. a section heading). Omitted ⇒ an unbroken line.
+ * - `width` — the visible column count of the whole rule; defaults to {@link DEFAULT_WIDTH}.
+ * - `fill` — the single character the rule is drawn with; defaults to {@link SEPARATOR_FILL}
+ *   (`─`). The VISIBLE width of the rule is `width` regardless of the fill's escape codes.
+ * - `styler` — colors the rule (and the embedded title) when supplied; the layout is
+ *   identical with or without it, since width is measured on the visible content.
+ */
+export declare interface SeparatorOptions {
+    readonly title?: string;
+    readonly width?: number;
+    readonly fill?: string;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * The minimal output primitive — the seam every formatted line is written through. A
+ * `Sink` is the ONE place text leaves the logging system; redirect output (to a file, a
+ * buffer, a test recorder, the browser `%c` path, a server TTY) by supplying a different
+ * `SinkInterface`, with no change to the logger.
+ *
+ * @remarks
+ * - **`write(text)` is the whole contract.** A custom sink (file / buffer / recorder)
+ *   implements just `write(text)` and ignores the rest — the optional `level` exists ONLY so
+ *   a stream-aware sink can ROUTE. The logger passes the originating record's {@link LogLevel}.
+ * - **The default {@link import('./factories.js').createConsoleSink} routes by level** —
+ *   `error` → `console.error`, `warn` → `console.warn`, everything else → `console.log` — and
+ *   writes to the UNDERLYING `console` methods SNAPSHOTTED at creation, so a later `Capture`
+ *   that patches `console` can never feed the sink's own output back into itself (the
+ *   no-capture-loop principle). The same `level` seam lets the C-g server TTY sink send
+ *   `error` / `warn` to `stderr`.
+ */
+export declare interface SinkInterface {
+    /**
+     * Write one already-formatted chunk of output. `text` receives ONE LINE WITHOUT its
+     * terminator — the sink's target supplies it (e.g. `console.log`; the server TTY sink
+     * appends one) — UNLESS `text` begins with `\r`: that is an in-place REDRAW frame (the
+     * Spinner / Progress animation protocol) carrying its own line endings, written verbatim.
+     * `level` is the originating record's {@link LogLevel} — supplied so a stream-aware sink
+     * can route (e.g. `error` to `stderr`); a plain sink ignores it.
+     */
+    write(text: string, level?: LogLevel): void;
+}
+
+/**
+ * A self-driving, observable activity spinner (AGENTS §13) — a glyph cycle that advances on a
+ * periodic timer, writing each `\r` + frame line to its {@link SinkInterface} and emitting it on
+ * `frame`. The leading `\r` is what an overwrite-capable sink (the C-g TTY sink) redraws on; a plain
+ * sink (C-f) degrades to a fresh, non-overwriting line — the line-OVERWRITE is the SINK's job, never
+ * the spinner's. UNIVERSAL — `setInterval` + the one {@link StylerInterface} + the one
+ * {@link SinkInterface}, no `node:*`, no `process.stdout`.
+ *
+ * @remarks
+ * - **Self-driving but deterministically testable.** `start()` arms a `setInterval` that calls
+ *   {@link tick} each `interval`; each {@link tick} builds the styled `glyph + message` line for the
+ *   current frame, emits it on `frame`, writes `'\r' + line` to the sink, then advances the frame
+ *   index (wrapping). A test drives frames by calling {@link tick} directly (NO real clock) and proves
+ *   the timer arms / clears with fake timers.
+ * - **Leak-free timer.** The interval is ALWAYS cleared on {@link success} / {@link failure} /
+ *   {@link stop} / {@link destroy} — `#handle` is the single source of `active`, set on arm and unset
+ *   on clear, so a spinner never leaks a running interval.
+ * - **Idempotent `start`.** A {@link start} while already `active` is a no-op (it never arms a second
+ *   timer).
+ * - **Outcome lines.** {@link success} / {@link failure} clear the timer then write + emit a FINAL line —
+ *   the {@link STATUS_ICONS} `✔` / `✖` (colored via {@link STATUS_COLORS}) + the message — terminated
+ *   by a newline (the activity is over; the line is committed, not overwritten). {@link failure} routes to
+ *   the sink's error stream.
+ * - **Lifecycle (§10).** {@link stop} clears the timer and LEAVES the current line; {@link destroy}
+ *   stops then destroys the emitter. {@link update} swaps the message and re-renders immediately when
+ *   `active`.
+ *
+ * @example
+ * ```ts
+ * const spinner = new Spinner({ message: 'building' })
+ * spinner.start() // arms the timer, paints the first frame to the sink
+ * spinner.update('bundling') // message changes, re-rendered at once
+ * spinner.success('built in 1.2s') // ✔ built in 1.2s — timer cleared, line committed
+ * ```
+ */
+export declare class Spinner implements SpinnerInterface {
+    #private;
+    constructor(options?: SpinnerOptions);
+    get emitter(): EmitterInterface<SpinnerEventMap>;
+    get active(): boolean;
+    get message(): string;
+    start(): void;
+    tick(): void;
+    update(message: string): void;
+    success(message?: string): void;
+    failure(message?: string): void;
+    stop(): void;
+    destroy(): void;
+}
+
+/**
+ * The default spinner frame cycle a {@link import('./types.js').SpinnerInterface} advances through —
+ * the ten braille-pattern glyphs (U+2800 block) that read as a smoothly rotating dot, the universal
+ * terminal-spinner convention. Frozen; a consumer swaps the whole cycle via `options.frames`.
+ *
+ * @remarks
+ * Braille glyphs are single visible cells, so every frame occupies one column — the spinner glyph
+ * never shifts the message beside it as it advances. The source of truth for the default frame axis.
+ */
+export declare const SPINNER_FRAMES: readonly string[];
+
+/**
+ * The observable events a {@link SpinnerInterface} emits (AGENTS §13).
+ *
+ * @remarks
+ * - `frame` — the core event: fires once per advance (every `tick()`, whether driven by the internal
+ *   timer or called directly) AND on the final `success` / `failure` line, carrying the rendered frame
+ *   line (the SAME text written to the sink, minus the leading `\r`). The hook a non-sink consumer
+ *   (a test, a remote mirror) rides to observe the animation without a terminal.
+ * - `start` / `stop` — the lifecycle signals bracketing the internal timer: `start` fires when the
+ *   timer is armed (the first `start()` on an inactive spinner), `stop` when it is cleared (a
+ *   `stop()` / `success()` / `failure()` on an active spinner, and from `destroy()`); both pure signals
+ *   (empty tuples) so a consumer can observe the activity lifecycle.
+ *
+ * Listener isolation is the emitter's (§13): a listener throw routes to the emitter's `error`
+ * handler, never onto this map. Declared as a `type` alias (not `interface extends EventMap`, §4.5):
+ * a type-literal satisfies the `EventMap` constraint structurally, whereas an interface lacks the
+ * index signature.
+ */
+export declare type SpinnerEventMap = {
+    /** A frame was produced (a `tick()` advance or the final `success` / `failure` line) — the rendered line. */
+    readonly frame: readonly [line: string];
+    /** The internal timer was armed (an inactive spinner's `start()`). */
+    readonly start: readonly [];
+    /** The internal timer was cleared (an active spinner's `stop()` / `success()` / `failure()` / `destroy()`). */
+    readonly stop: readonly [];
+};
+
+/**
+ * A self-driving, observable activity spinner (AGENTS §13) — a glyph cycle that advances on a
+ * periodic timer, writing each `\r` + frame line to its {@link SinkInterface} and emitting it on
+ * `frame`. The line-OVERWRITE is the sink's job (a TTY sink overwrites on the `\r`; a plain sink
+ * degrades to a fresh line).
+ *
+ * @remarks
+ * - **Self-driving but deterministically testable.** `start()` arms a `setInterval` (universal — no
+ *   `node:*`) that calls `tick()` each `interval`; each `tick()` advances the frame index, builds the
+ *   styled `glyph + message` line, emits it on `frame`, and writes `'\r' + line` to the sink. A test
+ *   drives frames by calling `tick()` directly (NO real clock) and proves the timer arms / clears
+ *   with fake timers — the timer is ALWAYS cleared on `success` / `failure` / `stop` / `destroy`, so it
+ *   never leaks.
+ * - **Idempotent `start`.** A `start()` while already `active` is a no-op (it never arms a second
+ *   timer). `active` reflects whether the timer is currently armed.
+ * - **Outcome lines.** `success(message?)` / `failure(message?)` clear the timer, then write + emit a
+ *   FINAL line — the {@link STATUS_ICONS} `✔` / `✖` (colored via {@link STATUS_COLORS}) + the
+ *   message — terminated by a newline (the activity is over; the line is committed, not overwritten).
+ *   `failure` routes to the sink's error stream.
+ * - **Lifecycle (§10).** `stop()` clears the timer and LEAVES the current line (no final write);
+ *   `destroy()` stops then destroys the emitter. `update(message)` swaps the message (re-rendering
+ *   immediately when active, so the change shows without waiting for the next tick).
+ */
+export declare interface SpinnerInterface {
+    readonly emitter: EmitterInterface<SpinnerEventMap>;
+    /** Whether the internal timer is currently armed (between `start()` and `stop` / `success` / `failure`). */
+    readonly active: boolean;
+    /** The current message shown beside the glyph. */
+    readonly message: string;
+    /** Arm the periodic timer and render the first frame — a no-op when already `active`. */
+    start(): void;
+    /** Advance one frame: build the line, emit `frame`, and write `\r` + line to the sink. */
+    tick(): void;
+    /** Change the message; re-renders immediately when `active` so the change shows at once. */
+    update(message: string): void;
+    /** Stop with a SUCCESS line — clear the timer, write + emit `✔ message` + newline. */
+    success(message?: string): void;
+    /** Stop with a FAILURE line — clear the timer, write + emit `✖ message` + newline (error stream). */
+    failure(message?: string): void;
+    /** Clear the timer and LEAVE the current line (no final write) — a no-op when not `active`. */
+    stop(): void;
+    /** Tear down — `stop()` then destroy the emitter. */
+    destroy(): void;
+}
+
+/**
+ * Options for `createSpinner` / the {@link SpinnerInterface} constructor.
+ *
+ * @remarks
+ * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the
+ *   {@link SpinnerEventMap}, wired at construction.
+ * - `error` — the emitter's listener-error handler (§13); a listener throw routes here.
+ * - `message` — the text shown beside the spinner glyph; defaults to `''` (a bare glyph). Changed
+ *   live via `update(message)` and overridden by a `success` / `failure` argument.
+ * - `frames` — the cycle of glyph frames the spinner advances through; defaults to
+ *   {@link SPINNER_FRAMES} (the braille set `⠋⠙⠹…`). Each `tick()` advances to the next, wrapping.
+ * - `interval` — the timer period in milliseconds between frames; defaults to
+ *   {@link DEFAULT_SPINNER_INTERVAL}. The timer is ALWAYS cleared on `success` / `failure` / `stop` /
+ *   `destroy`, so it never leaks; tests drive frames deterministically via `tick()` (no real clock).
+ * - `sink` — where each `\r` + frame line is written; defaults to
+ *   {@link import('./factories.js').createConsoleSink}. A TTY sink (C-g) overwrites on the `\r`.
+ * - `styler` — the {@link StylerInterface} the glyph is colored through; defaults to
+ *   {@link import('./factories.js').createStyler} (ANSI). The ONE styler the whole system shares.
+ */
+export declare interface SpinnerOptions {
+    readonly on?: EmitterHooks<SpinnerEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly message?: string;
+    readonly frames?: readonly string[];
+    readonly interval?: number;
+    readonly sink?: SinkInterface;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * Each {@link StatusLevel}'s {@link Color} — the icon + message color a `status` line renders
+ * in (`success` green, `error` red, `warn` yellow, `info` blue). The VISUAL treatment of a
+ * narrative outcome, colored through the reporter's styler; orthogonal to leveling, like
+ * {@link LEVEL_COLORS}. Excludes `default` so each value indexes a real styler accessor.
+ */
+export declare const STATUS_COLORS: Readonly<Record<StatusLevel, Exclude<Color, 'default'>>>;
+
+/**
+ * Each {@link StatusLevel}'s icon glyph — the leading mark a {@link
+ * import('./types.js').ReporterInterface.status} outcome line shows: `success` ✔, `error` ✖,
+ * `warn` ⚠, `info` ℹ. The narrative-outcome counterpart to a log level's label; frozen.
+ */
+export declare const STATUS_ICONS: Readonly<Record<StatusLevel, string>>;
+
+/**
+ * Every {@link StatusLevel}, frozen — the outcomes a `status` line supports (drives exhaustive
+ * tests). The source of truth for the status axis; aligned with {@link STATUS_ICONS} /
+ * {@link STATUS_COLORS}.
+ */
+export declare const STATUS_LEVELS: readonly StatusLevel[];
+
+/**
+ * A narrative outcome level — the four states {@link ReporterInterface.status} reports, each
+ * with its own icon + color ({@link STATUS_ICONS} / {@link STATUS_COLORS}).
+ *
+ * @remarks
+ * DISTINCT from {@link LogLevel} (`debug` / `info` / `warn` / `error`): a `StatusLevel` is a
+ * narrative OUTCOME (did the step success?), not a log SEVERITY threshold — there is no
+ * ordering and no gating. `success` (`✔`, green), `error` (`✖`, red), `warn` (`⚠`, yellow),
+ * `info` (`ℹ`, blue). `error` routes to the sink's error stream (the `level` hint passed to
+ * {@link SinkInterface.write}); the other three go to the default stream.
+ */
+export declare type StatusLevel = 'success' | 'error' | 'warn' | 'info';
+
+/**
+ * A step's position in a sequence — the `{ index, total }` a {@link ReporterInterface.step}
+ * renders as a `[2/5]` prefix.
+ *
+ * @remarks
+ * Both are 1-based for display (`{ index: 2, total: 5 }` ⇒ `[2/5]`); the reporter formats
+ * them verbatim, so a caller controls the numbering. Omitting the position renders a bare
+ * step line with no prefix.
+ */
+export declare interface StepPosition {
+    readonly index: number;
+    readonly total: number;
+}
+
+/**
+ * Stringify ONE captured console argument into a line fragment — the per-argument rule behind
+ * {@link formatArgs}: an `Error` → `name: message`, a plain object / array → circular-safe JSON,
+ * anything else (string, number, boolean, `null`, `undefined`, symbol, function) → `String(value)`.
+ *
+ * @remarks
+ * - **Total + never throws.** Like a guard (§14), this never throws on adversarial input — a value
+ *   carrying a circular reference, a `BigInt`, or a throwing `toJSON` is rendered, not raised. The
+ *   `JSON.stringify` runs with a circular-guard replacer (a seen-set drops a back-reference as
+ *   `'[Circular]'`); should `JSON.stringify` still throw (e.g. a `BigInt`), the value falls back to
+ *   `String(value)`. So a `Capture` can never crash the program whose `console.*` it intercepts.
+ * - **`Error` first.** An `Error` renders as `name: message` (e.g. `TypeError: bad`) — the useful
+ *   one-line form, since `JSON.stringify(error)` is `{}` (its fields are non-enumerable).
+ * - **Objects → JSON.** A non-null `object` (including an array) is `JSON.stringify`d; a primitive
+ *   (or `null` / `undefined` / `function` / `symbol`) goes through `String`.
+ *
+ * @param value - One console argument (any value)
+ * @returns The argument's one-line string form
+ *
+ * @example
+ * ```ts
+ * stringifyValue('hi') // 'hi'
+ * stringifyValue({ a: 1 }) // '{"a":1}'
+ * stringifyValue(new TypeError('bad')) // 'TypeError: bad'
+ * const cycle: Record<string, unknown> = {}
+ * cycle.self = cycle
+ * stringifyValue(cycle) // '{"self":"[Circular]"}'
+ * ```
+ */
+export declare function stringifyValue(value: unknown): string;
+
+/**
+ * Remove every ANSI escape sequence from `text`, returning the plain visible string.
+ *
+ * @remarks
+ * Strips SGR color/style codes AND other CSI controls (cursor, erase) plus OSC
+ * sequences (titles, hyperlinks) — see {@link ANSI_PATTERN}. A FRESH `RegExp` is built
+ * per call from the canonical pattern's `source` + `flags`, so the shared global
+ * pattern's `lastIndex` is never mutated across calls (re-entrant and deterministic).
+ *
+ * @param text - Any string, styled or plain
+ * @returns `text` with all ANSI escapes removed
+ *
+ * @example
+ * ```ts
+ * strip('\x1b[31mred\x1b[0m') // 'red'
+ * ```
+ */
+export declare function strip(text: string): string;
+
+/**
+ * Remove every non-printing C0 control character from `text` EXCEPT `\t` / `\n` / `\r`
+ * (meaningful whitespace), plus DEL — returning the sanitized string.
+ *
+ * @remarks
+ * Deliberately SEPARATE from {@link strip} (ANSI-escape removal only, so `width` /
+ * `align` stay untouched) — this is the additional pass a non-TTY output sink applies
+ * on top of `strip`, so a captured `\x07` bell or stray `\x00` never reaches a log file
+ * / non-terminal target. A FRESH `RegExp` is built per call from {@link CONTROL_PATTERN}'s
+ * `source` + `flags`, the same re-entrant idiom as `strip`.
+ *
+ * @param text - Any string, possibly carrying raw control bytes
+ * @returns `text` with C0 controls (other than tab/newline/CR) and DEL removed
+ *
+ * @example
+ * ```ts
+ * stripControls('a\x07b\nc') // 'ab\nc'
+ * ```
+ */
+export declare function stripControls(text: string): string;
+
+/**
+ * Text style as DATA — a frozen, readonly record of a foreground color, a background
+ * color, and a set of text attributes. The single style value the whole console /
+ * terminal system shares; a {@link RendererInterface} renders it for one target.
+ *
+ * @remarks
+ * - `foreground` / `background` are absent (not `'default'`) when unset — the renderer
+ *   emits a color code only for a set, non-`default` color.
+ * - `attributes` is a de-duplicated, order-stable list (a set modelled as an array so
+ *   the value stays plain JSON data — no `Set` to clone or serialize). An empty list +
+ *   no colors is the EMPTY style, which renders text unchanged.
+ * - The value is deeply frozen; compose a new style with the styler rather than mutating.
+ */
+export declare interface Style {
+    readonly foreground?: Color;
+    readonly background?: Color;
+    readonly attributes: readonly Attribute[];
+}
+
+/**
+ * The fluent, composable styler — the consumer-facing API over the style engine. It
+ * builds a {@link Style} (style as DATA) and renders it through an injected
+ * {@link RendererInterface} (the ANSI default, or a browser `%c` renderer at C-f). Each
+ * color / attribute accessor is immutable copy-on-write: it returns a NEW styler's
+ * surface with the token added, so `styler.red.bold('hi')` composes without mutating,
+ * and a base styler is freely reusable.
+ *
+ * @remarks
+ * - **Callable surface.** A `Styler` is not itself callable; its {@link surface} getter
+ *   returns the {@link StylerInterface} — a render FUNCTION carrying the chainable
+ *   accessors. The accessors are installed as LAZY getters (`Object.defineProperties`),
+ *   so a chain materializes only the stylers it actually walks — never the full tree —
+ *   and the recursion terminates. The factory returns that surface; this class is the
+ *   engine behind it.
+ * - **Immutable.** `#foreground` and `#attribute` return a fresh `Styler` (the style is
+ *   rebuilt, never mutated). A later color of the same channel WINS (last write); a
+ *   repeated attribute is idempotent (de-duplicated, order preserved).
+ * - **`enabled` switch.** When `false`, the render function returns text VERBATIM — no
+ *   renderer call, no escape codes (for a non-TTY / `NO_COLOR` / piped output).
+ * - **Event-free** — a pure styling primitive (AGENTS §13), like `Scheduler`.
+ */
+export declare class Styler {
+    #private;
+    constructor(renderer: RendererInterface, enabled: boolean, style: Style);
+    /** The accumulated style DATA — the empty style on a base styler. */
+    get style(): Style;
+    /** Whether styling is applied; when `false`, the surface returns text unchanged. */
+    get enabled(): boolean;
+    /**
+     * The fluent {@link StylerInterface} value — a render function (`text => string`) with
+     * `style`, `enabled`, and every {@link Color} / {@link Attribute} as a LAZY accessor
+     * (each computes the next styler's surface only when read). This is what consumers
+     * hold and call.
+     *
+     * @remarks
+     * The accessors are defined as getters (not eagerly-merged values), so accessing one
+     * builds exactly one child styler — the tree is never fully materialized and the
+     * construction terminates. The assembled function is then narrowed to
+     * {@link StylerInterface} through {@link #isSurface} (a real structural check), so no
+     * type assertion is used (AGENTS §1 / §14 — narrow, never assert).
+     */
+    get surface(): StylerInterface;
+}
+
+/**
+ * The fluent, composable styling surface — the consumer-facing API. It is BOTH a
+ * function (call it with text to render the accumulated style) AND a record of
+ * chainable accessors: every {@link Color} and {@link Attribute} is a getter returning a
+ * NEW styler with that token added, so `styler.red.bold('hi')` and
+ * `styler.red(styler.bold('hi'))` both work and nothing is mutated.
+ *
+ * @remarks
+ * - Each accessor returns a fresh `StylerInterface` (immutable, copy-on-write) — a base
+ *   styler is reusable and the chains never interfere.
+ * - Calling the styler builds the {@link Style} under the hood and renders it through the
+ *   injected renderer. When `enabled` is `false`, it returns the text verbatim.
+ * - `style` exposes the accumulated style DATA (the empty style on a base styler), and
+ *   `enabled` reflects the switch — both inspectable and testable.
+ * - A later color of the same channel wins (`styler.red.blue` is blue); a repeated
+ *   attribute is idempotent (`styler.bold.bold` carries one `bold`).
+ */
+export declare interface StylerInterface {
+    /** Render the accumulated style around `text` (verbatim when `enabled` is `false`). */
+    (text: string): string;
+    /** The accumulated style DATA — the empty style on a base styler. */
+    readonly style: Style;
+    /** Whether styling is applied; when `false`, calls return text unchanged. */
+    readonly enabled: boolean;
+    readonly black: StylerInterface;
+    readonly red: StylerInterface;
+    readonly green: StylerInterface;
+    readonly yellow: StylerInterface;
+    readonly blue: StylerInterface;
+    readonly magenta: StylerInterface;
+    readonly cyan: StylerInterface;
+    readonly white: StylerInterface;
+    readonly brightBlack: StylerInterface;
+    readonly brightRed: StylerInterface;
+    readonly brightGreen: StylerInterface;
+    readonly brightYellow: StylerInterface;
+    readonly brightBlue: StylerInterface;
+    readonly brightMagenta: StylerInterface;
+    readonly brightCyan: StylerInterface;
+    readonly brightWhite: StylerInterface;
+    readonly bold: StylerInterface;
+    readonly dim: StylerInterface;
+    readonly italic: StylerInterface;
+    readonly underline: StylerInterface;
+    readonly inverse: StylerInterface;
+    readonly strikethrough: StylerInterface;
+}
+
+/**
+ * Options for {@link createStyler}.
+ *
+ * @remarks
+ * - `renderer` — the {@link RendererInterface} every style renders through; defaults to
+ *   the ANSI renderer (the cross-environment default), so the styler works unchanged in
+ *   any terminal. Inject a browser `%c` renderer (C-f) to retarget with no other change.
+ * - `enabled` — the no-color switch. When `false`, the styler returns text VERBATIM
+ *   (for a non-TTY, a `NO_COLOR` environment, or piped output); defaults to `true`.
+ */
+export declare interface StylerOptions {
+    readonly renderer?: RendererInterface;
+    readonly enabled?: boolean;
+}
+
+/**
+ * Options for {@link import('./helpers.js').renderTable} — a bordered grid of columns + rows
+ * with per-column alignment and width-aware sizing.
+ *
+ * @remarks
+ * - `columns` — the {@link ColumnSpec}s, left to right; their `label`s form the header row.
+ * - `rows` — the body, one `readonly string[]` per row. A short row is padded with empty
+ *   cells, an over-long row is truncated to the column count, so a ragged input never throws.
+ * - `border` — the {@link BorderStyle} the frame + header rule + column separators draw in;
+ *   defaults to {@link DEFAULT_BORDER} (`single`).
+ * - `styler` — colors the border + header labels when supplied; the cells are written as
+ *   given (already-styled cells are honored — their VISIBLE width drives column sizing, never
+ *   their raw `.length`).
+ */
+export declare interface TableOptions {
+    readonly columns: readonly ColumnSpec[];
+    readonly rows: readonly (readonly string[])[];
+    readonly border?: BorderStyle;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * The tree connectors {@link import('./helpers.js').renderTree} draws — the `├─` branch (a
+ * non-last child), the `└─` corner (the last child), the `│ ` guide (carried down through an
+ * earlier branch's descendants), and the `  ` gap (under a last branch). Frozen.
+ */
+export declare const TREE_CHARS: Readonly<{
+    branch: "├─ ";
+    corner: "└─ ";
+    guide: "│  ";
+    gap: "   ";
+}>;
+
+/**
+ * One node of a {@link TreeOptions} tree — a label plus optional children, recursively.
+ *
+ * @remarks
+ * - `label` — the node's text (a single visible line; it may already be styled).
+ * - `children` — the node's sub-nodes, rendered indented beneath it with `├─` / `└─`
+ *   connectors and `│` guides; omitted (or empty) ⇒ a leaf.
+ */
+export declare interface TreeNode {
+    readonly label: string;
+    readonly children?: readonly TreeNode[];
+}
+
+/**
+ * Options for {@link import('./helpers.js').renderTree} — a nested {@link TreeNode} tree drawn
+ * with box-drawing connectors.
+ *
+ * @remarks
+ * - `root` — the top {@link TreeNode}; its `label` is the unindented first line and its
+ *   `children` descend beneath it (`├─` for each but the last, `└─` for the last, `│` guides
+ *   carried down through earlier branches).
+ * - `styler` — colors the connectors when supplied; node labels are written as given.
+ */
+export declare interface TreeOptions {
+    readonly root: TreeNode;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * The visible width of `text` — its length after ANSI escapes are stripped, counted in
+ * Unicode code points (so an astral character such as an emoji counts as one, not the
+ * two UTF-16 units `String.length` would report).
+ *
+ * @remarks
+ * The basis for terminal layout (box / table / progress alignment): the column count a
+ * styled string occupies, independent of its escape codes. It does NOT account for
+ * wide (CJK / fullwidth) glyphs occupying two cells — a deliberate, documented
+ * simplification at this layer; callers needing east-asian width handle it above.
+ *
+ * @param text - Any string, styled or plain
+ * @returns The count of visible code points
+ *
+ * @example
+ * ```ts
+ * width('\x1b[1mhi\x1b[0m') // 2
+ * ```
+ */
+export declare function width(text: string): number;
+
+export declare function withCapture<T>(fn: () => Promise<T>, options?: CaptureOptions): Promise<CaptureResult<T>>;
+
+export declare function withCapture<T>(fn: () => T, options?: CaptureOptions): CaptureResult<T>;
+
+export { }