cursedbelt-core 1.0.0

package/dist/core/category/index.js

@@ -0,0 +1,6 @@
+// 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 { buildCategoryForest, categoryPath, descendantCategoryIds, flattenCategoryForest, wouldCreateCycle, } from './tree';
+export { createMemoryCategoryStore } from './memoryStore';

package/dist/core/category/memoryStore.d.ts

@@ -0,0 +1,21 @@
+import type { Category, CategoryCreateInput } from './types';
+/**
+ * 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 declare function createMemoryCategoryStore(idFactory?: () => string): {
+    list(tenant: string): Category[];
+    create(tenant: string, input: CategoryCreateInput): Category;
+    rename(tenant: string, id: string, label: string): Category;
+    move(tenant: string, id: string, parentId: string | null, order?: number): Category;
+    /** 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;
+};

package/dist/core/category/memoryStore.js

@@ -0,0 +1,97 @@
+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 = () => crypto.randomUUID()) {
+    const byTenant = new Map();
+    const tenantMap = (tenant) => {
+        let map = byTenant.get(tenant);
+        if (!map) {
+            map = new Map();
+            byTenant.set(tenant, map);
+        }
+        return map;
+    };
+    const requireCategory = (map, id) => {
+        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, parentId) => {
+        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) {
+            return [...tenantMap(tenant).values()];
+        },
+        create(tenant, input) {
+            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 = {
+                id: idFactory(),
+                parentId,
+                label: input.label,
+                order: input.order ?? nextOrder(map, parentId),
+                tenant,
+            };
+            map.set(category.id, category);
+            return category;
+        },
+        rename(tenant, id, label) {
+            const map = tenantMap(tenant);
+            const cat = requireCategory(map, id);
+            const updated = { ...cat, label };
+            map.set(id, updated);
+            return updated;
+        },
+        move(tenant, id, parentId, order) {
+            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 = {
+                ...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, id) {
+            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/dist/core/category/tree.d.ts

@@ -0,0 +1,26 @@
+import type { Category, CategoryNode } from './types';
+/**
+ * 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 declare function wouldCreateCycle(cats: Category[], childId: string, candidateParentId: string | null): boolean;
+/**
+ * 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 declare function buildCategoryForest(cats: Category[]): CategoryNode[];
+/** Flatten a forest into pre-order (parent before its children), preserving the
+ * sibling ordering {@link buildCategoryForest} established. */
+export declare function flattenCategoryForest(forest: CategoryNode[]): CategoryNode[];
+/**
+ * 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 declare function categoryPath(cats: Category[], id: string): Category[];
+/** Every descendant id of `id` (excluding `id` itself), depth-first. Used by a
+ * store's `remove`/`move` to reason about a subtree. */
+export declare function descendantCategoryIds(cats: Category[], id: string): string[];

package/dist/core/category/tree.js

