# Plan: 高速化最優先ロードマップ

更新日: 2026-04-06

## 方針
- 最優先は処理高速化と体感遅延の削減。
- 既存機能の品質を崩さないことを前提に、性能回帰は即時停止・即時ロールバックする。
- README系のTODOは単一計画で管理し、速度改善タスクを常に先頭レーンに固定する。

## 現在の進捗サマリ

### 完了済み
- input.rs: デバウンス判定とナビゲーション処理の重複削減（約60行削減）。
- state.rs: ViewerStateの責務分割（God Object分割完了）。
- render/image.rs 分離案: 性能劣化のため撤回し、旧実装へ復帰。

### 進行前（高速化の主対象）
- smolによる非同期画像処理。
- image resizeの標準経路化（大画像の転送前縮小）。
- RGBAキャッシュ強化（再デコード抑止）。
- u32チャンク比較（差分判定ホットループの最適化）。
- タイルグリッドのセル倍数整列。
- dirty_ratio 2段階フォールバック（差分タイル上書き / フルフレーム送信）。
- ACK（a=q）によるバックプレッシャー制御。

### 後段（速度優先フェーズ完了後）
- キーバインドのユーザー定義。
- 簡易ファイル操作（削除/リネーム/移動）。
- optional: rayon による並列差分判定。
- optional: memmap2 によるメモリマップ I/O。

## 性能ゲート（全フェーズ共通）
1. 変更前にベースラインを取得する。
2. 小画像・大画像・連打操作で3回測定し、中央値で評価する。
3. 2倍以上の性能低下を検出した変更は即時ロールバックする。
4. 描画時間が16ms〜24msを安定して超える場合は「極めて遅い」扱いとして優先是正する。
5. 各作業単位で cargo check を実行し、ビルド健全性を維持する。

## 優先レーンA: コア高速化（最優先）

### Phase A0: 測定基盤の固定
1. 描画時間・cache hit率・dirty tile数の計測方法を固定する。
2. statusbar/headerでの統計表示フォーマットを定義する。

### Phase A1: 差分判定と転送コスト削減
3. terminal pixel情報を描画入力に追加し、セル/ピクセル換算を一元化する。
4. u32チャンク比較を差分判定経路へ導入する。
5. タイルグリッドをセル倍数へ整列し、差分位置指定を安定化する。
6. image resizeを導入し、大画像の転送前縮小を標準化する。

### Phase A2: UI停止の解消
7. decode→resize→encodeを非同期化し、UIスレッド停止を回避する。
8. RGBAキャッシュを非同期経路に統合し、再デコードを抑止する。
9. dirty_ratio 2段階フォールバックを実装する。
10. ACK（a=q）同期と背圧制御を導入し、フレーム詰まりを抑制する。

### Phase A3: 端末最適化と動画連携境界
11. Wezterm/bcon/Kittyの端末判定レイヤーを整備し、合成方式を分岐する。
12. FrameSource / FrameProcessor / FramePresenter の責務境界を定義する。
13. 実動画デコードは対象外とし、連携API境界の確立を完了条件にする。
14. Wezterm Nightly の `a=T` 透過合成可否を検証し、実測結果を記録する。

## 優先レーンB: UX機能（Aと競合しない範囲で並走）
1. 統計表示の改善（A0完了後に着手）。
2. ソート切替（名前/日付/サイズ）。
3. ズーム・パン・フィットの操作改善。
4. 画像情報オーバーレイ。
5. キーバインド設定化と簡易ファイル操作。

## 検証チェックリスト
1. cargo check。
2. 差分なしケースで不要アップロードが発生しないこと。
3. 大画像でリサイズ適用時に表示品質と速度のバランスが崩れないこと。
4. 非同期化後も入力レスポンスが劣化しないこと。
5. 端末分岐で転送経路が期待どおりに選択されること。
6. Wezterm Nightly の `a=T` 透過合成の動作有無を確認すること。

## 参照（リンク優先）
- README/todo.md: 高速化の未実装項目。
- README/今後のプロジェクト.md: 動画連携と端末分岐の要件。
- REFACTORING_ROADMAP.md: 完了済みリファクタリングの結果。
- AGENTS.md: 開発ポリシーと性能劣化時の判断基準。