feat(navigation): standardise multi-page mode menus in the header

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

@@ -999,7 +999,8 @@ function GlobalStandaloneSearchShellBody({
               section ids. Specifiers and Formulation keep their existing local
               Subnav (SpecifierSubnav / FormulationSubnav), so the shared mode bar
               is skipped for them to avoid a duplicate row on their workflow routes.
-              Rendered in normal flow (sticky={false}) so it never contends with
+              Mode navigation portals into the collapsing header; the "On this page"
+              bar renders in normal flow (sticky={false}) so it never contends with
               the universal collapsing header or page-flow search chrome.
             */}
             {!pendingModeNavigation && searchMode !== "specifiers" && searchMode !== "formulation" ? (
@@ -1008,7 +1009,6 @@ function GlobalStandaloneSearchShellBody({
                 pathname={pathname}
                 hasSubmittedSearch={hasSubmittedModeSearch}
                 searchParamString={searchParamString}
-                onSearch={() => inputRef.current?.focus({ preventScroll: true })}
                 sticky={false}
               />
             ) : null}

src/components/formulation/formulation-ui.tsx

@@ -1,8 +1,8 @@
-import Link from "next/link";
 import type { ReactNode } from "react";
 import { Info, Network, ShieldCheck } from "lucide-react";
 
 import { InformationPageBreadcrumbs, InformationPageShell } from "@/components/information-page-shell";
+import { RegistryModeNav } from "@/components/mode-nav/registry-mode-nav";
 import { cn, eyebrowText } from "@/components/ui-primitives";
 
 export const formulationCard =
@@ -17,36 +17,7 @@ export function FormulationBreadcrumbs({ current }: { current?: string }) {
 }
 
 export function FormulationSubnav({ active }: { active: "search" | "builder" | "compare" | "map" }) {
-  const items = [
-    { id: "search" as const, label: "Find mechanisms", shortLabel: "Find", href: "/formulation" },
-    { id: "builder" as const, label: "Build formulation", shortLabel: "Build", href: "/formulation/builder" },
-    { id: "compare" as const, label: "Compare", shortLabel: "Compare", href: "/formulation/compare" },
-    { id: "map" as const, label: "Mechanism map", shortLabel: "Map", href: "/formulation/map" },
-  ];
-
-  return (
-    <nav
-      aria-label="Formulation tools"
-      className="polished-scroll flex max-w-full gap-1 overflow-x-auto rounded-lg border border-[color:var(--border)] bg-[color:var(--surface-raised)] p-1 shadow-[var(--shadow-inset)]"
-    >
-      {items.map((item) => (
-        <Link
-          key={item.id}
-          href={item.href}
-          aria-current={active === item.id ? "page" : undefined}
-          className={cn(
-            "inline-flex min-h-tap shrink-0 items-center justify-center rounded-md px-3 text-xs font-bold transition focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)] sm:text-sm",
-            active === item.id
-              ? "bg-[color:var(--clinical-accent)] text-[color:var(--clinical-accent-contrast)] shadow-[var(--shadow-tight)]"
-              : "text-[color:var(--text-muted)] hover:bg-[color:var(--surface)] hover:text-[color:var(--text)]",
-          )}
-        >
-          <span className="sm:hidden">{item.shortLabel}</span>
-          <span className="hidden sm:inline">{item.label}</span>
-        </Link>
-      ))}
-    </nav>
-  );
+  return <RegistryModeNav modeId="formulation" activeId={active} />;
 }
 
 export function MechanismDomainChips({ values, limit }: { values: string[]; limit?: number }) {

src/components/mode-nav/mode-nav-portal.tsx

@@ -25,11 +25,10 @@ import { phoneHeaderCollapseAddonSlotId } from "@/lib/mode-home-composer";
  * Falls back to normal flow when no host exists — routes rendered without the
  * universal header, and the server pass — so navigation is never lost.
  *
- * Slot ownership: the addon slot holds ONE page-owned header. `DocumentViewer`
- * and the differentials detail page already claim it on phones, so a mode whose
- * routes include those pages must not also mount a bar there. `ModeNav` renders
- * nothing below two destinations, which is what keeps those modes clear today;
- * `tests/mode-nav-contract.test.ts` fails if that stops being true.
+ * Slot ownership: the addon slot holds ONE page-owned header. Document and
+ * detail-page owners claim it only on routes where the shared shell suppresses
+ * ModeNav first; one-destination modes also render nothing below the two-item
+ * minimum. Contract and route-level tests fail if those ownership gates drift.
  */
 export function ModeNavHeaderPortal({ children }: { children: ReactNode }) {
   const [host, setHost] = useState<HTMLElement | null>(null);

src/components/mode-nav/registry-mode-nav.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import { FileText, GitCompareArrows, ListChecks, Network, Search, type LucideIcon } from "lucide-react";
+
+import { ModeNav, type ModeNavItem } from "@/components/mode-nav/mode-nav";
+import { appModeDefinition, type AppModeId } from "@/lib/app-modes";
+import { modeSecondaryNavigationEntries, modeSecondaryNavigationHref } from "@/lib/mode-secondary-navigation";
+
+const iconByItemId: Record<string, LucideIcon> = {
+  search: Search,
+  diagnoses: FileText,
+  compare: GitCompareArrows,
+  builder: ListChecks,
+  map: Network,
+};
+
+/**
+ * Adapts the canonical route registry to the universal header-integrated mode
+ * navigation. Keeping this mapping in one component prevents the page shell,
+ * Specifiers, and Formulation from drifting onto different labels or URLs.
+ */
+export function RegistryModeNav({
+  modeId,
+  activeId,
+  searchParamString = "",
+}: {
+  modeId: AppModeId;
+  activeId: string;
+  searchParamString?: string;
+}) {
+  const currentSearchParams = new URLSearchParams(searchParamString);
+  const items = modeSecondaryNavigationEntries(modeId).flatMap<ModeNavItem>((entry) => {
+    if (!entry.href) return [];
+    return [
+      {
+        id: entry.id,
+        label: entry.label,
+        href: modeSecondaryNavigationHref({
+          modeId,
+          itemId: entry.id,
+          href: entry.href,
+          currentSearchParams,
+        }),
+        icon: iconByItemId[entry.id] ?? FileText,
+      },
+    ];
+  });
+
+  return <ModeNav items={items} label={`${appModeDefinition(modeId).label} pages`} activeId={activeId} />;
+}

src/components/page-secondary-navigation.tsx

@@ -1,21 +1,13 @@
 "use client";
 
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useState } from "react";
 
 import { isDocumentViewerOwnedRoute } from "@/components/clinical-dashboard/mobile-composer-reserve";
-import {
-  SecondaryNavigation,
-  type SecondaryNavigationItem,
-  type SecondaryNavigationSectionItem,
-} from "@/components/secondary-navigation";
-import { appModeDefinition, type AppModeId } from "@/lib/app-modes";
+import { RegistryModeNav } from "@/components/mode-nav/registry-mode-nav";
+import { SecondaryNavigation, type SecondaryNavigationSectionItem } from "@/components/secondary-navigation";
+import type { AppModeId } from "@/lib/app-modes";
 import { isInformationPage } from "@/lib/information-pages";
-import {
-  activeModeSecondaryNavigationId,
-  isModeSecondaryNavigationRoute,
-  modeSecondaryNavigationEntries,
-  modeSecondaryNavigationHref,
-} from "@/lib/mode-secondary-navigation";
+import { activeModeSecondaryNavigationId, isModeSecondaryNavigationRoute } from "@/lib/mode-secondary-navigation";
 
 export type InformationPageSectionDefinition = {
   id: string;
@@ -152,15 +144,19 @@ export function informationPageSectionDefinitions(pathname: string): readonly In
   if (
     pathname.startsWith("/specifiers/") &&
     !["/specifiers/builder", "/specifiers/compare", "/specifiers/map"].includes(pathname)
-  )
+  ) {
     return specifierSections;
+  }
   if (
     pathname.startsWith("/formulation/") &&
     !["/formulation/builder", "/formulation/compare", "/formulation/map"].includes(pathname)
-  )
+  ) {
     return formulationSections;
+  }
   if (pathname.startsWith("/differentials/presentations/")) return differentialPresentationSections;
-  if (pathname.endsWith("/differentials") && pathname.startsWith("/dsm/diagnoses/")) return dsmDifferentialSections;
+  if (pathname.endsWith("/differentials") && pathname.startsWith("/dsm/diagnoses/")) {
+    return dsmDifferentialSections;
+  }
   if (pathname.startsWith("/dsm/diagnoses/")) return dsmDiagnosisSections;
   if (pathname.startsWith("/documents/") && pathname !== "/documents/search") return documentSections;
   return [];
@@ -248,57 +244,28 @@ export function PageSecondaryNavigation({
   modeId,
   pathname,
   hasSubmittedSearch,
-  onSearch,
   /**
    * Bridged query string from GlobalStandaloneSearchShellBody. Must not call
    * useSearchParams here — that reintroduces a nested Suspense boundary under
    * the standalone shell body (search-chrome invariant 17).
    */
   searchParamString = "",
+  /**
+   * Only reaches the "On this page" bar. The mode bar is the header-integrated
+   * `ModeNav`, which portals into the collapsing header and owns its own
+   * placement, so no positioning prop is accepted for it.
+   */
   sticky = true,
-  stickyTop,
 }: {
   modeId: AppModeId;
   pathname: string;
   hasSubmittedSearch: boolean;
-  onSearch: () => void;
   searchParamString?: string;
   sticky?: boolean;
-  stickyTop?: number | string;
 }) {
   const informationDefinitions = informationPageSectionDefinitions(pathname);
   const locallyOwnedInformationNavigation = hasLocalInformationPageNavigation(pathname);
   const activeId = activeModeSecondaryNavigationId(modeId, pathname);
-  const modeLabel = appModeDefinition(modeId).label;
-  const modeAriaLabel = modeLabel.toLowerCase().endsWith("mode") ? modeLabel : `${modeLabel} mode`;
-  const modeItems = useMemo<SecondaryNavigationItem[]>(
-    () =>
-      modeSecondaryNavigationEntries(modeId).map((entry) =>
-        entry.href
-          ? {
-              kind: "route" as const,
-              id: entry.id,
-              label: entry.label,
-              shortLabel: entry.shortLabel,
-              href: modeSecondaryNavigationHref({
-                modeId,
-                itemId: entry.id,
-                href: entry.href,
-                currentSearchParams: new URLSearchParams(searchParamString),
-              }),
-              current: entry.id === activeId,
-            }
-          : {
-              kind: "action" as const,
-              id: entry.id,
-              label: entry.label,
-              shortLabel: entry.shortLabel,
-              onSelect: onSearch,
-              current: entry.id === activeId,
-            },
-      ),
-    [activeId, modeId, onSearch, searchParamString],
-  );
 
   // Therapy Compass owns both its workflow bindings and its dynamic detail
   // sections inside TcProvider; rendering the shell registry as well would
@@ -309,13 +276,5 @@ export function PageSecondaryNavigation({
     return <AvailableInformationPageNavigation definitions={informationDefinitions} sticky={sticky} />;
   }
   if (!isModeSecondaryNavigationRoute({ modeId, pathname, hasSubmittedSearch })) return null;
-  return (
-    <SecondaryNavigation
-      ariaLabel={modeAriaLabel}
-      items={modeItems}
-      activeId={activeId}
-      sticky={sticky}
-      stickyTop={stickyTop}
-    />
-  );
+  return <RegistryModeNav modeId={modeId} activeId={activeId} searchParamString={searchParamString} />;
 }

src/components/specifiers/specifier-ui.tsx

@@ -3,6 +3,7 @@ import type { ComponentType, CSSProperties, ReactNode } from "react";
 import { ArrowRight, CheckCircle2, ChevronsUpDown, Info, Minus, ShieldAlert, Tags } from "lucide-react";
 
 import { InformationPageBreadcrumbs, InformationPageShell } from "@/components/information-page-shell";
+import { RegistryModeNav } from "@/components/mode-nav/registry-mode-nav";
 import { cn, eyebrowText } from "@/components/ui-primitives";
 import type { SpecifierFamily, SpecifierRecord } from "@/lib/specifiers";
 import { specifierFamilies } from "@/lib/specifiers";
@@ -20,41 +21,7 @@ export function SpecifierBreadcrumbs({ current }: { current?: string }) {
 }
 
 export function SpecifierSubnav({ active }: { active: "search" | "builder" | "compare" | "map" }) {
-  const items = [
-    { id: "search" as const, label: "Find", shortLabel: "Find", href: "/specifiers" },
-    { id: "builder" as const, label: "Build wording", shortLabel: "Build", href: "/specifiers/builder" },
-    { id: "compare" as const, label: "Compare", shortLabel: "Compare", href: "/specifiers/compare" },
-    { id: "map" as const, label: "Map", shortLabel: "Map", href: "/specifiers/map" },
-  ];
-
-  return (
-    <nav
-      aria-label="Specifier tools"
-      className="polished-scroll flex max-w-full gap-1 overflow-x-auto rounded-lg border border-[color:var(--border)] bg-[color:var(--surface-raised)] p-1 shadow-[var(--shadow-inset)]"
-    >
-      {items.map((item) => (
-        <Link
-          key={item.id}
-          href={item.href}
-          aria-label={item.label}
-          aria-current={active === item.id ? "page" : undefined}
-          className={cn(
-            "inline-flex min-h-tap shrink-0 items-center justify-center rounded-md px-3 text-xs font-bold transition focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)] sm:text-sm",
-            active === item.id
-              ? "bg-[color:var(--clinical-accent)] text-[color:var(--clinical-accent-contrast)] shadow-[var(--shadow-tight)]"
-              : "text-[color:var(--text-muted)] hover:bg-[color:var(--surface)] hover:text-[color:var(--text)]",
-          )}
-        >
-          <span className="sm:hidden" aria-hidden>
-            {item.shortLabel}
-          </span>
-          <span className="hidden sm:inline" aria-hidden>
-            {item.label}
-          </span>
-        </Link>
-      ))}
-    </nav>
-  );
+  return <RegistryModeNav modeId="specifiers" activeId={active} />;
 }
 
 const familyChipBase =

src/lib/mode-secondary-navigation.ts

@@ -91,25 +91,42 @@ export function isModeSecondaryNavigationRoute(params: {
   hasSubmittedSearch: boolean;
 }): boolean {
   const { modeId, pathname, hasSubmittedSearch } = params;
+
+  // A one-destination mode has no meaningful secondary choice. Suppress it
+  // even after search submission rather than rendering a redundant one-item
+  // strip beneath the universal header.
+  if (modeSecondaryNavigationRegistry[modeId].length < 2) return false;
   if (hasSubmittedSearch) return true;
 
-  // /documents/search is the documents mode home (composer already visible); do
-  // not add a lone Search focus control until a query has been submitted.
-  if (modeId === "documents") return false;
   if (modeId === "differentials") {
-    return pathname === "/differentials/diagnoses" || pathname === "/differentials/presentations";
+    return (
+      pathname === "/differentials" ||
+      pathname === "/differentials/diagnoses" ||
+      pathname === "/differentials/presentations"
+    );
+  }
+  if (modeId === "dsm") {
+    return pathname === "/dsm" || pathname === "/dsm/search" || pathname === "/dsm/compare";
   }
-  if (modeId === "dsm") return pathname === "/dsm/search" || pathname === "/dsm/compare";
   if (modeId === "specifiers") {
-    return pathname === "/specifiers/builder" || pathname === "/specifiers/compare" || pathname === "/specifiers/map";
+    return (
+      pathname === "/specifiers" ||
+      pathname === "/specifiers/builder" ||
+      pathname === "/specifiers/compare" ||
+      pathname === "/specifiers/map"
+    );
   }
   if (modeId === "formulation") {
     return (
-      pathname === "/formulation/builder" || pathname === "/formulation/compare" || pathname === "/formulation/map"
+      pathname === "/formulation" ||
+      pathname === "/formulation/builder" ||
+      pathname === "/formulation/compare" ||
+      pathname === "/formulation/map"
     );
   }
-  if (modeId === "factsheets") return pathname === "/factsheets/search";
-  if (modeId === "therapy-compass") return pathname !== "/therapy-compass";
+  if (modeId === "therapy-compass") {
+    return pathname === "/therapy-compass" || pathname.startsWith("/therapy-compass/");
+  }
   return false;
 }
 
@@ -172,11 +189,12 @@ export function modeSecondaryNavigationHref(params: {
       currentSearchParams.get("b"),
       currentSearchParams.get("selected"),
     ]);
-    if (itemId === "builder")
+    if (itemId === "builder") {
       return navigationHrefWithParams(
         href,
         selections.map((value) => ["specifier", value] as const),
       );
+    }
     if (itemId === "compare") {
       return navigationHrefWithParams(
         href,
@@ -203,11 +221,12 @@ export function modeSecondaryNavigationHref(params: {
     ]);
     const template = currentSearchParams.get("template");
     const templateEntry: Array<readonly [string, string]> = template ? [["template", template]] : [];
-    if (itemId === "builder")
+    if (itemId === "builder") {
       return navigationHrefWithParams(href, [
         ...selections.map((value) => ["mechanism", value] as const),
         ...templateEntry,
       ]);
+    }
     if (itemId === "compare") {
       return navigationHrefWithParams(href, [
         ...selections.slice(0, 2).map((value, index) => [index === 0 ? "a" : "b", value] as const),