cursedbelt-core 1.0.0

package/src/core/navigation/navigationSelectors.ts

@@ -0,0 +1,206 @@
+// Pure derivations off the {@link NavigationModel}. Every nav surface (side nav,
+// hub tiles, breadcrumbs, search catalogue, palette, the coverage test) reads the
+// model exclusively through these — there is no second list to keep in sync. They
+// import nothing from React, so they run identically in the client, in a server
+// test, and in the CI coverage check.
+
+import {
+  allowAllGate,
+  type GateFn,
+  type NavDomain,
+  type NavGroup,
+  type NavItem,
+  type NavigationModel,
+} from './navigationModel';
+
+/**
+ * Normalize a path for route *matching* — drop the query string, the hash (the
+ * `#tab=…` in-page target), and a trailing slash. `'/'` stays `'/'`. Used so a tab
+ * variant (`/tools#tab=curl`) matches the base route (`/tools`) and `/lists/`
+ * matches `/lists`.
+ */
+export function normalizeNavPath(path: string): string {
+  // Null-safe: a nav selector must never throw (a breadcrumb derivation crashing
+  // white-screens the whole page). Coerce a missing/non-string path to ''.
+  const s = typeof path === 'string' ? path : '';
+  let p = (s.split('#')[0] ?? '').split('?')[0]?.trim() ?? '';
+  if (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+  return p || '/';
+}
+
+/** A flattened, gated catalogue entry — a leaf plus where it lives (for grouping). */
+export interface SearchCatalogueEntry extends NavItem {
+  /** Owning domain id (absent for ungrouped items). */
+  domainId?: string;
+  /** Owning domain label — groups search results + is itself matched. */
+  domainLabel?: string;
+  /** Owning group id (absent for domain landings + ungrouped items). */
+  groupId?: string;
+  /** Owning group label. */
+  groupLabel?: string;
+}
+
+/** One link in a breadcrumb trail — a coerced domain or item (always navigable). */
+export interface NavCrumb {
+  id: string;
+  label: string;
+  path: string;
+  icon?: string;
+}
+
+const domainCrumb = (d: NavDomain): NavCrumb => ({
+  id: d.id,
+  label: d.label,
+  path: d.path,
+  icon: d.icon,
+});
+const itemCrumb = (it: NavItem): NavCrumb => ({
+  id: it.id,
+  label: it.label,
+  path: it.path,
+  icon: it.icon,
+});
+
+/** The ordered domains visible under `gate` — the side-nav rail backbone. */
+export function deriveSideNavDomains(
+  model: NavigationModel,
+  gate: GateFn = allowAllGate,
+): NavDomain[] {
+  return (model?.domains ?? []).filter((d) => gate(d.gate));
+}
+
+/**
+ * Every visible (gated, non-`deepLinkOnly`) item of `domain`, flattened across its
+ * groups — for a simple HubTileGrid. Returns `[]` if the domain itself is gated out.
+ */
+export function deriveDomainItems(domain: NavDomain, gate: GateFn = allowAllGate): NavItem[] {
+  if (!gate(domain.gate)) return [];
+  return domain.groups.flatMap((g) => g.items).filter((it) => !it.deepLinkOnly && gate(it.gate));
+}
+
+/**
+ * The visible groups of `domain` (each with its visible items; empty groups
+ * dropped) — for a *grouped* hub landing that shows section headings. Returns `[]`
+ * if the domain is gated out.
+ */
+export function deriveDomainGroups(domain: NavDomain, gate: GateFn = allowAllGate): NavGroup[] {
+  if (!gate(domain.gate)) return [];
+  return domain.groups
+    .map((g) => ({ ...g, items: g.items.filter((it) => !it.deepLinkOnly && gate(it.gate)) }))
+    .filter((g) => g.items.length > 0);
+}
+
+/** Look up a domain by id (gated). */
+export function deriveDomain(
+  model: NavigationModel,
+  domainId: string,
+  gate: GateFn = allowAllGate,
+): NavDomain | undefined {
+  const d = (model?.domains ?? []).find((x) => x.id === domainId);
+  return d && gate(d.gate) ? d : undefined;
+}
+
+/**
+ * The ancestor chain for `path` — for Breadcrumbs. A domain landing yields
+ * `[domain]`; an item yields `[domain, item]`; an ungrouped item yields `[item]`.
+ * Matches the raw path first (so a `#tab=…` variant resolves to its own leaf), then
+ * falls back to the normalized base path. Returns `[]` when nothing matches.
+ */
+export function deriveBreadcrumbTrail(
+  model: NavigationModel,
+  path: string,
+  gate: GateFn = allowAllGate,
+): NavCrumb[] {
+  // Null-safe (see normalizeNavPath): a consumer that hasn't wired the model/path yet
+  // must get an empty trail, never a crash — a breadcrumb derivation throwing
+  // white-screens the whole page. Degrade gracefully on a missing model or path.
+  if (!model || !Array.isArray(model?.domains ?? [])) return [];
+  const safe = typeof path === 'string' ? path : '';
+  const raw = safe.trim();
+  const target = normalizeNavPath(safe);
+
+  // Two passes so an EXACT path wins over a merely-normalized one: `/tools#tab=curl`
+  // must resolve to the Curl tab leaf, not be shadowed by the `/tools` domain landing
+  // (which also normalizes to `/tools`). Within a pass, the domain landing is checked
+  // before its items so the bare `/tools` route yields `[Tools]`, not a tab leaf.
+  const find = (match: (p: string) => boolean): NavCrumb[] | null => {
+    for (const domain of model?.domains ?? []) {
+      if (!gate(domain.gate)) continue;
+      if (match(domain.path)) return [domainCrumb(domain)];
+      for (const group of domain.groups) {
+        for (const item of group.items) {
+          if (gate(item.gate) && match(item.path)) return [domainCrumb(domain), itemCrumb(item)];
+        }
+      }
+    }
+    for (const item of model.ungrouped ?? []) {
+      if (gate(item.gate) && match(item.path)) return [itemCrumb(item)];
+    }
+    return null;
+  };
+
+  return find((p) => p === raw) ?? find((p) => normalizeNavPath(p) === target) ?? [];
+}
+
+/**
+ * The flat list of searchable destinations — every visible (gated,
+ * non-`deepLinkOnly`) domain landing + item, each tagged with its domain/group so
+ * results can be grouped. Drives HeaderSearch's instant pages layer *and* the
+ * command palette; replaces every hand-listed search catalogue (so a feature is
+ * findable the moment it's registered).
+ */
+export function deriveSearchCatalogue(
+  model: NavigationModel,
+  gate: GateFn = allowAllGate,
+): SearchCatalogueEntry[] {
+  const out: SearchCatalogueEntry[] = [];
+  for (const domain of model?.domains ?? []) {
+    if (!gate(domain.gate)) continue;
+    out.push({
+      id: domain.id,
+      path: domain.path,
+      label: domain.label,
+      icon: domain.icon,
+      // A domain landing is a destination like any other, so it carries the same
+      // search metadata an item does — without these, an app whose places are
+      // leaf-shaped domains could only ever be found by exact label.
+      ...(domain.description === undefined ? {} : { description: domain.description }),
+      ...(domain.keywords === undefined ? {} : { keywords: domain.keywords }),
+      domainId: domain.id,
+      domainLabel: domain.label,
+    });
+    for (const group of domain.groups) {
+      for (const item of group.items) {
+        if (item.deepLinkOnly || !gate(item.gate)) continue;
+        out.push({
+          ...item,
+          domainId: domain.id,
+          domainLabel: domain.label,
+          groupId: group.id,
+          groupLabel: group.label,
+        });
+      }
+    }
+  }
+  for (const item of model.ungrouped ?? []) {
+    if (item.deepLinkOnly || !gate(item.gate)) continue;
+    out.push({ ...item });
+  }
+  return out;
+}
+
+/**
+ * Every path registered in the model (domain landings + all items + ungrouped),
+ * INCLUDING `deepLinkOnly` items — that's the point: a `deepLinkOnly` route is still
+ * "registered", so it satisfies coverage. De-duplicated. Consumed by the coverage
+ * test ({@link createCoverageTest}).
+ */
+export function deriveAllPaths(model: NavigationModel): string[] {
+  const paths = new Set<string>();
+  for (const domain of model?.domains ?? []) {
+    paths.add(domain.path);
+    for (const group of domain.groups) for (const item of group.items) paths.add(item.path);
+  }
+  for (const item of model.ungrouped ?? []) paths.add(item.path);
+  return [...paths];
+}

package/src/core/navigation/searchCatalogue.ts

@@ -0,0 +1,89 @@
+// Pure matcher + grouper for the instant client-side "pages" search layer. Ranks a
+// derived catalogue ({@link deriveSearchCatalogue}) against a query and buckets the
+// hits by their owning domain. Kept pure + framework-free so it's unit-testable and
+// shared by HeaderSearch and (task 14) the command palette. The palette upgrades the
+// *ranking* to uFuzzy; this is the dependency-free baseline both can fall back to.
+
+import type { SearchCatalogueEntry } from './navigationSelectors';
+
+/** A query hit with its computed relevance score (higher = better). */
+export interface CatalogueHit extends SearchCatalogueEntry {
+  score: number;
+}
+
+/** Hits bucketed under a domain (or under "" for ungrouped), preserving rank order. */
+export interface CatalogueResultGroup {
+  /** Domain id, or `''` for ungrouped destinations. */
+  key: string;
+  /** Domain label, or `'Pages'` for ungrouped. */
+  label: string;
+  items: CatalogueHit[];
+}
+
+const norm = (s: string) => s.toLowerCase().trim();
+
+/**
+ * Score one entry against a normalized query. Returns `0` for no match. Ranking
+ * favors, in order: exact label, label prefix, label word-boundary, label
+ * substring, then keyword / group / domain / path / description hits — so "env"
+ * surfaces "Env Sets" above a page that merely mentions environments.
+ */
+function scoreEntry(entry: SearchCatalogueEntry, q: string): number {
+  const label = norm(entry.label);
+  if (label === q) return 100;
+  if (label.startsWith(q)) return 80;
+  // word-boundary: a query that starts any word in the label ("col" → "Format **Col**…")
+  if (label.split(/[\s/&·-]+/).some((w) => w.startsWith(q))) return 65;
+  if (label.includes(q)) return 50;
+
+  for (const kw of entry.keywords ?? []) {
+    const k = norm(kw);
+    if (k === q || k.startsWith(q)) return 45;
+    if (k.includes(q)) return 35;
+  }
+  if (entry.groupLabel && norm(entry.groupLabel).includes(q)) return 25;
+  if (entry.domainLabel && norm(entry.domainLabel).includes(q)) return 20;
+  if (norm(entry.path).includes(q)) return 15;
+  if (entry.description && norm(entry.description).includes(q)) return 10;
+  return 0;
+}
+
+/**
+ * Filter + rank a catalogue by `query`. Empty/blank query → `[]` (the instant layer
+ * shows nothing until the user types). Stable: equal scores keep catalogue order.
+ */
+export function rankCatalogue(catalogue: SearchCatalogueEntry[], query: string): CatalogueHit[] {
+  const q = norm(query);
+  if (!q) return [];
+  const scored: CatalogueHit[] = [];
+  for (const entry of catalogue) {
+    const score = scoreEntry(entry, q);
+    if (score > 0) scored.push({ ...entry, score });
+  }
+  // Stable sort by score desc — Array.prototype.sort is stable in modern engines, so
+  // equal scores retain catalogue (authoring) order.
+  return scored.sort((a, b) => b.score - a.score);
+}
+
+/**
+ * Rank + bucket hits by owning domain (ungrouped under a "Pages" group), capping the
+ * total to `limit`. Groups appear in first-hit order; within a group, by rank.
+ */
+export function groupCatalogueHits(
+  catalogue: SearchCatalogueEntry[],
+  query: string,
+  limit = 20,
+): CatalogueResultGroup[] {
+  const hits = rankCatalogue(catalogue, query).slice(0, limit);
+  const groups = new Map<string, CatalogueResultGroup>();
+  for (const hit of hits) {
+    const key = hit.domainId ?? '';
+    let bucket = groups.get(key);
+    if (!bucket) {
+      bucket = { key, label: hit.domainLabel ?? 'Pages', items: [] };
+      groups.set(key, bucket);
+    }
+    bucket.items.push(hit);
+  }
+  return [...groups.values()];
+}

package/src/core/net/reconnectSchedule.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  createReconnectSchedule,
+  RECONNECT_CAP_MS,
+  retriesAreJittered,
+} from './reconnectSchedule';
+
+describe('reconnect backoff with full jitter (J5-2)', () => {
+  it('doubles the ceiling per attempt up to the cap', () => {
+    const schedule = createReconnectSchedule({ random: () => 1 });
+    expect(schedule.currentCeilingMs()).toBe(500);
+    schedule.nextDelayMs();
+    expect(schedule.currentCeilingMs()).toBe(1_000);
+    schedule.nextDelayMs();
+    expect(schedule.currentCeilingMs()).toBe(2_000);
+    for (let i = 0; i < 20; i++) schedule.nextDelayMs();
+    expect(schedule.currentCeilingMs()).toBe(RECONNECT_CAP_MS);
+  });
+
+  it('draws the delay from [0, ceiling) — full jitter, not a fixed interval', () => {
+    const lowest = createReconnectSchedule({ random: () => 0 });
+    const highest = createReconnectSchedule({ random: () => 0.999 });
+    expect(lowest.nextDelayMs()).toBe(0);
+    expect(highest.nextDelayMs()).toBeLessThan(500);
+    expect(highest.nextDelayMs()).toBeGreaterThan(500); // second attempt, larger window
+  });
+
+  it('spreads a synchronized wake across three clients', () => {
+    const clients = [0.05, 0.4, 0.95].map((seed) => createReconnectSchedule({ random: () => seed }));
+    const delays = clients.map((client) => client.nextDelayMs());
+    expect(retriesAreJittered(delays)).toBe(true);
+  });
+
+  it('flags a fixed-interval retry loop as a stampede', () => {
+    expect(retriesAreJittered([1000, 1001, 1002])).toBe(false);
+    expect(retriesAreJittered([1000])).toBe(true); // a single client cannot stampede
+  });
+
+  it('resets only after the connection has been stable long enough', () => {
+    const schedule = createReconnectSchedule({ random: () => 0.5 });
+    schedule.nextDelayMs();
+    schedule.nextDelayMs();
+    expect(schedule.attempt()).toBe(2);
+    schedule.onConnected(10_000);
+    expect(schedule.attempt()).toBe(2); // a brief connection is not stability
+    schedule.onConnected(60_000);
+    expect(schedule.attempt()).toBe(0);
+  });
+});

