Skip to content

FW6-HIST: local-first history overlay for mobile touch scrolling - #96

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 6 (owner, S25 Ultra): the FW6-TOUCH server-side scroll was slow, artifact-prone, and largely unusable; owner locked a local-first direction.

What changed

  • New inline TerminalHistoryOverlay: downward drag on an attached tmux terminal opens a bottom-anchored, natively-scrolling local history surface fed by the existing capture-pane range scrollback API (500-line pages, auto load-older — effectively unlimited history). Swipe up at the bottom (or the Live pill) returns instantly to the live terminal; the WS attachment stays connected throughout.
  • Touch scrolling no longer injects anything into tmux: the navigate {op:'scroll'} touch path and its rAF coalescer are removed from the dashboard (protocol/CP/agentd untouched for other callers), structurally eliminating both the round-trip latency and the escape-byte/repaint artifacts.
  • Works for shell AND codex panes through one uniform feed (verified empirically: codex writes the tmux normal screen with real pane history).
  • Read-only viewers get history too; Keyboard/Cursor rail keys, pinch zoom, horizontal swipes, selection, and the desktop History dialog are unchanged.

Review chain

  • Builder gates green (attempt 1); firewall clean.
  • Adversarial review: SHIP-WITH-NOTES, 0 critical. AI Lead integration fixes: natural drag direction (brief error), live-scrollTop prepend compensation, loadingOlder reset on close, bottom-anchored short histories, restored History-dialog + opposite-direction journey pins.
  • Full integration gate green: 200 CP + 232 dashboard tests, 21/21 smoke, 36 journeys, build.

Known (inherited) limitation flagged to owner: capture-pane ranges are relative to the moving history end, so browsing while a pane streams can duplicate a band at page seams (same as the existing History dialog).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Added an inline terminal history overlay with virtualized scrollback, paging, loading, empty, error, and retry states.
    • Added touch gestures to open history in attached terminals and dismiss it by overscrolling back to live view.
    • Preserved the visible transcript position when older history is loaded.
  • Bug Fixes

    • Prevented history gestures from sending terminal scroll or input messages.
    • Improved history behavior when switching sessions or reconnecting.
  • Tests

    • Added coverage for history paging, virtualization, gesture handling, dismissal, and end-to-end terminal journeys.

cvsloane and others added 13 commits July 21, 2026 12:08
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ning off

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
AI Lead integration fixes on FW6-HIST:
- open gesture flipped to downward drag (content-follows-finger; brief had
  it inverted, colliding with the upward dismiss overscroll)
- single pure gate shouldOpenHistoryOnGesture used by both touchmove paths
- prepend compensation reads live scrollTop inside the rAF (no jump-back
  when scrolling during a load-older fetch)
- loadingOlder state reset when the overlay closes mid-fetch
- short histories bottom-anchor via flex mt-auto
- journeys: upward-swipe no-op pin restored; History dialog pane-actions
  journey restored

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…9c51a)

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 history access for attached tmux sessions now opens an inline, virtualized overlay that fetches paginated scrollback locally. Touch routing, scrollback math, terminal integration, and journey coverage were updated accordingly.

Changes

Terminal history overlay

Layer / File(s) Summary
Scrollback paging foundation
apps/dashboard/src/components/terminal/scrollbackPaging.ts, apps/dashboard/src/components/terminal/ScrollbackPager.tsx, apps/dashboard/src/components/terminal/scrollbackPaging.test.ts
Shared helpers normalize scrollback content, preserve position during prepends, detect thresholds, calculate virtual windows, and handle overscroll dismissal.
History overlay rendering and loading
apps/dashboard/src/components/terminal/TerminalHistoryOverlay.tsx, apps/dashboard/src/components/terminal/TerminalSurface.tsx
The new overlay fetches range scrollback, renders virtualized lines, supports loading/error/empty states, prepends older pages, and closes on bottom overscroll.
Touch gesture history routing
apps/dashboard/src/hooks/useTerminalTouchScroll.ts, apps/dashboard/src/components/TerminalView.tsx, apps/dashboard/src/hooks/useTerminalTouchScroll.test.ts
Attached tmux gestures route to history opening instead of navigate scrolling, with one opening per gesture and session-aware overlay state.
Journey validation and implementation records
tests/journeys/fw6-focus.journey.spec.ts, tasks/2026-07-21-fw6-hist-brief.md, tasks/frontend-ux-handoffs/fw6-hist.md, tasks/frontend-ux-log.md, tasks/2026-07-21-orchestration-handoff-heavisidelinux.md
Journey tests cover opening, paging, dismissal, session switching, and suppressed terminal navigation/input emissions; task records document the implementation and verification state.

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

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant TerminalView
  participant useTerminalTouchScroll
  participant TerminalHistoryOverlay
  participant ScrollbackAPI
  User->>useTerminalTouchScroll: upward touch gesture
  useTerminalTouchScroll->>TerminalView: onOpenHistory
  TerminalView->>TerminalHistoryOverlay: open session overlay
  TerminalHistoryOverlay->>ScrollbackAPI: getSessionScrollback range
  ScrollbackAPI-->>TerminalHistoryOverlay: scrollback content
  TerminalHistoryOverlay-->>User: virtualized history view
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 summarizes the main change: a local-first history overlay for mobile touch scrolling in FW6-HIST.
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

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.


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

🧹 Nitpick comments (2)
apps/dashboard/src/components/terminal/ScrollbackPager.tsx (1)

158-163: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Virtualization math still duplicated; adopt resolveScrollbackVirtualWindow.

