@presto1314w/vite-devtools-browser 0.1.3 → 0.2.0

package/README.md

@@ -1,14 +1,70 @@
 # vite-browser
 
-Agent Skill for AI coding assistants to debug Vite applications with structured access to Vue/React/Svelte runtime state. The CLI is the supporting runtime used by the skill for component trees, store/router inspection, logs, network traces, screenshots, and scripted page evaluation.
+`vite-browser` is a runtime diagnostics toolchain for Vite applications.
 
-## Skills
+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 shell commands for local Vite debugging
+
+Current documented baseline: `v0.2.0`.
+
+## What's New In v0.2
+
+`v0.2.0` 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
+
+## 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:
+
+- 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
+
+### Install Skill
 
 ```bash
 npx skills add MapleCity1314/vite-browser
 ```
 
-## CLI Installation (Optional)
+### Install CLI
 
 ```bash
 npm install -g @presto1314w/vite-devtools-browser
@@ -18,100 +74,217 @@ npx playwright install chromium
 ## Quick Start
 
 ```bash
-# Start your Vite dev server
-cd my-vue-app
+# terminal A: start Vite app
+cd my-app
 npm run dev
 
-# In another terminal
+# terminal B: inspect runtime
 vite-browser open http://localhost:5173
-vite-browser detect              # vue@3.5.29 / react@19.x / svelte@x
-vite-browser vue tree            # Vue component tree
-vite-browser react tree          # React component tree
-vite-browser svelte tree         # Svelte component tree (best effort)
-vite-browser screenshot          # Take screenshot
-vite-browser logs                # Console logs
-vite-browser network             # Network requests
+vite-browser detect
+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 network
 vite-browser close
 ```
 
-## Features
+For component/state debugging, then branch into framework-specific commands:
 
-- Framework Detection: Auto-detect Vue, React, Svelte and versions (best effort)
-- Vue DevTools: Component tree, props, state, computed properties, source locations
-- React DevTools: Component tree + component inspection (props/hooks/state/context)
-- Svelte Support: Component tree + component detail inspection when runtime metadata is available
-- Pinia Integration: Inspect store state and getters
-- Vue Router: Current route, params, query, all routes
-- Network Monitoring: Track requests, headers, bodies, and response payloads
-- Console Logs: Capture console.log, warn, error, debug
-- Screenshots: Full-page PNG screenshots
-- JavaScript Evaluation: Run arbitrary JS in page context
-- Vite Integration: Error tracking, HMR monitoring
+```bash
+vite-browser vue tree
+vite-browser vue pinia
+vite-browser vue router
+vite-browser react tree
+vite-browser svelte tree
+```
 
-## Commands
+## What It Looks Like
 
-### Browser Control
 ```bash
-vite-browser open <url>           # Launch browser and navigate
-vite-browser close                # Close browser and daemon
-vite-browser goto <url>           # Navigate to URL
-vite-browser back                 # Go back
-vite-browser reload               # Reload page
+$ 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.
 ```
 
-### Framework Detection
+## Core Capabilities
+
+- Framework detection: Vue/React/Svelte best-effort detection and version hinting
+- Vue runtime inspection: component tree/details, Pinia stores/getters, Vue Router state
+- React runtime inspection: component tree/details (props/state/hooks/context/source)
+- Svelte runtime inspection: component tree/details when metadata is available
+- Vite runtime diagnostics:
+  - 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               # Detect framework and version
+vite-browser detect
+vite-browser vue tree
+vite-browser vue pinia
+vite-browser vue router
+vite-browser react tree
+vite-browser svelte tree
 ```
 
-### Vue DevTools
+## Current Boundaries
+
+`vite-browser` v0.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
+
 ```bash
-vite-browser vue tree             # Show component tree
-vite-browser vue tree <id>        # Inspect component details
-vite-browser vue pinia            # List all Pinia stores
-vite-browser vue pinia <store>    # Inspect specific store
-vite-browser vue router           # Show router information
+vite-browser open <url> [--cookies-json <file>]
+vite-browser close
+vite-browser goto <url>
+vite-browser back
+vite-browser reload
 ```
 
-### React DevTools
+### Framework
+
 ```bash
-vite-browser react tree           # Show React component tree
-vite-browser react tree <id>      # Inspect props/hooks/state/context/source
+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]
 ```
 
