# 機能設計書 101-BrowserPlatform

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるBrowserプラットフォーム統合機能（WebAssembly/Blazor統合）の機能設計書である。

### 本機能の処理概要

BrowserPlatformは、Avalonia UIアプリケーションをWebブラウザ上で動作させるためのプラットフォーム統合機能を提供する。WebAssemblyおよびBlazor技術を活用し、デスクトップアプリケーションと同等のUIをWeb環境で実現する。

**業務上の目的・背景**：従来、デスクトップ向けに開発されたAvaloniaアプリケーションをWebブラウザで実行するニーズが高まっている。BrowserPlatformは、コードの大幅な変更なしにデスクトップアプリケーションをWeb環境にデプロイ可能にし、クロスプラットフォーム展開を容易にする。これにより、ユーザーはインストール不要でアプリケーションを利用でき、配布・更新コストを削減できる。

**機能の利用シーン**：
- デスクトップアプリケーションのWeb版を提供する場合
- クライアントPCへのインストールが難しい環境でのアプリケーション配布
- Blazor WebAssemblyを活用したSPA（Single Page Application）の構築
- クロスプラットフォームアプリケーションのWebフロントエンド

**主要な処理内容**：
1. WebAssemblyランタイム上でのAvalonia描画エンジンの初期化
2. HTML Canvas要素を介したUIレンダリング（WebGL1/WebGL2/Software2D対応）
3. JavaScriptとC#間のインターオペレーション処理
4. ブラウザイベント（マウス、キーボード、タッチ）のAvalonia入力イベントへの変換
5. クリップボード、ストレージ、ファイルダイアログなどのWeb API統合
6. マルチスレッド環境でのDispatcher管理

**関連システム・外部連携**：
- JavaScript Interop（DomHelper, InputHelper, CanvasHelper等）
- Web Storage API（BrowserStorageProvider）
- Clipboard API（ClipboardImpl）
- WebGL API（BrowserWebGlRenderTarget）

**権限による制御**：特になし。ブラウザのセキュリティポリシーに従う。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | AvaloniaView | 主画面 | ブラウザ上でのAvalonia UIコンテンツの表示領域 |

## 機能種別

プラットフォーム統合 / レンダリング処理 / イベント処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| mainDivId | string | Yes | Avalonia UIをレンダリングするHTML要素のID | 空文字・null不可 |
| RenderingMode | BrowserRenderingMode[] | No | レンダリングモードの優先順位 | WebGL2, WebGL1, Software2Dの配列 |
| FrameworkAssetPathResolver | Func&lt;string, string&gt; | No | フレームワークアセットのパス解決関数 | - |
| RegisterAvaloniaServiceWorker | bool | No | Service Workerの登録有無 | - |
| PreferManagedThreadDispatcher | bool | No | マネージドDispatcherの使用有無 | デフォルトtrue |

### 入力データソース

- HTML DOM要素（divタグ）
- ブラウザ入力イベント（MouseEvent, KeyboardEvent, TouchEvent）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AvaloniaView | AvaloniaView | 作成されたAvalonia表示コンテナ |
| Canvas描画出力 | HTML Canvas | WebGL/2Dコンテキストによる描画結果 |

### 出力先

- HTML Canvas要素（ブラウザ画面）
- ブラウザコンソール（ログ出力）

## 処理フロー

### 処理シーケンス

```
1. StartBrowserAppAsync呼び出し
   └─ アプリケーションビルダーとmainDivIdを受け取る
2. PreSetupBrowser実行
   └─ BrowserPlatformOptionsの設定
   └─ AvaloniaModuleのJavaScriptモジュールインポート
   └─ GlobalThisの取得
   └─ RenderWorkerの初期化（スレッド有効時）
3. BrowserWindowingPlatform.Register実行
   └─ 各種プラットフォームサービスの登録
   └─ Dispatcherの設定
4. AvaloniaView作成
   └─ DOM要素の取得
   └─ BrowserTopLevelImplの作成
   └─ 入力ハンドラーの設定
   └─ レンダリングサーフェスの作成
5. アプリケーションのセットアップとライフタイム開始
```

