@orkestrel/console 0.0.5 → 0.0.7

package/dist/src/core/index.js

@@ -287,17 +287,6 @@ var STATUS_LEVELS = Object.freeze([
 	"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
@@ -413,6 +402,74 @@ var BAR_EMPTY = "░";
 * track is one inline element, not a full-width rule.
 */
 var DEFAULT_BAR_WIDTH = 30;
+/**
+* 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
+* entity uses when none is supplied.
+*
+* @remarks
+* - `levels` — each {@link LogLevel} label in its {@link LEVEL_COLORS} color, no attributes.
+* - `statuses` — each {@link StatusLevel}'s {@link STATUS_ICONS} glyph in its
+*   {@link STATUS_COLORS} color.
+* - `accent` — `cyan`: the spinner glyph, the progress fill, a step prefix.
+* - `chrome` — `dim`: separators, box / table / tree frames, and a log line's timestamp /
+*   name / data surround. A color-free attribute, so chrome recedes on any background.
+*/
+var DEFAULT_THEME = Object.freeze({
+	levels: Object.freeze({
+		debug: Object.freeze({
+			foreground: LEVEL_COLORS.debug,
+			attributes: EMPTY_STYLE.attributes
+		}),
+		info: Object.freeze({
+			foreground: LEVEL_COLORS.info,
+			attributes: EMPTY_STYLE.attributes
+		}),
+		warn: Object.freeze({
+			foreground: LEVEL_COLORS.warn,
+			attributes: EMPTY_STYLE.attributes
+		}),
+		error: Object.freeze({
+			foreground: LEVEL_COLORS.error,
+			attributes: EMPTY_STYLE.attributes
+		})
+	}),
+	statuses: Object.freeze({
+		success: Object.freeze({
+			icon: STATUS_ICONS.success,
+			style: Object.freeze({
+				foreground: STATUS_COLORS.success,
+				attributes: EMPTY_STYLE.attributes
+			})
+		}),
+		error: Object.freeze({
+			icon: STATUS_ICONS.error,
+			style: Object.freeze({
+				foreground: STATUS_COLORS.error,
+				attributes: EMPTY_STYLE.attributes
+			})
+		}),
+		warn: Object.freeze({
+			icon: STATUS_ICONS.warn,
+			style: Object.freeze({
+				foreground: STATUS_COLORS.warn,
+				attributes: EMPTY_STYLE.attributes
+			})
+		}),
+		info: Object.freeze({
+			icon: STATUS_ICONS.info,
+			style: Object.freeze({
+				foreground: STATUS_COLORS.info,
+				attributes: EMPTY_STYLE.attributes
+			})
+		})
+	}),
+	accent: Object.freeze({
+		foreground: "cyan",
+		attributes: EMPTY_STYLE.attributes
+	}),
+	chrome: Object.freeze({ attributes: Object.freeze(["dim"]) })
+});
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -452,6 +509,127 @@ function isConsoleError(value) {
 	return value instanceof ConsoleError;
 }
 //#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({
+			...options?.on !== void 0 ? { on: options.on } : {},
+			...options?.error !== void 0 ? { 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] = this.#captureCall.bind(this, level, 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();
+	}
+	#captureCall(level, mirror, ...args) {
+		this.#intercept(level, args, mirror);
+	}
+	#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/helpers.ts
 /**
 * Remove every ANSI escape sequence from `text`, returning the plain visible string.
@@ -518,6 +696,27 @@ function width(text) {
 	return [...strip(text)].length;
 }
 /**
+* Snapshot and deeply freeze one {@link Style} value.
+*
+* @param style - The caller-owned style to snapshot
+* @returns A frozen style record with an independently frozen attributes list
+*
+* @remarks
+* The record spread captures accessor values once and preserves each present color channel.
+* Copying `attributes` prevents later mutation of a caller-owned list from changing the result.
+*
+* @example
+* ```ts
+* freezeStyle({ foreground: 'red', attributes: ['bold'] })
+* ```
+*/
+function freezeStyle(style) {
+	return Object.freeze({
+		...style,
+		attributes: Object.freeze([...style.attributes])
+	});
+}
+/**
 * Whether a record at `level` passes a logger gated at `threshold` — i.e. its severity is
 * at or above the threshold's.
 *
@@ -559,7 +758,7 @@ function formatTime(time) {
 *
 * @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),
+* upper-cased level label (rendered through the theme's level role),
 * 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
@@ -568,19 +767,24 @@ function formatTime(time) {
 *
 * @param record - The {@link LogRecord} to render
 * @param styler - The {@link StylerInterface} the labels are colored through
+* @param theme - The {@link Theme} supplying the level and chrome roles
 * @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())
+* formatRecord(
+* 	{ level: 'warn', message: 'low disk', time: 0, name: 'fs' },
+* 	createStyler(),
+* 	DEFAULT_THEME,
+* )
 * // '<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))}`;
+function formatRecord(record, styler, theme) {
+	const time = styler.render(theme.chrome, formatTime(record.time));
+	const label = styler.render(theme.levels[record.level], record.level.toUpperCase());
+	const name = record.name === void 0 ? "" : ` ${styler.render(theme.chrome, `[${record.name}]`)}`;
+	const data = record.data === void 0 || Object.keys(record.data).length === 0 ? "" : ` ${styler.render(theme.chrome, JSON.stringify(record.data))}`;
 	return `${time} ${label}${name} ${record.message}${data}`;
 }
 /**
@@ -647,10 +851,12 @@ function formatDuration(ms) {
 *
 * @param styler - The {@link StylerInterface} to color with, or `undefined` for no styling
 * @param text - The glyphs / text to color
+* @param style - An optional {@link Style} to render by value instead of the styler's chain
 * @returns `styler(text)` when a styler is given, else `text` unchanged
 */
