@leftium/gg 0.0.27 → 0.0.29

package/README.md

@@ -20,7 +20,67 @@ npm add @leftium/gg
 
 ## Usage
 
-_Coming soon..._
+### Basic Logging
+
+```javascript
+import { gg } from '@leftium/gg';
+
+// Simple logging
+gg('Hello world');
+
+// Log expressions (returns first argument)
+const result = gg(someFunction());
+
+// Multiple arguments
+gg('User:', user, 'Status:', status);
+```
+
+### Color Support (ANSI)
+
+Color your logs for better visual distinction using `fg()` (foreground/text) and `bg()` (background):
+
+```javascript
+import { gg, fg, bg } from '@leftium/gg';
+
+// Simple foreground/background colors
+gg(fg('red')`Error occurred`);
+gg(bg('yellow')`Warning message`);
+
+// Method chaining (order doesn't matter!)
+gg(fg('white').bg('red')`Critical error!`);
+gg(bg('green').fg('white')`Success message`);
+
+// Define reusable color schemes
+const input = fg('blue').bg('yellow');
+const transcript = bg('green').fg('white');
+const error = fg('white').bg('red');
+
+gg(input`User input message`);
+gg(transcript`AI transcript response`);
+gg(error`Something went wrong`);
+
+// Mix colored and normal text
+gg(fg('red')`Error: ` + bg('yellow')`warning` + ' normal text');
+
+// Custom hex colors with chaining
+gg(fg('#ff6347').bg('#98fb98')`Custom colors`);
+
+// RGB colors
+gg(fg('rgb(255,99,71)')`Tomato text`);
+```
+
+**Supported color formats:**
+
+- Named colors: `'red'`, `'green'`, `'blue'`, `'cyan'`, `'magenta'`, `'yellow'`, `'white'`, `'black'`, `'gray'`, `'orange'`, `'purple'`, `'pink'`
+- Hex codes: `'#ff0000'`, `'#f00'`
+- RGB: `'rgb(255,0,0)'`, `'rgba(255,0,0,0.5)'`
+
+**Where colors work:**
+
+- ✅ Native browser console (Chrome DevTools, Firefox, etc.)
+- ✅ Eruda GG panel (mobile debugging)
+- ✅ Node.js terminal
+- ✅ All environments that support ANSI escape codes
 
 ## Technical Details
 

package/dist/eruda/plugin.js

@@ -570,7 +570,8 @@ export function createGgPlugin(options, gg) {
                     if (typeof arg === 'object' && arg !== null) {
                         return JSON.stringify(arg);
                     }
-                    return String(arg);
+                    // Strip ANSI escape codes from string args
+                    return stripAnsi(String(arg));
                 })
                     .join(' ');
                 return `${time} ${ns} ${argsStr}`;
@@ -715,13 +716,13 @@ export function createGgPlugin(options, gg) {
                         return `<span style="color: #888; cursor: pointer; text-decoration: underline;" class="gg-expand" data-index="${uniqueId}">${preview}</span>`;
                     }
                     else {
-                        // Convert URLs to clickable links
+                        // Parse ANSI codes first, then convert URLs to clickable links
                         const argStr = String(arg);
-                        const urlRegex = /(https?:\/\/[^\s]+)/g;
-                        const linkedText = argStr.replace(urlRegex, (url) => {
-                            return `<a href="${escapeHtml(url)}" target="_blank" style="color: #0066cc; text-decoration: underline;">${escapeHtml(url)}</a>`;
-                        });
-                        return `<span>${linkedText}</span>`;
+                        const parsedAnsi = parseAnsiToHtml(argStr);
+                        // Note: URL linking happens after ANSI parsing, so links work inside colored text
+                        // This is a simple approach - URLs inside ANSI codes won't be linkified
+                        // For more complex parsing, we'd need to track ANSI state while matching URLs
+                        return `<span>${parsedAnsi}</span>`;
                     }
                 })
                     .join(' ');
@@ -773,5 +774,72 @@ export function createGgPlugin(options, gg) {
         div.textContent = text;
         return div.innerHTML;
     }
