@orkestrel/console 0.0.6 → 0.0.8

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
 /**
@@ -639,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.
 *
@@ -680,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
@@ -689,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}`;
 }
 /**
@@ -768,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
@@ -837,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
@@ -874,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,
@@ -920,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),
@@ -942,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
@@ -960,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
@@ -974,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;
 }
@@ -1096,7 +1190,7 @@ 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`
@@ -1220,17 +1314,19 @@ var ANSIRenderer = class {
 * @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
+*   `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). `clear()` empties the registry.
+*   `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; each gates / emits / writes per its own `level` and `sink`. A
-*   fan-out over an empty registry is a no-op.
+*   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}.
 *
@@ -1248,12 +1344,16 @@ var LoggerManager = class {
 	#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;
 	}
@@ -1265,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,
@@ -1303,9 +1405,6 @@ var LoggerManager = class {
 		}
 		return this.#loggers.delete(names);
 	}
-	clear() {
-		this.#loggers.clear();
-	}
 };
 //#endregion
 //#region src/core/Progress.ts
@@ -1341,8 +1440,11 @@ var Progress = class {
 	#emitter;
 	#total;
 	#width;
+	#fill;
+	#empty;
 	#sink;
 	#styler;
+	#theme;
 	#message;
 	#current = 0;
 	#active = true;
@@ -1354,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() {
@@ -1408,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);
@@ -1429,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
@@ -1449,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);
@@ -1499,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
@@ -1522,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}
@@ -1543,6 +1654,7 @@ var Spinner = class {
 	#interval;
 	#sink;
 	#styler;
+	#theme;
 	#message;
 	#handle;
 	#index = 0;
@@ -1556,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() {
@@ -1601,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) {
@@ -1635,6 +1748,9 @@ var Spinner = class {
 * - **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`.
@@ -1670,7 +1786,7 @@ var Styler = class Styler {
 	* type assertion is used (AGENTS §1 / §14 — narrow, never assert).
 	*/
 	get surface() {
-		const render = this.#render.bind(this);
+		const callable = this.#render.bind(this);
 		const descriptors = {
 			style: {
 				value: this.#style,
@@ -1679,6 +1795,10 @@ var Styler = class Styler {
 			enabled: {
 				value: this.#enabled,
 				enumerable: true
+			},
+			render: {
+				value: this.render.bind(this),
+				enumerable: true
 			}
 		};
 		for (const color of COLORS) descriptors[color] = {
@@ -1689,13 +1809,44 @@ var Styler = class Styler {
 			get: this.#attributeSurface.bind(this, attribute),
 			enumerable: true
 		};
-		const surface = Object.defineProperties(render, descriptors);
+		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;
 	}
@@ -1703,7 +1854,7 @@ var Styler = class Styler {
 		return this.#attribute(attribute).surface;
 	}
 	#isSurface(value) {
-		return typeof value === "function" && "style" in value && "enabled" in value && "red" in value && "bold" in 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({
@@ -1773,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}.
@@ -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, 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