@leftium/gg 0.0.33 → 0.0.35

package/README.md

@@ -18,24 +18,101 @@
 npm add @leftium/gg
 ```
 
-## Usage
+## SvelteKit Quick Start
 
-### Basic Logging
+### 1. Use `gg()` anywhere
 
-```javascript
-import { gg } from '@leftium/gg';
+```svelte
+<script>
+	import { gg } from '@leftium/gg';
+
+	gg('Hello world');
+
+	// Log expressions (returns first argument)
+	const result = gg(someFunction());
+
+	// Multiple arguments
+	gg('User:', user, 'Status:', status);
+</script>
+```
+
+That's it! Output appears in the browser dev console and terminal. The following optional steps are highly recommended to unlock the full experience:
+
+### 2. Add Vite plugins (optional, recommended)
+
+Without plugins, namespaces are random word-tuples. With plugins, you get real file/function callpoints, open-in-editor links, and icecream-style source expressions.
+
+```ts
+// vite.config.ts
+import ggPlugins from '@leftium/gg/vite';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [sveltekit(), ...ggPlugins()]
+});
+```
+
+`ggPlugins()` includes:
+
+- **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.
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+	import { GgConsole } from '@leftium/gg';
+</script>
+
+<GgConsole />
+{@render children()}
+```
+
+In development, the debug console appears automatically.
+In production, add `?gg` to the URL or use a 5-tap gesture to activate.
 
-// Simple logging
-gg('Hello world');
+## GgConsole Options
 
-// Log expressions (returns first argument)
-const result = gg(someFunction());
+```svelte
+<GgConsole prod={['url-param', 'gesture']} maxEntries={5000} />
+```
+
+| Prop           | Type                       | Default                    | Description                    |
+| -------------- | -------------------------- | -------------------------- | ------------------------------ |
+| `prod`         | `Array \| string \| false` | `['url-param', 'gesture']` | Production activation triggers |
+| `maxEntries`   | `number`                   | `2000`                     | Max log entries in ring buffer |
+| `erudaOptions` | `object`                   | `{}`                       | Pass-through options to Eruda  |
+
+**Production triggers:**
+
+- `'url-param'` -- activate with `?gg` in the URL (persists to localStorage)
+- `'gesture'` -- activate with 5 rapid taps anywhere on the page
+- `'localStorage'` -- activate if `localStorage['gg-enabled']` is `'true'`
+- `false` -- disable debug console in production entirely
+
+## Vite Plugin Options
 
-// Multiple arguments
-gg('User:', user, 'Status:', status);
+```ts
+import ggPlugins from '@leftium/gg/vite';
+
+ggPlugins({
+	callSites: { srcRootPattern: '.*?(/src/)' },
+	openInEditor: false // disable open-in-editor middleware
+});
 ```
 
-### Color Support (ANSI)
+Individual plugins are also available for advanced setups:
+
+```ts
+import { ggCallSitesPlugin, openInEditorPlugin } from '@leftium/gg/vite';
+```
+
+## Color Support (ANSI)
 
 Color your logs for better visual distinction using `fg()` (foreground/text) and `bg()` (background):
 
@@ -77,46 +154,56 @@ gg(fg('rgb(255,99,71)')`Tomato text`);
 
 **Where colors work:**
 
-- ✅ Native browser console (Chrome DevTools, Firefox, etc.)
-- ✅ Eruda GG panel (mobile debugging)
-- ✅ Node.js terminal
-- ✅ All environments that support ANSI escape codes
+- Native browser console (Chrome DevTools, Firefox, etc.)
+- GgConsole debug panel (mobile debugging)
+- Node.js terminal
+- All environments that support ANSI escape codes
 
-## Technical Details
+## Other Frameworks
 
-### Bundled Dependencies
+`gg()` works in any JavaScript project. The Vite plugins work with any Vite-based framework (React, Vue, Solid, etc.).
 
-This library includes a **patched version** of the [`debug`](https://www.npmjs.com/package/debug) package. The patch reformats the output to display time diffs **before** the namespace for better readability:
+### Vanilla / Non-Svelte Setup
 
-**Standard debug output:**
+```ts
+// vite.config.ts
+import ggPlugins from '@leftium/gg/vite';
 
-```
-  gg:routes/+page.svelte +123ms
+export default defineConfig({
+	plugins: [...ggPlugins()]
+});
 ```
 
