cursedbelt 5.9.0 → 5.10.0

package/dist/react/nav/TopBar.d.ts

@@ -0,0 +1,65 @@
+import type { AnchorHTMLAttributes, ReactNode } from 'react';
+/** What an `<a>` in the bar is handed — `href`, `onClick`, whatever the app's router needs. */
+export type TopBarLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'children' | 'className' | 'aria-label' | 'href'>;
+export interface TopBarItem {
+    /** Stable key. */
+    id: string;
+    /** The place's name. It is the accessible name and the hover hint — it is NOT painted. */
+    label: string;
+    /** The glyph that IS the item. Required: an item without one cannot be drawn in this bar. */
+    icon: ReactNode;
+    /** The place the user is in. Lit, 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.
+     */
+    wordsBecause?: 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. */
+    items: readonly TopBarItem[];
+    /** The trailing cluster: theme toggle, account menu. Never shrinks. */
+    trailing?: ReactNode;
+    /** 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.
+ *
+ * ── 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.
+ *
+ * `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 declare function TopBar({ brand, items, trailing, navLabel, className }: TopBarProps): import("react").JSX.Element;
+//# sourceMappingURL=TopBar.d.ts.map

package/dist/react/nav/TopBar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopBar.d.ts","sourceRoot":"","sources":["../../../src/react/nav/TopBar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAO7D,+FAA+F;AAC/F,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,oBAAoB,CAAC,iBAAiB,CAAC,EACvC,UAAU,GAAG,WAAW,GAAG,YAAY,GAAG,MAAM,CACjD,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,kBAAkB;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,IAAI,EAAE,SAAS,CAAC;IAChB,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,+FAA+F;IAC/F,KAAK,EAAE;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;IACrF,wFAAwF;IACxF,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAmB,EAAE,SAAS,EAAE,EAAE,WAAW,+BAiD7F"}

package/dist/react/nav/TopBar.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ScrollArea } from '../components/ScrollArea.js';
+import { Tooltip } from '../components/Tooltip.js';
+import { useScrollEdgeFade } from '../hooks/useScrollEdgeFade.js';
+import { cn } from '../lib/cn.js';
+import { TAP_TARGET_SQUARE } from '../lib/tapTarget.js';
+/**
+ * THE top bar: brand, places, trailing controls — one 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.
+ *
+ * `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, navLabel = 'Places', className }) {
+    const fade = useScrollEdgeFade();
+    return (_jsxs("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), children: [_jsxs("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'), children: [_jsx("span", { "aria-hidden": 'true', className: 'grid size-6 place-items-center [&_svg]:size-5', children: brand.icon }), _jsx("span", { "aria-hidden": 'true', className: 'hidden md:inline', children: brand.label })] }), _jsx("nav", { "aria-label": navLabel, "data-cb-topbar-nav": '', className: 'min-w-0 flex-1', style: fade.maskStyle, children: _jsx(ScrollArea, { axis: 'x', space: 'none', safeArea: false, scrollRef: fade.ref, onScroll: fade.onScroll, className: 'w-full [scrollbar-width:none] [&::-webkit-scrollbar]:hidden', children: _jsx("div", { className: 'flex w-max items-center gap-1', children: items.map((item) => (_jsx(TopBarLink, { item: item }, item.id))) }) }) }), trailing ? _jsx("div", { className: 'flex shrink-0 items-center gap-1', children: trailing }) : null] }));
+}
+function TopBarLink({ item }) {
+    const words = Boolean(item.wordsBecause?.trim());
+    return (_jsx(Tooltip, { content: item.label, side: 'bottom', children: _jsxs("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'), children: [_jsx("span", { "aria-hidden": 'true', className: 'grid size-5 place-items-center [&_svg]:size-5', children: item.icon }), words ? (_jsx("span", { "aria-hidden": 'true', className: 'hidden text-sm font-medium sm:inline', children: item.label })) : null] }) }));
+}
+//# sourceMappingURL=TopBar.js.map

package/dist/react/nav/TopBar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopBar.js","sourceRoot":"","sources":["../../../src/react/nav/TopBar.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA0CxD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,EAAE,SAAS,EAAe;IAC5F,MAAM,IAAI,GAAG,iBAAiB,EAAE,CAAC;IACjC,OAAO,CACL,oCACiB,EAAE,EACjB,SAAS,EAAE,EAAE,CAAC,gFAAgF,EAAE,SAAS,CAAC,aAE1G,gBACM,KAAK,CAAC,SAAS,EACnB,IAAI,EAAE,KAAK,CAAC,IAAI,gBACJ,KAAK,CAAC,KAAK,0BACF,EAAE,EACvB,SAAS,EAAE,EAAE,CACX,uFAAuF,EACvF,yEAAyE,EACzE,iBAAiB,EACjB,0BAA0B,CAC3B,aAED,8BAAkB,MAAM,EAAC,SAAS,EAAC,+CAA+C,YAC/E,KAAK,CAAC,IAAI,GACN,EACP,8BAAkB,MAAM,EAAC,SAAS,EAAC,kBAAkB,YAClD,KAAK,CAAC,KAAK,GACP,IACL,EAEJ,4BAAiB,QAAQ,wBAAqB,EAAE,EAAC,SAAS,EAAC,gBAAgB,EAAC,KAAK,EAAE,IAAI,CAAC,SAAS,YAG/F,KAAC,UAAU,IACT,IAAI,EAAC,GAAG,EACR,KAAK,EAAC,MAAM,EACZ,QAAQ,EAAE,KAAK,EACf,SAAS,EAAE,IAAI,CAAC,GAAG,EACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ,EACvB,SAAS,EAAC,6DAA6D,YAEvE,cAAK,SAAS,EAAC,+BAA+B,YAC3C,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CACnB,KAAC,UAAU,IAAe,IAAI,EAAE,IAAI,IAAnB,IAAI,CAAC,EAAE,CAAgB,CACzC,CAAC,GACE,GACK,GACT,EAEL,QAAQ,CAAC,CAAC,CAAC,cAAK,SAAS,EAAC,kCAAkC,YAAE,QAAQ,GAAO,CAAC,CAAC,CAAC,IAAI,IAC9E,CACV,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,EAAE,IAAI,EAAwB;IAChD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,OAAO,CACL,KAAC,OAAO,IAAC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAC,QAAQ,YACzC,gBACM,IAAI,CAAC,SAAS,EAClB,IAAI,EAAE,IAAI,CAAC,IAAI,gBACH,IAAI,CAAC,KAAK,kBACR,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,iBACjC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,EACzC,SAAS,EAAE,EAAE,CACX,wGAAwG,EACxG,yEAAyE,EACzE,iBAAiB,EACjB,KAAK,IAAI,0BAA0B,EACnC,IAAI,CAAC,MAAM;gBACT,CAAC,CAAC,0BAA0B;gBAC5B,CAAC,CAAC,4DAA4D,CACjE,aAED,8BAAkB,MAAM,EAAC,SAAS,EAAC,+CAA+C,YAC/E,IAAI,CAAC,IAAI,GACL,EACN,KAAK,CAAC,CAAC,CAAC,CACP,8BAAkB,MAAM,EAAC,SAAS,EAAC,sCAAsC,YACtE,IAAI,CAAC,KAAK,GACN,CACR,CAAC,CAAC,CAAC,IAAI,IACN,GACI,CACX,CAAC;AACJ,CAAC"}

package/dist/react/nav/index.d.ts

@@ -16,4 +16,5 @@ export { type IconResolver, isPathWithin, NavLink, type NavLinkProps, type NavNa
 export { PlaceBar, type PlaceBarProps } from './PlaceBar.js';
 export { type SearchResultGroup, type SearchResultRow, SearchResults, type SearchResultsProps, searchOptionId, } from './SearchResults.js';
 export { SideNav, type SideNavProps } from './SideNav.js';
+export { TopBar, type TopBarItem, type TopBarLinkProps, type TopBarProps } from './TopBar.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/react/nav/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/nav/index.ts"],"names":[],"mappings":"AAQA,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,EACrB,eAAe,EACf,KAAK,oBAAoB,EACzB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,aAAa,EACb,aAAa,EACb,KAAK,qBAAqB,EAC1B,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EACL,KAAK,YAAY,EACjB,YAAY,EACZ,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,aAAa,EACb,KAAK,kBAAkB,EACvB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/nav/index.ts"],"names":[],"mappings":"AAQA,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,EACrB,eAAe,EACf,KAAK,oBAAoB,EACzB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,aAAa,EACb,aAAa,EACb,KAAK,qBAAqB,EAC1B,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EACL,KAAK,YAAY,EACjB,YAAY,EACZ,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,aAAa,EACb,KAAK,kBAAkB,EACvB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/react/nav/index.js

@@ -23,4 +23,5 @@ export { isPathWithin, NavLink, } from './navShared.js';
 export { PlaceBar } from './PlaceBar.js';
 export { SearchResults, searchOptionId, } from './SearchResults.js';
 export { SideNav } from './SideNav.js';
+export { TopBar } from './TopBar.js';
 //# sourceMappingURL=index.js.map

package/dist/react/nav/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/nav/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,iGAAiG;AACjG,sFAAsF;AACtF,mFAAmF;AACnF,mFAAmF;AACnF,oFAAoF;AACpF,6FAA6F;AAE7F,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EACL,WAAW,EAEX,eAAe,EAEf,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAA6B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,kBAAkB,EAElB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,GAEpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,qBAAqB,GAEtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAA6B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAKL,aAAa,EACb,aAAa,EAEb,QAAQ,EAGR,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAA6B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAwB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAA0B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAyB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,cAAc,EAA4B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAyB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAEL,YAAY,EACZ,OAAO,GAGR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAsB,MAAM,eAAe,CAAC;AAC7D,OAAO,EAGL,aAAa,EAEb,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAqB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/nav/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,iGAAiG;AACjG,sFAAsF;AACtF,mFAAmF;AACnF,mFAAmF;AACnF,oFAAoF;AACpF,6FAA6F;AAE7F,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EACL,WAAW,EAEX,eAAe,EAEf,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAA6B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,kBAAkB,EAElB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,GAEpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,qBAAqB,GAEtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAA6B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAKL,aAAa,EACb,aAAa,EAEb,QAAQ,EAGR,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAA6B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAwB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAA0B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAyB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,cAAc,EAA4B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAyB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAEL,YAAY,EACZ,OAAO,GAGR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAsB,MAAM,eAAe,CAAC;AAC7D,OAAO,EAGL,aAAa,EAEb,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAqB,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,MAAM,EAA2D,MAAM,aAAa,CAAC"}

package/dist/scripts/guardrailsEnforce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guardrailsEnforce.d.ts","sourceRoot":"","sources":["../../scripts/guardrailsEnforce.ts"],"names":[],"mappings":";AA8LA,UAAU,SAAS;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,IAAI;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;CACzD;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CA6B9D;AA+4BD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAEpE;AAghBD,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAmBtC,CAAC;AASF,eAAO,MAAM,uBAAuB,aAAkD,CAAC;AAGvF,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACb;AAED;2FAC2F;AAC3F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA0C3F;AAED,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAmGhC,wBAAgB,0BAA0B,CAAC,SAAS,GAAE,MAAwB,GAAG,MAAM,EAAE,CAyBxF"}
+{"version":3,"file":"guardrailsEnforce.d.ts","sourceRoot":"","sources":["../../scripts/guardrailsEnforce.ts"],"names":[],"mappings":";AAkMA,UAAU,SAAS;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,IAAI;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;CACzD;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CA6B9D;AA+4BD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAEpE;AAgkBD,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAoBtC,CAAC;AASF,eAAO,MAAM,uBAAuB,aAAkD,CAAC;AAGvF,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACb;AAED;2FAC2F;AAC3F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA0C3F;AAED,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAmGhC,wBAAgB,0BAA0B,CAAC,SAAS,GAAE,MAAwB,GAAG,MAAM,EAAE,CAyBxF"}

package/dist/styles-areas/nav.css

@@ -18,14 +18,15 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 99 candidate(s).
+ * 107 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("-mt-5 -top-1 [&>*]:min-w-0 [&_svg]:size-3.5 bg-accent/15 border-border/40 border-dashed border-l");
-@source inline("border-r collapse cursor-grab data-[state=checked]:ring-2 data-[state=checked]:ring-foreground");
+@source inline("-mt-5 -top-1 [&::-webkit-scrollbar]:hidden [&>*]:min-w-0 [&_svg]:size-3.5 [scrollbar-width:none]");
+@source inline("bg-accent/15 border-border/40 border-dashed border-l border-r collapse cursor-grab");
+@source inline("data-[state=checked]:ring-2 data-[state=checked]:ring-foreground");
 @source inline("data-[state=checked]:ring-offset-1 data-[state=closed]:slide-out-to-bottom");
 @source inline("data-[state=closed]:slide-out-to-left data-[state=closed]:slide-out-to-right");
 @source inline("data-[state=open]:slide-in-from-bottom data-[state=open]:slide-in-from-left");
@@ -36,8 +37,9 @@
 @source inline("items-stretch justify-around justify-start lead leading-4 left-0 left-3 lg:flex lg:flex-col");
 @source inline("lg:hidden lg:shrink-0 line-clamp-2 max-h-72 max-h-[40dvh] max-h-[65dvh] max-h-[85dvh]");
 @source inline("max-h-[inherit] max-sm:flex-none max-sm:justify-center max-sm:px-0 max-sm:w-10 max-w max-w-64");
-@source inline("max-w-[12rem] max-w-[20rem] md:flex md:flex-col md:hidden md:shrink-0 min-h-12 min-h-dvh");
-@source inline("min-w-3.5 min-w-8 mix-blend-difference mt-auto opacity-55 opacity-80 pb-1 pb-2");
-@source inline("pb-[env(safe-area-inset-bottom,0px)] pl-9 place-items-center pr-9 pt-1 px-0.5 right-1");
-@source inline("rounded-l-xl rounded-r-xl rounded-t-xl shadow-lg size-7 size-9 sm:inline sm:inline-flex");
-@source inline("space-y-0.5 space-y-2 text-[0.625rem] top-2 w-0.5 w-52 w-56 w-60");
+@source inline("max-w-[12rem] max-w-[20rem] md:flex md:flex-col md:gap-3 md:hidden md:pointer-coarse:w-auto");
+@source inline("md:px-6 md:shrink-0 min-h-12 min-h-dvh min-w-3.5 min-w-8 min-w-9 mix-blend-difference mt-auto");
+@source inline("opacity-55 opacity-80 pb-1 pb-2 pb-[env(safe-area-inset-bottom,0px)] pl-9 place-items-center");
+@source inline("pr-9 pt-1 px-0.5 right-1 rounded-l-xl rounded-r-xl rounded-t-xl shadow-lg size-7 size-9");
+@source inline("sm:inline sm:inline-flex sm:pointer-coarse:w-auto space-y-0.5 space-y-2 text-[0.625rem] top-2");
+@source inline("w-0.5 w-52 w-56 w-60 w-max");

package/dist/styles-utilities.css

@@ -1015,6 +1015,9 @@
   .min-w-8 {
     min-width: calc(var(--spacing) * 8);
   }
+  .min-w-9 {
+    min-width: calc(var(--spacing) * 9);
+  }
   .min-w-10 {
     min-width: calc(var(--spacing) * 10);
   }
@@ -4080,6 +4083,9 @@
     .md\:flex-row {
       flex-direction: row;
     }
+    .md\:gap-3 {
+      gap: calc(var(--spacing) * 3);
+    }
     :where(.md\:divide-x > :not(:last-child)) {
       --tw-divide-x-reverse: 0;
       border-inline-style: var(--tw-border-style);
@@ -4089,6 +4095,9 @@
     :where(.md\:divide-border > :not(:last-child)) {
       border-color: var(--border);
     }
+    .md\:px-6 {
+      padding-inline: calc(var(--spacing) * 6);
+    }
   }
   @media (width >= 64rem) {
     .lg\:inset-8 {
@@ -4313,6 +4322,20 @@
       translate: var(--tw-translate-x) var(--tw-translate-y);
     }
   }
+  @media (width >= 40rem) {
+    @media (pointer: coarse) {
+      .sm\:pointer-coarse\:w-auto {
+        width: auto;
+      }
+    }
+  }
+  @media (width >= 48rem) {
+    @media (pointer: coarse) {
+      .md\:pointer-coarse\:w-auto {
+        width: auto;
+      }
+    }
+  }
   .\[\&_\.alert-icon\]\:text-accent .alert-icon {
     color: var(--accent);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.9.0",
+	"version": "5.10.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",
@@ -692,8 +692,8 @@
 		"@types/react-dom": "^19.2.3",
 		"@vidstack/react": "1.15.6",
 		"@vitejs/plugin-react": "^5.2.0",
-		"cursedbelt-server": "^4.13.0",
-		"cursedops": "^0.8.1",
+		"cursedbelt-server": "^4.32.1",
+		"cursedops": "^0.10.7",
 		"diff": "^9.0.0",
 		"emoji-mart": "^5.6.0",
 		"hls.js": "^1.5.0",

package/scripts/guardrailsEnforce.spec.ts

@@ -1219,3 +1219,27 @@ const html = \`<input type="password">\`;`,
     expect(check('no-raw-password', `// never write type="password" by hand`)).toHaveLength(0);
   });
 });
+
+describe('no-raw-nav', () => {
+  test('🔴 flags a hand-rolled <nav> — the header music shipped on 2026-09-25', () => {
+    expect(
+      check('no-raw-nav', `<header><nav className="app-header__nav"><a href="/">Library</a></nav></header>`),
+    ).toHaveLength(1);
+  });
+
+  test('passes TopBar, and a nav with a stated reason in the block above', () => {
+    expect(check('no-raw-nav', `<TopBar brand={brand} items={items} />`)).toHaveLength(0);
+    expect(
+      check(
+        'no-raw-nav',
+        `{/* guardrails-ignore no-raw-nav: the library rail is a side list of folders,
+    not a top bar */}
+<nav aria-label="Library">`,
+      ),
+    ).toHaveLength(0);
+  });
+
+  test("a comment that merely mentions <nav> is not a violation", () => {
+    expect(check('no-raw-nav', `// replacing the <nav> would delete the landmark`)).toHaveLength(0);
+  });
+});

