cursedbelt 2.7.0 → 3.0.0

package/src/core/media/videoCuts.ts

@@ -1,355 +0,0 @@
-/**
- * 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/media-core`, 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

@@ -1,44 +0,0 @@
-// 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

@@ -1,54 +0,0 @@
-// 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

@@ -1,50 +0,0 @@
-// `cursedbelt/nav` — 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

@@ -1,119 +0,0 @@
-// 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;
-}