-**Patched output (this library):**
+```js
+// app.js
+import { gg } from '@leftium/gg';
+import { initGgEruda } from '@leftium/gg/eruda';
 
+initGgEruda();
+gg('works in any framework');
 ```
- +123ms gg:routes/+page.svelte
-```
 
-The patched `debug` library is bundled directly into the distribution, so consumers automatically get the correct behavior without needing to install or patch `debug` themselves.
+## Technical Details
+
+### Internal Debug Implementation
+
+This library includes an **internal TypeScript implementation** inspired by the [`debug`](https://www.npmjs.com/package/debug) package. The output format displays time diffs **before** the namespace for better readability:
 
-### Updating the Bundled debug Library
+**Output format:**
 
-When a new version of `debug` is released:
+```
+ +123ms gg:routes/+page.svelte
+```
 
-1. Update debug: `pnpm add debug@x.x.x`
-2. Update patch: `pnpm patch debug@x.x.x` (apply changes, then `pnpm patch-commit`)
-3. Run the update script: `./scripts/update-debug.sh`
-4. Verify patches are present: `git diff src/lib/debug/src/`
-5. Test dev mode: `pnpm dev`
-6. Test production build: `pnpm prepack`
-7. Commit changes: `git commit -am "Update bundled debug to x.x.x"`
+Features implemented internally (~290 lines of TypeScript):
 
-The patch is maintained in `patches/debug@4.4.3.patch` for reference.
+- Color hashing algorithm for consistent namespace colors
+- Millisecond diff formatting (e.g., `+123ms`, `+2s`, `+5m`)
+- Namespace wildcard matching (`gg:*`, `gg:routes/*`, `-gg:test`)
+- localStorage.debug / process.env.DEBUG persistence
+- Browser and Node.js environments
 
-**Note:** `debug` is kept in dependencies (not devDependencies) to support both dev and production modes.
+This approach eliminates the need for vendoring, patching, and bundling third-party code, resulting in better type safety and simpler maintenance.
 
 ## Inspirations
 

package/dist/GgConsole.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import type { GgErudaOptions } from './eruda/types.js';
+
+	let { prod, maxEntries, erudaOptions }: GgErudaOptions = $props();
+
+	onMount(() => {
+		import('./eruda/index.js').then(({ initGgEruda }) => {
+			initGgEruda({ prod, maxEntries, erudaOptions });
+		});
+	});
+</script>

package/dist/GgConsole.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { GgErudaOptions } from './eruda/types.js';
+declare const GgConsole: import("svelte").Component<GgErudaOptions, {}, "">;
+type GgConsole = ReturnType<typeof GgConsole>;
+export default GgConsole;

package/dist/OpenInEditorLink.svelte

@@ -1,22 +1,32 @@
 <script lang="ts">
 	import { dev } from '$app/environment';
 
+	type GgCallSiteInfo = { fileName: string; functionName: string; url: string };
+
 	let {
-		url,
-		fileName,
-		title = fileName
-	}: { url: string; fileName: string; title?: string } = $props();
+		gg,
+		url = gg?.url,
+		fileName = gg?.fileName,
+		title = gg ? `${gg.fileName}@${gg.functionName}` : fileName
+	}: {
+		gg?: GgCallSiteInfo;
+		url?: string;
+		fileName?: string;
+		title?: string;
+	} = $props();
 
 	// svelte-ignore non_reactive_update
 	let iframeElement: HTMLIFrameElement;
 
 	function onclick(event: MouseEvent) {
-		iframeElement.src = url;
-		event.preventDefault();
+		if (url) {
+			iframeElement.src = url;
+			event.preventDefault();
+		}
 	}
 </script>
 
-{#if dev}
+{#if dev && fileName}
 	[📝<a {onclick} href={url} {title} target="_open-in-editor" class="open-in-editor-link">
 		{fileName}
 	</a>

package/dist/OpenInEditorLink.svelte.d.ts

@@ -1,6 +1,12 @@
-type $$ComponentProps = {
-    url: string;
+type GgCallSiteInfo = {
     fileName: string;
+    functionName: string;
+    url: string;
+};
+type $$ComponentProps = {
+    gg?: GgCallSiteInfo;
+    url?: string;
+    fileName?: string;
     title?: string;
 };
 declare const OpenInEditorLink: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/debug/browser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Browser-specific debug implementation.
+ *
+ * Output: console.debug with %c CSS color formatting.
+ * Persistence: localStorage.debug
+ * Format (patched): +123ms namespace message
+ */
+import { type DebugFactory } from './common.js';
+declare const debug: DebugFactory;
+export default debug;

