cursedbelt-core 1.0.0

package/dist/core/navigation/migrateNavPreferences.js

@@ -0,0 +1,63 @@
+// One-time, idempotent preference migration. The IA overhaul re-groups the old
+// 8-hub layout into 6 domains; this remaps the user's saved nav/hub customizations
+// (order, hidden, per-row colors) onto the new ids so nothing resets. The *mapping*
+// (old key → new domain id) is app-supplied data (only the app knows its old hubs);
+// the runner is the framework's. Idempotent via a version stamp — it runs on every
+// cold load but no-ops once `version` is current, so colors/hidden the user set
+// AFTER migrating are never clobbered.
+/** Bump when the migration logic or the prefs shape changes. */
+export const CURRENT_NAV_PREFS_VERSION = 1;
+const uniq = (xs) => [...new Set(xs)];
+/** Merge two tile-pref blocks (union hidden, concat+dedupe order, later colors win). */
+function mergeTilePrefs(a, b) {
+    return {
+        order: uniq([...(a?.order ?? []), ...(b.order ?? [])]),
+        hidden: uniq([...(a?.hidden ?? []), ...(b.hidden ?? [])]),
+        colors: { ...(a?.colors ?? {}), ...(b.colors ?? {}) },
+    };
+}
+/**
+ * Migrate legacy nav prefs onto the new model. Idempotent: returns `old` untouched
+ * when it's already at {@link CURRENT_NAV_PREFS_VERSION}. Otherwise remaps via
+ * `options.keyMap`, drops domain-level keys whose target isn't a real domain in
+ * `model`, merges consolidated hubs, and stamps the version.
+ */
+export function migrateNavPreferences(old, model, options = {}) {
+    // Already migrated → no-op (don't reset user choices made post-migration).
+    if (old && typeof old.version === 'number' && old.version >= CURRENT_NAV_PREFS_VERSION) {
+        return old;
+    }
+    const keyMap = options.keyMap ?? {};
+    const remap = (k) => keyMap[k] ?? k;
+    const domainIds = new Set((model?.domains ?? []).map((d) => d.id));
+    const legacy = (old ?? {});
+    // Domain order: remap each old route id → domain id, dedupe, keep only real domains.
+    const order = uniq((legacy.nav?.order ?? []).map(remap)).filter((id) => domainIds.has(id));
+    // Hidden domains: remap, dedupe, keep only real domains.
+    const hidden = uniq((legacy.hiddenNavRoutes ?? []).map(remap)).filter((id) => domainIds.has(id));
+    // Domain colors: remap keys, keep only real domains (last write wins on collision).
+    const colors = {};
+    for (const [k, v] of Object.entries(legacy.nav?.colors ?? {})) {
+        const id = remap(k);
+        if (domainIds.has(id))
+            colors[id] = v;
+    }
+    // Hub tile prefs: remap hub key → domain id, merging when two hubs consolidate.
+    const hubs = {};
+    for (const [oldHub, prefs] of Object.entries(legacy.hubs ?? {})) {
+        const id = remap(oldHub);
+        if (!domainIds.has(id))
+            continue; // a hub with no surviving domain home is dropped
+        hubs[id] = mergeTilePrefs(hubs[id], prefs);
+    }
+    const result = { version: CURRENT_NAV_PREFS_VERSION };
+    if (order.length)
+        result.order = order;
+    if (hidden.length)
+        result.hidden = hidden;
+    if (Object.keys(colors).length)
+        result.colors = colors;
+    if (Object.keys(hubs).length)
+        result.hubs = hubs;
+    return result;
+}

package/dist/core/navigation/navigationModel.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 declare const allowAllGate: GateFn;

package/dist/core/navigation/navigationModel.js

@@ -0,0 +1,14 @@
+// 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.
+/** The trivial gate — everything is visible. Default for selectors + unguarded apps. */
+export const allowAllGate = () => true;

package/dist/core/navigation/navigationSelectors.d.ts

@@ -0,0 +1,63 @@
+import { 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 declare function normalizeNavPath(path: string): string;
+/** 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;
+}
+/** The ordered domains visible under `gate` — the side-nav rail backbone. */
+export declare function deriveSideNavDomains(model: NavigationModel, gate?: GateFn): NavDomain[];
+/**
+ * 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 declare function deriveDomainItems(domain: NavDomain, gate?: GateFn): NavItem[];
+/**
+ * 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 declare function deriveDomainGroups(domain: NavDomain, gate?: GateFn): NavGroup[];
+/** Look up a domain by id (gated). */
+export declare function deriveDomain(model: NavigationModel, domainId: string, gate?: GateFn): NavDomain | 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 declare function deriveBreadcrumbTrail(model: NavigationModel, path: string, gate?: GateFn): NavCrumb[];
+/**
+ * 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 declare function deriveSearchCatalogue(model: NavigationModel, gate?: GateFn): SearchCatalogueEntry[];
+/**
+ * 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 declare function deriveAllPaths(model: NavigationModel): string[];

package/dist/core/navigation/navigationSelectors.js

@@ -0,0 +1,167 @@
+// 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, } 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) {
+    // 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 || '/';
+}
+const domainCrumb = (d) => ({
+    id: d.id,
+    label: d.label,
+    path: d.path,
+    icon: d.icon,
+});
+const itemCrumb = (it) => ({
+    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, gate = allowAllGate) {
+    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, gate = allowAllGate) {
+    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, gate = allowAllGate) {
+    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, domainId, gate = allowAllGate) {
+    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, path, gate = allowAllGate) {
+    // 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) => {
+        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, gate = allowAllGate) {
+    const out = [];
+    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) {
+    const paths = new Set();
+    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/dist/core/navigation/searchCatalogue.d.ts

@@ -0,0 +1,23 @@
+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[];
+}
+/**
+ * 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 declare function rankCatalogue(catalogue: SearchCatalogueEntry[], query: string): CatalogueHit[];
+/**
+ * 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 declare function groupCatalogueHits(catalogue: SearchCatalogueEntry[], query: string, limit?: number): CatalogueResultGroup[];

package/dist/core/navigation/searchCatalogue.js

@@ -0,0 +1,76 @@
+// 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.
+const norm = (s) => 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, q) {
+    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, query) {
+    const q = norm(query);
+    if (!q)
+        return [];
+    const scored = [];
+    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, query, limit = 20) {
+    const hits = rankCatalogue(catalogue, query).slice(0, limit);
+    const groups = new Map();
+    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/dist/core/net/reconnectSchedule.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 declare const RECONNECT_BASE_MS = 500;
+export declare const RECONNECT_CAP_MS = 30000;
+export declare const RECONNECT_STABLE_RESET_MS = 60000;
+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 declare function createReconnectSchedule(options?: ReconnectScheduleOptions): ReconnectSchedule;
+/**
+ * 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 declare function retriesAreJittered(timestampsMs: readonly number[], bucketMs?: number): boolean;

package/dist/core/net/reconnectSchedule.js

@@ -0,0 +1,38 @@
+export const RECONNECT_BASE_MS = 500;
+export const RECONNECT_CAP_MS = 30_000;
+export const RECONNECT_STABLE_RESET_MS = 60_000;
+export function createReconnectSchedule(options = {}) {
+    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) => 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, bucketMs = 50) {
+    if (timestampsMs.length < 2)
+        return true;
+    const buckets = new Set(timestampsMs.map((t) => Math.floor(t / bucketMs)));
+    return buckets.size > 1;
+}