fix(dev-fleet): arrow-key navigation in row-actions menu (#5851)

[chenmingwei23]

What is the problem?

The Dev Fleet row-actions dropdown (MenuBtn in website/src/pages/DevFleetPage.tsx) announces role="menu", and that role promises ArrowDown/ArrowUp item navigation. PR #3525 added focus entry, Tab/Shift-Tab containment, and focus return, so the menu is usable via Tab -- but arrow keys did nothing.

Why this issue matters to the user

Screen-reader users hear "menu" and reach for arrow keys first; when arrows do nothing the menu appears broken even though Tab works. Keyboard users get the same dead keys, and an unhandled arrow scrolls the page behind the open menu.

How our fix solves it

The announced role and the handled keys now agree. In MenuBtn's open-effect key handler, ArrowDown/ArrowUp move focus through the same focusableItems() list the existing Tab containment uses (disabled items are already filtered out), wrapping at both ends; Home/End jump to the boundary items; preventDefault stops the page scrolling behind the menu. Three guards keep the new branch honest:

• Modified arrows (Cmd/Ctrl/Alt) pass through untouched -- they are OS/browser shortcuts the menu pattern assigns no behavior to.
• The shared IME latch (useDocumentImeLatch.claimKey) runs before preventDefault() and any focus move, so an arrow that belongs to a composition (candidate navigation) never moves menu focus -- the same claim contract as the existing Tab/Escape branches. The menu takes the stricter side than useListKeyboardNav (which lets composition arrows through) because the menu holds no editable target; the code comment records the divergence.
• When focus is outside the item list (reachable: the fleet page polls, so a focused item can unmount mid-open), ArrowDown enters at the first item and ArrowUp at the last.

Tab containment, Escape, focus return, and outside-click behavior are unchanged. Scope note: this delivers arrow-key navigation; full menu-pattern semantics (menuitem child roles, roving tabindex) are a pre-existing gap in the shared Clickable component and are out of scope here.

What tests we did

• 5 new tests in website/src/test/DevFleetPage.test.tsx: arrow cycling with wrap at both ends, Home/End jumps, IME-composition decline (focus stays put), outside-the-list entry (Down to first, Up to last), and modified-arrow passthrough.
• Mutation-verified: deleting the arrow branch reds the cycling tests; deleting only the claimKey line reds the decline test.
• Gates: npx tsc -b clean; full frontend suite 24646 tests passed; eslint warning count identical to base for both touched files.
• Pre-push review: two model-pinned reviewers (GPT + Opus lanes), both NO BLOCKING; all five advisories folded into this single commit or noted above.

Any other suggestions on the work

The IME ratchet (scanUnguardedTabFocusTraps) only recognizes Tab-shaped traps, so an unguarded arrow branch that moves focus is invisible to it -- widening the predicate to the choose-class key set is the cause-level fix and belongs to the existing ratchet-widening issue #5475.

Closes #5851

[github-actions]

UX Review (Fable 5) — ✅ PASS

UX-level review of ec4db9624152f2075565dc1c9c343632bad81239 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Arrow/Home/End navigation delivers the behavior role="menu" already promised to assistive tech; wrap, entry, disabled-skip, and modifier pass-through all match the existing Tab/Escape conventions.

[UX-REVIEWED] ec4db96

[github-actions]

Design Review (Fable 5) — ✅ PASS

Design-level review of ec4db9624152f2075565dc1c9c343632bad81239 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Small, correctly-scoped fix that makes the announced role="menu" contract true, reusing the existing focus list and IME-claim pattern already proven in this component.

Suggestions

• ~10 other role="menu" surfaces each hand-roll (or lack) this keyboard behavior; a shared menu-keyboard hook is the follow-up that stops this fix being re-written per page — file it alongside ImeEnterClaimRatchet has no rule for boundary-Tab traps; DevFleetPage carries an unguarded seventh instance #5475 rather than expanding here.

[DESIGN-REVIEWED] ec4db96

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of ec4db9624152f2075565dc1c9c343632bad81239 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ec4db96

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ec4db9624152f2075565dc1c9c343632bad81239: <one-sentence reason>

[github-actions]

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of ec4db9624152f2075565dc1c9c343632bad81239 — 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 evidence gathered. The fix itself is derived (WAI-ARIA role="menu" keyboard contract, reported defect #5851), it introduces no new public surface, and it reuses the existing IME latch rather than hand-rolling one. The two depth findings: five sibling role="menu" surfaces remain arrow-dead, and the description justifies divergence against useListKeyboardNav while never accounting for useListboxKeyboard, the closer existing mechanism (which I verified is meaningfully different: it closes on Tab where #2533 requires containment, doesn't wrap, and lacks the document-level IME latch).

First-Principles-Verdict: CONCERNS

The arrow fix is derived and honest, but it is the codebase's fourth keyboard-nav spelling and five counted role="menu" siblings stay arrow-dead.

What this change ships

Intent: make the Dev Fleet row-actions menu answer the arrow keys its role="menu" announcement promises — a FIX.

1. Arrow keys move through the row-actions menu, wrapping at the ends — justified (reported defect Dev Fleet row-actions menu: role="menu" promises arrow-key navigation but only Tab is handled #5851, ARIA role contract)
2. Home/End jump to first/last item — rides along, declared; same role contract names the harm
3. Arrows no longer scroll the page behind the open menu — justified
4. Cmd/Ctrl/Alt+arrow still reach the OS/browser — justified
5. An arrow owned by an IME composition leaves menu focus alone — justified; reuses the existing useDocumentImeLatch, no new mechanism
6. Arrow with focus outside the list enters at first/last item — justified, named reachable cause (polling unmount)

Watch

• Point patch with counted siblings: grepping role="menu" against Arrow handling, 5 menus ship no arrow navigation at all — AgentPillBar.tsx, MicSourceMenu.tsx, mochi ContextMenu.tsx, mochi PackEditor.tsx, PierreWorkspaceTreeImpl.tsx. The description defers the general fix to the Clickable gap and ImeEnterClaimRatchet has no rule for boundary-Tab traps; DevFleetPage carries an unguarded seventh instance #5475, but ImeEnterClaimRatchet has no rule for boundary-Tab traps; DevFleetPage carries an unguarded seventh instance #5475 widens the ratchet predicate, not the menus — nothing named fixes these five.
• The description argues divergence from useListKeyboardNav but never mentions useListboxKeyboard (hooks/useListboxKeyboard.ts), the closer mechanism already driving Arrow/Home/End roving focus on a role="menu" container (MarkdownPanel.tsx:483). It is meaningfully different today (Tab-close vs. Dev Fleet confirm popover does not trap focus #2533 containment, no wrap, no document IME latch), so this inline branch stands — but it is the fourth spelling of the same job, and the shared-primitive cause the author names is where the next one should land instead of a fifth.

[FIRST-PRINCIPLES-REVIEWED] ec4db96

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed ec4db9624152f2075565dc1c9c343632bad81239 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ec4db96

Verdict parsed from the review's SHA-scoped output markers for commit ec4db9624152f2075565dc1c9c343632bad81239.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ec4db9624152f2075565dc1c9c343632bad81239: <one-sentence reason>

[chenmingwei23]

Dispositions for the First Principles CONCERNS (advisory, head ec4db96):

1. Five sibling role="menu" surfaces remain arrow-dead -- accepted and deferred. Filed #6231 covering the five named surfaces (AgentPillBar.tsx, MicSourceMenu.tsx, mochi ContextMenu.tsx, mochi PackEditor.tsx, PierreWorkspaceTreeImpl.tsx). The review is right that #5475 widens only the ratchet predicate, not the menus, so #6231 carries the behavior half explicitly and names the shared-primitive direction (extend useListboxKeyboard or extract a shared menu-keyboard hook) so the sibling fix lands there instead of a fifth inline spelling. Folding five more surfaces into this converged single-commit PR would be the scope growth this repo's review process exists to prevent.

2. useListboxKeyboard not accounted for in the description -- acknowledged; the inline branch stands. The review's own verification settles the reuse question: useListboxKeyboard closes on Tab where #2533 requires containment, does not wrap, and lacks the document-level IME latch -- three load-bearing differences, so adopting it here would have regressed the #3525 containment contract. That comparison is now recorded in #6231 as the input to the shared-primitive design, which is the right place for the consolidation decision.

[dwu96]

Tier 1 auto-approve: fix (2 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, SAST annotations clean, security checklist all-NO, AI reviewers green. Category: role="menu" already promised WAI-ARIA arrow-key item navigation but the keydown handler only bound Escape/Tab, so screen-reader users had no arrow path through the row-actions menu; the fix adds ArrowUp/ArrowDown/Home/End with wrap, IME-composition and modified-key claims, plus five regression tests.

[bolichen97]

Tier 1 auto-approve: fix (2 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, SAST annotations clean, security checklist all-NO, AI reviewers green. Category: fix — arrow-key item navigation in the row-actions menu (WAI-ARIA menu pattern) for #5851, test-covered, no runtime/behavior change outside the menu keyboard handler.

[bolichen97]

Tier 1 auto-approve: fix (2 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, SAST annotations clean (Semgrep success/0, CodeQL success + 0 PR-scoped alerts), security checklist all-NO, AI reviewers green. Category: fix(dev-fleet) adds WAI-ARIA arrow-key/Home/End navigation to the existing row-actions menu keydown handler with tests, clear root cause (#5851: role=menu promised arrow navigation it lacked).