@orkestrel/console 0.0.12 → 0.0.13

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

@@ -1,8 +1,8 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { LogLevel } from '@orkestrel/console';
-import { SinkInterface } from '@orkestrel/console';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { LogLevel } from '@orkestrel/console';
+import type { SinkInterface } from '@orkestrel/console';
 
 /**
  * Represents one intercepted process-stream write — the immutable, serializable record a
@@ -25,21 +25,20 @@ export declare interface CapturedChunk {
 }
 
 /**
- * Creates the server TTY {@link ServerSinkInterface} — the server output backend, the
- * env-symmetric sibling of `createBrowserSink` / core's `createConsoleSink`. `write(text, level?)`
- * routes by level to the process streams and uses construction-time styled facts: it sends ANSI
- * straight to a styled target (with a leading `\r` overwriting a terminal line natively) but
- * {@link import('@src/core').strip}s ANSI to clean text for a plain target.
+ * Creates the server TTY {@link ServerSinkInterface} — the server output backend, whose
+ * `write(text, level?)` routes by level to the process streams and uses construction-time styled
+ * facts: it sends ANSI straight to a styled target (with a leading `\r` overwriting a terminal
+ * line natively) but {@link import('@orkestrel/console').strip}s ANSI to clean text for a plain target.
  *
  * @param options - See {@link ServerSinkOptions}
- * @returns A {@link ServerSinkInterface} — a {@link import('@src/core').SinkInterface} that also
+ * @returns A {@link ServerSinkInterface} — a {@link import('@orkestrel/console').SinkInterface} that also
  *   exposes the terminal `columns` width
  *
  * @remarks
  * - **Routes by level.** `error` / `warn` → the error stream (`process.stderr` by default), every
  *   other level (and an omitted level) → the `stdout` stream (`process.stdout`) — the same routing
  *   as core's `createConsoleSink`, so a logger's `error` reaches `stderr`. Both call the one
- *   {@link import('@src/core').selectWriter} leaf, which is what keeps them identical.
+ *   {@link import('@orkestrel/console').selectWriter} leaf, which is what keeps them identical.
  * - **Per-target styled facts.** At construction, each target uses `options.styled` when supplied;
  *   otherwise {@link inferStyled} applies the injected `environment` (default `process.env`) and
  *   then that target's `isTTY`.
@@ -55,16 +54,29 @@ export declare interface CapturedChunk {
  *   the sink (and the isTTY-strip path) with a fake stream that never touches the real process
  *   streams.
  *
- * @example
+ * @example The server — a TTY sink and a process capture
  * ```ts
  * import { createStyler, Logger, Reporter } from '@orkestrel/console'
- * import { createServerSink } from '@orkestrel/console/server'
+ * import { createServerSink, ProcessCapture } from '@orkestrel/console/server'
+ *
+ * const sink = createServerSink() // FORCE_COLOR, then NO_COLOR, then isTTY — per target, at construction
+ * const styler = createStyler({ enabled: sink.styled }) // keep generated ANSI paired with the sink's stdout stripping
+ * const logger = new Logger({ name: 'server', sink, styler })
+ * logger.error('boom') // → process.stderr (the error stream)
+ * const reporter = new Reporter({ sink, width: sink.columns }) // size the layout to the live terminal
+ *
+ * // `styled` overrides the inference outright — for a CI log that renders ANSI off a TTY, say.
+ * const forced = createServerSink({ styled: true })
+ * forced.styled // true, whatever the environment and the streams say
  *
- * const sink = createServerSink()
- * const styler = createStyler({ enabled: sink.styled })
- * const logger = new Logger({ name: 'app', sink, styler })
- * logger.error('boom') // → process.stderr, ANSI rendered on a TTY / stripped to a pipe
- * const reporter = new Reporter({ sink, width: sink.columns })
+ * // Own every output path — a direct process.stdout.write, library output, child-process pipes:
+ * const capture = new ProcessCapture({ levels: ['stderr'], mirror: true })
+ * capture.start()
+ * process.stderr.write('a library diagnostic\n') // captured and still shown (mirror: true)
+ * capture.messages('stderr') // [{ level: 'stderr', text: 'a library diagnostic\n', time: … }]
+ * capture.clear() // drop buffered chunks; interception is unaffected
+ * capture.stop()
+ * capture.destroy() // stop() then tear down the emitter
  * ```
  */
 export declare function createServerSink(options?: ServerSinkOptions): ServerSinkInterface;
