@orkestrel/console 0.0.12 → 0.0.14

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

@@ -1,6 +1,6 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
 
 /**
  * Pads (or, when over budget, truncates) `text` to exactly `columns` visible columns, positioning
@@ -29,9 +29,11 @@ import { EmitterInterface } from '@orkestrel/emitter';
 export declare function align(text: string, columns: number, alignment?: Alignment): string;
 
 /**
- * Names the 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, so it stays a union.
+ * Names the horizontal text alignment within a fixed-width cell — `left` / `center` / `right`,
+ * the conventional set a {@link ColumnSpec} (and the box / separator title) aligns by.
+ *
+ * @remarks
+ * A value set rather than a binary toggle, so it stays a union.
  */
 export declare type Alignment = 'left' | 'center' | 'right';
 
@@ -56,12 +58,13 @@ export declare const ANSI_PATTERN: RegExp;
 
 /**
  * Implements 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 implements the same contract over
- * the same {@link Style}, so retargeting changes the renderer, never the style model.
+ * SGR escape codes, stateless and event-free.
  *
  * @remarks
+ * It is the single styling output the whole console / terminal system uses in a terminal; the
+ * browser `%c` / CSS renderer implements the same contract over the same {@link Style}, so
+ * retargeting changes the renderer, never the style model.
+ *
  * - **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
@@ -85,7 +88,8 @@ export declare class ANSIRenderer implements RendererInterface {
 }
 
 /**
- * Names a text-style attribute — the standard SGR text effects.
+ * Names a text-style attribute — `bold` / `dim` / `italic` / `underline` / `inverse` /
+ * `strikethrough`, the standard SGR text effects.
  *
  * @remarks
  * Style as data: an `Attribute` is a name. The ANSI renderer maps each to its SGR
@@ -115,16 +119,16 @@ export declare const ATTRIBUTES: readonly Attribute[];
 export declare const BACKGROUND_CODES: Readonly<Record<Exclude<Color, 'default'>, number>>;
 
 /**
- * Holds 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 through {@link import('./types.js').BarOptions}`.empty`.
+ * Holds 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 through {@link import('./types.js').BarOptions.empty}.
  */
 export declare const BAR_EMPTY = "\u2591";
 
 /**
- * Holds 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
- * through {@link import('./types.js').BarOptions}`.fill`.
+ * Holds 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 through {@link import('./types.js').BarOptions.fill}.
  */
 export declare const BAR_FILL = "\u2588";
 
@@ -155,14 +159,17 @@ export declare interface BarOptions {
     readonly style?: Style;
 }
 
-/** Holds the BEL control character (`U+0007`) that can terminate an OSC sequence. */
+/** Holds the bell control character (`U+0007`) that can terminate an OSC sequence. */
 export declare const BEL: string;
 
 /**
  * Holds 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.
+ * Unicode box-drawing glyphs at each line weight, deeply frozen.
+ *
+ * @remarks
+ * 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.
  *
  * @remarks
  * `round` shares `single`'s edges and tees — only its corners differ (the rounded `╭╮╰╯`).
@@ -170,10 +177,13 @@ export declare const BEL: string;
 export declare const BORDER_CHARS: Readonly<Record<BorderStyle, BorderChars>>;
 
 /**
- * Represents 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.
+ * Represents one complete box-drawing junction set for a {@link BorderStyle} — the edges, the
+ * corners, and the `T` / cross junctions the box and table renderers need to frame content and
+ * rule a table.
+ *
+ * @remarks
+ * 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.
@@ -198,12 +208,13 @@ export declare interface BorderChars {
 }
 
 /**
- * Names 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.
+ * Names a box-drawing border style — `single` / `double` / `round` / `heavy`, the standard
+ * Unicode line weights the renderers frame with, each selecting a full junction set in
+ * {@link BORDER_CHARS}.
  *
  * @remarks
+ * A named, fixed set (an external-spec value family) rather than a toggle, so it stays a union.
+ *
  * `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`.
@@ -211,8 +222,8 @@ export declare interface BorderChars {
 export declare type BorderStyle = 'single' | 'double' | 'round' | 'heavy';
 
 /**
- * Configures {@link import('./helpers.js').renderBox} — content framed in box-drawing
- * characters.
+ * Configures {@link import('./helpers.js').renderBox} — content framed in box-drawing characters. A
+ * `Reporter` supplies its own chrome style only when the caller gives neither `styler` nor `style`.
  *
  * @remarks
  * - `content` — the body text; embedded newlines split it into lines, each framed on its own
@@ -286,7 +297,8 @@ export declare class Capture implements CaptureInterface {
 /**
  * Maps each {@link CaptureLevel} to its {@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` /
+ * import('./types.js').SinkInterface}. `sink.write(text, CAPTURE_LEVEL_MAP[level])` is the call
+ * this map backs. `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.
@@ -323,13 +335,13 @@ export declare interface CapturedMessage {
 }
 
 /**
- * Declares the observable events a {@link CaptureInterface} emits.
+ * Declares the observable events a {@link CaptureInterface} emits — `capture(message)` per
+ * intercepted call, plus the `start` and `stop` lifecycle signals.
  *
  * @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
+ * - `capture` — 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` — `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 (for example log that capture is engaged). They earn their place by
@@ -380,7 +392,10 @@ export declare interface CaptureInterface {
     start(): void;
     /** Restores the snapshot-original `console.*` — a no-op when not `active`. */
     stop(): void;
