# 機能設計書 109-DesignerSupport

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるデザイナー支援機能の機能設計書である。IDEプレビュー機能のサポートを提供する。

### 本機能の処理概要

DesignerSupportは、Visual Studio、Rider、Visual Studio CodeなどのIDEでAvalonia XAMLのリアルタイムプレビュー機能を実現するための基盤を提供する。XAMLファイルの変更をリアルタイムで反映し、デザイン時のUIプレビューを可能にする。

**業務上の目的・背景**：UI開発において、XAMLコードの変更結果を即座に確認できることは生産性向上に不可欠である。DesignerSupportにより、開発者はアプリケーションを再ビルド・再起動することなくUIの変更を確認でき、試行錯誤のサイクルが大幅に短縮される。これにより、UI/UXデザインの品質向上と開発効率の改善を実現する。

**機能の利用シーン**：
- Visual StudioでのXAMLデザイナー使用時
- JetBrains RiderでのAvaloniaプレビュー
- Visual Studio CodeのAvalonia拡張機能使用時
- XAMLホットリロード開発
- デザイン時データバインディングの確認

**主要な処理内容**：
1. デザイナープロセスとのトランスポート接続確立
2. XAML更新メッセージの受信と処理
3. デザインモードでのウィンドウ/コントロール生成
4. レンダリング結果のフレームデータ送信
5. 入力イベントの受信とシミュレーション
6. エラー情報のIDEへのフィードバック

**関連システム・外部連携**：
- Avalonia.Remote.Protocol（通信プロトコル）
- IDE拡張機能（Visual Studio、Rider等）
- TCP/BSON通信

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | デザイナープレビュー | 主画面 | IDEデザイナーに表示されるプレビュー画面 |

## 機能種別

IDE統合 / デザイン時サポート / リモート通信

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| transport | Uri | Yes | トランスポートURI（tcp-bson://等） | 有効なURI |
| method | string | No | 表示方式（avalonia-remote/win32/html） | 指定値のみ |
| session-id | string | No | セッションID | - |
| app | string | Yes | アプリケーションパス | 有効なパス |

### 入力データソース

- IDE からの UpdateXamlMessage
- IDE からのビューポート/DPI情報
- IDE からの入力イベント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FrameMessage | FrameMessage | レンダリングされたフレームデータ |
| UpdateXamlResultMessage | UpdateXamlResultMessage | XAML更新結果（成功/エラー） |

### 出力先

- IDEデザイナーウィンドウ
- エラーリストウィンドウ

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数解析
   └─ transport、method、session-id、app
2. トランスポート接続
   └─ tcp-bson://またはfile://
3. アプリケーションロード
   └─ Design.IsDesignMode = true
   └─ AppBuilder取得と設定
4. プラットフォーム初期化
   └─ methodに応じたWindowingSubsystem設定
5. メッセージループ開始
   └─ OnTransportMessageでメッセージ処理
6. XAML更新処理
   └─ DesignWindowLoader.LoadDesignerWindow
   └─ 結果またはエラーを返信
```

### フローチャート

```mermaid
flowchart TD
    A[Main開始] --> B[コマンドライン解析]
    B --> C[トランスポート作成]
    C --> D{methodの種類}
    D -->|avalonia-remote| E[PreviewerWindowingPlatform]
    D -->|html| F[HtmlWebSocketTransport]
    D -->|win32| G[Win32Platform]
    E --> H[SetupWithoutStarting]
    F --> H
    G --> H
    H --> I[イベントハンドラー登録]
    I --> J[StartDesignerSessionMessage送信]
    J --> K[MainLoop開始]
    K --> L{メッセージ受信}
    L -->|UpdateXamlMessage| M[LoadDesignerWindow]
    L -->|ViewportMessage| N[RebuildPreFlight]
    L -->|FormatMessage| N
    M --> O{成功?}
    O -->|Yes| P[UpdateXamlResultMessage送信]
    O -->|No| Q[エラー情報送信]
    P --> L
    Q --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-109-1 | デザインモード | Design.IsDesignMode=trueでコントロールのデザインモード動作 | 常時 |
| BR-109-2 | スケーリング維持 | 前回のRenderScalingを新しいウィンドウに適用 | XAML更新時 |
| BR-109-3 | ウィンドウ再作成 | XAML更新時は前のウィンドウを閉じて新規作成 | 常時 |
| BR-109-4 | エラー詳細 | XmlExceptionの場合は行番号・位置情報を含める | パースエラー時 |

### 計算ロジック

特になし。

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

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| XAML_PARSE_ERROR | XmlException | XAML構文エラー | 行番号付きエラー情報を返却 |
| APP_NOT_FOUND | Exception | アプリケーションパスが無効 | パス確認 |
| TRANSPORT_ERROR | Exception | 接続エラー | 再接続または終了 |

### リトライ仕様

トランスポートエラー時はプロセス終了。

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

トランザクションなし。

## パフォーマンス要件

- XAML更新からプレビュー反映まで低レイテンシ
- フレームデータの効率的な転送
- メモリリークのない継続的なXAML更新

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

