1jehuang--jcode/docs/TUISTATE_TRAIT_DECOMPOSITION.md

# TuiState Trait Decomposition Plan

Status: Analysis + proposed plan

This document audits the `TuiState` trait (`crates/jcode-tui/src/tui/mod.rs`) and
proposes a safe, incremental decomposition. It is the Phase 1.5 follow-on to the
`App` god-object decomposition (see `CLIENT_CORE_PRESENTATION_SPLIT_PLAN.md`).

## Current state

- `pub trait TuiState` exposes **114 methods**.
- Implementors: 2 (`App` in `tui/app/tui_state.rs`, and `TestState` in
  `tui/ui_tests/mod.rs`).
- Consumers: ~95 usages across 29 files, almost all as `&dyn TuiState` (50
  render-function signatures take `app: &dyn TuiState`).

It is the presentation-layer counterpart to the `App` god-object: a single wide
interface that couples every render module to the entire client surface.

## Why a naive sub-trait split has limited value

Two structural facts constrain the refactor:

1. **`App` implements the whole surface regardless.** Splitting `TuiState` into
   `TuiTranscriptState + TuiInputState + ...` does not reduce what `App` must
   implement, and (because the trait is presentation-only data access) it does
   not change crate-level compile coupling. The win is intent/navigability, not
   decoupling of `App`.

2. **`&dyn TuiState` does not compose.** Render functions take trait objects.
   Rust has no stable `&dyn (A + B)`, so any consumer that needs methods from
   more than one domain must take a supertrait that re-aggregates them. The two
   central renderers (`ui.rs`, `ui_viewport.rs`) use methods from nearly every
   domain, so they would keep the full supertrait bound.

Measured: of the ~28 `&dyn TuiState` render modules, only **2** are
multi-category (`ui.rs`, `ui_viewport.rs`); the other ~26 each use a single
domain. So a sub-trait split *does* narrow the declared surface for the majority
of render modules, but the headline god-interface (driven by the 2 central
renderers) stays wide via the supertrait.

Conclusion: the split is worthwhile for readability and for narrowing leaf
render-module bounds, but it is **not** a compile-coupling win and should be done
incrementally to avoid a high-conflict big-bang across 29 files.

## Proposed target shape

```
trait TuiState:
    TuiTranscriptState + TuiInputState + TuiScrollState + TuiStreamStatusState
    + TuiProviderState + TuiSessionServerState + TuiWorkspaceState
    + TuiDiagramPaneState + TuiDiffPaneState + TuiSidePanelState
    + TuiInlineState + TuiOverlayState + TuiCopySelectionState
    + TuiOnboardingState + TuiMiscState
{}
```

`App` and `TestState` keep a single `impl` per sub-trait (mechanical move). The 2
central renderers take `&dyn TuiState` (the supertrait). Each leaf render module
narrows to the one sub-trait it needs.

## Method categorization (all 114)

### TuiTranscriptState
display_messages, display_user_message_count, compacted_hidden_user_prompts,
has_display_edit_tool_messages, side_pane_images, display_messages_version,
render_streaming_markdown

### TuiInputState
input, cursor_pos, queued_messages, interleave_message,
pending_soft_interrupts, has_stashed_input, command_suggestions,
command_suggestion_selected, suggestion_prompts, queue_mode,
next_prompt_new_session_armed, dictation_key_label

### TuiScrollState
scroll_offset, auto_scroll_paused, chat_overscroll_active,
copy_selection_edge_autoscroll_active, chat_native_scrollbar,
has_pending_mouse_scroll_animation

### TuiStreamStatusState
streaming_text, is_processing, streaming_tokens, streaming_cache_tokens,
output_tps, streaming_tool_calls, elapsed, status, active_skill,
subagent_status, batch_progress, time_since_activity, stream_message_ended,
status_notice, status_detail, rate_limit_remaining, animation_elapsed

### TuiProviderState
provider_name, provider_model, upstream_provider, connection_type,
mcp_servers, available_skills, auth_status, update_cost,
total_session_tokens, session_compaction_count, context_info,
context_snapshot, context_limit, cache_ttl_status

### TuiSessionServerState
is_remote_mode, is_canary, is_replay, current_session_id,
session_display_name, server_display_name, server_display_icon,
server_sessions, connected_clients, remote_startup_phase_active,
client_update_available, server_update_available, info_widget_data,
active_experimental_feature_notice

### TuiWorkspaceState
workspace_mode_enabled, workspace_map_rows, workspace_animation_tick

### TuiDiagramPaneState
diagram_mode, diagram_focus, diagram_index, diagram_scroll,
diagram_pane_ratio, diagram_pane_ratio_user_adjusted, diagram_pane_animating,
diagram_pane_enabled, diagram_pane_position, diagram_zoom

### TuiDiffPaneState
diff_mode, diff_pane_scroll, diff_pane_scroll_x, diff_pane_focus,
diff_line_wrap

### TuiSidePanelState
side_panel, side_panel_image_zoom_percent, side_panel_native_scrollbar,
pin_images, pinned_images_auto_hide_remaining_secs

### TuiInlineState
inline_interactive_state, inline_view_state, inline_ui_state

### TuiOverlayState
changelog_scroll, help_scroll, model_status_overlay, session_picker_overlay,
login_picker_overlay, account_picker_overlay, usage_overlay

### TuiCopySelectionState
copy_badge_ui, copy_selection_mode, copy_selection_range,
copy_selection_status

### TuiOnboardingState
onboarding_preview_mode, onboarding_welcome_active, onboarding_welcome_kind

### TuiMiscState
working_dir, now_millis, has_notification, centered_mode

## Incremental, low-conflict migration

Do **not** split all 15 sub-traits at once across 29 files. Recommended order:

1. Land the documented section headers in the trait definition (done; pure
   comments, single file). Gives the categorization a canonical home.
2. Extract one leaf sub-trait with a single-file consumer as a proof of pattern
   (e.g. `TuiCopySelectionState` or `TuiDiagramPaneState`). Verify with
   `cargo check -p jcode-tui`.
3. Extract remaining leaf sub-traits one per commit, narrowing the corresponding
   leaf render module's bound in the same commit.
4. Keep `ui.rs` and `ui_viewport.rs` on the `TuiState` supertrait throughout.

Each step is behavior-preserving (data accessors only) and compiles
independently, so it can be merged between other agents' work without a
big-bang conflict.

## Verification

- `cargo check -p jcode-tui` after each sub-trait extraction (TMPDIR must point
  at real disk, not the RAM-backed tmpfs, or ring/aws-lc-sys build scripts fail
  with "Disk quota exceeded").
- `cargo test -p jcode-tui --lib` once at the end. Note: the lib test suite has
  pre-existing flaky parallel-order failures unrelated to this trait (verify any
  failing test in isolation with `--test-threads=1`).