@czap/core 0.1.0

package/src/speculative.ts

@@ -0,0 +1,186 @@
+/**
+ * SpeculativeEvaluator -- threshold proximity prefetching.
+ *
+ * When a boundary signal is near a threshold, pre-compute the next state.
+ * Uses hysteresis dead zone as the prefetch window and linear extrapolation
+ * from velocity (last 3-4 signal values) to predict crossings.
+ *
+ * Wrong prediction cost: ~80ns to recompute (negligible).
+ *
+ * @module
+ */
+
+import { Boundary } from './boundary.js';
+import type { StateUnion } from './type-utils.js';
+
+// Speculative pre-computation: when signal velocity indicates an imminent threshold crossing, pre-evaluate the predicted next state.
+
+interface SpeculativeResult<B extends Boundary.Shape> {
+  readonly current: StateUnion<B>;
+  readonly prefetched?: StateUnion<B>;
+  readonly confidence: number;
+}
+
+interface SpeculativeEvaluatorShape<B extends Boundary.Shape> {
+  evaluate(value: number, velocity?: number): SpeculativeResult<B>;
+}
+
+/**
+ * Creates a speculative evaluator for a boundary that prefetches the next state
+ * when the signal value is near a threshold and moving toward it.
+ *
+ * @example
+ * ```ts
+ * const boundary = Boundary.make({
+ *   thresholds: [768, 1024],
+ *   states: ['mobile', 'tablet', 'desktop'] as const,
+ *   hysteresis: 20,
+ * });
+ * const spec = SpeculativeEvaluator.make(boundary);
+ * const result = spec.evaluate(760, 2.0); // approaching 768 threshold
+ * result.current;     // 'mobile'
+ * result.prefetched;  // 'tablet' (pre-computed)
+ * result.confidence;  // 0.0-1.0 likelihood of crossing
+ * ```
+ */
+function _make<B extends Boundary.Shape>(boundary: B): SpeculativeEvaluatorShape<B> {
+  const thresholds = boundary.thresholds as readonly number[];
+  const hysteresis = boundary.hysteresis ?? 0;
+  const prefetchWindow = Math.max(hysteresis, 1); // Use hysteresis as window, min 1
+
+  // Compute epsilon from boundary scale rather than hardcoded constant
+  const minGap =
+    thresholds.length >= 2
+      ? Math.min(
+          ...Array.from(
+            { length: thresholds.length - 1 },
+            (_, i) => (thresholds[i + 1] as number) - (thresholds[i] as number),
+          ),
+        )
+      : 1;
+  const epsilon = Math.min(minGap * 0.001, hysteresis > 0 ? hysteresis * 0.01 : 0.001);
+
+  // Velocity estimation ring buffer (last 2 values)
+  const history: { value: number; time: number }[] = [];
+  // 2-sample velocity estimation buffer — gives instant responsiveness
+  const HISTORY_SIZE = 2;
+
+  // Boundary.make guarantees states is non-empty (readonly [string, ...string[]]).
+  let previousState: StateUnion<B> = boundary.states[0];
+
+  // Simple finite difference (not least-squares) — 2-sample gives instant responsiveness
+  // for UI prefetch.
+  function estimateVelocity(currentValue: number, explicitVelocity?: number): number {
+    if (explicitVelocity !== undefined) return explicitVelocity;
+    if (history.length < 2) return 0;
+
+    // Linear regression over recent samples
+    const last = history[history.length - 1]!;
+    const prev = history[history.length - 2]!;
+    const dt = last.time - prev.time;
+    if (dt <= 0) return 0;
+    return (last.value - prev.value) / dt;
+  }
+
+  function findNearestThreshold(
+    value: number,
+  ): { threshold: number; distance: number; direction: 'up' | 'down' } | null {
+    let nearest: { threshold: number; distance: number; direction: 'up' | 'down' } | null = null;
+
+    for (const t of thresholds) {
+      const dist = Math.abs(value - (t as number));
+      if (nearest === null || dist < nearest.distance) {
+        nearest = {
+          threshold: t as number,
+          distance: dist,
+          direction: value < (t as number) ? 'up' : 'down',
+        };
+      }
+    }
+
+    return nearest;
+  }
+
+  return {
+    evaluate(value: number, velocity?: number): SpeculativeResult<B> {
+      const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+      history.push({ value, time: now });
+      if (history.length > HISTORY_SIZE) history.shift();
+
+      // Evaluate current state
+      const current = boundary.hysteresis
+        ? Boundary.evaluateWithHysteresis(boundary, value, previousState)
+        : Boundary.evaluate(boundary, value);
+      previousState = current;
+
+      // Find nearest threshold
+      const nearest = findNearestThreshold(value);
+      if (!nearest) {
+        return { current, confidence: 0 };
+      }
+
+      const vel = estimateVelocity(value, velocity);
+
+      // Check if moving toward the threshold
+      const movingToward = (nearest.direction === 'up' && vel > 0) || (nearest.direction === 'down' && vel < 0);
+
+      if (!movingToward || nearest.distance > prefetchWindow) {
+        return { current, confidence: 0 };
+      }
+
+      // Compute confidence: closer to threshold + faster velocity = higher confidence
+      const distanceFactor = 1 - nearest.distance / prefetchWindow;
+      // Distance weighted 70%, velocity 30% — distance is more reliable for prefetch confidence
+      const velocityFactor = Math.min(Math.abs(vel) * 10, 1); // Normalize velocity contribution
+      const confidence = distanceFactor * 0.7 + velocityFactor * 0.3;
+
+      // Below 30% confidence, skip prefetch — not worth the speculative cost
+      if (confidence < 0.3) {
+        return { current, confidence };
+      }
+
+      // Pre-compute the predicted next state (jump past hysteresis zone if present)
+      const hysteresisJump = boundary.hysteresis ?? 0;
+      const predictedValue =
+        nearest.direction === 'up'
+          ? nearest.threshold + hysteresisJump + epsilon
+          : nearest.threshold - hysteresisJump - epsilon;
+
+      const prefetched = boundary.hysteresis
+        ? Boundary.evaluateWithHysteresis(boundary, predictedValue, current)
+        : Boundary.evaluate(boundary, predictedValue);
+
+      // Only return prefetch if it's actually different
+      if (prefetched === current) {
+        return { current, confidence: 0 };
+      }
+
+      return { current, prefetched, confidence };
+    },
+  };
+}
+
+/**
+ * SpeculativeEvaluator -- threshold proximity prefetching for boundaries.
+ * Pre-computes the next discrete state when a signal is near a threshold,
+ * using velocity estimation and hysteresis-based prefetch windows.
+ *
+ * @example
+ * ```ts
+ * const boundary = Boundary.make({
+ *   thresholds: [600],
+ *   states: ['small', 'large'] as const,
+ * });
+ * const spec = SpeculativeEvaluator.make(boundary);
+ * const { current, prefetched, confidence } = spec.evaluate(595, 1.5);
+ * // current='small', prefetched='large', confidence ~0.85
+ * ```
+ */
+export const SpeculativeEvaluator = { make: _make };
+
+export declare namespace SpeculativeEvaluator {
+  /** Structural shape of an evaluator bound to a specific {@link Boundary}. */
+  export type Shape<B extends Boundary.Shape> = SpeculativeEvaluatorShape<B>;
+  /** Prediction result from `evaluate()` — current state, optional prefetched next state, and confidence. */
+  export type Result<B extends Boundary.Shape> = SpeculativeResult<B>;
+}

