v0.14.0

.gitignore

@@ -16,5 +16,7 @@ Cargo.lock
 # Ignore GIF files in the tapes directory
 tapes/*.gif
 
-# Ignore test artifacts emitted by zsh-render-parity integration tests
-zsh-render-parity/.artifacts/
+# Keep tape fixtures under version control
+!tapes/*.csv
+!tapes/*.json
+!tapes/*.yaml

AGENTS.md

@@ -23,7 +23,7 @@ built on top of [crossterm](https://github.com/crossterm-rs/crossterm).
 
 ## Workspace Map (High Level)
 
-- `promkit/`: public prompt presets and `Prompt` lifecycle
+- `promkit/`: optional `Prompt` lifecycle runtime, capabilities, and widget facade
 - `promkit-core/`: rendering primitives and terminal drawing
 - `promkit-widgets/`: reusable widget states
 - `promkit-derive/`: proc macros
@@ -34,29 +34,59 @@ built on top of [crossterm](https://github.com/crossterm-rs/crossterm).
 
 The authoritative model is in [Concept.md](./Concept.md). Keep these boundaries:
 
-1. Event orchestration belongs to `promkit` (`Prompt` lifecycle).
-2. `promkit-widgets` is state-to-view projection, without event-loop policy.
-3. Rendering concerns belong to `promkit-core`.
+1. The `Prompt` lifecycle and terminal event stream belong to `promkit`.
+2. Key bindings, focus transitions, and other event policy belong to application
+   `Prompt` implementations, including the examples.
+3. `promkit-widgets` is state-to-view projection, without event-loop policy.
+4. Rendering concerns belong to `promkit-core`.
 
 When adding features, preserve these boundaries before optimizing code layout.
 
 ## Coding Conventions
 
+### Test Organization
+
+- Name the outer inline test module `tests`.
+- Group tests under a module named after the function or method under test.
+- When a file defines multiple production types, add a type-level module before
+  the function-level module.
+- Name test functions after the behavior or scenario being verified. Do not use
+  generic names such as `test` or repeat the function name in a `test_*` prefix.
+
+For example:
+
+```rust
+#[cfg(test)]
+mod tests {
+    mod widget_viewport {
+        mod scroll_to_include {
+            #[test]
+            fn does_not_scroll_while_the_position_is_visible() {
+                // ...
+            }
+        }
+    }
+}
+```
+
 ### Feature Wiring
 
 - Control module exposure via feature flags.
-  - Evidence: [promkit-widgets/src/lib.rs](./promkit-widgets/src/lib.rs), [promkit/src/preset.rs](./promkit/src/preset.rs)
+  - Evidence: [promkit-widgets/src/lib.rs](./promkit-widgets/src/lib.rs), [promkit/src/lib.rs](./promkit/src/lib.rs)
 - Wire `promkit` features to `promkit-widgets` features.
   - Evidence: [promkit/Cargo.toml](./promkit/Cargo.toml), [promkit-widgets/Cargo.toml](./promkit-widgets/Cargo.toml)
 
 ## Change Workflow for Agents
 
 When implementing a change:
 
-1. Locate the boundary first (`promkit` vs `promkit-widgets` vs `promkit-core`).
+1. Locate the boundary first (application vs `promkit` vs `promkit-widgets` vs
+   `promkit-core`).
 2. Make the smallest coherent edit set.
 3. Update tests/examples/docs that demonstrate behavior.
 4. Run validation commands locally when possible.
+5. For non-trivial implementation work, run the relevant `cargo bench` target
+   before and after the change and check for performance regressions.
 
 Recommended commands:
 
@@ -68,6 +98,25 @@ cargo test -- --nocapture --format pretty
 
 For broader changes, also build example crates.
 
+### Performance Validation
+
+- Benchmark new widgets, data structures, rendering paths, algorithms, and other
+  substantial implementations.
+- Compare against a pre-change result, using Criterion named baselines when the
+  relevant benchmark supports them.
+- Investigate and report meaningful regressions instead of relying only on a
+  successful benchmark run.
+- Documentation-only edits, formatting, and small changes outside
+  performance-sensitive paths may omit benchmarks. Small changes to hot paths
+  still require benchmark comparison.
+
+Select the benchmark and feature flags documented by the relevant crate. A
+typical invocation is:
+
+```bash
+cargo bench -p <crate> --bench <target> --features <features>
+```
+
 ## What Not to Put Here
 
 - Exhaustive feature tables copied from `Cargo.toml`

Cargo.toml

@@ -12,12 +12,13 @@ members = [
 [workspace.dependencies]
 anyhow = "1.0.102"
 async-trait = "0.1.89"
+bitflags = "2.9.0"
 crossbeam-skiplist = "0.1.3"
 crossterm = { version = "0.29.0", features = ["use-dev-tty", "event-stream", "serde"] }
+csv = "1.3.1"
 futures = "0.3.32"
 radix_trie = "0.3.0"
 rayon = "1.11.0"
-scopeguard = "1.2.0"
 serde = "1.0.228"
 serde_json = { version = "1.0.149", features = ["preserve_order"] }
 serde_yaml = "0.9.34"

Concept.md

@@ -1,44 +1,98 @@
 # Concept
 
+## Direction Since v0.14.0
+
+Starting with v0.14.0, promkit is developed around two primary goals:
+
+1. Expand `promkit-widgets` with reusable state and view projections that
+   applications can combine without adopting a framework-owned event policy.
+2. Improve `promkit-core` rendering performance and correctness so wrapping,
+   resizing, scrolling, viewport movement, and repeated redraws remain stable
+   without leaving stale or visually corrupted terminal content.
+
+This direction emerged from a feedback loop between the library and applications
+built with it, including [jnv](https://github.com/ynqa/jnv) and
+[sig](https://github.com/ynqa/sig). Those applications showed that a useful
+terminal UI eventually needs an application-specific runtime and event loop.
+Modes, key bindings, focus, background work, cancellation, validation, and
+domain state transitions cannot be generalized into prompt presets without
+constraining the application or adding increasingly application-specific
+configuration.
+
+The resulting development loop is:
+
+1. Application development exposes rendering, state, and interaction needs.
+2. Reusable state-to-view behavior is extracted into `promkit-widgets`.
+3. Rendering correctness and performance improvements are made in
+   `promkit-core` and verified against regression scenarios and benchmarks.
+4. Application-specific orchestration remains in the application, while
+   examples document useful compositions.
+
+For this reason, the `promkit` crate no longer owns preset implementations.
+It provides an optional `Prompt` lifecycle runtime, capabilities, and a widget
+facade for applications that find them useful, but it is not intended to replace
+an application's event loop. Removing presets is therefore not only a code
+reorganization; it establishes application-owned orchestration as the project
+direction from v0.14.0 onward.
+
 ## Responsibility Boundaries and Data Flow
 
-promkit is organized around three responsibilities with clear boundaries:
+promkit is organized around four responsibilities with clear boundaries:
 
-1. **Event orchestration (`promkit`)**
-   - [`Prompt`](./promkit/src/lib.rs) defines lifecycle hooks:
+1. **Prompt lifecycle runtime (`promkit`)**
+   - [`Prompt`](./promkit/src/runtime.rs) defines lifecycle hooks:
      `initialize -> evaluate -> finalize`
-   - [`Prompt::run`](./promkit/src/lib.rs) manages terminal setup/teardown
-     (raw mode, cursor visibility) and drives input events from a singleton
-     `EVENT_STREAM`.
+   - [`Prompt::run`](./promkit/src/runtime.rs) drives input events from a
+     singleton `EVENT_STREAM`.
+   - `TerminalSession` manages opt-in terminal setup/teardown separately from
+     the prompt lifecycle.
    - Events are processed sequentially.
 
-2. **State management and UI materialization (`promkit-widgets` + `promkit-core`)**
+2. **Application event policy (`examples` and downstream applications)**
+   - Applications implement `Prompt` by combining the widget states they need.
+   - Key bindings, focus transitions, validation flow, and quit conditions stay
+     in the application.
+   - The examples are reference compositions, not APIs exported by `promkit`.
+
+3. **State management and UI materialization (`promkit-widgets`)**
    - Each widget state implements [`Widget`](./promkit-core/src/lib.rs).
-   - `Widget::create_graphemes(width, height)` returns
-     [`StyledGraphemes`](./promkit-core/src/grapheme.rs), which is the render-ready
-     text unit including style and line breaks.
+   - `Widget::create_graphemes()` returns `CreatedGraphemes`: width-independent
+     styled content, layout hints, and an optional logical cursor position.
+   - Large widgets can override `create_graphemes_in_viewport(width, height)` to
+     project only content that can be displayed. Prompts that use this path
+     obtain the current terminal size before updating the renderer.
    - Widget states focus on state and projection only.
 
 > [!IMPORTANT]
 > Widgets intentionally do not own event-loop policies.
-> Event handling stays in presets or custom `Prompt` implementations,
+> Event handling stays in application `Prompt` implementations,
 > which avoids key-binding conflicts when multiple widgets are combined.
 
-3. **Rendering (`promkit-core`)**
-   - [`Renderer<K>`](./promkit-core/src/render.rs) stores ordered grapheme chunks in
-     `SkipMap<K, StyledGraphemes>`.
+4. **Rendering (`promkit-core`)**
+   - [`Renderer<K>`](./promkit-core/src/render.rs) stores ordered
+     `CreatedGraphemes` chunks.
+   - [`RendererLayout<K>`](./promkit-core/src/render/layout.rs) performs
+     terminal-size-dependent wrapping, pane allocation, cursor scrolling, and
+     viewport clipping without terminal I/O.
    - `update` / `remove` modify chunks by index key.
+   - `render` wraps or truncates content, assigns vertical viewports, scrolls
+     viewports to include logical cursors, and saves a keyed layout snapshot.
+   - The layout snapshot supports screen-to-widget hit testing and the inverse
+     widget-to-screen position mapping.
    - `render` delegates drawing to [`Terminal`](./promkit-core/src/terminal.rs).
-   - `Terminal::draw` performs wrapping, clearing, printing, and scrolling.
+   - `Terminal::draw_rows` performs clearing, printing, and terminal scrolling
+     after layout is complete.
 
 This keeps responsibilities explicit:
-- prompt = control flow
+- runtime = prompt lifecycle and terminal event stream
+- terminal session = terminal mode lifecycle
+- application prompt = event and focus policy
 - widgets = state to graphemes
 - core renderer = terminal output
 
 ## Event Loop
 
-Current core loop in [`Prompt::run`](./promkit/src/lib.rs):
+Current core loop in [`Prompt::run`](./promkit/src/runtime.rs):
 
 ```rust
 self.initialize().await?;
@@ -74,7 +128,7 @@ flowchart LR
         Continue -->|Continue| Observe
     end
 
-    subgraph Preset["promkit presets / custom prompt"]
+    subgraph Application["application prompt / examples"]
         Eval --> UpdateState[Update widget states]
         UpdateState --> Build[Widget::create_graphemes]
         Build --> Push[Renderer::update]
@@ -87,73 +141,32 @@ flowchart LR
 
 ## Customizability
 
-promkit supports customization at two levels.
-
-### 1. Configure existing presets
-
-High-level presets (e.g. `Readline`) expose builder-style options such as:
-
-- title and style
-- prefix and cursor styles
-- suggestion and history
-- masking
-- word-break characters
-- validator
-- text editor visible line count
-- evaluator override
-
-```rust
-use std::collections::HashSet;
-
-use promkit::{
-    Prompt,
-    core::crossterm::style::{Color, ContentStyle},
-    preset::readline::Readline,
-    suggest::Suggest,
-};
-
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
-    let result = Readline::default()
-        .title("Custom Title")
-        .prefix("$ ")
-        .prefix_style(ContentStyle {
-            foreground_color: Some(Color::DarkRed),
-            ..Default::default()
-        })
-        .active_char_style(ContentStyle {
-            background_color: Some(Color::DarkCyan),
-            ..Default::default()
-        })
-        .inactive_char_style(ContentStyle::default())
-        .enable_suggest(Suggest::from_iter(["option1", "option2"]))
-        .enable_history()
-        .mask('*')
-        .word_break_chars(HashSet::from([' ', '-']))
-        .text_editor_lines(3)
-        .validator(
-            |text| text.len() > 3,
-            |text| format!("Please enter more than 3 characters (current: {})", text.len()),
-        )
-        .run()
-        .await?;
-
-    println!("result: {result}");
-    Ok(())
-}
+Applications select the capabilities and widgets they need through Cargo
+features. The runtime is independent from the widget set:
+
+```toml
+promkit = { version = "0.14.0", features = [
+  "runtime",
+  "validate",
+  "prefixsearch",
+  "text",
+  "texteditor",
+] }
 ```
 
-### 2. Build your own prompt
-
-For advanced use cases, combine your own state + evaluator + renderer.
+The application then combines its own state, event policy, and renderer:
 
-- Implement `Widget` for custom state projection
+- Use the widget states required by the application
 - Implement `Prompt` for lifecycle and event handling
 - Use `Renderer::update(...).render().await` whenever UI should change
 
-This is the same pattern used in [`examples/byop`](./examples/byop/src/byop.rs),
-including async background updates (e.g. spinner/task monitor) that push
-grapheme updates directly to the shared renderer.
+The examples are the reference implementations for these compositions.
+[`examples/readline`](./examples/readline/) combines text, text-editor, and
+prefix-search widgets with validation. `PrefixSearch` retains its radix trie,
+active query, and selection as widget state and projects matching candidates
+directly without repackaging them into a listbox.
+[`examples/async_task`](./examples/async_task/) demonstrates background updates
+that push grapheme changes directly to a shared renderer.
 
 ## Quality Strategy for Rendering Behavior