@leftium/gg 0.0.49 → 0.0.51

package/README.md

@@ -273,16 +273,122 @@ import ggPlugins from '@leftium/gg/vite';
 
 ggPlugins({
 	callSites: { srcRootPattern: '.*?(/src/)' },
-	openInEditor: false // disable open-in-editor middleware
+	openInEditor: false, // disable open-in-editor middleware
+	fileSink: true // write all gg() calls to .gg/logs-{port}.jsonl (for coding agents)
 });
 ```
 
+| Option         | Type                          | Default | Description                                                   |
+| -------------- | ----------------------------- | ------- | ------------------------------------------------------------- |
+| `callSites`    | `boolean \| CallSiteOptions`  | `true`  | Rewrites `gg()` calls with source file/line/col metadata      |
+| `openInEditor` | `boolean`                     | `true`  | Adds dev server middleware for click-to-open source files     |
+| `fileSink`     | `boolean \| { dir?: string }` | `false` | Writes all `gg()` calls to `.gg/logs-{port}.jsonl` (dev only) |
+
 Individual plugins are also available for advanced setups:
 
 ```ts
-import { ggCallSitesPlugin, openInEditorPlugin } from '@leftium/gg/vite';
+import { ggCallSitesPlugin, openInEditorPlugin, ggFileSinkPlugin } from '@leftium/gg/vite';
+```
+
+## Coding Agent Access
+
+With `fileSink: true`, all `gg()` calls -- both browser-side and server-side -- are written to `.gg/logs-{port}.jsonl` during development. Coding agents (Claude, Cursor, etc.) can read this file directly without clipboard, browser automation, or manual copy/paste.
+
+Add `.gg/` to your `.gitignore` to keep log files out of version control.
+
+**Enable in `vite.config.ts`:**
+
+```ts
+ggPlugins({ fileSink: true });
 ```
 
+**Typical agent workflow:**
+
+```bash
+# 1. Clear logs before the action under investigation
+curl -X DELETE http://localhost:5173/__gg/logs
+
+# 2. Trigger the action (page load, button click, etc.)
+
+# 3. Read the logs — SSR duplicates are removed by default
+curl -s http://localhost:5173/__gg/logs
+
+# Or query the file directly with jq
+jq 'select(.lvl == "error")' .gg/logs-5173.jsonl
+```
+
+**Each JSONL line contains:**
+
+| Field    | Description                                                                                 |
+| -------- | ------------------------------------------------------------------------------------------- |
+| `ns`     | Namespace (file + function, e.g., `gg:routes/+page.svelte@click`)                           |
+| `msg`    | Formatted message string                                                                    |
+| `ts`     | Unix epoch ms                                                                               |
+| `lvl`    | `"debug"` \| `"info"` \| `"warn"` \| `"error"` (omitted if debug)                           |
+| `env`    | `"client"` or `"server"` -- which runtime produced this entry                               |
+| `origin` | `"tauri"` \| `"browser"` (client entries only)                                              |
+| `file`   | Source file path                                                                            |
+| `line`   | Source line number                                                                          |
+| `count`  | Repeat count when consecutive entries share the same `ns`+`msg` (HTTP only, omitted when 1) |
+
+**HTTP API:**
+
+In SSR apps, component `gg()` calls fire on both server and client. The HTTP endpoint deduplicates by default: server entries are canonical; a client entry at the same `[ns, line]` is dropped if its `msg` is identical. Client-only call sites (e.g. `onMount`) and hydration mismatches (same `[ns, line]`, different `msg`) are always kept.
+
+Consecutive repeated messages are collapsed by default (Chrome DevTools-style `count` field on the entry). Use `?raw` to disable collapsing and get one line per entry.
+
+```bash
+# Default — deduplicated, repeated messages collapsed
+curl -s http://localhost:5173/__gg/logs
+
+# Prefer jq over grep for filtering NDJSON — cleaner field access
+curl -s http://localhost:5173/__gg/logs | jq 'select(.msg | test("myFunction"))'
+curl -s http://localhost:5173/__gg/logs | jq -r '.msg'
+curl -s http://localhost:5173/__gg/logs | jq 'select(.lvl == "error")'
+
+# All entries, both sides (raw file contents)
+curl -s "http://localhost:5173/__gg/logs?all"
+
+# Unrolled — one line per entry, no count collapsing
+curl -s "http://localhost:5173/__gg/logs?raw"
+
+# Only call sites where server and client produced different values (hydration mismatches)
+curl -s "http://localhost:5173/__gg/logs?mismatch"
+
+# Filter by namespace glob, environment, origin, or timestamp — all compose with dedup
+curl -s "http://localhost:5173/__gg/logs?filter=api:*&env=server"
+curl -s "http://localhost:5173/__gg/logs?origin=tauri"
+curl -s "http://localhost:5173/__gg/logs?since=1741234567890"
+
+# Status and endpoint list
+curl -s http://localhost:5173/__gg/
+```
+
+**Querying the file directly with `jq`:**
+
+The JSONL file always contains all entries (both sides). Use `jq` when you need aggregation, field extraction, or queries the HTTP API doesn't cover:
+
+```bash
+# Check the env split (useful in SSR apps)
+jq -s 'group_by(.env) | map({env: .[0].env, count: length})' .gg/logs-5173.jsonl
+
+# Errors only
+jq 'select(.lvl == "error")' .gg/logs-5173.jsonl
+
+# Entries from a specific file
+jq 'select(.file | contains("+page.svelte"))' .gg/logs-5173.jsonl
+
+# Messages with source location
+jq -r '"\(.file):\(.line) \(.msg)"' .gg/logs-5173.jsonl
+
+# Count entries by namespace
+jq -s 'group_by(.ns) | map({ns: .[0].ns, count: length}) | sort_by(-.count)' .gg/logs-5173.jsonl
+```
+
+The file is truncated on dev server restart. Use `DELETE /__gg/logs` to clear mid-session. The `origin` field distinguishes Tauri webview (`"tauri"`) from browser tab (`"browser"`) when both are open.
+
+**Add to your project's `AGENTS.md`** -- see [Agent Instructions Template](specs/gg-agent-file-sink.md#agent-instructions-template-for-consuming-projects-agentsmd) in the spec for a copy-paste-ready block to add to consuming projects.
+
 ## Color Support (ANSI)
 
 Color your logs for better visual distinction using `fg()` (foreground/text) and `bg()` (background):

package/dist/debug/browser.d.ts

@@ -2,7 +2,7 @@
  * Browser-specific debug implementation.
  *
  * Output: console.debug with %c CSS color formatting.
- * Persistence: localStorage.debug
+ * Persistence: localStorage['gg-show'] + localStorage['gg-console']
  * Format (patched): +123ms namespace message
  */
 import { type DebugFactory } from './common.js';

package/dist/debug/browser.js

@@ -2,7 +2,7 @@
  * Browser-specific debug implementation.
  *
  * Output: console.debug with %c CSS color formatting.
- * Persistence: localStorage.debug
+ * Persistence: localStorage['gg-show'] + localStorage['gg-console']
  * Format (patched): +123ms namespace message
  */
 import { setup, humanize } from './common.js';
@@ -59,12 +59,13 @@ function formatArgs(args) {
 }
 function save(namespaces) {
     try {
+        // Only persist non-empty patterns. Empty string means "console disabled"
+        // (gg-console=false), not a user-set filter — don't wipe gg-show in that case.
         if (namespaces) {
-            localStorage.setItem('debug', namespaces);
-        }
-        else {
-            localStorage.removeItem('debug');
+            localStorage.setItem('gg-show', namespaces);
         }
+        // Intentionally no removeItem: gg-show is the Show filter, persisted independently.
+        // Console-disabled state is tracked via gg-console, not by clearing gg-show.
     }
     catch {
         // localStorage may not be available
@@ -72,7 +73,14 @@ function save(namespaces) {
 }
 function load() {
     try {
-        return localStorage.getItem('debug') || localStorage.getItem('DEBUG') || '';
+        // gg-console controls whether native console output is enabled at all.
+        // When it is 'false', disable all console output by returning '' (nothing enabled).
+        const consoleEnabled = localStorage.getItem('gg-console');
+        if (consoleEnabled === 'false')
+            return '';
+        // Use gg-show as the namespace filter for console output.
+        // Fall back to '*' (show all) so zero-config works out of the box.
+        return localStorage.getItem('gg-show') || '*';
     }
     catch {
         return '';

package/dist/debug/node.js

@@ -94,14 +94,16 @@ function log(...args) {
 }
 function save(namespaces) {
     if (namespaces) {
-        process.env.DEBUG = namespaces;
+        process.env.GG_KEEP = namespaces;
     }
     else {
-        delete process.env.DEBUG;
+        delete process.env.GG_KEEP;
     }
 }
 function load() {
-    return process.env.DEBUG || '';
+    // GG_KEEP controls which namespaces are kept (and thus output to the server console).
+    // Fall back to '*' so gg works zero-config in dev without setting any env var.
+    return process.env.GG_KEEP || '*';
 }
 function init(instance) {
     // Each instance gets its own inspectOpts copy (for per-instance color override)

package/dist/eruda/buffer.d.ts

@@ -53,4 +53,8 @@ export declare class LogBuffer {
      * Get the maximum capacity
      */
     get capacity(): number;
+    /**
+     * Resize the buffer. Existing entries are preserved up to newCapacity (oldest dropped if shrinking).
+     */
+    resize(newCapacity: number): void;
 }

package/dist/eruda/buffer.js

@@ -101,4 +101,20 @@ export class LogBuffer {
     get capacity() {
         return this.maxSize;
     }
+    /**
+     * Resize the buffer. Existing entries are preserved up to newCapacity (oldest dropped if shrinking).
+     */
+    resize(newCapacity) {
+        const entries = this.getEntries(); // oldest→newest, up to current count
+        this.maxSize = newCapacity;
+        this.buf = new Array(newCapacity);
+        this.head = 0;
+        this.count = 0;
+        this._totalPushed = 0;
+        // Re-push entries, keeping the most recent up to newCapacity
+        const start = entries.length > newCapacity ? entries.length - newCapacity : 0;
+        for (let i = start; i < entries.length; i++) {
+            this.push(entries[i]);
+        }
+    }
 }

package/dist/eruda/loader.js

@@ -52,6 +52,61 @@ export function shouldLoadEruda(options) {
     const prodTriggers = options.prod ?? ['url-param', 'gesture'];
     return checkProdTriggers(prodTriggers);
 }
+/**
+ * Adjusts document.body padding-bottom to match the Eruda panel height so
+ * the page remains fully scrollable while the panel is open.
+ *
+ * Mirrors the TanStack Router devtools approach: inject padding when visible,
+ * removed when hidden. A ResizeObserver tracks panel resizes (e.g. the user
+ * drags it taller or shorter).
+ *
+ * Implementation notes:
+ * - Eruda uses shadow DOM by default, so #eruda.shadowRoot must be queried
+ * - The visible panel is .eruda-dev-tools inside .eruda-container
+ * - Eruda appends its DOM asynchronously, so we poll with rAF until it appears
+ */
+function setupBodyPadding(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+eruda, initiallyOpen) {
+    let attempts = 0;
+    function trySetup() {
+        const host = document.getElementById('eruda');
+        const root = host?.shadowRoot ?? host;
+        const container = root?.querySelector('.eruda-container');
+        const panel = container?.querySelector('.eruda-dev-tools');
+        if (!panel) {
+            if (++attempts < 60)
+                requestAnimationFrame(trySetup);
+            return;
+        }
+        let observer = null;
+        function applyPadding() {
+            const h = panel.offsetHeight;
+            document.body.style.paddingBottom = `${h}px`;
+            // Ensure the document is tall enough to scroll even on short pages.
+            document.documentElement.style.minHeight = `calc(100vh + ${h}px)`;
+        }
+        function clearPadding() {
+            document.body.style.paddingBottom = '';
+            document.documentElement.style.minHeight = '';
+            observer?.disconnect();
+            observer = null;
+        }
+        function startObserving() {
+            if (observer)
+                return;
+            observer = new ResizeObserver(applyPadding);
+            observer.observe(panel);
+            applyPadding();
+        }
+        const devTools = eruda.get();
+        devTools.on('show', startObserving);
+        devTools.on('hide', clearPadding);
+        if (initiallyOpen)
+            startObserving();
+    }
+    requestAnimationFrame(trySetup);
+}
 /**
  * Dynamically imports and initializes Eruda
  */
@@ -92,6 +147,9 @@ export async function loadEruda(options) {
         if (options.open) {
             eruda.show();
         }
+        // Adjust body padding-bottom so the page remains fully scrollable while
+        // the panel is open — mirrors the TanStack Router devtools pattern.
+        setupBodyPadding(eruda, options.open ?? false);
         // Run diagnostics after Eruda is ready so they appear in Console tab
         await runGgDiagnostics();
     }

package/dist/eruda/plugin.d.ts

@@ -1,4 +1,4 @@
-import type { GgErudaOptions, CapturedEntry } from './types.js';
+import type { GgErudaOptions, CapturedEntry, DroppedNamespaceInfo } from './types.js';
 /**
  * Licia jQuery-like wrapper used by Eruda
  */
@@ -19,11 +19,15 @@ interface LiciaElement {
  */
 export declare function createGgPlugin(options: GgErudaOptions, gg: {
     _onLog?: ((entry: CapturedEntry) => void) | null;
+    addLogListener?: (callback: (entry: CapturedEntry) => void) => void;
+    removeLogListener?: (callback: (entry: CapturedEntry) => void) => void;
 }): {
     name: string;
     init($container: LiciaElement): void;
     show(): void;
     hide(): void;
     destroy(): void;
+    /** Returns a read-only view of the dropped-namespace tracking map (Phase 2 data layer). */
+    getDroppedNamespaces(): ReadonlyMap<string, DroppedNamespaceInfo>;
 };
 export {};