cursedbelt 5.81.2 → 5.85.0

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

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { cleanup, render } from '@testing-library/react';
+import { FilterRail } from '../filter-rail/FilterRail.js';
+import { RailPlaces } from './RailPlaces.js';
+import type { TopBarItem } from './TopBar.js';
+
+afterEach(cleanup);
+
+const Glyph = ({ name }: { name: string }) => <svg data-glyph={name} />;
+
+const items: TopBarItem[] = [
+  { id: 'library', label: 'Library', icon: <Glyph name='library' />, active: true, href: '#/' },
+  { id: 'stats', label: 'Stats', icon: <Glyph name='stats' />, href: '#/stats', badge: 3 },
+  { id: 'consoles', label: 'Consoles', icon: <Glyph name='consoles' />, href: '#/consoles', unavailable: 'Only on the Mac.' },
+];
+const brand = { icon: <Glyph name='brand' />, label: 'ROMs', href: '#/' };
+
+describe('RailPlaces — the top bar moved into the sidebar (owner, 2026-10-20)', () => {
+  test('🔴 every place is a labeled link with its real href, and the list is the primary nav', () => {
+    const { container, getByRole } = render(<RailPlaces brand={brand} items={items} />);
+    const nav = container.querySelector('nav[data-cb-primary-nav]') as HTMLElement;
+    expect(nav.getAttribute('aria-label')).toBe('Places');
+    const library = getByRole('link', { name: 'Library' });
+    expect(library.getAttribute('href')).toBe('#/');
+    expect(library.textContent).toContain('Library');
+    expect(getByRole('link', { name: 'Stats · 3' }).getAttribute('href')).toBe('#/stats');
+  });
+
+  test('the current place is marked three ways (NAV-6): aria-current, the raised fill, the 3px accent edge', () => {
+    const { getByRole } = render(<RailPlaces brand={brand} items={items} />);
+    const library = getByRole('link', { name: 'Library' });
+    expect(library.getAttribute('aria-current')).toBe('page');
+    expect(library.className).toContain('bg-card-overlay');
+    expect(library.className).toContain('inset_3px_0_0_0_var(--accent)');
+    expect(getByRole('link', { name: 'Stats · 3' }).getAttribute('aria-current')).toBeNull();
+  });
+
+  test('an unavailable place stays on screen as a disabled link, never a dead href (owner-uis-are-one-ui)', () => {
+    const { container } = render(<RailPlaces brand={brand} items={items} />);
+    const consoles = container.querySelector('[aria-label="Consoles"]') as HTMLElement;
+    expect(consoles.tagName).toBe('SPAN');
+    expect(consoles.getAttribute('aria-disabled')).toBe('true');
+    expect(consoles.hasAttribute('href')).toBe(false);
+  });
+
+  test('the brand links home and the utilities sit on its line, marked as utilities', () => {
+    const { container, getByRole } = render(
+      <RailPlaces brand={brand} items={items} trailing={<span data-utility=''>Account</span>} />,
+    );
+    expect(getByRole('link', { name: 'ROMs' }).getAttribute('href')).toBe('#/');
+    const utilities = container.querySelector('[data-cb-rail-utilities]') as HTMLElement;
+    expect(utilities.hasAttribute('data-cb-nav-utility')).toBe(true);
+    expect(utilities.textContent).toBe('Account');
+  });
+
+  test('🔴 collapsed: icons with an sr-only name, the utilities kept in a column, and the nav says it is the collapsed rail', () => {
+    const { container, getByRole } = render(
+      <RailPlaces brand={brand} items={items} collapsed trailing={<span data-utility=''>Account</span>} />,
+    );
+    // A folded rail keeps the account: it stacks under the mark rather than vanishing.
+    const utilities = container.querySelector('[data-cb-rail-utilities]') as HTMLElement;
+    expect(utilities.textContent).toBe('Account');
+    expect(utilities.className).toContain('flex-col');
+    expect(container.querySelector('nav')?.hasAttribute('data-cb-nav-collapsed')).toBe(true);
+    expect(getByRole('link', { name: 'Library' }).querySelector('.sr-only')?.textContent).toBe('Library');
+  });
+
+  test('🔴 in FilterRail\'s `places` slot it survives the rail collapsing, where `header` does not', () => {
+    const rail = (collapsed: boolean) => (
+      <FilterRail
+        label='Library'
+        sections={[{ id: 'views', items: [{ id: 'all', label: 'All' }] }]}
+        selected='all'
+        onSelect={() => {}}
+        collapsed={collapsed}
+        onCollapsedChange={() => {}}
+        places={<RailPlaces brand={brand} items={items} collapsed={collapsed} />}
+        header={<span data-rail-header=''>Filter</span>}
+      />
+    );
+    const open = render(rail(false));
+    expect(open.container.querySelector('[data-cb-rail-places]')).not.toBeNull();
+    expect(open.container.querySelector('[data-rail-header]')).not.toBeNull();
+    cleanup();
+    const folded = render(rail(true));
+    expect(folded.container.querySelector('[data-cb-rail-places]')).not.toBeNull();
+    expect(folded.getByRole('link', { name: 'Library' })).toBeTruthy();
+    expect(folded.container.querySelector('[data-rail-header]')).toBeNull();
+  });
+
+  test('🔴 a footer given as a function stays on the folded rail, told it is folded; a node footer does not', () => {
+    const rail = (collapsed: boolean, footer: Parameters<typeof FilterRail>[0]['footer']) => (
+      <FilterRail
+        label='Library'
+        sections={[{ id: 'views', items: [{ id: 'all', label: 'All' }] }]}
+        selected='all'
+        onSelect={() => {}}
+        collapsed={collapsed}
+        onCollapsedChange={() => {}}
+        footer={footer}
+      />
+    );
+    const folded = render(rail(true, (c) => <span data-foot=''>{c ? 'icons' : 'Settings'}</span>));
+    expect(folded.container.querySelector('[data-foot]')?.textContent).toBe('icons');
+    cleanup();
+    const open = render(rail(false, (c) => <span data-foot=''>{c ? 'icons' : 'Settings'}</span>));
+    expect(open.container.querySelector('[data-foot]')?.textContent).toBe('Settings');
+    cleanup();
+    expect(render(rail(true, <span data-foot=''>Settings</span>)).container.querySelector('[data-foot]')).toBeNull();
+  });
+});

