Fix choppy scroll chrome at page boundaries

[BigSimmo]

Summary

• keep phone bottom-composer clearance stable while the dock hides
• add directional hysteresis and ignore browser-driven bottom scroll clamps
• cover dock geometry and bottom-boundary reveal behavior with unit and UI regressions

Why

Changing the scroll viewport while chrome was hiding caused scrollTop to be clamped near the bottom. That synthetic upward movement was interpreted as user intent, producing repeated hide/show movement and choppy scrolling.

Verification

• npm run test -- tests/use-hide-on-scroll.test.ts — 8/8 passed
• npm run typecheck — passed
• scoped ESLint — passed
• scoped Prettier — passed
• git diff --check — passed

Local limitations

• npm run verify:cheap reached the full Vitest phase but was stopped after making no progress under concurrent local Vitest workloads.
• Turbopack rejected the external node_modules junction in this isolated worktree, and the Webpack fallback did not reach the project identity endpoint. Hosted exact-head UI and required CI are therefore merge gates.

No Supabase, OpenAI, or other live-provider workflow was run.

Summary by CodeRabbit

• Bug Fixes
  • Improved phone scroll behavior when the bottom composer dock hides to prevent scroll jumps, clamping jitter, and geometry changes.
  • Made header collapse/reveal more consistent by using sustained scroll intent (direction + travel) and the active scroll range, reducing feedback loops and handling overscroll safely.
  • Updated hide-on-scroll behavior to support unified control across breakpoints.
• Tests
  • Expanded UI smoke tests to deterministically verify scroll geometry stability and delayed header reveal/clamping behavior.
  • Updated unit tests to cover direction/travel thresholds, container switching, overscroll, and viewport change edge cases.
• Documentation
  • Updated the Branch Review Ledger with new scroll-geometry stability review and follow-up entries.

[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: 51ee3761-039b-4d48-be4d-fc4a84b0bdf3

📥 Commits

Reviewing files that changed from the base of the PR and between b03313e and ce39a02.

📒 Files selected for processing (3)

• docs/branch-review-ledger.md
• src/components/clinical-dashboard/master-search-header.tsx
• src/components/clinical-dashboard/use-hide-on-scroll.ts

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

• src/components/clinical-dashboard/master-search-header.tsx
• docs/branch-review-ledger.md
• src/components/clinical-dashboard/use-hide-on-scroll.ts

---

📝 Walkthrough

Walkthrough

Mobile phone scroll-hide behavior now uses scroll-range metrics and sustained directional intent. Composer-specific layout state was removed, bottom spacing remains reserved during hide transitions, and unit/UI tests verify stable geometry during composer hiding and in-flow header collapse.

Changes

Phone scroll stability

Layer / File(s)	Summary
Scroll metrics and intent tracking src/components/clinical-dashboard/use-hide-on-scroll.ts, tests/use-hide-on-scroll.test.ts	Scroll-hide updates now track direction, travel thresholds, overscroll, maximum offsets, source changes, and viewport clamp recovery.
Mobile layout and hide-state wiring src/components/ClinicalDashboard.tsx, src/components/clinical-dashboard/global-search-shell.tsx, src/components/clinical-dashboard/master-search-header.tsx	Scroll handlers report { offset, maxOffset, source }, composer-specific hidden state is removed, and mobile bottom spacing uses stable layout conditions.
Geometry validation and review record tests/ui-smoke.spec.ts, docs/branch-review-ledger.md	Unit and smoke tests verify scroll intent and geometry during composer hiding and header collapse; the ledger records verification outcomes and merge-gate constraints.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
participant ScrollContainer
participant ScrollHideReporter
participant MasterSearchHeader
participant MainContent
ScrollContainer->>ScrollHideReporter: report offset, maxOffset, and source
ScrollHideReporter->>MasterSearchHeader: update hidden state after directional intent
ScrollHideReporter->>MainContent: preserve scroll geometry during layout changes

Loading

Possibly related PRs

• BigSimmo/Database#431: Modifies the same mobile main bottom margin and composer-dock geometry.
• BigSimmo/Database#578: Updates the shared scroll-hide implementation and breakpoint state handling.
• BigSimmo/Database#703: Modifies scroll-intent accumulation and related unit-test expectations.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and matches the main change: fixing scroll chrome behavior at page boundaries.
Description check	✅ Passed	The description covers summary, why, verification, and limitations, but it omits the template's Notes section and checkbox-style verification items.
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.

✨ 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 codex/scroll-geometry-stability-20260717

---

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/components/clinical-dashboard/global-search-shell.tsx (1)

450-457: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Do not mix offsets from different scroll containers in one intent state.

The reporter retains lastOffset and direction globally, but this handler forwards offsets from every nested scroller. Switching from main.scrollTop = 500 to a descendant near scrollTop = 0 becomes a false upward gesture and reveals the chrome even when the user scrolls down. Track intent per target or explicitly rebase when the active scroll target changes, and add a nested-scroller regression test.

🤖 Prompt for 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.
In `@src/components/clinical-dashboard/global-search-shell.tsx` around lines 450 -
457, Update the scroll-intent handling around onScrollCapture and
reportPhoneScrollHideRef so offsets and direction are not carried between
different scroll containers; track the active target’s previous offset or
explicitly rebase state when event.target changes before reporting the new
offset. Preserve correct hide/reveal behavior for continued scrolling within one
container, and add a regression test covering a switch from a deeply scrolled
main container to a near-zero nested scroller.

🤖 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.
Outside diff comments:
In `@src/components/clinical-dashboard/global-search-shell.tsx`:
- Around line 450-457: Update the scroll-intent handling around onScrollCapture
and reportPhoneScrollHideRef so offsets and direction are not carried between
different scroll containers; track the active target’s previous offset or
explicitly rebase state when event.target changes before reporting the new
offset. Preserve correct hide/reveal behavior for continued scrolling within one
container, and add a regression test covering a switch from a deeply scrolled
main container to a near-zero nested scroller.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6715b8dc-d090-498d-9c1a-5c89aac894b6

📥 Commits

Reviewing files that changed from the base of the PR and between 561cefe and 03a01d7.

📒 Files selected for processing (7)

• docs/branch-review-ledger.md
• src/components/ClinicalDashboard.tsx
• src/components/clinical-dashboard/global-search-shell.tsx
• src/components/clinical-dashboard/master-search-header.tsx
• src/components/clinical-dashboard/use-hide-on-scroll.ts
• tests/ui-smoke.spec.ts
• tests/use-hide-on-scroll.test.ts

💤 Files with no reviewable changes (1)

• src/components/clinical-dashboard/master-search-header.tsx

[BigSimmo]

Addressed the valid CodeRabbit outside-diff finding in 35e74dd: scroll intent now rebases when the active scroll container changes, with focused unit and nested-scroller UI regressions. Local verification: 9/9 focused Vitest, TypeScript, scoped ESLint, Prettier, and diff checks passed.