@czap/core 0.1.0

package/src/av-bridge.ts

@@ -0,0 +1,161 @@
+/**
+ * AVBridge -- SharedArrayBuffer timeline bridge for A/V convergence.
+ *
+ * Provides a single sample counter shared between an AudioWorklet
+ * (which advances it) and the visual compositor (which reads it).
+ * Works in both real-time (browser) and offline (deterministic) modes.
+ *
+ * Memory layout (SharedArrayBuffer, 24 bytes):
+ *   Int32[0] -- sample counter (atomic increment by audio, atomic read by video)
+ *   Int32[1] -- audio running flag (1 = playing, 0 = paused)
+ *   Float64[1] -- audio start timestamp in ms (bytes 8-15, for drift calc)
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface AVBridgeShape {
+  readonly buffer: SharedArrayBuffer;
+  readonly sampleRate: number;
+  readonly fps: number;
+
+  advanceSamples(count: number): void;
+  getCurrentSample(): number;
+  setRunning(running: boolean): void;
+  isRunning(): boolean;
+
+  getCurrentFrame(): number;
+  sampleToTime(sample: number): number;
+  timeToSample(time: number): number;
+
+  isAudioAhead(): boolean;
+  drift(): number;
+  reset(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const BUFFER_BYTE_LENGTH = 24;
+const SAMPLE_COUNTER_IDX = 0;
+const RUNNING_FLAG_IDX = 1;
+const START_TIMESTAMP_F64_IDX = 1;
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+interface AVBridgeConfig {
+  readonly sampleRate: number;
+  readonly fps: number;
+  readonly buffer?: SharedArrayBuffer;
+}
+
+/**
+ * Creates an AVBridge backed by a SharedArrayBuffer for lock-free
+ * audio/video timeline synchronization between threads.
+ *
+ * @example
+ * ```ts
+ * const bridge = AVBridge.make({ sampleRate: 48000, fps: 60 });
+ * bridge.setRunning(true);
+ * bridge.advanceSamples(800); // AudioWorklet advances by 800 samples
+ * const frame = bridge.getCurrentFrame(); // current video frame number
+ * const drift = bridge.drift(); // fractional frame offset
+ * bridge.reset(); // zero out counters
+ * ```
+ */
+function _make(config: AVBridgeConfig): AVBridgeShape {
+  const { sampleRate, fps } = config;
+  if (sampleRate <= 0 || !Number.isFinite(sampleRate)) {
+    throw new RangeError(`AVBridge.make: sampleRate must be a positive finite number, got ${sampleRate}`);
+  }
+  if (fps <= 0 || !Number.isFinite(fps)) {
+    throw new RangeError(`AVBridge.make: fps must be a positive finite number, got ${fps}`);
+  }
+  const buffer = config.buffer ?? new SharedArrayBuffer(BUFFER_BYTE_LENGTH);
+  const i32 = new Int32Array(buffer);
+  const f64 = new Float64Array(buffer);
+
+  return {
+    buffer,
+    sampleRate,
+    fps,
+
+    advanceSamples(count: number): void {
+      Atomics.add(i32, SAMPLE_COUNTER_IDX, count);
+    },
+
+    getCurrentSample(): number {
+      return Atomics.load(i32, SAMPLE_COUNTER_IDX);
+    },
+
+    setRunning(running: boolean): void {
+      Atomics.store(i32, RUNNING_FLAG_IDX, running ? 1 : 0);
+    },
+
+    isRunning(): boolean {
+      return Atomics.load(i32, RUNNING_FLAG_IDX) === 1;
+    },
+
+    getCurrentFrame(): number {
+      const sample = Atomics.load(i32, SAMPLE_COUNTER_IDX);
+      return Math.floor((sample / sampleRate) * fps);
+    },
+
+    sampleToTime(sample: number): number {
+      return sample / sampleRate;
+    },
+
+    timeToSample(time: number): number {
+      return Math.round(time * sampleRate);
+    },
+
+    isAudioAhead(): boolean {
+      const sample = Atomics.load(i32, SAMPLE_COUNTER_IDX);
+      const frame = Math.floor((sample / sampleRate) * fps);
+      const samplesPerFrame = sampleRate / fps;
+      return sample % samplesPerFrame > 0 || sample > (frame + 1) * samplesPerFrame;
+    },
+
+    drift(): number {
+      const sample = Atomics.load(i32, SAMPLE_COUNTER_IDX);
+      const exactFrame = (sample / sampleRate) * fps;
+      const currentFrame = Math.floor(exactFrame);
+      return exactFrame - currentFrame;
+    },
+
+    reset(): void {
+      Atomics.store(i32, SAMPLE_COUNTER_IDX, 0);
+      Atomics.store(i32, RUNNING_FLAG_IDX, 0);
+      f64[START_TIMESTAMP_F64_IDX] = 0;
+    },
+  };
+}
+
+/**
+ * AVBridge -- SharedArrayBuffer-based timeline bridge for audio/video convergence.
+ * Provides atomic sample counting shared between AudioWorklet and visual compositor.
+ *
+ * @example
+ * ```ts
+ * const bridge = AVBridge.make({ sampleRate: 44100, fps: 30 });
+ * bridge.setRunning(true);
+ * bridge.advanceSamples(1470); // advance by one video frame worth of samples
+ * bridge.getCurrentFrame(); // 1
+ * bridge.sampleToTime(44100); // 1.0 (seconds)
+ * bridge.timeToSample(0.5);   // 22050
+ * ```
+ */
+export const AVBridge = { make: _make };
+
+export declare namespace AVBridge {
+  /** Structural shape of an AVBridge instance — sample counters, time conversions, reset. */
+  export type Shape = AVBridgeShape;
+  /** Configuration accepted by {@link AVBridge.make}: sample rate and fps. */
+  export type Config = AVBridgeConfig;
+}

