cursedbelt 2.8.0 → 3.0.0

package/src/core/colorScheme/colorSchemeStore.ts

@@ -1,184 +0,0 @@
-/**
- * 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 const COLOR_SCHEME_STORAGE_KEY = 'cwip.colorScheme';
-
-const isMode = (v: unknown): v is Exclude<ColorSchemeMode, 'system'> =>
-  v === 'light' || v === 'dark';
-
-export function createColorSchemeStore(options: ColorSchemeStoreOptions = {}): ColorSchemeStore {
-  const {
-    storage = null,
-    apply,
-    getSystemScheme = () => 'light',
-    onSystemChange,
-    onExternalChange,
-    key = COLOR_SCHEME_STORAGE_KEY,
-  } = options;
-  const listeners = new Set<() => void>();
-  let mode: ColorSchemeMode | undefined; // undefined until first hydrate
-  let watchingSystem = false;
-  let watchingExternal = false;
-
-  const hydrate = (): ColorSchemeMode => {
-    if (mode !== undefined) return mode;
-    const raw = storage?.getItem(key);
-    mode = isMode(raw) ? raw : 'system';
-    return mode;
-  };
-
-  const resolve = (): ResolvedColorScheme => {
-    const m = hydrate();
-    return m === 'system' ? getSystemScheme() : m;
-  };
-
-  const notify = (): void => {
-    for (const l of listeners) l();
-  };
-
-  const commit = (next: ColorSchemeMode): void => {
-    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: ResolvedColorScheme): void {
-  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: ColorSchemeStorage | null =
-  typeof localStorage !== 'undefined' ? localStorage : null;
-
-const darkQuery = (): MediaQueryList | null =>
-  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 = (): ColorSchemeMode => colorSchemeStore.getMode();
-export const getResolvedColorScheme = (): ResolvedColorScheme => colorSchemeStore.getResolved();
-export const setColorSchemeMode = (mode: ColorSchemeMode): void => colorSchemeStore.setMode(mode);
-export const toggleColorScheme = (): void => colorSchemeStore.toggle();
-export const subscribeColorScheme = (listener: () => void): (() => void) =>
-  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 = (): void => colorSchemeStore.init();

package/src/core/colorScheme/index.ts

@@ -1,23 +0,0 @@
-/**
- * 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/src/core/domainOwners.ts

@@ -1,32 +0,0 @@
-/**
- * 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 const DOMAIN_OWNER_ENGINE: Readonly<Record<DomainName, string>> = 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: readonly string[]): DomainName[] => {
-  const active = new Set(engines);
-  return (Object.keys(DOMAIN_OWNER_ENGINE) as DomainName[]).filter(
-    (domain) => domain !== 'staging' && active.has(DOMAIN_OWNER_ENGINE[domain]),
-  );
-};

package/src/core/download.spec.ts

@@ -1,38 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { base64ToBytes, downloadBlob } from './download';
-
-describe('base64ToBytes', () => {
-  test('decodes base64 to the original bytes', () => {
-    const bytes = base64ToBytes(btoa('SQLite'));
-    expect(new TextDecoder().decode(bytes)).toBe('SQLite');
-  });
-});
-
-describe('downloadBlob', () => {
-  test('creates then removes a download anchor (happy-dom)', () => {
-    let created: HTMLAnchorElement | null = null;
-    const origCreate = URL.createObjectURL;
-    const origRevoke = URL.revokeObjectURL;
-    let revoked = '';
-    URL.createObjectURL = () => 'blob:mock';
-    URL.revokeObjectURL = (u: string) => {
-      revoked = u;
-    };
-    const origClick = HTMLAnchorElement.prototype.click;
-    HTMLAnchorElement.prototype.click = function click(this: HTMLAnchorElement) {
-      created = this;
-    };
-    try {
-      downloadBlob('id,body\n1,a', 'notes.csv', 'text/csv');
-      expect(created).not.toBeNull();
-      expect((created as unknown as HTMLAnchorElement).download).toBe('notes.csv');
-      // Anchor is removed synchronously; the object URL revokes on the next tick.
-      expect(document.querySelector('a[download]')).toBeNull();
-    } finally {
-      URL.createObjectURL = origCreate;
-      URL.revokeObjectURL = origRevoke;
-      HTMLAnchorElement.prototype.click = origClick;
-      void revoked;
-    }
-  });
-});

package/src/core/download.ts

@@ -1,35 +0,0 @@
-/**
- * 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 function downloadBlob(data: BlobPart, filename: string, mime: string): void {
-  if (typeof document === 'undefined' || typeof URL.createObjectURL !== 'function') return;
-  const url = URL.createObjectURL(new Blob([data], { type: mime }));
-  try {
-    const a = document.createElement('a');
-    a.href = url;
-    a.download = filename;
-    a.rel = 'noopener';
-    document.body.appendChild(a);
-    a.click();
-    a.remove();
-  } finally {
-    // Revoke on the next tick so the click's navigation has grabbed the URL first.
-    setTimeout(() => URL.revokeObjectURL(url), 0);
-  }
-}
-
-/** Decode a base64 payload (e.g. an exported `.sqlite` snapshot) to bytes for {@link downloadBlob}. */
-export function base64ToBytes(base64: string): Uint8Array {
-  const bin = atob(base64);
-  const bytes = new Uint8Array(bin.length);
-  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
-  return bytes;
-}

