cursedbelt-core 1.0.0

package/src/core/category/category.spec.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  buildCategoryForest,
+  categoryPath,
+  createMemoryCategoryStore,
+  descendantCategoryIds,
+  flattenCategoryForest,
+  wouldCreateCycle,
+  type Category,
+} from './index';
+
+const cat = (id: string, parentId: string | null, label: string, order = 0): Category => ({
+  id,
+  parentId,
+  label,
+  order,
+  tenant: 't',
+});
+
+describe('buildCategoryForest', () => {
+  it('nests children under parents and sorts by order then label', () => {
+    const forest = buildCategoryForest([
+      cat('b', null, 'B', 1),
+      cat('a', null, 'A', 0),
+      cat('a2', 'a', 'Second', 1),
+      cat('a1', 'a', 'First', 0),
+    ]);
+    expect(forest.map((n) => n.id)).toEqual(['a', 'b']);
+    expect(forest[0]!.children.map((n) => n.id)).toEqual(['a1', 'a2']);
+    expect(forest[0]!.depth).toBe(0);
+    expect(forest[0]!.children[0]!.depth).toBe(1);
+  });
+
+  it('breaks ties on label when order is equal', () => {
+    const forest = buildCategoryForest([cat('z', null, 'Zebra', 0), cat('a', null, 'Apple', 0)]);
+    expect(forest.map((n) => n.label)).toEqual(['Apple', 'Zebra']);
+  });
+
+  it('treats orphans (missing parent) as roots without losing them', () => {
+    const forest = buildCategoryForest([cat('x', 'ghost', 'Orphan')]);
+    expect(forest.map((n) => n.id)).toEqual(['x']);
+  });
+
+  it('does not lose nodes or hang on a cyclic parent chain', () => {
+    // a -> b -> a is a pure cycle; both must still surface exactly once.
+    const forest = buildCategoryForest([cat('a', 'b', 'A'), cat('b', 'a', 'B')]);
+    const ids = flattenCategoryForest(forest).map((n) => n.id).sort();
+    expect(ids).toEqual(['a', 'b']);
+  });
+
+  it('emits every input category exactly once', () => {
+    const input = [cat('a', null, 'A'), cat('b', 'a', 'B'), cat('c', 'b', 'C'), cat('d', 'ghost', 'D')];
+    expect(flattenCategoryForest(buildCategoryForest(input)).length).toBe(input.length);
+  });
+});
+
+describe('categoryPath', () => {
+  const cats = [cat('a', null, 'A'), cat('b', 'a', 'B'), cat('c', 'b', 'C')];
+  it('returns the root→node breadcrumb', () => {
+    expect(categoryPath(cats, 'c').map((c) => c.id)).toEqual(['a', 'b', 'c']);
+  });
+  it('returns [] for an unknown id', () => {
+    expect(categoryPath(cats, 'nope')).toEqual([]);
+  });
+  it('is cycle-safe', () => {
+    const cyclic = [cat('a', 'b', 'A'), cat('b', 'a', 'B')];
+    expect(categoryPath(cyclic, 'a').length).toBeLessThanOrEqual(2);
+  });
+});
+
+describe('descendantCategoryIds', () => {
+  it('collects all descendants depth-first, excluding the root', () => {
+    const cats = [cat('a', null, 'A'), cat('b', 'a', 'B'), cat('c', 'b', 'C'), cat('d', 'a', 'D')];
+    expect(descendantCategoryIds(cats, 'a').sort()).toEqual(['b', 'c', 'd']);
+    expect(descendantCategoryIds(cats, 'b')).toEqual(['c']);
+    expect(descendantCategoryIds(cats, 'c')).toEqual([]);
+  });
+});
+
+describe('wouldCreateCycle', () => {
+  const cats = [cat('a', null, 'A'), cat('b', 'a', 'B'), cat('c', 'b', 'C')];
+  it('rejects self-parenting', () => {
+    expect(wouldCreateCycle(cats, 'a', 'a')).toBe(true);
+  });
+  it('rejects parenting under a descendant', () => {
+    expect(wouldCreateCycle(cats, 'a', 'c')).toBe(true);
+  });
+  it('allows a legal reparent and root moves', () => {
+    expect(wouldCreateCycle(cats, 'c', 'a')).toBe(false);
+    expect(wouldCreateCycle(cats, 'b', null)).toBe(false);
+  });
+});
+
+describe('createMemoryCategoryStore', () => {
+  it('creates with auto-incrementing sibling order and lists per tenant', () => {
+    let n = 0;
+    const store = createMemoryCategoryStore(() => `id${++n}`);
+    const a = store.create('t1', { label: 'A' });
+    const b = store.create('t1', { label: 'B' });
+    expect(a.order).toBe(0);
+    expect(b.order).toBe(1);
+    expect(store.list('t1').map((c) => c.id)).toEqual([a.id, b.id]);
+    expect(store.list('t2')).toEqual([]);
+  });
+
+  it('rejects creating under a missing parent', () => {
+    const store = createMemoryCategoryStore();
+    expect(() => store.create('t', { label: 'X', parentId: 'ghost' })).toThrow();
+  });
+
+  it('renames in place', () => {
+    const store = createMemoryCategoryStore();
+    const a = store.create('t', { label: 'A' });
+    const renamed = store.rename('t', a.id, 'Renamed');
+    expect(renamed.label).toBe('Renamed');
+    expect(store.list('t')[0]!.label).toBe('Renamed');
+  });
+
+  it('moves under a new parent but rejects cycles', () => {
+    const store = createMemoryCategoryStore();
+    const a = store.create('t', { label: 'A' });
+    const b = store.create('t', { label: 'B', parentId: a.id });
+    const moved = store.move('t', b.id, null);
+    expect(moved.parentId).toBeNull();
+    store.move('t', a.id, b.id); // legal now that b is a root
+    expect(() => store.move('t', b.id, a.id)).toThrow(); // b under a (its child) → cycle
+  });
+
+  it('promotes children to the removed category’s parent', () => {
+    const store = createMemoryCategoryStore();
+    const a = store.create('t', { label: 'A' });
+    const b = store.create('t', { label: 'B', parentId: a.id });
+    const c = store.create('t', { label: 'C', parentId: b.id });
+    store.remove('t', b.id);
+    const cats = store.list('t');
+    expect(cats.find((x) => x.id === c.id)!.parentId).toBe(a.id);
+    expect(cats.find((x) => x.id === b.id)).toBeUndefined();
+  });
+
+  it('remove is a no-op for an unknown id', () => {
+    const store = createMemoryCategoryStore();
+    expect(() => store.remove('t', 'ghost')).not.toThrow();
+  });
+});

