# 通知設計書 2-WindowCwdToast

## 概要

本ドキュメントは、Windows Terminal における現在の作業ディレクトリ（CWD）表示トースト通知（WindowCwdToast）の設計仕様を定義する。ターミナルの仮想作業ディレクトリをユーザーに一時的に表示するための TeachingTip ベースの通知機能である。

### 本通知の処理概要

WindowCwdToast は、ユーザーがデバッグ目的で現在のターミナルの仮想作業ディレクトリ（VirtualWorkingDirectory）を確認したい場合に、画面上に一時的にオーバーレイ表示するトースト通知である。

**業務上の目的・背景**：ターミナルの作業ディレクトリはシェル操作の基点となる重要な情報であるが、通常はプロンプトに表示される。しかし、プロンプトのカスタマイズやスクロールにより確認が困難な場合がある。本通知は、デバッグ機能が有効な環境においてCWD情報を即座に確認する手段を提供する。

**通知の送信タイミング**：ユーザーが `displayWorkingDirectory` アクションを実行した時に表示される。`_HandleDisplayWorkingDirectory` アクションハンドラを経由して `TerminalPage::ShowTerminalWorkingDirectory()` が呼び出される。ただし、デバッグ機能（`DebugFeaturesEnabled`）が有効な場合のみ動作する。

**通知の受信者**：現在のウィンドウを操作しているユーザー自身。アプリ内UI通知としてウィンドウ上にオーバーレイ表示される。

**通知内容の概要**：ターミナルの仮想作業ディレクトリ（`VirtualWorkingDirectory`）が TeachingTip の Title として表示される。

**期待されるアクション**：ユーザーは表示されたCWD情報を確認する。3秒後に自動的に消去されるため、特別な操作は不要である。ライトディスミスによる手動消去も可能。

## 通知種別

アプリ内通知（TeachingTip ベースの Toast 通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（UIスレッド上で即時表示） |
| 優先度 | 低（デバッグ用途） |
| リトライ | 無し |

### 送信先決定ロジック

アクションを実行したウィンドウの TerminalPage 上に直接表示される。送信先の決定は不要。

## 通知テンプレート

### アプリ内通知（TeachingTip）の場合

| 項目 | 内容 |
|-----|------|
| UIコントロール | `Microsoft.UI.Xaml.Controls.TeachingTip` |
| 名前 | `WindowCwdToast` |
| x:Uid | `WindowCwdToast`（ローカライズキー） |
| IsLightDismissEnabled | True |

### 本文テンプレート

