Module app

Expand description

FrankenTUI (ftui) application model for cass TUI.

Defines the Elm-architecture types: CassApp (Model), CassMsg (Message), and service trait boundaries. This module is the foundational type definition that all subsequent ftui feature work builds on (bead 2noh9.2.2).

§Architecture

  Event (key/mouse/resize/tick)
       │
       ▼
  CassMsg (from Event)
       │
       ▼
  CassApp::update(&mut self, msg) -> Cmd<CassMsg>
       │
       ├── Pure state transition  → Cmd::none()
       ├── Async search           → Cmd::task(SearchService::execute)
       ├── Spawn editor           → Cmd::task(EditorService::open)
       ├── Export                  → Cmd::task(ExportService::export)
       └── Persist state          → Cmd::save_state()

  CassApp::view(&self, frame)
       │
       ▼
  Renders current state to ftui Frame

§FrankenTUI UX Overhaul (1mfw3)

This module underwent a comprehensive UX overhaul migrating from ratatui to ftui (a custom Elm-architecture framework). Key subsystems introduced:

§Command Palette

Keyboard-first action dispatch via Ctrl+P / Alt+P. The palette provides fuzzy search over ~28 action variants grouped into 7 categories (Chrome, Filter, View, Analytics, Export, Recording, Sources). Filtering uses Bayesian-scored matching with six modes (All/Exact/Prefix/WordStart/Substring/Fuzzy) cycled via F9. See PaletteState in components/palette.rs for state, and PaletteLatencyStats for query performance instrumentation.

Design tradeoff: Bayesian scoring adds ~50μs per keystroke but produces significantly better ranking than simple substring matching. The latency budget indicator (OK <200μs, WARN <1000μs, SLOW ≥1000μs) keeps this measurable. Alt+B toggles a micro-bench overlay showing queries/second throughput.

§Responsive Layout

Terminal width drives LayoutBreakpoint (Narrow <80, MediumNarrow 80-119, Medium 120-159, Wide ≥160). Each breakpoint maps to concrete topology contracts:

SearchTopology: pane widths, split handle, dual-pane toggle
AnalyticsTopology: tab bar, filter summary, header rows, footer hints
VisibilityPolicy: theme label, hint slots/budget, saved-view path length

Ultra-narrow terminals (<30 cols or <6 rows) get a “terminal too small” fallback rather than a broken layout.

§Analytics Explorer

Seven views under AnalyticsView: Dashboard, Explorer, Heatmap, Breakdowns, Tools, Plans, Coverage. The Explorer view supports interactive cycling of:

ExplorerMetric (m/M): ApiTokens, ContentTokens, Messages, ToolCalls, etc.
ExplorerOverlay (o): None, ByAgent, ByWorkspace, BySource
ExplorerZoom (z/Z): All, 24h, 7d, 30d, 90d
GroupBy (g/G): Hour, Day, Week, Month

Chart data is pre-computed via load_chart_data() in analytics_charts.rs.

§Inspector & Diagnostics

Ctrl+Shift+I opens the inspector overlay with 7 tabs (InspectorTab): Timing, Layout, HitRegions, Resize, Diff, Budget, Timeline. Each tab renders from EvidenceSnapshots, which are updated per-tick from ftui’s evidence telemetry rather than re-parsing log files at render time.

FrameTimingStats maintains a rolling ring buffer of frame durations for FPS calculation and jitter detection.

§Theme Cycling

F2 cycles forward through 18 preset themes; Shift+F2 cycles backward. Theme selection persists to theme.json in the data directory.

§Key Bindings

Modal interceptors form a priority stack: inspector > palette > normal key handling. When a modal is open, it captures all input except its own dismiss/close messages, which must be explicitly passed through (not swallowed by _ => Cmd::none() wildcards).

§Test Coverage

532 unit tests in this module (palette, latency, responsive, inspector, etc.)
59 unit tests in components/palette.rs
74 cross-workstream integration tests in tests/cross_workstream_integration.rs
Key regression suites: palette lifecycle, dispatch coverage for all 28 action variants, responsive SIZE_MATRIX (16 entries), perf envelope checks

Re-exports§

pub use super::analytics_charts::AnalyticsChartData;

Modules§

anim_config: Spring-based animation durations / presets.
focus_ids: Well-known focus node IDs for the cass TUI layout.

Structs§

