# 通知設計書 16-screenハードステータス設定

## 概要

本ドキュメントは、Oh My Zshのターミナルサポート機能における、screen/tmux環境でのハードステータス（ウィンドウ名）を自動設定する通知の設計を記載する。

### 本通知の処理概要

この通知は、screenコマンドのエスケープシーケンス（`\ek...\e\\`）を使用して、screen/tmux環境でのウィンドウ名（ハードステータス）を動的に更新する機能である。通常のターミナルのOSC 1/2とは異なる形式のエスケープシーケンスを使用する。

**業務上の目的・背景**：screenやtmuxはターミナルマルチプレクサとして広く使用されており、複数のウィンドウを同時に管理する。各ウィンドウに適切な名前を設定することで、ウィンドウ一覧やステータスバーで現在の作業内容を把握でき、効率的なウィンドウ切り替えが可能になる。

**通知の送信タイミング**：precmdフック（プロンプト表示前）では現在のディレクトリ名を設定し、preexecフック（コマンド実行前）では実行中のコマンド名を設定する。

**通知の受信者**：screen/tmuxターミナルマルチプレクサ。エスケープシーケンスを解釈してウィンドウ名を更新する。

**通知内容の概要**：アイドル時は「%15<..<%~%<<」形式（例：ディレクトリ名を15文字以内で表示）、コマンド実行時はコマンド名（例：「git」）がウィンドウ名として設定される。

**期待されるアクション**：screen/tmuxがエスケープシーケンスを解釈し、ウィンドウ名を更新する。ユーザーはウィンドウ一覧（Ctrl-a "やtmux list-windows）やステータスバーで現在の作業内容を確認できる。

## 通知種別

ターミナルエスケープシーケンス（screenハードステータス）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（フック実行時に即座に送信） |
| 優先度 | 低（表示最適化のための補助機能） |
| リトライ | なし |

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

$TERMがscreen*またはtmux*の場合にのみエスケープシーケンスを出力する。

## 通知テンプレート

### エスケープシーケンス形式

| 項目 | 内容 |
|-----|------|
| 送信元 | termsupport.zsh |
| エスケープシーケンス | `\ek${title}\e\\` |
| 対応環境 | screen, tmux |

### 本文テンプレート

#### アイドル時（precmd）

```
\ek%15<..<%~%<<\e\\
```

展開例：`\ek~/project\e\\`

#### コマンド実行時（preexec）

```
\ek${CMD}\e\\
```

展開例：`\ekgit\e\\`

### エスケープシーケンスの詳細

| シーケンス | 意味 |
|-----------|------|
| `\ek` | screen/tmuxウィンドウ名設定の開始（ESC k） |
| `\e\\` | String Terminator（ST）- シーケンスの終了 |

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | エスケープシーケンスのため添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| %~ | カレントディレクトリ（~展開） | $PWD | Yes |
| ZSH_THEME_TERM_TAB_TITLE_IDLE | アイドル時タイトルフォーマット | 設定/デフォルト | No |
| CMD | コマンド名（sudo/ssh等を除く） | preexecの第1引数から抽出 | No（preexecのみ） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| フック | precmd | DISABLE_AUTO_TITLE != true かつ $TERM = screen*/tmux* | プロンプト表示前 |
| フック | preexec | DISABLE_AUTO_TITLE != true かつ $TERM = screen*/tmux* | コマンド実行前 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| DISABLE_AUTO_TITLE=true | タイトル自動設定を無効化 |
| INSIDE_EMACS != "" && != vterm | Emacs内（vtermを除く）では設定しない |
| $TERM != screen*/tmux* | screen/tmux以外では出力しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[precmd/preexecフック実行] --> B{DISABLE_AUTO_TITLE?}
    B -->|true| C[処理終了]
    B -->|false| D{INSIDE_EMACS?}
    D -->|Yes かつ != vterm| C
    D -->|No または vterm| E[title関数呼び出し]
    E --> F{$TERM判定}
    F -->|xterm等| G[OSC 1/2で設定]
    F -->|screen*/tmux*| H[screenハードステータス設定]
    F -->|その他| I[その他の処理]
    H --> J[\ek${title}\e\\を出力]
    J --> K[終了]
    G --> K
    I --> K
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | データベースは使用しない |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | データベースは使用しない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 環境非対応 | screen/tmux以外で実行 | エスケープシーケンスは出力されない |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | フックごとに1回のみ実行 |

### 配信時間帯

制限なし（フック実行時に即座に送信）

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

- タイトルにはディレクトリパスやコマンド名が含まれる
- screen/tmuxのステータスバーに表示されるため、スクリーンショット等で注意
- `${1:q}`によるクォート処理でエスケープシーケンスインジェクションを防止

## 備考

- screenハードステータスはOSC 1（タブタイトル）と同様のフォーマット変数を使用
- screen環境ではウィンドウタイトルとタブタイトルの概念がないため、ハードステータスのみ設定
- tmuxでも同じエスケープシーケンスが使用可能

---

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

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

### 推奨読解順序

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

まず、screen/tmux環境の判定と使用するフォーマット変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | termsupport.zsh | `lib/termsupport.zsh` | タブタイトルフォーマット変数の定義（41行目） |

**読解のコツ**: screenハードステータスはタブタイトルと同じフォーマット（第1引数）を使用する。

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

処理の起点となるtitle関数のscreen分岐を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | termsupport.zsh | `lib/termsupport.zsh` | title関数（9-39行目） |

**主要処理フロー**:
1. **24行目**: `screen*|tmux*)`パターンでマッチ
2. **25行目**: `print -Pn "\ek${1:q}\e\\"` でハードステータス設定

#### Step 3: エスケープシーケンスの詳細を理解する

screenのエスケープシーケンス形式を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | termsupport.zsh | `lib/termsupport.zsh` | 25行目のprint文 |

**エスケープシーケンスの解説**:
- `\ek`：ESC k - screenウィンドウ名設定の開始
- `${1:q}`：第1引数をクォート（%等の特殊文字をエスケープ）
- `\e\\`：ESC \ - String Terminator（シーケンス終了）

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

```
シェル起動（screen/tmux内）
    │
    └─ lib/termsupport.zsh (source)
           │
           ├─ add-zsh-hook precmd omz_termsupport_precmd (108行目)
           │      │
           │      └─ omz_termsupport_precmd (49-52行目)
           │             └─ title "$ZSH_THEME_TERM_TAB_TITLE_IDLE" ...
           │                    │
           │                    └─ [screen*/tmux*] print -Pn "\ek${1:q}\e\\" (25行目)
           │
           └─ add-zsh-hook preexec omz_termsupport_preexec (109行目)
                  │
                  └─ omz_termsupport_preexec (55-103行目)
                         │
                         ├─ CMD抽出 (99行目)
                         │
                         └─ title "$CMD" ...
                                │
                                └─ [screen*/tmux*] print -Pn "\ek${1:q}\e\\" (25行目)
```

### データフロー図

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

$TERM ─────────────▶ case分岐 ───────────▶ screen*/tmux*判定
                          │
                          ▼
$PWD ──────────────▶ フォーマット展開 ────▶ \ek..project\e\\
                                                 │
                                                 ▼
                                         screenハードステータス
                                         （ステータスバー表示）

---

コマンドライン ───▶ CMD抽出 ───────────────▶ \ekgit\e\\
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| termsupport.zsh | `lib/termsupport.zsh` | ソース | ターミナルタイトル設定のメイン実装 |