package/src/store.ts

@@ -0,0 +1,77 @@
+/**
+ * `Store<S, Msg>` — TEA-style reducer store.
+ *
+ * @module
+ */
+
+import type { Stream } from 'effect';
+import { Effect, SubscriptionRef, Semaphore } from 'effect';
+
+interface StoreShape<S, Msg> {
+  readonly _tag: 'Store';
+  readonly get: Effect.Effect<S>;
+  readonly changes: Stream.Stream<S>;
+  dispatch(msg: Msg): Effect.Effect<void>;
+}
+
+interface EffectfulStoreShape<S, Msg, E = never, R = never> {
+  readonly _tag: 'Store';
+  readonly get: Effect.Effect<S>;
+  readonly changes: Stream.Stream<S>;
+  dispatch(msg: Msg): Effect.Effect<void, E, R>;
+}
+
+const _make = <S, Msg>(initial: S, reducer: (state: S, msg: Msg) => S): Effect.Effect<StoreShape<S, Msg>> =>
+  Effect.gen(function* () {
+    const ref = yield* SubscriptionRef.make(initial);
+
+    return {
+      _tag: 'Store' as const,
+      get: SubscriptionRef.get(ref),
+      changes: SubscriptionRef.changes(ref),
+      dispatch: (msg: Msg) => SubscriptionRef.update(ref, (state) => reducer(state, msg)),
+    };
+  });
+
+const _makeWithEffect = <S, Msg, E, R>(
+  initial: S,
+  reducer: (state: S, msg: Msg) => Effect.Effect<S, E, R>,
+): Effect.Effect<EffectfulStoreShape<S, Msg, E, R>> =>
+  Effect.gen(function* () {
+    const ref = yield* SubscriptionRef.make(initial);
+    const mutex = yield* Semaphore.make(1);
+
+    return {
+      _tag: 'Store' as const,
+      get: SubscriptionRef.get(ref),
+      changes: SubscriptionRef.changes(ref),
+      dispatch: (msg: Msg) =>
+        mutex.withPermits(1)(
+          Effect.gen(function* () {
+            const current = yield* SubscriptionRef.get(ref);
+            const next = yield* reducer(current, msg);
+            yield* SubscriptionRef.set(ref, next);
+          }),
+        ),
+    };
+  });
+
+/**
+ * Store — TEA-style state container.
+ * Build with an initial state and a pure `reducer(state, msg) => state`, then
+ * dispatch messages; the store publishes the resulting state via `changes`.
+ * Use `makeWithEffect` when the reducer is itself an `Effect`.
+ */
+export const Store = {
+  /** Synchronous reducer store. */
+  make: _make,
+  /** Reducer store where state transitions are themselves `Effect`s. */
+  makeWithEffect: _makeWithEffect,
+};
+
+export declare namespace Store {
+  /** Structural shape of a synchronous store. */
+  export type Shape<S, Msg> = StoreShape<S, Msg>;
+  /** Structural shape of an effectful store; adds error channel `E` and requirements `R`. */
+  export type Effectful<S, Msg, E = never, R = never> = EffectfulStoreShape<S, Msg, E, R>;
+}

