# Karaage Browser Extension 仕様・マニュアル

<img src="../media/karaage_logo_v2.png" width="150" alt="Karaage Browser Logo" style="margin-bottom: 20px;">

**作成日**: 2026年03月12日  
**パッケージバージョン**: 1.0.0  
**作者**: Yosuke Kobayashi

## 1. 概要 (Overview)
Karaage Browser Extensionは、VS Code上で動作する強力なHTML/CSSインスペクターおよびUI生成・連携ツールです。ローカルのWeb開発環境をそのままVS Code内のWebViewパネルで再生（プレビュー）し、DevToolsライクな要素検査とライブ編集を提供します。
さらに、**Google Stitch MCP (Model Context Protocol)** 連携による最新UIのAI生成、コード編集、バリエーション作成、チャット履歴管理を実現します。

**デモ動画**

<video src="./video01.mp4" controls width="720" style="max-width:100%;"></video>

**画面例（起動後・全体）**

![Karaage Browser 全体画面 — ブラウザプレビューと Stitch MCP タブ](01.png)

---

## 2. システムアーキテクチャ (System Architecture)

本ツールの全体像は以下の通りです。VS CodeのWebViewパネルを中心に、ローカルファイルシステムとStitch MCP（AI）が相互に連携します。

```mermaid
graph TD
    User([ユーザー]) --> |"コマンド実行 / UI操作"| VSC[VS Code Extension]
    
    subgraph Karaage Browser Extension
        VSC --> |"パネル生成"| Panel[KaraageBrowserPanel]
        Panel --> |"連携"| Proxy[ProxyServer]
        Panel --> |"連携"| MCP[McpIntegration]
        Panel --> |"連携"| Logger[ContextLogger]
    end

    Proxy -->|"複数のInspector用スクリプト注入"| LocalFS[(Workspace / Local Files)]
    Panel -->|"WebView表示 (Iframe)"| Proxy
    
    MCP <-->|"Stdio通信"| StitchServer((Stitch MCP Server))
    StitchServer -.->|"UIレイアウト等"| AI((Gemini / AI Models))
    
    Panel -->|"LLM連携 (コンテキスト送信/チャット表示)"| Antigravity[(Antigravity Chat)]
```

### アーキテクチャのポイント
- **ProxyServer**: 対象のHTMLファイルを配信する際、動的にDOM解析・操作用のスクリプト (`selectionController.js`, `historyAdapter.js`, `domPatchAdapter.js`, `bridge.js`) を分割して注入します。
- **McpIntegration**: 設定ファイル(`.gemini/antigravity/mcp_config.json`)からStitch MCPサーバーのパスを読み取り、プロジェクト・画面の取得、UI生成指示（Generate/Edit/Variants）を行います。
- **KaraageBrowserPanel**: プロキシサーバーのURLを表示するIframeと、操作用のDevTools（Elementsタブ / Stitch MCPタブ）を描画します。
- **ContextLogger**: 手動の編集ログだけでなく、VS Codeのファイル保存アクション（`onDidSaveTextDocument`）をフックし、自動的に差分（Diff）を記録します。

---

## 3. 主要コンポーネント詳細

### 3.1. ProxyServer (`src/ProxyServer.ts`)

ProxyServerは、`express` と `http-proxy-middleware` を活用して動作します。

```mermaid
sequenceDiagram
    participant Webview as WebView Iframe
    participant Proxy as "ProxyServer(Express)"
    participant FS as Local File System

    Webview->>Proxy: 1. GET /index.html リクエスト
    Proxy->>FS: 2. ファイル読み込み
    FS-->>Proxy: 3. HTML (元のソースコード)
    Note over Proxy: <body> タグの直前に<br>分割されたInspector機能群を注入
    Proxy-->>Webview: 4. インジェクション済みHTML
```

#### 特徴
- Workspace内のファイルを監視・提供 (`internalRoot`)。Workspace外のファイルは、セキュリティを考慮し表示制御（`/__open__/`）を行っています。
- HTMLレスポンスを検知し、`identity` 圧縮を使用させて安全に文字列置換を実施。
- `selectionController.js`, `historyAdapter.js`, `domPatchAdapter.js`, `bridge.js` の4つのコアモジュールを注入します。

