@leftium/gg 0.0.33 → 0.0.35

package/dist/gg.js

@@ -1,4 +1,4 @@
-import debugFactory from './debug.js';
+import debugFactory, {} from './debug/index.js';
 import { BROWSER, DEV } from 'esm-env';
 import { toWordTuple } from './words.js';
 const _ggCallSitesPlugin = typeof __GG_TAG_PLUGIN__ !== 'undefined' ? __GG_TAG_PLUGIN__ : false;
@@ -8,23 +8,21 @@ const _ggCallSitesPlugin = typeof __GG_TAG_PLUGIN__ !== 'undefined' ? __GG_TAG_P
  */
 function createGgDebugger(namespace) {
     const dbg = debugFactory(namespace);
-    // Store the original formatArgs (if it exists)
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    // Store the original formatArgs
     const originalFormatArgs = dbg.formatArgs;
     // Override formatArgs to add padding to the namespace display
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     dbg.formatArgs = function (args) {
         // Call original formatArgs first
         if (originalFormatArgs) {
-            originalFormatArgs.call(this, args);
+            originalFormatArgs.call(dbg, args);
         }
         // Extract the callpoint from namespace (strip 'gg:' prefix and any URL suffix)
-        const nsMatch = this.namespace.match(/^gg:([^h]+?)(?:http|$)/);
-        const callpoint = nsMatch ? nsMatch[1] : this.namespace.replace(/^gg:/, '');
+        const nsMatch = dbg.namespace.match(/^gg:([^h]+?)(?:http|$)/);
+        const callpoint = nsMatch ? nsMatch[1] : dbg.namespace.replace(/^gg:/, '');
         const paddedCallpoint = callpoint.padEnd(maxCallpointLength, ' ');
         // Replace the namespace in the formatted string with padded version
         if (typeof args[0] === 'string') {
-            args[0] = args[0].replace(this.namespace, `gg:${paddedCallpoint}`);
+            args[0] = args[0].replace(dbg.namespace, `gg:${paddedCallpoint}`);
         }
     };
     return dbg;
@@ -167,6 +165,23 @@ const namespaceToLogFunction = new Map();
 let maxCallpointLength = 0;
 // Cache: raw stack line → word tuple (avoids re-hashing the same call site)
 const stackLineCache = new Map();
+/**
+ * Resolve the callpoint for the caller at the given stack depth.
+ * depth=2 → caller of gg(), depth=3 → caller of gg.ns() (extra frame).
+ */
+function resolveCallpoint(depth) {
+    const rawStack = new Error().stack || '';
+    const callerLine = rawStack.split('\n')[depth] || rawStack;
+    const callerKey = callerLine.replace(/:\d+:\d+\)?$/, '').trim();
+    const callpoint = stackLineCache.get(callerKey) ?? toWordTuple(callerKey);
+    if (!stackLineCache.has(callerKey)) {
+        stackLineCache.set(callerKey, callpoint);
+    }
+    if (callpoint.length < 80 && callpoint.length > maxCallpointLength) {
+        maxCallpointLength = callpoint.length;
+    }
+    return callpoint;
+}
 /**
  * Reset the namespace width tracking.
  * Useful after configuration checks that may have long callpoint paths.
@@ -190,69 +205,9 @@ export function gg(...args) {
     // When the plugin IS installed, all gg() calls are rewritten to gg._ns() at build time,
     // so this code path only runs for un-transformed calls (i.e. plugin not installed).
     // Same call site always produces the same word pair (e.g. "calm-fox").
-    const rawStack = new Error().stack || '';
-    // Stack line [2]: skip "Error" header [0] and gg() frame [1]
-    const callerLine = rawStack.split('\n')[2] || rawStack;
-    // Strip line:col numbers so all gg() calls within the same function
-    // hash to the same word tuple. In minified builds, multiple gg() calls
-    // in one function differ only by column offset — we want them grouped.
-    // Chrome: "at handleClick (chunk-abc.js:1:45892)" → "at handleClick (chunk-abc.js)"
-    // Firefox: "handleClick@https://...:1:45892" → "handleClick@https://..."
-    const callerKey = callerLine.replace(/:\d+:\d+\)?$/, '').trim();
-    const callpoint = stackLineCache.get(callerKey) ?? toWordTuple(callerKey);
-    if (!stackLineCache.has(callerKey)) {
-        stackLineCache.set(callerKey, callpoint);
-    }
-    if (callpoint.length < 80 && callpoint.length > maxCallpointLength) {
-        maxCallpointLength = callpoint.length;
-    }
-    const namespace = `gg:${callpoint}`;
-    const ggLogFunction = namespaceToLogFunction.get(namespace) ||
-        namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
-    // Prepare args for logging
-    let logArgs;
-    let returnValue;
-    if (!args.length) {
-        // No arguments: return stub call-site info (no open-in-editor without plugin)
-        logArgs = [`    📝 ${callpoint} (install gg-call-sites-plugin for editor links)`];
-        returnValue = {
-            fileName: callpoint,
-            functionName: '',
-            url: ''
-        };
-    }
-    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, // 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 returnValue;
+    // depth=2: skip "Error" header [0] and gg() frame [1]
+    const callpoint = resolveCallpoint(2);
+    return ggLog({ ns: callpoint }, ...args);
 }
 /**
  * gg.ns() - Log with an explicit namespace (callpoint label).
@@ -261,31 +216,43 @@ export function gg(...args) {
  * across builds. For the internal plugin-generated version with file
  * metadata, see gg._ns().
  *
+ * The label supports template variables (substituted by the vite plugin
+ * at build time, or at runtime for $NS):
+ *   $NS   - auto-generated callpoint (file@fn with plugin, word-tuple without)
+ *   $FN   - enclosing function name (plugin only, empty without)
+ *   $FILE - short file path (plugin only, empty without)
+ *   $LINE - line number (plugin only, empty without)
+ *   $COL  - column number (plugin only, empty without)
+ *
  * @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("auth", "login failed")        // → gg:auth
+ * gg.ns("ERROR:$NS", msg)              // → gg:ERROR:routes/+page.svelte@handleClick (with plugin)
+ *                                       // → gg:ERROR:calm-fox (without plugin)
+ * gg.ns("$NS:validation", fieldName)   // → gg:routes/+page.svelte@handleClick:validation
  */
 gg.ns = function (nsLabel, ...args) {
+    // Resolve $NS at runtime (word-tuple fallback when plugin isn't installed).
+    // With the plugin, $NS is already substituted at build time before this runs.
+    // depth=3: skip "Error" [0], resolveCallpoint [1], gg.ns [2] → caller [3]
+    if (nsLabel.includes('$NS')) {
+        const callpoint = resolveCallpoint(3);
+        nsLabel = nsLabel.replace(/\$NS/g, callpoint);
+    }
     return gg._ns({ ns: nsLabel }, ...args);
 };
 /**
- * gg._ns() - Internal: log with namespace and source file metadata.
+ * Core logging function shared by all gg methods.
  *
- * Called by the ggCallSitesPlugin Vite plugin, which rewrites both bare gg()
- * calls and manual gg.ns() calls to gg._ns({ns, file, line, col}, ...) at
- * build time. This gives each call site a unique namespace plus the source
- * location for open-in-editor support.
- *
- * @param options - { ns: string; file?: string; line?: number; col?: number }
- * @param args - Same arguments as gg()
- * @returns Same as gg() - the first arg, or call-site info if no args
+ * All public methods (gg, gg.ns, gg.warn, gg.error, gg.table, etc.)
+ * funnel through this function. It handles namespace resolution,
+ * debug output, capture hook, and passthrough return.
  */
