cursedbelt 5.40.0 → 5.45.0

package/src/react/nav/TopBar.tsx

@@ -1,9 +1,12 @@
-import type { AnchorHTMLAttributes, ReactNode } from 'react';
+import type { AnchorHTMLAttributes, ElementType, ReactNode } from 'react';
 import { ScrollArea } from '../components/ScrollArea.js';
 import { Tooltip } from '../components/Tooltip.js';
+import { useMediaQuery } from '../hooks/useMediaQuery.js';
 import { useScrollEdgeFade } from '../hooks/useScrollEdgeFade.js';
 import { cn } from '../lib/cn.js';
+import { devWarnOnce } from '../lib/devWarn.js';
 import { TAP_TARGET_SQUARE } from '../lib/tapTarget.js';
+import { NAV_BADGE_TONE, type NavBadgeTone } from './navShared.js';
 
 /** What an `<a>` in the bar is handed — `href`, `onClick`, whatever the app's router needs. */
 export type TopBarLinkProps = Omit<
@@ -14,148 +17,317 @@ export type TopBarLinkProps = Omit<
 export interface TopBarItem {
   /** Stable key. */
   id: string;
-  /** The place's name. It is the accessible name and the hover hint — it is NOT painted. */
+  /** The place's name — painted beside the icon from 768px up, and always its accessible name. */
   label: string;
-  /** The glyph that IS the item. Required: an item without one cannot be drawn in this bar. */
+  /** The place's glyph. Alone below 768px (or in an `iconOnly` utility bar), beside the label above. */
   icon: ReactNode;
-  /** The place the user is in. Lit, and `aria-current="page"`. */
+  /** The place the user is in. Marked three ways, and `aria-current="page"`. */
   active?: boolean;
   /** Where it goes. A real link, so it still copies and middle-clicks. */
   href: string;
   /** `onClick` and whatever else the app's router needs on the `<a>`. */
   linkProps?: TopBarLinkProps;
   /**
-   * 🔴 The purposefully made exception: paint `label` beside the icon. Takes the REASON,
-   * not a boolean — the owner's rule (2026-09-25) is icons, not words, "unless there is a
-   * purposefully made exception", and a `showLabel` flag is an exception nobody had to make.
-   * Even then the words drop below `sm`, because a phone is where they overflowed.
+   * A count beside the label (unread, waiting), on the icon's corner where the icon stands alone.
+   * Clamped to 99+, and read as part of the place's name (`Duplicates · 7`).
    */
-  wordsBecause?: string;
+  badge?: number | string;
+  /** How the count reads — `alert` (default, red) or a plain fact. */
+  badgeTone?: NavBadgeTone;
+  /**
+   * The place exists but cannot work on THIS host: it stays visible, cannot be followed, and
+   * says why on hover — the owner's one-UI rule, never a hidden item. The reason, in a sentence.
+   */
+  unavailable?: string;
 }
 
 export interface TopBarProps {
   /** The app's mark. Its `label` is painted from `md` up and is the accessible name below it. */
   brand: { icon: ReactNode; label: string; href: string; linkProps?: TopBarLinkProps };
-  /** The places. Icons only — see {@link TopBarItem.wordsBecause} for the one way out. */
+  /** The places — 2 to 5 of them (NAV-3). Six or more belong in `AppShell`'s sectioned `SideNav`. */
   items: readonly TopBarItem[];
-  /** The trailing cluster: theme toggle, account menu. Never shrinks. */
+  /** The right zone: ⌘K, alerts, theme toggle, account. Locked — it never shrinks (NAV-1). */
   trailing?: ReactNode;
   /**
    * One control BEFORE the brand — a phone's way into the app's sidebar drawer (the owner's
    * music report, 2026-09-28: *"there is a large horizontal scrolling header row and no sidebar
-   * popout"*). Top-left is where Gmail, Linear and Slack put it on a phone, so a reader finds it
-   * without being told. Never shrinks. Render it only where there is a sidebar to open.
+   * popout"*). Top-left is where Gmail, Linear and Slack put it on a phone. Never shrinks.
    */
   leading?: ReactNode;
+  /**
+   * The center zone's content when it is NOT the places — a global search, a command trigger.
+   * Given together with `items`, the places render first and this follows them.
+   */
+  center?: ReactNode;
+  /**
+   * The header height (NAV-1): `roomy` 64px for media and consumer apps, `dense` 48px for a
+   * tool (station, desk, binary-server). Unset, it reads `--header-h`, which a `.cb-dense`
+   * scope already sets to 48px.
+   */
+  density?: 'roomy' | 'dense';
+  /**
+   * A UTILITY bar, not the app's router: icons only at every width, each with its tooltip.
+   * NAV-2 allows icons alone only in a utility cluster — a row of window controls, a
+   * viewer's tools — so this is the mode for those, never for an app's places.
+   */
+  iconOnly?: boolean;
+  /**
+   * Below 768px: `'icons'` (default) keeps the places as an icon strip in the header; `'none'`
+   * drops them, for a shell whose bottom `PlaceBar` already carries every place (NAV-14).
+   */
+  phonePlaces?: 'icons' | 'none';
+  /** SPA link component (e.g. react-router `Link`) — receives `to` and `href`. Default `<a>`. */
+  linkComponent?: ElementType;
   /** The nav landmark's name. Default `'Places'`. */
   navLabel?: string;
   className?: string;
 }
 
 /**
- * THE top bar: brand, places, trailing controls — one row that can never be wider than the
- * screen.
+ * THE top bar: three zones on one midline — brand, places, utilities — in a row that can
+ * never be wider than the screen.
  *
- * ── Why it exists (owner, 2026-09-25) ───────────────────────────────────────────────────
- * *"the music app header on iphone goes off the right side of the screen. It should use
- * icons instead of words and it should not be allowed to make the screen have a wide
- * scrollbar … cb should enforce this via a top bar component so each app cannot do it wrong
- * with separately made components."* Every app had hand-rolled its own `<header><nav>`, and
- * music's — "♪ Music · Library · Visualize · YouTube · Add music · Downloads" plus a theme
- * toggle and an avatar — was ~560px of words on a 390px phone, so the whole page scrolled
- * sideways.
- *
- * Two properties are built in rather than asked for:
- *   · **Icons, not words.** An item cannot be declared without an icon, and its label is
- *     the accessible name + hover hint, never painted — unless `wordsBecause` says why.
- *   · **It cannot widen the page.** The row is `min-w-0 max-w-full`; the places take the
- *     remaining width and, if a phone is narrower still, scroll INSIDE their own strip.
- *     Brand and trailing controls never shrink, so the account menu is always reachable.
+ * ── Why it is shaped like this ─────────────────────────────────────────────────────────
+ * It was born (owner, 2026-09-25) from music's header running off a 390px phone, and the
+ * fix then was *"icons instead of words"*. The owner's 2026-10-01 review reversed the words
+ * half: thirteen naked icons is mystery-meat navigation (`docs/design/README.md`, "Settled
+ * conflicts" #1). So now (`docs/design/shell-and-navigation.md`):
+ *   · **Destinations have words** (NAV-2) — icon plus label from 768px up. Icons alone only
+ *     below 768px, or in an `iconOnly` utility bar.
+ *   · **Three zones, one height** (NAV-1) — `--header-h` (64/48px), every item on one
+ *     midline, a 1px bottom border and no shadow. Left and right are locked; when space
+ *     runs out the center gives way, scrolling INSIDE its own strip, so the page never
+ *     scrolls sideways and the account menu is always reachable.
+ *   · **The active place is unmistakable** (NAV-6) — a 3px accent bar on the header-side
+ *     edge, a tinted background and foreground (not muted) text. Never color alone.
  *
  * `guardrails no-raw-nav` is the other half: a hand-rolled `<nav>` in app source fails the
  * app's gate, so the next header is this one.
  */
