@czap/worker 0.1.0

package/dist/spsc-ring.js

@@ -0,0 +1,240 @@
+/**
+ * SPSCRing -- lock-free single-producer single-consumer ring buffer
+ * backed by SharedArrayBuffer.
+ *
+ * Designed for real-time compositor state streaming between a Worker
+ * (producer) and the main thread (consumer) without blocking either side.
+ *
+ * ## SharedArrayBuffer requirements
+ *
+ * SharedArrayBuffer requires the page to be served with the following
+ * HTTP headers (COOP/COEP):
+ *
+ *   Cross-Origin-Opener-Policy: same-origin
+ *   Cross-Origin-Embedder-Policy: require-corp
+ *
+ * Without these headers, `new SharedArrayBuffer(...)` will throw.
+ *
+ * ## Memory layout
+ *
+ * ```
+ * Int32Array view (control region):
+ *   [0]: write cursor  (atomically incremented by producer)
+ *   [1]: read cursor   (atomically incremented by consumer)
+ *
+ * Float64Array view (data region):
+ *   Offset = 8 bytes (aligned after two Int32 control slots)
+ *   [0 .. slotCount * slotSize - 1]: ring buffer data slots
+ * ```
+ *
+ * The producer writes at `writeCursor % slotCount`, the consumer reads
+ * at `readCursor % slotCount`. The buffer is full when
+ * `write - read === slotCount`, empty when `write === read`.
+ *
+ * Only `Atomics.load` and `Atomics.store` are used -- no `Atomics.wait`
+ * or `Atomics.notify` -- keeping this fully lock-free and non-blocking.
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Byte offset where the Int32 control slots live. */
+const WRITE_CURSOR_INDEX = 0;
+const READ_CURSOR_INDEX = 1;
+/**
+ * Byte size of the control region: two Int32 values (8 bytes),
+ * padded to 8-byte alignment for the Float64 data region.
+ */
+const CONTROL_BYTES = 8;
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+function _createBuffer(slotCount, slotSize) {
+    const dataBytes = slotCount * slotSize * Float64Array.BYTES_PER_ELEMENT;
+    return new SharedArrayBuffer(CONTROL_BYTES + dataBytes);
+}
+function _makeRing(sab, slotCount, slotSize, role) {
+    if (slotCount <= 0 || !Number.isInteger(slotCount)) {
+        throw new RangeError(`SPSCRingBuffer: slotCount must be a positive integer, got ${slotCount}`);
+    }
+    if (slotSize <= 0 || !Number.isInteger(slotSize)) {
+        throw new RangeError(`SPSCRingBuffer: slotSize must be a positive integer, got ${slotSize}`);
+    }
+    const control = new Int32Array(sab, 0, 2);
+    const data = new Float64Array(sab, CONTROL_BYTES);
+    return {
+        push(input) {
+            if (role !== 'producer') {
+                throw new Error('SPSCRingBuffer: only the producer may push');
+            }
+            if (input.length !== slotSize) {
+                throw new RangeError(`SPSCRingBuffer: expected slot size ${slotSize}, got ${input.length}`);
+            }
+            const write = Atomics.load(control, WRITE_CURSOR_INDEX);
+            const read = Atomics.load(control, READ_CURSOR_INDEX);
+            // Full when write - read === slotCount
+            if (write - read >= slotCount) {
+                return false;
+            }
+            const slotIndex = (write % slotCount) * slotSize;
+            for (let i = 0; i < slotSize; i++) {
+                data[slotIndex + i] = input[i];
+            }
+            // Store with release semantics: the data write must be visible
+            // before the cursor advances. Atomics.store on Int32Array provides
+            // a sequentially consistent store which is stronger than needed
+            // but correct.
+            Atomics.store(control, WRITE_CURSOR_INDEX, write + 1);
+            return true;
+        },
+        pop(out) {
+            if (role !== 'consumer') {
+                throw new Error('SPSCRingBuffer: only the consumer may pop');
+            }
+            if (out.length !== slotSize) {
+                throw new RangeError(`SPSCRingBuffer: expected slot size ${slotSize}, got ${out.length}`);
+            }
+            const write = Atomics.load(control, WRITE_CURSOR_INDEX);
+            const read = Atomics.load(control, READ_CURSOR_INDEX);
+            // Empty when write === read
+            if (write === read) {
+                return false;
+            }
+            const slotIndex = (read % slotCount) * slotSize;
+            for (let i = 0; i < slotSize; i++) {
+                out[i] = data[slotIndex + i];
+            }
+            Atomics.store(control, READ_CURSOR_INDEX, read + 1);
+            return true;
+        },
+        get capacity() {
+            return slotCount;
+        },
+        get count() {
+            const write = Atomics.load(control, WRITE_CURSOR_INDEX);
+            const read = Atomics.load(control, READ_CURSOR_INDEX);
+            return write - read;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Create a matched producer/consumer pair sharing the same SharedArrayBuffer.
+ *
+ * Typically called on the main thread; the `buffer` (SharedArrayBuffer) is
+ * then transferred to the Worker via `postMessage`, and the Worker calls
+ * `SPSCRing.attachProducer` to get its side of the ring.
+ *
+ * @example
+ * ```ts
+ * import { SPSCRing } from '@czap/worker';
+ *
+ * const { buffer, producer, consumer } = SPSCRing.createPair(64, 4);
+ * // producer.push(new Float64Array([1, 2, 3, 4])); // true
+ * // consumer.pop(new Float64Array(4));              // true
+ * // Transfer buffer to a Worker via postMessage
+ * worker.postMessage({ buffer, slotCount: 64, slotSize: 4 });
+ * ```
+ *
+ * @param slotCount - Number of slots in the ring (power of 2 recommended)
+ * @param slotSize  - Number of Float64 values per slot
+ * @returns An object with the shared buffer and producer/consumer ring handles
+ */
+function _createPair(slotCount, slotSize) {
+    const buffer = _createBuffer(slotCount, slotSize);
+    return {
+        buffer,
+        producer: _makeRing(buffer, slotCount, slotSize, 'producer'),
+        consumer: _makeRing(buffer, slotCount, slotSize, 'consumer'),
+    };
+}
+/**
+ * Attach as producer to an existing SharedArrayBuffer.
+ * Call this inside the Worker that produces data.
+ *
+ * @example
+ * ```ts
+ * import { SPSCRing } from '@czap/worker';
+ *
+ * // Inside a Worker's message handler:
+ * self.onmessage = (e) => {
+ *   const { buffer, slotCount, slotSize } = e.data;
+ *   const producer = SPSCRing.attachProducer(buffer, slotCount, slotSize);
+ *   const data = new Float64Array([1.0, 2.0, 3.0, 4.0]);
+ *   producer.push(data); // true if buffer not full
+ * };
+ * ```
+ *
+ * @param sab       - The SharedArrayBuffer from the main thread
+ * @param slotCount - Number of slots (must match createPair)
+ * @param slotSize  - Float64 values per slot (must match createPair)
+ * @returns A producer-side {@link SPSCRingBufferShape}
+ */
+function _attachProducer(sab, slotCount, slotSize) {
+    return _makeRing(sab, slotCount, slotSize, 'producer');
+}
+/**
+ * Attach as consumer to an existing SharedArrayBuffer.
+ * Call this on the main thread that consumes data.
+ *
+ * @example
+ * ```ts
+ * import { SPSCRing } from '@czap/worker';
+ *
+ * // On the main thread after receiving buffer from Worker:
+ * const consumer = SPSCRing.attachConsumer(sharedBuffer, 64, 4);
+ * const out = new Float64Array(4);
+ * if (consumer.pop(out)) {
+ *   console.log('Received:', out); // Float64Array [1.0, 2.0, 3.0, 4.0]
+ * }
+ * ```
+ *
+ * @param sab       - The SharedArrayBuffer shared with the producer
+ * @param slotCount - Number of slots (must match createPair)
+ * @param slotSize  - Float64 values per slot (must match createPair)
+ * @returns A consumer-side {@link SPSCRingBufferShape}
+ */
+function _attachConsumer(sab, slotCount, slotSize) {
+    return _makeRing(sab, slotCount, slotSize, 'consumer');
+}
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+/**
+ * SPSC ring buffer namespace.
+ *
+ * Lock-free single-producer single-consumer ring buffer backed by
+ * `SharedArrayBuffer`. Designed for real-time compositor state streaming
+ * between a Worker (producer) and the main thread (consumer) without
+ * blocking either side. Uses only `Atomics.load`/`Atomics.store` --
+ * fully non-blocking.
+ *
+ * @example
+ * ```ts
+ * import { SPSCRing } from '@czap/worker';
+ *
+ * // Main thread: create pair and send buffer to Worker
+ * const { buffer, producer, consumer } = SPSCRing.createPair(128, 8);
+ * worker.postMessage({ buffer, slotCount: 128, slotSize: 8 });
+ *
+ * // In Worker: attach as producer
+ * // const producer = SPSCRing.attachProducer(buffer, 128, 8);
+ * // producer.push(new Float64Array(8));
+ *
+ * // Main thread: consume in animation loop
+ * const out = new Float64Array(8);
+ * function frame() {
+ *   while (consumer.pop(out)) { /* process out *\/ }
+ *   requestAnimationFrame(frame);
+ * }
+ * ```
+ */
+export const SPSCRing = {
+    createPair: _createPair,
+    attachProducer: _attachProducer,
+    attachConsumer: _attachConsumer,
+};
+//# sourceMappingURL=spsc-ring.js.map

package/dist/spsc-ring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spsc-ring.js","sourceRoot":"","sources":["../src/spsc-ring.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@czap/worker",
+  "version": "0.1.0",
+  "description": "Off-thread compositor and render workers",
+  "license": "MIT",
+  "author": "Eassa Ayoub <eassa@heyoub.dev>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heyoub/LiteShip",
+    "directory": "packages/worker"
+  },
+  "bugs": "https://github.com/heyoub/LiteShip/issues",
+  "homepage": "https://github.com/heyoub/LiteShip#readme",
+  "keywords": [
+    "czap",
+    "web-worker",
+    "compositor",
+    "off-main-thread",
+    "spsc-ring",
+    "offscreen-canvas",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "development": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@czap/core": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/compositor-script.ts

@@ -0,0 +1,374 @@
+/**
+ * Inline worker script implementing a simplified compositor.
+ *
+ * This string is turned into a Blob URL at runtime so no separate
+ * worker file is needed. It cannot use ES module imports since it
+ * runs inside a classic Worker created from a Blob.
+ *
+ * @module
+ */
+
+/**
+ * JavaScript source of the inline compositor worker.
+ *
+ * The string is wrapped in a `Blob` at runtime and fed to the
+ * `Worker(url)` constructor, so this package ships without a separate
+ * worker entry file or bundler glue. Keep this source ES5-compatible:
+ * it runs inside a classic Worker and cannot use ES module imports.
+ */
+export const COMPOSITOR_WORKER_SCRIPT = /* js */ `
+"use strict";
+
+// ---------------------------------------------------------------------------
+// Simplified compositor state inside the worker
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, { id: string; states: string[]; thresholds: number[]; currentState: string; currentGeneration: number; cssKey: string|null; glslKey: string|null; ariaKey: string|null; oneHotWeights: Record<string, Record<string, number>>|null; _keysResolved: boolean }>} */
+const quantizers = new Map();
+
+/** @type {Map<string, Record<string, number>>} */
+const blendOverrides = new Map();
+
+/** @type {Set<string>} */
+const dirtyNames = new Set();
+
+const MS_PER_SEC = 1000;
+
+/** @type {number} */
+let lastComputeTime = 0;
+let frameCount = 0;
+let fpsAccum = 0;
+let currentFps = 0;
+
+function removeQuantizer(name) {
+  quantizers.delete(name);
+  blendOverrides.delete(name);
+  dirtyNames.delete(name);
+}
+
+function evaluateQuantizer(name, value) {
+  const q = quantizers.get(name);
+  if (q) {
+    const newState = evaluateThresholds(q.thresholds, q.states, value);
+    if (newState !== q.currentState) {
+      q.currentState = newState;
+      dirtyNames.add(name);
+    }
+  }
+}
+
+function setBlendWeights(name, weights) {
+  blendOverrides.set(name, weights);
+  dirtyNames.add(name);
+}
+
+function applyResolvedStateEntry(entry) {
+  const q = quantizers.get(entry.name);
+  if (!q) {
+    return;
+  }
+
+  const nextGeneration = typeof entry.generation === "number" ? entry.generation : q.currentGeneration;
+  const changed = entry.state !== q.currentState || nextGeneration !== q.currentGeneration;
+  q.currentState = entry.state;
+  q.currentGeneration = nextGeneration;
+  if (changed) {
+    dirtyNames.add(entry.name);
+  }
+}
+
+function applyUpdate(update) {
+  switch (update.type) {
+    case "remove-quantizer":
+      removeQuantizer(update.name);
+      break;
+    case "evaluate":
+      evaluateQuantizer(update.name, update.value);
+      break;
+    case "set-blend":
+      setBlendWeights(update.name, update.weights);
+      break;
+  }
+}
+
+function registerQuantizer(registration) {
+  const initialState =
+    typeof registration.initialState === "string"
+      ? registration.initialState
+      : registration.states[0] || "";
+  const thresholdsRaw = registration.thresholds;
+  const thresholds = thresholdsRaw instanceof Float64Array
+    ? Array.from(thresholdsRaw)
+    : Array.from(thresholdsRaw);
+  quantizers.set(registration.name, {
+    id: registration.boundaryId,
+    states: Array.from(registration.states),
+    thresholds: thresholds,
+    currentState: initialState,
+    currentGeneration: 0,
+    cssKey: null,
+    glslKey: null,
+    ariaKey: null,
+    oneHotWeights: null,
+    _keysResolved: false,
+  });
+  if (registration.blendWeights && typeof registration.blendWeights === "object") {
+    blendOverrides.set(registration.name, registration.blendWeights);
+  } else {
+    blendOverrides.delete(registration.name);
+  }
+  dirtyNames.add(registration.name);
+}
+
+function resolveOutputKeys(q, name) {
+  if (q._keysResolved) return;
+  q.cssKey = "--czap-" + name;
+  q.glslKey = "u_" + name;
+  q.ariaKey = "data-czap-" + name;
+  q.oneHotWeights = Object.fromEntries(
+    q.states.map((activeState) => [
+      activeState,
+      Object.fromEntries(
+        q.states.map((stateName) => [stateName, stateName === activeState ? 1 : 0]),
+      ),
+    ]),
+  );
+  q._keysResolved = true;
+}
+
+function resetWorkerState() {
+  quantizers.clear();
+  blendOverrides.clear();
+  dirtyNames.clear();
+}
+
+/**
+ * Evaluate which discrete state a value falls into based on thresholds.
+ * Thresholds are sorted ascending; the value maps to the state whose
+ * threshold it first exceeds (or the first state if below all thresholds).
+ *
+ * @param {number[]} thresholds
+ * @param {string[]} states
+ * @param {number} value
+ * @returns {string}
+ */
+function evaluateThresholds(thresholds, states, value) {
+  for (let i = thresholds.length - 1; i >= 0; i--) {
+    if (value >= thresholds[i]) {
+      return states[i] || states[0] || "";
+    }
+  }
+  return states[0] || "";
+}
+
+/**
+ * Build a CompositeState from the current quantizer state.
+ * @returns {{ discrete: Record<string, string>; blend: Record<string, Record<string, number>>; outputs: { css: Record<string, number|string>; glsl: Record<string, number>; aria: Record<string, string> } }}
+ */
+function compute() {
+  const now = typeof performance !== "undefined" ? performance.now() : Date.now();
+
+  const discrete = {};
+  const blend = {};
+  const css = {};
+  const glsl = {};
+  const aria = {};
+  const resolvedStateGenerations = {};
+
+  // Only recompute dirty quantizers if we have a dirty set,
+  // otherwise recompute all (initial case or fallback).
+  const names = dirtyNames.size > 0
+    ? Array.from(dirtyNames)
+    : Array.from(quantizers.keys());
+
+  for (const name of names) {
+    const q = quantizers.get(name);
+    if (!q) continue;
+
+    // Lazily resolve output keys on first compute
+    resolveOutputKeys(q, name);
+
+    const stateStr = q.currentState;
+    discrete[name] = stateStr;
+    resolvedStateGenerations[name] = q.currentGeneration;
+
+    // Blend weights
+      const override = blendOverrides.get(name);
+      if (override !== undefined) {
+        blend[name] = override;
+      } else {
+        blend[name] = q.oneHotWeights[stateStr] || {};
+      }
+
+      // CSS output
+      css[q.cssKey] = stateStr;
+
+    // GLSL output: index of current state
+    let stateIndex = 0;
+    for (let i = 0; i < q.states.length; i++) {
+      if (q.states[i] === stateStr) {
+        stateIndex = i;
+        break;
+      }
+    }
+      glsl[q.glslKey] = stateIndex;
+
+      // ARIA output
+      aria[q.ariaKey] = stateStr;
+  }
+
+  dirtyNames.clear();
+
+  // Metrics
+  if (lastComputeTime > 0) {
+    const dt = now - lastComputeTime;
+    frameCount++;
+    fpsAccum += dt;
+    if (fpsAccum >= MS_PER_SEC) {
+      currentFps = Math.round((frameCount * MS_PER_SEC) / fpsAccum);
+      frameCount = 0;
+      fpsAccum -= MS_PER_SEC;
+
+      self.postMessage({
+        type: "metrics",
+        fps: currentFps,
+        budgetUsed: dt,
+      });
+    }
+  }
+  lastComputeTime = now;
+
+  return { discrete, blend, outputs: { css, glsl, aria }, resolvedStateGenerations };
+}
+
+// ---------------------------------------------------------------------------
+// Message handler
+// ---------------------------------------------------------------------------
+
+self.addEventListener("message", function (e) {
+  const msg = e.data;
+  if (!msg || typeof msg.type !== "string") return;
+
+  switch (msg.type) {
+    case "init": {
+      // Reset state on init
+      resetWorkerState();
+      self.postMessage({ type: "ready" });
+      break;
+    }
+
+    case "add-quantizer": {
+      registerQuantizer(msg);
+      break;
+    }
+
+    case "bootstrap-quantizers": {
+      for (const registration of msg.registrations) {
+        registerQuantizer(registration);
+      }
+      break;
+    }
+
+    case "startup-compute": {
+      resetWorkerState();
+      const packet = msg.packet ?? { registrations: [], updates: [] };
+      for (const registration of packet.registrations) {
+        registerQuantizer(registration);
+      }
+      for (const update of packet.updates) {
+        applyUpdate(update);
+      }
+      try {
+        const state = compute();
+        self.postMessage({ type: "state", state: state, resolvedStateGenerations: state.resolvedStateGenerations });
+      } catch (err) {
+        self.postMessage({
+          type: "error",
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+      break;
+    }
+
+    case "bootstrap-resolved-state": {
+      for (const entry of msg.states) {
+        applyResolvedStateEntry(entry);
+      }
+      if (msg.ack === true) {
+        self.postMessage({
+          type: "resolved-state-ack",
+          generation: typeof msg.states[0]?.generation === "number" ? msg.states[0].generation : 0,
+          states: msg.states.map((entry) => ({ name: entry.name, state: entry.state })),
+          additionalOutputsChanged: false,
+        });
+      }
+      break;
+    }
+
+    case "apply-resolved-state": {
+      for (const entry of msg.states) {
+        applyResolvedStateEntry(entry);
+      }
+      if (msg.ack === true) {
+        self.postMessage({
+          type: "resolved-state-ack",
+          generation: typeof msg.states[0]?.generation === "number" ? msg.states[0].generation : 0,
+          states: msg.states.map((entry) => ({ name: entry.name, state: entry.state })),
+          additionalOutputsChanged: false,
+        });
+      }
+      break;
+    }
+
+    case "remove-quantizer": {
+      removeQuantizer(msg.name);
+      break;
+    }
+
+    case "evaluate": {
+      evaluateQuantizer(msg.name, msg.value);
+      break;
+    }
+
+    case "set-blend": {
+      setBlendWeights(msg.name, msg.weights);
+      break;
+    }
+
+    case "apply-updates": {
+      for (const update of msg.updates) {
+        applyUpdate(update);
+      }
+      break;
+    }
+
+    case "warm-reset": {
+      blendOverrides.clear();
+      dirtyNames.clear();
+      for (const quantizer of quantizers.values()) {
+        quantizer.currentState = quantizer.states[0] || "";
+      }
+      break;
+    }
+
+    case "compute": {
+      try {
+        const state = compute();
+        self.postMessage({ type: "state", state: state, resolvedStateGenerations: state.resolvedStateGenerations });
+      } catch (err) {
+        self.postMessage({
+          type: "error",
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+      break;
+    }
+
+    case "dispose": {
+      resetWorkerState();
+      self.close();
+      break;
+    }
+  }
+});
+`;