@czap/worker 0.1.0

package/src/host.ts

@@ -0,0 +1,189 @@
+/**
+ * WorkerHost -- main-thread coordinator for compositor and render workers.
+ *
+ * Provides a unified API for:
+ * - Managing a CompositorWorker (off-thread state computation)
+ * - Managing a RenderWorker (off-thread OffscreenCanvas rendering)
+ * - Attaching an HTMLCanvasElement for off-thread rendering
+ * - Subscribing to state updates from the compositor worker
+ *
+ * @module
+ */
+
+import type { CompositeState, VideoConfig } from '@czap/core';
+import type { WorkerConfig } from './messages.js';
+import { CompositorWorker, type CompositorWorkerStartupTelemetry } from './compositor-worker.js';
+import { RenderWorker } from './render-worker.js';
+
+type WorkerHostState = CompositeState & {
+  readonly resolvedStateGenerations?: Record<string, number>;
+};
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Host-facing surface of a worker host. Owns a compositor worker and,
+ * optionally, a render worker created on demand via
+ * {@link WorkerHostShape.attachCanvas}. Returned by {@link WorkerHost.create}.
+ */
+export interface WorkerHostShape {
+  /** The compositor worker instance. */
+  readonly compositor: CompositorWorker.Shape;
+
+  /** The render worker instance, or null if no canvas has been attached. */
+  readonly renderer: RenderWorker.Shape | null;
+
+  /**
+   * Attach an HTMLCanvasElement for off-thread rendering.
+   *
+   * Calls `canvas.transferControlToOffscreen()` and transfers the
+   * resulting OffscreenCanvas to the render worker. A render worker
+   * is created on demand if one does not already exist.
+   *
+   * This can only be called once per canvas element -- the browser
+   * does not allow transferring control multiple times.
+   */
+  attachCanvas(canvas: HTMLCanvasElement): void;
+
+  /** Start off-thread video rendering with the given configuration. */
+  startRender(config: VideoConfig): void;
+
+  /** Stop an in-progress off-thread render. */
+  stopRender(): void;
+
+  /**
+   * Subscribe to CompositeState updates from the compositor worker.
+   * Returns an unsubscribe function.
+   */
+  onState(callback: (state: WorkerHostState) => void): () => void;
+
+  /** Dispose both workers and release all resources. */
+  dispose(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+function _createWorkerHost(
+  config?: WorkerConfig,
+  startupTelemetry?: CompositorWorkerStartupTelemetry,
+): WorkerHostShape {
+  const compositor = CompositorWorker.create(config, startupTelemetry);
+  let renderer: RenderWorker.Shape | null = null;
+
+  // Forward compositor state to the render worker's quantizer registry.
+  // This keeps the render worker's internal state in sync when the
+  // compositor produces new states.
+  const stateUnsubscribers: Array<() => void> = [];
+
+  const host: WorkerHostShape = {
+    get compositor(): CompositorWorker.Shape {
+      return compositor;
+    },
+
+    get renderer(): RenderWorker.Shape | null {
+      return renderer;
+    },
+
+    attachCanvas(canvas: HTMLCanvasElement): void {
+      if (renderer === null) {
+        renderer = RenderWorker.create();
+      }
+
+      // Transfer control to an OffscreenCanvas and send it to the worker.
+      // `transferControlToOffscreen()` can only be called once per element.
+      const offscreen = canvas.transferControlToOffscreen();
+      renderer.transferCanvas(offscreen);
+    },
+
+    startRender(videoConfig: VideoConfig): void {
+      if (renderer === null) {
+        throw new Error('WorkerHost: cannot start render -- no canvas attached. Call attachCanvas() first.');
+      }
+      renderer.startRender(videoConfig);
+    },
+
+    stopRender(): void {
+      if (renderer !== null) {
+        renderer.stopRender();
+      }
+    },
+
+    onState(callback: (state: WorkerHostState) => void): () => void {
+      const unsub = compositor.onState(callback);
+      stateUnsubscribers.push(unsub);
+      return () => {
+        const index = stateUnsubscribers.indexOf(unsub);
+        if (index >= 0) {
+          stateUnsubscribers.splice(index, 1);
+        }
+        unsub();
+      };
+    },
+
+    dispose(): void {
+      for (const unsub of stateUnsubscribers) unsub();
+      stateUnsubscribers.length = 0;
+
+      compositor.dispose();
+      if (renderer !== null) {
+        renderer.dispose();
+        renderer = null;
+      }
+    },
+  };
+
+  return host;
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+/**
+ * `WorkerHost` -- main-thread lifecycle wrapper that owns a
+ * {@link CompositorWorker.Shape} and (optionally) a
+ * {@link RenderWorker.Shape}, exposing a single unified surface for DOM
+ * integration.
+ *
+ * Typical flow:
+ * 1. `const host = WorkerHost.create({...})` on the main thread.
+ * 2. `host.attachCanvas(canvasEl)` to lazily mint a render worker and
+ *    transfer its `OffscreenCanvas`.
+ * 3. `host.startRender(videoConfig)` / `host.stopRender()` to control
+ *    the render loop.
+ * 4. `host.onState(cb)` to subscribe to composite state updates.
+ * 5. `host.dispose()` when the host is unmounted -- releases both
+ *    workers and every subscription.
+ *
+ * @example
+ * ```ts
+ * import { WorkerHost } from '@czap/worker';
+ *
+ * const host = WorkerHost.create({ poolCapacity: 64 });
+ * host.attachCanvas(canvas);
+ * host.startRender({ durationMs: 5000, fps: 60, width: 1280, height: 720 });
+ * const unsub = host.onState((state) => console.log(state.discrete));
+ * // ...
+ * unsub();
+ * host.dispose();
+ * ```
+ */
+export const WorkerHost = {
+  /**
+   * Create a worker host. The compositor worker starts immediately; the
+   * render worker is created lazily on the first
+   * {@link WorkerHostShape.attachCanvas} call.
+   */
+  create: _createWorkerHost,
+} as const;
+
+export declare namespace WorkerHost {
+  /** Public host surface returned by {@link WorkerHost.create}. */
+  export type Shape = WorkerHostShape;
+  /** Telemetry sink forwarded to the inner compositor worker. */
+  export type StartupTelemetry = CompositorWorkerStartupTelemetry;
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * `@czap/worker` — **LiteShip** off-deck crew: compositor and render workers
+ * that keep the main thread trim while boundaries and media stay live.
+ *
+ * This package ships:
+ *
+ * - {@link SPSCRing}: lock-free single-producer/single-consumer ring
+ *   backed by `SharedArrayBuffer`, used for real-time state streaming
+ *   from a worker to the main thread.
+ * - {@link CompositorWorker}: a factory that spins up a worker which
+ *   evaluates quantizer boundaries and emits `CompositeState`.
+ * - {@link RenderWorker}: a factory for a worker that renders
+ *   `VideoFrameOutput` into an `OffscreenCanvas`.
+ * - {@link WorkerHost}: a thin lifecycle wrapper around `Worker` with
+ *   typed message helpers.
+ *
+ * ## SharedArrayBuffer requirements
+ *
+ * The SPSC ring buffer uses `SharedArrayBuffer`, which requires the page
+ * to be served with the following HTTP headers:
+ *
+ *   Cross-Origin-Opener-Policy: same-origin
+ *   Cross-Origin-Embedder-Policy: require-corp
+ *
+ * Workers created by this package use inline Blob URLs and do not require
+ * separate worker entry files or bundler configuration.
+ *
+ * @module
+ */
+
+// Messages
+export { Messages } from './messages.js';
+export type { ToWorkerMessage, FromWorkerMessage, WorkerConfig } from './messages.js';
+
+// SPSC Ring Buffer
+export { SPSCRing } from './spsc-ring.js';
+export type { SPSCRingBufferShape } from './spsc-ring.js';
+
+// Compositor Worker
+export { CompositorWorker } from './compositor-worker.js';
+export type { CompositorWorkerShape, CompositorWorkerState } from './compositor-types.js';
+
+// Render Worker
+export { RenderWorker } from './render-worker.js';
+export type { RenderWorkerShape } from './render-worker.js';
+
+// Host
+export { WorkerHost } from './host.js';
+export type { WorkerHostShape } from './host.js';

package/src/messages.ts

@@ -0,0 +1,343 @@
+/**
+ * Typed message protocol for main-thread and worker communication.
+ *
+ * All message types are discriminated unions keyed on `type`.
+ * Every payload must be Structured Clone compatible -- no functions,
+ * no Effect objects, only plain serializable data.
+ *
+ * @module
+ */
+
+import type { CompositeState, VideoConfig, VideoFrameOutput } from '@czap/core';
+
+// ---------------------------------------------------------------------------
+// Worker configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Tunable knobs that the main thread sends to a worker at construction time.
+ *
+ * Omitted fields fall back to worker-local defaults chosen by
+ * {@link CompositorWorker} / {@link RenderWorker}.
+ */
+export interface WorkerConfig {
+  /** Maximum number of pooled `CompositeState` slots the worker may hold. */
+  readonly poolCapacity?: number;
+  /** Target frames-per-second for the render loop (affects frame pacing). */
+  readonly targetFps?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Main -> Worker messages
+// ---------------------------------------------------------------------------
+
+interface InitMessage {
+  readonly type: 'init';
+}
+
+interface AddQuantizerMessage {
+  readonly type: 'add-quantizer';
+  readonly name: string;
+  readonly boundaryId: string;
+  readonly states: readonly string[];
+  readonly thresholds: Float64Array | readonly number[];
+}
+
+/**
+ * Bootstrap registration for a single quantizer inside a worker.
+ *
+ * Sent from the main thread so the worker can reconstruct its quantizer
+ * registry without re-running the full build pipeline on cold start.
+ */
+export interface BootstrapQuantizerRegistration {
+  /** Stable quantizer name (key in the registry). */
+  readonly name: string;
+  /** Boundary content-address this quantizer is anchored to. */
+  readonly boundaryId: string;
+  /** Ordered discrete state labels. */
+  readonly states: readonly string[];
+  /** Threshold boundaries (length = states.length - 1). */
+  readonly thresholds: Float64Array | readonly number[];
+  /** Optional initial discrete state (defaults to the first state). */
+  readonly initialState?: string;
+  /** Optional initial blend weights, keyed by state label. */
+  readonly blendWeights?: Record<string, number>;
+}
+
+/**
+ * Aggregate startup payload: registrations plus any pending updates that
+ * should be replayed immediately after the worker finishes wiring its
+ * quantizer registry.
+ */
+export interface StartupComputePacket {
+  /** Whether the worker should boot empty, rehydrate from snapshot, or fully rebuild. */
+  readonly bootstrapMode: 'cold' | 'warm-snapshot' | 'rebuild';
+  /** Registrations to install. */
+  readonly registrations: readonly BootstrapQuantizerRegistration[];
+  /** Updates to replay after registration. */
+  readonly updates: readonly WorkerUpdate[];
+}
+
+/**
+ * A single resolved discrete-state entry in a bootstrap/apply message.
+ *
+ * `generation` monotonically increases so receivers can discard stale
+ * out-of-order deliveries.
+ */
+export interface ResolvedStateEntry {
+  /** Quantizer name. */
+  readonly name: string;
+  /** Resolved discrete state label. */
+  readonly state: string;
+  /** Monotonically-increasing generation counter. */
+  readonly generation: number;
+}
+
+interface BootstrapQuantizersMessage {
+  readonly type: 'bootstrap-quantizers';
+  readonly registrations: readonly BootstrapQuantizerRegistration[];
+}
+
+interface StartupComputeMessage {
+  readonly type: 'startup-compute';
+  readonly packet: StartupComputePacket;
+}
+
+interface BootstrapResolvedStateMessage {
+  readonly type: 'bootstrap-resolved-state';
+  readonly states: readonly ResolvedStateEntry[];
+  readonly ack?: boolean;
+}
+
+interface ApplyResolvedStateMessage {
+  readonly type: 'apply-resolved-state';
+  readonly states: readonly ResolvedStateEntry[];
+  readonly ack?: boolean;
+}
+
+interface RemoveQuantizerMessage {
+  readonly type: 'remove-quantizer';
+  readonly name: string;
+}
+
+interface RemoveQuantizerUpdate {
+  readonly type: 'remove-quantizer';
+  readonly name: string;
+}
+
+interface EvaluateMessage {
+  readonly type: 'evaluate';
+  readonly name: string;
+  readonly value: number;
+}
+
+interface EvaluateUpdate {
+  readonly type: 'evaluate';
+  readonly name: string;
+  readonly value: number;
+}
+
+interface SetBlendMessage {
+  readonly type: 'set-blend';
+  readonly name: string;
+  readonly weights: Record<string, number>;
+}
+
+interface SetBlendUpdate {
+  readonly type: 'set-blend';
+  readonly name: string;
+  readonly weights: Record<string, number>;
+}
+
+/**
+ * Incremental update applied to a worker's quantizer registry after
+ * bootstrap. Replayed as part of {@link StartupComputePacket.updates} or
+ * sent directly via an `apply-updates` message.
+ */
+export type WorkerUpdate = RemoveQuantizerUpdate | EvaluateUpdate | SetBlendUpdate;
+
+interface ApplyUpdatesMessage {
+  readonly type: 'apply-updates';
+  readonly updates: readonly WorkerUpdate[];
+}
+
+interface ComputeMessage {
+  readonly type: 'compute';
+}
+
+interface WarmResetMessage {
+  readonly type: 'warm-reset';
+}
+
+interface StartRenderMessage {
+  readonly type: 'start-render';
+  readonly config: VideoConfig;
+}
+
+interface StopRenderMessage {
+  readonly type: 'stop-render';
+}
+
+/**
+ * Transfer an OffscreenCanvas to the worker.
+ * The canvas must be listed in the `transfer` array of postMessage.
+ */
+interface TransferCanvasMessage {
+  readonly type: 'transfer-canvas';
+  readonly canvas: OffscreenCanvas;
+}
+
+interface DisposeMessage {
+  readonly type: 'dispose';
+}
+
+/**
+ * Every message the main thread may send to a compositor/render worker.
+ * Discriminated on the `type` field.
+ */
+export type ToWorkerMessage =
+  | InitMessage
+  | AddQuantizerMessage
+  | BootstrapQuantizersMessage
+  | StartupComputeMessage
+  | BootstrapResolvedStateMessage
+  | ApplyResolvedStateMessage
+  | ApplyUpdatesMessage
+  | RemoveQuantizerMessage
+  | EvaluateMessage
+  | SetBlendMessage
+  | WarmResetMessage
+  | ComputeMessage
+  | StartRenderMessage
+  | StopRenderMessage
+  | TransferCanvasMessage
+  | DisposeMessage;
+
+// ---------------------------------------------------------------------------
+// Worker -> Main messages
+// ---------------------------------------------------------------------------
+
+interface ReadyMessage {
+  readonly type: 'ready';
+}
+
+interface StateMessage {
+  readonly type: 'state';
+  readonly state: CompositeState;
+  readonly resolvedStateGenerations?: Record<string, number>;
+}
+
+interface ResolvedStateAckMessage {
+  readonly type: 'resolved-state-ack';
+  readonly generation: number;
+  readonly states: readonly {
+    readonly name: string;
+    readonly state: string;
+  }[];
+  readonly additionalOutputsChanged: boolean;
+}
+
+interface FrameMessage {
+  readonly type: 'frame';
+  readonly output: VideoFrameOutput;
+}
+
+interface RenderCompleteMessage {
+  readonly type: 'render-complete';
+  readonly totalFrames: number;
+}
+
+interface ErrorMessage {
+  readonly type: 'error';
+  readonly message: string;
+}
+
+interface MetricsMessage {
+  readonly type: 'metrics';
+  readonly fps: number;
+  readonly budgetUsed: number;
+}
+
+/**
+ * Build a bootstrap/apply resolved-state envelope.
+ *
+ * Used by the main thread to ship a batch of resolved discrete states
+ * either as part of bootstrap (`bootstrap-resolved-state`) or as an
+ * incremental reconciliation (`apply-resolved-state`).
+ *
+ * @param type - Which envelope to produce.
+ * @param states - The resolved entries to include.
+ * @param ack - Whether the worker is expected to acknowledge the delivery.
+ */
+export function makeResolvedStateEnvelope(
+  type: 'bootstrap-resolved-state' | 'apply-resolved-state',
+  states: readonly ResolvedStateEntry[],
+  ack: boolean,
+): BootstrapResolvedStateMessage | ApplyResolvedStateMessage {
+  return {
+    type,
+    states,
+    ack,
+  };
+}
+
+/**
+ * Every message a worker may send back to the main thread. Discriminated
+ * on the `type` field. Includes readiness, state updates, frame output,
+ * metrics, completion signals, and errors.
+ */
+export type FromWorkerMessage =
+  | ReadyMessage
+  | StateMessage
+  | ResolvedStateAckMessage
+  | FrameMessage
+  | RenderCompleteMessage
+  | ErrorMessage
+  | MetricsMessage;
+
+// ---------------------------------------------------------------------------
+// Namespace re-export
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime type guards and type aliases for the worker message protocol.
+ * Consumers typically use {@link Messages.isToWorker} /
+ * {@link Messages.isFromWorker} inside a `message` handler to narrow
+ * `event.data` before switching on the `type` field.
+ *
+ * @example
+ * ```ts
+ * worker.addEventListener('message', (e) => {
+ *   if (!Messages.isFromWorker(e.data)) return;
+ *   if (e.data.type === 'state') { /* ... *\/ }
+ * });
+ * ```
+ */
+export const Messages = {
+  /** Type guard: is a ToWorkerMessage */
+  isToWorker(msg: unknown): msg is ToWorkerMessage {
+    return typeof msg === 'object' && msg !== null && 'type' in msg;
+  },
+
+  /** Type guard: is a FromWorkerMessage */
+  isFromWorker(msg: unknown): msg is FromWorkerMessage {
+    return typeof msg === 'object' && msg !== null && 'type' in msg;
+  },
+} as const;
+
+export declare namespace Messages {
+  /** Every message the main thread may send to a worker. */
+  export type ToWorker = ToWorkerMessage;
+  /** Every message a worker may send back to the main thread. */
+  export type FromWorker = FromWorkerMessage;
+  /** Tunable worker construction knobs. */
+  export type Config = WorkerConfig;
+  /** Incremental update applied post-bootstrap. */
+  export type Update = WorkerUpdate;
+  /** Single quantizer bootstrap registration. */
+  export type BootstrapRegistration = BootstrapQuantizerRegistration;
+  /** Full startup packet flushed once during worker boot. */
+  export type StartupPacket = StartupComputePacket;
+  /** Single resolved-state entry delivered to a worker. */
+  export type ResolvedState = ResolvedStateEntry;
+}