@presto1314w/vite-devtools-browser 0.3.2 → 0.3.5

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Vercel, Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,320 +1,135 @@
-# vite-browser
-
-**Explain why your Vite app broke after a hot update.**
-
-`vite-browser` is a runtime diagnostics toolchain for Vite apps. It connects current errors to recent HMR activity, traces store and module updates into rerender paths, and returns structured terminal output that both developers and AI agents can reason about directly.
-
-No plugin installation. No GUI. Just connect to a running Vite dev server and start querying.
-
-**CLI**
-```bash
-npm install -g @presto1314w/vite-devtools-browser
-npx playwright install chromium
-```
-
-**Agent Skill**
-```bash
-npx skills add MapleCity1314/vite-browser
-```
-
----
-
-## The Problem It Solves
-
-You save a file. Vite hot-updates. The page breaks.
-
-The error overlay tells you *what* broke. It does not tell you *why the update caused it*.
-
-You want to know:
-- which module change triggered this error
-- whether a store update propagated into a broken render path
-- what the HMR timeline looked like before the failure
-
-`vite-browser` answers these questions from the terminal, without touching your project config.
-
----
-
-## Quickstart
-
-```bash
-# terminal A - your app
-cd my-app && npm run dev
-
-# terminal B - diagnostics
-vite-browser open http://localhost:5173
-vite-browser vite runtime
-vite-browser errors --mapped --inline-source
-vite-browser correlate errors --mapped --window 5000
-vite-browser close
-```
-
----
-
-## Example: Tracing a Broken HMR Update
-
-You edit `src/store/cart.ts`. The page breaks with `TypeError: cannot read properties of undefined`.
-
-```bash
-# 1. check what the error actually is
-$ vite-browser errors --mapped --inline-source
-
-TypeError: Cannot read properties of undefined (reading 'items')
-
-# Mapped Stack
-- /src/components/CartSummary.tsx:14:12
-  14 | total = cart.items.reduce(...)
-```
-
-```bash
-# 2. correlate with recent HMR activity
-$ vite-browser correlate errors --mapped --window 5000
-
-# Error Correlation
-Confidence: high
-HMR update observed within 5000ms of the current error
-Matching modules: /src/store/cart.ts
-```
-
-```bash
-# 3. trace how the update propagated
-$ vite-browser correlate renders --window 5000
-
-# Render Correlation
-Confidence: high
-Recent store update likely propagated through 1 render step(s).
-
-## Store Updates
-- cart
-
-## Changed Keys
-- items
-
-## Render Path
-- AppShell > ShoppingCart > CartSummary
-```
-
-```bash
-# 4. get a structured diagnosis
-$ vite-browser diagnose propagation --window 5000
-
-# Propagation Diagnosis
-Status: fail
-Confidence: high
-A plausible store -> render -> error propagation path was found.
-```
-
-Four commands. You know the store update broke the render path. You know where to fix it.
-
----
-
-## Built For Agents
-
-Models cannot visually inspect a DevTools panel. They work much better when runtime signals are structured commands that can be queried, compared, and chained in a loop.
-
-`vite-browser` turns Vite runtime state, HMR activity, module graph changes, framework component trees, mapped errors, and network activity into terminal output an agent can consume directly.
-
-Each command is a one-shot request against a long-lived browser daemon - no browser lifecycle management on every step, no GUI dependency, no project config changes required.
-
-```bash
-# an agent debugging loop looks like this
-vite-browser vite runtime
-vite-browser errors --mapped --inline-source
-vite-browser correlate errors --mapped --window 5000
-vite-browser correlate renders --window 5000
-vite-browser diagnose propagation --window 5000
-vite-browser diagnose hmr --limit 50
-```
-
-Agent Skill workflows are also available for scenario-based debugging in coding assistants:
-
-```bash
-npx skills add MapleCity1314/vite-browser
-```
-
----
-
-## Core Capabilities
-
-**Framework detection**
-- Vue, React, Svelte best-effort detection with version hinting
-
-**Vue runtime**
-- component tree and details
-- Pinia stores, getters, and changed keys
-- Vue Router state
-
-**React runtime**
-- component tree with props, state, hooks, context, and source metadata
-
-**Svelte runtime**
-- component tree when metadata is available
-
-**Vite runtime diagnostics**
-- runtime status and HMR health
-- HMR timeline, summary, and clear
-- module graph snapshot, diff, trace, and clear
-- error / HMR correlation over configurable time windows
-- store and module update / render path correlation
-- propagation diagnosis with store updates, changed keys, and render paths
-- rule-based HMR diagnosis with confidence levels
-- source-mapped errors with optional inline source snippets
-
-**Debug utilities**
-- console logs, network tracing, screenshot, page `eval`
-
----
-
-## Positioning
-
-| Tool | Best for | Gap vs `vite-browser` |
-|---|---|---|
-| `agent-browser` | general browser automation | no Vite runtime awareness |
-| `next-browser` | Next.js + React debugging | not a Vite runtime tool |
-| `vite-plugin-vue-mcp` | Vue MCP integration | requires plugin install, Vue only |
-| `vite-browser` | Vite runtime diagnostics for agents and developers | browser lifecycle coverage still expanding |
-
-`vite-browser` requires no changes to your project. It works against any running Vite dev server across Vue, React, and Svelte.
-
----
-
-## Recommended Workflows
-
-### HMR / runtime 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
-```
-
-### Propagation / rerender triage
-```bash
-vite-browser correlate renders --window 5000
-vite-browser diagnose propagation --window 5000
-vite-browser vue pinia
-vite-browser vue tree
-```
-
-### 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
-```
-
----
-
-## Command Reference
-
-### Browser
-```bash
-vite-browser open <url> [--cookies-json <file>]
-vite-browser close
-vite-browser goto <url>
-vite-browser back
-vite-browser reload
-```
-
-### Framework
-```bash
-vite-browser detect
-vite-browser vue tree [id]
-vite-browser vue pinia [store]
-vite-browser vue router
-vite-browser react tree [id]
-vite-browser svelte tree [id]
-```
-
-### Vite Runtime
-```bash
-vite-browser vite restart
-vite-browser vite runtime
-vite-browser vite hmr
-vite-browser vite hmr trace [--limit <n>]
-vite-browser vite hmr clear
-vite-browser vite module-graph [--filter <txt>] [--limit <n>]
-vite-browser vite module-graph trace [--filter <txt>] [--limit <n>]
-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 renders [--window <ms>]
-vite-browser correlate errors --mapped --inline-source
-vite-browser diagnose hmr [--window <ms>] [--limit <n>]
-vite-browser diagnose propagation [--window <ms>]
-```
-
-### Utilities
-```bash
-vite-browser logs
-vite-browser network [idx]
-vite-browser screenshot
-vite-browser eval <script>
-```
-
----
-
-## Current Boundaries
-
-`v0.3.2` is strong at:
-- surfacing runtime state as structured shell output
-- linking current errors to recent HMR and module activity
-- detecting common HMR failure patterns with confidence levels
-- narrowing likely store/module -> render paths in Vue-first flows
-- capturing browser-side runtime errors even when the Vite overlay is absent
-- turning sparse live Vue/Pinia repro signals into actionable `store -> render -> error` guidance more reliably
-
-`correlate renders` and `diagnose propagation` are **high-confidence propagation clues**, not strict causal proof. They do not reliably trace deep chains like `store -> component A -> component B -> error` across arbitrary graphs, and intentionally fall back to conservative output when evidence is incomplete.
-
-React store inspection (Zustand, Redux) and deeper cross-framework propagation tracing are on the roadmap.
-
----
-
-## Skill Packs
-
-```
-skills/vite-browser-core-debug/SKILL.md
-skills/vite-browser-runtime-diagnostics/SKILL.md
-skills/vite-browser-network-regression/SKILL.md
-skills/vite-browser-release-smoke/SKILL.md
-```
-
-Router: [skills/SKILL.md](./skills/SKILL.md)
-
----
-
-## Local Development
-
-```bash
-pnpm install
-pnpm build
-pnpm test
-pnpm test:coverage
-pnpm test:evals
-pnpm test:evals:e2e
-```
-
-## Requirements
-
-- Node.js `>=20`
-- Chromium via Playwright
-- Running Vite dev server
-
-## License
-
-MIT
+# vite-browser
+
+**Know why your Vite app broke — not just where.**
+
+Runtime diagnostics CLI for Vite applications. Connect to a running dev server, correlate errors with recent HMR activity, trace store-to-render propagation paths, and inspect framework state — all from the terminal, with zero project setup.
+
+Built for developers and AI coding agents alike.
+
+📖 [Documentation](https://maplecity1314.github.io/vite-browser/) · 📦 [npm](https://www.npmjs.com/package/@presto1314w/vite-devtools-browser)
+
+## Install
+
+**Agent Skill** (recommended):
+
+```bash
+npx skills add MapleCity1314/vite-browser
+```
+
+**CLI only:**
+
+```bash
+npm install -g @presto1314w/vite-devtools-browser
+npx playwright install chromium
+```
+
+## The problem
+
+You save a file. Vite hot-updates. The page breaks.
+
+The error overlay tells you _what_ failed — but not _which update caused it_, how the change propagated through your component tree, or whether the real problem is a stale store, a broken import, or a network regression.
+
+## What vite-browser does
+
+```bash
+# 1. See the current error with source context
+$ vite-browser errors --mapped --inline-source
+
+TypeError: Cannot read properties of undefined (reading 'items')
+  → /src/components/CartSummary.tsx:14:12
+    14 | total = cart.items.reduce(...)
+
+# 2. Correlate with recent HMR activity
+$ vite-browser correlate errors --mapped --window 5000
+
+Confidence: high
+HMR update observed within 5000ms of the current error
+Matching modules: /src/store/cart.ts
+
+# 3. Trace the propagation path
+$ vite-browser diagnose propagation --window 5000
+
+Status: fail | Confidence: high
+Store → Render → Error path found:
+  store: cart (changedKeys: items)
+  render: AppShell > ShoppingCart > CartSummary
+```
+
+Four commands. You know the store update broke the render path. You know where to fix it.
+
+## Key features
+
+- **Error correlation** — Match errors against recent HMR-updated modules within a time window
+- **Propagation diagnosis** — Trace `store → render → error` paths with confidence levels
+- **HMR diagnosis** — Detect patterns like `missing-module`, `circular-dependency`, `hmr-websocket-closed`
+- **Framework inspection** — Vue trees, Pinia stores, Vue Router, React props/hooks/state, Svelte trees
+- **Mapped errors** — Source-mapped stack traces with inline source snippets
+- **Zero config** — No plugins, no project changes. Works with any running Vite dev server
+
+## Agent Skills
+
+`vite-browser` is designed skill-first. The skill router automatically picks the right debugging workflow based on the symptom:
+
+| Symptom | Routed to |
+|---|---|
+| Broad / unclear failure | `core-debug` |
+| Recent edit or HMR breakage | `runtime-diagnostics` |
+| Wrong data or failed requests | `network-regression` |
+| Pre-merge verification | `release-smoke` |
+
+AI coding agents (Claude Code, Codex, Cursor) follow the structured workflow instead of guessing.
+
+→ [Agent Skills guide](https://maplecity1314.github.io/vite-browser/guide/agent-skills) · [AI IDE Setup](https://maplecity1314.github.io/vite-browser/guide/ide-setup)
+
+## Quick reference
+
+```bash
+# Browser
+vite-browser open <url>          # Launch and navigate
+vite-browser close               # Close browser and daemon
+
+# Diagnostics
+vite-browser errors --mapped --inline-source
+vite-browser correlate errors --mapped --window <ms>
+vite-browser correlate renders --window <ms>
+vite-browser diagnose hmr --limit <n>
+vite-browser diagnose propagation --window <ms>
+
+# Framework
+vite-browser detect
+vite-browser vue tree | vue pinia | vue router
+vite-browser react tree
+vite-browser svelte tree
+
+# Vite runtime
+vite-browser vite runtime
+vite-browser vite hmr trace --limit <n>
+vite-browser vite module-graph trace --limit <n>
+
+# Utilities
+vite-browser logs | network | screenshot | eval <script>
+```
+
+→ [Full CLI reference](https://maplecity1314.github.io/vite-browser/reference/cli)
+
+## Current scope
+
+`v0.3.3` is reliable at surfacing runtime state, correlating errors with HMR activity, detecting common HMR failure patterns, and narrowing `store → render → error` paths in Vue + Pinia workflows.
+
+`correlate renders` and `diagnose propagation` are **high-confidence narrowing tools**, not strict causal proof. They intentionally produce conservative output when evidence is incomplete.
+
+React store inspection (Zustand, Redux) and deeper cross-framework propagation tracing are on the roadmap.
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
+**Requirements:** Node.js ≥ 20 · Chromium via Playwright · Running Vite dev server
+
+## License
+
+MIT

package/dist/browser-session.d.ts

@@ -20,7 +20,6 @@ export type BrowserSessionState = {
     context: BrowserContext | null;
     page: Page | null;
     framework: BrowserFramework;
-    extensionModeDisabled: boolean;
     collectorInstalled: boolean;
     consoleLogs: string[];
     hmrEvents: HmrEvent[];
@@ -35,3 +34,14 @@ export declare function ensureBrowserPage(state: BrowserSessionState, onPageRead
 export declare function closeBrowserSession(state: BrowserSessionState): Promise<void>;
 export declare function contextUsable(current: Pick<BrowserContext, "pages"> | null): current is Pick<BrowserContext, "pages">;
 export declare function isClosedTargetError(error: unknown): boolean;
+/**
+ * Build platform-aware Chromium launch arguments.
+ *
+ * On Linux (especially Docker / CI without a display server) we add
+ * `--no-sandbox` and `--disable-dev-shm-usage` so that Chromium can
+ * start reliably in headless-shell containers.
+ *
+ * On Windows, `--disable-gpu` is added to work around occasional GPU
+ * process crashes on older drivers.
+ */
+export declare function platformChromiumArgs(extra?: string[]): string[];

package/dist/browser-session.js

@@ -1,18 +1,11 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
 import { chromium } from "playwright";
-const extensionPath = process.env.REACT_DEVTOOLS_EXTENSION ??
-    resolve(import.meta.dirname, "../../next-browser/extensions/react-devtools-chrome");
-const hasReactExtension = existsSync(join(extensionPath, "manifest.json"));
-const installHook = hasReactExtension
-    ? readFileSync(join(extensionPath, "build", "installHook.js"), "utf-8")
-    : null;
+import { getHookSource } from "./react/hook-manager.js";
+import { isWindows, isLinux } from "./paths.js";
 export function createBrowserSessionState() {
     return {
         context: null,
         page: null,
         framework: "unknown",
-        extensionModeDisabled: false,
         collectorInstalled: false,
         consoleLogs: [],
         hmrEvents: [],
@@ -42,9 +35,7 @@ export function resetBrowserSessionState(state) {
 export async function ensureBrowserPage(state, onPageReady) {
     if (!contextUsable(state.context)) {
         await closeBrowserSession(state);
-        const launched = await launchBrowserContext(state.extensionModeDisabled);
-        state.context = launched.context;
-        state.extensionModeDisabled = launched.extensionModeDisabled;
+        state.context = await launchBrowserContext();
     }
     if (!state.context)
         throw new Error("browser not open");
@@ -56,10 +47,7 @@ export async function ensureBrowserPage(state, onPageReady) {
             if (!isClosedTargetError(error))
                 throw error;
             await closeBrowserSession(state);
-            state.extensionModeDisabled = true;
-            const launched = await launchBrowserContext(state.extensionModeDisabled);
-            state.context = launched.context;
-            state.extensionModeDisabled = launched.extensionModeDisabled;
+            state.context = await launchBrowserContext();
             state.page = state.context.pages()[0] ?? (await state.context.newPage());
         }
         onPageReady(state.page);
@@ -86,32 +74,33 @@ export function isClosedTargetError(error) {
         return false;
     return /Target page, context or browser has been closed/i.test(error.message);
 }
-async function launchBrowserContext(extensionModeDisabled) {
-    if (hasReactExtension && installHook && !extensionModeDisabled) {
-        try {
-            const context = await chromium.launchPersistentContext("", {
-                headless: false,
-                viewport: { width: 1280, height: 720 },
-                args: [
-                    `--disable-extensions-except=${extensionPath}`,
-                    `--load-extension=${extensionPath}`,
-                    "--auto-open-devtools-for-tabs",
-                ],
-            });
-            await context.waitForEvent("serviceworker").catch(() => { });
-            await context.addInitScript(installHook);
-            return { context, extensionModeDisabled };
-        }
-        catch {
-            extensionModeDisabled = true;
-        }
+/**
+ * Build platform-aware Chromium launch arguments.
+ *
+ * On Linux (especially Docker / CI without a display server) we add
+ * `--no-sandbox` and `--disable-dev-shm-usage` so that Chromium can
+ * start reliably in headless-shell containers.
+ *
+ * On Windows, `--disable-gpu` is added to work around occasional GPU
+ * process crashes on older drivers.
+ */
+export function platformChromiumArgs(extra = []) {
+    const args = ["--auto-open-devtools-for-tabs", ...extra];
+    if (isLinux) {
+        args.push("--no-sandbox", "--disable-dev-shm-usage");
+    }
+    else if (isWindows) {
+        args.push("--disable-gpu");
     }
+    return args;
+}
+async function launchBrowserContext() {
     const browser = await chromium.launch({
         headless: false,
-        args: ["--auto-open-devtools-for-tabs"],
+        args: platformChromiumArgs(),
     });
-    return {
-        context: await browser.newContext({ viewport: { width: 1280, height: 720 } }),
-        extensionModeDisabled,
-    };
+    const context = await browser.newContext({ viewport: { width: 1280, height: 720 } });
+    // Inject bundled React DevTools hook before any page loads
+    await context.addInitScript(getHookSource());
+    return context;
 }

package/dist/browser.d.ts

@@ -7,6 +7,17 @@ export { formatHmrTrace, formatModuleGraphSnapshot, formatModuleGraphTrace, form
 export type ModuleGraphMode = "snapshot" | "trace" | "clear";
 export declare function setEventQueue(queue: EventQueue): void;
 export declare function getEventQueue(): EventQueue | null;
+export declare function getTrackedHmrEvents(windowMs?: number): Array<{
+    timestamp: number;
+    type: "hmr-update" | "hmr-error";
+    payload: {
+        path?: string;
+        message?: string;
+        updates?: Array<{
+            path?: string;
+        }>;
+    };
+}>;
 export declare function getCurrentPage(): Page | null;
 /**
  * Flush browser events into daemon event queue