@leftium/gg 0.0.47 → 0.0.49

package/dist/gg.js

@@ -41,18 +41,11 @@ if (isCloudflareWorker()) {
 }
 // Lazy-load Node.js modules to avoid top-level await (Safari compatibility).
 // The imports start immediately but don't block module evaluation.
-let dotenvModule = null;
 let httpModule = null;
 function loadServerModules() {
     if (isCloudflareWorker() || BROWSER)
         return Promise.resolve();
     return (async () => {
-        try {
-            dotenvModule = await import('dotenv');
-        }
-        catch {
-            // dotenv not available — optional dependency
-        }
         try {
             httpModule = await import('http');
         }
@@ -221,7 +214,8 @@ function openInEditorUrl(fileName, line, col) {
 }
 export function gg(...args) {
     if (!ggConfig.enabled || isCloudflareWorker()) {
-        return args.length ? args[0] : { fileName: '', functionName: '', url: '' };
+        // Return a no-op chain that skips logging
+        return new GgChain(args[0], args, { ns: '' }, true);
     }
     // Without the call-sites plugin, use cheap stack hash → deterministic word tuple.
     // When the plugin IS installed, all gg() calls are rewritten to gg._ns() at build time,
@@ -229,49 +223,166 @@ export function gg(...args) {
     // Same call site always produces the same word pair (e.g. "calm-fox").
     // depth=2: skip "Error" header [0] and gg() frame [1]
     const callpoint = resolveCallpoint(2);
-    return ggLog({ ns: callpoint }, ...args);
+    return new GgChain(args[0], args, { ns: callpoint });
 }
 /**
- * gg.ns() - Log with an explicit namespace (callpoint label).
+ * gg.here() - Return call-site info for open-in-editor.
  *
- * Users call gg.ns() directly to set a meaningful label that survives
- * 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
+ * Replaces the old no-arg gg() overload. Returns an object with the
+ * file name, function name, and URL for opening the source in an editor.
  *
  * @example
- * 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
+ * <OpenInEditorLink gg={gg.here()} />
  */
-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);
+gg.here = function () {
+    if (!ggConfig.enabled || isCloudflareWorker()) {
+        return { fileName: '', functionName: '', url: '' };
     }
-    return gg._ns({ ns: nsLabel }, ...args);
+    const callpoint = resolveCallpoint(3);
+    const namespace = `gg:${callpoint}`;
+    // Log the call-site info
+    const ggLogFunction = namespaceToLogFunction.get(namespace) ||
+        namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
+    ggLogFunction(`    📝 ${callpoint}`);
+    return {
+        fileName: callpoint,
+        functionName: callpoint.includes('@') ? callpoint.split('@').pop() || '' : '',
+        url: ''
+    };
 };
+/**
+ * Resolve template variables in a namespace label using metadata from the plugin.
+ *
+ * The Vite plugin bakes the auto-generated callpoint into options.ns at build time
+ * (e.g. "routes/+page.svelte@handleClick"). This function extracts components from
+ * that callpoint and substitutes template variables:
+ *
+ *   $NS   - the full auto-generated callpoint (or runtime word-tuple fallback)
+ *   $FN   - the function name portion (after @)
+ *   $FILE - the file path portion (before @)
+ *   $LINE - the line number
+ *   $COL  - the column number
+ */
+function resolveNsTemplateVars(label, options) {
+    if (!label.includes('$'))
+        return label;
+    const ns = options.ns || '';
+    // $NS: use the full auto-generated callpoint. If no plugin, fall back to runtime stack hash.
+    if (label.includes('$NS')) {
+        const callpoint = ns || resolveCallpoint(4);
+        label = label.replace(/\$NS/g, callpoint);
+    }
+    // $FN: extract function name from "file@fn" format
+    if (label.includes('$FN')) {
+        const fn = ns.includes('@') ? ns.split('@').pop() || '' : '';
+        label = label.replace(/\$FN/g, fn);
+    }
+    // $FILE: extract file path from "file@fn" format
+    if (label.includes('$FILE')) {
+        const file = ns.includes('@') ? ns.split('@')[0] : ns;
+        label = label.replace(/\$FILE/g, file);
+    }
+    // $LINE / $COL: from plugin metadata
+    if (label.includes('$LINE')) {
+        label = label.replace(/\$LINE/g, String(options.line ?? ''));
+    }
+    if (label.includes('$COL')) {
+        label = label.replace(/\$COL/g, String(options.col ?? ''));
+    }
+    return label;
+}
+/**
+ * Chainable wrapper returned by gg(). Collects modifiers (.ns(), .warn(), etc.)
+ * and auto-flushes the log on the next microtask. Use `.v` to flush immediately
+ * and get the passthrough value.
+ *
+ * @example
+ * gg(value)                          // logs on microtask
+ * gg(value).ns('label').warn()       // logs with namespace + warn level
+ * const x = gg(value).v              // logs immediately, returns value
+ * const x = gg(value).ns('foo').v    // logs with namespace, returns value
+ */
+export class GgChain {
+    #value;
+    #args;
+    #options;
+    #flushed = false;
+    #disabled;
+    constructor(value, args, options, disabled = false) {
+        this.#value = value;
+        this.#args = args;
+        this.#options = options;
+        this.#disabled = disabled;
+        if (!disabled) {
+            // Auto-flush on microtask if not flushed synchronously by .v or another trigger
+            queueMicrotask(() => this.#flush());
+        }
+    }
+    /** Set a custom namespace for this log entry.
+     *
+     * Supports template variables (resolved from plugin-provided metadata):
+     *   $NS   - auto-generated callpoint (file@fn with plugin, word-tuple without)
+     *   $FN   - enclosing function name (extracted from $NS)
+     *   $FILE - short file path (extracted from $NS)
+     *   $LINE - line number
+     *   $COL  - column number
+     */
+    ns(label) {
+        this.#options.ns = resolveNsTemplateVars(label, this.#options);
+        return this;
+    }
+    /** Set log level to info (blue indicator). */
+    info() {
+        this.#options.level = 'info';
+        return this;
+    }
+    /** Set log level to warn (yellow indicator). */
+    warn() {
+        this.#options.level = 'warn';
+        return this;
+    }
+    /** Set log level to error (red indicator, captures stack trace). */
+    error() {
+        this.#options.level = 'error';
+        this.#options.stack = getErrorStack(this.#args[0], 3);
+        return this;
+    }
+    /** Include a full stack trace with this log entry. */
+    trace() {
+        this.#options.stack = captureStack(3);
+        return this;
+    }
+    /** Format the log output as an ASCII table. */
+    table(columns) {
+        const { keys, rows } = formatTable(this.#args[0], columns);
+        this.#options.tableData = { keys, rows };
+        // Override args to show '(table)' label, matching original gg.table() behavior
+        this.#args = ['(table)'];
+        // Also emit native console.table
+        if (columns) {
+            console.table(this.#value, columns);
+        }
+        else {
+            console.table(this.#value);
+        }
+        return this;
+    }
+    /** Flush the log immediately and return the passthrough value. */
+    get v() {
+        this.#flush();
+        return this.#value;
+    }
+    #flush() {
+        if (this.#flushed)
+            return;
+        this.#flushed = true;
+        ggLog(this.#options, ...this.#args);
+    }
+}
 /**
  * Core logging function shared by all gg methods.
  *
- * 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.
+ * Handles namespace resolution, debug output, capture hook, and return value.
  */
 function ggLog(options, ...args) {
     const { ns: nsLabel, file, line, col, src, level, stack, tableData } = options;
@@ -286,24 +397,7 @@ function ggLog(options, ...args) {
         namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
     // Prepare args for logging (console output is value-only; src is carried
     // on CapturedEntry for the Eruda UI to display on hover)
-    let logArgs;
-    let returnValue;
-    if (!args.length) {
-        // No arguments: return call-site info for open-in-editor
-        const fileName = file ? file.replace(srcRootRegex, '') : nsLabel;
-        const functionName = nsLabel.includes('@') ? nsLabel.split('@').pop() || '' : '';
-        const url = file ? openInEditorUrl(file, line, col) : '';
-        logArgs = [`    📝 ${nsLabel}`];
-        returnValue = { fileName, functionName, url };
-    }
-    else if (args.length === 1) {
-        logArgs = [args[0]];
-        returnValue = args[0];
-    }
-    else {
-        logArgs = [args[0], ...args.slice(1)];
-        returnValue = args[0];
-    }
+    const logArgs = args.length === 0 ? ['(no args)'] : [...args];
     // Add level prefix emoji for info/warn/error
     if (level === 'info') {
         logArgs[0] = `ℹ️ ${logArgs[0]}`;
@@ -351,22 +445,39 @@ function ggLog(options, ...args) {
     else {
         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
+ * Called by the ggCallSitesPlugin Vite plugin, which rewrites bare gg()
+ * calls to gg._ns({ns, file, line, col, src}, ...) 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
+ * Returns a GgChain for chaining modifiers (.ns(), .warn(), etc.)
  */
 gg._ns = function (options, ...args) {
-    return ggLog(options, ...args);
+    const disabled = !ggConfig.enabled || isCloudflareWorker();
+    return new GgChain(args[0], args, options, disabled);
+};
+/**
+ * gg._here() - Internal: call-site info with source metadata from Vite plugin.
+ *
+ * Called by the ggCallSitesPlugin when it rewrites gg.here() calls.
+ */
+gg._here = function (options) {
+    if (!ggConfig.enabled || isCloudflareWorker()) {
+        return { fileName: '', functionName: '', url: '' };
+    }
+    const { ns: nsLabel, file, line, col } = options;
+    const namespace = `gg:${nsLabel}`;
+    const ggLogFunction = namespaceToLogFunction.get(namespace) ||
+        namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
+    ggLogFunction(`    📝 ${nsLabel}`);
+    const fileName = file ? file.replace(srcRootRegex, '') : nsLabel;
+    const functionName = nsLabel.includes('@') ? nsLabel.split('@').pop() || '' : '';
+    const url = file ? openInEditorUrl(file, line, col) : '';
+    return { fileName, functionName, url };
 };
 /**
  * gg._o() - Internal: build options object for gg._ns() without object literal syntax.
@@ -423,181 +534,66 @@ function getErrorStack(firstArg, skipFrames) {
     }
     return captureStack(skipFrames);
 }
+// Timer storage for gg.time / gg.timeEnd / gg.timeLog
+// Maps timer label → { start: number, ns?: string, options?: LogOptions }
+const timers = new Map();
 /**
- * gg.info() - Log at info level.
- *
- * Passthrough: returns the first argument.
- * In Eruda, entries are styled with a blue/info indicator.
- *
- * @example
- * gg.info('System startup complete');
- * const config = gg.info(loadedConfig, 'loaded config');
- */
-gg.info = function (...args) {
-    if (!ggConfig.enabled || isCloudflareWorker()) {
-        return args.length ? args[0] : undefined;
-    }
-    const callpoint = resolveCallpoint(3);
-    return ggLog({ ns: callpoint, level: 'info' }, ...args);
-};
-/**
- * gg._info() - Internal: info with call-site metadata from Vite plugin.
- */
-gg._info = function (options, ...args) {
-    return ggLog({ ...options, level: 'info' }, ...args);
-};
-/**
- * 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.
+ * Chainable wrapper returned by gg.time(). Only supports .ns() for setting
+ * the namespace for the entire timer group (inherited by timeLog/timeEnd).
  *
  * @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);
+ * gg.time('fetch').ns('api-pipeline')
+ * gg.time('fetch').ns('$FN:timers')    // template vars work too
+ */
+export class GgTimerChain {
+    #label;
+    #options;
+    constructor(label, options) {
+        this.#label = label;
+        this.#options = options;
+    }
+    /** Set a custom namespace for this timer group.
+     * Supports the same template variables as GgChain.ns().
+     */
+    ns(label) {
+        const resolved = resolveNsTemplateVars(label, this.#options);
+        const timer = timers.get(this.#label);
+        if (timer)
+            timer.ns = resolved;
+        return this;
     }
-    return condition;
-};
+}
 /**
- * gg.table() - Log tabular data.
+ * gg.time() - Start a named timer. Returns a GgTimerChain for optional .ns() chaining.
  *
- * Formats an array of objects (or an object of objects) as an ASCII table.
- * Passthrough: returns the data argument.
+ * @param label - Timer label (default: 'default')
  *
  * @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('fetch')                     // basic timer
+ * gg.time('fetch').ns('api-pipeline')  // with namespace (inherited by timeLog/timeEnd)
+ * gg.time('fetch').ns('$FN:timers')    // with template variable (plugin)
  */
 gg.time = function (label = 'default') {
-    if (!ggConfig.enabled || isCloudflareWorker())
-        return;
-    timers.set(label, performance.now());
+    const options = { ns: resolveCallpoint(3) };
+    if (ggConfig.enabled && !isCloudflareWorker()) {
+        timers.set(label, { start: performance.now(), options });
+    }
+    return new GgTimerChain(label, options);
 };
 /** 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._time = function (options, label = 'default') {
+    if (ggConfig.enabled && !isCloudflareWorker()) {
+        timers.set(label, { start: performance.now(), options });
+    }
+    return new GgTimerChain(label, options);
 };
 /**
  * gg.timeLog() - Log the current elapsed time without stopping the timer.
  *
+ * Inherits the namespace set by gg.time().ns() for this timer label.
+ *
  * @example
- * gg.time('process');
+ * gg.time('process').ns('my-namespace');
  * // ... step 1 ...
  * gg.timeLog('process', 'step 1 done');
  * // ... step 2 ...
@@ -606,92 +602,66 @@ gg._time = function (_options, label = 'default') {
 gg.timeLog = function (label = 'default', ...args) {
     if (!ggConfig.enabled || isCloudflareWorker())
         return;
-    const start = timers.get(label);
-    if (start === undefined) {
+    const timer = timers.get(label);
+    if (timer === 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);
+    const elapsed = performance.now() - timer.start;
+    const ns = timer.ns ?? timer.options?.ns ?? resolveCallpoint(3);
+    ggLog({ ...timer.options, ns }, `${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) {
+    const timer = timers.get(label);
+    if (timer === undefined) {
         ggLog({ ...options, level: 'warn' }, `Timer '${label}' does not exist`);
         return;
     }
-    const elapsed = performance.now() - start;
-    ggLog(options, `${label}: ${formatElapsed(elapsed)}`, ...args);
+    const elapsed = performance.now() - timer.start;
+    const ns = timer.ns ?? timer.options?.ns ?? options.ns;
+    ggLog({ ...options, ns }, `${label}: ${formatElapsed(elapsed)}`, ...args);
 };
 /**
  * gg.timeEnd() - Stop a named timer and log the elapsed time.
  *
+ * Inherits the namespace set by gg.time().ns() for this timer label.
+ *
  * @example
- * gg.time('fetch');
+ * gg.time('fetch').ns('api-pipeline');
  * const data = await fetchData();
- * gg.timeEnd('fetch'); // logs "fetch: 456.12ms"
+ * gg.timeEnd('fetch'); // logs under 'api-pipeline' namespace
  */
 gg.timeEnd = function (label = 'default') {
     if (!ggConfig.enabled || isCloudflareWorker())
         return;
-    const start = timers.get(label);
-    if (start === undefined) {
+    const timer = timers.get(label);
+    if (timer === undefined) {
         const callpoint = resolveCallpoint(3);
         ggLog({ ns: callpoint, level: 'warn' }, `Timer '${label}' does not exist`);
         return;
     }
-    const elapsed = performance.now() - start;
+    const elapsed = performance.now() - timer.start;
     timers.delete(label);
-    const callpoint = resolveCallpoint(3);
-    ggLog({ ns: callpoint }, `${label}: ${formatElapsed(elapsed)}`);
+    const ns = timer.ns ?? timer.options?.ns ?? resolveCallpoint(3);
+    ggLog({ ...timer.options, ns }, `${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) {
+    const timer = timers.get(label);
+    if (timer === undefined) {
         ggLog({ ...options, level: 'warn' }, `Timer '${label}' does not exist`);
         return;
     }
-    const elapsed = performance.now() - start;
+    const elapsed = performance.now() - timer.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);
+    const ns = timer.ns ?? timer.options?.ns ?? options.ns;
+    ggLog({ ...options, ns }, `${label}: ${formatElapsed(elapsed)}`);
 };
 /**
  * Format elapsed time with appropriate precision.
@@ -986,7 +956,7 @@ export async function runGgDiagnostics() {
     if (!ggConfig.showHints || isCloudflareWorker() || diagnosticsRan)
         return;
     diagnosticsRan = true;
-    // Ensure server modules (dotenv) and debug factory are loaded before diagnostics
+    // Ensure server modules and debug factory are loaded before diagnostics
     await serverModulesReady;
     await debugReady;
     // Create test debugger for server-side enabled check
@@ -1018,10 +988,7 @@ export async function runGgDiagnostics() {
     message(`${checkbox(ggConfig.enabled)} gg enabled: ${ggConfig.enabled}${enableHint}`);
     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();
-        }
+        const hint = makeHint(!ggLogTest.enabled, ' (Try `DEBUG=gg:* npm run dev` or use --env-file=.env)');
         message(`${checkbox(ggLogTest.enabled)} DEBUG env variable: ${process?.env?.DEBUG}${hint}`);
     }
     // Optional plugin diagnostics

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { gg, fg, bg, bold, italic, underline, dim } from './gg.js';
+import { gg, GgChain, GgTimerChain, fg, bg, bold, italic, underline, dim } from './gg.js';
 import openInEditorPlugin from './open-in-editor.js';
 import ggCallSitesPlugin from './gg-call-sites-plugin.js';
 export { default as GgConsole } from './GgConsole.svelte';
-export { gg, fg, bg, bold, italic, underline, dim, openInEditorPlugin, ggCallSitesPlugin };
+export { gg, GgChain, GgTimerChain, fg, bg, bold, italic, underline, dim, openInEditorPlugin, ggCallSitesPlugin };