Repository navigation
feat(dashboard): route-history Back/Forward arrows and keyboard chords - #9550
Conversation
|
Intent: Give the dashboard a first-class Back/Forward over its own route history — visible top-left arrow buttons plus ⌘/Ctrl+←/→ — working identically in the browser and the Electron renderer, with disabled states that never promise a move that will not happen, and every step routed through the draft-discard guard so no pop silently destroys typed work. |
UX Review (Fable 5, fork) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS Solid browser-convention pattern in the conventional spot, but this fork lane could open none of the four screenshots and no blind reader has seen the arrows. Watch
Evidence gaps
[UX-REVIEWED] 105d224 |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of The base tree confirms the two things I needed: Design-Verdict: PASS Real gap (#8258), solved at the right seams: one leaf position store, the existing guard contract reused, conservative degrade everywhere the platform can't answer. [DESIGN-REVIEWED] 105d224 |
First Principles Review (Fable 5, fork) — ✅ PASSPremise-level review of All checks are done. The change is a well-provenanced feature (linked issue #8258), every base symbol it leans on exists, the two First-Principles-Verdict: PASS Verify on a macOS browser that an unclaimed ⌘← really is native Back — the narrow-viewport claim-as-no-op gate rests on that one platform premise. What this change shipsInventory (10 items) — 10 justifiedIntent: let a user retrace their steps through the dashboard's route history with visible arrows and keyboard chords (#8258). ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 105d224 |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
f80dc6e to
7312061
Compare
7312061 to
c37e082
Compare
|
|
|
|
|
|
|
|
Non-ledger notes on the remaining round-1 review items (no span ids — these were not findings):
|
|
CI note for a maintainer: the two reds on head c37e082 (Backend Tests Windows shard 4, and the E2E job's backend phase) are the same single failure — |
5fc3a95 to
b067bfd
Compare
|
|
|
|
CI note for a maintainer: the Bundle Size Gate red on this PR is upstream's, not this diff's. Pristine |
b067bfd to
ad89ced
Compare
|
|
|
ad89ced to
ba22eba
Compare
|
CI note for a maintainer: the E2E (stub ACP backend, offline) red on head ba22eba is upstream's. On a fresh build of this head the harness passes 257/258 with 0 flaky in 6.3 min — the single failure is |
Browser-style Back/Forward over the SPA's route history (kirodotdev#8258): two arrow buttons in the header's left cluster (desktop layout), plus Cmd+Left/Right on macOS and Ctrl+Left/Right elsewhere, both driving navigate(+-1) so the NavigationBackGuard draft trap covers them identically. Disabled states derive from react-router's history.state.idx with a conservative Forward watermark (module store, useSyncExternalStore). Chords are gated out of text fields and terminals to preserve caret and PTY meanings. i18n keys in all 13 catalogs + en-XA + translator context.
|
|
|
bolichen97
left a comment
There was a problem hiding this comment.
Maintainer review (agent-assisted, on behalf of @bolichen97 — approval delegated), head 105d224a6.
Verified: the 31-file diff matches the body's file list; the arrows sit inside the .tb-left container-query cluster with the new 208px rung and drive navigate(±1) through useGuardedHistoryStep, which defers to the draft trap only when the current entry carries the marker — consistent with the guard's re-mint-on-lost-marker path and its from === trap && idx === trap-1 prompt rule, so no double-prompt path; the chords are dispatch: 'registry' entries, a text field un-claims the hit, and a narrow viewport claims the chord as a deliberate no-op so macOS native Back cannot pop past an unarmed trap. Screenshots pinned to head.
One maintainer edit to the body: the trailer read Fixes #8258, which would have auto-closed an issue whose item 2 (hardware mouse back/forward buttons routed through the same guarded step) this PR does not implement; it now reads Part of #8258 with the deferral named. Non-blocking, for a follow-up: the Tests paragraph mentions a historyNavStep platform/modifier test that does not exist (the tests exercise matchShortcutEvent over the registry entries — reword); the App.tsx:3280-3283 comment saying header-left is empty on single-instance is now false on desktop; one stray blank line at useKeyboardShortcuts.ts before the ⌘[/⌘] block.
Problem / Motivation
Moving around the dashboard is a one-way street. Chat → Settings → an app page leaves no way back to where you came from: the desktop app has no browser chrome, no keyboard shortcut, and no visible control walks the route history. Some pages hand-roll a "Back" link, but it points at a fixed parent, not at where you actually were (#7884 is that gap on app pages).
Why it matters
Retracing your steps is a reflex every browser and most desktop apps honor. Without it, each wrong turn in the dashboard costs a manual re-navigation, and on desktop — where users expect OS conventions — there is no recovery gesture at all. #8258 asks for exactly this.
What changed (motivation → approach → change)
The header's top-left now has Back and Forward arrow buttons, and
⌘←/⌘→(macOS) orCtrl+←/Ctrl+→(Windows/Linux) do the same thing from the keyboard. Both drive react-router's own history (navigate(±1)), so they work identically in the browser dashboard and the Electron renderer, and desktop session switches — which push real history entries — retrace along with pages.Each arrow knows when it has nowhere to go. A new module store (
src/lib/routeHistoryPosition.ts) reads react-router'shistory.state.idxthrough the samerouterEntry()readerNavigationBackGuarduses: Back exists iffidx > 0(exact, survives reloads), Forward iffidxis below a watermark of the highest index seen, which a PUSH resets because a push truncates the Forward branch. The watermark is kept insessionStorage(per tab, dies with the tab — the stack's own lifetime), so a Forward branch built before a reload is still offered afterwards. A freshnavigatearrival (typed URL,location.href, a popout that cloned the tab's storage) truncates that branch, so there the stored value is discarded; a cross-documentback_forwardreturn (browser Back after an external link) — or its BFCache form, apageshowwithpersisted— collapses it to the current entry, because the external page's own PUSH may have truncated the branch where no app code could see it; the collapse is itself what gets persisted, so a reload after such a return cannot resurrect the stale branch, and Forward re-appears only for entries the document is then seen on or builds. Either way the arrow under-reports rather than promising a move that will not happen — and Forward can never leave the dashboard. ARouteHistoryTrackermounted next toNavigationBackGuardfeeds the store; the arrows and the chord read it. On a very narrow header (below a 208px left-cluster width, the documented drop-rung pattern) the arrows hide — they are the one redundant control in that cluster, since the chords and browser chrome reach the same history.Every step asks before it destroys. A pop is the one navigation the draft-discard trap (
NavigationBackGuard) already guards — but only while its trap is armed, and the trap deliberately stays out of the stack when the user has a Forward branch or after a reload. The newuseGuardedHistoryStep()closes that gap: it asks the page's leave guard up front unless the current entry is an armed trap duplicate, in which case the trap prompts instead. One prompt per click, wherever the ask lives. The chords are additionally gated out of text fields (where the same keys mean caret line-start/line-end or word-jump), terminals (the PTY owns them), and narrow viewports — the same condition that hides the arrows, because below the breakpoint the drill-in surfaces navigate by component state and a stack walk would move history the visible UI does not reflect.Entering the dashboard through a
?token=link used to leave the arrows permanently disabled: ChatPage's two URL strippers (the?prefill=consumer and the channel-token consumer) calledhistory.replaceState({}, …), erasing react-router'shistory.state.idxbookkeeping so every later index was NaN. Both now passwindow.history.statethrough — the query is still stripped, the router's state survives — androuterEntry()readsidxwithNumber.isFinite, so any future raw replace degrades the arrows to conservatively-disabled instead of poisoning every comparison.The arrows advertise their chords only while they work:
aria-keyshortcutsand the tooltip suffix ("Back (⌘←)") read the same shortcuts-enabled toggle the keydown handler honours, through the shareduseShortcutsEnabled(), and read the LIVE binding (useShortcutBindings()) rather than the factory default, so a rebound chord is announced correctly and an unbound one not at all; the catalog tooltip can only spell the factory chord, so it drops to the bare label once the user rebinds.The chords are
dispatch: 'registry'entries in the shortcut registry (history-back/history-forward,actionsgroup), so the #4608 rebind UI covers them for free; a text field un-claims the hit (the field consumes the caret chord), while a narrow viewport — where the arrows are hidden — claims the chord as a deliberate no-op, because on macOS an unclaimed⌘←is native browser Back and would pop past an unarmed draft trap.⌘[/⌘]stays on session cycling; the bracket-convention question from #8258 remains a maintainer call this PR does not preempt.Tests
NavHistoryArrows.test.tsx— arrows over a realBrowserRouter: disabled on a fresh document, Back enables after a push, walking back enables Forward, a mid-stack push truncates the Forward branch,aria-keyshortcutson both buttons; store unit tests (snapshot identity stability, subscriber notification only on change, null-idx claims nothing, livecanGoBackvs watermark-dependentcanGoForward).useKeyboardShortcuts.test.tsx—historyNavStepplatform/modifier discipline (⌘ vs Ctrl, rejects Shift/Alt/extra modifiers, vertical arrows); handler integration: navigates when history allows, claims the chord at the stack bottom so the arrows and keyboard agree, leaves the chord to text fields and terminals.Manual verification
Verified live against a dev gateway with Playwright: fresh load shows both arrows disabled; navigating enables Back; the Back arrow pops and enables Forward; Forward returns;
Ctrl+←navigates back with the same state flips. Screenshots below are from that session.Additionally verified by hand on the macOS desktop app against a dev gateway (via a remote-instance connection): arrows render in the header's left cluster clear of the traffic lights, enable/disable correctly across navigation, and the token-entry regression fixed on this head stays fixed on that path.
Screenshots / video
Fresh load — both arrows disabled (nowhere to go):
After navigating — Back enabled, Forward disabled:
After stepping Back — Forward enabled, Back disabled (dark theme):
The two new shortcuts-modal rows under Actions:
Related Issues
Part of #8258 — this PR ships the toolbar arrows and the keyboard shortcuts (items 1 and 3); hardware mouse back/forward buttons (item 2) and the menu items are deferred to a follow-up, so the issue stays open until they land. (Trailer changed from
Fixesby the maintainer.)Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)