-function paint(styler, text) {
-	return styler === void 0 ? text : styler(text);
+function paint(styler, text, style) {
+	if (styler === void 0) return text;
+	return style === void 0 ? styler(text) : styler.render(style, text);
 }
 /**
 * Repeat `unit` until it fills exactly `count` VISIBLE columns, trimming a trailing partial
@@ -716,12 +922,12 @@ function cellAt(row, index) {
 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)} `;
+	if (options.title === void 0) return paint(options.styler, repeatTo(fill, total), options.style);
+	const gapped = ` ${paint(options.styler, options.title, options.style)} `;
 	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))}`;
+	return `${paint(options.styler, repeatTo(fill, left), options.style)}${gapped}${paint(options.styler, repeatTo(fill, room - left), options.style)}`;
 }
 /**
 * Render `content` framed in box-drawing characters, optionally captioned, width-aware so
@@ -753,18 +959,18 @@ function renderBox(options) {
 	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 bar = paint(styler, chars.vertical, options.style);
 	const span = inner + padding * 2;
 	let top;
-	if (options.title === void 0) top = paint(styler, `${chars.topLeft}${repeatTo(chars.horizontal, span)}${chars.topRight}`);
+	if (options.title === void 0) top = paint(styler, `${chars.topLeft}${repeatTo(chars.horizontal, span)}${chars.topRight}`, options.style);
 	else {
 		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));
-		top = `${paint(styler, chars.topLeft)}${lead}${paint(styler, caption)}${rest}${paint(styler, chars.topRight)}`;
+		const lead = paint(styler, repeatTo(chars.horizontal, 1), options.style);
+		const rest = room - 1 <= 0 ? "" : paint(styler, repeatTo(chars.horizontal, room - 1), options.style);
+		top = `${paint(styler, chars.topLeft, options.style)}${lead}${paint(styler, caption, options.style)}${rest}${paint(styler, chars.topRight, options.style)}`;
 	}
-	const bottom = paint(styler, `${chars.bottomLeft}${repeatTo(chars.horizontal, inner + padding * 2)}${chars.bottomRight}`);
+	const bottom = paint(styler, `${chars.bottomLeft}${repeatTo(chars.horizontal, inner + padding * 2)}${chars.bottomRight}`, options.style);
 	const body = lines.map((line) => `${bar}${gutter}${align(line, inner)}${gutter}${bar}`);
 	return [
 		top,
@@ -799,14 +1005,14 @@ function renderTable(options) {
 	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 renderedRows = [columns.map((column) => paint(styler, column.label)), ...options.rows.map((row) => columns.map((_column, index) => cellAt(row, index)))].map((cells) => {
-		const bar = paint(styler, chars.vertical);
+	const renderedRows = [columns.map((column) => paint(styler, column.label, options.style)), ...options.rows.map((row) => columns.map((_column, index) => cellAt(row, index)))].map((cells) => {
+		const bar = paint(styler, chars.vertical, options.style);
 		return `${bar}${cells.map((cell, index) => ` ${align(cell, widths[index] ?? width(cell), aligns[index] ?? "left")} `).join(bar)}${bar}`;
 	});
 	const segments = widths.map((columnWidth) => repeatTo(chars.horizontal, columnWidth + 2));
-	const top = paint(styler, `${chars.topLeft}${segments.join(chars.teeDown)}${chars.topRight}`);
-	const rule = paint(styler, `${chars.teeRight}${segments.join(chars.cross)}${chars.teeLeft}`);
-	const bottom = paint(styler, `${chars.bottomLeft}${segments.join(chars.teeUp)}${chars.bottomRight}`);
+	const top = paint(styler, `${chars.topLeft}${segments.join(chars.teeDown)}${chars.topRight}`, options.style);
+	const rule = paint(styler, `${chars.teeRight}${segments.join(chars.cross)}${chars.teeLeft}`, options.style);
+	const bottom = paint(styler, `${chars.bottomLeft}${segments.join(chars.teeUp)}${chars.bottomRight}`, options.style);
 	return [
 		top,
 		...renderedRows.slice(0, 1),
@@ -821,7 +1027,7 @@ function renderTable(options) {
 *
 * @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
+* {@link BORDER_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
@@ -839,7 +1045,11 @@ function renderTable(options) {
 * ```
 */
 function renderTree(options) {
-	return [options.root.label, ...renderTreeChildren(options.root.children ?? [], "", options.styler)].join("\n");
+	const border = options.border ?? "single";
+	return [options.root.label, ...renderTreeChildren(options.root.children ?? [], "", {
+		...options,
+		border
+	})].join("\n");
 }
 /**
 * Render the connector-prefixed lines for a {@link TreeNode} list — the recursive core
@@ -853,22 +1063,27 @@ function renderTree(options) {
 *
 * @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
+* @param options - The required `border` selection plus optional connector `styler` and
+* by-value `style`
 * @returns The rendered lines for `nodes` and all their descendants
 *
 * @example
 * ```ts
-* renderTreeChildren([{ label: 'a' }, { label: 'b' }], '')
+* renderTreeChildren([{ label: 'a' }, { label: 'b' }], '', { border: 'single' })
 * // ['├─ a', '└─ b']
 * ```
 */
-function renderTreeChildren(nodes, prefix, styler) {
+function renderTreeChildren(nodes, prefix, options) {
+	const chars = BORDER_CHARS[options.border];
+	const branch = `${chars.teeRight}${chars.horizontal} `;
+	const corner = `${chars.bottomLeft}${chars.horizontal} `;
+	const guide = `${chars.vertical}  `;
 	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));
+		lines.push(`${prefix}${paint(options.styler, last ? corner : branch, options.style)}${node.label}`);
+		const carry = `${prefix}${paint(options.styler, last ? "   " : guide, options.style)}`;
+		lines.push(...renderTreeChildren(node.children ?? [], carry, options));
 	});
 	return lines;
 }
