fix: restore phone-safe dock behavior

docs/branch-review-ledger.md

@@ -1106,3 +1106,4 @@ This file is append-only. Never rewrite or delete an existing review record; app
 
 | 2026-07-26 | `codex/phone-footer-glass` | `7e4fd1a23` | Review-follow-up and CI hydration-race review | APPROVE. Scoped the expanded collapse runway only to combined in-flow header plus reserve owners, cleared the calculator dock focus latch after sheet teardown, and made mode-home UI assertions wait for one settled owner during production hydration. Both automated review threads were addressed and resolved. No P0-P3 findings remain; physical iOS/WebKit compositing remains the only material unverified surface. | `verify:cheap` PASS; focused scroll-hide/static contracts 25/25 PASS; focused calculator teardown/geometry Chromium 3/3 PASS; affected mode-home production Chromium 5/5 PASS; no provider-backed checks. |
 | 2026-07-27 | `codex/phone-footer-paint` | `e1657a4a4e3e25b4a35a1dcf544b3efddb123c3f` | Protected-main release-readiness review of phone footer safe-area paint | APPROVE. The prior footer remained visually opaque because its normal/fallback terminal tints reached 72-90%, all blur masks painted through the physical edge, and hidden WebKit paint had no explicit terminal visibility state. The shared dock now has bounded localized tint, transparent gradient/mask terminals, an 88% pill, and delayed `visibility: hidden` synchronized to the 240ms exit; reduced-motion hides immediately. Therapy and calculator ownership prove the standard shared behavior. No P0-P3 finding remains. Highest residual risk is physical iOS momentum/compositor behavior beyond local WebKit emulation. | `verify:cheap` PASS (393 files; 3518 passed / 2 skipped); focused Therapy Chromium + WebKit PASS; calculator shared-dock Chromium + WebKit PASS; `verify:ui` PASS (314/314); `verify:pr-local` PASS including production build/client-secret scan and 36-case offline RAG fixtures; no live provider-backed checks. |
+| 2026-07-27 | `codex/phone-bottom-band-root-20260727` | `a8efe4a08f00a2365e2035f83ce2128ec680576f` | Protected-main release-readiness review of the shared phone viewport shell | APPROVE. The remaining bottom band clipped live result content above the hidden dock because both phone application owners used viewport-sized fixed roots, a physical-iOS paint path that can disagree with correct DOM geometry. Both owners now share a bounded in-flow dynamic-viewport shell; hidden reserve remains zero, the last viewport pixel remains content-owned, and viewport resize preserves the reading offset. No P0-P3 finding remains. Highest residual risk is physical-device iOS compositing beyond desktop WebKit emulation. | `verify:cheap` PASS (393 files; 3519 passed / 2 skipped); focused Therapy and dashboard production WebKit PASS; `verify:ui` PASS (314/314); `verify:pr-local` PASS including production build/client-secret scan and 36-case offline RAG fixtures; no live provider-backed checks. |

docs/search-chrome-behaviour.md

@@ -51,7 +51,7 @@ Rules that keep this working:
 
 - **Hide the top bar, not the search field.** The collapse wrapper (`data-testid="universal-header-collapse"`) wraps `header#search` plus page navigation mounted through `PhoneHeaderCollapsePortal` into `#phone-header-collapse-addon-slot`. Keep composers outside the collapse row: tablet search stays pinned independently, and desktop search scrolls with page content rather than being translated by the header.
 - **Every production phone navigation header has one collapse owner.** `PhoneHeaderCollapsePortal` moves Therapy section navigation, DocumentViewer navigation, and Differential detail navigation into `#phone-header-collapse-addon-slot` below `sm`; the same subtree stays in its existing page position at `sm+`. Do not add a second sticky/fixed phone header inside `#main-content`: the universal collapse row must own its safe area, focus pinning, timing, clipping, and measured release. Semantic content headings and modal/sheet headers are not viewport chrome and stay in their own flow/scroll context.
