From 641c822f4947211df78ba5e82e66b55fe2250222 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 03:50:02 +0800
Subject: [PATCH 01/16] feat(ui): portal Therapy section nav into header
 collapse on phones

Anchor the Therapy secondary strip inside universal-header-collapse so it
hides and reveals with the top bar on the shared scroll signal. Desktop
keeps the in-flow sticky nav in the workspace.
---
 docs/search-chrome-behaviour.md               |  22 +--
 .../global-search-shell.tsx                   |  13 +-
 .../master-search-header.tsx                  | 142 ++++++++++--------
 src/components/therapy-compass/nav.tsx        |  34 ++++-
 .../therapy-compass/therapy-compass.css       |   8 +
 src/lib/mode-home-composer.ts                 |   6 +
 tests/header-scroll-hide-contract.test.ts     |  67 +++++----
 7 files changed, 192 insertions(+), 100 deletions(-)

diff --git a/docs/search-chrome-behaviour.md b/docs/search-chrome-behaviour.md
index a9b086bb9..81615e9d5 100644
--- a/docs/search-chrome-behaviour.md
+++ b/docs/search-chrome-behaviour.md
@@ -19,7 +19,7 @@ This repo uses one shared search experience across the global shell, dashboard r
 3. A visible fixed phone dock may include `var(--safe-area-bottom)` so the pill clears the home indicator.
 4. A hidden phone dock must release the content-facing reserve to `0rem`; do not use `env(safe-area-inset-bottom)` or `var(--safe-area-bottom)` for hidden content padding.
 5. Edge-to-edge phone dock mode is `left: 0; right: 0; bottom: 0; width: 100%`; inset the pill with padding, not with a non-zero bottom offset.
-6. Header and footer chrome that share the same scroll signal should hide/reveal symmetrically: when hidden, underlying content must be visible to the viewport edge. Header hide/reveal is cross-breakpoint; the bottom search dock is phone-only. Read "Scroll hide/reveal" below before changing either.
+6. Header and footer chrome that share the same scroll signal should hide/reveal symmetrically for the surfaces that actually hide: when the top bar is hidden, underlying content must be visible to the viewport edge. Top-bar hide/reveal is cross-breakpoint; the search field stays on tablet/desktop; the bottom search dock is phone-only. Read "Scroll hide/reveal" below before changing either.
 7. Do not add page-local dock-sized `pb-[calc(...safe-area...)]` under a shell-owned dock. Put clearance in the shared reserve or the page-owned composer, never both.
 8. `GlobalSearchShell` uses an inner `mobile-composer-reserve-pad` so phone padding contributes to scroll height; do not move phone shell clearance back to scrollport padding without a browser proof.
 9. Keep collapse-budget policy geometry-aware: an in-flow collapsing header needs enough remaining runway to absorb header + dock clearance, while a fixed overlay that only releases bottom reserve may hide when its post-collapse range retains the top reveal band plus deliberate hide intent _and_ the current offset already fits that post-collapse range (no material near-bottom clamp). Do not use synthetic page padding to make the stricter gate pass.
@@ -27,25 +27,25 @@ This repo uses one shared search experience across the global shell, dashboard r
 
 ## Scroll hide/reveal
 
-The universal header hides on a deliberate scroll down and returns on a deliberate scroll up at **every** breakpoint. The bottom search dock keeps that behaviour on phones only — on tablet and desktop the composer sits in the hero or the header, where there is nothing to reclaim. Both read one `useScrollHideReporter` per host, so the header and the phone dock can never disagree about direction.
+The universal **top bar** (mode, new chat, menu) hides on a deliberate scroll down and returns on a deliberate scroll up at **every** breakpoint. The search field does **not** hide with it on tablet or desktop — only the phone bottom search dock still scroll-hides, and that stays phone-only. Both the top bar and the phone dock read one `useScrollHideReporter` per host, so they can never disagree about direction.
 
 Choose the hide mechanism from where the host's scrollport lives, because that decides what hiding costs the reader:
 
-| Host                              | Scrollport                                    | `hideOnScroll`                           | Mechanism                                                                |
-| --------------------------------- | --------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
-| `ClinicalDashboard` (answer view) | `<main>` at every width                       | `strategy: "overlay", allBreakpoints`    | Absolute glass bar translates off; `<main>` keeps its top reserve        |
-| `ClinicalDashboard` (other modes) | `<main>` at every width                       | `strategy: "collapse", wide: "collapse"` | 1fr -> 0fr grid row; the released strip goes straight to the content     |
-| `GlobalSearchShell`               | `#main-content` on phones, the document above | `strategy: "collapse", wide: "sticky"`   | Grid collapse on phones; sticks to the viewport top and translates above |
+| Host                              | Scrollport                                    | `hideOnScroll`                           | Mechanism                                                                                          |
+| --------------------------------- | --------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `ClinicalDashboard` (answer view) | `<main>` at every width                       | `strategy: "overlay", allBreakpoints`    | Absolute glass top bar translates off; `<main>` keeps its top reserve; search stays                |
+| `ClinicalDashboard` (other modes) | `<main>` at every width                       | `strategy: "collapse", wide: "collapse"` | Top-bar 1fr -> 0fr grid row; released strip goes to content; search stays as a sibling             |
+| `GlobalSearchShell`               | `#main-content` on phones, the document above | `strategy: "collapse", wide: "sticky"`   | Sticky stack of [top bar \| search]; only the top-bar row collapses so search rises to the top     |
 
 Rules that keep this working:
 
+- **Hide the top bar, not the search field, above phones.** The collapse wrapper (`data-testid="universal-header-collapse"`) must wrap only `header#search`. Putting the inline composer inside that wrapper is what made tablet/desktop search disappear with the mode bar.
 - **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.