-export function TopBar({ brand, items, trailing, leading, navLabel = 'Places', className }: TopBarProps) {
-  const fade = useScrollEdgeFade();
+export function TopBar({
+  brand,
+  items,
+  trailing,
+  leading,
+  center,
+  density,
+  iconOnly = false,
+  phonePlaces = 'icons',
+  linkComponent,
+  navLabel = 'Places',
+  className,
+}: TopBarProps) {
+  if (!iconOnly && items.length > 5) {
+    devWarnOnce(
+      `TopBar:too-many:${brand.label}`,
+      `cursedbelt: <TopBar> "${brand.label}" puts ${items.length} places in the header. NAV-3 caps a top bar at 5 — ` +
+        'pass the places to AppShell as a NavigationModel with sections, and it renders a SideNav.',
+    );
+  }
+  const hasPlaces = items.length > 0;
   return (
     <header
       data-cb-topbar=''
-      className={cn('flex w-full min-w-0 max-w-full items-center gap-2 px-3 py-1.5 md:gap-3 md:px-6', className)}
+      data-cb-density={density}
+      className={cn(
+        'flex w-full min-w-0 max-w-full shrink-0 items-center gap-2 border-b border-border px-3 md:gap-4 md:px-6',
+        density === 'dense'
+          ? 'h-[var(--header-h-dense)]'
+          : density === 'roomy'
+            ? 'h-[var(--header-h-roomy)]'
+            : 'h-[var(--header-h)]',
+        className,
+      )}
     >
-      {leading ? <div className='flex shrink-0 items-center'>{leading}</div> : null}
-      <a
-        {...brand.linkProps}
-        href={brand.href}
-        aria-label={brand.label}
-        data-cb-topbar-brand=''
-        className={cn(
-          'flex shrink-0 items-center gap-2 rounded-md px-1.5 py-1 font-semibold text-foreground',
-          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
-          TAP_TARGET_SQUARE,
-          'md:pointer-coarse:w-auto',
-        )}
-      >
-        <span aria-hidden='true' className='grid size-6 place-items-center [&_svg]:size-5'>
-          {brand.icon}
-        </span>
-        <span aria-hidden='true' className='hidden md:inline'>
-          {brand.label}
-        </span>
-      </a>
-
-      <nav aria-label={navLabel} data-cb-topbar-nav='' className='min-w-0 flex-1' style={fade.maskStyle}>
-        {/* The places scroll INSIDE their own strip, so the page never does — with the
-            belt's one edge-fade cue saying there is more, as TagStrip and DataTable do. */}
-        <ScrollArea
-          axis='x'
-          space='none'
-          safeArea={false}
-          scrollRef={fade.ref}
-          onScroll={fade.onScroll}
-          className='w-full [scrollbar-width:none] [&::-webkit-scrollbar]:hidden'
+      {/* ── Left zone: locked ─────────────────────────────────────────────── */}
+      <div data-cb-topbar-zone='left' className='flex shrink-0 items-center gap-2'>
+        {leading ? <div className='flex shrink-0 items-center'>{leading}</div> : null}
+        <a
+          {...brand.linkProps}
+          href={brand.href}
+          aria-label={brand.label}
+          data-cb-topbar-brand=''
+          className={cn(
+            'flex shrink-0 items-center gap-2 rounded-md px-1.5 py-1 font-semibold text-foreground',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+            TAP_TARGET_SQUARE,
+            'md:pointer-coarse:w-auto',
+          )}
         >
-          <div className='flex w-max items-center gap-1'>
-            {items.map((item) => (
-              <TopBarLink key={item.id} item={item} />
-            ))}
-          </div>
-        </ScrollArea>
-      </nav>
+          <span aria-hidden='true' className='grid size-6 place-items-center [&_svg]:size-5'>
+            {brand.icon}
+          </span>
+          <span aria-hidden='true' className='hidden md:inline'>
+            {brand.label}
+          </span>
+        </a>
+      </div>
 
-      {trailing ? <div className='flex shrink-0 items-center gap-1'>{trailing}</div> : null}
+      {/* ── Center zone: fluid, gives way first ───────────────────────────── */}
+      <div data-cb-topbar-zone='center' className='flex h-full min-w-0 flex-1 items-center justify-center gap-3'>
+        {hasPlaces ? (
+          <TopBarPlaces
+            items={items}
+            iconOnly={iconOnly}
+            phonePlaces={phonePlaces}
+            linkComponent={linkComponent}
+            navLabel={navLabel}
+          />
+        ) : null}
+        {center ? <div className='flex min-w-0 flex-1 items-center justify-center'>{center}</div> : null}
+      </div>
+
+      {/* ── Right zone: locked, never shrinks ─────────────────────────────── */}
+      {trailing ? (
+        <div data-cb-topbar-zone='right' className='flex shrink-0 items-center gap-1'>
+          {trailing}
+        </div>
+      ) : null}
     </header>
   );
 }
 
-function TopBarLink({ item }: { item: TopBarItem }) {
-  const words = Boolean(item.wordsBecause?.trim());
+/** NAV-2's line: from here up a router's places show their words. */
+const WIDE_QUERY = '(min-width: 768px)';
+
+export interface TopBarPlacesProps
+  extends Pick<TopBarProps, 'items' | 'iconOnly' | 'phonePlaces' | 'linkComponent' | 'navLabel'> {}
+
+/**
+ * The center zone's places on their own — `TopBar` draws them, and so does `AppShell`'s
+ * header for a 2–5-place app (NAV-3). One strip, so the two can never drift.
+ */
+export function TopBarPlaces({
+  items,
+  iconOnly = false,
+  phonePlaces = 'icons',
+  linkComponent,
+  navLabel = 'Places',
+}: TopBarPlacesProps) {
+  const fade = useScrollEdgeFade();
+  const wide = useMediaQuery(WIDE_QUERY);
   return (
-    <Tooltip content={item.label} side='bottom'>
-      <a
-        {...item.linkProps}
-        href={item.href}
-        aria-label={item.label}
-        aria-current={item.active ? 'page' : undefined}
-        data-active={item.active ? '' : undefined}
-        className={cn(
-          'relative flex h-9 min-w-9 shrink-0 items-center justify-center gap-2 rounded-md px-2 transition-colors',
-          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
-          TAP_TARGET_SQUARE,
-          words && 'sm:pointer-coarse:w-auto',
-          item.active
-            ? 'bg-muted text-foreground'
-            : 'text-muted-foreground hover:bg-muted hover:text-foreground',
-        )}
+    <nav
+      aria-label={navLabel}
+      data-cb-topbar-nav=''
+      // The design audit's NAV-2 check reads `data-cb-primary-nav`: a router must show its
+      // words at ≥768px. A utility bar is not a router, so it is marked as one instead.
+      data-cb-primary-nav={iconOnly ? undefined : ''}
+      data-cb-nav-utility={iconOnly ? '' : undefined}
+      className={cn('h-full min-w-0', phonePlaces === 'none' && !iconOnly && 'max-md:hidden')}
+      style={fade.maskStyle}
+    >
+      {/* The places scroll INSIDE their own strip, so the page never does — with the
+          belt's one edge-fade cue saying there is more, as TagStrip and DataTable do. */}
+      <ScrollArea
+        axis='x'
+        space='none'
+        safeArea={false}
+        scrollRef={fade.ref}
+        onScroll={fade.onScroll}
+        className='h-full w-full [scrollbar-width:none] [&::-webkit-scrollbar]:hidden'
       >
-        <span aria-hidden='true' className='grid size-5 place-items-center [&_svg]:size-5'>
-          {item.icon}
+        <div className='flex h-full w-max items-center gap-1'>
+          {items.map((item) => (
+            <TopBarLink
+              key={item.id}
+              item={item}
+              hint={iconOnly || !wide}
+              iconOnly={iconOnly}
+              linkComponent={linkComponent}
+            />
+          ))}
+        </div>
+      </ScrollArea>
+    </nav>
+  );
+}
+
+function TopBarLink({
+  item,
+  hint,
+  iconOnly,
+  linkComponent,
+}: {
+  item: TopBarItem;
+  /** The glyph stands alone, so it carries a hover hint naming it. */
+  hint: boolean;
+  iconOnly: boolean;
+  linkComponent?: ElementType;
+}) {
+  const Link: ElementType = item.unavailable ? 'span' : (linkComponent ?? 'a');
+  const showBadge = item.badge != null && item.badge !== 0;
+  const badgeText = typeof item.badge === 'number' && item.badge > 99 ? '99+' : item.badge;
+  const target = item.unavailable
+    ? // HTML has no disabled anchor: a span that still announces as the link it is.
+      { role: 'link', 'aria-disabled': 'true', tabIndex: 0 }
+    : { ...item.linkProps, ...(linkComponent ? { to: item.href } : {}), href: item.href };
+  const link = (
+    <Link
+      {...target}
+      // The count is part of the name, so a screen reader hears what the eye sees.
+      aria-label={showBadge ? `${item.label} · ${badgeText}` : item.label}
+      aria-current={item.active ? 'page' : undefined}
+      data-active={item.active ? '' : undefined}
+      data-cb-nav-item=''
+      className={cn(
+        'relative flex h-9 min-w-9 shrink-0 items-center justify-center gap-2 rounded-md px-2 transition-colors',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        TAP_TARGET_SQUARE,
+        !iconOnly && 'md:px-3 md:pointer-coarse:w-auto',
+        item.unavailable && 'opacity-55',
+        item.active
+          ? 'bg-accent/10 text-foreground'
+          : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+      )}
+    >
+      {/* NAV-6's leading edge for a horizontal bar is the one facing the page: the bottom. */}
+      {item.active ? (
+        <span
+          aria-hidden='true'
+          data-cb-active-indicator=''
+          className='absolute inset-x-2 bottom-0 h-[var(--indicator-w)] rounded-full bg-accent-solid'
+        />
+      ) : null}
+      <span aria-hidden='true' className='grid size-5 place-items-center [&_svg]:size-5'>
+        {item.icon}
+      </span>
+      {iconOnly ? null : (
+        <span aria-hidden='true' className='hidden whitespace-nowrap text-sm font-medium md:inline'>
+          {item.label}
         </span>
-        {words ? (
-          <span aria-hidden='true' className='hidden text-sm font-medium sm:inline'>
-            {item.label}
-          </span>
-        ) : null}
-      </a>
+      )}
+      {showBadge ? (
+        <span
+          aria-hidden='true'
+          data-cb-nav-badge=''
+          className={cn(
+            'rounded-full px-1.5 py-0.5 text-xs font-bold leading-none',
+            NAV_BADGE_TONE[item.badgeTone ?? 'alert'],
+            // Where the glyph stands alone the count rides on its corner — a pill beside it
+            // would crowd the strip, and hiding it would hide the one figure the reader goes by.
+            iconOnly ? 'absolute -top-0.5 -right-0.5' : 'max-md:absolute max-md:-top-0.5 max-md:-right-0.5',
+          )}
+        >
+          {badgeText}
+        </span>
+      ) : null}
+    </Link>
+  );
+  if (item.unavailable) {
+    return (
+      <Tooltip content={`${item.label} — not available here. ${item.unavailable}`} side='bottom' multiline>
+        {link}
+      </Tooltip>
+    );
+  }
+  // The hover hint is only for a glyph standing alone: in a utility bar always, and below
+  // 768px in a router. Above it the word is painted, and a tooltip repeating it is noise.
+  return hint ? (
+    <Tooltip content={item.label} side='bottom'>
+      {link}
     </Tooltip>
+  ) : (
+    link
   );
 }

package/src/react/nav/index.ts

@@ -71,4 +71,11 @@ export {
   searchOptionId,
 } from './SearchResults.js';
 export { SideNav, type SideNavProps } from './SideNav.js';
-export { TopBar, type TopBarItem, type TopBarLinkProps, type TopBarProps } from './TopBar.js';
+export {
+  TopBar,
+  type TopBarItem,
+  type TopBarLinkProps,
+  TopBarPlaces,
+  type TopBarPlacesProps,
+  type TopBarProps,
+} from './TopBar.js';

package/src/react/nav/nav.spec.tsx

@@ -67,10 +67,54 @@ describe('SideNav', () => {
     const { container } = render(
       <SideNav model={model} activeHref='/games/fractal' onNavigate={() => {}} />,
     );
-    const rows = qa(container, '[data-cb-sidenav] a');
+    const rows = qa(container, '[data-cb-sidenav] a').filter((a) => !a.closest('[data-cb-sidenav-children]'));
     expect(rows.map((r) => text(r))).toEqual(['Today', 'Play', 'Tools', 'Admin']);
+    // /games/fractal lives within /games, and IS its Fractal item — the item is the page.
     const active = qa(container, '[data-cb-sidenav] a[aria-current="page"]');
-    expect(active.map((r) => text(r))).toEqual(['Play']); // /games/fractal lives within /games
+    expect(active.map((r) => text(r))).toEqual(['Fractal']);
+  });
+
+  test('NAV-7: the active place shows its items beneath it, each label indented under the parent label', () => {
+    const { container } = render(<SideNav model={model} activeHref='/games' onNavigate={() => {}} />);
+    const children = qa(container, '[data-cb-sidenav-children] a');
+    expect(children.map(text)).toEqual(['Fractal', 'Comet']);
+    // The parent row is px-3 + a 20px icon + gap-3 = 44px to its label; the child pads 44px.
+    const parent = qa(container, '[data-cb-sidenav] a').find((a) => text(a) === 'Play') as HTMLElement;
+    expect(parent.className).toContain('px-3');
+    expect(parent.className).toContain('gap-3');
+    for (const child of children) expect(child.className).toContain('pl-11');
+    // Only the active place expands; the icon rail never does.
+    cleanup();
+    const rail = render(<SideNav model={model} activeHref='/games' collapsed onNavigate={() => {}} />);
+    expect(qa(rail.container, '[data-cb-sidenav-children]')).toHaveLength(0);
+    cleanup();
+    const off = render(<SideNav model={model} activeHref='/games' expandActive={false} onNavigate={() => {}} />);
+    expect(qa(off.container, '[data-cb-sidenav-children]')).toHaveLength(0);
+  });
+
+  test('NAV-13: the footer is 12px muted under a rule — and the 64px icon rail leaves it out', () => {
+    const { container } = render(<SideNav model={model} footer={<span>v1.2.3</span>} onNavigate={() => {}} />);
+    const footer = container.querySelector('[data-cb-sidenav-footer]') as HTMLElement;
+    expect(footer.textContent).toBe('v1.2.3');
+    expect(footer.className).toContain('text-xs');
+    expect(footer.className).toContain('text-muted-foreground');
+    expect(footer.className).toContain('border-t');
+    cleanup();
+    const rail = render(<SideNav model={model} collapsed footer={<span>v1.2.3</span>} onNavigate={() => {}} />);
+    expect(rail.container.querySelector('[data-cb-sidenav-footer]')).toBeNull();
+  });
+
+  test('NAV-6: the current place is marked by a bar, a tint and a foreground label — never color alone', () => {
+    const { container } = render(<SideNav model={model} activeHref='/tools' onNavigate={() => {}} />);
+    const links = qa(container, '[data-cb-sidenav] a');
+    const active = links.find((a) => text(a) === 'Tools') as HTMLElement;
+    expect(active.getAttribute('aria-current')).toBe('page');
+    expect(active.querySelector('[data-cb-active-indicator]')?.className).toContain('w-[var(--indicator-w)]');
+    expect(active.className).toContain('bg-accent/10');
+    expect(active.className).toContain('text-foreground');
+    const idle = links.find((a) => text(a) === 'Today') as HTMLElement;
+    expect(idle.querySelector('[data-cb-active-indicator]')).toBeNull();
+    expect(idle.className).toContain('text-muted-foreground');
   });
 
   test('a role gate hides the gated domain', () => {

package/src/react/nav/navShared.tsx

@@ -7,8 +7,8 @@
 // nav rendered zero real anchors, so ctrl/cmd/middle-click "open in new tab"
 // and link-aware a11y/crawling tooling saw an empty nav).
 
-import type { CSSProperties, ElementType, ReactNode } from 'react';
-import { normalizeNavPath } from 'cursedbelt-core/navigation';
+import type { CSSProperties, ElementType, MouseEvent, ReactNode } from 'react';
+import { type NavDomain, normalizeNavPath } from 'cursedbelt-core/navigation';
 import { Tooltip } from '../components/Tooltip.js';
 
 /** Maps a model icon *name* to a node. Apps wire their icon set (e.g. lucide). */
@@ -165,6 +165,27 @@ export function isPathWithin(path: string, activeHref: string | undefined): bool
   return a === p || a.startsWith(`${p}/`);
 }
 
+/** A place is active when the route is its landing or lives within one of its items. */
+export function isDomainActive(domain: NavDomain, activeHref: string | undefined): boolean {
+  if (isPathWithin(domain.path, activeHref)) return true;
+  return domain.groups.some((g) => g.items.some((it) => isPathWithin(it.path, activeHref)));
+}
+
+/**
+ * The click a plain `<a href>` needs to route client-side through `onNavigate` — the same
+ * rule as {@link NavLink}: a plain left-click is intercepted, a modifier or middle click is
+ * left to the browser so "open in new tab" still works.
+ */
+export function routeClick(path: string, onNavigate: ((path: string) => void) | undefined) {
+  return (event: MouseEvent<HTMLAnchorElement>) => {
+    if (!onNavigate) return;
+    if (event.defaultPrevented || event.button !== 0) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    event.preventDefault();
+    onNavigate(path);
+  };
+}
+
 /** Resolve a model icon name to a node via the app's resolver (or nothing). */
 export function renderIcon(
   resolveIcon: IconResolver | undefined,

package/src/react/notifications/NotificationFeed.tsx

@@ -201,7 +201,7 @@ export function NotificationFeed({
   return (
     <div className={cn('flex flex-col', className)}>
       {/* Header */}
-      <div className='flex items-center justify-between border-b border-border px-4 py-2.5'>
+      <div className='flex items-center justify-between border-b border-border px-4 py-2'>
         <span className='text-sm font-semibold text-foreground'>
           Notifications
           {unreadCount > 0 && (
@@ -283,7 +283,7 @@ export function NotificationFeed({
 
 function GroupLabel({ label }: { label: string }) {
   return (
-    <p className='cb-meta-label px-4 pb-1 pt-2.5'>{label}</p>
+    <p className='cb-meta-label px-4 pb-1 pt-3'>{label}</p>
   );
 }
 

package/src/react/palette/Command.tsx

@@ -67,7 +67,7 @@ export function CommandInput({ className, trailing, ...props }: CommandInputProp
 /** The scrolling results region (keyboard-safe via `ScrollArea`), capped at 60dvh. */
 export function CommandList({
   className,
-  maxHeightClassName = 'max-h-[60dvh]',
+  maxHeightClassName = 'max-h-[var(--palette-max-h)]',
   ...props
 }: ComponentPropsWithoutRef<typeof CmdkList> & { maxHeightClassName?: string }) {
   return (

package/src/react/palette/CommandPalette.spec.tsx

@@ -4,6 +4,7 @@ import type { GateFn, NavGate, NavigationModel } from 'cursedbelt-core/navigatio
 import { shortcutRegistry } from 'cursedbelt-core/palette/shortcut-registry';
 import type { SearchResultGroup } from '../nav/SearchResults.js';
 import { CommandPalette } from './CommandPalette.js';
+import { PALETTE_RECENT_STORAGE_KEY } from './commandSources.js';
 import { useCommandPalette } from './useCommandPalette.js';
 
 afterEach(() => {
@@ -369,3 +370,33 @@ describe('registered shortcuts', () => {
     expect(onShortcut).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('contributed sources — recent items first (OVL-8)', () => {
+  test('an item run from the palette leads its group the next time it opens cold', () => {
+    localStorage.removeItem(PALETTE_RECENT_STORAGE_KEY);
+    const sources = [
+      {
+        group: 'Requests',
+        items: [
+          { id: 'a', label: 'Alpha request', onSelect: () => {} },
+          { id: 'b', label: 'Beta request', onSelect: () => {} },
+          { id: 'c', label: 'Gamma request', onSelect: () => {} },
+        ],
+      },
+    ];
+    const labels = () =>
+      Array.from(document.querySelectorAll('[cmdk-item]'))
+        .map((el) => el.textContent ?? '')
+        .filter((t) => t.endsWith('request'));
+    const view = (open: boolean) => (
+      <CommandPalette model={model} onNavigate={() => {}} shortcuts={[]} sources={sources} open={open} onOpenChange={() => {}} />
+    );
+    const { rerender } = render(view(true));
+    expect(labels()).toEqual(['Alpha request', 'Beta request', 'Gamma request']);
+    fireEvent.click(screen.getByText('Gamma request'));
+    rerender(view(false));
+    rerender(view(true));
+    expect(labels()).toEqual(['Gamma request', 'Alpha request', 'Beta request']);
+    localStorage.removeItem(PALETTE_RECENT_STORAGE_KEY);
+  });
+});