cursedbelt-core 2.12.0 → 2.13.1

package/README.md

@@ -0,0 +1,21 @@
+# cursedbelt-core
+
+Framework-agnostic core of the cursedbelt split — isomorphic domain logic, types, schemas and
+wire shapes both sides share. `cwip` is below it; `cursedbelt-server` and `cursedbelt` (the
+React design system) sit above it.
+
+```sh
+bun add cursedbelt-core
+```
+
+## The root export is a BARREL — import the leaf
+
+`import … from "cursedbelt-core"` re-exports everything below it. Import the subpath that owns
+the symbol instead — `cursedbelt-core/navigation`, `cursedbelt-core/media/ffmpeg`,
+`cursedbelt-core/master-lock`, and so on. `package.json`'s `exports` map is the full list of
+subpaths; there is no separate reference doc to keep in sync with it.
+
+## Docs in this repo
+
+[`docs/skipped-tests.md`](docs/skipped-tests.md) — the table `src/skippedTestsAreAnswered.spec.ts`
+keeps honest against every skip site in `src`.

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

@@ -40,6 +40,15 @@ export interface NavItem {
      * a way to dodge the coverage test for a real, discoverable feature.
      */
     deepLinkOnly?: true;
+    /**
+     * Found by search and the palette, but **never drawn** as a side-nav child row or a hub
+     * tile — the half of a page a reader types for rather than browses to: a tab (`?tab=agents`),
+     * a filter, a section of a long page. Without it, every such address either became a rail
+     * row (the sidebar grew with every tab) or was not findable by name at all (owner,
+     * 2026-10-09: *"Station is getting complicated to find things in with its dozens of sidebar
+     * items"*, and in the same breath, a search that finds a page by what it holds).
+     */
+    searchOnly?: true;
     /** Extra match terms for search / palette (synonyms, old names, abbreviations). */
     keywords?: string[];
 }

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