package/dist/debug/browser.js

@@ -0,0 +1,102 @@
+/**
+ * Browser-specific debug implementation.
+ *
+ * Output: console.debug with %c CSS color formatting.
+ * Persistence: localStorage.debug
+ * Format (patched): +123ms namespace message
+ */
+import { setup, humanize } from './common.js';
+/**
+ * 76 hex colors — identical to debug@4 browser.js for color-hash stability.
+ */
+const colors = [
+    '#0000CC', '#0000FF', '#0033CC', '#0033FF', '#0066CC', '#0066FF',
+    '#0099CC', '#0099FF', '#00CC00', '#00CC33', '#00CC66', '#00CC99',
+    '#00CCCC', '#00CCFF', '#3300CC', '#3300FF', '#3333CC', '#3333FF',
+    '#3366CC', '#3366FF', '#3399CC', '#3399FF', '#33CC00', '#33CC33',
+    '#33CC66', '#33CC99', '#33CCCC', '#33CCFF', '#6600CC', '#6600FF',
+    '#6633CC', '#6633FF', '#66CC00', '#66CC33', '#9900CC', '#9900FF',
+    '#9933CC', '#9933FF', '#99CC00', '#99CC33', '#CC0000', '#CC0033',
+    '#CC0066', '#CC0099', '#CC00CC', '#CC00FF', '#CC3300', '#CC3333',
+    '#CC3366', '#CC3399', '#CC33CC', '#CC33FF', '#CC6600', '#CC6633',
+    '#CC9900', '#CC9933', '#CCCC00', '#CCCC33', '#FF0000', '#FF0033',
+    '#FF0066', '#FF0099', '#FF00CC', '#FF00FF', '#FF3300', '#FF3333',
+    '#FF3366', '#FF3399', '#FF33CC', '#FF33FF', '#FF6600', '#FF6633',
+    '#FF9900', '#FF9933', '#FFCC00', '#FFCC33'
+];
+function useColors() {
+    // Modern browsers all support %c — simplified from debug's original checks
+    return typeof document !== 'undefined' || typeof navigator !== 'undefined';
+}
+/**
+ * Format args with color CSS and gg's patched prefix order:
+ *   +123ms namespace message
+ */
+function formatArgs(args) {
+    const h = humanize(this.diff);
+    const prefix = ('+' + h).padStart(6);
+    args[0] = (this.useColors ? '%c' : '') +
+        `${prefix} ${this.namespace}` +
+        (this.useColors ? ' %c' : ' ') +
+        args[0] +
+        (this.useColors ? '%c ' : ' ');
+    if (!this.useColors)
+        return;
+    const c = 'color: ' + this.color;
+    args.splice(1, 0, c, 'color: inherit');
+    // Insert CSS for the final %c
+    let index = 0;
+    let lastC = 0;
+    args[0].replace(/%[a-zA-Z%]/g, (match) => {
+        if (match === '%%')
+            return match;
+        index++;
+        if (match === '%c')
+            lastC = index;
+        return match;
+    });
+    args.splice(lastC, 0, c);
+}
+function save(namespaces) {
+    try {
+        if (namespaces) {
+            localStorage.setItem('debug', namespaces);
+        }
+        else {
+            localStorage.removeItem('debug');
+        }
+    }
+    catch {
+        // localStorage may not be available
+    }
+}
+function load() {
+    try {
+        return localStorage.getItem('debug') || localStorage.getItem('DEBUG') || '';
+    }
+    catch {
+        return '';
+    }
+}
+const log = console.debug || console.log || (() => { });
+const env = {
+    formatArgs,
+    save,
+    load,
+    useColors,
+    colors,
+    log,
+    formatters: {
+        /** %j → JSON.stringify (preserved for compatibility) */
+        j(v) {
+            try {
+                return JSON.stringify(v);
+            }
+            catch (e) {
+                return '[UnexpectedJSONParseError]: ' + e.message;
+            }
+        }
+    }
+};
+const debug = setup(env);
+export default debug;

