Skip to content

feat(tui): interactive book level cursor with cumulative readout#33

Merged
llcro merged 1 commit intomainfrom
feat/tui-book-level-cursor
May 5, 2026
Merged

feat(tui): interactive book level cursor with cumulative readout#33
llcro merged 1 commit intomainfrom
feat/tui-book-level-cursor

Conversation

@llcro
Copy link
Copy Markdown
Collaborator

@llcro llcro commented May 5, 2026

Closes #26 (Piece 2 — level-scroll cursor + cumulative-depth readout). Piece 1 shipped in #31.

Summary

  • ↑/↓ on Market Detail activates a cursor and walks through levels. Crosses the mid between best ask and best bid, clamps at the deepest visible level on each side (no wrap).
  • Selected row is highlighted (bg + bold).
  • Bottom line of the book panel swaps from the pressure bar to a cumulative readout when cursor is active: `ASK fix(tui): fill candle gaps for illiquid instruments #3 p=78,550.2 q=0.123 cum_q=0.543 cum_$=42,683 Δmid=+12.4bps`.
  • Cumulative notional = Σ (price × qty) per level, not `cum_qty × last_price` — the level-by-level sum matches what the user expects when prices vary across levels.
  • Double-Esc pattern: first press clears cursor (stays on Detail); second press exits Detail. Gives users a non-destructive way to dismiss the readout.
  • Cursor also clears on `D` (depth change invalidates index), `k`/`m` (view switch), instrument switch, or when the side empties out via WS update.
  • Help overlay "Detail View" page documents ↑↓ + new Esc semantics.

Test plan

  • `cargo test -p cdcx-tui --lib` → 73 passed, 11 new, 0 failed
  • `cargo fmt --all --check` clean
  • `cargo clippy --workspace --all-targets` clean
  • Mutation-verified: breaking `Ask(0) → Bid(0)` crossing fails `cursor_down_from_best_ask_crosses_to_best_bid`; replacing per-level notional with `cum_qty × last_price` fails `cumulative_at_sums_notional_level_by_level`
  • Manual QA: activate cursor with ↓, walk through both sides, verify clamping at deepest bid/ask, verify double-Esc, verify `D` clears cursor, verify cumulative numbers match the book's Total column row-for-row

Design decisions worth flagging

  • Pure helpers: `cursor_up`, `cursor_down`, `clamp_cursor`, `cumulative_at`, `bps_from_mid` are standalone functions testable without `AppState`. The cursor movement contract is encoded in tests, not implicit in the render path.
  • Title indicator: panel title becomes `"Order Book (50) — cursor"` when active, so the pressure-bar swap isn't surprising.
  • Scoped out of this PR: Enter-on-cursor to prefill the place-order modal (natural follow-up, file as separate issue). Mouse click to set cursor (UX polish). MCP tool exposing the same cumulative stats (agent-parity follow-up — reuses the pub helpers already shipped here).

Market Detail view gains an order-book cursor. ↑/↓ activates a cursor
at the best ask/bid; subsequent presses walk visually through the
book, crossing the mid between best ask and best bid, clamping at the
deepest visible level on each side.

The selected row is highlighted. The bottom line of the book panel
swaps from the buy/sell pressure bar to a cumulative readout for the
selected level: side+index, price, qty, cumulative qty from top of
book, cumulative notional (Σ price × qty level-by-level), and
distance from mid in basis points.

Cursor is cleared on:
- first Esc press (second Esc exits Detail — familiar two-step)
- D (depth change invalidates index bounds)
- k / m (switching to chart or compare views)
- entering Detail on a different instrument
- WS/REST book update that shrinks the cursor's side to zero

Pure helpers (cursor_up / cursor_down / clamp_cursor / cumulative_at /
bps_from_mid) are unit-tested without AppState. 11 new tests cover
movement, mid-crossing, clamping, empty-book edge cases, per-level
notional math, and signed bps distance. Mutation-verified against
broken mid-crossing and the naive cum_qty × last_price shortcut.

Help overlay "Detail View" page updated to document ↑↓ + new Esc
semantics.

Refs #26
@llcro llcro merged commit 7d032e6 into main May 5, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TUI: make order book depth levels interactive (toggle preset + scroll through levels)

1 participant