pwa-debug-layer

An AI-native debugging layer for PWAs and modern web apps. It lets an AI agent (e.g. Claude Code via MCP) see and act on your live, logged-in browser the way a developer with full DevTools open would — DOM, console, network, framework state, store state, service workers, caches, and direct interaction — as structured data the model consumes natively.

It's built for the questions developers actually search for and that Chrome DevTools makes you assemble by hand: why won't my service worker update? why is my cache stale? why won't my PWA install? why does this component have the wrong state? — answered by an agent reading the runtime directly, against your real browser profile (extensions, auth, and all), not a sterile automated tab.

What it answers

The PWA failures developers actually search for, read straight from your live runtime:

• Why won't my service worker update? Why are some users on old code? — SW lifecycle with waiting-vs-active versions, plus an update-propagation / version-skew analyzer.
• Why is my cache stale? Why are chunks 404ing after a deploy? — CacheStorage contents with age, and a cached-HTML-vs-JS skew check.
• Why won't my PWA install? — structured installability diagnostics with per-gap remediation, not just "manifest invalid."
• What's actually in IndexedDB / localStorage right now? — live storage inspection (inspect IndexedDB live).
• What can this browser actually do? — a live capability matrix (Push / Background Sync / Periodic Sync / Badging / File System Access / Window Controls Overlay).

All read from your real, logged-in profile — service-worker, cache, and extension state included — which chrome-devtools-mcp's sterile automated Chrome can't see.

The goal is to eliminate the "user is the AI's eyes and hands" loop. Today, debugging a PWA with AI usually means the human copy/pastes DOM snippets, describes console errors, screenshots UI state, and hand-executes clicks. This project replaces that with direct, structured access.

Status: working on Linux. The full MCP→IPC→native-host→service-worker→page-world round-trip is live, and a broad debugging surface is shipped:

• Capture — console / network / error / DOM-mutation / lifecycle, with persistent ring buffers + disk spill.
• Framework introspection — React, Vue, Svelte, and Solid (component/element trees, state, find-by-text/role).
• Store introspection — Redux, Zustand, Pinia, and Jotai (read, subscribe, dispatch).
• Interaction + touch gestures — click, fill, submit, hover, focus/blur, select, key/type, drag, scroll, swipe, tap, double-tap, long-press, pinch.
• Library-popup capture/replay — WalletConnect / SDK modals: record, replay, tail, failure correlation.
• Replay & source maps — rrweb session_record/session_replay, source_map_resolve.
• Browser launcher — one-call pdl_launch_browser with chrome-devtools-mcp coexistence.
• PWA Runtime Diagnostics — service-worker lifecycle + versions, CacheStorage contents + age, installability gaps, a live capability matrix, IndexedDB/web-storage inspection, update-propagation / version-skew analysis, and a one-shot runtime-state snapshot.

