@orkestrel/console 0.0.11 → 0.0.13

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

@@ -1,18 +1,18 @@
-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';
 
 /**
- * One intercepted process-stream write — the immutable, serializable record a
+ * Represents one intercepted process-stream write — the immutable, serializable record a
  * {@link ProcessCaptureInterface} buffers and emits, the server analogue of the core
  * `CapturedMessage`.
  *
  * @remarks
  * - `level` — the {@link StreamLevel} naming which stream (`stdout` / `stderr`) was written.
- * - `text` — the chunk decoded to a string (via {@link import('./helpers.js').decodeChunk} —
- *   total, never throws), VERBATIM: no trailing-newline trimming and no ANSI stripping, so the
+ * - `text` — the chunk decoded to a string (through {@link import('./helpers.js').decodeChunk} —
+ *   total, never throws), verbatim: no trailing-newline trimming and no ANSI stripping, so the
  *   captured text is exactly the bytes the program emitted.
  * - `time` — the capture instant as epoch milliseconds (`Date.now()`); a plain number so the record
  *   stays serializable and orderable.
@@ -25,96 +25,65 @@ export declare interface CapturedChunk {
 }
 
 /**
- * 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
- * accepts it only when it is a positive finite number; a missing / `0` / non-finite `columns` (a
- * piped, non-TTY stream) falls back to {@link DEFAULT_COLUMNS}. Total — never throws.
- *
- * @param target - The stream whose width to probe
- * @returns The terminal column count, or {@link DEFAULT_COLUMNS} when not a TTY
- */
-export declare function columnsOf(target: StreamTargetInterface): number;
-
-/**
- * Create an observable {@link ProcessCaptureInterface} — the server "own ALL output" capture. It
- * intercepts the RAW `process.stdout.write` / `process.stderr.write` (not just `console.*`, which is
- * the core `Capture`), so it catches direct `process` writes, library output, and child-process
- * pipes. Each intercepted write becomes a frozen {@link import('./types.js').CapturedChunk},
- * buffered (bounded, per-stream) and emitted on `capture`; per options it is mirrored back to the
- * real stream and/or forwarded to a {@link import('@src/core').SinkInterface}.
- *
- * @param options - See {@link ProcessCaptureOptions}
- * @returns A {@link ProcessCaptureInterface}
- *
- * @remarks
- * - **The wrapper never throws and passes backpressure through** — a throw in `process.stdout.write`
- *   would crash the host, so chunks are decoded totally and the original's `boolean` is returned.
- * - **Snapshot-at-start + non-reentrant + process-global** — `start()` snapshots and swaps the
- *   pristine `write`; `stop()` restores the EXACT original. At most ONE may be active at a time.
- *   Create any server sink BEFORE installing a capture so the mirror's replay is not re-captured.
- *
- * @example
- * ```ts
- * import { createProcessCapture } from '@src/server'
- *
- * const capture = createProcessCapture({ levels: ['stderr'], mirror: true })
- * capture.start()
- * process.stderr.write('a library diagnostic\n') // captured AND still shown
- * capture.stop()
- * ```
- */
-export declare function createProcessCapture(options?: ProcessCaptureOptions): ProcessCaptureInterface;
-
-/**
- * Create the server TTY {@link ServerSinkInterface} — the C-g 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 out stream (`process.stdout`) — the SAME routing as
- *   core's `createConsoleSink`, so a logger's `error` reaches `stderr`.
+ *   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('@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`.
- *   Writes use those stored facts, so `styled` and the out target's strip decision never disagree;
- *   the err target keeps its own fact internally.
- * - **Width.** `columns` reflects the live `out.columns` (so it tracks a terminal resize), falling
- *   back to {@link import('./constants.js').DEFAULT_COLUMNS} when the out stream is not a TTY — or a
- *   fixed value when `options.columns` is supplied. Feed it to a `Reporter` / `Progress` `width`.
- * - **Injectable + guard-narrowed.** `options.out` / `options.err` default to `process.stdout` /
- *   `process.stderr` but accept ANY {@link import('./types.js').StreamTargetInterface}, resolved
- *   through {@link isStreamTarget} (AGENTS §14 — narrow the boundary, never `as`), so a test drives
+ *   Writes use those stored facts, so `styled` and the `stdout` target's strip decision never
+ *   disagree; the `stderr` target keeps its own fact internally.
+ * - **Width.** `columns` reflects the live `stdout.columns` (so it tracks a terminal resize),
+ *   falling back to {@link import('./constants.js').DEFAULT_COLUMNS} when the `stdout` stream is not
+ *   a TTY — or a fixed value when `options.columns` is supplied. Feed it to a `Reporter` /
+ *   `Progress` `width`.
+ * - **Injectable + guard-narrowed.** `options.stdout` / `options.stderr` default to `process.stdout`
+ *   / `process.stderr` but accept any {@link import('./types.js').StreamTargetInterface}, resolved
+ *   through {@link isStreamTarget} (narrow the boundary, never `as`), so a test drives
  *   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 { createLogger, createReporter, createStyler } from '@src/core'
- * import { createServerSink } from '@src/server'
- *
- * const sink = createServerSink()
- * const styler = createStyler({ enabled: sink.styled })
- * const logger = createLogger({ name: 'app', sink, styler })
- * logger.error('boom') // → process.stderr, ANSI rendered on a TTY / stripped to a pipe
- * const reporter = createReporter({ sink, width: sink.columns })
+ * import { createStyler, Logger, Reporter } from '@orkestrel/console'
+ * 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
+ *
+ * // 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;
 
 /**
- * Decode one `process.stdout.write` / `process.stderr.write` chunk to a string — TOTAL, never
- * throws (AGENTS §14). The process write signature accepts `string | Uint8Array` plus an optional
+ * Decodes one `process.stdout.write` / `process.stderr.write` chunk to a string — total, never
+ * throws. The process write signature accepts `string | Uint8Array` plus an optional
  * encoding; the capture wrapper reuses this so intercepting a raw stream write can never crash the
  * host (a throw inside `process.stdout.write` would take the program down).
  *
@@ -123,12 +92,12 @@ export declare function createServerSink(options?: ServerSinkOptions): ServerSin
  *   and `process.stdout.write('text')` all pass a string).
  * - A `Buffer` chunk is decoded with the supplied `encoding` when it is a recognized
  *   {@link BufferEncoding} (`process` write supports `'utf8'` / `'hex'` / `'base64'` / …), defaulting
- *   to `'utf8'`; a bare `Uint8Array` is decoded via `TextDecoder` (always utf-8 — the `encoding`
- *   argument applies ONLY to a `Buffer`, never a plain `Uint8Array`).
+ *   to `'utf8'`; a bare `Uint8Array` is decoded through `TextDecoder` (always utf-8 — the `encoding`
+ *   argument applies only to a `Buffer`, never a plain `Uint8Array`).
  * - Anything else is coerced with `String(chunk)` (a number / object / bigint / symbol a misbehaving
  *   writer hands the stream). The coercion is itself guarded: a value whose `toString` /
  *   `Symbol.toPrimitive` throws yields the stable `'[unprintable]'` placeholder. So the helper is
- *   TOTAL on every input — it always yields SOME string, never an exception (a throw here would
+ *   total on every input — it always yields some string, never an exception (a throw here would
  *   escape into `process.*.write` and crash the host).
  *
  * @param chunk - The chunk passed to the stream's `write`
@@ -145,41 +114,54 @@ export declare function createServerSink(options?: ServerSinkOptions): ServerSin
 export declare function decodeChunk(chunk: unknown, encoding?: unknown): string;
 
 /**
- * The default set of {@link StreamLevel}s a process capture patches when `options.levels` is omitted
- * — BOTH streams ({@link STREAM_LEVELS}). A consumer narrows it (e.g. just `['stderr']`) via
- * `options.levels`.
+ * 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
+ * 80-column default a non-interactive context (a pipe, a CI log) assumes.
  */