### フローチャート

```mermaid
flowchart TD
    A[StartBrowserAppAsync] --> B[PreSetupBrowser]
    B --> C{スレッド対応?}
    C -->|Yes| D[RenderWorker初期化]
    C -->|No| E[シングルスレッドモード]
    D --> F[BrowserWindowingPlatform.Register]
    E --> F
    F --> G[AvaloniaView作成]
    G --> H[BrowserTopLevelImpl作成]
    H --> I[入力ハンドラー設定]
    I --> J[レンダリングサーフェス作成]
    J --> K{ManagedDispatcher?}
    K -->|Yes| L[別スレッドでRun]
    K -->|No| M[現スレッドでSetup]
    L --> N[アプリケーション実行]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-101 | レンダリングモードフォールバック | WebGL2 → WebGL1 → Software2Dの順でフォールバック | WebGLがサポートされない場合 |
| BR-102 | スレッドサポート検出 | Thread.IsThreadStartSupportedで判定、不明時は実際にスレッド起動を試行 | 初期化時 |
| BR-103 | シングルビューライフタイム | ブラウザはウィンドウイングをサポートしないためSingleViewLifetimeを使用 | 常時 |

### 計算ロジック

特になし。

## データベース操作仕様

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ELEM_NOT_FOUND | ArgumentException | 指定されたIDのHTML要素が存在しない | 正しいIDを指定 |
| WASM_INIT_FAIL | InvalidOperationException | Avalonia WASMホストの初期化失敗 | JavaScriptモジュールの読み込み確認 |
| WEBGL_NOT_SUPPORTED | - | WebGLがサポートされない | Software2Dへフォールバック |

### リトライ仕様

リトライなし。

## トランザクション仕様

トランザクションなし。

## パフォーマンス要件

- WebGL2を優先使用してGPUアクセラレーションを活用
- スレッド有効時はRenderWorkerで描画処理をオフロード
- ManagedDispatcherによる効率的なイベント処理

## セキュリティ考慮事項

- ブラウザのセキュリティポリシー（CORS、CSP等）に従う
- Service Workerは明示的な設定時のみ登録
- クリップボード操作はブラウザの許可ポリシーに依存

## 備考

- WebAssembly Threading（SharedArrayBuffer）はクロスオリジン分離が必要
- Blazor ServerはサポートせずBlazor WebAssemblyのみ対応

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、プラットフォームオプションと設定の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BrowserAppBuilder.cs | `src/Browser/Avalonia.Browser/BrowserAppBuilder.cs` | BrowserPlatformOptionsレコード（12-64行目）でレンダリングモードやService Worker設定を定義 |

**読解のコツ**: BrowserRenderingMode列挙型（12-17行目）で3つのレンダリングモード（Software2D, WebGL1, WebGL2）を定義。デフォルトはWebGL2優先。

#### Step 2: エントリーポイントを理解する

処理の起点となるAppBuilder拡張メソッドを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | BrowserAppBuilder.cs | `src/Browser/Avalonia.Browser/BrowserAppBuilder.cs` | StartBrowserAppAsync（74-119行目）がメインエントリーポイント |

**主要処理フロー**:
1. **74-76行目**: mainDivIdのnullチェック
2. **83行目**: PreSetupBrowserでプラットフォーム初期化
3. **85-90行目**: BrowserSingleViewLifetimeの作成とAfterApplicationSetup
4. **92-118行目**: スレッド有効時は別スレッドでRun、無効時は現スレッドでSetup

#### Step 3: プラットフォーム登録処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WindowingPlatform.cs | `src/Browser/Avalonia.Browser/WindowingPlatform.cs` | Register（83-121行目）で各種サービスをAvaloniaLocatorに登録 |

**主要処理フロー**:
- **88-99行目**: IRuntimePlatform, ICursorFactory, IKeyboardDevice等の登録
- **100-109行目**: ManagedDispatcherまたはBrowserDispatcherImplの選択

#### Step 4: トップレベル実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | BrowserTopLevelImpl.cs | `src/Browser/Avalonia.Browser/BrowserTopLevelImpl.cs` | コンストラクタ（53-75行目）でサーフェス作成と入力ハンドラー設定 |

**主要処理フロー**:
- **59行目**: BrowserInputHandlerの作成
- **61-63行目**: NativeControlHost、StorageProvider、Clipboardの初期化
- **68行目**: RenderTargetBrowserSurfaceの作成

#### Step 5: ビュー表示処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | AvaloniaView.cs | `src/Browser/Avalonia.Browser/AvaloniaView.cs` | コンストラクタ（21-57行目）でEmbeddableControlRootを作成しレンダラー起動 |

### プログラム呼び出し階層図

```
StartBrowserAppAsync (BrowserAppBuilder.cs)
    │
    ├─ PreSetupBrowser
    │      ├─ AvaloniaModule.ImportMain()
    │      ├─ DomHelper.GetGlobalThis()
    │      └─ RenderWorker.InitializeAsync()
    │
    ├─ BrowserWindowingPlatform.Register()
    │      └─ AvaloniaLocator設定
    │
    └─ AvaloniaView (constructor)
           │
           ├─ DomHelper.GetElementById()
           ├─ DomHelper.CreateAvaloniaHost()
           └─ BrowserTopLevelImpl (constructor)
                  │
                  ├─ BrowserInputHandler
                  ├─ BrowserInsetsManager
                  ├─ BrowserNativeControlHost
                  ├─ BrowserStorageProvider
                  └─ RenderTargetBrowserSurface.Create()