package/src/core/net/reconnectSchedule.ts

@@ -0,0 +1,78 @@
+/**
+ * Reconnect discipline for every persistent client connection (03 §6.5, J5-2).
+ *
+ * A server restart or a laptop resume wakes every client at once. With a fixed
+ * retry interval they all reconnect in the same millisecond and the app
+ * self-DDoSes its own Hono listener — the more clients, the harder the stampede.
+ *
+ * So: exponential backoff with FULL jitter — `delay = random(0, min(cap, base ·
+ * 2^attempt))`. Full jitter (rather than "±10%") is what actually spreads a
+ * synchronized wake across the window. A stable connection resets the attempt
+ * counter, so a flaky link does not inherit yesterday's backoff.
+ */
+export interface ReconnectScheduleOptions {
+  baseMs?: number;
+  capMs?: number;
+  /** Connected for this long ⇒ the next drop starts from attempt 0 again. */
+  stableResetMs?: number;
+  /** Injected for tests; defaults to Math.random. */
+  random?: () => number;
+}
+
+export const RECONNECT_BASE_MS = 500;
+export const RECONNECT_CAP_MS = 30_000;
+export const RECONNECT_STABLE_RESET_MS = 60_000;
+
+export interface ReconnectSchedule {
+  /** Delay for the next attempt, and advance the attempt counter. */
+  nextDelayMs(): number;
+  /** Call when a connection has been up; resets the counter once it has been stable. */
+  onConnected(uptimeMs: number): void;
+  /**
+   * Drop the accumulated backoff outright — for a DELIBERATE re-open (a
+   * credential change), which is not a failure and must not inherit the penalty
+   * the last outage earned. Never call this on a retry path: that is exactly how
+   * a fixed interval creeps back in.
+   */
+  reset(): void;
+  attempt(): number;
+  /** The deterministic ceiling for the current attempt — what the jitter is drawn from. */
+  currentCeilingMs(): number;
+}
+
+export function createReconnectSchedule(options: ReconnectScheduleOptions = {}): ReconnectSchedule {
+  const base = options.baseMs ?? RECONNECT_BASE_MS;
+  const cap = options.capMs ?? RECONNECT_CAP_MS;
+  const stableReset = options.stableResetMs ?? RECONNECT_STABLE_RESET_MS;
+  const random = options.random ?? Math.random;
+  let attempt = 0;
+
+  const ceiling = (n: number): number => Math.min(cap, base * 2 ** n);
+
+  return {
+    nextDelayMs() {
+      const delay = random() * ceiling(attempt);
+      attempt += 1;
+      return delay;
+    },
+    onConnected(uptimeMs) {
+      if (uptimeMs >= stableReset) attempt = 0;
+    },
+    reset() {
+      attempt = 0;
+    },
+    attempt: () => attempt,
+    currentCeilingMs: () => ceiling(attempt),
+  };
+}
+
+/**
+ * Did a set of observed retry timestamps actually spread? Used by V7.11: clients
+ * clustered inside one 50ms bucket beyond chance means someone reintroduced a
+ * fixed interval.
+ */
+export function retriesAreJittered(timestampsMs: readonly number[], bucketMs = 50): boolean {
+  if (timestampsMs.length < 2) return true;
+  const buckets = new Set(timestampsMs.map((t) => Math.floor(t / bucketMs)));
+  return buckets.size > 1;
+}

