Merge pull request #74 from ynqa/nopanematrixify

Test and refactor `core` module

Author: ynqa

.gitignore

@@ -15,3 +15,6 @@ 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/

Cargo.toml

@@ -1,12 +1,14 @@
 [workspace]
 resolver = "2"
 members = [
-  "event-dbg",
   "examples/*",
   "promkit",
   "promkit-core",
   "promkit-derive",
   "promkit-widgets",
+  "termharness",
+  "zsh-render-parity",
+  "zsherio",
 ]
 
 [workspace.dependencies]
@@ -15,11 +17,13 @@ async-trait = "0.1.89"
 crossbeam-skiplist = "0.1.3"
 crossterm = { version = "0.29.0", features = ["use-dev-tty", "event-stream", "serde"] }
 futures = "0.3.32"
+portable-pty = "0.9.0"
 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"] }
 termcfg = { version = "0.2.0", features = ["crossterm_0_29_0"] }
 tokio = { version = "1.49.0", features = ["full"] }
+thiserror = "2.0.18"
 unicode-width = "0.2.2"

Concept.md

@@ -1,201 +1,169 @@
 # Concept
 
-## Well-defined boundaries for responsibilities and modularization
+## Responsibility Boundaries and Data Flow
 
-The core design principle of promkit is the clear separation of the following three functions,
-each implemented in dedicated modules:
+promkit is organized around three responsibilities with clear boundaries:
 