package/dist/debug/common.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Internal debug implementation — replaces the `debug` npm package.
+ *
+ * Core logic: createDebug factory, enable/disable, namespace matching,
+ * color selection, and humanize (ms formatting).
+ */
+/** Format ms like debug's `ms` package: 0ms, 500ms, 5s, 2m, 1h, 3d */
+export declare function humanize(ms: number): string;
+export interface Debugger {
+    (...args: unknown[]): void;
+    namespace: string;
+    color: string;
+    diff: number;
+    enabled: boolean;
+    useColors: boolean;
+    formatArgs: (args: unknown[]) => void;
+    log: ((...args: unknown[]) => void) | null;
+}
+export interface DebugFactory {
+    (namespace: string): Debugger;
+    enable: (namespaces: string) => void;
+    disable: () => string;
+    enabled: (namespace: string) => boolean;
+    humanize: typeof humanize;
+    names: string[];
+    skips: string[];
+    namespaces: string;
+    formatters: Record<string, (this: Debugger, val: unknown) => string>;
+}
+/** Platform-specific hooks provided by browser.ts or node.ts */
+export interface DebugEnv {
+    formatArgs: (this: Debugger, args: unknown[]) => void;
+    save: (namespaces: string) => void;
+    load: () => string;
+    useColors: () => boolean;
+    colors: string[] | number[];
+    log: (...args: unknown[]) => void;
+    formatters?: Record<string, (this: Debugger, val: unknown) => string>;
+    init?: (instance: Debugger) => void;
+}
+export declare function setup(env: DebugEnv): DebugFactory;

package/dist/debug/common.js