package/src/core/palette/ShortcutRegistry.ts

@@ -0,0 +1,69 @@
+// A tiny global registry of the app's keyboard shortcuts — the single source of truth
+// that BOTH the keybinding layer (`useHotkeys`) and the command palette read from. An
+// app registers a shortcut once; the palette can then list "Board → ⌥B" in its
+// cold-state reference without the binding and its documentation drifting apart.
+//
+// Register in a mount effect (never at module load) so the palette's list reflects the
+// shortcuts actually wired up for the current screen; the registry notifies subscribers
+// on every change so a mounted palette stays live as shortcuts come and go.
+
+/** A registered keyboard shortcut — its binding plus how it reads in the palette. */
+export interface ShortcutEntry {
+  /** Short name of the thing it acts on (e.g. `'Board'`). */
+  label: string;
+  /** Binding in tinykeys format (`'$mod+k'`, `'alt+b'`) — also the registry key. */
+  keys: string;
+  /** What the shortcut does, shown as the palette row's description (e.g. `'Open the board'`). */
+  action: string;
+}
+
+type Listener = () => void;
+
+/**
+ * Keyed by `keys`, so registering the same binding twice replaces it (last write wins
+ * — no duplicate rows) and a feature can re-register on every mount idempotently.
+ */
+export class ShortcutRegistry {
+  private entries = new Map<string, ShortcutEntry>();
+  private listeners = new Set<Listener>();
+  // A frozen snapshot, rebuilt only on mutation, so `getAll()` is referentially stable
+  // between changes — required for `useSyncExternalStore` to not loop.
+  private snapshot: ShortcutEntry[] = [];
+
+  /** Add or replace the shortcut for `entry.keys`. */
+  register(entry: ShortcutEntry): void {
+    this.entries.set(entry.keys, entry);
+    this.commit();
+  }
+
+  /** Remove the shortcut bound to `keys` (no-op if absent). */
+  unregister(keys: string): void {
+    if (this.entries.delete(keys)) this.commit();
+  }
+
+  /** Every registered shortcut, in insertion order. Stable until the next mutation. */
+  getAll(): ShortcutEntry[] {
+    return this.snapshot;
+  }
+
+  /** Subscribe to registry changes (returns an unsubscribe). Powers the live palette list. */
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Drop every shortcut (mainly for tests / teardown). */
+  clear(): void {
+    if (this.entries.size === 0) return;
+    this.entries.clear();
+    this.commit();
+  }
+
+  private commit(): void {
+    this.snapshot = [...this.entries.values()];
+    for (const listener of this.listeners) listener();
+  }
+}
+
+/** The app-wide shortcut registry singleton. */
+export const shortcutRegistry = new ShortcutRegistry();

