feat(ui): phone Mode menu opens as a bottom sheet

[BigSimmo]

Summary

• On phone viewports (max-width: 639px), the header Mode picker opens as the shared bottom Sheet so the full mode list is scrollable with backdrop dismiss, Escape, focus trap, and return-focus to the Mode button.
• Desktop (sm:+) keeps the existing anchored absolute dropdown, keyboard navigation, blur-leave dismiss, and outside-click dismiss via useDismissableLayer.
• Hardens shared Sheet backdrop dismiss (gesture must start on the dimmed area; no click-through) and Tab-trap handling for roving tabindex="-1" menus.
• Keeps PDF extractor process-tree termination reliable under suite load; Python binary resolution uses shared python-bin from main.
• Fixes phone hydration: Mode layout gate initializes SSR-safe and syncs from matchMedia after mount / on open (avoids React Fix differential badge design for mobile search results #418 on phone route coverage).

Verification

• Focused Vitest — header/sheet/audit-navigation contracts green after hydration fix
• Mode Playwright proofs — phone sheet open/scroll/select, backdrop dismiss + focus restore, desktop outside-click (no sheet), keyboard nav (5/5)
• Previously failing Production UI route-coverage journeys — DSM/specifier/differential phone hydration (3/3)
• npm run check:production-readiness:ci — READY (no blocking failures)
• UI verification not run: full verify:ui / verify:release not required beyond the focused Mode + route-coverage proofs above
• Provider-backed live evals not run: no answer-generation or retrieval scoring changes

Risk and rollout

• Risk: low — phone-only Mode open path plus shared Sheet dismiss/focus hardening; desktop Mode contracts preserved. Extractor change is fail-closed process cleanup only.
• Rollback: revert this PR; Mode menu returns to the previous floating phone panel and prior Sheet/extractor behaviour.
• Provider or production effects: None

Clinical Governance Preflight

Touched extractors/document.ts (fail-closed process-tree cleanup only). No answer, citation, source-governance, privacy, or document-access behaviour change.

• 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

• Phone gate reuses phoneSearchLayoutMediaQuery (max-width: 639px).
• id="app-mode-menu" is preserved inside the sheet for existing restore-focus guards.

Summary by CodeRabbit

• New Features

  • On phones, the Mode menu now opens in a scrollable bottom sheet with improved keyboard focus and focus restoration.
  • On desktop, the Mode menu remains an overlay with clearer keyboard navigation and dismissal behavior.

• Bug Fixes

  • Prevented accidental sheet dismissal when dragging from the panel onto the backdrop.
  • Improved phone layout hydration to avoid display errors.
  • Strengthened PDF extraction cleanup when processing times out.

[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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 14bd252a-a119-4ca0-829f-f10a1ed63eb6

📥 Commits

Reviewing files that changed from the base of the PR and between c529b3a and 26b6945.

📒 Files selected for processing (7)

• PR_POLICY_BODY.md
• docs/branch-review-ledger.md
• scripts/check-pr-policy-workflow.mjs
• src/components/clinical-dashboard/master-search-header.tsx
• tests/audit-navigation-auth-regressions.test.ts
• tests/pdf-extraction-budget.test.ts
• tests/ui-overlay-css-contract.test.ts

🚧 Files skipped from review as they are similar to previous changes (4)

• tests/ui-overlay-css-contract.test.ts
• tests/pdf-extraction-budget.test.ts
• PR_POLICY_BODY.md
• src/components/clinical-dashboard/master-search-header.tsx

---

📝 Walkthrough

Walkthrough

The PR adds a responsive phone Sheet mode menu, hardens Sheet dismissal and focus trapping, improves PDF extractor process termination and Python resolution tests, and adds policy, review-ledger, and governance workflow validation updates.

Changes

Mode menu interaction

Layer / File(s)	Summary
Sheet interaction handling src/components/ui/sheet.tsx, tests/ui-overlay-css-contract.test.ts	Backdrop dismissal now requires a backdrop-originating gesture, while inactive roving-tabindex buttons are excluded from Tab traversal and the contract is tested.
Responsive mode-menu surfaces src/components/clinical-dashboard/master-search-header.tsx	The mode menu uses a desktop overlay or phone Sheet with responsive gating, focus targeting, focus restoration, and coordinated surface dismissal.
Mode-menu regression coverage tests/audit-navigation-auth-regressions.test.ts, tests/ui-smoke.spec.ts	Tests cover hydration-safe phone wiring, desktop separation, phone scrolling and selection, backdrop dismissal, and focus restoration.

PDF extractor process handling

Layer / File(s)	Summary
Python process cleanup src/lib/extractors/document.ts, tests/pdf-extraction-budget.test.ts	Process-tree termination now handles platform-specific fallbacks and closure waiting; tests cover Python binary overrides and polling-based liveness checks.

PR policy synchronization

Layer / File(s)	Summary
Governance policy validation PR_POLICY_BODY.md, docs/branch-review-ledger.md, scripts/check-pr-policy-workflow.mjs	Policy and review records document verification and governance scope, while workflow validation rejects markers that force governance checks.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• BigSimmo/Database#685: Touches mode-menu Tab dismissal and keyboard accessibility paths.
• BigSimmo/Database#822: Overlaps with Escape and focus-restoration behavior for the app-mode menu.
• BigSimmo/Database#832: Modifies the same app-mode menu open, close, and dismiss paths.

Suggested labels: codex

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely captures the main change: the phone Mode menu now opens as a bottom sheet.
Description check	✅ Passed	The description matches the required template with summary, verification, risk/rollback, clinical governance, and notes sections filled in.
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.

✨ 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/mobile-mode-menu-sheet-efee

---

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

[github-actions]

CI triage

CI failed on this PR. Automated classification of the 2 failed job(s):

• Static PR checks — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.
• PR required — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.

Compared with main CI run #3763 (success).

Classification is evidence routing, not permission to ignore a failure. Exact quarantined Playwright identities remain governed by the flake ledger.

[coderabbitai]

Actionable comments posted: 4

🤖 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 @.github/workflows/ci.yml:
- Around line 109-123: Prevent PR-head content from self-attesting governance
completion: in .github/workflows/ci.yml lines 109-123, remove the
template-controlled forceChecked logic and ensure required items are checked
only through the existing trusted attestation source; in PR_POLICY_BODY.md lines
23-28, remove the GOVERNANCE_ALL_CHECKED marker or gate it through that same
trusted approval path.

In `@scripts/pr-policy.mjs`:
- Around line 106-109: Update the regular expression in the checklist-matching
logic to use line-local whitespace instead of \s* before the optional trailing
annotation, and ensure the # or <!-- suffix cannot consume newline characters.
Preserve matching for annotations that remain on the same line while rejecting
annotations that begin on a separate line.

In `@src/components/clinical-dashboard/master-search-header.tsx`:
- Around line 324-328: Replace the window.matchMedia initializer for
usesPhoneSearchLayout with a hydration-safe media-query hook that provides a
stable server snapshot and client subscription. Preserve the existing
phone-layout breakpoint and the breakpoint-close effect, using the hook’s value
to keep the desktop menu and Sheet synchronized after hydration.

In `@tests/pdf-extraction-budget.test.ts`:
- Around line 58-60: Update the test covering non-Windows Python resolution to
exercise the actual default-parameter path in resolvePythonBin: delete or
otherwise temporarily unset process.env.PYTHON_BIN, restore its original value
after the assertion, and call resolvePythonBin() without an argument. Preserve
the existing platform-specific expectation.

🪄 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: 1daac8fa-2823-45c4-b1f3-7454847158ca

📥 Commits

Reviewing files that changed from the base of the PR and between 3ea9946 and c4da935.

📒 Files selected for processing (11)

• .github/workflows/ci.yml
• PR_POLICY_BODY.md
• docs/branch-review-ledger.md
• scripts/pr-policy.mjs
• src/components/clinical-dashboard/master-search-header.tsx
• src/components/ui/sheet.tsx
• src/lib/extractors/document.ts
• tests/audit-navigation-auth-regressions.test.ts
• tests/pdf-extraction-budget.test.ts
• tests/ui-overlay-css-contract.test.ts
• tests/ui-smoke.spec.ts