-- **Event Handlers**: Define behaviors for keyboard inputs (such as when <kbd>Enter</kbd> is pressed)
-  - **promkit**: Responsible for implementing [Prompt](https://docs.rs/promkit/0.10.0/promkit/trait.Prompt.html) trait, combining widgets and handling corresponding events
-  - The new async `Prompt` trait provides `initialize`, `evaluate`, and `finalize` methods for complete lifecycle management
-  - Event processing is now handled through a singleton `EventStream` for asynchronous event handling
+1. **Event orchestration (`promkit`)**
+   - [`Prompt`](./promkit/src/lib.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`.
+   - Events are processed sequentially.
 
-- **State Updates**: Managing and updating the internal state of widgets
-  - **promkit-widgets**: Responsible for state management of various widgets and pane generation
-  - Each widget implements
-  [PaneFactory](https://docs.rs/promkit-core/0.1.1/promkit_core/trait.PaneFactory.html)
-  trait to generate panes needed for rendering
+2. **State management and UI materialization (`promkit-widgets` + `promkit-core`)**
+   - 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 states focus on state and projection only.
 
 > [!IMPORTANT]
-> The widgets themselves DO NOT contain event handlers
-> - This prevents key operation conflicts
-> when combining multiple widgets
-> - e.g. When combining a listbox and text editor, <kbd>↓</kbd>
-> behavior could potentially conflict
->   - navigating the list vs. recalling input history
-
-- **Rendering**: Processing to visually display the generated panes
-  - **promkit-core**: Responsible for basic terminal operations and concurrent rendering
-  - [SharedRenderer](https://docs.rs/promkit-core/0.2.0/promkit_core/render/type.SharedRenderer.html) (`Arc<Renderer<K>>`) provides thread-safe rendering with `SkipMap` for efficient pane management
-  - Components now actively trigger rendering (Push-based) rather than being rendered by the event loop
-  - [Terminal](https://docs.rs/promkit_core/0.1.1/terminal/struct.Terminal.html) handles rendering with `Mutex` for concurrent access
-    - Currently uses full rendering with plans to implement differential rendering in the future.
-  - [Pane](https://docs.rs/promkit_core/0.1.1/pane/struct.Pane.html)
-  defines the data structures for rendering
-
-This separation allows each component to focus on a single responsibility,
-making customization and extension easier.
-
-### Event-Loop
-
-These three functions collectively form the core of "event-loop" logic.
-Here is the important part of the actual event-loop from the async
-[Prompt::run](https://docs.rs/promkit/0.10.0/promkit/trait.Prompt.html#method.run):
+> Widgets intentionally do not own event-loop policies.
+> Event handling stays in presets or custom `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>`.
+   - `update` / `remove` modify chunks by index key.
+   - `render` delegates drawing to [`Terminal`](./promkit-core/src/terminal.rs).
+   - `Terminal::draw` performs wrapping, clearing, printing, and scrolling.
+
+This keeps responsibilities explicit:
+- prompt = control flow
+- widgets = state to graphemes
+- core renderer = terminal output
+
+## Event Loop
+
+Current core loop in [`Prompt::run`](./promkit/src/lib.rs):
 
 ```rust
-// Initialize the prompt state
 self.initialize().await?;
 
-// Start the event loop
 while let Some(event) = EVENT_STREAM.lock().await.next().await {
     match event {
         Ok(event) => {
-            // Evaluate the event and update state
+            // Current behavior: skip resize events in run loop.
+            if event.is_resize() {
+                continue;
+            }
+
             if self.evaluate(&event).await? == Signal::Quit {
                 break;
             }
         }
-        Err(e) => {
-            eprintln!("Error reading event: {}", e);
-            break;
-        }
+        Err(_) => break,
     }
 }
 
-// Finalize the prompt and return the result
 self.finalize()
 ```
 
 As a diagram:
 
 ```mermaid
 flowchart LR
-    Initialize[Initilaize] --> A
-    subgraph promkit["promkit: event-loop"]
-        direction LR
-        A[Observe user input] --> B
-        B[Interpret as crossterm event] --> C
-
-        subgraph presets["promkit: presets"]
-            direction LR
-            C[Run operations corresponding to the observed events] --> D[Update state]
-
-            subgraph widgets["promkit-widgets"]
-                direction LR
-                D[Update state] --> |if needed| Y[Generate panes]
-            end
-
-            Y --> Z[Render widgets]
-            D --> E{Evaluate}
-        end
-
-        E -->|Continue| A
+    Init[Initialize] --> Observe
+
+    subgraph Runtime["promkit: Prompt::run"]
+        Observe[Read crossterm event] --> Eval[Prompt::evaluate]
+        Eval --> Continue{Signal}
+        Continue -->|Continue| Observe
     end
 
-    E -->|Quit| Finalize[Finalize]
-```
+    subgraph Preset["promkit presets / custom prompt"]
+        Eval --> UpdateState[Update widget states]
+        UpdateState --> Build[Widget::create_graphemes]
+        Build --> Push[Renderer::update]
+        Push --> Draw[Renderer::render]
+    end
 
-In the current implementation of promkit, event handling is centralized and async.
-All events are processed sequentially within the async
-[Prompt::run](https://docs.rs/promkit/0.10.0/promkit/trait.Prompt.html#method.run)
-method and propagated to each implementation through the
-[Prompt::evaluate](https://docs.rs/promkit/0.10.0/promkit/trait.Prompt.html#tymethod.evaluate) method.
+    Draw --> Continue
+    Continue -->|Quit| Finalize[Finalize]
+```
 
 ## Customizability
 
-promkit allows customization at various levels.
-You can choose the appropriate customization method
-according to your use case.
+promkit supports customization at two levels.
+
+### 1. Configure existing presets
 
-### Customize as configures
+High-level presets (e.g. `Readline`) expose builder-style options such as:
 
-Using high-level APIs, you can easily customize existing preset components. For example, in
-[preset::readline::Readline](https://github.com/ynqa/promkit/blob/v0.9.1/promkit/src/preset/readline.rs),
-the following customizations are possible:
+- title and style
+- prefix and cursor styles
+- suggestion and history
+- masking
+- word-break characters
+- validator
+- text editor visible line count
+- evaluator override
 
 ```rust
-let mut p = Readline::default()
-    // Set title text
-    .title("Custom Title")
-    // Change input prefix
-    .prefix("$ ")
-    // Prefix style
-    .prefix_style(ContentStyle {
-        foreground_color: Some(Color::DarkRed),
-        ..Default::default()
-    })
-    // Active character style
-    .active_char_style(ContentStyle {
-        background_color: Some(Color::DarkCyan),
-        ..Default::default()
-    })
-    // Inactive character style
-    .inactive_char_style(ContentStyle::default())
-    // Enable suggestion feature
-    .enable_suggest(Suggest::from_iter(["option1", "option2"]))
-    // Enable history feature
-    .enable_history()
-    // Input masking (for password input, etc.)
-    .mask('*')
-    // Set word break characters
-    .word_break_chars(HashSet::from([' ', '-']))
-    // Input validation feature
-    .validator(
-        |text| text.len() > 3,
-        |text| format!("Please enter more than 3 characters (current: {} characters)", text.len()),
-    )
-    // Register custom keymap
-    .register_keymap("custom", my_custom_keymap)
-    .prompt()?;
+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(())
+}
 ```
 
-By combining these configuration options, you can significantly customize existing presets.
-
-### Advanced Customization
+### 2. Build your own prompt
 
-Lower-level customization is also possible:
+For advanced use cases, combine your own state + evaluator + renderer.
 
-1. **Creating custom widgets**: You can create your own widgets equivalent to `promkit-widgets`. 
-By implementing
-[PaneFactory](https://docs.rs/promkit-core/0.1.1/promkit_core/trait.PaneFactory.html)
-trait for your data structure, you can use it like other standard widgets.
-e.g. https://github.com/ynqa/empiriqa/blob/v0.1.0/src/queue.rs
+- Implement `Widget` for custom state projection
+- Implement `Prompt` for lifecycle and event handling
+- Use `Renderer::update(...).render().await` whenever UI should change
 
-2. **Defining custom presets**: By combining multiple widgets and implementing your own event handlers, 
-you can create completely customized presets. In that case, you need to implement the async
-[Prompt](https://docs.rs/promkit/0.10.0/promkit/trait.Prompt.html) trait.
+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.
 
-This allows you to leave event-loop logic to promkit (i.e., you can execute the async
-[Prompt::run](https://docs.rs/promkit/0.10.0/promkit/trait.Prompt.html#method.run))
-while implementing your own rendering logic and event handling with full async support.
+## Quality Strategy for Rendering Behavior
 
-```rust
-// Example of implementing the new Prompt trait
-#[async_trait::async_trait]
-impl Prompt for MyCustomPrompt {
-    type Index = MyIndex;
-    type Return = MyResult;
-
-    fn renderer(&self) -> SharedRenderer<Self::Index> {
-        self.renderer.clone()
-    }
+Ensuring consistent rendering behavior across terminal environments is a key focus.
+To achieve this, promkit includes a suite of test tools:
 
-    async fn initialize(&mut self) -> anyhow::Result<()> {
-        // Initialize your prompt state
-        self.renderer.render().await
-    }
+- [`termharness`](./termharness)
+- [`zsherio`](./zsherio)
+- [`zsh-render-parity`](./zsh-render-parity)
 
-    async fn evaluate(&mut self, event: &Event) -> anyhow::Result<Signal> {
-        // Handle events and update state
-        match event {
-            // Your event handling logic
-            _ => Ok(Signal::Continue),
-        }
-    }
-
-    fn finalize(&mut self) -> anyhow::Result<Self::Return> {
-        // Produce final result
-        Ok(self.result.clone())
-    }
-}
-```
+These tools compare prompt behavior against zsh-oriented scenarios
+(e.g. wrapping, resize, and cursor movement), helping keep terminal behavior
+predictable while the rendering internals evolve.