@leftium/gg 0.0.26 → 0.0.28

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/loader.js

@@ -62,6 +62,17 @@ export async function loadEruda(options) {
         // Dynamic import of Eruda
         const erudaModule = await import('eruda');
         const eruda = erudaModule.default;
+        // Clear Eruda position state to prevent icon from being stuck in wrong position
+        // Eruda stores draggable icon position in localStorage which can get corrupted
+        // This ensures the icon always appears in the default bottom-right corner
+        try {
+            // Eruda uses keys like 'eruda-entry-button' for position state
+            const positionKeys = ['eruda-entry-button', 'eruda-position'];
+            positionKeys.forEach((key) => localStorage.removeItem(key));
+        }
+        catch {
+            // localStorage might not be available
+        }
         // Initialize Eruda
         eruda.init({
             ...options.erudaOptions,
@@ -81,13 +92,15 @@ export async function loadEruda(options) {
         }
         // Register gg plugin
         // Import gg and pass it to the plugin directly
-        const { gg } = await import('../gg.js');
+        const { gg, runGgDiagnostics } = await import('../gg.js');
         const { createGgPlugin } = await import('./plugin.js');
         const ggPlugin = createGgPlugin(options, gg);
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         eruda.add(ggPlugin);
         // Make GG tab the default selected tab
         eruda.show('GG');
+        // Run diagnostics after Eruda is ready so they appear in Console tab
+        await runGgDiagnostics();
     }
     catch (error) {
         console.error('[gg] Failed to load Eruda:', error);

package/dist/eruda/plugin.js

@@ -172,29 +172,37 @@ export function createGgPlugin(options, gg) {
     }
     function gridColumns() {
         const ns = nsColWidth !== null ? `${nsColWidth}px` : 'auto';
-        if (filterExpanded) {
-            // [×] | diff | ns | handle | content
-            return `24px auto ${ns} 4px 1fr`;
-        }
-        else {
-            // diff | ns | handle | content
-            return `auto ${ns} 4px 1fr`;
-        }
+        // diff | ns | handle | content (× is now inside ns)
+        return `auto ${ns} 4px 1fr`;
     }
     function buildHTML() {
         return `
 			<style>
-				.gg-log-grid {
-					display: grid;
-					grid-template-columns: ${gridColumns()};
-					column-gap: 0;
-					align-items: start !important;
-				}
-				.gg-log-grid > * {
-					min-width: 0;
-					border-top: 1px solid rgba(0,0,0,0.05);
-					align-self: start !important;
-				}
+			.gg-log-grid {
+				display: grid;
+				grid-template-columns: ${gridColumns()};
+				column-gap: 0;
+				align-items: start !important;
+			}
+			/* Desktop: hide wrapper divs, show direct children */
+			.gg-log-entry {
+				display: contents;
+			}
+			.gg-log-header {
+				display: contents;
+			}
+			.gg-log-diff,
+			.gg-log-ns,
+			.gg-log-handle,
+			.gg-log-content {
+				min-width: 0;
+				align-self: start !important;
+				border-top: 1px solid rgba(0,0,0,0.05);
+			}
+			.gg-details {
+				grid-column: 1 / -1;
+				border-top: none;
+			}
 				.gg-details {
 					align-self: stretch !important;
 					border-bottom: none;
@@ -234,19 +242,15 @@ export function createGgPlugin(options, gg) {
 					word-break: break-word;
 					padding: 4px 0;
 				}
-				.gg-row-filter {
-					text-align: center;
-					padding: 4px 8px 4px 0;
-					cursor: pointer;
-					user-select: none;
-					opacity: 0.6;
-					font-size: 14px;
-					align-self: start;
-				}
-				.gg-row-filter:hover {
-					opacity: 1;
-					background: rgba(0,0,0,0.05);
-				}
+			/* Make header clickable for filtering when filters are expanded */
+			.gg-log-header.clickable {
+				cursor: pointer;
+			}
+			/* Desktop: highlight child elements since header has display: contents */
+			.gg-log-header.clickable:hover .gg-log-diff,
+			.gg-log-header.clickable:hover .gg-log-ns {
+				background: rgba(0,0,0,0.05);
+			}
 				.gg-filter-panel {
 					background: #f5f5f5;
 					padding: 10px;
@@ -262,7 +266,7 @@ export function createGgPlugin(options, gg) {
 					width: 100%;
 					padding: 4px 8px;
 					font-family: monospace;
-					font-size: 12px;
+					font-size: 16px;
 					margin-bottom: 8px;
 				}
 				.gg-filter-checkboxes {
@@ -281,16 +285,125 @@ export function createGgPlugin(options, gg) {
 					font-family: monospace;
 					white-space: nowrap;
 				}
+				/* Mobile responsive styles */
+				.gg-toolbar {
+					display: flex;
+					align-items: center;
+					gap: 8px;
+					margin-bottom: 8px;
+					flex-shrink: 0;
+					overflow-x: auto;
+					-webkit-overflow-scrolling: touch;
+				}
+				.gg-toolbar button {
+					padding: 4px 10px;
+					cursor: pointer;
+					flex-shrink: 0;
+				}
+				.gg-btn-text {
+					display: inline;
+				}
+				.gg-btn-icon {
+					display: none;
+				}
+				@media (max-width: 640px) {
+					.gg-btn-text {
+						display: none;
+					}
+					.gg-btn-icon {
+						display: inline;
+					}
+					.gg-toolbar button {
+						padding: 4px 8px;
+						min-width: 32px;
+					}
+					.gg-filter-btn {
+						font-family: monospace;
+						font-size: 12px;
+					}
+					/* Stack log entries vertically on mobile */
+					.gg-log-grid {
+						display: block;
+					}
+					.gg-log-entry {
+						display: block;
+						padding: 8px 0;
+					}
+					/* Remove double borders on mobile - only border on entry wrapper */
+					.gg-log-entry:not(:first-child) {
+						border-top: 1px solid rgba(0,0,0,0.05);
+					}
+				.gg-log-diff,
+				.gg-log-ns,
+				.gg-log-handle,
+				.gg-log-content,
+				.gg-details {
+					border-top: none !important;
+				}
+			.gg-log-header {
+				display: flex;
+				align-items: center;
+				gap: 8px;
+				margin-bottom: 4px;
+				min-width: 0;
+			}
+			/* Mobile: hover on container since it's not display: contents */
+			.gg-log-header.clickable {
+				padding: 2px 0;
+			}
+			.gg-log-header.clickable:hover {
+				background: rgba(0,0,0,0.05);
+			}
+				/* Override desktop child hover on mobile */
+				.gg-log-header.clickable:hover .gg-log-diff,
+				.gg-log-header.clickable:hover .gg-log-ns {
+					background: transparent;
+				}
+				.gg-log-diff {
+					padding: 0;
+					text-align: left;
+					flex-shrink: 0;
+					white-space: nowrap;
+				}
+				.gg-log-ns {
+					padding: 0;
+					flex: 1;
+					min-width: 0;
+					overflow: hidden;
+					text-overflow: ellipsis;
+					white-space: nowrap;
+				}
+				.gg-log-handle {
+					display: none;
+				}
+				.gg-log-content {
+					padding: 0;
+					padding-left: 0;
+				}
+					.gg-details {
+						margin-top: 4px;
+					}
+				}
 			</style>
-			<div class="eruda-gg" style="padding: 10px; height: 100%; display: flex; flex-direction: column; font-size: 14px;">
-				<div style="display: flex; align-items: center; gap: 8px; margin-bottom: 8px; flex-shrink: 0;">
-					<button class="gg-clear-btn" style="padding: 4px 10px; cursor: pointer;">Clear</button>
-					<button class="gg-copy-btn" style="padding: 4px 10px; cursor: pointer;">Copy</button>
-					<button class="gg-filter-btn" style="padding: 4px 10px; cursor: pointer; flex: 1; min-width: 0; text-align: left; font-family: monospace; font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;">⚙️ Filters: <span class="gg-filter-summary"></span></button>
-					<span class="gg-count" style="opacity: 0.6; white-space: nowrap;"></span>
-				</div>
+		<div class="eruda-gg" style="padding: 10px; height: 100%; display: flex; flex-direction: column; font-size: 14px; touch-action: none; overscroll-behavior: contain;">
+			<div class="gg-toolbar">
+				<button class="gg-copy-btn">
+					<span class="gg-btn-text">Copy</span>
+					<span class="gg-btn-icon" title="Copy">📋</span>
+				</button>
+			<button class="gg-filter-btn" style="text-align: left; white-space: nowrap;">
+				<span class="gg-btn-text">Namespaces: </span>
+				<span class="gg-btn-icon">NS: </span>
+				<span class="gg-filter-summary"></span>
+			</button>
+				<span class="gg-count" style="opacity: 0.6; white-space: nowrap; flex: 1; text-align: right;"></span>
+				<button class="gg-clear-btn">
+					<span class="gg-btn-text">Clear</span>
+					<span class="gg-btn-icon" title="Clear">⊘</span>
+				</button>
+			</div>
 				<div class="gg-filter-panel"></div>
-				<div class="gg-log-container" style="flex: 1; overflow-y: auto; font-family: monospace; font-size: 12px;"></div>
+				<div class="gg-log-container" style="flex: 1; overflow-y: auto; font-family: monospace; font-size: 12px; touch-action: pan-y; overscroll-behavior: contain;"></div>
 			</div>
 		`;
     }
@@ -340,6 +453,27 @@ export function createGgPlugin(options, gg) {
         // Wire up checkboxes
         filterPanel.addEventListener('change', (e) => {
             const target = e.target;
+            // Handle ALL checkbox
+            if (target.classList.contains('gg-all-checkbox')) {
+                const allNamespaces = getAllCapturedNamespaces();
+                if (target.checked) {
+                    // Select all
+                    filterPattern = 'gg:*';
+                    enabledNamespaces.clear();
+                    allNamespaces.forEach((ns) => enabledNamespaces.add(ns));
+                }
+                else {
+                    // Deselect all
+                    const exclusions = allNamespaces.map((ns) => `-${ns}`).join(',');
+                    filterPattern = `gg:*,${exclusions}`;
+                    enabledNamespaces.clear();
+                }
+                localStorage.setItem('debug', filterPattern);
+                renderFilterUI();
+                renderLogs();
+                return;
+            }
+            // Handle individual namespace checkboxes
             if (target.classList.contains('gg-ns-checkbox')) {
                 const namespace = target.getAttribute('data-namespace');
                 if (!namespace)
@@ -355,11 +489,13 @@ export function createGgPlugin(options, gg) {
     function renderFilterUI() {
         if (!$el)
             return;
-        // Update button summary
+        const allNamespaces = getAllCapturedNamespaces();
+        const enabledCount = enabledNamespaces.size;
+        const totalCount = allNamespaces.length;
+        // Update button summary with count of enabled namespaces
         const filterSummary = $el.find('.gg-filter-summary').get(0);
         if (filterSummary) {
-            const summary = filterPattern || 'gg:*';
-            filterSummary.textContent = summary;
+            filterSummary.textContent = `${enabledCount}/${totalCount}`;
         }
         // Update panel
         const filterPanel = $el.find('.gg-filter-panel').get(0);
@@ -374,32 +510,37 @@ export function createGgPlugin(options, gg) {
             const effectivePattern = filterPattern || 'gg:*';
             let checkboxesHTML = '';
             if (simple && allNamespaces.length > 0) {
+                const allChecked = enabledCount === totalCount;
                 checkboxesHTML = `
-					<div class="gg-filter-checkboxes">
-						${allNamespaces
+				<div class="gg-filter-checkboxes">
+					<label class="gg-filter-checkbox" style="font-weight: bold;">
+						<input type="checkbox" class="gg-all-checkbox" ${allChecked ? 'checked' : ''}>
+						<span>ALL</span>
+					</label>
+					${allNamespaces
                     .map((ns) => {
                     // Check if namespace matches the current pattern
                     const checked = namespaceMatchesPattern(ns, effectivePattern);
                     return `
-								<label class="gg-filter-checkbox">
-									<input type="checkbox" class="gg-ns-checkbox" data-namespace="${escapeHtml(ns)}" ${checked ? 'checked' : ''}>
-									<span>${escapeHtml(ns)}</span>
-								</label>
-							`;
+							<label class="gg-filter-checkbox">
+								<input type="checkbox" class="gg-ns-checkbox" data-namespace="${escapeHtml(ns)}" ${checked ? 'checked' : ''}>
+								<span>${escapeHtml(ns)}</span>
+							</label>
+						`;
                 })
                     .join('')}
-					</div>
-				`;
+				</div>
+			`;
             }
             else if (!simple) {
                 checkboxesHTML = `<div style="opacity: 0.6; font-size: 11px; margin: 8px 0;">⚠️ Complex pattern - edit manually (quick filters disabled)</div>`;
             }
             filterPanel.innerHTML = `
-				<div style="margin-bottom: 8px;">
-					<input type="text" class="gg-filter-pattern" value="${escapeHtml(filterPattern)}" placeholder="gg:*" style="width: 100%;">
-				</div>
-				${checkboxesHTML}
-			`;
+			<div style="margin-bottom: 8px;">
+				<input type="text" class="gg-filter-pattern" value="${escapeHtml(filterPattern)}" placeholder="gg:*" style="width: 100%;">
+			</div>
+			${checkboxesHTML}
+		`;
         }
         else {
             // Hide panel
@@ -429,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}`;
@@ -470,9 +612,12 @@ export function createGgPlugin(options, gg) {
                 }
                 return;
             }
-            // Handle row filter button
-            if (target?.classList?.contains('gg-row-filter')) {
-                const namespace = target.getAttribute('data-namespace');
+            // Handle clickable header (when filters expanded)
+            // Skip if clicking on resize handle
+            if (!target?.classList?.contains('gg-log-handle') &&
+                target?.closest('.gg-log-header.clickable')) {
+                const header = target.closest('.gg-log-header.clickable');
+                const namespace = header.getAttribute('data-namespace');
                 if (!namespace)
                     return;
                 // Toggle this namespace off
@@ -567,25 +712,40 @@ export function createGgPlugin(options, gg) {
                         const jsonStr = escapeHtml(JSON.stringify(arg, null, 2));
                         const uniqueId = `${index}-${argIdx}`;
                         // Store details separately to render after the row
-                        detailsHTML += `<div class="gg-details" data-index="${uniqueId}" style="display: none; grid-column: 1 / -1; margin: 4px 0 8px 0; padding: 8px; background: #f8f8f8; border-left: 3px solid ${color}; font-size: 11px; overflow-x: auto;"><pre style="margin: 0;">${jsonStr}</pre></div>`;
+                        detailsHTML += `<div class="gg-details" data-index="${uniqueId}" style="display: none; margin: 4px 0 8px 0; padding: 8px; background: #f8f8f8; border-left: 3px solid ${color}; font-size: 11px; overflow-x: auto;"><pre style="margin: 0;">${jsonStr}</pre></div>`;
                         return `<span style="color: #888; cursor: pointer; text-decoration: underline;" class="gg-expand" data-index="${uniqueId}">${preview}</span>`;
                     }
                     else {
-                        return `<span>${escapeHtml(String(arg))}</span>`;
+                        // Parse ANSI codes first, then convert URLs to clickable links
+                        const argStr = String(arg);
+                        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(' ');
             }
-            // Add filter button if expanded
-            const filterBtn = filterExpanded
-                ? `<div class="gg-row-filter" data-namespace="${ns}" title="Hide this namespace">×</div>`
+            // Make header clickable when filters expanded
+            const headerClass = filterExpanded ? 'gg-log-header clickable' : 'gg-log-header';
+            const headerAttrs = filterExpanded
+                ? ` data-namespace="${ns}" title="Click to hide this namespace"`
                 : '';
-            return (filterBtn +
-                `<div class="gg-log-diff" style="color: ${color};">${diff}</div>` +
+            // Add × at start of diff when filters expanded (bold, darker)
+            const filterIcon = filterExpanded
+                ? '<span style="font-weight: bold; color: #000; opacity: 0.6;">× </span>'
+                : '';
+            // Desktop: grid layout, Mobile: stacked layout
+            return (`<div class="gg-log-entry">` +
+                `<div class="${headerClass}"${headerAttrs}>` +
+                `<div class="gg-log-diff" style="color: ${color};">${filterIcon}${diff}</div>` +
                 `<div class="gg-log-ns" style="color: ${color};">${ns}</div>` +
                 `<div class="gg-log-handle"></div>` +
+                `</div>` +
                 `<div class="gg-log-content">${argsHTML}</div>` +
-                detailsHTML);
+                detailsHTML +
+                `</div>`);
         })
             .join('')}</div>`;
         logContainer.html(logsHTML);
@@ -614,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-tag-plugin.d.ts

@@ -0,0 +1,31 @@
+import type { Plugin } from 'vite';
+export interface GgTagPluginOptions {
+    /**
+     * 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 { ggTagPlugin } from '@leftium/gg';
+ *
+ * export default defineConfig({
+ *   plugins: [ggTagPlugin()]
+ * });
+ */
+export default function ggTagPlugin(options?: GgTagPluginOptions): Plugin;

package/dist/gg-tag-plugin.js

@@ -0,0 +1,234 @@
+/**
+ * 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 { ggTagPlugin } from '@leftium/gg';
+ *
+ * export default defineConfig({
+ *   plugins: [ggTagPlugin()]
+ * });
+ */
+export default function ggTagPlugin(options = {}) {
+    const srcRootPattern = options.srcRootPattern ?? '.*?(/(?:src|chunks)/)';
+    const srcRootRegex = new RegExp(srcRootPattern, 'i');
+    return {
+        name: 'gg-tag',
+        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

@@ -22,6 +22,73 @@ export declare namespace gg {
     var disable: () => void;
     var enable: (namespaces: string) => void;
     var clearPersist: () => void;
-    var _onLog: OnLogCallback | null;
 }
+/**
+ * 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
+ * Can be called immediately or delayed (e.g., after Eruda loads)
+ */
+export declare function runGgDiagnostics(): Promise<void>;
 export {};

package/dist/gg.js

@@ -209,38 +209,117 @@ export function gg(...args) {
     }
     const ggLogFunction = namespaceToLogFunction.get(namespace) ||
         namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
+    // Prepare args for logging
+    let logArgs;
+    let returnValue;
     if (!args.length) {
-        ggLogFunction(`    📝📝 ${url} 👀👀`);
-        return {
+        // No arguments: log editor link
+        logArgs = [`    📝📝 ${url} 👀👀`];
+        returnValue = {
             fileName,
             functionName,
             url,
             stack
         };
     }
-    // Handle the case where args might be empty or have any number of arguments
-    if (args.length === 1) {
-        ggLogFunction(args[0]);
+    else if (args.length === 1) {
+        logArgs = [args[0]];
+        returnValue = args[0];
     }
     else {
-        ggLogFunction(args[0], ...args.slice(1));
+        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)
-    if (gg._onLog) {
-        // Don't stringify args - keep them as-is for expandable objects
-        const message = args.length === 1 ? String(args[0]) : args.map(String).join(' ');
-        // Use debug's native color (now deterministic since namespace has no padding)
-        gg._onLog({
-            namespace,
-            color: ggLogFunction.color,
-            diff: ggLogFunction.diff || 0, // Millisecond diff from debug library
-            message,
-            args, // Keep raw args for object inspection
-            timestamp: Date.now()
-        });
+    const entry = {
+        namespace,
+        color: ggLogFunction.color,
+        diff: ggLogFunction.diff || 0, // Millisecond diff from debug library
+        message: logArgs.length === 1 ? String(logArgs[0]) : logArgs.map(String).join(' '),
+        args: logArgs, // Keep raw args for object inspection
+        timestamp: Date.now()
+    };
+    if (_onLogCallback) {
+        _onLogCallback(entry);
+    }
+    else {
+        // Buffer early logs before Eruda initializes
+        earlyLogBuffer.push(entry);
     }
-    return args[0];
+    return returnValue;
 }
+/**
+ * gg.ns() - Log with an explicit namespace (callpoint label).
+ *
+ * In production builds, the ggTagPlugin 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;
 /**
@@ -258,25 +337,165 @@ 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
  */
-gg._onLog = null;
-// Log some gg info to the JS console/terminal:
-if (ggConfig.showHints && !isCloudflareWorker()) {
+// Buffer for capturing early logs before Eruda initializes
+const earlyLogBuffer = [];
+let _onLogCallback = null;
+// Proxy property that replays buffered logs when hook is registered
+Object.defineProperty(gg, '_onLog', {
+    get() {
+        return _onLogCallback;
+    },
+    set(callback) {
+        _onLogCallback = callback;
+        // Replay buffered logs when callback is first registered
+        if (callback && earlyLogBuffer.length > 0) {
+            earlyLogBuffer.forEach((entry) => callback(entry));
+            earlyLogBuffer.length = 0; // Clear buffer after replay
+        }
+    }
+});
+// Namespace for adding properties to the gg function
+// eslint-disable-next-line @typescript-eslint/no-namespace
+(function (gg) {
+})(gg || (gg = {}));
+/**
+ * Run gg diagnostics and log configuration status
+ * Can be called immediately or delayed (e.g., after Eruda loads)
+ */
+export async function runGgDiagnostics() {
+    if (!ggConfig.showHints || isCloudflareWorker())
+        return;
     const ggLogTest = debugFactory('gg:TEST');
     let ggMessage = '\n';
     // Utilities for forming ggMessage:
     const message = (s) => (ggMessage += `${s}\n`);
     const checkbox = (test) => (test ? '✅' : '❌');
     const makeHint = (test, ifTrue, ifFalse = '') => (test ? ifTrue : ifFalse);
+    // Use plain console.log for diagnostics - appears in Eruda's Console tab
     console.log(`Loaded gg module. Checking configuration...`);
     if (ggConfig.enabled && ggLogTest.enabled) {
         gg('If you can see this logg, gg configured correctly!');
         message(`No problems detected:`);
         if (BROWSER) {
-            message(`ℹ️ If gg output still not visible above, enable "Verbose" log level in browser DevTools.`);
+            message(`ℹ️ If gg output not visible: enable "Verbose" log level in DevTools, or check Eruda's GG tab.`);
         }
     }
     else {
@@ -307,8 +526,18 @@ if (ggConfig.showHints && !isCloudflareWorker()) {
         }
         message(`${checkbox(ggLogTest.enabled)} DEBUG env variable: ${process?.env?.DEBUG}${hint}`);
     }
+    // Use plain console.log for diagnostics - appears in Eruda's Console tab
     console.log(ggMessage);
     // Reset namespace width after configuration check
     // This prevents the long callpoint from the config check from affecting subsequent logs
     resetNamespaceWidth();
 }
+// Run diagnostics immediately on module load if Eruda is not being used
+// (If Eruda will load, the loader will call runGgDiagnostics after Eruda is ready)
+if (ggConfig.showHints && !isCloudflareWorker()) {
+    // Only run immediately if we're not in a context where Eruda might load
+    // In browser dev mode, assume Eruda might load and skip immediate diagnostics
+    if (!BROWSER || !DEV) {
+        runGgDiagnostics();
+    }
+}

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 ggTagPlugin from './gg-tag-plugin.js';
+export { gg, fg, bg, openInEditorPlugin, ggTagPlugin };

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 ggTagPlugin from './gg-tag-plugin.js';
+export { gg, fg, bg, openInEditorPlugin, ggTagPlugin };

package/package.json

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