Verified on Linux (the full suite live-tested against a real PWA). macOS/Windows code paths are implemented with unit coverage but still need real-machine retest (help wanted). Firefox is not supported (it doesn't speak CDP).

⚠️ macOS / Windows users, beware: these platforms have never been run on real hardware — only unit-tested with injected fakes. Expect rough edges (browser detection, profile paths, native-messaging registration, system-default resolution). Please open an issue with the failing command and its output — bug reports from real macOS/Windows machines are the single most useful contribution right now. See Help wanted for the specific things to try.

How it differs from chrome-devtools-mcp

Google's chrome-devtools-mcp gives an AI Chrome DevTools Protocol access (DOM, console, network, screenshots). That covers a lot.

pwa-debug-layer is complementary — it targets the things CDP can't reach:

• Your real, logged-in browser. chrome-devtools-mcp spawns a fresh automated Chrome — which shows "controlled by automated test software," blocks extension loading, and has none of your auth/session state, so authenticated apps are hard to debug (the extensions/auth gap, #265). pwa-debug-layer's default existing mode attaches to your normal profile, with its real cookies, extensions, and service-worker state — exactly the real-profile SW/extension visibility people keep asking Google for (#1173, #96).
• Framework state. React fiber trees, Vue reactive state, Svelte component graphs, Solid signals — read via the framework's own devtools hooks (__REACT_DEVTOOLS_GLOBAL_HOOK__, __vue_app__, _vnode, etc.). CDP can't see these.
• Store state. Redux / Zustand / Pinia / Jotai — read, subscribe, and dispatch.
• Service-worker, cache & installability state. SW lifecycle + versions, CacheStorage contents + age, manifest installability gaps, IndexedDB/web storage, and an update-propagation / version-skew analyzer — the highest-volume PWA pain (stale cache, "SW won't update," install failures, "why are some users on old code") that DevTools makes you piece together by hand.
• Shadow DOM, iframes, dynamically-injected library widgets. WalletConnect modals, third-party SDK popups, and other widgets that escape standard DOM tooling.
• Page-world reach in general. A MAIN-world script we inject reaches things isolated-world content scripts can't, and reaches them earlier than initScript-on-next-nav.
• Persistent ring buffers + rrweb-style replay across navigations and reloads.
• Configurable filters so the AI receives only the slice it asked for — no full-DOM noise.

The two are designed to coexist: install both, the AI uses each for what it does best, with zero tool-surface duplication.

Architecture

┌──────────────────┐  MCP (stdio)  ┌──────────────────────────┐
│  Claude Code     │ ◄───────────► │  Native Messaging Host   │
│  (or any MCP     │               │  - MCP server            │
│   client)        │               │  - Ring buffers          │
└──────────────────┘               │  - Replay/snapshot store │
                                   └────────────┬─────────────┘
                                                │ Native Messaging
                                                │ (JSON over stdio)
                                                ▼
                                   ┌──────────────────────────┐
                                   │  Extension Service Worker│
                                   │  - chrome.debugger (CDP) │
                                   │  - Tab/router            │
                                   └────────────┬─────────────┘
                                                │
                       ┌────────────────────────┼────────────────────────┐
                       ▼                        ▼                        ▼
            ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐
            │ Content Script     │  │ Page-World Script  │  │ DevTools Panel     │
            │ (isolated world)   │  │ (MAIN world)       │  │ (planned)          │
            │ - DOM observe      │  │ - React/Vue hooks  │  │ - Human inspector  │
            │ - Action exec      │  │ - fetch/XHR patch  │  │   of AI session    │
            │ - Bridge to SW     │  │ - Bus/RxJS taps    │  │                    │
            └────────────────────┘  └────────────────────┘  └────────────────────┘
                       └────────── live page (the PWA being debugged) ─────────┘

Three components, one installable unit:

• Extension owns the page (DOM, content scripts, page-world hooks).
• Native host owns persistence and the MCP server (long-lived, can hold buffers, can write files).
• MCP owns the AI contract.

Each does what only it can. See docs/PLAN.md for the full design.

Browser support

Chromium-family only, sideloaded. Tested against:

• Chromium (native package)
• Google Chrome (.deb / .rpm)
• Brave Browser
• Microsoft Edge (Linux .deb)
• Vivaldi
• Opera

macOS Application Support paths and Windows HKCU-registry registration are implemented and have unit-test coverage; the manual round-trip retest currently runs on Linux.

Snap browsers are not supported

If you installed your browser via snap (e.g. snap install chromium on Ubuntu), it will not work with pwa-debug-layer.

Why: snap's home interface allows the browser to read files in $HOME but blocks exec of any binary whose resolved path crosses a hidden directory (~/.nvm/..., ~/.config/...). The native messaging host launcher and the node binary it invokes both live under hidden paths in a normal install, so spawn fails with Permission denied and the service worker reports Native host has exited. There is no fix on the extension/host side that doesn't require copying ~125 MB of node into a non-hidden install dir per registration; not worth the install bloat for a setup most distros let you avoid.

What to do: install your Chromium-family browser from a native package source instead: