@czap/core 0.1.0

package/src/timeline.ts

@@ -0,0 +1,146 @@
+/**
+ * Timeline -- quantizer over time with play/pause/seek/scrub/reverse.
+ *
+ * A Timeline wraps a BoundaryDef and drives it from a time-based signal,
+ * producing discrete state transitions as the elapsed time crosses thresholds.
+ *
+ * @module
+ */
+
+import type { Stream, Scope } from 'effect';
+import { Effect, SubscriptionRef, Ref } from 'effect';
+import type { Millis } from './brands.js';
+import { Millis as mkMillis } from './brands.js';
+import { Boundary } from './boundary.js';
+import type { StateUnion } from './type-utils.js';
+import type { Scheduler } from './scheduler.js';
+import { Scheduler as SchedulerImpl } from './scheduler.js';
+
+interface TimelineShape<B extends Boundary.Shape = Boundary.Shape> {
+  readonly boundary: B;
+  readonly state: Effect.Effect<StateUnion<B>>;
+  readonly progress: Effect.Effect<number>;
+  readonly elapsed: Effect.Effect<Millis>;
+  readonly changes: Stream.Stream<StateUnion<B>>;
+  play(): Effect.Effect<void>;
+  pause(): Effect.Effect<void>;
+  reverse(): Effect.Effect<void>;
+  seek(ms: Millis): Effect.Effect<void>;
+  scrub(progress: number): Effect.Effect<void>;
+}
+
+interface TimelineFactory {
+  from<B extends Boundary.Shape>(
+    boundary: B,
+    config?: { duration?: Millis; loop?: boolean; scheduler?: Scheduler.Shape },
+  ): Effect.Effect<TimelineShape<B>, never, Scope.Scope>;
+}
+
+/**
+ * Timeline — scheduler-driven advancement over a {@link Boundary}.
+ * Produces a scoped reactive timeline that seeks or plays between boundary
+ * states; pluggable clock via {@link Scheduler}.
+ */
+export const Timeline: TimelineFactory = {
+  from<B extends Boundary.Shape>(
+    boundary: B,
+    config?: { duration?: Millis; loop?: boolean; scheduler?: Scheduler.Shape },
+  ): Effect.Effect<TimelineShape<B>, never, Scope.Scope> {
+    const duration =
+      config?.duration ??
+      (boundary.thresholds.length > 0 ? boundary.thresholds[boundary.thresholds.length - 1]! * 1.2 : 1000);
+    const loop = config?.loop ?? false;
+
+    return Effect.gen(function* () {
+      const elapsedRef = yield* SubscriptionRef.make(0);
+      const playingRef = yield* Ref.make(false);
+      const directionRef = yield* Ref.make<1 | -1>(1);
+      const initialState: StateUnion<B> = Boundary.evaluate(boundary, 0);
+      const stateRef = yield* SubscriptionRef.make<StateUnion<B>>(initialState);
+
+      const sched =
+        config?.scheduler ??
+        (typeof requestAnimationFrame !== 'undefined' ? SchedulerImpl.raf() : SchedulerImpl.noop());
+
+      let lastTime: number | null = null;
+      let playing = false;
+      let direction: 1 | -1 = 1;
+      let currentElapsed = 0;
+
+      const step = (now: number): void => {
+        if (lastTime !== null && playing) {
+          const dt = (now - lastTime) * direction;
+          let next = currentElapsed + dt;
+          if (loop) {
+            next = ((next % duration) + duration) % duration;
+          } else {
+            next = Math.max(0, Math.min(duration, next));
+          }
+          currentElapsed = next;
+          Effect.runSync(SubscriptionRef.set(elapsedRef, next));
+          const newState: StateUnion<B> = Boundary.evaluate(boundary, next);
+          const oldState = Effect.runSync(SubscriptionRef.get(stateRef));
+          if (newState !== oldState) {
+            Effect.runSync(SubscriptionRef.set(stateRef, newState));
+          }
+        }
+        lastTime = now;
+        schedId = sched.schedule(step);
+      };
+      let schedId = sched.schedule(step);
+      yield* Effect.addFinalizer(() => Effect.sync(() => sched.cancel(schedId)));
+
+      const timeline: TimelineShape<B> = {
+        boundary,
+        state: SubscriptionRef.get(stateRef),
+        progress: Effect.map(SubscriptionRef.get(elapsedRef), (e) => Math.max(0, Math.min(e / duration, 1))),
+        elapsed: Effect.map(SubscriptionRef.get(elapsedRef), (e) => mkMillis(e)),
+        changes: SubscriptionRef.changes(stateRef),
+        play: () =>
+          Effect.gen(function* () {
+            playing = true;
+            yield* Ref.set(playingRef, true);
+          }),
+        pause: () =>
+          Effect.gen(function* () {
+            playing = false;
+            yield* Ref.set(playingRef, false);
+          }),
+        reverse: () =>
+          Effect.gen(function* () {
+            direction = direction === 1 ? -1 : 1;
+            yield* Ref.update(directionRef, (d) => (d === 1 ? -1 : 1));
+          }),
+        seek: (ms: number) =>
+          Effect.gen(function* () {
+            const clamped = Math.max(0, Math.min(duration, ms));
+            currentElapsed = clamped;
+            yield* SubscriptionRef.set(elapsedRef, clamped);
+            const newState: StateUnion<B> = Boundary.evaluate(boundary, clamped);
+            const oldState = yield* SubscriptionRef.get(stateRef);
+            if (newState !== oldState) {
+              yield* SubscriptionRef.set(stateRef, newState);
+            }
+          }),
+        scrub: (progress: number) =>
+          Effect.gen(function* () {
+            const val = Math.max(0, Math.min(1, progress)) * duration;
+            currentElapsed = val;
+            yield* SubscriptionRef.set(elapsedRef, val);
+            const newState: StateUnion<B> = Boundary.evaluate(boundary, val);
+            const oldState = yield* SubscriptionRef.get(stateRef);
+            if (newState !== oldState) {
+              yield* SubscriptionRef.set(stateRef, newState);
+            }
+          }),
+      };
+
+      return timeline;
+    });
+  },
+};
+
+export declare namespace Timeline {
+  /** Structural shape of a timeline instance for a given {@link Boundary}. */
+  export type Shape<B extends Boundary.Shape = Boundary.Shape> = TimelineShape<B>;
+}

package/src/token-buffer.ts

@@ -0,0 +1,151 @@
+/**
+ * TokenBuffer -- ring buffer that absorbs bursty LLM token arrival
+ * and emits at smooth cadence.
+ *
+ * Backed by pre-allocated array (zero-alloc push/drain).
+ * EMA (exponential moving average) for rate estimation.
+ * Stall detection: buffer empty + `gen < consume`.
+ *
+ * @module
+ */
+
+interface TokenBufferShape<T = string> {
+  push(token: T): void;
+  drain(maxCount?: number): T[];
+  reset(): void;
+  readonly occupancy: number;
+  readonly generationRate: number;
+  readonly consumptionRate: number;
+  readonly isStalled: boolean;
+  readonly length: number;
+  readonly capacity: number;
+}
+
+interface TokenBufferConfig {
+  readonly capacity?: number;
+  readonly emaAlpha?: number;
+}
+
+function _make<T = string>(config?: TokenBufferConfig): TokenBufferShape<T> {
+  const capacity = config?.capacity ?? 256;
+  const alpha = config?.emaAlpha ?? 0.1;
+
+  // Ring buffer backing store
+  const buffer: (T | undefined)[] = new Array(capacity);
+  let head = 0; // next write position
+  let tail = 0; // next read position
+  let count = 0;
+
+  // Rate estimation
+  let genRate = 0; // tokens/sec EMA
+  let consumeRate = 0;
+  let lastPushTime = 0;
+  let lastDrainTime = 0;
+
+  function now(): number {
+    return typeof performance !== 'undefined' ? performance.now() : Date.now();
+  }
+
+  return {
+    push(token: T): void {
+      const t = now();
+      if (lastPushTime > 0) {
+        const dt = (t - lastPushTime) / 1000;
+        if (dt > 0) {
+          const instantRate = 1 / dt;
+          genRate = genRate === 0 ? instantRate : genRate * (1 - alpha) + instantRate * alpha;
+        }
+      }
+      lastPushTime = t;
+
+      if (count < capacity) {
+        buffer[head] = token;
+        head = (head + 1) % capacity;
+        count++;
+      } else {
+        // Overflow: overwrite oldest (drop tail)
+        buffer[head] = token;
+        head = (head + 1) % capacity;
+        tail = (tail + 1) % capacity;
+      }
+    },
+
+    drain(maxCount?: number): T[] {
+      const max = maxCount ?? count;
+      const drainSize = Math.min(max, count);
+      if (drainSize === 0) return [];
+
+      const t = now();
+      if (lastDrainTime > 0) {
+        const dt = (t - lastDrainTime) / 1000;
+        if (dt > 0) {
+          const instantRate = drainSize / dt;
+          consumeRate = consumeRate === 0 ? instantRate : consumeRate * (1 - alpha) + instantRate * alpha;
+        }
+      }
+      lastDrainTime = t;
+
+      const result: T[] = [];
+      for (let i = 0; i < drainSize; i++) {
+        result.push(buffer[tail]!);
+        buffer[tail] = undefined;
+        tail = (tail + 1) % capacity;
+        count--;
+      }
+
+      return result;
+    },
+
+    reset(): void {
+      head = 0;
+      tail = 0;
+      count = 0;
+      genRate = 0;
+      consumeRate = 0;
+      lastPushTime = 0;
+      lastDrainTime = 0;
+      buffer.fill(undefined);
+    },
+
+    get occupancy(): number {
+      return count / capacity;
+    },
+
+    get generationRate(): number {
+      return genRate;
+    },
+
+    get consumptionRate(): number {
+      return consumeRate;
+    },
+
+    get isStalled(): boolean {
+      return count === 0 && genRate > 0 && genRate < consumeRate;
+    },
+
+    get length(): number {
+      return count;
+    },
+
+    get capacity(): number {
+      return capacity;
+    },
+  };
+}
+
+/**
+ * TokenBuffer — zero-alloc ring buffer that absorbs bursty LLM token arrival
+ * and hands tokens out at a smooth cadence. Reports stall via `isStalled`
+ * and rate via an internal EMA.
+ */
+export const TokenBuffer = {
+  /** Build a new buffer — pass capacity or reuse defaults. */
+  make: _make,
+};
+
+export declare namespace TokenBuffer {
+  /** Structural shape of a token buffer: `push`, `drain`, `reset`, stall/rate accessors. */
+  export type Shape<T = string> = TokenBufferShape<T>;
+  /** Configuration accepted by {@link TokenBuffer.make}. */
+  export type Config = TokenBufferConfig;
+}