@@ -0,0 +1,191 @@
+/**
+ * Internal debug implementation — replaces the `debug` npm package.
+ *
+ * Core logic: createDebug factory, enable/disable, namespace matching,
+ * color selection, and humanize (ms formatting).
+ */
+/** Format ms like debug's `ms` package: 0ms, 500ms, 5s, 2m, 1h, 3d */
+export function humanize(ms) {
+    const abs = Math.abs(ms);
+    if (abs >= 86_400_000)
+        return Math.round(ms / 86_400_000) + 'd';
+    if (abs >= 3_600_000)
+        return Math.round(ms / 3_600_000) + 'h';
+    if (abs >= 60_000)
+        return Math.round(ms / 60_000) + 'm';
+    if (abs >= 1_000)
+        return Math.round(ms / 1_000) + 's';
+    return ms + 'ms';
+}
+/**
+ * Wildcard pattern matching (same algorithm as debug's `matchesTemplate`).
+ * Supports `*` as a wildcard that matches any sequence of characters.
+ */
+function matchesTemplate(search, template) {
+    let si = 0;
+    let ti = 0;
+    let starIdx = -1;
+    let matchIdx = 0;
+    while (si < search.length) {
+        if (ti < template.length && (template[ti] === search[si] || template[ti] === '*')) {
+            if (template[ti] === '*') {
+                starIdx = ti;
+                matchIdx = si;
+                ti++;
+            }
+            else {
+                si++;
+                ti++;
+            }
+        }
+        else if (starIdx !== -1) {
+            ti = starIdx + 1;
+            matchIdx++;
+            si = matchIdx;
+        }
+        else {
+            return false;
+        }
+    }
+    while (ti < template.length && template[ti] === '*') {
+        ti++;
+    }
+    return ti === template.length;
+}
+// ── Factory ────────────────────────────────────────────────────────────
+export function setup(env) {
+    /** Deterministic color for a namespace (same hash as debug@4) */
+    function selectColor(namespace) {
+        let hash = 0;
+        for (let i = 0; i < namespace.length; i++) {
+            hash = ((hash << 5) - hash) + namespace.charCodeAt(i);
+            hash |= 0;
+        }
+        return env.colors[Math.abs(hash) % env.colors.length];
+    }
+    // Active include/exclude lists
+    let names = [];
+    let skips = [];
+    let currentNamespaces = '';
+    function enable(namespaces) {
+        env.save(namespaces);
+        currentNamespaces = namespaces;
+        names = [];
+        skips = [];
+        const parts = (typeof namespaces === 'string' ? namespaces : '')
+            .trim()
+            .replace(/\s+/g, ',')
+            .split(',')
+            .filter(Boolean);
+        for (const part of parts) {
+            if (part[0] === '-') {
+                skips.push(part.slice(1));
+            }
+            else {
+                names.push(part);
+            }
+        }
+        // Update factory-level arrays for external inspection
+        factory.names = names;
+        factory.skips = skips;
+        factory.namespaces = currentNamespaces;
+    }
+    function disable() {
+        const prev = [
+            ...names,
+            ...skips.map((ns) => '-' + ns)
+        ].join(',');
+        enable('');
+        return prev;
+    }
+    function enabled(name) {
+        for (const skip of skips) {
+            if (matchesTemplate(name, skip))
+                return false;
+        }
+        for (const ns of names) {
+            if (matchesTemplate(name, ns))
+                return true;
+        }
+        return false;
+    }
+    // ── createDebug ────────────────────────────────────────────────────
+    function createDebug(namespace) {
+        let prevTime;
+        let enableOverride = null;
+        let namespacesCache;
+        let enabledCache;
+        const debug = function (...args) {
+            if (!debug.enabled)
+                return;
+            const curr = Date.now();
+            const ms = curr - (prevTime || curr);
+            debug.diff = ms;
+            prevTime = curr;
+            // Coerce first arg
+            if (typeof args[0] !== 'string') {
+                args.unshift('%O');
+            }
+            // Apply %format replacements
+            let idx = 0;
+            args[0] = args[0].replace(/%([a-zA-Z%])/g, (match, fmt) => {
+                if (match === '%%')
+                    return '%';
+                idx++;
+                const formatter = factory.formatters[fmt];
+                if (typeof formatter === 'function') {
+                    const val = args[idx];
+                    match = formatter.call(debug, val);
+                    args.splice(idx, 1);
+                    idx--;
+                }
+                return match;
+            });
+            // Platform-specific formatting (colors, prefix)
+            debug.formatArgs(args);
+            const logFn = debug.log || env.log;
+            logFn.apply(debug, args);
+        };
+        debug.namespace = namespace;
+        debug.useColors = env.useColors();
+        debug.color = String(selectColor(namespace));
+        debug.diff = 0;
+        debug.log = null;
+        debug.formatArgs = function (args) {
+            env.formatArgs.call(debug, args);
+        };
+        Object.defineProperty(debug, 'enabled', {
+            enumerable: true,
+            configurable: false,
+            get: () => {
+                if (enableOverride !== null)
+                    return enableOverride;
+                if (namespacesCache !== currentNamespaces) {
+                    namespacesCache = currentNamespaces;
+                    enabledCache = enabled(namespace);
+                }
+                return enabledCache;
+            },
+            set: (v) => {
+                enableOverride = v;
+            }
+        });
+        if (env.init) {
+            env.init(debug);
+        }
+        return debug;
+    }
+    // ── Assemble factory ───────────────────────────────────────────────
+    const factory = createDebug;
+    factory.enable = enable;
+    factory.disable = disable;
+    factory.enabled = enabled;
+    factory.humanize = humanize;
+    factory.names = names;
+    factory.skips = skips;
+    factory.namespaces = '';
+    factory.formatters = { ...env.formatters };
+    // Initialize from persisted namespaces
+    enable(env.load());
+    return factory;
+}

package/dist/debug/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Debug entry point — selects browser or node implementation.
+ *
+ * Re-exports the DebugFactory and Debugger types for consumers.
+ */
+import type { DebugFactory } from './common.js';
+export type { DebugFactory, Debugger } from './common.js';
+declare const _default: DebugFactory;
+export default _default;

package/dist/debug/index.js

@@ -0,0 +1,11 @@
+/**
+ * Debug entry point — selects browser or node implementation.
+ *
+ * Re-exports the DebugFactory and Debugger types for consumers.
+ */
+import { BROWSER } from 'esm-env';
+// Conditional import: browser.ts for browsers, node.ts for Node/Deno/Bun
+const { default: debug } = BROWSER
+    ? await import('./browser.js')
+    : await import('./node.js');
+export default debug;

package/dist/debug/node.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Node.js-specific debug implementation.
+ *
+ * Output: process.stderr via util.formatWithOptions.
+ * Persistence: process.env.DEBUG
+ * Format (patched): +123ms namespace message (ANSI colored)
+ */
+import { type DebugFactory } from './common.js';
+declare const debug: DebugFactory;
+export default debug;