Skip to content

FW6-ALT: hybrid scroll routing for alt-screen panes - #97

Merged
cvsloane merged 13 commits into
mainfrom
refactor/frontend-command-center
Jul 21, 2026
Merged

cvsloane merged 13 commits into
mainfrom
refactor/frontend-command-center

Conversation

@cvsloane

@cvsloane cvsloane commented Jul 21, 2026 •

Copy link
Copy Markdown
Owner

Device finding 6b: the FW6-HIST local history overlay showed a black screen on claude-code panes — alt-screen apps write nothing to tmux history, so the capture legitimately returned one line (root-caused from production audit logs to the exact pane).

What changed

  • Panes now classify automatically from the newest-page scrollback fetch (>=40 non-empty lines): history-rich panes (shells, codex) keep the local overlay; thin alt-screen panes (claude-code) route swipes through the already-deployed navigate {op:'scroll'} transport, so the app scrolls its own transcript — identical to desktop trackpad behavior. Frame-coalesced (restored 92d98d3 coalescer), ±120/message, read-only sends nothing.
  • Classification primes at attach (touch viewports only), caches per pane, re-resolves on in-place window/pane switches and overlay opens. Unclassified first gesture opens the overlay spinner, which auto-closes on a thin result and caches app-scroll.
  • Fixed a real cross-cutting defect found while stabilizing the gate: Chrome's native scroll anchoring raced the overlay's manual prepend compensation (double-compensation jump) — overflow-anchor: none.
  • No protocol/schema/CP/agentd changes; no binary rollout.

Review chain

  • Builder gates green (attempt 2, honest journey fixes isolated ×5); firewall clean.
  • Adversarial review SHIP-WITH-NOTES, 0 critical: read-only gating verified at three layers; claude-journey navigate frames pinned to the real page WebSocket. AI Lead fixes: coalescer cleanup reset (app-scroll deadlock after enabled toggle), guarded+gated prime fetch, classification survives spinner dismiss, new mutation-resistant auto-close journey.
  • Full integration gate green: 200 CP + 243 dashboard tests, 21/21 smoke, 38 journeys, build.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Improved terminal touch scrolling for alternate-screen applications.
    • Automatically routes scroll gestures to the appropriate terminal history or application scrolling behavior.
    • Detects terminal scroll behavior per session, including when switching between panes.
  • Bug Fixes
    • Prevented thin or empty history overlays from displaying a black or unusable screen.
    • Automatically closes history overlays when application scrolling is detected.
    • Clearing terminal search now reliably resets results and search state.

cvsloane and others added 13 commits July 21, 2026 17:36
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…e gating

AI Lead integration fixes on FW6-ALT (adversarial review):
- restore the coalescer reset in effect cleanup (pending 'scheduled' state
  otherwise deadlocks app-scroll after an enabled toggle)
- prime fetch wrapped in try/catch (transport errors stay unclassified
  instead of unhandled rejections) and gated to touch-enabled viewports
  (desktop no longer issues unused capture round-trips)
- overlay reports classification before the generation check so a quick
  dismiss during the spinner cannot discard it
- new journey: unclassified thin pane — overlay spinner auto-closes,
  caches app-scroll, second drag emits navigate frames

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Chrome's scroll anchoring races the manual prepend compensation and
double-compensates when it engages (load-dependent), causing a visible
jump and the prepend journey's full-suite flake. The overlay owns its
scroll math; overflow-anchor none makes it the only actor.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Jul 21, 2026 •

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Terminal scrollback is classified as history or app-scroll, cached per history session, and propagated through the terminal surface. Touch gestures open history overlays for history-rich panes and emit batched navigation scroll operations for app-scroll panes, with unit and journey coverage.

Changes

Hybrid terminal scroll routing

Layer / File(s) Summary
Scroll-mode classification and overlay wiring
apps/dashboard/src/components/TerminalView.tsx, apps/dashboard/src/components/terminal/*, tasks/...
Adds threshold-based scroll-mode classification, session-keyed priming and caching, overlay classification callbacks, app-scroll auto-close behavior, and related UI adjustments.
Touch navigation routing
apps/dashboard/src/hooks/useTerminalTouchScroll.ts, apps/dashboard/src/components/TerminalView.tsx
Adds mode-aware touch paths, navigation callbacks, requestAnimationFrame coalescing, read-only gating, cleanup, and terminal navigation scroll dispatch.
Routing validation and journey fixtures
apps/dashboard/src/**/*.test.ts, tests/journeys/*, tasks/frontend-ux-*
Adds classifier and dispatch tests, app-scroll journey fixtures, pane-switching and delayed-overlay journeys, and updated task verification records.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant TerminalView
  participant TouchScroll
  participant HistoryOverlay
  participant Agentd
  TerminalView->>TouchScroll: pass cached historyScrollMode
  TouchScroll->>HistoryOverlay: open overlay for history mode
  HistoryOverlay->>TerminalView: report resolved mode
  TouchScroll->>Agentd: send navigate scroll for app-scroll mode
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely summarizes the main change: hybrid scroll routing for alt-screen panes.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch refactor/frontend-command-center

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/dashboard/src/components/TerminalView.tsx`:
- Around line 66-70: Update the scroll-mode cache effect around
scrollModeCacheRef and historySessionId so it deletes the cached entry only when
the session ID actually changes, not on status or tmuxSessionKey updates.
Preserve cache entries across disconnect/reconnect cycles while retaining
refresh behavior for pane switches and history-overlay openings, including the
related logic in the effect body around lines 238–270.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1ad652e8-cf4b-4fa7-a93f-a2a92ad5de0c

📥 Commits

Reviewing files that changed from the base of the PR and between ef5abe3 and ae7177e.

📒 Files selected for processing (14)
  • apps/dashboard/src/components/TerminalView.tsx
  • apps/dashboard/src/components/terminal/TerminalHistoryOverlay.tsx
  • apps/dashboard/src/components/terminal/TerminalSurface.tsx
  • apps/dashboard/src/components/terminal/terminalScrollMode.test.ts
  • apps/dashboard/src/components/terminal/terminalScrollMode.ts
  • apps/dashboard/src/hooks/useTerminalTouchScroll.test.ts
  • apps/dashboard/src/hooks/useTerminalTouchScroll.ts
  • tasks/2026-07-21-fw6-alt-brief.md
  • tasks/frontend-ux-handoffs/fw6-alt.md
  • tasks/frontend-ux-log.md
  • tests/journeys/command-center.journey.spec.ts
  • tests/journeys/controlPlaneMock.ts
  • tests/journeys/fw6-focus.journey.spec.ts
  • tests/journeys/fw6-precision.journey.spec.ts

@cvsloane

Copy link
Copy Markdown
Owner Author

Re CodeRabbit's cache-wipe note: intentional. Reconnects and viewport-mode flips should re-probe — the pane's history profile can change while detached, and a stale 'history' classification would reopen the black-overlay bug class this PR fixes. Cost is one 500-line capture per reconnect on touch viewports only (the prime is gated), which we accept for correctness.

@cvsloane
cvsloane merged commit ea86b3e into main Jul 21, 2026
5 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.

1 participant