@@ -975,7 +1190,77 @@ function renderBar(options) {
 	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})`;
+	return `${`${paint(options.styler, repeatTo(fill, filledCells), options.style)}${repeatTo(empty, track - filledCells)}`} ${Math.round(fraction * 100)}% (${current}/${options.total})`;
+}
+/**
+* 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();
+	try {
+		const result = fn();
+		if (result instanceof Promise) return result.then((value) => {
+			const messages = capture.messages();
+			capture.destroy();
+			return {
+				value,
+				messages
+			};
+		}, (error) => {
+			capture.destroy();
+			throw error;
+		});
+		const messages = capture.messages();
+		capture.destroy();
+		return {
+			value: result,
+			messages
+		};
+	} catch (error) {
+		capture.destroy();
+		throw error;
+	}
 }
 //#endregion
 //#region src/core/ANSIRenderer.ts
@@ -1020,274 +1305,55 @@ var ANSIRenderer = class {
 	}
 };
 //#endregion
-//#region src/core/Styler.ts
+//#region src/core/LoggerManager.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.
+* 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
-* - **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 = this.#render.bind(this);
-		const descriptors = {
-			style: {
-				value: this.#style,
-				enumerable: true
-			},
-			enabled: {
-				value: this.#enabled,
-				enumerable: true
-			}
-		};
-		for (const color of COLORS) descriptors[color] = {
-			get: this.#foregroundSurface.bind(this, color),
-			enumerable: true
-		};
-		for (const attribute of ATTRIBUTES) descriptors[attribute] = {
-			get: this.#attributeSurface.bind(this, attribute),
-			enumerable: true
-		};
-		const surface = Object.defineProperties(render, descriptors);
-		if (this.#isSurface(surface)) return surface;
-		throw new ConsoleError("INVARIANT", "console: styler surface construction is incomplete");
-	}
-	#render(text) {
-		return this.#enabled ? this.#renderer.render(this.#style, text) : text;
-	}
-	#foregroundSurface(color) {
-		return this.#foreground(color).surface;
-	}
-	#attributeSurface(attribute) {
-		return this.#attribute(attribute).surface;
-	}
-	#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({
-			...options?.on !== void 0 ? { on: options.on } : {},
-			...options?.error !== void 0 ? { 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] = this.#captureCall.bind(this, level, 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();
-	}
-	#captureCall(level, mirror, ...args) {
-		this.#intercept(level, args, mirror);
-	}
-	#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
-* ```
+* - **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` / `theme` / `format` / `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).
+*   (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 in insertion order; each gates / emits / writes per its own `level`
+*   and `sink`. A formatter throw is a programmer error and propagates, stopping the remaining
+*   loggers for that call. 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;
+	#theme;
+	#format;
 	#limit;
 	#silent;
 	constructor(options) {
 		this.#level = options?.level;
 		this.#sink = options?.sink;
 		this.#styler = options?.styler;
+		this.#theme = options?.theme;
+		this.#format = options?.format;
 		this.#limit = options?.limit;
 		this.#silent = options?.silent;
 	}
@@ -1299,6 +1365,8 @@ var LoggerManager = class {
 			...this.#level !== void 0 ? { level: this.#level } : {},
 			...this.#sink !== void 0 ? { sink: this.#sink } : {},
 			...this.#styler !== void 0 ? { styler: this.#styler } : {},
+			...this.#theme !== void 0 ? { theme: this.#theme } : {},
+			...this.#format !== void 0 ? { format: this.#format } : {},
 			...this.#limit !== void 0 ? { limit: this.#limit } : {},
 			...this.#silent !== void 0 ? { silent: this.#silent } : {},
 			...options,
@@ -1337,9 +1405,6 @@ var LoggerManager = class {
 		}
 		return this.#loggers.delete(names);
 	}
-	clear() {
-		this.#loggers.clear();
-	}
 };
 //#endregion
 //#region src/core/Progress.ts