package/src/react/nav/RailPlaces.tsx

@@ -0,0 +1,192 @@
+import type { ElementType, ReactNode } from 'react';
+import { Tooltip } from '../components/Tooltip.js';
+import { cn } from '../lib/cn.js';
+import { TAP_TARGET, TAP_TARGET_HEIGHT } from '../lib/tapTarget.js';
+import { NAV_BADGE_TONE } from './navShared.js';
+import type { TopBarItem, TopBarProps } from './TopBar.js';
+
+export interface RailPlacesProps {
+  /** The app's mark and name, linking to its root — the same shape `TopBar` takes. */
+  brand: TopBarProps['brand'];
+  /** The app's places, in IA order — the same items a `TopBar` would have drawn. */
+  items: readonly TopBarItem[];
+  /**
+   * The utility cluster on the brand's line: help, theme, account. Icons, each with its own
+   * tooltip (NAV-2 allows utilities to be icons). Collapsed, they stack under the mark instead: a
+   * rail folded to icons must not lose the account or the lock.
+   */
+  trailing?: ReactNode;
+  /** The rail's icon-only state: every place is its icon, its tooltip and an sr-only name. */
+  collapsed?: boolean;
+  /** SPA link component (receives `to` as well as `href`), as `TopBar` takes it. */
+  linkComponent?: ElementType;
+  /** Accessible name of the places list. Default "Places". */
+  navLabel?: string;
+  className?: string;
+}
+
+/**
+ * An app's brand, its places and its global utilities at the TOP OF ITS SIDEBAR — in place of a
+ * `TopBar` above the page.
+ *
+ * ── Why ────────────────────────────────────────────────────────────────────
+ * The owner, 2026-10-20, on roms, vault and music: *"All apps will use the sidebar instead of an
+ * extra top row, utilize space better"* and *"move all top row buttons into the far left sidebar
+ * and no longer have the top row so we save space and see more content with less scrolling
+ * needed."* An app that already gives its left edge to a sidebar was spending a second 64px strip
+ * across the whole width on three places and an avatar. Linear and Notion put exactly these in
+ * the sidebar's head — workspace mark and account on one line, the places under it — and the page
+ * keeps its full height. NAV-3's top bar stays the pattern for an app with NO sidebar.
+ *
+ * ── The pieces ─────────────────────────────────────────────────────────────
+ * - The brand line: the mark and name (a link to the root), then `trailing` locked to the right.
+ * - The places: labeled rows with the rail's own look, so a place and a filter row line up — and
+ *   the current one is marked three ways (NAV-6): a 3px accent edge, the raised fill, the medium
+ *   weight. Real hrefs, so they copy and middle-click; `TopBarItem`'s `badge` and `unavailable`
+ *   behave as they do in the bar (`owner-uis-are-one-ui`: an unavailable place is shown, with why).
+ * - A hairline under the block, so the app's own sections below read as the page's, not the app's.
+ *
+ * Put it in `FilterRail`'s `places` slot (it survives the rail's collapse there) or at the top of
+ * any other sidebar. The design audit's NAV-15 fails a `TopBar` shown beside a sidebar at ≥768px,
+ * so the two cannot drift back into both.
+ */
+export function RailPlaces({
+  brand,
+  items,
+  trailing,
+  collapsed = false,
+  linkComponent,
+  navLabel = 'Places',
+  className,
+  ...rest
+}: RailPlacesProps) {
+  const Brand: ElementType = linkComponent ?? 'a';
+  return (
+    <div
+      {...rest}
+      data-cb-rail-places=''
+      className={cn('flex flex-none flex-col gap-1 border-b border-rule px-2 pt-2 pb-2', className)}
+    >
+      <div className={cn('flex h-10 min-w-0 items-center gap-1', collapsed && 'justify-center')}>
+        <Brand
+          {...brand.linkProps}
+          {...(linkComponent ? { to: brand.href } : {})}
+          href={brand.href}
+          aria-label={brand.label}
+          data-cb-rail-brand=''
+          className={cn(
+            'flex min-w-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,
+            !collapsed && 'flex-1',
+          )}
+        >
+          <span aria-hidden='true' className='grid size-6 shrink-0 place-items-center [&_svg]:size-5'>
+            {brand.icon}
+          </span>
+          {collapsed ? null : (
+            <span aria-hidden='true' className='truncate text-sm'>
+              {brand.label}
+            </span>
+          )}
+        </Brand>
+        {trailing && !collapsed ? (
+          <div data-cb-rail-utilities='' data-cb-nav-utility='' className='flex shrink-0 items-center gap-0.5'>
+            {trailing}
+          </div>
+        ) : null}
+      </div>
+      {trailing && collapsed ? (
+        <div data-cb-rail-utilities='' data-cb-nav-utility='' className='flex flex-col items-center gap-0.5'>
+          {trailing}
+        </div>
+      ) : null}
+      {items.length > 0 ? (
+        <nav
+          aria-label={navLabel}
+          data-cb-primary-nav=''
+          data-cb-nav-collapsed={collapsed ? '' : undefined}
+          className='flex flex-col gap-px'
+        >
+          {items.map((item) => (
+            <RailPlaceLink key={item.id} item={item} collapsed={collapsed} linkComponent={linkComponent} />
+          ))}
+        </nav>
+      ) : null}
+    </div>
+  );
+}
+
+function RailPlaceLink({
+  item,
+  collapsed,
+  linkComponent,
+}: {
+  item: TopBarItem;
+  collapsed: boolean;
+  linkComponent: ElementType | undefined;
+}) {
+  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}
+      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 items-center gap-2 rounded-md text-sm transition-colors',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        collapsed ? `size-10 justify-center mx-auto ${TAP_TARGET}` : `px-2.5 py-1.5 ${TAP_TARGET_HEIGHT}`,
+        item.unavailable && 'opacity-55',
+        item.active
+          ? 'bg-card-overlay font-medium text-foreground shadow-[inset_3px_0_0_0_var(--accent)]'
+          : 'text-muted-foreground hover:bg-card-raised hover:text-foreground',
+      )}
+    >
+      <span aria-hidden='true' className='grid size-4 shrink-0 place-items-center [&_svg]:size-4'>
+        {item.icon}
+      </span>
+      {collapsed ? (
+        <span className='sr-only'>{item.label}</span>
+      ) : (
+        <span aria-hidden='true' className='min-w-0 flex-1 truncate'>
+          {item.label}
+        </span>
+      )}
+      {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 tabular-nums',
+            NAV_BADGE_TONE[item.badgeTone ?? 'alert'],
+            collapsed && 'absolute -top-0.5 -right-0.5',
+          )}
+        >
+          {badgeText}
+        </span>
+      ) : null}
+    </Link>
+  );
+  if (item.unavailable) {
+    return (
+      <Tooltip content={`${item.label} — not available here. ${item.unavailable}`} side='right' multiline>
+        {link}
+      </Tooltip>
+    );
+  }
+  return collapsed ? (
+    <Tooltip content={item.label} side='right'>
+      {link}
+    </Tooltip>
+  ) : (
+    link
+  );
+}