package/src/core/category/index.ts

@@ -0,0 +1,19 @@
+// src/core/category — reusable hierarchical category/folder model, reaching consumers
+// through `cursedbelt/react`'s categoryTree. Pure and
+// React-free (the `TreeView` adapter lives in `cursedbelt/react`), so servers
+// can import the contract + store without pulling any UI runtime.
+
+export type {
+  Category,
+  CategoryCreateInput,
+  CategoryNode,
+  CategoryStore,
+} from './types';
+export {
+  buildCategoryForest,
+  categoryPath,
+  descendantCategoryIds,
+  flattenCategoryForest,
+  wouldCreateCycle,
+} from './tree';
+export { createMemoryCategoryStore } from './memoryStore';

package/src/core/category/memoryStore.ts

@@ -0,0 +1,104 @@
+import type { Category, CategoryCreateInput, CategoryStore } from './types';
+import { wouldCreateCycle } from './tree';
+
+/**
+ * Zero-config in-memory {@link CategoryStore}: a per-boot `Map` per tenant, so a
+ * host that wires nothing up still gets a working (non-persistent) category
+ * tree — the same role `createMemoryNotesStore`/`createMemoryAuditSink` play.
+ * Swap in a persistent store (f's `createSqliteCategoryStore`) for real data.
+ *
+ * Deliberately not annotated `: CategoryStore` — the interface allows async
+ * returns, which would force callers (and these tests) to `await` values that
+ * are always synchronous here. Structural typing keeps it assignable wherever a
+ * `CategoryStore` is expected.
+ */
+export function createMemoryCategoryStore(idFactory: () => string = () => crypto.randomUUID()) {
+  const byTenant = new Map<string, Map<string, Category>>();
+
+  const tenantMap = (tenant: string): Map<string, Category> => {
+    let map = byTenant.get(tenant);
+    if (!map) {
+      map = new Map();
+      byTenant.set(tenant, map);
+    }
+    return map;
+  };
+
+  const requireCategory = (map: Map<string, Category>, id: string): Category => {
+    const cat = map.get(id);
+    if (!cat) throw new Error(`no category with id ${id}`);
+    return cat;
+  };
+
+  /** Next order value at a level = max sibling order + 1 (append to the end). */
+  const nextOrder = (map: Map<string, Category>, parentId: string | null): number => {
+    let max = -1;
+    for (const c of map.values()) {
+      if (c.parentId === parentId && c.order > max) max = c.order;
+    }
+    return max + 1;
+  };
+
+  return {
+    list(tenant: string): Category[] {
+      return [...tenantMap(tenant).values()];
+    },
+
+    create(tenant: string, input: CategoryCreateInput): Category {
+      const map = tenantMap(tenant);
+      const parentId = input.parentId ?? null;
+      if (parentId !== null && !map.has(parentId)) {
+        throw new Error(`no parent category with id ${parentId}`);
+      }
+      const category: Category = {
+        id: idFactory(),
+        parentId,
+        label: input.label,
+        order: input.order ?? nextOrder(map, parentId),
+        tenant,
+      };
+      map.set(category.id, category);
+      return category;
+    },
+
+    rename(tenant: string, id: string, label: string): Category {
+      const map = tenantMap(tenant);
+      const cat = requireCategory(map, id);
+      const updated = { ...cat, label };
+      map.set(id, updated);
+      return updated;
+    },
+
+    move(tenant: string, id: string, parentId: string | null, order?: number): Category {
+      const map = tenantMap(tenant);
+      const cat = requireCategory(map, id);
+      if (parentId !== null && !map.has(parentId)) {
+        throw new Error(`no parent category with id ${parentId}`);
+      }
+      if (wouldCreateCycle([...map.values()], id, parentId)) {
+        throw new Error(`moving ${id} under ${parentId} would create a cycle`);
+      }
+      const updated: Category = {
+        ...cat,
+        parentId,
+        order: order ?? nextOrder(map, parentId),
+      };
+      map.set(id, updated);
+      return updated;
+    },
+
+    /** Remove a category, promoting its direct children to the removed node's
+     * own parent so no subtree is orphaned. */
+    remove(tenant: string, id: string): void {
+      const map = tenantMap(tenant);
+      const cat = map.get(id);
+      if (!cat) return;
+      for (const child of map.values()) {
+        if (child.parentId === id) {
+          map.set(child.id, { ...child, parentId: cat.parentId });
+        }
+      }
+      map.delete(id);
+    },
+  };
+}

