# ClipboardImageHelper 仕様書(ドラフト)

## コンセプト

クリップボードに画像やテキストしか入っていないとき、Explorer(デスクトップ・フォルダー)へ
Ctrl+V してもファイルとして貼り付けられない。本アプリはクリップボードを常駐監視し、
画像・テキストがコピーされた瞬間に **CF_HDROP(ファイルリスト)形式を追加**することで、
**OS 標準の貼り付け操作がそのままファイル貼り付けとして機能する**ようにする。

- ユーザーが覚える操作はゼロ(コピーしたら、フォルダーに Ctrl+V するだけ)
- 元の形式(画像・テキスト・HTML 等)は保持するので、通常のアプリへの貼り付けは従来通り
- PowerToys Advanced Paste は専用 UI 経由だが、本アプリは「素の Ctrl+V」で完結するのが差別化点

## 動作フロー

1. `AddClipboardFormatListener` で `WM_CLIPBOARDUPDATE` を受信
2. 判定:
   - 自分の書き換え(マーカー形式あり)→ 無視(ループ防止)
   - すでに CF_HDROP がある(通常のファイルコピー)→ 無視
   - 画像 or テキストがある → 処理対象
3. ステージングフォルダーへ実体ファイルを書き出す
   - 画像: PNG(`Clipboard 2026-07-04 163012.png`)
   - テキスト: UTF-8 の .txt(`Clipboard 2026-07-04 163012.txt`)
4. クリップボードを再セット:
   - 元の形式をすべて保持(可能な範囲でコピー)
   - CF_HDROP(書き出したファイルのパス)を追加
   - 自前マーカー形式を追加(ループ防止用)
   - `CanIncludeInClipboardHistory = 0` を付けて Win+V 履歴の重複を防ぐ

## ステージングフォルダー

- 既定: `%LOCALAPPDATA%\ClipboardImageHelper\Staging`(設定で変更可)
- 自動クリーンアップ: 起動時+定期的に「7日より古い or 直近100件を超えるファイル」を削除(閾値は設定可)
- サイズ上限: 既定 50MB を超えるデータはファイル化しない(巨大画像コピーでの引っかかり防止)

## 設定(トレイ → 設定ウィンドウ)

| 項目 | 既定値 |
|---|---|
| 画像をファイル化 | オン |
| テキストをファイル化 | オン |
| 一時停止(トレイから即トグル) | — |
| ステージングフォルダー | %LOCALAPPDATA%\...\Staging |
| ファイル名パターン | `Clipboard {timestamp}` |
| 画像形式 | PNG(将来: JPEG/WebP 選択) |
| 保持期間/件数 | 7日 / 100件 |
| スタートアップ登録 | オフ |

## 技術構成

- WinUI 3(Windows App SDK)+ タスクトレイ常駐(XTimelineViewer の構成を踏襲)
- クリップボード読み書き:
  - 第一候補: WinRT `Clipboard` / `DataPackage`(`SetStorageItems` で HDROP 相当、
    `SetData` で元形式の引き継ぎ)。実装が簡潔でメモリ管理が安全
  - WinRT で形式の保持に不足が出た場合のみ Win32 P/Invoke(`OpenClipboard` /
    `EnumClipboardFormats` / `SetClipboardData`)へ切り替え
- 配布: 自己署名 MSIX + GitHub Releases + winget(Store 提出・有料署名は不要)

## 既知のリスクと対策

| リスク | 対策 |
|---|---|
| 貼り付け先アプリが HDROP を優先し挙動が変わる(例: Outlook がインライン画像でなく添付にする) | トレイの「一時停止」で即回避。問題アプリが多ければ除外リスト機能を検討 |
| テキストのファイル化でパスワード等がディスクに残る | 設定でテキストをオフにできる。クリーンアップで自動削除。README に明記 |
| クリップボード所有権を奪うことで元アプリの遅延レンダリングが失効 | 再セット前に主要形式を実体化してコピー。取得できない私有形式は諦める(実害を検証) |
| 書き換えループ | 自前マーカー形式+クリップボードシーケンス番号で二重ガード |
| Win+V 履歴の重複 | `CanIncludeInClipboardHistory = 0` を再セット時に付与 |

## MVP スコープ

1. トレイ常駐+クリップボード監視+画像/テキストの HDROP 追加
2. ステージングフォルダーと自動クリーンアップ
3. 設定ウィンドウ(オン/オフ、一時停止、フォルダー変更)

### 後回し(v2 以降)

- 画像形式の選択(JPEG/WebP)、リサイズ・モザイク等の加工
- アプリ別除外リスト
- 遅延レンダリング方式(貼り付け時に初めてファイル生成)への切り替え

## 検証項目(リリース前)

- 貼り付け先: Explorer(デスクトップ/フォルダー/ZIP 内)、Word、Outlook、Excel、
  ペイント、Slack/Discord、ブラウザーのフォーム、VS Code
- コピー元: Snipping Tool、ブラウザー画像コピー、Excel セル、スクリーンショット(PrtScr)
- Win+V 履歴・クラウドクリップボード(同期)との相性
- 高頻度コピー時の競合(OpenClipboard の失敗リトライ)