package/src/av-renderer.ts

@@ -0,0 +1,118 @@
+/**
+ * AVRenderer -- deterministic offline A/V renderer.
+ *
+ * Steps through audio samples and visual frames in lockstep.
+ * Each video frame knows its exact audio position. No wall-clock
+ * dependency -- fully deterministic.
+ *
+ * @module
+ */
+
+import type { CompositeState } from './compositor.js';
+import type { Compositor } from './compositor.js';
+import { AVBridge } from './av-bridge.js';
+import type { Millis } from './brands.js';
+import { Effect } from 'effect';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface AVRenderConfig {
+  readonly sampleRate: number;
+  readonly fps: number;
+  readonly durationMs: Millis;
+}
+
+interface AVFrameOutput {
+  readonly frame: number;
+  readonly timestamp: number;
+  readonly sample: number;
+  readonly sampleCount: number;
+  readonly state: CompositeState;
+}
+
+interface AVRendererShape {
+  readonly config: AVRenderConfig;
+  readonly bridge: AVBridge.Shape;
+  readonly totalFrames: number;
+  frames(options?: {
+    onAudioFrame?: (sample: number, sampleCount: number) => void;
+    onVideoFrame?: (frame: number, timestamp: number, state: CompositeState) => void;
+  }): AsyncGenerator<AVFrameOutput>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+function _make(config: AVRenderConfig, compositor: Compositor.Shape, existingBridge?: AVBridge.Shape): AVRendererShape {
+  const { sampleRate, fps, durationMs } = config;
+  const totalFrames = Math.ceil((durationMs / 1000) * fps);
+  const samplesPerFrame = Math.round(sampleRate / fps);
+
+  const bridge = existingBridge ?? AVBridge.make({ sampleRate, fps });
+  bridge.reset();
+
+  return {
+    config,
+    bridge,
+    totalFrames,
+
+    async *frames(options) {
+      const { onAudioFrame, onVideoFrame } = options ?? {};
+
+      for (let i = 0; i < totalFrames; i++) {
+        const targetSample = (i + 1) * samplesPerFrame;
+        const currentSample = bridge.getCurrentSample();
+        const advance = targetSample - currentSample;
+
+        if (advance > 0) {
+          bridge.advanceSamples(advance);
+        }
+
+        const frameSample = i * samplesPerFrame;
+        const timestamp = (i * 1000) / fps;
+
+        if (onAudioFrame) {
+          onAudioFrame(frameSample, samplesPerFrame);
+        }
+
+        const state = await Effect.runPromise(compositor.compute());
+
+        if (onVideoFrame) {
+          onVideoFrame(i, timestamp, state);
+        }
+
+        yield {
+          frame: i,
+          timestamp,
+          sample: frameSample,
+          sampleCount: samplesPerFrame,
+          state,
+        };
+      }
+    },
+  };
+}
+
+/**
+ * AVRenderer — deterministic offline audio+video renderer.
+ *
+ * Steps an {@link AVBridge} in lockstep with a {@link Compositor} so every
+ * video frame carries the exact sample offset it corresponds to. Pure clock
+ * math — no wall-clock input, reproducible across runs.
+ */
+export const AVRenderer = {
+  /** Create a renderer bound to a compositor, optionally reusing an existing {@link AVBridge}. */
+  make: _make,
+};
+
+export declare namespace AVRenderer {
+  /** Structural shape of a renderer instance returned by {@link AVRenderer.make}. */
+  export type Shape = AVRendererShape;
+  /** Configuration accepted by {@link AVRenderer.make}. */
+  export type Config = AVRenderConfig;
+  /** Per-frame output yielded by the async iterator. */
+  export type FrameOutput = AVFrameOutput;
+}

package/src/blend.ts

@@ -0,0 +1,135 @@
+/**
+ * BlendTree -- weighted multi-state blending.
+ *
+ * A blend tree holds named numeric-record values with weights.
+ * `compute()` returns the weighted average of all values.
+ *
+ * @module
+ */
+
+import type { Scope } from 'effect';
+import { Effect, Stream, PubSub } from 'effect';
+
+interface BlendNodeShape<T> {
+  readonly value: T;
+  readonly weight: number;
+}
+
+interface BlendTreeShape<T extends Record<string, number>> {
+  add(name: string, value: T, weight: number): void;
+  remove(name: string): void;
+  setWeight(name: string, weight: number): void;
+  compute(): T;
+  readonly changes: Stream.Stream<T>;
+}
+
+/**
+ * Creates a new BlendTree for weighted multi-state blending of numeric records.
+ * Requires a Scope for lifecycle management of the change stream.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const tree = yield* BlendTree.make<{ x: number; y: number }>();
+ *   tree.add('idle', { x: 0, y: 0 }, 0.3);
+ *   tree.add('active', { x: 100, y: 50 }, 0.7);
+ *   const blended = tree.compute(); // { x: 70, y: 35 }
+ * }));
+ * ```
+ */
+function _make<T extends Record<string, number>>(): Effect.Effect<BlendTreeShape<T>, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const nodes = new Map<string, BlendNodeShape<T>>();
+    const pubsub = yield* PubSub.unbounded<T>();
+
+    // The computed result is a Record<string, number> whose keys match T's keys by
+     // construction (we only write keys copied from node.value, which is T). TS can't
+     // track that structural promise, so we contain one cast in a named helper.
+    const finalizeBlend = (record: Record<string, number>): T => record as unknown as T;
+
+    function computeBlend(): T {
+      const result: Record<string, number> = {};
+      let totalWeight = 0;
+
+      for (const node of nodes.values()) {
+        if (node.weight > 0) totalWeight += node.weight;
+      }
+
+      if (totalWeight === 0 || nodes.size === 0) {
+        return finalizeBlend(result);
+      }
+
+      let initialized = false;
+      for (const node of nodes.values()) {
+        const w = node.weight > 0 ? node.weight / totalWeight : 0;
+        for (const key in node.value) {
+          if (Object.prototype.hasOwnProperty.call(node.value, key)) {
+            if (!initialized || !(key in result)) {
+              result[key] = 0;
+            }
+            result[key]! += node.value[key]! * w;
+          }
+        }
+        initialized = true;
+      }
+
+      return finalizeBlend(result);
+    }
+
+    function notifyChange(): void {
+      const blended = computeBlend();
+      Effect.runSync(PubSub.publish(pubsub, blended));
+    }
+
+    const tree: BlendTreeShape<T> = {
+      add(name: string, value: T, weight: number): void {
+        nodes.set(name, { value, weight });
+        notifyChange();
+      },
+
+      remove(name: string): void {
+        nodes.delete(name);
+        notifyChange();
+      },
+
+      setWeight(name: string, weight: number): void {
+        const node = nodes.get(name);
+        if (node) {
+          nodes.set(name, { ...node, weight });
+          notifyChange();
+        }
+      },
+
+      compute(): T {
+        return computeBlend();
+      },
+
+      changes: Stream.fromPubSub(pubsub),
+    };
+
+    return tree;
+  });
+}
+
+/**
+ * BlendTree -- weighted multi-state blending for numeric records.
+ * Add named nodes with values and weights, then compute the weighted average.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const tree = yield* BlendTree.make<{ opacity: number }>();
+ *   tree.add('fadeIn', { opacity: 1 }, 0.8);
+ *   tree.add('fadeOut', { opacity: 0 }, 0.2);
+ *   const result = tree.compute(); // { opacity: 0.8 }
+ * }));
+ * ```
+ */
+export const BlendTree = { make: _make };
+
+export declare namespace BlendTree {
+  /** Structural shape of a blend-tree instance: `sample(weights)` over a `Record<string, number>` space. */
+  export type Shape<T extends Record<string, number>> = BlendTreeShape<T>;
+  /** Individual leaf/intermediate node in a blend tree. */
+  export type Node<T> = BlendNodeShape<T>;
+}