AgentPane: One column of results, grouped by a key.
AnalyticsFilterState: Analytics-specific filter state (persisted within the analytics surface).
AnalyticsTopology: Per-breakpoint layout parameters for the analytics surface.
AnimationState: Centralized animation state for all spring-based animations in the TUI.
CassApp: Top-level application state for the cass TUI.
CockpitTopology: Per-breakpoint sizing and truncation policy for the cockpit overlay.
DetailFindState: Inline find state within the detail pane.
DoctorHudSummary
DrilldownContext: Context passed when drilling down from an analytics selection into search.
EvidenceSnapshots: Cached evidence telemetry snapshots, polled from global singletons on each tick. Inspector/cockpit panels read these during view() instead of parsing the JSONL evidence file at render time.
ExportResult: Result returned by ExportService::export_html.
FrameTimingStats: Rolling frame timing statistics for the inspector overlay.
HoveredResult
InlineTuiConfig: Configuration for inline TUI mode.
MacroConfig: Configuration for macro recording/playback.
PaletteLatencyStats: Palette query latency instrumentation (1mfw3.1.7).
PaneSplitDragState
PersistedState: Subset of CassApp state that persists across sessions.
ResizeDecisionEntry: A single resize decision entry for the ring buffer history.
ResizeEvidenceSummary
ResultItem: A search result item prepared for rendering in a VirtualizedList.
RowMiniAnalytics
SavedView: Persisted filters+ranking for a saved-view slot.
SavedViewDragState
SearchParams: Parameters for a search query.
SearchResult: Result returned by SearchService::execute.
SearchTopology: Per-breakpoint layout parameters for the search surface.
SelectedHitKey: Stable identity for a selected search hit.
SourcesViewItem: Display-ready row for a configured source in the Sources view.
SourcesViewState: State for the Sources management surface.
SwarmCockpitSnapshot
SwarmCockpitState
SwarmStaleStateCounts
TerminalEventPayload: Wrapper for terminal events that will be converted to specific messages.
TimelineBuffer: Ring buffer of recent adaptive decision events.
TimelineEvent: A single timeline event for the explainability cockpit.
UndoEntry: Snapshot of undoable state for undo/redo (Ctrl+Z / Ctrl+Y).
UndoHistory: Fixed-capacity undo/redo history.
VisibilityPolicy: Per-breakpoint visibility policy for optional UI elements.

Enums§

AnalyticsView: Analytics subview within the Analytics surface.
AppSurface: Top-level application surface.
BreakdownTab: Active tab within the Breakdowns view.
CassMsg: Messages that drive the cass TUI state machine.
ContextWindow: How much surrounding context to show per result.
DensityMode: Visual density of the result list.
DetailTab: Which tab is active in the detail pane.
ExplorerMetric: Metric to display in the Explorer view.
ExplorerOverlay: Overlay mode for the Explorer view.
ExplorerZoom: Zoom presets for the Explorer time range.
FocusDirection: Direction for focus movement.
FocusRegion: Which pane currently holds keyboard focus.
HeatmapMetric: Metric to display in the Heatmap view.
InspectorTab: Active tab in the inspector overlay (Ctrl+Shift+I).
LayoutBreakpoint: Responsive layout breakpoint based on terminal width.
MatchMode: Text matching strategy for search queries.
MouseEventKind: Mouse event kinds (simplified from crossterm/ftui).
RankingMode: How search results are ranked and ordered.
ResultsGrouping: How results are grouped into panes (G to cycle).
ScreenshotFormat: Output format for TUI screenshot export.
SearchPass
TimePreset: Quick time filter presets for Shift+F5 cycling.
TimelineEventKind: Type of adaptive decision captured in the timeline.

Constants§

BULK_ACTIONS: Labels for the bulk-actions modal menu (order matters — matches action_index).
OPEN_CONFIRM_THRESHOLD: Number of selected items before requiring double-press confirmation.
RESIZE_HISTORY_CAPACITY: Rendering-ready resize evidence summary for inspector/cockpit panels.
SAVED_VIEWS_MODAL_TITLE: Title used by the saved-views manager modal.
ULTRA_NARROW_MIN_HEIGHT
ULTRA_NARROW_MIN_WIDTH: Ultra-narrow fallback policy constants.

Traits§

EditorService: Open files in external editors.
ExportService: HTML/markdown export.
IndexService: Background indexing with progress reporting.
PersistenceService: Save/load TUI state to disk.
SearchService: Async search execution.

Functions§

build_resize_config: Build the BOCPD-based resize coalescer configuration.
run_tui_ftui: Run the cass TUI using the ftui Program runtime.

Module app

Module app Copy item path

§Architecture

§FrankenTUI UX Overhaul (1mfw3)

§Command Palette

§Responsive Layout

§Analytics Explorer

§Inspector & Diagnostics

§Theme Cycling

§Key Bindings

§Test Coverage

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Module app