Skip to content

feat(dashboard): route-history Back/Forward arrows and keyboard chords - #9550

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
peterhieuvu:feat/nav-history-arrows
Sep 11, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
peterhieuvu:feat/nav-history-arrows

Conversation

@peterhieuvu

@peterhieuvu peterhieuvu commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

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) or Ctrl+←/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's history.state.idx through the same routerEntry() reader NavigationBackGuard uses: Back exists iff idx > 0 (exact, survives reloads), Forward iff idx is below a watermark of the highest index seen, which a PUSH resets because a push truncates the Forward branch. The watermark is kept in sessionStorage (per tab, dies with the tab — the stack's own lifetime), so a Forward branch built before a reload is still offered afterwards. A fresh navigate arrival (typed URL, location.href, a popout that cloned the tab's storage) truncates that branch, so there the stored value is discarded; a cross-document back_forward return (browser Back after an external link) — or its BFCache form, a pageshow with persisted — 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. A RouteHistoryTracker mounted next to NavigationBackGuard feeds 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 new useGuardedHistoryStep() 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) called history.replaceState({}, …), erasing react-router's history.state.idx bookkeeping so every later index was NaN. Both now pass window.history.state through — the query is still stripped, the router's state survives — and routerEntry() reads idx with Number.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-keyshortcuts and the tooltip suffix ("Back (⌘←)") read the same shortcuts-enabled toggle the keydown handler honours, through the shared useShortcutsEnabled(), 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, actions group), 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 real BrowserRouter: disabled on a fresh document, Back enables after a push, walking back enables Forward, a mid-stack push truncates the Forward branch, aria-keyshortcuts on both buttons; store unit tests (snapshot identity stability, subscriber notification only on change, null-idx claims nothing, live canGoBack vs watermark-dependent canGoForward).
  • Guard interplay (same file) — the exact review scenario: with a Forward branch blocking the trap, the arrow asks the leave guard before popping, a veto keeps the draft, an accept carries the pop; with the trap armed, exactly one prompt fires (the trap's), never two.
  • useKeyboardShortcuts.test.tsx — historyNavStep platform/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):

fresh load, both arrows disabled

After navigating — Back enabled, Forward disabled:

after navigation, back enabled

After stepping Back — Forward enabled, Back disabled (dark theme):

after back, forward enabled

The two new shortcuts-modal rows under Actions:

shortcuts modal rows

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 Fixes by the maintainer.)

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@peterhieuvu
peterhieuvu requested review from a team and bolichen97 September 8, 2026 21:21
@peterhieuvu

Copy link
Copy Markdown
Contributor Author

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.
Not a goal: Native Electron menu items, mouse button 4/5 handlers (Chromium already binds them in both surfaces), reassigning ⌘[/⌘] from session cycling, or closing the guard's own pre-existing browser-Back gaps (#8010).

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Sep 8, 2026
@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — 🟡 CONCERNS

UX-level review of 105d224a62e0ea0387b4335e7cba42e9011e18ad via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • On a narrow viewport, 'history-back': () => { if (!isNarrowViewport() …)} claims ⌘/Ctrl+← and does nothing, while the shortcuts modal still advertises the chord — a user in a half-width window presses an advertised, browser-universal chord and gets silence every time (low frequency × moderate friction × persistent). Smallest fix: suppress or annotate the modal rows / aria-keyshortcuts under the same narrow condition the handler checks.

