colorino 0.10.0 → 0.11.0

package/README.md

@@ -1,8 +1,8 @@
 # <a id="0"></a>🎨 Colorino
 
-**The zero-configuration, context-aware `console` logger for Node.js and the browser.**
+**The zero‑configuration, context‑aware `console` logger for Node.js and the browser—with smart theming and graceful color degradation.**
 
-Colorino automatically adapts its palette to your terminal or browser DevTools theme, and defaults to **minimal, high-contrast** colors unless you opt into a specific theme preset.
+Colorino automatically adapts its palette to your terminal or browser DevTools theme, and degrades colors gracefully so your logs stay readable and on‑brand even in limited environments
 
 # <a id="0"></a><a id="0"></a>
 
@@ -23,8 +23,10 @@ Colorino automatically adapts its palette to your terminal or browser DevTools t
   - [1. `colorino` (default instance)](#7-1)
   - [2. `createColorino(palette?, options?)` (factory)](#7-2)
 - [Extending Colorino](#8)
-  - [Why This Pattern?](#8-1)
-- [License](#9)
+  - [Use case: automatic file/context info](#8-1)
+- [Internals & Dependencies](#9)
+  - [Why This Pattern?](#9-1)
+- [License](#10)
 
 <!-- Table of contents is made with https://github.com/eugene-khyst/md-toc-cli -->
 
@@ -37,6 +39,7 @@ Colorino is different: it’s a "batteries-included" logging facade with beautif
 ## <a id="2"></a>Features
 
 - 🎨 **Smart Theming:** Automatically detects *dark/light* mode and applies a **minimal** high-contrast base palette by default; opt into a coordinated theme preset when you want richer colors.
+- 🤘 **Graceful Color Degradation**: Accepts rich colors (hex/RGB) and automatically down‑samples to the best ANSI‑16/ANSI‑256/Truecolor match for the current environment.​
 - 🤝 **Familiar API:** If you know `console.log`, you already know Colorino: all standard log levels are supported.
 - 🔀 **Environment-Aware:** Works in **Node.js** (ANSI color and truecolor) and all major **Browsers** (CSS styles).
 - ⚡️ **Fast, Lightweight:** Minimal dependencies, works great in modern frameworks and CLIs.
@@ -127,14 +130,17 @@ myLogger.info('Rebranded info!')
 
 `createColorino(palette?, options?)` accepts:
 
-| Option            | Type                           | Default | Description                                                                    |
-|-------------------|--------------------------------|---------|--------------------------------------------------------------------------------|
-| `disableWarnings` | `boolean`                      | `false` | Suppress warnings when color support can't be detected or is disabled.         |
-| `theme`           | `ThemeOption` (see below)      | `'auto'`| Control the active color theme or force a specific mode.                       |
+| Option            | Type                                 | Default | Description                                                                 |
+|-------------------|--------------------------------------|---------|-----------------------------------------------------------------------------|
+| `disableWarnings` | `boolean`                           | `false` | Suppress warnings when color support can't be detected or is disabled.      |
+| `theme`           | `ThemeOption` (see below)           | `'auto'`| Control the active color theme or force a specific mode.                    |
+| `disableOscProbe` | `boolean`                           | `false` | Disable OSC 11 terminal theme probing (use only env heuristics for theme).  |
+| `maxDepth`        | `number`                            | `5`     | Maximum depth when pretty-printing objects in log output.                   |
 
 **`theme` accepts three types of values:**
 
-1. **`'auto'`** (Default): Automatically detects your terminal or browser theme (dark/light) and applies the matching default preset.
+1. **`'auto'`** (Default): Automatically detects your terminal or browser theme (dark/light) and applies the matching default preset.  
+When combined with `disableOscProbe: true`, only environment variables are used for theme detection (no OSC 11 probe).
 2. **`'dark' | 'light'`**: Forces the logger into a specific mode using the default preset for that mode.
 3. **`ThemeName`**: Forces a specific built-in palette (e.g., `'dracula'`).
 
@@ -174,15 +180,7 @@ const myLogger = createColorino({
 // - info, log, debug, trace: #000000 (black - safe on light)
 ```
 
-**2. Force a specific mode (uses defaults):**
-Useful for CI/CD or environments where detection fails.
-
-```typescript
-// Forces dark mode using the default minimal palette (minimal-dark)
-const darkLogger = createColorino({}, { theme: 'dark' })
-```
-
-**3. Use a specific preset:**
+**2. Use a specific preset:**
 Instant branding with zero configuration.
 
 ```typescript
@@ -190,7 +188,7 @@ Instant branding with zero configuration.
 const draculaLogger = createColorino({}, { theme: 'dracula' })
 ```
 
-**4. Customize a preset:**
+**3. Customize a preset:**
 Overlay your own colors on top of a built-in theme.
 
 ```typescript
@@ -201,6 +199,14 @@ const myLogger = createColorino(
 )
 ```
 
+**4. Force a specific mode (uses defaults):**
+Useful for CI/CD or environments where detection fails.
+
+```typescript
+// Forces dark mode using the default minimal palette (minimal-dark)
+const darkLogger = createColorino({}, { theme: 'dark' })
+```
+
 > **Tip:**
 > Forcing `'dark'` or `'light'` bypasses automatic theming, ensuring predictable colors in environments with unknown or unsupported theme detection (like some CI pipelines, dumb terminals, or minimal browsers).
 
@@ -208,6 +214,10 @@ const myLogger = createColorino(
 
 Use your brand colors by passing a partial palette to the `createColorino` factory. Any log levels you don't specify will use the detected **minimal** defaults (`minimal-dark` / `minimal-light`) unless you explicitly select a theme preset.
 
+Colorino always targets the highest color fidelity supported by the environment. If your palette uses hex colors but only ANSI‑16 is available, Colorino computes the nearest ANSI color so your branding stays recognizable, even on limited terminals.
+
+If you pass an invalid color value (e.g. malformed hex) in a custom palette, Colorino throws an InputValidationError at creation time so broken palettes fail fast.
+
 ```typescript
 import { createColorino } from 'colorino'
 
@@ -222,16 +232,16 @@ myLogger.info('Still styled by theme.') // Uses the default theme color
 
 Colorino auto-detects your environment and color support, but you can override behavior using these standard environment variables (compatible with Chalk):
 
-| Variable         | Effect                                            | Example                  |
-|------------------|---------------------------------------------------|--------------------------|
-| `NO_COLOR`       | Forces *no color* output                          | `NO_COLOR=1 node app.js` |
-| `FORCE_COLOR`    | Forces color (`1`=ANSI, `2`=256, `3`=truecolor)   | `FORCE_COLOR=3 node app.js` |
-| `CLICOLOR`       | `"0"` disables color                              | `CLICOLOR=0 node app.js` |
-| `CLICOLOR_FORCE` | Non-`"0"` value enables color even if not a TTY   | `CLICOLOR_FORCE=1 node app.js` |
-| `TERM`           | Terminal type, can increase/decrease support      | `TERM=xterm-256color`    |
-| `COLORTERM`      | `'truecolor'` or `'24bit'` enables truecolor      | `COLORTERM=truecolor`    |
-| `WT_SESSION`     | Detected for Windows Terminal (enables color)     |                          |
-| `CI`             | Many CI platforms default to *no color*           | `CI=1 node app.js`       |
+| Variable        | Effect                                                                                   | Example                              |
+|-----------------|------------------------------------------------------------------------------------------|--------------------------------------|
+| `NO_COLOR`      | Forces no color output                                                                   | `NO_COLOR=1 node app.js`            |
+| `FORCE_COLOR`   | Forces color level: `0`=off, `1`=ANSI‑16, `2`=ANSI‑256, `3`=Truecolor                    | `FORCE_COLOR=3 node app.js`         |
+| `CLICOLOR`      | `"0"` disables color                                                                     | `CLICOLOR=0 node app.js`            |
+| `CLICOLOR_FORCE`| Non‑`"0"` value enables color even if not a TTY                                          | `CLICOLOR_FORCE=1 node app.js`      |
+| `TERM`          | Terminal type; may influence color support                                               | `TERM=xterm-256color`               |
+| `COLORTERM`     | `'truecolor'` or `'24bit'` enables truecolor                                             | `COLORTERM=truecolor`               |
+| `WT_SESSION`    | Enables color detection for Windows Terminal                                             |                                      |
+| `CI`            | Many CI platforms default to no color                                                    | `CI=1 node app.js`                  |
 
 ## <a id="6"></a>Colorino vs. Chalk
 
@@ -269,48 +279,69 @@ A factory function to create your own customized logger instances.
 
 ## <a id="8"></a>Extending Colorino
 
-Example: Add a `fatal()` logger for critical errors.
+Colorino is designed for composition: create a base logger via `createColorino()`, then extend it by inheriting from the base and overriding only the methods you need.
 
-Since colorino uses a factory pattern, extend it by creating your own factory that composes the base logger with additional methods:
+### <a id="8-1"></a>Use case: automatic file/context info
 
-```typescript
-import { createColorino, type ColorinoOptions, type Palette } from 'colorino'
-
-// Create a factory for your custom logger
-export function createMyLogger(palette?: Partial<Palette>, options?: ColorinoOptions) {
-  // Get the base logger instance
-  const baseLogger = createColorino(palette, options)
-
-  // Define your custom method
-  function fatal(...args: unknown[]): void {
-    // Reuse the base logger's error method
-    baseLogger.error(...args)
-
-    // Add your custom behavior
-    if (typeof process !== 'undefined' && process.exit) {
-      process.exit(1)
-    }
-  }
-
-  // Return a new object with all base methods + your custom ones
-  // This preserves type safety and the original API
-  return {
-    ...baseLogger,
-    fatal,
-  }
-}
-```
+This example prefixes every `.info()` and `.error()` call with best‑effort caller context (file/line) derived from a synthetic `Error` stack.
 
-Usage:
+```ts
+import { createColorino, type Colorino, type ColorinoOptions, type Palette } from 'colorino'
 
-```typescript
-const logger = createMyLogger({ error: '#d92626' })
+function getCallerContext(): string {
+  const err = new Error()
+  if (!err.stack) return 'unknown'
+
+  const lines = err.stack.split('\n').slice(2) // skip "Error" + current frame
+  const frame = lines[0] ?? ''
+
+  const match =
+    frame.match(/at (.+?) \((.+?):(\d+):\d+\)/) ??
+    frame.match(/at (.+?):(\d+):\d+/)
+
+  if (!match) return frame.trim() || 'unknown'
 
-logger.info('Starting!')
-logger.fatal('Missing config: Exiting')
+  const [_, maybeFn, fileOrLine, maybeLine] = match
+  const file = maybeLine ? fileOrLine : maybeFn
+  const line = maybeLine ?? fileOrLine
+
+  return `${file}:${line}`
+}
+
+export function createContextLogger(
+  palette?: Partial<Palette>,
+  options?: ColorinoOptions,
+): Colorino {
+  const base = createColorino(palette, options)
+
+  // Inherit all default methods from the base logger...
+  const logger = Object.create(base) as Colorino // Object.create uses `base` as the prototype. 
+
+  // ...and override only what you need.
+  Object.assign(logger, { // Object.assign copies these methods onto `logger`. [web:346]
+    info(...args: unknown[]) {
+      base.info(`[${getCallerContext()}]`, ...args)
+    },
+    error(...args: unknown[]) {
+      base.error(`[${getCallerContext()}]`, ...args)
+    },
+  })
+
+  return logger
+}
+
+// Usage
+const logger = createContextLogger({}, { theme: 'dracula' })
+logger.info('User created', { id: 123 })
+logger.error('Failed to load user', { id: 456 })
 ```
 
-### <a id="8-1"></a>Why This Pattern?
+## <a id="9"></a>Internals & Dependencies
+
+- Colorino’s runtime logic depends on a single bundled library, `neverthrow`, which is MIT‑licensed and used for type‑safe Result handling.
+- `neverthrow` is bundled into the published artifacts, so you do not need to install it separately; your application sees a single runtime dependency: Colorino itself.
+
+### <a id="9-1"></a>Why This Pattern?
 
 - **Composition > Inheritance**: No fragile base class problems
 - **Type Safe**: TypeScript infers the return type correctly
@@ -318,6 +349,6 @@ logger.fatal('Missing config: Exiting')
 - **Clean**: No messing with `super()` or constructor parameters
 - **Composable**: You can layer multiple extensions
 
-## <a id="9"></a>License
+## <a id="10"></a>License
 
 [MIT](LICENSE.md)

package/dist/browser.bundle.cjs

@@ -63,13 +63,115 @@ function isConsoleMethod(level) {
   return ["log", "info", "warn", "error", "trace", "debug"].includes(level);
 }
 
-class Colorino {
-  constructor(_palette, _validator, _browserColorSupportDetector, _nodeColorSupportDetector, _options = {}) {
-    this._palette = _palette;
+const catppuccinMochaPalette = {
+  log: "#cdd6f4",
+  // Text
+  info: "#89b4fa",
+  // Blue
+  warn: "#f9e2af",
+  // Yellow
+  error: "#f38ba8",
+  // Red
+  debug: "#a6adc8",
+  // Subtext0
+  trace: "#9399b2"
+  // Subtext1
+};
+const catppuccinLattePalette = {
+  log: "#4c4f69",
+  // Text
+  info: "#1e66f5",
+  // Blue
+  warn: "#df8e1d",
+  // Yellow
+  error: "#d20f39",
+  // Red
+  debug: "#7c7f93",
+  // Subtext0
+  trace: "#8c8fa1"
+  // Subtext1
+};
+const draculaPalette = {
+  log: "#f8f8f2",
+  // Foreground
+  info: "#8be9fd",
+  // Cyan
+  warn: "#f1fa8c",
+  // Yellow
+  error: "#ff5555",
+  // Red
+  debug: "#bd93f9",
+  // Purple
+  trace: "#6272a4"
+  // Comment
+};
+const githubLightPalette = {
+  log: "#24292e",
+  // Text
+  info: "#0366d6",
+  // Blue
+  warn: "#f9a002",
+  // Yellow
+  error: "#d73a49",
+  // Red
+  debug: "#586069",
+  // Gray
+  trace: "#6a737d"
+  // Gray-light
+};
+const minimalDarkPalette = {
+  log: "#ffffff",
+  info: "#ffffff",
+  warn: "#ffffff",
+  error: "#ffffff",
+  debug: "#ffffff",
+  trace: "#ffffff"
+};
+const minimalLightPalette = {
+  log: "#000000",
+  info: "#000000",
+  warn: "#000000",
+  error: "#000000",
+  debug: "#000000",
+  trace: "#000000"
+};
+
+const themePalettes = {
+  "catppuccin-mocha": catppuccinMochaPalette,
+  "catppuccin-latte": catppuccinLattePalette,
+  dracula: draculaPalette,
+  "github-light": githubLightPalette,
+  "minimal-dark": minimalDarkPalette,
+  "minimal-light": minimalLightPalette
+};
+const defaultDarkTheme = "minimal-dark";
+const defaultLightTheme = "minimal-light";
+function isThemeName(theme) {
+  return theme in themePalettes;
+}
+
+function determineBaseTheme(themeOpt, detectedBrowserTheme) {
+  let baseThemeName;
+  if (isThemeName(themeOpt)) {
+    baseThemeName = themeOpt;
+  } else if (themeOpt === "light") {
+    baseThemeName = defaultLightTheme;
+  } else if (themeOpt === "dark") {
+    baseThemeName = defaultDarkTheme;
+  } else {
+    baseThemeName = detectedBrowserTheme === "light" ? defaultLightTheme : defaultDarkTheme;
+  }
+  return baseThemeName;
+}
+
+class MyColorino {
+  constructor(initialPalette, _userPalette, _validator, _browserColorSupportDetector, _nodeColorSupportDetector, _options = {}) {
+    this._userPalette = _userPalette;
     this._validator = _validator;
     this._browserColorSupportDetector = _browserColorSupportDetector;
     this._nodeColorSupportDetector = _nodeColorSupportDetector;
     this._options = _options;
+    this._palette = initialPalette;
     this.isBrowser = !!this._browserColorSupportDetector;
     this._colorLevel = this._detectColorSupport();
     const validatePaletteResult = this._validator.validatePalette(this._palette);
@@ -77,10 +179,23 @@ class Colorino {
     if (this._colorLevel !== ColorLevel.NO_COLOR && !this._options.disableWarnings && this._colorLevel === "UnknownEnv") {
       this._maybeWarnUser();
     }
+    const themeOpt = this._options.theme ?? "auto";
+    if (themeOpt === "auto" && this._nodeColorSupportDetector) {
+      this._nodeColorSupportDetector.onTheme((resolvedTheme) => {
+        this._appllyResolvedTheme(resolvedTheme);
+      });
+    }
   }
   _alreadyWarned = false;
   _colorLevel;
   isBrowser;
+  _palette;
+  _appllyResolvedTheme(resolvedTheme) {
+    const themeOpt = this._options.theme ?? "auto";
+    const baseThemeName = determineBaseTheme(themeOpt, resolvedTheme);
+    const basePalette = themePalettes[baseThemeName];
+    this._palette = { ...basePalette, ...this._userPalette };
+  }
   log(...args) {
     this._out("log", args);
   }
@@ -112,10 +227,10 @@ class Colorino {
     if (this._alreadyWarned) return;
     this._alreadyWarned = true;
     console.warn(
-      "[Colorino] No ANSI color support detected in this terminal. See [https://github.com/chalk/supports-color#support-matrix](https://github.com/chalk/supports-color#support-matrix) to learn how to enable terminal color."
+      "No ANSI color support detected in this terminal. See [https://github.com/chalk/supports-color#support-matrix](https://github.com/chalk/supports-color#support-matrix) to learn how to enable terminal color."
     );
   }
-  _formatValue(value, maxDepth = 5) {
+  _formatValue(value, maxDepth = this._options.maxDepth ?? 5) {
     const seen = /* @__PURE__ */ new WeakSet();
     const sanitize = (val, currentDepth) => {
       if (val === null || typeof val !== "object") return val;
@@ -200,7 +315,7 @@ ${arg}`);
   }
   _output(consoleMethod, args) {
     if (consoleMethod === "trace") {
-      this._printCleanTrace(args, consoleMethod);
+      this._printCleanTrace(args);
     } else {
       console[consoleMethod](...args);
     }
@@ -221,9 +336,7 @@ ${arg}`);
     this._output(consoleMethod, coloredArgs);
   }
   _filterStack(stack) {
-    return stack.split("\n").filter(
-      (line) => !line.includes("colorino.js") && !line.includes("Colorino._out") && !line.includes("Colorino.error") && !line.includes("Colorino.warn") && !line.includes("Colorino.debug") && !line.includes("Colorino.info") && !line.includes("Colorino.log") && !line.includes("Colorino.trace") && !line.includes("Colorino._cleanErrorStack") && !line.includes("Colorino._printCleanTrace") && !line.includes("Colorino._filterStack")
-    ).join("\n");
+    return stack.split("\n").filter((line) => !line.match(/.*colorino.*/gi)).join("\n");
   }
   _cleanErrorStack(error) {
     if (!error.stack) return error;
@@ -233,14 +346,14 @@ ${arg}`);
     cloned.stack = cleanStack;
     return cloned;
   }
-  _printCleanTrace(args, method) {
+  _printCleanTrace(args) {
     const error = new Error();
     if (error.stack) {
       const cleanStack = this._filterStack(error.stack);
-      console[method](...args, `
+      console.log(...args, `
 ${cleanStack}`);
     } else {
-      console[method](...args);
+      console.log(...args);
     }
   }
 }
@@ -756,107 +869,6 @@ class InputValidator {
   }
 }
 
-const catppuccinMochaPalette = {
-  log: "#cdd6f4",
-  // Text
-  info: "#89b4fa",
-  // Blue
-  warn: "#f9e2af",
-  // Yellow
-  error: "#f38ba8",
-  // Red
-  debug: "#a6adc8",
-  // Subtext0
-  trace: "#9399b2"
-  // Subtext1
-};
-const catppuccinLattePalette = {
-  log: "#4c4f69",
-  // Text
-  info: "#1e66f5",
-  // Blue
-  warn: "#df8e1d",
-  // Yellow
-  error: "#d20f39",
-  // Red
-  debug: "#7c7f93",
-  // Subtext0
-  trace: "#8c8fa1"
-  // Subtext1
-};
-const draculaPalette = {
-  log: "#f8f8f2",
-  // Foreground
-  info: "#8be9fd",
-  // Cyan
-  warn: "#f1fa8c",
-  // Yellow
-  error: "#ff5555",
-  // Red
-  debug: "#bd93f9",
-  // Purple
-  trace: "#6272a4"
-  // Comment
-};
-const githubLightPalette = {
-  log: "#24292e",
-  // Text
-  info: "#0366d6",
-  // Blue
-  warn: "#f9a002",
-  // Yellow
-  error: "#d73a49",
-  // Red
-  debug: "#586069",
-  // Gray
-  trace: "#6a737d"
-  // Gray-light
-};
-const minimalDarkPalette = {
-  log: "#ffffff",
-  info: "#ffffff",
-  warn: "#ffffff",
-  error: "#ffffff",
-  debug: "#ffffff",
-  trace: "#ffffff"
-};
-const minimalLightPalette = {
-  log: "#000000",
-  info: "#000000",
-  warn: "#000000",
-  error: "#000000",
-  debug: "#000000",
-  trace: "#000000"
-};
-
-const themePalettes = {
-  "catppuccin-mocha": catppuccinMochaPalette,
-  "catppuccin-latte": catppuccinLattePalette,
-  dracula: draculaPalette,
-  "github-light": githubLightPalette,
-  "minimal-dark": minimalDarkPalette,
-  "minimal-light": minimalLightPalette
-};
-const defaultDarkTheme = "minimal-dark";
-const defaultLightTheme = "minimal-light";
-function isThemeName(theme) {
-  return theme in themePalettes;
-}
-
-function determineBaseTheme(themeOpt, detectedBrowserTheme) {
-  let baseThemeName;
-  if (isThemeName(themeOpt)) {
-    baseThemeName = themeOpt;
-  } else if (themeOpt === "light") {
-    baseThemeName = defaultLightTheme;
-  } else if (themeOpt === "dark") {
-    baseThemeName = defaultDarkTheme;
-  } else {
-    baseThemeName = detectedBrowserTheme === "light" ? defaultLightTheme : defaultDarkTheme;
-  }
-  return baseThemeName;
-}
-
 class BrowserColorSupportDetector {
   constructor(_window, _navigator, _overrideTheme) {
     this._window = _window;
@@ -892,7 +904,7 @@ class BrowserColorSupportDetector {
   }
 }
 
-function createColorino(palette = {}, options = {}) {
+function createColorino(userPalette = {}, options = {}) {
   const validator = new InputValidator();
   let detectorThemeOverride;
   if (options.theme === "dark" || options.theme === "light") {
@@ -910,9 +922,10 @@ function createColorino(palette = {}, options = {}) {
     detectedBrowserTheme
   );
   const basePalette = themePalettes[baseThemeName];
-  const finalPalette = { ...basePalette, ...palette };
-  return new Colorino(
+  const finalPalette = { ...basePalette, ...userPalette };
+  return new MyColorino(
     finalPalette,
+    userPalette,
     validator,
     browserDetector,
     // Always use browser detector
@@ -921,8 +934,6 @@ function createColorino(palette = {}, options = {}) {
     options
   );
 }
-const colorino = createColorino();
 
-exports.colorino = colorino;
 exports.createColorino = createColorino;
 exports.themePalettes = themePalettes;