@@ -0,0 +1,113 @@
+/** Sort siblings by explicit `order`, then label (locale-aware, stable). */
+function compareSiblings(a, b) {
+    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, childId, candidateParentId) {
+    if (candidateParentId === null)
+        return false;
+    if (candidateParentId === childId)
+        return true;
+    const byId = new Map(cats.map((c) => [c.id, c]));
+    let cursor = candidateParentId;
+    const seen = new Set();
+    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) {
+    const byId = new Map(cats.map((c) => [c.id, { ...c, children: [], depth: 0 }]));
+    const roots = [];
+    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, depth) => {
+        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) {
+    const out = [];
+    const visit = (nodes) => {
+        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, id) {
+    const byId = new Map(cats.map((c) => [c.id, c]));
+    const trail = [];
+    const seen = new Set();
+    let cursor = 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, id) {
+    const childrenByParent = new Map();
+    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 = [];
+    const seen = new Set([id]);
+    const visit = (parentId) => {
+        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/dist/core/category/types.d.ts

@@ -0,0 +1,48 @@
+/** 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/dist/core/category/types.js

@@ -0,0 +1,8 @@
+// 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.
+export {};

package/dist/core/color.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function contrastText(hex: string): 'black' | 'white';

package/dist/core/color.js

@@ -0,0 +1,32 @@
+// 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) {
+    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/dist/core/colorScheme/colorSchemeStore.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The color-scheme store: holds the current light/dark preference, persists it,
+ * applies it to the document root (the `.dark` class from `theme.css`'s contract),
+ * and notifies subscribers. Split from the React hook so it works before React
+ * mounts (call {@link initColorScheme} early to apply the saved scheme with no
+ * flash) and so its logic is testable without a DOM.
+ *
+ * Three modes, two resolved schemes: `'system'` (the default when nothing is
+ * stored) follows `prefers-color-scheme` live; picking light/dark via the toggle
+ * stores an explicit override. Side-effects (storage, applying to the page, the
+ * OS preference) are injected, so a test drives a real store with fakes; the
+ * exported default singleton binds them to `localStorage`, the `<html>` element,
+ * and `matchMedia`.
+ */
+/** What the user chose. `'system'` = no explicit choice, follow the OS. */
+export type ColorSchemeMode = 'light' | 'dark' | 'system';
+/** What the page actually renders. */
+export type ResolvedColorScheme = 'light' | 'dark';
+/** The slice of the Web Storage API the store needs (so a test can fake it). */
+export interface ColorSchemeStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface ColorSchemeStore {
+    /** Current mode (lazily hydrated from storage on first read). */
+    getMode(): ColorSchemeMode;
+    /** The scheme the page renders: the mode, or the OS preference under `'system'`. */
+    getResolved(): ResolvedColorScheme;
+    /** Set, persist, apply, and notify. `'system'` clears the stored override. */
+    setMode(mode: ColorSchemeMode): void;
+    /** Flip to the opposite of the currently *resolved* scheme (always explicit). */
+    toggle(): void;
+    /** Apply the persisted scheme to the page + start following OS changes while in
+     *  `'system'` mode (call once on app boot). Idempotent. */
+    init(): void;
+    subscribe(listener: () => void): () => void;
+}
+export interface ColorSchemeStoreOptions {
+    storage?: ColorSchemeStorage | null;
+    /** Apply a resolved scheme to the page. Default toggles `.dark` on `<html>`. */
+    apply?: (scheme: ResolvedColorScheme) => void;
+    /** Read the OS preference (default: `matchMedia('(prefers-color-scheme: dark)')`). */
+    getSystemScheme?: () => ResolvedColorScheme;
+    /** Subscribe to OS preference changes; returns an unsubscribe. */
+    onSystemChange?: (listener: () => void) => () => void;
+    /** Subscribe to the root element's `.dark` class being changed by something OTHER
+     *  than this store (devtools, a screenshot/visual-test harness driving the DOM
+     *  directly). Returns an unsubscribe. Default: a `MutationObserver` on
+     *  `document.documentElement`'s `class`/`style` attributes. */
+    onExternalChange?: (listener: () => void) => () => void;
+    /** localStorage key. */
+    key?: string;
+}
+export declare const COLOR_SCHEME_STORAGE_KEY = "cwip.colorScheme";
+export declare function createColorSchemeStore(options?: ColorSchemeStoreOptions): ColorSchemeStore;
+/** Apply a resolved scheme to the document root via the `theme.css` contract:
+ *  the `.dark` class on `<html>` (never `data-theme`, never the media query —
+ *  `dark:` utilities and every token consumer key off this class). SSR-safe. */
+export declare function applyColorSchemeToDocument(scheme: ResolvedColorScheme): void;
+/** The app-wide singleton bound to localStorage + the page + the OS preference. */
+export declare const colorSchemeStore: ColorSchemeStore;
+export declare const getColorSchemeMode: () => ColorSchemeMode;
+export declare const getResolvedColorScheme: () => ResolvedColorScheme;
+export declare const setColorSchemeMode: (mode: ColorSchemeMode) => void;
+export declare const toggleColorScheme: () => void;
+export declare const subscribeColorScheme: (listener: () => void) => (() => void);
+/** Apply the saved scheme on app boot, before React mounts (no flash), and start
+ *  following the OS preference while no explicit choice is stored. */
+export declare const initColorScheme: () => void;

package/dist/core/colorScheme/colorSchemeStore.js

@@ -0,0 +1,123 @@
+/**
+ * The color-scheme store: holds the current light/dark preference, persists it,
+ * applies it to the document root (the `.dark` class from `theme.css`'s contract),
+ * and notifies subscribers. Split from the React hook so it works before React
+ * mounts (call {@link initColorScheme} early to apply the saved scheme with no
+ * flash) and so its logic is testable without a DOM.
+ *
+ * Three modes, two resolved schemes: `'system'` (the default when nothing is
+ * stored) follows `prefers-color-scheme` live; picking light/dark via the toggle
+ * stores an explicit override. Side-effects (storage, applying to the page, the
+ * OS preference) are injected, so a test drives a real store with fakes; the
+ * exported default singleton binds them to `localStorage`, the `<html>` element,
+ * and `matchMedia`.
+ */
+export const COLOR_SCHEME_STORAGE_KEY = 'cwip.colorScheme';
+const isMode = (v) => v === 'light' || v === 'dark';
+export function createColorSchemeStore(options = {}) {
+    const { storage = null, apply, getSystemScheme = () => 'light', onSystemChange, onExternalChange, key = COLOR_SCHEME_STORAGE_KEY, } = options;
+    const listeners = new Set();
+    let mode; // undefined until first hydrate
+    let watchingSystem = false;
+    let watchingExternal = false;
+    const hydrate = () => {
+        if (mode !== undefined)
+            return mode;
+        const raw = storage?.getItem(key);
+        mode = isMode(raw) ? raw : 'system';
+        return mode;
+    };
+    const resolve = () => {
+        const m = hydrate();
+        return m === 'system' ? getSystemScheme() : m;
+    };
+    const notify = () => {
+        for (const l of listeners)
+            l();
+    };
+    const commit = (next) => {
+        mode = next;
+        if (next === 'system')
+            storage?.removeItem(key);
+        else
+            storage?.setItem(key, next);
+        apply?.(resolve());
+        notify();
+    };
+    return {
+        getMode: hydrate,
+        getResolved: resolve,
+        setMode: commit,
+        toggle: () => commit(resolve() === 'dark' ? 'light' : 'dark'),
+        init() {
+            apply?.(resolve());
+            if (!watchingSystem && onSystemChange) {
+                watchingSystem = true;
+                onSystemChange(() => {
+                    // Only the resolved scheme changed; re-apply + notify while following the OS.
+                    if (hydrate() === 'system') {
+                        apply?.(resolve());
+                        notify();
+                    }
+                });
+            }
+            if (!watchingExternal && onExternalChange) {
+                watchingExternal = true;
+                onExternalChange(() => {
+                    // Something outside this store (devtools, a visual-test harness) touched
+                    // the root's `.dark` class/localStorage directly — drop the cached mode
+                    // so the next read re-hydrates from storage, and tell every subscriber
+                    // (the theme toggle, etc.) to re-check so they can't render stale.
+                    mode = undefined;
+                    notify();
+                });
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+/** Apply a resolved scheme to the document root via the `theme.css` contract:
+ *  the `.dark` class on `<html>` (never `data-theme`, never the media query —
+ *  `dark:` utilities and every token consumer key off this class). SSR-safe. */
+export function applyColorSchemeToDocument(scheme) {
+    if (typeof document === 'undefined')
+        return;
+    document.documentElement.classList.toggle('dark', scheme === 'dark');
+    // Hint native form controls/scrollbars so they match the app chrome.
+    document.documentElement.style.colorScheme = scheme;
+}
+const defaultStorage = typeof localStorage !== 'undefined' ? localStorage : null;
+const darkQuery = () => typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+    ? window.matchMedia('(prefers-color-scheme: dark)')
+    : null;
+/** The app-wide singleton bound to localStorage + the page + the OS preference. */
+export const colorSchemeStore = createColorSchemeStore({
+    storage: defaultStorage,
+    apply: applyColorSchemeToDocument,
+    getSystemScheme: () => (darkQuery()?.matches ? 'dark' : 'light'),
+    onSystemChange: (listener) => {
+        const q = darkQuery();
+        if (!q)
+            return () => { };
+        q.addEventListener('change', listener);
+        return () => q.removeEventListener('change', listener);
+    },
+    onExternalChange: (listener) => {
+        if (typeof document === 'undefined' || typeof MutationObserver === 'undefined')
+            return () => { };
+        const observer = new MutationObserver(listener);
+        observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'style'] });
+        return () => observer.disconnect();
+    },
+});
+export const getColorSchemeMode = () => colorSchemeStore.getMode();
+export const getResolvedColorScheme = () => colorSchemeStore.getResolved();
+export const setColorSchemeMode = (mode) => colorSchemeStore.setMode(mode);
+export const toggleColorScheme = () => colorSchemeStore.toggle();
+export const subscribeColorScheme = (listener) => colorSchemeStore.subscribe(listener);
+/** Apply the saved scheme on app boot, before React mounts (no flash), and start
+ *  following the OS preference while no explicit choice is stored. */
+export const initColorScheme = () => colorSchemeStore.init();

package/dist/core/colorScheme/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Color-scheme core (framework-free) — the localStorage/document store behind the
+ * app-wide light/dark toggle. `initColorScheme()` applies the saved (or OS) scheme
+ * on app boot (before React mounts → no flash); the React control + hook live in
+ * `cursedbelt/react` (`ThemeToggle`, `useColorScheme`).
+ */
+export { applyColorSchemeToDocument, COLOR_SCHEME_STORAGE_KEY, type ColorSchemeMode, type ColorSchemeStorage, type ColorSchemeStore, type ColorSchemeStoreOptions, colorSchemeStore, createColorSchemeStore, getColorSchemeMode, getResolvedColorScheme, initColorScheme, type ResolvedColorScheme, setColorSchemeMode, subscribeColorScheme, toggleColorScheme, } from './colorSchemeStore';

package/dist/core/colorScheme/index.js

@@ -0,0 +1,7 @@
+/**
+ * Color-scheme core (framework-free) — the localStorage/document store behind the
+ * app-wide light/dark toggle. `initColorScheme()` applies the saved (or OS) scheme
+ * on app boot (before React mounts → no flash); the React control + hook live in
+ * `cursedbelt/react` (`ThemeToggle`, `useColorScheme`).
+ */
+export { applyColorSchemeToDocument, COLOR_SCHEME_STORAGE_KEY, colorSchemeStore, createColorSchemeStore, getColorSchemeMode, getResolvedColorScheme, initColorScheme, setColorSchemeMode, subscribeColorScheme, toggleColorScheme, } from './colorSchemeStore';

package/dist/core/domainOwners.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which engine owns which storage domain (01 §2.3/§5).
+ *
+ * Lives in `core/` because BOTH tiers need it and neither may import the other's
+ * graph: the server's CDC bridge fans a domain's writes to that engine's
+ * instances, and the client's DevStudio needs the domains an app can snapshot.
+ * A second copy on the client would be a map that drifts the day a domain moves
+ * — so there is one, here, with no dependency beyond cwip's domain names.
+ *
+ * `search` is knowledge's derived index and `staging` is a dev-time sandbox, so
+ * neither gets an engine of its own.
+ */
+import type { DomainName } from 'cwip/domains';
+export declare const DOMAIN_OWNER_ENGINE: Readonly<Record<DomainName, string>>;
+/**
+ * The domains a set of active engines owns, in DDL order. `staging` is excluded:
+ * it is never part of an exported app's storage map (V5 refuses it upstream).
+ */
+export declare const domainsForEngines: (engines: readonly string[]) => DomainName[];

package/dist/core/domainOwners.js

@@ -0,0 +1,15 @@
+export const DOMAIN_OWNER_ENGINE = Object.freeze({
+    knowledge: 'knowledge',
+    media: 'asset',
+    search: 'knowledge',
+    system: 'system',
+    staging: 'dev',
+});
+/**
+ * The domains a set of active engines owns, in DDL order. `staging` is excluded:
+ * it is never part of an exported app's storage map (V5 refuses it upstream).
+ */
+export const domainsForEngines = (engines) => {
+    const active = new Set(engines);
+    return Object.keys(DOMAIN_OWNER_ENGINE).filter((domain) => domain !== 'staging' && active.has(DOMAIN_OWNER_ENGINE[domain]));
+};

package/dist/core/download.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Trigger a browser file download from in-memory data — the canonical client-side
+ * "save this blob" primitive (there was no shared one; call sites hand-rolled
+ * `createObjectURL` + `<a download>` + revoke). DOM-only: it no-ops off the browser
+ * so importing modules stay server-safe.
+ *
+ * ```ts
+ * downloadBlob(csvText, 'notes.csv', 'text/csv');
+ * downloadBlob(sqliteBytes, 'snapshot.sqlite', 'application/x-sqlite3');
+ * ```
+ */
+export declare function downloadBlob(data: BlobPart, filename: string, mime: string): void;
+/** Decode a base64 payload (e.g. an exported `.sqlite` snapshot) to bytes for {@link downloadBlob}. */
+export declare function base64ToBytes(base64: string): Uint8Array;