package/src/core/category/tree.ts

@@ -0,0 +1,118 @@
+import type { Category, CategoryNode } from './types';
+
+/** Sort siblings by explicit `order`, then label (locale-aware, stable). */
+function compareSiblings(a: Category, b: Category): number {
+  return a.order - b.order || a.label.localeCompare(b.label);
+}
+
+/**
+ * Would setting `childId`'s parent to `candidateParentId` create a cycle?
+ * True when the candidate parent is the child itself or one of its
+ * descendants — i.e. walking UP from the candidate reaches the child.
+ */
+export function wouldCreateCycle(
+  cats: Category[],
+  childId: string,
+  candidateParentId: string | null,
+): boolean {
+  if (candidateParentId === null) return false;
+  if (candidateParentId === childId) return true;
+  const byId = new Map(cats.map((c) => [c.id, c]));
+  let cursor: string | null = candidateParentId;
+  const seen = new Set<string>();
+  while (cursor !== null) {
+    if (cursor === childId) return true;
+    if (seen.has(cursor)) break; // pre-existing cycle in the data — stop, don't hang
+    seen.add(cursor);
+    cursor = byId.get(cursor)?.parentId ?? null;
+  }
+  return false;
+}
+
+/**
+ * Assemble a flat category list into a sorted forest of {@link CategoryNode}s.
+ * Defensive by construction — a category is treated as a root when its
+ * `parentId` is `null`, points at a missing category (orphan), or would form a
+ * cycle. So malformed data never loses a node or infinite-loops; every input
+ * category appears exactly once in the output.
+ */
+export function buildCategoryForest(cats: Category[]): CategoryNode[] {
+  const byId = new Map<string, CategoryNode>(
+    cats.map((c) => [c.id, { ...c, children: [], depth: 0 }]),
+  );
+  const roots: CategoryNode[] = [];
+  for (const node of byId.values()) {
+    const parent = node.parentId !== null ? byId.get(node.parentId) : undefined;
+    if (parent && !wouldCreateCycle(cats, node.id, node.parentId)) {
+      parent.children.push(node);
+    } else {
+      roots.push(node);
+    }
+  }
+  const sortLevel = (level: CategoryNode[], depth: number): void => {
+    level.sort(compareSiblings);
+    for (const node of level) {
+      node.depth = depth;
+      sortLevel(node.children, depth + 1);
+    }
+  };
+  sortLevel(roots, 0);
+  return roots;
+}
+
+/** Flatten a forest into pre-order (parent before its children), preserving the
+ * sibling ordering {@link buildCategoryForest} established. */
+export function flattenCategoryForest(forest: CategoryNode[]): CategoryNode[] {
+  const out: CategoryNode[] = [];
+  const visit = (nodes: CategoryNode[]): void => {
+    for (const node of nodes) {
+      out.push(node);
+      visit(node.children);
+    }
+  };
+  visit(forest);
+  return out;
+}
+
+/**
+ * The root→node breadcrumb path for `id` (inclusive), or `[]` when the id is
+ * unknown. Cycle-safe — stops if the parent chain ever revisits a node.
+ */
+export function categoryPath(cats: Category[], id: string): Category[] {
+  const byId = new Map(cats.map((c) => [c.id, c]));
+  const trail: Category[] = [];
+  const seen = new Set<string>();
+  let cursor: string | null = id;
+  while (cursor !== null) {
+    const cat = byId.get(cursor);
+    if (!cat || seen.has(cursor)) break;
+    seen.add(cursor);
+    trail.push(cat);
+    cursor = cat.parentId;
+  }
+  return trail.reverse();
+}
+
+/** Every descendant id of `id` (excluding `id` itself), depth-first. Used by a
+ * store's `remove`/`move` to reason about a subtree. */
+export function descendantCategoryIds(cats: Category[], id: string): string[] {
+  const childrenByParent = new Map<string, Category[]>();
+  for (const c of cats) {
+    if (c.parentId === null) continue;
+    const list = childrenByParent.get(c.parentId) ?? [];
+    list.push(c);
+    childrenByParent.set(c.parentId, list);
+  }
+  const out: string[] = [];
+  const seen = new Set<string>([id]);
+  const visit = (parentId: string): void => {
+    for (const child of childrenByParent.get(parentId) ?? []) {
+      if (seen.has(child.id)) continue; // cycle guard
+      seen.add(child.id);
+      out.push(child.id);
+      visit(child.id);
+    }
+  };
+  visit(id);
+  return out;
+}