package/src/token.ts

@@ -0,0 +1,197 @@
+/**
+ * TokenDef -- design token primitive for constraint-based adaptive rendering.
+ *
+ * A token defines a named design value that varies across axes (e.g. theme,
+ * density, contrast). 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';
+
+/** Design-system category of a {@link Token} — governs compilation strategy and CSS property prefix. */
+export type TokenCategory = 'color' | 'spacing' | 'typography' | 'shadow' | 'radius' | 'animation' | 'effect';
+
+interface TokenDef<N extends string = string, Axes extends readonly string[] = readonly string[]> {
+  readonly _tag: 'TokenDef';
+  readonly _version: 1;
+  readonly id: ContentAddress;
+  readonly name: N;
+  readonly category: TokenCategory;
+  readonly axes: Axes;
+  readonly values: Record<string, unknown>;
+  readonly fallback: unknown;
+  readonly cssProperty: `--${string}`;
+}
+
+interface TokenFactory {
+  make<N extends string, const A extends readonly [string, ...string[]]>(config: {
+    readonly name: N;
+    readonly category: TokenCategory;
+    readonly axes: A;
+    readonly values: Record<string, unknown>;
+    readonly fallback: unknown;
+  }): TokenDef<N, A>;
+}
+
+function deterministicId(
+  name: string,
+  category: string,
+  axes: readonly string[],
+  values: Record<string, unknown>,
+  fallback: unknown,
+): ContentAddress {
+  return fnv1aBytes(
+    CanonicalCbor.encode({
+      _tag: 'TokenDef',
+      _version: 1,
+      name,
+      category,
+      axes,
+      values,
+      fallback,
+    }),
+  );
+}
+
+/**
+ * Resolve a token's value for the given axis values. Builds a sorted lookup key.
+ *
+ * Axes are sorted alphabetically and joined with ':' to form the lookup key.
+ * Falls back to the token's fallback value if no match is found.
+ *
+ * The optional type parameter `T` lets callers narrow the return value when
+ * they know the value shape; without it, the return is `unknown` (the
+ * underlying `TokenDef.values` is `Record<string, unknown>` because token
+ * values can be any JSON shape — colors as strings, spacing as numbers,
+ * shadow records as objects). Pass `Token.tap<string>(...)` for a color
+ * token, etc.
+ *
+ * @example
+ * ```ts
+ * const token = Token.make({
+ *   name: 'primary', category: 'color',
+ *   axes: ['theme'] as const,
+ *   values: { 'light': '#000', 'dark': '#fff' },
+ *   fallback: '#888',
+ * });
+ * const value = Token.tap<string>(token, { theme: 'dark' });
+ * // value === '#fff' (typed as string)
+ * ```
+ */
+function _tap<T = unknown>(token: TokenDef, axisValues: Record<string, string>): T {
+  const key = [...token.axes]
+    .sort()
+    .map((axis) => axisValues[axis] ?? '')
+    .join(':');
+  return (token.values[key] ?? token.fallback) as T;
+}
+
+/**
+ * Generate a CSS var() reference for a token.
+ *
+ * Returns a `var(--czap-<name>)` string suitable for use in CSS properties.
+ *
+ * @example
+ * ```ts
+ * const token = Token.make({
+ *   name: 'primary', category: 'color',
+ *   axes: ['theme'] as const,
+ *   values: { 'light': '#000' },
+ *   fallback: '#888',
+ * });
+ * const ref = Token.cssVar(token);
+ * // ref === 'var(--czap-primary)'
+ * ```
+ */
+function _cssVar<N extends string>(token: TokenDef<N>): `var(--czap-${N})` {
+  return `var(--czap-${token.name})` as `var(--czap-${N})`;
+}
+
+/**
+ * Token namespace -- design token primitive for adaptive rendering.
+ *
+ * Create named design values that vary across axes (theme, density, contrast).
+ * Tokens are content-addressed and produce CSS custom property references.
+ *
+ * @example
+ * ```ts
+ * import { Token } from '@czap/core';
+ *
+ * const spacing = Token.make({
+ *   name: 'gap', category: 'spacing',
+ *   axes: ['density'] as const,
+ *   values: { 'compact': '4px', 'comfortable': '8px' },
+ *   fallback: '6px',
+ * });
+ * const resolved = Token.tap(spacing, { density: 'compact' });
+ * // resolved === '4px'
+ * const cssRef = Token.cssVar(spacing);
+ * // cssRef === 'var(--czap-gap)'
+ * ```
+ */
+export const Token: TokenFactory & {
+  tap: typeof _tap;
+  cssVar: typeof _cssVar;
+} = {
+  /**
+   * Create a new TokenDef from a configuration object.
+   *
+   * The token is content-addressed via FNV-1a hash of its name, category,
+   * axes, and values. The resulting object is frozen.
+   *
+   * @example
+   * ```ts
+   * const token = Token.make({
+   *   name: 'bg', category: 'color',
+   *   axes: ['theme', 'contrast'] as const,
+   *   values: { 'light:normal': '#fff', 'dark:normal': '#111' },
+   *   fallback: '#ccc',
+   * });
+   * // token._tag === 'TokenDef'
+   * // token.cssProperty === '--czap-bg'
+   * ```
+   */
+  make<N extends string, const A extends readonly [string, ...string[]]>(config: {
+    readonly name: N;
+    readonly category: TokenCategory;
+    readonly axes: A;
+    readonly values: Record<string, unknown>;
+    readonly fallback: unknown;
+  }): TokenDef<N, A> {
+    if (config.name === '') {
+      throw new CzapValidationError('Token.make', 'Token name must not be empty.');
+    }
+    const seen = new Set<string>();
+    for (const axis of config.axes) {
+      if (seen.has(axis)) {
+        throw new CzapValidationError('Token.make', `duplicate axis "${axis}". Each axis must have a unique name.`);
+      }
+      seen.add(axis);
+    }
+
+    const id = deterministicId(config.name, config.category, config.axes, config.values, config.fallback);
+
+    return Object.freeze({
+      _tag: 'TokenDef' as const,
+      _version: 1 as const,
+      id,
+      name: config.name,
+      category: config.category,
+      axes: config.axes,
+      values: config.values,
+      fallback: config.fallback,
+      cssProperty: `--czap-${config.name}` as const,
+    });
+  },
+  tap: _tap,
+  cssVar: _cssVar,
+};
+
+export declare namespace Token {
+  /** Structural shape of a token definition parameterized by its name `N` and axis tuple `Axes`. */
+  export type Shape<N extends string = string, Axes extends readonly string[] = readonly string[]> = TokenDef<N, Axes>;
+}