-gg._ns = function (options, ...args) {
-    const { ns: nsLabel, file, line, col, src } = options;
+function ggLog(options, ...args) {
+    const { ns: nsLabel, file, line, col, src, level, stack, tableData } = options;
     if (!ggConfig.enabled || isCloudflareWorker()) {
         return args.length ? args[0] : { fileName: '', functionName: '', url: '' };
     }
@@ -315,6 +282,13 @@ gg._ns = function (options, ...args) {
         logArgs = [args[0], ...args.slice(1)];
         returnValue = args[0];
     }
+    // Add level prefix emoji for warn/error
+    if (level === 'warn') {
+        logArgs[0] = `⚠️ ${logArgs[0]}`;
+    }
+    else if (level === 'error') {
+        logArgs[0] = `⛔ ${logArgs[0]}`;
+    }
     // Log to console via debug
     if (logArgs.length === 1) {
         ggLogFunction(logArgs[0]);
@@ -333,7 +307,10 @@ gg._ns = function (options, ...args) {
         file,
         line,
         col,
-        src
+        src,
+        level,
+        stack,
+        tableData
     };
     if (_onLogCallback) {
         _onLogCallback(entry);
@@ -342,6 +319,33 @@ gg._ns = function (options, ...args) {
         earlyLogBuffer.push(entry);
     }
     return returnValue;
+}
+/**
+ * gg._ns() - Internal: log with namespace and source file metadata.
+ *
+ * Called by the ggCallSitesPlugin Vite plugin, which rewrites both bare gg()
+ * calls and manual gg.ns() calls to gg._ns({ns, file, line, col}, ...) at
+ * build time. This gives each call site a unique namespace plus the source
+ * location for open-in-editor support.
+ *
+ * @param options - { ns: string; file?: string; line?: number; col?: number }
+ * @param args - Same arguments as gg()
+ * @returns Same as gg() - the first arg, or call-site info if no args
+ */
+gg._ns = function (options, ...args) {
+    return ggLog(options, ...args);
+};
+/**
+ * gg._o() - Internal: build options object for gg._ns() without object literal syntax.
+ *
+ * Used by the vite plugin to transform gg() calls in Svelte template markup,
+ * where object literals ({...}) would break Svelte's template parser.
+ *
+ * In <script> blocks:  gg._ns({ns:'...', file:'...', line:1, col:1}, args)
+ * In template markup:  gg._ns(gg._o('...','...',1,1), args)
+ */
+gg._o = function (ns, file, line, col, src) {
+    return { ns, file, line, col, src };
 };
 gg.disable = isCloudflareWorker() ? () => { } : debugFactory.disable;
 gg.enable = isCloudflareWorker() ? () => { } : debugFactory.enable;
@@ -360,6 +364,357 @@ gg.clearPersist = () => {
         }
     }
 };
+// ── Console-like methods ───────────────────────────────────────────────
+// Each public method (gg.warn, gg.error, etc.) has a corresponding internal
+// method (gg._warn, gg._error, etc.) that accepts call-site metadata from
+// the Vite plugin. The public methods use runtime stack-based callpoints
+// as a fallback when the plugin isn't installed.
+/**
+ * Capture a cleaned-up stack trace, stripping internal gg frames.
+ * @param skipFrames - Number of internal frames to strip from the top
+ */
+function captureStack(skipFrames) {
+    let stack = new Error().stack || undefined;
+    if (stack) {
+        const lines = stack.split('\n');
+        stack = lines.slice(skipFrames).join('\n');
+    }
+    return stack;
+}
+/**
+ * Get stack from an Error arg or capture a fresh one.
+ */
+function getErrorStack(firstArg, skipFrames) {
+    if (firstArg instanceof Error && firstArg.stack) {
+        return firstArg.stack;
+    }
+    return captureStack(skipFrames);
+}
+/**
+ * gg.warn() - Log at warning level.
+ *
+ * Passthrough: returns the first argument.
+ * In Eruda, entries are styled with a yellow/warning indicator.
+ *
+ * @example
+ * gg.warn('deprecated API used');
+ * const result = gg.warn(computeValue(), 'might be slow');
+ */
+gg.warn = function (...args) {
+    if (!ggConfig.enabled || isCloudflareWorker()) {
+        return args.length ? args[0] : undefined;
+    }
+    const callpoint = resolveCallpoint(3);
+    return ggLog({ ns: callpoint, level: 'warn' }, ...args);
+};
+/**
+ * gg._warn() - Internal: warn with call-site metadata from Vite plugin.
+ */
+gg._warn = function (options, ...args) {
+    return ggLog({ ...options, level: 'warn' }, ...args);
+};
+/**
+ * gg.error() - Log at error level.
+ *
+ * Passthrough: returns the first argument.
+ * Captures a stack trace silently — visible in Eruda via a collapsible toggle.
+ * If the first argument is an Error object, its .stack is used instead.
+ *
+ * @example
+ * gg.error('connection failed');
+ * gg.error(new Error('timeout'));
+ * const val = gg.error(response, 'unexpected status');
+ */
+gg.error = function (...args) {
+    if (!ggConfig.enabled || isCloudflareWorker()) {
+        return args.length ? args[0] : undefined;
+    }
+    const callpoint = resolveCallpoint(3);
+    const stack = getErrorStack(args[0], 4);
+    return ggLog({ ns: callpoint, level: 'error', stack }, ...args);
+};
+/**
+ * gg._error() - Internal: error with call-site metadata from Vite plugin.
+ */
+gg._error = function (options, ...args) {
+    const stack = getErrorStack(args[0], 3);
+    return ggLog({ ...options, level: 'error', stack }, ...args);
+};
+/**
+ * gg.assert() - Log only if condition is false.
+ *
+ * Like console.assert: if the first argument is falsy, logs the remaining
+ * arguments at error level. If the condition is truthy, does nothing.
+ * Passthrough: always returns the condition value.
+ *
+ * @example
+ * gg.assert(user != null, 'user should exist');
+ * gg.assert(list.length > 0, 'list is empty', list);
+ */
+gg.assert = function (condition, ...args) {
+    if (!condition) {
+        if (!ggConfig.enabled || isCloudflareWorker())
+            return condition;
+        const callpoint = resolveCallpoint(3);
+        const stack = captureStack(4);
+        const assertArgs = args.length > 0 ? args : ['Assertion failed'];
+        ggLog({ ns: callpoint, level: 'error', stack }, ...assertArgs);
+    }
+    return condition;
+};
+/**
+ * gg._assert() - Internal: assert with call-site metadata from Vite plugin.
+ */
+gg._assert = function (options, condition, ...args) {
+    if (!condition) {
+        if (!ggConfig.enabled || isCloudflareWorker())
+            return condition;
+        const stack = captureStack(3);
+        const assertArgs = args.length > 0 ? args : ['Assertion failed'];
+        ggLog({ ...options, level: 'error', stack }, ...assertArgs);
+    }
+    return condition;
+};
+/**
+ * gg.table() - Log tabular data.
+ *
+ * Formats an array of objects (or an object of objects) as an ASCII table.
+ * Passthrough: returns the data argument.
+ *
+ * @example
+ * gg.table([{name: 'Alice', age: 30}, {name: 'Bob', age: 25}]);
+ * gg.table({a: {x: 1}, b: {x: 2}});
+ */
+gg.table = function (data, columns) {
+    if (!ggConfig.enabled || isCloudflareWorker())
+        return data;
+    const callpoint = resolveCallpoint(3);
+    const { keys, rows } = formatTable(data, columns);
+    ggLog({ ns: callpoint, tableData: { keys, rows } }, '(table)');
+    // Also emit a native console.table for proper rendering in browser/Node consoles
+    if (columns) {
+        console.table(data, columns);
+    }
+    else {
+        console.table(data);
+    }
+    return data;
+};
+/**
+ * gg._table() - Internal: table with call-site metadata from Vite plugin.
+ */
+gg._table = function (options, data, columns) {
+    if (!ggConfig.enabled || isCloudflareWorker())
+        return data;
+    const { keys, rows } = formatTable(data, columns);
+    ggLog({ ...options, tableData: { keys, rows } }, '(table)');
+    if (columns) {
+        console.table(data, columns);
+    }
+    else {
+        console.table(data);
+    }
+    return data;
+};
+// Timer storage for gg.time / gg.timeEnd / gg.timeLog
+const timers = new Map();
+/**
+ * gg.time() - Start a named timer.
+ *
+ * @example
+ * gg.time('fetch');
+ * const data = await fetchData();
+ * gg.timeEnd('fetch'); // logs "+123ms fetch: 456ms"
+ */
+gg.time = function (label = 'default') {
+    if (!ggConfig.enabled || isCloudflareWorker())
+        return;
+    timers.set(label, performance.now());
+};
+/** gg._time() - Internal: time with call-site metadata from Vite plugin. */
+gg._time = function (_options, label = 'default') {
+    if (!ggConfig.enabled || isCloudflareWorker())
+        return;
+    timers.set(label, performance.now());
+};
+/**
+ * gg.timeLog() - Log the current elapsed time without stopping the timer.
+ *
+ * @example
+ * gg.time('process');
+ * // ... step 1 ...
+ * gg.timeLog('process', 'step 1 done');
+ * // ... step 2 ...
+ * gg.timeEnd('process');
+ */
+gg.timeLog = function (label = 'default', ...args) {
+    if (!ggConfig.enabled || isCloudflareWorker())
+        return;
+    const start = timers.get(label);
+    if (start === undefined) {
+        const callpoint = resolveCallpoint(3);
+        ggLog({ ns: callpoint, level: 'warn' }, `Timer '${label}' does not exist`);
+        return;
+    }
+    const elapsed = performance.now() - start;
+    const callpoint = resolveCallpoint(3);
+    ggLog({ ns: callpoint }, `${label}: ${formatElapsed(elapsed)}`, ...args);
+};
+/** gg._timeLog() - Internal: timeLog with call-site metadata from Vite plugin. */
+gg._timeLog = function (options, label = 'default', ...args) {
+    if (!ggConfig.enabled || isCloudflareWorker())
+        return;
+    const start = timers.get(label);
+    if (start === undefined) {
+        ggLog({ ...options, level: 'warn' }, `Timer '${label}' does not exist`);
+        return;
+    }
+    const elapsed = performance.now() - start;
+    ggLog(options, `${label}: ${formatElapsed(elapsed)}`, ...args);
+};
+/**
+ * gg.timeEnd() - Stop a named timer and log the elapsed time.
+ *
+ * @example
+ * gg.time('fetch');
+ * const data = await fetchData();
+ * gg.timeEnd('fetch'); // logs "fetch: 456.12ms"
+ */
+gg.timeEnd = function (label = 'default') {
+    if (!ggConfig.enabled || isCloudflareWorker())
+        return;
+    const start = timers.get(label);
+    if (start === undefined) {
+        const callpoint = resolveCallpoint(3);
+        ggLog({ ns: callpoint, level: 'warn' }, `Timer '${label}' does not exist`);
+        return;
+    }
+    const elapsed = performance.now() - start;
+    timers.delete(label);
+    const callpoint = resolveCallpoint(3);
+    ggLog({ ns: callpoint }, `${label}: ${formatElapsed(elapsed)}`);
+};
+/** gg._timeEnd() - Internal: timeEnd with call-site metadata from Vite plugin. */
+gg._timeEnd = function (options, label = 'default') {
+    if (!ggConfig.enabled || isCloudflareWorker())
+        return;
+    const start = timers.get(label);
+    if (start === undefined) {
+        ggLog({ ...options, level: 'warn' }, `Timer '${label}' does not exist`);
+        return;
+    }
+    const elapsed = performance.now() - start;
+    timers.delete(label);
+    ggLog(options, `${label}: ${formatElapsed(elapsed)}`);
+};
+/**
+ * gg.trace() - Log with a stack trace.
+ *
+ * Like console.trace: logs the arguments plus a full stack trace.
+ * Passthrough: returns the first argument.
+ *
+ * @example
+ * gg.trace('how did we get here?');
+ * const val = gg.trace(result, 'call path');
+ */
+gg.trace = function (...args) {
+    if (!ggConfig.enabled || isCloudflareWorker()) {
+        return args.length ? args[0] : undefined;
+    }
+    const callpoint = resolveCallpoint(3);
+    const stack = captureStack(4);
+    const traceArgs = args.length > 0 ? args : ['Trace'];
+    return ggLog({ ns: callpoint, stack }, ...traceArgs);
+};
+/**
+ * gg._trace() - Internal: trace with call-site metadata from Vite plugin.
+ */
+gg._trace = function (options, ...args) {
+    if (!ggConfig.enabled || isCloudflareWorker()) {
+        return args.length ? args[0] : undefined;
+    }
+    const stack = captureStack(3);
+    const traceArgs = args.length > 0 ? args : ['Trace'];
+    return ggLog({ ...options, stack }, ...traceArgs);
+};
+/**
+ * Format elapsed time with appropriate precision.
+ * < 1s → "123.45ms", >= 1s → "1.23s", >= 60s → "1m 2.3s"
+ */
+function formatElapsed(ms) {
+    if (ms < 1000)
+        return `${ms.toFixed(2)}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(2)}s`;
+    const minutes = Math.floor(ms / 60000);
+    const seconds = (ms % 60000) / 1000;
+    return `${minutes}m ${seconds.toFixed(1)}s`;
+}
+/**
+ * Normalize data into structured keys + rows for table rendering.
+ * Used by both Eruda (HTML table) and console.table() delegation.
+ * Supports arrays of objects, arrays of primitives, and objects of objects.
+ */
+function formatTable(data, columns) {
+    if (data === null || data === undefined || typeof data !== 'object') {
+        return { keys: [], rows: [] };
+    }
+    // Normalize to rows: [{key, ...values}]
+    let rows;
+    let allKeys;
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return { keys: [], rows: [] };
+        // Array of primitives
+        if (typeof data[0] !== 'object' || data[0] === null) {
+            allKeys = ['(index)', 'Value'];
+            rows = data.map((v, i) => ({ '(index)': i, Value: v }));
+        }
+        else {
+            // Array of objects
+            const keySet = new Set();
+            keySet.add('(index)');
+            for (const item of data) {
+                if (item && typeof item === 'object') {
+                    Object.keys(item).forEach((k) => keySet.add(k));
+                }
+            }
+            allKeys = Array.from(keySet);
+            rows = data.map((item, i) => ({
+                '(index)': i,
+                ...(item && typeof item === 'object' ? item : { Value: item })
+            }));
+        }
+    }
+    else {
+        // Object of objects/values
+        const entries = Object.entries(data);
+        if (entries.length === 0)
+            return { keys: [], rows: [] };
+        const keySet = new Set();
+        keySet.add('(index)');
+        for (const [, val] of entries) {
+            if (val && typeof val === 'object' && !Array.isArray(val)) {
+                Object.keys(val).forEach((k) => keySet.add(k));
+            }
+            else {
+                keySet.add('Value');
+            }
+        }
+        allKeys = Array.from(keySet);
+        rows = entries.map(([key, val]) => ({
+            '(index)': key,
+            ...(val && typeof val === 'object' && !Array.isArray(val)
+                ? val
+                : { Value: val })
+        }));
+    }
+    // Apply column filter
+    if (columns && columns.length > 0) {
+        allKeys = ['(index)', ...columns.filter((c) => allKeys.includes(c))];
+    }
+    return { keys: allKeys, rows };
+}
 /**
  * Parse color string to RGB values
  * Accepts: named colors, hex (#rgb, #rrggbb), rgb(r,g,b), rgba(r,g,b,a)
@@ -499,26 +854,28 @@ Object.defineProperty(gg, '_onLog', {
 // eslint-disable-next-line @typescript-eslint/no-namespace
 (function (gg) {
 })(gg || (gg = {}));
+// Track if diagnostics have already run to prevent double execution
+let diagnosticsRan = false;
 /**
  * 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())
+    if (!ggConfig.showHints || isCloudflareWorker() || diagnosticsRan)
         return;
+    diagnosticsRan = true;
+    // Create test debugger for server-side enabled check
     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!');
+    const configOk = BROWSER ? ggConfig.enabled : ggConfig.enabled && ggLogTest.enabled;
+    if (configOk) {
         message(`No problems detected:`);
         if (BROWSER) {
-            message(`ℹ️ If gg output not visible: enable "Verbose" log level in DevTools, or check Eruda's GG tab.`);
+            message(`ℹ️ gg messages appear in the Eruda GG panel. Use Settings > Native Console to also show in browser console.`);
         }
     }
     else {
@@ -534,35 +891,27 @@ export async function runGgDiagnostics() {
         }
     }
     message(`${checkbox(ggConfig.enabled)} gg enabled: ${ggConfig.enabled}${enableHint}`);
-    if (BROWSER) {
-        const hint = makeHint(!ggLogTest.enabled, " (Try `localStorage.debug = 'gg:*'`)");
-        message(`${checkbox(ggLogTest.enabled)} localStorage.debug: ${localStorage?.debug}${hint}`);
-    }
-    else {
-        const hint = makeHint(!ggLogTest.enabled, ' (Try `DEBUG=gg:* npm dev`)');
+    if (!BROWSER) {
+        // Server-side: check DEBUG env var (the only output path on the server)
+        const hint = makeHint(!ggLogTest.enabled, ' (Try `DEBUG=gg:* npm run dev`)');
         if (dotenvModule) {
-            dotenvModule.config(); // Load the environment variables
+            dotenvModule.config();
         }
         message(`${checkbox(ggLogTest.enabled)} DEBUG env variable: ${process?.env?.DEBUG}${hint}`);
     }
-    // Optional plugin diagnostics listed last
+    // Optional plugin diagnostics
     message(makeHint(_ggCallSitesPlugin, `✅ gg-call-sites vite plugin detected! Call-site namespaces and open-in-editor links baked in at build time.`, `⚠️ gg-call-sites vite plugin not detected. Add ggCallSitesPlugin() to vite.config.ts for file:line call-site namespaces and open-in-editor links. Without plugin, using word-tuple names (e.g. calm-fox) as call-site identifiers.`));
     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
-    // 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();
-    }
+// Run diagnostics immediately on module load ONLY in Node.js environments
+// In browser, the Eruda loader (if configured) will call runGgDiagnostics()
+// after Eruda is ready. If Eruda is not configured, diagnostics won't run
+// in browser (user must manually check console or call runGgDiagnostics()).
+if (ggConfig.showHints && !isCloudflareWorker() && !BROWSER) {
+    runGgDiagnostics();
 }