package/src/core/category/types.ts

@@ -0,0 +1,59 @@
+// src/core/category — a reusable, hierarchical category/folder model shared
+// by content plugins (notes today; snippets/aliases/… later). React-free and
+// storage-agnostic: the pure `Category` data + a host-injected `CategoryStore`
+// contract, mirroring how `cwip`'s `AuditSink` and cursedshell's `NotesStore`
+// ship a pure contract that a host backs with its own (SQLite) implementation.
+// The cursedbelt `TreeView` adapter lives in the React layer, so importing this
+// module on a server (e.g. f's covert-GET backend) never pulls React.
+
+/** One node in a category tree. Roots have `parentId === null`. `order` sorts
+ * siblings ascending; `tenant` scopes every category to its owner so two
+ * tenants' trees never collide. */
+export interface Category {
+  id: string;
+  parentId: string | null;
+  label: string;
+  order: number;
+  tenant: string;
+}
+
+/** Fields a caller supplies when creating a category — the store assigns `id`,
+ * `tenant` (from the call), and a default `order` when omitted. */
+export interface CategoryCreateInput {
+  label: string;
+  parentId?: string | null;
+  order?: number;
+}
+
+/**
+ * A `Category` assembled into a tree by {@link buildCategoryForest} — its
+ * resolved `children` plus a `depth` (0 at the root) for indentation without a
+ * second traversal.
+ */
+export interface CategoryNode extends Category {
+  children: CategoryNode[];
+  depth: number;
+}
+
+/**
+ * Storage-agnostic, tenant-scoped category store. The host injects a real
+ * implementation (f backs it with SQLite); {@link createMemoryCategoryStore}
+ * is the zero-config in-memory default. Every method is tenant-first, matching
+ * the `NotesStore`/`AliasStore` contracts so a host can resolve the tenant to a
+ * per-role DB handle identically.
+ *
+ * `remove` promotes a removed category's direct children to its own parent
+ * (they are never silently dropped); a host that also stores per-item
+ * `categoryId`s is responsible for re-pointing those items (to the parent or
+ * `null`) in the same transaction.
+ */
+export interface CategoryStore {
+  list(tenant: string): Category[] | Promise<Category[]>;
+  create(tenant: string, input: CategoryCreateInput): Category | Promise<Category>;
+  rename(tenant: string, id: string, label: string): Category | Promise<Category>;
+  /** Reparent (and optionally reorder) a category. Passing `parentId` equal to
+   * `id` or to one of the category's own descendants is rejected — it would
+   * orphan a subtree by creating a cycle. */
+  move(tenant: string, id: string, parentId: string | null, order?: number): Category | Promise<Category>;
+  remove(tenant: string, id: string): void | Promise<void>;
+}

