@leftium/gg 0.0.47 → 0.0.48

package/README.md

@@ -6,7 +6,8 @@
   - Each namespace gets a unique color for easier visual parsing.
   - Simple syntax with wildcards to filter/hide debug output at runtime.
   - Millisecond diff (timestamps) for each namespace.
-- Can be inserted into the middle of expressions (returns the value of the first argument).
+- Chainable API: `.ns()`, `.warn()`, `.error()`, `.info()`, `.trace()`, `.table()`.
+- Can be inserted into the middle of expressions (use `.v` to get the passthrough value).
 - Can output a link that opens the source file in your editor (like VS Code).
 - Simple to disable (turn all loggs into NOP's for production).
 - Diagnostics/hints in dev console & terminal to help install and configure correctly.
@@ -28,8 +29,12 @@ npm add @leftium/gg
 
 	gg('Hello world');
 
-	// Log expressions (returns first argument)
-	const result = gg(someFunction());
+	// Log with modifiers
+	gg('Connection timeout').warn();
+	gg('User authenticated', user).info();
+
+	// Passthrough with .v (returns the first argument)
+	const result = gg(someFunction()).v;
 
 	// Multiple arguments
 	gg('User:', user, 'Status:', status);
@@ -57,11 +62,10 @@ export default defineConfig({
 
 - **Call-sites plugin** -- rewrites `gg()` calls with source file/line/col metadata
 - **Open-in-editor plugin** -- adds dev server middleware for click-to-open
-- **Automatic `es2022` target** -- required for top-level await
 
 ### 3. Add the debug console (optional, recommended)
 
-An in-browser debug console (powered by Eruda) with a dedicated GG tab for filtering and inspecting logs — especially useful on mobile.
+An in-browser debug console (powered by Eruda) with a dedicated GG tab for filtering and inspecting logs -- especially useful on mobile.
 
 ```svelte
 <!-- src/routes/+layout.svelte -->
@@ -76,6 +80,173 @@ An in-browser debug console (powered by Eruda) with a dedicated GG tab for filte
 In development, the debug console appears automatically.
 In production, add `?gg` to the URL or use a 5-tap gesture to activate.
 
+## Chaining API
+
+`gg()` returns a `GgChain<T>` with composable modifiers. Chain any combination, in any order. The log auto-flushes on the next microtask, or use `.v` to flush immediately and get the passthrough value.
+
+```javascript
+import { gg } from '@leftium/gg';
+
+// Basic logging (auto-flushes on microtask)
+gg('hello');
+gg('multiple', 'args', { data: 42 });
+
+// Passthrough with .v (flushes immediately, returns first arg)
+const result = gg(computeValue()).v;
+const user = gg(await fetchUser()).ns('api').v;
+
+// Log levels
+gg('System ready').info(); // blue indicator
+gg('Deprecated API call').warn(); // yellow indicator
+gg('Connection failed').error(); // red indicator + stack trace
+
+// Custom namespace
+gg('Processing request').ns('api:handler');
+
+// Stack trace
+gg('Debug checkpoint').trace();
+
+// Table formatting (also emits native console.table)
+gg(arrayOfObjects).table();
+gg(data).table(['name', 'age']); // filter columns
+
+// Combine modifiers freely
+gg('Slow query', { ms: 3200 }).ns('db').warn();
+const rows = gg(queryResult).ns('db:query').table().v;
+```
+
+### `.v` -- Passthrough
+
+Use `.v` at the end of any chain to flush the log immediately and return the first argument. This lets you insert `gg()` into the middle of expressions:
+
+```javascript
+// Without .v: logs on microtask, returns GgChain (not the value!)
+gg(someValue);
+
+// With .v: logs immediately, returns someValue
+const x = gg(someValue).v;
+const y = gg(compute()).ns('math').warn().v;
+
+// Insert into expressions
+processData(gg(inputData).v);
+return gg(result).ns('output').v;
+```
+
+### `.ns(label)` -- Custom Namespace
+
+Override the auto-generated namespace (file@function) with a custom label. Useful for grouping related logs across files:
+
+```javascript
+gg('Request received').ns('api:incoming');
+gg('Response sent').ns('api:outgoing');
+gg('Cache hit').ns('api:cache');
+```
+
+Namespace labels support **template variables** that resolve from plugin-provided metadata:
+
+| Variable | Description                   | Example                           |
+| -------- | ----------------------------- | --------------------------------- |
+| `$NS`    | Full auto-generated callpoint | `routes/+page.svelte@handleClick` |
+| `$FN`    | Enclosing function name       | `handleClick`                     |
+| `$FILE`  | Source file path              | `routes/+page.svelte`             |
+| `$LINE`  | Line number                   | `42`                              |
+| `$COL`   | Column number                 | `3`                               |
+
+```javascript
+gg('debug info').ns('ERROR:$NS'); // → ERROR:routes/+page.svelte@handleClick
+gg('validation').ns('$FILE:validate'); // → routes/+page.svelte:validate
+gg('step 1').ns('TRACE:$FN'); // → TRACE:handleClick
+gg('context').ns('$NS:debug'); // → routes/+page.svelte@handleClick:debug
+```
+
+Without the Vite plugin, `$NS` falls back to a runtime word-tuple (e.g. `calm-fox`). `$FN`, `$FILE`, `$LINE`, and `$COL` require the plugin.
+
+### `.info()` / `.warn()` / `.error()` -- Log Levels
+
+```javascript
+gg('Server started on port 3000').info(); // blue badge
+gg('Rate limit approaching').warn(); // yellow badge
+gg('Unhandled exception').error(); // red badge + captures stack
+
+// .error() with an Error object uses its .stack
+try {
+	riskyOperation();
+} catch (err) {
+	gg(err).error();
+}
+```
+
+### `.trace()` -- Stack Trace
+
+Captures a full stack trace (cleaned of internal gg frames) alongside the log entry:
+
+```javascript
+gg('How did we get here?').trace();
+```
+
+### `.table(columns?)` -- Table Formatting
+
+Formats the first argument as a table. Also emits a native `console.table()` call. Optionally filter columns:
+
+```javascript
+gg([
+	{ name: 'Alice', age: 30, role: 'admin' },
+	{ name: 'Bob', age: 25, role: 'user' }
+]).table();
+
+// Filter columns
+gg(users).table(['name', 'role']);
+
+// Works with objects-of-objects and arrays of primitives too
+gg({ us: { pop: '331M' }, uk: { pop: '67M' } }).table();
+gg(['apple', 'banana', 'cherry']).table();
+```
+
+## Timers
+
+Measure elapsed time with `gg.time()`, `gg.timeLog()`, and `gg.timeEnd()`:
+
+```javascript
+import { gg } from '@leftium/gg';
+
+gg.time('fetch');
+
+// ... some work ...
+gg.timeLog('fetch', 'headers received'); // logs elapsed without stopping
+
+// ... more work ...
+gg.timeEnd('fetch'); // logs elapsed and stops timer
+```
+
+### Timer Namespaces
+
+`gg.time()` returns a `GgTimerChain` that supports `.ns()` for grouping. The namespace is inherited by subsequent `timeLog` and `timeEnd` calls for the same label:
+
+```javascript
+gg.time('fetch').ns('api-pipeline');
+
+gg.timeLog('fetch', 'step 1 done'); // logged under 'api-pipeline'
+gg.timeEnd('fetch'); // logged under 'api-pipeline'
+
+// Template variables work too
+gg.time('db-query').ns('$FN:timers');
+```
+
+## `gg.here()` -- Open in Editor
+
+Returns call-site metadata for rendering "open in editor" links. Replaces the old no-arg `gg()` introspection.
+
+```svelte
+<script>
+	import { gg } from '@leftium/gg';
+</script>
+
+<!-- Pass to a link component -->
+<OpenInEditorLink gg={gg.here()} />
+```
+
+Returns `{ fileName, functionName, url }` where `url` points to the dev server's open-in-editor endpoint.
+
 ## GgConsole Options
 
 ```svelte
@@ -226,6 +397,40 @@ initGgEruda();
 gg('works in any framework');
 ```
 
+## API Reference
+
+### `gg(value, ...args)` -- Returns `GgChain<T>`
+
+| Method / Property | Description                                   |
+| ----------------- | --------------------------------------------- |
+| `.v`              | Flush log immediately, return first argument  |
+| `.ns(label)`      | Set custom namespace (supports template vars) |
+| `.info()`         | Set log level to info                         |
+| `.warn()`         | Set log level to warn                         |
+| `.error()`        | Set log level to error (captures stack)       |
+| `.trace()`        | Attach full stack trace                       |
+| `.table(cols?)`   | Format as table, optional column filter       |
+
+### `gg.time(label?)` -- Returns `GgTimerChain`
+
+| Method       | Description                               |
+| ------------ | ----------------------------------------- |
+| `.ns(label)` | Set namespace for timer group (inherited) |
+
+### `gg.timeLog(label?, ...args)` -- Log elapsed without stopping
+
+### `gg.timeEnd(label?)` -- Log elapsed and stop timer
+
+### `gg.here()` -- Returns `{ fileName, functionName, url }`
+
+### Control
+
+| Method              | Description                               |
+| ------------------- | ----------------------------------------- |
+| `gg.enable(ns)`     | Enable debug output for namespace pattern |
+| `gg.disable()`      | Disable all debug output                  |
+| `gg.clearPersist()` | Clear `gg-enabled` from localStorage      |
+
 ## Technical Details
 
 ### Internal Debug Implementation
@@ -248,6 +453,20 @@ Features implemented internally (~290 lines of TypeScript):
 
 This approach eliminates the need for vendoring, patching, and bundling third-party code, resulting in better type safety and simpler maintenance.
 
+### Microtask Auto-Flush
+
+When you call `gg(value)`, the log is **deferred to the next microtask**. This means chain modifiers (`.ns()`, `.warn()`, etc.) can be added synchronously after the call. If you need the value immediately (passthrough), use `.v` which forces an immediate flush.
+
+```javascript
+// These two are equivalent:
+gg('hello').warn(); // .warn() runs sync, log flushes on microtask
+gg('hello').warn().v; // .v forces immediate flush + returns 'hello'
+
+// Auto-flush means order doesn't matter for modifiers:
+gg('x').ns('foo').warn(); // same as:
+gg('x').warn().ns('foo'); // (both set ns and level before flush)
+```
+
 ## Inspirations
 
 ### debug

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

@@ -90,16 +90,19 @@ export declare function findEnclosingFunctionFromScopes(pos: number, scopes: Fun
  */
 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.
+ * Transform gg() calls in source code to inject call-site metadata.
  *
  * 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.here() → gg._here({ns, file, line, col})
+ * - gg.time/timeLog/timeEnd → gg._time/_timeLog/_timeEnd with metadata
+ * - gg.enable, gg.disable, gg.clearPersist, gg._ns, gg._onLog → left untouched
  * - gg inside strings and comments → left untouched
  *
+ * Chain methods (.ns(), .warn(), .error(), etc.) are NOT rewritten —
+ * they run at runtime and resolve template variables from the metadata
+ * that the plugin baked into the gg._ns() options object.
+ *
  * 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()`

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

@@ -47,13 +47,7 @@ export default function ggCallSitesPlugin(options = {}) {
                 return null;
             // Quick bail: no gg calls in this file
             if (!code.includes('gg(') &&
-                !code.includes('gg.ns(') &&
-                !code.includes('gg.info(') &&
-                !code.includes('gg.warn(') &&
-                !code.includes('gg.error(') &&
-                !code.includes('gg.table(') &&
-                !code.includes('gg.trace(') &&
-                !code.includes('gg.assert(') &&
+                !code.includes('gg.here(') &&
                 !code.includes('gg.time(') &&
                 !code.includes('gg.timeLog(') &&
                 !code.includes('gg.timeEnd('))
@@ -590,16 +584,19 @@ export function escapeForString(s) {
     return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n').replace(/\r/g, '\\r');
 }
 /**
- * Transform gg() and gg.ns() calls in source code to gg._ns({ns, file, line, col, src}, ...) calls.
+ * Transform gg() calls in source code to inject call-site metadata.
  *
  * 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.here() → gg._here({ns, file, line, col})
+ * - gg.time/timeLog/timeEnd → gg._time/_timeLog/_timeEnd with metadata
+ * - gg.enable, gg.disable, gg.clearPersist, gg._ns, gg._onLog → left untouched
  * - gg inside strings and comments → left untouched
  *
+ * Chain methods (.ns(), .warn(), .error(), etc.) are NOT rewritten —
+ * they run at runtime and resolve template variables from the metadata
+ * that the plugin baked into the gg._ns() options object.
+ *
  * 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()`
@@ -720,7 +717,7 @@ export function transformGgCalls(code, shortPath, filePath, svelteInfo, jsFuncti
                 continue;
             }
         }
-        // Look for 'gg' pattern — could be gg( or gg.ns(
+        // Look for 'gg' pattern — could be gg( or gg.here( or gg.time(
         if (code[i] === 'g' && code[i + 1] === 'g') {
             // In .svelte files, skip gg outside code ranges (prose text, etc.)
             const range = rangeAt(i);
@@ -734,83 +731,22 @@ export function transformGgCalls(code, shortPath, filePath, svelteInfo, jsFuncti
                 i++;
                 continue;
             }
-            // Case 1: gg.ns('label', ...) → gg._ns({ns: 'label', file, line, col, src}, ...)
-            if (code.slice(i + 2, i + 6) === '.ns(') {
+            // Case 1: gg.here() → gg._here({ns, file, line, col})
+            if (code.slice(i + 2, i + 9) === '.here()') {
                 const { line, col } = getLineCol(code, i);
                 const fnName = getFunctionName(i, range);
-                const openParenPos = i + 5; // position of '(' in 'gg.ns('
-                // Find matching closing paren for the entire gg.ns(...) call
-                const closeParenPos = findMatchingParen(code, openParenPos);
-                if (closeParenPos === -1) {
-                    i += 6;
-                    continue;
-                }
-                // Extract the first argument (the namespace string)
-                // Look for the string literal after 'gg.ns('
-                let afterNsParen = i + 6; // position after 'gg.ns('
-                while (afterNsParen < code.length && /\s/.test(code[afterNsParen]))
-                    afterNsParen++;
-                const quoteChar = code[afterNsParen];
-                if (quoteChar === "'" || quoteChar === '"') {
-                    // Find the closing quote
-                    let j = afterNsParen + 1;
-                    while (j < code.length && code[j] !== quoteChar) {
-                        if (code[j] === '\\')
-                            j++; // skip escaped chars
-                        j++;
-                    }
-                    // j now points to closing quote
-                    const nsLabelRaw = code.slice(afterNsParen + 1, j);
-                    // Build callpoint: substitute $NS/$FN/$FILE/$LINE/$COL template variables.
-                    // The auto-generated callpoint (file@fn) is what bare gg() would produce.
-                    const autoCallpoint = `${shortPath}${fnName ? `@${fnName}` : ''}`;
-                    const callpoint = escapeForString(nsLabelRaw
-                        .replace(/\$NS/g, autoCallpoint)
-                        .replace(/\$FN/g, fnName)
-                        .replace(/\$FILE/g, shortPath)
-                        .replace(/\$LINE/g, String(line))
-                        .replace(/\$COL/g, String(col)));
-                    // Check if there are more args after the string
-                    const afterClosingQuote = j + 1;
-                    let k = afterClosingQuote;
-                    while (k < code.length && /\s/.test(code[k]))
-                        k++;
-                    if (code[k] === ')') {
-                        // gg.ns('label') → gg._ns(opts)
-                        result.push(code.slice(lastIndex, i));
-                        result.push(`gg._ns(${buildOptions(range, callpoint, line, col)})`);
-                        lastIndex = k + 1;
-                        i = k + 1;
-                    }
-                    else if (code[k] === ',') {
-                        // gg.ns('label', args...) → gg._ns(opts, args...)
-                        let argsStart = k + 1;
-                        while (argsStart < closeParenPos && /\s/.test(code[argsStart]))
-                            argsStart++;
-                        const argsSrc = code.slice(argsStart, closeParenPos).trim();
-                        const escapedSrc = escapeForString(argsSrc);
-                        result.push(code.slice(lastIndex, i));
-                        result.push(`gg._ns(${buildOptions(range, callpoint, line, col, escapedSrc)}, `);
-                        lastIndex = k + 1; // skip past the comma, keep args as-is
-                        i = k + 1;
-                    }
-                    else {
-                        // Unexpected — leave untouched
-                        i += 6;
-                        continue;
-                    }
-                    modified = true;
-                    continue;
-                }
-                // Non-string first arg to gg.ns — skip (can't extract ns at build time)
-                i += 6;
+                const callpoint = `${shortPath}${fnName ? `@${fnName}` : ''}`;
+                const escapedNs = escapeForString(callpoint);
+                result.push(code.slice(lastIndex, i));
+                result.push(`gg._here(${buildOptions(range, escapedNs, line, col)})`);
+                lastIndex = i + 9; // skip past 'gg.here()'
+                i = lastIndex;
+                modified = true;
                 continue;
             }
-            // Case 1b: gg.info/warn/error/table/trace/assert → gg._info/_warn/_error/_table/_trace/_assert
-            // These methods are rewritten like bare gg() but with their internal variant.
-            const dotMethodMatch = code
-                .slice(i + 2)
-                .match(/^\.(info|warn|error|table|trace|assert|time|timeLog|timeEnd)\(/);
+            // Case 2: gg.time/timeLog/timeEnd → gg._time/_timeLog/_timeEnd
+            // Timer methods are rewritten to inject call-site metadata.
+            const dotMethodMatch = code.slice(i + 2).match(/^\.(time|timeLog|timeEnd)\(/);
             if (dotMethodMatch) {
                 const methodName = dotMethodMatch[1];
                 const internalName = `_${methodName}`;
@@ -828,13 +764,13 @@ export function transformGgCalls(code, shortPath, filePath, svelteInfo, jsFuncti
                 const argsText = code.slice(openParenPos + 1, closeParenPos).trim();
                 result.push(code.slice(lastIndex, i));
                 if (argsText === '') {
-                    // gg.warn() → gg._warn(opts)
+                    // gg.time() → gg._time(opts)
                     result.push(`gg.${internalName}(${buildOptions(range, escapedNs, line, col)})`);
                     lastIndex = closeParenPos + 1;
                     i = closeParenPos + 1;
                 }
                 else {
-                    // gg.warn(expr) → gg._warn(opts, expr)
+                    // gg.time('label') → gg._time(opts, 'label')
                     const escapedSrc = escapeForString(argsText);
                     result.push(`gg.${internalName}(${buildOptions(range, escapedNs, line, col, escapedSrc)}, `);
                     lastIndex = openParenPos + 1; // keep original args
@@ -843,12 +779,12 @@ export function transformGgCalls(code, shortPath, filePath, svelteInfo, jsFuncti
                 modified = true;
                 continue;
             }
-            // Skip other gg.* calls (gg.enable, gg.disable, gg._ns, gg._onLog, gg.time, etc.)
+            // Skip other gg.* calls (gg.enable, gg.disable, gg._ns, gg._onLog, etc.)
             if (code[i + 2] === '.') {
                 i += 3;
                 continue;
             }
-            // Case 2: bare gg(...) → gg._ns({ns, file, line, col, src}, ...)
+            // Case 3: bare gg(...) → gg._ns({ns, file, line, col, src}, ...)
             if (code[i + 2] === '(') {
                 const { line, col } = getLineCol(code, i);
                 const fnName = getFunctionName(i, range);

package/dist/gg.d.ts

@@ -21,16 +21,91 @@ interface CapturedEntry {
     };
 }
 type OnLogCallback = (entry: CapturedEntry) => void;
-export declare function gg(): {
-    fileName: string;
-    functionName: string;
-    url: string;
-};
-export declare function gg<T>(arg: T, ...args: unknown[]): T;
-export declare namespace gg {
-    var disable: () => string;
-    var enable: (ns: string) => void;
-    var clearPersist: () => void;
+/**
+ * Log a value and return a chainable wrapper.
+ *
+ * Chain modifiers to configure the log entry:
+ * - `.ns('label')` — set a custom namespace
+ * - `.warn()` / `.error()` / `.info()` — set log level
+ * - `.trace()` — include stack trace
+ * - `.table()` — format as ASCII table
+ * - `.v` — flush immediately and return the passthrough value
+ *
+ * Without `.v`, the log auto-flushes on the next microtask.
+ *
+ * @example
+ * gg(value)                          // log with auto namespace
+ * gg(value).ns('label').warn()       // log with namespace + warn level
+ * const x = gg(value).v              // passthrough
+ * const x = gg(value).ns('foo').v    // passthrough with namespace
+ */
+export declare function gg<T>(arg: T, ...args: unknown[]): GgChain<T>;
+/** Internal options for the core log function */
+interface LogOptions {
+    ns: string;
+    file?: string;
+    line?: number;
+    col?: number;
+    src?: string;
+    level?: LogLevel;
+    stack?: string;
+    tableData?: {
+        keys: string[];
+        rows: Array<Record<string, unknown>>;
+    };
+}
+/**
+ * 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 declare class GgChain<T> {
+    #private;
+    constructor(value: T, args: unknown[], options: LogOptions, disabled?: boolean);
+    /** 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: string): GgChain<T>;
+    /** Set log level to info (blue indicator). */
+    info(): GgChain<T>;
+    /** Set log level to warn (yellow indicator). */
+    warn(): GgChain<T>;
+    /** Set log level to error (red indicator, captures stack trace). */
+    error(): GgChain<T>;
+    /** Include a full stack trace with this log entry. */
+    trace(): GgChain<T>;
+    /** Format the log output as an ASCII table. */
+    table(columns?: string[]): GgChain<T>;
+    /** Flush the log immediately and return the passthrough value. */
+    get v(): T;
+}
+/**
+ * Chainable wrapper returned by gg.time(). Only supports .ns() for setting
+ * the namespace for the entire timer group (inherited by timeLog/timeEnd).
+ *
+ * @example
+ * gg.time('fetch').ns('api-pipeline')
+ * gg.time('fetch').ns('$FN:timers')    // template vars work too
+ */
+export declare class GgTimerChain {
+    #private;
+    constructor(label: string, options: LogOptions);
+    /** Set a custom namespace for this timer group.
+     * Supports the same template variables as GgChain.ns().
+     */
+    ns(label: string): GgTimerChain;
 }
 /**
  * ANSI Color Helpers for gg()
@@ -134,7 +209,6 @@ export declare function underline(): ChainableColorFn;
 export declare function dim(): ChainableColorFn;
 export declare namespace gg {
     let _onLog: OnLogCallback | null;
-    let ns: (nsLabel: string, ...args: unknown[]) => unknown;
     let _ns: (options: {
         ns: string;
         file?: string;
@@ -143,7 +217,7 @@ export declare namespace gg {
         src?: string;
         level?: LogLevel;
         stack?: string;
-    }, ...args: unknown[]) => unknown;
+    }, ...args: unknown[]) => GgChain<unknown>;
     let _o: (ns: string, file?: string, line?: number, col?: number, src?: string) => {
         ns: string;
         file?: string;
@@ -151,64 +225,34 @@ export declare namespace gg {
         col?: number;
         src?: string;
     };
-    let info: (...args: unknown[]) => unknown;
-    let warn: (...args: unknown[]) => unknown;
-    let error: (...args: unknown[]) => unknown;
-    let assert: (condition: unknown, ...args: unknown[]) => unknown;
-    let table: (data: unknown, columns?: string[]) => unknown;
-    let time: (label?: string) => void;
-    let timeLog: (label?: string, ...args: unknown[]) => void;
-    let timeEnd: (label?: string) => void;
-    let trace: (...args: unknown[]) => unknown;
-    let _info: (options: {
-        ns: string;
-        file?: string;
-        line?: number;
-        col?: number;
-        src?: string;
-    }, ...args: unknown[]) => unknown;
-    let _warn: (options: {
-        ns: string;
-        file?: string;
-        line?: number;
-        col?: number;
-        src?: string;
-    }, ...args: unknown[]) => unknown;
-    let _error: (options: {
-        ns: string;
-        file?: string;
-        line?: number;
-        col?: number;
-        src?: string;
-    }, ...args: unknown[]) => unknown;
-    let _assert: (options: {
-        ns: string;
-        file?: string;
-        line?: number;
-        col?: number;
-        src?: string;
-    }, condition: unknown, ...args: unknown[]) => unknown;
-    let _table: (options: {
-        ns: string;
-        file?: string;
-        line?: number;
-        col?: number;
-        src?: string;
-    }, data: unknown, columns?: string[]) => unknown;
-    let _trace: (options: {
+    let here: () => {
+        fileName: string;
+        functionName: string;
+        url: string;
+    };
+    let _here: (options: {
         ns: string;
         file?: string;
         line?: number;
         col?: number;
-        src?: string;
-    }, ...args: unknown[]) => unknown;
+    }) => {
+        fileName: string;
+        functionName: string;
+        url: string;
+    };
+    let enable: (ns: string) => void;
+    let disable: () => string;
+    let clearPersist: () => void;
+    let time: (label?: string) => GgTimerChain;
+    let timeLog: (label?: string, ...args: unknown[]) => void;
+    let timeEnd: (label?: string) => void;
     let _time: (options: {
         ns: string;
         file?: string;
         line?: number;
         col?: number;
         src?: string;
-    }, label?: string) => void;
+    }, label?: string) => GgTimerChain;
     let _timeLog: (options: {
         ns: string;
         file?: string;

package/dist/gg.js

@@ -221,7 +221,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 +230,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).
- *
- * 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)
+ * gg.here() - Return call-site info for open-in-editor.
  *
- * @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 +404,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 +452,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 +541,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.
- *
- * @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.
+ * @param label - Timer label (default: 'default')
  *
  * @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 +609,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.

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 };

package/dist/index.js

@@ -1,6 +1,6 @@
 // Reexport your entry components here
-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 };

package/package.json

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