@orkestrel/console 0.0.6 → 0.0.8

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

@@ -1,3 +1,4 @@
+import { Attribute } from '@orkestrel/console';
 import { Color } from '@orkestrel/console';
 import { SinkInterface } from '@orkestrel/console';
 
@@ -19,10 +20,14 @@ import { SinkInterface } from '@orkestrel/console';
  *   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>,
  *   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
+ *   unrelated entries stay byte-identical.
  * - **Pure + total.** Same input → same output; it never throws on any string (adversarial escapes,
  *   lone `ESC`, unterminated sequences all fall through as literal text).
  *
  * @param text - Any string, ANSI-styled or plain
+ * @param palette - Optional partial browser CSS overrides
  * @returns The `%c` format string + parallel CSS array ({@link ConsoleOutput})
  *
  * @example
@@ -32,7 +37,7 @@ import { SinkInterface } from '@orkestrel/console';
  * ansiToConsole('50%') // { format: '50%%', styles: [] }
  * ```
  */
-export declare function ansiToConsole(text: string): ConsoleOutput;
+export declare function ansiToConsole(text: string, palette?: BrowserPalette): ConsoleOutput;
 
 /**
  * Each text-{@link Attribute}'s SGR "on" number → its equivalent CSS declaration — the browser
@@ -50,15 +55,28 @@ export declare function ansiToConsole(text: string): ConsoleOutput;
 export declare const ATTRIBUTE_CSS: Readonly<Record<number, string>>;
 
 /**
- * Each SGR BACKGROUND parameter (40–47 / 100–107) → its `background:<hex>` CSS. The sink reads this
- * while scanning a run to translate a background code to CSS.
+ * 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.
  *
  * @remarks
- * Built the same way as {@link FOREGROUND_CSS} — keys from core's {@link BACKGROUND_CODES}, values
- * from {@link COLOR_HEX} — and covered by the same exhaustive walk over core's {@link COLORS} in
- * `tests/src/browser/helpers.test.ts`. Deeply frozen.
+ * - `color` maps a named non-default {@link Color} to the CSS color value used for both foreground
+ *   and background SGR codes.
+ * - `attribute` maps an {@link Attribute} to the CSS declaration used for its SGR code.
  */
-export declare const BACKGROUND_CSS: Readonly<Record<number, string>>;
+export declare interface BrowserPalette {
+    readonly color?: Readonly<Partial<Record<Exclude<Color, 'default'>, string>>>;
+    readonly attribute?: Readonly<Partial<Record<Attribute, string>>>;
+}
+
+/**
+ * Options for {@link import('./factories.js').createBrowserSink}.
+ *
+ * @remarks
+ * `palette` partially overrides the browser's default 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
@@ -100,12 +118,14 @@ export declare interface ConsoleOutput {
  * as a logger / reporter / spinner sink (`createLogger({ sink: createBrowserSink() })`) to retarget the
  * core output to the browser console with no change to the core.
  *
+ * @param options - See {@link BrowserSinkOptions}
  * @returns A browser `%c` {@link SinkInterface}
  *
  * @remarks
  * - **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.
@@ -127,7 +147,7 @@ export declare interface ConsoleOutput {
  * logger.error('boom') // → console.error('%c…', 'color:#cd0000;…') in DevTools
  * ```
  */
-export declare function createBrowserSink(): SinkInterface;
+export declare function createBrowserSink(options?: BrowserSinkOptions): SinkInterface;
 
 /**
  * The browser console directive that switches the active style — one `%c` prefixes every styled run
@@ -152,19 +172,6 @@ export declare const DIRECTIVE = "%c";
  */
 export declare function escapePercent(text: string): string;
 
-/**
- * Each SGR FOREGROUND parameter (30–37 / 90–97) → its `color:<hex>` CSS. The sink reads this while
- * scanning a run to translate a foreground code to CSS.
- *
- * @remarks
- * Every key is core's {@link FOREGROUND_CODES} entry and every value reads {@link COLOR_HEX}, so
- * neither the number↔name mapping nor the palette is duplicated here — this is a table of
- * references, not of literals. `tests/src/browser/helpers.test.ts` walks core's {@link COLORS} and
- * asserts this record covers every one of them, so a color added to core fails there rather than
- * going silently untranslated. Deeply frozen.
- */
-export declare const FOREGROUND_CSS: Readonly<Record<number, 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

package/dist/src/browser/index.js