-### Svelte
+### Vite Runtime
+
 ```bash
-vite-browser svelte tree          # Show Svelte component tree
-vite-browser svelte tree <id>     # Inspect Svelte component details
+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 errors --mapped --inline-source
+vite-browser diagnose hmr [--window <ms>] [--limit <n>]
 ```
 
-### Debugging
+### Utilities
+
 ```bash
-vite-browser screenshot           # Take full-page screenshot
-vite-browser eval <script>        # Run JavaScript in page
-vite-browser logs                 # Show console logs
-vite-browser errors               # Show Vite errors
-vite-browser network              # List network requests
-vite-browser network <idx>        # Inspect specific request
+vite-browser logs
+vite-browser network [idx]
+vite-browser screenshot
+vite-browser eval <script>
 ```
 
-## Architecture
+## Skill Packs
 
-- Daemon + Socket: Background process with socket communication
-- Playwright: Headed Chromium browser
-- One Browser, One Page: Single persistent browser instance
-- Auto-start: Daemon starts automatically on first command
+The entry skill routes to specialized workflows:
 
-## Requirements
+- `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`
 
-- Node.js 20+
-- Chromium (via Playwright)
-- Vite dev server running
-- Vue/React/Svelte app for framework-specific commands
+Router definition: [skills/SKILL.md](./skills/SKILL.md)
 
-## Documentation
+## Local Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm test:coverage
+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
 
-See [SKILL.md](./skills/SKILL.md) for complete command reference and usage examples.
+- Node.js `>=20`
+- Chromium installed via Playwright
+- Running Vite dev server
 
 ## License
 

package/dist/browser.d.ts

@@ -1,9 +1,48 @@
+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;
+    type: HmrEventType;
+    message: string;
+    path?: string;
+};
+export type RuntimeSnapshot = {
+    url: string;
+    hasViteClient: boolean;
+    wsState: string;
+    hasErrorOverlay: boolean;
+    timestamp: number;
+};
+export type ModuleRow = {
+    url: string;
+    initiator: string;
+    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;
     value: string;
 }[], domain: string): Promise<number>;
 export declare function close(): Promise<void>;
+export declare function contextUsable(current: Pick<BrowserContext, "pages"> | null): current is Pick<BrowserContext, "pages">;
+export declare function isClosedTargetError(error: unknown): boolean;
+export declare function recordConsoleMessage(logs: string[], events: HmrEvent[], type: string, message: string, maxLogs?: number, maxEvents?: number): void;
+export declare function parseViteLog(message: string): HmrEvent;
+export declare function normalizeLimit(limit: number, fallback: number, max: number): number;
+export declare function formatRuntimeStatus(runtime: RuntimeSnapshot, currentFramework: string, events: HmrEvent[]): string;
+export declare function formatHmrTrace(mode: "summary" | "trace", events: HmrEvent[], limit: number): string;
+export declare function formatModuleGraphSnapshot(rows: ModuleRow[], filter?: string, limit?: number): string;
+export declare function formatModuleGraphTrace(currentUrls: string[], previousUrls: Set<string> | null, filter?: string, limit?: number): string;
 export declare function goto(url: string): Promise<string>;
 export declare function back(): Promise<void>;
 export declare function reload(): Promise<string>;
@@ -17,9 +56,11 @@ export declare function viteRestart(): Promise<string>;
 export declare function viteHMR(): Promise<string>;
 export declare function viteRuntimeStatus(): Promise<string>;
 export declare function viteHMRTrace(mode: "summary" | "trace" | "clear", limit?: number): Promise<string>;
-export declare function viteModuleGraph(filter?: string, limit?: number, mode?: "snapshot" | "trace" | "clear"): Promise<string>;
+export declare function viteModuleGraph(filter?: string, limit?: number, mode?: ModuleGraphMode): Promise<string>;
 export declare function errors(mapped?: boolean, inlineSource?: boolean): Promise<string>;
 export declare function logs(): Promise<string>;
 export declare function screenshot(): Promise<string>;
 export declare function evaluate(script: string): Promise<string>;
 export declare function network(idx?: number): Promise<string>;
+export declare function mapStackTrace(stack: string, origin: string, inlineSource?: boolean, resolver?: typeof resolveViaSourceMap): Promise<string>;
+export {};