package/scripts/guardrailsEnforce.ts

@@ -126,6 +126,10 @@
 //     `type="password"` on ANY tag or props object (the `<Input type="password">` form that
 //     `no-raw-inputs` cannot see) and in template-literal HTML. Use `SecretInput`.
 //
+//   no-raw-nav — owner, 2026-09-25: no hand-rolled `<nav>` in app source. An app's top bar
+//     is `TopBar` (icons, not words, and it cannot widen the page); the other landmarks are
+//     `SideNav`, `PlaceBar`, `BreadcrumbTrail`. Anything else takes the opt-out with a reason.
+//
 // Opt-out (mirrors this repo's existing `biome-ignore lint/<rule>: <reason>` convention —
 // see e.g. packages/cursedbelt/src/react/components/ButtonGroup.tsx): put a same-shaped
 // line comment as the FIRST thing inside the tag's attribute list (for `no-raw-action-button`
@@ -1670,6 +1674,54 @@ const noRawPassword: Rule = {
 	},
 };
 
+// ── no-raw-nav ──────────────────────────────────────────────────────────────
+// The 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 … 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 each one re-decided — usually
+// wrongly — whether its places were words, how wide they could get, and what happens on a
+// 390px phone. `TopBar` (cursedbelt/react) decides all three once: icons only unless an item
+// states `wordsBecause`, clamped to the screen, the places scrolling inside their own strip.
+// `SideNav`, `PlaceBar` and `BreadcrumbTrail` are the belt's other navigation landmarks.
+//
+// The rule is on the ELEMENT, for the reason `no-raw-data-table` gives: "is this hand-rolled
+// nav icon-only and clamped?" is not decidable by a scanner, and a rule that guesses is a
+// rule people route around. A nav that genuinely is not a top bar (a library rail, a
+// settings section list) takes the opt-out with its reason in the comment block above.
+// cursedbelt's own `react/nav/` subtree emits the element and is exempt by construction.
+const RAW_NAV_RE = /<nav\b/g;
+const RAW_NAV_IGNORE_RE = /guardrails-ignore\s+no-raw-nav\s*:/;
+
+const noRawNav: Rule = {
+	name: "no-raw-nav",
+	description:
+		"Owner, 2026-09-25: no hand-rolled <nav> — an app's top bar is cursedbelt's `TopBar` (icons, not words; it cannot widen the page), and its other landmarks are `SideNav`, `PlaceBar` or `BreadcrumbTrail`. A nav that is none of those takes the opt-out with its reason.",
+	check(filePath, source) {
+		const normalized = filePath.replace(/\\/g, "/");
+		if (normalized.includes("react/nav/")) return [];
+		if (isTestSource(normalized)) return [];
+		const violations: Violation[] = [];
+		const scannable = blankComments(source);
+		const lines = source.split("\n");
+		RAW_NAV_RE.lastIndex = 0;
+		for (const match of scannable.matchAll(RAW_NAV_RE)) {
+			const line = lineOf(source, match.index ?? 0);
+			// The contiguous comment block above, same as no-raw-data-table: a real reason runs
+			// to several lines and the marker sits on its first.
+			const block: string[] = [];
+			for (let i = line - 2; i >= 0 && block.length < 12; i--) {
+				const raw = lines[i] ?? "";
+				if (raw.trim() === "") break;
+				block.push(raw);
+			}
+			if (RAW_NAV_IGNORE_RE.test(block.join("\n")) || RAW_NAV_IGNORE_RE.test(lines[line - 1] ?? "")) continue;
+			violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		}
+		return violations;
+	},
+};
+
 export const RULES: Record<string, Rule> = {
 	[noRawActionButton.name]: noRawActionButton,
 	[noRawOverflow.name]: noRawOverflow,
@@ -1689,6 +1741,7 @@ export const RULES: Record<string, Rule> = {
 	[noNativeDialog.name]: noNativeDialog,
 	[noFastTooltip.name]: noFastTooltip,
 	[noRawPassword.name]: noRawPassword,
+	[noRawNav.name]: noRawNav,
 };
 
 // ── File-scoped allowances ──────────────────────────────────────────────────────

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

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { TopBar, 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: 'downloads', label: 'Downloads', icon: <Glyph name='downloads' />, href: '/downloads' },
+];
+
+const brand = { icon: <Glyph name='brand' />, label: 'Music', href: '/' };
+
+describe('TopBar — icons, not words (owner, 2026-09-25)', () => {
+  test('🔴 an item paints its ICON and no words; the label is its accessible name', () => {
+    const { getByRole } = render(<TopBar brand={brand} items={items} />);
+    const link = getByRole('link', { name: 'Downloads' });
+    expect(link.querySelector('[data-glyph="downloads"]')).not.toBeNull();
+    // No text at all inside the link — the word lives only in aria-label.
+    expect(link.textContent).toBe('');
+    expect(link.getAttribute('href')).toBe('/downloads');
+  });
+
+  test('the active place is lit and announced as the current page', () => {
+    const { getByRole } = render(<TopBar brand={brand} items={items} />);
+    expect(getByRole('link', { name: 'Library' }).getAttribute('aria-current')).toBe('page');
+    expect(getByRole('link', { name: 'Downloads' }).getAttribute('aria-current')).toBeNull();
+  });
+
+  test('words appear ONLY with a stated reason, and even then drop below sm', () => {
+    const withReason: TopBarItem[] = [{ ...items[1], wordsBecause: 'two identical glyphs side by side' }];
+    const { getByRole } = render(<TopBar brand={brand} items={withReason} />);
+    const words = Array.from(getByRole('link', { name: 'Downloads' }).querySelectorAll('span')).find(
+      (s) => s.textContent === 'Downloads',
+    );
+    expect(words?.className).toContain('hidden');
+    expect(words?.className).toContain('sm:inline');
+    const blank: TopBarItem[] = [{ ...items[1], wordsBecause: '   ' }];
+    cleanup();
+    const again = render(<TopBar brand={brand} items={blank} />);
+    expect(again.getByRole('link', { name: 'Downloads' }).textContent).toBe('');
+  });
+
+  test('🔴 the row cannot widen the page: clamped, and the places scroll inside themselves', () => {
+    const { container } = render(<TopBar brand={brand} items={items} trailing={<span data-trailing=''>x</span>} />);
+    const bar = container.querySelector('[data-cb-topbar]') as HTMLElement;
+    expect(bar.className).toContain('min-w-0');
+    expect(bar.className).toContain('max-w-full');
+    const nav = container.querySelector('[data-cb-topbar-nav]') as HTMLElement;
+    expect(nav.className).toContain('min-w-0');
+    // The places sit in a sideways ScrollArea inside the nav — the strip scrolls, never the page.
+    expect(nav.querySelector('[data-cb-scrollarea]')).not.toBeNull();
+    // Brand and trailing controls never shrink — the account menu stays reachable.
+    const brandLink = container.querySelector('[data-cb-topbar-brand]') as HTMLElement;
+    expect(brandLink.className).toContain('shrink-0');
+    expect((nav.nextElementSibling as HTMLElement).className).toContain('shrink-0');
+  });
+
+  test('the brand is a link named by its label; its word is painted only from md up', () => {
+    const { getByRole } = render(<TopBar brand={brand} items={items} />);
+    const link = getByRole('link', { name: 'Music' });
+    const word = Array.from(link.querySelectorAll('span')).find((s) => s.textContent === 'Music');
+    expect(word?.className).toContain('hidden md:inline');
+  });
+
+  test('link props pass through — an SPA router can intercept the click', () => {
+    let clicked = '';
+    const routed: TopBarItem[] = [
+      { ...items[1], href: '/downloads', linkProps: { onClick: (e) => { e.preventDefault(); clicked = 'downloads'; } } },
+    ];
+    const { getByRole } = render(<TopBar brand={brand} items={routed} />);
+    fireEvent.click(getByRole('link', { name: 'Downloads' }));
+    expect(clicked).toBe('downloads');
+  });
+});

