cursedbelt 5.40.0 → 5.45.0

package/src/react/components/AppShell.tsx

@@ -1,12 +1,24 @@
-import type { ElementType, ReactNode, Ref } from 'react';
-import type { GateFn, NavigationModel, NavPreferences } from 'cursedbelt-core/navigation';
+import { type ElementType, type ReactNode, type Ref, useLayoutEffect, useRef } from 'react';
+import {
+  allowAllGate,
+  deriveSideNavDomains,
+  type GateFn,
+  type NavigationModel,
+  type NavPreferences,
+} from 'cursedbelt-core/navigation';
 import { useKeyboardInset } from '../hooks/useKeyboardInset.js';
 import { cn } from '../lib/cn.js';
+import { devWarnOnce } from '../lib/devWarn.js';
 import { CommandBar } from '../nav/CommandBar.js';
-import type { IconResolver, NavBadgeTone } from '../nav/navShared.js';
+import { type IconResolver, isDomainActive, type NavBadgeTone, renderIcon, routeClick } from '../nav/navShared.js';
 import { PlaceBar } from '../nav/PlaceBar.js';
 import { SideNav } from '../nav/SideNav.js';
+import { TopBarPlaces } from '../nav/TopBar.js';
+import { CommandPalette } from '../palette/CommandPalette.js';
+import { CommandSourceProvider, useCommandSources } from '../palette/commandSources.js';
+import { useCommandPalette } from '../palette/useCommandPalette.js';
 import { AmbientBackdrop, type AmbientBackdropProps } from './AmbientBackdrop.js';
