@presto1314w/vite-devtools-browser 0.1.3 → 0.1.4

package/README.md

@@ -1,14 +1,20 @@
 # 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 debugging toolchain for Vite apps:
+- Agent Skill: scenario-based debugging workflows for coding assistants
+- CLI Runtime (`@presto1314w/vite-devtools-browser`): structured inspection of Vue/React/Svelte runtime state
 
-## Skills
+Current documented baseline: `v0.1.4`.
+
+## 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 +24,111 @@ 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 vue tree
+vite-browser vue pinia
+vite-browser vite runtime
+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
 ```
 
-## Features
+## Core Capabilities
 
-- 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
+- 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
+  - source-mapped errors with optional inline source snippet
+- Debug utilities: console logs, network tracing, screenshot, page `eval`
 
-## Commands
+## Command Reference
 
-### 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
-```
+### Browser
 
-### Framework Detection
 ```bash
-vite-browser detect               # Detect framework and version
+vite-browser open <url> [--cookies-json <file>]
+vite-browser close
+vite-browser goto <url>
+vite-browser back
+vite-browser reload
 ```
 
-### Vue DevTools
-```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
-```
+### Framework
 
-### React DevTools
 ```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
 ```
 
-### 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
+```
+
+## 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,40 @@
+import { type BrowserContext } from "playwright";
+import { resolveViaSourceMap } from "./sourcemap.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 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 +48,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 {};

package/dist/browser.js

@@ -71,7 +71,7 @@ async function ensurePage() {
     }
     return page;
 }
-function contextUsable(current) {
+export function contextUsable(current) {
     if (!current)
         return false;
     try {
@@ -82,7 +82,7 @@ function contextUsable(current) {
         return false;
     }
 }
-function isClosedTargetError(error) {
+export function isClosedTargetError(error) {
     if (!(error instanceof Error))
         return false;
     return /Target page, context or browser has been closed/i.test(error.message);
@@ -115,20 +115,22 @@ async function launch() {
 }
 function attachListeners(currentPage) {
     currentPage.on("console", (msg) => {
-        const text = `[${msg.type()}] ${msg.text()}`;
-        consoleLogs.push(text);
-        if (consoleLogs.length > MAX_LOGS)
-            consoleLogs.shift();
-        const viteMessage = msg.text();
-        if (!viteMessage.includes("[vite]"))
-            return;
-        const event = parseViteLog(viteMessage);
-        hmrEvents.push(event);
-        if (hmrEvents.length > MAX_HMR_EVENTS)
-            hmrEvents.shift();
+        recordConsoleMessage(consoleLogs, hmrEvents, msg.type(), msg.text());
     });
 }
-function parseViteLog(message) {
+export function recordConsoleMessage(logs, events, type, message, maxLogs = MAX_LOGS, maxEvents = MAX_HMR_EVENTS) {
+    const text = `[${type}] ${message}`;
+    logs.push(text);
+    if (logs.length > maxLogs)
+        logs.shift();
+    if (!message.includes("[vite]"))
+        return;
+    const event = parseViteLog(message);
+    events.push(event);
+    if (events.length > maxEvents)
+        events.shift();
+}
+export function parseViteLog(message) {
     const lower = message.toLowerCase();
     const event = {
         timestamp: Date.now(),
@@ -154,6 +156,103 @@ function parseViteLog(message) {
         event.path = hotUpdateMatch[1].trim();
     return event;
 }
+export function normalizeLimit(limit, fallback, max) {
+    if (!Number.isFinite(limit) || limit <= 0)
+        return fallback;
+    return Math.min(limit, max);
+}
+export function formatRuntimeStatus(runtime, currentFramework, events) {
+    const output = [];
+    output.push("# Vite Runtime");
+    output.push(`URL: ${runtime.url}`);
+    output.push(`Framework: ${currentFramework}`);
+    output.push(`Vite Client: ${runtime.hasViteClient ? "loaded" : "not detected"}`);
+    output.push(`HMR Socket: ${runtime.wsState}`);
+    output.push(`Error Overlay: ${runtime.hasErrorOverlay ? "present" : "none"}`);
+    output.push(`Tracked HMR Events: ${events.length}`);
+    const last = events[events.length - 1];
+    if (last) {
+        output.push(`Last HMR Event: ${new Date(last.timestamp).toLocaleTimeString()} [${last.type}] ${last.message}`);
+    }
+    return output.join("\n");
+}
+export function formatHmrTrace(mode, events, limit) {
+    if (events.length === 0)
+        return "No HMR updates";
+    const safeLimit = normalizeLimit(limit, 20, 200);
+    const recent = events.slice(-safeLimit);
+    if (mode === "summary") {
+        const counts = recent.reduce((acc, event) => {
+            acc[event.type] = (acc[event.type] ?? 0) + 1;
+            return acc;
+        }, {});
+        const lines = ["# HMR Summary"];
+        lines.push(`Events considered: ${recent.length}`);
+        lines.push(`Counts: ${Object.entries(counts)
+            .map(([k, v]) => `${k}=${v}`)
+            .join(", ")}`);
+        const last = recent[recent.length - 1];
+        lines.push(`Last: ${new Date(last.timestamp).toLocaleTimeString()} [${last.type}] ${last.path ?? last.message}`);
+        lines.push("\nUse `vite-browser vite hmr trace --limit <n>` for timeline details.");
+        return lines.join("\n");
+    }
+    return [
+        "# HMR Trace",
+        ...recent.map((event) => {
+            const detail = event.path ? `${event.path}` : event.message;
+            return `[${new Date(event.timestamp).toLocaleTimeString()}] ${event.type} ${detail}`;
+        }),
+    ].join("\n");
+}
+export function formatModuleGraphSnapshot(rows, filter, limit = 200) {
+    const normalizedFilter = filter?.trim().toLowerCase();
+    const safeLimit = normalizeLimit(limit, 200, 500);
+    const filtered = rows.filter((row) => normalizedFilter ? row.url.toLowerCase().includes(normalizedFilter) : true);
+    const limited = filtered.slice(0, safeLimit);
+    if (limited.length === 0)
+        return "No module resources found";
+    const lines = [];
+    lines.push("# Vite Module Graph (loaded resources)");
+    lines.push(`Total: ${filtered.length}${filtered.length > limited.length ? ` (showing ${limited.length})` : ""}`);
+    lines.push("# idx initiator ms url");
+    lines.push("");
+    limited.forEach((row, idx) => {
+        lines.push(`${idx} ${row.initiator} ${row.durationMs}ms ${row.url}`);
+    });
+    return lines.join("\n");
+}
+export function formatModuleGraphTrace(currentUrls, previousUrls, filter, limit = 200) {
+    if (!previousUrls) {
+        return "No module-graph baseline. Captured current snapshot; run `vite module-graph trace` again.";
+    }
+    const currentSet = new Set(currentUrls);
+    const added = currentUrls.filter((url) => !previousUrls.has(url));
+    const removed = [...previousUrls].filter((url) => !currentSet.has(url));
+    const normalizedFilter = filter?.trim().toLowerCase();
+    const safeLimit = normalizeLimit(limit, 200, 500);
+    const addedFiltered = normalizedFilter
+        ? added.filter((url) => url.toLowerCase().includes(normalizedFilter))
+        : added;
+    const removedFiltered = normalizedFilter
+        ? removed.filter((url) => url.toLowerCase().includes(normalizedFilter))
+        : removed;
+    const lines = [];
+    lines.push("# Vite Module Graph Trace");
+    lines.push(`Added: ${addedFiltered.length}, Removed: ${removedFiltered.length}`);
+    lines.push("");
+    lines.push("## Added");
+    if (addedFiltered.length === 0)
+        lines.push("(none)");
+    else
+        addedFiltered.slice(0, safeLimit).forEach((url) => lines.push(`+ ${url}`));
+    lines.push("");
+    lines.push("## Removed");
+    if (removedFiltered.length === 0)
+        lines.push("(none)");
+    else
+        removedFiltered.slice(0, safeLimit).forEach((url) => lines.push(`- ${url}`));
+    return lines.join("\n");
+}
 export async function goto(url) {
     const currentPage = await ensurePage();
     await currentPage.goto(url, { waitUntil: "domcontentloaded" });
@@ -295,19 +394,7 @@ export async function viteRuntimeStatus() {
             timestamp: Date.now(),
         };
     });
-    const output = [];
-    output.push("# Vite Runtime");
-    output.push(`URL: ${runtime.url}`);
-    output.push(`Framework: ${framework}`);
-    output.push(`Vite Client: ${runtime.hasViteClient ? "loaded" : "not detected"}`);
-    output.push(`HMR Socket: ${runtime.wsState}`);
-    output.push(`Error Overlay: ${runtime.hasErrorOverlay ? "present" : "none"}`);
-    output.push(`Tracked HMR Events: ${hmrEvents.length}`);
-    const last = hmrEvents[hmrEvents.length - 1];
-    if (last) {
-        output.push(`Last HMR Event: ${new Date(last.timestamp).toLocaleTimeString()} [${last.type}] ${last.message}`);
-    }
-    return output.join("\n");
+    return formatRuntimeStatus(runtime, framework, hmrEvents);
 }
 export async function viteHMRTrace(mode, limit = 20) {
     if (!page)
@@ -331,30 +418,7 @@ export async function viteHMRTrace(mode, limit = 20) {
     }
     if (hmrEvents.length === 0)
         return "No HMR updates";
-    const safeLimit = Number.isFinite(limit) && limit > 0 ? Math.min(limit, 200) : 20;
-    const recent = hmrEvents.slice(-safeLimit);
-    if (mode === "summary") {
-        const counts = recent.reduce((acc, event) => {
-            acc[event.type] = (acc[event.type] ?? 0) + 1;
-            return acc;
-        }, {});
-        const lines = ["# HMR Summary"];
-        lines.push(`Events considered: ${recent.length}`);
-        lines.push(`Counts: ${Object.entries(counts)
-            .map(([k, v]) => `${k}=${v}`)
-            .join(", ")}`);
-        const last = recent[recent.length - 1];
-        lines.push(`Last: ${new Date(last.timestamp).toLocaleTimeString()} [${last.type}] ${last.path ?? last.message}`);
-        lines.push("\nUse `vite-browser vite hmr trace --limit <n>` for timeline details.");
-        return lines.join("\n");
-    }
-    return [
-        "# HMR Trace",
-        ...recent.map((event) => {
-            const detail = event.path ? `${event.path}` : event.message;
-            return `[${new Date(event.timestamp).toLocaleTimeString()}] ${event.type} ${detail}`;
-        }),
-    ].join("\n");
+    return formatHmrTrace(mode, hmrEvents, limit);
 }
 export async function viteModuleGraph(filter, limit = 200, mode = "snapshot") {
     if (!page)
@@ -366,52 +430,11 @@ export async function viteModuleGraph(filter, limit = 200, mode = "snapshot") {
     const moduleRows = await collectModuleRows(page);
     const currentUrls = moduleRows.map((row) => row.url);
     const previousUrls = lastModuleGraphUrls ? new Set(lastModuleGraphUrls) : null;
-    const currentSet = new Set(currentUrls);
     lastModuleGraphUrls = [...currentUrls];
-    const normalizedFilter = filter?.trim().toLowerCase();
-    const safeLimit = Number.isFinite(limit) && limit > 0 ? Math.min(limit, 500) : 200;
     if (mode === "trace") {
-        if (!previousUrls) {
-            return "No module-graph baseline. Captured current snapshot; run `vite module-graph trace` again.";
-        }
-        const added = currentUrls.filter((url) => !previousUrls.has(url));
-        const removed = [...previousUrls].filter((url) => !currentSet.has(url));
-        const addedFiltered = normalizedFilter
-            ? added.filter((url) => url.toLowerCase().includes(normalizedFilter))
-            : added;
-        const removedFiltered = normalizedFilter
-            ? removed.filter((url) => url.toLowerCase().includes(normalizedFilter))
-            : removed;
-        const lines = [];
-        lines.push("# Vite Module Graph Trace");
-        lines.push(`Added: ${addedFiltered.length}, Removed: ${removedFiltered.length}`);
-        lines.push("");
-        lines.push("## Added");
-        if (addedFiltered.length === 0)
-            lines.push("(none)");
-        else
-            addedFiltered.slice(0, safeLimit).forEach((url) => lines.push(`+ ${url}`));
-        lines.push("");
-        lines.push("## Removed");
-        if (removedFiltered.length === 0)
-            lines.push("(none)");
-        else
-            removedFiltered.slice(0, safeLimit).forEach((url) => lines.push(`- ${url}`));
-        return lines.join("\n");
+        return formatModuleGraphTrace(currentUrls, previousUrls, filter, limit);
     }
-    const filtered = moduleRows.filter((row) => normalizedFilter ? row.url.toLowerCase().includes(normalizedFilter) : true);
-    const limited = filtered.slice(0, safeLimit);
-    if (limited.length === 0)
-        return "No module resources found";
-    const lines = [];
-    lines.push("# Vite Module Graph (loaded resources)");
-    lines.push(`Total: ${filtered.length}${filtered.length > limited.length ? ` (showing ${limited.length})` : ""}`);
-    lines.push("# idx initiator ms url");
-    lines.push("");
-    limited.forEach((row, idx) => {
-        lines.push(`${idx} ${row.initiator} ${row.durationMs}ms ${row.url}`);
-    });
-    return lines.join("\n");
+    return formatModuleGraphSnapshot(moduleRows, filter, limit);
 }
 async function collectModuleRows(page) {
     return page.evaluate(() => {
@@ -500,7 +523,7 @@ export async function network(idx) {
         return networkLog.format();
     return networkLog.detail(idx);
 }
-async function mapStackTrace(stack, origin, inlineSource = false) {
+export async function mapStackTrace(stack, origin, inlineSource = false, resolver = resolveViaSourceMap) {
     const locationRegex = /(https?:\/\/[^\s)]+):(\d+):(\d+)/g;
     const matches = Array.from(stack.matchAll(locationRegex));
     if (matches.length === 0)
@@ -512,7 +535,7 @@ async function mapStackTrace(stack, origin, inlineSource = false) {
         const column = Number.parseInt(match[3], 10);
         if (!Number.isFinite(line) || !Number.isFinite(column))
             continue;
-        const mapped = await resolveViaSourceMap(origin, fileUrl, line, column, inlineSource);
+        const mapped = await resolver(origin, fileUrl, line, column, inlineSource);
         if (!mapped)
             continue;
         mappedLines.push(`- ${fileUrl}:${line}:${column} -> ${mapped.file}:${mapped.line}:${mapped.column}`);

package/dist/cli.d.ts

@@ -1,2 +1,14 @@
 #!/usr/bin/env node
-export {};
+import { send, type Response } from "./client.js";
+export type CliIo = {
+    send: typeof send;
+    readFile: (path: string, encoding: BufferEncoding) => string;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    exit: (code: number) => never;
+};
+export declare function normalizeUrl(value: string): string;
+export declare function parseNumberFlag(args: string[], name: string, fallback: number): number;
+export declare function runCli(argv: string[], io: CliIo): Promise<void>;
+export declare function exit(io: Pick<CliIo, "stdout" | "stderr" | "exit">, res: Response, msg: string): never;
+export declare function printUsage(): string;