# 画面設計書 17-MultiLinePasteDialog（複数行貼り付け確認）

## 概要

本ドキュメントは、Windows Terminal の MultiLinePasteDialog（複数行貼り付け確認）画面の設計仕様を記述する。MultiLinePasteDialog は、クリップボードの内容が複数行テキストを含む場合に、貼り付け操作の確認を求めるダイアログである。

### 本画面の処理概要

MultiLinePasteDialog は、ユーザーがターミナルにテキストを貼り付けようとした際に、そのテキストが改行文字を含む場合に表示される確認ダイアログである。クリップボードの内容のプレビューを含み、ユーザーに貼り付け操作の意図を確認する。

**業務上の目的・背景**：複数行テキストの貼り付けは、シェル環境では各行が個別のコマンドとして実行される可能性がある。ユーザーが意図せず危険なコマンドを実行してしまうリスクを回避するために、複数行テキストの貼り付け時には事前確認が必要である。例えば、Webページからコピーしたスクリプトに悪意のある隠しコマンドが含まれている場合の対策となる。

**画面へのアクセス方法**：TerminalPage の貼り付け処理（`_PasteFromClipboardHandler`）において、クリップボードテキストに改行が含まれ、かつ `WarnAboutMultiLinePaste` 設定が有効な場合に表示される。

**主要な操作・処理内容**：
1. 警告メッセージの表示：複数行テキストの貼り付けが予期しないコマンド実行を引き起こす可能性がある旨の警告を表示する
2. クリップボード内容のプレビュー：貼り付け対象のテキストを ScrollViewer 内にプレビュー表示する（最大1024文字に省略）
3. 貼り付け続行（Primary ボタン）：「Paste anyway」ボタンで貼り付け操作を続行する
4. キャンセル（Close ボタン）：「Cancel」ボタンで貼り付け操作を中断する

**画面遷移**：TerminalPage の貼り付け操作からダイアログが表示される。Primary ボタンで貼り付けが実行され、Close ボタンで TerminalPage に戻る。

**権限による表示制御**：特になし。ただし、`WarnAboutMultiLinePaste` 設定が false の場合はダイアログが表示されない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 32 | テキストの貼り付け | 主機能 | 複数行テキスト貼り付け時の確認ダイアログ表示 |

## 画面種別

ダイアログ（ContentDialog - インライン定義）

## URL/ルーティング

該当なし（TerminalPage.xaml 内にインライン定義される ContentDialog）

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| ClipboardText | 入力（表示） | String | Yes | クリップボードのテキスト内容（最大1024文字に省略） |
| ContentDialogResult | 出力 | ContentDialogResult | Yes | ユーザーの選択結果（Primary = 貼り付け / None = キャンセル） |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Title | テキスト | "Warning" |
| MultiLineWarningText | TextBlock | 複数行貼り付けの警告メッセージ |
| ClipboardTextHeader | TextBlock | "Clipboard contents (preview):" ラベル |
| ClipboardContentScrollViewer | ScrollViewer | クリップボード内容のスクロール表示領域（最大高さ100px） |
| ClipboardText | TextBlock | クリップボードテキストのプレビュー（Cascadia Mono フォント、折り返し表示） |
| PrimaryButtonText | ボタンラベル | "Paste anyway" |
| CloseButtonText | ボタンラベル | "Cancel" |

## イベント仕様

### 1-ダイアログ表示前のテキスト設定

TerminalPage.cpp の `_PasteFromClipboardHandler`（行2995-3052）内で、貼り付けテキストが複数行を含むかチェックされる。表示前に以下の処理が行われる：
- `FindName(L"MultiLinePasteDialog")` でダイアログを遅延読み込み（行3007）
- テキストが1024文字を超える場合は512文字 + 省略記号に切り詰め（行3012-3018）
- `ClipboardText().Text()` でプレビューテキストを設定（行3020）
- `ClipboardContentScrollViewer().ScrollToVerticalOffset(0)` でスクロール位置をリセット（行3023）

### 2-Primary ボタン（Paste anyway）

ユーザーが「Paste anyway」ボタンをクリックすると、ContentDialogResult::Primary が返される。貼り付け処理が続行され、テキストがターミナルに送信される。ダイアログ閉じ後に `ClipboardText().Text({})` でプレビューテキストがクリアされる（行3036）。

### 3-Close ボタン（Cancel）

ユーザーが「Cancel」ボタンをクリックすると、貼り付け操作が中断される（行3038-3041）。

## データベース更新仕様

### 操作別データベース影響一覧

