cursedbelt-core 1.0.0

package/src/core/media/videoCuts.ts

@@ -0,0 +1,355 @@
+/**
+ * Marking parts of a video to REMOVE — the model, with no browser and no ffmpeg in it.
+ *
+ * ── The owner's ask, 2026-08-25 ────────────────────────────────────────────────────────
+ * *"We will use a unique strategy and not have live video changes in the UI. What I want is
+ * to be able to mark points in the video to indicate where to cut out sections. The browser
+ * is not great at actually removing segments in the UI even with the cc editor for video. So
+ * I will just mark them and send them to binary-server to handle it with the video software
+ * it uses."*
+ *
+ * 🔴 That is a decision about WHERE the work happens, and it is the right one for a reason
+ * worth writing down: `ffmpeg.wasm` decodes a multi-gigabyte clip inside a tab, at a few
+ * frames a second, holding the whole thing in memory — and this library's files are phone
+ * and camera masters. binary-server already runs native ffmpeg on this Mac with measured
+ * encoder settings (`ffmpegJobs.ts`), so the browser's only job is to say WHERE, which is
+ * exactly what a browser is good at.
+ *
+ * So a cut list is DATA. It is produced here, travels as JSON, and is executed somewhere
+ * else — which is why every rule about what makes a list valid lives in this file rather
+ * than being re-derived by the editor, by the app's route and by the ffmpeg arg builder. A
+ * cut list the UI thinks is fine and the encoder thinks is empty is the failure mode this
+ * shape exists to make impossible.
+ *
+ * ── 🔴 Why it lives in `core/`, not beside the editor in `react/media/` ────────────────
+ * Because the SERVER needs it. `apps/collections`' route refuses a cut list with the same
+ * function the dialog's Send button was disabled by, and a second definition of "a cut list
+ * that cannot be executed" is exactly the drift this module exists to prevent. Importing it
+ * from `cursedbelt/react/media` would pull the mask painter, the picture editor and React
+ * itself into a Hono server — so the model is `cursedbelt-core/media`, which is framework-free
+ * by construction, and `react/media` re-exports it for the dialog's convenience.
+ *
+ * ── Half-open, in seconds ──────────────────────────────────────────────────────────────
+ * A cut is `[start, end)`. Adjacent cuts therefore MERGE without leaving a frame between
+ * them, and a cut ending exactly where the next begins is one cut rather than two with an
+ * invisible sliver of footage in the middle.
+ */
+
+/*
+ * ── 🔴 The MARKING model (owner, 2026-08-26) ──────────────────────────────────────────
+ *
+ * *"I could also cut many sections from the middle instead of just one … There are always
+ * start and end points needed for mid section removals to be valid. I think there could be
+ * ambiguity about which side to cut in some cases if the same type of marker is used for
+ * every cut marker. You can make it allow clicking 'x' on a section to indicate remove it. If
+ * I make one cut in the middle then I can choose the left of it and click 'x' to indicate the
+ * left should be the deleted side."*
+ *
+ * He identified the defect in the first design exactly. Marks that PAIR — an in point and an
+ * out point — are ambiguous the moment there is more than one pair, because nothing in a row
+ * of identical markers says which gap is a cut and which is footage. `-[--|-|-]-` has to be
+ * read, and two people read it differently.
+ *
+ * So the model is his: a CUT is a split point, and splits divide the clip into SEGMENTS. A
+ * segment is either kept or removed, and you say which by clicking it. There is no pairing,
+ * no ordering rule, and no "which side" question left to ask — every point in the video
+ * belongs to exactly one segment, and that segment is either in or out.
+ *
+ * It also makes the two things he listed as separate cases the same case: one cut and remove
+ * the left is `[X][ keep ]`, and cutting several sections out of the middle is
+ * `[keep][X][keep][X][keep]`. Nothing special-cases the head or the tail.
+ *
+ * `VideoCut[]` remains the wire format — the encoder still receives spans to remove — so the
+ * server, binary-server and every test below are unchanged by this. What changed is only how
+ * a person produces one.
+ */
+
+/** One removed span. Seconds from the start of the source, half-open: `[start, end)`. */
+export interface VideoCut {
+  start: number;
+  end: number;
+}
+
+/**
+ * The shortest span worth cutting, in seconds.
+ *
+ * 🔴 Not zero, and not "whatever the person dragged". Below roughly a frame the request is
+ * indistinguishable from a mis-click, and it is a request ffmpeg cannot honour anyway — a
+ * cut has to land on a frame boundary, so a 4 ms span asks the encoder to remove nothing and
+ * charges a full re-encode of the file for it. 40 ms is one frame at 25fps, the slowest rate
+ * anything in this library was shot at.
+ */
+export const MIN_CUT_SECONDS = 0.04;
+
+const clamp = (value: number, low: number, high: number): number =>
+  Math.min(high, Math.max(low, value));
+
+/**
+ * Put a raw list into the one canonical form everything downstream may assume: inside the
+ * clip, ordered, non-overlapping, and free of spans too short to mean anything.
+ *
+ * 🔴 Overlaps are MERGED rather than refused. They are not a mistake to report — they are
+ * what marking naturally produces: you cut a passage, watch it back, and cut a span that
+ * happens to include part of what you already removed. Refusing that would make the editor
+ * argue with the person using it about an intention that is perfectly clear.
+ *
+ * A non-finite bound (a `NaN` duration from a video element that has not loaded yet is the
+ * usual source) drops its cut instead of poisoning the sort — every comparison against `NaN`
+ * is false, which silently produces an unsorted "sorted" array and a merge pass that leaves
+ * overlaps in.
+ */
+export function normalizeCuts(cuts: readonly VideoCut[], duration: number): VideoCut[] {
+  if (!Number.isFinite(duration) || duration <= 0) return [];
+  const clean = cuts
+    .filter((cut) => Number.isFinite(cut.start) && Number.isFinite(cut.end))
+    .map((cut) => ({
+      start: clamp(Math.min(cut.start, cut.end), 0, duration),
+      end: clamp(Math.max(cut.start, cut.end), 0, duration),
+    }))
+    .filter((cut) => cut.end - cut.start >= MIN_CUT_SECONDS)
+    .sort((a, b) => a.start - b.start);
+
+  const merged: VideoCut[] = [];
+  for (const cut of clean) {
+    const last = merged[merged.length - 1];
+    // `>=` not `>`: half-open spans that touch are one span, not two with a gap of zero
+    // seconds between them that no frame can live in.
+    if (last && cut.start <= last.end) last.end = Math.max(last.end, cut.end);
+    else merged.push({ ...cut });
+  }
+  return merged;
+}
+
+/**
+ * What SURVIVES — the complement of the cut list, which is what the encoder actually
+ * concatenates.
+ *
+ * The editor shows this and the encoder builds from it, from one function, because the
+ * alternative is two independent readings of "the parts you keep" and a preview that
+ * disagrees with the file that comes back.
+ */
+export function keptSegments(cuts: readonly VideoCut[], duration: number): VideoCut[] {
+  const removed = normalizeCuts(cuts, duration);
+  if (!Number.isFinite(duration) || duration <= 0) return [];
+  const kept: VideoCut[] = [];
+  let at = 0;
+  for (const cut of removed) {
+    if (cut.start - at >= MIN_CUT_SECONDS) kept.push({ start: at, end: cut.start });
+    at = Math.max(at, cut.end);
+  }
+  if (duration - at >= MIN_CUT_SECONDS) kept.push({ start: at, end: duration });
+  return kept;
+}
+
+/** How much of the clip the marks remove. */
+export function cutSeconds(cuts: readonly VideoCut[], duration: number): number {
+  return normalizeCuts(cuts, duration).reduce((total, cut) => total + (cut.end - cut.start), 0);
+}
+
+/** How long the result will be. */
+export function keptSeconds(cuts: readonly VideoCut[], duration: number): number {
+  return keptSegments(cuts, duration).reduce((total, seg) => total + (seg.end - seg.start), 0);
+}
+
+/**
+ * Why this list cannot be sent, or `null` when it can.
+ *
+ * 🔴 A SENTENCE, not a boolean, and the same sentence in the editor and on the server. The
+ * two refusals below are the only ones, and both are things a person can reach by accident
+ * in a few seconds of marking:
+ *
+ *  · nothing marked — pressing Send with no cuts would queue a full re-encode that produces
+ *    a byte-for-byte-pointless second copy of a multi-gigabyte file, and then ask the owner
+ *    to choose between two identical videos.
+ *  · everything marked — the result is an empty file. ffmpeg's `concat` with zero segments
+ *    does not fail loudly; it writes a valid container with no frames in it, which arrives
+ *    as a "finished" edit that plays nothing.
+ */
+export function cutListProblem(cuts: readonly VideoCut[], duration: number): string | null {
+  if (!Number.isFinite(duration) || duration <= 0)
+    return "This video's length is not known yet, so a cut cannot be placed in it.";
+  if (normalizeCuts(cuts, duration).length === 0)
+    return "Nothing is marked for removal yet — mark at least one section first.";
+  if (keptSegments(cuts, duration).length === 0)
+    return "That removes the whole video. Leave at least one section to keep.";
+  return null;
+}
+
+/**
+ * Seconds as `m:ss.s` / `h:mm:ss.s` — a TENTH of a second, unlike the timecode the player's
+ * scrub bar shows.
+ *
+ * 🔴 The extra digit is the difference between a readable clock and a usable cut point. At
+ * whole seconds two marks a few frames apart render identically, so a list of cuts around
+ * one moment reads as the same row repeated — and there is no way to tell, from the list,
+ * which of them is the one you meant to delete.
+ */
+export function cutTimecode(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds < 0) return '0:00.0';
+  /*
+   * 🔴 Integer tenths, with an epsilon, rather than `Math.floor((seconds % 1) * 10)`.
+   *
+   * A playhead is a float from a decoder, and the fractional part of one is not the number
+   * you wrote down: `3725.2 % 1` is 0.19999999999981810, which floors to ONE tenth — the
+   * timecode reads 1:02:05.1 for a mark placed at 1:02:05.2, so a person nudging a cut watches
+   * the clock disagree with the frame. Truncating in tenths (and nudging past the
+   * representation error first) keeps the readout monotonic with the playhead.
+   */
+  const totalTenths = Math.floor(seconds * 10 + 1e-6);
+  const tenths = totalTenths % 10;
+  const whole = Math.floor(totalTenths / 10);
+  const s = whole % 60;
+  const m = Math.floor(whole / 60) % 60;
+  const h = Math.floor(whole / 3600);
+  const mm = h > 0 ? String(m).padStart(2, '0') : String(m);
+  return `${h > 0 ? `${h}:` : ''}${mm}:${String(s).padStart(2, '0')}.${tenths}`;
+}
+
+
+// ── The plan: split points, and which pieces are out ────────────────────────────────────
+
+/**
+ * What the editor holds: where the scissors have been, and which pieces are marked out.
+ *
+ * 🔴 `removed` names segments by their BOUNDS, not by an index. Indices shift the moment a
+ * new split lands anywhere to their left, so a plan stored as `removed: [2]` silently comes
+ * to mean a different piece of footage — and it would do so during the one gesture people use
+ * most, which is cutting again after looking at what they have. Bounds cannot drift: a
+ * segment either still exists with those bounds or it has been divided, and dividing one is
+ * handled explicitly below.
+ */
+export interface CutPlan {
+  /** Split points in seconds, sorted, unique, strictly inside `(0, duration)`. */
+  splits: number[];
+  /** The pieces marked for removal, by their `[start, end)` bounds. */
+  removed: VideoCut[];
+}
+
+export const EMPTY_PLAN: CutPlan = { splits: [], removed: [] };
+
+/** A segment of the clip, and whether it survives. */
+export interface PlanSegment extends VideoCut {
+  removed: boolean;
+  /** Stable across re-renders and safe as a React key — bounds, not position. */
+  key: string;
+}
+
+const segmentKey = (start: number, end: number): string => `${start.toFixed(3)}-${end.toFixed(3)}`;
+
+/** Sorted, unique, inside the clip, and never closer together than a frame. */
+function tidySplits(splits: readonly number[], duration: number): number[] {
+  if (!Number.isFinite(duration) || duration <= 0) return [];
+  const out: number[] = [];
+  for (const at of [...splits].filter(Number.isFinite).sort((a, b) => a - b)) {
+    if (at <= MIN_CUT_SECONDS || at >= duration - MIN_CUT_SECONDS) continue;
+    // A split a frame away from the previous one makes a segment no frame can live in — and
+    // an unclickable sliver on the strip, which is worse than refusing the cut.
+    if (out.length > 0 && at - (out[out.length - 1] as number) < MIN_CUT_SECONDS) continue;
+    out.push(at);
+  }
+  return out;
+}
+
+/** The clip, divided. Always covers `[0, duration)` exactly, with no gaps. */
+export function planSegments(plan: CutPlan, duration: number): PlanSegment[] {
+  if (!Number.isFinite(duration) || duration <= 0) return [];
+  const splits = tidySplits(plan.splits, duration);
+  const bounds = [0, ...splits, duration];
+  const out: PlanSegment[] = [];
+  for (let i = 0; i < bounds.length - 1; i++) {
+    const start = bounds[i] as number;
+    const end = bounds[i + 1] as number;
+    out.push({
+      start,
+      end,
+      key: segmentKey(start, end),
+      // A segment is removed when the plan holds a removal that COVERS it. Covers, not
+      // equals: a segment that was marked out and has since been split in two is two removed
+      // segments, and the alternative — dropping the mark on a re-split — silently restores
+      // footage somebody had already decided against.
+      removed: plan.removed.some((cut) => cut.start <= start + 1e-6 && cut.end >= end - 1e-6),
+    });
+  }
+  return out;
+}
+
+/** Cut here. A split inside a removed piece divides it into two removed pieces. */
+export function addSplit(plan: CutPlan, at: number, duration: number): CutPlan {
+  const splits = tidySplits([...plan.splits, at], duration);
+  if (splits.length === tidySplits(plan.splits, duration).length) return plan;
+  return { splits, removed: plan.removed };
+}
+
+/**
+ * Undo a cut, merging the two pieces either side.
+ *
+ * 🔴 The merged piece is removed only if BOTH halves were. Anything else invents an
+ * intention: promoting a half-removed merge to "removed" deletes footage nobody marked, and
+ * demoting it to "kept" restores footage somebody did mark. Requiring agreement means the
+ * only way to lose a decision is to have made two conflicting ones, and then the safe
+ * reading — keep it — is the one that costs nothing but another click.
+ */
+export function removeSplit(plan: CutPlan, at: number, duration: number): CutPlan {
+  const splits = tidySplits(plan.splits, duration);
+  const index = splits.findIndex((split) => Math.abs(split - at) < 1e-6);
+  if (index === -1) return plan;
+  const before = planSegments(plan, duration);
+  const left = before.find((segment) => Math.abs(segment.end - at) < 1e-6);
+  const right = before.find((segment) => Math.abs(segment.start - at) < 1e-6);
+  const nextSplits = [...splits.slice(0, index), ...splits.slice(index + 1)];
+  const nextPlan: CutPlan = { splits: nextSplits, removed: plan.removed };
+  if (!left || !right) return nextPlan;
+  const merged = { start: left.start, end: right.end };
+  const kept = plan.removed.filter(
+    (cut) => !(cut.start >= merged.start - 1e-6 && cut.end <= merged.end + 1e-6),
+  );
+  return {
+    splits: nextSplits,
+    removed: left.removed && right.removed ? [...kept, merged] : kept,
+  };
+}
+
+/** Mark a piece out, or put it back — the ✗ on a segment. */
+export function toggleSegment(plan: CutPlan, segment: VideoCut, duration: number): CutPlan {
+  const current = planSegments(plan, duration).find(
+    (candidate) => candidate.key === segmentKey(segment.start, segment.end),
+  );
+  if (!current) return plan;
+  if (current.removed) {
+    return {
+      splits: plan.splits,
+      // Drop every removal this segment sits inside, then put back the parts of a WIDER
+      // removal that are still meant to go — un-marking one piece of a span that was marked
+      // before it was split must not resurrect its neighbours.
+      removed: plan.removed.flatMap((cut) => {
+        if (!(cut.start <= current.start + 1e-6 && cut.end >= current.end - 1e-6)) return [cut];
+        const rest: VideoCut[] = [];
+        if (current.start - cut.start >= MIN_CUT_SECONDS)
+          rest.push({ start: cut.start, end: current.start });
+        if (cut.end - current.end >= MIN_CUT_SECONDS) rest.push({ start: current.end, end: cut.end });
+        return rest;
+      }),
+    };
+  }
+  return { splits: plan.splits, removed: [...plan.removed, { start: current.start, end: current.end }] };
+}
+
+/**
+ * The plan as the wire format — the spans to remove, normalized.
+ *
+ * Adjacent removed segments merge here, which is why the editor can let somebody mark three
+ * pieces in a row without producing three cuts the encoder has to join back up.
+ */
+export function planCuts(plan: CutPlan, duration: number): VideoCut[] {
+  return normalizeCuts(
+    planSegments(plan, duration)
+      .filter((segment) => segment.removed)
+      .map(({ start, end }) => ({ start, end })),
+    duration,
+  );
+}
+
+/** Why this plan cannot be sent, or `null`. The same two refusals, asked of a plan. */
+export function planProblem(plan: CutPlan, duration: number): string | null {
+  return cutListProblem(planCuts(plan, duration), duration);
+}

