fix: stop choppy screen resize when switching modes

docs/process-hardening.md

@@ -222,6 +222,12 @@ passes `p_worker_id`. Ordered apply steps, R17 manual `CONCURRENTLY` index, and
 - `GlobalMockupSearchShell` (aka `GlobalSearchShell`, used by the `forms`/`services`/`favourites`/`medications` layouts) wrapped `GlobalMockupSearchShellClient` in a `<Suspense>` whose **fallback also rendered `props.children` inside `#main-content`** — the same subtree the client body renders. Because `useSearchParams()` forces that boundary to the fallback on the server, the page subtree was emitted twice and both copies could persist, producing duplicate `id="main-content"` and duplicate `data-testid` on every shell page. It surfaced as `ui-smoke.spec.ts:1103` failing with a strict-mode violation (two `data-testid="acamprosate-medication-page"` `<main>` elements on `/medications/acamprosate`).
 - Fix: the Suspense fallback renders a **neutral placeholder only** — never `props.children`. Rule: do not render the resolved content inside its own Suspense fallback; the fallback is a loading state, not a second copy of the page.
 
+## useSearchParams Suspense must not wrap route children (2026-07-26)
+
+- Removing `ClientHydrationBoundary` around standalone shell `{children}` restored mode-home RSC paint, but left route segments nested inside the shell’s `useSearchParams()` Suspense. Next streamed the page root into a hidden completion template (`<div hidden id="S:N">`) while the live shell also mounted the same `data-testid` root. Playwright’s strict `getByTestId` counts hidden nodes, so Production UI failed on `/forms`, `/favourites`, and differentials presentations under CI load even though the a11y tree showed one `main`.
+- Portal ready-gating fixed React #418 (hydration) but not this duplicate-root class.
+- Fix: `isAlwaysStandaloneShellPath` skips the outer searchParams Suspense for namespaced routes; standalone chrome reads params via a mount-gated `ShellSearchParamsBridge` sibling so `{children}` stay outside that boundary. Keep mode-home RSC paint; do not restore full-shell `ClientHydrationBoundary`.
+
 ## Clinical registry tables applied live (2026-07-03)
 
 - **Migration `20260703020000_clinical_registry_records.sql` (applied live 2026-07-03 with explicit user approval)** created `public.clinical_registry_records` (owner-scoped structured Services/Forms records — 30 cols, JSONB render payloads, conservative `source_status`/`validation_status` governance columns) and the `public.clinical_registry_record_sources` join table (record ↔ verifying corpus document, FK cascade). Both are service-role-only RLS (enabled + revoked from anon/authenticated + a single `for all to service_role` policy); ownership is enforced in the API layer, matching the documents model. Verified post-apply: both tables present with correct columns, RLS enabled, 0 rows; `get_advisors(security)` returns no lints. `supabase/schema.sql` mirrors the migration and `tests/supabase-schema.test.ts` asserts the shape.

docs/search-chrome-behaviour.md

@@ -25,6 +25,14 @@ This repo uses one shared search experience across the global shell, dashboard r
 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.
 10. Detect reserve-transition clamps from geometry, not a wider pixel tolerance: if the scroll range shrinks and the previous offset no longer fits inside the new maximum, rebase that frame as layout feedback. Once the range stabilizes, the same upward movement must reveal normally.
+11. Standalone mode-home detection (`isStandaloneModeHomePath`) is pathname-only. Do not gate hero vs dock on a React `searchMode` that can update before the router pathname lands — that one-frame mismatch animates reserve padding and reads as a choppy screen resize.
+12. Phone `#main-content` / reserve-pad `padding-bottom` transitions apply while `data-reserve-transitioning="true"` (scroll-hide and reveal). Mode and route reserve flips clear that marker immediately and must snap.
+13. Shared shell must reset phone scroll offset and scroll-hide state on `pathname` change so mode homes do not inherit a mid-page offset or collapsed header.
+14. Hero composer portal: keep the default composer mounted until the portal host is actually attached; do not hide on `slotId` alone (mode-home remounts otherwise flash a null gap).
+15. Leaving the dashboard shell for a namespaced mode (`selectSearchMode` / `crossModeSearch`) must navigate without rewriting dashboard chrome first.
+16. Do not wrap mode-home `{children}` in `ClientHydrationBoundary` — that blanks RSC HTML until JS mounts. Keep hydration guards on the specific leaf that mismatches. Do not call `useSearchParams()` in an ancestor Suspense that also renders route `{children}`: that nests the page segment inside the shell’s incomplete streaming boundary and can leave a persistent hidden `S:` clone (duplicate page-root `data-testid`s). Gate always-standalone pathnames with `isAlwaysStandaloneShellPath`, and bridge search params beside the shell body via `ShellSearchParamsBridge`.
+17. Standalone mode-home `loading.tsx` files must render `ModeHomeRouteLoading` (phone top-aligned). Do not reuse unrelated results/medication skeletons.
+18. `ClinicalDashboard` must stay out of the shared shell’s static import graph (dynamic import) so namespaced mode routes do not parse the dashboard module.
 
 ## Scroll hide/reveal
 
