@presto1314w/vite-devtools-browser 0.2.0 → 0.3.0

package/README.md

@@ -7,6 +7,7 @@ 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
+- early propagation diagnostics from store/module updates into rerender paths
 - rule-based HMR diagnosis with confidence levels
 - module graph snapshots and diffs
 - mapped error output with optional source snippets
@@ -17,16 +18,19 @@ 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`.
+Current documented baseline: `v0.3.0`.
 
-## What's New In v0.2
+## What's New In v0.3
 
-`v0.2.0` moves `vite-browser` from snapshot-style inspection toward runtime diagnosis:
+`v0.3.0` is the propagation-diagnostics release.
 
-- 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
+It keeps the `v0.2.x` runtime diagnosis model, then adds a new layer of propagation-oriented reasoning:
+
+- `correlate renders` summarizes recent render/update propagation evidence
+- `diagnose propagation` turns store/module/render/error signals into structured guidance
+- Vue-first store updates now include top-level `changedKeys`
+- browser-side collection now captures render and store-update signals as first-class events
+- propagation output stays conservative when evidence is incomplete
 
 ## Built For Agents
 
@@ -45,6 +49,7 @@ Most browser CLIs are optimized for automation. Most framework devtools are opti
 - 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 can surface high-confidence clues about how store/module changes propagate into rerender paths
 - it returns structured text that AI agents can consume directly in loops
 
 ## Positioning
@@ -84,6 +89,8 @@ vite-browser detect
 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
 vite-browser vite hmr trace --limit 20
 vite-browser vite module-graph trace --limit 50
@@ -135,6 +142,26 @@ Confidence: high
 HMR update observed within 5000ms of the current error
 Matching modules: /src/App.tsx
 
+$ vite-browser correlate renders --window 5000
+# Render Correlation
+Confidence: high
+Recent source/store updates likely propagated through 1 render step(s).
+
+## Store Updates
+- cart
+
+## Changed Keys
+- items
+
+## Render Path
+- AppShell > ShoppingCart > CartSummary
+
+$ vite-browser diagnose propagation --window 5000
+# Propagation Diagnosis
+Status: fail
+Confidence: high
+A plausible store -> render -> error propagation path was found.
+
 $ vite-browser diagnose hmr --limit 50
 # HMR Diagnosis
 ## missing-module
@@ -155,6 +182,8 @@ Suggestion: Verify the import path, file extension, alias configuration, and whe
   - HMR summary/timeline/clear
   - module-graph snapshot/diff/clear
   - error/HMR correlation over recent event windows
+  - render/store propagation correlation over recent event windows
+  - early propagation diagnosis with store updates, changed keys, and render paths
   - rule-based HMR diagnosis with confidence levels
   - source-mapped errors with optional inline source snippet
 - Debug utilities: console logs, network tracing, screenshot, page `eval`
@@ -167,6 +196,8 @@ Suggestion: Verify the import path, file extension, alias configuration, and whe
 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
 vite-browser vite hmr trace --limit 50
 vite-browser vite module-graph trace --limit 200
@@ -195,13 +226,14 @@ vite-browser svelte tree
 
 ## Current Boundaries
 
-`vite-browser` v0.2 is strong at:
+`vite-browser` v0.3.0 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
+- narrowing likely store/module -> render paths in Vue-first flows
 
-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.
+`v0.3.0` is still not a full propagation-trace engine. Treat `correlate renders` and `diagnose propagation` as high-confidence propagation clues, not strict causal proof. In particular, they do not reliably infer deep chains like `store -> component A -> component B -> error` across arbitrary component graphs, and they intentionally fall back to conservative output when evidence is incomplete.
 
 ## Command Reference
 
@@ -241,8 +273,10 @@ 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

package/dist/browser-collector.d.ts

@@ -0,0 +1,3 @@
+import type { VBEvent } from "./event-queue.js";
+export declare function initBrowserEventCollector(): void;
+export declare function readBrowserEvents(): VBEvent[];

package/dist/browser-collector.js

@@ -0,0 +1,256 @@
+export function initBrowserEventCollector() {
+    if (window.__vb_events)
+        return;
+    window.__vb_events = [];
+    window.__vb_push = (event) => {
+        const q = window.__vb_events;
+        q.push(event);
+        if (q.length > 1000)
+            q.shift();
+    };
+    const inferFramework = () => {
+        if (window.__VUE__ || window.__VUE_DEVTOOLS_GLOBAL_HOOK__)
+            return "vue";
+        if (window.__REACT_DEVTOOLS_GLOBAL_HOOK__ || window.React)
+            return "react";
+        if (window.__SVELTE__ || window.__svelte || window.__SVELTE_DEVTOOLS_GLOBAL_HOOK__) {
+            return "svelte";
+        }
+        return "unknown";
+    };
+    const inferRenderLabel = () => {
+        const heading = document.querySelector("main h1, [role='main'] h1, h1")?.textContent?.trim() ||
+            document.title ||
+            location.pathname ||
+            "/";
+        return heading.slice(0, 120);
+    };
+    const inferVueRenderDetails = () => {
+        const hook = window.__VUE_DEVTOOLS_GLOBAL_HOOK__;
+        const apps = hook?.apps;
+        if (!Array.isArray(apps) || apps.length === 0)
+            return null;
+        const app = apps[0];
+        const rootInstance = app?._instance || app?._container?._vnode?.component;
+        if (!rootInstance)
+            return null;
+        const names = [];
+        let current = rootInstance;
+        let guard = 0;
+        while (current && guard < 8) {
+            const name = current.type?.name ||
+                current.type?.__name ||
+                current.type?.__file?.split(/[\\/]/).pop()?.replace(/\.\w+$/, "") ||
+                "Anonymous";
+            names.push(String(name));
+            const nextFromSubtree = current.subTree?.component;
+            const nextFromChildren = Array.isArray(current.subTree?.children)
+                ? current.subTree.children.find((child) => child?.component)?.component
+                : null;
+            current = nextFromSubtree || nextFromChildren || null;
+            guard++;
+        }
+        const pinia = window.__PINIA__ || window.pinia || app?.config?.globalProperties?.$pinia;
+        const registry = pinia?._s;
+        const storeIds = registry instanceof Map
+            ? Array.from(registry.keys()).map(String)
+            : registry && typeof registry === "object"
+                ? Object.keys(registry)
+                : [];
+        return {
+            component: names[names.length - 1] || inferRenderLabel(),
+            componentPath: names.join(" > "),
+            storeHints: storeIds.slice(0, 5),
+        };
+    };
+    const inferRenderDetails = () => {
+        const framework = inferFramework();
+        if (framework === "vue") {
+            const vue = inferVueRenderDetails();
+            if (vue) {
+                return {
+                    framework,
+                    component: vue.component,
+                    path: vue.componentPath,
+                    storeHints: vue.storeHints,
+                };
+            }
+        }
+        return {
+            framework,
+            component: inferRenderLabel(),
+            path: `${framework}:${location.pathname || "/"}`,
+            storeHints: [],
+        };
+    };
+    const renderState = window.__vb_render_state ||
+        (window.__vb_render_state = {
+            timer: null,
+            lastReason: "initial-load",
+            mutationCount: 0,
+        });
+    const scheduleRender = (reason, extra = {}) => {
+        renderState.lastReason = reason;
+        renderState.mutationCount += Number(extra.mutationCount ?? 0);
+        if (renderState.timer != null)
+            window.clearTimeout(renderState.timer);
+        renderState.timer = window.setTimeout(() => {
+            const details = inferRenderDetails();
+            const changedKeys = Array.isArray(extra.changedKeys)
+                ? extra.changedKeys.filter((value) => typeof value === "string" && value.length > 0)
+                : [];
+            window.__vb_push({
+                timestamp: Date.now(),
+                type: "render",
+                payload: {
+                    component: details.component,
+                    path: details.path,
+                    framework: details.framework,
+                    reason: renderState.lastReason,
+                    mutationCount: renderState.mutationCount,
+                    storeHints: details.storeHints,
+                    changedKeys,
+                },
+            });
+            renderState.timer = null;
+            renderState.mutationCount = 0;
+        }, 60);
+    };
+    const attachPiniaSubscriptions = () => {
+        if (window.__vb_pinia_attached)
+            return;
+        const hook = window.__VUE_DEVTOOLS_GLOBAL_HOOK__;
+        const app = Array.isArray(hook?.apps) ? hook.apps[0] : null;
+        const pinia = window.__PINIA__ || window.pinia || app?.config?.globalProperties?.$pinia;
+        const registry = pinia?._s;
+        if (!(registry instanceof Map) || registry.size === 0)
+            return;
+        const attached = (window.__vb_pinia_attached = new Set());
+        registry.forEach((store, storeId) => {
+            if (!store || typeof store.$subscribe !== "function" || attached.has(String(storeId)))
+                return;
+            attached.add(String(storeId));
+            const extractChangedKeys = (mutation) => {
+                const keys = new Set();
+                const events = mutation?.events;
+                const collect = (entry) => {
+                    const key = entry?.key ?? entry?.path;
+                    if (typeof key === "string" && key.length > 0)
+                        keys.add(key.split(".")[0]);
+                };
+                if (Array.isArray(events))
+                    events.forEach(collect);
+                else if (events && typeof events === "object")
+                    collect(events);
+                const payload = mutation?.payload;
+                if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+                    Object.keys(payload).forEach((key) => keys.add(key));
+                }
+                return Array.from(keys).slice(0, 10);
+            };
+            store.$subscribe((mutation) => {
+                const changedKeys = extractChangedKeys(mutation);
+                window.__vb_push({
+                    timestamp: Date.now(),
+                    type: "store-update",
+                    payload: {
+                        store: String(storeId),
+                        mutationType: typeof mutation?.type === "string" ? mutation.type : "unknown",
+                        events: Array.isArray(mutation?.events) ? mutation.events.length : 0,
+                        changedKeys,
+                    },
+                });
+                scheduleRender("store-update", { changedKeys });
+            }, { detached: true });
+        });
+    };
+    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,
+                    });
+                    if (data.type === "update" || data.type === "full-reload") {
+                        scheduleRender("hmr-message");
+                    }
+                }
+                catch { }
+            });
+            return true;
+        }
+        return false;
+    }
+    if (!attachViteListener()) {
+        let attempts = 0;
+        const timer = setInterval(() => {
+            attempts++;
+            if (attachViteListener() || attempts >= 50) {
+                clearInterval(timer);
+            }
+        }, 100);
+    }
+    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;
+    };
+    window.addEventListener("unhandledrejection", (e) => {
+        window.__vb_push({
+            timestamp: Date.now(),
+            type: "error",
+            payload: { message: e.reason?.message, stack: e.reason?.stack },
+        });
+    });
+    const observeDom = () => {
+        const root = document.body || document.documentElement;
+        if (!root || window.__vb_render_observer)
+            return;
+        const observer = new MutationObserver((mutations) => {
+            scheduleRender("dom-mutation", { mutationCount: mutations.length });
+        });
+        observer.observe(root, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            characterData: true,
+        });
+        window.__vb_render_observer = observer;
+    };
+    const patchHistory = () => {
+        if (window.__vb_history_patched)
+            return;
+        const wrap = (method) => {
+            const original = history[method];
+            const wrapped = ((...args) => {
+                const result = Reflect.apply(original, history, args);
+                scheduleRender(`history-${method}`);
+                return result;
+            });
+            history[method] = wrapped;
+        };
+        wrap("pushState");
+        wrap("replaceState");
+        window.addEventListener("popstate", () => scheduleRender("history-popstate"));
+        window.addEventListener("hashchange", () => scheduleRender("hashchange"));
+        window.__vb_history_patched = true;
+    };
+    observeDom();
+    patchHistory();
+    attachPiniaSubscriptions();
+    window.setInterval(attachPiniaSubscriptions, 1000);
+    scheduleRender("initial-load");
+}
+export function readBrowserEvents() {
+    const events = (window.__vb_events ?? []);
+    window.__vb_events = [];
+    return events;
+}

package/dist/browser-frameworks.d.ts

@@ -0,0 +1,11 @@
+import type { Page } from "playwright";
+import type { BrowserFramework, BrowserSessionState } from "./browser-session.js";
+export declare function detectBrowserFramework(page: Page): Promise<{
+    detected: string;
+    framework: BrowserFramework;
+}>;
+export declare function inspectVueTree(page: Page, id?: string): Promise<string>;
+export declare function inspectVuePinia(page: Page, store?: string): Promise<string>;
+export declare function inspectVueRouter(page: Page): Promise<string>;
+export declare function inspectReactTree(state: BrowserSessionState, page: Page, id?: string): Promise<string>;
+export declare function inspectSvelteTree(page: Page, id?: string): Promise<string>;

package/dist/browser-frameworks.js

@@ -0,0 +1,72 @@
+import * as vueDevtools from "./vue/devtools.js";
+import * as reactDevtools from "./react/devtools.js";
+import * as svelteDevtools from "./svelte/devtools.js";
+export async function detectBrowserFramework(page) {
+    const detected = await page.evaluate(() => {
+        if (window.__VUE__ || window.__VUE_DEVTOOLS_GLOBAL_HOOK__) {
+            const version = window.__VUE__?.version || "unknown";
+            return `vue@${version}`;
+        }
+        const reactHook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+        if (reactHook || window.React || document.querySelector("[data-reactroot]")) {
+            const renderers = reactHook?.renderers;
+            const firstRenderer = renderers ? renderers.values().next().value : null;
+            const version = firstRenderer?.version || window.React?.version || "unknown";
+            return `react@${version}`;
+        }
+        if (window.__SVELTE__ ||
+            window.__svelte ||
+            window.__SVELTE_DEVTOOLS_GLOBAL_HOOK__) {
+            const version = window.__SVELTE__?.VERSION ||
+                window.__svelte?.version ||
+                "unknown";
+            return `svelte@${version}`;
+        }
+        return "unknown";
+    });
+    return {
+        detected,
+        framework: toBrowserFramework(detected),
+    };
+}
+export async function inspectVueTree(page, id) {
+    return id ? vueDevtools.getComponentDetails(page, id) : vueDevtools.getComponentTree(page);
+}
+export async function inspectVuePinia(page, store) {
+    return vueDevtools.getPiniaStores(page, store);
+}
+export async function inspectVueRouter(page) {
+    return vueDevtools.getRouterInfo(page);
+}
+export async function inspectReactTree(state, page, id) {
+    if (!id) {
+        state.lastReactSnapshot = await reactDevtools.snapshot(page);
+        return reactDevtools.format(state.lastReactSnapshot);
+    }
+    const parsed = Number.parseInt(id, 10);
+    if (!Number.isFinite(parsed))
+        throw new Error("react component id must be a number");
+    const inspected = await reactDevtools.inspect(page, parsed);
+    const lines = [];
+    const componentPath = reactDevtools.path(state.lastReactSnapshot, parsed);
+    if (componentPath)
+        lines.push(`path: ${componentPath}`);
+    lines.push(inspected.text);
+    if (inspected.source) {
+        const [file, line, column] = inspected.source;
+        lines.push(`source: ${file}:${line}:${column}`);
+    }
+    return lines.join("\n");
+}
+export async function inspectSvelteTree(page, id) {
+    return id ? svelteDevtools.getComponentDetails(page, id) : svelteDevtools.getComponentTree(page);
+}
+function toBrowserFramework(detected) {
+    if (detected.startsWith("vue"))
+        return "vue";
+    if (detected.startsWith("react"))
+        return "react";
+    if (detected.startsWith("svelte"))
+        return "svelte";
+    return "unknown";
+}

package/dist/browser-session.d.ts

@@ -0,0 +1,27 @@
+import { type BrowserContext, type Page } from "playwright";
+import type { ReactNode } from "./react/devtools.js";
+export type BrowserFramework = "vue" | "react" | "svelte" | "unknown";
+export type HmrEventType = "connecting" | "connected" | "update" | "full-reload" | "error" | "log";
+export type HmrEvent = {
+    timestamp: number;
+    type: HmrEventType;
+    message: string;
+    path?: string;
+};
+export type BrowserSessionState = {
+    context: BrowserContext | null;
+    page: Page | null;
+    framework: BrowserFramework;
+    extensionModeDisabled: boolean;
+    consoleLogs: string[];
+    hmrEvents: HmrEvent[];
+    lastReactSnapshot: ReactNode[];
+    lastModuleGraphUrls: string[] | null;
+};
+export declare function createBrowserSessionState(): BrowserSessionState;
+export declare function getCurrentPage(state: BrowserSessionState): Page | null;
+export declare function resetBrowserSessionState(state: BrowserSessionState): void;
+export declare function ensureBrowserPage(state: BrowserSessionState, onPageReady: (page: Page) => void): Promise<Page>;
+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;

package/dist/browser-session.js

@@ -0,0 +1,113 @@
+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;
+export function createBrowserSessionState() {
+    return {
+        context: null,
+        page: null,
+        framework: "unknown",
+        extensionModeDisabled: false,
+        consoleLogs: [],
+        hmrEvents: [],
+        lastReactSnapshot: [],
+        lastModuleGraphUrls: null,
+    };
+}
+export function getCurrentPage(state) {
+    if (!contextUsable(state.context))
+        return null;
+    if (!state.page || state.page.isClosed())
+        return null;
+    return state.page;
+}
+export function resetBrowserSessionState(state) {
+    state.context = null;
+    state.page = null;
+    state.framework = "unknown";
+    state.consoleLogs.length = 0;
+    state.hmrEvents.length = 0;
+    state.lastModuleGraphUrls = null;
+    state.lastReactSnapshot = [];
+}
+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;
+    }
+    if (!state.context)
+        throw new Error("browser not open");
+    if (!state.page || state.page.isClosed()) {
+        try {
+            state.page = state.context.pages()[0] ?? (await state.context.newPage());
+        }
+        catch (error) {
+            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.page = state.context.pages()[0] ?? (await state.context.newPage());
+        }
+        onPageReady(state.page);
+    }
+    return state.page;
+}
+export async function closeBrowserSession(state) {
+    await state.context?.close();
+    resetBrowserSessionState(state);
+}
+export function contextUsable(current) {
+    if (!current)
+        return false;
+    try {
+        current.pages();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isClosedTargetError(error) {
+    if (!(error instanceof 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;
+        }
+    }
+    const browser = await chromium.launch({
+        headless: false,
+        args: ["--auto-open-devtools-for-tabs"],
+    });
+    return {
+        context: await browser.newContext({ viewport: { width: 1280, height: 720 } }),
+        extensionModeDisabled,
+    };
+}

package/dist/browser-vite.d.ts

@@ -0,0 +1,25 @@
+import type { Page } from "playwright";
+import type { HmrEvent } from "./browser-session.js";
+export type RuntimeSnapshot = {
+    url: string;
+    hasViteClient: boolean;
+    wsState: string;
+    hasErrorOverlay: boolean;
+    timestamp: number;
+};
+export type ModuleRow = {
+    url: string;
+    initiator: string;
+    durationMs: number;
+};
+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 readRuntimeSnapshot(page: Page): Promise<RuntimeSnapshot>;
+export declare function collectModuleRows(page: Page): Promise<ModuleRow[]>;
+export declare function readOverlayError(page: Page): Promise<{
+    message?: string;
+    stack?: string;
+} | null>;