> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# ローカルデバッグ

> ローカルネットワークで Chrome DevTools に接続し MCP エンドポイントにアクセスする

BRICKS Foundation は Chrome DevTools Protocol (CDP) を実装しており、アプリケーションに対してフロントエンドに近いデバッグ体験を提供します。Chrome DevTools を通じて接続することで、DOM の検査、JavaScript のデバッグ、パフォーマンスのプロファイリング、コンソールログの確認が可能です。Puppeteer や Playwright などの CDP 対応ツールを接続して自動化スクリプトを書いたり、AI エージェント経由で接続することもできます。AI エージェント連携用の MCP エンドポイントも提供されています。

## デバイスで DevTools を有効にする

<Steps>
  <Step title="詳細設定を開く">
    デバイスで**設定**を開き、詳細設定セクションに移動します。
  </Step>

  <Step title="Chrome DevTools を有効にする">
    **Chrome DevTools** をオンにします。デバイスはローカルネットワーク上のポート `19851` で DevTools サーバーを起動します。そのポートが使用中の場合、次の利用可能なポートに自動的に切り替わります。
  </Step>
</Steps>

## デバイスを検索する

[BRICKS CLI](/ja/cli) を使ってローカルネットワーク上の DevTools が有効なデバイスをスキャンします：

```bash theme={null}
bricks devtools scan
```

<Info>
  ネットワークスキャンが機能するには、デバイスの詳細設定で**LAN ディスカバリーを有効にする**がオンになっている必要があります。これはデフォルトで有効です。
</Info>

## DevTools エンドポイント

デバイスを見つけたら、`bricks devtools open` に `--info` フラグを付けてすべての利用可能なエンドポイントを確認します：

```bash theme={null}
bricks devtools open <device-address> --info
```

以下の接続 URL が表示されます：

| エンドポイント     | 説明                                                         |
| ----------- | ---------------------------------------------------------- |
| **Web UI**  | ブラウザでこの URL を開くと DevTools ランディングページにアクセスできます               |
| **CDP**     | 直接接続用の Chrome DevTools Protocol エンドポイント                    |
| **MCP**     | AI エージェント連携用の Model Context Protocol エンドポイント               |
| **MCP SSE** | Server-Sent Events トランスポートを使用する MCP エンドポイント                |
| **Info**    | デバイス、バージョン、プロトコルを記述する `/devtools/info` の JSON メタデータエンドポイント |

検出されたデバイスの passcode と、MCP および MCP SSE エンドポイントに必要な `Authorization: Bearer <passcode>` ヘッダーも併せて表示されます。

`--info` を付けない場合、コマンドはサーバー識別情報（名前、バージョン、デバイス ID、ワークスペース、プロトコル、認証状態）を表示します。

### DevTools ページを開く

**Web UI** URL をブラウザで開くと DevTools ランディングページにアクセスできます。そこから実行中のアプリケーションを検査したり、利用可能なデバッグターゲットを確認したり、デバイスに接続したりできます。

### Chrome で接続する

Chrome から直接接続することもできます：

