# Karaage Browser Extension — Specification & Manual

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

**Created**: 2026-03-12  
**Package version**: 1.0.0  
**Author**: Yosuke Kobayashi

## 1. Overview

Karaage Browser Extension is a powerful HTML/CSS inspector and UI generation/integration tool that runs on VS Code. It previews your local web development environment inside a VS Code WebView panel and provides DevTools-like element inspection and live editing. It also integrates with **Google Stitch MCP (Model Context Protocol)** for AI-driven UI generation, code editing, variant creation, and chat history management.

**Demo video**

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

**Screen overview (after launch)**

![Karaage Browser — Browser preview and Stitch MCP tab](01.png)

---

## 2. System Architecture

The tool is structured as follows. A VS Code WebView panel is at the center, with the local file system and Stitch MCP (AI) working together.

```mermaid
graph TD
    User([User]) --> |"Run commands / UI actions"| VSC[VS Code Extension]
    
    subgraph Karaage Browser Extension
        VSC --> |"Create panel"| Panel[KaraageBrowserPanel]
        Panel --> |"Integrate"| Proxy[ProxyServer]
        Panel --> |"Integrate"| MCP[McpIntegration]
        Panel --> |"Integrate"| Logger[ContextLogger]
    end

    Proxy -->|"Inject Inspector scripts"| LocalFS[(Workspace / Local Files)]
    Panel -->|"WebView (Iframe)"| Proxy
    
    MCP <-->|"Stdio"| StitchServer((Stitch MCP Server))
    StitchServer -.->|"UI layout etc."| AI((Gemini / AI Models))
    
    Panel -->|"LLM (context / chat)"| Antigravity[(Antigravity Chat)]
```

### Architecture notes

- **ProxyServer**: When serving HTML, it injects DOM inspection/editing scripts (`selectionController.js`, `historyAdapter.js`, `domPatchAdapter.js`, `bridge.js`) before the `<body>` tag.
- **McpIntegration**: Reads the Stitch MCP server path from config (e.g. `.gemini/antigravity/mcp_config.json`) and performs project/screen listing and UI generation (Generate/Edit/Variants).
- **KaraageBrowserPanel**: Renders an iframe with the proxy URL and a control panel with DevTools (Elements tab and Stitch MCP tab).
- **ContextLogger**: Logs manual edits and hooks `onDidSaveTextDocument` to record automatic diffs for context shared with the Antigravity LLM.

---

## 3. Main components

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

ProxyServer uses `express` and `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. Read file
    FS-->>Proxy: 3. HTML source
    Note over Proxy: Inject Inspector scripts<br>before body
    Proxy-->>Webview: 4. HTML with scripts
```

#### Features

- Serves files from the workspace (`internalRoot`). Access to files outside the workspace is restricted (`/__open__/`).
- Detects HTML responses and performs safe string replacement with `identity` encoding.
- Injects four core modules: `selectionController.js`, `historyAdapter.js`, `domPatchAdapter.js`, `bridge.js`.

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

The UI has two panes: a web preview on the left and a control panel on the right.

| Tab | Role |
| :--- | :--- |
| **Elements** | Inspector (click elements to get DOM), Apply HTML / Apply Inline Style, Delete Element, **Edit History** (list and revert changes), **Copy to clipboard**: copies the element’s HTML/CSS as LLM context (ContextLogger) and supports pasting into chat. |
| **Stitch MCP (Beta)** | Three-level drill-down: (1) **Project list** — list and create Stitch projects; (2) **Screens** — list screens, Download All, Generate Screen, Conversation History and export, offline cache; (3) **Screen detail** — in-browser preview, download HTML, Edit and Variants via natural language. |

**Elements tab**

![Elements tab — Inspect, HTML/CSS edit, Copy to Clipboard](02.png)

**Stitch MCP (Beta) tab**

![Stitch MCP tab — Project list and screen generation](01.png)

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

The extension acts as an MCP client and talks to the Stitch MCP server via the SDK.

```mermaid
stateDiagram-v2
    [*] --> Connect
    Connect --> CheckConfig: Read mcp_config.json
    CheckConfig --> InitializeClient: StdioClientTransport
    InitializeClient --> CallTool: Call tools
    
    state CallTool {
        list_projects
        create_project
        list_screens
        get_screen
        generate_screen_from_text
        edit_screens
        generate_variants
    }
    
    CallTool --> DownloadScreen: "Save to workspace (offline cache)"
    DownloadScreen --> [*]
```

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

Writes operation history and context to a markdown log (`karaage-session.log.md`) in the workspace. Used to share context with the Antigravity LLM.

- **Explicit UI logs**: Records Edit, Delete, Revert, and Copy-to-clipboard (LLM context) actions.
- **Auto-Diff on save**: Hooks `vscode.workspace.onDidSaveTextDocument` and appends diffs for watched files (HTML, CSS, JS, etc.) to the log.