package/src/tuple.ts

@@ -0,0 +1,19 @@
+/**
+ * Map each element of a readonly tuple, preserving tuple arity and ordering.
+ *
+ * TypeScript's Array.prototype.map returns U[], erasing tuple structure.
+ * This helper reintroduces the mapped tuple type via one narrow cast,
+ * provably safe: the map is total over the input and the output element
+ * type is uniform.
+ *
+ * @example
+ * ```ts
+ * const types = tupleMap([1, 'two', true] as const, (el) => typeof el);
+ * // types: readonly ['number', 'string', 'boolean']
+ * ```
+ */
+export const tupleMap = <T extends readonly unknown[], U>(
+  tuple: T,
+  fn: (element: T[number], index: number) => U,
+): { readonly [K in keyof T]: U } =>
+  tuple.map(fn) as { readonly [K in keyof T]: U };

package/src/type-utils.ts

@@ -0,0 +1,48 @@
+/**
+ * Type-level utilities for `@czap/core`.
+ *
+ * Mapped types, conditional helpers, and structural utilities
+ * used across boundary definitions and compositor outputs.
+ *
+ * @module
+ */
+
+import type { Boundary } from './boundary.js';
+import type { StateName, HLC } from './brands.js';
+import type { Effect as EffectType } from 'effect';
+
+/** Flatten branded intersections for clean IDE hints */
+export type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Extract literal union of state names from a Boundary.Shape */
+export type StateUnion<B extends Boundary.Shape> = B['states'][number];
+
+/** Generate valid output shapes per state */
+export type OutputsFor<B extends Boundary.Shape, T> = {
+  readonly [S in StateUnion<B>]: T;
+};
+
+/** Discriminated union of boundary crossings */
+export type BoundaryCrossing<S extends string = string> = {
+  readonly from: StateName<S>;
+  readonly to: StateName<S>;
+  readonly timestamp: HLC;
+  readonly value: number;
+};
+
+/** Extract the value type from an Effect */
+export type EffectValue<T> = T extends EffectType.Effect<infer A, unknown, unknown> ? A : never;
+
+/** Extract the error type from an Effect */
+export type EffectError<T> = T extends EffectType.Effect<unknown, infer E, unknown> ? E : never;
+
+/** Require at least one key of T */
+export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> &
+  { [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>> }[Keys];
+
+/** Deep readonly */
+export type DeepReadonly<T> = T extends (infer U)[]
+  ? ReadonlyArray<DeepReadonly<U>>
+  : T extends Record<string, unknown>
+    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
+    : T;

package/src/typed-ref.ts

@@ -0,0 +1,79 @@
+/**
+ * TypedRef -- content-addressed payload references.
+ *
+ * Uses CBOR canonical encoding (cborg) and SHA-256 via crypto.subtle.
+ *
+ * @module
+ */
+
+import { Effect } from 'effect';
+import { encode } from 'cborg';
+
+// Content-addressed identity: CBOR-canonical payload → FNV-1a hash. Same definition = same address.
+
+interface TypedRefShape {
+  readonly schema_hash: string;
+  readonly content_hash: string;
+}
+
+/** Canonicalize value to CBOR bytes using canonical (deterministic) encoding. */
+export const canonicalize = (value: unknown): Uint8Array => encode(value);
+
+/**
+ * Hash data using SHA-256. Returns "sha256:hex" formatted hash.
+ *
+ * The `bytes as BufferSource` assertion is the single sanctioned cast in this
+ * file. `Uint8Array` is structurally a BufferSource, but TS's DOM lib types
+ * `bytes.buffer` as potentially-SharedArrayBuffer, preventing direct assignment.
+ * Safe: cborg encodes into fresh ArrayBuffer and TextEncoder.encode returns
+ * ArrayBuffer-backed views. No data copy.
+ *
+ * Hash-primitive failures are unrecoverable in practice (crypto.subtle errors
+ * are environment-level, not user-recoverable), so we `Effect.orDie` to fold
+ * the Error channel into a defect and keep the `Effect<string>` signature that
+ * the content-addressing pipeline relies on.
+ */
+export const hash = (data: string | Uint8Array): Effect.Effect<string> =>
+  Effect.tryPromise({
+    try: async () => {
+      const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+      const buffer = await crypto.subtle.digest('SHA-256', bytes as BufferSource);
+      const hashHex = Array.from(new Uint8Array(buffer))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+      return `sha256:${hashHex}`;
+    },
+    catch: (error) => new Error(`SHA-256 hash failed: ${error instanceof Error ? error.message : String(error)}`),
+  }).pipe(Effect.orDie);
+
+/** Create a TypedRef from schema hash and payload. */
+const _create = (schemaHash: string, payload: unknown): Effect.Effect<TypedRefShape> =>
+  Effect.gen(function* () {
+    const contentHash = yield* hash(canonicalize(payload));
+    return { schema_hash: schemaHash, content_hash: contentHash };
+  });
+
+/** Compare two TypedRefs for structural equality. */
+const _equals = (a: TypedRefShape, b: TypedRefShape): boolean =>
+  a.schema_hash === b.schema_hash && a.content_hash === b.content_hash;
+
+/**
+ * TypedRef — schema-plus-content-hash pointer used by the receipt pipeline.
+ * Lets a receipt reference a payload by its content address without embedding
+ * the payload itself, while still binding it to a schema identity.
+ */
+export const TypedRef = {
+  /** Build a {@link TypedRef} from a schema hash and an arbitrary payload. */
+  create: _create,
+  /** Structural equality over schema + content hashes. */
+  equals: _equals,
+  /** Canonical-CBOR-ish serialization used to compute the content hash. */
+  canonicalize,
+  /** Hash a canonicalized payload to its content address. */
+  hash,
+};
+
+export declare namespace TypedRef {
+  /** Structural shape of a typed reference: schema hash + content hash. */
+  export type Shape = TypedRefShape;
+}