Evidence gaps

  • Back/Forward arrows (all three states: both-disabled, Back-enabled, Forward-enabled) — the four temp-screenshots/nav-history-arrows/*.png are fork-head binaries not materialized here, and no blind read ran; push the branch to this repo to close.
  • Shortcuts-modal rows for Back/Forward — same unopenable shortcuts-modal-rows.png, no blind read.
  • Narrow-header state (the 208px tb-drop-navhistory rung hiding the arrows) — shown in no screenshot, even in the PR; add one of the header below the rung.

[UX-REVIEWED] 105d224

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 105d224a62e0ea0387b4335e7cba42e9011e18ad via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

The base tree confirms the two things I needed: NavigationBackGuard already read react-router's history.state.idx internals (this PR centralizes that coupling into one shared routerEntry() rather than introducing it), and .gitignore explicitly names temp-screenshots/ as a committed-deliverable convention, so the screenshot binaries are sanctioned, not scope creep. Every described behavior — arrows, chords, guard interplay, the replaceState({}) regression fix, the watermark collapse rules — has backing code and tests; every hunk is accounted for by the stated purpose; the failure posture is uniformly conservative (under-report, degrade to disabled); nothing is a one-way door.

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

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 105d224a62e0ea0387b4335e7cba42e9011e18ad via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All checks are done. The change is a well-provenanced feature (linked issue #8258), every base symbol it leans on exists, the two replaceState siblings are both fixed, temp-screenshots/ is an established deliverable convention (1729 existing files), test-only reset exports have 15+ precedents, and the draft-guard gap useGuardedHistoryStep closes is documented in the base guard's own comments (NavigationLeaveGuard.tsx:257-262).

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 ships

Inventory (10 items) — 10 justified

Intent: let a user retrace their steps through the dashboard's route history with visible arrows and keyboard chords (#8258). ADDITION.

  1. Back/Forward arrows appear in the header's left cluster on desktop layout — justified
  2. ⌘/Ctrl+←/→ chords do the same, as rebindable registry entries with shortcuts-modal rows — justified
  3. Arrows/chords disable with nowhere to go; Forward watermark persists per tab in sessionStorage — justified
  4. Each step asks the page's draft guard when the back-trap is unarmed — justified
  5. Chords yield to text fields and terminals; claimed as a no-op on narrow viewports — justified
  6. Arrows hide below a 208px left-cluster width — justified
  7. ?token=/?prefill= URL strippers now preserve router history state (both sites; 2 of 2 replaceState( calls grepped) — justified
  8. Tooltips and aria-keyshortcuts advertise only live, enabled bindings — justified
  9. Trap/entry-reader helpers moved from NavigationLeaveGuard into lib/routeHistoryPosition (import-leaf need, behavior unchanged) — justified
  10. Feature-map row and six strings across thirteen locales — justified

[FIRST-PRINCIPLES-REVIEWED] 105d224

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed 105d224a62e0ea0387b4335e7cba42e9011e18ad via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 105d224

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 105d224a62e0ea0387b4335e7cba42e9011e18ad via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 105d224

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 8, 2026
@peterhieuvu
peterhieuvu force-pushed the feat/nav-history-arrows branch from f80dc6e to 7312061 Compare September 8, 2026 22:58
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 8, 2026
@peterhieuvu
peterhieuvu force-pushed the feat/nav-history-arrows branch from 7312061 to c37e082 Compare September 9, 2026 03:25
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 9, 2026
@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • aria-keyshortcuts advertises a dead chord when shortcuts are off span=1b2a6858544a — fixed
    self-added: yes
    mechanism: shared useShortcutsEnabled() hook exported from useNavShortcutHint.ts

Fixed in c37e082: both arrows now gate aria-keyshortcuts (and the tooltip chord suffix) on the same shortcuts-enabled snapshot the rail hints read, via a shared useShortcutsEnabled() subscribed to SHORTCUTS_ENABLED_EVENT — the one source the live keydown handler honours. With shortcuts off, the attribute is absent and the tooltip is the bare label. Locked by the new "advertises no chord while shortcuts are globally disabled" test in NavHistoryArrows.test.tsx. This ruling covers any control that advertises a chord: the advertisement must read the same toggle as the binding.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Append the chord to the tooltip span=06dcfdf60194 — fixed
    self-added: yes

Fixed in c37e082: tooltips now read "Back (⌘←)" / "Back (Ctrl + ←)" via formatShortcut() from the registry entry — derived, not hand-written per platform, matching the rail rows' hint pattern — and only while shortcuts are enabled (see the span=1b2a6858544a ruling). Asserted in the chord-labels test.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • The rationale that hides the arrows on mobile does not gate the keyboard chord span=edeae87154f0 — fixed
    self-added: yes
    mechanism: isNarrowViewport() — live matchMedia read of the useIsMobile breakpoint at keypress

Fixed in c37e082: the chord branch now bails on isNarrowViewport(), a live matchMedia read of the same MOBILE_BREAKPOINT useIsMobile uses (read at keypress so the document listener never re-registers on resize). Below the breakpoint the chord falls through unclaimed, exactly as the arrows are hidden — the two affordances now agree in both directions. Locked by the new "leaves the chord unclaimed on a narrow viewport" test.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • routerIdx re-derives what routerEntry already reads span=73260e3c5a7a — fixed
    self-added: yes

Fixed in c37e082: routerEntry() is now the single exported reader, living in lib/routeHistoryPosition.ts; NavigationLeaveGuard imports it and its local copy is deleted; routerIdx is gone. The history.state coupling to react-router internals is in exactly one place.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Arrows disappear below a 208px header cluster — undeclared span=ef3eef211e22 — fixed
    self-added: yes

Fixed in c37e082 (PR body): "What changed" now declares the 208px drop rung and its reason — the arrows are the one redundant control in the left cluster (chords and browser chrome reach the same history), following the documented narrow-viewport rung pattern.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Unexport routerIdx — zero external consumers span=1655015a3b4c — fixed
    self-added: yes

Fixed in c37e082: routerIdx no longer exists as an export or a function — folded into routerEntry(), whose consumers are real (the store internals, the guard, and the keydown reads).

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • routerIdx duplicates the guard's routerEntry reader — export one, delete the other span=eea23cd017e3 — fixed
    self-added: yes

Fixed in c37e082, in the direction that keeps layering clean: the reader lives in lib/routeHistoryPosition.ts (a lib module) and components/NavigationLeaveGuard.tsx imports it, rather than a lib importing from a component. One spelling, one place, same shape the guard documented.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author

Non-ledger notes on the remaining round-1 review items (no span ids — these were not findings):

  • UX evidence gaps: c37e082 adds the two missing captures — after-back-forward-enabled.png (Forward enabled, dark theme) and shortcuts-modal-rows.png (the two new Actions rows) — SHA-pinned in the body. The fork-lane blind-read half is a pipeline constraint (fork screenshots are not materialized for the lane); the SHA-pinned images in the body are the human review path.
  • First-Principles: verify ⌘←/⌘→ on a real macOS browser: accepted — flagged to the PR author for a manual pass on the macOS desktop app and Safari/Chrome (this box is Linux; manual verification so far used Ctrl+← in Chromium). The claim-at-stack-bottom behavior deliberately mirrors the existing ⌘[/⌘] session-cycling claim two lines above it.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author

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 — test/test_work_ledger.py::test_two_conductors_binding_one_worker_at_once_yield_exactly_one_binding, the Windows lock-file binding race that #9237 fixed a truncation in and #9257 + faf4d9b recently instrumented ("expected 3 threads to report already_bound, got 1"). This PR is frontend-only (website/ + temp-screenshots/; the backend suite runs here via the temp-screenshots catch-all classification, #8027) and touches no ledger or locking code. Could someone re-run the failed jobs? Fork PRs cannot self-serve gh run rerun --failed. All 5 AI review lanes pass on this head; this is the only blocker.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 10, 2026
@peterhieuvu
peterhieuvu force-pushed the feat/nav-history-arrows branch from 5fc3a95 to b067bfd Compare September 10, 2026 20:14
@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Forward can leave the dashboard after a cross-document Back return span=2f6082500a24 — fixed
    self-added: yes
    mechanism: forwardConfirmed flag — a back_forward arrival withholds Forward until the next in-app PUSH

Fixed in b067bfd, as prescribed: on a document whose navigation-timing type is back_forward, the restored watermark is kept but Forward is WITHHELD (forwardConfirmed=false) until an in-app PUSH re-establishes the frontier by construction; a reload keeps trusting it, a navigate still discards it. Back is unaffected (reads idx > 0 live). So Forward can no longer offer, let alone perform, a move onto an external document. New test models the back_forward arrival and the PUSH that re-enables Forward. The feature-map row and PR body now say this precisely; the module header's former 'accepted residual' paragraph is replaced by the behavior.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Stale-watermark residual yields an enabled Forward whose click does nothing span=a8a363b03d4b — fixed
    self-added: yes

Closed by the same change (see span=2f6082500a24): the case that produced the dead click — return by browser Back after an external link — now arrives as back_forward, where Forward is withheld until an in-app navigation confirms the frontier. No enabled-but-inert Forward remains on any arrival type; no post-hoc re-publish heuristic was needed.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • ⌘/Ctrl+← claimed at the stack bottom on the web build costs native browser-back span=8fdb680b80e2 — rebutted
    self-added: yes

Same tradeoff as rounds 6, 8, 9 and 10 (spans 70203bb22fc5, 33604a434d59, e55971218bd4, de6c07b6a4e5), re-affirmed. The suggested web-only release at the stack bottom re-opens the upheld round-5 data-loss finding (span=516000879ef9) exactly where the trap is unarmed: post-reload before a stake publishes, and in the guard's documented calibration gap — both are web cases too, not desktop-only. The claim mirrors the pre-existing ⌘[/⌘] session-cycling claim two branches above, which already swallows native Back on macOS at every stack position; the exit the user reaches for remains the browser's own toolbar button and mouse buttons, which this PR never touches. Stated for the maintainer to own.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author

CI note for a maintainer: the Bundle Size Gate red on this PR is upstream's, not this diff's. Pristine upstream/main (no PR code) fails the same gate: all chunk 10.78 MB vs a 10.72 MB budget, over by 62 KB (reproduced locally with vite build --mode analyze + check-bundle-size.mjs on a clean worktree at the main tip). This PR adds six catalog keys × 13 locales (~2 KB) on top — the same i18n-catalog drift the CHUNK_BUDGETS comments document (last re-measured 2026-09-06). Likewise WebPreviewPanel.test.tsx fails on pristine main. Neither is fixed here per the single-concern rule; both clear when main's budget/test are re-measured.

@peterhieuvu
peterhieuvu force-pushed the feat/nav-history-arrows branch from b067bfd to ad89ced Compare September 10, 2026 21:35
@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • BFCache restores can make Forward leave the dashboard span=2f6082500a24 — fixed
    self-added: yes
    mechanism: module-level pageshow listener — a persisted restore withholds Forward until the next in-app PUSH

Fixed in ad89ced, as prescribed. A back/forward-cache restore is the back_forward case without a document start: module state survives frozen and navigation timing still describes the original load, so the arrival-type check cannot see it. The store now listens for pageshow and, when persisted, clears forwardConfirmed and re-publishes — Forward is withheld until an in-app PUSH re-establishes the frontier, exactly as on a cold back_forward arrival. New test drives a persisted pageshow, asserts Forward drops and Back holds, asserts a non-persisted pageshow is inert, and asserts the next PUSH restores Forward. With this, every re-entry path — reload, fresh navigate, cross-document Back, BFCache — is handled, and 'Forward never leaves the dashboard' holds. Also rebased onto #9953, which re-measured the all-chunk budget: the Bundle Size Gate is green locally on this head.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Narrow-viewport claimed no-op suppresses native ⌘← with zero feedback span=9863015e5e4c — rebutted
    self-added: yes

Same tradeoff as rounds 6, 8, 9, 10 and 12 (spans 70203bb22fc5, 33604a434d59, e55971218bd4, de6c07b6a4e5, 8fdb680b80e2), unchanged: releasing the chord re-opens the upheld round-5 data-loss finding (span=516000879ef9), and navigating would move a stack the drill-in UI does not reflect. Documented in the registry entry and the PR body; stated for the maintainer to own, as the review asks.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Narrow-viewport chord claimed as a silent no-op span=269b08b538ad — rebutted
    self-added: yes

Same tradeoff as rounds 6, 8, 9, 10, 12 and 13 (spans 70203bb22fc5, 33604a434d59, e55971218bd4, de6c07b6a4e5, 8fdb680b80e2, 9863015e5e4c), unchanged: releasing the chord re-opens the upheld round-5 data-loss finding (span=516000879ef9 — an unclaimed macOS ⌘← is native Back past an unarmed draft trap), and navigating would move a stack the drill-in UI does not reflect. A flash or hint on a hidden control is UI for a state the design says has no affordance; it is noted as optional polish, not widened here. Documented in the registry entry and PR body; stated for the maintainer to own, as the review asks.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author

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 fork.spec.ts:36 (/chat never reaches networkidle), which fails identically on pristine upstream/main with no PR code. Filed as #10034. Together with #10007 (WebPreviewPanel.test.tsx) and the now-fixed #9952 (bundle budget), that accounts for every red on this PR that is not this diff's.

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.
@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Reload can re-enable Forward toward an external document span=2f6082500a24 — fixed
    mechanism: the withheld state lived only in memory (forwardConfirmed), so a reload after a cross-document return trusted the stale persisted watermark. Replaced the flag with a persisted COLLAPSE: loadMaxIdx now discards the stored watermark on a back_forward arrival exactly as on navigate, and the BFCache pageshow persisted path nulls maxIdx; the first report re-seeds the watermark at the current entry and persists that seed, so a reload cannot resurrect the branch. forwardConfirmed is gone. Side effect, also a fix: after such a return, Back then Forward to an entry the document was just seen on is offered again (a POP raises the watermark), where before it stayed dead until a PUSH.
    test: NavHistoryArrows.test.tsx — 'collapses the watermark on a back_forward arrival — and the collapse survives a reload' replays the finding's exact sequence (external → Back → reload) and asserts Forward stays off and the stored watermark reads the collapsed value; the BFCache test asserts the same persistence.

Valid finding — thank you. Head 105d224.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Narrow-viewport chord is a silent no-op span=9863015e5e4c — rebutted

Eighth restatement of the same Watch (prior spans 70203bb22fc5, 33604a434d59, e55971218bd4, de6c07b6a4e5, 8fdb680b80e2, 9863015e5e4c, 269b08b538ad, and upheld data-loss span 516000879ef9 which motivated the design). The chord is claimed on narrow viewports on purpose: letting it fall through to native Back there bypasses NavigationLeaveGuard and discards an unsaved draft — a confirmed data-loss defect fixed in an earlier round. Where the arrows are hidden the feature is deliberately absent, and a keystroke that does nothing is the standard behaviour for an unavailable shortcut across the dashboard (every registry chord whose surface is unmounted is a no-op). Leaving as designed.

@peterhieuvu

Copy link
Copy Markdown
Contributor Author
  • Narrow-viewport chord is a silent no-op while the shortcuts modal advertises it span=1c19bcf72d46 — rebutted

Ninth restatement of the same Watch (prior spans 70203bb22fc5, 33604a434d59, e55971218bd4, de6c07b6a4e5, 8fdb680b80e2, 9863015e5e4c, 269b08b538ad, 9863015e5e4c; and upheld data-loss span 516000879ef9 which motivated the design). The no-op is deliberate: letting the chord fall through to native Back on a narrow viewport bypasses NavigationLeaveGuard and discards an unsaved draft — a confirmed defect fixed in an earlier round — so claiming it is the safe branch.
On the one new angle, the modal listing: ShortcutsModal filters its rows on persistent configuration only (the Terminal toggle hides when the terminal feature is disabled), never on transient window geometry — no existing chord is added or removed from the list as the window is resized, and the modal is a static registry listing by design. Making one row viewport-reactive would be a new modal behaviour with no precedent, for a chord whose surface is simply unmounted at that width, which is how every other unmounted-surface chord in the dashboard already behaves. Leaving as designed.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants