PWA Debug Layer

pwa-debug-layer

PWA と最新のウェブアプリ向けの AI ネイティブなデバッグレイヤーです。AI エージェント（MCP 経由の Claude Code など）が、開発者が DevTools をすべて開いているときと同じように、実行中のログイン済みブラウザーを確認し、操作できます。DOM、コンソール、ネットワーク、フレームワークの状態、ストアの状態、サービスワーカー、キャッシュ、直接の操作を、モデルがネイティブに処理できる構造化データとして扱います。

開発者が実際に検索する疑問、そして Chrome DevTools では手作業で情報を集める必要がある疑問に答えるために作られています。サービスワーカーが更新されないのはなぜ？ キャッシュが古いのはなぜ？ PWA をインストールできないのはなぜ？ このコンポーネントの状態が間違っているのはなぜ？ ― エージェントが実行時の情報を直接読み取って解決します。対象は、拡張機能や認証情報などを含む実際のブラウザープロファイルであり、隔離された自動操作用タブではありません。

回答できる質問

開発者が実際に検索している PWA の問題について、稼働中のランタイムから直接読み取って答えます。

• サービスワーカーが更新されないのはなぜですか？古いコードを使っているユーザーがいるのはなぜですか？ — 待機中とアクティブなバージョンを含む SW のライフサイクルに加え、更新の伝播／バージョン不整合を分析します。
• キャッシュが古いのはなぜですか？デプロイ後にチャンクが 404 になるのはなぜですか？ — キャッシュの経過時間を含む CacheStorage の内容と、キャッシュされた HTML と JS の不整合チェックを確認します。
• PWA をインストールできないのはなぜですか？ — 「マニフェストが無効です」と伝えるだけでなく、不足項目ごとの修正方法を含む、構造化されたインストール可能性の診断を行います。
• 今、IndexedDB／localStorage には実際に何が入っていますか？ — ストレージの内容をリアルタイムで確認します（IndexedDB のリアルタイム検査）。
• このブラウザーで実際に利用できる機能は何ですか？ — 機能のライブマトリックス（Push / Background Sync / Periodic Sync / Badging / File System Access / Window Controls Overlay）を確認します。

いずれも、実際にログインしているプロファイルから読み取ります。サービスワーカー、キャッシュ、拡張機能の状態も含まれます。chrome-devtools-mcp の無機質な自動化 Chrome では確認できない情報です。

目標は、「ユーザーが AI の目と手になる」ループをなくすことです。現在、AI を使って PWA をデバッグするには、通常、人間が DOM のスニペットをコピー＆ペーストし、コンソールのエラーを説明し、UI の状態をスクリーンショットで共有して、クリックを手動で実行します。このプロジェクトは、そうした作業を構造化された直接アクセスに置き換えます。

ステータス：Linux で動作中です。 MCP→IPC→ネイティブホスト→サービスワーカー→ページワールドの全ラウンドトリップが稼働しており、幅広いデバッグ機能を提供しています。

• キャプチャ — コンソール／ネットワーク／エラー／DOM の変更／ライフサイクルを、永続リングバッファーとディスクへの退避機能付きで記録します。
• フレームワークのイントロスペクション — React、Vue、Svelte、Solid（コンポーネント／要素のツリー、状態、テキスト／ロールによる検索）。
• ストアのイントロスペクション — Redux、Zustand、Pinia、Jotai（読み取り、購読、ディスパッチ）。
• 操作とタッチジェスチャー — クリック、入力、送信、ホバー、フォーカス／フォーカス解除、選択、キー入力／文字入力、ドラッグ、スクロール、スワイプ、タップ、ダブルタップ、長押し、ピンチ。
• ライブラリのポップアップのキャプチャ／再生 — WalletConnect／SDK モーダル：記録、再生、追跡、失敗との関連付け。
• リプレイとソースマップ — rrweb の session_record／session_replay、source_map_resolve。
• ブラウザーランチャー — chrome-devtools-mcp との共存に対応した、ワンコールの pdl_launch_browser。
• PWA ランタイム診断 — サービスワーカーのライフサイクルとバージョン、CacheStorage の内容と経過時間、インストール可能性の不足項目、ライブ機能マトリックス、IndexedDB／Web ストレージの検査、更新の伝播／バージョン不整合の分析、ワンショットのランタイム状態スナップショット。

Linux で検証済み（実際の PWA を対象に、全テストスイートを稼働状態でテスト済みです）。macOS／Windows のコードパスはユニットテストを含めて実装済みですが、実機での再テストが必要です（ご協力ください：macOS／Windows での検証）。Firefox はサポート対象外です（CDP に対応していません）。

⚠️ macOS／Windows ユーザーの方はご注意ください：これらのプラットフォームは実機で一度も動作させていません。注入したフェイクを使ったユニットテストのみを実施しています。ブラウザーの検出、プロファイルのパス、ネイティブメッセージングの登録、システム既定値の解決などに不具合が残っている可能性があります。失敗したコマンドとその出力を添えて、イシューを作成してください。現在、実際の macOS／Windows マシンからのバグ報告が最も役立つ貢献です。具体的に試していただきたい内容は、ご協力くださいをご覧ください。

chrome-devtools-mcp との違い

Google の chrome-devtools-mcp は、AI に Chrome DevTools Protocol へのアクセスを提供します（DOM、コンソール、ネットワーク、スクリーンショット）。これで多くのことに対応できます。

pwa-debug-layer は相補的なツールであり、CDP ではアクセスできないものを対象としています。

