cursedbelt-core 1.0.0

package/src/core/navigation/navigation.spec.ts

@@ -0,0 +1,388 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  CURRENT_NAV_PREFS_VERSION,
+  createCoverageTest,
+  deriveAllPaths,
+  deriveBreadcrumbTrail,
+  deriveDomainGroups,
+  deriveDomainItems,
+  deriveSearchCatalogue,
+  deriveSideNavDomains,
+  findCoverageGaps,
+  type GateFn,
+  groupCatalogueHits,
+  type LegacyNavPrefs,
+  migrateNavPreferences,
+  type NavGate,
+  type NavigationModel,
+  normalizeNavPath,
+  rankCatalogue,
+} from './index';
+
+// A representative slice of the ca IA: 6 domains + an Admin domain + ungrouped, with
+// deepLinkOnly + gated + tab-target items — enough to exercise every selector.
+const model: NavigationModel = {
+  domains: [
+    {
+      id: 'today',
+      label: 'Today',
+      icon: 'home',
+      path: '/',
+      groups: [
+        {
+          id: 'today-main',
+          label: 'At a glance',
+          items: [{ id: 'daily', path: '/daily', label: 'Daily' }],
+        },
+      ],
+    },
+    {
+      id: 'tools',
+      label: 'Tools',
+      icon: 'wrench',
+      path: '/tools',
+      groups: [
+        {
+          id: 'connectors',
+          label: 'Connectors',
+          items: [
+            { id: 'curl', path: '/tools#tab=curl', label: 'Curl', keywords: ['http', 'request'] },
+            { id: 'query', path: '/tools#tab=query', label: 'Query Builder' },
+          ],
+        },
+        {
+          id: 'utilities',
+          label: 'Utilities',
+          items: [
+            {
+              id: 'env-sets',
+              path: '/env-sets',
+              label: 'Env Sets',
+              keywords: ['environment', 'variables'],
+            },
+            { id: 'aliases', path: '/aliases', label: 'Shell Aliases' },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'play',
+      label: 'Play',
+      icon: 'gamepad',
+      path: '/games',
+      groups: [
+        {
+          id: 'generative',
+          label: 'Generative',
+          items: [
+            { id: 'fractal', path: '/games/fractal', label: 'Fractal', keywords: ['mandelbrot'] },
+            { id: 'comet', path: '/games/comet', label: 'Comet' },
+          ],
+        },
+        {
+          id: 'media',
+          label: 'Media',
+          items: [{ id: 'youtube', path: '/youtube', label: 'YouTube' }],
+        },
+      ],
+    },
+    {
+      id: 'admin',
+      label: 'Admin',
+      icon: 'shield',
+      path: '/admin',
+      gate: { requiresAuth: true, requiredRoles: ['admin', 'owner'] },
+      groups: [
+        {
+          id: 'admin-access',
+          label: 'Users & Access',
+          items: [
+            { id: 'admin-users', path: '/admin/users', label: 'Users' },
+            {
+              id: 'admin-vault',
+              path: '/admin/vault',
+              label: 'Vault',
+              gate: { hiddenInCtgr: true },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  ungrouped: [
+    { id: 'settings', path: '/settings', label: 'Settings', keywords: ['preferences'] },
+    { id: 'shared-space', path: '/shared/:id', label: 'Shared Space', deepLinkOnly: true },
+    { id: 'set-pw', path: '/set-initial-password', label: 'Set Password', deepLinkOnly: true },
+  ],
+};
+
+const allowAll: GateFn = () => true;
+// A signed-in, non-admin, ctgr-off gate.
+const userGate: GateFn = (g?: NavGate) => {
+  if (g?.requiresNoAuth) return false;
+  if (g?.requiredRoles && !g.requiredRoles.includes('user')) return false;
+  return true;
+};
+
+describe('normalizeNavPath', () => {
+  test('strips hash, query, trailing slash; preserves root', () => {
+    expect(normalizeNavPath('/tools#tab=curl')).toBe('/tools');
+    expect(normalizeNavPath('/lists/?q=1')).toBe('/lists');
+    expect(normalizeNavPath('/')).toBe('/');
+    expect(normalizeNavPath('/admin/users')).toBe('/admin/users');
+  });
+});
+
+describe('deriveSideNavDomains', () => {
+  test('returns all domains under an allow-all gate', () => {
+    expect(deriveSideNavDomains(model, allowAll).map((d) => d.id)).toEqual([
+      'today',
+      'tools',
+      'play',
+      'admin',
+    ]);
+  });
+  test('drops role-gated domains the user cannot see', () => {
+    expect(deriveSideNavDomains(model, userGate).map((d) => d.id)).toEqual([
+      'today',
+      'tools',
+      'play',
+    ]);
+  });
+});
+
+describe('deriveDomainItems / deriveDomainGroups', () => {
+  const play = model.domains.find((d) => d.id === 'play')!;
+  test('flattens visible items across groups', () => {
+    expect(deriveDomainItems(play, allowAll).map((i) => i.id)).toEqual([
+      'fractal',
+      'comet',
+      'youtube',
+    ]);
+  });
+  test('groups keep their labels and only non-empty groups survive', () => {
+    const groups = deriveDomainGroups(play, allowAll);
+    expect(groups.map((g) => g.label)).toEqual(['Generative', 'Media']);
+    expect(groups[0]!.items.map((i) => i.id)).toEqual(['fractal', 'comet']);
+  });
+  test('a ctgr gate hides the flagged item', () => {
+    const admin = model.domains.find((d) => d.id === 'admin')!;
+    const ctgrGate: GateFn = (g?: NavGate) => !g?.hiddenInCtgr;
+    expect(deriveDomainItems(admin, ctgrGate).map((i) => i.id)).toEqual(['admin-users']);
+  });
+});
+
+describe('deriveBreadcrumbTrail', () => {
+  test('domain landing → [domain]', () => {
+    expect(deriveBreadcrumbTrail(model, '/tools').map((c) => c.label)).toEqual(['Tools']);
+  });
+  test('item → [domain, item] for ≥5 deep paths', () => {
+    expect(deriveBreadcrumbTrail(model, '/admin/users').map((c) => c.label)).toEqual([
+      'Admin',
+      'Users',
+    ]);
+    expect(deriveBreadcrumbTrail(model, '/games/fractal').map((c) => c.label)).toEqual([
+      'Play',
+      'Fractal',
+    ]);
+    expect(deriveBreadcrumbTrail(model, '/env-sets').map((c) => c.label)).toEqual([
+      'Tools',
+      'Env Sets',
+    ]);
+    expect(deriveBreadcrumbTrail(model, '/youtube').map((c) => c.label)).toEqual([
+      'Play',
+      'YouTube',
+    ]);
+    expect(deriveBreadcrumbTrail(model, '/daily').map((c) => c.label)).toEqual(['Today', 'Daily']);
+  });
+  test('a tab-target path resolves to its own leaf', () => {
+    expect(deriveBreadcrumbTrail(model, '/tools#tab=curl').map((c) => c.label)).toEqual([
+      'Tools',
+      'Curl',
+    ]);
+  });
+  test('ungrouped item → [item]; unknown → []', () => {
+    expect(deriveBreadcrumbTrail(model, '/settings').map((c) => c.label)).toEqual(['Settings']);
+    expect(deriveBreadcrumbTrail(model, '/nope')).toEqual([]);
+  });
+});
+
+describe('deriveSearchCatalogue + rankCatalogue', () => {
+  const catalogue = deriveSearchCatalogue(model, allowAll);
+
+  test('every visible domain + item is catalogued; deepLinkOnly is excluded', () => {
+    const ids = catalogue.map((e) => e.id);
+    expect(ids).toContain('fractal');
+    expect(ids).toContain('env-sets');
+    expect(ids).toContain('youtube');
+    expect(ids).toContain('settings');
+    // deepLinkOnly never surfaces in search
+    expect(ids).not.toContain('shared-space');
+    expect(ids).not.toContain('set-pw');
+  });
+
+  test('previously-buried features are now findable (parity check #3)', () => {
+    expect(rankCatalogue(catalogue, 'fractal')[0]?.path).toBe('/games/fractal');
+    expect(rankCatalogue(catalogue, 'env')[0]?.path).toBe('/env-sets');
+    expect(rankCatalogue(catalogue, 'youtube')[0]?.path).toBe('/youtube');
+    // keyword match
+    expect(rankCatalogue(catalogue, 'mandelbrot')[0]?.id).toBe('fractal');
+  });
+
+  test('exact label outranks substring; blank query → no hits', () => {
+    expect(rankCatalogue(catalogue, '')).toEqual([]);
+    const hits = rankCatalogue(catalogue, 'tools');
+    expect(hits[0]?.id).toBe('tools'); // the domain landing, exact label
+  });
+
+  test('groupCatalogueHits buckets by domain and caps to limit', () => {
+    const groups = groupCatalogueHits(catalogue, 'e', 3);
+    expect(groups.flatMap((g) => g.items).length).toBeLessThanOrEqual(3);
+  });
+
+  test('role-gated entries are absent under a non-admin gate', () => {
+    const userCat = deriveSearchCatalogue(model, userGate);
+    expect(userCat.map((e) => e.id)).not.toContain('admin-users');
+  });
+
+  test("a DOMAIN's description + keywords reach the catalogue, so a leaf-shaped rail is findable by synonym", () => {
+    // The asymmetry this closes: an app whose places are leaf domains (no
+    // sub-items) used to be searchable by exact label only, while an identical
+    // rail expressed as items matched synonyms — a data-model gap, not a ranking one.
+    const leafRail = deriveSearchCatalogue(
+      {
+        domains: [
+          {
+            id: 'changes',
+            label: 'Changes',
+            icon: 'git-compare-arrows',
+            path: '/changes',
+            description: 'Notes that changed at their source',
+            keywords: ['review', 'diff', 'merge'],
+            groups: [],
+          },
+        ],
+      },
+      allowAll,
+    );
+    expect(leafRail[0]?.description).toBe('Notes that changed at their source');
+    expect(rankCatalogue(leafRail, 'diff')[0]?.id).toBe('changes');
+    expect(rankCatalogue(leafRail, 'review')[0]?.id).toBe('changes');
+  });
+
+  test('a domain without them still catalogues cleanly (both stay optional)', () => {
+    const bare = deriveSearchCatalogue(
+      { domains: [{ id: 'x', label: 'X', icon: 'a', path: '/x', groups: [] }] },
+      allowAll,
+    );
+    expect(bare).toHaveLength(1);
+    expect('description' in (bare[0] ?? {})).toBe(false);
+    expect('keywords' in (bare[0] ?? {})).toBe(false);
+  });
+});
+
+describe('deriveAllPaths + createCoverageTest', () => {
+  test('all paths include deepLinkOnly entries', () => {
+    const paths = deriveAllPaths(model);
+    expect(paths).toContain('/shared/:id');
+    expect(paths).toContain('/set-initial-password');
+    expect(paths).toContain('/admin/users');
+  });
+
+  test('coverage passes when every route is registered', () => {
+    const routes = [
+      '/',
+      '/daily',
+      '/tools',
+      '/env-sets',
+      '/aliases',
+      '/games',
+      '/games/fractal',
+      '/games/comet',
+      '/youtube',
+      '/admin',
+      '/admin/users',
+      '/admin/vault',
+      '/settings',
+      '/shared/:id',
+      '/set-initial-password',
+    ];
+    expect(createCoverageTest(model, routes)).not.toThrow();
+  });
+
+  test('coverage FAILS when a route is missing from the model (negative — parity check #6)', () => {
+    const routes = ['/tools', '/brand-new-feature'];
+    expect(createCoverageTest(model, routes)).toThrow(/coverage gap/i);
+    expect(findCoverageGaps(model, routes)).toEqual(['/brand-new-feature']);
+  });
+
+  test('a tab-target model entry covers its base route', () => {
+    // The model only has /tools#tab=curl, but routes.tsx lists the base /tools route.
+    expect(findCoverageGaps(model, ['/tools'])).toEqual([]);
+  });
+});
+
+describe('migrateNavPreferences', () => {
+  // Old 8-hub world: planner + finance both consolidate into the new "plan" domain.
+  const legacy: LegacyNavPrefs = {
+    nav: {
+      order: ['planner', 'finance', 'games', 'youtube'],
+      colors: { games: '#f43f5e', finance: '#10b981' },
+    },
+    hiddenNavRoutes: ['youtube'],
+    hubs: {
+      planner: {
+        order: ['/calendar', '/alarms'],
+        hidden: ['/timeoff'],
+        colors: { '/calendar': '#3b82f6' },
+      },
+      finance: { order: ['/budgets'], colors: { '/budgets': '#f59e0b' } },
+      games: { order: ['/games/fractal'] },
+    },
+  };
+  const keyMap = {
+    planner: 'plan',
+    finance: 'plan',
+    games: 'play',
+    youtube: 'play',
+  };
+  // The migration target model (ids the legacy keys remap onto).
+  const target: NavigationModel = {
+    domains: [
+      { id: 'plan', label: 'Plan', icon: 'calendar', path: '/plan', groups: [] },
+      { id: 'play', label: 'Play', icon: 'gamepad', path: '/games', groups: [] },
+    ],
+  };
+
+  test('remaps 8 hubs → fewer domains, merging consolidated tile prefs (no data loss)', () => {
+    const next = migrateNavPreferences(legacy, target, { keyMap });
+    expect(next.version).toBe(CURRENT_NAV_PREFS_VERSION);
+    // order: planner+finance→plan (deduped), games+youtube→play
+    expect(next.order).toEqual(['plan', 'play']);
+    // hidden: youtube → play
+    expect(next.hidden).toEqual(['play']);
+    // colors: games→play, finance→plan
+    expect(next.colors).toEqual({ play: '#f43f5e', plan: '#10b981' });
+    // hubs: planner + finance MERGED into plan; games → play
+    expect(next.hubs?.plan?.order).toEqual(['/calendar', '/alarms', '/budgets']);
+    expect(next.hubs?.plan?.hidden).toEqual(['/timeoff']);
+    expect(next.hubs?.plan?.colors).toEqual({ '/calendar': '#3b82f6', '/budgets': '#f59e0b' });
+    expect(next.hubs?.play?.order).toEqual(['/games/fractal']);
+  });
+
+  test('drops keys whose target domain no longer exists', () => {
+    const next = migrateNavPreferences(
+      { nav: { order: ['gone'] }, hubs: { gone: { order: ['/x'] } } },
+      target,
+      { keyMap: { gone: 'nonexistent' } },
+    );
+    expect(next.order).toBeUndefined();
+    expect(next.hubs).toBeUndefined();
+  });
+
+  test('is idempotent — re-running on already-migrated prefs is a no-op', () => {
+    const once = migrateNavPreferences(legacy, target, { keyMap });
+    const twice = migrateNavPreferences(once, target, { keyMap });
+    expect(twice).toBe(once); // same reference, no re-mapping / no reset
+  });
+});

package/src/core/navigation/navigationModel.ts

@@ -0,0 +1,185 @@
+// The single navigation source of truth — a declarative Information-Architecture
+// tree (Domain → Group → Item) every nav surface derives from: the side nav, hub
+// landing tiles, breadcrumbs, the universal-search catalogue, and the command
+// palette. Authoring a feature into the model is the *only* way to surface it, so
+// the historical "four hand-maintained lists drift out of sync → features get
+// buried" bug is structurally impossible (the coverage test enforces it in CI).
+//
+// This module is **React-free and routing-free** (it ships from `cursedbelt-core/navigation`):
+// items carry icon *names* (strings) and *paths* (strings), never components or
+// `<Link>`s, so the same model is consumed by client components, server tests, and
+// the coverage test alike. The React layer (`cursedbelt/react`) resolves icon names
+// to nodes and paths to navigation.
+
+/**
+ * Visibility / eligibility gate carried by a domain or item. The model only stores
+ * the *flags*; the consuming app injects a {@link GateFn} that decides what they
+ * mean (is the user authed, do they hold the role, is the GET-only "ctgr" mode on).
+ * Gates are inherited: an item inside a gated-out domain never surfaces.
+ */
+export interface NavGate {
+  /** Only visible when signed in. */
+  requiresAuth?: boolean;
+  /** Only visible when signed out (public/marketing routes). */
+  requiresNoAuth?: boolean;
+  /** Visible only to users holding ONE of these roles (e.g. `['admin','owner']`). */
+  requiredRoles?: string[];
+  /** Hidden while the GET-only ("ctgr") session mode is active (write-heavy tools). */
+  hiddenInCtgr?: boolean;
+}
+
+/**
+ * A navigable leaf. `path` references a route (a `routeMeta` path in ca); use a
+ * `#tab=…` suffix for an in-page tab target (`/tools#tab=curl`) — the selectors
+ * strip the hash for route matching but keep it for navigation.
+ */
+export interface NavItem {
+  /** Stable unique key — the React key AND the key prefs (order/hide/color) store by. */
+  id: string;
+  /** Route destination. `#tab=…` addresses an in-page tab. */
+  path: string;
+  /** Display label (side nav row, hub tile title, breadcrumb leaf, search hit). */
+  label: string;
+  /** Icon *name* from the app's icon set (resolved to a node by the React layer). */
+  icon?: string;
+  /** Short description — hub-tile subtitle + search snippet. */
+  description?: string;
+  /** Auth / role / ctgr gate (see {@link NavGate}). */
+  gate?: NavGate;
+  /**
+   * Registered for coverage + deep-link reachability, but **never surfaced** in the
+   * side nav, hub tiles, search, or palette. For routes reachable only by a shared
+   * link, a notification, or a WS invite (Shared Space, `/watch/:type/:id`, auth
+   * routes, `/set-initial-password`, admin deep-links). Use deliberately — it is not
+   * a way to dodge the coverage test for a real, discoverable feature.
+   */
+  deepLinkOnly?: true;
+  /** Extra match terms for search / palette (synonyms, old names, abbreviations). */
+  keywords?: string[];
+}
+
+/** A labeled cluster of items inside a domain (a sub-section of a hub landing). */
+export interface NavGroup {
+  /** Stable unique key (within the model). */
+  id: string;
+  /** Section heading shown on the hub landing; omit-able visually when there's one. */
+  label: string;
+  items: NavItem[];
+}
+
+/**
+ * A top-level **place** — the browsable backbone (the UX north-star's small fixed
+ * place-set: Today / Library / People / Calendar / Play + a role-gated Operate; see
+ * `react/components/SHELL.md`). It is itself navigable (its `path` is the place
+ * landing) and owns the groups of items shown there. The shell renders these as the
+ * slim desktop place rail (`SideNav`) and the mobile capture-forward `PlaceBar`.
+ */
+/**
+ * A place that exists in the IA but CANNOT do its job on the host currently
+ * serving the page.
+ *
+ * The worked example is the station's "Vault" row: the prod mirror offers it
+ * identically to the local one, and clicking it there reaches a machine that does
+ * not hold the data. The owner's ruling (`owner-uis-are-one-ui`, 2026-08-13) is
+ * that the answer is never a second UI and never a hidden item:
+ *
+ *   *"Keeping two versions of UIs … is not a good long-term approach. I'd rather
+ *   a button that literally can't work in prod just be disabled but in the same
+ *   UI and with a message about why when I hover."*
+ *
+ * A hidden row teaches the reader the feature does not exist; a disabled row with
+ * a reason teaches them where to go. `UX_STANDARDS.md` §8.6 states it as a rule
+ * and no component carried it until unit 11.
+ *
+ * 🔴 "Too dangerous to expose" is NOT a host limit — Cloudflare Access already
+ * enforces owner-only at the edge. Only three things qualify: the destination
+ * points at the Mac, the bytes are not on this host, or it drives local
+ * hardware/the desktop.
+ */
+export interface NavHostLimit {
+  /** Why it cannot work here, in a sentence the owner would write. Shown on hover. */
+  reason: string;
+  /** Where it DOES work, if anywhere — "Open it on the Mac at localhost:4747". */
+  worksAt?: string;
+  /** Still let it be clicked (it degrades rather than failing). Default `false`. */
+  navigable?: boolean;
+}
+
+export interface NavDomain {
+  /** Stable unique key — prefs (order/hide/color) for the side-nav rail store by it. */
+  id: string;
+  /** Display label (side-nav row + hub landing title + breadcrumb root). */
+  label: string;
+  /** Icon *name* (required — domains always show an icon in the rail). */
+  icon: string;
+  /** The hub landing page path. */
+  path: string;
+  /** Domain-wide gate — inherited by every group/item under it. */
+  gate?: NavGate;
+  /**
+   * Short description — the hub-tile subtitle and the search/palette snippet, the
+   * same role it plays on a {@link NavItem}.
+   */
+  description?: string;
+  /**
+   * Extra match terms for search / palette (synonyms, old names, abbreviations) —
+   * again the same as on a {@link NavItem}.
+   *
+   * Both of these exist because a domain IS a destination: `deriveSearchCatalogue`
+   * emits one catalogue entry per domain, so a rail of leaf-shaped domains (an app
+   * whose places have no sub-items) had no way to be found by synonym while an
+   * otherwise identical rail of items did. That asymmetry was in the data model,
+   * not in the ranker.
+   */
+  keywords?: string[];
+  /**
+   * Optional rail section label. When any domain carries one, `SideNav` renders the
+   * rail as labeled, collapsible groups instead of one flat list — the fix for the
+   * "wall of 20+ flat items" rail (owner UX teardown 2026-07-15 §2). Domains without
+   * a section render first, ungrouped. Section order follows first appearance.
+   */
+  section?: string;
+  /**
+   * Mark this place as belonging in the mobile `PlaceBar`'s **thumb zone** — the
+   * flat row of tabs a phone shows, as opposed to the "More" bottom-sheet behind it.
+   * When ANY domain in the model is pinned, the `PlaceBar` fills the thumb zone from
+   * the pinned set (in declaration order, up to its `max` budget) and overflows the
+   * *unpinned* places to More — so the important destinations survive onto a phone
+   * regardless of where they sit in the rail order.
+   *
+   * The default (no domain pinned) is the historical behavior: the first `max - 1`
+   * places by declaration order ride the bar and the rest go to More. Reach for a pin
+   * when an app has more places than fit AND the ones that matter on a phone are not
+   * the first few — e.g. an Inbox declared after Media/Prompts (owner UX report
+   * 2026-08-04: the Inbox fell into More, and it is a place the owner opens).
+   *
+   * `SideNav` (the desktop rail) ignores this — the rail shows every place.
+   */
+  mobilePinned?: boolean;
+  /** Declare that this place cannot do its job on THIS host. It stays visible and
+   *  says why on hover, rather than vanishing. @see NavHostLimit */
+  hostLimit?: NavHostLimit;
+  groups: NavGroup[];
+}
+
+/**
+ * The complete IA tree. `domains` are the browsable backbone; `ungrouped` items are
+ * registered + searchable (and reachable by palette) but live under no domain hub —
+ * use it for cross-cutting destinations (Settings, Profile) or for `deepLinkOnly`
+ * routes that need coverage without a hub home.
+ */
+export interface NavigationModel {
+  domains: NavDomain[];
+  ungrouped?: NavItem[];
+}
+
+/**
+ * Injected by the app: decides whether a gated node is visible *right now* (auth
+ * state, the user's roles, the ctgr GET-only mode). Pure — the selectors call it for
+ * every domain/item, so it must be cheap and side-effect-free. An undefined gate
+ * (no restrictions) is always visible.
+ */
+export type GateFn = (gate?: NavGate) => boolean;
+
+/** The trivial gate — everything is visible. Default for selectors + unguarded apps. */
+export const allowAllGate: GateFn = () => true;