@@ -33,8 +33,9 @@ export interface NavCrumb {
 /** 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.
+ * Every visible (gated, non-`deepLinkOnly`, non-`searchOnly`) item of `domain`, flattened
+ * across its groups — for a simple HubTileGrid and the side nav's child rows. Returns `[]` if
+ * the domain itself is gated out.
  */
 export declare function deriveDomainItems(domain: NavDomain, gate?: GateFn): NavItem[];
 /**
@@ -54,7 +55,7 @@ export declare function deriveDomain(model: NavigationModel, domainId: string, g
 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
+ * non-`deepLinkOnly`) domain landing + item, `searchOnly` ones included, 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).

package/dist/core/navigation/navigationSelectors.js

@@ -45,14 +45,17 @@ const itemCrumb = (it) => ({
 export function deriveSideNavDomains(model, gate = allowAllGate) {
     return (model?.domains ?? []).filter((d) => gate(d.gate));
 }
+/** An item a reader can BROWSE to — drawn as a row or a tile, not only found by search. */
+const isBrowsable = (it, gate) => !it.deepLinkOnly && !it.searchOnly && gate(it.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.
+ * Every visible (gated, non-`deepLinkOnly`, non-`searchOnly`) item of `domain`, flattened
+ * across its groups — for a simple HubTileGrid and the side nav's child rows. 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));
+    return domain.groups.flatMap((g) => g.items).filter((it) => isBrowsable(it, gate));
 }
 /**
  * The visible groups of `domain` (each with its visible items; empty groups
@@ -63,7 +66,7 @@ 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)) }))
+        .map((g) => ({ ...g, items: g.items.filter((it) => isBrowsable(it, gate)) }))
         .filter((g) => g.items.length > 0);
 }
 /** Look up a domain by id (gated). */
@@ -113,7 +116,7 @@ export function deriveBreadcrumbTrail(model, path, gate = allowAllGate) {
 }
 /**
  * The flat list of searchable destinations — every visible (gated,
- * non-`deepLinkOnly`) domain landing + item, each tagged with its domain/group so
+ * non-`deepLinkOnly`) domain landing + item, `searchOnly` ones included, 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).

package/dist/core/palette/fuzzyRank.d.ts

@@ -11,6 +11,11 @@ export declare function searchInitials(label: string): string;
  * 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).
  *
+ * Two tiers, the first always ahead of the second: an item whose NAME matches (label,
+ * initials, keywords), then one that matches only by what it HOLDS (description, group,
+ * place). So "frac" ranks Fractal first however many descriptions mention fractals, while
+ * a word that names no page still finds the pages that are about it.
+ *
  * 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".

package/dist/core/palette/fuzzyRank.js

@@ -40,12 +40,38 @@ function haystackFor(item) {
         .filter(Boolean)
         .join(' ');
 }
+/**
+ * The SECOND tier: what a destination holds rather than what it is called — its description,
+ * and the group and place it sits under when the entry carries them (catalogue entries do).
+ * Owner, 2026-10-09: *"I may not know where to go but typing something like 'api' brings up the
+ * relevant page links quickly"* — a page found only by its exact name is not found by someone
+ * who does not know the name.
+ */
+function secondaryHaystackFor(item) {
+    return [item.description, item.groupLabel, item.domainLabel].filter(Boolean).join(' ');
+}
+/** uFuzzy's ranked indexes into `haystack` for `q`, `[]` when nothing matched. */
+function rankedIndexes(haystack, q) {
+    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 [];
+    return order ? order.map((o) => idxs[o]) : [...idxs];
+}
 /**
  * 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).
  *
+ * Two tiers, the first always ahead of the second: an item whose NAME matches (label,
+ * initials, keywords), then one that matches only by what it HOLDS (description, group,
+ * place). So "frac" ranks Fractal first however many descriptions mention fractals, while
+ * a word that names no page still finds the pages that are about it.
+ *
  * 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".
@@ -54,17 +80,11 @@ export function fuzzyRankItems(query, items) {
     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 primary = rankedIndexes(items.map(haystackFor), q);
+    const named = new Set(primary);
+    const secondary = rankedIndexes(items.map(secondaryHaystackFor), q).filter((i) => !named.has(i));
     const out = [];
-    for (const haystackIdx of ranked) {
+    for (const haystackIdx of [...primary, ...secondary]) {
         const item = items[haystackIdx];
         if (item)
             out.push(item);

package/dist/core/palette/hotkeys.d.ts

@@ -15,7 +15,10 @@ export interface ParsedHotkey extends HotkeyMods {
  * returns `false` when there's no `navigator`.
  */
 export declare function isApplePlatform(): boolean;
-/** Split a `'+'`-separated binding into its required modifiers + final key. */
+/**
+ * Split a `'+'`-separated binding into its required modifiers + final key. `+` is itself a
+ * key — a bare `'+'` or `'$mod++'` splits into empty parts, and the key is the `+`.
+ */
 export declare function parseHotkey(binding: string, isApple?: boolean): ParsedHotkey;
 /** Does a keyboard event satisfy `binding` — exact modifier set + the key? */
 export declare function matchHotkey(e: KeyboardEvent, binding: string, isApple?: boolean): boolean;

package/dist/core/palette/hotkeys.js

@@ -21,14 +21,18 @@ export function isApplePlatform() {
     const probe = `${navigator.platform ?? ''} ${navigator.userAgent ?? ''}`;
     return /mac|iphone|ipad|ipod/i.test(probe);
 }
-/** Split a `'+'`-separated binding into its required modifiers + final key. */
+/**
+ * Split a `'+'`-separated binding into its required modifiers + final key. `+` is itself a
+ * key — a bare `'+'` or `'$mod++'` splits into empty parts, and the key is the `+`.
+ */
 export function parseHotkey(binding, isApple = isApplePlatform()) {
-    const parts = binding
+    const split = binding
         .toLowerCase()
         .split('+')
-        .map((p) => p.trim())
-        .filter(Boolean);
-    const key = parts.pop() ?? '';
+        .map((p) => p.trim());
+    const plusKey = split.length > 1 && split[split.length - 1] === '';
+    const parts = split.filter(Boolean);
+    const key = plusKey ? '+' : (parts.pop() ?? '');
     const tokens = new Set(parts);
     const mod = tokens.has('$mod');
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.12.0",
+	"version": "2.13.1",
 	"license": "ISC",
 	"type": "module",
 	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
@@ -424,5 +424,9 @@
 				"why": "build starts with `rm -rf dist`, and leafSubpathsImportNothing / shippedFilesAreTracked read dist/; racing it they read a directory that is not there yet"
 			}
 		]
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wizardmordamir/cursedforge-cursedbelt-core.git"
 	}
 }

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