• 実際にログインしているブラウザー。 chrome-devtools-mcp は新しい自動化された Chrome を起動します。そこには「自動テスト ソフトウェアによって制御されています」と表示され、拡張機能の読み込みがブロックされ、認証やセッションの状態もないため、認証が必要なアプリのデバッグは困難です（拡張機能／認証のギャップ、#265）。pwa-debug-layer のデフォルトの existing モードは、実際の Cookie、拡張機能、サービスワーカーの状態を備えた通常のプロファイルに接続します。これは、Google に対して繰り返し要望されている、実際のプロファイルにおける SW／拡張機能の可視性を実現します（#1173、#96）。
• フレームワークの状態。 React のファイバーツリー、Vue のリアクティブな状態、Svelte のコンポーネントグラフ、Solid のシグナルなどを、フレームワーク独自の DevTools フック（__REACT_DEVTOOLS_GLOBAL_HOOK__、__vue_app__、_vnode など）経由で読み取ります。CDP からはこれらを確認できません。
• ストアの状態。 Redux／Zustand／Pinia／Jotai の状態を読み取り、購読し、ディスパッチします。
• サービスワーカー、キャッシュ、インストール可能性の状態。 SW のライフサイクルとバージョン、CacheStorage の内容と経過時間、マニフェストのインストール可能性に関する問題、IndexedDB／Web Storage に加え、更新の伝播／バージョン不一致を分析します。これらは PWA で最も頻繁に発生する問題です（古いキャッシュ、「SW が更新されない」、インストールの失敗、「一部のユーザーが古いコードを使っているのはなぜか」など）。DevTools では、これらを手作業で組み合わせて把握する必要があります。
• Shadow DOM、iframe、動的に挿入されるライブラリーのウィジェット。 WalletConnect のモーダル、サードパーティ SDK のポップアップ、標準的な DOM ツールでは扱えないその他のウィジェットに対応します。
• 一般的なページワールドへのアクセス。 注入する MAIN ワールドのスクリプトは、分離されたワールドのコンテンツスクリプトではアクセスできないものにアクセスでき、次のページ遷移時に実行する initScript よりも早くアクセスできます。
• ナビゲーションや再読み込みをまたいで保持されるリングバッファーと、rrweb 形式のリプレイ。
• 設定可能なフィルターにより、AI には要求された範囲だけが渡されます。DOM 全体によるノイズはありません。

この 2 つは併用できるよう設計されています。両方をインストールすると、AI はそれぞれの得意分野に応じて使い分け、ツール機能の重複は発生しません。

アーキテクチャ

┌──────────────────┐  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) ─────────┘

3 つのコンポーネントを、1 つのインストール可能なユニットにまとめています。

• 拡張機能はページ（DOM、コンテンツスクリプト、ページワールドのフック）を担当します。
• ネイティブホストは永続化と MCP サーバーを担当します（長時間稼働でき、バッファーを保持し、ファイルを書き込めます）。
• MCPは AI との契約を担当します。

それぞれにしかできないことを担います。設計の全容については、docs/PLAN.md を参照してください。

ブラウザーのサポート

Chromium 系のみで、サイドロード方式です。以下のブラウザーでテスト済みです。

• Chromium（ネイティブパッケージ）
• Google Chrome（.deb／.rpm）
• Brave Browser
• Microsoft Edge（Linux .deb）
• Vivaldi
• Opera

macOS の Application Support パスと、Windows の HKCU レジストリ登録は実装済みで、ユニットテストでカバーされています。手動での一連の再テストは現在、Linux 上で実施しています。

Snap ブラウザーには対応していません

ブラウザーを snap（Ubuntu での snap install chromium など）経由でインストールした場合、pwa-debug-layer では動作しません。

理由： snap の home インターフェースでは、ブラウザーによる $HOME 内のファイルの 読み取り は許可されますが、解決後のパスが隠しディレクトリ（~/.nvm/...、~/.config/...）を通るバイナリの 実行 はブロックされます。通常のインストールでは、ネイティブメッセージングホストのランチャーと、それが呼び出す Node バイナリがどちらも隠しパス内にあるため、起動時に Permission denied が発生し、サービスワーカーは Native host has exited. と報告します。登録ごとに約 125 MB の Node を隠しディレクトリではないインストール先にコピーしない限り、拡張機能／ホスト側での解決策はありません。多くのディストリビューションで回避できる構成のために、インストール容量を増やす価値はありません。

対応方法： Chromium 系ブラウザーをネイティブのパッケージソースからインストールしてください。

• Ubuntu/Debian： snap 以外のソースを有効にしている場合は、universe リポジトリから apt install chromium を実行するか、それぞれの .deb リポジトリから apt install brave-browser ／ microsoft-edge-stable を実行してください。chromium.org の Chromium tarball も使用できます。
• Fedora： dnf install chromium はデフォルトで snap ではありません。
• Arch： pacman -S chromium を実行してください。

Flatpak ブラウザーは検出され、マニフェストが書き込まれますが、Flatpak の隔離機能も実行をブロックすることがあります。失敗する場合は、flatpak override --user --filesystem=host <app-id> を実行してから再試行してください。

インストール

前提条件

• Node.js ≥ 20.19（23.x で開発）
• pnpm
• snap 経由でインストールされていない Chromium 系ブラウザー（上記を参照）
• MCP 対応クライアント（例：Claude Code）

1. ホストと拡張機能をビルドする

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. MCP クライアントにホストを追加する

Claude Code の場合は、.mcp.json（プロジェクト単位）または ~/.claude/mcp.json（グローバル）に追加します。

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

サーバーを認識させるため、Claude Code を再起動してください。

3. 拡張機能を読み込む

1. ブラウザーで chrome://extensions（または brave://extensions など）を開きます。
2. Developer mode をオンにします。
3. Load unpacked をクリックし、packages/extension/dist/ を選択します。
4. 拡張機能の ID を確認します（カードに表示されています）。次の手順で Claude に調べてもらうこともできます。拡張機能のサービスワーカーは、起動するたびに [pwa-debug/sw] id=<id> をログに出力します。

4. Claude にセットアップを指示する

ホストの登録は AI によって行われます。セットアップ用に 6 つの MCP ツールが公開されており、Claude はガイド付きの手順に沿って呼び出します。

pwa-debug をセットアップしてください。拡張機能の ID は <your-id> です。 (ID を省略すると、chrome-devtools-mcp もインストールされている場合、Claude が SW のコンソールから取得できます。)

Claude は次の操作を行います。