### 3.2. KaraageBrowserPanel (`src/KaraageBrowserPanel.ts`)

UIパネルは、「左側のWebプレビュー」と「右側の操作パネル」の2ペイン構成です。

| タブ名称 | 主な機能・役割 |
| :--- | :--- |
| **Elementsタブ** | ・インスペクター機能（ページ上の要素をクリックして特定のDOMを取得）<br>・「Apply HTML」「Apply Inline Style」による動的書き換え<br>・「Delete Element」削除機能<br>・**Edit History（編集履歴）**: 過去の変更を一覧化し、リバート（元に戻す）操作が可能。<br>・「CopyClipBoard」: 対象要素のソースコード（HTML/CSS）をLLMの文脈（ContextLogger）として転送し、自動的にチャットを開始します。 |
| **Stitch MCP (Beta)タブ** | 3階層のドリルダウン構造を持っています。<br>1. **プロジェクト一覧**: 手持ちのStitchプロジェクト一覧表示、新規作成。<br>2. **画面(Screens)一覧**: プロジェクトに属する画面一覧。一括ダウンロード「Download All」や、新規画面生成(Generate Screen)が可能。「会話履歴(Conversation History)」へのアクセスとエクスポートに対応。オフラインキャッシュ機能によりダウンロード済の画面も統合表示されます。<br>3. **画面詳細**: 対象画面のブラウザ内プレビュー表示。HTMLの個別ダウンロード、および自然言語による「編集(Edit)」「バリエーション追加(Variants)」が可能です。 |

**Elements タブの例**

![Elements タブ — 要素選択・HTML/CSS 編集・Copy to Clipboard](02.png)

**Stitch MCP (Beta) タブの例**

![Stitch MCP タブ — プロジェクト一覧と画面生成](01.png)

### 3.3. Stitch MCP連携 (`src/McpIntegration.ts`)

Stitch MCPサーバーとの通信フローです。拡張機能がClientとして働き、SDKを通じてサーバーにリクエストを投げます。

```mermaid
stateDiagram-v2
    [*] --> Connect
    Connect --> CheckConfig: mcp_config.json読み込み
    CheckConfig --> InitializeClient: StdioClientTransport
    InitializeClient --> CallTool: ツール呼び出し
    
    state CallTool {
        list_projects
        create_project
        list_screens
        get_screen
        generate_screen_from_text
        edit_screens
        generate_variants
    }
    
    CallTool --> DownloadScreen: "Workspaceに保存 (オフラインキャッシュ連携)"
    DownloadScreen --> [*]
```

### 3.4. ContextLogger (`src/ContextLogger.ts`)

操作履歴やコンテキスト情報をマークダウン形式のログ（`karaage-session.log.md`）として作業ディレクトリに保存します。Antigravity LLMとの文脈（Context）共有に不可欠な役割を担います。

- **明示的なUI操作ログ**: Edit、Delete、Revert、LLMへのコンテキスト送信（CopyClipBoard）時のアクションを記録。
- **ファイル保存時差分（Auto-Diff）**: `vscode.workspace.onDidSaveTextDocument` をフックして、監視対象のファイル（HTML, CSS, JS等）が保存された際に、旧内容とのDiff（差分）を自動計算してログに追記します。

### 3.5. DOM Element Locator (`src/elements/HtmlLocator.ts` / `CssLocator.ts`)

プロキシサーバーから送られてくるブラウザ上の「Inspector（要素選択）」イベントを受け取り、ローカルのソースコード文字列の中から対応する **行番号（startLine, endLine）** を特定する重要な解析ロジックです。
- **HtmlLocator**: 対象の `domPath`、`tagName`、`id`、`classList` などの情報から、正規表現やタグの内包関係の深さを計算（`depth`管理）して対象要素の開始・終了タグの位置を見つけ出します。同一タグが複数ある場合やid・classが不足している場合は、独自のスコアリングパターンの合算（`scoreCandidate`）によって最も確からしい要素を特定します。
- **CssLocator**: インラインスタイルだけでなく、CSSファイル上の特定のセレクタ位置をソースコードから特定します。

