@orkestrel/console 0.0.11 → 0.0.13

package/README.md

@@ -1,12 +1,13 @@
 # @orkestrel/console
 
-A unified output-control system for the `@orkestrel` line — one
-environment-agnostic engine composing five concerns over a shared substrate:
-a **style engine** (`Styler` + `ANSIRenderer`, style as data), **structured
-logging** (`Logger`, `LoggerManager`), **narrative reporting** (`Reporter`),
-**console & stream capture** (`Capture`, `ProcessCapture`), and **live
-animations** (`Spinner`, `Progress`). Built to sit beside `@orkestrel/emitter`
-(observable lifecycle), reusing it as it takes shape.
+> A unified output-control system for a terminal, a browser, and a server: a style engine over
+> frozen `Style` data, structured logging whose record and `entry` event are the transport seam,
+> narrative reporting, console and stream capture, and live animations — one engine, environment
+> sinks, with the platform backend swapped at the `Sink` seam.
+
+Install the package, build a `Logger` or a `Reporter`, and swap its `sink` to move the same code
+between a terminal, a browser, and a server. Part of the `@orkestrel` line, built to sit beside
+`@orkestrel/emitter` (observable lifecycle), reusing it as it takes shape.
 
 ## Install
 
@@ -25,27 +26,27 @@ npm install @orkestrel/console
 The same code retargets to any environment by swapping the `sink`:
 
 ```ts
-import { createLogger, createReporter, createSpinner } from '@src/core'
+import { Logger, Reporter, Spinner } from '@orkestrel/console'
 
-const logger = createLogger({ name: 'http', level: 'info' }) // ANSI to the console by default
+const logger = new Logger({ name: 'http', level: 'info' }) // ANSI to the console by default
 logger.info('request', { method: 'GET', path: '/' }) // a styled, leveled line + an `entry` event
 logger.emitter.on('entry', (record) => archive(record)) // the transport seam — file / JSON / remote
 
-const reporter = createReporter()
+const reporter = new Reporter()
 reporter.section('Build')
 reporter.step('bundling', { index: 2, total: 5 }) // [2/5] bundling
 reporter.status('success', 'built in 1.2s') // ✔ built in 1.2s
 
-const spinner = createSpinner({ message: 'deploying' })
+const spinner = new Spinner({ message: 'deploying' })
 spinner.start() // a self-driving glyph cycle, `\r`-redrawn by an overwrite-capable sink
-spinner.success('deployed') // ✔ deployed — the timer cleared, the line committed
+spinner.succeed('deployed') // ✔ deployed — the timer cleared, the line committed
 ```
 
 Style is data — a `Style` is a frozen record rendered through a swappable
 `RendererInterface` (`ANSIRenderer` by default):
 
 ```ts
-import { createStyler } from '@src/core'
+import { createStyler } from '@orkestrel/console'
 
 const styler = createStyler()
 console.log(styler.red.bold('hi')) // renders through the injected renderer
@@ -54,9 +55,9 @@ console.log(styler.red.bold('hi')) // renders through the injected renderer
 Take control of `console.*` on the read side with `Capture`:
 
 ```ts
-import { createCapture } from '@src/core'
+import { Capture } from '@orkestrel/console'
 
-const capture = createCapture({ mirror: true })
+const capture = new Capture({ mirror: true })
 capture.start()
 console.log('hello')
 capture.messages() // [{ level: 'log', text: 'hello', time: ... }]
@@ -64,24 +65,25 @@ capture.stop()
 ```
 
 On the server, `ProcessCapture` takes over the whole `process` output surface
-(direct `process.stdout`/`stderr` writes, not just `console.*`):
+(direct `process.stdout`/`stderr` writes, not `console.*`):
 
 ```ts
-import { createProcessCapture } from '@src/server'
+import { ProcessCapture } from '@orkestrel/console/server'
 