1. host_status を呼び出して、すでに登録されているものを確認します。
2. host_register_extension(id) を呼び出します。これにより、検出されたすべてのインストール先（Chromium 系のネイティブインストール、macOS の Application Support、Windows の HKCU レジストリ）に、ブラウザーごとのネイティブメッセージングマニフェストを書き込みます。また、絶対パスの Node を指定したランチャースクリプトも配置します（サンドボックス化された PATH 環境でもホストを起動できるようにするためです）。
3. chrome://extensions で拡張機能を再読み込みするよう案内します。
4. 再読み込み後、再び host_status を呼び出し、マニフェストがディスク上に存在し、SW が接続していることを確認します。

往復通信が成功すると、SW のコンソール（拡張機能カードの Inspect views: service worker）に次のように表示されます。

[pwa-debug/sw] connected to host
[pwa-debug/sw] pong …
[pwa-debug/sw] hello …          (5s after connect — host-pushed message proving bidirectional flow)

ブラウザーの起動と chrome-devtools-mcp との共存

pwa-debug と chrome-devtools-mcp は、1 つのブラウザーを共有する 別々の 2 つの MCP サーバーです。pwa-debug はリモートデバッグポートを有効にした Chromium ブラウザーを起動（または接続）し、chrome-devtools-mcp は CDP 経由で同じポートに接続します。プロキシは不要で、バージョンの連動もありません。

両方をクライアントに登録してください。Claude Code の場合：

# pwa-debug (this project) — adjust the path to your checkout
claude mcp add pwa-debug --scope user -- node /absolute/path/to/pwa-debug-layer/packages/host/dist/main.js

# chrome-devtools-mcp (optional but recommended) — runs via npx, no global install
# The --browserUrl port MUST match the port pwa-debug launches on (launch.defaultPort, default 9222).
claude mcp add chrome-devtools --scope user -- npx -y chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222

または、pwa-debug を Claude Code プラグインとしてインストールする

このリポジトリには .claude-plugin/ マニフェストが含まれており、その MCP サーバーは 公開済みの npm パッケージ（npx -y @aryanduntley/pwa-debug@latest）を実行します。そのため、プラグインのインストール時に クローンもビルドも不要で、完全な再起動なしに /reload-plugins で更新を適用できます。

# Add the marketplace straight from GitHub (no checkout needed)
/plugin marketplace add aryanduntley/pwa-debug-layer
# Install + enable the pwa-debug plugin
/plugin install pwa-debug@pwa-debug
# Bring the MCP server up with no restart:
/reload-plugins

ビルドは不要です。 プラグインの MCP エントリは npx -y @aryanduntley/pwa-debug@latest です。npm からビルド済みホスト（および同梱の拡張機能）を取得します。ローカルのクローンを使って作業していますか？ プラグインを使わず、独自のビルドを直接登録してください：claude mcp add pwa-debug --scope user -- node /absolute/path/to/pwa-debug-layer/packages/host/dist/main.js。

chrome-devtools-mcp は引き続き別個です。 プラグインが宣言するのは pwa-debug ホストのみです。chrome-devtools-mcp は、上記の省略可能な claude mcp add chrome-devtools … のままです（バージョンの連動はなく、起動も管理しません）。同梱の chrome-devtools-coexistence スキルで登録手順を確認できます。プラグインをインストールした場合、「ツールを表示する」手順は /reload-plugins です。

ポートを一致させる必要があります。 chrome-devtools-mcp の --browserUrl は、pwa-debug が開くポート、つまり launch.defaultPort の設定値（デフォルトは 9222）、または現在の pdl_launch_browser が使用中のポートを指定する必要があります。手動で記述する代わりに、Claude に pdl_register_chrome_devtools を呼び出させてください。適切なポートを固定して、上記の claude mcp add を実行します（また、pdl_check_setup は、ポートが 固定されていない 登録、つまり --browserUrl がなく独立したブラウザーを起動する登録や、誤ったポートを指定した登録を検出します）。

再接続を忘れないでください。 claude mcp add で追加または変更した登録は、サーバーが再接続したときにのみ有効になります。最も手早い方法は、/mcp を開いて chrome-devtools を再接続することです。これにより、現在の登録から再読み込みされます（変更した --browserUrl が反映されることを確認済みです）。完全な再起動もコンテキストの消失も必要ありません。その方法でクライアントが読み込めない場合は、代わりに Claude Code を完全に再起動してください。chrome-devtools-mcp をプラグインとしてインストールした場合は、/reload-plugins を実行します。同梱の chrome-devtools-coexistence スキルでは、すべての方法を Claude に案内させることができます。また、完全な再起動が必要な場合は、後で貼り戻せるコンテキストメモを用意します。

ホストには install／serve サブコマンドはありません。dist/main.js が実行モードを自動判定します。Chrome によって起動された場合（argv が chrome-extension:// で始まる場合）はネイティブメッセージングホストとして実行され、MCP クライアントによって起動された場合は MCP サーバーとして実行されます。

続いて、Claude にセットアップと起動を任せます：

1. pdl_check_setup — { ok, gaps[], recommendations[] } を報告します。chrome-devtools-mcp が（claude CLI から読み取った設定で）登録済みで、適切なデバッグポートを指す --browserUrl が固定されているかどうかを確認します。固定されていない登録（自分専用の隔離されたブラウザーを起動し、既存のブラウザーに接続しない状態）と、間違ったポートを指している登録の両方を検出します。また、ホストマニフェストがインストール済みか（アクティブなサンドボックスプロファイルごとに確認）、拡張機能の配布ファイルが存在するか、拡張機能 ID が登録済みかどうかも確認します。問題を解消するには、next_steps に従ってください。
2. pdl_register_chrome_devtools — アクティブポートまたは launch.defaultPort に固定した chrome-devtools-mcp の登録を代わりに書き込みます（冪等です。固定されていない場合や間違ったポートを指している場合は、登録先を変更します）。(MCP 設定を変更します — Claude が事前に確認します。その後、再起動または再接続が行われます。上記を参照してください。)
3. pdl_install_extension — 拡張機能を ~/Downloads/pwa-debug-extension（または指定した target）にコピーし、chrome://extensions で「Load unpacked」する手順を表示します。(ほとんどのブラウザーではサンドボックスモードで拡張機能が事前に読み込まれるため、この手順は省略できます。Google Chrome 142 以降のブランド版では事前読み込みができません。サンドボックスの起動時に案内される手動インストール方法です。)
4. pdl_launch_browser — デバッグポートを有効にしてブラウザーを起動または接続し、chrome-devtools-mcp に渡す browserUrl を返します。必ず最初に起動してください。 ブラウザーとデバッグポートが存在し、接続できるように、ほかの chrome-devtools-mcp ツールより先に呼び出してください。next_steps に従ってください。そこにはブランドやバージョンに応じた案内（事前読み込みと手動の Load unpacked、または最新の Chromium におけるポートの注意事項）が記載されています。
5. pdl_browser_status — 起動済みのブラウザー、プロファイルモード、ポート、PID を表示し、各デバッグポートの稼働状況を再確認するとともに、拡張機能のサービスワーカーのハートビートを報告します。

