@leftium/gg 0.0.33 → 0.0.34

package/dist/debug/node.js

@@ -0,0 +1,137 @@
+/**
+ * Node.js-specific debug implementation.
+ *
+ * Output: process.stderr via util.formatWithOptions.
+ * Persistence: process.env.DEBUG
+ * Format (patched): +123ms namespace message (ANSI colored)
+ */
+import { setup, humanize } from './common.js';
+import tty from 'tty';
+import util from 'util';
+/**
+ * Basic ANSI colors (6) — used when 256-color support is not detected.
+ * Extended 256-color palette matches debug@4 for color-hash stability.
+ */
+const basicColors = [6, 2, 3, 4, 5, 1];
+const extendedColors = [
+    20, 21, 26, 27, 32, 33, 38, 39, 40, 41, 42, 43, 44, 45,
+    56, 57, 62, 63, 68, 69, 74, 75, 76, 77, 78, 79, 80, 81,
+    92, 93, 98, 99, 112, 113, 128, 129, 134, 135, 148, 149,
+    160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171,
+    172, 173, 178, 179, 184, 185, 196, 197, 198, 199, 200, 201,
+    202, 203, 204, 205, 206, 207, 208, 209, 214, 215, 220, 221
+];
+/** Detect 256-color support via supports-color (optional) or heuristic */
+function detectColors() {
+    try {
+        // Try supports-color if available (same as debug@4)
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const supportsColor = require('supports-color');
+        if (supportsColor && (supportsColor.stderr || supportsColor).level >= 2) {
+            return extendedColors;
+        }
+    }
+    catch {
+        // Not installed — fall through
+    }
+    return basicColors;
+}
+/**
+ * Build inspectOpts from DEBUG_* environment variables.
+ * Supports: DEBUG_COLORS, DEBUG_DEPTH, DEBUG_SHOW_HIDDEN, DEBUG_HIDE_DATE
+ */
+const inspectOpts = Object.keys(process.env)
+    .filter((key) => /^debug_/i.test(key))
+    .reduce((obj, key) => {
+    const prop = key
+        .substring(6)
+        .toLowerCase()
+        .replace(/_([a-z])/g, (_, k) => k.toUpperCase());
+    let val = process.env[key];
+    if (/^(yes|on|true|enabled)$/i.test(val))
+        val = true;
+    else if (/^(no|off|false|disabled)$/i.test(val))
+        val = false;
+    else if (val === 'null')
+        val = null;
+    else
+        val = Number(val);
+    obj[prop] = val;
+    return obj;
+}, {});
+function useColors() {
+    return 'colors' in inspectOpts
+        ? Boolean(inspectOpts.colors)
+        : tty.isatty(process.stderr.fd);
+}
+function getDate() {
+    if (inspectOpts.hideDate)
+        return '';
+    return new Date().toISOString() + ' ';
+}
+/**
+ * Format args with ANSI colors and gg's patched prefix order:
+ *   +123ms namespace message
+ */
+function formatArgs(args) {
+    const name = this.namespace;
+    const useCol = this.useColors;
+    if (useCol) {
+        const c = Number(this.color);
+        const colorCode = '\u001B[3' + (c < 8 ? String(c) : '8;5;' + c);
+        const h = ('+' + humanize(this.diff)).padStart(6);
+        const prefix = `${colorCode};1m${h} ${name} \u001B[0m`;
+        args[0] = prefix + String(args[0]).split('\n').join('\n' + prefix);
+        // Append empty color reset (preserves arg count parity from original debug)
+        args.push(colorCode + '' + '\u001B[0m');
+    }
+    else {
+        args[0] = getDate() + name + ' ' + args[0];
+    }
+}
+function log(...args) {
+    process.stderr.write(util.formatWithOptions(inspectOpts, ...args) + '\n');
+}
+function save(namespaces) {
+    if (namespaces) {
+        process.env.DEBUG = namespaces;
+    }
+    else {
+        delete process.env.DEBUG;
+    }
+}
+function load() {
+    return process.env.DEBUG || '';
+}
+function init(instance) {
+    // Each instance gets its own inspectOpts copy (for per-instance color override)
+    instance.inspectOpts = { ...inspectOpts };
+}
+const env = {
+    formatArgs,
+    save,
+    load,
+    useColors,
+    colors: detectColors(),
+    log,
+    init,
+    formatters: {
+        /** %o → util.inspect, single line */
+        o(v) {
+            const opts = this.inspectOpts || {};
+            opts.colors = this.useColors;
+            return util.inspect(v, opts)
+                .split('\n')
+                .map((str) => str.trim())
+                .join(' ');
+        },
+        /** %O → util.inspect, multi-line */
+        O(v) {
+            const opts = this.inspectOpts || {};
+            opts.colors = this.useColors;
+            return util.inspect(v, opts);
+        }
+    }
+};
+const debug = setup(env);
+export default debug;