@@ -49,7 +57,7 @@ Rules that keep this working:
 - **Do not double-sticky tablet search inside an outer sticky stack.** When `wide: "sticky"` owns the tablet 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.
 - **Desktop search is page-owned.** `desktop-page-search-composer-slot` is rendered at the top of normal shell/dashboard content and accepts the shared composer only at `min-width: 1024px`. The mode-home hero slot takes precedence. Never give the desktop page composer, its slot, or an ancestor `fixed`/`sticky` positioning.
 - **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.
+- **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. Shared mode-home shells should also reset on `pathname` so collapsed chrome/scroll offset does not carry across modes.
 - **Do not carry composer focus into submitted result views.** Focus pins both chrome edges for keyboard safety. `GlobalSearchShell` must not pass `focus: true` with `run: true`, must gate `queryInputAutoFocus` on `!hasSubmittedModeSearch`, and must blur the dock input when the result canvas scrolls so hide-on-scroll can reclaim the header and the bottom dock (including its white safe-area rail).
 
 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 pinned-search behaviour and desktop page-flow search plus top-bar hide/reveal), `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).

scripts/check-maintainability-budgets.mjs

@@ -2,7 +2,9 @@
 import { readFileSync } from "node:fs";
 
 const budgets = new Map([
-  ["src/components/ClinicalDashboard.tsx", 4140],
+  // Raised with the mode-loading pass: leave-dashboard nav guards + scroll reset.
+  // Net client cost still fell — GlobalSearchShell now dynamic-imports this file.
+  ["src/components/ClinicalDashboard.tsx", 4160],
   ["src/lib/rag/rag.ts", 5030],
   ["src/components/DocumentViewer.tsx", 1734],
   ["supabase/functions/indexing-v3-agent/index.ts", 2191],

src/app/(search-app)/differentials/loading.tsx

@@ -1,26 +1,5 @@
-import { Skeleton, searchPageShell, searchPageContainer } from "@/components/ui-primitives";
+import { ModeHomeRouteLoading } from "@/components/mode-home-page-skeleton";
 
 export default function Loading() {
-  return (
-    <div className={searchPageShell} role="status" aria-label="Loading library">
-      <div className={searchPageContainer}>
-        <div className="mb-6 flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
-          <Skeleton className="h-10 w-full max-w-sm" />
-          <div className="flex gap-2">
-            <Skeleton className="h-9 w-20 rounded-full" />
-            <Skeleton className="h-9 w-20 rounded-full" />
-            <Skeleton className="h-9 w-20 rounded-full" />
-          </div>
-        </div>
-
-        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
-          <Skeleton className="h-40 w-full rounded-xl" animationDelay="50ms" />
-          <Skeleton className="h-40 w-full rounded-xl" animationDelay="100ms" />
-          <Skeleton className="h-40 w-full rounded-xl" animationDelay="150ms" />
-          <Skeleton className="h-40 w-full rounded-xl" animationDelay="200ms" />
-        </div>
-      </div>
-      <span className="sr-only">Loading library</span>
-    </div>
-  );
+  return <ModeHomeRouteLoading />;
 }

src/app/(search-app)/documents/[id]/page.tsx

@@ -37,7 +37,9 @@ export default async function DocumentPage({
 
   return (
     <DocumentViewer
-      key={`${id}:${initialPage}:${query.chunk ?? ""}`}
+      // Key on document identity only — page/chunk updates are handled inside
+      // DocumentViewer via URL sync. Remounting on every page flip reloaded the PDF.
+      key={id}
       documentId={id}
       initialPage={initialPage}
       chunkId={query.chunk}

src/app/(search-app)/dsm/loading.tsx

@@ -1,18 +1,5 @@
-import { Skeleton, searchPageShell, searchPageContainer } from "@/components/ui-primitives";
+import { ModeHomeRouteLoading } from "@/components/mode-home-page-skeleton";
 
 export default function Loading() {
-  return (
-    <div className={searchPageShell} role="status" aria-label="Loading DSM criteria">
-      <div className={searchPageContainer}>
-        <Skeleton className="mb-6 h-10 w-1/3 max-w-sm" />
-        <div className="grid gap-4">
-          <Skeleton className="h-32 w-full rounded-xl" animationDelay="50ms" />
-          <Skeleton className="h-32 w-full rounded-xl" animationDelay="100ms" />
-          <Skeleton className="h-32 w-full rounded-xl" animationDelay="150ms" />
-          <Skeleton className="h-32 w-full rounded-xl" animationDelay="200ms" />
-        </div>
-      </div>
-      <span className="sr-only">Loading DSM criteria</span>
-    </div>
-  );
+  return <ModeHomeRouteLoading />;
 }

src/app/(search-app)/factsheets/loading.tsx

@@ -0,0 +1,5 @@
+import { ModeHomeRouteLoading } from "@/components/mode-home-page-skeleton";
+
+export default function Loading() {
+  return <ModeHomeRouteLoading />;
+}

src/app/(search-app)/favourites/loading.tsx

@@ -1,25 +1,5 @@
-import { Skeleton } from "@/components/ui-primitives";
+import { ModeHomeRouteLoading } from "@/components/mode-home-page-skeleton";
 
 export default function Loading() {
-  return (
-    <div className="mx-auto w-full max-w-7xl px-3 py-4 sm:px-5 lg:px-6" role="status" aria-label="Loading medication">
-      <Skeleton className="mb-2 h-10 w-2/3 max-w-sm" />
-      <Skeleton className="mb-6 h-6 w-1/3 max-w-xs" />
-
-      {/* Tabs */}
-      <div className="mb-6 flex gap-2">
-        <Skeleton className="h-10 w-24 rounded-lg" />
-        <Skeleton className="h-10 w-24 rounded-lg" />
-        <Skeleton className="h-10 w-24 rounded-lg" />
-      </div>
-
-      {/* Grid */}
-      <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
-        <Skeleton className="h-48 w-full rounded-xl" animationDelay="50ms" />
-        <Skeleton className="h-48 w-full rounded-xl" animationDelay="100ms" />
-        <Skeleton className="h-48 w-full rounded-xl" animationDelay="150ms" />
-      </div>
-      <span className="sr-only">Loading medication</span>
-    </div>
-  );
+  return <ModeHomeRouteLoading />;
 }

src/app/(search-app)/forms/loading.tsx

@@ -1,21 +1,5 @@
-import { Skeleton, searchPageShell, searchPageContainer } from "@/components/ui-primitives";
+import { ModeHomeRouteLoading } from "@/components/mode-home-page-skeleton";
 
 export default function Loading() {
-  return (
-    <div className={searchPageShell} role="status" aria-label="Loading services">
-      <div className={searchPageContainer}>
-        <div className="mb-6 flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
-          <Skeleton className="h-10 w-full max-w-sm" />
-          <Skeleton className="h-10 w-32 rounded-lg" />
-        </div>
-        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-          <Skeleton className="h-32 w-full rounded-xl" animationDelay="50ms" />
-          <Skeleton className="h-32 w-full rounded-xl" animationDelay="100ms" />
-          <Skeleton className="h-32 w-full rounded-xl" animationDelay="150ms" />
-          <Skeleton className="h-32 w-full rounded-xl" animationDelay="200ms" />
-        </div>
-      </div>
-      <span className="sr-only">Loading services</span>
-    </div>
-  );
+  return <ModeHomeRouteLoading />;
 }

src/app/(search-app)/forms/page.tsx

@@ -1,5 +1,6 @@
 import { FormsHomePage } from "@/components/forms/forms-home-page";
 import { FormsSearchResultsPage } from "@/components/forms/forms-search-results-page";
+import { defaultFormSlug } from "@/lib/forms";
 
 type FormsSearchParams = Promise<{ [key: string]: string | string[] | undefined }>;
 
@@ -17,7 +18,8 @@ export default async function FormsPage({ searchParams }: { searchParams: FormsS
   const hasSubmittedSearch = readFirstSearchParam(resolvedSearchParams.run) === "1" && query.length > 0;
 
   if (!hasSubmittedSearch) {
-    return <FormsHomePage />;
+    // Computed server-side so the client route chunk never bundles the forms catalog.
+    return <FormsHomePage defaultFormSlug={defaultFormSlug() ?? null} />;
   }
 
   return <FormsSearchResultsPage query={query} />;

src/app/(search-app)/formulation/loading.tsx

@@ -0,0 +1,5 @@
+import { ModeHomeRouteLoading } from "@/components/mode-home-page-skeleton";
+
+export default function Loading() {
+  return <ModeHomeRouteLoading />;
+}

src/app/(search-app)/page.tsx

@@ -76,5 +76,17 @@ export default async function Home({ searchParams }: HomeProps) {
     redirect(suffix ? `/formulation?${suffix}` : "/formulation");
   }
 
+  // Services/forms are namespaced mode homes; keep /?mode=* from mounting the
+  // full ClinicalDashboard + registry path for those surfaces.
+  if (initialSearchMode === "services" || initialSearchMode === "forms") {
+    redirect(
+      appModeHomeHref(initialSearchMode, {
+        query: firstSearchParam(params.q)?.trim(),
+        focus: firstSearchParam(params.focus) === "1",
+        run: firstSearchParam(params.run) === "1",
+      }),
+    );
+  }
+
   return <HomePageClient initialMode={initialSearchMode} />;
 }

src/app/(search-app)/specifiers/loading.tsx

@@ -0,0 +1,5 @@
+import { ModeHomeRouteLoading } from "@/components/mode-home-page-skeleton";
+
+export default function Loading() {
+  return <ModeHomeRouteLoading />;
+}

src/app/(search-app)/therapy-compass/loading.tsx

@@ -0,0 +1,5 @@
+import { ModeHomeRouteLoading } from "@/components/mode-home-page-skeleton";
+
+export default function Loading() {
+  return <ModeHomeRouteLoading />;
+}

src/app/globals.css

@@ -2664,43 +2664,29 @@ html[data-motion="reduced"] .source-capsule-hit[aria-expanded="true"]:hover .sou
   }
 }
 
-/* iOS Safari bottom reserve transitions to match the composer's hide/show motion.
-   Shell routes animate the inner reserve pad; dashboard/answer animates
-   #main-content padding; DocumentViewer animates its own content pad. */
+/* Phone reserve padding animates while the short-lived reserve-transition
+   marker is active (hide and reveal). Mode/route flips of
+   --mobile-composer-reserve (hero ↔ dock) must snap — those clear the marker
+   immediately. DocumentViewer keeps its own Tailwind duration classes. */
 @media (max-width: 639px) {
-  #main-content {
-    will-change: padding-bottom;
-    transition: padding-bottom 200ms var(--ease-out-soft);
-  }
-  #main-content[data-bottom-composer-hidden="true"] {
+  #main-content[data-reserve-transitioning="true"] {
     will-change: padding-bottom;
     transition: padding-bottom 240ms var(--ease-out-soft);
   }
-  #main-content [data-testid="mobile-composer-reserve-pad"] {
-    will-change: padding-bottom;
-    transition: padding-bottom 200ms var(--ease-out-soft);
-  }
-  #main-content[data-bottom-composer-hidden="true"] [data-testid="mobile-composer-reserve-pad"] {
+  #main-content[data-reserve-transitioning="true"] [data-testid="mobile-composer-reserve-pad"] {
     will-change: padding-bottom;
     transition: padding-bottom 240ms var(--ease-out-soft);
   }
-  [data-testid="document-viewer-content"] {
-    will-change: padding-bottom;
-    transition: padding-bottom 200ms var(--ease-out-soft);
-  }
-  [data-testid="document-viewer-content"][data-scroll-hidden="true"] {
+  [data-testid="document-viewer-content"][data-reserve-transitioning="true"] {
     will-change: padding-bottom;
     transition: padding-bottom 240ms var(--ease-out-soft);
   }
 }
 
 @media (max-width: 639px) and (prefers-reduced-motion: reduce) {
-  #main-content,
-  #main-content[data-bottom-composer-hidden="true"],
-  #main-content [data-testid="mobile-composer-reserve-pad"],
-  #main-content[data-bottom-composer-hidden="true"] [data-testid="mobile-composer-reserve-pad"],
-  [data-testid="document-viewer-content"],
-  [data-testid="document-viewer-content"][data-scroll-hidden="true"] {
+  #main-content[data-reserve-transitioning="true"],
+  #main-content[data-reserve-transitioning="true"] [data-testid="mobile-composer-reserve-pad"],
+  [data-testid="document-viewer-content"][data-reserve-transitioning="true"] {
     transition: none;
   }
 }