検証済みの単一プロファイル手順（各ツールが最終的に導く手順。Brave 148 で実機検証済み）：

pdl_launch_browser({ browser: "brave", mode: "sandbox-persistent" })
  → dedicated profile at ~/.pwa-debug/profiles/brave with:
      • the native-messaging manifest auto-written into the profile (so the extension connects), and
      • the pwa-debug extension preloaded via --load-extension (Brave honors it), and
      • --remote-debugging-port live (custom profile dir, so Chromium 136+ opens it).
pdl_register_chrome_devtools()  → pins chrome-devtools-mcp at that port
restart / reconnect chrome-devtools-mcp  → it attaches to the SAME browser

これで、chrome-devtools-mcp（CDP）と pwa-debug（拡張機能 → ページワールド）が、同じタブを同時に操作できます。それぞれ独立した、競合しないチャネルです（拡張機能はページワールドへのインジェクションを使用し、chrome.debugger は使用しないため、CDP アタッチャーとの競合はありません）。

プロファイルモード

pdl_launch_browser は mode（デフォルトは existing）、browser（デフォルトはシステム既定の Chromium ブラウザー）、port（デフォルトは 9222）を受け取ります。

モード	プロファイル	使用する場面
existing (デフォルト)	通常のブラウザープロファイル	pwa-debug を使って実際のブラウジングセッション（実際の Cookie、拡張機能、SW／キャッシュの状態）をデバッグする場合。状況に応じて適切に動作します。(a) デバッグポートがすでに起動中 → 接続します。(b) デバッグポートなしでブラウザーが起動中 → 既存のセッションで新しいウィンドウを開きます（拡張機能ツールは使えますが、chrome-devtools-mcp は使えません）。(c) ブラウザーが起動していない → プロファイルを使って新たに起動します。最新 Chromium の注意点（136 以降）： Chromium はデフォルトプロファイルでの --remote-debugging-port を拒否します。そのため、最新のブラウザーでは existing モードで pwa-debug は使えますが、CDP ポートは使えません。起動時にこの状態が通知され（attached:false、誤った browserUrl は表示されません）、chrome-devtools-mcp を使う場合は sandbox-persistent が案内されます。
sandbox-persistent	~/.pwa-debug/profiles/<browser>/（再起動後も保持）	両方のツールに対応する標準プロファイルです。メインのブラウザーとは別に専用プロファイルを用意し、独自の --user-data-dir を使うため、Chromium 136 以降でもデバッグポートが機能します。ランチャーはプロファイルにネイティブメッセージングマニフェストを自動で書き込み、ほとんどのブラウザーでは --load-extension を使って pwa-debug 拡張機能を事前に読み込みます。Google Chrome 142 以降の注意点： Chrome では --load-extension が削除されているため、デバッグポート（chrome-devtools-mcp 用）は起動しますが、拡張機能は読み込まれません。初回のみ手動で Load unpacked する手順が表示されます（このプロファイルに保持されます）。または、事前読み込みがそのまま機能する Google 製ではない Chromium を使うよう案内されます。
sandbox-temp	新しい mktemp ディレクトリ（ホストのシャットダウン時に削除）	使い切りの実行、CI、クリーンな状態での実行に使います。sandbox-persistent と同じですが、一時的なプロファイルです。そのため、Chrome 142 以降で必要となる手動読み込みは実用上保持されません。拡張機能が必要な一時実行には、Google 製ではない Chromium をおすすめします。

拡張機能の事前読み込みはブラウザーのブランドとバージョンによって異なります（ランチャーは --version から判定し、適切に対応します）。

ブラウザー	--load-extension（サンドボックスでの事前読み込み）
Brave、Chromium、Edge、Opera、Vivaldi、Chrome for Testing	✅ 現行バージョンで動作します
Google Chrome ≤ 136	✅ 動作します
Google Chrome 137–141	✅ 動作します — ランチャーが --disable-features=DisableLoadExtensionCommandLineSwitch を追加します
Google Chrome ≥ 142	❌ 削除済み — ランチャーは機能しないフラグを省略し、初回のみ手動で Load unpacked する手順を案内します（または Brave／Chromium を使用してください）

推奨する併用構成： Google 製ではない Chromium（例：Brave または Chromium）で sandbox-persistent を使用します。この単一のプロファイルには拡張機能が事前に読み込まれ、デバッグポートも起動するため、手動の手順なしで pwa-debug と chrome-devtools-mcp が同じブラウザーを操作できます。

ブラウザーのサポート状況

Chromium 系のみ対応しています（Firefox は CDP を使用しません）。Linux は正式にサポートされています。macOS／Windows のバイナリ検出、プロファイル／user-data-dir のパス、および システム既定ブラウザーの検出（macOS の LaunchServices、Windows の UserChoice レジストリ）はすべて実装済みで、単体テストでもカバーされていますが、実機の macOS／Windows での動作確認はまだ必要です。協力のお願いをご覧ください。

