PWA Debug Layer

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).
• Does anything break at 360 px, in Spanish, in dark mode, in this app state? — one layout_sweep call checks every page × width × color scheme × state and returns a short list of distinct problems.

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.

- Android phones — the same tools drive Android Chrome tabs and installed PWAs over adb (pdl_android_attach), no desktop browser in the loop.

- Responsive layout sweep — layout_sweep emulates widths and color schemes over CDP, walks app states and languages, measures overflow, off-screen elements, tap targets, pinned bars, cut-off text, edge contact, clipped focus/selection rings and unresolved copy, runs your own custom_checks, and groups the results into distinct problems.

- 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:

• Ubuntu/Debian: apt install chromium from the universe repo if you've enabled the non-snap source, or apt install brave-browser / microsoft-edge-stable from their respective .deb repos. The Chromium tarball from chromium.org also works.
• Fedora: dnf install chromium is non-snap by default.
• Arch: pacman -S chromium.

Flatpak browsers are detected and have a manifest written, but flatpak confinement may also block exec — if it fails, run flatpak override --user --filesystem=host and retry.

Installation

Prerequisites

• Node.js ≥ 20.19 (developed on 23.x)
• pnpm
• A Chromium-family browser not installed via snap (see above)
• An MCP-aware client (e.g. Claude Code)

1. Build the host and extension

git clone https://github.com/<your-fork>/pwa-debug-layer

cd pwa-debug-layer pnpm install pnpm build # builds packages/host/dist/main.js and packages/extension/dist/ pnpm test # full workspace unit suite (shared + host + extension)

2. Add the host to your MCP client

For Claude Code, add to your .mcp.json (project-scoped) or ~/.claude/mcp.json (global):

{

"mcpServers": { "pwa-debug": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/pwa-debug-layer/packages/host/dist/main.js"] } } }

Restart Claude Code so it picks up