fix: stop Escape focus restore from closing the app-mode menu

[BigSimmo]

Summary

• Fixes a Production UI flake where Escape from the scope popover deferred a focus restore onto "Open answer options", which stole focus while the app-mode menu was opening and dismissed the menu via onBlur before the Documents item was visible.
• Adds restoreFocusUnlessMoved() so Escape/scope-close restore is skipped when focus already moved (for example into the mode menu).
• Hardens the smoke helper to wait for a visible scope popover to hide before opening the mode menu (fail-closed on timeout), and adds a focused unit test for the restore guard.

Verification

• npm run test -- tests/restore-focus-unless-moved.dom.test.tsx (3 passed)
• Focused Chromium: tests/ui-smoke.spec.ts for dashboard defers source and administration requests until their surfaces open and document search mode lists matching documents (2 passed; 6/6 stress reruns of the formerly flaky test)
• UI verification not run: targeted Playwright path covers the regression; hosted Production UI required for the gate

Risk and rollout

• Risk: low — focus-restore guard on dismissable layers plus a smoke wait; no clinical/data path changes
• Rollback: revert this squash merge
• Provider or production effects: None

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed

Notes

• Unblocks Production UI flakes that previously failed babysat PRs (fix(forms): stop long pathway step codes overflowing the decision context #742/CI: include answer-progress Playwright journey in production UI gate #793 lineage) via switchToDocumentSearchMode / Documents menuitemradio not found.
• Screenshot PR queue (fix(forms): stop long pathway step codes overflowing the decision context #742/docs: record component wiring review #747/CI: include answer-progress Playwright journey in production UI gate #748/Place 'Also matches in other modes' panel after primary results #749/Add patient information factsheet vertical slice (home, search, detail) #751/refactor: centralize search route ownership #752) was largely landed via fix: land unique open-PR queue onto current main #808/fix: finish screenshot-PR residuals (Also matches order + error focus) #812; fix(forms): truncate long pathway step codes in decision context #816 landed the remaining pathway-code overflow fix.

Summary by CodeRabbit

• Bug Fixes

  • Improved focus restoration when closing search scope controls or pressing Escape.
  • Prevented focus from being unexpectedly redirected when users have moved to another control or opened the app mode menu.
  • Reduced interaction conflicts when switching document search modes.

• Tests

  • Added coverage for focus restoration and scenarios where restoration should be skipped.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Focus restoration

Layer / File(s)	Summary
Guarded focus helper and Escape integration src/components/use-dismissable-layer.ts, tests/restore-focus-unless-moved.dom.test.tsx	restoreFocusUnlessMoved conditionally restores focus without overriding app-mode menu focus or focus moved to another control. Escape handling and DOM tests use the guarded behavior.
Scope close integration and smoke synchronization src/components/clinical-dashboard/master-search-header.tsx, tests/ui-smoke.spec.ts	Scope UI close paths use guarded focus restoration, and the smoke helper waits for the scope popover to become hidden before opening the app-mode menu.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers:claude, copilot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Title check	✅ Passed	The title clearly matches the PR’s main fix: preventing Escape focus restore from closing the app-mode menu.
Description check	✅ Passed	The description follows the template with Summary, Verification, Risk and rollout, Clinical Governance Preflight, and Notes.

✨ 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 cursor/fix-mode-menu-escape-focus-race-828c

---

_{Comment @coderabbitai help to get the list of available commands.}

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@tests/ui-smoke.spec.ts`:
- Around line 166-171: Remove the catch that suppresses failures from the
scope-command-popover wait in the deferred focus restore flow. Let waitFor({
state: "hidden", timeout: uiAssertionTimeoutMs }) fail when the popover remains
visible, so opening the mode menu only occurs after the dismissal precondition
succeeds.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 68cee0a8-6428-48d8-9e43-8c8944253ae9

📥 Commits

Reviewing files that changed from the base of the PR and between 77ab4a6 and f0febf2.

📒 Files selected for processing (4)

• src/components/clinical-dashboard/master-search-header.tsx
• src/components/use-dismissable-layer.ts
• tests/restore-focus-unless-moved.dom.test.tsx
• tests/ui-smoke.spec.ts