-export declare const DEFAULT_CAPTURE_LEVELS: readonly StreamLevel[];
+export declare const DEFAULT_COLUMNS = 80;
 
 /**
- * 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 via `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_CAPTURE_LIMIT = 1000;
+export declare const DEFAULT_STREAM_LIMIT = 1000;
 
 /**
- * The terminal width {@link import('./factories.js').createServerSink} reports through
- * {@link import('./types.js').ServerSinkInterface.columns} when the out 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.
+ * 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
+ * accepts it only when it is a positive finite number; a missing / `0` / non-finite `columns` (a
+ * piped, non-TTY stream) falls back to {@link DEFAULT_COLUMNS}. Total — never throws.
+ *
+ * @param target - The stream whose width to probe
+ * @returns The terminal column count, or {@link DEFAULT_COLUMNS} when not a TTY
  */
-export declare const DEFAULT_COLUMNS = 80;
+export declare function inferColumns(target: StreamTargetInterface): number;
 
 /**
- * Infer whether one stream target should receive 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`
- * @returns Whether output for the target should retain styling and control sequences
+ * @returns True if output for the target retains styling and control sequences; false otherwise
  *
  * @example
  * ```ts
@@ -190,28 +172,28 @@ export declare const DEFAULT_COLUMNS = 80;
 export declare function inferStyled(target: StreamTargetInterface, environment: Readonly<Record<string, string | undefined>>): boolean;
 
 /**
- * Whether `encoding` is a {@link BufferEncoding} accepted by `Buffer.prototype.toString` — a total
- * guard used by {@link 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` when `encoding` names a supported buffer encoding
+ * @returns True if `encoding` names a supported buffer encoding; false otherwise
  */
 export declare function isBufferEncoding(encoding: unknown): encoding is BufferEncoding;
 
 /**
- * Whether `value` is a usable {@link StreamTargetInterface} — a record with a callable `write`. A
- * total type guard (AGENTS §14): it NEVER throws and returns `false` for anything off-shape, so it
+ * Checks whether `value` is a usable {@link StreamTargetInterface} — a record with a callable `write`. A
+ * total type guard: it never throws and returns `false` for anything off-shape, so it
  * narrows the one unavoidable boundary (the real `process.stdout` / `process.stderr`, or a fake
  * stream a test injects) to the exact slice the sink + capture touch — no `as`.
  *
  * @remarks
  * Only `write` is required (the irreducible output method); `isTTY` and `columns` are optional on
  * {@link StreamTargetInterface}, so their absence does not disqualify a target — a piped stream
- * (no `isTTY`) is still a valid write target, just a non-terminal one.
+ * (no `isTTY`) is still a valid write target, only a non-terminal one.
  *
  * @param value - Any value crossing the boundary (a process stream, an injected fake, `unknown`)
- * @returns `true` when `value` has a callable `write`
+ * @returns True if `value` has a callable `write`; false otherwise
  *
  * @example
  * ```ts
@@ -223,28 +205,28 @@ export declare function isBufferEncoding(encoding: unknown): encoding is BufferE
 export declare function isStreamTarget(value: unknown): value is StreamTargetInterface;
 
 /**
- * An observable interceptor of the RAW process output streams (AGENTS §13) — it takes control of
- * `process.stdout.write` / `process.stderr.write` on the WRITE side. While `active`, every write to
+ * Implements an observable interceptor of the raw process output streams — it takes control of
+ * `process.stdout.write` / `process.stderr.write` on the write side. While `active`, every write to
  * a configured {@link StreamLevel} is captured as a frozen {@link CapturedChunk}, buffered (total +
- * per-stream, bounded), emitted on `capture`, and — per options — mirrored to the real stream and/or
- * forwarded to a {@link SinkInterface}.
+ * per-stream, bounded), emitted on `capture`, and — per options — mirrored to the real stream,
+ * forwarded to a {@link SinkInterface}, or both.
  *
  * @remarks
  * Where the core `Capture` patches `console.*` (the high-level read side), this patches the
- * low-level stream `write`, so it owns ALL server output: a direct `process.stdout.write`, a
+ * low-level stream `write`, so it owns all server output: a direct `process.stdout.write`, a
  * third-party library's writes, a child-process pipe — not only `console.*`.
  *
- * - **Snapshot-at-start (the no-capture-loop principle).** `start()` snapshots the CURRENT
+ * - **Snapshot-at-start (the no-capture-loop principle).** `start()` snapshots the current
  *   `process[stream].write` for each configured level, then installs the wrappers. The mirror
  *   replays through that snapshot (bound to its stream) — so a server sink created from the same
- *   streams BEFORE the capture is never re-captured: this catches OTHER writers, not the mirror's
+ *   streams before the capture is never re-captured: this catches other writers, not the mirror's
  *   own replay. Create your sinks before installing a capture.
- * - **Idempotent + PROCESS-GLOBAL + NON-REENTRANT.** `start()` while `active` is a no-op (never
+ * - **Idempotent + process-global + non-reentrant.** `start()` while `active` is a no-op (never
  *   double-patches — that would snapshot the wrapper as the "original" and break restore); `stop()`
- *   while inactive is a no-op. It patches the ONE global `process`, so at most ONE process capture
+ *   while inactive is a no-op. It patches the one global `process`, so at most one process capture
  *   may be active at a time — two concurrently would interleave buffers and clobber each other's
  *   restore.
- * - **The wrapper NEVER throws and passes backpressure through.** A throw inside
+ * - **The wrapper never throws and passes backpressure through.** A throw inside
  *   `process.stdout.write` would crash the host, so the wrapper decodes each chunk totally (a byte
  *   chunk through the per-level streaming decoder below, everything else through the total
  *   {@link decodeChunk}), and returns the snapshot-original's `boolean` when mirroring (so a caller's
@@ -255,18 +237,18 @@ export declare function isStreamTarget(value: unknown): value is StreamTargetInt
  *   child-process pipe, a library, or OS buffering all produce this — carries its partial bytes to
  *   the next write instead of decoding each half to `U+FFFD`. `stop()` flushes each decoder once, so
  *   a codepoint left half-written at stop is still surfaced. A `string` chunk is already text and
- *   passes through; an explicit NON-utf-8 buffer encoding (`latin1` / `hex` / `base64` / …) names a
+ *   passes through; an explicit non-utf-8 buffer encoding (`latin1` / `hex` / `base64` / …) names a
  *   self-contained per-write decode and is honored one-shot through {@link decodeChunk}.
  * - **Bounded buffers.** The total buffer and each per-stream bucket are each capped at `limit`
  *   (oldest dropped first), never unbounded — the same retention precedent as the core `Capture`.
- * - **Lifecycle (§10).** `start` / `stop` toggle interception (emitting `start` / `stop`);
- *   `destroy()` stops (restoring the PRISTINE `write`) then destroys the emitter.
+ * - **Lifecycle.** `start` / `stop` toggle interception (emitting `start` / `stop`);
+ *   `destroy()` stops (restoring the pristine `write`) then destroys the emitter.
  *
  * @example
  * ```ts
  * const capture = new ProcessCapture({ levels: ['stderr'], mirror: true })
  * capture.start()
- * process.stderr.write('a library diagnostic\n') // captured AND still written to the terminal
+ * process.stderr.write('a library diagnostic\n') // captured and still written to the terminal
  * capture.messages('stderr') // [{ level: 'stderr', text: 'a library diagnostic\n', time: … }]
  * capture.stop() // process.stderr.write restored
  * ```
@@ -285,92 +267,101 @@ export declare class ProcessCapture implements ProcessCaptureInterface {
 }
 
 /**
- * The observable events a {@link ProcessCaptureInterface} emits (AGENTS §13) — 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).
  *
- * Listener isolation is the emitter's (§13): a listener throw routes to the emitter's `error`
+ * Listener isolation is the emitter's: a listener throw routes to the emitter's `error`
  * handler, never onto this map — so a buggy `capture` listener can never escape into the host's
  * `process.stdout.write` call (which would crash the program).
  *
- * Declared as a `type` alias (not `interface extends EventMap`, §4.5): a type-literal satisfies the
+ * Declared as a `type` alias (not `interface extends EventMap`): a type-literal satisfies the
  * `EventMap` constraint structurally, whereas an interface lacks the index signature.
  */
 export declare type ProcessCaptureEventMap = {
-    /** An intercepted process-stream write — the frozen {@link CapturedChunk}. */
+    /** Fires on an intercepted process-stream write — the frozen {@link CapturedChunk}. */
     readonly capture: readonly [chunk: CapturedChunk];
-    /** Interception began (`process.*.write` patched). */
+    /** Fires after interception began (`process.*.write` patched). */
     readonly start: readonly [];
-    /** Interception ended (`process.*.write` restored). */
+    /** Fires after interception ended (`process.*.write` restored). */
     readonly stop: readonly [];
 };
 
 /**
- * An observable interceptor of the RAW process output streams (AGENTS §13) — 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 just `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
- * - **Snapshot-at-start (the no-capture-loop principle).** `start()` snapshots the CURRENT
+ * 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
+ *   mirror replays through that snapshot — so a server sink created from the same streams before the
  *   capture is never re-captured. Create your sinks before installing a capture.
- * - **Idempotent + PROCESS-GLOBAL + NON-REENTRANT.** `start()` while `active` is a no-op (never
- *   double-patches); `stop()` while inactive is a no-op. It patches the ONE global `process`, so at
- *   most ONE process capture may be active at a time — running two concurrently interleaves their
+ * - **Idempotent + process-global + non-reentrant.** `start()` while `active` is a no-op (never
+ *   double-patches); `stop()` while inactive is a no-op. It patches the one global `process`, so at
+ *   most one process capture may be active at a time — running two concurrently interleaves their
  *   buffers and clobbers each other's restore.
- * - **The wrapper NEVER throws and passes through backpressure.** A throw inside
+ * - **The wrapper never throws and passes through backpressure.** A throw inside
  *   `process.stdout.write` would crash the host, so the wrapper builds its record through a total
  *   decode, and returns the snapshot-original's boolean (or `true` when mirroring is off) so a
  *   caller's backpressure handling keeps working.
  * - **Bounded buffers.** The total buffer and each per-stream bucket are each capped at `limit`
  *   (oldest dropped first), never unbounded.
- * - **Lifecycle (§10).** `start` / `stop` toggle interception (emitting `start` / `stop`);
+ * - **Lifecycle.** `start` / `stop` toggle interception (emitting `start` / `stop`);
  *   `destroy()` stops (restoring the pristine `write`) then destroys the emitter.
  */
 export declare interface ProcessCaptureInterface {
     readonly emitter: EmitterInterface<ProcessCaptureEventMap>;
-    /** Whether interception is currently installed (`start`ed and not yet `stop`ped). */
+    /** Reports whether interception is installed (`start`ed and not yet `stop`ped). */
     readonly active: boolean;
-    /** Begin intercepting the configured process streams (idempotent; emits `start`). */
+    /** Begins intercepting the configured process streams (idempotent; emits `start`). */
     start(): void;
-    /** Restore the pristine `process.*.write` references (idempotent; emits `stop`). */
+    /** Restores the pristine `process.*.write` references (idempotent; emits `stop`). */
     stop(): void;
-    /** 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[];
-    /** A copy of the captured buffer for ONE {@link StreamLevel}, oldest first (capped at `limit`). */
+    /** Returns a copy of the captured buffer for one {@link StreamLevel}, oldest first (capped at `limit`). */
     messages(level: StreamLevel): readonly CapturedChunk[];
-    /** Drop every buffered chunk (total + per-stream); interception is unaffected. */
+    /** Drops every buffered chunk (total + per-stream); interception is unaffected. */
     clear(): void;
-    /** Stop interception (restoring the streams) and tear down the emitter. */
+    /** Stops interception (restoring the streams) and tears down the emitter. */
     destroy(): void;
 }
 
 /**
- * Options for {@link import('./factories.js').createProcessCapture} — every field optional, so a
- * bare `createProcessCapture()` 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 (e.g.
+ * - `on` — initial {@link ProcessCaptureEventMap} listeners, wired at construction (for example
  *   `{ capture: (c) => tee(c) }`).
- * - `error` — the listener-error handler forwarded to the entity's emitter (§13).
- * - `levels` — which streams to intercept; defaults to {@link import('./constants.js').DEFAULT_CAPTURE_LEVELS}
- *   (both `stdout` and `stderr`). Narrow it (e.g. just `['stderr']`) to capture one stream.
- * - `mirror` — when `true`, each intercepted write is ALSO replayed to the snapshot-original
+ * - `error` — the listener-error handler forwarded to the entity's emitter.
+ * - `levels` — which streams to intercept; defaults to {@link import('./constants.js').STREAM_LEVELS}
+ *   (`stdout` and `stderr`). Narrow it (for example to `['stderr']`) to capture one stream.
+ * - `mirror` — when `true`, each intercepted write is also replayed to the snapshot-original
  *   `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} via
+ *   (`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
- *   {@link import('./constants.js').DEFAULT_CAPTURE_LIMIT}. Retention is ALWAYS bounded.
+ * - `limit` — the bounded-buffer cap (total and each per-stream bucket); defaults to
+ *   {@link import('./constants.js').DEFAULT_STREAM_LIMIT}. Retention is always bounded.
  */
 export declare interface ProcessCaptureOptions {
     readonly on?: EmitterHooks<ProcessCaptureEventMap>;
@@ -382,16 +373,19 @@ export declare interface ProcessCaptureOptions {
 }
 
 /**
- * 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 out 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
- * - `styled` is the `out` target's construction-time fact. The sink handles `err` 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
+ * 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
  *   resize is observed) unless a fixed `options.columns` was supplied, in which case it is constant.
  */
 export declare interface ServerSinkInterface extends SinkInterface {
@@ -400,71 +394,78 @@ export declare interface ServerSinkInterface extends SinkInterface {
 }
 
 /**
- * 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
- * - `out` — the stream `info` / `debug` (and an omitted level) are written to; defaults to
- *   `process.stdout`. Any {@link StreamTargetInterface} is accepted, so a test injects a fake.
- * - `err` — the stream `error` / `warn` are written to; defaults to `process.stderr`.
+ * - `stdout` — the stream `info` / `debug` (and an omitted level) are written to; defaults to
+ *   `process.stdout`, whose name it mirrors. Any {@link StreamTargetInterface} is accepted, so a
+ *   test injects a fake.
+ * - `stderr` — the stream `error` / `warn` are written to; defaults to `process.stderr`, whose
+ *   name it mirrors.
  * - `styled` — an explicit styling decision for both targets. When omitted, each target infers its
  *   own fact from `FORCE_COLOR`, `NO_COLOR`, and `isTTY` at construction.
  * - `environment` — the environment used for inference; defaults to `process.env`.
  * - `columns` — an explicit width override for {@link ServerSinkInterface.columns}. When omitted,
- *   the sink reads the live `out.columns` (so it tracks a terminal resize), falling back to
- *   {@link import('./constants.js').DEFAULT_COLUMNS} when the out stream is not a TTY.
+ *   the sink reads the live `stdout.columns` (so it tracks a terminal resize), falling back to
+ *   {@link import('./constants.js').DEFAULT_COLUMNS} when the `stdout` stream is not a TTY.
  */
 export declare interface ServerSinkOptions {
-    readonly out?: StreamTargetInterface;
-    readonly err?: StreamTargetInterface;
+    readonly stdout?: StreamTargetInterface;
+    readonly stderr?: StreamTargetInterface;
     readonly styled?: boolean;
     readonly environment?: Readonly<Record<string, string | undefined>>;
     readonly columns?: number;
 }
 
 /**
- * Each {@link StreamLevel}'s {@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>>;
 
 /**
- * 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[];
 
 /**
- * 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
- * forward), never a binary toggle — so it stays a union (AGENTS §4.4).
+ * {@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';
 
 /**
- * The minimal writable-stream shape the C-g 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 via {@link import('./helpers.js').isStreamTarget} (AGENTS §14 — 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
@@ -476,8 +477,30 @@ export declare interface StreamTargetInterface {
     readonly columns?: number;
 }
 
+/**
+ * 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
+ * write-completion handler still fires.
+ */
 export declare type StreamWriteCallback = (error?: Error | null) => void;
 
+/**
+ * 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
+ * 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
+ * itself the `process` property key, so `process[level]` indexes the matching `WriteStream`
+ * directly, with no lookup map.
+ */
 export declare type StreamWriteFunction = NodeJS.WriteStream['write'];
 
 export { }