colorino 0.14.1 → 0.15.1

package/README.md

@@ -23,6 +23,7 @@ Colorino automatically adapts its palette to your terminal or browser DevTools t
   - [Customization](#5-4)
   - [Supported Environment Variables](#5-5)
   - [Colorize Helper (Manual Overrides)](#5-6)
+  - [Browser‑only CSS Helper (`css()`)](#5-7)
 - [Colorino vs. Chalk](#6)
 - [API Reference](#7)
   - [1. `colorino` (default instance)](#7-1)
@@ -45,6 +46,7 @@ Colorino is different: it’s a "batteries-included" logging facade with beautif
 
 - 🎨 **Smart Theming:** Automatically detects _dark/light_ mode and applies a high‑contrast base palette by default (Dracula for dark, GitHub Light for light); 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.​
+- 🎯 **CSS styling in DevTools (browser only):** Use a dedicated helper to apply arbitrary CSS properties to specific console segments in Chrome, Firefox, and Safari DevTools, powered by the `%c` formatter.
 - 🤝 **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.
@@ -282,6 +284,25 @@ colorino.info(important, 'Something happened')
 
 When color is disabled (for example via `NO_COLOR=1` or lack of support), `colorize` returns the plain input string, so your logs stay readable.
 
+### <a id="5-7"></a>Browser‑only CSS Helper (`css()`)
+
+In the browser, Colorino also exposes a `css(text, style)` helper that lets you apply arbitrary CSS to a single segment in DevTools using the `%c` formatter.
+
+```ts
+import { colorino } from 'colorino'
+
+// Object form: keys are CSS properties, values are strings
+const badge = colorino.css('NEW', {
+  color: 'white',
+  'background-color': '#e91e63',
+  'font-weight': 'bold',
+  'border-radius': '4px',
+  padding: '2px 6px',
+})
+
+colorino.info('Release status:', badge, 'shipped')
+```
+
 ## <a id="6"></a>Colorino vs. Chalk
 
 | Feature                 | 🎨 **Colorino**          | 🖍️ **Chalk**      |
@@ -355,11 +376,11 @@ function getCallerContext(): string {
 export function createContextLogger(
   palette?: Partial<Palette>,
   options?: ColorinoOptions
-): Colorino {
+): ReturnType<typeof createColorino> {
   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.
+  const logger = Object.create(base) as ReturnType<typeof createColorino> // Object.create uses `base` as the prototype.
 
   // ...and override only what you need.
   Object.assign(logger, {
@@ -384,7 +405,7 @@ logger.error('Failed to load user', { id: 456 })
 ## <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.
+- `neverthrow` is bundled into the published artifacts, so you do not need to install it separately.
 
 ### <a id="9-1"></a>Why This Pattern?
 

package/dist/browser.d.mts

@@ -3,6 +3,16 @@ type LogLevel = ConsoleMethod & string;
 type Palette = Record<LogLevel, string>;
 type TerminalTheme = 'dark' | 'light' | 'unknown';
 type ThemeName = 'catppuccin-mocha' | 'catppuccin-latte' | 'dracula' | 'github-light';
+declare const ColorinoBrowserCss: unique symbol;
+type CssConsoleStyle = string | Record<string, string>;
+interface BrowserCssArg {
+    [ColorinoBrowserCss]: true;
+    text: string;
+    css: string;
+}
+
+declare const themePalettes: Record<ThemeName, Palette>;
+
 interface ColorinoOptions {
     disableWarnings?: boolean;
     theme?: TerminalTheme | ThemeName | 'auto';
@@ -18,12 +28,13 @@ interface Colorino {
     trace(...args: unknown[]): void;
     colorize(text: string, hex: string): void;
 }
+interface ColorinoBrowserInterface extends Colorino {
+    css(text: string, style: CssConsoleStyle): string | BrowserCssArg;
+}
 
-declare const themePalettes: Record<ThemeName, Palette>;
-
-declare function createColorino(userPalette?: Partial<Palette>, options?: ColorinoOptions): Colorino;
+declare function createColorino(userPalette?: Partial<Palette>, options?: ColorinoOptions): ColorinoBrowserInterface;
 
-declare const colorino: Colorino;
+declare const colorino: ColorinoBrowserInterface;
 
 export { colorino, createColorino, themePalettes };
-export type { Colorino, ColorinoOptions, LogLevel, Palette, ThemeName };
+export type { ColorinoBrowserInterface, ColorinoOptions, LogLevel, Palette, ThemeName };

package/dist/browser.d.ts

@@ -3,6 +3,16 @@ type LogLevel = ConsoleMethod & string;
 type Palette = Record<LogLevel, string>;
 type TerminalTheme = 'dark' | 'light' | 'unknown';
 type ThemeName = 'catppuccin-mocha' | 'catppuccin-latte' | 'dracula' | 'github-light';
+declare const ColorinoBrowserCss: unique symbol;
+type CssConsoleStyle = string | Record<string, string>;
+interface BrowserCssArg {
+    [ColorinoBrowserCss]: true;
+    text: string;
+    css: string;
+}
+
+declare const themePalettes: Record<ThemeName, Palette>;
+
 interface ColorinoOptions {
     disableWarnings?: boolean;
     theme?: TerminalTheme | ThemeName | 'auto';
@@ -18,12 +28,13 @@ interface Colorino {
     trace(...args: unknown[]): void;
     colorize(text: string, hex: string): void;
 }
+interface ColorinoBrowserInterface extends Colorino {
+    css(text: string, style: CssConsoleStyle): string | BrowserCssArg;
+}
 
-declare const themePalettes: Record<ThemeName, Palette>;
-
-declare function createColorino(userPalette?: Partial<Palette>, options?: ColorinoOptions): Colorino;
+declare function createColorino(userPalette?: Partial<Palette>, options?: ColorinoOptions): ColorinoBrowserInterface;
 
-declare const colorino: Colorino;
+declare const colorino: ColorinoBrowserInterface;
 
 export { colorino, createColorino, themePalettes };
-export type { Colorino, ColorinoOptions, LogLevel, Palette, ThemeName };
+export type { ColorinoBrowserInterface, ColorinoOptions, LogLevel, Palette, ThemeName };

package/dist/browser.mjs

@@ -2,6 +2,7 @@ import { err, ok } from 'neverthrow';
 
 const ColorinoBrowserColorized = Symbol("colorino.browserColorized");
 const ColorinoBrowserObject = Symbol("colorino.browserObject");
+const ColorinoBrowserCss = Symbol("colorino.browserCss");
 
 var ColorLevel = /* @__PURE__ */ ((ColorLevel2) => {
   ColorLevel2[ColorLevel2["NO_COLOR"] = 0] = "NO_COLOR";
@@ -36,6 +37,9 @@ class TypeValidator {
   static isBrowserColorizedArg(value) {
     return TypeValidator.isObject(value) && ColorinoBrowserColorized in value;
   }
+  static isBrowserCssArg(value) {
+    return typeof value === "object" && value !== null && ColorinoBrowserCss in value && value[ColorinoBrowserCss] === true;
+  }
   static isBrowserObjectArg(value) {
     return TypeValidator.isObject(value) && ColorinoBrowserObject in value;
   }
@@ -100,13 +104,13 @@ class AbstractColorino {
   }
   _out(level, args) {
     const consoleMethod = TypeValidator.isConsoleMethod(level) ? level : "log";
-    const processedArgs = this.processArgs(args);
+    const processedArgs = this._processArgs(args);
     if (this._colorLevel === ColorLevel.NO_COLOR || this._colorLevel === "UnknownEnv") {
-      this.output(consoleMethod, processedArgs);
+      this._output(consoleMethod, processedArgs);
       return;
     }
-    const coloredArgs = this.applyColors(consoleMethod, processedArgs);
-    this.output(consoleMethod, coloredArgs);
+    const coloredArgs = this._applyColors(consoleMethod, processedArgs);
+    this._output(consoleMethod, coloredArgs);
   }
   _toAnsiPrefix(_hex) {
     return "";
@@ -165,41 +169,69 @@ class ColorinoBrowser extends AbstractColorino {
   constructor(initialPalette, userPalette, validator, colorLevel, options = {}) {
     super(initialPalette, userPalette, validator, colorLevel, options);
   }
-  applyColors(consoleMethod, args) {
+  css(text, style) {
+    if (this._colorLevel === ColorLevel.NO_COLOR || this._colorLevel === "UnknownEnv") {
+      return text;
+    }
+    const css = this._normalizeCssStyle(style);
+    return {
+      [ColorinoBrowserCss]: true,
+      text,
+      css
+    };
+  }
+  _normalizeCssStyle(style) {
+    if (TypeValidator.isString(style)) return style;
+    const parts = [];
+    for (const propertyName in style) {
+      if (!Object.prototype.hasOwnProperty.call(style, propertyName)) {
+        continue;
+      }
+      const value = style[propertyName];
+      if (!value) continue;
+      parts.push(`${propertyName}:${value}`);
+    }
+    return parts.join(";");
+  }
+  _applyColors(consoleMethod, args) {
     const formatParts = [];
-    const cssArgs = [];
-    const otherArgs = [];
+    const formatArgs = [];
     const paletteHex = this._palette[consoleMethod];
     for (const arg of args) {
       if (TypeValidator.isBrowserColorizedArg(arg)) {
         formatParts.push(`%c${arg.text}`);
-        cssArgs.push(`color:${arg.hex}`);
+        formatArgs.push(`color:${arg.hex}`);
+        continue;
+      }
+      if (TypeValidator.isBrowserCssArg(arg)) {
+        formatParts.push(`%c${arg.text}`);
+        formatArgs.push(arg.css);
         continue;
       }
       if (TypeValidator.isBrowserObjectArg(arg)) {
         formatParts.push("%o");
-        otherArgs.push(arg.value);
+        formatArgs.push(arg.value);
         continue;
       }
       if (TypeValidator.isString(arg)) {
         formatParts.push(`%c${arg}`);
-        cssArgs.push(`color:${paletteHex}`);
+        formatArgs.push(`color:${paletteHex}`);
         continue;
       }
       formatParts.push("%o");
-      otherArgs.push(arg);
+      formatArgs.push(arg);
     }
     if (formatParts.length === 0) return args;
-    return [formatParts.join(""), ...cssArgs, ...otherArgs];
+    return [formatParts.join(""), ...formatArgs];
   }
-  output(consoleMethod, args) {
+  _output(consoleMethod, args) {
     console[consoleMethod](...args);
   }
-  processArgs(args) {
+  _processArgs(args) {
     const processedArgs = [];
     let previousWasObject = false;
     for (const arg of args) {
-      if (TypeValidator.isBrowserColorizedArg(arg)) {
+      if (TypeValidator.isBrowserColorizedArg(arg) || TypeValidator.isBrowserCssArg(arg)) {
         processedArgs.push(arg);
         previousWasObject = false;
         continue;

package/dist/cdn.js

@@ -1,11 +1,12 @@
 (function (global, factory) {
-  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
-  typeof define === 'function' && define.amd ? define(['exports'], factory) :
-  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.colorino = {}));
-})(this, (function (exports) { 'use strict';
+  typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
+  typeof define === 'function' && define.amd ? define(factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, global.colorino = factory());
+})(this, (function () { 'use strict';
 
   const ColorinoBrowserColorized = Symbol("colorino.browserColorized");
   const ColorinoBrowserObject = Symbol("colorino.browserObject");
+  const ColorinoBrowserCss = Symbol("colorino.browserCss");
 
   var ColorLevel = /* @__PURE__ */ ((ColorLevel2) => {
     ColorLevel2[ColorLevel2["NO_COLOR"] = 0] = "NO_COLOR";
@@ -40,6 +41,9 @@
     static isBrowserColorizedArg(value) {
       return TypeValidator.isObject(value) && ColorinoBrowserColorized in value;
     }
+    static isBrowserCssArg(value) {
+      return typeof value === "object" && value !== null && ColorinoBrowserCss in value && value[ColorinoBrowserCss] === true;
+    }
     static isBrowserObjectArg(value) {
       return TypeValidator.isObject(value) && ColorinoBrowserObject in value;
     }
@@ -104,13 +108,13 @@
     }
     _out(level, args) {
       const consoleMethod = TypeValidator.isConsoleMethod(level) ? level : "log";
-      const processedArgs = this.processArgs(args);
+      const processedArgs = this._processArgs(args);
       if (this._colorLevel === ColorLevel.NO_COLOR || this._colorLevel === "UnknownEnv") {
-        this.output(consoleMethod, processedArgs);
+        this._output(consoleMethod, processedArgs);
         return;
       }
-      const coloredArgs = this.applyColors(consoleMethod, processedArgs);
-      this.output(consoleMethod, coloredArgs);
+      const coloredArgs = this._applyColors(consoleMethod, processedArgs);
+      this._output(consoleMethod, coloredArgs);
     }
     _toAnsiPrefix(_hex) {
       return "";
@@ -169,41 +173,69 @@ ${cleanStack}`);
     constructor(initialPalette, userPalette, validator, colorLevel, options = {}) {
       super(initialPalette, userPalette, validator, colorLevel, options);
     }
-    applyColors(consoleMethod, args) {
+    css(text, style) {
+      if (this._colorLevel === ColorLevel.NO_COLOR || this._colorLevel === "UnknownEnv") {
+        return text;
+      }
+      const css = this._normalizeCssStyle(style);
+      return {
+        [ColorinoBrowserCss]: true,
+        text,
+        css
+      };
+    }
+    _normalizeCssStyle(style) {
+      if (TypeValidator.isString(style)) return style;
+      const parts = [];
+      for (const propertyName in style) {
+        if (!Object.prototype.hasOwnProperty.call(style, propertyName)) {
+          continue;
+        }
+        const value = style[propertyName];
+        if (!value) continue;
+        parts.push(`${propertyName}:${value}`);
+      }
+      return parts.join(";");
+    }
+    _applyColors(consoleMethod, args) {
       const formatParts = [];
-      const cssArgs = [];
-      const otherArgs = [];
+      const formatArgs = [];
       const paletteHex = this._palette[consoleMethod];
       for (const arg of args) {
         if (TypeValidator.isBrowserColorizedArg(arg)) {
           formatParts.push(`%c${arg.text}`);
-          cssArgs.push(`color:${arg.hex}`);
+          formatArgs.push(`color:${arg.hex}`);
+          continue;
+        }
+        if (TypeValidator.isBrowserCssArg(arg)) {
+          formatParts.push(`%c${arg.text}`);
+          formatArgs.push(arg.css);
           continue;
         }
         if (TypeValidator.isBrowserObjectArg(arg)) {
           formatParts.push("%o");
-          otherArgs.push(arg.value);
+          formatArgs.push(arg.value);
           continue;
         }
         if (TypeValidator.isString(arg)) {
           formatParts.push(`%c${arg}`);
-          cssArgs.push(`color:${paletteHex}`);
+          formatArgs.push(`color:${paletteHex}`);
           continue;
         }
         formatParts.push("%o");
-        otherArgs.push(arg);
+        formatArgs.push(arg);
       }
       if (formatParts.length === 0) return args;
-      return [formatParts.join(""), ...cssArgs, ...otherArgs];
+      return [formatParts.join(""), ...formatArgs];
     }
-    output(consoleMethod, args) {
+    _output(consoleMethod, args) {
       console[consoleMethod](...args);
     }
-    processArgs(args) {
+    _processArgs(args) {
       const processedArgs = [];
       let previousWasObject = false;
       for (const arg of args) {
-        if (TypeValidator.isBrowserColorizedArg(arg)) {
+        if (TypeValidator.isBrowserColorizedArg(arg) || TypeValidator.isBrowserCssArg(arg)) {
           processedArgs.push(arg);
           previousWasObject = false;
           continue;
@@ -894,9 +926,11 @@ ${arg}` : arg
   }
   const colorino = createColorino();
 
-  exports.colorino = colorino;
-  exports.createColorino = createColorino;
-  exports.themePalettes = themePalettes;
+  const colorinoUmdGlobal = colorino;
+  colorinoUmdGlobal.createColorino = createColorino;
+  colorinoUmdGlobal.themePalettes = themePalettes;
+
+  return colorinoUmdGlobal;
 
 }));
 //# sourceMappingURL=cdn.js.map