orca/docs/back-button-tasks-page.md

Back/Forward support for the Tasks page

Goal

Make the titlebar back/forward buttons and the Cmd/Ctrl+Alt+←/→ shortcut traverse Tasks visits in addition to worktree activations. Today both are no-ops outside activeView === 'terminal' (see App.tsx:616, App.tsx:900).

Current shape

• History lives in src/renderer/src/store/slices/worktree-nav-history.ts.
• Entries are string[] (worktree IDs), recorded from worktree-activation.ts:96 via recordWorktreeVisit.
• goBackWorktree/goForwardWorktree skip dead worktrees via findPrev/NextLiveWorktreeHistoryIndex, gated by an activator ref and isNavigatingHistory to prevent re-recording.
• UI (pre-change): titlebar buttons hidden unless activeView === 'terminal'; shortcut ignored outside terminal view.

Minimal implementation (downscoped)

1. History entry type → string | 'tasks'.

   • findPrev/NextLiveWorktreeHistoryIndex must short-circuit on 'tasks' before calling findWorktreeById (which takes a worktree id, not a view tag) — Tasks entries are unconditionally live.
   • Keep recordWorktreeVisit(worktreeId: string) signature to avoid churn in terminals-hydration.test.ts. Add a sibling recordViewVisit(entry: 'tasks') that shares the dedupe/truncate/cap logic.
   • Keep existing names (worktreeNavHistory, goBackWorktree, canGoBackWorktreeHistory). They're now slight misnomers since entries may be 'tasks', but renaming touches ~20 call sites for no behavioral win. Add a one-line comment at the top of the slice stating the entry type and the intentional keeping of the name, so future readers don't assume it's worktree-only.

2. Record Tasks visits → call recordViewVisit('tasks') from openTaskPage (ui.ts:189). No isNavigatingHistory guard needed: back-to-Tasks routes through setActiveView('tasks') per step 3, which never touches openTaskPage. The slice's existing adjacent-entry dedupe covers any other re-entry. Note: openTaskPage is called with varying taskPageData (e.g. { taskSource: 'github' } vs 'linear' from SidebarNav.tsx:88,102); all collapse to a single 'tasks' entry and dedupe against the current entry, so toggling presets produces no extra history entries. This is consistent with the out-of-scope "no per-entry snapshotting" decision.

3. Dispatch in goBack/goForward → based on entry kind:

   • worktreeId → existing activator(worktreeId) path. When current entry is 'tasks', no extra view handling is needed: activateAndRevealWorktree at worktree-activation.ts:82-84 already switches activeView back to 'terminal'.
   • 'tasks' → setActiveView('tasks') (not openTaskPage — avoids mutating previousViewBeforeTasks and the SWR prefetch).

4. Fix Esc-close history desync. closeTaskPage (ui.ts:210) currently sets activeView to previousViewBeforeTasks without touching the history index, so after A → Tasks → Esc the index still points at the 'tasks' entry and Back becomes a visual no-op (activator re-activates A) while Forward re-opens Tasks. Fix: in closeTaskPage, if the current history entry is 'tasks', move the index to the previous live entry (same scan as findPrevLiveWorktreeHistoryIndex). Sub-case: if there is no previous live entry (e.g. user's first action was open Tasks, then Esc — history ['tasks'] at index 0), leave the index unchanged at 0. Accept the minor cost (Back becomes a visual no-op until a real visit records a new entry) rather than setting to -1, which would lose the only forward target. Guard with isNavigatingHistory is unnecessary here — closeTaskPage is never invoked from the history path.

5. Unhide UI on Tasks (allowlist, not denylist — activeView union is 'terminal' | 'settings' | 'tasks', but an allowlist won't silently include future views):

   • Replace the activeView !== 'terminal' early-return at App.tsx:616 with activeView !== 'terminal' && activeView !== 'tasks'. Update the adjacent comment (App.tsx:613-615) — it currently claims the shortcut is a no-op outside terminal because the buttons are hidden; replace with: back/forward traverse worktree + Tasks visits, so the shortcut is active whenever the button cluster is (terminal or Tasks); still suppressed elsewhere (Settings).
   • Change the titlebar cluster guard at App.tsx:900 to activeView === 'terminal' || activeView === 'tasks'. Update the adjacent comment (App.tsx:896-899) — drop the "terminal view only" framing; explain the cluster is shown wherever the history shortcut is live, and hidden in Settings to keep that view modal-ish.

6. Tests: extend worktree-nav-history.test.ts for mixed entries:

   • A → Tasks → B, back lands on Tasks, back again on A.
   • Tasks dedupe against current entry.
   • Dead worktree between Tasks entries is skipped.
   • A → Tasks → closeTaskPage(): index moves back to A; subsequent Back is a no-op, Forward re-opens Tasks.
   • Tasks (only entry) → closeTaskPage(): index stays at 0, Back is a visual no-op.

Explicitly out of scope

• Settings in history. Stays modal-ish; closes via previousViewBeforeSettings.
• Per-entry taskPageData snapshotting. Back-to-Tasks opens Tasks with default filters/source. Revisit if users complain.
• Session persistence of history. Keep in-memory only (it already is).

Edge cases handled

• Worktree deletion mid-session → skipped by existing live-check; Tasks entries always live.
• Dedupe semantics → same adjacency rule works for 'tasks'.
• Activator failure on worktree → unchanged (result !== false gate). Tasks dispatch can't fail.
• Editable-target guard at App.tsx:600 still fires first → typing in the Tasks search box + Cmd+Alt+← remains a no-op.
• MAX_HISTORY = 50 → Tasks entries consume slots; worst-case effective worktree depth halves to ~25. Acceptable.

Known residual quirks (accepted)

1. Prefetch loss on back-to-Tasks. Routing through setActiveView('tasks') skips the SWR prefetch at ui.ts:201-208; back-to-Tasks is ~300–800ms slower than a fresh open via the sidebar. Not a regression vs today (back-to-Tasks isn't possible at all today).

2. Titlebar layout shift. Revealing the button cluster on Tasks changes the titlebar — needs a visual check that nothing Tasks-specific collides.

Files touched

• src/renderer/src/store/slices/worktree-nav-history.ts — entry type, recordViewVisit, dispatch in goBack/goForwardWorktree.
• src/renderer/src/store/slices/worktree-nav-history.test.ts — new cases.
• src/renderer/src/store/slices/ui.ts — openTaskPage records via recordViewVisit; closeTaskPage rewinds history index when the current entry is 'tasks'.
• src/renderer/src/App.tsx — widen the two activeView === 'terminal' guards to include 'tasks', and update the adjacent "why" comments at App.tsx:613-615 and App.tsx:896-899 to reflect the new invariant.

Estimated diff: ~30 lines of slice logic, 1 call site in ui.ts, 2 guards in App.tsx, plus tests.