@leftium/gg 0.0.52 → 0.0.54

package/dist/eruda/index.js

@@ -1,5 +1,6 @@
 import { BROWSER } from 'esm-env';
 import { shouldLoadEruda, loadEruda } from './loader.js';
+import { enableGgRuntime } from '../gg.js';
 let initialized = false;
 /**
  * Initialize the gg Eruda plugin
@@ -62,16 +63,11 @@ function setupGestureDetection(options) {
         // Reset timer on each tap
         if (tapTimer)
             clearTimeout(tapTimer);
-        // If 5 taps detected, load Eruda
+        // If 5 taps detected, enable gg logging and load Eruda
         if (tapCount >= 5) {
-            console.log('[gg] 5 taps detected, loading Eruda...');
-            // Persist the decision
-            try {
-                localStorage.setItem('gg-enabled', 'true');
-            }
-            catch {
-                // localStorage might not be available
-            }
+            console.log('[gg] 5 taps detected, enabling gg logging and loading Eruda (session-only). For persistent logging across app restarts, run: localStorage.setItem("gg-enabled", "true")');
+            // Enable gg runtime for this session (flips ggConfig.enabled in memory only)
+            enableGgRuntime();
             loadEruda(options);
             resetTaps();
             return;

package/dist/gg-file-sink-plugin.js

@@ -5,14 +5,10 @@ import { matchesPattern } from './pattern.js';
 /**
  * Serialize a CapturedEntry for writing to the JSONL log file.
  *
- * IMPORTANT: The SSR injection string (in the `transform` hook below) and the
- * browser injection string hand-roll the same logic as plain JS because injected
- * code cannot import from this module. If you change the SerializedEntry schema
- * (add/rename/remove fields), update both injection strings to match.
- *
- * Server path: `serializeEntry(entry, 'server')` → appended via configureServer listener
- * SSR path:    ssrInjection string (search for `__ggFileSinkServerWriter`)
- * Browser path: injection string (search for `__ggFileSinkSender`)
+ * Used by:
+ * - configureServer listener (plugin's own gg instance)
+ * - globalThis.__ggFileSink.write() (SSR gg instances via self-registration)
+ * - Virtual module sender mirrors this schema as inline JS (search for `__ggFileSinkSender`)
  */
 function serializeEntry(entry, env, origin) {
     const out = {
@@ -20,7 +16,7 @@ function serializeEntry(entry, env, origin) {
         msg: entry.message,
         ts: entry.timestamp,
         env,
-        diff: entry.diff
+        diff: entry.diff,
     };
     if (entry.level && entry.level !== 'debug')
         out.lvl = entry.level;
@@ -161,88 +157,97 @@ function collapseRepeats(entries) {
     }
     return out;
 }
+/**
+ * Virtual module ID for the browser-side file sink sender.
+ *
+ * Virtual modules go through Vite's normal transform pipeline (NOT pre-bundled
+ * by esbuild), so `import.meta.hot` is available. This solves the fundamental
+ * problem: code inside pre-bundled deps (like gg.js) cannot use import.meta.hot
+ * because esbuild evaluates `typeof import.meta.hot` as "undefined" during
+ * dep optimization and tree-shakes the entire block.
+ *
+ * The virtual module is imported via a <script type="module"> tag injected by
+ * the `transformIndexHtml` hook below.
+ */
+const VIRTUAL_MODULE_ID = 'virtual:gg-file-sink-sender';
+const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
 export default function ggFileSinkPlugin(options = {}) {
     let logFile;
     let serverSideListener = null;
-    let ggModulePath = '';
     return {
         name: 'gg-file-sink',
-        configResolved(config) {
-            // Resolve the absolute path to gg.ts — works both in this repo (src/lib/gg.ts)
-            // and in consumer projects where gg is in node_modules/@leftium/gg/src/lib/gg.ts.
-            // We try both locations; whichever resolves to an existing file wins.
-            const candidates = [
-                path.resolve(config.root, 'src/lib/gg.ts'),
-                path.resolve(config.root, 'node_modules/@leftium/gg/src/lib/gg.ts')
-            ];
-            ggModulePath = candidates.find((p) => fs.existsSync(p)) ?? candidates[0];
+        // Virtual module: resolve and load the browser-side HMR sender.
+        resolveId(id) {
+            if (id === VIRTUAL_MODULE_ID)
+                return RESOLVED_VIRTUAL_MODULE_ID;
         },
-        transform(code, id, transformOptions) {
-            if (id !== ggModulePath)
-                return null;
-            if (transformOptions?.ssr) {
-                // SSR injection: write server-side entries directly to the log file.
-                // Runs in Vite's SSR module runner (same Node.js process but separate module
-                // instance from configureServer, so we can't share a listener — inject instead).
-                // We pass appendFileSync + the log file path via globalThis so the injected
-                // code has no imports of its own (avoids TLA / static import constraints).
-                // Guarded by import.meta.env.DEV — tree-shaken in production builds.
-                // NOTE: this string mirrors serializeEntry() above — keep in sync if schema changes.
-                const ssrInjection = `
-// gg-file-sink: server-side direct writer (injected by ggFileSinkPlugin)
-if (import.meta.env.DEV && globalThis.__ggFileSink) {
-	const { appendFileSync: __ggAppendFileSync, logFile: __ggLogFile } = globalThis.__ggFileSink;
-	gg.addLogListener(function __ggFileSinkServerWriter(entry) {
-		if (!__ggLogFile) return;
-		const s = {
-			ns: entry.namespace,
-			msg: entry.message,
-			ts: entry.timestamp,
-			env: 'server',
-			diff: entry.diff,
-		};
-		if (entry.level && entry.level !== 'debug') s.lvl = entry.level;
-		if (entry.file) s.file = entry.file;
-		if (entry.line !== undefined) s.line = entry.line;
-		if (entry.src) s.src = entry.src;
-		if (entry.tableData) s.table = entry.tableData;
-		try { __ggAppendFileSync(__ggLogFile, JSON.stringify(s) + '\\n'); } catch {}
-	});
+        load(id) {
+            if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+                // This code runs through Vite's normal transform pipeline (not
+                // pre-bundled), so import.meta.hot is properly available.
+                //
+                // Uses a dual strategy for sending log entries to the dev server:
+                // 1. import.meta.hot.send() via HMR WebSocket (fast, no HTTP overhead)
+                // 2. fetch() POST to /__gg/logs as fallback (works even if HMR is unavailable)
+                //
+                // NOTE: this string mirrors serializeEntry() above — keep in sync.
+                return `
+import { gg } from '@leftium/gg';
+
+const origin =
+	typeof window !== 'undefined' && '__TAURI_INTERNALS__' in window
+		? 'tauri'
+		: 'browser';
+
+// Batch entries and flush via fetch POST — works regardless of HMR state.
+let __ggPendingEntries = [];
+let __ggFlushTimer = null;
+function __ggFlushEntries() {
+	__ggFlushTimer = null;
+	if (__ggPendingEntries.length === 0) return;
+	const batch = __ggPendingEntries;
+	__ggPendingEntries = [];
+	const body = batch.map(e => JSON.stringify(e)).join('\\n');
+	fetch('/__gg/logs', { method: 'POST', body, headers: { 'Content-Type': 'text/plain' } }).catch(() => {});
 }
-`;
-                return { code: code + ssrInjection, map: null };
-            }
-            // Browser injection: relay entries to Vite dev server via HMR WebSocket.
-            // Runs once when the gg module is first loaded in the browser.
-            // Guarded by import.meta.hot — Vite tree-shakes this in production builds.
-            // NOTE: this string mirrors serializeEntry() above — keep in sync if schema changes.
-            const injection = `
-// gg-file-sink: client-side HMR sender (injected by ggFileSinkPlugin)
-if (import.meta.hot) {
-	const __ggFileSinkOrigin =
-		typeof window !== 'undefined' && '__TAURI_INTERNALS__' in window
-			? 'tauri'
-			: 'browser';
-	gg.addLogListener(function __ggFileSinkSender(entry) {
-		if (!import.meta.hot) return;
-		const s = {
-			ns: entry.namespace,
-			msg: entry.message,
-			ts: entry.timestamp,
-			env: 'client',
-			origin: __ggFileSinkOrigin,
-			diff: entry.diff,
-		};
-		if (entry.level && entry.level !== 'debug') s.lvl = entry.level;
-		if (entry.file) s.file = entry.file;
-		if (entry.line !== undefined) s.line = entry.line;
-		if (entry.src) s.src = entry.src;
-		if (entry.tableData) s.table = entry.tableData;
+
+gg.addLogListener(function __ggFileSinkSender(entry) {
+	const s = {
+		ns: entry.namespace,
+		msg: entry.message,
+		ts: entry.timestamp,
+		env: 'client',
+		origin,
+		diff: entry.diff,
+	};
+	if (entry.level && entry.level !== 'debug') s.lvl = entry.level;
+	if (entry.file) s.file = entry.file;
+	if (entry.line !== undefined) s.line = entry.line;
+	if (entry.src) s.src = entry.src;
+	if (entry.tableData) s.table = entry.tableData;
+
+	// Try HMR first (lowest latency), fall back to batched fetch
+	if (import.meta.hot) {
 		import.meta.hot.send('gg:log', { entry: s });
-	});
-}
+	} else {
+		__ggPendingEntries.push(s);
+		if (!__ggFlushTimer) __ggFlushTimer = setTimeout(__ggFlushEntries, 100);
+	}
+});
 `;
-            return { code: code + injection, map: null };
+            }
+        },
+        // Inject the virtual module into the HTML page so it runs in the browser.
+        // Uses both transformIndexHtml (plain Vite apps) and a response-intercepting
+        // middleware (SvelteKit and other frameworks that bypass Vite's HTML pipeline).
+        transformIndexHtml() {
+            return [
+                {
+                    tag: 'script',
+                    attrs: { type: 'module', src: `/@id/${VIRTUAL_MODULE_ID}` },
+                    injectTo: 'head',
+                },
+            ];
         },
         configureServer(server) {
             // Truncate/create log file once the actual port is known.
@@ -250,26 +255,29 @@ if (import.meta.hot) {
             // before listening fires, so no entries are written to the wrong file.
             server.httpServer?.once('listening', () => {
                 const addr = server.httpServer?.address();
-                const port = addr && typeof addr === 'object' ? addr.port : (server.config.server.port ?? 5173);
-                const dir = options.dir ? path.resolve(options.dir) : path.resolve(process.cwd(), '.gg');
+                const port = addr && typeof addr === 'object'
+                    ? addr.port
+                    : (server.config.server.port ?? 5173);
+                const dir = options.dir
+                    ? path.resolve(options.dir)
+                    : path.resolve(process.cwd(), '.gg');
                 fs.mkdirSync(dir, { recursive: true });
                 logFile = path.join(dir, `logs-${port}.jsonl`);
                 fs.writeFileSync(logFile, '');
             });
-            // Expose appendFileSync + logFile path via globalThis so the SSR-injected
-            // listener (running in Vite's separate module runner context) can write to the
-            // same file without needing its own fs import.
-            globalThis.__ggFileSink = {
-                appendFileSync: fs.appendFileSync.bind(fs),
-                get logFile() {
-                    return logFile;
-                }
-            };
             const appendEntry = (serialized) => {
                 if (!logFile)
                     return;
                 fs.appendFileSync(logFile, JSON.stringify(serialized) + '\n');
             };
+            // Expose a write() function via globalThis so ANY gg module instance
+            // (SSR, pre-bundled, monorepo-hoisted) can self-register a listener
+            // that writes to the log file. This replaces the broken transform hook.
+            globalThis.__ggFileSink = {
+                write(entry, env, origin) {
+                    appendEntry(serializeEntry(entry, env, origin));
+                },
+            };
             // Client-side entries arrive via HMR custom event
             server.hot.on('gg:log', (data) => {
                 if (!data?.entry)
@@ -277,7 +285,7 @@ if (import.meta.hot) {
                 const serialized = {
                     ...data.entry,
                     env: 'client',
-                    origin: data.entry.origin ?? 'browser'
+                    origin: data.entry.origin ?? 'browser',
                 };
                 appendEntry(serialized);
             });
@@ -297,6 +305,29 @@ if (import.meta.hot) {
             // /__gg/ index — JSON status for agents and developers
             server.middlewares.use('/__gg', (req, res, next) => {
                 const pathname = new URL(req.url || '/', 'http://x').pathname;
+                // /__gg/stack — dump Connect middleware stack for debugging
+                if (pathname === '/stack') {
+                    const stack = server.middlewares.stack;
+                    const routes = stack.map((layer, i) => ({
+                        i,
+                        route: layer.route,
+                        name: layer.handle?.name || '(anonymous)',
+                    }));
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(routes, null, 2));
+                    return;
+                }
+                // /__gg/sender — redirect to the virtual module URL so Vite's
+                // normal transform pipeline handles it (including HMR injection).
+                // Direct transformRequest() fails in consumer apps because the
+                // module graph hasn't loaded the virtual module yet at request time.
+                if (pathname === '/sender') {
+                    res.writeHead(302, {
+                        Location: `/@id/${VIRTUAL_MODULE_ID}`,
+                    });
+                    res.end();
+                    return;
+                }
                 // Only handle exact /__gg or /__gg/ — let other /__gg/* routes fall through
                 if (pathname !== '' && pathname !== '/')
                     return next();
@@ -312,7 +343,9 @@ if (import.meta.hot) {
                 }
                 const port = (() => {
                     const addr = server.httpServer?.address();
-                    return addr && typeof addr === 'object' ? addr.port : (server.config.server.port ?? 5173);
+                    return addr && typeof addr === 'object'
+                        ? addr.port
+                        : (server.config.server.port ?? 5173);
                 })();
                 const body = JSON.stringify({
                     plugin: 'gg-file-sink',
@@ -321,8 +354,8 @@ if (import.meta.hot) {
                     endpoints: {
                         'GET /__gg/logs': 'read deduplicated JSONL entries (?filter=, ?since=, ?env=, ?origin=, ?all, ?mismatch, ?raw)',
                         'DELETE /__gg/logs': 'truncate log file',
-                        'GET /__gg/project-root': 'project root path'
-                    }
+                        'GET /__gg/project-root': 'project root path',
+                    },
                 }, null, 2);
                 res.statusCode = 200;
                 res.setHeader('Content-Type', 'application/json; charset=utf-8');
@@ -337,6 +370,31 @@ if (import.meta.hot) {
                     res.end();
                     return;
                 }
+                // POST: receive client-side log entries via fetch (fallback for HMR)
+                if (method === 'POST') {
+                    let body = '';
+                    req.on('data', (chunk) => {
+                        body += chunk.toString();
+                    });
+                    req.on('end', () => {
+                        try {
+                            const lines = body.split('\n').filter((l) => l.trim());
+                            for (const line of lines) {
+                                const entry = JSON.parse(line);
+                                entry.env = 'client';
+                                entry.origin = entry.origin ?? 'browser';
+                                appendEntry(entry);
+                            }
+                            res.statusCode = 204;
+                            res.end();
+                        }
+                        catch (err) {
+                            res.statusCode = 400;
+                            res.end(String(err));
+                        }
+                    });
+                    return;
+                }
                 if (method === 'DELETE') {
                     try {
                         fs.writeFileSync(logFile, '');
@@ -358,7 +416,9 @@ if (import.meta.hot) {
                         const noCollapse = params.has('raw');
                         res.setHeader('Content-Type', 'text/plain; charset=utf-8');
                         const fileContent = fs.readFileSync(logFile, 'utf-8');
-                        const lines = fileContent.split('\n').filter((l) => l.trim());
+                        const lines = fileContent
+                            .split('\n')
+                            .filter((l) => l.trim());
                         // Pre-dedup filters: namespace glob and timestamp (symmetric — don't affect cross-env index)
                         const preFiltered = lines.filter((l) => filterLinePreDedup(l, params));
                         // Parse surviving lines for dedup/mismatch pass
@@ -375,9 +435,12 @@ if (import.meta.hot) {
                         // Post-dedup filters: env and origin (applied after so cross-env index is intact)
                         const postFiltered = deduped.filter((e) => filterEntryPostDedup(e, params));
                         // Collapse consecutive repeated messages (count field), unless ?raw
-                        const result = noCollapse ? postFiltered : collapseRepeats(postFiltered);
+                        const result = noCollapse
+                            ? postFiltered
+                            : collapseRepeats(postFiltered);
                         res.statusCode = 200;
-                        res.end(result.map((e) => JSON.stringify(e)).join('\n') + (result.length ? '\n' : ''));
+                        res.end(result.map((e) => JSON.stringify(e)).join('\n') +
+                            (result.length ? '\n' : ''));
                     }
                     catch (err) {
                         res.statusCode = 500;
@@ -389,6 +452,6 @@ if (import.meta.hot) {
                 res.setHeader('Allow', 'GET, HEAD, DELETE');
                 res.end('Method Not Allowed');
             });
-        }
+        },
     };
 }

package/dist/gg.d.ts

@@ -91,6 +91,20 @@ export declare class GgChain<T> {
     /** Flush the log immediately and return the passthrough value. */
     get v(): T;
 }
+/**
+ * Enable gg logging at runtime (e.g., after 5-tap gesture in production).
+ * Flips the internal enabled flag so subsequent gg() calls start capturing.
+ * This is session-only — does not persist to localStorage, so the next
+ * page load / app launch starts with gg disabled again.
+ *
+ * To enable gg across app restarts (e.g., in a prod Tauri app), run this
+ * in the Eruda console instead:
+ *   localStorage.setItem("gg-enabled", "true")
+ * Clear with: localStorage.removeItem("gg-enabled") or gg.clearPersist()
+ *
+ * @internal Used by the Eruda gesture handler — not part of the public API.
+ */
+export declare function enableGgRuntime(): void;
 /**
  * Chainable wrapper returned by gg.time(). Only supports .ns() for setting
  * the namespace for the entire timer group (inherited by timeLog/timeEnd).

package/dist/gg.js

@@ -71,7 +71,8 @@ function getServerPort() {
     return new Promise((resolve) => {
         if (BROWSER) {
             // Browser environment
-            const currentPort = window.location.port || (window.location.protocol === 'https:' ? '443' : '80');
+            const currentPort = window.location.port ||
+                (window.location.protocol === 'https:' ? '443' : '80');
             // Resolve the promise with the detected port
             resolve(currentPort);
         }
@@ -165,7 +166,7 @@ const ggConfig = {
     // filename B        : http://localhost:5173/src/lib/gg.ts
     // srcRootprefix     : http://localhost:5173/src/
     // <folderName> group:                       src
-    srcRootPattern: '.*?(/(?<folderName>src|chunks)/)'
+    srcRootPattern: '.*?(/(?<folderName>src|chunks)/)',
 };
 const srcRootRegex = new RegExp(ggConfig.srcRootPattern, 'i');
 // To maintain unique millisecond diffs for each callpoint:
@@ -240,12 +241,16 @@ gg.here = () => {
     const namespace = callpoint;
     // Log the call-site info
     const ggLogFunction = namespaceToLogFunction.get(namespace) ||
-        namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
+        namespaceToLogFunction
+            .set(namespace, createGgDebugger(namespace))
+            .get(namespace);
     ggLogFunction(`    📝 ${callpoint}`);
     return {
         fileName: callpoint,
-        functionName: callpoint.includes('@') ? callpoint.split('@').pop() || '' : '',
-        url: ''
+        functionName: callpoint.includes('@')
+            ? callpoint.split('@').pop() || ''
+            : '',
+        url: '',
     };
 };
 /**
@@ -424,7 +429,10 @@ function formatValue(v) {
 /** JSON replacer that limits nesting depth to avoid huge output. */
 function jsonReplacer(key, value) {
     // 'this' is the parent object; key === '' at the root level
-    if (key !== '' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    if (key !== '' &&
+        typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value)) {
         // Count depth by checking how many ancestors are objects/arrays
         // Simple approximation: truncate any nested object at depth > 2
         const str = JSON.stringify(value);
@@ -434,7 +442,7 @@ function jsonReplacer(key, value) {
     return value;
 }
 function ggLog(options, ...args) {
-    const { ns: nsLabel, file, line, col, src, level, stack, tableData } = options;
+    const { ns: nsLabel, file, line, col, src, level, stack, tableData, } = options;
     if (!ggConfig.enabled) {
         return args.length ? args[0] : { fileName: '', functionName: '', url: '' };
     }
@@ -443,12 +451,20 @@ function ggLog(options, ...args) {
         maxCallpointLength = namespace.length;
     }
     const ggLogFunction = namespaceToLogFunction.get(namespace) ||
-        namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
+        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)
     const logArgs = args.length === 0 ? ['(no args)'] : [...args];
     // Add level prefix emoji for info/warn/error
-    const levelEmoji = level === 'info' ? 'ℹ️' : level === 'warn' ? '⚠️' : level === 'error' ? '⛔' : '';
+    const levelEmoji = level === 'info'
+        ? 'ℹ️'
+        : level === 'warn'
+            ? '⚠️'
+            : level === 'error'
+                ? '⛔'
+                : '';
     if (levelEmoji) {
         if (typeof logArgs[0] === 'string') {
             logArgs[0] = `${levelEmoji} ${logArgs[0]}`;
@@ -478,7 +494,9 @@ function ggLog(options, ...args) {
         namespace,
         color: ggLogFunction.color,
         diff,
-        message: logArgs.length === 1 ? formatValue(logArgs[0]) : logArgs.map(formatValue).join(' '),
+        message: logArgs.length === 1
+            ? formatValue(logArgs[0])
+            : logArgs.map(formatValue).join(' '),
         args: logArgs,
         timestamp: Date.now(),
         file,
@@ -487,7 +505,7 @@ function ggLog(options, ...args) {
         src,
         level,
         stack,
-        tableData
+        tableData,
     };
     // Always buffer — earlyLogBuffer is a persistent replay log so late-registering
     // listeners (e.g. Eruda mounting after the file-sink listener) still receive entries
@@ -525,10 +543,14 @@ gg._here = (options) => {
     const { ns: nsLabel, file, line, col } = options;
     const namespace = nsLabel.startsWith('gg:') ? nsLabel : `gg:${nsLabel}`;
     const ggLogFunction = namespaceToLogFunction.get(namespace) ||
-        namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
+        namespaceToLogFunction
+            .set(namespace, createGgDebugger(namespace))
+            .get(namespace);
     ggLogFunction(`    📝 ${namespace}`);
     const fileName = file ? file.replace(srcRootRegex, '') : nsLabel;
-    const functionName = nsLabel.includes('@') ? nsLabel.split('@').pop() || '' : '';
+    const functionName = nsLabel.includes('@')
+        ? nsLabel.split('@').pop() || ''
+        : '';
     const url = file ? openInEditorUrl(file, line, col) : '';
     return { fileName, functionName, url };
 };
@@ -543,7 +565,9 @@ gg._here = (options) => {
  */
 gg._o = (ns, file, line, col, src) => ({ ns, file, line, col, src });
 gg.disable = isCloudflareWorker() ? () => '' : () => debugFactory.disable();
-gg.enable = isCloudflareWorker() ? () => { } : (ns) => debugFactory.enable(ns);
+gg.enable = isCloudflareWorker()
+    ? () => { }
+    : (ns) => debugFactory.enable(ns);
 /**
  * Clear the persisted gg-enabled state from localStorage.
  * Useful to reset production trigger after testing with ?gg parameter.
@@ -559,6 +583,22 @@ gg.clearPersist = () => {
         }
     }
 };
+/**
+ * Enable gg logging at runtime (e.g., after 5-tap gesture in production).
+ * Flips the internal enabled flag so subsequent gg() calls start capturing.
+ * This is session-only — does not persist to localStorage, so the next
+ * page load / app launch starts with gg disabled again.
+ *
+ * To enable gg across app restarts (e.g., in a prod Tauri app), run this
+ * in the Eruda console instead:
+ *   localStorage.setItem("gg-enabled", "true")
+ * Clear with: localStorage.removeItem("gg-enabled") or gg.clearPersist()
+ *
+ * @internal Used by the Eruda gesture handler — not part of the public API.
+ */
+export function enableGgRuntime() {
+    ggConfig.enabled = true;
+}
 // ── Console-like methods ───────────────────────────────────────────────
 // Each public method (gg.warn, gg.error, etc.) has a corresponding internal
 // method (gg._warn, gg._error, etc.) that accepts call-site metadata from
@@ -759,7 +799,9 @@ function formatTable(data, columns) {
             allKeys = Array.from(keySet);
             rows = data.map((item, i) => ({
                 '(index)': i,
-                ...(item && typeof item === 'object' ? item : { Value: item })
+                ...(item && typeof item === 'object'
+                    ? item
+                    : { Value: item }),
             }));
         }
     }
@@ -783,7 +825,7 @@ function formatTable(data, columns) {
             '(index)': key,
             ...(val && typeof val === 'object' && !Array.isArray(val)
                 ? val
-                : { Value: val })
+                : { Value: val }),
         }));
     }
     // Apply column filter
@@ -821,7 +863,7 @@ function parseColor(color) {
         grey: '#808080',
         orange: '#ffa500',
         purple: '#800080',
-        pink: '#ffc0cb'
+        pink: '#ffc0cb',
     };
     // Check named colors first
     const normalized = color.toLowerCase().trim();
@@ -834,7 +876,7 @@ function parseColor(color) {
         return {
             r: parseInt(hexMatch[1], 16),
             g: parseInt(hexMatch[2], 16),
-            b: parseInt(hexMatch[3], 16)
+            b: parseInt(hexMatch[3], 16),
         };
     }
     // Parse short hex (#rgb)
@@ -843,7 +885,7 @@ function parseColor(color) {
         return {
             r: parseInt(shortHexMatch[1] + shortHexMatch[1], 16),
             g: parseInt(shortHexMatch[2] + shortHexMatch[2], 16),
-            b: parseInt(shortHexMatch[3] + shortHexMatch[3], 16)
+            b: parseInt(shortHexMatch[3] + shortHexMatch[3], 16),
         };
     }
     // Parse rgb(r,g,b) or rgba(r,g,b,a)
@@ -852,7 +894,7 @@ function parseColor(color) {
         return {
             r: parseInt(rgbMatch[1]),
             g: parseInt(rgbMatch[2]),
-            b: parseInt(rgbMatch[3])
+            b: parseInt(rgbMatch[3]),
         };
     }
     return null;
@@ -864,7 +906,7 @@ const STYLE_CODES = {
     bold: '\x1b[1m',
     dim: '\x1b[2m',
     italic: '\x1b[3m',
-    underline: '\x1b[4m'
+    underline: '\x1b[4m',
 };
 /**
  * Internal helper to create chainable color function with method chaining
@@ -1006,14 +1048,14 @@ Object.defineProperty(gg, 'addLogListener', {
         }
     },
     writable: false,
-    configurable: true
+    configurable: true,
 });
 Object.defineProperty(gg, 'removeLogListener', {
     value(callback) {
         _logListeners.delete(callback);
     },
     writable: false,
-    configurable: true
+    configurable: true,
 });
 // Legacy gg._onLog — backward-compatible single-slot alias
 Object.defineProperty(gg, '_onLog', {
@@ -1033,7 +1075,7 @@ Object.defineProperty(gg, '_onLog', {
                 earlyLogBuffer.forEach((entry) => callback(entry));
             }
         }
-    }
+    },
 });
 // Namespace for adding properties to the gg function
 // eslint-disable-next-line @typescript-eslint/no-namespace
@@ -1057,9 +1099,11 @@ export async function runGgDiagnostics() {
     let ggMessage = '\n';
     const message = (s) => (ggMessage += `${s}\n`);
     const checkbox = (test) => (test ? '✅' : '❌');
-    const makeHint = (test, ifTrue, ifFalse = '') => (test ? ifTrue : ifFalse);
+    const makeHint = (test, ifTrue, ifFalse = '') => test ? ifTrue : ifFalse;
     console.log(`Loaded gg module. Checking configuration...`);
-    const configOk = BROWSER ? ggConfig.enabled : ggConfig.enabled && ggLogTest.enabled;
+    const configOk = BROWSER
+        ? ggConfig.enabled
+        : ggConfig.enabled && ggLogTest.enabled;
     if (configOk) {
         message(`No problems detected:`);
         if (BROWSER) {
@@ -1104,3 +1148,41 @@ export async function runGgDiagnostics() {
 if (ggConfig.showHints && !isCloudflareWorker() && !BROWSER) {
     runGgDiagnostics();
 }
+// ── File sink: browser → dev server relay ──────────────────────────────
+// Dynamically import the file-sink sender module served by ggFileSinkPlugin.
+// The sender registers a log listener that relays entries to the Vite dev
+// server via import.meta.hot.send() over the HMR WebSocket.
+//
+// Why dynamic import instead of inline code?
+// The gg module is pre-bundled by Vite's dep optimizer (esbuild), which
+// evaluates `typeof import.meta.hot` as "undefined" and tree-shakes any
+// code guarded by it. Dynamic import() is preserved by esbuild, and the
+// imported module (served at /__gg/sender.mjs by the plugin's middleware)
+// goes through Vite's normal transform pipeline where import.meta.hot IS
+// available.
+//
+// The .catch() silently handles the case where ggFileSinkPlugin isn't active
+// (e.g., production builds, or projects that don't use the file sink).
+if (BROWSER && DEV) {
+    // Import the virtual module directly through Vite's module URL.
+    // Dynamic string construction defeats Rollup's static import analysis —
+    // without this, `vite build` fails because Rollup tries to resolve the
+    // dev-server-only URL. The runtime guard (BROWSER && DEV) prevents
+    // execution in production, but Rollup analyzes statically.
+    const senderUrl = '/@id/' + 'virtual:gg-file-sink-sender';
+    import(/* @vite-ignore */ senderUrl).catch(() => { });
+}
+// ── File sink: server-side self-registration via globalThis bridge ───────
+// When ggFileSinkPlugin is active, configureServer sets globalThis.__ggFileSink
+// with a write() function that serializes and appends entries to the JSONL file.
+// Any gg module instance (SSR, pre-bundled, monorepo-hoisted) that sees the
+// bridge registers a listener — no transform hook or path matching needed.
+if (!BROWSER &&
+    typeof globalThis !== 'undefined' &&
+    globalThis.__ggFileSink &&
+    typeof globalThis.__ggFileSink?.write === 'function') {
+    const sink = globalThis.__ggFileSink;
+    gg.addLogListener((entry) => {
+        sink.write(entry, 'server');
+    });
+}

package/package.json

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