+import { BannerLane, type ShellBanner } from './BannerLane.js';
 import { ScrollArea, type ScrollAreaSpace } from './ScrollArea.js';
 
 export interface AppShellProps {
@@ -14,11 +26,15 @@ export interface AppShellProps {
   children: ReactNode;
 
   /**
-   * The navigation model — the single `navigationModel` registry generalized to the
-   * UX north-star's **small fixed place-set** (Today/Library/People/Calendar/Play +
-   * a role-gated Operate). The shell renders it as the slim desktop **place rail**
-   * (`SideNav`, md+) and the mobile capture-forward **`PlaceBar`** (below md) — never
-   * a 256px hub list and never a hamburger drawer. Omit for chromeless pages.
+   * The navigation model — the one registry every nav surface reads. The app passes it and
+   * the SHELL picks the pattern from the number of places (NAV-3):
+   *
+   * | places | ≥1024px | 768–1023px | <768px |
+   * |---|---|---|---|
+   * | 2–5 | labeled `TopBar` places in the header's center | same | `PlaceBar`, every place |
+   * | 6+  | `SideNav` with labeled sections, 240px | the 64px icon rail | `PlaceBar`, top 4 + More |
+   *
+   * Six or more places mount the ⌘K `CommandPalette` too (NAV-9). Omit for chromeless pages.
    */
   nav?: NavigationModel;
 
@@ -50,9 +66,34 @@ export interface AppShellProps {
   /** Brand slot — top-left of the command spine (logo / app name). */
   navHeader?: ReactNode;
 
-  /** Slot at the bottom of the desktop place rail (theme toggle, secondary links). */
+  /**
+   * The sidebar's footer (NAV-13): the version, `BuildFreshness` and a Settings link, set in
+   * 12px muted type. Only a 6+-place shell has a sidebar; a 2–5-place app keeps these in
+   * Settings → About.
+   */
   navFooter?: ReactNode;
 
+  /**
+   * App-wide conditions — a sign-in broke, the Mac is asleep, the app is offline — as the ONE
+   * banner lane between the header and the page (NAV-10). One line each; two or more collapse
+   * into "N problems · View". Never a card inside the page.
+   */
+  banners?: readonly ShellBanner[];
+
+  /**
+   * The header's height (NAV-1): `dense` 48px for a tool (station, desk, binary-server),
+   * `roomy` 64px for media and consumer apps. Unset, it reads `--header-h` (64px; 48px
+   * inside `.cb-dense`).
+   */
+  density?: 'roomy' | 'dense';
+
+  /**
+   * Mount the shell's own ⌘K `CommandPalette` — every place preloaded, plus whatever pages
+   * contribute through `useCommandSource`. `'auto'` (default) mounts it for 6+ places
+   * (NAV-9). Ignored when the app renders its own through `palette`.
+   */
+  commandPalette?: boolean | 'auto';
+
   /**
    * Universal capture (UX north-star §8.2) — wired to the command spine's capture
    * hero (desktop) and the `PlaceBar`'s raised center FAB (mobile). Capture is a
@@ -94,7 +135,7 @@ export interface AppShellProps {
    */
   palette?: ReactNode;
 
-  /** Max places in the mobile `PlaceBar` thumb zone (rest reachable via command). Default 5. */
+  /** Max places in the mobile `PlaceBar` thumb zone; past it, `max - 1` places + More. Default 5. */
   placeBarMax?: number;
 
   /** PlaceBar caption policy (`'active'` | `'all'`). Pass `'all'` when place names
@@ -127,52 +168,58 @@ export interface AppShellProps {
   className?: string;
 }
 
-// The desktop place rail is a *small spatial floor* (a handful of places), not the old
-// 256px hub list — slimmer + quiet, with the command spine carrying the second way to move.
-const RAIL_WIDTH = 'w-60'; // 240px
+/** NAV-3's line: up to this many places ride a labeled top bar; past it, a sectioned sidebar. */
+const TOP_BAR_MAX_PLACES = 5;
+/** Past this many places, a sidebar with no sections is a wall (NAV-3: ≤7 items a section). */
+const UNSECTIONED_MAX_PLACES = 7;
 
 /**
- * THE single application shell. One per app — reconciled to the UX north-star
- * (`cursedalchemy/UX_NORTH_STAR.md`, §§6–7, 10; reconciliation #311 + `SHELL.md`).
+ * THE single application shell. One per app — the frame every page sits in
+ * (`docs/design/shell-and-navigation.md`, NAV-1…NAV-14). The app passes ONE navigation
+ * model and the shell decides how to draw it, so no app can pick the wrong pattern:
  *
- * **What changed, and why** (the old form was kept by inertia and failed the §12
- * anti-anchoring gate, not preserved as optimal):
- * - The fixed **256px hub-list sidebar** → a slim, quiet **place rail** (the small
- *   fixed place-set is a defended spatial anchor; the *hub-list form* is not).
- * - The **hamburger → `translate-x` drawer** → the capture-forward **`PlaceBar`**: the
- *   place-set in the thumb zone around a raised center capture FAB (mobile is
- *   capture-forward, not tab-forward — §7).
- * - The buried, invisible ⌘K palette + no capture → the first-class **`CommandBar`
- *   spine**: a visible command/search field (the co-equal second way to move) + a
- *   capture hero (universal capture, §8.2).
- * - The avatar-in-nav → **account chrome** behind the avatar in the spine (not a door).
+ * - **2–5 places** → their labels in the header's center zone (NAV-2: destinations have
+ *   words from 768px up), every place in the `PlaceBar` on a phone.
+ * - **6+ places** → a 240px `SideNav` in labeled sections at ≥1024px, the 64px icon rail
+ *   at 768–1023px, the `PlaceBar` with the top 4 + More on a phone, and a ⌘K
+ *   `CommandPalette` preloaded with every place (NAV-9).
  *
- * What is *kept* (proven optimal, §11): the single `navigationModel` registry + its
- * coverage test (anti-drift substrate), per-user place prefs, badges, and the
- * keyboard-safe single `ScrollArea`. Capabilities preserved; form reimagined.
+ * Kept from the shell before it (owner teardowns 2026-07-15, the UX north-star): the single
+ * `navigationModel` registry and its coverage test, per-user place prefs, badges, universal
+ * capture (the spine's hero on desktop, the `PlaceBar` FAB on a phone), and the
+ * keyboard-safe single `ScrollArea`. No hamburger drawer, ever.
  *
  * Layout model:
  * ```
  *   <div h-dvh flex flex-col overflow-hidden>     ← dvh excludes the mobile URL bar
- *     <header />                                    ← brand + CommandBar spine + account
- *     <div flex min-h-0 grow>                       ← rail + content row
- *       <aside hidden md:flex w-60>                 ← slim place rail (SideNav, md+ only)
+ *     <header h-[--header-h]>                       ← left: brand · center: places or ⌘K field · right: account
+ *     <BannerLane />                                ← NAV-10, only when there is a banner
+ *     <div flex min-h-0 grow>                       ← sidebar + content row
+ *       <aside md:flex lg:hidden w-16 />            ← 6+ places: the icon rail
+ *       <aside lg:flex w-60 />                      ← 6+ places: the sectioned SideNav
  *       <main><ScrollArea>{children}</ScrollArea></main>  ← THE ONLY page scroll container
  *     </div>
  *     <div pb-[safe-area]>                          ← bottomDock + mobile PlaceBar
- *       {bottomDock}
- *       <PlaceBar md:hidden />                       ← capture-forward bottom bar
- *     </div>
  *   </div>
  * ```
  *
  * Keyboard model: `useKeyboardInset` (installed exactly once, here) writes
  * `--keyboard-inset` onto `<html>`; `ScrollArea` reads it via CSS `calc()`.
  */
-export function AppShell({
+export function AppShell(props: AppShellProps) {
+  // The provider sits ABOVE the shell, so a page anywhere in `children` can contribute to the
+  // palette the shell mounts, and the shell can read what they contributed.
+  return (
+    <CommandSourceProvider>
+      <Shell {...props} />
+    </CommandSourceProvider>
+  );
+}
+
+function Shell({
   children,
   nav,
-  navGate,
+  navGate = allowAllGate,
   activeHref,
   onNavigate,
   navLinkComponent,
@@ -183,6 +230,9 @@ export function AppShell({
   navBadgeTone,
   navHeader,
   navFooter,
+  banners,
+  density,
+  commandPalette = 'auto',
   onCapture,
   captureLabel,
   onOpenCommand,
@@ -201,16 +251,68 @@ export function AppShell({
 }: AppShellProps) {
   useKeyboardInset();
 
-  const showSpine = Boolean(navHeader || account || onOpenCommand || onCapture || commandBarExtra);
+  const places = nav ? deriveSideNavDomains(nav, navGate) : [];
+  const pattern: 'none' | 'top' | 'side' = !nav ? 'none' : places.length <= TOP_BAR_MAX_PLACES ? 'top' : 'side';
+  if (pattern === 'side' && places.length > UNSECTIONED_MAX_PLACES && !places.some((d) => d.section)) {
+    devWarnOnce(
+      'AppShell:unsectioned',
+      `cursedbelt: <AppShell> was given ${places.length} places and no sections. NAV-3 wants 2–5 labeled sections ` +
+        'of ≤7 places each — give each NavDomain a `section` ("Operate", "Insight", "Limits", "Records").',
+    );
+  }
+
+  // NAV-9: the shell's own palette, unless the app renders one.
+  const ownPalette = !palette && Boolean(nav) && (commandPalette === 'auto' ? pattern === 'side' : commandPalette);
+  const paletteControls = useCommandPalette({ enabled: ownPalette });
+  const sources = useCommandSources();
+  const openCommand = onOpenCommand ?? (ownPalette ? paletteControls.toggle : undefined);
+  const navigate = (path: string) => {
+    if (onNavigate) onNavigate(path);
+    else window.location.assign(path);
+  };
+
+  const showSpine = Boolean(nav || navHeader || account || openCommand || onCapture || commandBarExtra);
   const showBottom = Boolean(bottomDock || nav);
+  const bottomChromeRef = usePublishedBottomChrome(showBottom);
   // Chrome that lets the field through. The rails/spine keep their own directional
   // border either way — only the FILL changes, so the layout is byte-identical and
   // an app can flip `ambient` on and off without anything reflowing.
   const chrome = ambient ? 'cb-glass-chrome' : 'bg-background';
 
+  const commandBar = (
+    <CommandBar
+      // The search field is capped and centered: a 2000px-wide input reads as a form, not a
+      // header (Linear and GitHub cap theirs the same way).
+      className={pattern === 'top' ? 'shrink-0' : 'min-w-0 max-w-2xl flex-1'}
+      compact={pattern === 'top'}
+      onCapture={onCapture}
+      captureLabel={captureLabel}
+      // On mobile the PlaceBar FAB owns capture — don't duplicate it in the spine.
+      captureDesktopOnly={Boolean(nav)}
+      onOpenCommand={openCommand}
+      commandPlaceholder={commandLabel}
+      commandHint={commandHint}
+      extra={commandBarExtra}
+    />
+  );
+
+  const sideNavProps = {
+    model: nav as NavigationModel,
+    gate: navGate,
+    activeHref,
+    onNavigate,
+    linkComponent: navLinkComponent,
+    resolveIcon,
+    prefs: navPrefs,
+    badges: navBadges,
+    badgeTone: navBadgeTone,
+    footer: navFooter,
+  };
+
   return (
     <div
       data-cb-appshell=''
+      data-cb-nav-pattern={pattern}
       className={cn(
         'flex h-dvh flex-col overflow-hidden bg-background text-foreground',
         // `isolation: isolate` is load-bearing, not decoration: the blobs blend with
@@ -228,86 +330,89 @@ export function AppShell({
         <AmbientBackdrop position='absolute' {...(ambient === true ? {} : ambient)} />
       ) : null}
 
-      {/* ── Top spine: brand + command/capture + account ───────────────────── */}
+      {/* ── Header: three zones on one midline (NAV-1) ─────────────────────── */}
       {showSpine && (
         <header
           data-cb-appheader=''
+          data-cb-density={density}
           className={cn(
-            'relative z-30 flex shrink-0 items-center gap-3 border-b border-border px-3 py-2',
+            'relative z-30 flex shrink-0 items-center gap-3 border-b border-border px-3 md:px-6',
+            density === 'dense'
+              ? 'h-[var(--header-h-dense)]'
+              : density === 'roomy'
+                ? 'h-[var(--header-h-roomy)]'
+                : 'h-[var(--header-h)]',
             ambient && chrome,
           )}
         >
-          {navHeader && <div className='shrink-0'>{navHeader}</div>}
-          <CommandBar
-            className='min-w-0 flex-1'
-            onCapture={onCapture}
-            captureLabel={captureLabel}
-            // On mobile the PlaceBar FAB owns capture — don't duplicate it in the spine.
-            captureDesktopOnly={Boolean(nav)}
-            onOpenCommand={onOpenCommand}
-            commandPlaceholder={commandLabel}
-            commandHint={commandHint}
-            extra={commandBarExtra}
-          />
-          {account && (
-            <div data-cb-account='' className='shrink-0'>
-              {account}
+          <div data-cb-header-zone='left' className='flex shrink-0 items-center'>
+            {navHeader}
+          </div>
+          <div data-cb-header-zone='center' className='flex h-full min-w-0 flex-1 items-center justify-center'>
+            {pattern === 'top' ? (
+              <TopBarPlaces
+                // Below 768px the PlaceBar carries every place (NAV-14), so the header doesn't.
+                phonePlaces='none'
+                linkComponent={navLinkComponent}
+                items={places.map((d) => ({
+                  id: d.id,
+                  label: d.label,
+                  icon: renderIcon(resolveIcon, d.icon),
+                  href: d.path,
+                  active: isDomainActive(d, activeHref),
+                  badge: navBadges?.[d.id],
+                  badgeTone: navBadgeTone,
+                  unavailable: d.hostLimit && d.hostLimit.navigable !== true ? d.hostLimit.reason : undefined,
+                  linkProps: navLinkComponent ? undefined : { onClick: routeClick(d.path, onNavigate) },
+                }))}
+              />
+            ) : (
+              commandBar
+            )}
+          </div>
+          {/* The right zone is locked: it never shrinks (NAV-1). */}
+          {(pattern === 'top' || account) && (
+            <div data-cb-header-zone='right' className='flex shrink-0 items-center gap-2'>
+              {pattern === 'top' ? commandBar : null}
+              {account && (
+                <div data-cb-account='' className='shrink-0'>
+                  {account}
+                </div>
+              )}
             </div>
           )}
         </header>
       )}
 
-      {/* ── Body row (slim place rail + content) ───────────────────────────── */}
+      {/* ── The one banner lane (NAV-10) ──────────────────────────────────── */}
+      {banners && banners.length > 0 ? <BannerLane banners={banners} className={cn(ambient && chrome)} /> : null}
+
+      {/* ── Body row (sidebar + content) ───────────────────────────────────── */}
       <div className='relative flex min-h-0 grow overflow-hidden'>
-        {/* Desktop place rail. Tablet (md→lg) gets the ICON rail — a full-width
-            240px rail on an ~820px screen squeezes the workspace into a cramped
-            column (owner tablet teardown 2026-07-15 §4); the full labeled rail
-            returns at lg. Two CSS-switched renders (SideNav's `collapsed` is a
-            prop, not a media query) — the rail is cheap to render twice. */}
-        {nav && (
+        {/* 6+ places: the labeled, sectioned sidebar at lg (240px), the icon rail at md–lg
+            (64px — a 240px rail on an ~820px screen squeezes the workspace, owner tablet
+            teardown 2026-07-15 §4). Two CSS-switched renders: SideNav's `collapsed` is a
+            prop, not a media query, and the rail is cheap to render twice. */}
+        {pattern === 'side' && (
           <>
             <aside
               data-cb-nav-rail=''
+              data-cb-nav-collapsed=''
               className={cn(
-                'hidden w-16 border-r border-border md:flex md:shrink-0 md:flex-col lg:hidden',
+                'hidden w-[var(--rail-w-collapsed)] border-r border-border md:flex md:shrink-0 md:flex-col lg:hidden',
                 chrome,
               )}
             >
-              <SideNav
-                model={nav}
-                gate={navGate}
-                activeHref={activeHref}
-                onNavigate={onNavigate}
-                linkComponent={navLinkComponent}
-                resolveIcon={resolveIcon}
-                prefs={navPrefs}
-                collapsed
-                badges={navBadges}
-              badgeTone={navBadgeTone}
-                footer={navFooter}
-              />
+              <SideNav {...sideNavProps} collapsed />
             </aside>
             <aside
               data-cb-nav-rail=''
               className={cn(
-                'hidden border-r border-border lg:flex lg:shrink-0 lg:flex-col',
+                'hidden w-[var(--rail-w)] border-r border-border lg:flex lg:shrink-0 lg:flex-col',
                 chrome,
-                RAIL_WIDTH,
               )}
             >
-              <SideNav
-                model={nav}
-                gate={navGate}
-                activeHref={activeHref}
-                onNavigate={onNavigate}
-                linkComponent={navLinkComponent}
-                resolveIcon={resolveIcon}
-                prefs={navPrefs}
-                onPrefsChange={onNavPrefsChange}
-                badges={navBadges}
-              badgeTone={navBadgeTone}
-                footer={navFooter}
-              />
+              <SideNav {...sideNavProps} onPrefsChange={onNavPrefsChange} />
             </aside>
           </>
         )}
@@ -325,7 +430,7 @@ export function AppShell({
 
       {/* ── Bottom: dock + mobile PlaceBar — the ONLY safe-area owner. ──────── */}
       {showBottom && (
-        <div className='shrink-0 pb-[env(safe-area-inset-bottom,0px)]'>
+        <div ref={bottomChromeRef} className='shrink-0 pb-[env(safe-area-inset-bottom,0px)]'>
           {bottomDock && <div className='border-t border-border'>{bottomDock}</div>}
           {nav && (
             <PlaceBar
@@ -349,6 +454,44 @@ export function AppShell({
 
       {/* The command palette portals its own Dialog; rendered here so one shell owns one. */}
       {palette}
+      {ownPalette && nav ? (
+        <CommandPalette
+          model={nav}
+          gate={navGate}
+          open={paletteControls.open}
+          onOpenChange={paletteControls.setOpen}
+          onNavigate={navigate}
+          resolveIcon={resolveIcon}
+          currentPath={activeHref}
+          places
+          sources={sources}
+        />
+      ) : null}
     </div>
   );
 }
+
+/**
+ * Publishes the bottom chrome's height (dock + `PlaceBar` + safe area) as
+ * `--cb-bottom-chrome-h` on the root, so what floats over the page — the `Toaster`'s stack
+ * (OVL-9) — rises above the navigation instead of covering it. A `PlaceBar` hidden at `md` up
+ * measures 0, so the desktop stack drops back to the corner by itself.
+ */
+function usePublishedBottomChrome(shown: boolean) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `shown` mounts or drops the element the ref points at.
+  useLayoutEffect(() => {
+    const el = ref.current;
+    const root = document.documentElement;
+    if (!el) return;
+    const publish = () => root.style.setProperty('--cb-bottom-chrome-h', `${el.offsetHeight}px`);
+    publish();
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(publish);
+    observer?.observe(el);
+    return () => {
+      observer?.disconnect();
+      root.style.removeProperty('--cb-bottom-chrome-h');
+    };
+  }, [shown]);
+  return ref;
+}

package/src/react/components/AsyncPanel.spec.tsx

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { cleanup, render } from '@testing-library/react';
-import { AsyncPanel } from './AsyncPanel.js';
+import { AsyncPanel, ageLabel } from './AsyncPanel.js';
 
 afterEach(cleanup);
 
@@ -65,4 +65,10 @@ describe('AsyncPanel', () => {
     expect(getByText('No volumes reported')).toBeDefined();
     expect(getByText('The collector has not run.')).toBeDefined();
   });
+
+  test('ageLabel reads in the largest whole unit', () => {
+    expect(ageLabel(4_000)).toBe('just now');
+    expect(ageLabel(12_000)).toBe('12s ago');
+    expect(ageLabel(5 * 60_000)).toBe('5m ago');
+  });
 });

package/src/react/components/AsyncPanel.tsx

@@ -1,7 +1,7 @@
-import type { ReactNode } from 'react';
+import { type ReactNode, useEffect, useRef, useState } from 'react';
 import { Alert } from './Alert.js';
 import { EmptyState } from './EmptyState.js';
-import { SkeletonList } from './Skeleton.js';
+import { ContentSkeleton, type SkeletonVariant } from './Skeleton.js';
 
 export interface AsyncPanelProps {
   loading?: boolean;
@@ -12,8 +12,23 @@ export interface AsyncPanelProps {
   /** Copy for the empty state. */
   emptyTitle?: ReactNode;
   emptyDescription?: ReactNode;
-  /** Rows of skeleton to show while loading. Default 3. */
+  /** Rows (or tiles) of skeleton to show while loading. Default 3. */
   skeletonRows?: number;
+  /**
+   * The SHAPE of the first-load skeleton (STA-1): `rows` for a list or table, `tiles` for a
+   * stat strip, `chart` for a chart frame at the chart's own height. Default `rows`.
+   */
+  skeleton?: SkeletonVariant;
+  /**
+   * A refetch is in flight while the panel already shows data (STA-2). The data stays and a
+   * quiet "Updating…" replaces the freshness stamp — the panel never blanks to a skeleton on
+   * every poll. `loading` after the first content behaves the same way on its own.
+   */
+  refreshing?: boolean;
+  /** When the shown data was fetched — rendered as "Updated 12s ago" (STA-2, STA-8). */
+  updatedAt?: number | Date | null;
+  /** Past this age the stamp turns amber and says so ("No update for 5m", STA-8). */
+  staleAfterMs?: number;
   /**
    * Names the failing section in its error message ("AWS cost is unavailable").
    * Without it the reader gets "Something went wrong" on a page of twelve
@@ -25,6 +40,54 @@ export interface AsyncPanelProps {
   children: ReactNode;
 }
 
+/** "just now", "12s ago", "3m ago", "2h ago", "4d ago" — the freshness stamp's wording. */
+export function ageLabel(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 5_000) return 'just now';
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 48) return `${h}h ago`;
+  return `${Math.floor(h / 24)}d ago`;
+}
+
+/** Re-render on a slow tick so an age keeps reading true without a refetch. */
+function useNow(active: boolean, everyMs = 10_000): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!active) return;
+    const id = setInterval(() => setNow(Date.now()), everyMs);
+    return () => clearInterval(id);
+  }, [active, everyMs]);
+  return now;
+}
+
+function Freshness({
+  refreshing,
+  updatedAt,
+  staleAfterMs,
+}: {
+  refreshing: boolean;
+  updatedAt: number | Date | null | undefined;
+  staleAfterMs: number | undefined;
+}) {
+  const at = updatedAt == null ? null : typeof updatedAt === 'number' ? updatedAt : updatedAt.getTime();
+  const now = useNow(at != null);
+  if (!refreshing && at == null) return null;
+  const age = at == null ? 0 : Math.max(0, now - at);
+  const stale = !refreshing && staleAfterMs != null && at != null && age > staleAfterMs;
+  return (
+    <p
+      data-cb-freshness={refreshing ? 'updating' : stale ? 'stale' : 'fresh'}
+      aria-live='polite'
+      className={stale ? 'text-right text-xs tabular-nums text-warning' : 'text-right text-xs tabular-nums text-muted-foreground'}
+    >
+      {refreshing ? 'Updating…' : stale ? `No update for ${ageLabel(age).replace(' ago', '')}` : `Updated ${ageLabel(age)}`}
+    </p>
+  );
+}
+
 const messageOf = (error: unknown): string => {
   if (error instanceof Error) return error.message;
   if (typeof error === 'string') return error;
@@ -54,11 +117,20 @@ export function AsyncPanel({
   emptyTitle = 'Nothing to show',
   emptyDescription,
   skeletonRows = 3,
+  skeleton = 'rows',
+  refreshing = false,
+  updatedAt,
+  staleAfterMs,
   label,
   onRetryAction,
   children,
 }: AsyncPanelProps) {
-  if (loading) return <SkeletonList rows={skeletonRows} />;
+  // STA-2: once the panel has shown its content, a later `loading` is a REFRESH — the content
+  // stays on screen. Only the first load draws the skeleton.
+  const shownContent = useRef(false);
+  if (loading && !shownContent.current) {
+    return <ContentSkeleton variant={skeleton} count={skeletonRows} />;
+  }
   if (error) {
     return (
       <Alert tone='warning' {...(onRetryAction ? { action: onRetryAction } : {})}>
@@ -76,5 +148,13 @@ export function AsyncPanel({
       />
     );
   }
-  return <>{children}</>;
+  shownContent.current = true;
+  const busy = refreshing || loading === true;
+  if (!busy && updatedAt == null) return <>{children}</>;
+  return (
+    <div className='flex min-w-0 flex-col gap-2' aria-busy={busy || undefined}>
+      <Freshness refreshing={busy} updatedAt={updatedAt} staleAfterMs={staleAfterMs} />
+      {children}
+    </div>
+  );
 }