@czap/worker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Eassa Ayoub <eassa@heyoub.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @czap/worker
+
+Off-thread: SPSC ring buffer, compositor worker, render worker, OffscreenCanvas.
+
+## Docs
+
+- [Naming & vocabulary](../../docs/GLOSSARY.md) — LiteShip, CZAP, `@czap/*`
+
+- [API reference](https://github.com/heyoub/LiteShip/tree/main/docs/api/worker/) — generated from source TSDoc
+- [Architecture index](https://github.com/heyoub/LiteShip/blob/main/docs/ARCHITECTURE.md)
+- [ADRs](https://github.com/heyoub/LiteShip/tree/main/docs/adr/)
+
+## Install
+
+```bash
+pnpm add @czap/worker
+```
+
+## Part of [LiteShip](https://github.com/heyoub/LiteShip#readme)

package/dist/compositor-script.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare const COMPOSITOR_WORKER_SCRIPT = "\n\"use strict\";\n\n// ---------------------------------------------------------------------------\n// Simplified compositor state inside the worker\n// ---------------------------------------------------------------------------\n\n/** @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 }>} */\nconst quantizers = new Map();\n\n/** @type {Map<string, Record<string, number>>} */\nconst blendOverrides = new Map();\n\n/** @type {Set<string>} */\nconst dirtyNames = new Set();\n\nconst MS_PER_SEC = 1000;\n\n/** @type {number} */\nlet lastComputeTime = 0;\nlet frameCount = 0;\nlet fpsAccum = 0;\nlet currentFps = 0;\n\nfunction removeQuantizer(name) {\n  quantizers.delete(name);\n  blendOverrides.delete(name);\n  dirtyNames.delete(name);\n}\n\nfunction evaluateQuantizer(name, value) {\n  const q = quantizers.get(name);\n  if (q) {\n    const newState = evaluateThresholds(q.thresholds, q.states, value);\n    if (newState !== q.currentState) {\n      q.currentState = newState;\n      dirtyNames.add(name);\n    }\n  }\n}\n\nfunction setBlendWeights(name, weights) {\n  blendOverrides.set(name, weights);\n  dirtyNames.add(name);\n}\n\nfunction applyResolvedStateEntry(entry) {\n  const q = quantizers.get(entry.name);\n  if (!q) {\n    return;\n  }\n\n  const nextGeneration = typeof entry.generation === \"number\" ? entry.generation : q.currentGeneration;\n  const changed = entry.state !== q.currentState || nextGeneration !== q.currentGeneration;\n  q.currentState = entry.state;\n  q.currentGeneration = nextGeneration;\n  if (changed) {\n    dirtyNames.add(entry.name);\n  }\n}\n\nfunction applyUpdate(update) {\n  switch (update.type) {\n    case \"remove-quantizer\":\n      removeQuantizer(update.name);\n      break;\n    case \"evaluate\":\n      evaluateQuantizer(update.name, update.value);\n      break;\n    case \"set-blend\":\n      setBlendWeights(update.name, update.weights);\n      break;\n  }\n}\n\nfunction registerQuantizer(registration) {\n  const initialState =\n    typeof registration.initialState === \"string\"\n      ? registration.initialState\n      : registration.states[0] || \"\";\n  const thresholdsRaw = registration.thresholds;\n  const thresholds = thresholdsRaw instanceof Float64Array\n    ? Array.from(thresholdsRaw)\n    : Array.from(thresholdsRaw);\n  quantizers.set(registration.name, {\n    id: registration.boundaryId,\n    states: Array.from(registration.states),\n    thresholds: thresholds,\n    currentState: initialState,\n    currentGeneration: 0,\n    cssKey: null,\n    glslKey: null,\n    ariaKey: null,\n    oneHotWeights: null,\n    _keysResolved: false,\n  });\n  if (registration.blendWeights && typeof registration.blendWeights === \"object\") {\n    blendOverrides.set(registration.name, registration.blendWeights);\n  } else {\n    blendOverrides.delete(registration.name);\n  }\n  dirtyNames.add(registration.name);\n}\n\nfunction resolveOutputKeys(q, name) {\n  if (q._keysResolved) return;\n  q.cssKey = \"--czap-\" + name;\n  q.glslKey = \"u_\" + name;\n  q.ariaKey = \"data-czap-\" + name;\n  q.oneHotWeights = Object.fromEntries(\n    q.states.map((activeState) => [\n      activeState,\n      Object.fromEntries(\n        q.states.map((stateName) => [stateName, stateName === activeState ? 1 : 0]),\n      ),\n    ]),\n  );\n  q._keysResolved = true;\n}\n\nfunction resetWorkerState() {\n  quantizers.clear();\n  blendOverrides.clear();\n  dirtyNames.clear();\n}\n\n/**\n * Evaluate which discrete state a value falls into based on thresholds.\n * Thresholds are sorted ascending; the value maps to the state whose\n * threshold it first exceeds (or the first state if below all thresholds).\n *\n * @param {number[]} thresholds\n * @param {string[]} states\n * @param {number} value\n * @returns {string}\n */\nfunction evaluateThresholds(thresholds, states, value) {\n  for (let i = thresholds.length - 1; i >= 0; i--) {\n    if (value >= thresholds[i]) {\n      return states[i] || states[0] || \"\";\n    }\n  }\n  return states[0] || \"\";\n}\n\n/**\n * Build a CompositeState from the current quantizer state.\n * @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> } }}\n */\nfunction compute() {\n  const now = typeof performance !== \"undefined\" ? performance.now() : Date.now();\n\n  const discrete = {};\n  const blend = {};\n  const css = {};\n  const glsl = {};\n  const aria = {};\n  const resolvedStateGenerations = {};\n\n  // Only recompute dirty quantizers if we have a dirty set,\n  // otherwise recompute all (initial case or fallback).\n  const names = dirtyNames.size > 0\n    ? Array.from(dirtyNames)\n    : Array.from(quantizers.keys());\n\n  for (const name of names) {\n    const q = quantizers.get(name);\n    if (!q) continue;\n\n    // Lazily resolve output keys on first compute\n    resolveOutputKeys(q, name);\n\n    const stateStr = q.currentState;\n    discrete[name] = stateStr;\n    resolvedStateGenerations[name] = q.currentGeneration;\n\n    // Blend weights\n      const override = blendOverrides.get(name);\n      if (override !== undefined) {\n        blend[name] = override;\n      } else {\n        blend[name] = q.oneHotWeights[stateStr] || {};\n      }\n\n      // CSS output\n      css[q.cssKey] = stateStr;\n\n    // GLSL output: index of current state\n    let stateIndex = 0;\n    for (let i = 0; i < q.states.length; i++) {\n      if (q.states[i] === stateStr) {\n        stateIndex = i;\n        break;\n      }\n    }\n      glsl[q.glslKey] = stateIndex;\n\n      // ARIA output\n      aria[q.ariaKey] = stateStr;\n  }\n\n  dirtyNames.clear();\n\n  // Metrics\n  if (lastComputeTime > 0) {\n    const dt = now - lastComputeTime;\n    frameCount++;\n    fpsAccum += dt;\n    if (fpsAccum >= MS_PER_SEC) {\n      currentFps = Math.round((frameCount * MS_PER_SEC) / fpsAccum);\n      frameCount = 0;\n      fpsAccum -= MS_PER_SEC;\n\n      self.postMessage({\n        type: \"metrics\",\n        fps: currentFps,\n        budgetUsed: dt,\n      });\n    }\n  }\n  lastComputeTime = now;\n\n  return { discrete, blend, outputs: { css, glsl, aria }, resolvedStateGenerations };\n}\n\n// ---------------------------------------------------------------------------\n// Message handler\n// ---------------------------------------------------------------------------\n\nself.addEventListener(\"message\", function (e) {\n  const msg = e.data;\n  if (!msg || typeof msg.type !== \"string\") return;\n\n  switch (msg.type) {\n    case \"init\": {\n      // Reset state on init\n      resetWorkerState();\n      self.postMessage({ type: \"ready\" });\n      break;\n    }\n\n    case \"add-quantizer\": {\n      registerQuantizer(msg);\n      break;\n    }\n\n    case \"bootstrap-quantizers\": {\n      for (const registration of msg.registrations) {\n        registerQuantizer(registration);\n      }\n      break;\n    }\n\n    case \"startup-compute\": {\n      resetWorkerState();\n      const packet = msg.packet ?? { registrations: [], updates: [] };\n      for (const registration of packet.registrations) {\n        registerQuantizer(registration);\n      }\n      for (const update of packet.updates) {\n        applyUpdate(update);\n      }\n      try {\n        const state = compute();\n        self.postMessage({ type: \"state\", state: state, resolvedStateGenerations: state.resolvedStateGenerations });\n      } catch (err) {\n        self.postMessage({\n          type: \"error\",\n          message: err instanceof Error ? err.message : String(err),\n        });\n      }\n      break;\n    }\n\n    case \"bootstrap-resolved-state\": {\n      for (const entry of msg.states) {\n        applyResolvedStateEntry(entry);\n      }\n      if (msg.ack === true) {\n        self.postMessage({\n          type: \"resolved-state-ack\",\n          generation: typeof msg.states[0]?.generation === \"number\" ? msg.states[0].generation : 0,\n          states: msg.states.map((entry) => ({ name: entry.name, state: entry.state })),\n          additionalOutputsChanged: false,\n        });\n      }\n      break;\n    }\n\n    case \"apply-resolved-state\": {\n      for (const entry of msg.states) {\n        applyResolvedStateEntry(entry);\n      }\n      if (msg.ack === true) {\n        self.postMessage({\n          type: \"resolved-state-ack\",\n          generation: typeof msg.states[0]?.generation === \"number\" ? msg.states[0].generation : 0,\n          states: msg.states.map((entry) => ({ name: entry.name, state: entry.state })),\n          additionalOutputsChanged: false,\n        });\n      }\n      break;\n    }\n\n    case \"remove-quantizer\": {\n      removeQuantizer(msg.name);\n      break;\n    }\n\n    case \"evaluate\": {\n      evaluateQuantizer(msg.name, msg.value);\n      break;\n    }\n\n    case \"set-blend\": {\n      setBlendWeights(msg.name, msg.weights);\n      break;\n    }\n\n    case \"apply-updates\": {\n      for (const update of msg.updates) {\n        applyUpdate(update);\n      }\n      break;\n    }\n\n    case \"warm-reset\": {\n      blendOverrides.clear();\n      dirtyNames.clear();\n      for (const quantizer of quantizers.values()) {\n        quantizer.currentState = quantizer.states[0] || \"\";\n      }\n      break;\n    }\n\n    case \"compute\": {\n      try {\n        const state = compute();\n        self.postMessage({ type: \"state\", state: state, resolvedStateGenerations: state.resolvedStateGenerations });\n      } catch (err) {\n        self.postMessage({\n          type: \"error\",\n          message: err instanceof Error ? err.message : String(err),\n        });\n      }\n      break;\n    }\n\n    case \"dispose\": {\n      resetWorkerState();\n      self.close();\n      break;\n    }\n  }\n});\n";
+//# sourceMappingURL=compositor-script.d.ts.map

package/dist/compositor-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compositor-script.d.ts","sourceRoot":"","sources":["../src/compositor-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,y1TAmWpC,CAAC"}

package/dist/compositor-script.js

@@ -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;
+    }
+  }
+});
+`;
+//# sourceMappingURL=compositor-script.js.map

package/dist/compositor-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compositor-script.js","sourceRoot":"","sources":["../src/compositor-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,QAAQ,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmWhD,CAAC"}

package/dist/compositor-startup.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Startup packet building, startup mode management, and compositor lease
+ * lifecycle helpers for the CompositorWorker module.
+ *
+ * @module
+ */
+import { RuntimeCoordinator } from '@czap/core';
+import type { ToWorkerMessage, WorkerUpdate, BootstrapQuantizerRegistration, StartupComputePacket, ResolvedStateEntry } from './messages.js';
+import type { CompositorWorkerStartupTelemetry, CompositorWorkerStartupDiagnosticStage, ResolvedStateAckPayload, StartupPacketState } from './compositor-types.js';
+/**
+ * Return the current high-resolution wall-clock time in nanoseconds.
+ *
+ * Uses `performance.now()` when available; falls back to `Date.now()`
+ * in environments without the performance timeline.
+ */
+export declare function currentTimeNs(): number;
+/**
+ * Forward a fine-grained startup-diagnostic duration sample to a
+ * telemetry sink (if the sink opts into diagnostic stages).
+ *
+ * Safe to call when `telemetry` is undefined or does not implement
+ * `recordDiagnosticStage` -- the call becomes a no-op.
+ */
+export declare function recordStartupDiagnosticStage(telemetry: CompositorWorkerStartupTelemetry | undefined, stage: CompositorWorkerStartupDiagnosticStage, durationNs: number): void;
+/**
+ * Notify a telemetry sink that the worker acknowledged a resolved-state
+ * hydration. Safe to call when the sink does not implement
+ * `onResolvedStateSettled`.
+ */
+export declare function notifyResolvedStateSettled(telemetry: CompositorWorkerStartupTelemetry | undefined, states: readonly ResolvedStateEntry[]): void;
+/**
+ * Project a set of bootstrap registrations down to the minimal
+ * `{ name, states }` shape the runtime coordinator needs to seed its
+ * quantizer registry.
+ */
+export declare function registrationsToRuntimeSeed(registrations: readonly BootstrapQuantizerRegistration[]): readonly {
+    readonly name: string;
+    readonly states: readonly string[];
+}[];
+/**
+ * Build a fresh {@link StartupPacketState} seeded with an initial
+ * bootstrap mode and registration list. Used by the compositor worker to
+ * stage messages before flushing them in a single `startup-compute` post.
+ */
+export declare function createStartupPacketState(bootstrapMode: StartupComputePacket['bootstrapMode'], initialRegistrations?: readonly BootstrapQuantizerRegistration[]): StartupPacketState;
+/**
+ * Snapshot a {@link StartupPacketState} into an immutable
+ * {@link StartupComputePacket} suitable for `postMessage`.
+ */
+export declare function buildStartupComputePacket(packet: StartupPacketState): StartupComputePacket;
+/**
+ * Return the ordered list of registrations in the startup packet,
+ * caching the result so repeated reads are O(1).
+ */
+export declare function getStartupPacketRegistrations(packet: StartupPacketState): readonly BootstrapQuantizerRegistration[];
+/**
+ * Return the runtime-seed projection of the startup packet's
+ * registrations, recomputing on demand if invalidated.
+ */
+export declare function getStartupPacketRuntimeSeed(packet: StartupPacketState): readonly {
+    readonly name: string;
+    readonly states: readonly string[];
+}[];
+/**
+ * Return `true` when the given runtime coordinator already has every
+ * quantizer referenced by the runtime seed registered (by name).
+ *
+ * Used to decide whether a pre-warmed lease's runtime can be reused
+ * as-is or must be reset before replay.
+ */
+export declare function runtimeMatchesStartupSeed(runtime: RuntimeCoordinator.Shape, runtimeSeed: readonly {
+    readonly name: string;
+    readonly states: readonly string[];
+}[]): boolean;
+/**
+ * Insert or overwrite a registration in the startup packet, invalidating
+ * derived caches. Pass `invalidateRuntimeSeed: false` when the caller
+ * already knows the runtime seed is structurally unchanged (e.g. only
+ * initial state or blend weights changed).
+ */
+export declare function setStartupPacketRegistration(packet: StartupPacketState, registration: BootstrapQuantizerRegistration, invalidateRuntimeSeed?: boolean): void;
+/**
+ * Drop a registration by name from the startup packet and invalidate
+ * derived caches.
+ */
+export declare function removeStartupPacketRegistration(packet: StartupPacketState, name: string): void;
+/**
+ * Queue a {@link WorkerUpdate} to be replayed after bootstrap. Order is
+ * preserved to match main-thread issue order.
+ */
+export declare function pushStartupPacketUpdate(packet: StartupPacketState, update: WorkerUpdate): void;
+/**
+ * Filter the packet's pending update queue in-place. Typically used to
+ * drop redundant updates (e.g. newer `set-blend` supersedes older ones).
+ */
+export declare function filterStartupPacketUpdates(packet: StartupPacketState, keep: (update: WorkerUpdate) => boolean): void;
+/**
+ * Structural equality check for `Record<string, number>` blend-weight
+ * maps. `undefined === undefined` is true; mismatched presence is false.
+ */
+export declare function sameNumericRecord(left: Record<string, number> | undefined, right: Record<string, number> | undefined): boolean;
+/**
+ * Merge an updated initial-state assignment into an existing registration.
+ * Also scrubs any queued `evaluate` update targeting the same quantizer,
+ * since the new initial state supersedes it.
+ */
+export declare function setStartupPacketInitialState(packet: StartupPacketState, registration: BootstrapQuantizerRegistration, state: string): void;
+/**
+ * Merge updated blend weights for an existing registration. Returns
+ * `false` when no registration with that name is present (the update is
+ * ignored). Scrubs superseded `set-blend` updates from the queue.
+ */
+export declare function setStartupPacketBlendWeights(packet: StartupPacketState, name: string, weights: Record<string, number>): boolean;
+/**
+ * Remove a registration and every pending update targeting it.
+ * Equivalent to undoing `add-quantizer` + any in-flight mutations.
+ */
+export declare function removeStartupPacketEntries(packet: StartupPacketState, name: string): void;
+/**
+ * Clear all transient state on a startup packet, leaving only the
+ * `bootstrapMode` in place. Used when the lease is recycled and the
+ * caller wants to start accumulating fresh messages.
+ */
+export declare function resetStartupPacketTransientState(packet: StartupPacketState): void;
+/**
+ * Claim a compositor lease: either hand back the standby pre-warmed
+ * worker (if one is parked and matches the requested capacity) or mint a
+ * fresh `Worker` + {@link RuntimeCoordinator}. Emits
+ * `claim-or-create` and `coordinator-reset-or-create` stage samples to
+ * the optional telemetry sink.
+ *
+ * @param capacity - Runtime coordinator capacity to request.
+ * @param startupTelemetry - Optional sink for stage timings.
+ * @returns The worker, its coordinator, and any bootstrap snapshot the
+ *   parked lease brought with it.
+ */
+export declare function claimCompositorLease(capacity: number, startupTelemetry?: CompositorWorkerStartupTelemetry): {
+    readonly worker: Worker;
+    readonly runtime: RuntimeCoordinator.Shape;
+    readonly bootstrapSnapshot: readonly BootstrapQuantizerRegistration[];
+};
+/**
+ * Park a compositor lease in the module-level standby slot so a future
+ * {@link claimCompositorLease} can reuse it. If the standby slot is
+ * already occupied, the incoming lease is disposed (`dispose` message +
+ * `terminate()`) instead.
+ */
+export declare function parkOrDisposeCompositorLease(lease: {
+    readonly worker: Worker;
+    readonly runtime: RuntimeCoordinator.Shape;
+    readonly capacity: number;
+    readonly bootstrapSnapshot: readonly BootstrapQuantizerRegistration[];
+}): void;
+/**
+ * Internal `postMessage` helper with an explicit transfer-list default.
+ * Named with a leading underscore to signal that host code should use
+ * the typed methods on {@link CompositorWorkerShape} instead.
+ */
+export declare function _send(worker: Worker, msg: ToWorkerMessage, transfer?: Transferable[]): void;
+/**
+ * Convert a registration's thresholds to a Float64Array for transfer.
+ * Returns a new registration object with the typed array and the ArrayBuffer to transfer.
+ */
+export declare function prepareRegistrationForTransfer(registration: BootstrapQuantizerRegistration): {
+    registration: BootstrapQuantizerRegistration;
+    buffer: ArrayBuffer;
+};
+/**
+ * Prepare a list of registrations for transfer, returning new registrations
+ * and the collected ArrayBuffers to include in the transfer list.
+ */
+export declare function prepareRegistrationsForTransfer(registrations: readonly BootstrapQuantizerRegistration[]): {
+    registrations: readonly BootstrapQuantizerRegistration[];
+    buffers: ArrayBuffer[];
+};
+/**
+ * Structural equality for two `ArrayLike` sequences (same length, same
+ * `===` elements at every index). Works for both plain arrays and typed
+ * arrays.
+ */
+export declare function sameArray<T>(left: ArrayLike<T>, right: ArrayLike<T>): boolean;
+/**
+ * Return `true` when two bootstrap registrations share the same
+ * `boundaryId`, state list, and threshold list. Used to elide redundant
+ * `add-quantizer` messages during bootstrap coalescing.
+ */
+export declare function sameBootstrapRegistration(left: BootstrapQuantizerRegistration | undefined, right: BootstrapQuantizerRegistration): boolean;
+/**
+ * Quantize a numeric value against a registration's thresholds and
+ * return the corresponding state label. Falls back to `states[0]` if the
+ * value lies below every threshold.
+ */
+export declare function evaluateRegistrationState(registration: BootstrapQuantizerRegistration, value: number): string;
+/**
+ * Re-shape a {@link ResolvedStateAckPayload} into the flat
+ * {@link ResolvedStateEntry} form that the main-thread state store
+ * consumes. Propagates `ack.generation` into each entry.
+ */
+export declare function toResolvedStateEntriesFromAck(ack: ResolvedStateAckPayload): readonly ResolvedStateEntry[];
+//# sourceMappingURL=compositor-startup.d.ts.map

package/dist/compositor-startup.d.ts.map

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