@orkestrel/console 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,2105 @@
+import { Emitter } from "@orkestrel/emitter";
+import { isArray } from "@orkestrel/contract";
+//#region src/core/constants.ts
+/**
+* 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).
+*/
+var FOREGROUND_CODES = Object.freeze({
+	black: 30,
+	red: 31,
+	green: 32,
+	yellow: 33,
+	blue: 34,
+	magenta: 35,
+	cyan: 36,
+	white: 37,
+	brightBlack: 90,
+	brightRed: 91,
+	brightGreen: 92,
+	brightYellow: 93,
+	brightBlue: 94,
+	brightMagenta: 95,
+	brightCyan: 96,
+	brightWhite: 97
+});
+/**
+* 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).
+*/
+var BACKGROUND_CODES = Object.freeze({
+	black: 40,
+	red: 41,
+	green: 42,
+	yellow: 43,
+	blue: 44,
+	magenta: 45,
+	cyan: 46,
+	white: 47,
+	brightBlack: 100,
+	brightRed: 101,
+	brightGreen: 102,
+	brightYellow: 103,
+	brightBlue: 104,
+	brightMagenta: 105,
+	brightCyan: 106,
+	brightWhite: 107
+});
+/**
+* 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.
+*/
+var ATTRIBUTE_CODES = Object.freeze({
+	bold: 1,
+	dim: 2,
+	italic: 3,
+	underline: 4,
+	inverse: 7,
+	strikethrough: 9
+});
+/**
+* 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.
+*/
+var EMPTY_STYLE = Object.freeze({ attributes: Object.freeze([]) });
+/**
+* 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.
+*/
+var COLORS = Object.freeze([
+	"black",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"magenta",
+	"cyan",
+	"white",
+	"brightBlack",
+	"brightRed",
+	"brightGreen",
+	"brightYellow",
+	"brightBlue",
+	"brightMagenta",
+	"brightCyan",
+	"brightWhite"
+]);
+/**
+* Every {@link Attribute}, frozen — the attributes the styler exposes as chainable
+* accessors. The source of truth for the attribute axis.
+*/
+var ATTRIBUTES = Object.freeze([
+	"bold",
+	"dim",
+	"italic",
+	"underline",
+	"inverse",
+	"strikethrough"
+]);
+/** The SGR RESET parameter (0) — terminates a styled run, clearing all colors and attributes. */
+var RESET_CODE = 0;
+/**
+* The ESC control character (`U+001B`) that begins every ANSI escape sequence. Built
+* with `String.fromCharCode` so no raw control character appears in source.
+*/
+var ESC = String.fromCharCode(27);
+/** The BEL control character (`U+0007`) that can terminate an OSC sequence. */
+var BEL = String.fromCharCode(7);
+/** The Control Sequence Introducer (`ESC[`) that opens every SGR sequence. */
+var CSI = `[`;
+/** The full SGR reset sequence (`ESC[0m`) appended after a styled run. */
+var RESET = `${CSI}0m`;
+/**
+* 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).
+*/
+var ANSI_PATTERN = new RegExp(`(?:\\[[0-?]*[ -/]*[@-~]|\\][^]*(?:|\\\\)|[P^_X][^]*(?:|\\\\)|[ -/]+[0-~]|[0-?]|[@-OQ-WYZ\\\\]|[\`-~])`, "g");
+/**
+* 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.
+*/
+var CONTROL_PATTERN = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCode(8)}${String.fromCharCode(11)}${String.fromCharCode(12)}${String.fromCharCode(14)}-${String.fromCharCode(31)}${String.fromCharCode(127)}]`, "g");
+/**
+* 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.
+*/
+var LEVEL_SEVERITY = Object.freeze({
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+});
+/**
+* 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.
+*/
+var LEVEL_COLORS = Object.freeze({
+	debug: "cyan",
+	info: "blue",
+	warn: "yellow",
+	error: "red"
+});
+/**
+* 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`.
+*/
+var DEFAULT_LOG_LIMIT = 1e3;
+/** The default {@link LogLevel} threshold a logger gates at when none is supplied — `info`. */
+var DEFAULT_LOG_LEVEL = "info";
+/**
+* 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}.
+*/
+var LEVELS = Object.freeze([
+	"debug",
+	"info",
+	"warn",
+	"error"
+]);
+/**
+* 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 `╭╮╰╯`).
+*/
+var BORDER_CHARS = Object.freeze({
+	single: Object.freeze({
+		horizontal: "─",
+		vertical: "│",
+		topLeft: "┌",
+		topRight: "┐",
+		bottomLeft: "└",
+		bottomRight: "┘",
+		cross: "┼",
+		teeDown: "┬",
+		teeUp: "┴",
+		teeRight: "├",
+		teeLeft: "┤"
+	}),
+	double: Object.freeze({
+		horizontal: "═",
+		vertical: "║",
+		topLeft: "╔",
+		topRight: "╗",
+		bottomLeft: "╚",
+		bottomRight: "╝",
+		cross: "╬",
+		teeDown: "╦",
+		teeUp: "╩",
+		teeRight: "╠",
+		teeLeft: "╣"
+	}),
+	round: Object.freeze({
+		horizontal: "─",
+		vertical: "│",
+		topLeft: "╭",
+		topRight: "╮",
+		bottomLeft: "╰",
+		bottomRight: "╯",
+		cross: "┼",
+		teeDown: "┬",
+		teeUp: "┴",
+		teeRight: "├",
+		teeLeft: "┤"
+	}),
+	heavy: Object.freeze({
+		horizontal: "━",
+		vertical: "┃",
+		topLeft: "┏",
+		topRight: "┓",
+		bottomLeft: "┗",
+		bottomRight: "┛",
+		cross: "╋",
+		teeDown: "┳",
+		teeUp: "┻",
+		teeRight: "┣",
+		teeLeft: "┫"
+	})
+});
+/**
+* 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.
+*/
+var STATUS_ICONS = Object.freeze({
+	success: "✔",
+	error: "✖",
+	warn: "⚠",
+	info: "ℹ"
+});
+/**
+* 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.
+*/
+var STATUS_COLORS = Object.freeze({
+	success: "green",
+	error: "red",
+	warn: "yellow",
+	info: "blue"
+});
+/**
+* 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}.
+*/
+var STATUS_LEVELS = Object.freeze([
+	"success",
+	"error",
+	"warn",
+	"info"
+]);
+/**
+* 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.
+*/
+var TREE_CHARS = Object.freeze({
+	branch: "├─ ",
+	corner: "└─ ",
+	guide: "│  ",
+	gap: "   "
+});
+/**
+* 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`.
+*/
+var DEFAULT_WIDTH = 80;
+/** The default horizontal padding inside a box's edges ({@link import('./helpers.js').renderBox}) — one cell. */
+var DEFAULT_PADDING = 1;
+/** The default {@link BorderStyle} the box / table renderers frame with when none is given — `single`. */
+var DEFAULT_BORDER = "single";
+/** The default cell {@link Alignment} a {@link import('./types.js').ColumnSpec} uses when none is given — `left`. */
+var DEFAULT_ALIGN = "left";
+/** The default fill character {@link import('./helpers.js').renderSeparator} draws its rule with — `─`. */
+var SEPARATOR_FILL = "─";
+/**
+* The single padding cell on each side of a separator's embedded title (` title `) — keeps the
+* title from butting against the rule. One space.
+*/
+var SEPARATOR_TITLE_GAP = " ";
+/**
+* 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.
+*/
+var SECOND_MS = 1e3;
+/**
+* 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`.
+*/
+var CAPTURE_LEVELS = Object.freeze([
+	"log",
+	"info",
+	"warn",
+	"error",
+	"debug"
+]);
+/**
+* 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`.
+*/
+var DEFAULT_CAPTURE_LEVELS = CAPTURE_LEVELS;
+/**
+* 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`.
+*/
+var DEFAULT_CAPTURE_LIMIT = 1e3;
+/**
+* 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.
+*/
+var CAPTURE_LEVEL_MAP = Object.freeze({
+	log: "info",
+	info: "info",
+	warn: "warn",
+	error: "error",
+	debug: "debug"
+});
+/**
+* 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.
+*/
+var SPINNER_FRAMES = Object.freeze([
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+]);
+/**
+* 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`.
+*/
+var DEFAULT_SPINNER_INTERVAL = 80;
+/**
+* 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`.
+*/
+var BAR_FILL = "█";
+/**
+* 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`.
+*/
+var BAR_EMPTY = "░";
+/**
+* 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.
+*/
+var DEFAULT_BAR_WIDTH = 30;
+//#endregion
+//#region src/core/errors.ts
+/**
+* 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.
+*/
+var ConsoleError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "ConsoleError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* 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)
+* }
+* ```
+*/
+function isConsoleError(value) {
+	return value instanceof ConsoleError;
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* 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'
+* ```
+*/
+function strip(text) {
+	return text.replace(new RegExp(ANSI_PATTERN.source, ANSI_PATTERN.flags), "");
+}
+/**
+* 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'
+* ```
+*/
+function stripControls(text) {
+	return text.replace(new RegExp(CONTROL_PATTERN.source, CONTROL_PATTERN.flags), "");
+}
+/**
+* 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
+* ```
+*/
+function width(text) {
+	return [...strip(text)].length;
+}
+/**
+* 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
+* ```
+*/
+function meetsLevel(threshold, level) {
+	return LEVEL_SEVERITY[level] >= LEVEL_SEVERITY[threshold];
+}
+/**
+* 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
+*/
+function formatTime(time) {
+	return new Date(time).toISOString();
+}
+/**
+* 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'
+* ```
+*/
+function formatRecord(record, styler) {
+	const time = styler.dim(formatTime(record.time));
+	const label = styler[LEVEL_COLORS[record.level]](record.level.toUpperCase());
+	const name = record.name === void 0 ? "" : ` ${styler.dim(`[${record.name}]`)}`;
+	const data = record.data === void 0 || Object.keys(record.data).length === 0 ? "" : ` ${styler.dim(JSON.stringify(record.data))}`;
+	return `${time} ${label}${name} ${record.message}${data}`;
+}
+/**
+* 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  '
+* ```
+*/
+function align(text, target, alignment = DEFAULT_ALIGN) {
+	const visible = width(text);
+	if (visible > target) return [...strip(text)].slice(0, target).join("");
+	const deficit = target - visible;
+	if (alignment === "right") return `${" ".repeat(deficit)}${text}`;
+	if (alignment === "center") {
+		const left = Math.floor(deficit / 2);
+		return `${" ".repeat(left)}${text}${" ".repeat(deficit - left)}`;
+	}
+	return `${text}${" ".repeat(deficit)}`;
+}
+/**
+* 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'`)
+*/
+function formatDuration(ms) {
+	return ms < 1e3 ? `${ms}ms` : `${(ms / SECOND_MS).toFixed(2)}s`;
+}
+/**
+* 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
+*/
+function paint(styler, text) {
+	return styler === void 0 ? text : styler(text);
+}
+/**
+* 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) // '=-=-='
+* ```
+*/
+function repeatTo(unit, count) {
+	if (count <= 0) return "";
+	const per = width(unit);
+	if (per === 0) return "";
+	return [...unit.repeat(Math.ceil(count / per))].slice(0, count).join("");
+}
+/**
+* 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`
+*/
+function cellAt(row, index) {
+	return row[index] ?? "";
+}
+/**
+* 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)
+* ```
+*/
+function renderSeparator(options) {
+	const total = options.width ?? 80;
+	const fill = options.fill ?? "─";
+	if (options.title === void 0) return paint(options.styler, repeatTo(fill, total));
+	const gapped = ` ${paint(options.styler, options.title)} `;
+	const room = total - width(options.title) - 2;
+	if (room <= 0) return gapped;
+	const left = Math.floor(room / 2);
+	return `${paint(options.styler, repeatTo(fill, left))}${gapped}${paint(options.styler, repeatTo(fill, room - left))}`;
+}
+/**
+* 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`)
+*/
+function renderBox(options) {
+	const chars = BORDER_CHARS[options.border ?? "single"];
+	const padding = Math.max(0, Math.trunc(options.padding ?? 1));
+	const styler = options.styler;
+	const lines = options.content.split("\n");
+	const titleRoom = options.title === void 0 ? 0 : width(options.title) + 2 + 1 - padding * 2;
+	const budget = options.width === void 0 ? 0 : options.width - 2 - padding * 2;
+	const inner = lines.reduce((max, line) => Math.max(max, width(line)), Math.max(0, titleRoom, budget));
+	const gutter = " ".repeat(padding);
+	const bar = paint(styler, chars.vertical);
+	const boxTop = () => {
+		const span = inner + padding * 2;
+		if (options.title === void 0) return paint(styler, `${chars.topLeft}${repeatTo(chars.horizontal, span)}${chars.topRight}`);
+		const caption = ` ${options.title} `;
+		const room = span - width(caption);
+		const lead = paint(styler, repeatTo(chars.horizontal, 1));
+		const rest = room - 1 <= 0 ? "" : paint(styler, repeatTo(chars.horizontal, room - 1));
+		return `${paint(styler, chars.topLeft)}${lead}${paint(styler, caption)}${rest}${paint(styler, chars.topRight)}`;
+	};
+	const top = boxTop();
+	const bottom = paint(styler, `${chars.bottomLeft}${repeatTo(chars.horizontal, inner + padding * 2)}${chars.bottomRight}`);
+	return [
+		top,
+		...lines.map((line) => `${bar}${gutter}${align(line, inner)}${gutter}${bar}`),
+		bottom
+	].join("\n");
+}
+/**
+* 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`)
+*/
+function renderTable(options) {
+	const chars = BORDER_CHARS[options.border ?? "single"];
+	const styler = options.styler;
+	const columns = options.columns;
+	const widths = columns.map((column, index) => options.rows.reduce((max, row) => Math.max(max, width(cellAt(row, index))), width(column.label)));
+	const aligns = columns.map((column) => column.align ?? "left");
+	const tableRow = (cells) => {
+		const bar = paint(styler, chars.vertical);
+		return `${bar}${cells.map((cell, index) => ` ${align(cell, widths[index] ?? width(cell), aligns[index] ?? "left")} `).join(bar)}${bar}`;
+	};
+	const tableEdge = (left, mid, right) => {
+		const segments = widths.map((columnWidth) => repeatTo(chars.horizontal, columnWidth + 2));
+		return paint(styler, `${left}${segments.join(mid)}${right}`);
+	};
+	const header = tableRow(columns.map((column) => paint(styler, column.label)));
+	const body = options.rows.map((row) => tableRow(columns.map((_column, index) => cellAt(row, index))));
+	return [
+		tableEdge(chars.topLeft, chars.teeDown, chars.topRight),
+		header,
+		tableEdge(chars.teeRight, chars.cross, chars.teeLeft),
+		...body,
+		tableEdge(chars.bottomLeft, chars.teeUp, chars.bottomRight)
+	].join("\n");
+}
+/**
+* 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
+* ```
+*/
+function renderTree(options) {
+	return [options.root.label, ...renderTreeChildren(options.root.children ?? [], "", options.styler)].join("\n");
+}
+/**
+* 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']
+* ```
+*/
+function renderTreeChildren(nodes, prefix, styler) {
+	const lines = [];
+	nodes.forEach((node, index) => {
+		const last = index === nodes.length - 1;
+		lines.push(`${prefix}${paint(styler, last ? TREE_CHARS.corner : TREE_CHARS.branch)}${node.label}`);
+		const carry = `${prefix}${paint(styler, last ? TREE_CHARS.gap : TREE_CHARS.guide)}`;
+		lines.push(...renderTreeChildren(node.children ?? [], carry, styler));
+	});
+	return lines;
+}
+/**
+* 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]"}'
+* ```
+*/
+function stringifyValue(value) {
+	if (value instanceof Error) return `${value.name}: ${value.message}`;
+	if (value === null || typeof value !== "object") return String(value);
+	const seen = /* @__PURE__ */ new WeakSet();
+	try {
+		return JSON.stringify(value, (_key, nested) => {
+			if (nested !== null && typeof nested === "object") {
+				if (seen.has(nested)) return "[Circular]";
+				seen.add(nested);
+			}
+			return nested;
+		});
+	} catch {
+		return String(value);
+	}
+}
+/**
+* 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([]) // ''
+* ```
+*/
+function formatArgs(args) {
+	return args.map(stringifyValue).join(" ");
+}
+/**
+* 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)'
+* ```
+*/
+function renderBar(options) {
+	const track = options.width ?? 30;
+	const fill = options.fill ?? "█";
+	const empty = options.empty ?? "░";
+	const current = options.total <= 0 ? 0 : Math.max(0, Math.min(options.total, options.current));
+	const fraction = options.total <= 0 ? 1 : current / options.total;
+	const filledCells = Math.round(fraction * track);
+	return `${`${paint(options.styler, repeatTo(fill, filledCells))}${repeatTo(empty, track - filledCells)}`} ${Math.round(fraction * 100)}% (${current}/${options.total})`;
+}
+//#endregion
+//#region src/core/ANSIRenderer.ts
+/**
+* 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.
+*/
+var ANSIRenderer = class {
+	/**
+	* Wrap `text` in the SGR codes for `style`. Returns `text` unchanged when the style
+	* is empty or `text` is `''`.
+	*/
+	render(style, text) {
+		if (text === "") return text;
+		const codes = this.#codes(style);
+		if (codes.length === 0) return text;
+		return `${CSI}${codes.join(";")}m${text}${RESET}`;
+	}
+	#codes(style) {
+		const codes = [];
+		for (const attribute of style.attributes) codes.push(ATTRIBUTE_CODES[attribute]);
+		if (style.foreground !== void 0 && style.foreground !== "default") codes.push(FOREGROUND_CODES[style.foreground]);
+		if (style.background !== void 0 && style.background !== "default") codes.push(BACKGROUND_CODES[style.background]);
+		return codes;
+	}
+};
+//#endregion
+//#region src/core/Styler.ts
+/**
+* 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`.
+*/
+var Styler = class Styler {
+	#renderer;
+	#enabled;
+	#style;
+	constructor(renderer, enabled, style) {
+		this.#renderer = renderer;
+		this.#enabled = enabled;
+		this.#style = style;
+	}
+	/** The accumulated style DATA — the empty style on a base styler. */
+	get style() {
+		return this.#style;
+	}
+	/** Whether styling is applied; when `false`, the surface returns text unchanged. */
+	get enabled() {
+		return this.#enabled;
+	}
+	/**
+	* 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() {
+		const render = (text) => this.#enabled ? this.#renderer.render(this.#style, text) : text;
+		const descriptors = {
+			style: {
+				value: this.#style,
+				enumerable: true
+			},
+			enabled: {
+				value: this.#enabled,
+				enumerable: true
+			}
+		};
+		for (const color of COLORS) descriptors[color] = {
+			get: () => this.#foreground(color).surface,
+			enumerable: true
+		};
+		for (const attribute of ATTRIBUTES) descriptors[attribute] = {
+			get: () => this.#attribute(attribute).surface,
+			enumerable: true
+		};
+		const surface = Object.defineProperties(render, descriptors);
+		if (this.#isSurface(surface)) return surface;
+		throw new ConsoleError("INVARIANT", "console: styler surface construction is incomplete");
+	}
+	#isSurface(value) {
+		return typeof value === "function" && "style" in value && "enabled" in value && "red" in value && "bold" in value;
+	}
+	#foreground(color) {
+		return new Styler(this.#renderer, this.#enabled, Object.freeze({
+			...this.#style,
+			foreground: color
+		}));
+	}
+	#attribute(attribute) {
+		if (this.#style.attributes.includes(attribute)) return this;
+		return new Styler(this.#renderer, this.#enabled, Object.freeze({
+			...this.#style,
+			attributes: Object.freeze([...this.#style.attributes, attribute])
+		}));
+	}
+};
+//#endregion
+//#region src/core/Capture.ts
+/**
+* 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
+* ```
+*/
+var Capture = class {
+	#emitter;
+	#levels;
+	#mirror;
+	#sink;
+	#limit;
+	#messages = [];
+	#buckets = /* @__PURE__ */ new Map();
+	#originals = /* @__PURE__ */ new Map();
+	#active = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#levels = options?.levels ?? DEFAULT_CAPTURE_LEVELS;
+		this.#mirror = options?.mirror ?? false;
+		this.#sink = options?.sink;
+		this.#limit = options?.limit ?? 1e3;
+		for (const level of this.#levels) this.#buckets.set(level, []);
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get active() {
+		return this.#active;
+	}
+	start() {
+		if (this.#active) return;
+		this.#active = true;
+		const target = console;
+		for (const level of this.#levels) {
+			const original = target[level];
+			this.#originals.set(level, original);
+			const mirror = original.bind(console);
+			target[level] = (...args) => this.#intercept(level, args, mirror);
+		}
+		this.#emitter.emit("start");
+	}
+	stop() {
+		if (!this.#active) return;
+		this.#active = false;
+		const target = console;
+		for (const [level, original] of this.#originals) target[level] = original;
+		this.#originals.clear();
+		this.#emitter.emit("stop");
+	}
+	messages(level) {
+		if (level === void 0) return [...this.#messages];
+		return [...this.#buckets.get(level) ?? []];
+	}
+	clear() {
+		this.#messages.length = 0;
+		for (const bucket of this.#buckets.values()) bucket.length = 0;
+	}
+	destroy() {
+		this.stop();
+		this.#emitter.destroy();
+	}
+	#intercept(level, args, mirror) {
+		const message = this.#capture(level, args);
+		this.#retain(message);
+		this.#emitter.emit("capture", message);
+		if (this.#mirror) mirror(...args);
+		if (this.#sink !== void 0) try {
+			this.#sink.write(message.text, CAPTURE_LEVEL_MAP[level]);
+		} catch {}
+	}
+	#capture(level, args) {
+		return Object.freeze({
+			level,
+			text: formatArgs(args),
+			time: Date.now()
+		});
+	}
+	#retain(message) {
+		this.#push(this.#messages, message);
+		const bucket = this.#buckets.get(message.level);
+		if (bucket !== void 0) this.#push(bucket, message);
+	}
+	#push(buffer, message) {
+		buffer.push(message);
+		if (buffer.length > this.#limit) buffer.shift();
+	}
+};
+//#endregion
+//#region src/core/LoggerManager.ts
+/**
+* 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
+* ```
+*/
+var LoggerManager = class {
+	#loggers = /* @__PURE__ */ new Map();
+	#level;
+	#sink;
+	#styler;
+	#limit;
+	#silent;
+	constructor(options) {
+		this.#level = options?.level;
+		this.#sink = options?.sink;
+		this.#styler = options?.styler;
+		this.#limit = options?.limit;
+		this.#silent = options?.silent;
+	}
+	get count() {
+		return this.#loggers.size;
+	}
+	register(name, options) {
+		const logger = new Logger({
+			level: this.#level,
+			sink: this.#sink,
+			styler: this.#styler,
+			limit: this.#limit,
+			silent: this.#silent,
+			...options,
+			name
+		});
+		this.#loggers.set(name, logger);
+		return logger;
+	}
+	logger(name) {
+		return this.#loggers.get(name);
+	}
+	loggers() {
+		return [...this.#loggers.values()];
+	}
+	debug(message, data) {
+		for (const logger of this.#loggers.values()) logger.debug(message, data);
+	}
+	info(message, data) {
+		for (const logger of this.#loggers.values()) logger.info(message, data);
+	}
+	warn(message, data) {
+		for (const logger of this.#loggers.values()) logger.warn(message, data);
+	}
+	error(message, data) {
+		for (const logger of this.#loggers.values()) logger.error(message, data);
+	}
+	remove(names) {
+		if (names === void 0) {
+			this.#loggers.clear();
+			return;
+		}
+		if (isArray(names)) {
+			let removed = false;
+			for (const name of names) if (this.#loggers.delete(name)) removed = true;
+			return removed;
+		}
+		return this.#loggers.delete(names);
+	}
+	clear() {
+		this.#loggers.clear();
+	}
+};
+//#endregion
+//#region src/core/Progress.ts
+/**
+* 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
+* ```
+*/
+var Progress = class {
+	#emitter;
+	#total;
+	#width;
+	#sink;
+	#styler;
+	#message;
+	#current = 0;
+	#active = true;
+	#completed = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options.on,
+			error: options.error
+		});
+		this.#total = options.total;
+		this.#width = options.width ?? 30;
+		this.#sink = options.sink ?? createConsoleSink();
+		this.#styler = options.styler ?? createStyler();
+		this.#message = options.message ?? "";
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get active() {
+		return this.#active;
+	}
+	get completed() {
+		return this.#completed;
+	}
+	get current() {
+		return this.#current;
+	}
+	get total() {
+		return this.#total;
+	}
+	update(current, message) {
+		if (!this.#active) return;
+		this.#advance(current, message);
+		this.#paint(false);
+	}
+	complete(message) {
+		if (!this.#active) return;
+		this.#advance(this.#total, message);
+		this.#active = false;
+		this.#completed = true;
+		this.#paint(true);
+		this.#emitter.emit("complete");
+	}
+	failure(message) {
+		if (!this.#active) return;
+		this.#advance(this.#current, message);
+		this.#active = false;
+		this.#paint(true, "error");
+	}
+	destroy() {
+		this.#emitter.destroy();
+	}
+	#advance(current, message) {
+		this.#current = Math.max(0, Math.min(this.#total, current));
+		if (message !== void 0) this.#message = message;
+		this.#emitter.emit("update", {
+			current: this.#current,
+			total: this.#total
+		});
+	}
+	#paint(final, level) {
+		const bar = renderBar({
+			current: this.#current,
+			total: this.#total,
+			width: this.#width,
+			styler: this.#styler.cyan
+		});
+		const line = this.#message === "" ? bar : `${bar} ${this.#message}`;
+		this.#sink.write(`\r${line}${final ? "\n" : ""}`, level);
+	}
+};
+//#endregion
+//#region src/core/Reporter.ts
+/**
+* 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
+* ```
+*/
+var Reporter = class {
+	#sink;
+	#styler;
+	#width;
+	constructor(options) {
+		this.#sink = options?.sink ?? createConsoleSink();
+		this.#styler = options?.styler ?? createStyler();
+		this.#width = options?.width ?? 80;
+	}
+	section(title) {
+		this.#sink.write(renderSeparator({
+			title,
+			width: this.#width,
+			styler: this.#styler.dim
+		}));
+	}
+	step(message, position) {
+		const prefix = position === void 0 ? "" : `${this.#styler.cyan(`[${position.index}/${position.total}]`)} `;
+		this.#sink.write(`${prefix}${message}`);
+	}
+	timing(label, ms) {
+		this.#sink.write(`${label} ${this.#styler.dim(`… ${formatDuration(ms)}`)}`);
+	}
+	status(level, message) {
+		const color = this.#styler[STATUS_COLORS[level]];
+		const line = `${color(STATUS_ICONS[level])} ${color(message)}`;
+		this.#sink.write(line, level === "error" ? "error" : void 0);
+	}
+	table(options) {
+		this.#sink.write(renderTable({
+			styler: this.#styler.dim,
+			...options
+		}));
+	}
+	tree(options) {
+		this.#sink.write(renderTree({
+			styler: this.#styler.dim,
+			...options
+		}));
+	}
+	box(options) {
+		this.#sink.write(renderBox({
+			width: this.#width,
+			styler: this.#styler.dim,
+			...options
+		}));
+	}
+	line(text) {
+		this.#sink.write(text);
+	}
+	blank(count = 1) {
+		for (let index = 0; index < count; index += 1) this.#sink.write("");
+	}
+};
+//#endregion
+//#region src/core/Spinner.ts
+/**
+* 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
+* ```
+*/
+var Spinner = class {
+	#emitter;
+	#frames;
+	#interval;
+	#sink;
+	#styler;
+	#message;
+	#handle;
+	#index = 0;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		const frames = options?.frames ?? SPINNER_FRAMES;
+		this.#frames = frames.length === 0 ? SPINNER_FRAMES : frames;
+		this.#interval = options?.interval ?? 80;
+		this.#sink = options?.sink ?? createConsoleSink();
+		this.#styler = options?.styler ?? createStyler();
+		this.#message = options?.message ?? "";
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get active() {
+		return this.#handle !== void 0;
+	}
+	get message() {
+		return this.#message;
+	}
+	start() {
+		if (this.#handle !== void 0) return;
+		this.#handle = setInterval(() => this.tick(), this.#interval);
+		this.#emitter.emit("start");
+		this.tick();
+	}
+	tick() {
+		this.#paint(this.#line());
+		this.#index = (this.#index + 1) % this.#frames.length;
+	}
+	update(message) {
+		this.#message = message;
+		if (this.#handle !== void 0) this.#paint(this.#line());
+	}
+	success(message) {
+		this.#finish("success", message);
+	}
+	failure(message) {
+		this.#finish("error", message);
+	}
+	stop() {
+		if (this.#handle === void 0) return;
+		clearInterval(this.#handle);
+		this.#handle = void 0;
+		this.#emitter.emit("stop");
+	}
+	destroy() {
+		this.stop();
+		this.#emitter.destroy();
+	}
+	#finish(level, message) {
+		this.stop();
+		const text = message ?? this.#message;
+		if (message !== void 0) this.#message = message;
+		const color = this.#styler[STATUS_COLORS[level]];
+		const line = `${color(STATUS_ICONS[level])} ${color(text)}`;
+		this.#emitter.emit("frame", line);
+		this.#sink.write(`\r${line}\n`, level === "error" ? "error" : void 0);
+	}
+	#line() {
+		const glyph = this.#styler.cyan(this.#frames[this.#index] ?? "");
+		return this.#message === "" ? glyph : `${glyph} ${this.#message}`;
+	}
+	#paint(line) {
+		this.#emitter.emit("frame", line);
+		this.#sink.write(`\r${line}`);
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* 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'
+* ```
+*/
+function createANSIRenderer() {
+	return new ANSIRenderer();
+}
+/**
+* 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'
+* ```
+*/
+function createStyler(options) {
+	return new Styler(options?.renderer ?? new ANSIRenderer(), options?.enabled ?? true, EMPTY_STYLE).surface;
+}
+/**
+* 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
+* ```
+*/
+function createConsoleSink() {
+	const log = console.log.bind(console);
+	const warn = console.warn.bind(console);
+	const error = console.error.bind(console);
+	return { write(text, level) {
+		if (level === "error") {
+			error(text);
+			return;
+		}
+		if (level === "warn") {
+			warn(text);
+			return;
+		}
+		log(text);
+	} };
+}
+/**
+* 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
+* ```
+*/
+function createLogger(options) {
+	return new Logger(options);
+}
+/**
+* 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
+* ```
+*/
+function createLoggerManager(options) {
+	return new LoggerManager(options);
+}
+/**
+* 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 }) })
+* ```
+*/
+function createReporter(options) {
+	return new Reporter(options);
+}
+/**
+* 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()
+* ```
+*/
+function createCapture(options) {
+	return new Capture(options);
+}
+/**
+* Run `fn` with the global `console.*` captured for its duration, returning the function's `value`
+* plus the {@link import('./types.js').CapturedMessage}s it logged — the scoped, self-restoring
+* ergonomic form of {@link createCapture}.
+*
+* @param fn - The function to run under capture; may be sync (returns `T`) or async (returns
+*   `Promise<T>`)
+* @param options - See {@link CaptureOptions} (`levels` / `mirror` / `sink` / `limit` / `on` /
+*   `error`); the capture is started for the duration of `fn` regardless
+* @returns For a sync `fn`, a {@link CaptureResult}`<T>` (`{ value, messages }`); for an async
+*   `fn`, a `Promise<CaptureResult<T>>` (awaited, then console restored)
+*
+* @remarks
+* - **Always restores.** `start()` runs before `fn`; `stop()` runs in a `finally`, so `console` is
+*   restored even if `fn` throws / rejects (the throw / rejection still propagates). The capture
+*   is local — created, used, and destroyed within the call.
+* - **Sync vs async.** A `fn` returning a `Promise` is detected and AWAITED before `stop()`, so
+*   captures during the async work are included; a plain `fn` stops synchronously. The return type
+*   follows `fn`'s (overloaded).
+* - **PROCESS-GLOBAL caveat.** Like {@link createCapture}, this patches the one global `console`.
+*   Concurrent `withCapture` calls (or a `withCapture` around other capturing code) INTERLEAVE —
+*   each captures every `console.*` call in flight, and the inner `stop()` restores whatever the
+*   outer had installed. Use it for sequential, scoped capture, not overlapping captures.
+*
+* @example
+* ```ts
+* import { withCapture } from '@src/core'
+*
+* const { value, messages } = withCapture(() => {
+* 	console.log('working')
+* 	return 42
+* })
+* value // 42
+* messages.map((m) => m.text) // ['working']
+*
+* // Async — awaited before console is restored.
+* const out = await withCapture(async () => {
+* 	console.warn('async noise')
+* 	return 'done'
+* })
+* out.value // 'done'
+* ```
+*/
+function withCapture(fn, options) {
+	const capture = new Capture(options);
+	capture.start();
+	const settle = (value) => {
+		const messages = capture.messages();
+		capture.destroy();
+		return {
+			value,
+			messages
+		};
+	};
+	try {
+		const result = fn();
+		if (result instanceof Promise) return result.then((value) => settle(value), (error) => {
+			capture.destroy();
+			throw error;
+		});
+		return settle(result);
+	} catch (error) {
+		capture.destroy();
+		throw error;
+	}
+}
+/**
+* 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
+* ```
+*/
+function createSpinner(options) {
+	return new Spinner(options);
+}
+/**
+* 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')
+* ```
+*/
+function createProgress(options) {
+	return new Progress(options);
+}
+//#endregion
+//#region src/core/Logger.ts
+/**
+* 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]
+* ```
+*/
+var Logger = class {
+	#emitter;
+	#level;
+	#name;
+	#sink;
+	#styler;
+	#limit;
+	#silent;
+	#entries = [];
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#level = options?.level ?? "info";
+		this.#name = options?.name;
+		this.#sink = options?.sink ?? createConsoleSink();
+		this.#styler = options?.styler ?? createStyler();
+		this.#limit = options?.limit ?? 1e3;
+		this.#silent = options?.silent ?? false;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get level() {
+		return this.#level;
+	}
+	get name() {
+		return this.#name;
+	}
+	debug(message, data) {
+		this.#log("debug", message, data);
+	}
+	info(message, data) {
+		this.#log("info", message, data);
+	}
+	warn(message, data) {
+		this.#log("warn", message, data);
+	}
+	error(message, data) {
+		this.#log("error", message, data);
+	}
+	entries() {
+		return [...this.#entries];
+	}
+	clear() {
+		this.#entries.length = 0;
+	}
+	destroy() {
+		this.#entries.length = 0;
+		this.#emitter.destroy();
+	}
+	#log(level, message, data) {
+		if (!meetsLevel(this.#level, level)) return;
+		const record = this.#record(level, message, data);
+		this.#retain(record);
+		this.#emitter.emit("entry", record);
+		if (this.#silent) return;
+		this.#sink.write(formatRecord(record, this.#styler), level);
+	}
+	#record(level, message, data) {
+		return Object.freeze({
+			level,
+			message,
+			time: Date.now(),
+			...this.#name === void 0 ? {} : { name: this.#name },
+			...data === void 0 ? {} : { data: Object.freeze({ ...data }) }
+		});
+	}
+	#retain(record) {
+		this.#entries.push(record);
+		if (this.#entries.length > this.#limit) this.#entries.shift();
+	}
+};
+//#endregion
+export { ANSIRenderer, ANSI_PATTERN, ATTRIBUTES, ATTRIBUTE_CODES, BACKGROUND_CODES, BAR_EMPTY, BAR_FILL, BEL, BORDER_CHARS, CAPTURE_LEVELS, CAPTURE_LEVEL_MAP, COLORS, CONTROL_PATTERN, CSI, Capture, ConsoleError, DEFAULT_ALIGN, DEFAULT_BAR_WIDTH, DEFAULT_BORDER, DEFAULT_CAPTURE_LEVELS, DEFAULT_CAPTURE_LIMIT, DEFAULT_LOG_LEVEL, DEFAULT_LOG_LIMIT, DEFAULT_PADDING, DEFAULT_SPINNER_INTERVAL, DEFAULT_WIDTH, EMPTY_STYLE, ESC, FOREGROUND_CODES, LEVELS, LEVEL_COLORS, LEVEL_SEVERITY, Logger, LoggerManager, Progress, RESET, RESET_CODE, Reporter, SECOND_MS, SEPARATOR_FILL, SEPARATOR_TITLE_GAP, SPINNER_FRAMES, STATUS_COLORS, STATUS_ICONS, STATUS_LEVELS, Spinner, Styler, TREE_CHARS, align, cellAt, createANSIRenderer, createCapture, createConsoleSink, createLogger, createLoggerManager, createProgress, createReporter, createSpinner, createStyler, formatArgs, formatDuration, formatRecord, formatTime, isConsoleError, meetsLevel, paint, renderBar, renderBox, renderSeparator, renderTable, renderTree, renderTreeChildren, repeatTo, stringifyValue, strip, stripControls, width, withCapture };
+
+//# sourceMappingURL=index.js.map