@@ -1375,8 +1440,11 @@ var Progress = class {
 	#emitter;
 	#total;
 	#width;
+	#fill;
+	#empty;
 	#sink;
 	#styler;
+	#theme;
 	#message;
 	#current = 0;
 	#active = true;
@@ -1388,8 +1456,11 @@ var Progress = class {
 		});
 		this.#total = options.total;
 		this.#width = options.width ?? 30;
+		this.#fill = options.fill;
+		this.#empty = options.empty;
 		this.#sink = options.sink ?? createConsoleSink();
 		this.#styler = options.styler ?? createStyler();
+		this.#theme = options.theme ?? DEFAULT_THEME;
 		this.#message = options.message ?? "";
 	}
 	get emitter() {
@@ -1442,7 +1513,10 @@ var Progress = class {
 			current: this.#current,
 			total: this.#total,
 			width: this.#width,
-			styler: this.#styler.cyan
+			...this.#fill === void 0 ? {} : { fill: this.#fill },
+			...this.#empty === void 0 ? {} : { empty: this.#empty },
+			styler: this.#styler,
+			style: this.#theme.accent
 		});
 		const line = this.#message === "" ? bar : `${bar} ${this.#message}`;
 		this.#sink.write(`\r${line}${final ? "\n" : ""}`, level);