+    /**
+     * Strip ANSI escape codes from text
+     * Removes all ANSI escape sequences like \x1b[...m
+     */
+    function stripAnsi(text) {
+        // Remove all ANSI escape codes
+        return text.replace(/\x1b\[[0-9;]*m/g, '');
+    }
+    /**
+     * Parse ANSI escape codes and convert to HTML with inline styles
+     * Supports:
+     * - 24-bit RGB: \x1b[38;2;r;g;bm (foreground), \x1b[48;2;r;g;bm (background)
+     * - Reset: \x1b[0m
+     */
+    function parseAnsiToHtml(text) {
+        // ANSI escape sequence regex
+        // Matches: \x1b[38;2;r;g;bm, \x1b[48;2;r;g;bm, \x1b[0m
+        const ansiRegex = /\x1b\[([0-9;]+)m/g;
+        let html = '';
+        let lastIndex = 0;
+        let currentFg = null;
+        let currentBg = null;
+        let match;
+        while ((match = ansiRegex.exec(text)) !== null) {
+            // Add text before this code (with current styling)
+            const textBefore = text.slice(lastIndex, match.index);
+            if (textBefore) {
+                html += wrapWithStyle(escapeHtml(textBefore), currentFg, currentBg);
+            }
+            // Parse the ANSI code
+            const code = match[1];
+            const parts = code.split(';').map(Number);
+            if (parts[0] === 0) {
+                // Reset
+                currentFg = null;
+                currentBg = null;
+            }
+            else if (parts[0] === 38 && parts[1] === 2 && parts.length >= 5) {
+                // Foreground RGB: 38;2;r;g;b
+                currentFg = `rgb(${parts[2]},${parts[3]},${parts[4]})`;
+            }
+            else if (parts[0] === 48 && parts[1] === 2 && parts.length >= 5) {
+                // Background RGB: 48;2;r;g;b
+                currentBg = `rgb(${parts[2]},${parts[3]},${parts[4]})`;
+            }
+            lastIndex = ansiRegex.lastIndex;
+        }
+        // Add remaining text
+        const remaining = text.slice(lastIndex);
+        if (remaining) {
+            html += wrapWithStyle(escapeHtml(remaining), currentFg, currentBg);
+        }
+        return html || escapeHtml(text);
+    }
+    /**
+     * Wrap text with inline color styles
+     */
+    function wrapWithStyle(text, fg, bg) {
+        if (!fg && !bg)
+            return text;
+        const styles = [];
+        if (fg)
+            styles.push(`color: ${fg}`);
+        if (bg)
+            styles.push(`background-color: ${bg}`);
+        return `<span style="${styles.join('; ')}">${text}</span>`;
+    }
     return plugin;
 }

package/dist/gg-call-sites-plugin.d.ts

@@ -0,0 +1,31 @@
+import type { Plugin } from 'vite';
+export interface GgCallSitesPluginOptions {
+    /**
+     * Pattern to strip from file paths to produce short callpoints.
+     * Should match up to and including the source root folder.
+     *
+     * Default: /.*?(\/(?:src|chunks)\/)/ which strips everything up to "src/" or "chunks/",
+     * matching the dev-mode behavior of gg().
+     *
+     * Example: "/Users/me/project/src/routes/+page.svelte" → "routes/+page.svelte"
+     */
+    srcRootPattern?: string;
+}
+/**
+ * Vite plugin that rewrites bare `gg(...)` calls to `gg.ns('callpoint', ...)`
+ * at build time. This gives each call site a unique namespace with zero runtime
+ * cost — no stack trace parsing needed.
+ *
+ * Works in both dev and prod. When the plugin is installed, `gg.ns()` is called
+ * with the callpoint baked in as a string literal. Without the plugin, gg()
+ * falls back to runtime stack parsing in dev and bare `gg:` in prod.
+ *
+ * @example
+ * // vite.config.ts
+ * import { ggCallSitesPlugin } from '@leftium/gg';
+ *
+ * export default defineConfig({
+ *   plugins: [ggCallSitesPlugin()]
+ * });
+ */
+export default function ggCallSitesPlugin(options?: GgCallSitesPluginOptions): Plugin;

package/dist/gg-call-sites-plugin.js

@@ -0,0 +1,244 @@
+/**
+ * Vite plugin that rewrites bare `gg(...)` calls to `gg.ns('callpoint', ...)`
+ * at build time. This gives each call site a unique namespace with zero runtime
+ * cost — no stack trace parsing needed.
+ *
+ * Works in both dev and prod. When the plugin is installed, `gg.ns()` is called
+ * with the callpoint baked in as a string literal. Without the plugin, gg()
+ * falls back to runtime stack parsing in dev and bare `gg:` in prod.
+ *
+ * @example
+ * // vite.config.ts
+ * import { ggCallSitesPlugin } from '@leftium/gg';
+ *
+ * export default defineConfig({
+ *   plugins: [ggCallSitesPlugin()]
+ * });
+ */
+export default function ggCallSitesPlugin(options = {}) {
+    const srcRootPattern = options.srcRootPattern ?? '.*?(/(?:src|chunks)/)';
+    const srcRootRegex = new RegExp(srcRootPattern, 'i');
+    return {
+        name: 'gg-call-sites',
+        config() {
+            // Set a compile-time flag so gg() can detect the plugin is installed.
+            // Vite replaces all occurrences of __GG_TAG_PLUGIN__ with true at build time,
+            // before any code executes — no ordering issues.
+            return {
+                define: {
+                    __GG_TAG_PLUGIN__: 'true'
+                }
+            };
+        },
+        transform(code, id) {
+            // Only process JS/TS/Svelte files
+            if (!/\.(js|ts|svelte|jsx|tsx|mjs|mts)(\?.*)?$/.test(id))
+                return null;
+            // Quick bail: no gg calls in this file
+            if (!code.includes('gg('))
+                return null;
+            // Don't transform gg's own source files
+            if (id.includes('/lib/gg.') || id.includes('/lib/debug'))
+                return null;
+            // Build the short callpoint from the file path
+            // e.g. "/Users/me/project/src/routes/+page.svelte" → "routes/+page.svelte"
+            const shortPath = id.replace(srcRootRegex, '');
+            return transformGgCalls(code, shortPath);
+        }
+    };
+}
+/**
+ * Find the enclosing function name for a given position in source code.
+ * Scans backwards from the position looking for function/method declarations.
+ */
+function findEnclosingFunction(code, position) {
+    // Look backwards from the gg( call for the nearest function declaration
+    const before = code.slice(0, position);
+    // Try several patterns, take the closest (last) match
+    // Named function: function handleClick(
+    // Arrow in variable: const handleClick = (...) =>
+    // Arrow in variable: let handleClick = (...) =>
+    // Method shorthand: handleClick() {
+    // Method: handleClick: function(
+    // Class method: async handleClick(
+    const patterns = [
+        // function declarations: function foo(
+        /function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/g,
+        // const/let/var assignment to arrow or function: const foo =
+        /(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=/g,
+        // object method shorthand: foo() { or async foo() {
+        /(?:async\s+)?([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\([^)]*\)\s*\{/g,
+        // object property function: foo: function
+        /([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:\s*(?:async\s+)?function/g
+    ];
+    let closestName = '';
+    let closestPos = -1;
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(before)) !== null) {
+            const name = match[1];
+            // Skip common false positives
+            if ([
+                'if',
+                'for',
+                'while',
+                'switch',
+                'catch',
+                'return',
+                'import',
+                'export',
+                'from',
+                'new',
+                'typeof',
+                'instanceof',
+                'void',
+                'delete',
+                'throw',
+                'case',
+                'else',
+                'in',
+                'of',
+                'do',
+                'try',
+                'class',
+                'super',
+                'this',
+                'with',
+                'yield',
+                'await',
+                'debugger',
+                'default'
+            ].includes(name)) {
+                continue;
+            }
+            if (match.index > closestPos) {
+                closestPos = match.index;
+                closestName = name;
+            }
+        }
+    }
+    return closestName;
+}
+/**
+ * Transform gg() calls in source code to gg.ns('callpoint', ...) calls.
+ *
+ * Handles:
+ * - bare gg(...) → gg.ns('callpoint', ...)
+ * - gg.ns(...) → left untouched (user-specified namespace)
+ * - gg.enable, gg.disable, gg.clearPersist, gg._onLog → left untouched
+ * - gg inside strings and comments → left untouched
+ */
+function transformGgCalls(code, shortPath) {
+    // Match gg( that is:
+    // - not preceded by a dot (would be obj.gg() — not our function)
+    // - not preceded by a word char (would be dogg() or something)
+    // - not followed by a dot before the paren (gg.ns, gg.enable, etc.)
+    //
+    // We use a manual scan approach to correctly handle strings and comments.
+    const result = [];
+    let lastIndex = 0;
+    let modified = false;
+    // States for string/comment tracking
+    let i = 0;
+    while (i < code.length) {
+        // Skip single-line comments
+        if (code[i] === '/' && code[i + 1] === '/') {
+            const end = code.indexOf('\n', i);
+            i = end === -1 ? code.length : end + 1;
+            continue;
+        }
+        // Skip multi-line comments
+        if (code[i] === '/' && code[i + 1] === '*') {
+            const end = code.indexOf('*/', i + 2);
+            i = end === -1 ? code.length : end + 2;
+            continue;
+        }
+        // Skip template literals (backticks)
+        if (code[i] === '`') {
+            i++;
+            let depth = 0;
+            while (i < code.length) {
+                if (code[i] === '\\') {
+                    i += 2;
+                    continue;
+                }
+                if (code[i] === '$' && code[i + 1] === '{') {
+                    depth++;
+                    i += 2;
+                    continue;
+                }
+                if (code[i] === '}' && depth > 0) {
+                    depth--;
+                    i++;
+                    continue;
+                }
+                if (code[i] === '`' && depth === 0) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        // Skip strings (single and double quotes)
+        if (code[i] === '"' || code[i] === "'") {
+            const quote = code[i];
+            i++;
+            while (i < code.length) {
+                if (code[i] === '\\') {
+                    i += 2;
+                    continue;
+                }
+                if (code[i] === quote) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        // Look for 'gg(' pattern
+        if (code[i] === 'g' && code[i + 1] === 'g' && code[i + 2] === '(') {
+            // Check preceding character: must not be a word char or dot
+            const prevChar = i > 0 ? code[i - 1] : '';
+            if (prevChar && /[a-zA-Z0-9_$.]/.test(prevChar)) {
+                i++;
+                continue;
+            }
+            // Check it's not gg.something (gg.ns, gg.enable, etc.)
+            // At this point we know code[i..i+2] is "gg(" — it's a bare call
+            // Find the enclosing function
+            const fnName = findEnclosingFunction(code, i);
+            const callpoint = `${shortPath}${fnName ? `@${fnName}` : ''}`;
+            const escaped = callpoint.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+            // Emit everything before this match
+            result.push(code.slice(lastIndex, i));
+            // Replace gg( with gg.ns('callpoint',
+            // Need to handle gg() with no args → gg.ns('callpoint')
+            // and gg(x) → gg.ns('callpoint', x)
+            // Peek ahead to check if it's gg() with no args
+            const afterParen = code.indexOf(')', i + 3);
+            const betweenParens = code.slice(i + 3, afterParen);
+            const isNoArgs = betweenParens.trim() === '';
+            if (isNoArgs && afterParen !== -1 && !betweenParens.includes('(')) {
+                // gg() → gg.ns('callpoint')
+                result.push(`gg.ns('${escaped}')`);
+                lastIndex = afterParen + 1;
+                i = afterParen + 1;
+            }
+            else {
+                // gg(args...) → gg.ns('callpoint', args...)
+                result.push(`gg.ns('${escaped}', `);
+                lastIndex = i + 3; // skip past "gg("
+                i = i + 3;
+            }
+            modified = true;
+            continue;
+        }
+        i++;
+    }
+    if (!modified)
+        return null;
+    result.push(code.slice(lastIndex));
+    return { code: result.join(''), map: null };
+}

package/dist/gg.d.ts

@@ -23,8 +23,68 @@ export declare namespace gg {
     var enable: (namespaces: string) => void;
     var clearPersist: () => void;
 }
+/**
+ * ANSI Color Helpers for gg()
+ *
+ * Create reusable color schemes with foreground (fg) and background (bg) colors.
+ * Works in both native console and Eruda plugin.
+ *
+ * @example
+ * // Method chaining (order doesn't matter)
+ * gg(fg('white').bg('red')`Critical error!`);
+ * gg(bg('green').fg('white')`Success!`);
+ *
+ * @example
+ * // Define color schemes once, reuse everywhere
+ * const input = fg('blue').bg('yellow');
+ * const transcript = bg('green').fg('white');
+ * const error = fg('white').bg('red');
+ *
+ * gg(input`User said: hello`);
+ * gg(transcript`AI responded: hi`);
+ * gg(error`Something broke!`);
+ *
+ * @example
+ * // Mix colored and normal text inline
+ * gg(fg('red')`Error: ` + bg('yellow')`warning` + ' normal text');
+ *
+ * @example
+ * // Custom colors (hex, rgb, or named)
+ * gg(fg('#ff6347').bg('#98fb98')`Custom colors`);
+ *
+ * @example
+ * // Just foreground or background
+ * gg(fg('cyan')`Cyan text`);
+ * gg(bg('magenta')`Magenta background`);
+ */
+type ColorTagFunction = (strings: TemplateStringsArray, ...values: unknown[]) => string;
+interface ChainableColorFn extends ColorTagFunction {
+    fg: (color: string) => ChainableColorFn;
+    bg: (color: string) => ChainableColorFn;
+}
+/**
+ * Foreground (text) color helper
+ * Can be used directly or chained with .bg()
+ *
+ * @param color - Named color, hex (#rrggbb), or rgb(r,g,b)
+ * @example
+ * gg(fg('red')`Error`);
+ * gg(fg('white').bg('red')`Critical!`);
+ */
+export declare function fg(color: string): ChainableColorFn;
+/**
+ * Background color helper
+ * Can be used directly or chained with .fg()
+ *
+ * @param color - Named color, hex (#rrggbb), or rgb(r,g,b)
+ * @example
+ * gg(bg('yellow')`Warning`);
+ * gg(bg('green').fg('white')`Success!`);
+ */
+export declare function bg(color: string): ChainableColorFn;
 export declare namespace gg {
     let _onLog: OnLogCallback | null;
+    let ns: (nsLabel: string, ...args: unknown[]) => unknown;
 }
 /**
  * Run gg diagnostics and log configuration status

package/dist/gg.js

@@ -1,6 +1,7 @@
 import debugFactory from './debug.js';
 import ErrorStackParser from 'error-stack-parser';
 import { BROWSER, DEV } from 'esm-env';
+const _ggCallSitesPlugin = typeof __GG_TAG_PLUGIN__ !== 'undefined' ? __GG_TAG_PLUGIN__ : false;
 /**
  * Creates a debug instance with custom formatArgs to add namespace padding
  * Padding is done at format time, not in the namespace itself, to keep colors stable
@@ -185,9 +186,12 @@ export function gg(...args) {
     let url = '';
     let stack = [];
     let namespace = 'gg:';
-    // In development: calculate detailed callpoint information
-    // In production: skip expensive stack parsing and use simple namespace
-    if (DEV) {
+    // When ggCallSitesPlugin is installed, all bare gg() calls are rewritten to gg.ns()
+    // at build time, so this code path only runs for un-transformed calls.
+    // Skip expensive stack parsing if the plugin is handling callpoints.
+    // In development without plugin: calculate detailed callpoint information
+    // In production without plugin: skip expensive stack parsing and use simple namespace
+    if (DEV && !_ggCallSitesPlugin) {
         // Ignore first stack frame, which is always the call to gg() itself.
         stack = ErrorStackParser.parse(new Error()).splice(1);
         // Example: http://localhost:5173/src/routes/+page.svelte
@@ -255,6 +259,71 @@ export function gg(...args) {
     }
     return returnValue;
 }
+/**
+ * gg.ns() - Log with an explicit namespace (callpoint label).
+ *
+ * In production builds, the ggCallSitesPlugin Vite plugin rewrites bare gg() calls
+ * to gg.ns('callpoint', ...) so each call site gets a unique namespace even
+ * after minification. Users can also call gg.ns() directly to set a meaningful
+ * label that survives across builds.
+ *
+ * @param nsLabel - The namespace label (appears as gg:<nsLabel> in output)
+ * @param args - Same arguments as gg()
+ * @returns Same as gg() - the first arg, or call-site info if no args
+ *
+ * @example
+ * gg.ns("auth", "login failed")   // logs under namespace "gg:auth"
+ * gg.ns("cart", item, quantity)    // logs under namespace "gg:cart"
+ */
+gg.ns = function (nsLabel, ...args) {
+    if (!ggConfig.enabled || isCloudflareWorker()) {
+        return args.length ? args[0] : { url: '', stack: [] };
+    }
+    const namespace = `gg:${nsLabel}`;
+    if (nsLabel.length < 80 && nsLabel.length > maxCallpointLength) {
+        maxCallpointLength = nsLabel.length;
+    }
+    const ggLogFunction = namespaceToLogFunction.get(namespace) ||
+        namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
+    // Prepare args for logging
+    let logArgs;
+    let returnValue;
+    if (!args.length) {
+        logArgs = [`    📝 ${nsLabel}`];
+        returnValue = { fileName: '', functionName: '', url: '', stack: [] };
+    }
+    else if (args.length === 1) {
+        logArgs = [args[0]];
+        returnValue = args[0];
+    }
+    else {
+        logArgs = [args[0], ...args.slice(1)];
+        returnValue = args[0];
+    }
+    // Log to console via debug
+    if (logArgs.length === 1) {
+        ggLogFunction(logArgs[0]);
+    }
+    else {
+        ggLogFunction(logArgs[0], ...logArgs.slice(1));
+    }
+    // Call capture hook if registered (for Eruda plugin)
+    const entry = {
+        namespace,
+        color: ggLogFunction.color,
+        diff: ggLogFunction.diff || 0,
+        message: logArgs.length === 1 ? String(logArgs[0]) : logArgs.map(String).join(' '),
+        args: logArgs,
+        timestamp: Date.now()
+    };
+    if (_onLogCallback) {
+        _onLogCallback(entry);
+    }
+    else {
+        earlyLogBuffer.push(entry);
+    }
+    return returnValue;
+};
 gg.disable = isCloudflareWorker() ? () => { } : debugFactory.disable;
 gg.enable = isCloudflareWorker() ? () => { } : debugFactory.enable;
 /**
@@ -272,6 +341,120 @@ gg.clearPersist = () => {
         }
     }
 };
+/**
+ * Parse color string to RGB values
+ * Accepts: named colors, hex (#rgb, #rrggbb), rgb(r,g,b), rgba(r,g,b,a)
+ */
+function parseColor(color) {
+    // Named colors map (basic ANSI colors + common web colors)
+    const namedColors = {
+        black: '#000000',
+        red: '#ff0000',
+        green: '#00ff00',
+        yellow: '#ffff00',
+        blue: '#0000ff',
+        magenta: '#ff00ff',
+        cyan: '#00ffff',
+        white: '#ffffff',
+        // Bright variants
+        brightBlack: '#808080',
+        brightRed: '#ff6666',
+        brightGreen: '#66ff66',
+        brightYellow: '#ffff66',
+        brightBlue: '#6666ff',
+        brightMagenta: '#ff66ff',
+        brightCyan: '#66ffff',
+        brightWhite: '#ffffff',
+        // Common aliases
+        gray: '#808080',
+        grey: '#808080',
+        orange: '#ffa500',
+        purple: '#800080',
+        pink: '#ffc0cb'
+    };
+    // Check named colors first
+    const normalized = color.toLowerCase().trim();
+    if (namedColors[normalized]) {
+        color = namedColors[normalized];
+    }
+    // Parse hex color
+    const hexMatch = color.match(/^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i);
+    if (hexMatch) {
+        return {
+            r: parseInt(hexMatch[1], 16),
+            g: parseInt(hexMatch[2], 16),
+            b: parseInt(hexMatch[3], 16)
+        };
+    }
+    // Parse short hex (#rgb)
+    const shortHexMatch = color.match(/^#?([a-f\d])([a-f\d])([a-f\d])$/i);
+    if (shortHexMatch) {
+        return {
+            r: parseInt(shortHexMatch[1] + shortHexMatch[1], 16),
+            g: parseInt(shortHexMatch[2] + shortHexMatch[2], 16),
+            b: parseInt(shortHexMatch[3] + shortHexMatch[3], 16)
+        };
+    }
+    // Parse rgb(r,g,b) or rgba(r,g,b,a)
+    const rgbMatch = color.match(/rgba?\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i);
+    if (rgbMatch) {
+        return {
+            r: parseInt(rgbMatch[1]),
+            g: parseInt(rgbMatch[2]),
+            b: parseInt(rgbMatch[3])
+        };
+    }
+    return null;
+}
+/**
+ * Internal helper to create chainable color function with method chaining
+ */
+function createColorFunction(fgCode = '', bgCode = '') {
+    const tagFn = function (strings, ...values) {
+        const text = strings.reduce((acc, str, i) => acc + str + (values[i] !== undefined ? String(values[i]) : ''), '');
+        return fgCode + bgCode + text + '\x1b[0m';
+    };
+    // Add method chaining
+    tagFn.fg = (color) => {
+        const rgb = parseColor(color);
+        const newFgCode = rgb ? `\x1b[38;2;${rgb.r};${rgb.g};${rgb.b}m` : '';
+        return createColorFunction(newFgCode, bgCode);
+    };
+    tagFn.bg = (color) => {
+        const rgb = parseColor(color);
+        const newBgCode = rgb ? `\x1b[48;2;${rgb.r};${rgb.g};${rgb.b}m` : '';
+        return createColorFunction(fgCode, newBgCode);
+    };
+    return tagFn;
+}
+/**
+ * Foreground (text) color helper
+ * Can be used directly or chained with .bg()
+ *
+ * @param color - Named color, hex (#rrggbb), or rgb(r,g,b)
+ * @example
+ * gg(fg('red')`Error`);
+ * gg(fg('white').bg('red')`Critical!`);
+ */
+export function fg(color) {
+    const rgb = parseColor(color);
+    const fgCode = rgb ? `\x1b[38;2;${rgb.r};${rgb.g};${rgb.b}m` : '';
+    return createColorFunction(fgCode, '');
+}
+/**
+ * Background color helper
+ * Can be used directly or chained with .fg()
+ *
+ * @param color - Named color, hex (#rrggbb), or rgb(r,g,b)
+ * @example
+ * gg(bg('yellow')`Warning`);
+ * gg(bg('green').fg('white')`Success!`);
+ */
+export function bg(color) {
+    const rgb = parseColor(color);
+    const bgCode = rgb ? `\x1b[48;2;${rgb.r};${rgb.g};${rgb.b}m` : '';
+    return createColorFunction('', bgCode);
+}
 /**
  * Hook for capturing gg() output (used by Eruda plugin)
  * Set this to a callback function to receive log entries
@@ -335,10 +518,6 @@ export async function runGgDiagnostics() {
     if (BROWSER) {
         const hint = makeHint(!ggLogTest.enabled, " (Try `localStorage.debug = 'gg:*'`)");
         message(`${checkbox(ggLogTest.enabled)} localStorage.debug: ${localStorage?.debug}${hint}`);
-        if (DEV) {
-            const { status } = await fetch('/__open-in-editor?file=+');
-            message(makeHint(status === 222, `✅ (optional) open-in-editor vite plugin detected! (status code: ${status})`, `⚠️ (optional) open-in-editor vite plugin not detected. (status code: ${status}.) Add plugin in vite.config.ts`));
-        }
     }
     else {
         const hint = makeHint(!ggLogTest.enabled, ' (Try `DEBUG=gg:* npm dev`)');
@@ -347,6 +526,12 @@ export async function runGgDiagnostics() {
         }
         message(`${checkbox(ggLogTest.enabled)} DEBUG env variable: ${process?.env?.DEBUG}${hint}`);
     }
+    // Optional plugin diagnostics listed last
+    message(makeHint(_ggCallSitesPlugin, `✅ (optional) gg-call-sites vite plugin detected! Call-site namespaces baked in at build time.`, `⚠️ (optional) gg-call-sites vite plugin not detected. Add ggCallSitesPlugin() to vite.config.ts for build-time call-site namespaces (needed for useful namespaces in prod, faster/more reliable in dev)`));
+    if (BROWSER && DEV) {
+        const { status } = await fetch('/__open-in-editor?file=+');
+        message(makeHint(status === 222, `✅ (optional) open-in-editor vite plugin detected! (status code: ${status}) Clickable links open source files in editor.`, `⚠️ (optional) open-in-editor vite plugin not detected. (status code: ${status}) Add openInEditorPlugin() to vite.config.ts for clickable links that open source files in editor`));
+    }
     // Use plain console.log for diagnostics - appears in Eruda's Console tab
     console.log(ggMessage);
     // Reset namespace width after configuration check

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-import { gg } from './gg.js';
+import { gg, fg, bg } from './gg.js';
 import openInEditorPlugin from './open-in-editor.js';
-export { gg, openInEditorPlugin };
+import ggCallSitesPlugin from './gg-call-sites-plugin.js';
+export { gg, fg, bg, openInEditorPlugin, ggCallSitesPlugin };

package/dist/index.js

@@ -1,4 +1,5 @@
 // Reexport your entry components here
-import { gg } from './gg.js';
+import { gg, fg, bg } from './gg.js';
 import openInEditorPlugin from './open-in-editor.js';
-export { gg, openInEditorPlugin };
+import ggCallSitesPlugin from './gg-call-sites-plugin.js';
+export { gg, fg, bg, openInEditorPlugin, ggCallSitesPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leftium/gg",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Leftium/gg.git"