該当なし。本画面はデータベースを操作しない。

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|----------|---------------|
| MultiLinePasteDialog.Title | タイトル | 常時 | "Warning" |
| MultiLineWarningText.Text | 警告文 | 常時 | "You are about to paste text that contains multiple lines. If you paste this text into your shell, it may result in the unexpected execution of commands. Do you wish to continue?" |
| ClipboardTextHeader.Text | ラベル | 常時 | "Clipboard contents (preview):" |
| MultiLinePasteDialog.PrimaryButtonText | ボタンラベル | 常時 | "Paste anyway" |
| MultiLinePasteDialog.CloseButtonText | ボタンラベル | 常時 | "Cancel" |

## 例外処理

- テキストのサロゲートペア切断防止：テキスト切り詰め時に `til::utf16_iterate_prev` を使用してサロゲートペアの中間での切断を回避する（TerminalPage.cpp 行3016）
- 大量テキストの表示パフォーマンス対策：WinUI がO(n)以上の処理コストを持つため、プレビューテキストを1024文字に制限している（行3009-3010のコメント参照）

## 備考

- DefaultButton は Primary に設定されている（TerminalPage.xaml 行111）
- x:Load="False" により遅延読み込みされる（TerminalPage.xaml 行110）
- クリップボードテキストのプレビューには Cascadia Mono フォントが使用される（行121）
- ScrollViewer の最大高さは100pxに設定されている（行118）
- ダイアログ閉じ後にクリップボードテキストがメモリ上からクリアされる（セキュリティ対策、行3036）
- WarnAboutMultiLinePaste 設定と WarnAboutLargePaste 設定の両方が判定され、複数行警告が優先される（行3026-3033）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TerminalPage.xaml | `src/cascadia/TerminalApp/TerminalPage.xaml` | MultiLinePasteDialog の XAML 定義（行107-125）。内部に StackPanel を持ち、警告テキスト・ヘッダー・ScrollViewer・クリップボードプレビューの構成を確認 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | `_PasteFromClipboardHandler`（行2995付近）内のダイアログ表示フロー。テキスト切り詰め処理（行3012-3018）、テキスト設定（行3020）、スクロールリセット（行3023）を確認 |
| 2-2 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | `_ShowMultiLinePasteWarningDialog`（行925-928）で `_ShowDialogHelper` を呼び出す |

**主要処理フロー**:
1. **行2997-2998**: `minimumSizeForWarning`（5KiB）との比較で大量テキスト警告を判定
2. **行3007**: `FindName(L"MultiLinePasteDialog")` で遅延読み込み
3. **行3012-3018**: テキスト切り詰め処理（サロゲートペア安全）
4. **行3020-3023**: プレビューテキスト設定とスクロールリセット
5. **行3026-3033**: 複数行警告 or 大量テキスト警告の判定
6. **行3036**: ダイアログ閉じ後のテキストクリア

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

```
TerminalPage::_PasteFromClipboardHandler (TerminalPage.cpp:~2970)
    |
    +-- テキスト改行チェック / サイズチェック
    |
    +-- FindName("MultiLinePasteDialog") 遅延読み込み
    |
    +-- テキスト切り詰め（1024文字制限）
    |       +-- til::utf16_iterate_prev（サロゲートペア安全な切断）
    |
    +-- ClipboardText().Text() 設定
    |
    +-- [warnMultiLine?] _ShowMultiLinePasteWarningDialog (行925)
    |       +-- _ShowDialogHelper("MultiLinePasteDialog")
    |
    +-- [warnLargeText?] _ShowLargePasteWarningDialog (行936)
    |
    +-- ClipboardText().Text({}) クリア
    |
    +-- [結果判定]
            +-- Primary --> eventArgs.HandleClipboardData()
            +-- Other --> co_return（キャンセル）
```

### データフロー図

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

クリップボード          --> _PasteFromClipboardHandler      --> MultiLinePasteDialog 表示
  (テキスト)                 |                                   |
                        --> 改行チェック                     --> 警告メッセージ
                        --> テキスト切り詰め(1024文字)       --> ClipboardText プレビュー
                             |                                   |
ユーザー選択            --> ContentDialogResult              --> 貼り付け実行 or キャンセル
                        --> ClipboardText クリア
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TerminalPage.xaml | `src/cascadia/TerminalApp/TerminalPage.xaml` | ソース（XAML） | MultiLinePasteDialog のインライン定義（行107-125） |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース（実装） | _PasteFromClipboardHandler / _ShowMultiLinePasteWarningDialog の実装 |
| Resources.resw | `src/cascadia/TerminalApp/Resources/en-US/Resources.resw` | リソース | ダイアログテキストの文字列リソース（行541-551, 702-703） |
