basalt-ui 1.18.0 → 1.19.1

package/dist/tokens/palette.d.ts

@@ -495,6 +495,17 @@ declare const SPACE_STEP_BASE: {
     readonly appShellNavbarRailWidth: 48;
     /** Tab's icon-to-label gap. */
     readonly mobileNavTabGap: 3;
+    /** Bar height, EXCLUDING the safe-area inset — Mantine's own `AppShell.footer` rule adds
+     *  `env(safe-area-inset-bottom)` to it. JS-consumed (AppShell `footer.height`), no `--vx-*` var,
+     *  same shape as `appShellHeaderHeight`. Floored at 48px in `deriveSpacing`. */
+    readonly mobileNavBarHeight: 56;
+    /** Slot icon box. */
+    readonly mobileNavIconSize: 24;
+    /** Menu/sheet row height. Floored at 44px in `deriveSpacing` (Apple HIG 44pt / WCAG 2.5.5 AAA). */
+    readonly mobileNavRowHeight: 44;
+    /** More/group `<Menu width={…}>`. JS-consumed, no var — same rationale as
+     *  `sidebarSettingsMenuWidth` directly above. */
+    readonly mobileNavMenuWidth: 232;
     /** `ChartLegend`'s column/row gap (`VX.legendGap`). */
     readonly chartLegendGap: 22;
     /** Chart plot-area margin, top (`VX.margin.top`). */
@@ -870,6 +881,10 @@ export declare const SPACE_STEP: {
     readonly appShellNavbarWidth: number;
     readonly appShellNavbarRailWidth: number;
     readonly mobileNavTabGap: number;
+    readonly mobileNavBarHeight: number;
+    readonly mobileNavIconSize: number;
+    readonly mobileNavRowHeight: number;
+    readonly mobileNavMenuWidth: number;
     readonly chartLegendGap: number;
     readonly chartMarginTop: number;
     readonly chartMarginRight: number;

package/dist/tokens/palette.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"palette.d.ts","sourceRoot":"","sources":["../../src/tokens/palette.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"palette.d.ts","sourceRoot":"","sources":["../../src/tokens/palette.ts"],"names":[],"mappings":"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"}

package/dist/tokens/palette.js

@@ -410,6 +410,17 @@ const SPACE_STEP_BASE = {
   // ── shell/app-mobile-nav.module.css ───────────────────────────────────────────────────────────
   /** Tab's icon-to-label gap. */
   mobileNavTabGap: 3,
+  /** Bar height, EXCLUDING the safe-area inset — Mantine's own `AppShell.footer` rule adds
+   *  `env(safe-area-inset-bottom)` to it. JS-consumed (AppShell `footer.height`), no `--vx-*` var,
+   *  same shape as `appShellHeaderHeight`. Floored at 48px in `deriveSpacing`. */
+  mobileNavBarHeight: 56,
+  /** Slot icon box. */
+  mobileNavIconSize: 24,
+  /** Menu/sheet row height. Floored at 44px in `deriveSpacing` (Apple HIG 44pt / WCAG 2.5.5 AAA). */
+  mobileNavRowHeight: 44,
+  /** More/group `<Menu width={…}>`. JS-consumed, no var — same rationale as
+   *  `sidebarSettingsMenuWidth` directly above. */
+  mobileNavMenuWidth: 232,
   // ── charts (tokens/index.ts's `VX` object — structural, tracks density) ──────────────────────
   // `VX.lineWidth`/`VX.line2Width` are DELIBERATELY absent here — they are stroke WEIGHTS (line
   // thickness), not spacing/gaps/sizes, so they stay fixed regardless of density (see `VX` in
@@ -515,6 +526,8 @@ function deriveSpacing(level) {
   anchors.stackXl = stackUnit * 6;
   const mappedStep = mapSpaceGroup(SPACE_STEP_BASE, level, multiplier);
   mappedStep.sidebarSearchTriggerHeight = Math.max(24, mappedStep.sidebarSearchTriggerHeight);
+  mappedStep.mobileNavBarHeight = Math.max(48, mappedStep.mobileNavBarHeight);
+  mappedStep.mobileNavRowHeight = Math.max(44, mappedStep.mobileNavRowHeight);
   const step = {
     ...mappedStep,
     // RESPONSIVE, one per AppShell breakpoint — each DERIVED from its own header, plus

package/dist/tokens.css

@@ -95,6 +95,8 @@
   --vx-space-sidebar-child-row-indent: 12px;
   --vx-space-app-header-mobile-actions-height: 52px;
   --vx-space-mobile-nav-tab-gap: 3px;
+  --vx-space-mobile-nav-icon-size: 24px;
+  --vx-space-mobile-nav-row-height: 44px;
   --vx-space-agent-rail-inset-x: 10px;
   --vx-space-agent-part-gap-top: 6px;
   --vx-space-agent-code-inset: 8px;

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.18.0
+# basalt-ui v1.19.1
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.18.0
+Version: 1.19.1
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
@@ -65,7 +65,7 @@ OptionalPeers: @tanstack/react-query-devtools@^5.101.0
 
 ## basalt-ui/router-tanstack
 Import: import { ... } from 'basalt-ui/router-tanstack'
-Description: TanStack Router bridge: useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)
+Description: TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)
 Layer: headless
 Rule: basalt-router
 OptionalPeers: @tanstack/react-router@^1.170.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.18.0",
+  "version": "1.19.1",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/index.ts

@@ -24,21 +24,31 @@ export {
   type SidebarSearchConfig,
   SidebarAccount,
   MobileNav,
+  type MobileNavProps,
+  projectMobileNav,
+  type ProjectMobileNavOptions,
+  MOBILE_MAX_TABS_DEFAULT,
+  MOBILE_MENU_MAX_DEFAULT,
+  MOBILE_MORE_KEY,
   AppBreadcrumbs,
-  type BreadcrumbLinkRenderer,
   PageHeaderProvider,
   PageActions,
   PageActionsOutlet,
   type SidebarSection,
   type SidebarItem,
+  type NavAnchor,
+  type NavAnchorProps,
+  type NavMobilePlacement,
+  type NavSectionMobile,
+  type MobileNavConfig,
+  type MobileNavGroup,
+  type MobileNavModel,
+  type MobileNavSlot,
+  type MobileNavSurface,
   type BasaltShellProps,
   type BrandConfig,
   type SettingsMenuItem,
   type AppSidebarProps,
-  type MobileNavItem,
-  type MobileNavSection,
-  type NavLinkRenderer,
-  type MobileNavLinkRenderer,
   type AccountBadgeTone,
   type BasaltIdentity,
   type BasaltRole,

package/src/nav/types.ts

@@ -0,0 +1,115 @@
+/**
+ * The shared nav vocabulary. TYPE-ONLY BY CONTRACT — never add a value export here.
+ * `src/shell/**` (Mantine) and `src/router-tanstack/**` (headless) both `import type` from it,
+ * which is erased by tsup, so `dist/router-tanstack/index.js` gains no edge into `shell/` and
+ * `scripts/check-dist-layering.mjs` stays green with no config change.
+ */
+import type { MouseEvent, ReactNode } from 'react'
+
+/** Where a destination appears on the mobile bar. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. */
+export type NavMobilePlacement = 'tab' | 'more' | 'hidden'
+
+/**
+ * Props basalt hands a nav anchor. Deliberately a PLAIN FUNCTION TYPE, not `ComponentType`
+ * or `ElementType`: both are unions, and a union defeats Mantine's polymorphic `component`
+ * inference (`<NavLink component={…}>` then rejects `label`). VERIFIED both ways.
+ */
+export type NavAnchorProps = {
+  className?: string
+  children?: ReactNode
+  onClick?: (e: MouseEvent<HTMLElement>) => void
+  'aria-current'?: 'page' | undefined
+  'aria-label'?: string
+}
+export type NavAnchor = (props: NavAnchorProps) => ReactNode
+
+/** A single nav destination. */
+export type SidebarItem = {
+  key: string
+  label: string
+  /** Bar/menu label. Falls back to `label`. Keep ≤ 10 chars — a 5-slot bar is ~72px wide. */
+  short?: string
+  /** Mobile placement. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. @default 'more' */
+  mobile?: boolean | NavMobilePlacement
+  icon: ReactNode
+  /**
+   * The router seam. basalt renders every pixel of chrome (desktop row, 56px slot, 44px sheet
+   * row) and only hosts this component. When absent the row falls back to `<a href>` + `onClick`.
+   */
+  Anchor?: NavAnchor
+  /** Plain href — the no-router fallback, and the breadcrumb parent target. */
+  href?: string
+  active?: boolean
+  disabled?: boolean
+  onClick?: (e: MouseEvent) => void
+  /** Rich desktop badge (e.g. `NavCountBadge`). Desktop only. */
+  badge?: ReactNode
+  /** Unread count. Renders `NavCountBadge` on desktop when `badge` is absent, and an accent
+   *  dot on the mobile slot icon. `0` renders nothing. */
+  count?: number
+  children?: SidebarItem[]
+}
+
+/** Per-section mobile configuration. `false` hides the whole section from mobile. */
+export type NavSectionMobile = {
+  /** Give this SECTION a bar slot; its destinations open per §2.2 cardinality inference. */
+  tab?: true
+  /** Slot label override; falls back to `SidebarSection.label`. */
+  label?: string
+  /** Slot icon override; falls back to `SidebarSection.icon`. */
+  icon?: ReactNode
+}
+
+export type SidebarSection = {
+  label: string
+  items: SidebarItem[]
+  icon?: ReactNode
+  collapsible?: boolean
+  defaultCollapsed?: boolean
+  /** Mobile behaviour for this section. Omit for the default (items place themselves). */
+  mobile?: false | NavSectionMobile
+}
+
+export type MobileNavSurface = 'link' | 'menu' | 'sheet'
+
+/** One row inside a `menu`/`sheet` slot, grouped under its source section. */
+export type MobileNavGroup = { key: string; label?: string; items: SidebarItem[] }
+
+export type MobileNavSlot =
+  | {
+      kind: 'link'
+      key: string
+      label: string
+      short: string
+      icon: ReactNode
+      active: boolean
+      item: SidebarItem
+    }
+  | {
+      kind: 'menu' | 'sheet'
+      key: string
+      label: string
+      short: string
+      icon: ReactNode
+      active: boolean
+      groups: MobileNavGroup[]
+      isMore: boolean
+    }
+
+/** Pure projection of `sections` onto the bar. Unit-testable with no DOM. */
+export type MobileNavModel = { slots: MobileNavSlot[] }
+
+export type MobileNavConfig = {
+  /** Explicit slot order by item/section key. Overrides every `item.mobile` placement. */
+  tabs?: readonly string[]
+  /** Hard cap on bar slots, INCLUDING More. @default 5 */
+  maxTabs?: number
+  /** Rows a slot may hold before it becomes a sheet instead of a menu. @default 6 */
+  menuMax?: number
+  /** @default 'More' */
+  moreLabel?: string
+  /** Extra content pinned to the bottom of the More surface. */
+  moreExtra?: ReactNode
+  /** Scroll container for active-slot re-tap. @default document.scrollingElement */
+  getScrollElement?: () => HTMLElement | null
+}

package/src/router-tanstack/index.ts

@@ -1,8 +1,10 @@
 /**
  * ./router-tanstack — headless TanStack Router bridge for the app shell.
  * Optional peer: @tanstack/react-router.
- * Augments StaticDataRouteOption with title/icon/navSection for breadcrumb
- * and nav-active wiring — no Mantine, no JSX, no navigate() helper.
+ * Carries the typed navigation definition (`defineNav`/`navGroup`/`navTarget`/`flattenNav`) and
+ * `useNav`, which resolves it into `BasaltShell`'s `sections` + `mobileNav` props; plus the
+ * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs and
+ * the search-param stores — no Mantine, no JSX.
  */
 
 export {
@@ -15,6 +17,23 @@ export {
   type MultiSearchParamStore,
   type MultiSearchParamStoreOptions,
 } from './multi-search-param-store'
+export { defineNav, navGroup, navTarget, flattenNav } from './nav'
+export type {
+  NavItemMeta,
+  NavGroupMeta,
+  AnyNavItem,
+  AnyNavGroup,
+  AnyNavLink,
+  FlatNavItem,
+  NavConfig,
+  NavItemId,
+  NavGroupId,
+  NavTabId,
+  NavIndex,
+} from './nav'
+export { useNav } from './use-nav'
+export type { UseNavOptions, NavBinding } from './use-nav'
+export type { NavAnchor, NavAnchorProps, NavMobilePlacement } from '../nav/types'
 import type { ReactNode } from 'react'
 import { useLocation, useMatches } from '@tanstack/react-router'
 

package/src/router-tanstack/nav.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from 'bun:test'
+import { defineNav, flattenNav, navGroup, navTarget } from './nav'
+
+/**
+ * The definition below is deliberately built with the real builders (not object literals) so the
+ * runtime-identity assertions below prove the builders are erased at runtime — every bit of value
+ * they add is compile-time. The type-level half of the contract lives in the playground's
+ * `nav.type-guard.ts` fixture, which is where a registered router exists to validate `to` against.
+ */
+const NAV = defineNav({
+  groups: [
+    navGroup({ id: 'main', label: 'Main' }, [
+      { id: 'dash', label: 'Dashboard', short: 'Home', mobile: 'tab', link: { to: '/dashboard' } },
+      {
+        id: 'reports',
+        label: 'Reports',
+        link: { to: '/reports' },
+        children: [
+          { id: 'reports-daily', label: 'Daily', link: { to: '/reports/daily' } },
+          { id: 'reports-weekly', label: 'Weekly', link: { to: '/reports/weekly' } },
+        ],
+      },
+    ]),
+    navGroup({ id: 'system', label: 'System', collapsible: true }, [
+      { id: 'usage', label: 'Usage', disabled: true, link: { to: '/usage', search: { r: '30d' } } },
+    ]),
+  ],
+})
+
+describe('defineNav / navGroup', () => {
+  test('defineNav is runtime identity — it returns the very object it was given', () => {
+    const config = { groups: [] } as const
+    expect(defineNav(config)).toBe(config)
+  })
+
+  test('navGroup merges meta and items into one plain object, preserving item order', () => {
+    const group = navGroup({ id: 'g', label: 'G', collapsible: true }, [
+      { id: 'a', label: 'A', link: { to: '/a' } },
+      { id: 'b', label: 'B', link: { to: '/b' } },
+    ])
+    expect(group).toEqual({
+      id: 'g',
+      label: 'G',
+      collapsible: true,
+      items: [
+        { id: 'a', label: 'A', link: { to: '/a' } },
+        { id: 'b', label: 'B', link: { to: '/b' } },
+      ],
+    })
+  })
+
+  test('navGroup does not mutate the meta object it was handed', () => {
+    const meta = { id: 'g', label: 'G' }
+    navGroup(meta, [{ id: 'a', label: 'A', link: { to: '/a' } }])
+    expect(meta).toEqual({ id: 'g', label: 'G' })
+  })
+})
+
+describe('flattenNav', () => {
+  test('walks depth-first — parent immediately before its own children', () => {
+    expect(flattenNav(NAV).map((d) => d.id)).toEqual([
+      'dash',
+      'reports',
+      'reports-daily',
+      'reports-weekly',
+      'usage',
+    ])
+  })
+
+  test('tags every destination — including nested children — with its declaring group', () => {
+    const byId = new Map(flattenNav(NAV).map((d) => [d.id, d]))
+    expect(byId.get('dash')).toMatchObject({ groupId: 'main', groupLabel: 'Main' })
+    expect(byId.get('reports-weekly')).toMatchObject({ groupId: 'main', groupLabel: 'Main' })
+    expect(byId.get('usage')).toMatchObject({ groupId: 'system', groupLabel: 'System' })
+  })
+
+  test('carries the authored metadata through untouched', () => {
+    const dash = flattenNav(NAV)[0]
+    expect(dash).toMatchObject({
+      label: 'Dashboard',
+      short: 'Home',
+      mobile: 'tab',
+      link: { to: '/dashboard' },
+    })
+  })
+
+  test('an empty definition flattens to an empty list', () => {
+    expect(flattenNav({ groups: [] })).toEqual([])
+  })
+})
+
+describe('navTarget', () => {
+  test('returns the destination link options by id', () => {
+    expect(navTarget(NAV, 'dash')).toEqual({ to: '/dashboard' })
+    expect(navTarget(NAV, 'usage')).toEqual({ to: '/usage', search: { r: '30d' } })
+  })
+
+  test('returns the SAME object the definition holds — spreadable with no copy', () => {
+    expect(navTarget(NAV, 'dash')).toBe(NAV.groups[0].items[0].link)
+  })
+
+  test('resolves ids nested under a parent destination', () => {
+    expect(navTarget(NAV, 'reports-weekly')).toEqual({ to: '/reports/weekly' })
+  })
+
+  test('throws a named error on an unknown id', () => {
+    // The id union makes this a compile error for a consumer; the throw is the runtime backstop
+    // for the untyped edge (a dynamic id, or an unregistered router degrading `NavItemId` away).
+    expect(() => navTarget(NAV, 'zzz' as 'dash')).toThrow('navTarget: no nav item with id "zzz"')
+  })
+})

package/src/router-tanstack/nav.ts

@@ -0,0 +1,205 @@
+/**
+ * Typed navigation definition. Wraps TanStack's own `linkOptions` rather than reimplementing its
+ * validator, so `to` / `search` / `params` get the router's full checking, and nav metadata rides
+ * OUTSIDE the validated object in a sibling `link:` key.
+ *
+ * Why not flat (`{ id, label, to, search }`) via a carrier `TComp` over `ValidateLinkOptions`:
+ * `Constrain<T, C> = (T extends C ? T : never) | C` is an ASSIGNABILITY check, and assignability
+ * does not do excess-property checking — so `{ id, label, to: '/charts', colour: 'red' }` compiles
+ * silently. Compile-verified. A config whose selling point is "typos are compile errors" cannot
+ * have a hole exactly where metadata typos live.
+ *
+ * No JSX and no Mantine in this module — `./router-tanstack` is a headless barrel by contract.
+ */
+import type { ReactNode } from 'react'
+import type { NavMobilePlacement, NavSectionMobile } from '../nav/types'
+
+// ── authoring shapes ─────────────────────────────────────────────────────────────────────────────
+
+export type NavItemMeta = {
+  id: string
+  label: string
+  /** Bar/menu label. Falls back to `label`. */
+  short?: string
+  icon?: ReactNode
+  disabled?: boolean
+  /** Mobile placement. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. @default 'more' */
+  mobile?: boolean | NavMobilePlacement
+  /** Active on an exact path match only. Default: prefix (`fuzzy: true`). `'/'` is always exact. */
+  exact?: boolean
+}
+
+export type NavGroupMeta = {
+  id: string
+  label: string
+  icon?: ReactNode
+  collapsible?: boolean
+  defaultCollapsed?: boolean
+  mobile?: false | NavSectionMobile
+}
+
+/** Widened read shapes. The framework reads through these; a consumer never writes them. */
+export type AnyNavLink = { to: string; search?: unknown; params?: unknown }
+export type AnyNavItem = NavItemMeta & { link: AnyNavLink; children?: ReadonlyArray<AnyNavItem> }
+export type AnyNavGroup = NavGroupMeta & { items: ReadonlyArray<AnyNavItem> }
+
+// ── inference machinery ──────────────────────────────────────────────────────────────────────────
+
+/** Exact-object check: any key outside `Shape` is typed `never`, which surfaces as an error. */
+export type Exact<T, Shape> = T & { readonly [K in Exclude<keyof T, keyof Shape>]: never }
+
+/**
+ * `Exact` for ONE item, recursing into `children`.
+ *
+ * The recursion is the whole point: `AnyNavItem['children']` is a plain
+ * `ReadonlyArray<AnyNavItem>` constraint, and a constraint is an assignability check — so a
+ * top-level-only `Exact` leaves the metadata-typo hole wide open exactly one level down
+ * (`children: [{ id, label, colour: 'red', link }]` compiled silently). Reapplying `Exact` per
+ * child, at every depth, is what makes the nested `link:` design actually deliver "every typo is a
+ * compile error" rather than "every typo in the top row is a compile error".
+ *
+ * The `[K in Extract<keyof T, 'children'>]` form rather than a `children?:` property is what keeps
+ * this inference-safe: it evaluates to `{}` for an item that declares no children (so no phantom
+ * key is added to the checked shape and nothing becomes required), and the intersection with
+ * `Exact<T, AnyNavItem>` keeps `T` in a naked inference position so the caller's literal types
+ * still flow out of `navGroup`'s `const T`.
+ */
+export type ExactNavItem<T> = Exact<T, AnyNavItem> & {
+  readonly [K in Extract<keyof T, 'children'>]: T[K] extends ReadonlyArray<AnyNavItem>
+    ? NavItemsInput<T[K]>
+    : T[K]
+}
+
+/** Per-element `Exact` over a tuple of items, so an unknown key errors at the item that owns it. */
+export type NavItemsInput<T extends ReadonlyArray<AnyNavItem>> = {
+  readonly [K in keyof T]: ExactNavItem<T[K]>
+}
+
+type ItemsOf<G> = G extends ReadonlyArray<{ items: ReadonlyArray<infer I> }> ? I : never
+
+/**
+ * One item plus every descendant, at arbitrary depth. Recursive so the TYPE side matches what
+ * `findById` / `flattenNav` already do at RUNTIME — a one-level walk made `navTarget(nav,
+ * 'grandchild')` a compile error against an id the runtime resolves fine.
+ */
+type WithDescendants<I> =
+  | I
+  | (I extends { children: ReadonlyArray<infer C> } ? WithDescendants<C> : never)
+
+type AllItemsOf<G> = WithDescendants<ItemsOf<G>>
+
+/**
+ * id → link options, as a mapped type with key remapping. Do NOT replace this with
+ * `Extract<AllItemsOf<G>, { id: K }>['link']` — that form was compile-tested and returns the
+ * WHOLE union, silently losing per-id precision.
+ */
+export type NavIndex<G> = {
+  [I in AllItemsOf<G> as I extends { id: infer K extends string } ? K : never]: I extends {
+    link: infer L
+  }
+    ? L
+    : never
+}
+
+/**
+ * The literal union of every addressable destination id in a definition — parents, children and
+ * grandchildren alike, at ARBITRARY depth, matching what `findById` / `flattenNav` resolve at
+ * runtime. Verified to seven levels of `children` with no instantiation-depth complaint.
+ *
+ * If this ever resolves to plain `string`, the entire nav API validates nothing while reporting
+ * zero errors — so any change to the generics above must be re-checked against
+ * `apps/playground/src/nav.type-guard.tsx`, whose `@ts-expect-error` rows go UNUSED (TS2578) the
+ * moment the union widens.
+ */
+export type NavItemId<G> = Extract<keyof NavIndex<G>, string>
+export type NavGroupId<G> = G extends ReadonlyArray<{ id: infer I }> ? I : never
+export type NavTabId<G> = NavItemId<G> | NavGroupId<G>
+
+export type NavConfig<
+  G extends ReadonlyArray<AnyNavGroup>,
+  T extends ReadonlyArray<NavTabId<G>>,
+> = {
+  groups: G
+  mobile?: {
+    /** Explicit bar order by item/group id. Omit to let each item's `mobile` field decide. */
+    tabs?: T
+    /** @default 5 */ maxTabs?: number
+    /** @default 6 */ menuMax?: number
+    /** @default 'More' */ moreLabel?: string
+  }
+}
+
+// ── builders (identity at runtime) ───────────────────────────────────────────────────────────────
+
+/**
+ * One nav group. `const M` on the meta is load-bearing: without it the group `id` widens to
+ * `string` from `NavGroupMeta` and `mobile.tabs` silently stops validating group ids.
+ */
+export function navGroup<const M extends NavGroupMeta, const T extends ReadonlyArray<AnyNavItem>>(
+  meta: Exact<M, NavGroupMeta>,
+  items: NavItemsInput<T>,
+): M & { items: T } {
+  return { ...(meta as M), items: items as unknown as T }
+}
+
+/**
+ * The whole navigation — desktop and mobile — in one inferred definition.
+ *
+ * There is deliberately NO compile-time cap on `mobile.tabs.length`. Both a
+ * `T extends … & { length: 0|1|2|3|4|5 }` constraint and a `tabs: T & MaxFive` property form were
+ * compile-tested: each makes the length check work but silently degrades `NavTabId<G>` to `string`,
+ * killing the far more valuable id-union validation. The cap is a runtime concern — the shell's
+ * `projectMobileNav` slices to `maxTabs` and DEV-warns about what it dropped.
+ */
+export function defineNav<
+  const G extends ReadonlyArray<AnyNavGroup>,
+  const T extends ReadonlyArray<NavTabId<G>>,
+>(config: NavConfig<G, T>): NavConfig<G, T> {
+  return config
+}
+
+// ── readers ──────────────────────────────────────────────────────────────────────────────────────
+
+function findById(items: ReadonlyArray<AnyNavItem>, id: string): AnyNavItem | undefined {
+  for (const item of items) {
+    if (item.id === id) return item
+    const hit = item.children ? findById(item.children, id) : undefined
+    if (hit) return hit
+  }
+  return undefined
+}
+
+/**
+ * The link options for one destination, by id. Spreadable into `<Link>`, `router.navigate()`
+ * and `redirect()`. This is what collapses a consumer's Spotlight commands and index redirect.
+ *
+ * `id` is the definition's literal id union (`NavItemId`) at any nesting depth, so a nested child
+ * or grandchild is addressable exactly like a top-level item — the type side and `findById`'s
+ * runtime walk agree.
+ */
+export function navTarget<
+  const C extends { groups: ReadonlyArray<AnyNavGroup> },
+  K extends NavItemId<C['groups']>,
+>(config: C, id: K): NavIndex<C['groups']>[K] {
+  for (const g of config.groups) {
+    const hit = findById(g.items, id)
+    if (hit) return hit.link as NavIndex<C['groups']>[K]
+  }
+  throw new Error(`navTarget: no nav item with id "${id}"`)
+}
+
+/** A flattened destination, tagged with the group it was declared in. */
+export type FlatNavItem = AnyNavItem & { groupId: string; groupLabel: string }
+
+/** Depth-first flatten, parent then children — the leaf every other surface reads. */
+export function flattenNav(config: { groups: ReadonlyArray<AnyNavGroup> }): FlatNavItem[] {
+  const out: FlatNavItem[] = []
+  const walk = (items: ReadonlyArray<AnyNavItem>, groupId: string, groupLabel: string): void => {
+    for (const item of items) {
+      out.push({ ...item, groupId, groupLabel })
+      if (item.children) walk(item.children, groupId, groupLabel)
+    }
+  }
+  for (const g of config.groups) walk(g.items, g.id, g.label)
+  return out
+}