@presto1314w/vite-devtools-browser 0.1.4 → 0.2.2

package/README.md

@@ -1,10 +1,66 @@
 # vite-browser
 
-`vite-browser` is a debugging toolchain for Vite apps:
+`vite-browser` is a runtime diagnostics toolchain for Vite applications.
+
+It gives agents and developers structured access to:
+
+- Vue, React, and Svelte runtime state
+- Vite HMR activity and runtime health
+- event-window correlation between current errors and recent hot updates
+- rule-based HMR diagnosis with confidence levels
+- module graph snapshots and diffs
+- mapped error output with optional source snippets
+- network, logs, screenshots, and page evaluation
+
+It ships in two forms:
+
 - Agent Skill: scenario-based debugging workflows for coding assistants
-- CLI Runtime (`@presto1314w/vite-devtools-browser`): structured inspection of Vue/React/Svelte runtime state
+- CLI Runtime (`@presto1314w/vite-devtools-browser`): structured shell commands for local Vite debugging
+
+Current documented baseline: `v0.2.2`.
+
+## What's New In v0.2
+
+`v0.2.x` moves `vite-browser` from snapshot-style inspection toward runtime diagnosis:
+
+- browser/runtime events are captured into a daemon-side event queue
+- `correlate errors` links the current error to recent HMR-updated modules
+- `diagnose hmr` turns runtime, trace, and error signals into structured findings
+- skills and CLI flows now route more directly to runtime triage instead of raw log inspection
+
+`v0.2.2` is the stabilization pass for this model:
+
+- tighter `diagnose hmr` wording around websocket evidence and runtime ambiguity
+- better test coverage for the four built-in diagnosis families
+- docs and release positioning aligned around the stable `v0.2.x` surface
+
+## Built For Agents
+
+`vite-browser` is designed for agent workflows as much as local debugging.
+
+Models do not work well with a DevTools panel that has to be visually inspected step by step. They work much better when runtime signals are exposed as structured commands that can be queried, compared, and chained in a loop. `vite-browser` turns framework state, Vite runtime status, HMR activity, module graph changes, mapped errors, logs, and network activity into terminal output that an agent can actually reason about.
+
+Under the hood, each command is a one-shot request against a long-lived browser daemon. That keeps the CLI simple for users while letting agent loops inspect a running app repeatedly without having to manage browser lifecycle on every step.
+
+## Why vite-browser
+
+Most browser CLIs are optimized for automation. Most framework devtools are optimized for humans in a GUI.
+
+`vite-browser` is optimized for structured Vite runtime debugging:
 
-Current documented baseline: `v0.1.4`.
+- it can inspect framework state like a devtools bridge
+- it can explain Vite-specific behavior like HMR updates and module graph changes
+- it can correlate recent updates with current failures
+- it returns structured text that AI agents can consume directly in loops
+
+## Positioning
+
+| Tool | Best for | Notable gap compared with `vite-browser` |
+| --- | --- | --- |
+| `agent-browser` | general browser automation | not focused on Vite runtime diagnostics |
+| `next-browser` | Next.js + React debugging | not designed as a Vite runtime tool |
+| `vite-plugin-vue-mcp` | Vue MCP integration inside Vite | plugin/MCP-first, not a standalone diagnostics CLI |
+| `vite-browser` | Vite runtime diagnostics for agents and developers | browser lifecycle coverage still being expanded |
 
 ## Install
 
@@ -31,16 +87,69 @@ npm run dev
 # terminal B: inspect runtime
 vite-browser open http://localhost:5173
 vite-browser detect
-vite-browser vue tree
-vite-browser vue pinia
 vite-browser vite runtime
+vite-browser errors --mapped --inline-source
+vite-browser correlate errors --mapped --window 5000
+vite-browser diagnose hmr --limit 50
 vite-browser vite hmr trace --limit 20
 vite-browser vite module-graph trace --limit 50