@@ -103,24 +115,29 @@ export declare function decodeChunk(chunk: unknown, encoding?: unknown): string;
 
 /**
  * Sets the terminal width {@link import('./factories.js').createServerSink} reports through
- * {@link import('./types.js').ServerSinkInterface.columns} when the `stdout` stream is not a TTY (so
- * `.columns` is `undefined`) and no explicit `options.columns` was supplied — the conventional
+ * {@link import('./types.js').ServerSinkInterface.columns} when the `stdout` stream is not a TTY
+ * (so `.columns` is `undefined`) and no explicit `options.columns` was supplied — the conventional
  * 80-column default a non-interactive context (a pipe, a CI log) assumes.
  */
 export declare const DEFAULT_COLUMNS = 80;
 
 /**
- * Sets the default bounded-buffer cap for a {@link import('./types.js').ProcessCaptureInterface} — at
- * most this many recent {@link import('./types.js').CapturedChunk}s are retained per buffer (the
- * total buffer and each per-stream bucket; oldest dropped first). Mirrors the core `Capture`'s
- * `DEFAULT_CAPTURE_LIMIT`; a consumer overrides it through `options.limit`.
+ * Sets the default bounded-buffer cap for a {@link import('./types.js').ProcessCaptureInterface} —
+ * `1000`, so at most that many recent {@link import('./types.js').CapturedChunk}s are retained per
+ * buffer (the total buffer and each per-stream bucket; oldest dropped first) and retention is
+ * always bounded.
+ *
+ * @remarks
+ * It mirrors the core `Capture`'s `DEFAULT_CAPTURE_LIMIT`; a consumer overrides the cap through
+ * `options.limit`.
  */
 export declare const DEFAULT_STREAM_LIMIT = 1000;
 
 /**
- * Infers the width in character cells of a stream target — its live `columns` when it is a TTY, else
- * the non-interactive {@link DEFAULT_COLUMNS} fallback. The basis a {@link import('./types.js').ServerSinkInterface}
- * reports through `columns` so a `Reporter` / `Progress` can size its layout to the terminal.
+ * Infers the width in character cells of a stream target — its live `columns` when it is a TTY,
+ * else the non-interactive {@link DEFAULT_COLUMNS} fallback. The basis a
+ * {@link import('./types.js').ServerSinkInterface} reports through `columns` so a `Reporter` /
+ * `Progress` can size its layout to the terminal.
  *
  * @remarks
  * Reads `target.columns` on each call (so a getter-backed real stream reflects a live resize) and
@@ -133,14 +150,14 @@ export declare const DEFAULT_STREAM_LIMIT = 1000;
 export declare function inferColumns(target: StreamTargetInterface): number;
 
 /**
- * Infers whether one stream target receives styled output. The result is a construction-time
- * target fact for {@link import('./factories.js').createServerSink}; this helper is pure and never
- * reads process globals itself.
+ * Infers whether one stream target receives styled output — a present `FORCE_COLOR` first, then a
+ * non-empty `NO_COLOR`, then `target.isTTY === true`.
  *
  * @remarks
- * A present `FORCE_COLOR` key has first precedence: only the exact value `'0'` disables styling.
- * Next, a non-empty `NO_COLOR` disables styling. Otherwise styling follows
- * `target.isTTY === true`.
+ * The result is a construction-time target fact for
+ * {@link import('./factories.js').createServerSink}; this helper is pure and
+ * never reads process globals itself. Under `FORCE_COLOR` only the exact value `'0'` disables
+ * styling.
  *
  * @param target - The stream target whose terminal capability is the fallback
  * @param environment - The environment record supplying `FORCE_COLOR` and `NO_COLOR`
@@ -155,9 +172,9 @@ export declare function inferColumns(target: StreamTargetInterface): number;
 export declare function inferStyled(target: StreamTargetInterface, environment: Readonly<Record<string, string | undefined>>): boolean;
 
 /**
- * Checks whether `encoding` is a {@link BufferEncoding} accepted by `Buffer.prototype.toString` — a total
- * guard used by {@link import('./helpers.js').decodeChunk} to honor a process-write `encoding`
- * argument only when it is a real Node encoding (otherwise utf-8 is assumed).
+ * Checks whether `encoding` is a {@link BufferEncoding} accepted by `Buffer.prototype.toString` — a
+ * total guard used by {@link import('./helpers.js').decodeChunk} to honor a process-write
+ * `encoding` argument only when it is a real Node encoding (otherwise utf-8 is assumed).
  *
  * @param encoding - The candidate encoding (the second `write` argument, possibly a callback)
  * @returns True if `encoding` names a supported buffer encoding; false otherwise
@@ -250,10 +267,13 @@ export declare class ProcessCapture implements ProcessCaptureInterface {
 }
 
 /**
- * Declares the observable events a {@link ProcessCaptureInterface} emits — mirrors the core
- * `Capture`'s `CaptureEventMap`, but the captured record is a {@link CapturedChunk} (stream-keyed).
+ * Declares the observable events a {@link ProcessCaptureInterface} emits — `capture(chunk)` per
+ * intercepted write, plus the `start` and `stop` signals.
  *
  * @remarks
+ * The map mirrors the core `Capture`'s `CaptureEventMap`, and the captured record is a
+ * {@link CapturedChunk} (stream-keyed).
+ *
  * - `capture` — an intercepted `process.stdout` / `process.stderr` write, carrying the frozen
  *   {@link CapturedChunk}. The hook a live log viewer / tee subscribes to.
  * - `start` / `stop` — the interception toggled on / off (pure signals, empty tuples).
@@ -275,13 +295,14 @@ export declare type ProcessCaptureEventMap = {
 };
 
 /**
- * Declares an observable interceptor of the raw process output streams — the server's
- * "own all output" capture. Where the core `Capture` patches `console.*` (the high-level read
- * side), this patches `process.stdout.write` / `process.stderr.write` (the low-level stream), so it
- * catches direct `process.stdout.write`, third-party library output, and child-process pipes —
- * everything that reaches the streams, not only `console.*`.
+ * Declares an observable interceptor of the raw process output streams — the server's "own all
+ * output" capture, patching `process.stdout.write` / `process.stderr.write` on the low-level
+ * stream where the core `Capture` patches `console.*`.
  *
  * @remarks
+ * Patching the stream catches a direct `process.stdout.write`, third-party library output, and
+ * child-process pipes — everything that reaches the streams, not only `console.*`.
+ *
  * - **Snapshot-at-start (the no-capture-loop principle).** `start()` snapshots the current
  *   `process[stream].write` for each configured {@link StreamLevel}, then installs the wrappers. The
  *   mirror replays through that snapshot — so a server sink created from the same streams before the
@@ -307,7 +328,10 @@ export declare interface ProcessCaptureInterface {
     start(): void;
     /** Restores the pristine `process.*.write` references (idempotent; emits `stop`). */
     stop(): void;