```
Title: {WindowProperties.VirtualWorkingDirectory}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| VirtualWorkingDirectory | ターミナルの仮想作業ディレクトリパス | WindowProperties.VirtualWorkingDirectory（Mode=OneWay） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ユーザーアクション | `displayWorkingDirectory` アクション | `DebugFeaturesEnabled` が true | デバッグ機能有効時のみCWDを表示 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| DebugFeaturesEnabled が false | デバッグ機能が無効な場合、アクションはハンドルされず通知は表示されない |
| TeachingTip の FindName 失敗 | XAML要素が見つからない場合、Toast が生成されず表示されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザーがdisplayWorkingDirectoryアクション実行] --> B[_HandleDisplayWorkingDirectory]
    B --> C{DebugFeaturesEnabled?}
    C -->|No| D[アクション未処理で終了]
    C -->|Yes| E[ShowTerminalWorkingDirectory]
    E --> F{_windowCwdToast == nullptr?}
    F -->|Yes| G[FindName でTeachingTip取得]
    G --> H[Toast オブジェクト生成]
    H --> I[Closed コールバック登録]
    F -->|No| J[テーマ更新]
    I --> J
    J --> K{_windowCwdToast != nullptr?}
    K -->|Yes| L[Toast::Open 呼び出し]
    K -->|No| M[表示スキップ]
    L --> N[3秒後自動消去]
    M --> O[終了]
    N --> O
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（データベースは使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| XAML要素未発見 | FindName(L"WindowCwdToast") が null を返す場合 | Toast が生成されず、通知は表示されない（サイレント失敗） |
| 弱参照消失 | Toast::Open 内のタイマーコールバック実行時にオブジェクトが破棄済み | weak_ptr.lock() が失敗し安全にスキップ |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限 | 特になし |

### 配信時間帯

制限なし

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

ファイルシステムのパス情報が表示されるため、スクリーンシェアリング等の画面共有環境では注意が必要である。ただし、デバッグ機能有効時のみ動作するため、通常の利用では表示されない。

## 備考

- 本通知はデバッグ専用機能であり、`DebugFeaturesEnabled` 設定が `true` の場合のみアクションが処理される。
- WindowIdToast とは異なり、`IsLightDismissEnabled` はコード上で `false` に変更されない。これは単一目的（CWD表示）の通知であり、マルチウィンドウとの干渉が問題にならないためと考えられる。
- 自動消去時間は Toast クラス共通の3秒（ToastDuration）。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Toast.h | `src/cascadia/TerminalApp/Toast.h` | Toast クラスの構造（行29-38） |
| 1-2 | Toast.cpp | `src/cascadia/TerminalApp/Toast.cpp` | ToastDuration と Open() の実装（行12, 27-40） |

**読解のコツ**: WindowIdToast と同じ Toast クラスを利用する。クラス自体の理解は No.1 と共通。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | `_HandleDisplayWorkingDirectory` メソッド（行1087-1094）。DebugFeaturesEnabled のチェックを確認 |

**主要処理フロー**:
1. **行1090**: `_settings.GlobalSettings().DebugFeaturesEnabled()` をチェック
2. **行1092**: 有効な場合のみ `ShowTerminalWorkingDirectory()` を呼び出す

#### Step 3: Toast 表示処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | `ShowTerminalWorkingDirectory()` メソッド（行4545-4564）。遅延ロード、Toast 初期化、Open を実行 |

**主要処理フロー**:
- **行4549**: `_windowCwdToast` が null かチェック（初回のみ初期化）
- **行4551**: `FindName` で XAML の `WindowCwdToast` TeachingTip を遅延ロード
- **行4553**: `std::make_shared<Toast>(tip)` で Toast オブジェクトを生成
- **行4556**: `tip.Closed` コールバックに `_FocusActiveControl` を登録
- **行4559**: テーマを更新
- **行4563**: `_windowCwdToast->Open()` でトーストを表示

#### Step 4: XAML定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TerminalPage.xaml | `src/cascadia/TerminalApp/TerminalPage.xaml` | `WindowCwdToast` TeachingTip の定義（行208-212）。Title のバインディングを確認 |

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

```
ユーザーアクション (displayWorkingDirectory)
    |
    +-- AppActionHandlers::_HandleDisplayWorkingDirectory (行1087)
           |
           +-- [DebugFeaturesEnabled チェック] (行1090)
           |
           +-- TerminalPage::ShowTerminalWorkingDirectory() (行4545)
                  |
                  +-- FindName("WindowCwdToast") ... 初回のみ (行4551)
                  |      |
                  |      +-- std::make_shared<Toast>(tip) (行4553)
                  |      +-- tip.Closed += _FocusActiveControl (行4556)
                  |
                  +-- _UpdateTeachingTipTheme() (行4559)
                  |
                  +-- Toast::Open() (行4563)
                         |
                         +-- TeachingTip.IsOpen(true)
                         +-- タイマー開始（3秒後に自動消去）
```

### データフロー図

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

displayWorkingDirectory  TerminalPage::ShowTerminalWorkingDirectory()  TeachingTip 表示
アクション         --->  Toast オブジェクト初期化・Open          --->   (3秒後自動消去)

WindowProperties         x:Bind (XAML DataBinding)                     Title: VirtualWorkingDirectory
.VirtualWorkingDirectory --> TerminalPage.xaml TeachingTip         -->
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Toast.h | `src/cascadia/TerminalApp/Toast.h` | ソース | Toast ヘルパークラスのヘッダ定義 |
| Toast.cpp | `src/cascadia/TerminalApp/Toast.cpp` | ソース | Toast クラスの実装 |
| TerminalPage.xaml | `src/cascadia/TerminalApp/TerminalPage.xaml` | XAML | WindowCwdToast TeachingTip のUI定義 |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース | ShowTerminalWorkingDirectory() の実装 |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ソース | _windowCwdToast メンバの宣言 |
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleDisplayWorkingDirectory アクションハンドラ |
