@@ -0,0 +1,190 @@
+# preset の今後の方針
+
+> [!NOTE]
+> この文書は設計上の提案です。現状と推奨方針を整理するものであり、この文書だけをもって公開 API を非推奨化・削除するものではありません。
+
+## 背景
+
+promkit は今後、再利用可能な widget を増やすことを中心に発展させたいと考えています。現在の workspace は、主に次の3レイヤーで構成されています。
+
+- [`promkit-core`](./promkit-core/): 描画、レイアウト、terminal への出力、hit testing
+- [`promkit-widgets`](./promkit-widgets/): widget の状態と、状態から view への projection
+- [`promkit`](./promkit/): `Prompt` のライフサイクルと高レベルな preset
+
+現在の責務境界は [`Concept.md`](./Concept.md) に記載されています。特に、widget は event loop のポリシーを持たず、event をどの操作に対応づけるかは application または preset が決定する設計です。
+
+## 現状
+
+### preset は複数のポリシーを一体化している
+
+preset は単なる widget の alias ではありません。一般に、次の要素をまとめて提供しています。
+
+- widget の構築とデフォルトの style
+- key と mouse の binding
+- renderer の初期化と更新
+- terminal size の取り扱い
+- 終了条件とエラー条件
+- 最終的な返り値
+- widget の一部の設定を公開する builder method
+
+これは one-shot prompt としては便利ですが、各 preset が固有の公開 API を持つ E2E の UI 実装になることも意味します。
+
+### widget と preset は一対一である必要がない
+
+現在の feature 定義でも、widget と preset は一対一ではありません。たとえば `spinner` と `table` は `promkit` の feature として公開されていますが、対応する preset module はありません。
+
+したがって、widget を追加するたびに preset の設計、実装、ドキュメント、保守まで必須にする必要はありません。
+
+### preset は widget API の一部を重複して公開している
+
+widget に設定項目を追加した場合、それを preset から利用可能にするために、builder method、ドキュメント、転送処理のテストを追加することがあります。このため、widget 本体とは別に、同期が必要な第二の API surface が生まれます。
+
+このコストは widget と設定項目の増加に比例して大きくなります。preset 固有の振る舞いが少ない場合でも同様です。
+
+### 組み込みの event loop が対象とする範囲は狭い
+
+[`Prompt::run`](./promkit/src/lib.rs) は、単純で逐次的な prompt には有用です。terminal の setup と teardown を行い、singleton の event stream から event を読み、終了するまで一つの prompt に渡します。
+
+一方、規模の大きな terminal application では、次のような application 固有の制御が必要になります。
+
+- 複数 component 間の focus 管理
+- background task と channel
+- terminal event と application event を処理する `tokio::select!`
+- resize event の明示的な処理
+- 設定可能な key binding
+- alternate screen の切り替え
+- application 固有の終了処理とエラー処理
+
+[`csv` example](./examples/csv/) は、単純な `Prompt` lifecycle を利用しつつ、widget 固有の振る舞いを preset の外側で実装しています。[`repl` example](./examples/repl/) と [jnv](https://github.com/ynqa/jnv) は、さらに進んで独自の event loop を構築しています。
+
+これらすべての application model を `Prompt::run` に取り込もうとすると、promkit は汎用 TUI framework に近づきます。その結果、高レベルな `promkit` crate の実装コストが増える一方で、widget の再利用性には必ずしも寄与しません。
+
+## 評価
+
+現在の preset model は、widget を中心に機能を増やしていく方針とは相性がよくありません。
+
+問題は preset が存在すること自体ではなく、すべての有用な widget に対して安定した E2E の preset も提供すべきだという期待です。この期待により、widget の追加が次の要素と結びつきます。
+
+- 特定の event loop
+- 特定の操作ポリシー
+- 重複した設定 API
+- 追加の example と regression test
+
+複数の操作モデルに参加できる widget や、高度な利用者を対象とする場合は、application 側で widget を組み立てる方が適しています。
+
+## 推奨方針
+
+### widget ごとの preset を必須にしない
+
+新しい widget は、対応する `promkit::preset` module がなくても、`promkit-widgets` と `promkit-core` から完全に利用できる状態を目指します。
+
+widget の実装では、主に次を完成条件とします。
+
+- 状態遷移と意味的な操作
+- 状態から view への projection
+- 必要に応じた viewport の処理
+- 必要に応じた hit testing
+- 対象を絞った unit test と rendering test
+
+デフォルトの event loop や key binding 自体が開発対象でない限り、それらを widget の完成条件には含めません。
+
+### E2E の組み立ては recipe に移す
+
+デフォルトの key binding や完全な対話フローは、主に compile・test される example として提供します。example であれば、特定の方針を持つ構成を示しつつ、それを永続的な library abstraction にする必要がありません。
+
+recipe では、少なくとも次の二つの integration level を扱います。
+
+1. CSV viewer のように、単純な `Prompt` lifecycle を利用する小規模な application
+2. REPL のように、`promkit-core` と `promkit-widgets` を利用して独自の event loop を構築する application
+
+### 複雑な application に合わせて組み込み loop を汎用化しない
+
+組み込みの event loop は、逐次的な one-shot interaction のための小さな convenience API として残せます。ただし、jnv のような application まで表現できるように汎用化することは目指しません。
+
+複雑な application は、crossterm、Tokio、channel、promkit の描画 primitive を直接組み合わせられる状態を維持します。
+
+### 小さく、ポリシーを持たない支援 API を優先する
+
+example 間で機械的なコードの重複が確認できた場合は、次のような限定的な helper の抽出を検討します。
+
+- raw mode、cursor visibility、mouse capture、alternate screen を復元する RAII terminal session guard
+- 特定の action を割り当てず、共通する key press の形だけを判定する helper
+- terminal backend の差異に対応する event normalization utility
+- 単純な runner に event source を注入する仕組み
+- 使用例の蓄積によって安定した境界が確認できた場合の、小さな renderer 初期化・更新 helper
+
+これらの helper は terminal と event の plumbing を減らすものであり、どの key で widget を移動、選択、確定、終了させるかは決定しません。
+
+## 目標とする責務境界
+
+### `promkit-core`
+
+- terminal の描画と復元に関する primitive
+- layout と viewport の計算
+- renderer の保持と更新
+- hit testing と座標変換
+
+### `promkit-widgets`
+
+- widget の状態
+- 移動、toggle、挿入、scroll などの意味的な状態操作
+- 状態から grapheme への projection
+- widget 固有の設定
+
+widget は引き続き、event loop とデフォルトの global key binding を所有しません。
+
+### `promkit`
+
+- 単純な prompt のための、任意で利用できる小さな runtime
+- 明確な価値がある場合の re-export または integration helper
+- widget ごとの E2E wrapper は提供要件としない
+
+### `examples`
+
+- 完全な event mapping
+- 複数 widget の組み立て
+- application の終了ポリシー
+- terminal mode の選択
+- 単純な application と高度な application の実用的な recipe
+
+## プロダクト上のトレードオフ
+
+preset を削除すると、`Readline`、`Confirm`、`Password` のように、少量のコードで結果を取得できる利便性も失われます。これらは、一貫した one-shot のユーザー体験を表現しているため、viewer 系の preset よりも独立したプロダクトとしての性質が強いものです。
+
+すべての preset を削除する前に、次のどちらを目指すか明示的に決める必要があります。
+
+- **toolkit のみにする:** E2E の prompt API の保守を終了し、すべての操作ポリシーを example に移す
+- **二層構成にする:** widget ごとの preset は約束せず、少数の one-shot prompt のみを、必要であれば別 crate で維持する
+
+widget を中心とし、E2E の prompt behavior を保守しない方針であれば、長期的には toolkit のみにする方が責務境界は明確です。preset を別 crate に移す方法は利用者の利便性を維持できますが、保守コストの多くも残ります。
+
+## 移行時の考慮事項
+
+preset の削除は `promkit/src/preset/` directory だけでは完結しません。
+
+- README の example は、現在 preset を主要機能として紹介しています。
+- `promkit/Cargo.toml` の feature wiring には、preset の feature と widget の forwarding feature が混在しています。
+- `suggest` と `validate` は主に Readline 関連の preset から使われているため、移動先または代替が必要です。
+- [`promkit-derive`](./promkit-derive/) は `promkit::preset::form::Form` を直接構築するコードを生成しています。
+- Readline の terminal regression test は、現在 preset API を対象にしています。
+
+これらは preset directory だけを削除するのではなく、意図的な breaking change の一部として対応する必要があります。
+
+## 移行手順案
+
+1. widget の追加に preset の追加は必須ではないことを明文化する
+2. JSON、Listbox、Readline などの代表的な example を、widget を直接組み立てる形に変更する
+3. それらの example から機械的な重複を特定し、安定した、ポリシーを持たない helper だけを抽出する
+4. one-shot prompt をサポート対象として残すか決定する
+5. preset API を非推奨化し、同等の recipe を示す migration guide を公開する
+6. `promkit-derive` を再設計または終了し、preset 固有の support module を移動する
+7. 明示的な breaking release で preset を削除し、feature wiring を単純化する
+8. 目標とする architecture が実装された時点で [`Concept.md`](./Concept.md) と README を更新する
+
+## 対象外
+
+- すべての widget にデフォルトの preset を提供すること
+- key binding のポリシーを widget state に移すこと
+- `Prompt::run` ですべての非同期 TUI architecture を扱うこと
+- example を安定した公開 API として扱うこと
+- 利用例の重複から有用な境界が確認できる前に helper を抽出すること