-const capture = createProcessCapture({ levels: ['stderr'], mirror: true })
+const capture = new ProcessCapture({ levels: ['stderr'], mirror: true })
 capture.start()
 ```
 
 ## Guide
 
-See [guides/src/console.md](./guides/src/console.md) for the full documented
+See [guides/console.md](./guides/console.md) for the full documented
 surface — styling, logging, reporting, capture, and animations.
 
 ## Package
 
-Published as three environment-scoped entry points per the `exports` field
-in `package.json`: `.` (the shared, environment-agnostic core engine, the
+Published as the `.`, `./server`, and `./browser` environment-scoped entry
+points per the `exports` field in `package.json`: `.` (the shared,
+environment-agnostic core engine, the
 default ANSI renderer, and the console sink), `./server` (adds the server
 sink and `ProcessCapture`), and `./browser` (adds the browser sink
 translating ANSI to `console.log('%c…', css)`). Core and `./server` ship

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

@@ -1,24 +1,27 @@
-import { Attribute } from '@orkestrel/console';
-import { Color } from '@orkestrel/console';
-import { SinkInterface } from '@orkestrel/console';
+import type { Attribute } from '@orkestrel/console';
+import type { Color } from '@orkestrel/console';
+import type { SinkInterface } from '@orkestrel/console';
 
 /**
- * Translate an ANSI-styled string into a browser `console.log`-ready {@link ConsoleOutput} — a
- * `%c`-segmented format string and the parallel array of CSS declarations, so a DevTools console
- * renders the SAME styling a terminal would (the C-f sink calls `console[method](format, ...styles)`).
+ * Translates an ANSI-styled string into a browser `console.log`-ready {@link ConsoleOutput} — a
+ * `%c`-segmented format string and the parallel array of CSS declarations, an optional partial
+ * {@link BrowserPalette} overriding the CSS per named lookup.
  *
  * @remarks
+ * A DevTools console then renders the same styling a terminal would; the browser sink calls
+ * `console[method](format, ...styles)`.
+ *
  * - **SGR runs → `%c` segments.** The text is scanned for SGR sequences ({@link SGR_PATTERN} —
- *   `ESC[…m`); each delimits a run. A run carrying VISIBLE text emits one `%c` directive plus that
+ *   `ESC[…m`); each delimits a run. A run carrying visible text emits one `%c` directive plus that
  *   text into `format` and the run's accumulated CSS into `styles`, so the browser switches style at
  *   each `%c`. Foreground / background / attribute codes accumulate; the reset code (`0`, or a bare
- *   `ESC[m`) clears the accumulated style back to none. A later color of the same channel REPLACES
+ *   `ESC[m`) clears the accumulated style back to none. A later color of the same channel replaces
  *   the earlier one; an attribute is added once. Non-SGR escapes (cursor / erase / OSC) are not style
  *   and are left in the text verbatim.
- * - **`%`-safe.** Every LITERAL `%` in the text is doubled to `%%` so the console never treats it as
+ * - **`%`-safe.** Every literal `%` in the text is doubled to `%%` so the console never treats it as
  *   a directive — only the `%c`s this function inserts are real directives. So `format`'s real `%c`
  *   count always equals `styles.length`, and `console.log(format, ...styles)` lines up exactly.
- * - **Plain text short-circuits.** A string with NO SGR sequence yields `{ format: <escaped text>,
+ * - **Plain text short-circuits.** A string with no SGR sequence yields `{ format: <escaped text>,
  *   styles: [] }` — no `%c`, no styles (the text is still `%`-escaped).
  * - **Partial palette.** A supplied palette overrides only its named colors and attributes. Every
  *   omitted entry resolves through {@link COLOR_HEX} or {@link ATTRIBUTE_CSS}, so defaults and
@@ -40,14 +43,15 @@ import { SinkInterface } from '@orkestrel/console';
 export declare function ansiToConsole(text: string, palette?: BrowserPalette): ConsoleOutput;
 
 /**
- * Each text-{@link Attribute}'s SGR "on" number → its equivalent CSS declaration — the browser
- * counterpart to the terminal's SGR text effects (`bold` 1 → `font-weight:bold`, `dim` 2 →
- * `opacity:0.6`, `italic` 3 → `font-style:italic`, `underline` 4 → `text-decoration:underline`,
- * `inverse` 7 → best-effort, `strikethrough` 9 → `text-decoration:line-through`). Keyed by the SGR
- * NUMBER (derived from core's {@link ATTRIBUTE_CODES}) so the sink looks a parameter up directly
- * while scanning a run.
+ * Maps each text-{@link Attribute}'s SGR "on" number to its equivalent CSS declaration — the
+ * browser counterpart to the terminal's SGR text effects (`bold` 1 → `font-weight:bold`, `dim` 2
+ * → `opacity:0.6`, `italic` 3 → `font-style:italic`, `underline` 4 → `text-decoration:underline`,
+ * `inverse` 7 → best-effort, `strikethrough` 9 → `text-decoration:line-through`).
  *
  * @remarks
+ * Keyed by the SGR number (derived from core's {@link ATTRIBUTE_CODES}) so the sink looks a
+ * parameter up directly while scanning a run.
+ *
  * `inverse` (SGR 7) has no faithful single-declaration CSS equivalent (it swaps the fore/back inks,
  * which depends on the live colors); it maps to a best-effort `filter:invert(100%)` — documented as
  * approximate, never silently dropped. Deeply frozen.
@@ -55,8 +59,8 @@ export declare function ansiToConsole(text: string, palette?: BrowserPalette): C
 export declare const ATTRIBUTE_CSS: Readonly<Record<number, string>>;
 
 /**
- * Partial browser CSS overrides for the core color and attribute axes. Omitted entries retain the
- * built-in browser mappings, so one override changes only its named value.
+ * Holds partial browser CSS overrides for the core color and attribute axes — a named `color` or
+ * `attribute` entry replaces only that entry, and every omission keeps its default.
  *
  * @remarks
  * - `color` maps a named non-default {@link Color} to the CSS color value used for both foreground
@@ -69,18 +73,16 @@ export declare interface BrowserPalette {
 }
 
 /**
- * Options for {@link import('./factories.js').createBrowserSink}.
- *
- * @remarks
- * `palette` partially overrides the browser's default color and attribute CSS mappings.
+ * Configures {@link import('./factories.js').createBrowserSink} — the optional `palette` partially
+ * overriding the browser's named color and attribute CSS mappings.
  */
 export declare interface BrowserSinkOptions {
     readonly palette?: BrowserPalette;
 }
 
 /**
- * Each named {@link Color}'s hex value — the 16 standard terminal colors a browser DevTools
- * console renders the SAME {@link Color} names as. The source of truth for the BROWSER color
+ * Maps each named {@link Color} to its hex value — the 16 standard terminal colors a browser DevTools
+ * console renders the same {@link Color} names as. The source of truth for the browser color
  * axis: the ANSI renderer maps a `Color` name to an SGR number, and this maps the same name to
  * the CSS color the `%c` sink paints with, so a browser shows the same 16 colors a terminal does.
  *
@@ -91,20 +93,20 @@ export declare interface BrowserSinkOptions {
 export declare const COLOR_HEX: Readonly<Record<Exclude<Color, 'default'>, string>>;
 
 /**
- * The `console.log`-ready output {@link import('./helpers.js').ansiToConsole} produces from
- * an ANSI-styled string — a format string of `%c`-prefixed segments and the parallel array
- * of CSS declarations, ready to spread into a browser `console` call as
- * `console.log(format, ...styles)`.
+ * Represents the `console.log`-ready output {@link import('./helpers.js').ansiToConsole} produces
+ * from an ANSI-styled string — a format string of `%c`-prefixed segments and the parallel array of
+ * CSS declarations, ready to spread into a browser `console` call as `console.log(format,
+ * ...styles)`.
  *
  * @remarks
  * - `format` — the text with each styled run prefixed by one `%c` directive (the directive
- *   the browser console consumes to switch the active style) and every LITERAL `%` doubled to
+ *   the browser console consumes to switch the active style) and every literal `%` doubled to
  *   `%%` so it is not mistaken for a directive. A plain (no-ANSI) input yields the text
- *   verbatim with NO `%c` and an empty `styles` (still `%`-escaped).
+ *   verbatim with no `%c` and an empty `styles` (still `%`-escaped).
  * - `styles` — one CSS declaration string per `%c` in `format`, in order: the browser applies
  *   `styles[n]` from the n-th `%c` onward. Each entry is the accumulated style for that run
- *   (an SGR reset clears it back to `''`). `format`'s `%c` count always equals `styles.length`,
- *   so the spread `console.log(format, ...styles)` lines up exactly.
+ *   (an SGR reset clears it back to the empty declaration string). `format`'s `%c` count always
+ *   equals `styles.length`, so the spread `console.log(format, ...styles)` lines up exactly.
  */
 export declare interface ConsoleOutput {
     readonly format: string;
@@ -112,53 +114,56 @@ export declare interface ConsoleOutput {
 }
 
 /**
- * Create the browser `%c` {@link SinkInterface} — the C-f browser output backend. `write(text, level?)`
+ * Creates the browser `%c` {@link SinkInterface} — the browser output backend. `write(text, level?)`
  * translates the ANSI-styled `text` into a browser `console` call (`console[method](format, ...styles)`)
- * via {@link ansiToConsole}, so a DevTools console renders the SAME styling a terminal does. Drop it in
- * as a logger / reporter / spinner sink (`createLogger({ sink: createBrowserSink() })`) to retarget the
- * core output to the browser console with no change to the core.
+ * through {@link ansiToConsole}, an optional partial {@link BrowserPalette} overriding the named
+ * color and attribute CSS.
  *
  * @param options - See {@link BrowserSinkOptions}
  * @returns A browser `%c` {@link SinkInterface}
  *
  * @remarks
+ * Drop it in as a logger / reporter / spinner sink (`new Logger({ sink: createBrowserSink() })`)
+ * to retarget the core output to the browser console with no change to the core.
+ *
  * - **ANSI → `%c` at the sink.** The core produces ANSI strings; this sink parses the SGR runs and
  *   re-emits them as a `console.log`-ready `%c` format string + parallel CSS array ({@link ansiToConsole}
  *   — pure, total, and `%`-safe), so the styling survives the trip to a console that can't render ANSI.
  *   `options.palette` supplies partial named color and attribute overrides to that translation.
  * - **Routes by level.** `error` → `console.error`, `warn` → `console.warn`, every other level (and an
- *   omitted level) → `console.log` — the SAME routing as core's `createConsoleSink`, so a logger's level
- *   reaches the matching DevTools stream.
+ *   omitted level) → `console.log` — the same routing as core's `createConsoleSink`, so a logger's level
+ *   reaches the matching DevTools stream. Both call the one
+ *   {@link import('@orkestrel/console').selectWriter} leaf, which is what keeps them identical.
  * - **Animation degrade (locked).** A browser console cannot overwrite a line, so a `text` beginning with
- *   a carriage return `\r` (a spinner / progress redraw) has the leading `\r` STRIPPED and is written as a
- *   fresh, non-overwriting line — the locked browser degrade. Only a LEADING `\r` is stripped; an interior
+ *   a carriage return `\r` (a spinner / progress redraw) has the leading `\r` stripped and is written as a
+ *   fresh, non-overwriting line — the locked browser degrade. Only a leading `\r` is stripped; an interior
  *   one is left to the console.
- * - **Snapshotted — no capture loop.** It captures `console.log` / `console.warn` / `console.error` AT
- *   CREATION and writes through those references, so a later `Capture` that PATCHES `console.*` can never
- *   feed this sink's output back into itself (the no-capture-loop principle, AGENTS / the core sink's
- *   precedent). Create the sink (or the logger) BEFORE installing a capture.
+ * - **Snapshotted — no capture loop.** It captures `console.log` / `console.warn` / `console.error` at
+ *   creation and writes through those references, so a later `Capture` that patches `console.*` can never
+ *   feed this sink's output back into itself (the no-capture-loop principle, following the core
+ *   sink's precedent). Create the sink (or the logger) before installing a capture.
  *
  * @example
  * ```ts
- * import { createLogger } from '@src/core'
- * import { createBrowserSink } from '@src/browser'
+ * import { Logger } from '@orkestrel/console'
+ * import { createBrowserSink } from '@orkestrel/console/browser'
  *
- * const logger = createLogger({ name: 'app', sink: createBrowserSink() })
+ * const logger = new Logger({ name: 'app', sink: createBrowserSink() })
  * logger.error('boom') // → console.error('%c…', 'color:#cd0000;…') in DevTools
  * ```
  */
 export declare function createBrowserSink(options?: BrowserSinkOptions): SinkInterface;
 
 /**
- * The browser console directive that switches the active style — one `%c` prefixes every styled run
- * in the {@link import('./types.js').ConsoleOutput} format string, consuming the next entry of the
- * parallel CSS array. The single source of truth for the directive token.
+ * Names the browser console directive that switches the active style — one `%c` prefixes every
+ * styled run in the {@link import('./types.js').ConsoleOutput} format string, consuming the next
+ * entry of the parallel CSS array. The single source of truth for the directive token.
  */
 export declare const DIRECTIVE = "%c";
 
 /**
- * Double every literal `%` in `text` to `%%` — the `%`-escape that keeps a browser console from
- * reading a stray `%` (e.g. in `50%` or `%s`) as a format directive. The single escape the
+ * Doubles every literal `%` in `text` to `%%` — the `%`-escape that keeps a browser console from
+ * reading a stray `%` (for example in `50%` or `%s`) as a format directive. The single escape the
  * {@link ansiToConsole} translation applies to every text segment before assembling the format
  * string (so only the `%c`s it inserts are real directives).
  *
@@ -173,56 +178,62 @@ export declare const DIRECTIVE = "%c";
 export declare function escapePercent(text: string): string;
 
 /**
- * Parse an SGR parameter list (the `;`-separated numeric string captured by {@link SGR_PATTERN})
- * into its numeric codes — `'1;31'` → `[1, 31]`. An EMPTY list (a bare `ESC[m`) yields `[0]`, since
- * the SGR spec treats a parameterless sequence as a reset; an empty field within a list (`'1;;4'`)
- * likewise counts as a `0` reset, matching the spec.
+ * Walks an SGR parameter list (the `;`-separated numeric string captured by {@link SGR_PATTERN})
+ * and returns its numeric codes — `'1;31'` → `[1, 31]`, a bare or empty field becoming a `0`
+ * reset. It is total: every input yields a code list.
  *
  * @param parameters - The raw `;`-separated parameter string (the regex capture)
- * @returns The parsed SGR codes (a parameterless / empty field becoming `0`)
+ * @returns The SGR codes found (a parameterless / empty field becoming `0`)
+ *
+ * @remarks
+ * An empty list (a bare `ESC[m`) yields `[0]`, because the SGR spec treats a parameterless
+ * sequence as a reset; an empty field within a list (`'1;;4'`) likewise counts as a `0` reset,
+ * matching the spec, and a non-numeric field yields `NaN`, which the caller then ignores.
  *
  * @example
  * ```ts
- * parseParameters('1;31') // [1, 31]
- * parseParameters('') // [0]
+ * scanParameters('1;31') // [1, 31]
+ * scanParameters('') // [0]
  * ```
  */
-export declare function parseParameters(parameters: string): readonly number[];
+export declare function scanParameters(parameters: string): readonly number[];
 
 /**
- * Matches one SGR sequence (`ESC[ <params> m`) and CAPTURES its `;`-separated numeric parameters —
- * the subset of ANSI {@link import('@src/core').strip} cares about that carries STYLE (color /
+ * Matches one SGR sequence (`ESC[ <params> m`) and captures its `;`-separated numeric parameters —
+ * the subset of ANSI {@link import('@orkestrel/console').strip} cares about that carries style (color /
  * attribute / reset), as opposed to cursor / erase / OSC sequences. Global, so the scanner walks
  * every SGR run in a string; built from core's {@link ESC} so no control-character literal appears
  * in source (the codebase idiom). The capture group is the parameter list (`''` for a bare `ESC[m`,
  * which the spec treats as a reset).
  *
  * @remarks
- * A global `RegExp` carries a mutable `lastIndex`; a scan builds a FRESH `RegExp` from this one's
+ * A global `RegExp` carries a mutable `lastIndex`; a scan builds a fresh `RegExp` from this one's
  * `source` + `flags` rather than reuse this instance, so concurrent scans never collide. This is the
  * canonical definition, not a shared scanner.
  */
 export declare const SGR_PATTERN: RegExp;
 
 /**
- * The immutable accumulator {@link import('./helpers.js').ansiToConsole} carries across a run while
- * translating SGR codes to CSS — a single `foreground` and `background` declaration (each channel
- * REPLACEABLE by a later color of the same channel) plus an ordered, de-duplicated list of attribute
- * declarations. An SGR reset empties all three; {@link import('./helpers.js').ansiToConsole} folds
- * it into the `;`-joined CSS string a run emits.
+ * Represents the immutable scan state {@link import('./helpers.js').ansiToConsole} replaces while
+ * translating SGR codes to CSS — an optional `foreground` and `background` declaration plus a
+ * readonly list of attribute declarations.
  *
  * @remarks
+ * A later color of the same channel replaces that channel; an SGR reset drops both channels and
+ * empties the list; {@link import('./helpers.js').ansiToConsole} folds the state into the
+ * `;`-joined CSS string a run emits.
+ *
  * Each SGR sequence produces a new frozen value; earlier run snapshots never drift when a later
- * sequence changes a channel. A channel holds the FULL CSS declaration (`'color:#cd0000'`, not a
- * bare hex), or `''` when unset.
- * - `foreground` — the current `color:<hex>` declaration, or `''` (unset / post-reset).
- * - `background` — the current `background:<hex>` declaration, or `''`.
+ * sequence changes a channel. A channel holds the full CSS declaration (`'color:#cd0000'`, not a
+ * bare hex), and is absent when unset.
+ * - `foreground` — the current `color:<hex>` declaration; absent when unset or after a reset.
+ * - `background` — the current `background:<hex>` declaration; absent on the same terms.
  * - `attributes` — the active text-effect declarations in insertion order (`'font-weight:bold'`, …),
  *   each present at most once.
  */
 export declare interface StyleAccumulator {
-    readonly foreground: string;
-    readonly background: string;
+    readonly foreground?: string;
+    readonly background?: string;
     readonly attributes: readonly string[];
 }