@orkestrel/console 0.0.4 → 0.0.6

package/dist/src/core/index.js

@@ -452,6 +452,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.
@@ -977,271 +1098,116 @@ function renderBar(options) {
 	const filledCells = Math.round(fraction * track);
 	return `${`${paint(options.styler, repeatTo(fill, filledCells))}${repeatTo(empty, track - filledCells)}`} ${Math.round(fraction * 100)}% (${current}/${options.total})`;
 }
-//#endregion
-//#region src/core/ANSIRenderer.ts
-/**
-* The cross-environment default {@link RendererInterface} — renders style DATA as ANSI
-* SGR escape codes, exactly as `Scheduler` is the `setTimeout` default for its seam. It
-* is the single styling output the whole console / terminal system uses in a terminal;
-* the browser `%c` / CSS renderer (the C-f branch) implements the SAME contract over
-* the SAME {@link Style}, so retargeting changes the renderer, never the style model.
-*
-* @remarks
-* - **Style is DATA in, SGR string out.** It reads the style's `foreground` /
-*   `background` / `attributes` and emits one `ESC[…m` sequence whose parameters are the
-*   mapped SGR numbers (foreground 30–37 / 90–97, background 40–47 / 100–107, attributes
-*   1 / 2 / 3 / 4 / 7 / 9), followed by `text`, terminated by the reset `ESC[0m`.
-* - **Multiple attributes compose** — their codes join with `;` in a single sequence
-*   (`ESC[1;4;31m` for bold + underline + red), so one open and one reset wrap the run.
-* - **`default` and unset colors emit no code** — a `default` (or absent) `foreground` /
-*   `background` leaves the terminal's own ink.
-* - **The empty style and the empty string pass through** — when there is nothing to
-*   apply (no colors, no attributes) or `text` is `''`, `text` is returned VERBATIM with
-*   no escape codes, so an unstyled render never injects a stray reset.
-* - **Stateless and event-free** — no fields, no events; safe to share one instance.
-*/
-var ANSIRenderer = class {
-	/**
-	* Wrap `text` in the SGR codes for `style`. Returns `text` unchanged when the style
-	* is empty or `text` is `''`.
-	*/
-	render(style, text) {
-		if (text === "") return text;
-		const codes = this.#codes(style);
-		if (codes.length === 0) return text;
-		return `${CSI}${codes.join(";")}m${text}${RESET}`;
-	}
-	#codes(style) {
-		const codes = [];
-		for (const attribute of style.attributes) codes.push(ATTRIBUTE_CODES[attribute]);
-		if (style.foreground !== void 0 && style.foreground !== "default") codes.push(FOREGROUND_CODES[style.foreground]);
-		if (style.background !== void 0 && style.background !== "default") codes.push(BACKGROUND_CODES[style.background]);
-		return codes;
-	}
-};
-//#endregion
-//#region src/core/Styler.ts
 /**
-* The fluent, composable styler — the consumer-facing API over the style engine. It
-* builds a {@link Style} (style as DATA) and renders it through an injected
-* {@link RendererInterface} (the ANSI default, or a browser `%c` renderer at C-f). Each
-* color / attribute accessor is immutable copy-on-write: it returns a NEW styler's
-* surface with the token added, so `styler.red.bold('hi')` composes without mutating,
-* and a base styler is freely reusable.
+* 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}.
 *
-* @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}.
+* @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
-* - **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.
+* - **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
-* 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()
+* 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;
 	}
-	#retain(message) {
-		this.#push(this.#messages, message);
-		const bucket = this.#buckets.get(message.level);
-		if (bucket !== void 0) this.#push(bucket, message);
+}
+//#endregion
+//#region src/core/ANSIRenderer.ts
+/**
+* The cross-environment default {@link RendererInterface} — renders style DATA as ANSI
+* SGR escape codes, exactly as `Scheduler` is the `setTimeout` default for its seam. It
+* is the single styling output the whole console / terminal system uses in a terminal;
+* the browser `%c` / CSS renderer (the C-f branch) implements the SAME contract over
+* the SAME {@link Style}, so retargeting changes the renderer, never the style model.
+*
+* @remarks
+* - **Style is DATA in, SGR string out.** It reads the style's `foreground` /
+*   `background` / `attributes` and emits one `ESC[…m` sequence whose parameters are the
+*   mapped SGR numbers (foreground 30–37 / 90–97, background 40–47 / 100–107, attributes
+*   1 / 2 / 3 / 4 / 7 / 9), followed by `text`, terminated by the reset `ESC[0m`.
+* - **Multiple attributes compose** — their codes join with `;` in a single sequence
+*   (`ESC[1;4;31m` for bold + underline + red), so one open and one reset wrap the run.
+* - **`default` and unset colors emit no code** — a `default` (or absent) `foreground` /
+*   `background` leaves the terminal's own ink.
+* - **The empty style and the empty string pass through** — when there is nothing to
+*   apply (no colors, no attributes) or `text` is `''`, `text` is returned VERBATIM with
+*   no escape codes, so an unstyled render never injects a stray reset.
+* - **Stateless and event-free** — no fields, no events; safe to share one instance.
+*/
+var ANSIRenderer = class {
+	/**
+	* Wrap `text` in the SGR codes for `style`. Returns `text` unchanged when the style
+	* is empty or `text` is `''`.
+	*/
+	render(style, text) {
+		if (text === "") return text;
+		const codes = this.#codes(style);
+		if (codes.length === 0) return text;
+		return `${CSI}${codes.join(";")}m${text}${RESET}`;
 	}
-	#push(buffer, message) {
-		buffer.push(message);
-		if (buffer.length > this.#limit) buffer.shift();
+	#codes(style) {
+		const codes = [];
+		for (const attribute of style.attributes) codes.push(ATTRIBUTE_CODES[attribute]);
+		if (style.foreground !== void 0 && style.foreground !== "default") codes.push(FOREGROUND_CODES[style.foreground]);
+		if (style.background !== void 0 && style.background !== "default") codes.push(BACKGROUND_CODES[style.background]);
+		return codes;
 	}
 };
 //#endregion
@@ -1650,6 +1616,110 @@ 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).
+* - **`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/factories.ts
 /**
 * Create the cross-environment default {@link RendererInterface} — the ANSI / SGR
@@ -1875,76 +1945,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
@@ -2112,6 +2112,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_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 };
 
 //# sourceMappingURL=index.js.map