package/src/style.ts

@@ -0,0 +1,249 @@
+/**
+ * StyleDef -- adaptive style primitive for constraint-based rendering.
+ *
+ * A style binds a base style layer to optional boundary states with
+ * per-state overrides and transitions. Content-addressed via FNV-1a.
+ *
+ * @module
+ */
+
+import type { ContentAddress, Millis } from './brands.js';
+import type { Boundary } from './boundary.js';
+import type { StateUnion } from './type-utils.js';
+import { CanonicalCbor } from './cbor.js';
+import { fnv1aBytes } from './fnv.js';
+import { CzapValidationError } from './validation-error.js';
+
+/** Single `box-shadow` layer — compiled into a space-separated CSS value by {@link Style.tap}. */
+export interface ShadowLayer {
+  readonly x: number;
+  readonly y: number;
+  readonly blur: number;
+  readonly spread?: number;
+  readonly color: string;
+  readonly inset?: boolean;
+}
+
+/**
+ * One layer of a {@link Style}: a flat property bag plus optional pseudo
+ * selectors (`:hover`, `::before`, …) and structured `box-shadow` layers.
+ */
+export interface StyleLayer {
+  readonly properties: Record<string, string>;
+  readonly pseudo?: Record<string, Record<string, string>>;
+  readonly boxShadow?: readonly ShadowLayer[];
+}
+
+interface StyleDef<B extends Boundary.Shape = Boundary.Shape> {
+  readonly _tag: 'StyleDef';
+  readonly _version: 1;
+  readonly id: ContentAddress;
+  readonly boundary?: B;
+  readonly base: StyleLayer;
+  readonly states?: { readonly [S in StateUnion<B> & string]?: StyleLayer };
+  readonly transition?: {
+    readonly duration: Millis;
+    readonly easing?: string;
+    readonly properties?: readonly string[];
+  };
+}
+
+interface StyleFactory {
+  make<B extends Boundary.Shape>(config: {
+    readonly boundary?: B;
+    readonly base: StyleLayer;
+    readonly states?: { readonly [S in StateUnion<B> & string]?: StyleLayer };
+    readonly transition?: StyleDef['transition'];
+  }): StyleDef<B>;
+}
+
+function deterministicId<B extends Boundary.Shape>(
+  boundary: B | undefined,
+  base: StyleLayer,
+  states: StyleDef<B>['states'],
+  transition: StyleDef['transition'] | undefined,
+): ContentAddress {
+  return fnv1aBytes(
+    CanonicalCbor.encode({
+      _tag: 'StyleDef',
+      _version: 1,
+      boundaryId: boundary?.id ?? null,
+      base,
+      states: states ?? {},
+      transition: transition ?? null,
+    }),
+  );
+}
+
+/**
+ * Deep merge two style layers: properties spread, pseudo merge per selector, boxShadow concat.
+ *
+ * Override properties win over base. Pseudo-element selectors are merged per
+ * key. Box shadows are concatenated (base first, then override).
+ *
+ * @example
+ * ```ts
+ * const base = { properties: { color: 'red', padding: '4px' } };
+ * const override = { properties: { color: 'blue', margin: '8px' } };
+ * const merged = Style.mergeLayers(base, override);
+ * // merged.properties === { color: 'blue', padding: '4px', margin: '8px' }
+ * ```
+ */
+function _mergeLayers(base: StyleLayer, override: StyleLayer): StyleLayer {
+  const properties = { ...base.properties, ...override.properties };
+
+  let pseudo: Record<string, Record<string, string>> | undefined;
+  if (base.pseudo || override.pseudo) {
+    const allSelectors = new Set([...Object.keys(base.pseudo ?? {}), ...Object.keys(override.pseudo ?? {})]);
+    pseudo = {};
+    for (const sel of allSelectors) {
+      pseudo[sel] = { ...base.pseudo?.[sel], ...override.pseudo?.[sel] };
+    }
+  }
+
+  let boxShadow: readonly ShadowLayer[] | undefined;
+  if (base.boxShadow || override.boxShadow) {
+    boxShadow = [...(base.boxShadow ?? []), ...(override.boxShadow ?? [])];
+  }
+
+  return {
+    properties,
+    ...(pseudo !== undefined ? { pseudo } : {}),
+    ...(boxShadow !== undefined ? { boxShadow } : {}),
+  };
+}
+
+/**
+ * Resolve a style to a flat `Record<string, string>` for the given state.
+ *
+ * Merges base layer with the state-specific override (if any), flattens
+ * pseudo selectors and box-shadow into the result map.
+ *
+ * @example
+ * ```ts
+ * const style = Style.make({
+ *   base: { properties: { color: 'black' } },
+ *   states: { dark: { properties: { color: 'white' } } },
+ * });
+ * const props = Style.tap(style, 'dark');
+ * // props === { color: 'white' }
+ * const baseProps = Style.tap(style);
+ * // baseProps === { color: 'black' }
+ * ```
+ */
+function _tap(style: StyleDef, state?: string): Record<string, string> {
+  let layer = style.base;
+
+  if (state && style.states) {
+    const stateLayer = style.states[state];
+    if (stateLayer) {
+      layer = _mergeLayers(layer, stateLayer);
+    }
+  }
+
+  const result: Record<string, string> = { ...layer.properties };
+
+  if (layer.pseudo) {
+    for (const [sel, props] of Object.entries(layer.pseudo)) {
+      for (const [prop, val] of Object.entries(props)) {
+        result[`${sel}::${prop}`] = val;
+      }
+    }
+  }
+
+  if (layer.boxShadow && layer.boxShadow.length > 0) {
+    result['box-shadow'] = layer.boxShadow
+      .map((s) => {
+        const parts: string[] = [];
+        if (s.inset) parts.push('inset');
+        parts.push(`${s.x}px`, `${s.y}px`, `${s.blur}px`);
+        if (s.spread !== undefined) parts.push(`${s.spread}px`);
+        parts.push(s.color);
+        return parts.join(' ');
+      })
+      .join(', ');
+  }
+
+  return result;
+}
+
+/**
+ * Style namespace -- adaptive style primitive for constraint-based rendering.
+ *
+ * Bind base styles to optional boundary states with per-state overrides and
+ * CSS transitions. Resolve to flat property maps for any given state.
+ *
+ * @example
+ * ```ts
+ * import { Boundary, Style } from '@czap/core';
+ *
+ * const bp = Boundary.make({ input: 'viewport.width', at: [[0, 'sm'], [768, 'lg']] });
+ * const style = Style.make({
+ *   boundary: bp,
+ *   base: { properties: { 'font-size': '14px' } },
+ *   states: { lg: { properties: { 'font-size': '18px' } } },
+ *   transition: { duration: Millis(200) },
+ * });
+ * const resolved = Style.tap(style, 'lg');
+ * // resolved === { 'font-size': '18px' }
+ * ```
+ */
+export const Style: StyleFactory & {
+  tap: typeof _tap;
+  mergeLayers: typeof _mergeLayers;
+} = {
+  /**
+   * Create a new StyleDef from a configuration object.
+   *
+   * Validates that state keys match the boundary's states (if a boundary is
+   * provided). The resulting object is frozen and content-addressed.
+   *
+   * @example
+   * ```ts
+   * const style = Style.make({
+   *   base: { properties: { display: 'flex', gap: '8px' } },
+   * });
+   * // style._tag === 'StyleDef'
+   * // style.id === 'fnv1a:...'
+   * ```
+   */
+  make<B extends Boundary.Shape>(config: {
+    readonly boundary?: B;
+    readonly base: StyleLayer;
+    readonly states?: { readonly [S in StateUnion<B> & string]?: StyleLayer };
+    readonly transition?: StyleDef['transition'];
+  }): StyleDef<B> {
+    if (config.boundary && config.states) {
+      const boundaryStates = config.boundary.states as readonly string[];
+      const stateKeys = Object.keys(config.states);
+      for (const key of stateKeys) {
+        if (!boundaryStates.includes(key)) {
+          throw new CzapValidationError(
+            'Style.make',
+            `state "${key}" does not match boundary states [${boundaryStates.join(', ')}]`,
+          );
+        }
+      }
+    }
+
+    const id = deterministicId<B>(config.boundary, config.base, config.states, config.transition);
+
+    const def: StyleDef<B> = {
+      _tag: 'StyleDef',
+      _version: 1,
+      id,
+      ...(config.boundary !== undefined ? { boundary: config.boundary } : {}),
+      base: config.base,
+      ...(config.states !== undefined ? { states: config.states } : {}),
+      ...(config.transition !== undefined ? { transition: config.transition } : {}),
+    };
+    return Object.freeze(def);
+  },
+  tap: _tap,
+  mergeLayers: _mergeLayers,
+};
+
+export declare namespace Style {
+  /** Structural shape of a style definition parameterized by its governing {@link Boundary}. */
+  export type Shape<B extends Boundary.Shape = Boundary.Shape> = StyleDef<B>;
+}