@@ -1,4 +1,4 @@
-import { ATTRIBUTE_CODES, BACKGROUND_CODES, ESC, FOREGROUND_CODES, RESET_CODE } from "../core/index.js";
+import { ATTRIBUTES, ATTRIBUTE_CODES, BACKGROUND_CODES, COLORS, ESC, FOREGROUND_CODES, RESET_CODE } from "../core/index.js";
 //#region src/browser/constants.ts
 /**
 * Each named {@link Color}'s hex value — the 16 standard terminal colors a browser DevTools
@@ -50,62 +50,6 @@ var ATTRIBUTE_CSS = Object.freeze({
 	[ATTRIBUTE_CODES.strikethrough]: "text-decoration:line-through"
 });
 /**
-* Each SGR FOREGROUND parameter (30–37 / 90–97) → its `color:<hex>` CSS. The sink reads this while
-* scanning a run to translate a foreground code to CSS.
-*
-* @remarks
-* Every key is core's {@link FOREGROUND_CODES} entry and every value reads {@link COLOR_HEX}, so
-* neither the number↔name mapping nor the palette is duplicated here — this is a table of
-* references, not of literals. `tests/src/browser/helpers.test.ts` walks core's {@link COLORS} and
-* asserts this record covers every one of them, so a color added to core fails there rather than
-* going silently untranslated. Deeply frozen.
-*/
-var FOREGROUND_CSS = Object.freeze({
-	[FOREGROUND_CODES.black]: `color:${COLOR_HEX.black}`,
-	[FOREGROUND_CODES.red]: `color:${COLOR_HEX.red}`,
-	[FOREGROUND_CODES.green]: `color:${COLOR_HEX.green}`,
-	[FOREGROUND_CODES.yellow]: `color:${COLOR_HEX.yellow}`,
-	[FOREGROUND_CODES.blue]: `color:${COLOR_HEX.blue}`,
-	[FOREGROUND_CODES.magenta]: `color:${COLOR_HEX.magenta}`,
-	[FOREGROUND_CODES.cyan]: `color:${COLOR_HEX.cyan}`,
-	[FOREGROUND_CODES.white]: `color:${COLOR_HEX.white}`,
-	[FOREGROUND_CODES.brightBlack]: `color:${COLOR_HEX.brightBlack}`,
-	[FOREGROUND_CODES.brightRed]: `color:${COLOR_HEX.brightRed}`,
-	[FOREGROUND_CODES.brightGreen]: `color:${COLOR_HEX.brightGreen}`,
-	[FOREGROUND_CODES.brightYellow]: `color:${COLOR_HEX.brightYellow}`,
-	[FOREGROUND_CODES.brightBlue]: `color:${COLOR_HEX.brightBlue}`,
-	[FOREGROUND_CODES.brightMagenta]: `color:${COLOR_HEX.brightMagenta}`,
-	[FOREGROUND_CODES.brightCyan]: `color:${COLOR_HEX.brightCyan}`,
-	[FOREGROUND_CODES.brightWhite]: `color:${COLOR_HEX.brightWhite}`
-});
-/**
-* Each SGR BACKGROUND parameter (40–47 / 100–107) → its `background:<hex>` CSS. The sink reads this
-* while scanning a run to translate a background code to CSS.
-*
-* @remarks
-* Built the same way as {@link FOREGROUND_CSS} — keys from core's {@link BACKGROUND_CODES}, values
-* from {@link COLOR_HEX} — and covered by the same exhaustive walk over core's {@link COLORS} in
-* `tests/src/browser/helpers.test.ts`. Deeply frozen.
-*/
-var BACKGROUND_CSS = Object.freeze({
-	[BACKGROUND_CODES.black]: `background:${COLOR_HEX.black}`,
-	[BACKGROUND_CODES.red]: `background:${COLOR_HEX.red}`,
-	[BACKGROUND_CODES.green]: `background:${COLOR_HEX.green}`,
-	[BACKGROUND_CODES.yellow]: `background:${COLOR_HEX.yellow}`,
-	[BACKGROUND_CODES.blue]: `background:${COLOR_HEX.blue}`,
-	[BACKGROUND_CODES.magenta]: `background:${COLOR_HEX.magenta}`,
-	[BACKGROUND_CODES.cyan]: `background:${COLOR_HEX.cyan}`,
-	[BACKGROUND_CODES.white]: `background:${COLOR_HEX.white}`,
-	[BACKGROUND_CODES.brightBlack]: `background:${COLOR_HEX.brightBlack}`,
-	[BACKGROUND_CODES.brightRed]: `background:${COLOR_HEX.brightRed}`,
-	[BACKGROUND_CODES.brightGreen]: `background:${COLOR_HEX.brightGreen}`,
-	[BACKGROUND_CODES.brightYellow]: `background:${COLOR_HEX.brightYellow}`,
-	[BACKGROUND_CODES.brightBlue]: `background:${COLOR_HEX.brightBlue}`,
-	[BACKGROUND_CODES.brightMagenta]: `background:${COLOR_HEX.brightMagenta}`,
-	[BACKGROUND_CODES.brightCyan]: `background:${COLOR_HEX.brightCyan}`,
-	[BACKGROUND_CODES.brightWhite]: `background:${COLOR_HEX.brightWhite}`
-});
-/**
 * 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.
@@ -145,10 +89,14 @@ var SGR_PATTERN = new RegExp(`${ESC}\\[([0-9;]*)m`, "g");
 *   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>,
 *   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
+*   unrelated entries stay byte-identical.
 * - **Pure + total.** Same input → same output; it never throws on any string (adversarial escapes,
 *   lone `ESC`, unterminated sequences all fall through as literal text).
 *
 * @param text - Any string, ANSI-styled or plain
+* @param palette - Optional partial browser CSS overrides
 * @returns The `%c` format string + parallel CSS array ({@link ConsoleOutput})
 *
 * @example
@@ -158,7 +106,7 @@ var SGR_PATTERN = new RegExp(`${ESC}\\[([0-9;]*)m`, "g");
 * ansiToConsole('50%') // { format: '50%%', styles: [] }
 * ```
 */