### 3.6. Stitch Conversation Store (`src/StitchConversationStore.ts`)

Stitch MCPタブ周辺でのAIとのチャットや、生成・編集機能（Generate / Edit / Variants）のやり取りをプロジェクト単位で永続化し、会話履歴として管理するコンポーネントです。
- **Storageの利用**: VS Codeの `workspaceState`（`memento` API）を利用し、プロジェクト単位でインメモリの会話データを保存します。
- **履歴管理機能**: `user` と `ai` のロールごとの履歴をそれぞれ追記・保存（`appendUser`, `appendAi`）します。過剰なデータによる圧迫を防ぐため、プロジェクトごとに最大メッセージ件数の制限（最大50件）を行っています。Markdown形式での履歴出力（`exportAsMarkdown`）にも対応しています。

---

## 4. ディレクトリ・ファイル構成

| ディレクトリ / ファイル | 役割 |
| :--- | :--- |
| `package.json` | 拡張機能のメタデータ、コマンド、バージョン(`1.0.0`)の定義。 |
| `src/extension.ts` | アドオンのエントリーポイント。ActivityBarやコマンド群の設定、構成UIへのアクセス。 |
| `src/McpIntegration.ts` | Stitch MCPサーバーとの通信（取得、生成、編集、バリアント追加など）。 |
| `src/ProxyServer.ts` | ローカルプロキシサーバー。レスポンスをフックしてスクリプト群を安全に注入。 |
| `src/KaraageBrowserPanel.ts` | WebviewのメインUI構築、リソース処理（HTML/CSS表示抽出、履歴管理等）。 |
| `src/StitchPanel.ts` | Stitch用タブのHTML生成、3階層ドリルダウンUIの構成、チャット表示管理等の連携ロジック。 |
| `src/StitchConversationStore.ts` | VS Code `workspaceState` を用いたプロジェクト別のUI生成の会話履歴（チャット）永続化。 |
| `src/ContextLogger.ts` | AIとの統合向けに操作ログや自動コンテキスト保存（Diff等）を管理。 |
| `src/elements/` | CSS/HTML解析モジュール。DOM位置からソースコード上の行数を抽出・特定。 |
| `media/inspector/` | ProxyServerによって動的注入されるブラウザ上の操作スクリプト群。 |

---

## 5. コマンドリファレンス (Command Reference)

VS Codeのコマンドパレットから以下が実行可能です。

| コマンドID | Title (表示名) | 概要 |
| :--- | :--- | :--- |
| `karaageBrowser.open` | Launch Karaage Browser | メインのパネルを開き、ProxyServerを起動。 |
| `karaageBrowser.server.stop` | Stop Karaage Browser Server | パネルを終了し、ProxyServerを停止。 |
| `karaageBrowser.server.changeTarget` | Change Karaage Browser Target | 表示対象のパスやURLを変更するインプットボックス表示。 |
| `karaageBrowser.server.showLogs` | Show Karaage Browser Proxy Logs | Proxyサーバー側のアウトプットチャンネルを表示。 |
| `antigravity.openConfigurePluginsPage` | - | （Webview内のConfigurationボタン経由）MCPの設定画面を開く。 |

---

## 6. 使用手順（マニュアル）

**起動前（サイドバー・環境情報）**

![Karaage Browser メニュー — 起動前のサイドバーと View Manual](03.png)

1. **起動**:
   VS Codeの左アクティビティバーから「Karaage Browser」アイコンをクリックし、「Launch Karaage Browser」を押下します。
2. **プレビューの確認**:
   対象とするプロジェクト（Workspace）の `index.html` などがサーバー経由でWebViewの左側に表示されます。
3. **要素の検査 (Inspect) と編集**:
   右側のElementsタブで「Inspect Element」をオンにして左側のブラウザ内でクリックすると、対応するHTML/CSS構造が抽き出されます。
   「Apply HTML」や「Apply Inline Style」でライブ編集を行い、ミスがあれば「Edit History」からRevert可能です。AIへの相談が必要な場合は「CopyClipBoard」を使って直接LLMに投げて質問できます。