-vite-browser errors --mapped --inline-source
 vite-browser network
 vite-browser close
 ```
 
+For component/state debugging, then branch into framework-specific commands:
+
+```bash
+vite-browser vue tree
+vite-browser vue pinia
+vite-browser vue router
+vite-browser react tree
+vite-browser svelte tree
+```
+
+## What It Looks Like
+
+```bash
+$ vite-browser vite runtime
+# Vite Runtime
+URL: http://localhost:5173/
+Framework: vue
+Vite Client: loaded
+HMR Socket: open
+Error Overlay: none
+Tracked HMR Events: 3
+
+$ vite-browser vite hmr trace --limit 5
+# HMR Trace
+[12:34:10] connected [vite] connected.
+[12:34:15] update /src/App.vue
+
+$ vite-browser errors --mapped --inline-source
+Failed to resolve import "./missing"
+
+# Mapped Stack
+- http://localhost:5173/src/main.ts:12:4 -> /src/main.ts:12:4
+  12 | import "./missing"
+
+$ vite-browser correlate errors --mapped --window 5000
+# Error Correlation
+## Current Error
+TypeError: boom at /src/App.tsx:4:2
+
+## Correlation
+Confidence: high
+HMR update observed within 5000ms of the current error
+Matching modules: /src/App.tsx
+
+$ vite-browser diagnose hmr --limit 50
+# HMR Diagnosis
+## missing-module
+Status: fail
+Confidence: high
+A module import failed to resolve during HMR.
+Suggestion: Verify the import path, file extension, alias configuration, and whether the module exists on disk.
+```
+
 ## Core Capabilities
 
 - Framework detection: Vue/React/Svelte best-effort detection and version hinting
@@ -51,9 +160,55 @@ vite-browser close
   - runtime status summary
   - HMR summary/timeline/clear
   - module-graph snapshot/diff/clear
+  - error/HMR correlation over recent event windows
+  - rule-based HMR diagnosis with confidence levels
   - source-mapped errors with optional inline source snippet
 - Debug utilities: console logs, network tracing, screenshot, page `eval`
 
+## Recommended Workflows
+
+### Runtime/HMR triage
+
+```bash
+vite-browser vite runtime
+vite-browser errors --mapped --inline-source
+vite-browser correlate errors --mapped --window 5000
+vite-browser diagnose hmr --limit 50
+vite-browser vite hmr trace --limit 50
+vite-browser vite module-graph trace --limit 200
+```
+
+### Data/API triage
+
+```bash
+vite-browser errors --mapped
+vite-browser logs
+vite-browser network
+vite-browser network <idx>
+vite-browser eval '<state probe>'
+```
+
+### Component/state triage
+
+```bash
+vite-browser detect
+vite-browser vue tree
+vite-browser vue pinia
+vite-browser vue router
+vite-browser react tree
+vite-browser svelte tree
+```
+
+## Current Boundaries
+
+`vite-browser` v0.2.2 is strong at:
+
+- surfacing runtime state as structured shell output
+- linking current errors to recent HMR/module activity
+- detecting several common HMR failure patterns quickly
+
+It is not yet a full propagation-trace engine. In particular, it does not reliably infer deep chains like `store -> component A -> component B -> error` across arbitrary component graphs.
+
 ## Command Reference
 
 ### Browser
@@ -91,6 +246,9 @@ vite-browser vite module-graph clear
 vite-browser errors
 vite-browser errors --mapped
 vite-browser errors --mapped --inline-source
+vite-browser correlate errors [--window <ms>]
+vite-browser correlate errors --mapped --inline-source
+vite-browser diagnose hmr [--window <ms>] [--limit <n>]
 ```
 
 ### Utilities