-    /** Returns a copy of the whole captured buffer, oldest first (capped at `limit`). */
+    /**
+     * Returns a copy of the whole captured buffer, oldest first (capped at `limit`), or — given
+     * a {@link CaptureLevel} — a copy of only that level's bucket.
+     */
     messages(): readonly CapturedMessage[];
     /** Returns a copy of the captured buffer for one {@link CaptureLevel}, oldest first (capped at `limit`). */
     messages(level: CaptureLevel): readonly CapturedMessage[];
@@ -391,12 +406,13 @@ export declare interface CaptureInterface {
 }
 
 /**
- * Identifies 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.
+ * Identifies one intercepted `console` method — `log` / `info` / `warn` / `error` / `debug`, the
+ * names a {@link CaptureInterface} patches and reports under.
  *
  * @remarks
+ * A named value family (it indexes {@link CAPTURE_LEVEL_MAP} to a {@link LogLevel} for the
+ * optional sink forward) rather than a binary toggle, so it stays a union.
+ *
  * 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),
@@ -406,7 +422,9 @@ export declare interface CaptureInterface {
 export declare type CaptureLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
 
 /**
- * Configures the {@link import('./Capture.js').Capture} constructor.
+ * Configures the {@link import('./Capture.js').Capture} constructor — the `on` / `error` emitter
+ * keys, the `levels` intercepted, the `mirror` pass-through, the `sink` forward, and the buffer
+ * `limit`.
  *
  * @remarks
  * - `on` — the reserved {@link EmitterHooks} key: initial listeners for the
@@ -438,8 +456,8 @@ export declare interface CaptureOptions {
 }
 
 /**
- * Represents the structured outcome of {@link import('./factories.js').createCaptureResult} — the wrapped function's
- * own return `value` plus the {@link CapturedMessage}s intercepted while it ran.
+ * Represents the structured outcome of {@link import('./factories.js').createCaptureResult} — the
+ * wrapped function's own return `value` plus the `messages` it logged while it ran.
  *
  * @remarks
  * - `value` — whatever the wrapped `fn` returned (its `T`).
@@ -497,12 +515,12 @@ export declare interface ColumnSpec {
 }
 
 /**
- * Represents an error thrown by the console layer.
+ * Carries a {@link ConsoleErrorCode} and an optional `context` bag — the error the console layer
+ * throws for an internal invariant violated at a defensive guard.
  *
  * @remarks
- * Carries a {@link ConsoleErrorCode} and an optional `context` bag. Thrown for: an
- * internal invariant violated at a defensive, structurally-unreachable guard
- * (`INVARIANT`).
+ * `INVARIANT` is the code for a guard that is structurally unreachable, so a `catch` branches on
+ * `error.code` rather than parsing the message.
  */
 export declare class ConsoleError extends Error {
     readonly code: ConsoleErrorCode;
@@ -511,11 +529,12 @@ export declare class ConsoleError extends Error {
 }
 
 /**
- * Names a machine-readable error code for a {@link import('./errors.js').ConsoleError}.
+ * Names the machine-readable error code a {@link import('./errors.js').ConsoleError} carries —
+ * `INVARIANT`, the only code the package throws.
  *
  * @remarks
- * `INVARIANT` — an internal invariant or unreachable guard was violated (a defensive check that is
- * structurally impossible to trip). It is the only code the package throws.
+ * `INVARIANT` reports that an internal invariant or unreachable guard was violated — a defensive
+ * check that is structurally impossible to trip.
  */
 export declare type ConsoleErrorCode = 'INVARIANT';
 
@@ -635,10 +654,13 @@ export declare function createCaptureResult<T>(fn: () => T, options?: CaptureOpt
 export declare function createConsoleSink(): SinkInterface;
 
 /**
- * Creates 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 import('./types.js').RendererInterface} (the ANSI default), so
- * `styler.red.bold('hi')` yields styled text. Chains are immutable, so a base styler is freely reusable.
+ * Creates the fluent, composable {@link StylerInterface} — ANSI by default, retargeted by a
+ * `renderer` and stripped of color by `enabled: false`.
+ *
+ * @remarks
+ * It builds a {@link import('./types.js').Style} under the hood and renders it through a
+ * {@link import('./types.js').RendererInterface}, 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}
@@ -702,11 +724,14 @@ export declare const CSI: string;
 export declare const DEFAULT_ALIGN: Alignment;
 
 /**
- * Sets 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 through
- * `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.
+ * Sets the default visible cell count of a progress-bar track — the glyph run
+ * {@link import('./helpers.js').renderBar} fills, and the width a
+ * {@link import('./types.js').ProgressInterface} sizes its bar to. `30` cells.
+ *
+ * @remarks
+ * Thirty cells is a compact, terminal-friendly default; a consumer overrides it through
+ * `options.width`. It is 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;
 
@@ -714,11 +739,13 @@ export declare const DEFAULT_BAR_WIDTH = 30;
 export declare const DEFAULT_BORDER: BorderStyle;
 
 /**
- * Sets 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 through `options.limit`.
+ * Sets the default bounded-buffer cap for a {@link import('./types.js').CaptureInterface} — `1000`,
+ * so at most that many recent {@link CapturedMessage}s are retained per buffer (the total buffer
+ * and each by-level bucket; oldest dropped first) and retention is always bounded.
+ *
+ * @remarks
+ * A long-running capture can never grow without bound (the same retention precedent as
+ * {@link DEFAULT_LOG_LIMIT}); a consumer overrides the cap through `options.limit`.
  */
 export declare const DEFAULT_CAPTURE_LIMIT = 1000;
 
@@ -726,9 +753,12 @@ export declare const DEFAULT_CAPTURE_LIMIT = 1000;
 export declare const DEFAULT_LOG_LEVEL: LogLevel;
 
 /**
- * Sets 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 — the
- * oldest record is dropped after the cap is reached; a consumer overrides it through `options.limit`.
+ * Sets the default bounded-retention cap for a {@link import('./types.js').LoggerInterface} —
+ * `1000`, so at most that many recent records are kept and retention is always bounded.
+ *
+ * @remarks
+ * The oldest record is dropped after the cap is reached; a consumer overrides the cap through
+ * `options.limit`.
  */
 export declare const DEFAULT_LOG_LIMIT = 1000;
 
@@ -736,16 +766,21 @@ export declare const DEFAULT_LOG_LIMIT = 1000;
 export declare const DEFAULT_PADDING = 1;
 
 /**
- * Sets 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 through `options.interval`.
+ * Sets the default timer period between a {@link import('./types.js').SpinnerInterface}'s frames —
+ * the `setInterval` interval `start()` arms, `80` ms (≈12.5 frames/second).
+ *
+ * @remarks
+ * That is the conventional spinner cadence: fast enough to read as motion, slow enough not to
+ * thrash a terminal. A consumer overrides it through `options.interval`.
  */
 export declare const DEFAULT_SPINNER_INTERVAL = 80;
 
 /**
- * Holds the default {@link Theme} — every role bound to its default {@link Style}, deeply frozen.
- * The base {@link import('./factories.js').createTheme} merges over, and the theme every
+ * Holds the default {@link Theme} — every role bound to its default {@link Style}, assembled from
+ * {@link LEVEL_COLORS}, {@link STATUS_ICONS}, and {@link STATUS_COLORS} and deeply frozen.
+ *
+ * @remarks
+ * It is the base {@link import('./factories.js').createTheme} merges over, and the theme every
  * entity uses when none is supplied.
  *
  * @remarks
@@ -762,7 +797,7 @@ export declare const DEFAULT_THEME: Theme;
  * Sets 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 through
- * {@link import('./types.js').ReporterOptions}`.width`.
+ * {@link import('./types.js').ReporterOptions.width}.
  */
 export declare const DEFAULT_WIDTH = 80;
 
@@ -774,7 +809,7 @@ export declare const DEFAULT_WIDTH = 80;
 export declare const EMPTY_STYLE: Style;
 
 /**
- * Holds the ESC control character (`U+001B`) that begins every ANSI escape sequence. Built
+ * Holds the escape 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;
@@ -864,7 +899,8 @@ export declare function formatRecord(record: LogRecord, styler: StylerInterface,
 export declare function formatTime(time: number): string;
 
 /**
- * Snapshots and deeply freezes one {@link Style} value.
+ * Snapshots and deeply freezes one {@link Style} value, including an independent frozen copy of
+ * its `attributes`.
  *
  * @param style - The caller-owned style to snapshot
  * @returns A frozen style record with an independently frozen attributes list
@@ -881,7 +917,7 @@ export declare function formatTime(time: number): string;
 export declare function freezeStyle(style: Style): Style;
 
 /**
- * Narrows an unknown caught value to a {@link ConsoleError}.
+ * Narrows an unknown caught value to a {@link ConsoleError} — the guard a `catch` branches on.
  *
  * @param value - The value to test (typically a `catch` binding)
  * @returns True if `value` is a {@link ConsoleError}; false otherwise
@@ -924,8 +960,9 @@ export declare const LEVEL_SEVERITY: Readonly<Record<LogLevel, number>>;
 export declare const LOG_LEVELS: readonly LogLevel[];
 
 /**
- * Represents the line layout a logger writes — one {@link LogRecord} plus the styling substrate in,
- * one finished line out. {@link import('./helpers.js').formatRecord} is the default.
+ * Represents the line layout a logger writes — `(record, styler, theme) => string`, one
+ * {@link LogRecord} plus the styling substrate in and one finished line out.
+ * {@link import('./helpers.js').formatRecord} is the default.
  *
  * @param record - The frozen record to lay out
  * @param styler - The logger's {@link StylerInterface} — color through it (and through
@@ -992,11 +1029,12 @@ export declare class Logger implements LoggerInterface {
 }
 
 /**
- * Declares the observable events a {@link LoggerInterface} emits — the transport seam.
+ * Declares the observable events a {@link LoggerInterface} emits — `entry(record)` for every
+ * accepted record, 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
+ * `entry` carries the frozen {@link LogRecord} and fires 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: a listener throw routes to the emitter's `error` handler, never onto
  * this map — so a buggy transport can never perturb logging.
@@ -1117,8 +1155,14 @@ export declare class LoggerManager implements LoggerManagerInterface {
  */
 export declare interface LoggerManagerInterface {
     readonly count: number;
+    /**
+     * Mints and stores a logger named `name`, the manager's defaults flowing in — a
+     * re-register of the same name overwrites.
+     */
     register(name: string, options?: LoggerOptions): LoggerInterface;
+    /** Looks one registered logger up by name. */
     logger(name: string): LoggerInterface | undefined;
+    /** Lists the registered loggers in insertion order. */
     loggers(): readonly LoggerInterface[];
     /** Fans out a `debug` log to every registered logger. */
     debug(message: string, data?: Record<string, unknown>): void;
@@ -1128,21 +1172,24 @@ export declare interface LoggerManagerInterface {
     warn(message: string, data?: Record<string, unknown>): void;
     /** Fans out an `error` log to every registered logger. */
     error(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Removes every registered logger with `remove()`, one with `remove(name)`, or a batch
+     * with `remove(names)`.
+     */
     remove(): void;
     remove(name: string): boolean;
     remove(names: readonly string[]): boolean;
 }
 
 /**
- * Configures the {@link import('./loggers/LoggerManager.js').LoggerManager} constructor.
+ * Configures the {@link import('./loggers/LoggerManager.js').LoggerManager} constructor — the
+ * `level` / `sink` / `styler` / `theme` / `format` / `limit` / `silent` defaults flowed into every
+ * logger it mints.
  *
  * @remarks
  * The manager is an event-free registry — 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), `theme` (semantic styles), `format` (line layout), `limit` (retention cap),
- * and `silent`.
+ * registered {@link LoggerInterface} owns its observable `emitter`). A per-`register`
+ * override wins over any default supplied here.
  */
 export declare interface LoggerManagerOptions {
     readonly level?: LogLevel;
@@ -1155,7 +1202,9 @@ export declare interface LoggerManagerOptions {
 }
 
 /**
- * Configures the {@link import('./loggers/Logger.js').Logger} constructor.
+ * Configures the {@link import('./loggers/Logger.js').Logger} constructor — the `on` / `error`
+ * emitter keys, the `level` threshold, the logger's `name`, the `sink` / `styler` / `theme` /
+ * `format` line substrate, the retention `limit`, and the `silent` write switch.
  *
  * @remarks
  * - `on` — the reserved {@link EmitterHooks} key: initial listeners for the
@@ -1191,21 +1240,21 @@ export declare interface LoggerOptions {
 }
 
 /**
- * Names the severity level of a {@link LogRecord} — one coherent, ascending-severity scale.
+ * Names the severity level of a {@link LogRecord} — one coherent, ascending scale, `debug` <
+ * `info` < `warn` < `error`, that a {@link LoggerInterface} gates by threshold.
  *
  * @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
+ * 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';
 
 /**
- * Represents 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.
+ * Represents one immutable, serializable log entry. 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}.
@@ -1250,9 +1299,9 @@ export declare interface LogRecord {
 export declare function meetsLevel(threshold: LogLevel, level: LogLevel): boolean;
 
 /**
- * Colors `text` through `styler`, or returns it verbatim when `styler` is `undefined` — the
- * single optional-styling primitive every renderer applies to its border / title / connector
- * glyphs (the one styler seam, shared, never re-hand-rolled per renderer).
+ * Colors `text` through `styler` and an optional by-value {@link Style}, or returns it verbatim
+ * when `styler` is `undefined` — the single optional-styling primitive every renderer applies to
+ * its border / title / connector glyphs.
  *
  * @remarks
  * The renderers all take an optional `styler`: present ⇒ glyphs are colored, absent ⇒ plain.
@@ -1270,13 +1319,16 @@ export declare function paint(styler: StylerInterface | undefined, text: string,
 
 /**
  * Implements an update-driven, observable progress bar — {@link update} recomputes the bar through
- * {@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 TTY sink) redraws on; a
- * plain sink 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.
+ * {@link renderBar}, writes `\r` + bar to its {@link SinkInterface}, and emits the `{ current,
+ * total }` on `update`. No self-timer, unlike {@link import('./Spinner.js').Spinner} — the caller
+ * drives it.
  *
  * @remarks
+ * The leading `\r` is what an overwrite-capable sink (the TTY sink) redraws on; a plain sink
+ * 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`.
+ *
  * - **Update-driven.** Each {@link update} clamps `current` to `[0, total]`, renders the bar (filled
  *   to `current / total`, with the trailing `percent (current/total)` + message) through {@link renderBar},
  *   emits `update`, and writes `'\r' + bar`. Progress advances only when the caller reports it.
@@ -1311,10 +1363,11 @@ export declare class Progress implements ProgressInterface {
 }
 
 /**
- * Declares the observable events a {@link ProgressInterface} emits.
+ * Declares the observable events a {@link ProgressInterface} emits — `update(progress)` per
+ * report, plus a `succeed` signal on a successful finish.
  *
  * @remarks
- * - `update` — the core event: fires on every `update(current)` (and on `succeed` / `fail`),
+ * - `update` — fires on every `update(current)` (and on `succeed` / `fail`),
  *   carrying the `{ current, total }` progress (the clamped `current`). The hook a non-sink consumer
  *   rides to observe progress without a terminal.
  * - `succeed` — the terminal signal: fires once from `succeed()` (a successful finish), a pure
@@ -1335,9 +1388,10 @@ export declare type ProgressEventMap = {
 
 /**
  * Declares an update-driven, observable progress bar — `update(current)` recomputes the bar through
- * {@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.
+ * {@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
@@ -1362,7 +1416,10 @@ export declare interface ProgressInterface {
     readonly current: number;
     /** Holds the target value the bar fills toward. */
     readonly total: number;
-    /** Reports progress: clamps `current`, re-renders the bar, emits `update`, writes `\r` + bar. Ignored once terminal. */
+    /**
+     * Reports progress: clamps `current`, re-renders the bar, emits `update`, writes `\r` + bar.
+     * Ignored after a terminal `succeed` or `fail`.
+     */
     update(current: number, message?: string): void;
     /** Finishes successfully — renders a full bar + newline, emits a final `update` then `succeed`. */
     succeed(message?: string): void;
@@ -1373,7 +1430,9 @@ export declare interface ProgressInterface {
 }
 
 /**
- * Configures the {@link import('./Progress.js').Progress} constructor.
+ * Configures the {@link import('./Progress.js').Progress} constructor — the `on` / `error` emitter
+ * keys, the required `total`, the `message` shown, the bar's `width` / `fill` / `empty` glyphs, and
+ * the `sink` / `styler` / `theme` line substrate.
  *
  * @remarks
  * - `on` — the reserved {@link EmitterHooks} key: initial listeners for the
@@ -1407,8 +1466,8 @@ export declare interface ProgressOptions {
 }
 
 /**
- * Reports one advance of a {@link ProgressInterface} — the clamped `{ current, total }` payload
- * carried by the `update` event of {@link ProgressEventMap}.
+ * Reports one advance of a {@link ProgressInterface} — the clamped payload carried by the `update`
+ * event of {@link ProgressEventMap}.
  *
  * @remarks
  * `current` is always the value after clamping into `[0, total]`, so a listener never sees an
@@ -1423,12 +1482,15 @@ export declare interface ProgressReport {
 
 /**
  * Renders 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 BarOptions} →
- * same string. The animation-layer sibling of the `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.
+ * and the `(current/total)` count (`█████░░░░░ 50% (5/10)`). Pure and width-aware: same
+ * {@link BarOptions} → same string.
  *
  * @remarks
+ * It is the animation-layer sibling of the `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.
+ *
  * - **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).
@@ -1542,8 +1604,8 @@ export declare function renderSeparator(options: SeparatorOptions): string;
 export declare function renderTable(options: TableOptions): string;
 
 /**
- * Renders a nested {@link TreeNode} tree with box-drawing connectors. Pure: same
- * {@link TreeOptions} → same string.
+ * Renders a nested {@link TreeNode} tree whose connectors derive from the chosen `border` set.
+ * Pure: same {@link TreeOptions} → same string.
  *
  * @remarks
  * The `root` label is the unindented first line; its descendants are drawn beneath it with
@@ -1567,10 +1629,14 @@ export declare function renderTable(options: TableOptions): string;
 export declare function renderTree(options: TreeOptions): string;
 
 /**
- * Renders 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).
+ * Renders the connector-prefixed lines for a {@link TreeNode} list — the recursive core behind
+ * {@link renderTree}, whose third options argument requires `border` and groups the optional
+ * `styler` and `style`.
+ *
+ * @remarks
+ * 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 so it is directly testable and
@@ -1695,7 +1761,9 @@ export declare interface ReporterInterface {
 }
 
 /**
- * Configures the {@link import('./Reporter.js').Reporter} constructor.
+ * Configures the {@link import('./Reporter.js').Reporter} constructor — the `sink` every line is
+ * written to, the `styler` and `theme` it formats through, and the `width` its layouts measure
+ * against.
  *
  * @remarks
  * - `sink` — where every formatted line is written; defaults to
@@ -1727,7 +1795,8 @@ export declare const RESET: string;
 export declare const RESET_CODE = 0;
 
 /**
- * Implements the bounded, level-keyed retention engine both captures buffer through — one capped total buffer
+ * Implements the bounded, level-keyed retention engine the console and process captures buffer
+ * through — one capped total buffer
  * plus one capped bucket per level, generic over the record type each capture carries.
  *
  * @remarks
@@ -1781,9 +1850,15 @@ export declare class Retention<T extends {
 export declare interface RetentionInterface<T extends {
     readonly level: string;
 }> {
-    /** Retains one record — appends it to the total buffer and to its level's bucket, evicting the oldest of each past the cap. */
+    /**
+     * Retains one record — appends it to the total buffer and to its level's bucket, evicting the
+     * oldest of each past `limit`.
+     */
     add(record: T): void;
-    /** Returns a copy of the whole retained buffer, oldest first. */
+    /**
+     * Returns a copy of the whole retained buffer, oldest first, or — given a level — a copy of
+     * that level's bucket, empty for a level with no bucket.
+     */
     records(): readonly T[];
     /** Returns a copy of one level's bucket, oldest first; empty for a level with no bucket. */
     records(level: T['level']): readonly T[];
@@ -1792,9 +1867,9 @@ export declare interface RetentionInterface<T extends {
 }
 
 /**
- * Sets 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.
+ * Sets the millisecond threshold 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
+ * — `1000`, exactly one second.
  */
 export declare const SECOND_MS = 1000;
 
@@ -1835,7 +1910,7 @@ export declare const SEPARATOR_TITLE_GAP = " ";
 
 /**
  * Configures {@link import('./helpers.js').renderSeparator} — a horizontal rule, optionally
- * carrying a centered title.
+ * carrying a centered title. Every key is optional.
  *
  * @remarks
  * - `title` — text to embed in the rule (for example a section heading). Omitted ⇒ an unbroken line.
@@ -1873,13 +1948,15 @@ export declare interface SeparatorOptions {
  */
 export declare interface SinkInterface {
     /**
-     * Writes one already-formatted chunk of output. `text` receives one line without its
-     * terminator — the sink's target supplies it (for example `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), written verbatim. A tick frame carries no
-     * terminator; a final frame carries its own.
-     * `level` is the originating record's {@link LogLevel} — supplied so a stream-aware sink
-     * can route (for example `error` to `stderr`); a plain sink ignores it.
+     * Writes one already-formatted chunk of output — one line without its terminator, or a
+     * `\r`-leading redraw frame written verbatim, routed by the optional `level`.
+     *
+     * @remarks
+     * The sink's target supplies the terminator (for example `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). A tick frame carries no terminator; a final frame
+     * carries its own. `level` is the originating record's {@link LogLevel} — supplied so a
+     * stream-aware sink can route (for example `error` to `stderr`); a plain sink ignores it.
      */
     write(text: string, level?: LogLevel): void;
 }
@@ -1887,12 +1964,14 @@ export declare interface SinkInterface {
 /**
  * Implements a self-driving, observable activity spinner — 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 TTY sink) redraws on; a plain
- * sink 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`.
+ * `frame`. The timer is always cleared on an outcome, so the spinner is leak-free.
  *
  * @remarks
+ * The leading `\r` is what an overwrite-capable sink (the TTY sink) redraws on; a plain sink
+ * 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`.
+ *
  * - **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
@@ -1935,21 +2014,25 @@ export declare class Spinner implements SpinnerInterface {
 }
 
 /**
- * Holds 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 through `options.frames`.
+ * Holds the default spinner frame cycle a {@link import('./types.js').SpinnerInterface} advances
+ * through — the braille-pattern glyphs (`⠋⠙⠹…`, the U+2800 block) that read as a smoothly rotating
+ * dot.
  *
  * @remarks
+ * The cycle is the universal terminal-spinner convention. Frozen; a consumer swaps the whole
+ * cycle through `options.frames`.
+ *
  * 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[];
 
 /**
- * Declares the observable events a {@link SpinnerInterface} emits.
+ * Declares the observable events a {@link SpinnerInterface} emits — `frame(line)` per advance and
+ * per outcome, plus the `start` and `stop` timer-lifecycle signals.
  *
  * @remarks
- * - `frame` — the core event: fires once per advance (every `tick()`, whether driven by the internal
+ * - `frame` — fires once per advance (every `tick()`, whether driven by the internal
  *   timer or called directly) and on the final `succeed` / `fail` 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.
@@ -2018,7 +2101,9 @@ export declare interface SpinnerInterface {
 }
 
 /**
- * Configures the {@link import('./Spinner.js').Spinner} constructor.
+ * Configures the {@link import('./Spinner.js').Spinner} constructor — the `on` / `error` emitter
+ * keys, the `message` shown, the glyph `frames` and their `interval`, and the `sink` / `styler` /
+ * `theme` line substrate.
  *
  * @remarks
  * - `on` — the reserved {@link EmitterHooks} key: initial listeners for the
@@ -2072,8 +2157,9 @@ export declare const STATUS_ICONS: Readonly<Record<StatusLevel, string>>;
 export declare const STATUS_LEVELS: readonly StatusLevel[];
 
 /**
- * Names a narrative outcome level — the four states {@link ReporterInterface.status} reports, each
- * with its own icon + color ({@link STATUS_ICONS} / {@link STATUS_COLORS}).
+ * Names a narrative outcome level — `success` / `error` / `warn` / `info`, the 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
@@ -2085,8 +2171,8 @@ export declare const STATUS_LEVELS: readonly StatusLevel[];
 export declare type StatusLevel = 'success' | 'error' | 'warn' | 'info';
 
 /**
- * Represents where one step sits in a sequence — the `{ index, total }` a
- * {@link ReporterInterface.step} renders as a `[2/5]` prefix.
+ * Represents where one step sits in a sequence — what {@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
@@ -2151,7 +2237,8 @@ export declare function strip(text: string): string;
 
 /**
  * Removes every non-printing C0 control character from `text` except `\t` / `\n` / `\r`
- * (meaningful whitespace), plus DEL — returning the sanitized string.
+ * (meaningful whitespace), plus DEL — a separate pass from {@link strip}, so `width` stays
+ * untouched.
  *
  * @remarks
  * Deliberately separate from {@link strip} (ANSI-escape removal only, so `width` /
@@ -2262,14 +2349,15 @@ export declare interface StylerInterface {
 }
 
 /**
- * Configures {@link createStyler}.
+ * Configures {@link createStyler} — `renderer` selects the output target, defaulting to the ANSI
+ * renderer, and `enabled` is the no-color switch, defaulting to `true`.
  *
  * @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 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`.
+ * - `renderer` — the {@link RendererInterface} every style renders through, so the styler
+ *   works unchanged in any terminal. Inject a browser `%c` renderer to retarget with no
+ *   other change.
+ * - `enabled` — when `false`, the styler returns text verbatim, for a non-TTY, a
+ *   `NO_COLOR` environment, or piped output.
  */
 export declare interface StylerOptions {
     readonly renderer?: RendererInterface;
@@ -2277,8 +2365,9 @@ export declare interface StylerOptions {
 }
 
 /**
- * Configures {@link import('./helpers.js').renderTable} — a bordered grid of columns + rows
- * with per-column alignment and width-aware sizing.
+ * Configures {@link import('./helpers.js').renderTable} — a bordered grid of columns + rows with
+ * per-column alignment and width-aware sizing. A `Reporter` supplies its own chrome style only when
+ * the caller gives neither `styler` nor `style`.
  *
  * @remarks
  * - `columns` — the {@link ColumnSpec}s, left to right; their `label`s form the header row.
@@ -2300,9 +2389,8 @@ export declare interface TableOptions {
 }
 
 /**
- * Represents the app-wide semantic style vocabulary — every role the console system styles, bound to a
- * {@link Style} value. Pass one theme to a logger / reporter / spinner / progress and every
- * surface speaks it.
+ * Represents the app-wide semantic style vocabulary — each role bound to a {@link Style} value.
+ * Pass one theme to a logger / reporter / spinner / progress and every surface speaks it.
  *
  * @remarks
  * - `levels` — the label style per {@link LogLevel} (a log line's severity label).
@@ -2325,14 +2413,14 @@ export declare interface Theme {
 }
 
 /**
- * Holds the options for {@link createTheme} — the roles to override on {@link DEFAULT_THEME}.
+ * Holds the options for {@link createTheme} — the roles to override on {@link DEFAULT_THEME}, a
+ * status supplying its whole copied `{ icon, style }` record.
  *
  * @remarks
  * Every key is optional and merges per role, never per theme: an omitted role keeps its
  * default, and `levels` / `statuses` merge per entry, so `{ levels: { warn: … } }` restyles
- * the `warn` label and leaves `debug`, `info`, and `error` alone. A status override supplies its whole
- * `{ icon, style }` record; {@link createTheme} snapshots and freezes that record and every
- * style leaf it receives.
+ * the `warn` label and leaves `debug`, `info`, and `error` alone. {@link createTheme}
+ * snapshots and freezes each status record and every style leaf it receives.
  */
 export declare interface ThemeOptions {
     readonly levels?: Readonly<Partial<Record<LogLevel, Style>>>;
@@ -2369,8 +2457,9 @@ export declare interface TreeNode {
 }
 
 /**
- * Configures {@link import('./helpers.js').renderTree} — a nested {@link TreeNode} tree drawn
- * with box-drawing connectors.
+ * Configures {@link import('./helpers.js').renderTree} — a nested {@link TreeNode} tree drawn with
+ * box-drawing connectors. A `Reporter` supplies its own chrome style only when the caller gives
+ * neither `styler` nor `style`.
  *
  * @remarks
  * - `root` — the top {@link TreeNode}; its `label` is the unindented first line and its
@@ -2410,8 +2499,8 @@ export declare interface TreeOptions {
 export declare function width(text: string): number;
 
 /**
- * Groups the three write targets a level-routing sink chooses between — the normal target, the
- * warning target, and the error target.
+ * Groups the write targets a level-routing sink chooses between — each of the backend's own member
+ * type.
  *
  * @remarks
  * The member type is the sink's own: a bound `console` method in core, a browser `%c` console