@@ -13,6 +13,7 @@ import {
   groupCatalogueHits,
   type LegacyNavPrefs,
   migrateNavPreferences,
+  type NavDomain,
   type NavGate,
   type NavigationModel,
   normalizeNavPath,
@@ -180,6 +181,30 @@ describe('deriveDomainItems / deriveDomainGroups', () => {
     const ctgrGate: GateFn = (g?: NavGate) => !g?.hiddenInCtgr;
     expect(deriveDomainItems(admin, ctgrGate).map((i) => i.id)).toEqual(['admin-users']);
   });
+  test('a searchOnly item is found by search but never drawn as a row or a tile', () => {
+    const perf: NavDomain = {
+      id: 'perf',
+      label: 'Performance',
+      icon: 'activity',
+      path: '/performance',
+      groups: [
+        {
+          id: 'perf-pages',
+          label: 'Pages',
+          items: [
+            { id: 'perf-overview', label: 'Overview', path: '/performance/overview' },
+            { id: 'perf-agents', label: 'Agents', path: '/performance?tab=agents', searchOnly: true },
+          ],
+        },
+        { id: 'perf-tabs', label: 'Tabs', items: [{ id: 'perf-cost', label: 'Cost', path: '/performance?tab=cost', searchOnly: true }] },
+      ],
+    };
+    expect(deriveDomainItems(perf).map((i) => i.id)).toEqual(['perf-overview']);
+    // A group whose every item is searchOnly is not a heading on a hub landing.
+    expect(deriveDomainGroups(perf).map((g) => g.id)).toEqual(['perf-pages']);
+    const found = deriveSearchCatalogue({ domains: [perf] }).map((e) => e.id);
+    expect(found).toEqual(['perf', 'perf-overview', 'perf-agents', 'perf-cost']);
+  });
 });
 
 describe('deriveBreadcrumbTrail', () => {

package/src/core/navigation/navigationModel.ts

@@ -54,6 +54,15 @@ export interface NavItem {
    * a way to dodge the coverage test for a real, discoverable feature.
    */
   deepLinkOnly?: true;
+  /**
+   * Found by search and the palette, but **never drawn** as a side-nav child row or a hub
+   * tile — the half of a page a reader types for rather than browses to: a tab (`?tab=agents`),
+   * a filter, a section of a long page. Without it, every such address either became a rail
+   * row (the sidebar grew with every tab) or was not findable by name at all (owner,
+   * 2026-10-09: *"Station is getting complicated to find things in with its dozens of sidebar
+   * items"*, and in the same breath, a search that finds a page by what it holds).
+   */
+  searchOnly?: true;
   /** Extra match terms for search / palette (synonyms, old names, abbreviations). */
   keywords?: string[];
 }

package/src/core/navigation/navigationSelectors.ts

@@ -79,13 +79,17 @@ export function deriveSideNavDomains(
   return (model?.domains ?? []).filter((d) => gate(d.gate));
 }
 
+/** An item a reader can BROWSE to — drawn as a row or a tile, not only found by search. */
+const isBrowsable = (it: NavItem, gate: GateFn): boolean => !it.deepLinkOnly && !it.searchOnly && gate(it.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.
+ * Every visible (gated, non-`deepLinkOnly`, non-`searchOnly`) item of `domain`, flattened
+ * across its groups — for a simple HubTileGrid and the side nav's child rows. 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));
+  return domain.groups.flatMap((g) => g.items).filter((it) => isBrowsable(it, gate));
 }
 
 /**
@@ -96,7 +100,7 @@ export function deriveDomainItems(domain: NavDomain, gate: GateFn = allowAllGate
 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)) }))
+    .map((g) => ({ ...g, items: g.items.filter((it) => isBrowsable(it, gate)) }))
     .filter((g) => g.items.length > 0);
 }
 
@@ -154,7 +158,7 @@ export function deriveBreadcrumbTrail(
 
 /**
  * The flat list of searchable destinations — every visible (gated,
- * non-`deepLinkOnly`) domain landing + item, each tagged with its domain/group so
+ * non-`deepLinkOnly`) domain landing + item, `searchOnly` ones included, 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).

package/src/core/palette/fuzzyRank.ts

@@ -46,12 +46,39 @@ function haystackFor(item: NavItem): string {
     .join(' ');
 }
 
+/**
+ * The SECOND tier: what a destination holds rather than what it is called — its description,
+ * and the group and place it sits under when the entry carries them (catalogue entries do).
+ * Owner, 2026-10-09: *"I may not know where to go but typing something like 'api' brings up the
+ * relevant page links quickly"* — a page found only by its exact name is not found by someone
+ * who does not know the name.
+ */
+function secondaryHaystackFor(item: NavItem & { groupLabel?: string; domainLabel?: string }): string {
+  return [item.description, item.groupLabel, item.domainLabel].filter(Boolean).join(' ');
+}
+
+/** uFuzzy's ranked indexes into `haystack` for `q`, `[]` when nothing matched. */
+function rankedIndexes(haystack: string[], q: string): number[] {
+  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 [];
+  return order ? order.map((o) => idxs[o] as number) : [...idxs];
+}
+
 /**
  * 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).
  *
+ * Two tiers, the first always ahead of the second: an item whose NAME matches (label,
+ * initials, keywords), then one that matches only by what it HOLDS (description, group,
+ * place). So "frac" ranks Fractal first however many descriptions mention fractals, while
+ * a word that names no page still finds the pages that are about it.
+ *
  * 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".
@@ -60,17 +87,12 @@ 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 primary = rankedIndexes(items.map(haystackFor), q);
+  const named = new Set(primary);
+  const secondary = rankedIndexes(items.map(secondaryHaystackFor), q).filter((i) => !named.has(i));
 
   const out: T[] = [];
-  for (const haystackIdx of ranked) {
+  for (const haystackIdx of [...primary, ...secondary]) {
     const item = items[haystackIdx];
     if (item) out.push(item);
   }

package/src/core/palette/hotkeys.ts

@@ -35,14 +35,18 @@ export function isApplePlatform(): boolean {
   return /mac|iphone|ipad|ipod/i.test(probe);
 }
 
-/** Split a `'+'`-separated binding into its required modifiers + final key. */
+/**
+ * Split a `'+'`-separated binding into its required modifiers + final key. `+` is itself a
+ * key — a bare `'+'` or `'$mod++'` splits into empty parts, and the key is the `+`.
+ */
 export function parseHotkey(binding: string, isApple = isApplePlatform()): ParsedHotkey {
-  const parts = binding
+  const split = binding
     .toLowerCase()
     .split('+')
-    .map((p) => p.trim())
-    .filter(Boolean);
-  const key = parts.pop() ?? '';
+    .map((p) => p.trim());
+  const plusKey = split.length > 1 && split[split.length - 1] === '';
+  const parts = split.filter(Boolean);
+  const key = plusKey ? '+' : (parts.pop() ?? '');
   const tokens = new Set(parts);
   const mod = tokens.has('$mod');
   return {

package/src/core/palette/palette.spec.ts

@@ -66,6 +66,21 @@ describe('fuzzyRankItems', () => {
     expect(fuzzyRankItems('zzqzzx', ITEMS)).toEqual([]);
   });
 
+  test('what a page HOLDS finds it: a description-only word ranks after every name match', () => {
+    const pages: (NavItem & { domainLabel?: string })[] = [
+      { ...item('Connections', ['google', 'github']), description: 'The sign-ins and API tokens your apps run on' },
+      { ...item('Traffic'), description: 'What this Mac served' },
+      { ...item('Agents'), domainLabel: 'Performance', description: 'What each agent cost' },
+      { ...item('API keys') },
+    ];
+    // "api" names "API keys" — that is first — and is only HELD by Connections, which follows.
+    expect(labels(fuzzyRankItems('api', pages))).toEqual(['API keys', 'Connections']);
+    // The place an entry sits under counts as what it holds: "performance" finds its tab.
+    expect(labels(fuzzyRankItems('performance', pages))).toEqual(['Agents']);
+    // Never the same item twice when it matches in both tiers.
+    expect(labels(fuzzyRankItems('agent', pages))).toEqual(['Agents']);
+  });
+
   test('carries through extra fields on richer entry types (domain tags)', () => {
     type Tagged = NavItem & { domainId: string };
     const tagged: Tagged[] = [{ ...item('Fractal'), domainId: 'play' }];
@@ -118,6 +133,14 @@ describe('formatHotkey', () => {
   test('multiple modifiers order Apple-style (⌃⌥⇧⌘)', () => {
     expect(formatHotkey('$mod+shift+p', true)).toBe('⇧⌘P');
   });
+  test('`+` is a key too — a bare `+` or `shift++` draws a + cap, never an empty one', () => {
+    expect(formatHotkey('+', true)).toBe('+');
+    expect(formatHotkey('+', false)).toBe('+');
+    expect(formatHotkey('$mod++', true)).toBe('⌘+');
+    expect(formatHotkey('$mod++', false)).toBe('Ctrl +');
+    expect(parseHotkey('shift++')).toMatchObject({ shift: true, key: '+' });
+    expect(matchHotkey(kd({ key: '+' }), '+', true)).toBe(true);
+  });
 });
 
 // ── ShortcutRegistry ──────────────────────────────────────────────────────────