-- **Feed the reporter from the element that actually scrolls.** `GlobalSearchShell`'s `#main-content` is the scrollport only on phones, so above that it also runs `useDocumentScrollHideReporter`. That hook self-gates: the phone shell is `fixed inset-0`, so the document cannot scroll and never fires.
+- **Feed the reporter from the element that actually scrolls.** `GlobalSearchShell`'s `#main-content` is the scrollport only on phones, so above that it also runs `useDocumentScrollHideReporter`. That hook self-gates: the phone shell is a bounded, overflow-clipped `.phone-viewport-shell`, so the document cannot scroll and never fires. Keep that shell in normal flow; viewport-sized fixed roots trigger a physical-iOS bottom-gap compositor bug even when DOM geometry is correct.
 - **Tablet stickiness belongs on the outer [top bar \| search] stack, not on `header#search`.** The top bar sits inside header-height boxes, which leaves a sticky rule on it zero travel. For the same reason the stack's ancestor in `GlobalSearchShell` is `display: contents` above the phone breakpoint rather than a block, and collapse returns a fragment (safe-area spacer + stack) rather than a single root box. At desktop widths the search portal leaves that same outer stack holding only the top bar.
 - **Collapse only the top-bar row inside a sticky stack.** On tablets, translating the whole stack would take the search field off-screen; collapsing just the top bar lets search stay pinned at the viewport top below the wide-layout safe-area spacer. On desktop, the page-flow search is outside the stack entirely.
 - **Release the phone top inset with hidden chrome.** `chrome-safe-area-top` is a full-width sibling that is `h-[var(--safe-area-top)]` while the phone header is visible and `h-0` while hidden, using the same transition timing as the top-bar row. `readChromeCollapseMetrics` must charge that released phone height as well as the controls and dock reserve, or short pages clamp and oscillate at the bottom. At `sm+` the spacer remains `h-[var(--safe-area-top)]`, and sticky chrome pins at `top: var(--safe-area-top)`. Do not leave a phone-only surface/status-bar band after the controls collapse.

src/app/globals.css

@@ -2331,6 +2331,24 @@ html[data-motion="reduced"] .pwa-notice-card {
  height: 100svh;
  }
 
+ /*
+ * Phone search surfaces keep #main-content as their only scrollport, but the
+ * viewport shell itself must remain in normal flow. iOS can leave a painted
+ * gap under viewport-sized position:fixed containers even when CSSOM reports
+ * the correct bounds. A bounded dynamic-viewport block avoids that compositor
+ * path while still giving the flex scroller an exact height.
+ */
+ @media (max-width: 639px) {
+ .phone-viewport-shell {
+ position: relative;
+ width: 100%;
+ min-height: 100vh;
+ height: 100vh;
+ min-height: 100svh;
+ height: 100svh;
+ }
+ }
+
  .mobile-popover-scroll {
  max-height: min(70svh, 28rem);
  }
@@ -2341,18 +2359,15 @@ html[data-motion="reduced"] .pwa-notice-card {
  height: 100dvh;
  }
 
- .mobile-popover-scroll {
- max-height: min(70dvh, 28rem);
+ @media (max-width: 639px) {
+ .phone-viewport-shell {
+ min-height: 100dvh;
+ height: 100dvh;
+ }
  }
- }
 