-function ansiToConsole(text) {
+function ansiToConsole(text, palette) {
 	const scanner = new RegExp(SGR_PATTERN.source, SGR_PATTERN.flags);
 	let active = Object.freeze({
 		foreground: "",
@@ -195,23 +143,26 @@ function ansiToConsole(text) {
 				});
 				continue;
 			}
-			const foreground = FOREGROUND_CSS[code];
+			const foreground = COLORS.find((color) => FOREGROUND_CODES[color] === code);
 			if (foreground !== void 0) {
+				const color = palette?.color?.[foreground] ?? COLOR_HEX[foreground];
 				active = Object.freeze({
 					...active,
-					foreground
+					foreground: `color:${color}`
 				});
 				continue;
 			}
-			const background = BACKGROUND_CSS[code];
+			const background = COLORS.find((color) => BACKGROUND_CODES[color] === code);
 			if (background !== void 0) {
+				const color = palette?.color?.[background] ?? COLOR_HEX[background];
 				active = Object.freeze({
 					...active,
-					background
+					background: `background:${color}`
 				});
 				continue;
 			}
-			const attribute = ATTRIBUTE_CSS[code];
+			const name = ATTRIBUTES.find((attribute) => ATTRIBUTE_CODES[attribute] === code);
+			const attribute = name === void 0 ? void 0 : palette?.attribute?.[name] ?? ATTRIBUTE_CSS[code];
 			if (attribute !== void 0 && !active.attributes.includes(attribute)) active = Object.freeze({
 				...active,
 				attributes: Object.freeze([...active.attributes, attribute])
@@ -270,12 +221,14 @@ function parseParameters(parameters) {
 * as a logger / reporter / spinner sink (`createLogger({ sink: createBrowserSink() })`) to retarget the
 * core output to the browser console with no change to the core.
 *
+* @param options - See {@link BrowserSinkOptions}
 * @returns A browser `%c` {@link SinkInterface}
 *
 * @remarks
 * - **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.
@@ -297,12 +250,12 @@ function parseParameters(parameters) {
 * logger.error('boom') // → console.error('%c…', 'color:#cd0000;…') in DevTools
 * ```
 */
-function createBrowserSink() {
+function createBrowserSink(options) {
 	const log = console.log.bind(console);
 	const warn = console.warn.bind(console);
 	const error = console.error.bind(console);
 	return { write(text, level) {
-		const { format, styles } = ansiToConsole(text.startsWith("\r") ? text.slice(1) : text);
+		const { format, styles } = ansiToConsole(text.startsWith("\r") ? text.slice(1) : text, options?.palette);
 		if (level === "error") {
 			error(format, ...styles);
 			return;
@@ -315,6 +268,6 @@ function createBrowserSink() {
 	} };
 }
 //#endregion
-export { ATTRIBUTE_CSS, BACKGROUND_CSS, COLOR_HEX, DIRECTIVE, FOREGROUND_CSS, SGR_PATTERN, ansiToConsole, createBrowserSink, escapePercent, parseParameters };
+export { ATTRIBUTE_CSS, COLOR_HEX, DIRECTIVE, SGR_PATTERN, ansiToConsole, createBrowserSink, escapePercent, parseParameters };
 
 //# sourceMappingURL=index.js.map