@@ -124,6 +282,10 @@ pnpm test:evals
 pnpm test:evals:e2e
 ```
 
+## Discovery
+
+If you want to introduce the project to new users, start with the launch kit in [docs/launch-kit.md](./docs/launch-kit.md).
+
 ## Requirements
 
 - Node.js `>=20`

package/dist/browser.d.ts

@@ -1,5 +1,6 @@
-import { type BrowserContext } from "playwright";
+import { type BrowserContext, type Page } from "playwright";
 import { resolveViaSourceMap } from "./sourcemap.js";
+import { EventQueue } from "./event-queue.js";
 type HmrEventType = "connecting" | "connected" | "update" | "full-reload" | "error" | "log";
 export type HmrEvent = {
     timestamp: number;
@@ -20,6 +21,13 @@ export type ModuleRow = {
     durationMs: number;
 };
 export type ModuleGraphMode = "snapshot" | "trace" | "clear";
+export declare function setEventQueue(queue: EventQueue): void;
+export declare function getEventQueue(): EventQueue | null;
+export declare function getCurrentPage(): Page | null;
+/**
+ * Flush browser events into daemon event queue
+ */
+export declare function flushBrowserEvents(currentPage: Page, queue: EventQueue): Promise<void>;
 export declare function open(url: string | undefined): Promise<void>;
 export declare function cookies(cookies: {
     name: string;

package/dist/browser.js

@@ -17,16 +17,107 @@ let context = null;
 let page = null;
 let framework = "unknown";
 let extensionModeDisabled = false;
+let eventQueue = null;
 const consoleLogs = [];
 const MAX_LOGS = 200;
 const MAX_HMR_EVENTS = 500;
 let lastReactSnapshot = [];
 const hmrEvents = [];
 let lastModuleGraphUrls = null;
+export function setEventQueue(queue) {
+    eventQueue = queue;
+}
+export function getEventQueue() {
+    return eventQueue;
+}
+export function getCurrentPage() {
+    if (!contextUsable(context))
+        return null;
+    if (!page || page.isClosed())
+        return null;
+    return page;
+}
+/**
+ * Inject browser-side event collector into the page
+ */
+async function injectEventCollector(currentPage) {
+    await currentPage.evaluate(() => {
+        if (window.__vb_events)
+            return; // already injected
+        window.__vb_events = [];
+        window.__vb_push = (event) => {
+            const q = window.__vb_events;
+            q.push(event);
+            if (q.length > 1000)
+                q.shift();
+        };
+        // Subscribe to Vite HMR WebSocket
+        function attachViteListener() {
+            const hot = window.__vite_hot;
+            if (hot?.ws) {
+                hot.ws.addEventListener('message', (e) => {
+                    try {
+                        const data = JSON.parse(e.data);
+                        window.__vb_push({
+                            timestamp: Date.now(),
+                            type: data.type === 'error' ? 'hmr-error' : 'hmr-update',
+                            payload: data
+                        });
+                    }
+                    catch { }
+                });
+                return true;
+            }
+            return false;
+        }
+        // Retry if __vite_hot not ready yet
+        if (!attachViteListener()) {
+            let attempts = 0;
+            const timer = setInterval(() => {
+                attempts++;
+                if (attachViteListener() || attempts >= 50) {
+                    clearInterval(timer);
+                }
+            }, 100);
+        }
+        // Hook window.onerror for runtime errors
+        const origOnError = window.onerror;
+        window.onerror = (msg, src, line, col, err) => {
+            window.__vb_push({
+                timestamp: Date.now(),
+                type: 'error',
+                payload: { message: String(msg), source: src, line, col, stack: err?.stack }
+            });
+            return origOnError ? origOnError(msg, src, line, col, err) : false;
+        };
+        // Hook unhandledrejection
+        window.addEventListener('unhandledrejection', (e) => {
+            window.__vb_push({
+                timestamp: Date.now(),
+                type: 'error',
+                payload: { message: e.reason?.message, stack: e.reason?.stack }
+            });
+        });
+    });
+}
+/**
+ * Flush browser events into daemon event queue
+ */
+export async function flushBrowserEvents(currentPage, queue) {
+    const raw = await currentPage.evaluate(() => {
+        const events = window.__vb_events ?? [];
+        window.__vb_events = []; // clear after flush
+        return events;
+    });
+    for (const e of raw) {
+        queue.push(e);
+    }
+}
 export async function open(url) {
     const currentPage = await ensurePage();
     if (url) {
         await currentPage.goto(url, { waitUntil: "domcontentloaded" });
+        await injectEventCollector(currentPage);
         await detectFramework();
     }
 }
@@ -256,6 +347,7 @@ export function formatModuleGraphTrace(currentUrls, previousUrls, filter, limit
 export async function goto(url) {
     const currentPage = await ensurePage();
     await currentPage.goto(url, { waitUntil: "domcontentloaded" });
+    await injectEventCollector(currentPage);
     await detectFramework();
     return currentPage.url();
 }

package/dist/cli.js

@@ -136,6 +136,21 @@ export async function runCli(argv, io) {
         const res = await io.send("errors", { mapped, inlineSource });
         exit(io, res, res.ok && res.data ? String(res.data) : "no errors");
     }
+    if (cmd === "correlate" && arg === "errors") {
+        const mapped = args.includes("--mapped");
+        const inlineSource = args.includes("--inline-source");
+        const windowMs = parseNumberFlag(args, "--window", 5000);
+        const res = await io.send("correlate-errors", { mapped, inlineSource, windowMs });
+        exit(io, res, res.ok && res.data ? String(res.data) : "");
+    }
+    if (cmd === "diagnose" && arg === "hmr") {
+        const mapped = args.includes("--mapped");
+        const inlineSource = args.includes("--inline-source");
+        const windowMs = parseNumberFlag(args, "--window", 5000);
+        const limit = parseNumberFlag(args, "--limit", 50);
+        const res = await io.send("diagnose-hmr", { mapped, inlineSource, windowMs, limit });
+        exit(io, res, res.ok && res.data ? String(res.data) : "");
+    }
     if (cmd === "logs") {
         const res = await io.send("logs");
         exit(io, res, res.ok && res.data ? String(res.data) : "");
@@ -211,6 +226,10 @@ VITE COMMANDS
   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 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
   logs                                Show dev server logs
 
 UTILITIES

package/dist/correlate.d.ts

@@ -0,0 +1,20 @@
+import type { VBEvent } from "./event-queue.js";
+export type CorrelationConfidence = "high" | "medium" | "low";
+export type ErrorCorrelation = {
+    summary: string;
+    detail: string;
+    confidence: CorrelationConfidence;
+    windowMs: number;
+    matchingModules: string[];
+    relatedEvents: VBEvent[];
+};
+export type RenderNetworkCorrelation = {
+    summary: string;
+    detail: string;
+    confidence: CorrelationConfidence;
+    requestCount: number;
+    urls: string[];
+};
+export declare function correlateErrorWithHMR(errorText: string, events: VBEvent[], windowMs?: number): ErrorCorrelation | null;
+export declare function correlateRenderWithNetwork(events: VBEvent[], requestThreshold?: number): RenderNetworkCorrelation | null;
+export declare function formatErrorCorrelationReport(errorText: string, correlation: ErrorCorrelation | null): string;

package/dist/correlate.js

@@ -0,0 +1,110 @@
+const MODULE_PATTERNS = [
+    /\/src\/[^\s"'`):]+/g,
+    /\/@fs\/[^\s"'`):]+/g,
+    /[A-Za-z]:\\[^:\n]+/g,
+];
+export function correlateErrorWithHMR(errorText, events, windowMs = 5000) {
+    const recentEvents = events.filter((event) => event.type === "hmr-update" || event.type === "hmr-error");
+    if (recentEvents.length === 0)
+        return null;
+    const errorModules = extractModules(errorText);
+    const matchedEvents = recentEvents.filter((event) => {
+        const modules = extractModulesFromEvent(event);
+        if (errorModules.length === 0)
+            return event.type === "hmr-error";
+        return modules.some((module) => errorModules.includes(module));
+    });
+    const relatedEvents = matchedEvents.length > 0 ? matchedEvents : recentEvents;
+    const matchingModules = unique(relatedEvents.flatMap((event) => extractModulesFromEvent(event)).filter((module) => errorModules.includes(module)));
+    const confidence = inferConfidence(errorModules, matchingModules, relatedEvents);
+    const eventKind = relatedEvents.some((event) => event.type === "hmr-error") ? "HMR error" : "HMR update";
+    const moduleText = matchingModules.length > 0
+        ? `Matching modules: ${matchingModules.join(", ")}`
+        : errorModules.length > 0
+            ? `Error modules: ${errorModules.join(", ")}`
+            : "No module path overlap; correlation is time-window based.";
+    return {
+        summary: `${eventKind} observed within ${windowMs}ms of the current error`,
+        detail: `${moduleText}\nRecent events considered: ${relatedEvents.length}`,
+        confidence,
+        windowMs,
+        matchingModules,
+        relatedEvents,
+    };
+}
+export function correlateRenderWithNetwork(events, requestThreshold = 3) {
+    const renderEvents = events.filter((event) => event.type === "render");
+    const networkEvents = events.filter((event) => event.type === "network");
+    if (renderEvents.length === 0 || networkEvents.length === 0)
+        return null;
+    const latestRender = renderEvents[renderEvents.length - 1];
+    const start = latestRender.timestamp - 1000;
+    const end = latestRender.timestamp + 1000;
+    const overlappingNetwork = networkEvents.filter((event) => event.timestamp >= start && event.timestamp <= end);
+    const urls = unique(overlappingNetwork
+        .map((event) => event.payload.url)
+        .filter((url) => typeof url === "string"));
+    if (overlappingNetwork.length < requestThreshold)
+        return null;
+    return {
+        summary: "Repeated network activity detected around a render event",
+        detail: `Observed ${overlappingNetwork.length} network requests near the latest render. URLs: ${urls.join(", ")}`,
+        confidence: overlappingNetwork.length >= requestThreshold + 2 ? "high" : "medium",
+        requestCount: overlappingNetwork.length,
+        urls,
+    };
+}
+export function formatErrorCorrelationReport(errorText, correlation) {
+    const lines = ["# Error Correlation", "", "## Current Error", errorText.trim() || "(empty error)"];
+    if (!correlation) {
+        lines.push("", "## Correlation", "No recent HMR events correlated with the current error.");
+        return lines.join("\n");
+    }
+    lines.push("", "## Correlation", `Confidence: ${correlation.confidence}`, correlation.summary, correlation.detail, "", "## Related Events", ...correlation.relatedEvents.map((event) => formatEventLine(event)));
+    return lines.join("\n");
+}
+function formatEventLine(event) {
+    const payload = event.payload;
+    const path = payload.path;
+    const message = payload.message;
+    if (typeof path === "string")
+        return `- ${event.type}: ${path}`;
+    if (typeof message === "string")
+        return `- ${event.type}: ${message}`;
+    return `- ${event.type}: ${JSON.stringify(payload)}`;
+}
+function inferConfidence(errorModules, matchingModules, events) {
+    if (matchingModules.length > 0)
+        return "high";
+    if (events.some((event) => event.type === "hmr-error"))
+        return "medium";
+    if (errorModules.length === 0 && events.length > 0)
+        return "low";
+    return "medium";
+}
+function extractModulesFromEvent(event) {
+    const payload = event.payload;
+    const candidates = [];
+    if (typeof payload.path === "string")
+        candidates.push(payload.path);
+    if (typeof payload.message === "string")
+        candidates.push(payload.message);
+    if (Array.isArray(payload.updates)) {
+        for (const update of payload.updates) {
+            if (update && typeof update === "object" && typeof update.path === "string") {
+                candidates.push(update.path);
+            }
+        }
+    }
+    return unique(candidates.flatMap((candidate) => extractModules(candidate)));
+}
+function extractModules(text) {
+    const matches = MODULE_PATTERNS.flatMap((pattern) => text.match(pattern) ?? []);
+    return unique(matches.map(normalizeModulePath).filter(Boolean));
+}
+function normalizeModulePath(value) {
+    return value.replace(/[),.:]+$/, "");
+}
+function unique(values) {
+    return [...new Set(values)];
+}