@@ -1463,7 +1537,7 @@ var Progress = class {
 *   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
+*   supplied theme status icon + style, 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
@@ -1483,49 +1557,45 @@ var Progress = class {
 var Reporter = class {
 	#sink;
 	#styler;
+	#theme;
 	#width;
 	constructor(options) {
 		this.#sink = options?.sink ?? createConsoleSink();
 		this.#styler = options?.styler ?? createStyler();
+		this.#theme = options?.theme ?? DEFAULT_THEME;
 		this.#width = options?.width ?? 80;
 	}
 	section(title) {
 		this.#sink.write(renderSeparator({
 			title,
 			width: this.#width,
-			styler: this.#styler.dim
+			styler: this.#styler,
+			style: this.#theme.chrome
 		}));
 	}
 	step(message, position) {
-		const prefix = position === void 0 ? "" : `${this.#styler.cyan(`[${position.index}/${position.total}]`)} `;
+		const prefix = position === void 0 ? "" : `${this.#styler.render(this.#theme.accent, `[${position.index}/${position.total}]`)} `;
 		this.#sink.write(`${prefix}${message}`);
 	}
 	timing(label, ms) {
-		this.#sink.write(`${label} ${this.#styler.dim(`… ${formatDuration(ms)}`)}`);
+		this.#sink.write(`${label} ${this.#styler.render(this.#theme.chrome, `… ${formatDuration(ms)}`)}`);
 	}
 	status(level, message) {
-		const color = this.#styler[STATUS_COLORS[level]];
-		const line = `${color(STATUS_ICONS[level])} ${color(message)}`;
+		const status = this.#theme.statuses[level];
+		const line = `${this.#styler.render(status.style, status.icon)} ${this.#styler.render(status.style, message)}`;
 		this.#sink.write(line, level === "error" ? "error" : void 0);
 	}
 	table(options) {
-		this.#sink.write(renderTable({
-			styler: this.#styler.dim,
-			...options
-		}));
+		this.#sink.write(renderTable(this.#resolveStyle(options)));
 	}
 	tree(options) {
-		this.#sink.write(renderTree({
-			styler: this.#styler.dim,
-			...options
-		}));
+		this.#sink.write(renderTree(this.#resolveStyle(options)));
 	}
 	box(options) {
-		this.#sink.write(renderBox({
+		this.#sink.write(renderBox(this.#resolveStyle({
 			width: this.#width,
-			styler: this.#styler.dim,
 			...options
-		}));
+		})));
 	}
 	line(text) {
 		this.#sink.write(text);
@@ -1533,6 +1603,13 @@ var Reporter = class {
 	blank(count = 1) {
 		for (let index = 0; index < count; index += 1) this.#sink.write("");
 	}
+	#resolveStyle(options) {
+		return {
+			styler: this.#styler,
+			...options.styler === void 0 && options.style === void 0 ? { style: this.#theme.chrome } : {},
+			...options
+		};
+	}
 };
 //#endregion
 //#region src/core/Spinner.ts
@@ -1556,7 +1633,7 @@ var Reporter = class {
 * - **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
+*   the supplied theme status icon + style (`✔` / `✖` by default) + 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}
@@ -1577,6 +1654,7 @@ var Spinner = class {
 	#interval;
 	#sink;
 	#styler;
+	#theme;
 	#message;
 	#handle;
 	#index = 0;
@@ -1590,6 +1668,7 @@ var Spinner = class {
 		this.#interval = options?.interval ?? 80;
 		this.#sink = options?.sink ?? createConsoleSink();
 		this.#styler = options?.styler ?? createStyler();
+		this.#theme = options?.theme ?? DEFAULT_THEME;
 		this.#message = options?.message ?? "";
 	}
 	get emitter() {
@@ -1635,13 +1714,13 @@ var Spinner = class {
 		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)}`;
+		const status = this.#theme.statuses[level];
+		const line = `${this.#styler.render(status.style, status.icon)} ${this.#styler.render(status.style, 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] ?? "");
+		const glyph = this.#styler.render(this.#theme.accent, this.#frames[this.#index] ?? "");
 		return this.#message === "" ? glyph : `${glyph} ${this.#message}`;
 	}
 	#paint(line) {
@@ -1650,6 +1729,148 @@ var Spinner = class {
 	}
 };
 //#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).
+* - **Styling by value.** `render(style, text)` merges a {@link Style} over the accumulated
+*   one and renders that — the same precedence a chain applies, reached with DATA instead of
+*   accessor names. It is how a {@link import('./types.js').Theme} role is drawn.
+* - **`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 callable = this.#render.bind(this);
+		const descriptors = {
+			style: {
+				value: this.#style,
+				enumerable: true
+			},
+			enabled: {
+				value: this.#enabled,
+				enumerable: true
+			},
+			render: {
+				value: this.render.bind(this),
+				enumerable: true
+			}
+		};
+		for (const color of COLORS) descriptors[color] = {
+			get: this.#foregroundSurface.bind(this, color),
+			enumerable: true
+		};
+		for (const attribute of ATTRIBUTES) descriptors[attribute] = {
+			get: this.#attributeSurface.bind(this, attribute),
+			enumerable: true
+		};
+		const surface = Object.defineProperties(callable, descriptors);
+		if (this.#isSurface(surface)) return surface;
+		throw new ConsoleError("INVARIANT", "console: styler surface construction is incomplete");
+	}
+	/**
+	* Render `text` in `style` merged OVER the accumulated style — the by-value door beside
+	* the accessor chain, and how a {@link import('./types.js').Theme} role is applied.
+	*
+	* @param style - The style to overlay; its colors win over the accumulated ones and its
+	* attributes join them (de-duplicated, the accumulated ones first)
+	* @param text - The text to wrap
+	* @returns The rendered text — verbatim when `enabled` is `false`, and (by the
+	* {@link RendererInterface} contract) when the merged style or `text` is empty
+	*
+	* @example
+	* ```ts
+	* import { createStyler, DEFAULT_THEME } from '@src/core'
+	*
+	* const styler = createStyler()
+	* styler.render(DEFAULT_THEME.levels.warn, 'WARN') // yellow
+	* styler.bold.render(DEFAULT_THEME.chrome, '│') // dim, over the accumulated bold
+	* ```
+	*/
+	render(style, text) {
+		return this.#enabled ? this.#renderer.render(this.#merge(style), text) : text;
+	}
+	#render(text) {
+		return this.#enabled ? this.#renderer.render(this.#style, text) : text;
+	}
+	#merge(style) {
+		const attributes = [...this.#style.attributes];
+		for (const attribute of style.attributes) if (!attributes.includes(attribute)) attributes.push(attribute);
+		return Object.freeze({
+			...this.#style,
+			...style,
+			attributes: Object.freeze(attributes)
+		});
+	}
+	#foregroundSurface(color) {
+		return this.#foreground(color).surface;
+	}
+	#attributeSurface(attribute) {
+		return this.#attribute(attribute).surface;
+	}
+	#isSurface(value) {
+		return typeof value === "function" && "style" in value && "enabled" in value && "render" 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/factories.ts
 /**
 * Create the cross-environment default {@link RendererInterface} — the ANSI / SGR
@@ -1703,6 +1924,52 @@ function createStyler(options) {
 	return new Styler(options?.renderer ?? new ANSIRenderer(), options?.enabled ?? true, EMPTY_STYLE).surface;
 }
 /**
+* Create a {@link Theme} — the app-wide semantic style vocabulary, merged role by role over
+* {@link DEFAULT_THEME}. Hand one theme to a logger / reporter / spinner / progress and every
+* surface speaks it; omit `options` for the defaults.
+*
+* @param options - See {@link ThemeOptions}
+* @returns A frozen {@link Theme}
+*
+* @remarks
+* - **Merges per ROLE, not per theme.** An omitted role keeps its default, and `levels` /
+*   `statuses` merge per ENTRY — `{ levels: { warn: … } }` restyles the `warn` label and
+*   leaves `debug` / `info` / `error` untouched.
+* - **Frozen and shareable.** The factory snapshots and deep-freezes every style leaf. The
+*   returned theme and its `levels` / `statuses` records are frozen. Each status record is also
+*   copied and frozen. One theme is therefore safely shared across every entity.
+*
+* @example
+* ```ts
+* import { createStyler, createTheme } from '@src/core'
+*
+* const styler = createStyler()
+* const theme = createTheme({
+* 	levels: { warn: styler.brightYellow.bold.style }, // only the warn label changes
+* 	accent: styler.magenta.style, // spinner glyph, progress fill, step prefix
+* })
+* theme.levels.error // still the default red
+* ```
+*/
+function createTheme(options) {
+	const levels = { ...DEFAULT_THEME.levels };
+	for (const level of LEVELS) levels[level] = freezeStyle(options?.levels?.[level] ?? DEFAULT_THEME.levels[level]);
+	const statuses = { ...DEFAULT_THEME.statuses };
+	for (const status of STATUS_LEVELS) {
+		const source = options?.statuses?.[status] ?? DEFAULT_THEME.statuses[status];
+		statuses[status] = Object.freeze({
+			icon: source.icon,
+			style: freezeStyle(source.style)
+		});
+	}
+	return Object.freeze({
+		levels: Object.freeze(levels),
+		statuses: Object.freeze(statuses),
+		accent: freezeStyle(options?.accent ?? DEFAULT_THEME.accent),
+		chrome: freezeStyle(options?.chrome ?? DEFAULT_THEME.chrome)
+	});
+}
+/**
 * 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}.
@@ -1875,76 +2142,6 @@ 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();
-	try {
-		const result = fn();
-		if (result instanceof Promise) return result.then((value) => {
-			const messages = capture.messages();
-			capture.destroy();
-			return {
-				value,
-				messages
-			};
-		}, (error) => {
-			capture.destroy();
-			throw error;
-		});
-		const messages = capture.messages();
-		capture.destroy();
-		return {
-			value: result,
-			messages
-		};
-	} 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
@@ -2045,6 +2242,8 @@ var Logger = class {
 	#level;
 	#sink;
 	#styler;
+	#theme;
+	#format;
 	#limit;
 	#silent;
 	#entries = [];
@@ -2058,6 +2257,8 @@ var Logger = class {
 		if (options?.name !== void 0) this.name = options.name;
 		this.#sink = options?.sink ?? createConsoleSink();
 		this.#styler = options?.styler ?? createStyler();
+		this.#theme = options?.theme ?? DEFAULT_THEME;
+		this.#format = options?.format ?? formatRecord;
 		this.#limit = options?.limit ?? 1e3;
 		this.#silent = options?.silent ?? false;
 	}
@@ -2095,7 +2296,7 @@ var Logger = class {
 		this.#retain(record);
 		this.#emitter.emit("entry", record);
 		if (this.#silent) return;
-		this.#sink.write(formatRecord(record, this.#styler), level);
+		this.#sink.write(this.#format(record, this.#styler, this.#theme), level);
 	}
 	#record(level, message, data) {
 		return Object.freeze({
@@ -2112,6 +2313,6 @@ var Logger = class {
 	}
 };
 //#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 };
+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_THEME, 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, align, cellAt, createANSIRenderer, createCapture, createConsoleSink, createLogger, createLoggerManager, createProgress, createReporter, createSpinner, createStyler, createTheme, formatArgs, formatDuration, formatRecord, formatTime, freezeStyle, isConsoleError, meetsLevel, paint, renderBar, renderBox, renderSeparator, renderTable, renderTree, renderTreeChildren, repeatTo, stringifyValue, strip, stripControls, width, withCapture };
 
 //# sourceMappingURL=index.js.map