package/src/core/navigation/breadcrumbCompat.ts

@@ -0,0 +1,44 @@
+// Backward-compatible breadcrumb helpers for apps that maintain a flat node map
+// (key → label + optional parent key) rather than deriving the trail from a full
+// NavigationModel. Apps that have migrated to NavigationModel should use
+// deriveBreadcrumbTrail (navigationSelectors) instead.
+
+/** A node in a flat breadcrumb hierarchy map. */
+export interface BreadcrumbNode {
+  /** The stable key for this node (usually its path). */
+  key: string;
+  /** Human-readable label. */
+  label: string;
+  /** Key of the parent node, if any. Absent for root nodes. */
+  parent?: string;
+}
+
+/** A resolved breadcrumb crumb ready to render. */
+export interface BreadcrumbItem {
+  /** Stable key (used as the React list key). */
+  key: string;
+  /** Human-readable label. */
+  label: string;
+  /** Navigation target — omit for a non-interactive (current page) leaf. */
+  href?: string;
+}
+
+/**
+ * Walk `nodes` upward from `path` to the root and return the ancestor chain
+ * ordered root-first (Home → … → `path`). Returns `[]` when `path` is absent
+ * from the map.
+ */
+export function buildBreadcrumbTrail(
+  nodes: Record<string, BreadcrumbNode>,
+  path: string,
+): BreadcrumbItem[] {
+  const chain: BreadcrumbItem[] = [];
+  let cur: string | undefined = path;
+  while (cur) {
+    const node: BreadcrumbNode | undefined = nodes[cur];
+    if (!node) break;
+    chain.unshift({ key: node.key, label: node.label, href: node.key });
+    cur = node.parent;
+  }
+  return chain;
+}

