@orkestrel/console 0.0.5 → 0.0.7

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

@@ -200,6 +200,7 @@ export declare type BorderStyle = 'single' | 'double' | 'round' | 'heavy';
  *   that wide (content wider than the budget is not truncated — `renderTable` is the
  *   width-bounded renderer).
  * - `styler` — colors the border (and title) when supplied; alignment is unaffected.
+ * - `style` — an optional by-value style rendered through `styler` for the frame and title.
  */
 export declare interface BoxOptions {
     readonly content: string;
@@ -208,6 +209,7 @@ export declare interface BoxOptions {
     readonly border?: BorderStyle;
     readonly width?: number;
     readonly styler?: StylerInterface;
+    readonly style?: Style;
 }
 
 /**
@@ -409,7 +411,7 @@ export declare interface CaptureOptions {
 }
 
 /**
- * The structured outcome of {@link import('./factories.js').withCapture} — the wrapped function's
+ * The structured outcome of {@link import('./helpers.js').withCapture} — the wrapped function's
  * own return `value` plus the {@link CapturedMessage}s intercepted while it ran.
  *
  * @remarks
@@ -450,7 +452,7 @@ export declare type Color = 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'mag
  * chainable accessors. The source of truth for the color axis; the styler drives its
  * accessors from this array so the literals live in one place.
  */
-export declare const COLORS: readonly Exclude<Color, 'default'>[];
+export declare const COLORS: ReadonlyArray<Exclude<Color, 'default'>>;
 
 /**
  * One column of a {@link TableOptions} — its header label and how its cells align.
@@ -768,6 +770,36 @@ export declare function createSpinner(options?: SpinnerOptions): SpinnerInterfac
  */
 export declare function createStyler(options?: StylerOptions): StylerInterface;
 
+/**
+ * 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
+ * ```
+ */
+export declare function createTheme(options?: ThemeOptions): Theme;
+
 /** The Control Sequence Introducer (`ESC[`) that opens every SGR sequence. */
 export declare const CSI: string;
 
@@ -823,6 +855,21 @@ export declare const DEFAULT_PADDING = 1;
  */
 export declare const DEFAULT_SPINNER_INTERVAL = 80;
 
+/**
+ * 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.
+ */
+export declare const DEFAULT_THEME: Theme;
+
 /**
  * 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
@@ -891,7 +938,7 @@ export declare function formatDuration(ms: number): string;
  *
  * @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
@@ -900,15 +947,20 @@ export declare function formatDuration(ms: number): string;
  *
  * @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'
  * ```
  */
-export declare function formatRecord(record: LogRecord, styler: StylerInterface): string;
+export declare function formatRecord(record: LogRecord, styler: StylerInterface, theme: Theme): string;
 
 /**
  * Format a {@link LogRecord}'s `time` (epoch milliseconds) as an ISO-8601 timestamp string.
@@ -923,6 +975,23 @@ export declare function formatRecord(record: LogRecord, styler: StylerInterface)
  */
 export declare function formatTime(time: number): string;
 
+/**
+ * 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'] })
+ * ```
+ */
+export declare function freezeStyle(style: Style): Style;
+
 /**
  * Narrow an unknown caught value to a {@link ConsoleError}.
  *
@@ -966,6 +1035,25 @@ export declare const LEVEL_SEVERITY: Readonly<Record<LogLevel, number>>;
  */
 export declare const LEVELS: readonly LogLevel[];
 
+/**
+ * The line layout a logger writes — one {@link LogRecord} plus the styling substrate in,
+ * one finished line out. {@link import('./helpers.js').formatRecord} is the default.
+ *
+ * @param record - The frozen record to lay out
+ * @param styler - The logger's {@link StylerInterface} — color through it (and through
+ * {@link StylerInterface.render} for a {@link Theme} role) so a disabled styler yields a
+ * plain line with no second code path
+ * @param theme - The logger's {@link Theme} — the level label style, the chrome surround
+ * @returns The line to write, WITHOUT a trailing terminator (the sink's target supplies it)
+ *
+ * @remarks
+ * The formatter owns the LINE; the `entry` event owns the RECORD. A transport that wants
+ * structure rides the event rather than parsing a line back out of this. A formatter throw
+ * propagates to the caller of `logger.info` and prevents that line's write, so keep it total.
+ * A manager fans out sequentially; a formatter throw stops the remaining loggers for that call.
+ */
+export declare type LogFormatFunction = (record: LogRecord, styler: StylerInterface, theme: Theme) => string;
+
 /**
  * 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},
@@ -1079,17 +1167,19 @@ export declare interface LoggerInterface {
  * @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}.
  *
@@ -1116,7 +1206,6 @@ export declare class LoggerManager implements LoggerManagerInterface {
     remove(names: readonly string[]): boolean;
     remove(name: string): boolean;
     remove(): void;
-    clear(): void;
 }
 
 /**
@@ -1130,7 +1219,7 @@ export declare class LoggerManager implements LoggerManagerInterface {
  *   (a re-`register` of the same name OVERWRITES — last write wins), and returns it.
  *   `logger(name)` looks one up; `loggers()` lists them in insertion order; `count` is the size.
  * - **Removal (§9.2).** `remove()` clears ALL, `remove(name)` drops ONE, `remove(names)` drops
- *   a batch (`true` when any was removed). `clear()` empties the registry.
+ *   a batch (`true` when any was removed).
  * - **Fan-out.** `debug` / `info` / `warn` / `error(message, data?)` forward the call to every
  *   registered logger (each gates / emits / writes per its own `level` and `sink`).
  * - **Event-free.** No emitter, no events — each logger carries its own observability; the
@@ -1152,7 +1241,6 @@ export declare interface LoggerManagerInterface {
     remove(): void;
     remove(name: string): boolean;
     remove(names: readonly string[]): boolean;
-    clear(): void;
 }
 
 /**
@@ -1163,12 +1251,15 @@ export declare interface LoggerManagerInterface {
  * registered {@link LoggerInterface} owns its observable `emitter`). These options supply
  * the DEFAULTS flowed into every logger the manager mints, unless a per-`register` override
  * wins: `level` (default threshold), `sink` (shared output target), `styler` (shared
- * coloring), `limit` (retention cap), and `silent`.
+ * coloring), `theme` (semantic styles), `format` (line layout), `limit` (retention cap),
+ * and `silent`.
  */
 export declare interface LoggerManagerOptions {
     readonly level?: LogLevel;
     readonly sink?: SinkInterface;
     readonly styler?: StylerInterface;
+    readonly theme?: Theme;
+    readonly format?: LogFormatFunction;
     readonly limit?: number;
     readonly silent?: boolean;
 }
@@ -1187,6 +1278,10 @@ export declare interface LoggerManagerOptions {
  *   {@link import('./factories.js').createConsoleSink} (the snapshotted-console sink).
  * - `styler` — the {@link StylerInterface} the line is colored through; defaults to
  *   {@link import('./factories.js').createStyler} (ANSI). Styling is orthogonal to level.
+ * - `theme` — the {@link Theme} supplying the line's semantic styles; defaults to
+ *   {@link DEFAULT_THEME}.
+ * - `format` — the {@link LogFormatFunction} that owns the written line; defaults to
+ *   {@link import('./helpers.js').formatRecord}.
  * - `limit` — the bounded retention cap: at most this many recent records are kept
  *   (oldest dropped first). Defaults to {@link DEFAULT_LOG_LIMIT}; never unbounded.
  * - `silent` — when `true`, suppresses the SINK WRITE only; `entry` still fires and the
@@ -1199,6 +1294,8 @@ export declare interface LoggerOptions {
     readonly name?: string;
     readonly sink?: SinkInterface;
     readonly styler?: StylerInterface;
+    readonly theme?: Theme;
+    readonly format?: LogFormatFunction;
     readonly limit?: number;
     readonly silent?: boolean;
 }
@@ -1276,9 +1373,10 @@ export declare function meetsLevel(threshold: LogLevel, level: LogLevel): boolea
  *
  * @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
  */
-export declare function paint(styler: StylerInterface | undefined, text: string): string;
+export declare function paint(styler: StylerInterface | undefined, text: string, style?: Style): string;
 
 /**
  * An update-driven, observable progress bar (AGENTS §13) — {@link update} recomputes the bar via
@@ -1337,6 +1435,7 @@ export declare class Progress implements ProgressInterface {
  *   import('./helpers.js').width}), so a multi-cell glyph still yields a `width`-wide track.
  * - `styler` — colors the FILLED run when supplied (the empty run + the trailing label stay plain);
  *   the layout is identical with or without color, since the track is measured on visible width.
+ * - `style` — an optional by-value style rendered through `styler` for the filled run.
  */
 export declare interface ProgressBarOptions {
     readonly current: number;
@@ -1345,6 +1444,7 @@ export declare interface ProgressBarOptions {
     readonly fill?: string;
     readonly empty?: string;
     readonly styler?: StylerInterface;
+    readonly style?: Style;
 }
 
 /**
@@ -1424,10 +1524,14 @@ export declare interface ProgressInterface {
  *   `complete` / `failure` argument.
  * - `width` — the bar track's visible cell count, handed to {@link import('./helpers.js').renderBar};
  *   defaults to {@link DEFAULT_BAR_WIDTH}.
+ * - `fill` / `empty` — the filled and empty track glyphs handed to
+ *   {@link import('./helpers.js').renderBar}; default to {@link BAR_FILL} / {@link BAR_EMPTY}.
  * - `sink` — where each `\r` + bar line is written; defaults to
  *   {@link import('./factories.js').createConsoleSink}. A TTY sink (C-g) overwrites on the `\r`.
  * - `styler` — the {@link StylerInterface} the filled run is colored through; defaults to
  *   {@link import('./factories.js').createStyler} (ANSI). The ONE styler the whole system shares.
+ * - `theme` — the {@link Theme} supplying the filled run's accent role; defaults to
+ *   {@link DEFAULT_THEME}.
  */
 export declare interface ProgressOptions {
     readonly on?: EmitterHooks<ProgressEventMap>;
@@ -1435,8 +1539,11 @@ export declare interface ProgressOptions {
     readonly total: number;
     readonly message?: string;
     readonly width?: number;
+    readonly fill?: string;
+    readonly empty?: string;
     readonly sink?: SinkInterface;
     readonly styler?: StylerInterface;
+    readonly theme?: Theme;
 }
 
 /**
@@ -1562,7 +1669,7 @@ export declare function renderTable(options: TableOptions): 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
+ * {@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
@@ -1593,16 +1700,17 @@ export declare function renderTree(options: TreeOptions): string;
  *
  * @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']
  * ```
  */
-export declare function renderTreeChildren(nodes: readonly TreeNode[], prefix: string, styler?: StylerInterface): readonly string[];
+export declare function renderTreeChildren(nodes: readonly TreeNode[], prefix: string, options: Required<Pick<TreeOptions, 'border'>> & Pick<TreeOptions, 'style' | 'styler'>): readonly string[];
 
 /**
  * Repeat `unit` until it fills exactly `count` VISIBLE columns, trimming a trailing partial
@@ -1638,7 +1746,7 @@ export declare function repeatTo(unit: string, count: number): string;
  *   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
@@ -1719,6 +1827,8 @@ export declare interface ReporterInterface {
  * - `styler` — the {@link StylerInterface} every line is colored through; defaults to
  *   {@link import('./factories.js').createStyler} (ANSI). The ONE styler the whole system
  *   shares — no second colorizer. A disabled styler yields plain narration.
+ * - `theme` — the {@link Theme} supplying status, accent, and chrome roles; defaults to
+ *   {@link DEFAULT_THEME}.
  * - `width` — the default column width handed to the separator / box renderers (the section
  *   rule, a `box` with no explicit width); defaults to {@link DEFAULT_WIDTH}.
  *
@@ -1728,6 +1838,7 @@ export declare interface ReporterInterface {
 export declare interface ReporterOptions {
     readonly sink?: SinkInterface;
     readonly styler?: StylerInterface;
+    readonly theme?: Theme;
     readonly width?: number;
 }
 
@@ -1764,12 +1875,14 @@ export declare const SEPARATOR_TITLE_GAP = " ";
  *   (`─`). The VISIBLE width of the rule is `width` regardless of the fill's escape codes.
  * - `styler` — colors the rule (and the embedded title) when supplied; the layout is
  *   identical with or without it, since width is measured on the visible content.
+ * - `style` — an optional by-value style rendered through `styler` for the rule and title.
  */
 export declare interface SeparatorOptions {
     readonly title?: string;
     readonly width?: number;
     readonly fill?: string;
     readonly styler?: StylerInterface;
+    readonly style?: Style;
 }
 
 /**
@@ -1794,7 +1907,8 @@ export declare interface SinkInterface {
      * Write one already-formatted chunk of output. `text` receives ONE LINE WITHOUT its
      * terminator — the sink's target supplies it (e.g. `console.log`; the server TTY sink
      * appends one) — UNLESS `text` begins with `\r`: that is an in-place REDRAW frame (the
-     * Spinner / Progress animation protocol) carrying its own line endings, written verbatim.
+     * Spinner / Progress animation protocol), written verbatim. A tick frame carries no
+     * terminator; a final frame carries its own.
      * `level` is the originating record's {@link LogLevel} — supplied so a stream-aware sink
      * can route (e.g. `error` to `stderr`); a plain sink ignores it.
      */
@@ -1821,7 +1935,7 @@ export declare interface SinkInterface {
  * - **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}
@@ -1905,7 +2019,7 @@ export declare type SpinnerEventMap = {
  * - **Idempotent `start`.** A `start()` while already `active` is a no-op (it never arms a second
  *   timer). `active` reflects whether the timer is currently armed.
  * - **Outcome lines.** `success(message?)` / `failure(message?)` clear the timer, then write + emit a
- *   FINAL line — the {@link STATUS_ICONS} `✔` / `✖` (colored via {@link STATUS_COLORS}) + the
+ *   FINAL line — the theme's success / error status icon + style (`✔` / `✖` by default) + the
  *   message — terminated by a newline (the activity is over; the line is committed, not overwritten).
  *   `failure` routes to the sink's error stream.
  * - **Lifecycle (§10).** `stop()` clears the timer and LEAVES the current line (no final write);
@@ -1952,6 +2066,8 @@ export declare interface SpinnerInterface {
  *   {@link import('./factories.js').createConsoleSink}. A TTY sink (C-g) overwrites on the `\r`.
  * - `styler` — the {@link StylerInterface} the glyph is colored through; defaults to
  *   {@link import('./factories.js').createStyler} (ANSI). The ONE styler the whole system shares.
+ * - `theme` — the {@link Theme} supplying the accent and outcome roles; defaults to
+ *   {@link DEFAULT_THEME}.
  */
 export declare interface SpinnerOptions {
     readonly on?: EmitterHooks<SpinnerEventMap>;
@@ -1961,6 +2077,7 @@ export declare interface SpinnerOptions {
     readonly interval?: number;
     readonly sink?: SinkInterface;
     readonly styler?: StylerInterface;
+    readonly theme?: Theme;
 }
 
 /**
@@ -2102,51 +2219,6 @@ export declare interface Style {
     readonly attributes: readonly Attribute[];
 }
 
-/**
- * The fluent, composable styler — the consumer-facing API over the style engine. It
- * builds a {@link Style} (style as DATA) and renders it through an injected
- * {@link RendererInterface} (the ANSI default, or a browser `%c` renderer at C-f). Each
- * color / attribute accessor is immutable copy-on-write: it returns a NEW styler's
- * surface with the token added, so `styler.red.bold('hi')` composes without mutating,
- * and a base styler is freely reusable.
- *
- * @remarks
- * - **Callable surface.** A `Styler` is not itself callable; its {@link surface} getter
- *   returns the {@link StylerInterface} — a render FUNCTION carrying the chainable
- *   accessors. The accessors are installed as LAZY getters (`Object.defineProperties`),
- *   so a chain materializes only the stylers it actually walks — never the full tree —
- *   and the recursion terminates. The factory returns that surface; this class is the
- *   engine behind it.
- * - **Immutable.** `#foreground` and `#attribute` return a fresh `Styler` (the style is
- *   rebuilt, never mutated). A later color of the same channel WINS (last write); a
- *   repeated attribute is idempotent (de-duplicated, order preserved).
- * - **`enabled` switch.** When `false`, the render function returns text VERBATIM — no
- *   renderer call, no escape codes (for a non-TTY / `NO_COLOR` / piped output).
- * - **Event-free** — a pure styling primitive (AGENTS §13), like `Scheduler`.
- */
-export declare class Styler {
-    #private;
-    constructor(renderer: RendererInterface, enabled: boolean, style: Style);
-    /** The accumulated style DATA — the empty style on a base styler. */
-    get style(): Style;
-    /** Whether styling is applied; when `false`, the surface returns text unchanged. */
-    get enabled(): boolean;
-    /**
-     * The fluent {@link StylerInterface} value — a render function (`text => string`) with
-     * `style`, `enabled`, and every {@link Color} / {@link Attribute} as a LAZY accessor
-     * (each computes the next styler's surface only when read). This is what consumers
-     * hold and call.
-     *
-     * @remarks
-     * The accessors are defined as getters (not eagerly-merged values), so accessing one
-     * builds exactly one child styler — the tree is never fully materialized and the
-     * construction terminates. The assembled function is then narrowed to
-     * {@link StylerInterface} through {@link #isSurface} (a real structural check), so no
-     * type assertion is used (AGENTS §1 / §14 — narrow, never assert).
-     */
-    get surface(): StylerInterface;
-}
-
 /**
  * The fluent, composable styling surface — the consumer-facing API. It is BOTH a
  * function (call it with text to render the accumulated style) AND a record of
@@ -2159,6 +2231,10 @@ export declare class Styler {
  *   styler is reusable and the chains never interfere.
  * - Calling the styler builds the {@link Style} under the hood and renders it through the
  *   injected renderer. When `enabled` is `false`, it returns the text verbatim.
+ * - `render` is the DATA door beside the accessor chain: it renders a {@link Style} value
+ *   (a {@link Theme} role, say) merged over the accumulated style, so a caller styles by
+ *   value where the chain styles by name. Both go through the same renderer and the same
+ *   `enabled` switch.
  * - `style` exposes the accumulated style DATA (the empty style on a base styler), and
  *   `enabled` reflects the switch — both inspectable and testable.
  * - A later color of the same channel wins (`styler.red.blue` is blue); a repeated
@@ -2171,6 +2247,26 @@ export declare interface StylerInterface {
     readonly style: Style;
     /** Whether styling is applied; when `false`, calls return text unchanged. */
     readonly enabled: boolean;
+    /**
+     * Render `text` in `style` merged OVER the accumulated style — the by-value counterpart
+     * of the accessor chain, and the door a {@link Theme} role is applied through.
+     *
+     * @param style - The style to overlay; its colors win over the accumulated ones and its
+     * attributes join them (de-duplicated, 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: Style, text: string): string;
     readonly black: StylerInterface;
     readonly red: StylerInterface;
     readonly green: StylerInterface;
@@ -2223,25 +2319,71 @@ export declare interface StylerOptions {
  * - `styler` — colors the border + header labels when supplied; the cells are written as
  *   given (already-styled cells are honored — their VISIBLE width drives column sizing, never
  *   their raw `.length`).
+ * - `style` — an optional by-value style rendered through `styler` for the frame and headers.
  */
 export declare interface TableOptions {
     readonly columns: readonly ColumnSpec[];
-    readonly rows: readonly (readonly string[])[];
+    readonly rows: ReadonlyArray<readonly string[]>;
     readonly border?: BorderStyle;
     readonly styler?: StylerInterface;
+    readonly style?: Style;
+}
+
+/**
+ * The app-wide semantic style vocabulary — every role the console system styles, bound to a
+ * {@link Style} value. Pass one theme to a logger / reporter / spinner / progress and every
+ * surface speaks it.
+ *
+ * @remarks
+ * - `levels` — the label style per {@link LogLevel} (a log line's severity label).
+ * - `statuses` — the icon + style per {@link StatusLevel} (a reporter outcome, a spinner's
+ *   final line).
+ * - `accent` — the one highlight role: a spinner glyph, a progress bar's filled run, a
+ *   step prefix.
+ * - `chrome` — the frame role: separators, box / table / tree connectors, and a log line's
+ *   timestamp / name / data surround.
+ * - A theme is the vocabulary the WHOLE application shares; a per-entity option (a
+ *   `ProgressOptions.fill`, a `BoxOptions.border`) is the presentation of that one instance.
+ * - A theme returned by {@link createTheme} is frozen with every {@link Style} leaf deeply
+ *   frozen, so one theme is safely shared across every entity.
+ */
+export declare interface Theme {
+    readonly levels: Readonly<Record<LogLevel, Style>>;
+    readonly statuses: Readonly<Record<StatusLevel, ThemeStatus>>;
+    readonly accent: Style;
+    readonly chrome: Style;
+}
+
+/**
+ * Options for {@link createTheme} — the roles to override on {@link DEFAULT_THEME}.
+ *
+ * @remarks
+ * Every key is optional and merges per ROLE, never per theme: an omitted role keeps its
+ * default, and `levels` / `statuses` merge per entry, so `{ levels: { warn: … } }` restyles
+ * the `warn` label and leaves the other three alone. A status override supplies its whole
+ * `{ icon, style }` record; {@link createTheme} snapshots and freezes that record and every
+ * style leaf it receives.
+ */
+export declare interface ThemeOptions {
+    readonly levels?: Readonly<Partial<Record<LogLevel, Style>>>;
+    readonly statuses?: Readonly<Partial<Record<StatusLevel, ThemeStatus>>>;
+    readonly accent?: Style;
+    readonly chrome?: Style;
 }
 
 /**
- * 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.
+ * One narrative outcome's presentation — the icon glyph a {@link StatusLevel} shows and the
+ * {@link Style} the line renders in.
+ *
+ * @remarks
+ * The themed counterpart of the {@link STATUS_ICONS} / {@link STATUS_COLORS} defaults: those
+ * two constants are the SOURCE of {@link DEFAULT_THEME}'s statuses. A status override supplies
+ * the whole record — both `icon` and `style` — through {@link ThemeOptions}.
  */
-export declare const TREE_CHARS: Readonly<{
-    branch: "├─ ";
-    corner: "└─ ";
-    guide: "│  ";
-    gap: "   ";
-}>;
+export declare interface ThemeStatus {
+    readonly icon: string;
+    readonly style: Style;
+}
 
 /**
  * One node of a {@link TreeOptions} tree — a label plus optional children, recursively.
@@ -2264,11 +2406,16 @@ export declare interface TreeNode {
  * - `root` — the top {@link TreeNode}; its `label` is the unindented first line and its
  *   `children` descend beneath it (`├─` for each but the last, `└─` for the last, `│` guides
  *   carried down through earlier branches).
+ * - `border` — the {@link BorderStyle} whose junction set supplies every connector;
+ *   defaults to {@link DEFAULT_BORDER} (`single`).
  * - `styler` — colors the connectors when supplied; node labels are written as given.
+ * - `style` — an optional by-value style rendered through `styler` for the connectors.
  */
 export declare interface TreeOptions {
     readonly root: TreeNode;
+    readonly border?: BorderStyle;
     readonly styler?: StylerInterface;
+    readonly style?: Style;
 }
 
 /**