@ccheever/exact-facet-core 0.1.0

package/src/provenance-trace.ts

@@ -0,0 +1,153 @@
+// @system @ref LLP 0158 — Design Mode D0: recipe origin tracing.
+//
+// Builds a sentinel twin of a FacetTheme: primitive leaves are replaced by
+// unique sentinel values and object leaves (shadow specs, transition
+// presets) are registered by identity, each remembering its token path.
+// Running a pure recipe against the twin — a second, dev-only call, never
+// the render path — lets the caller map each output property back to the
+// token it passed through unchanged. Values transformed on the way out
+// (color math, arithmetic, string templates) do not survive as sentinels
+// and honestly report as computed (LLP 0158 §4.1: tracing is exact or it
+// is nothing; no value-matching heuristics).
+
+import type { FacetTheme } from './internals.js';
+
+const STRING_SENTINEL_PREFIX = '__exact_tok__:';
+const STRING_SENTINEL_SUFFIX = '__';
+
+// 2^25 base plus exact binary fractions: survives identity passthrough,
+// vanishingly unlikely to collide with anything a recipe computes.
+const NUMBER_SENTINEL_BASE = 33554432;
+const NUMBER_SENTINEL_STEP = 0.0009765625; // 2^-10, exact in float64
+
+export interface ThemeTraceHandle {
+  /** Sentinel twin, shaped like the source theme. */
+  theme: FacetTheme;
+  /** Maps a traced output value back to a token path, or null. */
+  resolve(value: unknown): string | null;
+}
+
+export interface TracedOrigin {
+  kind: 'token' | 'computed';
+  tokenPath?: string;
+}
+
+export type TracedStyleOrigins = Record<string, TracedOrigin>;
+
+export function createTracingTheme(real: FacetTheme): ThemeTraceHandle {
+  const numberPaths = new Map<number, string>();
+  const objectPaths = new WeakMap<object, string>();
+  let numberIndex = 0;
+
+  const twin = (value: unknown, path: string[]): unknown => {
+    if (typeof value === 'string') {
+      return `${STRING_SENTINEL_PREFIX}${path.join('.')}${STRING_SENTINEL_SUFFIX}`;
+    }
+    if (typeof value === 'number') {
+      // `density.paddingScale` is a multiplier recipes FOLD INTO geometry
+      // (LLP 0269 §5 apply-time density), never a value they pass through;
+      // a sentinel here would poison every padding trace even when the
+      // scale is inert. Carrying the real value keeps tracing honest both
+      // ways: at scale 1 the geometry token's sentinel survives (token),
+      // at any real scale the arithmetic reports computed.
+      if (path.length === 2 && path[0] === 'density' && path[1] === 'paddingScale') {
+        return value;
+      }
+      numberIndex += 1;
+      const sentinel = NUMBER_SENTINEL_BASE + numberIndex * NUMBER_SENTINEL_STEP;
+      numberPaths.set(sentinel, path.join('.'));
+      return sentinel;
+    }
+    if (Array.isArray(value)) {
+      const copy = value.map((entry, index) => twin(entry, [...path, String(index)]));
+      objectPaths.set(copy, path.join('.'));
+      return copy;
+    }
+    if (value !== null && typeof value === 'object') {
+      const copy: Record<string, unknown> = {};
+      for (const [key, entry] of Object.entries(value)) {
+        copy[key] = twin(entry, [...path, key]);
+      }
+      objectPaths.set(copy, path.join('.'));
+      return copy;
+    }
+    // booleans / null / undefined are not traceable (two-valued or empty
+    // domains); pass the real value through.
+    return value;
+  };
+
+  const theme = twin(real, []) as FacetTheme;
+
+  const resolve = (value: unknown): string | null => {
+    if (typeof value === 'string') {
+      if (
+        value.startsWith(STRING_SENTINEL_PREFIX) &&
+        value.endsWith(STRING_SENTINEL_SUFFIX)
+      ) {
+        return value.slice(
+          STRING_SENTINEL_PREFIX.length,
+          value.length - STRING_SENTINEL_SUFFIX.length,
+        );
+      }
+      return null;
+    }
+    if (typeof value === 'number') {
+      return numberPaths.get(value) ?? null;
+    }
+    if (value !== null && typeof value === 'object') {
+      return objectPaths.get(value) ?? null;
+    }
+    return null;
+  };
+
+  return { theme, resolve };
+}
+
+function isThemeLikeArg(value: unknown): value is FacetTheme {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const candidate = value as Record<string, unknown>;
+  return 'color' in candidate && 'scheme' in candidate && 'space' in candidate;
+}
+
+/**
+ * Re-runs a pure style recipe with the theme argument replaced by a
+ * sentinel twin and maps each output property to its origin. Returns null
+ * when the call has no theme-shaped argument or the traced run throws —
+ * callers fall back to a plain computed origin, never a wrong one.
+ */
+export function traceStyleOrigins(
+  fn: unknown,
+  args: readonly unknown[],
+): TracedStyleOrigins | null {
+  if (typeof fn !== 'function') {
+    return null;
+  }
+  const themeIndex = args.findIndex(isThemeLikeArg);
+  if (themeIndex === -1) {
+    return null;
+  }
+
+  try {
+    const handle = createTracingTheme(args[themeIndex] as FacetTheme);
+    const tracedArgs = args.slice();
+    tracedArgs[themeIndex] = handle.theme;
+    const output = (fn as (...a: unknown[]) => unknown)(...tracedArgs);
+    if (output === null || typeof output !== 'object') {
+      return null;
+    }
+
+    const origins: TracedStyleOrigins = {};
+    for (const [prop, value] of Object.entries(output as Record<string, unknown>)) {
+      if (value === undefined) {
+        continue;
+      }
+      const tokenPath = handle.resolve(value);
+      origins[prop] = tokenPath ? { kind: 'token', tokenPath } : { kind: 'computed' };
+    }
+    return origins;
+  } catch {
+    return null;
+  }
+}