package/src/core/navigation/coverageTest.ts

@@ -0,0 +1,54 @@
+// The anti-drift guarantee. `createCoverageTest` returns an assertion the consuming
+// app runs in its own `navigationModel.spec.ts`: it fails the build the instant a
+// route exists in `routes.tsx` that no one registered in the navigation model. Since
+// the side nav / hub tiles / breadcrumbs / search / palette ALL derive from that one
+// model, a registered route is automatically discoverable — and an unregistered one
+// can never silently bury. Framework-agnostic (throws a plain Error; works under
+// bun:test, vitest, jest) so the same factory drops into any app's spec file.
+
+import type { NavigationModel } from './navigationModel';
+import { deriveAllPaths, normalizeNavPath } from './navigationSelectors';
+
+/**
+ * Build the coverage assertion for `model` against `allRoutePaths` (the app's full
+ * route list, e.g. derived from `routes.tsx`). The returned `() => void` throws —
+ * listing every gap — when a route path is neither registered in the model nor
+ * registered as `deepLinkOnly` (both forms appear in {@link deriveAllPaths}).
+ *
+ * ```ts
+ * // ca/ru navigationModel.spec.ts
+ * import { test } from 'bun:test';
+ * test('every route is registered in the navigation model',
+ *   createCoverageTest(caNavigationModel, caAllRoutePaths));
+ * ```
+ *
+ * Route matching is by {@link normalizeNavPath} on both sides, so a `#tab=…` model
+ * entry covers its base route and a trailing slash is ignored.
+ */
+export function createCoverageTest(model: NavigationModel, allRoutePaths: string[]): () => void {
+  return () => {
+    const covered = new Set(deriveAllPaths(model).map(normalizeNavPath));
+    const missing = [...new Set(allRoutePaths.map((p) => p.trim()).filter(Boolean))]
+      .filter((p) => !covered.has(normalizeNavPath(p)))
+      .sort();
+    if (missing.length > 0) {
+      throw new Error(
+        `navigationModel coverage gap — ${missing.length} route path(s) are not registered.\n` +
+          'Add each to a domain group (or mark it deepLinkOnly) so it can never silently bury:\n' +
+          missing.map((p) => `  • ${p}`).join('\n'),
+      );
+    }
+  };
+}
+
+/**
+ * Non-throwing companion — the raw set of route paths missing from the model. Useful
+ * during a migration (N1 of the IA overhaul) to *enumerate* the discovery gaps
+ * before fixing them, rather than failing on the first one.
+ */
+export function findCoverageGaps(model: NavigationModel, allRoutePaths: string[]): string[] {
+  const covered = new Set(deriveAllPaths(model).map(normalizeNavPath));
+  return [...new Set(allRoutePaths.map((p) => p.trim()).filter(Boolean))]
+    .filter((p) => !covered.has(normalizeNavPath(p)))
+    .sort();
+}