package/src/core/color.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'bun:test';
+import { contrastText } from './color';
+
+describe('contrastText', () => {
+  it('returns white on dark backgrounds', () => {
+    expect(contrastText('#000000')).toBe('white');
+    expect(contrastText('#111827')).toBe('white'); // gray-900
+    expect(contrastText('#1f2937')).toBe('white'); // slate-800
+    expect(contrastText('#7c3aed')).toBe('white'); // violet-600
+    expect(contrastText('#dc2626')).toBe('white'); // red-600
+  });
+
+  it('returns black on light backgrounds', () => {
+    expect(contrastText('#ffffff')).toBe('black');
+    expect(contrastText('#f59e0b')).toBe('black'); // amber-500
+    expect(contrastText('#facc15')).toBe('black'); // yellow-400
+    expect(contrastText('#22c55e')).toBe('black'); // green-500
+    // Mid-tones where WCAG luminance (unlike the old YIQ@0.6 formula) correctly
+    // prefers black for a higher contrast ratio.
+    expect(contrastText('#3b82f6')).toBe('black'); // blue-500
+    expect(contrastText('#a855f7')).toBe('black'); // purple-500
+  });
+
+  it('accepts hex without a leading # and 3-digit shorthand', () => {
+    expect(contrastText('000')).toBe('white');
+    expect(contrastText('fff')).toBe('black');
+    expect(contrastText('1f2937')).toBe('white');
+  });
+
+  it('falls back to white for unparseable input', () => {
+    expect(contrastText('')).toBe('white');
+    expect(contrastText('not-a-color')).toBe('white');
+    expect(contrastText('#12')).toBe('white');
+  });
+});

package/src/core/color.ts

@@ -0,0 +1,35 @@
+// Framework-agnostic color helpers. Pure functions over hex strings — no React,
+// no DOM — so they're usable in the apps, on the server, and in tests.
+
+/**
+ * Pick the readable foreground keyword (`'black'` or `'white'`) for text on a solid
+ * hex background, using the WCAG relative-luminance formula (sRGB gamma-expanded).
+ *
+ * Returns CSS color keywords (not hex) so a call site can drop the result straight
+ * into a `color:` style. Accepts 3- or 6-digit hex, with or without a leading `#`;
+ * an unparseable input falls back to `'white'` (legible on most accent colors).
+ *
+ * This is the canonical contrast primitive. The nav toolkit's `readableTextOn`
+ * (`react/nav/colors.ts`) and the spreadsheet theme's `contrastOn` deliberately
+ * return tuned near-black/near-white *hex* with their own thresholds for those
+ * surfaces; this returns pure keywords on the standard WCAG threshold.
+ */
+export function contrastText(hex: string): 'black' | 'white' {
+  const c = hex.replace('#', '').trim();
+  const full =
+    c.length === 3
+      ? c
+          .split('')
+          .map((ch) => ch + ch)
+          .join('')
+      : c;
+  if (!/^[0-9a-f]{6}$/i.test(full)) return 'white';
+  const r = Number.parseInt(full.slice(0, 2), 16) / 255;
+  const g = Number.parseInt(full.slice(2, 4), 16) / 255;
+  const b = Number.parseInt(full.slice(4, 6), 16) / 255;
+  const [rs, gs, bs] = [r, g, b].map((v) =>
+    v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4,
+  );
+  const luminance = 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+  return luminance > 0.179 ? 'black' : 'white';
+}