package/src/store-machinery.ts

@@ -0,0 +1,128 @@
+// @system @ref LLP 0157 — shared store machinery for theme-preference stores.
+//
+// This is the generic part of the repo's theme stores: a persisted string
+// preference plus host-fed inputs with subscribe/version semantics. The
+// facet-core theme store (`theme-store.ts`) and the lab/demo design system
+// (`js/src/_design/theme.ts`) both build on this machinery; per the
+// four-layer styling charter they share machinery, not tokens.
+//
+// Persistence is injected. Core never touches `localStorage` or platform
+// settings itself — the binding that owns persistence (e.g. `_design` on
+// web) supplies an adapter.
+
+export interface PreferencePersistenceAdapter {
+  load(): string | null;
+  save(value: string): void;
+}
+
+export interface PreferenceStore<T extends string> {
+  get(): T;
+  /** Sets the preference, persists it through the adapter, notifies. */
+  set(next: T): void;
+  subscribe(listener: () => void): () => void;
+  /** Monotonic change counter, usable with useSyncExternalStore-style bindings. */
+  version(): number;
+  /**
+   * Installs the persistence adapter. Loads the persisted value immediately
+   * (if any) and persists subsequent writes.
+   */
+  configurePersistence(adapter: PreferencePersistenceAdapter | null): void;
+}
+
+export function createPreferenceStore<T extends string>(options: {
+  defaultValue: T;
+  /** Validates/normalizes a raw persisted string; return null to reject it. */
+  normalize?: (raw: string) => T | null;
+}): PreferenceStore<T> {
+  const listeners = new Set<() => void>();
+  let value: T = options.defaultValue;
+  let storeVersion = 0;
+  let persistence: PreferencePersistenceAdapter | null = null;
+
+  function notify(): void {
+    storeVersion += 1;
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  return {
+    get(): T {
+      return value;
+    },
+    set(next: T): void {
+      if (next === value) {
+        return;
+      }
+      value = next;
+      try {
+        persistence?.save(next);
+      } catch {
+        // Persistence is best-effort; preference still applies in-memory.
+      }
+      notify();
+    },
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    version(): number {
+      return storeVersion;
+    },
+    configurePersistence(adapter: PreferencePersistenceAdapter | null): void {
+      persistence = adapter;
+      if (!adapter) {
+        return;
+      }
+      let raw: string | null = null;
+      try {
+        raw = adapter.load();
+      } catch {
+        raw = null;
+      }
+      if (raw == null) {
+        return;
+      }
+      const normalized = options.normalize ? options.normalize(raw) : (raw as T);
+      if (normalized != null && normalized !== value) {
+        value = normalized;
+        notify();
+      }
+    },
+  };
+}
+
+export interface HostInput<T> {
+  get(): T;
+  /** Host integrations feed this (system appearance listener, reduced-motion media query, ...). */
+  set(next: T): void;
+  subscribe(listener: () => void): () => void;
+}
+
+export function createHostInput<T>(initial: T): HostInput<T> {
+  const listeners = new Set<() => void>();
+  let value = initial;
+
+  return {
+    get(): T {
+      return value;
+    },
+    set(next: T): void {
+      if (next === value) {
+        return;
+      }
+      value = next;
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}