package/src/core/navigation/index.ts

@@ -0,0 +1,50 @@
+// `cursedbelt-core/navigation` — the navigation contract + pure selectors. React-free and
+// routing-free: the single source of truth (the IA tree) plus every derivation off
+// it (side nav, hub tiles, breadcrumbs, search catalogue, coverage test, prefs
+// migration). The React components in `cursedbelt/react` consume exactly this.
+
+export {
+  type BreadcrumbItem,
+  type BreadcrumbNode,
+  buildBreadcrumbTrail,
+} from './breadcrumbCompat';
+export {
+  createCoverageTest,
+  findCoverageGaps,
+} from './coverageTest';
+export {
+  CURRENT_NAV_PREFS_VERSION,
+  type LegacyNavPrefs,
+  type MigrateNavPrefsOptions,
+  migrateNavPreferences,
+  type NavPreferences,
+  type NavTilePrefs,
+} from './migrateNavPreferences';
+export {
+  allowAllGate,
+  type GateFn,
+  type NavDomain,
+  type NavGate,
+  type NavGroup,
+  type NavHostLimit,
+  type NavItem,
+  type NavigationModel,
+} from './navigationModel';
+export {
+  deriveAllPaths,
+  deriveBreadcrumbTrail,
+  deriveDomain,
+  deriveDomainGroups,
+  deriveDomainItems,
+  deriveSearchCatalogue,
+  deriveSideNavDomains,
+  type NavCrumb,
+  normalizeNavPath,
+  type SearchCatalogueEntry,
+} from './navigationSelectors';
+export {
+  type CatalogueHit,
+  type CatalogueResultGroup,
+  groupCatalogueHits,
+  rankCatalogue,
+} from './searchCatalogue';