This file already switched to the shared contentScrollbackLines/compensateScrollbackPrepend helpers (lines 13-14, 66, 124-130), but the equivalent start/end index computation here still reimplements the same overscan logic that now lives in resolveScrollbackVirtualWindow (scrollbackPaging.ts). Leaving both implementations around risks them silently diverging.

♻️ Proposed refactor
-  const startIndex = Math.max(0, Math.floor(scrollTop / LINE_HEIGHT) - OVERSCAN);
-  const endIndex = Math.min(
-    filteredLines.length,
-    startIndex + VIEWPORT_LINE_ESTIMATE + OVERSCAN * 2
-  );
+  const { startIndex, endIndex } = resolveScrollbackVirtualWindow({
+    lineCount: filteredLines.length,
+    scrollTop,
+    viewportHeight: VIEWPORT_LINE_ESTIMATE * LINE_HEIGHT,
+    lineHeight: LINE_HEIGHT,
+    overscan: OVERSCAN,
+  });
🤖 Prompt for 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.

In `@apps/dashboard/src/components/terminal/ScrollbackPager.tsx` around lines 158
- 163, Replace the duplicated startIndex/endIndex virtualization calculation in
ScrollbackPager with the shared resolveScrollbackVirtualWindow helper from
scrollbackPaging.ts. Pass the existing scroll position, filtered line
collection, viewport estimate, line height, and overscan inputs as required,
then slice using the helper’s resolved window while preserving current rendering
behavior.
tests/journeys/fw6-focus.journey.spec.ts (1)

261-273: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Restore the session-identity check for the pane-actions History dialog test.

The assertion was weakened from checking scrollbackSessionIds.at(-1) to recorder.scrollbackRequests.length > 0, so this test no longer verifies the History dialog fetched scrollback for the correct session — only that some request happened. Since this test runs in isolation (no prior overlay activity), restoring the session-id check should be low-cost and would catch a regression where the dialog resolves the wrong pane/session.

♻️ Proposed fix
-    await expect.poll(() => recorder.scrollbackRequests.length).toBeGreaterThan(0);
+    await expect.poll(() => recorder.scrollbackSessionIds.at(-1)).toBe(sessionId);
🤖 Prompt for 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.

In `@tests/journeys/fw6-focus.journey.spec.ts` around lines 261 - 273, Restore the
session-identity assertion in the pane-actions History dialog test after opening
the dialog: verify the latest recorder.scrollbackSessionIds entry equals
windowSession.id, replacing the weaker scrollbackRequests.length check while
preserving the dialog visibility assertion.
🤖 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/terminal/TerminalHistoryOverlay.tsx`:
- Around line 120-156: Keep the loading guard active until the
scroll-compensation requestAnimationFrame callback in loadOlder has applied
compensateScrollbackPrepend and updated scrollTop/setScrollTop. Move the
successful-load cleanup of loadingOlderRef.current and setLoadingOlder(false)
into that callback, while preserving generation checks and ensuring error or
stale-generation paths still release the guard without allowing a second load
before compensation.

---

Nitpick comments:
In `@apps/dashboard/src/components/terminal/ScrollbackPager.tsx`:
- Around line 158-163: Replace the duplicated startIndex/endIndex virtualization
calculation in ScrollbackPager with the shared resolveScrollbackVirtualWindow
helper from scrollbackPaging.ts. Pass the existing scroll position, filtered
line collection, viewport estimate, line height, and overscan inputs as
required, then slice using the helper’s resolved window while preserving current
rendering behavior.

In `@tests/journeys/fw6-focus.journey.spec.ts`:
- Around line 261-273: Restore the session-identity assertion in the
pane-actions History dialog test after opening the dialog: verify the latest
recorder.scrollbackSessionIds entry equals windowSession.id, replacing the
weaker scrollbackRequests.length check while preserving the dialog visibility
assertion.
🪄 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: a0373229-dd20-467a-bc24-4b89b275efa6

📥 Commits

Reviewing files that changed from the base of the PR and between b835f78 and 167e5e9.

📒 Files selected for processing (13)
  • apps/dashboard/src/components/TerminalView.tsx
  • apps/dashboard/src/components/terminal/ScrollbackPager.tsx
  • apps/dashboard/src/components/terminal/TerminalHistoryOverlay.tsx
  • apps/dashboard/src/components/terminal/TerminalSurface.tsx
  • apps/dashboard/src/components/terminal/scrollbackPaging.test.ts
  • apps/dashboard/src/components/terminal/scrollbackPaging.ts
  • apps/dashboard/src/hooks/useTerminalTouchScroll.test.ts
  • apps/dashboard/src/hooks/useTerminalTouchScroll.ts
  • tasks/2026-07-21-fw6-hist-brief.md
  • tasks/2026-07-21-orchestration-handoff-heavisidelinux.md
  • tasks/frontend-ux-handoffs/fw6-hist.md
  • tasks/frontend-ux-log.md
  • tests/journeys/fw6-focus.journey.spec.ts

@cvsloane

Copy link
Copy Markdown
Owner Author

Re CodeRabbit's loading-guard note: acknowledged and reviewed. Because prepend compensation reads the live scrollTop inside the rAF (cc9c51a), a load-older triggered in the guard-release window computes against the already-grown scrollHeight and stays consistent — the effect is at most one eager page prefetch, not a position error. Leaving as-is to avoid coupling the guard lifetime to paint timing.

@cvsloane
cvsloane merged commit ef5abe3 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