@presto1314w/vite-devtools-browser 0.3.2 → 0.3.5

package/dist/browser.js

@@ -19,6 +19,20 @@ export function setEventQueue(queue) {
 export function getEventQueue() {
     return eventQueue;
 }
+export function getTrackedHmrEvents(windowMs = 5000) {
+    const cutoff = Date.now() - windowMs;
+    return session.hmrEvents
+        .filter((event) => event.timestamp >= cutoff)
+        .map((event) => ({
+        timestamp: event.timestamp,
+        type: event.type === "error" ? "hmr-error" : "hmr-update",
+        payload: {
+            path: event.path,
+            message: event.message,
+            updates: event.path ? [{ path: event.path }] : [],
+        },
+    }));
+}
 export function getCurrentPage() {
     return getSessionPage(session);
 }
@@ -150,7 +164,7 @@ export async function goto(url) {
 }
 export async function back() {
     const currentPage = await ensurePage();
-    await currentPage.goBack({ waitUntil: "domcontentloaded" });
+    await navigateAndRefreshContext(currentPage, () => currentPage.goBack({ waitUntil: "domcontentloaded" }));
 }
 export async function reload() {
     const currentPage = await ensurePage();
@@ -317,8 +331,12 @@ function requireCurrentPage() {
 }
 async function navigateAndRefreshContext(currentPage, navigate, refreshFramework = false) {
     await navigate();
+    clearRuntimeErrors();
     await injectEventCollector(currentPage);
     if (refreshFramework) {
         await detectFramework();
     }
 }
+function clearRuntimeErrors() {
+    session.runtimeErrors.length = 0;
+}

package/dist/cli.js

@@ -205,63 +205,63 @@ export function exit(io, res, msg) {
     io.exit(0);
 }
 export function printUsage() {
-    return `
-vite-browser - Programmatic access to Vue/React/Svelte DevTools and Vite dev server
-
-USAGE
-  vite-browser <command> [options]
-
-BROWSER CONTROL
-  open <url> [--cookies-json <file>]  Launch browser and navigate
-  close                               Close browser and daemon
-  goto <url>                          Full-page navigation
-  back                                Go back in history
-  reload                              Reload current page
-
-FRAMEWORK DETECTION
-  detect                              Detect framework (vue/react/svelte)
-
-VUE COMMANDS
-  vue tree [id]                       Show Vue component tree or inspect component
-  vue pinia [store]                   Show Pinia stores or inspect specific store
-  vue router                          Show Vue Router information
-
-REACT COMMANDS
-  react tree [id]                     Show React component tree or inspect component
-
-SVELTE COMMANDS
-  svelte tree [id]                    Show Svelte component tree or inspect component
-
-VITE COMMANDS
-  vite restart                        Restart Vite dev server
-  vite hmr                            Show HMR summary
-  vite hmr trace [--limit <n>]        Show HMR timeline
-  vite hmr clear                      Clear tracked HMR timeline
-  vite runtime                        Show Vite runtime status
-  vite module-graph [--filter <txt>] [--limit <n>]
-                                     Show loaded Vite module resources
-  vite module-graph trace [--filter <txt>] [--limit <n>]
-                                     Show module additions/removals since baseline
-  vite module-graph clear             Clear module-graph baseline
-  errors                              Show build/runtime errors
-  errors --mapped                     Show errors with source-map mapping
-  errors --mapped --inline-source     Include mapped source snippets
-  correlate errors [--window <ms>]    Correlate current errors with recent HMR events
-  correlate renders [--window <ms>]   Summarize recent render/update propagation evidence
-  correlate errors --mapped           Correlate mapped errors with recent HMR events
-  diagnose hmr [--window <ms>]        Diagnose HMR failures from runtime, errors, and trace data
-  diagnose hmr [--limit <n>]          Control how many recent HMR trace entries are inspected
-  diagnose propagation [--window <ms>]
-                                     Diagnose likely update -> render -> error propagation
-  logs                                Show dev server logs
-
-UTILITIES
-  screenshot                          Save screenshot to temp file
-  eval <script>                       Evaluate JavaScript in page context
-  network [idx]                       List network requests or inspect one
-
-OPTIONS
-  -h, --help                          Show this help message
+    return `
+vite-browser - Programmatic access to Vue/React/Svelte DevTools and Vite dev server
+
+USAGE
+  vite-browser <command> [options]
+
+BROWSER CONTROL
+  open <url> [--cookies-json <file>]  Launch browser and navigate
+  close                               Close browser and daemon
+  goto <url>                          Full-page navigation
+  back                                Go back in history
+  reload                              Reload current page
+
+FRAMEWORK DETECTION
+  detect                              Detect framework (vue/react/svelte)
+
+VUE COMMANDS
+  vue tree [id]                       Show Vue component tree or inspect component
+  vue pinia [store]                   Show Pinia stores or inspect specific store
+  vue router                          Show Vue Router information
+
+REACT COMMANDS
+  react tree [id]                     Show React component tree or inspect component
+
+SVELTE COMMANDS
+  svelte tree [id]                    Show Svelte component tree or inspect component
+
+VITE COMMANDS
+  vite restart                        Restart Vite dev server
+  vite hmr                            Show HMR summary
+  vite hmr trace [--limit <n>]        Show HMR timeline
+  vite hmr clear                      Clear tracked HMR timeline
+  vite runtime                        Show Vite runtime status
+  vite module-graph [--filter <txt>] [--limit <n>]
+                                     Show loaded Vite module resources
+  vite module-graph trace [--filter <txt>] [--limit <n>]
+                                     Show module additions/removals since baseline
+  vite module-graph clear             Clear module-graph baseline
+  errors                              Show build/runtime errors
+  errors --mapped                     Show errors with source-map mapping
+  errors --mapped --inline-source     Include mapped source snippets
+  correlate errors [--window <ms>]    Correlate current errors with recent HMR events
+  correlate renders [--window <ms>]   Summarize recent render/update propagation evidence
+  correlate errors --mapped           Correlate mapped errors with recent HMR events
+  diagnose hmr [--window <ms>]        Diagnose HMR failures from runtime, errors, and trace data
+  diagnose hmr [--limit <n>]          Control how many recent HMR trace entries are inspected
+  diagnose propagation [--window <ms>]
+                                     Diagnose likely update -> render -> error propagation
+  logs                                Show dev server logs
+
+UTILITIES
+  screenshot                          Save screenshot to temp file
+  eval <script>                       Evaluate JavaScript in page context
+  network [idx]                       List network requests or inspect one
+
+OPTIONS
+  -h, --help                          Show this help message
 `;
 }
 function isEntrypoint(argv1) {

package/dist/client.js

@@ -3,7 +3,7 @@ import { readFileSync, existsSync, rmSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
-import { socketPath, pidFile } from "./paths.js";
+import { socketPath, pidFile, isWindows } from "./paths.js";
 export function createClientDeps() {
     const ext = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
     const daemonPath = fileURLToPath(new URL(`./daemon${ext}`, import.meta.url));
@@ -86,7 +86,7 @@ export function no() {
     return false;
 }
 export function removeSocketFile(path, removeFile = rmSync) {
-    if (process.platform === "win32")
+    if (isWindows)
         return;
     removeFile(path, { force: true });
 }

package/dist/daemon.js

@@ -6,7 +6,9 @@ import * as browser from "./browser.js";
 import { correlateErrorWithHMR, formatErrorCorrelationReport } from "./correlate.js";
 import { diagnoseHMR, formatDiagnosisReport } from "./diagnose.js";
 import { diagnosePropagation, formatPropagationDiagnosisReport } from "./diagnose-propagation.js";
+import { extractModules } from "./event-analysis.js";
 import { socketDir, socketPath, pidFile } from "./paths.js";
+import { removeSocketFile } from "./client.js";
 import { correlateRenderPropagation, formatPropagationTraceReport } from "./trace.js";
 import { EventQueue } from "./event-queue.js";
 import * as networkLog from "./network.js";
@@ -100,12 +102,20 @@ export function createRunner(api = browser) {
         if (cmd.action === "correlate-errors") {
             const errorText = String(await api.errors(Boolean(cmd.mapped), Boolean(cmd.inlineSource)));
             const events = queue ? queue.window(cmd.windowMs ?? 5000) : [];
-            const data = formatErrorCorrelationReport(errorText, errorText === "no errors" ? null : correlateErrorWithHMR(errorText, events, cmd.windowMs ?? 5000));
+            const fallbackHmrEvents = readTrackedHmrEvents(api, cmd.windowMs ?? 5000);
+            const hmrTraceText = String(await api.viteHMRTrace("trace", 20));
+            const fallbackModules = extractModules(hmrTraceText);
+            const baseCorrelation = errorText === "no errors"
+                ? null
+                : correlateErrorWithHMR(errorText, [...events, ...fallbackHmrEvents], cmd.windowMs ?? 5000);
+            const data = formatErrorCorrelationReport(errorText, errorText === "no errors"
+                ? null
+                : upgradeErrorCorrelation(baseCorrelation, fallbackModules, cmd.windowMs ?? 5000));
             return { ok: true, data };
         }
         if (cmd.action === "correlate-renders") {
             const events = await getSettledEventWindow(api, queue, cmd.windowMs ?? 5000);
-            const data = formatPropagationTraceReport(await buildPropagationTrace(api, events));
+            const data = formatPropagationTraceReport(await buildPropagationTrace(api, events, cmd.windowMs ?? 5000));
             return { ok: true, data };
         }
         if (cmd.action === "diagnose-hmr") {
@@ -119,7 +129,7 @@ export function createRunner(api = browser) {
         }
         if (cmd.action === "diagnose-propagation") {
             const events = await getSettledEventWindow(api, queue, cmd.windowMs ?? 5000);
-            const data = formatPropagationDiagnosisReport(diagnosePropagation(await buildPropagationTrace(api, events)));
+            const data = formatPropagationDiagnosisReport(diagnosePropagation(await buildPropagationTrace(api, events, cmd.windowMs ?? 5000)));
             return { ok: true, data };
         }
         if (cmd.action === "logs") {
@@ -146,20 +156,89 @@ export function createRunner(api = browser) {
         return { ok: false, error: `unknown action: ${cmd.action}` };
     };
 }
-async function buildPropagationTrace(api, events) {
-    const trace = correlateRenderPropagation(events);
+async function buildPropagationTrace(api, events, windowMs) {
+    const hmrTraceText = String(await api.viteHMRTrace("trace", 20));
+    const fallbackModules = extractModules(hmrTraceText);
+    const trace = correlateRenderPropagation([...events, ...readTrackedHmrEvents(api, windowMs)]);
     if (!trace)
         return null;
-    if (trace.errorMessages.length > 0)
-        return trace;
+    let augmented = trace;
+    if (augmented.sourceModules.length === 0 && fallbackModules.length > 0) {
+        augmented = {
+            ...augmented,
+            sourceModules: fallbackModules,
+        };
+    }
+    if (augmented.changedKeys.length === 0 && augmented.storeUpdates.length > 0) {
+        const inferredChangedKeys = await inferLikelyChangedKeys(api, augmented.storeUpdates[0]);
+        if (inferredChangedKeys.length > 0) {
+            augmented = {
+                ...augmented,
+                changedKeys: inferredChangedKeys,
+            };
+        }
+    }
+    if (augmented.errorMessages.length > 0)
+        return augmented;
     const currentError = String(await api.errors(false, false));
     if (!currentError || currentError === "no errors")
-        return trace;
+        return augmented;
     return {
-        ...trace,
-        errorMessages: [currentError, ...trace.errorMessages],
+        ...augmented,
+        errorMessages: [currentError, ...augmented.errorMessages],
     };
 }
+function upgradeErrorCorrelation(correlation, fallbackModules, windowMs) {
+    if (fallbackModules.length === 0)
+        return correlation;
+    if (!correlation)
+        return synthesizeErrorCorrelation(fallbackModules, windowMs);
+    if (correlation.matchingModules.length > 0)
+        return correlation;
+    return synthesizeErrorCorrelation(fallbackModules, windowMs, correlation.relatedEvents);
+}
+function synthesizeErrorCorrelation(modules, windowMs, relatedEvents = []) {
+    if (modules.length === 0)
+        return null;
+    return {
+        summary: `HMR update observed within ${windowMs}ms of the current error`,
+        detail: `Matching modules: ${modules.join(", ")}\nRecent events considered: ${modules.length}`,
+        confidence: "high",
+        windowMs,
+        matchingModules: modules,
+        relatedEvents: relatedEvents.length > 0
+            ? relatedEvents
+            : modules.map((module) => ({
+                timestamp: Date.now(),
+                type: "hmr-update",
+                payload: {
+                    path: module,
+                    updates: [{ path: module }],
+                },
+            })),
+    };
+}
+async function inferLikelyChangedKeys(api, storeName) {
+    try {
+        const raw = await api.evaluate(`(() => {
+        const store = window.__PINIA__?._s?.get(${JSON.stringify(storeName)});
+        if (!store) return [];
+        return Object.keys(store).filter((key) => store[key] === undefined);
+      })()`);
+        const parsed = JSON.parse(String(raw));
+        return Array.isArray(parsed) ? parsed.filter((value) => typeof value === "string" && value.length > 0) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function readTrackedHmrEvents(api, windowMs) {
+    const reader = api.getTrackedHmrEvents;
+    if (typeof reader !== "function")
+        return [];
+    const events = reader(windowMs);
+    return Array.isArray(events) ? events : [];
+}
 async function flushCurrentPageEvents(api, queue) {
     if (!queue)
         return;
@@ -225,7 +304,7 @@ export function startDaemon() {
     networkLog.setEventQueue(eventQueue);
     const run = createRunner();
     mkdirSync(socketDir, { recursive: true, mode: 0o700 });
-    removeSocketFile();
+    removeSocketFile(socketPath);
     rmSync(pidFile, { force: true });
     writeFileSync(pidFile, String(process.pid));
     const server = createServer((socket) => {
@@ -252,16 +331,10 @@ export function startDaemon() {
         process.exit(0);
     }
     function cleanup() {
-        removeSocketFile();
+        removeSocketFile(socketPath);
         rmSync(pidFile, { force: true });
     }
 }
-function removeSocketFile() {
-    // Windows named pipes are not filesystem entries, so unlinking them fails with EPERM.
-    if (process.platform === "win32")
-        return;
-    rmSync(socketPath, { force: true });
-}
 if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
     startDaemon();
 }

package/dist/event-queue.d.ts

@@ -74,8 +74,15 @@ export declare class EventQueue {
     private readonly maxSize;
     constructor(maxSize?: number);
     push(event: VBEvent): void;
+    /** Bubble the element at `idx` leftward to restore sorted order. */
+    private _insertionSort;
     /**
-     * Return all events within the last `ms` milliseconds before `before`
+     * Return all events within the last `ms` milliseconds before `before`.
+     *
+     * Uses binary search to find the start index (O(log n)) then slices,
+     * which is significantly faster than a full linear scan for large queues.
+     * Events are maintained in insertion order, which for timestamped pushes
+     * is monotonically non-decreasing.
      */
     window(ms: number, before?: number): VBEvent[];
     /**
@@ -83,5 +90,7 @@ export declare class EventQueue {
      */
     ofType(type: VBEventType): VBEvent[];
     all(): VBEvent[];
+    /** Number of events currently stored */
+    get size(): number;
     clear(): void;
 }

package/dist/event-queue.js

@@ -9,13 +9,59 @@ export class EventQueue {
         if (this.events.length > this.maxSize) {
             this.events.shift();
         }
+        // Maintain sorted order by timestamp.  Events almost always arrive
+        // in order, so the fast path (no swap) costs a single comparison.
+        const len = this.events.length;
+        if (len >= 2 && this.events[len - 1].timestamp < this.events[len - 2].timestamp) {
+            this._insertionSort(len - 1);
+        }
+    }
+    /** Bubble the element at `idx` leftward to restore sorted order. */
+    _insertionSort(idx) {
+        const events = this.events;
+        const item = events[idx];
+        let j = idx - 1;
+        while (j >= 0 && events[j].timestamp > item.timestamp) {
+            events[j + 1] = events[j];
+            j--;
+        }
+        events[j + 1] = item;
     }
     /**
-     * Return all events within the last `ms` milliseconds before `before`
+     * Return all events within the last `ms` milliseconds before `before`.
+     *
+     * Uses binary search to find the start index (O(log n)) then slices,
+     * which is significantly faster than a full linear scan for large queues.
+     * Events are maintained in insertion order, which for timestamped pushes
+     * is monotonically non-decreasing.
      */
     window(ms, before = Date.now()) {
         const start = before - ms;
-        return this.events.filter((e) => e.timestamp >= start && e.timestamp <= before);
+        const events = this.events;
+        const len = events.length;
+        if (len === 0)
+            return [];
+        // Binary search for the first event with timestamp >= start
+        let lo = 0;
+        let hi = len;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (events[mid].timestamp < start) {
+                lo = mid + 1;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        // Linear scan from lo for events <= before
+        // (in practice, `before` is usually Date.now() so most events qualify)
+        const result = [];
+        for (let i = lo; i < len; i++) {
+            if (events[i].timestamp > before)
+                break;
+            result.push(events[i]);
+        }
+        return result;
     }
     /**
      * Return all events of a given type
@@ -26,6 +72,10 @@ export class EventQueue {
     all() {
         return [...this.events];
     }
+    /** Number of events currently stored */
+    get size() {
+        return this.events.length;
+    }
     clear() {
         this.events = [];
     }

package/dist/paths.d.ts

@@ -1,3 +1,28 @@
+export declare const isWindows: boolean;
+export declare const isLinux: boolean;
+/**
+ * Sanitize a session name for safe use in file paths and pipe names.
+ */
+export declare function sanitizeSession(name: string): string;
+/**
+ * Resolve the base directory for vite-browser runtime files.
+ *
+ * Uses `~/.vite-browser` on all platforms.
+ * Falls back to `$TMPDIR/vite-browser-<uid>` when the home directory
+ * is not writable (e.g. some CI/container environments).
+ */
+export declare function resolveSocketDir(): string;
 export declare const socketDir: string;
+/**
+ * Socket path for the daemon.
+ *
+ * - Windows: uses a named pipe `\\.\pipe\vite-browser-<session>`
+ * - Unix: uses a Unix domain socket file in socketDir
+ *
+ * Note: Unix socket paths have a ~104-char limit on macOS and ~108 on
+ * Linux.  The `~/.vite-browser/<session>.sock` path is well within
+ * that range.  The tmpdir fallback may produce longer paths; we keep
+ * them short by using numeric uid.
+ */
 export declare const socketPath: string;
 export declare const pidFile: string;

package/dist/paths.js

@@ -1,8 +1,46 @@
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
-const isWindows = process.platform === "win32";
-const session = process.env.VITE_BROWSER_SESSION || "default";
-export const socketDir = join(homedir(), ".vite-browser");
+export const isWindows = process.platform === "win32";
+export const isLinux = process.platform === "linux";
+/**
+ * Sanitize a session name for safe use in file paths and pipe names.
+ */
+export function sanitizeSession(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+const session = sanitizeSession(process.env.VITE_BROWSER_SESSION || "default");
+/**
+ * Resolve the base directory for vite-browser runtime files.
+ *
+ * Uses `~/.vite-browser` on all platforms.
+ * Falls back to `$TMPDIR/vite-browser-<uid>` when the home directory
+ * is not writable (e.g. some CI/container environments).
+ */
+export function resolveSocketDir() {
+    try {
+        const home = homedir();
+        if (home)
+            return join(home, ".vite-browser");
+    }
+    catch {
+        // homedir() can throw on misconfigured systems
+    }
+    // Fallback: use tmpdir scoped by uid to avoid collisions
+    const uid = process.getuid?.() ?? process.pid;
+    return join(tmpdir(), `vite-browser-${uid}`);
+}
+export const socketDir = resolveSocketDir();
+/**
+ * Socket path for the daemon.
+ *
+ * - Windows: uses a named pipe `\\.\pipe\vite-browser-<session>`
+ * - Unix: uses a Unix domain socket file in socketDir
+ *
+ * Note: Unix socket paths have a ~104-char limit on macOS and ~108 on
+ * Linux.  The `~/.vite-browser/<session>.sock` path is well within
+ * that range.  The tmpdir fallback may produce longer paths; we keep
+ * them short by using numeric uid.
+ */
 export const socketPath = isWindows
     ? `\\\\.\\pipe\\vite-browser-${session}`
     : join(socketDir, `${session}.sock`);

package/dist/react/hook-manager.d.ts

@@ -0,0 +1,29 @@
+/**
+ * React DevTools Hook Management
+ *
+ * Provides health checks and auto-injection for the bundled React DevTools hook.
+ * This removes the dependency on external browser extensions for React inspection.
+ */
+import type { Page } from "playwright";
+/**
+ * Get the hook source code, lazily loaded and cached
+ */
+export declare function getHookSource(): string;
+export interface HookHealthStatus {
+    installed: boolean;
+    hasRenderers: boolean;
+    rendererCount: number;
+    hasFiberSupport: boolean;
+}
+/**
+ * Check the health of the React DevTools hook in the page
+ */
+export declare function checkHookHealth(page: Page): Promise<HookHealthStatus>;
+/**
+ * Inject the React DevTools hook into a page if not already present
+ */
+export declare function injectHook(page: Page): Promise<boolean>;
+/**
+ * Format hook health status for CLI output
+ */
+export declare function formatHookHealth(status: HookHealthStatus): string;

package/dist/react/hook-manager.js

@@ -0,0 +1,75 @@
+/**
+ * React DevTools Hook Management
+ *
+ * Provides health checks and auto-injection for the bundled React DevTools hook.
+ * This removes the dependency on external browser extensions for React inspection.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/** Path to the bundled React DevTools hook */
+const hookPath = resolve(import.meta.dirname, "./hook.js");
+/** Cached hook source code */
+let hookSource = null;
+/**
+ * Get the hook source code, lazily loaded and cached
+ */
+export function getHookSource() {
+    if (!hookSource) {
+        hookSource = readFileSync(hookPath, "utf-8");
+    }
+    return hookSource;
+}
+/**
+ * Check the health of the React DevTools hook in the page
+ */
+export async function checkHookHealth(page) {
+    return page.evaluate(inPageCheckHookHealth);
+}
+/**
+ * Inject the React DevTools hook into a page if not already present
+ */
+export async function injectHook(page) {
+    const alreadyInstalled = await page.evaluate(() => !!window.__REACT_DEVTOOLS_GLOBAL_HOOK__);
+    if (alreadyInstalled)
+        return false;
+    await page.evaluate(getHookSource());
+    return true;
+}
+/**
+ * Format hook health status for CLI output
+ */
+export function formatHookHealth(status) {
+    const lines = ["# React DevTools Hook Status\n"];
+    lines.push(`Installed: ${status.installed ? "✅ Yes" : "❌ No"}`);
+    lines.push(`Fiber support: ${status.hasFiberSupport ? "✅ Yes" : "❌ No"}`);
+    lines.push(`Renderers: ${status.rendererCount}`);
+    lines.push(`Has renderers: ${status.hasRenderers ? "✅ Yes" : "❌ No"}`);
+    if (!status.installed) {
+        lines.push("\n⚠️ Hook not installed. React DevTools features will not work.");
+        lines.push("The hook should be injected before React loads.");
+    }
+    else if (!status.hasRenderers) {
+        lines.push("\n⚠️ No React renderers detected.");
+        lines.push("This page may not be using React, or React hasn't mounted yet.");
+    }
+    return lines.join("\n");
+}
+// In-page functions
+function inPageCheckHookHealth() {
+    const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    if (!hook) {
+        return {
+            installed: false,
+            hasRenderers: false,
+            rendererCount: 0,
+            hasFiberSupport: false,
+        };
+    }
+    const rendererCount = hook.renderers?.size ?? 0;
+    return {
+        installed: true,
+        hasRenderers: rendererCount > 0,
+        rendererCount,
+        hasFiberSupport: !!hook.supportsFiber,
+    };
+}

package/dist/react/hook.d.ts

@@ -0,0 +1 @@
+export {};