package/src/core/events/ccEventBus.spec.ts

@@ -1,90 +0,0 @@
-import { describe, expect, it } from 'bun:test';
-import { createCcEventBus, MAX_EVENT_DEPTH } from './ccEventBus';
-
-describe('CCEventBus', () => {
-  it('delivers to every subscriber of a type and to nobody else', async () => {
-    const bus = createCcEventBus();
-    const saved: string[] = [];
-    const locked: string[] = [];
-    bus.on('NOTE_SAVED', (event) => saved.push(event.type));
-    bus.on('NOTE_SAVED', (event) => saved.push(`${event.type}:second`));
-    bus.on('VAULT_LOCKED', (event) => locked.push(event.type));
-
-    bus.emit({ type: 'NOTE_SAVED' });
-    await bus.settled();
-
-    expect(saved).toEqual(['NOTE_SAVED', 'NOTE_SAVED:second']);
-    expect(locked).toEqual([]);
-  });
-
-  it('unsubscribes cleanly', async () => {
-    const bus = createCcEventBus();
-    const seen: number[] = [];
-    const off = bus.on('APP_DEPLOYED', () => seen.push(1));
-    bus.emit({ type: 'APP_DEPLOYED' });
-    await bus.settled();
-    off();
-    bus.emit({ type: 'APP_DEPLOYED' });
-    await bus.settled();
-    expect(seen).toEqual([1]);
-  });
-
-  it('keeps a throwing subscriber from stopping the rest of the chain', async () => {
-    const bus = createCcEventBus();
-    const seen: string[] = [];
-    bus.on('NOTE_SAVED', () => {
-      throw new Error('subscriber blew up');
-    });
-    bus.on('NOTE_SAVED', () => seen.push('second ran'));
-    bus.emit({ type: 'NOTE_SAVED' });
-    await bus.settled();
-    expect(seen).toEqual(['second ran']);
-  });
-
-  it('terminates a chain past the depth limit and names the whole chain', async () => {
-    const diagnostics: string[][] = [];
-    const bus = createCcEventBus({ onLoopDiagnostic: (d) => diagnostics.push(d.chain) });
-    const chain = ['A', 'B', 'C', 'D', 'E', 'F'];
-    let handled = 0;
-
-    chain.forEach((type, index) => {
-      const next = chain[(index + 1) % chain.length] as string;
-      bus.on(type, (event) => {
-        handled += 1;
-        bus.emit({ type: next, causationId: event.causationId, depth: event.depth + 1 });
-      });
-    });
-
-    bus.emit({ type: 'A' });
-    await bus.settled();
-
-    expect(diagnostics).toHaveLength(1);
-    expect(diagnostics[0]?.length).toBe(MAX_EVENT_DEPTH + 2); // the chain up to and including the terminated emission
-    expect(handled).toBeLessThanOrEqual(MAX_EVENT_DEPTH + 1);
-  });
-
-  it('lets an independent chain run to its own depth — the guard is per causation', async () => {
-    const bus = createCcEventBus();
-    bus.on('PING', (event) => {
-      if (event.depth < 3) bus.emit({ type: 'PING', causationId: event.causationId, depth: event.depth + 1 });
-    });
-    bus.emit({ type: 'PING', causationId: 'chain-1' });
-    bus.emit({ type: 'PING', causationId: 'chain-2' });
-    await bus.settled();
-    expect(bus.diagnostics()).toEqual([]);
-  });
-
-  it('schedules handlers instead of re-entering the dispatcher', async () => {
-    const bus = createCcEventBus();
-    const order: string[] = [];
-    bus.on('FIRST', () => {
-      order.push('first-start');
-      bus.emit({ type: 'SECOND' });
-      order.push('first-end');
-    });
-    bus.on('SECOND', () => order.push('second'));
-    bus.emit({ type: 'FIRST' });
-    await bus.settled();
-    expect(order).toEqual(['first-start', 'first-end', 'second']);
-  });
-});