-- **Do not release flow space out of a document-scrolled page.** Collapsing the header row while the document scrolls pulls the whole page up by the header height mid-scroll. Stick and translate instead; `readChromeCollapseBudget` therefore charges the header's height against the scroll runway only while the wrapper is a grid at the current width.
-- **Sticky belongs on the collapse wrapper, not on `header#search`.** The header sits inside two header-height boxes, which leaves a sticky rule on it zero travel — that is what made the desktop bar scroll away and only return at the top of the page. For the same reason the wrapper's ancestor in `GlobalSearchShell` is `display: contents` above the phone breakpoint rather than a block.
-- **Transform only while hidden.** A standing transform on the wrapper would become the containing block for the fixed-position menus and composers rendered inside it.
+- **Sticky 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.
+- **Collapse only the top-bar row inside a sticky stack.** Translating the whole stack would take the search field off-screen; collapsing just the top bar lets search stay pinned at the viewport top.
 - **Rebase the reporter on geometry switches.** Pass `resetKey` when the host changes the scrollport under it (`ClinicalDashboard` passes `searchMode`, which swaps `<main>`'s header reserve); otherwise the carried-over offset spends the first post-switch scroll on a spurious hide or reveal.
 
-Coverage: `tests/header-scroll-hide-contract.test.ts` (wiring), `tests/use-hide-on-scroll.test.ts` (decision logic), `tests/ui-chrome-scroll.spec.ts` (tablet/desktop hide and reveal), `tests/ui-phone-scroll.spec.ts` (phone scroll geometry).
+Coverage: `tests/header-scroll-hide-contract.test.ts` (wiring), `tests/use-hide-on-scroll.test.ts` (decision logic), `tests/ui-chrome-scroll.spec.ts` (tablet/desktop top-bar hide/reveal with search still visible), `tests/ui-phone-scroll.spec.ts` (phone scroll geometry).
 
 ## Change checklist
 
diff --git a/src/components/clinical-dashboard/global-search-shell.tsx b/src/components/clinical-dashboard/global-search-shell.tsx
index 3cb196565..0be485e02 100644
--- a/src/components/clinical-dashboard/global-search-shell.tsx
+++ b/src/components/clinical-dashboard/global-search-shell.tsx
@@ -57,7 +57,11 @@ import {
 import { isLocalNoAuthMode, resolveClientDemoMode } from "@/lib/client-env";
 import { documentsSearchHref } from "@/lib/document-flow-routes";
 import { isInformationPage } from "@/lib/information-pages";
-import { differentialsMobileCompareAddonSlotId, modeHomeDesktopComposerSlotId } from "@/lib/mode-home-composer";
+import {
+  differentialsMobileCompareAddonSlotId,
+  modeHomeDesktopComposerSlotId,
+  therapyHeaderCollapseAddonSlotId,
+} from "@/lib/mode-home-composer";
 import { readSearchNavigationContext, type SearchNavigationOptions } from "@/lib/search-navigation-context";
 import { shouldRenderClinicalDashboard, shouldRenderDashboardSearch } from "@/lib/search-route-ownership";
 import type { SearchScopeFilters } from "@/lib/search-scope";
@@ -710,6 +714,13 @@ function GlobalStandaloneSearchShellClient({
             mobileBottomSearchAddonSlotId={
               differentialsCompareAddonActive ? differentialsMobileCompareAddonSlotId : undefined
             }
+            // Therapy non-home screens portal their section strip into the
+            // collapsing top-bar track so it hides/reveals with the header.
+            headerCollapseAddonSlotId={
+              pathname.startsWith("/therapy-compass") && pathname !== "/therapy-compass"
+                ? therapyHeaderCollapseAddonSlotId
+                : undefined
+            }
             desktopSearchPlacement={desktopSearchPlacement === "hero" && isStandaloneModeHome ? "hero" : "default"}
             searchComposerVisible={shouldShowSearchComposer}
             desktopHomeComposerSlotId={isStandaloneModeHome ? modeHomeDesktopComposerSlotId : undefined}
diff --git a/src/components/clinical-dashboard/master-search-header.tsx b/src/components/clinical-dashboard/master-search-header.tsx
index 3830aa9fa..dda3d0213 100644
--- a/src/components/clinical-dashboard/master-search-header.tsx
+++ b/src/components/clinical-dashboard/master-search-header.tsx
@@ -185,6 +185,7 @@ export function MasterSearchHeader({
   desktopHomeComposerSlotId,
   heroComposerBreakpoint = "all",
   mobileBottomSearchAddonSlotId,
+  headerCollapseAddonSlotId,
   mobileLeadingAction = "menu",
   onMobileBack,
   hideOnScroll,
@@ -249,6 +250,12 @@ export function MasterSearchHeader({
   heroComposerBreakpoint?: "all" | "sm-up";
   /** Mobile/tablet slot rendered above the search pill for page-specific composer addons. */
   mobileBottomSearchAddonSlotId?: string;
+  /**
+   * Optional host rendered inside the collapsing top-bar track (after `header#search`)
+   * for page chrome that must hide/reveal with the universal top bar — e.g. Therapy
+   * section nav on phones. Keep search composers out of this slot.
+   */
+  headerCollapseAddonSlotId?: string;
   mobileLeadingAction?: "menu" | "back";
   onMobileBack?: () => void;
   /** Phone-only hide-on-scroll for the universal header and bottom search dock.
@@ -270,14 +277,15 @@ export function MasterSearchHeader({
      * Collapse-only: how the chrome hides above the phone breakpoint. Omitting
      * it keeps the hide/reveal phone-only.
      *
-     * "collapse" releases the header's layout row at every width — for hosts
+     * "collapse" releases the top bar's layout row at every width — for hosts
      * whose scrollport is an internal element at every width (ClinicalDashboard's
      * `<main>`), where the released strip goes straight to the content.
      *
-     * "sticky" pins the chrome to the viewport top and slides it away instead —
-     * for hosts that hand scrolling back to the document above the phone
-     * breakpoint (GlobalSearchShell), where releasing flow space would jump the
-     * page under the reader.
+     * "sticky" pins an outer stack (top bar + search) to the viewport top above
+     * phones and still collapses only the top-bar row inside that stack — for
+     * hosts that hand scrolling back to the document (GlobalSearchShell). The
+     * search composer must stay outside the collapsing row so tablet/desktop
+     * keep a usable search field.
      */
     wide?: "collapse" | "sticky";
     /** Parent-owned hidden state for hosts that report scroll via React `onScroll`. */
@@ -1732,8 +1740,11 @@ export function MasterSearchHeader({
       }
     : undefined;
 
-  const headerAndComposer = (
-    <>
+  // Top bar only (mode / new chat / menu). The search composer is intentionally
+  // NOT part of this node: on tablet/desktop hide-on-scroll must reclaim the top
+  // bar without taking the search field with it. Phone bottom docks are fixed and
+  // escape any collapse wrapper; hero composers portal out of this tree.
+  const topBar = (
       <header
         id="search"
         data-scroll-hidden={hideStrategy === "overlay" && headerChromeHidden ? "true" : undefined}
@@ -1742,17 +1753,14 @@ export function MasterSearchHeader({
           // root and starve the .edge-glass-header-backdrop scrim (the single
           // source of the bar's frost) of the real page behind it.
           "edge-glass-header universal-header z-30 py-2 pt-[max(0.5rem,env(safe-area-inset-top))] text-[color:var(--text)]",
-          // Collapse hosts keep the header above an internally scrolling <main>,
+          // Collapse hosts keep the top bar above an internally scrolling <main>,
           // so sticky is unnecessary wherever the row collapses and fights the
-          // 0fr grid by pinning the bar inside the viewport. Where the chrome
-          // sticks instead, the pinning belongs to the collapse wrapper: this
-          // <header> sits inside two header-height boxes, which leaves a sticky
-          // rule here zero travel — the bar simply scrolled off with the page
-          // and only came back at scroll top. All-breakpoints overlay hosts take
-          // the header out of flow entirely (absolute over the padded <main>) —
-          // sticky would be inert there because the scroll container is <main>,
-          // not an ancestor of the header. Legacy overlay hosts keep sticky
-          // (they ride document scroll) and translate away with no layout shift.
+          // 0fr grid by pinning the bar inside the viewport. Sticky hosts pin an
+          // outer stack (top bar + search) instead; this <header> stays relative
+          // inside that stack. All-breakpoints overlay hosts take the bar out of
+          // flow entirely (absolute over the padded <main>). Legacy overlay hosts
+          // keep sticky (they ride document scroll) and translate away with no
+          // layout shift.
           hideStrategy === "collapse"
             ? sticksAbovePhones || collapsesAtEveryWidth
               ? "relative"
@@ -1962,42 +1970,41 @@ export function MasterSearchHeader({
           </Sheet>
         ) : null}
       </header>
-
-      {searchComposerVisible ? (
-        <>
-          {(desktopHomeComposerActive && desktopHomeComposerHost) ||
-          (desktopHomeComposerSlotId && !desktopHomeComposerFallback)
-            ? null
-            : renderSearchComposer("default")}
-          {desktopHomeComposerActive && desktopHomeComposerHost
-            ? createPortal(renderSearchComposer("desktop-home"), desktopHomeComposerHost)
-            : null}
-        </>
-      ) : null}
-    </>
   );
 
+  const searchComposer =
+    searchComposerVisible ? (
+      <>
+        {(desktopHomeComposerActive && desktopHomeComposerHost) ||
+        (desktopHomeComposerSlotId && !desktopHomeComposerFallback)
+          ? null
+          : renderSearchComposer("default")}
+        {desktopHomeComposerActive && desktopHomeComposerHost
+          ? createPortal(renderSearchComposer("desktop-home"), desktopHomeComposerHost)
+          : null}
+      </>
+    ) : null;
+
   if (hideStrategy === "collapse") {
-    // Collapse hide-on-scroll: the host renders the header above an internally
-    // scrolling element, so hiding must also release the header's layout space.
-    // A 1fr -> 0fr grid row animates the collapse without any height
-    // measurement; the bottom-anchored inner track makes the chrome slide up
-    // out of the viewport top. Fixed-position composers (answer footer, mobile
-    // bottom search) escape the wrapper naturally because it carries no
-    // transform in this mode.
+    // Collapse hide-on-scroll applies to the TOP BAR only (mode / new chat). The
+    // search composer stays a sibling so tablet/desktop keep a usable search
+    // field while the top bar hides. A 1fr -> 0fr grid row animates the collapse
+    // without height measurement; the bottom-anchored inner track slides the
+    // top bar up out of the viewport. Fixed-position phone docks escape this
+    // tree via `position: fixed`; hero composers portal out.
     //
-    // Above the phone breakpoint a `wide: "sticky"` host scrolls the document
-    // instead, so this wrapper — not the <header> inside it, which has no
-    // sticky travel within its header-height parents — pins to the viewport top
-    // and translates away. Releasing the row there would pull the whole page up
-    // by the header height mid-scroll; translating leaves the geometry alone.
-    return (
+    // Above the phone breakpoint a `wide: "sticky"` host scrolls the document,
+    // so an outer sticky stack pins [top bar | search] to the viewport and the
+    // collapse row still only wraps the top bar — translating the whole stack
+    // would take the search field with it. Releasing only the top-bar row lets
+    // the search rise to the viewport top.
+    const collapsingTopBar = (
       <div
         data-scroll-hidden={headerChromeHidden ? "true" : undefined}
         data-testid="universal-header-collapse"
         className={cn(
           "motion-reduce:transition-none",
-          collapsesAtEveryWidth
+          collapsesAtEveryWidth || sticksAbovePhones
             ? cn(
                 "grid transition-[grid-template-rows]",
                 headerChromeHidden
@@ -2011,17 +2018,6 @@ export function MasterSearchHeader({
                   ? "max-sm:duration-[240ms] max-sm:ease-[cubic-bezier(0.4,0,0.2,1)]"
                   : "max-sm:duration-200 max-sm:ease-[cubic-bezier(0.22,1,0.36,1)]",
                 headerChromeHidden ? "max-sm:[grid-template-rows:0fr]" : "max-sm:[grid-template-rows:1fr]",
-                sticksAbovePhones &&
-                  cn(
-                    "sm:sticky sm:top-0 sm:z-30 sm:transition-transform",
-                    headerChromeHidden
-                      ? "sm:duration-[240ms] sm:ease-[cubic-bezier(0.4,0,0.2,1)]"
-                      : "sm:duration-200 sm:ease-[cubic-bezier(0.22,1,0.36,1)]",
-                  ),
-                // Transform only while hidden: a standing transform would make
-                // this wrapper the containing block for the fixed-position menus
-                // and composers rendered inside it.
-                sticksAbovePhones && headerChromeHidden && "sm:-translate-y-full",
               ),
         )}
         {...chromeFocusProps}
@@ -2029,18 +2025,46 @@ export function MasterSearchHeader({
         <div
           className={cn(
             "max-sm:flex max-sm:min-h-0 max-sm:flex-col max-sm:justify-end",
-            collapsesAtEveryWidth && "sm:flex sm:min-h-0 sm:flex-col sm:justify-end",
+            (collapsesAtEveryWidth || sticksAbovePhones) && "sm:flex sm:min-h-0 sm:flex-col sm:justify-end",
             // Clip only while hiding so the edge-glass-header gradient that
             // extends below the header keeps painting when the chrome is shown.
             headerChromeHidden && "max-sm:overflow-hidden",
-            collapsesAtEveryWidth && headerChromeHidden && "sm:overflow-hidden",
+            (collapsesAtEveryWidth || sticksAbovePhones) && headerChromeHidden && "sm:overflow-hidden",
           )}
         >
-          {headerAndComposer}
+          {topBar}
+          {headerCollapseAddonSlotId ? (
+            <div
+              id={headerCollapseAddonSlotId}
+              data-testid="header-collapse-addon"
+              className="w-full empty:hidden"
+            />
+          ) : null}
         </div>
       </div>
     );
+
+    if (sticksAbovePhones) {
+      return (
+        <div className="sm:sticky sm:top-0 sm:z-30">
+          {collapsingTopBar}
+          {searchComposer}
+        </div>
+      );
+    }
+
+    return (
+      <>
+        {collapsingTopBar}
+        {searchComposer}
+      </>
+    );
   }
 
-  return headerAndComposer;
+  return (
+    <>
+      {topBar}
+      {searchComposer}
+    </>
+  );
 }
diff --git a/src/components/therapy-compass/nav.tsx b/src/components/therapy-compass/nav.tsx
index 014655dde..3253d2562 100644
--- a/src/components/therapy-compass/nav.tsx
+++ b/src/components/therapy-compass/nav.tsx
@@ -1,13 +1,38 @@
 "use client";
 
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+
+import { therapyHeaderCollapseAddonSlotId } from "@/lib/mode-home-composer";
+
 import { useTcBindings } from "./bindings";
 
+// Matches phoneSearchLayoutMediaQuery in master-search-header.tsx and
+// phoneMediaQuery in use-hide-on-scroll.ts — the shared phone/tablet seam.
+const phoneCollapseMediaQuery = "(max-width: 639px)";
+
 /** Core Therapy destinations for non-home screens. */
 export function TherapyCompassNav() {
   const b = useTcBindings();
+  const [phoneHost, setPhoneHost] = useState<HTMLElement | null>(null);
 
-  return (
-    <div className="tc-topnav tc-no-print tc-nav-001">
+  useEffect(() => {
+    const phoneMedia = window.matchMedia(phoneCollapseMediaQuery);
+    const sync = () => {
+      setPhoneHost(phoneMedia.matches ? document.getElementById(therapyHeaderCollapseAddonSlotId) : null);
+    };
+    sync();
+    phoneMedia.addEventListener("change", sync);
+    const observer = new MutationObserver(sync);
+    observer.observe(document.body, { childList: true, subtree: true });
+    return () => {
+      phoneMedia.removeEventListener("change", sync);
+      observer.disconnect();
+    };
+  }, []);
+
+  const navShell = (
+    <div className="tc-topnav tc-no-print tc-nav-001" data-testid="therapy-compass-section-nav">
       <nav className="tc-scroll tc-nav-007" aria-label="Therapy sections">
         <button
           type="button"
@@ -159,4 +184,9 @@ export function TherapyCompassNav() {
       </nav>
     </div>
   );
+
+  // Phones: portal into the collapsing top-bar track so the strip hides/reveals
+  // with the universal header. sm+: keep in-flow sticky inside the workspace.
+  if (phoneHost) return createPortal(navShell, phoneHost);
+  return navShell;
 }
diff --git a/src/components/therapy-compass/therapy-compass.css b/src/components/therapy-compass/therapy-compass.css
index 820619cea..3a7261ac4 100644
--- a/src/components/therapy-compass/therapy-compass.css
+++ b/src/components/therapy-compass/therapy-compass.css
@@ -1050,6 +1050,14 @@
   backdrop-filter: blur(12px);
   border-bottom: 1px solid var(--border);
 }
+
+/* Portaled under the universal header on phones: the collapse row owns
+   stacking/hide, so sticky would fight the shared chrome geometry. */
+#therapy-header-collapse-addon-slot .tc-nav-001 {
+  position: relative;
+  top: auto;
+  z-index: auto;
+}
 .tc-root .tc-nav-007 {
   display: flex;
   align-items: center;
diff --git a/src/lib/mode-home-composer.ts b/src/lib/mode-home-composer.ts
index a5a5d3ddc..4e5b71e36 100644
--- a/src/lib/mode-home-composer.ts
+++ b/src/lib/mode-home-composer.ts
@@ -2,3 +2,9 @@ export const modeHomeDesktopComposerSlotId = "mode-home-desktop-composer-slot";
 
 /** Mobile/tablet search-composer slot for differentials compare actions. */
 export const differentialsMobileCompareAddonSlotId = "differentials-mobile-compare-addon-slot";
+
+/**
+ * Host inside `universal-header-collapse` for Therapy section nav on phones.
+ * Portaled chrome here hides/reveals with the top bar on the shared scroll signal.
+ */
+export const therapyHeaderCollapseAddonSlotId = "therapy-header-collapse-addon-slot";
diff --git a/tests/header-scroll-hide-contract.test.ts b/tests/header-scroll-hide-contract.test.ts
index 65d33a23f..24a6a2990 100644
--- a/tests/header-scroll-hide-contract.test.ts
+++ b/tests/header-scroll-hide-contract.test.ts
@@ -3,15 +3,14 @@ import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
 /**
- * Static contract for the shared header hide/reveal.
+ * Static contract for the shared top-bar hide/reveal.
  *
- * The header hides on scroll down and returns on scroll up at every breakpoint,
- * while the bottom search dock stays a phone-only behaviour. Getting that right
- * depends on three things no runtime unit test can see: which scroll source
- * feeds the reporter at each width, whether the chrome collapses its layout row
- * or sticks and translates, and whether the sticky wrapper actually has any
- * travel against the viewport. Each was individually wrong at some point while
- * the desktop header "only came back at the top of the page".
+ * The top bar (mode / new chat) hides on scroll down and returns on scroll up at
+ * every breakpoint, while the search field stays on tablet/desktop and the
+ * bottom search dock stays phone-only. Getting that right depends on wiring no
+ * runtime unit test can see: which scroll source feeds the reporter, whether
+ * only `header#search` is inside the collapse row, and whether sticky hosts pin
+ * an outer [top bar | search] stack instead of translating the search away.
  *
  * The Chromium proof lives in tests/ui-chrome-scroll.spec.ts; this file keeps
  * the cheap suite honest about the wiring that proof depends on.
@@ -42,26 +41,39 @@ describe("shared header hide/reveal wiring", () => {
 
   it("picks the hide mechanism from where each host's scrollport lives", () => {
     // GlobalSearchShell hands scrolling back to the document above phones, so
-    // releasing the header's flow row there would jump the page mid-scroll.
+    // the outer stack sticks while only the top-bar row collapses.
     expect(shellSource).toContain('hideOnScroll={{ strategy: "collapse", wide: "sticky"');
     // ClinicalDashboard's <main> is the scrollport at every width (the shell is
-    // dvh-tall and overflow-hidden), so the released strip goes to the content.
+    // dvh-tall and overflow-hidden), so the released top-bar strip goes to the
+    // content.
     expect(dashboardSource).toContain('{ strategy: "collapse", wide: "collapse"');
   });
 
-  it("gives the sticky chrome wrapper real travel against the viewport", () => {
-    // A plain block here is a header-height containing block, which leaves the
-    // wrapper's sticky rule nowhere to stick: the bar scrolled off with the
-    // page and only reappeared at scroll top. `contents` removes that box.
-    expect(shellSource).toContain('className={mobileChromeVisible ? "sm:contents" : "hidden lg:contents"}');
-    expect(shellSource).not.toContain('mobileChromeVisible ? undefined : "hidden lg:block"');
-    expect(headerSource).toContain("sm:sticky sm:top-0 sm:z-30 sm:transition-transform");
+  it("collapses only the top bar and keeps the search composer outside that row", () => {
+    // Wrapping headerAndComposer (top bar + search) is what made tablet/desktop
+    // search disappear with the mode bar.
+    expect(headerSource).toContain("const collapsingTopBar = (");
+    expect(headerSource).toContain("{topBar}");
+    expect(headerSource).toContain("{searchComposer}");
+    expect(headerSource).not.toContain("{headerAndComposer}");
+    // The collapse testid must sit on the top-bar wrapper, not a joint stack.
+    const collapseIdx = headerSource.indexOf('data-testid="universal-header-collapse"');
+    const topBarCloseIdx = headerSource.indexOf("{topBar}", collapseIdx);
+    const composerIdx = headerSource.indexOf("{searchComposer}", collapseIdx);
+    expect(collapseIdx).toBeGreaterThan(-1);
+    expect(topBarCloseIdx).toBeGreaterThan(collapseIdx);
+    expect(composerIdx).toBeGreaterThan(topBarCloseIdx);
   });
 
-  it("transforms the sticky wrapper only while the chrome is hidden", () => {
-    // A standing transform would make the wrapper the containing block for the
-    // fixed-position menus and composers rendered inside it.
-    expect(headerSource).toContain('sticksAbovePhones && headerChromeHidden && "sm:-translate-y-full"');
+  it("gives the sticky chrome stack real travel against the viewport", () => {
+    // A plain block around the stack is a containing block that leaves sticky
+    // nowhere to stick. `contents` removes that box on GlobalSearchShell.
+    expect(shellSource).toContain('className={mobileChromeVisible ? "sm:contents" : "hidden lg:contents"}');
+    expect(shellSource).not.toContain('mobileChromeVisible ? undefined : "hidden lg:block"');
+    // Sticky pins the outer [top bar | search] stack; translating that whole
+    // stack would take the search field off-screen.
+    expect(headerSource).toContain('className="sm:sticky sm:top-0 sm:z-30"');
+    expect(headerSource).not.toContain("sm:-translate-y-full");
   });
 
   it("keeps the header out of sticky positioning wherever its row collapses", () => {
@@ -70,8 +82,8 @@ describe("shared header hide/reveal wiring", () => {
   });
 
   it("counts the collapse budget only where the wrapper really collapses", () => {
-    // Chrome that sticks and translates releases no layout, so charging the
-    // header's height against the scroll runway would suppress valid hides.
+    // Sticky hosts now collapse only the top-bar row (still `display: grid`), so
+    // the budget correctly charges that height; non-grid wrappers stay at 0.
     expect(hookSource).toContain('window.getComputedStyle(collapse).display === "grid"');
   });
 
@@ -83,8 +95,8 @@ describe("shared header hide/reveal wiring", () => {
   });
 
   it("keeps the bottom search dock a phone-only behaviour", () => {
-    // The user-visible contract: the header hides everywhere, the footer search
-    // bar hides on phones only. Both gates below require the phone layout.
+    // The user-visible contract: the top bar hides everywhere, the footer
+    // search bar hides on phones only. Both gates below require the phone layout.
     expect(headerSource).toContain(
       "const bottomComposerScrollHiddenActive = Boolean(hideOnScroll && phoneBottomSearchDockActive);",
     );
@@ -92,7 +104,8 @@ describe("shared header hide/reveal wiring", () => {
     expect(headerSource).toContain("const usesPhoneFooterDock = usesBottomComposerPlacement && usesPhoneSearchLayout;");
   });
 
-  it("documents the cross-breakpoint behaviour alongside the code", () => {
-    expect(behaviourDocSource).toContain("Header hide/reveal is cross-breakpoint");
+  it("documents that tablet/desktop search stays while the top bar hides", () => {
+    expect(behaviourDocSource).toContain("Hide the top bar, not the search field, above phones");
+    expect(behaviourDocSource).toContain("Top-bar hide/reveal is cross-breakpoint");
   });
 });

From 086c1dca2c39d8cfaf62e80d11e8ce33fd206b78 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 03:51:08 +0800
Subject: [PATCH 02/16] test(ui): contract and Playwright proof for Therapy nav
 collapse

Document the header-collapse addon rule and lock the phone portal wiring
with static contracts plus a Chromium hide/reveal check.
---
 docs/search-chrome-behaviour.md               |   5 +-
 .../global-search-shell.tsx                   |   7 +-
 tests/header-scroll-hide-contract.test.ts     |  19 ++-
 ...herapy-compass-responsive-contract.test.ts |  17 +++
 tests/ui-therapy-nav-scroll.spec.ts           | 144 ++++++++++++++++++
 5 files changed, 186 insertions(+), 6 deletions(-)
 create mode 100644 tests/ui-therapy-nav-scroll.spec.ts

diff --git a/docs/search-chrome-behaviour.md b/docs/search-chrome-behaviour.md
index 81615e9d5..b45eb3171 100644
--- a/docs/search-chrome-behaviour.md
+++ b/docs/search-chrome-behaviour.md
@@ -39,13 +39,14 @@ Choose the hide mechanism from where the host's scrollport lives, because that d
 
 Rules that keep this working:
 
-- **Hide the top bar, not the search field, above phones.** The collapse wrapper (`data-testid="universal-header-collapse"`) must wrap only `header#search`. Putting the inline composer inside that wrapper is what made tablet/desktop search disappear with the mode bar.
+- **Hide the top bar, not the search field, above phones.** The collapse wrapper (`data-testid="universal-header-collapse"`) wraps `header#search` plus optional page chrome that must match top-bar hide/reveal (via `headerCollapseAddonSlotId`). Putting the inline search composer inside that wrapper is what made tablet/desktop search disappear with the mode bar — keep composers outside the collapse row.
+- **Page chrome that must match the top bar portals into the collapse host.** Do not pin tool secondary nav with `position: sticky` inside `#main-content` on phones — after the header collapses that sticky row becomes a second stuck header. Therapy's section strip portals into `#therapy-header-collapse-addon-slot` below `max-sm` and stays in-flow sticky above that.
 - **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.
 - **Sticky 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.
 - **Collapse only the top-bar row inside a sticky stack.** Translating the whole stack would take the search field off-screen; collapsing just the top bar lets search stay pinned at the viewport top.
 - **Rebase the reporter on geometry switches.** Pass `resetKey` when the host changes the scrollport under it (`ClinicalDashboard` passes `searchMode`, which swaps `<main>`'s header reserve); otherwise the carried-over offset spends the first post-switch scroll on a spurious hide or reveal.
 
-Coverage: `tests/header-scroll-hide-contract.test.ts` (wiring), `tests/use-hide-on-scroll.test.ts` (decision logic), `tests/ui-chrome-scroll.spec.ts` (tablet/desktop top-bar hide/reveal with search still visible), `tests/ui-phone-scroll.spec.ts` (phone scroll geometry).
+Coverage: `tests/header-scroll-hide-contract.test.ts` (wiring), `tests/use-hide-on-scroll.test.ts` (decision logic), `tests/ui-chrome-scroll.spec.ts` (tablet/desktop top-bar hide/reveal with search still visible), `tests/ui-phone-scroll.spec.ts` (phone scroll geometry), `tests/ui-therapy-nav-scroll.spec.ts` (Therapy section nav hide/reveal with the top bar).
 
 ## Change checklist
 
diff --git a/src/components/clinical-dashboard/global-search-shell.tsx b/src/components/clinical-dashboard/global-search-shell.tsx
index 0be485e02..f1b90fb03 100644
--- a/src/components/clinical-dashboard/global-search-shell.tsx
+++ b/src/components/clinical-dashboard/global-search-shell.tsx
@@ -730,9 +730,10 @@ function GlobalStandaloneSearchShellClient({
             // docking to the bottom edge.
             heroComposerBreakpoint="all"
             // Phones: #main-content owns vertical scroll, so hide-on-scroll
-            // collapses the header/composer to hand space back to content.
-            // Tablet/desktop: the document scrolls, so the chrome sticks to the
-            // viewport top and slides away instead of releasing flow space.
+            // collapses the top bar to hand space back to content.
+            // Tablet/desktop: the document scrolls, so an outer sticky stack
+            // pins [top bar | search] and only the top-bar row collapses —
+            // translating the whole stack would take the search field with it.
             hideOnScroll={{ strategy: "collapse", wide: "sticky", scrollHidden: chromeScrollHide.hidden }}
             onBottomComposerHiddenChange={setBottomComposerHidden}
             queryInputAutoFocus={searchParams.get("focus") === "1"}
diff --git a/tests/header-scroll-hide-contract.test.ts b/tests/header-scroll-hide-contract.test.ts
index 24a6a2990..02d189243 100644
--- a/tests/header-scroll-hide-contract.test.ts
+++ b/tests/header-scroll-hide-contract.test.ts
@@ -59,10 +59,26 @@ describe("shared header hide/reveal wiring", () => {
     // The collapse testid must sit on the top-bar wrapper, not a joint stack.
     const collapseIdx = headerSource.indexOf('data-testid="universal-header-collapse"');
     const topBarCloseIdx = headerSource.indexOf("{topBar}", collapseIdx);
+    const addonIdx = headerSource.indexOf("headerCollapseAddonSlotId", topBarCloseIdx);
     const composerIdx = headerSource.indexOf("{searchComposer}", collapseIdx);
     expect(collapseIdx).toBeGreaterThan(-1);
     expect(topBarCloseIdx).toBeGreaterThan(collapseIdx);
-    expect(composerIdx).toBeGreaterThan(topBarCloseIdx);
+    // Optional page chrome (Therapy section nav) may sit after the top bar
+    // inside the collapse row; the search composer must stay outside it.
+    expect(addonIdx).toBeGreaterThan(topBarCloseIdx);
+    expect(composerIdx).toBeGreaterThan(addonIdx);
+  });
+
+  it("hosts Therapy section nav inside the collapse row on non-home therapy routes", () => {
+    expect(shellSource).toContain("therapyHeaderCollapseAddonSlotId");
+    expect(shellSource).toContain('pathname.startsWith("/therapy-compass") && pathname !== "/therapy-compass"');
+    expect(headerSource).toContain('data-testid="header-collapse-addon"');
+    // Addon host must be declared inside collapsingTopBar, not beside search.
+    const collapseIdx = headerSource.indexOf('data-testid="universal-header-collapse"');
+    const addonHostIdx = headerSource.indexOf('data-testid="header-collapse-addon"', collapseIdx);
+    const collapsingClose = headerSource.indexOf("if (sticksAbovePhones)", collapseIdx);
+    expect(addonHostIdx).toBeGreaterThan(collapseIdx);
+    expect(addonHostIdx).toBeLessThan(collapsingClose);
   });
 
   it("gives the sticky chrome stack real travel against the viewport", () => {
@@ -107,5 +123,6 @@ describe("shared header hide/reveal wiring", () => {
   it("documents that tablet/desktop search stays while the top bar hides", () => {
     expect(behaviourDocSource).toContain("Hide the top bar, not the search field, above phones");
     expect(behaviourDocSource).toContain("Top-bar hide/reveal is cross-breakpoint");
+    expect(behaviourDocSource).toContain("Page chrome that must match the top bar portals into the collapse host");
   });
 });
diff --git a/tests/therapy-compass-responsive-contract.test.ts b/tests/therapy-compass-responsive-contract.test.ts
index bfca87e40..49595c477 100644
--- a/tests/therapy-compass-responsive-contract.test.ts
+++ b/tests/therapy-compass-responsive-contract.test.ts
@@ -6,8 +6,10 @@ const read = (relativePath: string) => readFileSync(new URL(`../${relativePath}`
 const therapyPath = "src/components/therapy-compass";
 
 const therapyCssSource = read(`${therapyPath}/therapy-compass.css`);
+const therapyNavSource = read(`${therapyPath}/nav.tsx`);
 const therapyCardSource = read(`${therapyPath}/therapy-card.tsx`);
 const homeSource = read(`${therapyPath}/screens/home-screen.tsx`);
+const modeHomeComposerSource = read("src/lib/mode-home-composer.ts");
 const modeHomeTemplateSource = read("src/components/mode-home-template.tsx");
 const detailSource = read(`${therapyPath}/screens/detail-screen.tsx`);
 const compareSource = read(`${therapyPath}/screens/compare-screen.tsx`);
@@ -52,6 +54,8 @@ describe("Therapy Compass responsive contract", () => {
     const workspaceRule = therapyCssSource.match(/\.tc-root \.tc-workspace-006\s*\{([^}]*)\}/)?.[1] ?? "";
     const navShellRule = therapyCssSource.match(/\.tc-root \.tc-nav-001\s*\{([^}]*)\}/)?.[1] ?? "";
     const navScrollerRule = therapyCssSource.match(/\.tc-root \.tc-nav-007\s*\{([^}]*)\}/)?.[1] ?? "";
+    const portaledNavRule =
+      therapyCssSource.match(/#therapy-header-collapse-addon-slot \.tc-nav-001\s*\{([^}]*)\}/)?.[1] ?? "";
 
     expect(rootRule).toContain("background: var(--background);");
     expect(workspaceRule).toContain("background: var(--background);");
@@ -63,6 +67,19 @@ describe("Therapy Compass responsive contract", () => {
     expect(navScrollerRule).toContain("max-width: 100%;");
     expect(navScrollerRule).toContain("margin-inline: auto;");
     expect(navScrollerRule).toContain("overflow-x: auto;");
+    // Portaled phone chrome must not keep sticky — the collapse row owns hide.
+    expect(portaledNavRule).toContain("position: relative;");
+    expect(portaledNavRule).toContain("top: auto;");
+  });
+
+  it("portals the section nav into the header collapse host on phones", () => {
+    expect(modeHomeComposerSource).toContain(
+      'export const therapyHeaderCollapseAddonSlotId = "therapy-header-collapse-addon-slot"',
+    );
+    expect(therapyNavSource).toContain("createPortal");
+    expect(therapyNavSource).toContain("therapyHeaderCollapseAddonSlotId");
+    expect(therapyNavSource).toContain('"(max-width: 639px)"');
+    expect(therapyNavSource).toContain('data-testid="therapy-compass-section-nav"');
   });
 
   it("defines one scoped phone reflow and a local comparison scroller", () => {
diff --git a/tests/ui-therapy-nav-scroll.spec.ts b/tests/ui-therapy-nav-scroll.spec.ts
new file mode 100644
index 000000000..5bfae41b9
--- /dev/null
+++ b/tests/ui-therapy-nav-scroll.spec.ts
@@ -0,0 +1,144 @@
+import { expect, test, type Page } from "playwright/test";
+import { resolve } from "node:path";
+
+import { scrollPrimarySurface } from "./playwright-scroll";
+
+/**
+ * Therapy section nav must hide/reveal with the universal top bar on phones.
+ * Sticky-in-content left the strip pinned after header collapse (the defect
+ * these checks guard). The nav portals into universal-header-collapse below
+ * the phone seam so one scroll signal owns both surfaces.
+ */
+
+const phoneViewport = { width: 390, height: 844 };
+
+async function blockExternalRequests(page: Page) {
+  await page.route("**/*", async (route) => {
+    const url = new URL(route.request().url());
+    if (
+      (url.protocol === "http:" || url.protocol === "https:") &&
+      !["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname)
+    ) {
+      await route.abort("blockedbyclient");
+      return;
+    }
+    await route.fallback();
+  });
+}
+
+async function installTherapyFixtures(page: Page) {
+  await page.route("**/therapy-compass-data/*.json", async (route) => {
+    const filename = new URL(route.request().url()).pathname.split("/").at(-1) ?? "";
+    if (!new Set(["therapies.json", "therapies-index.json", "pathways.json", "reference.json"]).has(filename)) {
+      await route.abort("blockedbyclient");
+      return;
+    }
+    await route.fulfill({
+      contentType: "application/json",
+      path: resolve(process.cwd(), "public", "therapy-compass-data", filename),
+    });
+  });
+}
+
+async function gotoTherapySearch(page: Page) {
+  await page.goto("/therapy-compass/search?q=CBT&run=1", { waitUntil: "domcontentloaded" });
+  await expect(page.locator("#main-content").first()).toBeVisible({ timeout: 15_000 });
+  await page.addStyleTag({
+    content: ":root{--safe-area-top:59px !important;--safe-area-bottom:34px !important;}",
+  });
+  await page.waitForTimeout(700);
+}
+
+async function waitForMainScrollHandler(page: Page) {
+  const main = page.locator("#main-content");
+  await expect
+    .poll(
+      async () =>
+        main.evaluate((element) => {
+          const propsKey = Object.keys(element).find((key) => key.startsWith("__reactProps$"));
+          if (!propsKey) return false;
+          const props = (element as unknown as Record<string, Record<string, unknown>>)[propsKey];
+          return typeof props?.onScroll === "function";
+        }),
+      { timeout: 15_000 },
+    )
+    .toBe(true);
+}
+
+test.beforeEach(async ({ page }) => {
+  await blockExternalRequests(page);
+  await installTherapyFixtures(page);
+});
+
+test("phone Therapy section nav hides and returns with the universal header", async ({ page }) => {
+  await page.emulateMedia({ reducedMotion: "no-preference" });
+  await page.setViewportSize(phoneViewport);
+  await gotoTherapySearch(page);
+
+  const collapseHost = page.getByTestId("universal-header-collapse");
+  const sectionNav = page.getByTestId("therapy-compass-section-nav");
+  const addonHost = page.getByTestId("header-collapse-addon");
+
+  await expect(collapseHost).toBeVisible();
+  await expect(sectionNav).toBeVisible();
+  await expect(addonHost).toBeVisible();
+
+  // Anchored: the portaled strip lives inside the collapse row, not sticky in content.
+  await expect
+    .poll(async () =>
+      sectionNav.evaluate((node) => Boolean(node.closest('[data-testid="universal-header-collapse"]'))),
+    )
+    .toBe(true);
+  await expect
+    .poll(async () =>
+      page.evaluate(() => {
+        const inContent = document.querySelector("#main-content [data-testid='therapy-compass-section-nav']");
+        return inContent === null;
+      }),
+    )
+    .toBe(true);
+
+  await waitForMainScrollHandler(page);
+  await page.locator("#main-content").evaluate((node) => {
+    const spacer = document.createElement("div");
+    spacer.setAttribute("data-testid", "therapy-nav-hide-scroll-spacer");
+    spacer.style.height = "2400px";
+    node.appendChild(spacer);
+  });
+
+  await expect(collapseHost).not.toHaveAttribute("data-scroll-hidden", "true");
+
+  for (const offset of [40, 80, 120, 160, 220, 300]) {
+    await scrollPrimarySurface(page, offset);
+  }
+
+  await expect(collapseHost).toHaveAttribute("data-scroll-hidden", "true", { timeout: 5_000 });
+  // Collapsed chrome is clipped by the 0fr track — height/bottom must leave the viewport.
+  await expect
+    .poll(async () =>
+      sectionNav.evaluate((node) => {
+        const rect = node.getBoundingClientRect();
+        return { height: rect.height, bottom: rect.bottom };
+      }),
+    )
+    .toEqual(expect.objectContaining({ height: expect.any(Number) }));
+  await expect
+    .poll(async () =>
+      sectionNav.evaluate((node) => {
+        const rect = node.getBoundingClientRect();
+        return rect.height <= 1 || rect.bottom <= 1;
+      }),
+    )
+    .toBe(true);
+
+  for (const offset of [220, 140, 60, 0]) {
+    await scrollPrimarySurface(page, offset);
+  }
+
+  await expect(collapseHost).not.toHaveAttribute("data-scroll-hidden", "true", { timeout: 5_000 });
+  await expect(sectionNav).toBeVisible();
+  const box = await sectionNav.boundingBox();
+  expect(box).not.toBeNull();
+  expect(box!.y).toBeGreaterThanOrEqual(0);
+  expect(box!.height).toBeGreaterThan(8);
+});

From 69338e7362114ee21e1941f571c109a7beef1710 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 03:51:44 +0800
Subject: [PATCH 03/16] test: avoid false positive on max-sm translate-y
 contract

---
 tests/header-scroll-hide-contract.test.ts | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/tests/header-scroll-hide-contract.test.ts b/tests/header-scroll-hide-contract.test.ts
index 02d189243..8cbc3d30c 100644
--- a/tests/header-scroll-hide-contract.test.ts
+++ b/tests/header-scroll-hide-contract.test.ts
@@ -87,9 +87,12 @@ describe("shared header hide/reveal wiring", () => {
     expect(shellSource).toContain('className={mobileChromeVisible ? "sm:contents" : "hidden lg:contents"}');
     expect(shellSource).not.toContain('mobileChromeVisible ? undefined : "hidden lg:block"');
     // Sticky pins the outer [top bar | search] stack; translating that whole
-    // stack would take the search field off-screen.
+    // stack would take the search field off-screen. Overlay hosts still use
+    // max-sm:-translate-y-full — strip that before asserting sticky collapse
+    // does not revive the sm: translate path.
     expect(headerSource).toContain('className="sm:sticky sm:top-0 sm:z-30"');
-    expect(headerSource).not.toContain("sm:-translate-y-full");
+    expect(headerSource.replaceAll("max-sm:-translate-y-full", "")).not.toContain("sm:-translate-y-full");
+    expect(headerSource).not.toContain('sticksAbovePhones && headerChromeHidden && "sm:-translate-y-full"');
   });
 
   it("keeps the header out of sticky positioning wherever its row collapses", () => {

From a594188a91100abe67f86fa324164b1aacb8a679 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 03:53:24 +0800
Subject: [PATCH 04/16] test(ui): prove tablet/desktop search stays while the
 top bar hides

The prior chrome-scroll suite only checked data-scroll-hidden on forms, so
wrapping the search composer inside the collapse row could still go green.
Assert header-band search geometry stays on screen, and register the Therapy
nav scroll spec in the production Playwright matcher.
---
 playwright.config.ts           |  4 +-
 tests/ui-chrome-scroll.spec.ts | 92 ++++++++++++++++++++++++----------
 2 files changed, 67 insertions(+), 29 deletions(-)

diff --git a/playwright.config.ts b/playwright.config.ts
index f2b65893c..00378f9d9 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -16,14 +16,14 @@ const chromiumExecutablePath = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH;
 // they share a spec file. Every required browser project uses the same
 // production matcher and tag exclusion.
 const productionSpecPattern =
-  /.*(?:answer-progress-ui-smoke|ui-(smoke|stress|accessibility|tools|overlap|universal-search|specifiers|formulation|chrome-scroll|phone-scroll|pwa|route-coverage|visual-artifacts|hydration))\.spec\.ts/;
+  /.*(?:answer-progress-ui-smoke|ui-(smoke|stress|accessibility|tools|overlap|universal-search|specifiers|formulation|chrome-scroll|therapy-nav-scroll|phone-scroll|pwa|route-coverage|visual-artifacts|hydration))\.spec\.ts/;
 const mockupSpecPattern = /.*ui-(tools|tools-collapse|tools-task-directory)\.spec\.ts/;
 const mockupTag = /@mockup/;
 
 export default defineConfig({
   testDir: "./tests",
   testMatch:
-    /.*(?:answer-progress-ui-smoke|ui-(smoke|stress|accessibility|tools|tools-collapse|tools-task-directory|overlap|universal-search|specifiers|formulation|chrome-scroll|phone-scroll|pwa|route-coverage|visual-artifacts|hydration))\.spec\.ts/,
+    /.*(?:answer-progress-ui-smoke|ui-(smoke|stress|accessibility|tools|tools-collapse|tools-task-directory|overlap|universal-search|specifiers|formulation|chrome-scroll|therapy-nav-scroll|phone-scroll|pwa|route-coverage|visual-artifacts|hydration))\.spec\.ts/,
   timeout: 60_000,
   retries: 0,
   // Fail the run if a stray `test.only` is committed: otherwise it silently
diff --git a/tests/ui-chrome-scroll.spec.ts b/tests/ui-chrome-scroll.spec.ts
index 1a517391f..9998a2598 100644
--- a/tests/ui-chrome-scroll.spec.ts
+++ b/tests/ui-chrome-scroll.spec.ts
@@ -1,22 +1,19 @@
 import { expect, test, type Page } from "playwright/test";
 
 /**
- * Tablet/desktop header hide-and-return.
+ * Tablet/desktop top-bar hide-and-return, with the search field staying put.
  *
- * The reported defect: above the phone breakpoint the header scrolled away with
- * the page and only came back once the reader reached the very top. Two
- * distinct causes, one per scroll-ownership model, so both are swept here:
+ * Two defects are guarded here:
  *
- *  - GlobalSearchShell hands scrolling back to the document above phones, so
- *    `#main-content`'s React onScroll never fired and nothing reported scroll
- *    at all. Its chrome now sticks to the viewport top and translates away.
- *  - ClinicalDashboard keeps `<main>` as the scrollport at every width, but its
- *    collapse row was gated to `max-sm`, so the header simply never hid.
+ *  1. Above the phone breakpoint the top bar used to scroll away with the page
+ *     and only return at the very top (no scroll reporter / sticky travel).
+ *  2. The first cross-breakpoint fix wrapped the search composer inside the
+ *     same collapse/translate row as the top bar, so tablet/desktop search
+ *     disappeared with mode / new chat — only the top bar should hide.
  *
- * The load-bearing assertion is the reveal *mid-page*: hidden must clear while
- * the reader is still hundreds of pixels down, with the bar back on screen.
- * Asserting only `data-scroll-hidden` would have passed against the old sticky
- * header, which flipped the attribute while sitting far off the viewport top.
+ * The load-bearing assertions are (a) the reveal *mid-page* and (b) the search
+ * input remaining on screen while the top bar is hidden. Asserting only
+ * `data-scroll-hidden` would miss both.
  *
  * The suite-wide `reducedMotion: "reduce"` is kept deliberately: the chrome
  * carries `motion-reduce:transition-none`, so geometry settles in one frame and
@@ -31,6 +28,9 @@ const breakpoints = [
 
 // One surface per scroll-ownership model above the phone breakpoint, chosen for
 // having real scroll runway at both sizes (short pages legitimately never hide).
+// Dashboard results keep an inline header search; shell mode homes may portal
+// the composer into the hero (still covered by the search-visible assertion
+// when an input is present).
 const surfaces = [
   { name: "shell mode home", route: "/tools" },
   { name: "shell detail page", route: "/formulation/worry" },
@@ -59,6 +59,9 @@ interface ChromeState {
   hidden: boolean;
   headerTop: number;
   headerBottom: number;
+  searchTop: number;
+  searchBottom: number;
+  searchVisible: boolean;
   hiddenBottomComposers: number;
 }
 
@@ -71,11 +74,24 @@ function readChromeState(page: Page): Promise<ChromeState> {
     const main = document.getElementById("main-content");
     const mainScrolls = Boolean(main && main.scrollHeight > main.clientHeight + 1);
     const doc = document.documentElement;
-    // Collapse hosts flip data-scroll-hidden on the grid wrapper; the answer
-    // view's overlay glass bar flips it on header#search itself.
+    // Collapse hosts flip data-scroll-hidden on the top-bar grid wrapper; the
+    // answer view's overlay glass bar flips it on header#search itself.
     const header = document.querySelector("header#search");
     const hideTarget = document.querySelector('[data-testid="universal-header-collapse"]') ?? header;
     const rect = header?.getBoundingClientRect();
+    // Prefer the global search input; fall back to any visible search textbox
+    // so hero-portaled composers still count.
+    const search =
+      document.querySelector<HTMLElement>('[data-testid="global-search-input"]') ??
+      document.querySelector<HTMLElement>('input[type="search"], input[role="combobox"]');
+    const searchRect = search?.getBoundingClientRect();
+    const searchOnScreen = Boolean(
+      searchRect &&
+        searchRect.width > 0 &&
+        searchRect.height > 0 &&
+        searchRect.bottom > 0 &&
+        searchRect.top < window.innerHeight,
+    );
     return {
       offset: Math.round(mainScrolls && main ? main.scrollTop : window.scrollY),
       maxOffset: Math.round(
@@ -84,6 +100,9 @@ function readChromeState(page: Page): Promise<ChromeState> {
       hidden: hideTarget?.getAttribute("data-scroll-hidden") === "true",
       headerTop: rect ? Math.round(rect.top) : Number.NaN,
       headerBottom: rect ? Math.round(rect.bottom) : Number.NaN,
+      searchTop: searchRect ? Math.round(searchRect.top) : Number.NaN,
+      searchBottom: searchRect ? Math.round(searchRect.bottom) : Number.NaN,
+      searchVisible: searchOnScreen,
       hiddenBottomComposers: document.querySelectorAll('form[data-scroll-hidden="true"]').length,
     };
   });
@@ -134,7 +153,7 @@ test.beforeEach(async ({ page }) => {
 
 for (const { name: sizeName, viewport } of breakpoints) {
   for (const { name: surfaceName, route } of surfaces) {
-    test(`${sizeName}: header hides on scroll down and returns mid-page on ${surfaceName}`, async ({ page }) => {
+    test(`${sizeName}: top bar hides on scroll down and returns mid-page on ${surfaceName}`, async ({ page }) => {
       await page.setViewportSize(viewport);
       await page.goto(route, { waitUntil: "domcontentloaded" });
       await expect(page.locator("header#search").first()).toBeVisible({ timeout: 15_000 });
@@ -142,16 +161,26 @@ for (const { name: sizeName, viewport } of breakpoints) {
       await page.waitForTimeout(400);
 
       const atTop = await readChromeState(page);
-      expect(atTop.hidden, "header visible at the top").toBe(false);
-      expect(atTop.headerTop, "header starts at the viewport top").toBeLessThanOrEqual(8);
+      expect(atTop.hidden, "top bar visible at the top").toBe(false);
+      expect(atTop.headerTop, "top bar starts at the viewport top").toBeLessThanOrEqual(8);
+      // Hero composers sit mid-page and scroll with content; only a search that
+      // starts in the chrome band must remain after the top bar collapses.
+      const searchStartedInChrome = atTop.searchVisible && atTop.searchTop <= 120;
 
       await scrollBy(page, atTop.maxOffset + 320, 160);
       await page.waitForTimeout(300);
 
       const scrolledDown = await readChromeState(page);
       expect(scrolledDown.offset, "descent moved the scroller").toBeGreaterThan(requiredRunway - 200);
-      expect(scrolledDown.hidden, "header hides on a deliberate scroll down").toBe(true);
-      expect(scrolledDown.headerBottom, "hidden header is off the top of the viewport").toBeLessThanOrEqual(0);
+      expect(scrolledDown.hidden, "top bar hides on a deliberate scroll down").toBe(true);
+      expect(scrolledDown.headerBottom, "hidden top bar is off the top of the viewport").toBeLessThanOrEqual(0);
+      if (searchStartedInChrome) {
+        expect(scrolledDown.searchVisible, "header search stays on screen while the top bar is hidden").toBe(true);
+        expect(
+          scrolledDown.searchTop,
+          "header search sits near the viewport top after the top bar collapses",
+        ).toBeLessThanOrEqual(24);
+      }
 
       // Three deliberate upward steps — nowhere near the top of the page.
       await scrollBy(page, -360, 120);
@@ -159,14 +188,17 @@ for (const { name: sizeName, viewport } of breakpoints) {
 
       const scrolledUp = await readChromeState(page);
       expect(scrolledUp.offset, "the reveal happens well short of the top").toBeGreaterThan(200);
-      expect(scrolledUp.hidden, "header returns on a deliberate scroll up").toBe(false);
-      expect(scrolledUp.headerBottom, "returned header is actually on screen").toBeGreaterThan(0);
-      expect(scrolledUp.headerTop, "returned header sits at the viewport top").toBeLessThanOrEqual(8);
+      expect(scrolledUp.hidden, "top bar returns on a deliberate scroll up").toBe(false);
+      expect(scrolledUp.headerBottom, "returned top bar is actually on screen").toBeGreaterThan(0);
+      expect(scrolledUp.headerTop, "returned top bar sits at the viewport top").toBeLessThanOrEqual(8);
+      if (searchStartedInChrome) {
+        expect(scrolledUp.searchVisible, "header search remains on screen after the top bar returns").toBe(true);
+      }
     });
 
-    test(`${sizeName}: bottom search composer never scroll-hides on ${surfaceName}`, async ({ page }) => {
+    test(`${sizeName}: search composer never scroll-hides on ${surfaceName}`, async ({ page }) => {
       // The phone dock hide is phone-only by contract; above that breakpoint the
-      // composer lives in the hero or the header and has nothing to reclaim.
+      // composer lives in the hero or beside the top bar and must stay usable.
       await page.setViewportSize(viewport);
       await page.goto(route, { waitUntil: "domcontentloaded" });
       await expect(page.locator("header#search").first()).toBeVisible({ timeout: 15_000 });
@@ -174,12 +206,18 @@ for (const { name: sizeName, viewport } of breakpoints) {
       await page.waitForTimeout(400);
 
       const atTop = await readChromeState(page);
+      const searchStartedInChrome = atTop.searchVisible && atTop.searchTop <= 120;
       await scrollBy(page, atTop.maxOffset + 320, 160);
       await page.waitForTimeout(300);
 
       const scrolledDown = await readChromeState(page);
-      expect(scrolledDown.hidden, "the header still hides").toBe(true);
-      expect(scrolledDown.hiddenBottomComposers, "no composer hides above the phone breakpoint").toBe(0);
+      expect(scrolledDown.hidden, "the top bar still hides").toBe(true);
+      expect(scrolledDown.hiddenBottomComposers, "no composer flips data-scroll-hidden above the phone breakpoint").toBe(
+        0,
+      );
+      if (searchStartedInChrome) {
+        expect(scrolledDown.searchVisible, "header search geometry stays on screen").toBe(true);
+      }
     });
   }
 }

From f1f6b43933206c6f2be5d39d3c15ed8084f83cde Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:03:59 +0800
Subject: [PATCH 05/16] style: prettier format chrome hide and Therapy nav
 files

---
 docs/search-chrome-behaviour.md               |  10 +-
 .../master-search-header.tsx                  | 437 +++++++++---------
 tests/ui-chrome-scroll.spec.ts                |  15 +-
 tests/ui-therapy-nav-scroll.spec.ts           |   4 +-
 4 files changed, 230 insertions(+), 236 deletions(-)

diff --git a/docs/search-chrome-behaviour.md b/docs/search-chrome-behaviour.md
index b45eb3171..802733ad3 100644
--- a/docs/search-chrome-behaviour.md
+++ b/docs/search-chrome-behaviour.md
@@ -31,11 +31,11 @@ The universal **top bar** (mode, new chat, menu) hides on a deliberate scroll do
 
 Choose the hide mechanism from where the host's scrollport lives, because that decides what hiding costs the reader:
 
-| Host                              | Scrollport                                    | `hideOnScroll`                           | Mechanism                                                                                          |
-| --------------------------------- | --------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `ClinicalDashboard` (answer view) | `<main>` at every width                       | `strategy: "overlay", allBreakpoints`    | Absolute glass top bar translates off; `<main>` keeps its top reserve; search stays                |
-| `ClinicalDashboard` (other modes) | `<main>` at every width                       | `strategy: "collapse", wide: "collapse"` | Top-bar 1fr -> 0fr grid row; released strip goes to content; search stays as a sibling             |
-| `GlobalSearchShell`               | `#main-content` on phones, the document above | `strategy: "collapse", wide: "sticky"`   | Sticky stack of [top bar \| search]; only the top-bar row collapses so search rises to the top     |
+| Host                              | Scrollport                                    | `hideOnScroll`                           | Mechanism                                                                                      |
+| --------------------------------- | --------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `ClinicalDashboard` (answer view) | `<main>` at every width                       | `strategy: "overlay", allBreakpoints`    | Absolute glass top bar translates off; `<main>` keeps its top reserve; search stays            |
+| `ClinicalDashboard` (other modes) | `<main>` at every width                       | `strategy: "collapse", wide: "collapse"` | Top-bar 1fr -> 0fr grid row; released strip goes to content; search stays as a sibling         |
+| `GlobalSearchShell`               | `#main-content` on phones, the document above | `strategy: "collapse", wide: "sticky"`   | Sticky stack of [top bar \| search]; only the top-bar row collapses so search rises to the top |
 
 Rules that keep this working:
 
diff --git a/src/components/clinical-dashboard/master-search-header.tsx b/src/components/clinical-dashboard/master-search-header.tsx
index dda3d0213..a32f545d7 100644
--- a/src/components/clinical-dashboard/master-search-header.tsx
+++ b/src/components/clinical-dashboard/master-search-header.tsx
@@ -1745,245 +1745,244 @@ export function MasterSearchHeader({
   // bar without taking the search field with it. Phone bottom docks are fixed and
   // escape any collapse wrapper; hero composers portal out of this tree.
   const topBar = (
-      <header
-        id="search"
-        data-scroll-hidden={hideStrategy === "overlay" && headerChromeHidden ? "true" : undefined}
+    <header
+      id="search"
+      data-scroll-hidden={hideStrategy === "overlay" && headerChromeHidden ? "true" : undefined}
+      className={cn(
+        // No backdrop-filter on the header itself: it would form a backdrop
+        // root and starve the .edge-glass-header-backdrop scrim (the single
+        // source of the bar's frost) of the real page behind it.
+        "edge-glass-header universal-header z-30 py-2 pt-[max(0.5rem,env(safe-area-inset-top))] text-[color:var(--text)]",
+        // Collapse hosts keep the top bar above an internally scrolling <main>,
+        // so sticky is unnecessary wherever the row collapses and fights the
+        // 0fr grid by pinning the bar inside the viewport. Sticky hosts pin an
+        // outer stack (top bar + search) instead; this <header> stays relative
+        // inside that stack. All-breakpoints overlay hosts take the bar out of
+        // flow entirely (absolute over the padded <main>). Legacy overlay hosts
+        // keep sticky (they ride document scroll) and translate away with no
+        // layout shift.
+        hideStrategy === "collapse"
+          ? sticksAbovePhones || collapsesAtEveryWidth
+            ? "relative"
+            : "max-sm:relative sm:sticky sm:top-0"
+          : overlayAllBreakpoints
+            ? "absolute inset-x-0 top-0"
+            : "sticky top-0",
+        // Overlay hide-on-scroll: a plain translate reveals the content already
+        // flowing beneath it. No transform is applied while visible so the
+        // fixed-position mobile mode menu keeps the viewport as its containing block.
+        hideStrategy === "overlay" &&
+          (overlayAllBreakpoints
+            ? cn(
+                "transition-transform motion-reduce:transition-none",
+                headerChromeHidden
+                  ? "duration-[240ms] ease-[cubic-bezier(0.4,0,0.2,1)]"
+                  : "duration-200 ease-[cubic-bezier(0.22,1,0.36,1)]",
+              )
+            : cn(
+                "max-sm:transition-transform motion-reduce:transition-none",
+                headerChromeHidden
+                  ? "max-sm:duration-[240ms] max-sm:ease-[cubic-bezier(0.4,0,0.2,1)]"
+                  : "max-sm:duration-200 max-sm:ease-[cubic-bezier(0.22,1,0.36,1)]",
+              )),
+        hideStrategy === "overlay" &&
+          headerChromeHidden &&
+          (overlayAllBreakpoints ? "-translate-y-full" : "max-sm:-translate-y-full"),
+      )}
+      {...(hideStrategy === "overlay" ? chromeFocusProps : undefined)}
+    >
+      <div className="edge-glass-header-backdrop" aria-hidden="true" />
+      <div
         className={cn(
-          // No backdrop-filter on the header itself: it would form a backdrop
-          // root and starve the .edge-glass-header-backdrop scrim (the single
-          // source of the bar's frost) of the real page behind it.
-          "edge-glass-header universal-header z-30 py-2 pt-[max(0.5rem,env(safe-area-inset-top))] text-[color:var(--text)]",
-          // Collapse hosts keep the top bar above an internally scrolling <main>,
-          // so sticky is unnecessary wherever the row collapses and fights the
-          // 0fr grid by pinning the bar inside the viewport. Sticky hosts pin an
-          // outer stack (top bar + search) instead; this <header> stays relative
-          // inside that stack. All-breakpoints overlay hosts take the bar out of
-          // flow entirely (absolute over the padded <main>). Legacy overlay hosts
-          // keep sticky (they ride document scroll) and translate away with no
-          // layout shift.
-          hideStrategy === "collapse"
-            ? sticksAbovePhones || collapsesAtEveryWidth
-              ? "relative"
-              : "max-sm:relative sm:sticky sm:top-0"
-            : overlayAllBreakpoints
-              ? "absolute inset-x-0 top-0"
-              : "sticky top-0",
-          // Overlay hide-on-scroll: a plain translate reveals the content already
-          // flowing beneath it. No transform is applied while visible so the
-          // fixed-position mobile mode menu keeps the viewport as its containing block.
-          hideStrategy === "overlay" &&
-            (overlayAllBreakpoints
-              ? cn(
-                  "transition-transform motion-reduce:transition-none",
-                  headerChromeHidden
-                    ? "duration-[240ms] ease-[cubic-bezier(0.4,0,0.2,1)]"
-                    : "duration-200 ease-[cubic-bezier(0.22,1,0.36,1)]",
-                )
-              : cn(
-                  "max-sm:transition-transform motion-reduce:transition-none",
-                  headerChromeHidden
-                    ? "max-sm:duration-[240ms] max-sm:ease-[cubic-bezier(0.4,0,0.2,1)]"
-                    : "max-sm:duration-200 max-sm:ease-[cubic-bezier(0.22,1,0.36,1)]",
-                )),
-          hideStrategy === "overlay" &&
-            headerChromeHidden &&
-            (overlayAllBreakpoints ? "-translate-y-full" : "max-sm:-translate-y-full"),
+          "relative mx-auto grid min-h-14 grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-2 sm:gap-3",
+          isWorkflowHeader
+            ? "max-w-none px-3 sm:px-5 lg:grid-cols-[auto_auto_minmax(0,1fr)] lg:gap-4 lg:px-6"
+            : "max-w-7xl lg:grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)]",
         )}
-        {...(hideStrategy === "overlay" ? chromeFocusProps : undefined)}
       >
-        <div className="edge-glass-header-backdrop" aria-hidden="true" />
+        <div className="flex min-w-0 items-center gap-2 sm:gap-3">
+          <button
+            type="button"
+            onClick={useMobileBackControl ? onMobileBack : onOpenMobileSidebar}
+            className={cn(
+              "universal-header-icon-control h-tap w-tap shrink-0 place-items-center rounded-full text-[color:var(--text-muted)] transition hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--text)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]",
+              // From md the desktop icon rail owns navigation, so the drawer
+              // trigger is phone-only outside workflow headers.
+              isWorkflowHeader || useMobileBackControl ? "grid" : "grid md:hidden",
+            )}
+            aria-label={useMobileBackControl ? "Go back" : "Open Clinical Guide menu"}
+          >
+            {useMobileBackControl ? (
+              <ArrowLeft aria-hidden="true" className="h-5 w-5" />
+            ) : (
+              <Menu aria-hidden="true" className="h-5 w-5" />
+            )}
+          </button>
+          {isServicesMode ? (
+            <div className="hidden min-w-0 items-center gap-3 lg:flex">
+              <span className="grid h-10 w-10 place-items-center rounded-xl bg-[color:var(--clinical-accent)] text-[color:var(--clinical-accent-contrast)] shadow-[var(--shadow-tight)]">
+                <ShieldCheck className="h-5 w-5" aria-hidden />
+              </span>
+              <span className="min-w-0">
+                <span className="block truncate text-lg font-extrabold leading-5 text-[color:var(--text-heading)]">
+                  Services Navigator
+                </span>
+                <span className="block truncate text-xs font-semibold text-[color:var(--text-muted)]">
+                  Psychiatry referral directory
+                </span>
+              </span>
+            </div>
+          ) : null}
+        </div>
+
         <div
-          className={cn(
-            "relative mx-auto grid min-h-14 grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-2 sm:gap-3",
-            isWorkflowHeader
-              ? "max-w-none px-3 sm:px-5 lg:grid-cols-[auto_auto_minmax(0,1fr)] lg:gap-4 lg:px-6"
-              : "max-w-7xl lg:grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)]",
-          )}
+          ref={modeMenuRef}
+          onBlur={(event) => {
+            // Phone Mode menu is portaled into Sheet; blur-leave on this wrapper
+            // would close the sheet as soon as focus moved into the dialog.
+            if (usesPhoneSearchLayout) return;
+            const nextFocusedElement = event.relatedTarget;
+            if (nextFocusedElement instanceof Node && event.currentTarget.contains(nextFocusedElement)) return;
+            setModeMenuOpen(false);
+          }}
+          className={cn("relative z-[60] min-w-0", isWorkflowHeader ? "justify-self-start" : "justify-self-center")}
         >
-          <div className="flex min-w-0 items-center gap-2 sm:gap-3">
-            <button
-              type="button"
-              onClick={useMobileBackControl ? onMobileBack : onOpenMobileSidebar}
+          <button
+            ref={modeButtonRef}
+            type="button"
+            onClick={toggleModeMenu}
+            onKeyDown={handleModeTriggerKeyDown}
+            className={cn(
+              // Size utilities live in the per-variant branch, never the shared
+              // base: cn() is plain concat (no tailwind-merge), so keeping the
+              // default h-/w-/min-w- here too made the workflow overrides dead —
+              // Tailwind v4 emits same-property utilities in canonical order and
+              // the base won at every breakpoint but lg:.
+              "universal-header-mode-button inline-grid min-w-0 grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-2 rounded-full border border-[color:var(--border)] bg-[color:var(--surface)] px-2.5 text-left transition hover:border-[color:var(--border-strong)] hover:bg-[color:var(--surface-subtle)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]",
+              isWorkflowHeader
+                ? "h-tap w-[min(11rem,calc(100vw-11rem))] sm:w-[12rem] sm:min-w-0 lg:w-[12.5rem]"
+                : "h-12 w-[min(13rem,calc(100vw-11.5rem))] sm:w-auto sm:min-w-[13rem] sm:pr-3",
+            )}
+            aria-haspopup={usesPhoneSearchLayout ? "dialog" : "menu"}
+            aria-expanded={modeMenuOpen}
+            aria-controls={modeMenuOpen ? "app-mode-menu" : undefined}
+            aria-label={`Mode ${selectedAppMode.label}`}
+          >
+            <span className="grid h-8 w-8 place-items-center rounded-full bg-[color:var(--clinical-accent)] text-[color:var(--clinical-accent-contrast)] shadow-[var(--shadow-tight)]">
+              <SelectedAppModeIcon aria-hidden="true" className="h-3.5 w-3.5" />
+            </span>
+            <span className="min-w-0">
+              <span className="hidden truncate text-2xs font-extrabold uppercase leading-3 tracking-[0.08em] text-[color:var(--text-muted)] sm:block">
+                Mode
+              </span>
+              <span className="block truncate text-sm font-extrabold leading-5 text-[color:var(--text-heading)]">
+                {selectedAppMode.label}
+              </span>
+            </span>
+            <ChevronDown
+              aria-hidden="true"
               className={cn(
-                "universal-header-icon-control h-tap w-tap shrink-0 place-items-center rounded-full text-[color:var(--text-muted)] transition hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--text)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]",
-                // From md the desktop icon rail owns navigation, so the drawer
-                // trigger is phone-only outside workflow headers.
-                isWorkflowHeader || useMobileBackControl ? "grid" : "grid md:hidden",
-              )}
-              aria-label={useMobileBackControl ? "Go back" : "Open Clinical Guide menu"}
-            >
-              {useMobileBackControl ? (
-                <ArrowLeft aria-hidden="true" className="h-5 w-5" />
-              ) : (
-                <Menu aria-hidden="true" className="h-5 w-5" />
+                "h-4 w-4 text-[color:var(--text-soft)] transition-transform motion-reduce:transition-none",
+                modeMenuOpen && "rotate-180",
               )}
-            </button>
-            {isServicesMode ? (
-              <div className="hidden min-w-0 items-center gap-3 lg:flex">
-                <span className="grid h-10 w-10 place-items-center rounded-xl bg-[color:var(--clinical-accent)] text-[color:var(--clinical-accent-contrast)] shadow-[var(--shadow-tight)]">
-                  <ShieldCheck className="h-5 w-5" aria-hidden />
-                </span>
-                <span className="min-w-0">
-                  <span className="block truncate text-lg font-extrabold leading-5 text-[color:var(--text-heading)]">
-                    Services Navigator
-                  </span>
-                  <span className="block truncate text-xs font-semibold text-[color:var(--text-muted)]">
-                    Psychiatry referral directory
-                  </span>
-                </span>
-              </div>
-            ) : null}
-          </div>
+            />
+          </button>
 
-          <div
-            ref={modeMenuRef}
-            onBlur={(event) => {
-              // Phone Mode menu is portaled into Sheet; blur-leave on this wrapper
-              // would close the sheet as soon as focus moved into the dialog.
-              if (usesPhoneSearchLayout) return;
-              const nextFocusedElement = event.relatedTarget;
-              if (nextFocusedElement instanceof Node && event.currentTarget.contains(nextFocusedElement)) return;
-              setModeMenuOpen(false);
-            }}
-            className={cn("relative z-[60] min-w-0", isWorkflowHeader ? "justify-self-start" : "justify-self-center")}
-          >
-            <button
-              ref={modeButtonRef}
-              type="button"
-              onClick={toggleModeMenu}
-              onKeyDown={handleModeTriggerKeyDown}
+          {!usesPhoneSearchLayout && modeMenuOpen ? (
+            <div
+              id="app-mode-menu"
+              role="menu"
+              aria-label="Choose app mode"
               className={cn(
-                // Size utilities live in the per-variant branch, never the shared
-                // base: cn() is plain concat (no tailwind-merge), so keeping the
-                // default h-/w-/min-w- here too made the workflow overrides dead —
-                // Tailwind v4 emits same-property utilities in canonical order and
-                // the base won at every breakpoint but lg:.
-                "universal-header-mode-button inline-grid min-w-0 grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-2 rounded-full border border-[color:var(--border)] bg-[color:var(--surface)] px-2.5 text-left transition hover:border-[color:var(--border-strong)] hover:bg-[color:var(--surface-subtle)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]",
-                isWorkflowHeader
-                  ? "h-tap w-[min(11rem,calc(100vw-11rem))] sm:w-[12rem] sm:min-w-0 lg:w-[12.5rem]"
-                  : "h-12 w-[min(13rem,calc(100vw-11.5rem))] sm:w-auto sm:min-w-[13rem] sm:pr-3",
+                glassOverlaySurface,
+                "polished-scroll absolute left-0 top-[calc(100%+0.5rem)] z-50 max-h-[min(20rem,calc(100dvh-5.5rem))] w-[min(21rem,calc(100vw-2rem))] overflow-y-auto rounded-lg bg-[color:var(--surface-lux)] p-1.5 text-[color:var(--text)] shadow-[var(--shadow-lux)]",
               )}
-              aria-haspopup={usesPhoneSearchLayout ? "dialog" : "menu"}
-              aria-expanded={modeMenuOpen}
-              aria-controls={modeMenuOpen ? "app-mode-menu" : undefined}
-              aria-label={`Mode ${selectedAppMode.label}`}
             >
-              <span className="grid h-8 w-8 place-items-center rounded-full bg-[color:var(--clinical-accent)] text-[color:var(--clinical-accent-contrast)] shadow-[var(--shadow-tight)]">
-                <SelectedAppModeIcon aria-hidden="true" className="h-3.5 w-3.5" />
-              </span>
-              <span className="min-w-0">
-                <span className="hidden truncate text-2xs font-extrabold uppercase leading-3 tracking-[0.08em] text-[color:var(--text-muted)] sm:block">
-                  Mode
-                </span>
-                <span className="block truncate text-sm font-extrabold leading-5 text-[color:var(--text-heading)]">
-                  {selectedAppMode.label}
-                </span>
-              </span>
-              <ChevronDown
-                aria-hidden="true"
-                className={cn(
-                  "h-4 w-4 text-[color:var(--text-soft)] transition-transform motion-reduce:transition-none",
-                  modeMenuOpen && "rotate-180",
-                )}
-              />
-            </button>
+              {renderModeMenuOptions()}
+            </div>
+          ) : null}
+        </div>
 
-            {!usesPhoneSearchLayout && modeMenuOpen ? (
-              <div
-                id="app-mode-menu"
-                role="menu"
-                aria-label="Choose app mode"
-                className={cn(
-                  glassOverlaySurface,
-                  "polished-scroll absolute left-0 top-[calc(100%+0.5rem)] z-50 max-h-[min(20rem,calc(100dvh-5.5rem))] w-[min(21rem,calc(100vw-2rem))] overflow-y-auto rounded-lg bg-[color:var(--surface-lux)] p-1.5 text-[color:var(--text)] shadow-[var(--shadow-lux)]",
-                )}
+        <div className="relative flex min-w-0 shrink-0 items-center justify-end gap-1.5 justify-self-end sm:gap-2">
+          {isWorkflowHeader ? (
+            <>
+              <button
+                type="button"
+                aria-disabled="true"
+                aria-describedby="workflow-language-region-unavailable"
+                className="universal-header-icon-control grid h-tap w-tap shrink-0 cursor-not-allowed place-items-center rounded-full text-[color:var(--text-muted)] opacity-60 transition hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--clinical-accent)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]"
+                aria-label="Language and region settings (coming soon)"
+                title="Language and region — coming soon"
               >
-                {renderModeMenuOptions()}
-              </div>
-            ) : null}
-          </div>
-
-          <div className="relative flex min-w-0 shrink-0 items-center justify-end gap-1.5 justify-self-end sm:gap-2">
-            {isWorkflowHeader ? (
-              <>
-                <button
-                  type="button"
-                  aria-disabled="true"
-                  aria-describedby="workflow-language-region-unavailable"
-                  className="universal-header-icon-control grid h-tap w-tap shrink-0 cursor-not-allowed place-items-center rounded-full text-[color:var(--text-muted)] opacity-60 transition hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--clinical-accent)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]"
-                  aria-label="Language and region settings (coming soon)"
-                  title="Language and region — coming soon"
-                >
-                  <Globe2 className="h-5 w-5" aria-hidden />
-                </button>
-                <span id="workflow-language-region-unavailable" className="sr-only">
-                  Language and region settings are coming soon.
-                </span>
-                <span className="hidden h-8 w-px bg-[color:var(--border)] sm:block" aria-hidden />
-                <button
-                  type="button"
-                  onClick={onNewChat}
-                  className="universal-header-icon-control grid h-tap w-tap shrink-0 place-items-center rounded-full text-[color:var(--text-muted)] transition hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--clinical-accent)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]"
-                  aria-label="Start a new comparison"
-                  title="New comparison"
-                >
-                  <Plus className="h-5 w-5" aria-hidden />
-                </button>
-              </>
-            ) : null}
-            {!isWorkflowHeader ? (
+                <Globe2 className="h-5 w-5" aria-hidden />
+              </button>
+              <span id="workflow-language-region-unavailable" className="sr-only">
+                Language and region settings are coming soon.
+              </span>
+              <span className="hidden h-8 w-px bg-[color:var(--border)] sm:block" aria-hidden />
               <button
                 type="button"
                 onClick={onNewChat}
-                className="universal-header-icon-control inline-flex h-tap w-tap shrink-0 items-center justify-center gap-2 rounded-full border border-[color:var(--border)] bg-[color:var(--surface)] text-[color:var(--text-muted)] transition hover:border-[color:var(--clinical-accent-border)] hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--clinical-accent)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)] xl:w-auto xl:px-3 xl:text-xs xl:font-semibold xl:text-[color:var(--text)]"
-                aria-label="Start a new chat"
-                title="New chat"
+                className="universal-header-icon-control grid h-tap w-tap shrink-0 place-items-center rounded-full text-[color:var(--text-muted)] transition hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--clinical-accent)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]"
+                aria-label="Start a new comparison"
+                title="New comparison"
               >
-                <MessageSquarePlus aria-hidden="true" className="h-5 w-5 xl:h-4 xl:w-4" />
-                <span className="hidden whitespace-nowrap xl:inline">New chat</span>
+                <Plus className="h-5 w-5" aria-hidden />
               </button>
-            ) : null}
-          </div>
+            </>
+          ) : null}
+          {!isWorkflowHeader ? (
+            <button
+              type="button"
+              onClick={onNewChat}
+              className="universal-header-icon-control inline-flex h-tap w-tap shrink-0 items-center justify-center gap-2 rounded-full border border-[color:var(--border)] bg-[color:var(--surface)] text-[color:var(--text-muted)] transition hover:border-[color:var(--clinical-accent-border)] hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--clinical-accent)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)] xl:w-auto xl:px-3 xl:text-xs xl:font-semibold xl:text-[color:var(--text)]"
+              aria-label="Start a new chat"
+              title="New chat"
+            >
+              <MessageSquarePlus aria-hidden="true" className="h-5 w-5 xl:h-4 xl:w-4" />
+              <span className="hidden whitespace-nowrap xl:inline">New chat</span>
+            </button>
+          ) : null}
         </div>
+      </div>
 
-        {/* Portaled outside the 3-column header grid so a non-portal regression
+      {/* Portaled outside the 3-column header grid so a non-portal regression
             cannot steal a grid track and shove trailing actions onto a new row. */}
-        {usesPhoneSearchLayout ? (
-          <Sheet
-            open={modeMenuOpen}
-            onClose={dismissModeMenu}
-            title="Choose mode"
-            description="Switch the clinical workspace mode."
-            closeLabel="Close mode menu"
-            returnFocusRef={modeButtonRef}
-            portal
-            mobilePlacement="bottom"
-            mobileSize="content"
-            testId="app-mode-menu-sheet"
-            contentClassName="max-h-[min(88dvh,36rem)] sm:max-w-md"
-            bodyClassName="p-2"
-            headerClassName="bg-[color:var(--surface-lux)] px-4 py-3"
-          >
-            <div id="app-mode-menu" role="menu" aria-label="Choose app mode" className="grid gap-0.5">
-              {renderModeMenuOptions()}
-            </div>
-          </Sheet>
-        ) : null}
-      </header>
+      {usesPhoneSearchLayout ? (
+        <Sheet
+          open={modeMenuOpen}
+          onClose={dismissModeMenu}
+          title="Choose mode"
+          description="Switch the clinical workspace mode."
+          closeLabel="Close mode menu"
+          returnFocusRef={modeButtonRef}
+          portal
+          mobilePlacement="bottom"
+          mobileSize="content"
+          testId="app-mode-menu-sheet"
+          contentClassName="max-h-[min(88dvh,36rem)] sm:max-w-md"
+          bodyClassName="p-2"
+          headerClassName="bg-[color:var(--surface-lux)] px-4 py-3"
+        >
+          <div id="app-mode-menu" role="menu" aria-label="Choose app mode" className="grid gap-0.5">
+            {renderModeMenuOptions()}
+          </div>
+        </Sheet>
+      ) : null}
+    </header>
   );
 
-  const searchComposer =
-    searchComposerVisible ? (
-      <>
-        {(desktopHomeComposerActive && desktopHomeComposerHost) ||
-        (desktopHomeComposerSlotId && !desktopHomeComposerFallback)
-          ? null
-          : renderSearchComposer("default")}
-        {desktopHomeComposerActive && desktopHomeComposerHost
-          ? createPortal(renderSearchComposer("desktop-home"), desktopHomeComposerHost)
-          : null}
-      </>
-    ) : null;
+  const searchComposer = searchComposerVisible ? (
+    <>
+      {(desktopHomeComposerActive && desktopHomeComposerHost) ||
+      (desktopHomeComposerSlotId && !desktopHomeComposerFallback)
+        ? null
+        : renderSearchComposer("default")}
+      {desktopHomeComposerActive && desktopHomeComposerHost
+        ? createPortal(renderSearchComposer("desktop-home"), desktopHomeComposerHost)
+        : null}
+    </>
+  ) : null;
 
   if (hideStrategy === "collapse") {
     // Collapse hide-on-scroll applies to the TOP BAR only (mode / new chat). The
@@ -2034,11 +2033,7 @@ export function MasterSearchHeader({
         >
           {topBar}
           {headerCollapseAddonSlotId ? (
-            <div
-              id={headerCollapseAddonSlotId}
-              data-testid="header-collapse-addon"
-              className="w-full empty:hidden"
-            />
+            <div id={headerCollapseAddonSlotId} data-testid="header-collapse-addon" className="w-full empty:hidden" />
           ) : null}
         </div>
       </div>
diff --git a/tests/ui-chrome-scroll.spec.ts b/tests/ui-chrome-scroll.spec.ts
index 9998a2598..67813115b 100644
--- a/tests/ui-chrome-scroll.spec.ts
+++ b/tests/ui-chrome-scroll.spec.ts
@@ -87,10 +87,10 @@ function readChromeState(page: Page): Promise<ChromeState> {
     const searchRect = search?.getBoundingClientRect();
     const searchOnScreen = Boolean(
       searchRect &&
-        searchRect.width > 0 &&
-        searchRect.height > 0 &&
-        searchRect.bottom > 0 &&
-        searchRect.top < window.innerHeight,
+      searchRect.width > 0 &&
+      searchRect.height > 0 &&
+      searchRect.bottom > 0 &&
+      searchRect.top < window.innerHeight,
     );
     return {
       offset: Math.round(mainScrolls && main ? main.scrollTop : window.scrollY),
@@ -212,9 +212,10 @@ for (const { name: sizeName, viewport } of breakpoints) {
 
       const scrolledDown = await readChromeState(page);
       expect(scrolledDown.hidden, "the top bar still hides").toBe(true);
-      expect(scrolledDown.hiddenBottomComposers, "no composer flips data-scroll-hidden above the phone breakpoint").toBe(
-        0,
-      );
+      expect(
+        scrolledDown.hiddenBottomComposers,
+        "no composer flips data-scroll-hidden above the phone breakpoint",
+      ).toBe(0);
       if (searchStartedInChrome) {
         expect(scrolledDown.searchVisible, "header search geometry stays on screen").toBe(true);
       }
diff --git a/tests/ui-therapy-nav-scroll.spec.ts b/tests/ui-therapy-nav-scroll.spec.ts
index 5bfae41b9..cea3e09e4 100644
--- a/tests/ui-therapy-nav-scroll.spec.ts
+++ b/tests/ui-therapy-nav-scroll.spec.ts
@@ -85,9 +85,7 @@ test("phone Therapy section nav hides and returns with the universal header", as
 
   // Anchored: the portaled strip lives inside the collapse row, not sticky in content.
   await expect
-    .poll(async () =>
-      sectionNav.evaluate((node) => Boolean(node.closest('[data-testid="universal-header-collapse"]'))),
-    )
+    .poll(async () => sectionNav.evaluate((node) => Boolean(node.closest('[data-testid="universal-header-collapse"]'))))
     .toBe(true);
   await expect
     .poll(async () =>

From afb0ab27506bffead0771e29095148764fcb28f7 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:05:46 +0800
Subject: [PATCH 06/16] test: tolerate prettier whitespace in header sticky
 contract

---
 tests/header-scroll-hide-contract.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/header-scroll-hide-contract.test.ts b/tests/header-scroll-hide-contract.test.ts
index 8cbc3d30c..541a07d03 100644
--- a/tests/header-scroll-hide-contract.test.ts
+++ b/tests/header-scroll-hide-contract.test.ts
@@ -97,7 +97,7 @@ describe("shared header hide/reveal wiring", () => {
 
   it("keeps the header out of sticky positioning wherever its row collapses", () => {
     // Sticky pins the bar inside the viewport and fights the 1fr -> 0fr grid.
-    expect(headerSource).toContain('sticksAbovePhones || collapsesAtEveryWidth\n              ? "relative"');
+    expect(headerSource).toMatch(/sticksAbovePhones \|\| collapsesAtEveryWidth\s*\?\s*"relative"/);
   });
 
   it("counts the collapse budget only where the wrapper really collapses", () => {

From e3785be1e0ceddecaa930850b6fd50fd886def05 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:14:26 +0800
Subject: [PATCH 07/16] fix(ui): drop sticky search top offset when top bar
 collapses

Dashboard result composers still cleared a 4.75rem top-bar band after the
mode bar hid, leaving a dead gap above search. Rise to the viewport top
while collapse hide is active.
---
 docs/search-chrome-behaviour.md                  |  1 +
 .../clinical-dashboard/master-search-header.tsx  | 16 ++++++++++++----
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/search-chrome-behaviour.md b/docs/search-chrome-behaviour.md
index 802733ad3..36ad9ab62 100644
--- a/docs/search-chrome-behaviour.md
+++ b/docs/search-chrome-behaviour.md
@@ -44,6 +44,7 @@ Rules that keep this working:
 - **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.
 - **Sticky 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.
 - **Collapse only the top-bar row inside a sticky stack.** Translating the whole stack would take the search field off-screen; collapsing just the top bar lets search stay pinned at the viewport top.
+- **Drop the sticky search top offset while the top bar is hidden.** Result composers that clear a visible top bar with `top: 4.75rem + safe-area` must switch to `top: 0` when collapse hide is active — otherwise a dead band the height of the mode bar remains above the search field.
 - **Rebase the reporter on geometry switches.** Pass `resetKey` when the host changes the scrollport under it (`ClinicalDashboard` passes `searchMode`, which swaps `<main>`'s header reserve); otherwise the carried-over offset spends the first post-switch scroll on a spurious hide or reveal.
 
 Coverage: `tests/header-scroll-hide-contract.test.ts` (wiring), `tests/use-hide-on-scroll.test.ts` (decision logic), `tests/ui-chrome-scroll.spec.ts` (tablet/desktop top-bar hide/reveal with search still visible), `tests/ui-phone-scroll.spec.ts` (phone scroll geometry), `tests/ui-therapy-nav-scroll.spec.ts` (Therapy section nav hide/reveal with the top bar).
diff --git a/src/components/clinical-dashboard/master-search-header.tsx b/src/components/clinical-dashboard/master-search-header.tsx
index a32f545d7..71e8ddf22 100644
--- a/src/components/clinical-dashboard/master-search-header.tsx
+++ b/src/components/clinical-dashboard/master-search-header.tsx
@@ -1419,6 +1419,13 @@ export function MasterSearchHeader({
     const showsComposerPrivacyNotice = usesPhoneSearchLayout ? isDesktopHomeComposer : true;
 
     const commandSurfacePlacement = usesBottomComposerPlacement ? "bottom-dock" : "inline";
+    // Search sits outside the collapsing top-bar row. While the top bar is
+    // visible, sticky search clears its height; once the top bar hides, that
+    // offset would leave a dead band — drop to the viewport top instead.
+    const stickySearchClearsTopBar = !(hideStrategy === "collapse" && headerChromeHidden);
+    const stickySearchTopClass = stickySearchClearsTopBar
+      ? "top-[calc(4.75rem+env(safe-area-inset-top))] sm:top-[calc(4.75rem+env(safe-area-inset-top))]"
+      : "top-0 sm:top-0";
 
     return (
       <form
@@ -1462,12 +1469,13 @@ export function MasterSearchHeader({
                       ? "document-mobile-search-edge universal-top-search-edge fixed z-40 w-full"
                       : cn(
                           "document-mobile-search-edge universal-top-search-edge fixed z-40 mx-auto max-w-3xl sm:z-20 sm:w-full sm:px-4 sm:py-3 lg:max-w-4xl",
-                          isHeroDesktopComposer
-                            ? "sm:hidden"
-                            : "sm:sticky sm:top-[calc(4.75rem+env(safe-area-inset-top))]",
+                          isHeroDesktopComposer ? "sm:hidden" : cn("sm:sticky", stickySearchTopClass),
                         ),
                   )
-                : "universal-top-search-edge sticky top-[calc(4.75rem+env(safe-area-inset-top))] z-20 mx-auto box-border w-full px-3 py-3 sm:px-4",
+                : cn(
+                    "universal-top-search-edge sticky z-20 mx-auto box-border w-full px-3 py-3 sm:px-4",
+                    stickySearchTopClass,
+                  ),
           usesBottomComposerPlacement && "answer-footer-search-edge",
           usesPhoneFooterDock && "answer-footer-search-dock",
           usesCompactMobileBottomStyle && "document-mobile-search-compact",

From 64503ba6fbba96cc59ab6d8c5829955dd449c501 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:14:48 +0800
Subject: [PATCH 08/16] test: contract sticky search top offset drops when top
 bar hides

---
 tests/header-scroll-hide-contract.test.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/tests/header-scroll-hide-contract.test.ts b/tests/header-scroll-hide-contract.test.ts
index 541a07d03..1a8a6178e 100644
--- a/tests/header-scroll-hide-contract.test.ts
+++ b/tests/header-scroll-hide-contract.test.ts
@@ -127,5 +127,14 @@ describe("shared header hide/reveal wiring", () => {
     expect(behaviourDocSource).toContain("Hide the top bar, not the search field, above phones");
     expect(behaviourDocSource).toContain("Top-bar hide/reveal is cross-breakpoint");
     expect(behaviourDocSource).toContain("Page chrome that must match the top bar portals into the collapse host");
+    expect(behaviourDocSource).toContain("Drop the sticky search top offset while the top bar is hidden");
+  });
+
+  it("drops the sticky search top offset while the collapsing top bar is hidden", () => {
+    // Leaving top: 4.75rem after the mode bar collapses left a dead band above
+    // dashboard result search on tablet/desktop.
+    expect(headerSource).toContain("const stickySearchClearsTopBar");
+    expect(headerSource).toContain('hideStrategy === "collapse" && headerChromeHidden');
+    expect(headerSource).toContain('"top-0 sm:top-0"');
   });
 });

From 57e7a2729fa28baef3c02db564b8436b973c9ed0 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:30:59 +0800
Subject: [PATCH 09/16] test(ui): read Therapy canvas colour after phone nav
 portal

Phone section nav portals outside .tc-root into the header collapse host,
so closest(.tc-root) was empty. Read the workspace root from the document
and assert the strip is anchored under universal-header-collapse.
---
 tests/ui-route-coverage.spec.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/tests/ui-route-coverage.spec.ts b/tests/ui-route-coverage.spec.ts
index 857cb7db6..20d32d92e 100644
--- a/tests/ui-route-coverage.spec.ts
+++ b/tests/ui-route-coverage.spec.ts
@@ -246,19 +246,24 @@ test.describe("previously uncovered production routes", () => {
         await search.click();
         await expect(currentPage.getByRole("heading", { name: "Therapy", level: 1, exact: true })).toBeVisible();
         const nav = currentPage.getByRole("navigation", { name: "Therapy sections" });
+        // Phone: section nav portals into the header collapse host (outside
+        // .tc-root). Read canvas colour from the workspace root still in the
+        // page, and prove the strip is anchored under the collapsing top bar.
         const layout = await nav.evaluate((element) => {
           const navRect = element.getBoundingClientRect();
           const shellRect = element.parentElement?.getBoundingClientRect();
-          const root = element.closest(".tc-root");
+          const root = document.querySelector(".tc-root");
           return {
             centerDelta: shellRect
               ? navRect.left + navRect.width / 2 - (shellRect.left + shellRect.width / 2)
               : Number.POSITIVE_INFINITY,
             backgroundColor: root ? getComputedStyle(root).backgroundColor : "",
+            portaledIntoCollapse: Boolean(element.closest('[data-testid="universal-header-collapse"]')),
           };
         });
         expect(Math.abs(layout.centerDelta)).toBeLessThanOrEqual(1);
         expect(layout.backgroundColor).toBe("rgb(255, 255, 255)");
+        expect(layout.portaledIntoCollapse).toBe(true);
       },
     );
   });

From bb164e3d20c7871dbb877cf86e2909e72bc412a7 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:55:36 +0800
Subject: [PATCH 10/16] fix(ui): stop double-sticky search overlay and harden
 services Clear

Sticky-stack hosts already pin [top bar | search]; a second sticky composer
with its own top offset overlays page controls once the top bar collapses.
Keep that composer in normal flow inside the outer stack. Also target the
decision-rail Clear by title and re-query Compare after RightRail remounts.
---
 docs/search-chrome-behaviour.md               |  3 +-
 .../master-search-header.tsx                  | 29 +++++++++++++------
 .../services/services-navigator-page.tsx      |  5 ++++
 tests/header-scroll-hide-contract.test.ts     | 14 ++++++---
 tests/ui-smoke.spec.ts                        | 13 +++++++--
 5 files changed, 48 insertions(+), 16 deletions(-)

diff --git a/docs/search-chrome-behaviour.md b/docs/search-chrome-behaviour.md
index 36ad9ab62..86b2db8eb 100644
--- a/docs/search-chrome-behaviour.md
+++ b/docs/search-chrome-behaviour.md
@@ -44,7 +44,8 @@ Rules that keep this working:
 - **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.
 - **Sticky 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.
 - **Collapse only the top-bar row inside a sticky stack.** Translating the whole stack would take the search field off-screen; collapsing just the top bar lets search stay pinned at the viewport top.
-- **Drop the sticky search top offset while the top bar is hidden.** Result composers that clear a visible top bar with `top: 4.75rem + safe-area` must switch to `top: 0` when collapse hide is active — otherwise a dead band the height of the mode bar remains above the search field.
+- **Do not double-sticky the search inside an outer sticky stack.** When `wide: "sticky"` owns an outer stack, the composer stays `relative` in that stack. A second sticky search with its own `top` overlays page controls (and blocks clicks) once the top bar collapses.
+- **Collapse-everywhere hosts still drop their own sticky search offset while the top bar is hidden.** Dashboard result composers that clear a visible top bar with `top: 4.75rem + safe-area` must switch to `top: 0` when collapse hide is active — otherwise a dead band the height of the mode bar remains above the search field.
 - **Rebase the reporter on geometry switches.** Pass `resetKey` when the host changes the scrollport under it (`ClinicalDashboard` passes `searchMode`, which swaps `<main>`'s header reserve); otherwise the carried-over offset spends the first post-switch scroll on a spurious hide or reveal.
 
 Coverage: `tests/header-scroll-hide-contract.test.ts` (wiring), `tests/use-hide-on-scroll.test.ts` (decision logic), `tests/ui-chrome-scroll.spec.ts` (tablet/desktop top-bar hide/reveal with search still visible), `tests/ui-phone-scroll.spec.ts` (phone scroll geometry), `tests/ui-therapy-nav-scroll.spec.ts` (Therapy section nav hide/reveal with the top bar).
diff --git a/src/components/clinical-dashboard/master-search-header.tsx b/src/components/clinical-dashboard/master-search-header.tsx
index 71e8ddf22..bd407123f 100644
--- a/src/components/clinical-dashboard/master-search-header.tsx
+++ b/src/components/clinical-dashboard/master-search-header.tsx
@@ -1419,13 +1419,22 @@ export function MasterSearchHeader({
     const showsComposerPrivacyNotice = usesPhoneSearchLayout ? isDesktopHomeComposer : true;
 
     const commandSurfacePlacement = usesBottomComposerPlacement ? "bottom-dock" : "inline";
-    // Search sits outside the collapsing top-bar row. While the top bar is
-    // visible, sticky search clears its height; once the top bar hides, that
-    // offset would leave a dead band — drop to the viewport top instead.
+    // Search sits outside the collapsing top-bar row. Sticky hosts already pin an
+    // outer [top bar | search] stack, so the composer must stay in normal flow
+    // inside that stack — a second sticky + top offset would overlay page
+    // controls once the top bar collapses. Collapse-everywhere hosts have no
+    // outer stack, so their composer keeps its own sticky and drops the top-bar
+    // clearance while the bar is hidden.
+    const stickySearchOwnedByOuterStack = sticksAbovePhones;
     const stickySearchClearsTopBar = !(hideStrategy === "collapse" && headerChromeHidden);
-    const stickySearchTopClass = stickySearchClearsTopBar
-      ? "top-[calc(4.75rem+env(safe-area-inset-top))] sm:top-[calc(4.75rem+env(safe-area-inset-top))]"
-      : "top-0 sm:top-0";
+    const stickySearchTopClass = stickySearchOwnedByOuterStack
+      ? undefined
+      : stickySearchClearsTopBar
+        ? "top-[calc(4.75rem+env(safe-area-inset-top))] sm:top-[calc(4.75rem+env(safe-area-inset-top))]"
+        : "top-0 sm:top-0";
+    const stickySearchPositionClass = stickySearchOwnedByOuterStack
+      ? "relative sm:relative"
+      : cn("sm:sticky", stickySearchTopClass);
 
     return (
       <form
@@ -1469,12 +1478,14 @@ export function MasterSearchHeader({
                       ? "document-mobile-search-edge universal-top-search-edge fixed z-40 w-full"
                       : cn(
                           "document-mobile-search-edge universal-top-search-edge fixed z-40 mx-auto max-w-3xl sm:z-20 sm:w-full sm:px-4 sm:py-3 lg:max-w-4xl",
-                          isHeroDesktopComposer ? "sm:hidden" : cn("sm:sticky", stickySearchTopClass),
+                          isHeroDesktopComposer ? "sm:hidden" : stickySearchPositionClass,
                         ),
                   )
                 : cn(
-                    "universal-top-search-edge sticky z-20 mx-auto box-border w-full px-3 py-3 sm:px-4",
-                    stickySearchTopClass,
+                    "universal-top-search-edge mx-auto box-border w-full px-3 py-3 sm:px-4",
+                    stickySearchOwnedByOuterStack
+                      ? "relative z-20"
+                      : cn("sticky z-20", stickySearchTopClass),
                   ),
           usesBottomComposerPlacement && "answer-footer-search-edge",
           usesPhoneFooterDock && "answer-footer-search-dock",
diff --git a/src/components/services/services-navigator-page.tsx b/src/components/services/services-navigator-page.tsx
index df7df92b3..b195da6fa 100644
--- a/src/components/services/services-navigator-page.tsx
+++ b/src/components/services/services-navigator-page.tsx
@@ -491,6 +491,11 @@ function RightRail({
         type="button"
         disabled={!comparisonAvailable}
         title={comparisonAvailable ? "Compare selected services" : "Select at least two services before comparing"}
+        aria-label={
+          comparisonAvailable
+            ? `Compare selected services (${selected.length})`
+            : "Select at least two services before comparing"
+        }
         onClick={() => setShowComparison((current) => !current)}
         aria-expanded={comparisonExpanded}
         aria-controls={comparisonExpanded ? "selected-services-comparison" : undefined}
diff --git a/tests/header-scroll-hide-contract.test.ts b/tests/header-scroll-hide-contract.test.ts
index 1a8a6178e..1e703f405 100644
--- a/tests/header-scroll-hide-contract.test.ts
+++ b/tests/header-scroll-hide-contract.test.ts
@@ -127,12 +127,18 @@ describe("shared header hide/reveal wiring", () => {
     expect(behaviourDocSource).toContain("Hide the top bar, not the search field, above phones");
     expect(behaviourDocSource).toContain("Top-bar hide/reveal is cross-breakpoint");
     expect(behaviourDocSource).toContain("Page chrome that must match the top bar portals into the collapse host");
-    expect(behaviourDocSource).toContain("Drop the sticky search top offset while the top bar is hidden");
+    expect(behaviourDocSource).toContain("Do not double-sticky the search inside an outer sticky stack");
+    expect(behaviourDocSource).toContain(
+      "Collapse-everywhere hosts still drop their own sticky search offset while the top bar is hidden",
+    );
   });
 
-  it("drops the sticky search top offset while the collapsing top bar is hidden", () => {
-    // Leaving top: 4.75rem after the mode bar collapses left a dead band above
-    // dashboard result search on tablet/desktop.
+  it("keeps sticky-stack search in normal flow and only self-stickies collapse-everywhere hosts", () => {
+    // Double sticky (outer stack + composer top offset) overlays page controls
+    // once the top bar collapses — that blocked the services Clear control.
+    expect(headerSource).toContain("const stickySearchOwnedByOuterStack = sticksAbovePhones");
+    expect(headerSource).toContain('stickySearchOwnedByOuterStack\n      ? "relative sm:relative"');
+    // Dashboard collapse-everywhere composers still drop the 4.75rem clearance.
     expect(headerSource).toContain("const stickySearchClearsTopBar");
     expect(headerSource).toContain('hideStrategy === "collapse" && headerChromeHidden');
     expect(headerSource).toContain('"top-0 sm:top-0"');
diff --git a/tests/ui-smoke.spec.ts b/tests/ui-smoke.spec.ts
index 46451c66f..4aa9b5716 100644
--- a/tests/ui-smoke.spec.ts
+++ b/tests/ui-smoke.spec.ts
@@ -3351,11 +3351,20 @@ test.describe("Clinical KB UI smoke coverage", () => {
     await expect(compare).toHaveAttribute("title", "Compare selected services");
     await compare.click();
     await expect(navigator.getByRole("region", { name: "Selected service comparison" })).toBeVisible();
-    const clear = navigator.getByRole("button", { name: "Clear", exact: true });
+    // Prefer the decision-rail clear control — the results pane also exposes a
+    // "Clear" for quick filters, and a first-match click leaves selection intact.
+    const clear = navigator.locator('button[title="Clear selected services"]');
     await expect(clear).toBeEnabled();
     await clear.click();
     await expect(navigator.getByText("Selected services (0)")).toBeVisible();
-    await expect(compare).toHaveAttribute("title", "Select at least two services before comparing");
+    // RightRail remounts when selection empties (`key` swaps to "empty"), so
+    // re-query the compare control instead of reusing the pre-clear locator.
+    // Accessible name comes from aria-label once selection is empty.
+    const compareAfterClear = navigator.getByRole("button", {
+      name: "Select at least two services before comparing",
+    });
+    await expect(compareAfterClear).toBeDisabled();
+    await expect(compareAfterClear).toHaveAttribute("title", "Select at least two services before comparing");
   });
 
   test("search regressions avoid fetch errors and open viewer hits @critical", async ({ page }) => {

From 7aceb3212925e193b86c46be0724a4e53c2313b5 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:04:09 +0800
Subject: [PATCH 11/16] fix(ui): keep sticky-stack search out of fixed
 positioning above phones

A bare ixed class on the composer survived beside sm:relative under
Tailwind's cascade, so GlobalSearchShell search kept overlaying page
controls (Services Clear/Compare). Scope fixed to max-sm when the outer
sticky stack owns tablet/desktop placement, and assert Compare by title.
---
 .../master-search-header.tsx                  | 33 ++++++++++---------
 tests/ui-smoke.spec.ts                        |  9 ++---
 2 files changed, 20 insertions(+), 22 deletions(-)

diff --git a/src/components/clinical-dashboard/master-search-header.tsx b/src/components/clinical-dashboard/master-search-header.tsx
index bd407123f..e8e2eaa07 100644
--- a/src/components/clinical-dashboard/master-search-header.tsx
+++ b/src/components/clinical-dashboard/master-search-header.tsx
@@ -1382,6 +1382,18 @@ export function MasterSearchHeader({
     );
   }
 
+  const hideStrategy = hideOnScroll?.strategy;
+  // Overlay hosts that opt into all breakpoints take the header fully out of
+  // flow (absolute over the scrolling <main>, which reserves matching top
+  // padding) so content frosts under the glass bar at every width.
+  const overlayAllBreakpoints = hideStrategy === "overlay" && Boolean(hideOnScroll?.allBreakpoints);
+  const wideCollapseBehaviour = hideStrategy === "collapse" ? hideOnScroll?.wide : undefined;
+  // Collapse hosts whose scrollport is internal at every width release the
+  // header row at every width too; hosts that hand scrolling back to the
+  // document above the phone breakpoint stick and translate there instead.
+  const collapsesAtEveryWidth = wideCollapseBehaviour === "collapse";
+  const sticksAbovePhones = wideCollapseBehaviour === "sticky";
+
   function renderSearchComposer(placement: "default" | "desktop-home") {
     const isDesktopHomeComposer = placement === "desktop-home";
     const usesAnswerFooterStyle = isAnswerFooterComposer && !isDesktopHomeComposer;
@@ -1477,15 +1489,17 @@ export function MasterSearchHeader({
                     usesPhoneFooterDock
                       ? "document-mobile-search-edge universal-top-search-edge fixed z-40 w-full"
                       : cn(
-                          "document-mobile-search-edge universal-top-search-edge fixed z-40 mx-auto max-w-3xl sm:z-20 sm:w-full sm:px-4 sm:py-3 lg:max-w-4xl",
+                          // Sticky-stack hosts must not keep a bare `fixed` class:
+                          // if `sm:relative` loses the cascade fight, the composer
+                          // overlays the page (e.g. Services decision rail).
+                          "document-mobile-search-edge universal-top-search-edge z-40 mx-auto max-w-3xl sm:z-20 sm:w-full sm:px-4 sm:py-3 lg:max-w-4xl",
+                          stickySearchOwnedByOuterStack ? "max-sm:fixed" : "fixed",
                           isHeroDesktopComposer ? "sm:hidden" : stickySearchPositionClass,
                         ),
                   )
                 : cn(
                     "universal-top-search-edge mx-auto box-border w-full px-3 py-3 sm:px-4",
-                    stickySearchOwnedByOuterStack
-                      ? "relative z-20"
-                      : cn("sticky z-20", stickySearchTopClass),
+                    stickySearchOwnedByOuterStack ? "relative z-20" : cn("sticky z-20", stickySearchTopClass),
                   ),
           usesBottomComposerPlacement && "answer-footer-search-edge",
           usesPhoneFooterDock && "answer-footer-search-dock",
@@ -1731,17 +1745,6 @@ export function MasterSearchHeader({
     );
   }
 
-  const hideStrategy = hideOnScroll?.strategy;
-  // Overlay hosts that opt into all breakpoints take the header fully out of
-  // flow (absolute over the scrolling <main>, which reserves matching top
-  // padding) so content frosts under the glass bar at every width.
-  const overlayAllBreakpoints = hideStrategy === "overlay" && Boolean(hideOnScroll?.allBreakpoints);
-  const wideCollapseBehaviour = hideStrategy === "collapse" ? hideOnScroll?.wide : undefined;
-  // Collapse hosts whose scrollport is internal at every width release the
-  // header row at every width too; hosts that hand scrolling back to the
-  // document above the phone breakpoint stick and translate there instead.
-  const collapsesAtEveryWidth = wideCollapseBehaviour === "collapse";
-  const sticksAbovePhones = wideCollapseBehaviour === "sticky";
   const chromeFocusProps = hideOnScroll
     ? {
         onFocusCapture: () => setHeaderChromeFocused(true),
diff --git a/tests/ui-smoke.spec.ts b/tests/ui-smoke.spec.ts
index 4aa9b5716..485282b41 100644
--- a/tests/ui-smoke.spec.ts
+++ b/tests/ui-smoke.spec.ts
@@ -3348,7 +3348,6 @@ test.describe("Clinical KB UI smoke coverage", () => {
     await expect(navigator.locator("#service-confidence-details")).toBeVisible();
     const compare = navigator.getByRole("button", { name: /Compare selected/ });
     await expect(compare).toBeEnabled();
-    await expect(compare).toHaveAttribute("title", "Compare selected services");
     await compare.click();
     await expect(navigator.getByRole("region", { name: "Selected service comparison" })).toBeVisible();
     // Prefer the decision-rail clear control — the results pane also exposes a
@@ -3358,13 +3357,9 @@ test.describe("Clinical KB UI smoke coverage", () => {
     await clear.click();
     await expect(navigator.getByText("Selected services (0)")).toBeVisible();
     // RightRail remounts when selection empties (`key` swaps to "empty"), so
-    // re-query the compare control instead of reusing the pre-clear locator.
-    // Accessible name comes from aria-label once selection is empty.
-    const compareAfterClear = navigator.getByRole("button", {
-      name: "Select at least two services before comparing",
-    });
+    // re-query by the stable title attribute rather than accessible name.
+    const compareAfterClear = navigator.locator('button[title="Select at least two services before comparing"]');
     await expect(compareAfterClear).toBeDisabled();
-    await expect(compareAfterClear).toHaveAttribute("title", "Select at least two services before comparing");
   });
 
   test("search regressions avoid fetch errors and open viewer hits @critical", async ({ page }) => {

From c232c53ed0de87d9d820902d496bb9ae0e112eaf Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:22:33 +0800
Subject: [PATCH 12/16] fix(ui): stop sticky-stack search overlay and update UI
 assertions

Keep sticky-stack composers in normal flow (relative), harden Services rail
testids/scroll-into-view for the pinned search band, and accept sticky
ancestors in desktop composer placement checks.
---
 .../master-search-header.tsx                  | 24 +++++++--------
 .../services/services-navigator-page.tsx      | 13 +++++++--
 tests/header-scroll-hide-contract.test.ts     |  9 ++++--
 tests/ui-smoke.spec.ts                        | 29 ++++++++++++-------
 tests/ui-tools.spec.ts                        | 15 +++++++++-
 5 files changed, 60 insertions(+), 30 deletions(-)

diff --git a/src/components/clinical-dashboard/master-search-header.tsx b/src/components/clinical-dashboard/master-search-header.tsx
index e8e2eaa07..f84b392e9 100644
--- a/src/components/clinical-dashboard/master-search-header.tsx
+++ b/src/components/clinical-dashboard/master-search-header.tsx
@@ -1439,14 +1439,10 @@ export function MasterSearchHeader({
     // clearance while the bar is hidden.
     const stickySearchOwnedByOuterStack = sticksAbovePhones;
     const stickySearchClearsTopBar = !(hideStrategy === "collapse" && headerChromeHidden);
-    const stickySearchTopClass = stickySearchOwnedByOuterStack
-      ? undefined
-      : stickySearchClearsTopBar
-        ? "top-[calc(4.75rem+env(safe-area-inset-top))] sm:top-[calc(4.75rem+env(safe-area-inset-top))]"
-        : "top-0 sm:top-0";
-    const stickySearchPositionClass = stickySearchOwnedByOuterStack
-      ? "relative sm:relative"
-      : cn("sm:sticky", stickySearchTopClass);
+    const stickySearchTopClass = stickySearchClearsTopBar
+      ? "top-[calc(4.75rem+env(safe-area-inset-top))] sm:top-[calc(4.75rem+env(safe-area-inset-top))]"
+      : "top-0 sm:top-0";
+    const stickySearchPositionClass = cn("sm:sticky", stickySearchTopClass);
 
     return (
       <form
@@ -1489,12 +1485,14 @@ export function MasterSearchHeader({
                     usesPhoneFooterDock
                       ? "document-mobile-search-edge universal-top-search-edge fixed z-40 w-full"
                       : cn(
-                          // Sticky-stack hosts must not keep a bare `fixed` class:
-                          // if `sm:relative` loses the cascade fight, the composer
-                          // overlays the page (e.g. Services decision rail).
                           "document-mobile-search-edge universal-top-search-edge z-40 mx-auto max-w-3xl sm:z-20 sm:w-full sm:px-4 sm:py-3 lg:max-w-4xl",
-                          stickySearchOwnedByOuterStack ? "max-sm:fixed" : "fixed",
-                          isHeroDesktopComposer ? "sm:hidden" : stickySearchPositionClass,
+                          // Sticky-stack hosts already pin [top bar | search]. Never
+                          // leave a `fixed`/`sticky` composer in that stack — it
+                          // overlays page controls (Services decision rail).
+                          stickySearchOwnedByOuterStack
+                            ? "relative"
+                            : cn("fixed", isHeroDesktopComposer ? "sm:hidden" : stickySearchPositionClass),
+                          stickySearchOwnedByOuterStack && isHeroDesktopComposer && "sm:hidden",
                         ),
                   )
                 : cn(
diff --git a/src/components/services/services-navigator-page.tsx b/src/components/services/services-navigator-page.tsx
index b195da6fa..a44d92c07 100644
--- a/src/components/services/services-navigator-page.tsx
+++ b/src/components/services/services-navigator-page.tsx
@@ -336,12 +336,16 @@ function RightRail({
 
   return (
     <div className="space-y-4">
-      <section className="rounded-lg border border-[color:var(--border)] bg-[color:var(--surface)] p-4 shadow-[var(--shadow-tight)]">
+      <section
+        data-testid="services-referral-decision"
+        className="rounded-lg border border-[color:var(--border)] bg-[color:var(--surface)] p-4 shadow-[var(--shadow-tight)]"
+      >
         <div className="flex items-center justify-between gap-2">
           <h3 className="text-lg font-bold text-[color:var(--text-heading)]">Referral decision</h3>
           <button
             className="inline-flex min-h-tap items-center text-xs font-bold text-[color:var(--clinical-accent)] hover:text-[color:var(--clinical-accent-hover)] disabled:cursor-not-allowed disabled:opacity-50 sm:min-h-0"
             type="button"
+            data-testid="services-clear-selected"
             onClick={clearSelectedServices}
             disabled={selected.length === 0}
             title={selected.length === 0 ? "No selected services to clear" : "Clear selected services"}
@@ -349,7 +353,9 @@ function RightRail({
             Clear
           </button>
         </div>
-        <p className="mt-3 text-sm font-bold text-[color:var(--text-heading)]">Selected services ({selected.length})</p>
+        <p data-testid="services-selected-count" className="mt-3 text-sm font-bold text-[color:var(--text-heading)]">
+          Selected services ({selected.length})
+        </p>
         <div className="mt-3 grid gap-2">
           {selected.map((service, index) => (
             <button
@@ -392,7 +398,7 @@ function RightRail({
           ))}
         </div>
         <button
-          className="mt-4 inline-flex min-h-tap items-center gap-2 text-sm font-bold text-[color:var(--clinical-accent)] hover:text-[color:var(--clinical-accent-hover)] disabled:cursor-not-allowed disabled:opacity-50 sm:min-h-9"
+          className="mt-4 inline-flex min-h-tap scroll-mt-40 items-center gap-2 text-sm font-bold text-[color:var(--clinical-accent)] hover:text-[color:var(--clinical-accent-hover)] disabled:cursor-not-allowed disabled:opacity-50 sm:min-h-9 sm:scroll-mt-44"
           type="button"
           onClick={() => setShowChecklistDetails((current) => !current)}
           disabled={selected.length === 0}
@@ -489,6 +495,7 @@ function RightRail({
       <button
         className="inline-flex min-h-12 w-full items-center justify-center gap-2 rounded-lg bg-[color:var(--clinical-accent)] text-sm font-bold text-[color:var(--clinical-accent-contrast)] shadow-[var(--shadow-tight)] hover:bg-[color:var(--clinical-accent-hover)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)] disabled:cursor-not-allowed disabled:opacity-50"
         type="button"
+        data-testid="services-compare-selected"
         disabled={!comparisonAvailable}
         title={comparisonAvailable ? "Compare selected services" : "Select at least two services before comparing"}
         aria-label={
diff --git a/tests/header-scroll-hide-contract.test.ts b/tests/header-scroll-hide-contract.test.ts
index 1e703f405..795e3aeda 100644
--- a/tests/header-scroll-hide-contract.test.ts
+++ b/tests/header-scroll-hide-contract.test.ts
@@ -135,9 +135,14 @@ describe("shared header hide/reveal wiring", () => {
 
   it("keeps sticky-stack search in normal flow and only self-stickies collapse-everywhere hosts", () => {
     // Double sticky (outer stack + composer top offset) overlays page controls
-    // once the top bar collapses — that blocked the services Clear control.
+    // once the top bar collapses — that blocked the services decision rail.
     expect(headerSource).toContain("const stickySearchOwnedByOuterStack = sticksAbovePhones");
-    expect(headerSource).toContain('stickySearchOwnedByOuterStack\n      ? "relative sm:relative"');
+    // Bare `fixed` must not remain on sticky-stack composers (cascade fight).
+    expect(headerSource).toMatch(/stickySearchOwnedByOuterStack\s*\?\s*"relative"/);
+    expect(headerSource).toContain(
+      'stickySearchOwnedByOuterStack\n                            ? "relative"\n                            : cn("fixed"',
+    );
+    expect(headerSource).toContain('stickySearchOwnedByOuterStack ? "relative z-20" : cn("sticky z-20"');
     // Dashboard collapse-everywhere composers still drop the 4.75rem clearance.
     expect(headerSource).toContain("const stickySearchClearsTopBar");
     expect(headerSource).toContain('hideStrategy === "collapse" && headerChromeHidden');
diff --git a/tests/ui-smoke.spec.ts b/tests/ui-smoke.spec.ts
index 485282b41..a14bfb023 100644
--- a/tests/ui-smoke.spec.ts
+++ b/tests/ui-smoke.spec.ts
@@ -3338,28 +3338,35 @@ test.describe("Clinical KB UI smoke coverage", () => {
     const navigator = page.getByRole("main");
     await expect(navigator).toBeVisible();
     await expect(navigator.getByRole("button", { name: "Edit" })).toHaveCount(0);
+    // Sticky-stack search stays pinned above phones. Playwright's default
+    // scroll-into-view parks rail controls under that composer (Clear search
+    // intercepts). Center the control first so the click hits the rail.
+    const clickRailControl = async (locator: Locator) => {
+      await locator.evaluate((element) => {
+        element.scrollIntoView({ block: "center", inline: "nearest" });
+      });
+      await locator.click();
+    };
     const reviewDetails = navigator.getByRole("button", { name: "Review details" });
     await expect(reviewDetails).toBeEnabled();
-    await reviewDetails.click();
+    await clickRailControl(reviewDetails);
     await expect(navigator.locator("#service-checklist-details")).toBeVisible();
     const viewDetails = navigator.getByRole("button", { name: "View details" });
     await expect(viewDetails).toBeEnabled();
-    await viewDetails.click();
+    await clickRailControl(viewDetails);
     await expect(navigator.locator("#service-confidence-details")).toBeVisible();
-    const compare = navigator.getByRole("button", { name: /Compare selected/ });
+    const compare = navigator.getByTestId("services-compare-selected");
     await expect(compare).toBeEnabled();
-    await compare.click();
+    await clickRailControl(compare);
     await expect(navigator.getByRole("region", { name: "Selected service comparison" })).toBeVisible();
     // Prefer the decision-rail clear control — the results pane also exposes a
     // "Clear" for quick filters, and a first-match click leaves selection intact.
-    const clear = navigator.locator('button[title="Clear selected services"]');
+    const clear = navigator.getByTestId("services-clear-selected");
     await expect(clear).toBeEnabled();
-    await clear.click();
-    await expect(navigator.getByText("Selected services (0)")).toBeVisible();
-    // RightRail remounts when selection empties (`key` swaps to "empty"), so
-    // re-query by the stable title attribute rather than accessible name.
-    const compareAfterClear = navigator.locator('button[title="Select at least two services before comparing"]');
-    await expect(compareAfterClear).toBeDisabled();
+    await clickRailControl(clear);
+    await expect(navigator.getByTestId("services-selected-count")).toHaveText("Selected services (0)");
+    // RightRail remounts when selection empties (`key` swaps to "empty").
+    await expect(navigator.getByTestId("services-compare-selected")).toBeDisabled();
   });
 
   test("search regressions avoid fetch errors and open viewer hits @critical", async ({ page }) => {
diff --git a/tests/ui-tools.spec.ts b/tests/ui-tools.spec.ts
index 35e9454ff..ab2dc2194 100644
--- a/tests/ui-tools.spec.ts
+++ b/tests/ui-tools.spec.ts
@@ -313,6 +313,13 @@ async function globalSearchComposerMetrics(page: Page, homeTestId?: string) {
       const formRect = form.getBoundingClientRect();
       const homeRect = home?.getBoundingClientRect();
       const style = window.getComputedStyle(form);
+      // Sticky-stack hosts (`wide: "sticky"`) keep the composer `relative` inside
+      // an outer sticky [top bar | search] wrapper — do not require the form itself
+      // to be `position: sticky`.
+      let stickyAncestor = style.position === "sticky";
+      for (let node: HTMLElement | null = form.parentElement; node && !stickyAncestor; node = node.parentElement) {
+        if (window.getComputedStyle(node).position === "sticky") stickyAncestor = true;
+      }
 
       return {
         formLeft: formRect.left,
@@ -326,6 +333,7 @@ async function globalSearchComposerMetrics(page: Page, homeTestId?: string) {
         homeRight: homeRect?.right ?? null,
         homeCenterX: homeRect ? homeRect.left + homeRect.width / 2 : null,
         position: style.position,
+        stickyAncestor,
         viewportWidth: window.innerWidth,
         viewportHeight: window.innerHeight,
         pillClassName: pill?.className?.toString() ?? "",
@@ -930,7 +938,12 @@ test.describe("Clinical KB tools launcher", () => {
             expect(metrics?.formBottom ?? 0).toBeGreaterThanOrEqual(viewport.height - 2);
           }
         } else {
-          expect(metrics?.position).toBe("sticky");
+          // Sticky-stack shells pin via an outer wrapper; collapse-everywhere hosts
+          // still self-sticky the form. Either keeps the composer in the top band.
+          expect(
+            metrics?.position === "sticky" || metrics?.stickyAncestor,
+            `${route.path} at ${viewport.name} should stick via the form or its sticky stack`,
+          ).toBe(true);
           expect(metrics?.formCenterY ?? viewport.height).toBeLessThan(viewport.height * 0.25);
           await expect(page.locator(".answer-footer-search-chip:visible")).toHaveCount(0);
         }

From 79dcee52dc75c340ef5eea041c3fe8ae0016d2c5 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:45:34 +0800
Subject: [PATCH 13/16] chore: re-trigger CI after main sync left workflows
 pending approval


From 1280fcd7f40fcd766d34e19ad35e58f32e313f10 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:50:02 +0800
Subject: [PATCH 14/16] docs(ui): note sticky search can overlap wide decision
 rails

Document the Services-rail click hazard under the pinned sticky-stack
search band and keep the header scroll contract aligned.
---
 docs/search-chrome-behaviour.md           | 1 +
 tests/header-scroll-hide-contract.test.ts | 1 +
 2 files changed, 2 insertions(+)

diff --git a/docs/search-chrome-behaviour.md b/docs/search-chrome-behaviour.md
index 86b2db8eb..93f7da35d 100644
--- a/docs/search-chrome-behaviour.md
+++ b/docs/search-chrome-behaviour.md
@@ -45,6 +45,7 @@ Rules that keep this working:
 - **Sticky 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.
 - **Collapse only the top-bar row inside a sticky stack.** Translating the whole stack would take the search field off-screen; collapsing just the top bar lets search stay pinned at the viewport top.
 - **Do not double-sticky the search inside an outer sticky stack.** When `wide: "sticky"` owns an outer stack, the composer stays `relative` in that stack. A second sticky search with its own `top` overlays page controls (and blocks clicks) once the top bar collapses.
+- **Pinned search can cover wide side rails.** The sticky stack stays centred and can geometrically overlap `xl` decision rails (Services). Prefer `scroll-margin-top` on rail controls and centre scroll-into-view in tests; do not put the composer back to `fixed`/`sticky` inside the stack to “win” that fight.
 - **Collapse-everywhere hosts still drop their own sticky search offset while the top bar is hidden.** Dashboard result composers that clear a visible top bar with `top: 4.75rem + safe-area` must switch to `top: 0` when collapse hide is active — otherwise a dead band the height of the mode bar remains above the search field.
 - **Rebase the reporter on geometry switches.** Pass `resetKey` when the host changes the scrollport under it (`ClinicalDashboard` passes `searchMode`, which swaps `<main>`'s header reserve); otherwise the carried-over offset spends the first post-switch scroll on a spurious hide or reveal.
 
diff --git a/tests/header-scroll-hide-contract.test.ts b/tests/header-scroll-hide-contract.test.ts
index 795e3aeda..2e546db93 100644
--- a/tests/header-scroll-hide-contract.test.ts
+++ b/tests/header-scroll-hide-contract.test.ts
@@ -128,6 +128,7 @@ describe("shared header hide/reveal wiring", () => {
     expect(behaviourDocSource).toContain("Top-bar hide/reveal is cross-breakpoint");
     expect(behaviourDocSource).toContain("Page chrome that must match the top bar portals into the collapse host");
     expect(behaviourDocSource).toContain("Do not double-sticky the search inside an outer sticky stack");
+    expect(behaviourDocSource).toContain("Pinned search can cover wide side rails");
     expect(behaviourDocSource).toContain(
       "Collapse-everywhere hosts still drop their own sticky search offset while the top bar is hidden",
     );

From fdc20bfedb61a2c267c22a3d78ccc8214e6c0087 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:09:57 +0800
Subject: [PATCH 15/16] fix(test): account for safe-area spacer in Therapy nav
 hide assert

Collapsed chrome now sits below chrome-safe-area-top, so the phone nav
off-screen check must use the collapse host top rather than viewport y=0.
---
 tests/ui-therapy-nav-scroll.spec.ts | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

diff --git a/tests/ui-therapy-nav-scroll.spec.ts b/tests/ui-therapy-nav-scroll.spec.ts
index cea3e09e4..14609e858 100644
--- a/tests/ui-therapy-nav-scroll.spec.ts
+++ b/tests/ui-therapy-nav-scroll.spec.ts
@@ -111,20 +111,18 @@ test("phone Therapy section nav hides and returns with the universal header", as
   }
 
   await expect(collapseHost).toHaveAttribute("data-scroll-hidden", "true", { timeout: 5_000 });
-  // Collapsed chrome is clipped by the 0fr track — height/bottom must leave the viewport.
+  // Collapsed chrome is clipped by the 0fr track. With the always-on
+  // chrome-safe-area-top spacer, the collapse host sits below that band — so
+  // "off screen" means above-or-at the spacer bottom, not necessarily y<=1.
   await expect
     .poll(async () =>
-      sectionNav.evaluate((node) => {
-        const rect = node.getBoundingClientRect();
-        return { height: rect.height, bottom: rect.bottom };
-      }),
-    )
-    .toEqual(expect.objectContaining({ height: expect.any(Number) }));
-  await expect
-    .poll(async () =>
-      sectionNav.evaluate((node) => {
-        const rect = node.getBoundingClientRect();
-        return rect.height <= 1 || rect.bottom <= 1;
+      page.evaluate(() => {
+        const nav = document.querySelector('[data-testid="therapy-compass-section-nav"]');
+        const collapse = document.querySelector('[data-testid="universal-header-collapse"]');
+        if (!(nav instanceof HTMLElement) || !(collapse instanceof HTMLElement)) return false;
+        const navRect = nav.getBoundingClientRect();
+        const collapseRect = collapse.getBoundingClientRect();
+        return navRect.height <= 1 || navRect.bottom <= collapseRect.top + 1;
       }),
     )
     .toBe(true);

From db4390b3814910d0210497e2982414904f2e0704 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:22:11 +0800
Subject: [PATCH 16/16] docs(ledger): record PR #1238 header top-bar-only hide
 CI green

---
 docs/branch-review-ledger.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/branch-review-ledger.md b/docs/branch-review-ledger.md
index 767536970..ea41fcd9a 100644
--- a/docs/branch-review-ledger.md
+++ b/docs/branch-review-ledger.md
@@ -1034,3 +1034,4 @@ This file is append-only. Never rewrite or delete an existing review record; app
 | 2026-07-25 | origin/execute-audit-remediation-plan (PR #1188 closed tip) | `8b8639113925601e1687bfe4f1f29c44a4308b61` | branch-cleanup | DELETED remote. Tip rejected (conflict markers + parse breakers); intentional maintainability work already on main via #1213 (`8e3a49d0`). IMP-04 mockup/export prune from tip commit `3bc391dff` was not ported (knip-only unexports; optional follow-up). Local Antigravity worktrees left untouched. | Content proof: notices/utils/Sheet autofocus on origin/main; tip marker count 12; `git push origin --delete execute-audit-remediation-plan`. No provider calls. |
 | 2026-07-25 | PR #1195 / `subagent-Asset-Optimization-Implementer-self-b295a5bb` | `c612c88aae386a29715cadfb5dbd2b95163e1dc9` | prlanded after squash merge | MERGED. Squash tip `c612c88aa` on main; remote feature branch deleted. Product content verified on main (`check:assets`, icon Cache-Control, SignedImage/non-PDF a11y). Local review worktree retained for optional cleanup. | gh pr view MERGED; two-dot product-file diff empty vs origin/main; no provider checks. |
 
+| 2026-07-26 | PR #1238 / `cursor/header-hide-top-bar-only-4fd7` | `fdc20bfedb61a2c267c22a3d78ccc8214e6c0087` | Continue-executing: top-bar-only hide + CI green | APPROVE / MERGEABLE. Root cause fixed: collapse wraps only `header#search` (+ Therapy addon); sticky hosts pin outer [top bar \| search] below `chrome-safe-area-top` without translating search away; sticky-stack composers stay `relative`. Services rail overlay hardened (testids + center scrollIntoView); ui-tools accepts sticky ancestor; Therapy nav assert uses collapse-host top under safe-area spacer. Merged main safe-area + submitted-result focus rules. | Hosted PR required + Production UI SUCCESS on tip; contract 14/14; focused Playwright services/desktop composers 6/6, chrome-scroll 12/12, therapy-nav 1/1. No provider-backed checks. |