4. **Stitchと連動**:
   UIの生成や自動コーディングを行いたい場合は「Stitch MCP (Beta)」タブを開きます。
   - **New Project**からプロジェクトを作成、**Generate Screen**でプロンプトから画面生成。
   - 生成結果に対し、**Edit**（修正）や**Variants**（バリエーション追加）を行いブラッシュアップ。
   - ブラッシュアップ過程の会話履歴（Conversation History）を見返したり、**Download All** で直接ローカルにHTMLとして保存し、そのままブラウザ上で確認することができます。

---

## 7. 使用ライブラリとライセンス (Open Source Libraries)

本製品（Karaage Browser Extension）の開発および実行には、以下のオープンソースソフトウェア（OSS）およびエコシステムを利用しています。商用利用・有料販売を含め、各OSSのライセンス規約に則りここに帰属を表示します。各作者およびコミュニティの皆様に深く感謝いたします。

### 7.1. 基盤プラットフォーム / エコシステム (Platforms & Ecosystems)
これらは本拡張機能が起動・連携して動作するための外部プラットフォームであり、本パッケージそのものにはコードとして同梱されていません。
- **Visual Studio Code (VS Code) / VS Code Extension API**: 本拡張機能のメイン動作基盤。
- **Antigravity Extension**: LLMコンテキスト連携先として動作するVS Code拡張機能。
- **Google Stitch MCP Server**: Model Context Protocolを用いたAI UI生成・編集サーバー。
- **Mermaid JS**: 本マニュアルにおけるアーキテクチャ図の描画（VS CodeやAntigravityのマークダウン標準機能として利用）。

### 7.2. 実行時パッケージ (Runtime Dependencies)
拡張機能の動作に直接必要となり、パッケージビルド時（VSIX等）に同梱されるライブラリ群です。いずれも商用利用（有料販売）可能な準拠しやすいライセンスです。
- **`@modelcontextprotocol/sdk`** (v1.27.1) - [MIT License] : Stitch MCPサーバーとの通信基盤 (StdioClientTransport 等)
- **`express`** (v5.2.1) - [MIT License] : ローカルWebプレビューを提供するプロキシサーバー・フレームワーク
- **`http-proxy-middleware`** (v3.0.5) - [MIT License] : プロキシリクエストのハンドリングおよびHTML内容の書き換え処理
- **`cheerio`** (v1.2.0) - [MIT License] : サーバーサイドでの高速なHTML要素の解析・操作
- **`diff`** (v8.0.3) - [BSD 3-Clause License] : ファイル保存時に実行される自動Diff（変更差分）計算

### 7.3. 開発・テストツール (Development Dependencies)
製品の開発、ビルド、テスト等でのみ使用し、配布される最終パッケージには直接**含まれない**ライブラリ群です。
- **`typescript`** (v5.1.3) - [Apache License 2.0]
- **`mocha`** (v10.0.0) - [MIT License]
- **`@vscode/test-electron`** (v2.4.0) - [MIT License]
- **`@types/*` 関連パケージ** - [MIT License]

---

## 8. 謝辞 (Acknowledgements)

Karaage Browser Extensionは、Antigravityを活用した先進的なUI生成およびシームレスなローカル開発体験を実現するために生まれました。

本ツールの構想から実装に至るまで、**Visual Studio Code** や **Express** をはじめとする各種オープンソースエコシステム、そして **Google Stitch MCP** や **Antigravity** などの強力なAI基盤に強く支えられています。コミュニティの皆様が提供する素晴らしいライブラリと知見、プラットフォームがなければ、このプロジェクトは実現しませんでした。

プロジェクトの改善にフィードバックを下さった全てのユーザー、そして日々進化するテクノロジーを生み出している開発者の皆様に**心からの感謝を申し上げます。**  
皆様のより良い開発・クリエイティブ体験に、この拡張機能が少しでも貢献できることを願っています。

Kobayashi Yosuke 2026.03.12

*-- End of Document --*