package/src/core/events/ccEventBus.ts

@@ -1,120 +0,0 @@
-/**
- * The global event bus (03 §6.4) — lifecycle notifications only, never data
- * payloads (those ride the port hub).
- *
- * The depth guard is the reason this is a primitive rather than an EventEmitter:
- * handlers emit, and a handler chain that loops — `NOTE_SAVED` → indexer →
- * dashboard → audit interceptor → `NOTE_SAVED` — freezes the main thread with no
- * error and no stack that names the cycle. Each emission inherits
- * `depth = parent.depth + 1` via `causationId`; past `MAX_EVENT_DEPTH` the bus
- * terminates the chain and raises an `EventLoopDiagnostic` that names the whole
- * chain, so the loop is a report instead of a hang.
- *
- * Handlers are async-scheduled, never re-entrant: emitting from inside a handler
- * queues, so a synchronous handler cannot re-enter the dispatcher mid-iteration.
- */
-export interface CCEvent {
-  type: string;
-  tenantId: string;
-  causationId: string;
-  depth: number;
-  payload: Record<string, unknown>;
-}
-
-export interface EventLoopDiagnostic {
-  chain: string[];
-  terminatedAt: string;
-  causationId: string;
-}
-
-export type Unsubscribe = () => void;
-
-/** Past this depth a chain is a loop, not a workflow (03 §6.4). */
-export const MAX_EVENT_DEPTH = 5;
-
-export interface CCEventBusOptions {
-  onLoopDiagnostic?: (diagnostic: EventLoopDiagnostic) => void;
-  maxDepth?: number;
-}
-
-export interface CCEventBus {
-  emit(event: Partial<CCEvent> & { type: string }): void;
-  on(type: string, handler: (event: CCEvent) => void): Unsubscribe;
-  /** Resolves once the queue drains — the probe's "is the main thread still responsive?" hook. */
-  settled(): Promise<void>;
-  diagnostics(): readonly EventLoopDiagnostic[];
-}
-
-export function createCcEventBus(options: CCEventBusOptions = {}): CCEventBus {
-  const maxDepth = options.maxDepth ?? MAX_EVENT_DEPTH;
-  const handlers = new Map<string, ((event: CCEvent) => void)[]>();
-  const diagnostics: EventLoopDiagnostic[] = [];
-  const chains = new Map<string, string[]>();
-  const queue: CCEvent[] = [];
-  let draining = false;
-  let drained: Promise<void> = Promise.resolve();
-  let resolveDrained: (() => void) | null = null;
-
-  const drain = async (): Promise<void> => {
-    draining = true;
-    while (queue.length > 0) {
-      const event = queue.shift() as CCEvent;
-      for (const handler of handlers.get(event.type) ?? []) {
-        try {
-          handler(event);
-        } catch {
-          // A throwing subscriber must not stop the rest of the chain.
-        }
-      }
-      await Promise.resolve(); // yield: handlers are scheduled, never re-entrant
-    }
-    draining = false;
-    resolveDrained?.();
-    resolveDrained = null;
-  };
-
-  return {
-    emit(partial) {
-      const causationId = partial.causationId ?? `cause_${chains.size + 1}_${partial.type}`;
-      const depth = partial.depth ?? 0;
-      const chain = [...(chains.get(causationId) ?? []), partial.type];
-      chains.set(causationId, chain);
-
-      if (depth > maxDepth) {
-        const diagnostic: EventLoopDiagnostic = { chain, terminatedAt: partial.type, causationId };
-        diagnostics.push(diagnostic);
-        options.onLoopDiagnostic?.(diagnostic);
-        return; // chain terminated — the guard, not a crash
-      }
-
-      queue.push({
-        type: partial.type,
-        tenantId: partial.tenantId ?? 'tenant-a',
-        causationId,
-        depth,
-        payload: partial.payload ?? {},
-      });
-
-      if (!draining) {
-        drained = new Promise<void>((resolve) => {
-          resolveDrained = resolve;
-        });
-        void drain();
-      }
-    },
-
-    on(type, handler) {
-      const list = handlers.get(type) ?? [];
-      list.push(handler);
-      handlers.set(type, list);
-      return () => {
-        const current = handlers.get(type) ?? [];
-        const index = current.indexOf(handler);
-        if (index >= 0) current.splice(index, 1);
-      };
-    },
-
-    settled: () => (draining ? drained : Promise.resolve()),
-    diagnostics: () => diagnostics,
-  };
-}