package/src/core/colorScheme/colorScheme.spec.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  COLOR_SCHEME_STORAGE_KEY,
+  type ColorSchemeStorage,
+  createColorSchemeStore,
+  type ResolvedColorScheme,
+} from './index';
+
+const makeStorage = (): ColorSchemeStorage & { map: Map<string, string> } => {
+  const map = new Map<string, string>();
+  return {
+    map,
+    getItem: (k) => map.get(k) ?? null,
+    setItem: (k, v) => void map.set(k, v),
+    removeItem: (k) => void map.delete(k),
+  };
+};
+
+describe('color-scheme store (injected side-effects)', () => {
+  test('defaults to system mode resolving through the OS preference', () => {
+    const store = createColorSchemeStore({ getSystemScheme: () => 'dark' });
+    expect(store.getMode()).toBe('system');
+    expect(store.getResolved()).toBe('dark');
+  });
+
+  test('hydrates an explicit stored choice; garbage in storage → system', () => {
+    const storage = makeStorage();
+    storage.map.set(COLOR_SCHEME_STORAGE_KEY, 'dark');
+    expect(createColorSchemeStore({ storage }).getResolved()).toBe('dark');
+
+    const garbage = makeStorage();
+    garbage.map.set(COLOR_SCHEME_STORAGE_KEY, 'blurple');
+    expect(createColorSchemeStore({ storage: garbage }).getMode()).toBe('system');
+  });
+
+  test('setMode persists + applies + notifies; system clears the override', () => {
+    const storage = makeStorage();
+    const applied: ResolvedColorScheme[] = [];
+    const store = createColorSchemeStore({ storage, apply: (s) => applied.push(s) });
+    let notifications = 0;
+    const unsub = store.subscribe(() => notifications++);
+
+    store.setMode('dark');
+    expect(storage.getItem(COLOR_SCHEME_STORAGE_KEY)).toBe('dark');
+    expect(applied).toEqual(['dark']);
+    expect(notifications).toBe(1);
+
+    store.setMode('system');
+    expect(storage.getItem(COLOR_SCHEME_STORAGE_KEY)).toBeNull();
+    expect(applied).toEqual(['dark', 'light']);
+    unsub();
+  });
+
+  test('toggle flips the RESOLVED scheme and stores it explicitly', () => {
+    const storage = makeStorage();
+    const store = createColorSchemeStore({ storage, getSystemScheme: () => 'dark' });
+    expect(store.getResolved()).toBe('dark'); // system → OS dark
+    store.toggle();
+    expect(store.getMode()).toBe('light'); // explicit now
+    expect(storage.getItem(COLOR_SCHEME_STORAGE_KEY)).toBe('light');
+    store.toggle();
+    expect(store.getMode()).toBe('dark');
+  });
+
+  test('init applies the resolved scheme and follows OS changes only in system mode', () => {
+    let system: ResolvedColorScheme = 'light';
+    let systemListener: (() => void) | undefined;
+    const applied: ResolvedColorScheme[] = [];
+    const store = createColorSchemeStore({
+      storage: makeStorage(),
+      apply: (s) => applied.push(s),
+      getSystemScheme: () => system,
+      onSystemChange: (l) => {
+        systemListener = l;
+        return () => {
+          systemListener = undefined;
+        };
+      },
+    });
+
+    store.init();
+    expect(applied).toEqual(['light']);
+
+    // OS flips while in system mode → re-applied.
+    system = 'dark';
+    systemListener?.();
+    expect(applied).toEqual(['light', 'dark']);
+
+    // Explicit choice pins the scheme; OS flips are ignored.
+    store.setMode('light');
+    system = 'light';
+    systemListener?.();
+    expect(applied).toEqual(['light', 'dark', 'light']);
+  });
+
+  test('an out-of-band class change (devtools, a screenshot harness) drops the cached mode and re-notifies', () => {
+    // Simulates cursedshell's screenshot-engine: it sets localStorage AND toggles
+    // the `.dark` class directly via CDP, bypassing setMode()/commit() entirely —
+    // so the store must re-hydrate from storage rather than trust its stale cache.
+    const storage = makeStorage();
+    let externalListener: (() => void) | undefined;
+    const store = createColorSchemeStore({
+      storage,
+      getSystemScheme: () => 'light',
+      onExternalChange: (l) => {
+        externalListener = l;
+        return () => {
+          externalListener = undefined;
+        };
+      },
+    });
+
+    expect(store.getResolved()).toBe('light'); // hydrates + caches 'system' → light
+    store.init();
+
+    // Something outside the store flips storage + the DOM class without calling setMode.
+    storage.map.set(COLOR_SCHEME_STORAGE_KEY, 'dark');
+    let notifications = 0;
+    const unsub = store.subscribe(() => notifications++);
+    externalListener?.();
+
+    expect(notifications).toBe(1);
+    expect(store.getMode()).toBe('dark'); // re-hydrated from storage, not the stale cache
+    expect(store.getResolved()).toBe('dark');
+    unsub();
+  });
+});