-    /** Returns a copy of the full captured buffer, oldest first (capped at `limit`). */
+    /**
+     * Returns a copy of the full captured buffer, oldest first (capped at `limit`), or — given a
+     * {@link StreamLevel} — a copy of only that stream's bucket.
+     */
     messages(): readonly CapturedChunk[];
     /** Returns a copy of the captured buffer for one {@link StreamLevel}, oldest first (capped at `limit`). */
     messages(level: StreamLevel): readonly CapturedChunk[];
@@ -318,9 +342,10 @@ export declare interface ProcessCaptureInterface {
 }
 
 /**
- * Holds the options for the {@link import('./ProcessCapture.js').ProcessCapture} constructor — every
- * field optional, so a bare `new ProcessCapture()` buffers both streams without mirroring or
- * forwarding.
+ * Holds the options for the {@link import('./ProcessCapture.js').ProcessCapture} constructor — the
+ * `on` / `error` emitter keys, the `levels` intercepted, the `mirror` pass-through, the `sink`
+ * forward, and the buffer `limit`. Every field is optional, so a bare `new ProcessCapture()`
+ * buffers both streams without mirroring or forwarding.
  *
  * @remarks
  * - `on` — initial {@link ProcessCaptureEventMap} listeners, wired at construction (for example
@@ -332,7 +357,7 @@ export declare interface ProcessCaptureInterface {
  *   `write` (bound to its stream), so the output still reaches the terminal while being captured;
  *   defaults to `false` (capture-only, the program's output is swallowed into the buffer).
  * - `sink` — an optional {@link SinkInterface} each intercepted chunk is also written to
- *   (`sink.write(text, level)` with the {@link StreamLevel} mapped to a {@link import('@src/core').LogLevel} through
+ *   (`sink.write(text, level)` with the {@link StreamLevel} mapped to a {@link import('@orkestrel/console').LogLevel} through
  *   {@link import('./constants.js').STREAM_LEVEL_MAP}), to tee captured output into the logging
  *   pipeline / a file. Absent by default.
  * - `limit` — the bounded-buffer cap (total and each per-stream bucket); defaults to
@@ -348,13 +373,16 @@ export declare interface ProcessCaptureOptions {
 }
 
 /**
- * Declares a {@link SinkInterface} that also exposes the target terminal's {@link columns} width — the shape
- * {@link import('./factories.js').createServerSink} returns. It is a drop-in {@link SinkInterface}
- * (so a `Logger` / `Reporter` / `Spinner` / `Progress` takes it as `sink`) whose extra `columns`
- * getter lets a consumer size a `Reporter`'s layout to the live terminal. Its `styled` fact lets
- * the same consumer enable or disable its styler for the `stdout` target.
+ * Declares a {@link SinkInterface} that also exposes the `stdout` target's construction-time
+ * `styled` fact and the terminal's live or fixed {@link columns} width — the shape
+ * {@link import('./factories.js').createServerSink} returns.
  *
  * @remarks
+ * It is a drop-in {@link SinkInterface} (so a `Logger` / `Reporter` / `Spinner` / `Progress`
+ * takes it as `sink`) whose extra `columns` getter lets a consumer size a `Reporter`'s layout to
+ * the live terminal, and whose `styled` fact lets the same consumer enable or disable its styler
+ * for the `stdout` target.
+ *
  * - `styled` is the `stdout` target's construction-time fact. The sink handles `stderr` through its
  *   own independently inferred fact because the two targets can differ.
  * - `columns` is a getter, re-read on every access — so it reflects the current terminal width (a
@@ -366,8 +394,10 @@ export declare interface ServerSinkInterface extends SinkInterface {
 }
 
 /**
- * Holds the options for {@link import('./factories.js').createServerSink} — all optional, so a bare
- * `createServerSink()` writes to the real process streams.
+ * Holds the options for {@link import('./factories.js').createServerSink} — the `stdout` and
+ * `stderr` targets, the `styled` override, the `environment` inference reads, and an explicit
+ * `columns` width. All are optional, so a bare `createServerSink()` writes to the real process
+ * streams.
  *
  * @remarks
  * - `stdout` — the stream `info` / `debug` (and an omitted level) are written to; defaults to
@@ -391,48 +421,51 @@ export declare interface ServerSinkOptions {
 }
 
 /**
- * Maps each {@link StreamLevel} to its {@link LogLevel} for the optional sink forward — the projection a
- * process capture routes through when writing an intercepted chunk to a
- * {@link import('@src/core').SinkInterface}
- * (`sink.write(text, STREAM_LEVEL_MAP[level])`). `stderr` is conventionally the error/diagnostic
- * stream → `error`; `stdout` is the normal output stream → `info`. The source of truth for the
- * stream-to-log projection (the server analogue of the core `CAPTURE_LEVEL_MAP`).
+ * Maps each {@link StreamLevel} to its {@link LogLevel} for the optional sink forward — the
+ * projection a process capture routes through when writing an intercepted chunk to a
+ * {@link import('@orkestrel/console').SinkInterface}. `sink.write(text, STREAM_LEVEL_MAP[level])` is the
+ * call this map backs. `stderr` is conventionally the error/diagnostic stream → `error`; `stdout`
+ * is the normal output stream → `info`. The source of truth for the stream-to-log projection (the
+ * server analogue of the core `CAPTURE_LEVEL_MAP`).
  */
 export declare const STREAM_LEVEL_MAP: Readonly<Record<StreamLevel, LogLevel>>;
 
 /**
- * Lists the two process streams a {@link import('./types.js').ProcessCaptureInterface} can intercept, in
- * `stdout`-then-`stderr` order — the {@link StreamLevel} universe and the default configured set.
+ * Lists the process streams a {@link import('./types.js').ProcessCaptureInterface} can intercept,
+ * in `stdout`-then-`stderr` order — the {@link StreamLevel} universe and the default configured
+ * set.
  */
 export declare const STREAM_LEVELS: readonly StreamLevel[];
 
 /**
- * Names which process stream a {@link CapturedChunk} came from — the "level" axis of the process-stream
- * {@link ProcessCaptureInterface}, the server analogue of the core `Capture`'s `CaptureLevel`.
+ * Names which process stream a {@link CapturedChunk} came from — `stdout` or `stderr`, the
+ * "level" axis of the process-stream {@link ProcessCaptureInterface} and the server analogue of
+ * the core `Capture`'s `CaptureLevel`.
  *
  * @remarks
- * distinct from {@link import('@src/core').LogLevel}: a `StreamLevel` names the originating process stream
+ * distinct from {@link import('@orkestrel/console').LogLevel}: a `StreamLevel` names the originating process stream
  * (`process.stdout` vs `process.stderr`), not a severity. It is a named value family (it indexes
- * {@link import('./constants.js').STREAM_LEVEL_MAP} to a {@link import('@src/core').LogLevel} for the optional sink
+ * {@link import('./constants.js').STREAM_LEVEL_MAP} to a {@link import('@orkestrel/console').LogLevel} for the optional sink
  * forward), never a binary toggle — so it stays a union.
  */
 export declare type StreamLevel = 'stdout' | 'stderr';
 
 /**
- * Declares the minimal writable-stream shape the server sink and process capture address — exactly the
- * slice of a Node `tty.WriteStream` / `process.stdout` they touch, and no more. A
- * {@link ServerSinkOptions} target and a {@link ProcessCaptureInterface}'s patched streams are
- * narrowed to this through {@link import('./validators.js').isStreamTarget} (narrow the
- * boundary, never `as`), so a test can drive either with a hand-built fake stream that never
- * touches the real `process` streams.
+ * Declares the minimal writable-stream shape the server sink and process capture address — exactly
+ * the slice of a Node `tty.WriteStream` / `process.stdout` they touch and no more.
  *
  * @remarks
+ * A {@link ServerSinkOptions} target and a {@link ProcessCaptureInterface}'s patched streams are
+ * narrowed to this through {@link import('./validators.js').isStreamTarget} (narrow the boundary,
+ * never `as`), so a test can
+ * drive either with a hand-built fake stream that never touches the real `process` streams.
+ *
  * - `write(text)` — the one required method: push a chunk to the stream, returning the host's
  *   backpressure boolean (`false` when the kernel buffer is full). A `process` stream returns it;
  *   a fake may return `void` (read as truthy / no backpressure).
  * - `isTTY` — present and `true` on a real terminal, absent / `false` when the stream is piped to a
  *   file or another process. When no explicit styling override exists, the sink reads it at
- *   construction to decide whether to keep ANSI or {@link import('@src/core').strip} it to clean
+ *   construction to decide whether to keep ANSI or {@link import('@orkestrel/console').strip} it to clean
  *   text.
  * - `columns` — the terminal width in character cells when the stream is a TTY, `undefined`
  *   otherwise; the sink surfaces it as {@link ServerSinkInterface.columns} so a consumer can feed a
@@ -445,8 +478,9 @@ export declare interface StreamTargetInterface {
 }
 
 /**
- * Names the completion callback `process.*.write` accepts as its last argument — the Node `write`
- * callback shape, and the {@link StreamWriteFunction} companion.
+ * Names the completion callback `process.*.write` accepts as its last argument —
+ * `(error?) => void`, the Node `write` callback shape and the {@link StreamWriteFunction}
+ * companion.
  *
  * @remarks
  * The capture wrapper forwards the callback verbatim to the mirror, so a caller's
@@ -455,11 +489,12 @@ export declare interface StreamTargetInterface {
 export declare type StreamWriteCallback = (error?: Error | null) => void;
 
 /**
- * Names the process-stream `write` method a {@link ProcessCaptureInterface} snapshots and swaps at
- * the patch boundary — the write-side analogue of {@link import('@src/core').ConsoleMethod}.
+ * Names the process-stream `write` method a {@link ProcessCaptureInterface} snapshots and swaps
+ * at the patch boundary — `NodeJS.WriteStream['write']` verbatim, the write-side analogue of
+ * {@link import('@orkestrel/console').ConsoleMethod}.
  *
  * @remarks
- * It is taken verbatim as `NodeJS.WriteStream['write']`, the overloaded
+ * The type is the overloaded
  * `(chunk, encoding?, callback?) => boolean` of `process.stdout.write` / `process.stderr.write`.
  * Using the canonical type rather than a hand-rolled approximation keeps snapshot and restore
  * exact and lets the wrapper assign cleanly. A {@link StreamLevel} (`'stdout' | 'stderr'`) is

package/dist/src/server/index.js

@@ -3,31 +3,36 @@ import { Emitter } from "@orkestrel/emitter";
 import { Retention, selectWriter, strip, stripControls } from "../core/index.js";
 //#region src/server/constants.ts
 /**
-* Lists the two process streams a {@link import('./types.js').ProcessCaptureInterface} can intercept, in
-* `stdout`-then-`stderr` order — the {@link StreamLevel} universe and the default configured set.
+* Lists the process streams a {@link import('./types.js').ProcessCaptureInterface} can intercept,
+* in `stdout`-then-`stderr` order — the {@link StreamLevel} universe and the default configured
+* set.
 */
 var STREAM_LEVELS = Object.freeze(["stdout", "stderr"]);
 /**
-* Sets the default bounded-buffer cap for a {@link import('./types.js').ProcessCaptureInterface} — at
-* most this many recent {@link import('./types.js').CapturedChunk}s are retained per buffer (the
-* total buffer and each per-stream bucket; oldest dropped first). Mirrors the core `Capture`'s
-* `DEFAULT_CAPTURE_LIMIT`; a consumer overrides it through `options.limit`.
+* Sets the default bounded-buffer cap for a {@link import('./types.js').ProcessCaptureInterface} —
+* `1000`, so at most that many recent {@link import('./types.js').CapturedChunk}s are retained per
+* buffer (the total buffer and each per-stream bucket; oldest dropped first) and retention is
+* always bounded.
+*
+* @remarks
+* It mirrors the core `Capture`'s `DEFAULT_CAPTURE_LIMIT`; a consumer overrides the cap through
+* `options.limit`.
 */
 var DEFAULT_STREAM_LIMIT = 1e3;
 /**
 * Sets the terminal width {@link import('./factories.js').createServerSink} reports through
-* {@link import('./types.js').ServerSinkInterface.columns} when the `stdout` stream is not a TTY (so
-* `.columns` is `undefined`) and no explicit `options.columns` was supplied — the conventional
+* {@link import('./types.js').ServerSinkInterface.columns} when the `stdout` stream is not a TTY
+* (so `.columns` is `undefined`) and no explicit `options.columns` was supplied — the conventional
 * 80-column default a non-interactive context (a pipe, a CI log) assumes.
 */
 var DEFAULT_COLUMNS = 80;
 /**
-* Maps each {@link StreamLevel} to its {@link LogLevel} for the optional sink forward — the projection a
-* process capture routes through when writing an intercepted chunk to a
-* {@link import('@src/core').SinkInterface}
-* (`sink.write(text, STREAM_LEVEL_MAP[level])`). `stderr` is conventionally the error/diagnostic
-* stream → `error`; `stdout` is the normal output stream → `info`. The source of truth for the
-* stream-to-log projection (the server analogue of the core `CAPTURE_LEVEL_MAP`).
+* Maps each {@link StreamLevel} to its {@link LogLevel} for the optional sink forward — the
+* projection a process capture routes through when writing an intercepted chunk to a
+* {@link import('@src/core').SinkInterface}. `sink.write(text, STREAM_LEVEL_MAP[level])` is the
+* call this map backs. `stderr` is conventionally the error/diagnostic stream → `error`; `stdout`
+* is the normal output stream → `info`. The source of truth for the stream-to-log projection (the
+* server analogue of the core `CAPTURE_LEVEL_MAP`).
 */
 var STREAM_LEVEL_MAP = Object.freeze({
 	stdout: "info",
@@ -60,9 +65,9 @@ function isStreamTarget(value) {
 	return typeof value === "object" && value !== null && "write" in value && typeof value.write === "function";
 }
 /**
-* Checks whether `encoding` is a {@link BufferEncoding} accepted by `Buffer.prototype.toString` — a total
-* guard used by {@link import('./helpers.js').decodeChunk} to honor a process-write `encoding`
-* argument only when it is a real Node encoding (otherwise utf-8 is assumed).
+* Checks whether `encoding` is a {@link BufferEncoding} accepted by `Buffer.prototype.toString` — a
+* total guard used by {@link import('./helpers.js').decodeChunk} to honor a process-write
+* `encoding` argument only when it is a real Node encoding (otherwise utf-8 is assumed).
 *
 * @param encoding - The candidate encoding (the second `write` argument, possibly a callback)
 * @returns True if `encoding` names a supported buffer encoding; false otherwise
@@ -73,9 +78,10 @@ function isBufferEncoding(encoding) {
 //#endregion
 //#region src/server/helpers.ts
 /**
-* Infers the width in character cells of a stream target — its live `columns` when it is a TTY, else
-* the non-interactive {@link DEFAULT_COLUMNS} fallback. The basis a {@link import('./types.js').ServerSinkInterface}
-* reports through `columns` so a `Reporter` / `Progress` can size its layout to the terminal.
+* Infers the width in character cells of a stream target — its live `columns` when it is a TTY,
+* else the non-interactive {@link DEFAULT_COLUMNS} fallback. The basis a
+* {@link import('./types.js').ServerSinkInterface} reports through `columns` so a `Reporter` /
+* `Progress` can size its layout to the terminal.
 *
 * @remarks
 * Reads `target.columns` on each call (so a getter-backed real stream reflects a live resize) and
@@ -91,14 +97,14 @@ function inferColumns(target) {
 	return 80;
 }
 /**
-* Infers whether one stream target receives styled output. The result is a construction-time
-* target fact for {@link import('./factories.js').createServerSink}; this helper is pure and never
-* reads process globals itself.
+* Infers whether one stream target receives styled output — a present `FORCE_COLOR` first, then a
+* non-empty `NO_COLOR`, then `target.isTTY === true`.
 *
 * @remarks
-* A present `FORCE_COLOR` key has first precedence: only the exact value `'0'` disables styling.
-* Next, a non-empty `NO_COLOR` disables styling. Otherwise styling follows
-* `target.isTTY === true`.
+* The result is a construction-time target fact for
+* {@link import('./factories.js').createServerSink}; this helper is pure and
+* never reads process globals itself. Under `FORCE_COLOR` only the exact value `'0'` disables
+* styling.
 *
 * @param target - The stream target whose terminal capability is the fallback
 * @param environment - The environment record supplying `FORCE_COLOR` and `NO_COLOR`
@@ -314,11 +320,10 @@ var ProcessCapture = class {
 //#endregion
 //#region src/server/factories.ts
 /**
-* Creates the server TTY {@link ServerSinkInterface} — the server output backend, the
-* env-symmetric sibling of `createBrowserSink` / core's `createConsoleSink`. `write(text, level?)`
-* routes by level to the process streams and uses construction-time styled facts: it sends ANSI
-* straight to a styled target (with a leading `\r` overwriting a terminal line natively) but
-* {@link import('@src/core').strip}s ANSI to clean text for a plain target.
+* Creates the server TTY {@link ServerSinkInterface} — the server output backend, whose
+* `write(text, level?)` routes by level to the process streams and uses construction-time styled
+* facts: it sends ANSI straight to a styled target (with a leading `\r` overwriting a terminal
+* line natively) but {@link import('@src/core').strip}s ANSI to clean text for a plain target.
 *
 * @param options - See {@link ServerSinkOptions}
 * @returns A {@link ServerSinkInterface} — a {@link import('@src/core').SinkInterface} that also
@@ -344,16 +349,29 @@ var ProcessCapture = class {
 *   the sink (and the isTTY-strip path) with a fake stream that never touches the real process
 *   streams.
 *
-* @example
+* @example The server — a TTY sink and a process capture
 * ```ts
 * import { createStyler, Logger, Reporter } from '@orkestrel/console'
-* import { createServerSink } from '@orkestrel/console/server'
+* import { createServerSink, ProcessCapture } from '@orkestrel/console/server'
+*
+* const sink = createServerSink() // FORCE_COLOR, then NO_COLOR, then isTTY — per target, at construction
+* const styler = createStyler({ enabled: sink.styled }) // keep generated ANSI paired with the sink's stdout stripping
+* const logger = new Logger({ name: 'server', sink, styler })
+* logger.error('boom') // → process.stderr (the error stream)
+* const reporter = new Reporter({ sink, width: sink.columns }) // size the layout to the live terminal
 *
-* const sink = createServerSink()
-* const styler = createStyler({ enabled: sink.styled })
-* const logger = new Logger({ name: 'app', sink, styler })
-* logger.error('boom') // → process.stderr, ANSI rendered on a TTY / stripped to a pipe
-* const reporter = new Reporter({ sink, width: sink.columns })
+* // `styled` overrides the inference outright — for a CI log that renders ANSI off a TTY, say.
+* const forced = createServerSink({ styled: true })
+* forced.styled // true, whatever the environment and the streams say
+*
+* // Own every output path — a direct process.stdout.write, library output, child-process pipes:
+* const capture = new ProcessCapture({ levels: ['stderr'], mirror: true })
+* capture.start()
+* process.stderr.write('a library diagnostic\n') // captured and still shown (mirror: true)
+* capture.messages('stderr') // [{ level: 'stderr', text: 'a library diagnostic\n', time: … }]
+* capture.clear() // drop buffered chunks; interception is unaffected
+* capture.stop()
+* capture.destroy() // stop() then tear down the emitter
 * ```
 */
 function createServerSink(options) {