package/src/core/navigation/migrateNavPreferences.ts

@@ -0,0 +1,119 @@
+// 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.
+
+import type { NavigationModel } from './navigationModel';
+
+/** Bump when the migration logic or the prefs shape changes. */
+export const CURRENT_NAV_PREFS_VERSION = 1;
+
+/** Per-hub tile customization (keyed by item path/id within a domain). */
+export interface NavTilePrefs {
+  /** Saved tile order (item ids). */
+  order?: string[];
+  /** Hidden tile ids. */
+  hidden?: string[];
+  /** Per-tile accent override (item id → hex). */
+  colors?: Record<string, string>;
+}
+
+/** The post-migration navigation preferences. */
+export interface NavPreferences {
+  /** Stamp — equals {@link CURRENT_NAV_PREFS_VERSION} after a successful migration. */
+  version: number;
+  /** Side-nav domain order (domain ids). */
+  order?: string[];
+  /** Hidden domain ids (removed from the side-nav rail; restorable). */
+  hidden?: string[];
+  /** Per-domain accent override (domain id → hex). */
+  colors?: Record<string, string>;
+  /** Collapsed rail section labels (see `NavDomain.section`). */
+  collapsedSections?: string[];
+  /** Per-domain hub-tile customization (domain id → {@link NavTilePrefs}). */
+  hubs?: Record<string, NavTilePrefs>;
+}
+
+/** The legacy (pre-overhaul) shape: a top-level nav block + per-hub tile prefs. */
+export interface LegacyNavPrefs {
+  version?: number;
+  /** Old side-nav customization, keyed by route id. */
+  nav?: { order?: string[]; colors?: Record<string, string> };
+  /** Old hidden side-nav routes (route ids). */
+  hiddenNavRoutes?: string[];
+  /** Old per-hub tile prefs, keyed by the OLD hub id. */
+  hubs?: Record<string, NavTilePrefs>;
+}
+
+export interface MigrateNavPrefsOptions {
+  /**
+   * Old key → new domain id. Applied to side-nav route ids AND hub keys; unmapped
+   * keys pass through unchanged. When two old hubs map to one domain (an 8→6
+   * consolidation), their tile prefs are merged.
+   */
+  keyMap?: Record<string, string>;
+}
+
+const uniq = (xs: string[]): string[] => [...new Set(xs)];
+
+/** Merge two tile-pref blocks (union hidden, concat+dedupe order, later colors win). */
+function mergeTilePrefs(a: NavTilePrefs | undefined, b: NavTilePrefs): NavTilePrefs {
+  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: LegacyNavPrefs | NavPreferences | null | undefined,
+  model: NavigationModel,
+  options: MigrateNavPrefsOptions = {},
+): NavPreferences {
+  // 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 as NavPreferences;
+  }
+
+  const keyMap = options.keyMap ?? {};
+  const remap = (k: string) => keyMap[k] ?? k;
+  const domainIds = new Set((model?.domains ?? []).map((d) => d.id));
+  const legacy = (old ?? {}) as LegacyNavPrefs;
+
+  // 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: Record<string, string> = {};
+  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: Record<string, NavTilePrefs> = {};
+  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: NavPreferences = { 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;
+}