ブラウザー	PATH で検出する名前	Linux の標準バイナリ	Linux のプロファイルディレクトリ（existing モード）
Chrome	google-chrome、google-chrome-stable	/opt/google/chrome/chrome、/usr/bin/google-chrome*	~/.config/google-chrome
Chromium	chromium、chromium-browser	/usr/bin/chromium*、/snap/bin/chromium	~/.config/chromium
Edge	microsoft-edge、microsoft-edge-stable	/opt/microsoft/msedge/msedge	~/.config/microsoft-edge
Brave	brave-browser、brave	/opt/brave.com/brave/brave-browser	~/.config/BraveSoftware/Brave-Browser
Vivaldi	vivaldi、vivaldi-stable	/opt/vivaldi/vivaldi	~/.config/vivaldi
Opera	opera	/usr/bin/opera、/opt/opera/opera	~/.config/opera

• システム既定ブラウザー： ブラウザーを指定しない場合、ランチャーはシステムの既定ブラウザーを優先します。Linux では xdg-settings get default-web-browser、macOS では LaunchServices（defaults read … LSHandlers）、Windows では HKCU の UrlAssociations\http\UserChoice ProgId を使用します。macOS／Windows 用の処理は実装済みで単体テストも完了していますが、実機ではまだ検証されていません。
• 既定のデバッグポートは 9222（chrome-devtools-mcp の慣例）です。毎回 port を渡さずに変更するには、launch.defaultPort 設定（settings.set）を使用してください。
• Snap のプロファイル： existing モードで Snap パッケージのブラウザー（/snap/bin/…）を起動すると、ランチャーは ~/.config ではなく、隔離されたプロファイル（~/snap/<snap>/common/<cfg>）を解決します。ただし、Snap ブラウザーではネイティブメッセージングホストを実行できないため（Snap の項を参照）、この動作が関係するのは、その隔離制限が解除された場合に限られます。
• Brave Shields は、サイト上でコンテンツスクリプトをブロックすることがあります。session_ping が page_blocks_scripts を報告する場合は、そのサイトで Shields を Down に設定してください。
• Snap ブラウザーはネイティブメッセージングホストに対応していません（下記参照）。ランチャーから起動することはできますが、ホストとの往復通信は接続されません。ネイティブパッケージ版のブラウザーを使用してください。
• Flatpak でインストールするとマニフェストは書き込まれますが、隔離環境によって実行がブロックされる場合があります。flatpak override --user --filesystem=host <app-id> を実行してから、再試行してください。

ご協力ください：macOS／Windows での検証

開発は Linux で行っているため、macOS と Windows のコードパスはフェイクを注入して作成・単体テストしていますが、実機では一度も実行していません。 macOS または Windows をお使いの方は、以下を試して結果を報告していただけると、現時点で最も役立つ貢献になります（出力を添えて issue を作成してください）。

macOS