### 3.5. DOM element locator (`src/elements/HtmlLocator.ts` / `CssLocator.ts`)

Maps inspector (element selection) events from the browser to **line numbers (startLine, endLine)** in local source.

- **HtmlLocator**: Uses `domPath`, `tagName`, `id`, `classList`, depth, and scoring to find the matching element in the HTML source.
- **CssLocator**: Locates the selector in CSS files (including inline styles) in the source.

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

Stores chat and Generate/Edit/Variants history per project using VS Code `workspaceState` (memento). Appends and caps messages (e.g. max 50 per project) and supports Markdown export.

---

## 4. Directory and file layout

| Path | Role |
| :--- | :--- |
| `package.json` | Extension metadata, commands, version (1.0.0). |
| `src/extension.ts` | Entry point; Activity Bar, commands, sidebar UI. |
| `src/McpIntegration.ts` | Stitch MCP client (list, generate, edit, variants). |
| `src/ProxyServer.ts` | Local proxy; injects scripts into responses. |
| `src/KaraageBrowserPanel.ts` | Main WebView UI, resources, history. |
| `src/StitchPanel.ts` | Stitch tab HTML and three-level UI. |
| `src/StitchConversationStore.ts` | Per-project chat persistence via workspaceState. |
| `src/ContextLogger.ts` | Operation log and auto context (diffs). |
| `src/elements/` | HTML/CSS locators (DOM → line numbers). |
| `media/inspector/` | Scripts injected by ProxyServer. |

---

## 5. Command reference

These commands are available from the VS Code command palette.

| Command ID | Title | Summary |
| :--- | :--- | :--- |
| `karaageBrowser.open` | Launch Karaage Browser | Opens the main panel and starts the proxy. |
| `karaageBrowser.server.stop` | Stop Karaage Browser Server | Closes the panel and stops the proxy. |
| `karaageBrowser.server.changeTarget` | Change Karaage Browser Target | Shows an input to change the target path/URL. |
| `karaageBrowser.server.showLogs` | Show Karaage Browser Proxy Logs | Opens the proxy output channel. |
| `antigravity.openConfigurePluginsPage` | — | Opens MCP config (via Configuration button in WebView). |

---

## 6. How to use

**Sidebar before launch**

![Karaage Browser menu — Sidebar and View Manual before launch](03.png)

1. **Start**: Click the “Karaage Browser” icon in the Activity Bar and run “Launch Karaage Browser”.
2. **Preview**: Your workspace’s `index.html` (or target file) is shown on the left via the proxy.
3. **Inspect and edit**: In the Elements tab, turn on “Inspect Element” and click in the preview to get the HTML/CSS. Use “Apply HTML” / “Apply Inline Style” for live edits; use “Edit History” to revert. Use “Copy to clipboard” to send context to the LLM chat.
4. **Stitch**: Open the “Stitch MCP (Beta)” tab to generate or edit UI: create a project, use Generate Screen, then Edit/Variants. Use Conversation History and “Download All” to save HTML locally.

---

## 7. Libraries and licenses

Karaage Browser Extension uses the following open source software. Use and distribution must comply with each project’s license.

### 7.1. Platforms and ecosystems

Not bundled as code; required for the extension to run.

- **Visual Studio Code / VS Code Extension API**: Main host.
- **Antigravity Extension**: LLM/chat integration.
- **Google Stitch MCP Server**: AI UI generation via MCP.
- **Mermaid JS**: Diagrams in this manual (Markdown preview).

### 7.2. Runtime dependencies

Bundled in the VSIX. Permissive licenses.

- **`@modelcontextprotocol/sdk`** (v1.27.1) — [MIT]: MCP client (StdioClientTransport, etc.)
- **`express`** (v5.2.1) — [MIT]: Proxy server
- **`http-proxy-middleware`** (v3.0.5) — [MIT]: Proxy and HTML rewriting
- **`cheerio`** (v1.2.0) — [MIT]: HTML parsing
- **`diff`** (v8.0.3) — [BSD 3-Clause]: Diff calculation on save

### 7.3. Development dependencies

Not included in the distributed package.

- **`typescript`** (v5.1.3) — [Apache 2.0]
- **`@types/*`** — [MIT]

---

## 8. Acknowledgements

Karaage Browser Extension was created to provide UI generation and a smooth local development experience with Antigravity. It relies on **Visual Studio Code**, **Express**, **Google Stitch MCP**, and **Antigravity**, and on the open source community. Thank you to everyone who has given feedback and to the developers behind these tools. We hope this extension helps you build and create more effectively.

Yosuke Kobayashi, 2026-03-12

*— End of document —*