1. [詳細設定](/ja/foundation/settings#chrome-devtools)で **Expose endpoints for chrome://inspect** を有効にする
2. Chrome で `chrome://inspect` を開く
3. デバイスがリモートターゲットの一覧に表示される
4. **inspect** をクリックして実行中のアプリケーションに接続した DevTools ウィンドウを開く

<Warning>
  **Expose endpoints for chrome://inspect** は認証なしで `/json` エンドポイントを公開するため Chrome から検出できるようになりますが、passcode が平文で露出します。信頼できるネットワーク上のデバッグでのみ有効にしてください。
</Warning>

### BRICKS CLI で検査する（CDP）

<Info>
  BRICKS Foundation バージョン **2.24** 以降が必要です。
</Info>

[BRICKS CLI](/ja/cli) は CDP コマンドを提供し、ブラウザを開かずにターミナルから直接デバイスを検査できます：

```bash theme={null}
# brick コンポーネントツリーを出力
bricks devtools brick tree -a <device-address>

# スクリーンショットを取得
bricks devtools screenshot -a <device-address> -o screenshot.png

# JavaScript 式を評価
bricks devtools runtime eval -a <device-address> "document.title"

# ネットワークアクティビティをモニタリング
bricks devtools network list -a <device-address>
```

デバイスが認証を必要とする場合は `--passcode` を使用します。CDP コマンドの全リストは [CLI コマンドリファレンス](/ja/cli/commands#devtools-cdp-コマンド) を参照してください。

## DevTools でできること

接続した DevTools ウィンドウはブラウザのように見えますが、BRICKS Foundation は Web ページではありません。各パネルは代わりにデバイスのライブランタイムを投影します。有効で意味のあるパネルは 4 つ — **Elements**、**Console**、**Network**、**Application** です。その他のパネル（Sources、Performance、Memory、要素検査ボタン）は、背後に Web ページが存在しないため非表示になっています。

### Elements — Brick ツリー

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/elements-light.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=4538b96005a06765d77add9cf23b599b" alt="DOM ドキュメントとして投影された BRICKS レンダーツリーを表示する DevTools Elements パネル" width="1600" height="827" data-path="images/foundation/elements-light.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/elements-dark.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=aa67aa7af66515329bb7989c96a3b29e" alt="DOM ドキュメントとして投影された BRICKS レンダーツリーを表示する DevTools Elements パネル" width="1600" height="833" data-path="images/foundation/elements-dark.webp" />
</Frame>

Elements パネルはアプリケーションの**レンダーツリー**を DOM ドキュメントとして投影します。ツリーは `#document` をルートとし、BRICKS で構築した構造を入れ子にします：

```text theme={null}
#document
└─ bricks-system
   └─ subspace          ← レンダリングされた Subspace ごとに 1 つ
      ├─ text           ← 現在の Canvas 上の Brick ごとに 1 要素
      ├─ image
      └─ subspace       ← ネストした Subspace
```

* 各 **Subspace** は `<subspace>` 要素です。現在表示されている Canvas はその中にマージされるため、その Bricks は直接子要素として現れ（独立した `<canvas>` ノードはありません）、`canvas-*` 属性（`canvas-id`、`canvas-title` など）がどの Canvas を表示しているかを示します。
* 各 **Brick** は 1 要素で、タグ名は `BRICK_` 接頭辞を除いた Brick の種類です（例：`<text>`、`<image>`、`<text_input>`、`<video>`、`<chart>`、`<items>`、`<webview>`、`<qrcode>`）。
* Brick の主要なコンテンツは要素のテキストとして表示されます。Text Brick は文字列を、Image Brick はソースパスを表示します（長い値は切り詰められます）。

各 Subspace は**現在レンダリングされている Canvas** のみを表示します。その Subspace の他の Canvas 上の Bricks はツリーに含まれません。**Generator** と **Data** は Elements には現れません。Generator のトラフィックは **Network** パネルで、保存された Data は **Application** パネルで確認してください。

Brick の属性からその識別情報とレイアウトを読み取れます：

| 属性                          | 意味                                                                                        |
| --------------------------- | ----------------------------------------------------------------------------------------- |
| `id` / `alias` / `short-id` | 識別子。Short ID は種類ごとに接頭辞が付きます：`B_` Brick、`S_` Subspace、`C_` Canvas、`D_` Data、`G_` Generator |
| `title`                     | エディター上の Brick のタイトル                                                                       |
| `pressable` / `editable`    | Brick がタップに反応する／テキスト入力を受け付けるか                                                             |
| `hide`                      | Brick が非表示かどうか                                                                            |
| `x` / `y` / `w` / `h`       | BRICKS の**グリッド単位**（ピクセルではない）での位置とサイズ                                                      |

Brick を選択すると、その属性がインラインで表示され、解決済みのランタイム状態がサイドパネルに表示されます。**Properties** タブには Brick の `props`、`events`、`outlet`、`templateKey` が、**Styles** と **Computed** には合成されたレイアウトが表示されます。ノードにカーソルを合わせる、または選択すると、デバイス上で**対応する Brick または Subspace がハイライト**され、`text — WelcomeHeader` のようなラベルが表示されます。

Elements の検索ボックスから BRICKS 固有のセレクターでツリーを検索できます：

* `#welcome-text` または `#B_3` — エイリアスまたは short ID で一致
* `:pressable`、`:editable`、`:hidden` — 機能または状態で一致
* `.MyStateGroup` — 状態グループに属する Brick に一致

<Note>
  Elements ツリーは**読み取り専用**です。属性の編集やノードの削除は実行中のアプリを変更せず、編集は元に戻ります。アプリを操作するには、Console の `system` ヘルパー（下記）または CDP 対応の自動化ツールを使用してください。
</Note>

### Console — ランタイムログと `system` ヘルパー

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/console-light.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=80ced98558809614177f0ba0543ea70a" alt="接続バナーと展開された system ヘルパーオブジェクトを表示する DevTools Console パネル" width="1600" height="226" data-path="images/foundation/console-light.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/console-dark.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=81f10d7da3cf917d64cc85e8d9e0eb0f" alt="接続バナーと展開された system ヘルパーオブジェクトを表示する DevTools Console パネル" width="1600" height="223" data-path="images/foundation/console-dark.webp" />
</Frame>

Console はデバイスの**ランタイム自身のログ**をストリーミングします。アプリケーションの出力、イベント発生時の `[System] Event:` 行、ネイティブモデル（LLM/STT）のログなどです。Web ページの `console.*` ではありません。接続時に最近の履歴が自動的に再生されます。

接続時、BRICKS は一連のヘルパーオブジェクトを Console の評価スコープに直接注入します。**名前で直接入力**してください — `globals` 接頭辞は不要です。まず `usage()` を実行して全カタログを表示するか、`globalThis` と入力してツリー全体を展開します。

| ヘルパー                                       | 機能                                                                                                                                                                          |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `info()` · `memoryUsage()` · `diskUsage()` | デバイスとアプリの情報、メモリ、ディスク使用量                                                                                                                                                     |
| `usage()`                                  | 利用可能なヘルパーのカタログを表示                                                                                                                                                           |
| `system.*`                                 | 実行中のアプリを検査・操作する（下記参照）                                                                                                                                                       |
| `control.*`                                | `refresh()`、`clearCache()`、`takeScreenshot()`、`checkUpdate()`、`rebindDevice('imsure')`、`externalScreen(enable)`                                                             |
| `panel.*`                                  | デバイス上のオーバーレイを開く — `panel.menu()`、`panel.info()`、`panel.apps()`、`panel.debug.root/data/log/cache/localSync()`、`panel.automation()`、`panel.advancedSetting()`、`panel.about()` |
| `automation.*`                             | E2E 自動化の `list()`、`run(testId, payload)`、`stop()`                                                                                                                           |
| `mcp.*`                                    | MCP server/client Generator のツール、リソース、プロンプトを呼び出す                                                                                                                            |
| `tv.focusRegistry()`                       | TV/リモコンのフォーカスレジストリを検査                                                                                                                                                       |

`system.*` がアプリ検査の中核です：

| 呼び出し                                                                | 戻り値／動作                             |
| ------------------------------------------------------------------- | ---------------------------------- |
| `system.isReady()`                                                  | ランタイムが準備完了かどうか                     |
| `system.subspaces()`                                                | Subspace ツリーのスナップショット              |
| `system.querySelector(sel)` · `querySelectorAll(sel)`               | **レンダリングされた** Brick ツリーを照会         |
| `system.query(sel)` · `queryAll(sel)`                               | **完全な**インスタンスツリーを照会                |
| `system.simulatePress(subspaceId, brickId)`                         | Brick をタップ                         |
| `system.simulateKeyDown(code, key, flags)` · `simulateKeyUp(...)`   | キー入力を送信                            |
| `system.executeAction(subspaceId, { handler, action, parameters })` | Brick、Data、または Generator のアクションを実行 |
| `system.data.storeList()`                                           | Data store を一覧表示                   |
| `system.data.properties(subspaceId, { filter, command })`           | Property Bank のプロパティを一覧表示          |
| `system.data.property(subspaceId, propertyId)`                      | 単一のプロパティ値を読み取る                     |
| `system.cache.generatorCache(subspaceId, generatorId)`              | Generator のキャッシュ出力を読み取る            |
| `system.cache.runtimeCacheStats(subspaceId)`                        | ランタイムキャッシュの統計                      |
| `system.channel.keys()` · `subscriptions(regex)`                    | channel（pub/sub）を検査                |
| `system.storage.persist.global.get(key)` · `allKeys()`              | 永続スコープストレージを読み取る（`memory` はメモリ内）   |
| `system.localSync.isEnabled()` · `isMain()` · `summary()`           | Local Sync の状態                     |
| `system.inspectEventRouting(id)` · `inspectParentCall(id)`          | イベントの配線を追跡                         |

```js theme={null}
usage()                                  // ヘルパーのカタログを表示
system.subspaces()
system.querySelectorAll(':pressable')    // レンダリングされたツリー内のすべての pressable な Brick
system.data.storeList()
system.data.properties('S_1', { command: false })
system.simulatePress('S_1', 'B_3')       // Subspace S_1 の Brick B_3 をタップ
control.takeScreenshot()                 // Console 内にインラインで表示
panel.debug.log(true)                    // デバイス上のログパネルを開く
```

<Tip>
  ID は Elements パネルと同じ接頭辞に従います — Subspace は `S_`、Brick は `B_`、Data／プロパティは `D_`、Generator は `G_`。非同期ヘルパーはインラインの戻り値ではなく `[Launcher] …` のログ行で報告します。機密情報（パスワード、token、API キー）は `[HIDDEN]` としてマスクされます。
</Tip>

### Network — リクエストトラフィック

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/network-light.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=b94a05d0dd0f70ad7eec1f729749bbc6" alt="キャプチャされた HTTP リクエストとヘッダーを表示する DevTools Network パネル" width="1600" height="723" data-path="images/foundation/network-light.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/network-dark.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=bba4afde4db8dd6c2389387e2358a234" alt="キャプチャされた HTTP リクエストとヘッダーを表示する DevTools Network パネル" width="1600" height="729" data-path="images/foundation/network-dark.webp" />
</Frame>

Network パネルは **Generator**、**Preload**（プリロード）プロセス、およびランタイムが行うリクエストを表示します。DevTools が有効な間は常にキャプチャされるため、パネルを開く前でもリクエストが現れます。各ソースの表現方法：

| トラフィック                              | 表示形式                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| HTTP／HTTPS（HTTP Generator、内部 fetch） | 標準的なリクエスト行（タイプ **Fetch**）— メソッド、URL、ステータス、ヘッダー、リクエストペイロード、レスポンスボディ             |
| ストリーミング／サーバー送信（HTTP・LLM Generator）  | 1 つの **EventSource** 行。**EventStream** タブを開いてイベントを確認                           |
| WebSocket（`ws` / `wss`）             | **WebSocket** 行。**Messages** タブを開いてフレームを確認                                     |
| MQTT（`mqtt` / `mqtts`）              | broker URL の WebSocket 形式の行。publish や受信メッセージはそれぞれ `[topic] payload` のフレームとして表示 |
| Data Bank ライブサブスクリプション、GraphQL      | クエリは HTTP 行、サブスクリプションは WebSocket 行                                             |
| **Preload**（アセット、フォント、Media Box）    | アプリがコンテンツをプリロードする際の `HEAD` サイズプローブと `GET`／`POST` ダウンロード                        |

例えば、`mqtt://broker.example.com:1883` を指す Generator は 1 行（ステータス `101 Connected`）を表示します。`{"temp":21}` を `sensors/room1` に publish すると、**Messages** に送信フレーム `[sensors/room1] {"temp":21}` として現れ、受信メッセージは受信フレームとして現れます。

<Warning>
  ネットワークトラフィックは**そのまま表示され、マスクされません** — `Authorization` ヘッダー、URL 内の API キー、リクエスト／レスポンスボディはすべて表示されます。DevTools へのアクセスは機密として扱い、デバイスの passcode は信頼できる人とのみ共有してください。
</Warning>

Subspace、Canvas、Brick、Property Bank の値には直接の Network 行はありません。リクエストを行う Generator や Preload ステップの発生源として間接的に現れるだけです。レスポンスボディは最近のリクエストのみキャッシュされ、DevTools 起動前に開かれた接続は現れません。

<Note>
  ランタイムキャッシュから提供されるレスポンスは、まだネットワークリクエストとしては表示されません。このパネルでランタイムキャッシュの動作を表示することは、将来のリリースで予定されています。
</Note>

### Application — 保存された Data（読み取り専用）

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/application-light.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=e49c06a591cb369454cef2309a6cc4d1" alt="IndexedDB に投影された BRICKS ストレージを表示する DevTools Application パネル" width="1600" height="612" data-path="images/foundation/application-light.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/application-dark.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=2c6217ed1c45d45d062e9d52525822de" alt="IndexedDB に投影された BRICKS ストレージを表示する DevTools Application パネル" width="1600" height="614" data-path="images/foundation/application-dark.webp" />
</Frame>

Application パネルはデバイスのランタイムストレージをブラウザのストレージバケットに投影します。すべて単一のオリジン `bricks://app` の下にあります：

| DevTools の場所                             | BRICKS のデータ                                                                             |
| ---------------------------------------- | --------------------------------------------------------------------------------------- |
| **Local Storage**                        | 永続スコープストレージ（再起動後も保持）、キーは `global:<key>` と `subspace:<id>:<key>`                         |
| **Session Storage**                      | メモリ内スコープストレージ（リセット時にクリア）                                                                |
| **IndexedDB → `GENERATOR_CACHE`**        | キャッシュされた Generator の出力                                                                  |
| **IndexedDB → `GENERATIVE_MEDIA_CACHE`** | キャッシュされた生成メディアの結果                                                                       |
| **IndexedDB → `DATA-<subspace>`**        | Subspace ごとの **Property Bank** の値（ストア `properties`）。`[persist]` を接頭辞とする行は永続化されたバッキングコピー |

<Note>
  `DATA-…` データベースが保持するのはランタイムの **Property Bank** であり、[BRICKS Controller](/ja/controller) の [Data Bank](/ja/controller/data-bank) ストレージ製品とは別物です。同様に、`GENERATIVE_MEDIA_CACHE` はランタイムキャッシュであり、Media Box や Media Flow ではありません。
</Note>

Application パネルは**読み取り専用**です。値は DevTools から編集できません。アプリ内で変更してください。オブジェクト値はアプリの実行に伴ってライブで更新され、機密情報は `[HIDDEN]` としてマスクされます。

## 次のステップ

<CardGroup cols={2}>
  <Card title="リモートデバッグ" icon="tower-broadcast" href="/ja/foundation/remote-debug">
    ローカルネットワークアクセスなしに BRICKS Controller 経由でデバイスをリモートデバッグします。
  </Card>

  <Card title="デバッグパネル" icon="bug" href="/ja/foundation/debug-panel">
    デバイス上のオーバーレイを使ってランタイム状態を検査します。
  </Card>
</CardGroup>