```

### データフロー図

```
[入力]                    [処理]                         [出力]

HTMLイベント ───────▶ BrowserInputHandler ───────▶ RawInputEventArgs
(MouseEvent等)           ↓
                    InputHelper (JS Interop)

BrowserRenderingMode ──▶ RenderTargetBrowserSurface ──▶ HTML Canvas
                         ↓
                    WebGL/2D Context
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| BrowserAppBuilder.cs | `src/Browser/Avalonia.Browser/BrowserAppBuilder.cs` | ソース | アプリケーションビルダー拡張 |
| WindowingPlatform.cs | `src/Browser/Avalonia.Browser/WindowingPlatform.cs` | ソース | ウィンドウイングプラットフォーム実装 |
| BrowserTopLevelImpl.cs | `src/Browser/Avalonia.Browser/BrowserTopLevelImpl.cs` | ソース | トップレベルウィンドウ実装 |
| AvaloniaView.cs | `src/Browser/Avalonia.Browser/AvaloniaView.cs` | ソース | Avaloniaビューコンテナ |
| BrowserInputHandler.cs | `src/Browser/Avalonia.Browser/BrowserInputHandler.cs` | ソース | 入力イベントハンドラー |
| BrowserSurface.cs | `src/Browser/Avalonia.Browser/Rendering/BrowserSurface.cs` | ソース | レンダリングサーフェス基底 |
| BrowserWebGlRenderTarget.cs | `src/Browser/Avalonia.Browser/Rendering/BrowserWebGlRenderTarget.cs` | ソース | WebGLレンダーターゲット |
| BrowserStorageProvider.cs | `src/Browser/Avalonia.Browser/Storage/BrowserStorageProvider.cs` | ソース | ストレージプロバイダー |
| ClipboardImpl.cs | `src/Browser/Avalonia.Browser/ClipboardImpl.cs` | ソース | クリップボード実装 |
| DomHelper.cs | `src/Browser/Avalonia.Browser/Interop/DomHelper.cs` | ソース | DOM操作ヘルパー |
| InputHelper.cs | `src/Browser/Avalonia.Browser/Interop/InputHelper.cs` | ソース | 入力処理ヘルパー |
| CanvasHelper.cs | `src/Browser/Avalonia.Browser/Interop/CanvasHelper.cs` | ソース | Canvas操作ヘルパー |