- デフォルトはローカルホスト接続のみ
- 任意のXAMLコードを実行するため、信頼されたソースのみ使用

## 備考

- tcp-bson、file、htmlの3つのトランスポートをサポート
- htmlメソッドはWebブラウザでプレビュー表示

---

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

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

### 推奨読解順序

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

コマンドライン引数とメソッド定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | RemoteDesignerEntryPoint.cs | `src/Avalonia.DesignerSupport/Remote/RemoteDesignerEntryPoint.cs` | CommandLineArgsクラス（23-30行目）、Methodsクラス（32-37行目） |

**読解のコツ**: 3つのメソッド（avalonia-remote、win32、html）がそれぞれ異なるプレビュー方式を提供。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | RemoteDesignerEntryPoint.cs | `src/Avalonia.DesignerSupport/Remote/RemoteDesignerEntryPoint.cs` | Main（169-191行目）でコマンドライン解析とアプリケーション起動 |

**主要処理フロー**:
- **171-172行目**: コマンドライン解析とトランスポート作成
- **178行目**: Design.IsDesignMode = true
- **180行目**: AppBuilder.Configure
- **182行目**: initializer.ConfigureApp
- **190行目**: Dispatcher.UIThread.MainLoop

#### Step 3: アプリケーション設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | RemoteDesignerEntryPoint.cs | `src/Avalonia.DesignerSupport/Remote/RemoteDesignerEntryPoint.cs` | AppInitializer.ConfigureApp（137-156行目）でプラットフォーム設定 |

**主要処理フロー**:
- **142-143行目**: avalonia-remoteメソッドでPreviewerWindowingPlatform
- **144-150行目**: htmlメソッドでHtmlWebSocketTransport
- **152-153行目**: win32メソッドでWin32Platform

#### Step 4: メッセージ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | RemoteDesignerEntryPoint.cs | `src/Avalonia.DesignerSupport/Remote/RemoteDesignerEntryPoint.cs` | OnTransportMessage（205-250行目）でメッセージディスパッチ |

**主要処理フロー**:
- **207-216行目**: プリフライトメッセージの再構築
- **222-249行目**: UpdateXamlMessageの処理とウィンドウ生成

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

```
Main (RemoteDesignerEntryPoint.cs)
    │
    ├─ ParseCommandLineArgs
    │      └─ CommandLineArgs作成
    │
    ├─ CreateTransport
    │      ├─ BsonTcpTransport (tcp-bson://)
    │      └─ FileWatcherTransport (file://)
    │
    ├─ AppBuilder.Configure
    │      └─ AppInitializer.ConfigureApp
    │             │
    │             ├─ PreviewerWindowingPlatform.Initialize
    │             │      └─ PreviewerWindowImpl
    │             │
    │             └─ SetupWithoutStarting
    │
    └─ Dispatcher.UIThread.MainLoop
           │
           └─ OnTransportMessage
                  │
                  ├─ ClientSupportedPixelFormatsMessage処理
                  ├─ ClientViewportAllocatedMessage処理
                  ├─ ClientRenderInfoMessage処理
                  │
                  └─ UpdateXamlMessage処理
                         └─ DesignWindowLoader.LoadDesignerWindow
```

### データフロー図

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

IDE (UpdateXamlMessage) ──▶ OnTransportMessage ──────────▶ ウィンドウ作成
                               │
                               ▼
XAML文字列 ────────────▶ DesignWindowLoader ─────────────▶ Window
                               │
                               ▼
レンダリング ──────────▶ PreviewerWindowImpl ────────────▶ FrameMessage
                               │
                               ▼
                          トランスポート送信 ───────────▶ IDEプレビュー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| RemoteDesignerEntryPoint.cs | `src/Avalonia.DesignerSupport/Remote/RemoteDesignerEntryPoint.cs` | ソース | デザイナーエントリーポイント |
| DesignWindowLoader.cs | `src/Avalonia.DesignerSupport/DesignWindowLoader.cs` | ソース | デザインウィンドウローダー |
| PreviewerWindowingPlatform.cs | `src/Avalonia.DesignerSupport/Remote/PreviewerWindowingPlatform.cs` | ソース | プレビューワー用プラットフォーム |
| PreviewerWindowImpl.cs | `src/Avalonia.DesignerSupport/Remote/PreviewerWindowImpl.cs` | ソース | プレビューワーウィンドウ実装 |
| HtmlTransport.cs | `src/Avalonia.DesignerSupport/Remote/HtmlTransport/HtmlTransport.cs` | ソース | HTML表示用トランスポート |
| FileWatcherTransport.cs | `src/Avalonia.DesignerSupport/Remote/FileWatcherTransport.cs` | ソース | ファイル監視トランスポート |
| DetachableTransportConnection.cs | `src/Avalonia.DesignerSupport/Remote/DetachableTransportConnection.cs` | ソース | 切断可能トランスポート |
| Stubs.cs | `src/Avalonia.DesignerSupport/Remote/Stubs.cs` | ソース | スタブ実装 |