package/dist/daemon.d.ts

@@ -9,6 +9,7 @@ export type Cmd = {
     idx?: number;
     mode?: "summary" | "trace" | "clear" | "snapshot";
     limit?: number;
+    windowMs?: number;
     filter?: string;
     mapped?: boolean;
     inlineSource?: boolean;

package/dist/daemon.js

@@ -2,7 +2,11 @@ import { createServer } from "node:net";
 import { mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import * as browser from "./browser.js";
+import { correlateErrorWithHMR, formatErrorCorrelationReport } from "./correlate.js";
+import { diagnoseHMR, formatDiagnosisReport } from "./diagnose.js";
 import { socketDir, socketPath, pidFile } from "./paths.js";
+import { EventQueue } from "./event-queue.js";
+import * as networkLog from "./network.js";
 export function cleanError(err) {
     if (!(err instanceof Error))
         return String(err);
@@ -12,6 +16,19 @@ export function cleanError(err) {
 }
 export function createRunner(api = browser) {
     return async function run(cmd) {
+        // Flush browser events to daemon queue before processing command
+        const queue = api.getEventQueue();
+        if (queue) {
+            try {
+                const currentPage = api.getCurrentPage();
+                if (currentPage) {
+                    await api.flushBrowserEvents(currentPage, queue);
+                }
+            }
+            catch {
+                // Ignore flush errors (page might not be open yet)
+            }
+        }
         // Browser control
         if (cmd.action === "open") {
             await api.open(cmd.url);
@@ -88,6 +105,21 @@ export function createRunner(api = browser) {
             const data = await api.errors(Boolean(cmd.mapped), Boolean(cmd.inlineSource));
             return { ok: true, data };
         }
+        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));
+            return { ok: true, data };
+        }
+        if (cmd.action === "diagnose-hmr") {
+            const errorText = String(await api.errors(Boolean(cmd.mapped), Boolean(cmd.inlineSource)));
+            const runtimeText = String(await api.viteRuntimeStatus());
+            const hmrTraceText = String(await api.viteHMRTrace("trace", cmd.limit ?? 50));
+            const events = queue ? queue.window(cmd.windowMs ?? 5000) : [];
+            const correlation = errorText === "no errors" ? null : correlateErrorWithHMR(errorText, events, cmd.windowMs ?? 5000);
+            const data = formatDiagnosisReport(diagnoseHMR({ errorText, runtimeText, hmrTraceText, correlation }));
+            return { ok: true, data };
+        }
         if (cmd.action === "logs") {
             const data = await api.logs();
             return { ok: true, data };
@@ -123,6 +155,10 @@ export async function dispatchLine(line, socket, run = createRunner(), onClose)
         setImmediate(() => onClose?.());
 }
 export function startDaemon() {
+    // Initialize event queue
+    const eventQueue = new EventQueue(1000);
+    browser.setEventQueue(eventQueue);
+    networkLog.setEventQueue(eventQueue);
     const run = createRunner();
     mkdirSync(socketDir, { recursive: true, mode: 0o700 });
     removeSocketFile();

package/dist/diagnose.d.ts

@@ -0,0 +1,19 @@
+import type { ErrorCorrelation } from "./correlate.js";
+export type DiagnosisStatus = "pass" | "warn" | "fail";
+export type DiagnosisConfidence = "high" | "medium" | "low";
+export type DiagnosisResult = {
+    code: "circular-dependency" | "missing-module" | "hmr-websocket-closed" | "repeated-full-reload";
+    status: DiagnosisStatus;
+    confidence: DiagnosisConfidence;
+    summary: string;
+    detail: string;
+    suggestion: string;
+};
+export type DiagnoseInput = {
+    errorText: string;
+    runtimeText: string;
+    hmrTraceText: string;
+    correlation: ErrorCorrelation | null;
+};
+export declare function diagnoseHMR(input: DiagnoseInput): DiagnosisResult[];
+export declare function formatDiagnosisReport(results: DiagnosisResult[]): string;

package/dist/diagnose.js

@@ -0,0 +1,111 @@
+export function diagnoseHMR(input) {
+    const results = [
+        detectCircularDependency(input),
+        detectMissingModule(input),
+        detectClosedWebsocket(input),
+        detectRepeatedFullReload(input),
+    ]
+        .filter((result) => result !== null)
+        .sort(compareDiagnosisResults);
+    if (results.length > 0)
+        return results;
+    return [
+        {
+            code: "hmr-websocket-closed",
+            status: "pass",
+            confidence: "low",
+            summary: "No obvious HMR failure pattern detected",
+            detail: "Runtime, current error text, and HMR trace did not match any built-in failure rules.",
+            suggestion: "If symptoms persist, inspect `vite hmr trace`, `network`, and `correlate errors` output together.",
+        },
+    ];
+}
+export function formatDiagnosisReport(results) {
+    const lines = ["# HMR Diagnosis", ""];
+    for (const result of results) {
+        lines.push(`## ${result.code}`, `Status: ${result.status}`, `Confidence: ${result.confidence}`, result.summary, result.detail, `Suggestion: ${result.suggestion}`, "");
+    }
+    return lines.join("\n").trimEnd();
+}
+function detectCircularDependency(input) {
+    const text = `${input.errorText}\n${input.hmrTraceText}`;
+    if (!/circular (dependency|import)|import cycle/i.test(text))
+        return null;
+    const moduleText = input.correlation?.matchingModules.length
+        ? `Likely modules: ${input.correlation.matchingModules.join(", ")}.`
+        : "The error text points to a circular import/dependency chain.";
+    return {
+        code: "circular-dependency",
+        status: "fail",
+        confidence: input.correlation?.matchingModules.length ? "high" : "medium",
+        summary: "HMR is likely breaking because of a circular dependency.",
+        detail: `${moduleText} Circular imports often prevent safe hot replacement and force stale state or reload loops.`,
+        suggestion: "Break the import cycle by extracting shared code into a leaf module or switching one edge to a lazy import.",
+    };
+}
+function detectMissingModule(input) {
+    const text = input.errorText;
+    if (!/failed to resolve import|cannot find module|could not resolve|does the file exist/i.test(text)) {
+        return null;
+    }
+    return {
+        code: "missing-module",
+        status: "fail",
+        confidence: "high",
+        summary: "A module import failed to resolve during HMR.",
+        detail: input.correlation?.matchingModules.length
+            ? `The current error overlaps with recent updates to ${input.correlation.matchingModules.join(", ")}.`
+            : "The current error text matches a missing or unresolved import pattern.",
+        suggestion: "Verify the import path, file extension, alias configuration, and whether the module exists on disk.",
+    };
+}
+function detectClosedWebsocket(input) {
+    const runtimeState = extractRuntimeSocketState(input.runtimeText);
+    const runtimeClosed = runtimeState === "closed" || runtimeState === "closing";
+    const traceClosed = /disconnected|failed to connect|connection lost|ws closed/i.test(input.hmrTraceText);
+    if (!runtimeClosed && !traceClosed)
+        return null;
+    const runtimeOnly = runtimeClosed && !traceClosed;
+    const traceOnly = traceClosed && !runtimeClosed;
+    return {
+        code: "hmr-websocket-closed",
+        status: "fail",
+        confidence: runtimeClosed && traceClosed ? "high" : "medium",
+        summary: "The HMR websocket is not healthy.",
+        detail: runtimeOnly
+            ? "Runtime status reports the HMR socket as closed or closing."
+            : traceOnly
+                ? "HMR trace contains disconnect or websocket failure messages."
+                : "Runtime status and HMR trace both indicate websocket instability.",
+        suggestion: "Check the dev server is running, the page is connected to the correct origin, and no proxy/firewall is blocking the websocket.",
+    };
+}
+function detectRepeatedFullReload(input) {
+    const matches = input.hmrTraceText.match(/full-reload|page reload/gi) ?? [];
+    if (matches.length < 2)
+        return null;
+    return {
+        code: "repeated-full-reload",
+        status: "warn",
+        confidence: matches.length >= 3 ? "high" : "medium",
+        summary: "Vite is repeatedly falling back to full page reloads.",
+        detail: `Observed ${matches.length} full-reload events in the recent HMR trace.`,
+        suggestion: "Check whether the changed module is outside HMR boundaries, introduces side effects, or triggers a circular dependency.",
+    };
+}
+function extractRuntimeSocketState(runtimeText) {
+    const match = runtimeText.match(/HMR Socket:\s*(open|closed|closing|connecting|unknown)/i);
+    const state = match?.[1]?.toLowerCase();
+    if (state === "open" || state === "closed" || state === "closing" || state === "connecting") {
+        return state;
+    }
+    return "unknown";
+}
+function compareDiagnosisResults(a, b) {
+    return scoreDiagnosis(b) - scoreDiagnosis(a);
+}
+function scoreDiagnosis(result) {
+    const statusScore = result.status === "fail" ? 30 : result.status === "warn" ? 20 : 10;
+    const confidenceScore = result.confidence === "high" ? 3 : result.confidence === "medium" ? 2 : 1;
+    return statusScore + confidenceScore;
+}

package/dist/event-queue.d.ts

@@ -0,0 +1,22 @@
+export type VBEventType = 'hmr-update' | 'hmr-error' | 'module-change' | 'network' | 'error' | 'render';
+export interface VBEvent {
+    timestamp: number;
+    type: VBEventType;
+    payload: unknown;
+}
+export declare class EventQueue {
+    private events;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    push(event: VBEvent): void;
+    /**
+     * Return all events within the last `ms` milliseconds before `before`
+     */
+    window(ms: number, before?: number): VBEvent[];
+    /**
+     * Return all events of a given type
+     */
+    ofType(type: VBEventType): VBEvent[];
+    all(): VBEvent[];
+    clear(): void;
+}

package/dist/event-queue.js

@@ -0,0 +1,32 @@
+export class EventQueue {
+    events = [];
+    maxSize;
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    push(event) {
+        this.events.push(event);
+        if (this.events.length > this.maxSize) {
+            this.events.shift();
+        }
+    }
+    /**
+     * Return all events within the last `ms` milliseconds before `before`
+     */
+    window(ms, before = Date.now()) {
+        const start = before - ms;
+        return this.events.filter((e) => e.timestamp >= start && e.timestamp <= before);
+    }
+    /**
+     * Return all events of a given type
+     */
+    ofType(type) {
+        return this.events.filter((e) => e.type === type);
+    }
+    all() {
+        return [...this.events];
+    }
+    clear() {
+        this.events = [];
+    }
+}

package/dist/network.d.ts

@@ -1,4 +1,6 @@
 import type { Page } from "playwright";
+import type { EventQueue } from "./event-queue.js";
+export declare function setEventQueue(queue: EventQueue): void;
 export declare function attach(page: Page): void;
 export declare function clear(): void;
 export declare function detail(idx: number): Promise<string>;

package/dist/network.js

@@ -4,6 +4,10 @@ import { join } from "node:path";
 const BODY_INLINE_LIMIT = 4000;
 let entries = [];
 let startTime = new Map();
+let eventQueue = null;
+export function setEventQueue(queue) {
+    eventQueue = queue;
+}
 export function attach(page) {
     page.on("request", (req) => {
         if (req.resourceType() === "document" && req.frame() === page.mainFrame()) {
@@ -16,7 +20,21 @@ export function attach(page) {
         const t0 = startTime.get(req);
         if (t0 == null)
             return;
-        entries.push({ req, res, ms: Date.now() - t0 });
+        const ms = Date.now() - t0;
+        entries.push({ req, res, ms });
+        // Push to event queue if available
+        if (eventQueue) {
+            eventQueue.push({
+                timestamp: Date.now(),
+                type: 'network',
+                payload: {
+                    url: req.url(),
+                    method: req.method(),
+                    status: res.status(),
+                    ms
+                }
+            });
+        }
     });
     page.on("requestfailed", (req) => {
         if (!startTime.has(req))

package/package.json

@@ -1,8 +1,22 @@
 {
   "name": "@presto1314w/vite-devtools-browser",
-  "version": "0.1.4",
-  "description": "CLI for programmatic access to Vue/React DevTools in Vite applications",
-  "license": "MIT",
+  "version": "0.2.2",
+  "description": "Runtime diagnostics CLI for Vite apps with event-stream correlation, HMR diagnosis, framework inspection, and mapped errors",
+  "license": "MIT",
+  "keywords": [
+    "vite",
+    "devtools",
+    "debugging",
+    "runtime-diagnostics",
+    "hmr",
+    "module-graph",
+    "sourcemap",
+    "vue",
+    "react",
+    "svelte",
+    "cli",
+    "ai-agents"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/MapleCity1314/vite-browser.git"