package/src/core/palette/fuzzyRank.ts

@@ -0,0 +1,78 @@
+// The command-palette ranking layer — uFuzzy over the nav catalogue. This is the
+// *upgrade* HeaderSearch's `rankCatalogue` (a substring scorer) cannot match: uFuzzy
+// scores by contiguous-match proximity, so abbreviated/typeahead input ranks the
+// right page first. Pure + synchronous + React-free (uFuzzy is regex-based, no DOM),
+// so it runs in the client, a server test, or the kitchen-sink demo identically.
+//
+// Why `intraMode: 1` (SingleError, contiguous) over `0` (MultiInsert, scattered):
+// scattered mode treats every needle char as "appears somewhere later", which is far
+// too permissive for short nav labels (every query matches half the menu). Contiguous
+// mode keeps results tight — the documented tradeoff is lower typo tolerance, which is
+// the right call for a fixed, known set of navigation labels.
+//
+// The catch: contiguous mode means a bare initialism ("qb") would NOT reach "Query
+// Builder" (the chars aren't adjacent). So each haystack string is augmented with the
+// label's **initials** as an explicit token ("Query Builder" → "query builder qb") —
+// now "qb" matches that token contiguously, giving free initialism support without
+// loosening the matcher. Keywords (synonyms / old names / abbreviations) are appended
+// too, so "mandelbrot" still finds "Fractal".
+
+import uFuzzy from '@leeoniya/ufuzzy';
+import type { NavItem } from '../navigation';
+
+// One singleton instance — uFuzzy compiles regexes from its options on construction,
+// so re-creating it per query would be wasteful. `intraMode: 1` = contiguous match.
+const uf = new uFuzzy({ intraMode: 1 });
+
+/** Split a label into words on whitespace and the separators nav labels actually use. */
+const WORD_SPLIT = /[\s/&·,_-]+/;
+
+/**
+ * The initials of a multi-word label (`'Query Builder'` → `'qb'`). Single-word labels
+ * return `''` (their prefix already matches via the label itself). Powers initialism
+ * matching ("sh" → "System Health") under the strict contiguous matcher.
+ */
+export function searchInitials(label: string): string {
+  const words = label.split(WORD_SPLIT).filter(Boolean);
+  if (words.length < 2) return '';
+  // Lower-cased for a predictable token; uFuzzy matches case-insensitively anyway.
+  return words.map((w) => (w[0] ?? '').toLowerCase()).join('');
+}
+
+/** Build the per-item haystack string: label + its initials + any keywords, space-joined. */
+function haystackFor(item: NavItem): string {
+  return [item.label, searchInitials(item.label), ...(item.keywords ?? [])]
+    .filter(Boolean)
+    .join(' ');
+}
+
+/**
+ * Rank `items` against `query`, best match first; non-matches dropped. Generic over the
+ * item type (so callers can pass plain {@link NavItem}s *or* richer catalogue entries
+ * that carry domain/group tags for grouping — the extra fields ride straight through).
+ * An empty/blank query returns `[]` (the palette shows its cold state instead).
+ *
+ * Returns *all* matches in rank order; callers cap the count for display (the palette
+ * shows 30). uFuzzy's contiguous scorer means "frac" ranks "Fractal" above "Format
+ * Lab", and the initials augmentation means "qb" surfaces "Query Builder".
+ */
+export function fuzzyRankItems<T extends NavItem>(query: string, items: T[]): T[] {
+  const q = query.trim();
+  if (!q || items.length === 0) return [];
+
+  const haystack = items.map(haystackFor);
+  const [idxs, , order] = uf.search(haystack, q);
+  // `idxs` is null when nothing matched and an empty array when filtered to zero; both
+  // mean "no results". `order` (the ranked iteration order into `idxs`) is present
+  // whenever there are matches under uFuzzy's info threshold (1e3 — far above any nav
+  // set); fall back to raw `idxs` order if it's ever absent.
+  if (!idxs || idxs.length === 0) return [];
+  const ranked = order ? order.map((o) => idxs[o]) : idxs;
+
+  const out: T[] = [];
+  for (const haystackIdx of ranked) {
+    const item = items[haystackIdx];
+    if (item) out.push(item);
+  }
+  return out;
+}