package/src/testing.ts

@@ -0,0 +1,14 @@
+/**
+ * Test-only entrypoint for `@czap/core`. Imported as `@czap/core/testing`.
+ *
+ * These helpers mutate global registry state and would be footguns in
+ * production code paths (an edge worker warm-start that calls
+ * `resetCapsuleCatalog` would silently wipe every registered capsule,
+ * causing dispatch to fail intermittently). They are intentionally
+ * partitioned off the main package entry so a consumer cannot reach
+ * them by importing `@czap/core` directly.
+ *
+ * @module
+ */
+
+export { resetCapsuleCatalog } from './assembly.js';

package/src/theme.ts

@@ -0,0 +1,153 @@
+/**
+ * ThemeDef -- theme primitive for constraint-based adaptive rendering.
+ *
+ * A theme maps a set of token names to variant-keyed values, enabling
+ * coherent multi-variant token resolution. Content-addressed via FNV-1a.
+ *
+ * @module
+ */
+
+import type { ContentAddress } from './brands.js';
+import { CanonicalCbor } from './cbor.js';
+import { fnv1aBytes } from './fnv.js';
+import { CzapValidationError } from './validation-error.js';
+
+interface ThemeDef<V extends readonly string[] = readonly string[]> {
+  readonly _tag: 'ThemeDef';
+  readonly _version: 1;
+  readonly id: ContentAddress;
+  readonly name: string;
+  readonly variants: V;
+  readonly tokens: Record<string, Record<V[number] & string, unknown>>;
+  readonly meta?: Record<V[number] & string, { readonly label: string; readonly mode: 'light' | 'dark' }>;
+}
+
+interface ThemeFactory {
+  make<const V extends readonly [string, ...string[]]>(config: {
+    readonly name: string;
+    readonly variants: V;
+    readonly tokens: Record<string, Record<V[number] & string, unknown>>;
+    readonly meta?: ThemeDef<V>['meta'];
+  }): ThemeDef<V>;
+}
+
+function deterministicId<V extends readonly string[]>(
+  name: string,
+  variants: V,
+  tokens: ThemeDef<V>['tokens'],
+  meta: ThemeDef<V>['meta'] | undefined,
+): ContentAddress {
+  return fnv1aBytes(
+    CanonicalCbor.encode({
+      _tag: 'ThemeDef',
+      _version: 1,
+      name,
+      variants,
+      tokens,
+      meta: meta ?? null,
+    }),
+  );
+}
+
+/**
+ * Resolve all tokens for a given variant, returning a map of token name to value.
+ *
+ * Iterates the theme's token map and extracts each token's value for the
+ * specified variant.
+ *
+ * @example
+ * ```ts
+ * const theme = Theme.make({
+ *   name: 'brand',
+ *   variants: ['light', 'dark'] as const,
+ *   tokens: { bg: { light: '#fff', dark: '#111' }, fg: { light: '#000', dark: '#eee' } },
+ * });
+ * const darkTokens = Theme.tap(theme, 'dark');
+ * // darkTokens === { bg: '#111', fg: '#eee' }
+ * ```
+ */
+function _tap<V extends readonly string[]>(theme: ThemeDef<V>, variant: V[number] & string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [tokenName, variantMap] of Object.entries(theme.tokens)) {
+    result[tokenName] = variantMap[variant];
+  }
+  return result;
+}
+
+/**
+ * Theme namespace -- theme primitive for constraint-based adaptive rendering.
+ *
+ * Map token names to variant-keyed values, enabling coherent multi-variant
+ * token resolution (e.g. light/dark themes). Content-addressed via FNV-1a.
+ *
+ * @example
+ * ```ts
+ * import { Theme } from '@czap/core';
+ *
+ * const theme = Theme.make({
+ *   name: 'brand',
+ *   variants: ['light', 'dark'] as const,
+ *   tokens: {
+ *     bg: { light: '#fff', dark: '#111' },
+ *     fg: { light: '#000', dark: '#eee' },
+ *   },
+ * });
+ * const lightTokens = Theme.tap(theme, 'light');
+ * // lightTokens === { bg: '#fff', fg: '#000' }
+ * ```
+ */
+export const Theme: ThemeFactory & {
+  tap: typeof _tap;
+} = {
+  /**
+   * Create a new ThemeDef from a configuration object.
+   *
+   * Validates that every token has a value for each declared variant.
+   * The resulting object is frozen and content-addressed.
+   *
+   * @example
+   * ```ts
+   * const theme = Theme.make({
+   *   name: 'ocean',
+   *   variants: ['light', 'dark'] as const,
+   *   tokens: { primary: { light: '#0066cc', dark: '#3399ff' } },
+   *   meta: { light: { label: 'Light', mode: 'light' }, dark: { label: 'Dark', mode: 'dark' } },
+   * });
+   * // theme._tag === 'ThemeDef'
+   * // theme.id === 'fnv1a:...'
+   * ```
+   */
+  make<const V extends readonly [string, ...string[]]>(config: {
+    readonly name: string;
+    readonly variants: V;
+    readonly tokens: Record<string, Record<V[number] & string, unknown>>;
+    readonly meta?: ThemeDef<V>['meta'];
+  }): ThemeDef<V> {
+    const variantSet = new Set(config.variants as readonly string[]);
+    for (const [tokenName, variantMap] of Object.entries(config.tokens)) {
+      for (const variant of variantSet) {
+        if (!(variant in variantMap)) {
+          throw new CzapValidationError('Theme.make', `Token "${tokenName}" is missing value for variant "${variant}"`);
+        }
+      }
+    }
+
+    const id = deterministicId<V>(config.name, config.variants, config.tokens, config.meta);
+
+    return Object.freeze({
+      _tag: 'ThemeDef' as const,
+      _version: 1 as const,
+      id,
+      name: config.name,
+      variants: config.variants,
+      tokens: config.tokens,
+      ...(config.meta !== undefined ? { meta: config.meta } : {}),
+    });
+  },
+  tap: _tap,
+};
+
+export declare namespace Theme {
+  /** Structural shape of a {@link Theme} definition, parameterized by its variant tuple `V`. */
+  export type Shape<V extends readonly string[] = readonly string[]> = ThemeDef<V>;
+}