package/src/react/nav/TopBar.tsx

@@ -0,0 +1,153 @@
+import type { AnchorHTMLAttributes, ReactNode } from 'react';
+import { ScrollArea } from '../components/ScrollArea.js';
+import { Tooltip } from '../components/Tooltip.js';
+import { useScrollEdgeFade } from '../hooks/useScrollEdgeFade.js';
+import { cn } from '../lib/cn.js';
+import { TAP_TARGET_SQUARE } from '../lib/tapTarget.js';
+
+/** What an `<a>` in the bar is handed — `href`, `onClick`, whatever the app's router needs. */
+export type TopBarLinkProps = Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  'children' | 'className' | 'aria-label' | 'href'
+>;
+
+export interface TopBarItem {
+  /** Stable key. */
+  id: string;
+  /** The place's name. It is the accessible name and the hover hint — it is NOT painted. */
+  label: string;
+  /** The glyph that IS the item. Required: an item without one cannot be drawn in this bar. */
+  icon: ReactNode;
+  /** The place the user is in. Lit, 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.
+   */
+  wordsBecause?: 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. */
+  items: readonly TopBarItem[];
+  /** The trailing cluster: theme toggle, account menu. Never shrinks. */
+  trailing?: ReactNode;
+  /** 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.
+ *
+ * ── 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.
+ *
+ * `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, navLabel = 'Places', className }: TopBarProps) {
+  const fade = useScrollEdgeFade();
+  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)}
+    >
+      <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'
+        >
+          <div className='flex w-max items-center gap-1'>
+            {items.map((item) => (
+              <TopBarLink key={item.id} item={item} />
+            ))}
+          </div>
+        </ScrollArea>
+      </nav>
+
+      {trailing ? <div className='flex shrink-0 items-center gap-1'>{trailing}</div> : null}
+    </header>
+  );
+}
+
+function TopBarLink({ item }: { item: TopBarItem }) {
+  const words = Boolean(item.wordsBecause?.trim());
+  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',
+        )}
+      >
+        <span aria-hidden='true' className='grid size-5 place-items-center [&_svg]:size-5'>
+          {item.icon}
+        </span>
+        {words ? (
+          <span aria-hidden='true' className='hidden text-sm font-medium sm:inline'>
+            {item.label}
+          </span>
+        ) : null}
+      </a>
+    </Tooltip>
+  );
+}

package/src/react/nav/index.ts

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

package/src/styles-areas/nav.css

@@ -18,14 +18,15 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 99 candidate(s).
+ * 107 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("-mt-5 -top-1 [&>*]:min-w-0 [&_svg]:size-3.5 bg-accent/15 border-border/40 border-dashed border-l");
-@source inline("border-r collapse cursor-grab data-[state=checked]:ring-2 data-[state=checked]:ring-foreground");
+@source inline("-mt-5 -top-1 [&::-webkit-scrollbar]:hidden [&>*]:min-w-0 [&_svg]:size-3.5 [scrollbar-width:none]");
+@source inline("bg-accent/15 border-border/40 border-dashed border-l border-r collapse cursor-grab");
+@source inline("data-[state=checked]:ring-2 data-[state=checked]:ring-foreground");
 @source inline("data-[state=checked]:ring-offset-1 data-[state=closed]:slide-out-to-bottom");
 @source inline("data-[state=closed]:slide-out-to-left data-[state=closed]:slide-out-to-right");
 @source inline("data-[state=open]:slide-in-from-bottom data-[state=open]:slide-in-from-left");
@@ -36,8 +37,9 @@
 @source inline("items-stretch justify-around justify-start lead leading-4 left-0 left-3 lg:flex lg:flex-col");
 @source inline("lg:hidden lg:shrink-0 line-clamp-2 max-h-72 max-h-[40dvh] max-h-[65dvh] max-h-[85dvh]");
 @source inline("max-h-[inherit] max-sm:flex-none max-sm:justify-center max-sm:px-0 max-sm:w-10 max-w max-w-64");
-@source inline("max-w-[12rem] max-w-[20rem] md:flex md:flex-col md:hidden md:shrink-0 min-h-12 min-h-dvh");
-@source inline("min-w-3.5 min-w-8 mix-blend-difference mt-auto opacity-55 opacity-80 pb-1 pb-2");
-@source inline("pb-[env(safe-area-inset-bottom,0px)] pl-9 place-items-center pr-9 pt-1 px-0.5 right-1");
-@source inline("rounded-l-xl rounded-r-xl rounded-t-xl shadow-lg size-7 size-9 sm:inline sm:inline-flex");
-@source inline("space-y-0.5 space-y-2 text-[0.625rem] top-2 w-0.5 w-52 w-56 w-60");
+@source inline("max-w-[12rem] max-w-[20rem] md:flex md:flex-col md:gap-3 md:hidden md:pointer-coarse:w-auto");
+@source inline("md:px-6 md:shrink-0 min-h-12 min-h-dvh min-w-3.5 min-w-8 min-w-9 mix-blend-difference mt-auto");
+@source inline("opacity-55 opacity-80 pb-1 pb-2 pb-[env(safe-area-inset-bottom,0px)] pl-9 place-items-center");
+@source inline("pr-9 pt-1 px-0.5 right-1 rounded-l-xl rounded-r-xl rounded-t-xl shadow-lg size-7 size-9");
+@source inline("sm:inline sm:inline-flex sm:pointer-coarse:w-auto space-y-0.5 space-y-2 text-[0.625rem] top-2");
+@source inline("w-0.5 w-52 w-56 w-60 w-max");

package/src/styles-utilities.css

@@ -1015,6 +1015,9 @@
   .min-w-8 {
     min-width: calc(var(--spacing) * 8);
   }
+  .min-w-9 {
+    min-width: calc(var(--spacing) * 9);
+  }
   .min-w-10 {
     min-width: calc(var(--spacing) * 10);
   }
@@ -4080,6 +4083,9 @@
     .md\:flex-row {
       flex-direction: row;
     }
+    .md\:gap-3 {
+      gap: calc(var(--spacing) * 3);
+    }
     :where(.md\:divide-x > :not(:last-child)) {
       --tw-divide-x-reverse: 0;
       border-inline-style: var(--tw-border-style);
@@ -4089,6 +4095,9 @@
     :where(.md\:divide-border > :not(:last-child)) {
       border-color: var(--border);
     }
+    .md\:px-6 {
+      padding-inline: calc(var(--spacing) * 6);
+    }
   }
   @media (width >= 64rem) {
     .lg\:inset-8 {
@@ -4313,6 +4322,20 @@
       translate: var(--tw-translate-x) var(--tw-translate-y);
     }
   }
+  @media (width >= 40rem) {
+    @media (pointer: coarse) {
+      .sm\:pointer-coarse\:w-auto {
+        width: auto;
+      }
+    }
+  }
+  @media (width >= 48rem) {
+    @media (pointer: coarse) {
+      .md\:pointer-coarse\:w-auto {
+        width: auto;
+      }
+    }
+  }
   .\[\&_\.alert-icon\]\:text-accent .alert-icon {
     color: var(--accent);
   }