• pdl_check_setup / pdl_install_extension — 拡張機能が解決されてコピーされるか、また chrome://extensions の手順が機能するか。
• /Applications/*.app/Contents/MacOS/… 配下でのブラウザーバイナリーの検出。
• システム既定の検出：defaults read com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers — パーサーが適切なブラウザーを選択するか（選択されない場合は、生の出力を貼り付けてください）。
• pdl_launch_browser のモード existing（~/Library/Application Support/… 配下のプロファイル）と、2 つのサンドボックスモード。

Windows

• %PROGRAMFILES% / %LOCALAPPDATA% 配下でのブラウザーの検出。
• システム既定の検出：reg query "HKCU\Software\Microsoft\Windows\Shell\Associations\UrlAssociations\http\UserChoice" /v ProgId — ProgId が適切なブラウザーに対応するか。
• pdl_launch_browser（%LOCALAPPDATA%\…\User Data 配下のプロファイル）と、HKCU のネイティブメッセージング登録。

すべての OS

• ホスト再起動後の pdl_browser_status — 起動情報は launches.json に保存されるようになったため、以前に起動したブラウザーも引き続き一覧に表示されるはずです（生存状態を改めて確認します）。一覧が再起動後も維持されること、閉じたブラウザーが稼働していないと表示されることをご確認ください。

ランチャーが実行中のブラウザーを終了させることはなく、サンドボックスモードでは一時的な専用プロファイルを使うため、リスクを抑えて試せます。

トラブルシューティング

検証手順

問題が発生した場合は、次の手順を順に確認してください。各手順で問題箇所を絞り込めます。

1. pdl_check_setup — セットアップの未完了項目はすべて解消されていますか？（CDP に到達できる、マニフェストがインストール済み、拡張機能が存在する、ID が登録済み。）
2. pdl_browser_status — ブラウザーは起動していますか？ デバッグポートは引き続き稼働していますか？ 拡張機能のサービスワーカーは接続されていますか（最近のハートビートがある）？
3. host_status — ネイティブメッセージングホストは登録されていますか？ NMH インスタンスは接続されていますか？
4. session_ping — アクティブなタブで、MCP → SW → ページワールドの往復通信は正常に完了しますか？（以下の型付き pageWorldError テーブルを参照してください。）

共通の起動時の注意点

• 「existing モードで起動しましたが、chrome-devtools-mcp が接続できません。」 原因は2つあります。(1) Chrome が --remote-debugging-port を開くのはプロセスの起動時だけです。ブラウザーがすでにポートなしで起動していた場合、pdl_launch_browser は新しいウィンドウを開きます（サブ状態 b）が、実行中のプロセスにポートを追加できません（attached:false）。(2) Chromium 136+ では、新規起動でもデフォルトプロファイルでポートが拒否されます。いずれの場合も、chrome-devtools-mcp には mode: sandbox-persistent（ポートが使用できる専用プロファイル）を使ってください。
• Brave／Chrome に「既存のブラウザーセッションで開いています。」と表示されます。 これはサブ状態 b です。バイナリはポート付きで新たに起動する代わりに、リクエストをすでに実行中のプロセスに渡しました。上記と同じ方法で解決してください。
• サンドボックスは起動しましたが、pwa-debug が接続できません（Google Chrome 142+）。 ブランド版の Google Chrome 142+ は --load-extension を恒久的に無視するため、サンドボックスは拡張機能を自動で事前読み込みできません。起動時にその旨が表示され、chrome://extensions → デベロッパーモード → 展開して読み込み の手順が一度だけ案内されます（専用プロファイルに保存されます）。または、browser: "brave"／"chromium" で再起動してください。これらでは事前読み込みが自動で機能します。どちらの場合も、chrome-devtools-mcp は引き続き動作します（デバッグポートは有効です）。
• chrome-devtools-mcp が自分の空のブラウザーを開き、使用中のブラウザーを使いません。 登録が固定されていません（--browserUrl が指定されていません）。pdl_register_chrome_devtools を実行する（または --browserUrl http://127.0.0.1:<port> を指定して再追加する）とともに、再起動／再接続してください。pdl_check_setup でこの問題が検出されます。
• MCP サーバーを追加しましたが、ツールが表示されません。 .mcp.json／クライアントの MCP 設定は起動時に読み込まれます。pwa-debug または chrome-devtools を追加した後、MCP クライアントを再起動するか、そのサーバーに /mcp で再接続してください。
• ツールは動作していましたが、拡張機能を再読み込みした後に動かなくなりました。 chrome://extensions で拡張機能を再読み込みすると、すでに開いているタブからコンテンツスクリプトが切り離されます。ページタブをハード再読み込みしてください（Ctrl+Shift+R）。また、次の session_ping 時に SW が自動で再挿入します（pageWorldSelfHealed: true を確認してください）。サンドボックスモードでは、タブを開く前に拡張機能が読み込まれるため、この問題は発生しません。

session_ping が pageWorld: null と型付きの pageWorldError を返す場合

session_ping は、pageWorldError に失敗モードを型付きコード（機械可読）で示し、ログ用に元の Chrome ランタイム文字列を pageWorldErrorMessage に格納します。MCP の next_steps[] フィールドには、コードに応じた命令形のガイダンスが含まれます。AI クライアントは、これをそのまま伝えてください。拡張機能の再読み込みより前から開かれていたタブ（開発ループで最もよくある摩擦要因）は、SW が chrome.scripting.executeScript を使用して自動的に復旧します。復旧に成功すると、pageWorld が設定され、それとともに pageWorldSelfHealed: true が表示されます。以下の表は正式な対応表です（唯一の情報源：packages/host/src/mcp/tools/session_ping.ts の NEXT_STEPS_BY_CODE）。

pageWorldError	意味	対処方法
pageWorldSelfHealed: true で (欠落)	アクティブなタブに静的コンテンツスクリプトがありませんでした。SW が content-script.js と page-world.js を通知なく再注入し、再試行しました。対処は不要です。	情報のみです。
cs_not_attached_refresh_tab	自動復旧を試みましたが、定着しませんでした（ページが注入を拒否したか、処理中に再読み込みされました）。	ページのタブをハード再読み込み（Ctrl+Shift+R）して再試行してください。繰り返し発生する場合は、chrome://extensions で拡張機能を再読み込みしてから、ハード再読み込みしてください。
page_blocks_scripts	コンテンツブロッカーがスクリプトを拒否しています（Brave Shields、uBlock Origin、AdGuard など）。サイトの CSP が原因の可能性もあります。	**Brave：**ライオンのアイコンをクリック → サイトの Shields を Down に設定 → 更新 → 再試行してください。**uBlock Origin など：**このサイトで無効にする → 更新 → 再試行してください。どちらでもない場合は、サイト独自の CSP がブロックしており、pwa-debug では回避できません。
page_world_blocked	コンテンツスクリプトは接続しましたが、MAIN ワールドの page-world ブリッジに到達できません。サイトの Content-Security-Policy がインラインスクリプトタグをブロックしています。	サイトレベルの制限のため、回避できません。コンテンツスクリプト側を通じてコンソールとネットワークのキャプチャは引き続き利用できる場合がありますが、ライブの page-world 読み取り（state、evaluate）は利用できません。
restricted_url	アクティブなタブが、ブラウザーによって拡張機能からのアクセスを許可されていない URL（chrome://、chromewebstore.google.com、about:、devtools://、file://、view-source: など）を表示しています。	PWA の通常の http(s) タブにフォーカスを切り替えてから、再試行してください。
no_active_tab	アクティブな http(s) タブにフォーカスがありません（DevTools ウィンドウや拡張機能のポップアップにフォーカスしている可能性があります）。	通常のブラウザータブにフォーカスしてから、再試行してください。
cs_inject_failed	自動復旧の chrome.scripting.executeScript 自体が失敗しました。拡張機能はこのタブにアクセスできません。	chrome://extensions で拡張機能を再読み込みし、ページをハード再読み込み（Ctrl+Shift+R）してください。解決しない場合、その URL はブラウザーがすべての拡張機能をブロックする対象である可能性があります。アドレスバーを確認してください。

ラウンドトリップの成功後にコンテンツスクリプトが接続されたことを確認するには、ページタブの DevTools（SW コンソールではなく、ページ自体で F12）を開き、コンソールに [pwa-debug/cs] attached at <url> が表示されていることを確認してください。

MCP ツールのインターフェース

すべてのツールは、{ ok, data, error?, next_steps[] } 形式の構造化レスポンスを返します。next_steps 配列には、実際のレスポンスの形式に応じて次に呼び出すものを示す、AI が従うべきルールが記述されています。これは AIMFP の return_statements パターンに対応しています。正式な一覧は packages/host/src/mcp/tools/index.ts にあります。

ホスト管理とセットアップ

ツール	目的
host_status	インストール／稼働状態：登録済み ID、マニフェストのパス、ランチャーのパス、アクティブな接続。低コストで冪等です。必ず最初に呼び出してください。
host_register_extension(id) / host_unregister_extension(id)	ブラウザーごとのマニフェストとランチャースクリプトに対して、拡張機能 ID を追加／削除します。冪等です。
host_list_registrations / host_reset	登録済み ID を読み取ります。再ブートストラップのためにクリーンアップを実行します（破壊的操作）。
session_ping	型付きの pageWorldError コードと自己修復を備えた、MCP → IPC → NMH → SW → ページワールド間の完全な往復確認です。
pdl_check_setup	セットアップを診断し、{ ok, gaps[], recommendations[] } を返します（CDP への接続可否、マニフェストのインストール状況、拡張機能の有無、ID の登録状況）。
pdl_install_extension({ target? })	解凍インストール用のフォルダーに拡張機能をコピーします。

ブラウザーランチャー

ツール	目的
pdl_launch_browser({ browser?, port?, mode? })	ライブデバッグポートを持つ Chromium ブラウザーを起動／接続します。mode：existing（デフォルト）、sandbox-persistent、sandbox-temp。chrome-devtools-mcp 用の browserUrl を返します。
pdl_browser_status	管理対象の起動情報（ブラウザー、プロファイルモード、ポート、pid）を、デバッグポートのライブ再確認と拡張機能 SW のハートビートとともに表示します。

キャプチャ、評価、再生

ツール	目的
console_tail / network_tail / error_tail	永続キャプチャのリングバッファー（メモリーとディスクへのスピル）を、カーソルによるページネーションとフィルターで取得します。
recent_events	簡単な確認用に、種類をまたいだ最近のキャプチャイベントを取得します。
evaluate	ページワールドで式を評価します。
session_record / session_replay	rrweb セッションの記録と、カーソルによるページネーション対応の再生です。
source_map_resolve	生成されたスタックフレームを元の src/…:line:col に解決します。
settings_list_schema / settings_get / settings_set	型付き設定スキーマの読み取りと、値の取得／設定を行います（許可リスト、キャプチャフィルター、ディスクへのスピルなど）。

PWA ランタイム診断

名前の由来となったこのツール群では、デバッグ対象の PWA のサービスワーカー、キャッシュ、インストール可否、ストレージ、更新状態を読み取ります。ページワールドからの読み取りはすべて実際のプロファイルに対して行われます。CDP／chrome-devtools-mcp ではこれらの情報を取得できません。

ツール	目的
sw_status	サービスワーカーの登録情報：インストール中／待機中／アクティブなバージョン、updateViaCache、コントローラー、および更新が待機中のままになっているかどうか（「更新が表示されないのはなぜ？」という問題の第 1 位）。
sw_lifecycle_tail	SW ライフサイクルイベント（updatefound / statechange / controllerchange）のストリームを、カーソルによるページネーションで取得します。
cache_list / cache_inspect / cache_match	CacheStorage のキャッシュと各エントリーの { url, status, content-type, size, ageSeconds, cache-control }、および指定 URL をどのキャッシュが提供しているかを表示します。古いキャッシュのデバッグの中核となる情報です。
pwa_status	表示モード／スタンドアロン、コントローラー、権限、ライブの機能マトリックス（Push / Background Sync / Periodic Sync / Badging / File System Access / Window Controls Overlay）を表示します。
pwa_installability	マニフェストを検出して解析し、インストール可否を確認します。各不足項目への対処法を含む構造化データ { supported, gaps[], fixes[] } を返します。
storage_get	localStorage / sessionStorage のスナップショットを取得します（上限あり）。
idb_list / idb_query	IndexedDB データベースとオブジェクトストアのスキーマを取得し、続いてレコードの一部を読み取り専用で取得します（上限あり）。IndexedDB のライブデータを確認できます。
pwa_update_analyze	SW の状態、キャッシュの経過時間、最近の 404 を関連付けて、判定結果を返します：アクティブなクライアント上で更新が待機中、キャッシュされた HTML と JS のバージョン不一致、チャンクの 404 など。一部のユーザーが古いコードを使っているのはなぜか？
pwa_snapshot	再現性のあるバグ再現／引き継ぎ用に、ランタイム状態をまとめた上限付きの単一データ（SW + ストア + Web ストレージ + IndexedDB + キャッシュ名）を取得します。

フレームワークのイントロスペクション

各フレームワーク独自のモデルを介して読み取ります。CDP では見えない情報を取得できます。フレームワークが状態を保持している場合はツリー／状態を取得し、どこでも要素レベルで検索できます。

ツールファミリー	目的
react_tree / react_get_state / react_find_by_text / react_find_by_role	React のファイバーツリーをイントロスペクションし、安定 ID による props／状態／フックの取得と、コンポーネント検索を行います。
vue_tree / vue_get_state / vue_find_by_text / vue_find_by_role	Vue 3 の ComponentInternalInstance ツリー、リアクティブな状態、検索機能を提供します（React と同等の機能です）。
svelte_components / svelte_find_by_text / svelte_find_by_role	Svelte コンポーネントの検出、__svelte_meta のソース位置情報、要素検索を行います（Svelte はインスタンスの状態を公開しないため、状態は取得できません）。
solid_detect / solid_find_by_text / solid_find_by_role	Solid の検出と要素レベルの検索を行います（@solid-devtools がない場合、保持されたツリー／状態は取得できません）。

ストアのイントロスペクション

ツールファミリー	目的
redux_get_state / redux_subscribe / redux_tail / redux_dispatch	Redux の読み取り、変更差分のサブスクライブ／末尾取得、JSONPath-lite によるスライス取得、（オプトインでの）ディスパッチを行います。
store_get_state / store_subscribe / store_tail / store_dispatch	1 つの契約（名前による読み取り／サブスクライブ／ディスパッチ）を通じて Zustand / Pinia / Jotai に対応する、フレームワークに依存しないアダプターです。

インタラクションとタッチジェスチャー

React／Vue などの委譲型合成イベントシステムが発火するよう、フレームワークに依存しないネイティブイベントシーケンスをディスパッチします。各ツールは統一ロケーター（セレクター／ロール／テキスト／フレームワークの安定 ID）を対象にします。

ツール	目的
pdl_click / pdl_dblclick / pdl_hover	ポインター操作です。
pdl_fill / pdl_submit / pdl_select_option / pdl_uncheck	フォーム操作です。
pdl_focus / pdl_blur / pdl_key_press / pdl_type_sequence	フォーカスとキーボード操作です。
pdl_drag / pdl_scroll / pdl_swipe / pdl_tap / pdl_double_tap / pdl_long_press / pdl_pinch	タッチ／ジェスチャー操作の基本機能です（方向／距離／時間／ステップのモデルを使用し、座標を手作業で組み立てる必要はありません）。

ライブラリのポップアップ

ツール	目的
popup_tail	ライブラリのポップアップイベントストリームを末尾まで取得します（WalletConnect / RainbowKit / SDK のモーダルを含み、シャドウルートとネストにも対応します）。
popup_record / popup_replay	意図に基づいてポップアップのプライマリおよびネストされたストリーム全体を記録します（リングバッファからの削除の影響を受けません）。フラット／プライマリ／ツリー形式で再生できます。
popup_failures	ポップアップが開いている間に発生したコンソールエラーと失敗したリクエストを照合し、ポップアップの認証／接続失敗を特定します。

ロードマップ

• 基盤 ✅ — pnpm ワークスペースとビルドパイプライン。MV3 拡張機能が問題なく読み込まれること、ネイティブメッセージングのラウンドトリップ、AI によるホスト登録、クロスプラットフォームインストール（Linux ネイティブ＋macOS＋Windows レジストリ。snap は未対応）、MCP↔IPC↔NMH↔SW ブリッジ。
• キャプチャ ✅ — コンソール／ネットワーク（fetch/XHR/WebSocket）／DOM 変更／ライフサイクルのプロデューサー。ディスクへの退避とアーカイブの整理に対応したホストリングバッファー。フィルター可能でカーソルページネーション対応の console_tail／network_tail。
• フレームワークのイントロスペクション ✅ — React、Vue、Svelte、Solid（フレームワークが状態を保持する場合はツリー／状態を取得し、あらゆる箇所でテキスト／ロールによる検索が可能）。ページワールドでの evaluate。
• ストアのイントロスペクション ✅ — Redux（読み取り／サブスクライブ／末尾取得／ディスパッチ）に加え、Zustand、Pinia、Jotai を網羅するフレームワーク非依存のアダプター。
• 操作とジェスチャー ✅ — 統一ロケーターを使った個別操作（クリック／入力／送信／ホバー／フォーカス／フォーカス解除／選択／キー入力／タイピング）とタッチジェスチャー（ドラッグ／スクロール／スワイプ／タップ／ダブルタップ／長押し／ピンチ）。
• ライブラリーのポップアップ ✅ — WalletConnect と SDK のモーダル（シャドウルートとネスト構造を含む）向けの popup_record／popup_replay／popup_tail／popup_failures。
• リプレイとソースマップ ✅ — rrweb の session_record／session_replay。スタックフレーム向けの source_map_resolve。
• 設定 ✅ — 型付きスキーマストア（許可リスト／ブロックリスト、種類ごとのキャプチャフィルター、サイトごとの読み取り制御、ディスクへの退避）。
• ブラウザーランチャー ✅ — pdl_launch_browser（既存＋サンドボックス永続＋サンドボックス一時）、pdl_check_setup、pdl_browser_status、pdl_close_browser、pdl_install_extension、pdl_register_chrome_devtools、および chrome-devtools-mcp との共存。
• PWA ランタイム診断 ✅ — 名を冠した機能一式を実際の PWA で実機検証済み。サービスワーカーのイントロスペクション（sw_status＋sw_lifecycle_tail：インストール中／待機中／アクティブなバージョン、updateViaCache、skipWaiting／claim／controllerchange）。CacheStorage の検査（cache_list／cache_inspect／cache_match：サイズ／経過時間、URL による照合）。pwa_status（表示モード、コントローラー、権限、Push／Background Sync／Periodic Sync／Badging／File System Access／Window Controls Overlay のライブ機能マトリックス）。インストール可能性の診断（pwa_installability → 構造化された {gaps[], fixes[]}）。IndexedDB／Web Storage の検査（idb_list／idb_query／storage_get）。更新の伝播／バージョン不整合の分析（pwa_update_analyze）。ワンショットのランタイム状態スナップショット（pwa_snapshot）。実際のプロファイルで、古いキャッシュ／「SW が更新されない」／インストール失敗／バージョン不整合という一連の問題を解消します。
• 今後 — AI セッションを人間が観察するための DevTools パネル、複数タブのルーティングモデル、イベント因果関係グラフ（クリック → 操作 → リクエスト → SW → キャッシュ → 再レンダリング）、実ユーザーの障害を記録する本番環境向けの安全な診断モード。
• 延期 — Firefox への移植（CDP ではなく WebDriver BiDi が必要）、macOS／Windows での実機検証（協力者募集中）、モバイル、ホスト型／チームモード。
• 意図的に対象外 — Chrome ウェブストアでの配布。 この拡張機能は広範なページアクセス（DOM、フレームワークの状態、ストア、ネットワーク）を許可し、MCP ホストと併用して初めて意味を持ちます。MCP に同梱する形のみで提供し、手動の開発者モード「Load unpacked」（pdl_install_extension がパスと手順を提示）でインストールします。これにより、ユーザーは実行するものとその理由を正確に把握できます。Chrome のデベロッパーモードを無効にすると、この拡張機能も自動的に無効になります。

コードスタイル

• FP のみ：純粋関数、不変性、OOP なし、メソッドを持つクラスなし。
• 副作用（CDP 呼び出し、ファイル I/O、ネイティブメッセージング、MCP トランスポート）は境界に置き、コアロジックは純粋にします。
• OOP ライブラリーのインターフェイス（Chrome API、MCP SDK、winreg）は、テスト用の注入ポイントを備えた薄い関数型アダプターでラップします。

リポジトリの構成

pwa-debug-layer/
├── packages/
│   ├── host/                Native-messaging host + MCP server (Node, ESM, rollup-bundled)
│   ├── extension/           WebExtension (MV3) — service worker, content script, page-world
│   └── shared/              Cross-package types
├── docs/
│   ├── PLAN.md              Full design doc (architecture, capability matrix, phased plan)
│   └── goals.txt
├── examples/                (future: test PWAs)
└── reference/               Read-only reference checkouts

コントリビューション

これは現在も積極的に再設計を進めている個人プロジェクトです。PR は歓迎しますが、スコープについて話し合うため、まず issue を立ててください。アーキテクチャはまだ固まりきっていません。FP／OOP なしの方針はすべてのコントリビューションに適用されます。詳細なルールについては CLAUDE.md を参照してください。

License

MIT — see LICENSE.