vikingowl
2d45406982
Acceptance Criteria:\n- Declarative keymap sequences replace pending_key/pending_focus_chord logic.\n- :keymap show streams the active binding table and bindings export reflects new schema.\n- Vim/Emacs default keymaps resolve multi-step chords via the registry. Test Notes:\n- cargo test -p owlen-tui
79 lines
8.5 KiB
Markdown
79 lines
8.5 KiB
Markdown
## audit(keys): current bindings & commands
|
|
- Default Vim profile only maps 13 actions (model picker, focus cycling, palette, debug) leaving core editor/navigation keys hard-coded elsewhere, limiting customisation and discoverability (`crates/owlen-tui/keymap.toml:1`).
|
|
- Emacs profile mirrors the same minimal surface with Alt-based chords, lacking text editing staples like yank/kill rings or buffer navigation (`crates/owlen-tui/keymap_emacs.toml:1`).
|
|
- Normal-mode logic wires multi-key sequences (`gg`, `dd`, `Ctrl+W` splits) and focus chords directly in Rust, bypassing the registry and preventing remapping (`crates/owlen-tui/src/chat_app.rs:5691`).
|
|
- Command palette exposes 52 keywords but lacks grouping, fuzzy tags, and modern discoverability patterns (`crates/owlen-tui/src/commands/mod.rs:12`).
|
|
- Pane management, resize, and accessibility toggles rely on bespoke status messaging with limited visual affordances, creating inconsistency across panels (`crates/owlen-tui/src/chat_app.rs:5800`).
|
|
|
|
## research recap (vim/emacs & modern TUI UX)
|
|
- Contemporary TUI stacks (e.g., Textual) ship keymap registries with runtime swapping, fuzzy command launcher, and discoverable overlays, setting a parity bar for custom apps.
|
|
- GNU Emacs emphasises mnemonic, consistent command families (`C-x` for control commands, `M-` for meta navigation) and discourages overloading chords without documentation.
|
|
- Vim ecosystem guidance encourages using `:` commands plus modal consistency, avoiding unremappable hard-coded sequences to keep leader mappings customisable.
|
|
- Modern UX trends for 2025 favour adaptive layouts, depth via dupal layers, and clear affordances even in minimalist shells, suggesting richer theming, animation, and responsive scaffolding.
|
|
- Emerging terminal UIs adopt layered “glass + neon” aesthetics with light/dark parity and accessible contrasts instead of monochrome blocks.
|
|
- CLI design critiques highlight the need for preview panes, keyboard hints, and status context to bridge novice gaps.
|
|
|
|
## roadmap (Owlen UX parity sprint)
|
|
|
|
### 1) feat(keymap): rebuild binding registry with modal coverage
|
|
- **Status:** Complete — unified keymap tree with sequence-aware matching, binding export, and runtime introspection.
|
|
- **Highlights:**
|
|
1. Replaced ad-hoc `pending_key`/`pending_focus_chord` logic with a trie-driven resolver supporting arbitrary sequences, timeouts, and per-mode registries (`crates/owlen-tui/src/state/keymap.rs`).
|
|
2. Extended TOML schema (`crates/owlen-tui/keymap.toml`) to declare multi-step chords (`gg`, `dd`, `Ctrl+W s`, `Ctrl+K ←`), mapping them to new `AppCommand` variants consumed in `chat_app`.
|
|
3. Added `:keymap show` to stream the active binding table into the transcript, aiding discoverability and regression review (`crates/owlen-tui/src/chat_app.rs`).
|
|
- **Tests:** `cargo test -p owlen-tui` (covers keymap parser + sequence resolution).
|
|
|
|
### 2) feat(keymap): enhance Emacs profile & leader ergonomics
|
|
- **Why:** Match Emacs conventions (C-x, C-c prefixes, yank/kill, buffer switching) and provide Vim leaders for workspace, tools, search.
|
|
- **Implement:** Flesh out Emacs profile with kill-ring commands, register `C-x C-f`, `C-x C-s`, `M-g` jumps, etc. Introduce configurable Vim leader (default space) with namespaced commands for provider/model, tools, layout.
|
|
- **AC:** Built-in keymaps cover ≥90% of documented commands; help overlay lists canonical chords.
|
|
- **Tests:** Snapshot tests for `:keymap vim|emacs`, runtime switch coverage, toml schema validation.
|
|
|
|
### 3) feat(commands): modern palette with tagging & fuzzy discovery
|
|
- **Why:** Current flat list scales poorly; modern TUIs expose grouped, searchable command centers with context previews.
|
|
- **Implement:** Introduce metadata (category, mode availability, keybinding). Replace static array with data-driven registry backing palette cards, filters, quick docs. Add inline preview for high-impact commands (`:files`, `:model`).
|
|
- **AC:** Typing `focus` shows grouped matches with key hints; palette supports tag filters (e.g., `/agent`).
|
|
- **Tests:** Command search integration test, snapshot for palette rendering, lint verifying metadata completeness.
|
|
|
|
### 4) feat(tui): adaptive layout & polish refresh
|
|
- **Why:** Align Owlen with 2025 TUI styling (responsive spacing, depth cues, animated transitions) while preserving accessibility.
|
|
- **Implement:** Build layout system with breakpoints (≤80 cols stacked, ≥120 cols split). Introduce layer tokens (frosted glass, neon accent) with configurable shadows, transitions, and focus rings. Add optional micro-animations for context gauges, pane toggles.
|
|
- **AC:** UI adapts seamlessly across 80/100/140-col snapshots; focus state and warnings remain perceivable in high-contrast mode.
|
|
- **Tests:** Ratatui snapshot suite for multiple terminal sizes/themes; golden tests for animation fallbacks when disabled.
|
|
|
|
### 5) feat(guidance): inline cheat-sheets & onboarding
|
|
- **Why:** Keyboard-rich TUIs need embedded guidance to bridge novices; industry examples surface dynamic hints and quick tours.
|
|
- **Implement:** Contextual overlay triggered via `?` showing active keymap, top commands, search tips; first-run coach marks for focus chords and leader keys. Persist completion flags in config.
|
|
- **AC:** First launch displays onboarding flow; `?` overlay updates with keymap swaps.
|
|
- **Tests:** Snapshot coverage for overlays; integration test ensuring onboarding flag persists.
|
|
|
|
### 6) feat(tui): status surface & toast overhaul
|
|
- **Why:** Current status text is terse; need richer multi-line feedback with icons, timers, action shortcuts.
|
|
- **Implement:** Replace single-line status with layered HUD (primary message, subtext, progress). Add toast API with severity icons, auto-dismiss timers, and keyboard hints.
|
|
- **AC:** Streaming, tool calls, rate limits show structured cards; toasts accessible via history panel.
|
|
- **Tests:** Unit tests for toast queue, snapshot for HUD states, integration verifying keyboard hints update per keymap.
|
|
|
|
### 7) docs(tui): publish UX & keybinding playbook
|
|
- **Why:** Documenting conventions reduces drift and eases contributor onboarding; aligns with Emacs/Vim guidelines.
|
|
- **Implement:** Author guide covering modal philosophy, command metadata schema, theming tokens, animation policy. Include migration notes for custom keymaps.
|
|
- **AC:** Docs indexed from README, changelog summarises parity steps.
|
|
- **Tests:** Link checker; sample custom keymap validated in CI.
|
|
|
|
### 8) test(tui): automated UX regression suite
|
|
- **Why:** Large visual refactor demands deterministic screenshots across modes & terminal sizes.
|
|
- **Implement:** Expand `chat_snapshots.rs` to cover normal/insert/visual/command states, both keymaps, accessibility toggles, and responsive breakpoints. Wire into CI with diff artifact upload.
|
|
- **AC:** Snapshot set protects ≥90% of critical panels; CI fails on visual drift.
|
|
- **Tests:** `cargo test -p owlen-tui --test chat_snapshots` with feature gates for animations.
|
|
|
|
### 9) chore(assets): scripted screenshot pipeline
|
|
- **Why:** We need gallery-quality imagery for docs/changelog while keeping it reproducible.
|
|
- **Implement:** Add a demo harness that stages representative scenes (model picker, usage header, tool call, accessibility modes) using deterministic seeds; render frames via ratatui `TestBackend`, export ANSI dumps, and convert to PNG with an ANSI→image tool (e.g., chafa). Provide a `cargo xtask screenshots` command and update docs to reference the generated assets.
|
|
- **AC:** Running `cargo xtask screenshots` regenerates all gallery files; README/docs reference the latest images.
|
|
- **Tests:** CI smoke test invoking the harness (PNG conversion optional via feature flag); checksum guard to detect drift.
|
|
|
|
### 10) feat(compression): adaptive transcript compactor with auto-toggle
|
|
- **Why:** Long chats blow past context windows; we need an owned compression pipeline that keeps history usable without manual pruning.
|
|
- **Implement:** Build a compression service that chunks stale turns, summarises via chosen model/tool, and rewrites history entries. Auto mode enabled by default; expose config flag (`chat.auto_compress = true`), CLI opt-out (`--no-auto-compress`), and runtime command (`:compress auto on|off`, `:compress now`). Provide granular settings (threshold tokens, model override, strategy).
|
|
- **AC:** Owlen transparently compresses once history exceeds threshold; users can toggle via config/CLI/command and view status. Compression metadata logged for audit.
|
|
- **Tests:** Unit test strategy selection; integration harness simulating long conversations verifying auto-trigger, manual command, and CLI flag precedence.
|