package/dist/eruda/loader.js

@@ -79,17 +79,6 @@ export async function loadEruda(options) {
             // Ensure tool is always visible in case user customizes
             tool: ['console', 'elements', 'network', 'resources', 'info', 'snippets', 'sources']
         });
-        // Auto-enable localStorage.debug if requested and unset
-        if (options.autoEnable !== false) {
-            try {
-                if (!localStorage.getItem('debug')) {
-                    localStorage.setItem('debug', 'gg:*');
-                }
-            }
-            catch {
-                // localStorage might not be available
-            }
-        }
         // Register gg plugin
         // Import gg and pass it to the plugin directly
         const { gg, runGgDiagnostics } = await import('../gg.js');

package/dist/eruda/plugin.js

@@ -19,8 +19,12 @@ export function createGgPlugin(options, gg) {
     let filterExpanded = false;
     let filterPattern = '';
     const enabledNamespaces = new Set();
+    // Last rendered entries (for hover tooltip arg lookup)
+    let renderedEntries = [];
     // Settings UI state
     let settingsExpanded = false;
+    // Filter pattern persistence key (independent of localStorage.debug)
+    const FILTER_KEY = 'gg-filter';
     // Namespace click action: 'open' uses Vite dev middleware, 'copy' copies formatted string, 'open-url' navigates to URI
     const NS_ACTION_KEY = 'gg-ns-action';
     const EDITOR_BIN_KEY = 'gg-editor-bin';
@@ -78,13 +82,6 @@ export function createGgPlugin(options, gg) {
     };
     let nsClickAction = localStorage.getItem(NS_ACTION_KEY) || (DEV ? 'open' : 'copy');
     let editorBin = localStorage.getItem(EDITOR_BIN_KEY) || '';
-    // Separate format strings for copy vs URL modes (each persisted independently)
-    // Migrate from old single-key format (gg-editor-format) if present
-    const legacyFormat = localStorage.getItem('gg-editor-format');
-    if (legacyFormat && !localStorage.getItem(COPY_FORMAT_KEY)) {
-        localStorage.setItem(COPY_FORMAT_KEY, legacyFormat);
-        localStorage.removeItem('gg-editor-format');
-    }
     let copyFormat = localStorage.getItem(COPY_FORMAT_KEY) || copyPresets['Raw path'];
     let urlFormat = localStorage.getItem(URL_FORMAT_KEY) || uriPresets['VS Code'];
     let projectRoot = localStorage.getItem(PROJECT_ROOT_KEY) || '';
@@ -107,24 +104,27 @@ export function createGgPlugin(options, gg) {
         name: 'GG',
         init($container) {
             $el = $container;
+            // Load filter state BEFORE registering _onLog hook, because setting _onLog
+            // triggers replay of earlyLogBuffer and each entry checks filterPattern
+            filterPattern = localStorage.getItem(FILTER_KEY) || 'gg:*';
             // Register the capture hook on gg
             if (gg) {
                 gg._onLog = (entry) => {
+                    // Track namespaces for filter UI update (check BEFORE pushing to buffer)
+                    const hadNamespace = getAllCapturedNamespaces().includes(entry.namespace);
                     buffer.push(entry);
                     // Add new namespace to enabledNamespaces if it matches the current pattern
                     const effectivePattern = filterPattern || 'gg:*';
                     if (namespaceMatchesPattern(entry.namespace, effectivePattern)) {
                         enabledNamespaces.add(entry.namespace);
                     }
-                    // Update filter UI if expanded (new namespace may have appeared)
-                    if (filterExpanded) {
+                    // Update filter UI if new namespace appeared (updates button summary count)
+                    if (!hadNamespace) {
                         renderFilterUI();
                     }
                     renderLogs();
                 };
             }
-            // Load initial filter state
-            filterPattern = localStorage.getItem('debug') || '';
             // Probe for openInEditorPlugin (status 222) and auto-populate $ROOT in dev mode
             if (DEV) {
                 fetch('/__open-in-editor?file=+')
@@ -420,21 +420,38 @@ export function createGgPlugin(options, gg) {
 					word-break: break-word;
 					padding: 4px 0;
 					position: relative;
+					-webkit-user-select: text !important;
+					user-select: text !important;
+					cursor: text;
+				}
+				.gg-log-content * {
+					-webkit-user-select: text !important;
+					user-select: text !important;
+				}
+				.gg-log-diff, .gg-log-ns {
+					-webkit-user-select: text !important;
+					user-select: text !important;
 				}
-				/* Fast custom tooltip for src expression (no delay like native title) */
+				.gg-details, .gg-details * {
+					-webkit-user-select: text !important;
+					user-select: text !important;
+					cursor: text;
+				}
+				/* Fast custom tooltip for src expression on primitive-only rows (no expandable objects) */
 				.gg-log-content[data-src] {
 					cursor: help;
 				}
-				.gg-log-content[data-src]::before {
-					content: '🔍';
+				/* Show icon only on primitive rows (no .gg-expand child) */
+				.gg-log-content[data-src]:not(:has(.gg-expand))::before {
+					content: '\uD83D\uDD0D';
 					font-size: 10px;
 					margin-right: 4px;
 					opacity: 0.4;
 				}
-				.gg-log-content[data-src]:hover::before {
+				.gg-log-content[data-src]:not(:has(.gg-expand)):hover::before {
 					opacity: 1;
 				}
-				.gg-log-content[data-src]::after {
+				.gg-log-content[data-src]:not(:has(.gg-expand))::after {
 					content: attr(data-src);
 					position: absolute;
 					top: 100%;
@@ -454,9 +471,56 @@ export function createGgPlugin(options, gg) {
 					overflow: hidden;
 					text-overflow: ellipsis;
 				}
-				.gg-log-content[data-src]:hover::after {
+				.gg-log-content[data-src]:not(:has(.gg-expand)):hover::after {
+					opacity: 1;
+				}
+				/* Expression icon inline with expandable object labels */
+				.gg-src-icon {
+					font-size: 10px;
+					margin-right: 2px;
+					opacity: 0.4;
+					cursor: pointer;
+				}
+				.gg-expand:hover .gg-src-icon,
+				.gg-src-icon:hover {
 					opacity: 1;
 				}
+				/* Hover tooltip for expandable objects/arrays */
+				.gg-hover-tooltip {
+					display: none;
+					position: fixed;
+					background: #1e1e1e;
+					color: #d4d4d4;
+					font-size: 11px;
+					font-family: monospace;
+					padding: 8px 10px;
+					border-radius: 4px;
+					white-space: pre;
+					pointer-events: none;
+					z-index: 100000;
+					max-width: min(90vw, 500px);
+					max-height: 300px;
+					overflow: auto;
+					box-shadow: 0 2px 8px rgba(0,0,0,0.3);
+					line-height: 1.4;
+				}
+				.gg-hover-tooltip-src {
+					color: #9cdcfe;
+					font-style: italic;
+					margin-bottom: 4px;
+					padding-bottom: 4px;
+					border-bottom: 1px solid #444;
+				}
+				/* Expression header inside expanded details */
+				.gg-details-src {
+					color: #555;
+					font-style: italic;
+					font-family: monospace;
+					font-size: 11px;
+					margin-bottom: 6px;
+					padding-bottom: 4px;
+					border-bottom: 1px solid #ddd;
+				}
 				.gg-filter-panel {
 					background: #f5f5f5;
 					padding: 10px;
@@ -683,7 +747,7 @@ export function createGgPlugin(options, gg) {
     }
     function applyPatternFromInput(value) {
         filterPattern = value;
-        localStorage.setItem('debug', filterPattern);
+        localStorage.setItem(FILTER_KEY, filterPattern);
         // Sync enabledNamespaces from the new pattern
         const allNamespaces = getAllCapturedNamespaces();
         enabledNamespaces.clear();
@@ -746,7 +810,7 @@ export function createGgPlugin(options, gg) {
                     filterPattern = `gg:*,${exclusions}`;
                     enabledNamespaces.clear();
                 }
-                localStorage.setItem('debug', filterPattern);
+                localStorage.setItem(FILTER_KEY, filterPattern);
                 renderFilterUI();
                 renderLogs();
                 return;
@@ -893,6 +957,37 @@ export function createGgPlugin(options, gg) {
             else if (nsClickAction === 'copy' || nsClickAction === 'open-url') {
                 optionsSection = renderFormatSection(nsClickAction === 'open-url');
             }
+            // Native Console section
+            const currentDebugValue = localStorage.getItem('debug');
+            const debugDisplay = currentDebugValue !== null ? `'${escapeHtml(currentDebugValue)}'` : 'not set';
+            const currentFilter = filterPattern || 'gg:*';
+            const debugMatchesFilter = currentDebugValue === currentFilter;
+            const debugIncludesGg = currentDebugValue !== null &&
+                (currentDebugValue.includes('gg:') || currentDebugValue === '*');
+            const nativeConsoleSection = `
+				<div style="margin-top: 12px; padding-top: 12px; border-top: 1px solid #ddd;">
+					<div class="gg-settings-label">Native Console Output</div>
+					<div style="font-size: 11px; opacity: 0.7; margin-bottom: 8px;">
+						gg messages always appear in this GG panel. To also see them in the browser's native console, set <code>localStorage.debug</code> below.
+						For server-side: <code>DEBUG=gg:* npm run dev</code>
+					</div>
+					<div style="font-family: monospace; font-size: 12px; margin-bottom: 6px;">
+						localStorage.debug = ${debugDisplay}
+						${debugIncludesGg ? '<span style="color: green;">✅</span>' : '<span style="color: #999;">⚫ gg:* not included</span>'}
+					</div>
+					<div style="display: flex; gap: 6px; flex-wrap: wrap;">
+						<button class="gg-sync-debug-btn" style="padding: 4px 10px; font-size: 12px; cursor: pointer; border: 1px solid #ccc; border-radius: 3px; background: ${debugMatchesFilter ? '#e8e8e8' : '#fff'};"${debugMatchesFilter ? ' disabled' : ''}>
+							${debugMatchesFilter ? 'In sync' : `Set to '${escapeHtml(currentFilter)}'`}
+						</button>
+						<button class="gg-clear-debug-btn" style="padding: 4px 10px; font-size: 12px; cursor: pointer; border: 1px solid #ccc; border-radius: 3px; background: #fff;"${currentDebugValue === null ? ' disabled' : ''}>
+							Clear
+						</button>
+					</div>
+					<div style="font-size: 10px; opacity: 0.5; margin-top: 4px;">
+						Changes take effect on next page reload.
+					</div>
+				</div>
+			`;
             settingsPanel.innerHTML = `
 				${callSitesWarning}
 				<div class="gg-settings-label">When namespace clicked:</div>
@@ -911,6 +1006,7 @@ export function createGgPlugin(options, gg) {
 					</label>
 				</div>
 				${optionsSection}
+				${nativeConsoleSection}
 			`;
         }
         else {
@@ -970,7 +1066,7 @@ export function createGgPlugin(options, gg) {
                 target.blur();
             }
         });
-        // Preset button clicks + editor bin button clicks
+        // Preset button clicks + editor bin button clicks + native console buttons
         settingsPanel.addEventListener('click', (e) => {
             const target = e.target;
             if (target.classList.contains('gg-preset-btn')) {
@@ -988,6 +1084,17 @@ export function createGgPlugin(options, gg) {
                     renderSettingsUI();
                 }
             }
+            // Native Console: sync localStorage.debug to current gg-filter
+            if (target.classList.contains('gg-sync-debug-btn')) {
+                const currentFilter = localStorage.getItem(FILTER_KEY) || 'gg:*';
+                localStorage.setItem('debug', currentFilter);
+                renderSettingsUI();
+            }
+            // Native Console: clear localStorage.debug
+            if (target.classList.contains('gg-clear-debug-btn')) {
+                localStorage.removeItem('debug');
+                renderSettingsUI();
+            }
         });
     }
     function wireUpButtons() {
@@ -1127,7 +1234,7 @@ export function createGgPlugin(options, gg) {
                 else {
                     soloNamespace(namespace);
                 }
-                localStorage.setItem('debug', filterPattern);
+                localStorage.setItem(FILTER_KEY, filterPattern);
                 renderFilterUI();
                 renderLogs();
                 return;
@@ -1138,7 +1245,7 @@ export function createGgPlugin(options, gg) {
                 if (!namespace)
                     return;
                 soloNamespace(namespace);
-                localStorage.setItem('debug', filterPattern);
+                localStorage.setItem(FILTER_KEY, filterPattern);
                 renderFilterUI();
                 renderLogs();
                 return;
@@ -1150,11 +1257,75 @@ export function createGgPlugin(options, gg) {
                 filterPattern = 'gg:*';
                 enabledNamespaces.clear();
                 getAllCapturedNamespaces().forEach((ns) => enabledNamespaces.add(ns));
-                localStorage.setItem('debug', filterPattern);
+                localStorage.setItem(FILTER_KEY, filterPattern);
                 renderFilterUI();
                 renderLogs();
             }
         });
+        // Hover tooltip for expandable objects/arrays.
+        // The tooltip div is re-created after each renderLogs() call
+        // since logContainer.html() destroys children. Event listeners query it dynamically.
+        containerEl.addEventListener('mouseover', (e) => {
+            const target = e.target?.closest?.('.gg-expand');
+            if (!target)
+                return;
+            const entryIdx = target.getAttribute('data-entry');
+            const argIdx = target.getAttribute('data-arg');
+            if (entryIdx === null || argIdx === null)
+                return;
+            const entry = renderedEntries[Number(entryIdx)];
+            if (!entry)
+                return;
+            const arg = entry.args[Number(argIdx)];
+            if (arg === undefined)
+                return;
+            const tip = containerEl.querySelector('.gg-hover-tooltip');
+            if (!tip)
+                return;
+            const srcExpr = target.getAttribute('data-src');
+            // Build tooltip content using DOM API (safe, no HTML injection)
+            tip.textContent = '';
+            if (srcExpr) {
+                const srcDiv = document.createElement('div');
+                srcDiv.className = 'gg-hover-tooltip-src';
+                srcDiv.textContent = srcExpr;
+                tip.appendChild(srcDiv);
+            }
+            const pre = document.createElement('pre');
+            pre.style.margin = '0';
+            pre.textContent = JSON.stringify(arg, null, 2);
+            tip.appendChild(pre);
+            tip.style.display = 'block';
+            // Position below the hovered element using viewport coords (fixed positioning)
+            const targetRect = target.getBoundingClientRect();
+            let left = targetRect.left;
+            let top = targetRect.bottom + 4;
+            // Keep tooltip within viewport
+            const tipRect = tip.getBoundingClientRect();
+            if (left + tipRect.width > window.innerWidth) {
+                left = window.innerWidth - tipRect.width - 8;
+            }
+            if (left < 4)
+                left = 4;
+            // If tooltip would go below viewport, show above instead
+            if (top + tipRect.height > window.innerHeight) {
+                top = targetRect.top - tipRect.height - 4;
+            }
+            tip.style.left = `${left}px`;
+            tip.style.top = `${top}px`;
+        });
+        containerEl.addEventListener('mouseout', (e) => {
+            const target = e.target?.closest?.('.gg-expand');
+            if (!target)
+                return;
+            // Only hide if we're not moving to another child of the same .gg-expand
+            const related = e.relatedTarget;
+            if (related?.closest?.('.gg-expand') === target)
+                return;
+            const tip = containerEl.querySelector('.gg-hover-tooltip');
+            if (tip)
+                tip.style.display = 'none';
+        });
         expanderAttached = true;
     }
     function wireUpResize() {
@@ -1214,6 +1385,7 @@ export function createGgPlugin(options, gg) {
         const allEntries = buffer.getEntries();
         // Apply filtering
         const entries = allEntries.filter((entry) => enabledNamespaces.has(entry.namespace));
+        renderedEntries = entries;
         const countText = entries.length === allEntries.length
             ? `${entries.length} entries`
             : `${entries.length} / ${allEntries.length} entries`;
@@ -1230,6 +1402,8 @@ export function createGgPlugin(options, gg) {
             // Format each arg individually - objects are expandable
             let argsHTML = '';
             let detailsHTML = '';
+            // Source expression for this entry (used in hover tooltips and expanded details)
+            const srcExpr = entry.src?.trim() && !/^['"`]/.test(entry.src) ? escapeHtml(entry.src) : '';
             if (entry.args.length > 0) {
                 argsHTML = entry.args
                     .map((arg, argIdx) => {
@@ -1238,9 +1412,14 @@ export function createGgPlugin(options, gg) {
                         const preview = Array.isArray(arg) ? `Array(${arg.length})` : 'Object';
                         const jsonStr = escapeHtml(JSON.stringify(arg, null, 2));
                         const uniqueId = `${index}-${argIdx}`;
+                        // Expression header inside expanded details
+                        const srcHeader = srcExpr ? `<div class="gg-details-src">${srcExpr}</div>` : '';
                         // Store details separately to render after the row
-                        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>`;
+                        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;">${srcHeader}<pre style="margin: 0;">${jsonStr}</pre></div>`;
+                        // data-entry/data-arg for hover tooltip lookup, data-src for expression context
+                        const srcAttr = srcExpr ? ` data-src="${srcExpr}"` : '';
+                        const srcIcon = srcExpr ? `<span class="gg-src-icon">\uD83D\uDD0D</span>` : '';
+                        return `<span style="color: #888; cursor: pointer; text-decoration: underline;" class="gg-expand" data-index="${uniqueId}" data-entry="${index}" data-arg="${argIdx}"${srcAttr}>${srcIcon}${preview}</span>`;
                     }
                     else {
                         // Parse ANSI codes first, then convert URLs to clickable links
@@ -1295,6 +1474,13 @@ export function createGgPlugin(options, gg) {
         })
             .join('')}</div>`;
         logContainer.html(logsHTML);
+        // Append hover tooltip div (destroyed by .html() each render, so re-create)
+        const containerDom = logContainer.get(0);
+        if (containerDom) {
+            const tip = document.createElement('div');
+            tip.className = 'gg-hover-tooltip';
+            containerDom.appendChild(tip);
+        }
         // Re-wire expanders after rendering
         wireUpExpanders();
         // Auto-scroll to bottom
@@ -1326,6 +1512,7 @@ export function createGgPlugin(options, gg) {
      */
     function stripAnsi(text) {
         // Remove all ANSI escape codes
+        // eslint-disable-next-line no-control-regex
         return text.replace(/\x1b\[[0-9;]*m/g, '');
     }
     // Standard ANSI 3/4-bit color palette
@@ -1376,6 +1563,7 @@ export function createGgPlugin(options, gg) {
      */
     function parseAnsiToHtml(text) {
         // ANSI escape sequence regex
+        // eslint-disable-next-line no-control-regex
         const ansiRegex = /\x1b\[([0-9;]+)m/g;
         let html = '';
         let lastIndex = 0;

package/dist/eruda/types.d.ts

@@ -12,11 +12,6 @@ export interface GgErudaOptions {
      * @default 2000
      */
     maxEntries?: number;
-    /**
-     * Auto-enable localStorage.debug = 'gg:*' if unset
-     * @default true
-     */
-    autoEnable?: boolean;
     /**
      * Additional Eruda options passed to eruda.init()
      * @default {}

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

@@ -11,6 +11,33 @@ export interface GgCallSitesPluginOptions {
      */
     srcRootPattern?: string;
 }
+/**
+ * A range of source code that contains JS expressions, tagged with its context.
+ * - 'script': inside a `<script>` block — use object literal `{...}` syntax
+ * - 'template': inside a template expression `{...}` or event handler — use `gg._o()` syntax
+ */
+export interface CodeRange {
+    start: number;
+    end: number;
+    context: 'script' | 'template';
+}
+/**
+ * A function scope range, mapping a byte range to the enclosing function name.
+ * Built from the estree AST during `collectCodeRanges()`.
+ */
+export interface FunctionScope {
+    start: number;
+    end: number;
+    name: string;
+}
+/**
+ * Result of `collectCodeRanges()` — code ranges plus function scope info.
+ */
+export interface SvelteCodeInfo {
+    ranges: CodeRange[];
+    /** Function scopes extracted from the estree AST, sorted by start position. */
+    functionScopes: FunctionScope[];
+}
 /**
  * Vite plugin that rewrites `gg(...)` and `gg.ns(...)` calls to
  * `gg._ns({ns, file, line, col}, ...)` at build time. This gives each call
@@ -29,3 +56,60 @@ export interface GgCallSitesPluginOptions {
  * });
  */
 export default function ggCallSitesPlugin(options?: GgCallSitesPluginOptions): Plugin;
+/**
+ * Parse JavaScript/TypeScript code using acorn to extract function scopes.
+ * Returns function scope ranges for accurate function name detection in .js/.ts files.
+ * Uses @sveltejs/acorn-typescript plugin to handle TypeScript syntax.
+ *
+ * For .svelte files, use `collectCodeRanges()` instead (which uses svelte.parse()).
+ */
+export declare function parseJavaScript(code: string): FunctionScope[];
+/**
+ * Use `svelte.parse()` to collect all code ranges and function scopes in a .svelte file.
+ *
+ * Code ranges identify where JS expressions live:
+ * - `<script>` blocks (context: 'script')
+ * - Template expressions: `{expr}`, `onclick={expr}`, `bind:value={expr}`,
+ *   `class:name={expr}`, `{#if expr}`, `{#each expr}`, etc. (context: 'template')
+ *
+ * Function scopes are extracted from the estree AST in script blocks, mapping
+ * byte ranges to enclosing function names. This replaces regex-based function
+ * detection for .svelte files.
+ *
+ * Text nodes (prose) are NOT included, so `gg()` in `<p>text gg()</p>` is never transformed.
+ */
+export declare function collectCodeRanges(code: string): SvelteCodeInfo;
+/**
+ * Find the innermost enclosing function name for a byte position
+ * using the pre-built function scope map.
+ * Returns empty string if not inside any named function.
+ */
+export declare function findEnclosingFunctionFromScopes(pos: number, scopes: FunctionScope[]): string;
+/**
+ * Escape a string for embedding as a single-quoted JS string literal.
+ */
+export declare function escapeForString(s: string): string;
+/**
+ * Transform gg() and gg.ns() calls in source code to gg._ns({ns, file, line, col, src}, ...) calls.
+ *
+ * Handles:
+ * - bare gg(expr) → gg._ns({ns, file, line, col, src: 'expr'}, expr)
+ * - gg.ns('label', expr) → gg._ns({ns, file, line, col, src: 'expr'}, expr)
+ *   - label supports template variables: $NS, $FN, $FILE, $LINE, $COL
+ *   - plain label (no variables) is used as-is (no auto @fn append)
+ * - gg.enable, gg.disable, gg.clearPersist, gg._onLog, gg._ns → left untouched
+ * - gg inside strings and comments → left untouched
+ *
+ * For .svelte files, `svelteInfo` (from `collectCodeRanges()`) determines which
+ * positions contain JS code and provides AST-based function scope detection.
+ * Script ranges use `{...}` object literal syntax; template ranges use `gg._o()`
+ * function-call syntax (no braces in Svelte markup). Positions outside any code
+ * range (e.g. prose text) are skipped.
+ *
+ * For .js/.ts files, `jsFunctionScopes` (from `parseJavaScript()`) provides
+ * AST-based function scope detection (no regex fallback).
+ */
+export declare function transformGgCalls(code: string, shortPath: string, filePath: string, svelteInfo?: SvelteCodeInfo, jsFunctionScopes?: FunctionScope[]): {
+    code: string;
+    map: null;
+} | null;