refactor: as components

.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
         uses: swatinem/rust-cache@v2
 
       - name: Run Clippy
-        run: cargo clippy --all-targets -- -D warnings
+        run: cargo clippy --all-targets --all-features -- -D warnings
 
   build-and-test:
     name: Build & Test
@@ -57,7 +57,7 @@ jobs:
         uses: swatinem/rust-cache@v2
 
       - name: Build
-        run: cargo build --all-targets
+        run: cargo build --all-targets --all-features
 
       - name: Run tests
-        run: cargo test --all-targets
+        run: cargo test --all-targets --all-features

.gitignore

@@ -1,3 +1,4 @@
 .direnv/
 result
 target/
+*.snap.new

Cargo.toml

@@ -31,10 +31,12 @@ similar = "2"
 fuzzy-matcher = "0.3"
 syntect = { version = "5", default-features = false, features = ["default-syntaxes", "default-themes", "regex-onig"] }
 unicode-width = "0.2"
+chrono = { version = "0.4.45", default-features = false, features = ["std"] }
 toml = "1"
 dirs = "6"
 fs2 = "0.4"
 tokio-tungstenite = "0.29"
 
 [dev-dependencies]
+insta = "1.48.0"
 serial_test = "3"

README.md

@@ -1 +1,131 @@
-# qmtui
+# qmtui
+
+`qmtui` is the Rust terminal interface for QueryMT agents. It connects to an
+Agent Client Protocol (ACP) endpoint, translates terminal and ACP activity into
+application events, updates feature-owned state, executes explicit effects, and
+renders the result with Ratatui.
+
+## Architecture
+
+The binary entry point is intentionally small: `src/main.rs` installs Tokio and
+calls `qmtui::runtime::run()`. The library is organized around these layers:
+
+| Area | Responsibility |
+| --- | --- |
+| `src/domain/` | Semantic data shared by state and features; no terminal, UI, transport, channel, filesystem, or process dependencies. |
+| `src/*_state.rs` | Feature-owned semantic state and reducer operations. `src/render_state.rs` separately owns layout metrics, render caches, and Ratatui primitives. |
+| `src/features/*/input/` | Feature input interpretation. These modules may consume Crossterm key types but do not perform I/O or know about rendering and ACP transport. |
+| `src/features/*/view/` | Feature rendering with Ratatui. Views receive state or narrow render inputs and do not know about ACP transport. |
+| `src/application.rs` | The `AppEvent`, `Effect`, and `update` boundary for application transitions. |
+| `src/handlers.rs` | Root input routing and cross-feature composition over the feature input modules. |
+| `src/acp/` | ACP connections, transport, protocol translation, replay, and command dispatch. This subsystem emits application-facing ACP events and has no UI dependency. |
+| `src/runtime/` | Process composition: endpoint selection, channels, terminal lifecycle, event scheduling, persistence, clipboard/editor work, and effect execution. |
+| `src/ui/mod.rs` | Root screen and popup composition through `ui::draw`; detailed rendering remains in feature view modules. |
+| `src/app.rs` | Crate-local composition root joining the twelve feature/state owners plus `should_quit`. |
+
+`App` fields are `pub(crate)` deliberately. Routing, persistence, rendering,
+and runtime composition need to combine multiple owners, while public getters
+for every field would broaden rather than improve the internal boundary.
+Reducers are pure with respect to external side effects: they update in-memory
+state and return `Effect` values for the runtime to execute.
+
+## Event And Effect Flow
+
+The application follows one production event path:
+
+```text
+Crossterm key/mouse       ACP connection       runtime/connection/supervisor
+        |                       |                           |
+        +-----------------------+---------------------------+
+                                v
+                 runtime::event_loop -> AppEvent
+                                |
+                                v
+                     application::update
+                       /              \
+              handlers + feature      ACP/state reducers
+                    input modules      and coordination
+                       \              /
+                         state changes
+                         + Vec<Effect>
+                                |
+                                v
+                    runtime::EffectExecutor
+       command channel / persistence / clipboard / editor / terminal / quit
+                                |
+                      RuntimeEvent feedback
+                                |
+                       application::update
+                                |
+                                v
+             ui::draw -> feature views -> RenderState
+```
+
+`runtime::event_loop::run_loop` schedules terminal, ACP, connection, supervisor,
+and tick events without letting a permanently ready source starve the others.
+It draws the current state, sends each event through `application::update`, and
+passes returned effects to `runtime::EffectExecutor::execute`. Runtime work that
+needs application feedback is converted to `RuntimeEvent` and re-enters the
+same update path rather than mutating state from a background adapter.
+
+ACP input follows the same boundary. `acp::inbound` decodes WebSocket or shared
+connection input, `acp::notification::translate` converts SDK notifications to
+application-facing updates, and `acp::notification::apply` handles replay and
+stream ordering before emitting `AcpAppEvent`. The runtime event loop wraps that
+as `AppEvent::Acp`; ACP code never renders or imports `crate::ui`.
+
+## Boundary Rules
+
+The architectural guidelines are:
+
+- Domain modules stay free of UI/terminal crates, Tokio synchronization,
+  filesystem/process access, ACP transport, and protocol DTO imports.
+- Top-level semantic `*_state.rs` modules stay free of Ratatui, Crossterm,
+  channels, I/O, process spawning, and ACP transport.
+- Feature input may use Crossterm but not Ratatui, Tokio synchronization, I/O,
+  process spawning, or ACP transport. Feature views and root UI may use Ratatui
+  but not ACP transport.
+- ACP may use Tokio, JSON-RPC, SDK, and transport types, but not `crate::ui`.
+- Removed migration surfaces stay removed: legacy server-message symbols,
+  diagnostic forwarding methods on `App`, root UI temporary exports, broad
+  `use crate::handlers::*`, and crate-wide dead-code suppression.
+- `src/main.rs` remains a thin call to `qmtui::runtime::run()`, and the twelve
+  `App` owners plus `should_quit` remain `pub(crate)`.
+
+Intentional exceptions are narrow and documented:
+
+- `src/render_state.rs`, feature views, and `src/ui/` may use Ratatui because
+  they own render caches, layout primitives, or rendering.
+- Feature input may use Crossterm key types. Test modules may use `use super::*`.
+- ACP owns its Tokio, JSON-RPC, SDK, and transport dependencies. Runtime,
+  configuration, session, and persistence adapters may own channels, files,
+  subprocesses, terminal operations, and other side effects.
+- `src/themes_gen.rs` retains its generated crate-level `allow(dead_code)`;
+  targeted item-level allowances remain valid for retained decoded fields.
+- The `cfg(test)` App-to-render adapters in `src/features/chat/view/mod.rs` are
+  retained for root cache/session integration tests.
+- `TuiConfig::delegate_models` remains a read-only migration field, and hidden
+  `--acp-websocket` remains a compatibility alias for `--ws`.
+
+## Testing
+
+Tests live with the code that owns the contract. Domain and state modules test
+semantic transitions; feature input modules test key-to-intent behavior; feature
+view modules use Ratatui test backends for layout and rendering; ACP modules test
+translation, command, replay, JSON-RPC, and transport contracts; and application,
+handler, runtime, and root UI tests cover composition and event/effect ordering.
+
+Run the same primary gates used by CI:
+
+```sh
+cargo fmt --all -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo build --all-targets --all-features
+cargo test --all-targets --all-features
+```
+
+Deterministic tests do not replace environmental validation. Live ACP/backend
+behavior, an external compatible WebSocket service, subprocess stdio framing,
+real terminal interaction, system clipboard integration, and complete
+interactive UI smoke require suitable external services or a manual environment
+and are not claimed by the automated suite.