- /* Phones: ClinicalDashboard pins with fixed inset-0 utilities. Do not keep a
- dvh height clamp here — it recreates the Safari toolbar dead band under
- the shell even when inset-0 is present if height still resolves to dvh. */
- @media (max-width: 639px) {
- .mobile-app-shell {
- min-height: 0;
- height: auto;
+ .mobile-popover-scroll {
+ max-height: min(70dvh, 28rem);
  }
  }
 

src/components/ClinicalDashboard.tsx

@@ -3314,8 +3314,9 @@ export function ClinicalDashboard({
  <div
  className={cn(
  appBackdrop,
- // Phone: fixed inset-0 (not 100dvh) — matches GlobalSearchShell; avoids Safari toolbar dead band.
- "mobile-app-shell flex flex-col overflow-hidden text-[color:var(--text)] max-sm:fixed max-sm:inset-0 max-sm:h-auto max-sm:min-h-0 max-sm:overflow-hidden md:grid md:grid-cols-[5.25rem_minmax(0,1fr)] md:overflow-hidden",
+ // Share the same in-flow phone viewport contract as GlobalSearchShell.
+ // Avoiding a viewport-sized fixed root prevents iOS compositor gaps.
+ "mobile-app-shell phone-viewport-shell flex flex-col overflow-hidden text-[color:var(--text)] max-sm:overflow-hidden md:grid md:grid-cols-[5.25rem_minmax(0,1fr)] md:overflow-hidden",
  sidebarColumnTransitionReady &&
  "motion-safe:transition-[grid-template-columns] motion-safe:duration-200 motion-safe:ease-out",
  sidebarCollapsed ? "lg:grid-cols-[5.25rem_minmax(0,1fr)]" : "lg:grid-cols-[20rem_minmax(0,1fr)]",

src/components/calculators/search-page.tsx

@@ -520,17 +520,15 @@ export function CalculatorsSearchPage() {
  const dockHidden = footerHidden && !dockFocused;
  const reserveTransitioning = useReserveTransitionMarker(dockHidden, activeCalc);
  useEffect(() => {
- if (!activeCalc) return undefined;
- let cancelled = false;
+ if (!activeCalc) return;
  // Submitting a focused dock input unmounts the dock before React is
  // guaranteed to dispatch blur. Clear the latch after teardown so the dock
- // can resume hide-on-scroll when the calculator sheet closes.
+ // can resume hide-on-scroll when the calculator sheet closes. This reset
+ // must survive a fast close: cancelling the microtask during effect cleanup
+ // can otherwise leave the remounted dock permanently focus-pinned.
  queueMicrotask(() => {
-if (!cancelled) setDockFocused(false);
+ setDockFocused(false);
  });
- return () => {
- cancelled = true;
- };
  }, [activeCalc]);
 
  const compact = density === "compact";

src/components/clinical-dashboard/global-search-shell.tsx

@@ -709,12 +709,11 @@ function GlobalStandaloneSearchShellBody({
  return (
  <div
  className={cn(
- // Phone shell height comes from inset-0 alone, never 100dvh: iOS Safari
- // re-resolves dvh lazily when its toolbar collapses/expands (especially
- // with body scrolling disabled like here), leaving a dead band between
- // the clipped shell and the toolbar. Fixed insets track the live
- // viewport through the whole transition, so content stays edge to edge.
- "sm:min-h-dvh max-sm:fixed max-sm:inset-0 max-sm:overflow-hidden bg-[color:var(--background)] text-[color:var(--text)]",
+ // Keep the phone shell viewport-bounded without making the whole app a
+ // viewport-sized fixed layer. Physical iOS can paint a bottom gap under
+ // fixed inset shells while reporting correct geometry; the shared
+ // in-flow contract still bounds #main-content for internal scrolling.
+ "phone-viewport-shell sm:min-h-dvh max-sm:overflow-hidden bg-[color:var(--background)] text-[color:var(--text)]",
  shouldShowDesktopSidebar && "md:grid md:grid-cols-[5.25rem_minmax(0,1fr)]",
  shouldShowDesktopSidebar &&
  sidebarColumnTransitionReady &&

src/components/clinical-dashboard/use-hide-on-scroll.ts

@@ -434,7 +434,8 @@ export function useScrollHideReporter(disabled = false, allowAllBreakpoints = fa
  * page scrolls the document above the phone breakpoint — GlobalSearchShell,
  * where `#main-content` is the scrollport only on phones and its `onScroll`
  * therefore never fires on tablet/desktop. Self-gating: while the document
- * cannot scroll (the phone shell is `fixed inset-0`) no scroll event arrives,
+ * cannot scroll (the phone shell is viewport-bounded and overflow-clipped) no
+ * scroll event arrives,
  * so the internal scroller stays the single source at that width.
  */
 export function useDocumentScrollHideReporter(reportScroll: (metrics: ScrollMetrics) => void) {

tests/clinical-dashboard-merge-artifacts.test.ts

@@ -118,6 +118,16 @@ describe("ClinicalDashboard merge-artifact guards", () => {
  expect(globalStylesSource).not.toMatch(/^\s*-webkit-backdrop-filter\s*:/m);
  });
 
+ it("keeps shared phone shells out of the iOS fixed-viewport compositor path", () => {
+ expect(globalSearchShellSource).toContain('"phone-viewport-shell sm:min-h-dvh');
+ expect(clinicalDashboardSource).toContain('"mobile-app-shell phone-viewport-shell flex');
+ expect(globalSearchShellSource).not.toContain("max-sm:fixed max-sm:inset-0");
+ expect(clinicalDashboardSource).not.toContain("max-sm:fixed max-sm:inset-0");
+ expect(globalStylesSource).toContain(".phone-viewport-shell {");
+ expect(globalStylesSource).toContain("position: relative;");
+ expect(globalStylesSource).toContain("height: 100dvh;");
+ });
+
  it("releases the Safari toolbar reserve only after phone composers hide", () => {
  expect(mobileComposerReserveSource).toContain('export const mobileComposerHiddenReserve = "0rem"');
  expect(mobileComposerReserveSource).toContain(

tests/ui-phone-scroll.spec.ts

@@ -290,6 +290,10 @@ test("phone chrome keeps an opaque header and a light edge-to-edge Therapy foote
  const dock = document.querySelector<HTMLElement>(".answer-footer-search-dock");
  const backdrop = dock?.querySelector<HTMLElement>(".answer-footer-search-backdrop");
  const main = document.getElementById("main-content");
+ const shell = main?.closest<HTMLElement>(".phone-viewport-shell");
+ const shellRect = shell?.getBoundingClientRect();
+ const mainRect = main?.getBoundingClientRect();
+ const bottomPaintOwner = document.elementFromPoint(window.innerWidth / 2, window.innerHeight - 1);
  return {
  collapseHeight: collapse?.getBoundingClientRect().height ?? -1,
  dockTop: dock?.getBoundingClientRect().top ?? -1,
@@ -298,6 +302,13 @@ test("phone chrome keeps an opaque header and a light edge-to-edge Therapy foote
  backdropOpacity: backdrop ? getComputedStyle(backdrop).opacity : "",
  backdropVisibility: backdrop ? getComputedStyle(backdrop).visibility : "",
  reserve: main ? getComputedStyle(main).getPropertyValue("--mobile-composer-reserve").trim() : "",
+ shellPosition: shell ? getComputedStyle(shell).position : "missing",
+ shellTop: shellRect?.top ?? -1,
+ shellBottom: shellRect?.bottom ?? -1,
+ mainBottom: mainRect?.bottom ?? -1,
+ bottomPaintOwnedByMain: Boolean(main && bottomPaintOwner && main.contains(bottomPaintOwner)),
+ scrollTop: main?.scrollTop ?? -1,
+ viewportHeight: window.innerHeight,
  };
  });
  expect(hidden.collapseHeight).toBeLessThanOrEqual(1);
@@ -307,6 +318,37 @@ test("phone chrome keeps an opaque header and a light edge-to-edge Therapy foote
  expect(hidden.backdropOpacity).toBe("0");
  expect(hidden.backdropVisibility).toBe("hidden");
  expect(hidden.reserve).toBe("0rem");
+ expect(hidden.shellPosition).toBe("relative");
+ expect(hidden.shellTop).toBeCloseTo(0, 0);
+ expect(hidden.shellBottom).toBeCloseTo(hidden.viewportHeight, 0);
+ expect(hidden.mainBottom).toBeCloseTo(hidden.viewportHeight, 0);
+ expect(hidden.bottomPaintOwnedByMain, "hidden chrome leaves live content at the last viewport pixel").toBe(true);
+
+ // Safari toolbar changes resize the visual viewport after scrolling. The
+ // in-flow shell must track that new edge without moving the reading offset;
+ // a viewport-sized fixed root passes these DOM bounds but can still mispaint
+ // a white compositor band on physical iOS.
+ await page.setViewportSize({ width: phoneViewport.width, height: phoneViewport.height - 64 });
+ await page.waitForTimeout(100);
+ const afterViewportResize = await page.evaluate(() => {
+ const main = document.getElementById("main-content");
+ const shell = main?.closest<HTMLElement>(".phone-viewport-shell");
+ const bottomPaintOwner = document.elementFromPoint(window.innerWidth / 2, window.innerHeight - 1);
+ return {
+ shellBottom: shell?.getBoundingClientRect().bottom ?? -1,
+ mainBottom: main?.getBoundingClientRect().bottom ?? -1,
+ bottomPaintOwnedByMain: Boolean(main && bottomPaintOwner && main.contains(bottomPaintOwner)),
+ scrollTop: main?.scrollTop ?? -1,
+ viewportHeight: window.innerHeight,
+ };
+ });
+ expect(afterViewportResize.shellBottom).toBeCloseTo(afterViewportResize.viewportHeight, 0);
+ expect(afterViewportResize.mainBottom).toBeCloseTo(afterViewportResize.viewportHeight, 0);
+ expect(afterViewportResize.bottomPaintOwnedByMain).toBe(true);
+ expect(afterViewportResize.scrollTop, "viewport resize does not jump the reading position").toBeCloseTo(
+ hidden.scrollTop,
+ 0,
+ );
 });
 
 test("calculators page-owned phone dock uses localized glass and releases its reserve when hidden", async ({
@@ -349,6 +391,10 @@ test("calculators page-owned phone dock uses localized glass and releases its re
  )
  .toBeGreaterThan(112);
 
+ // This journey owns the visible/hidden paint contract. Give it explicit
+ // runway so the separate near-bottom tests remain the sole owner of the
+ // intentional anti-clamp behavior on naturally short calculator pages.
+ await addPhoneScrollRunway(page);
  const geometry = await readGeometry(page);
  await dragScrollBy(page, Math.min(Math.max(geometry.maxOffset, 500), 900), 24);
  await expect(dock).toHaveAttribute("data-scroll-hidden", "true");
@@ -381,6 +427,7 @@ test("calculator dock clears its focus pin after a focused submit opens and clos
  await expect(page.getByRole("button", { name: "Close", exact: true })).toBeVisible();
  await page.getByRole("button", { name: "Close", exact: true }).click();
  await expect(dock).toBeVisible();
+ await expect(input).not.toBeFocused();
 
  await addPhoneScrollRunway(page);
  await dragScrollBy(page, 900, 24);

tests/ui-tools.spec.ts

@@ -265,7 +265,7 @@ async function gotoLauncher(page: Page, path = "/?mode=tools") {
  await expect(page.locator("#main-content").first()).toBeVisible({ timeout: 15_000 });
 }
 
-async function waitForReactEventHandler(locator: Locator, eventName: "onClick" | "onSubmit" = "onClick") {
+async function waitForReactEventHandler(locator: Locator, eventName: "onChange" | "onClick" | "onSubmit" = "onClick") {
  await expect
  .poll(
  async () =>
@@ -301,6 +301,14 @@ function visibleGlobalSearchInput(page: Page) {
  return page.locator('[data-testid="global-search-input"]:visible');
 }
 
+async function fillHydratedGlobalSearch(page: Page, value: string) {
+ const input = visibleGlobalSearchInput(page).first();
+ await expect(input).toBeVisible();
+ await waitForReactEventHandler(input, "onChange");
+ await input.fill(value);
+ await expect(input).toHaveValue(value);
+}
+
 async function globalSearchComposerMetrics(page: Page, homeTestId?: string) {
  return visibleGlobalSearchInput(page)
  .first()
@@ -429,7 +437,7 @@ test.describe("Clinical KB tools launcher", () => {
  await expect(page.getByTestId("tools-local-search-input")).toHaveCount(0);
 
  // Typing in the shared composer live-filters the tools grid, matching /?mode=tools.
- await visibleGlobalSearchInput(page).fill("medication");
+ await fillHydratedGlobalSearch(page, "medication");
  await expect(page.getByTestId("application-card-medication-prescribing")).toBeVisible();
  await expect(page.getByTestId("application-card-documents")).toBeHidden();
  await expectNoPageHorizontalOverflow(page);
@@ -462,7 +470,7 @@ test.describe("Clinical KB tools launcher", () => {
  await page.setViewportSize({ width: 1280, height: 900 });
  await gotoLauncher(page);
 
- await visibleGlobalSearchInput(page).fill("medication");
+ await fillHydratedGlobalSearch(page, "medication");
 
  await expect(page.getByTestId("application-card-medication-prescribing")).toBeVisible();
  await expect(page.getByTestId("application-card-documents")).toBeHidden();