package/src/react/nav/SearchResults.tsx

@@ -55,16 +55,17 @@ export function SearchResults({
   onAfterNavigate,
   resolveIcon,
   className,
+  ...rest
 }: SearchResultsProps) {
   const hasResults = groups.some((g) => g.items.length > 0);
   if (!hasResults) {
     return emptyContent ? (
-      <div className={cn('p-6 text-center', className)}>{emptyContent}</div>
+      <div {...rest} className={cn('p-6 text-center', className)}>{emptyContent}</div>
     ) : null;
   }
 
   return (
-    <div className={cn('flex flex-col', className)} role='listbox' aria-label='Search results'>
+    <div {...rest} className={cn('flex flex-col', className)} role='listbox' aria-label='Search results'>
       {groups.map((group) =>
         group.items.length === 0 ? null : (
           <div key={group.key} className='py-1'>

package/src/react/nav/SideNav.tsx

@@ -26,6 +26,10 @@ import {
   navAccent,
   rankBySavedOrder,
   renderIcon,
+  type NavBadge,
+  navBadgeText,
+  navBadgeTone,
+  navBadgeValue,
 } from './navShared.js';
 import { TAP_TARGET, TAP_TARGET_HEIGHT } from '../lib/tapTarget.js';
 
@@ -73,8 +77,8 @@ export interface SideNavProps extends NavNavigationProps {
   /** Fired when a section header is toggled while `collapsedSections` is controlled;
    *  `collapsed` is the section's NEXT state. */
   onSectionToggle?: (section: string, collapsed: boolean) => void;
-  /** Dynamic per-domain badge (unread count, etc.), keyed by domain id. */
-  badges?: Record<string, number | string>;
+  /** Dynamic per-domain badge (unread count, etc.), keyed by domain id. A badge may carry its own tone — see {@link NavBadge}. */
+  badges?: Record<string, NavBadge>;
   /** How those counts read — see {@link NavBadgeTone}. Default `alert` (red). */
   badgeTone?: NavBadgeTone;
   /** App slot above the list (logo / brand). */
@@ -124,6 +128,7 @@ export function SideNav({
   footer,
   expandActive = true,
   className,
+  ...rest
 }: SideNavProps) {
   const domains = deriveSideNavDomains(model, gate);
   const hiddenIds = prefs?.hidden ?? [];
@@ -218,6 +223,7 @@ export function SideNav({
 
   return (
     <nav
+      {...rest}
       data-cb-sidenav=''
       data-cb-nav-collapsed={collapsed ? '' : undefined}
       aria-label='Primary'
@@ -319,7 +325,7 @@ interface DomainRowProps extends NavNavigationProps {
   /** The current page is one of this place's items, shown beneath it. */
   activeIsChild?: boolean;
   color?: string;
-  badge?: number | string;
+  badge?: NavBadge;
   badgeTone: NavBadgeTone;
   collapsed: boolean;
   canCustomize: boolean;
@@ -347,6 +353,7 @@ function DomainRow({
 }: DomainRowProps) {
   const accent = navAccent(color);
   const icon = renderIcon(resolveIcon, domain.icon);
+  const badgeShown = navBadgeValue(badge);
   /**
    * 🔴 `UX_STANDARDS.md` §8.6 / the owner's `owner-uis-are-one-ui` ruling: a nav item
    * that cannot do its job on this host must SAY SO BEFORE IT IS CLICKED. The prod
@@ -422,9 +429,9 @@ function DomainRow({
         </span>
       )}
       {!collapsed && <span className='flex-1 truncate text-left'>{domain.label}</span>}
-      {!collapsed && badge != null && badge !== 0 && (
-        <span className={cn('rounded-full px-1.5 py-0.5 text-xs font-bold', NAV_BADGE_TONE[badgeTone])}>
-          {typeof badge === 'number' && badge > 99 ? '99+' : badge}
+      {!collapsed && badgeShown !== null && (
+        <span data-cb-nav-badge='' className={cn('rounded-full px-1.5 py-0.5 text-xs font-bold tabular-nums', NAV_BADGE_TONE[navBadgeTone(badge, badgeTone)])}>
+          {navBadgeText(badgeShown)}
         </span>
       )}
     </NavLink>

package/src/react/nav/SideNavCustomize.tsx

@@ -40,7 +40,7 @@ export interface ReorderableRowsProps {
 }
 
 /** The rail's list, drag-reorderable (pointer, touch and keyboard via the shared hook). */
-export function ReorderableRows({ domains, onReorder, renderRow }: ReorderableRowsProps) {
+export function ReorderableRows({ domains, onReorder, renderRow, ...rest }: ReorderableRowsProps) {
   const reorder = useDragReorder({
     items: domains,
     getKey: (d) => d.id,
@@ -51,7 +51,7 @@ export function ReorderableRows({ domains, onReorder, renderRow }: ReorderableRo
 
   return (
     <reorder.DragContext>
-      <ul className='space-y-0.5'>
+      <ul {...rest} className='space-y-0.5'>
         {domains.map((domain) => (
           <reorder.Sortable key={domain.id} itemKey={domain.id}>
             {(api) => (
@@ -81,9 +81,10 @@ export function RowCustomizeControls({
   drag,
   onHide,
   onColor,
+  ...rest
 }: RowCustomizeControlsProps) {
   return (
-    <div className='absolute right-1 flex items-center gap-0.5 opacity-0 transition-opacity focus-within:opacity-100 group-hover/navitem:opacity-100'>
+    <div {...rest} className='absolute right-1 flex items-center gap-0.5 opacity-0 transition-opacity focus-within:opacity-100 group-hover/navitem:opacity-100'>
       {drag && (
         <Tooltip content={`Reorder ${label}`}>
           <button
@@ -117,6 +118,7 @@ export function RestoreHiddenMenu({
   domains,
   resolveIcon,
   onRestore,
+  ...rest
 }: {
   domains: NavDomain[];
   resolveIcon?: IconResolver;
@@ -125,6 +127,7 @@ export function RestoreHiddenMenu({
   const [open, setOpen] = useState(false);
   return (
     <Popover
+      {...rest}
       open={open}
       onOpenChange={setOpen}
       align='start'

package/src/react/nav/TopBar.tsx

@@ -104,6 +104,11 @@ export interface TopBarProps {
  *
  * `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.
+ *
+ * 🔴 **Only for an app with no sidebar** (NAV-15, owner 2026-10-20: *"All apps will use the
+ * sidebar instead of an extra top row"*). Where a sidebar is on screen, the same `brand` and
+ * `items` go to `RailPlaces` at its top and this bar is not drawn; it stays the phone's
+ * shell where that sidebar is a drawer. The design audit fails the two shown together at ≥768px.
  */
 export function TopBar({
   brand,
@@ -117,6 +122,7 @@ export function TopBar({
   linkComponent,
   navLabel = 'Places',
   className,
+  ...rest
 }: TopBarProps) {
   if (!iconOnly && items.length > 5) {
     devWarnOnce(
@@ -128,6 +134,7 @@ export function TopBar({
   const hasPlaces = items.length > 0;
   return (
     <header
+      {...rest}
       data-cb-topbar=''
       data-cb-density={density}
       className={cn(
@@ -208,6 +215,7 @@ export function TopBarPlaces({
   phonePlaces = 'icons',
   linkComponent,
   navLabel = 'Places',
+  ...rest
 }: TopBarPlacesProps) {
   const fade = useScrollEdgeFade();
   const wide = useMediaQuery(WIDE_QUERY);
@@ -234,6 +242,7 @@ export function TopBarPlaces({
       </span>
     ) : null}
     <nav
+      {...rest}
       aria-label={navLabel}
       data-cb-topbar-nav=''
       // The design audit's NAV-2 check reads `data-cb-primary-nav`: a router must show its

package/src/react/nav/index.ts

@@ -61,6 +61,10 @@ export {
   NavLink,
   type NavLinkProps,
   type NavNavigationProps,
+  type NavBadge,
+  navBadgeText,
+  navBadgeTone,
+  navBadgeValue,
 } from './navShared.js';
 export { PlaceBar, type PlaceBarProps } from './PlaceBar.js';
 export {
@@ -79,3 +83,4 @@ export {
   type TopBarPlacesProps,
   type TopBarProps,
 } from './TopBar.js';
+export { RailPlaces, type RailPlacesProps } from './RailPlaces.js';

package/src/react/nav/navShared.tsx

@@ -74,6 +74,7 @@ export function NavLink({
   tabIndex,
   disabled,
   children,
+  ...rest
 }: NavLinkProps) {
   const handleClick = () => {
     onNavigate?.(path);
@@ -91,6 +92,7 @@ export function NavLink({
     const row = (
       // biome-ignore lint/a11y/useSemanticElements: HTML has no disabled anchor; an <a> without href carries no link role at all, and one WITH href is followable — the bug this branch exists to stop.
       <span
+        {...rest}
         // `role='link'` so the row still ANNOUNCES as the destination it is, with
         // `aria-disabled` saying it cannot be followed here — a bare <span> with an
         // aria-label is not a supported combination and reads as nothing.
@@ -113,6 +115,7 @@ export function NavLink({
       const Link = linkComponent;
       return (
         <Link
+          {...rest}
           to={path}
           href={path}
           className={className}
@@ -128,6 +131,7 @@ export function NavLink({
     })()
   ) : (
     <a
+      {...rest}
       href={path}
       className={className}
       style={style}
@@ -225,3 +229,24 @@ export const NAV_BADGE_TONE: Record<NavBadgeTone, string> = {
   neutral: 'bg-muted text-muted-foreground',
   accent: 'bg-accent/15 text-accent-strong',
 };
+
+/**
+ * A place's badge: a bare count or word (the shell's one `badgeTone` applies), or a count WITH
+ * its own tone — so one sidebar can say "3 problems you have not seen" in red beside "12 queued"
+ * in grey. Station asked for exactly that on 2026-10-20 (forge task station-evolution): the red
+ * number is reserved for what the owner has not looked at yet, and a plain fact never shares it.
+ */
+export type NavBadge = number | string | { value: number | string; tone?: NavBadgeTone };
+
+/** The count or word a badge shows — `null` for nothing to draw (absent, `0`, an empty string). */
+export function navBadgeValue(badge: NavBadge | undefined): number | string | null {
+  const v = badge !== null && typeof badge === 'object' ? badge.value : badge;
+  return v == null || v === 0 || v === '' ? null : v;
+}
+
+/** The badge's own tone, else the shell's. */
+export const navBadgeTone = (badge: NavBadge | undefined, fallback: NavBadgeTone): NavBadgeTone =>
+  badge !== null && typeof badge === 'object' && badge.tone ? badge.tone : fallback;
+
+/** `150` → `99+`: a badge is a glance, not a figure. */
+export const navBadgeText = (value: number | string): string => (typeof value === 'number' && value > 99 ? '99+' : String(value));

package/src/react/notifications/NotificationBell.tsx

@@ -48,12 +48,14 @@ export function NotificationBell({
   feedMaxHeight = '420px',
   onOpen,
   className,
+  ...rest
 }: NotificationBellProps) {
   const unreadCount = useNotificationStore(store, (s) => s.unreadCount);
   const [open, setOpen] = useState(false);
 
   return (
     <Popover
+      {...rest}
       open={open}
       onOpenChange={setOpen}
       width={feedWidth}

package/src/react/notifications/NotificationFeed.tsx

@@ -187,6 +187,7 @@ export function NotificationFeed({
   maxHeight = '400px',
   onOpen,
   className,
+  ...rest
 }: NotificationFeedProps) {
   const notifications = useNotificationStore(store, (s) => s.notifications);
   const unreadCount = useNotificationStore(store, (s) => s.unreadCount);
@@ -199,7 +200,7 @@ export function NotificationFeed({
   const read = notifications.filter((n) => n.read);
 
   return (
-    <div className={cn('flex flex-col', className)}>
+    <div {...rest} className={cn('flex flex-col', className)}>
       {/* Header */}
       <div className='flex items-center justify-between border-b border-border px-4 py-2'>
         <span className='text-sm font-semibold text-foreground'>

package/src/react/notifications/NotificationInbox.tsx

@@ -199,10 +199,11 @@ export function NotificationInbox({
   onOpen,
   focusId,
   className,
+  ...rest
 }: NotificationInboxProps) {
   const anyUnread = items.some((n) => !n.read && !n.done);
   return (
-    <div className={cn('flex min-w-0 flex-col', className)}>
+    <div {...rest} className={cn('flex min-w-0 flex-col', className)}>
       {/* pt gives the filter row breathing room under the page header; pb separates
           it from the list/empty state below. */}
       <div className='flex flex-wrap items-center justify-between gap-2 pb-4 pt-2'>

package/src/react/palette/CommandPalette.tsx

@@ -190,6 +190,7 @@ export function CommandPalette({
   placeholder = 'Search pages, run a command…',
   emptyContent = 'No matches.',
   className,
+  ...rest
 }: CommandPaletteProps) {
   const [query, setQuery] = useState('');
   const trimmed = query.trim();
@@ -375,6 +376,7 @@ export function CommandPalette({
       <Dialog.Portal>
         <Dialog.Overlay className={cn('fixed inset-0 z-50 bg-black/50 backdrop-blur-sm', SCRIM_MOTION)} />
         <Dialog.Content
+          {...rest}
           data-cb-command-palette=''
           onOpenAutoFocus={(e) => {
             // Let cmdk's input keep the autofocus (Radix would otherwise focus the

package/src/react/palette/Kbd.tsx

@@ -26,13 +26,13 @@ const CAP =
   'rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-caption font-medium text-muted-foreground';
 
 /** One key cap, in the platform's notation. */
-export function Kbd({ keys, platform, children, className }: KbdProps) {
+export function Kbd({ keys, platform, children, className, ...rest }: KbdProps) {
   if (keys !== undefined && platform === 'both') {
     const mac = formatHotkey(keys, true);
     const windows = formatHotkey(keys, false);
     if (mac !== windows) {
       return (
-        <span className={cn('inline-flex items-center gap-1', className)}>
+        <span {...rest} className={cn('inline-flex items-center gap-1', className)}>
           <kbd className={CAP}>{mac}</kbd>
           <span className='text-caption text-muted-foreground'>
             (<kbd className={CAP}>{windows}</kbd>)
@@ -42,5 +42,5 @@ export function Kbd({ keys, platform, children, className }: KbdProps) {
     }
   }
   const apple = platform === 'mac' ? true : platform === 'windows' ? false : undefined;
-  return <kbd className={cn(CAP, className)}>{keys !== undefined ? formatHotkey(keys, apple) : children}</kbd>;
+  return <kbd {...rest} className={cn(CAP, className)}>{keys !== undefined ? formatHotkey(keys, apple) : children}</kbd>;
 }

package/src/react/palette/ShortcutSheet.tsx

@@ -51,9 +51,11 @@ export function ShortcutSheet({
   title = 'Keyboard shortcuts',
   subtitle = 'Keys work anywhere outside a text field.',
   platform,
+  ...rest
 }: ShortcutSheetProps) {
   return (
     <Modal
+      {...rest}
       open={open}
       onClose={onClose}
       size='md'

package/src/react/palette/commandSources.tsx

@@ -92,6 +92,7 @@ export class CommandSourceStore {
 const SourceContext = createContext<CommandSourceStore | null>(null);
 
 /** Holds the sources pages contribute. `AppShell` mounts one; an app without it can too. */
+// no-attribute-forward: a context provider; it renders only its children.
 export function CommandSourceProvider({ children }: { children: ReactNode }) {
   const [store] = useState(() => new CommandSourceStore());
   return <SourceContext.Provider value={store}>{children}</SourceContext.Provider>;