@czap/worker 0.1.0

package/dist/render-worker.d.ts

@@ -0,0 +1,77 @@
+/**
+ * RenderWorker -- off-main-thread video renderer using OffscreenCanvas.
+ *
+ * The render worker:
+ * 1. Receives an OffscreenCanvas via postMessage transfer
+ * 2. On `start-render`, iterates frames at the configured fps
+ * 3. For each frame, computes state (simplified inline compositor)
+ *    and draws to the OffscreenCanvas 2d context
+ * 4. Posts `frame` messages back with VideoFrameOutput data
+ * 5. Posts `render-complete` when done
+ *
+ * The worker script is inlined as a Blob URL (no separate file needed).
+ *
+ * @module
+ */
+import { type VideoConfig, type VideoFrameOutput } from '@czap/core';
+/**
+ * Host-facing surface of a render worker. Owns the underlying `Worker`
+ * and `OffscreenCanvas` once transferred; created by
+ * {@link RenderWorker.create}.
+ */
+export interface RenderWorkerShape {
+    /** The underlying Worker instance. */
+    readonly worker: Worker;
+    /**
+     * Transfer an OffscreenCanvas to the worker.
+     * The canvas must have been obtained via `canvas.transferControlToOffscreen()`.
+     */
+    transferCanvas(canvas: OffscreenCanvas): void;
+    /** Start rendering frames with the given video configuration. */
+    startRender(config: VideoConfig): void;
+    /** Stop an in-progress render. */
+    stopRender(): void;
+    /** Subscribe to per-frame output. Returns an unsubscribe function. */
+    onFrame(callback: (output: VideoFrameOutput) => void): () => void;
+    /** Subscribe to render completion. Returns an unsubscribe function. */
+    onComplete(callback: (totalFrames: number) => void): () => void;
+    /** Terminate the worker and clean up resources. */
+    dispose(): void;
+}
+declare function _createRenderWorker(): RenderWorkerShape;
+/**
+ * Factory namespace for the render worker.
+ *
+ * Call {@link RenderWorker.create} on the main thread to mint a worker
+ * that owns an `OffscreenCanvas` and renders `VideoFrameOutput` frames
+ * off the main thread. Transfer control via
+ * {@link RenderWorkerShape.transferCanvas} before calling `startRender`.
+ *
+ * @example
+ * ```ts
+ * import { RenderWorker } from '@czap/worker';
+ *
+ * const renderer = RenderWorker.create();
+ * const offscreen = canvas.transferControlToOffscreen();
+ * renderer.transferCanvas(offscreen);
+ * renderer.onFrame((frame) => {
+ *   // stream frame.image / frame.timestampMs somewhere
+ * });
+ * renderer.startRender({ durationMs: 4000, fps: 30, width: 640, height: 360 });
+ * ```
+ */
+export declare const RenderWorker: {
+    /**
+     * Spin up a render worker. The worker starts idle; transfer an
+     * `OffscreenCanvas` via
+     * {@link RenderWorkerShape.transferCanvas} before calling
+     * `startRender`.
+     */
+    readonly create: typeof _createRenderWorker;
+};
+export declare namespace RenderWorker {
+    /** Public host-side surface returned by {@link RenderWorker.create}. */
+    type Shape = RenderWorkerShape;
+}
+export {};
+//# sourceMappingURL=render-worker.d.ts.map

package/dist/render-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-worker.d.ts","sourceRoot":"","sources":["../src/render-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAe,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAQlF;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAE9C,iEAAiE;IACjE,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAEvC,kCAAkC;IAClC,UAAU,IAAI,IAAI,CAAC;IAEnB,sEAAsE;IACtE,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAElE,uEAAuE;IACvE,UAAU,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEhE,mDAAmD;IACnD,OAAO,IAAI,IAAI,CAAC;CACjB;AAqRD,iBAAS,mBAAmB,IAAI,iBAAiB,CAmFhD;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,YAAY;IACvB;;;;;OAKG;;CAEK,CAAC;AAEX,MAAM,CAAC,OAAO,WAAW,YAAY,CAAC;IACpC,wEAAwE;IACxE,KAAY,KAAK,GAAG,iBAAiB,CAAC;CACvC"}

package/dist/render-worker.js

@@ -0,0 +1,396 @@
+/**
+ * RenderWorker -- off-main-thread video renderer using OffscreenCanvas.
+ *
+ * The render worker:
+ * 1. Receives an OffscreenCanvas via postMessage transfer
+ * 2. On `start-render`, iterates frames at the configured fps
+ * 3. For each frame, computes state (simplified inline compositor)
+ *    and draws to the OffscreenCanvas 2d context
+ * 4. Posts `frame` messages back with VideoFrameOutput data
+ * 5. Posts `render-complete` when done
+ *
+ * The worker script is inlined as a Blob URL (no separate file needed).
+ *
+ * @module
+ */
+import { Diagnostics } from '@czap/core';
+import { EVALUATE_THRESHOLDS_SOURCE } from './evaluate-inline.js';
+// ---------------------------------------------------------------------------
+// Inline worker script
+// ---------------------------------------------------------------------------
+/**
+ * Self-contained render worker script.
+ *
+ * Contains a minimal compositor and frame iterator that draws state
+ * visualization to an OffscreenCanvas.
+ */
+const RENDER_WORKER_SCRIPT = /* js */ `
+"use strict";
+
+/** @type {OffscreenCanvas | null} */
+let canvas = null;
+
+/** @type {OffscreenCanvasRenderingContext2D | null} */
+let ctx = null;
+
+/** @type {boolean} */
+let rendering = false;
+
+/** @type {boolean} */
+let stopRequested = false;
+
+// ---------------------------------------------------------------------------
+// Simplified inline compositor (mirrors compositor-worker / Boundary.evaluate)
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, { id: string; states: string[]; thresholds: number[]; currentState: string }>} */
+const quantizers = new Map();
+
+/** @type {Map<string, Record<string, number>>} */
+const blendOverrides = new Map();
+
+${EVALUATE_THRESHOLDS_SOURCE}
+
+/**
+ * Compute a CompositeState from the current quantizer state.
+ */
+function computeState() {
+  const discrete = {};
+  const blend = {};
+  const css = {};
+  const glsl = {};
+  const aria = {};
+
+  for (const [name, q] of quantizers) {
+    const stateStr = q.currentState;
+    discrete[name] = stateStr;
+
+    const override = blendOverrides.get(name);
+    if (override !== undefined) {
+      blend[name] = override;
+    } else {
+      const weights = {};
+      for (const s of q.states) {
+        weights[s] = s === stateStr ? 1 : 0;
+      }
+      blend[name] = weights;
+    }
+
+    css["--czap-" + name] = stateStr;
+
+    let stateIndex = 0;
+    for (let i = 0; i < q.states.length; i++) {
+      if (q.states[i] === stateStr) {
+        stateIndex = i;
+        break;
+      }
+    }
+    glsl["u_" + name] = stateIndex;
+    aria["data-czap-" + name] = stateStr;
+  }
+
+  return { discrete, blend, outputs: { css, glsl, aria } };
+}
+
+// ---------------------------------------------------------------------------
+// Canvas rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Draw the current CompositeState to the OffscreenCanvas.
+ * This is a diagnostic visualization; real applications would
+ * implement domain-specific rendering.
+ *
+ * @param {{ discrete: Record<string, string>; blend: Record<string, Record<string, number>>; outputs: { css: Record<string, number|string>; glsl: Record<string, number>; aria: Record<string, string> } }} state
+ * @param {number} frame
+ * @param {number} progress
+ */
+function drawState(state, frame, progress) {
+  if (!ctx || !canvas) return;
+
+  const w = canvas.width;
+  const h = canvas.height;
+
+  // Clear
+  ctx.clearRect(0, 0, w, h);
+
+  // Background: gradient based on progress
+  const gray = Math.round(32 + progress * 32);
+  ctx.fillStyle = "rgb(" + gray + "," + gray + "," + gray + ")";
+  ctx.fillRect(0, 0, w, h);
+
+  // Draw discrete state labels
+  ctx.fillStyle = "#ffffff";
+  ctx.font = "14px monospace";
+  ctx.textBaseline = "top";
+
+  let y = 16;
+  const keys = Object.keys(state.discrete);
+  for (let i = 0; i < keys.length; i++) {
+    const name = keys[i];
+    const value = state.discrete[name];
+    ctx.fillText(name + ": " + value, 16, y);
+    y += 20;
+  }
+
+  // Draw progress bar
+  const barY = h - 24;
+  const barH = 8;
+  ctx.fillStyle = "#333333";
+  ctx.fillRect(16, barY, w - 32, barH);
+  ctx.fillStyle = "#4488ff";
+  ctx.fillRect(16, barY, (w - 32) * progress, barH);
+
+  // Frame counter
+  ctx.fillStyle = "#aaaaaa";
+  ctx.font = "12px monospace";
+  ctx.textBaseline = "bottom";
+  ctx.fillText("frame " + frame, 16, barY - 4);
+}
+
+// ---------------------------------------------------------------------------
+// Render loop
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the fixed-step render loop.
+ * @param {{ fps: number; width: number; height: number; durationMs: number }} config
+ */
+async function runRender(config) {
+  if (rendering) return;
+  rendering = true;
+  stopRequested = false;
+
+  const totalFrames = Math.ceil((config.durationMs / 1000) * config.fps);
+
+  try {
+    for (let i = 0; i < totalFrames; i++) {
+      if (stopRequested) break;
+
+      const timestamp = (i * 1000) / config.fps;
+      const progress = totalFrames > 1 ? i / (totalFrames - 1) : 1;
+      const state = computeState();
+
+      // Draw to canvas
+      drawState(state, i, progress);
+
+      /** @type {import('./messages.js').VideoFrameOutput} */
+      const output = { frame: i, timestamp, progress, state };
+
+      self.postMessage({ type: "frame", output: output });
+
+      // Yield to allow stop messages to be processed.
+      // In a real scenario, the frame rate would be controlled by
+      // the encoding pipeline; here we use a minimal yield.
+      if (i % 10 === 9) {
+        await new Promise(function (r) { setTimeout(r, 0); });
+      }
+    }
+
+    self.postMessage({ type: "render-complete", totalFrames: totalFrames });
+  } catch (err) {
+    self.postMessage({
+      type: "error",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  } finally {
+    rendering = false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Message handler
+// ---------------------------------------------------------------------------
+
+self.addEventListener("message", function (e) {
+  const msg = e.data;
+  if (!msg || typeof msg.type !== "string") return;
+
+  switch (msg.type) {
+    case "init": {
+      quantizers.clear();
+      blendOverrides.clear();
+      self.postMessage({ type: "ready" });
+      break;
+    }
+
+    case "transfer-canvas": {
+      canvas = msg.canvas;
+      ctx = canvas.getContext("2d");
+      break;
+    }
+
+    case "add-quantizer": {
+      const initialState = msg.states[0] || "";
+      quantizers.set(msg.name, {
+        id: msg.boundaryId,
+        states: Array.from(msg.states),
+        thresholds: Array.from(msg.thresholds),
+        currentState: initialState,
+      });
+      break;
+    }
+
+    case "remove-quantizer": {
+      quantizers.delete(msg.name);
+      blendOverrides.delete(msg.name);
+      break;
+    }
+
+    case "evaluate": {
+      const q = quantizers.get(msg.name);
+      if (q) {
+        q.currentState = evaluateThresholds(q.thresholds, q.states, msg.value);
+      }
+      break;
+    }
+
+    case "set-blend": {
+      blendOverrides.set(msg.name, msg.weights);
+      break;
+    }
+
+    case "start-render": {
+      runRender(msg.config);
+      break;
+    }
+
+    case "stop-render": {
+      stopRequested = true;
+      break;
+    }
+
+    case "dispose": {
+      stopRequested = true;
+      quantizers.clear();
+      blendOverrides.clear();
+      canvas = null;
+      ctx = null;
+      self.close();
+      break;
+    }
+  }
+});
+`;
+// ---------------------------------------------------------------------------
+// Factory helpers
+// ---------------------------------------------------------------------------
+function _send(worker, msg, transfer) {
+    if (transfer && transfer.length > 0) {
+        worker.postMessage(msg, transfer);
+    }
+    else {
+        worker.postMessage(msg);
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+function _createRenderWorker() {
+    const blob = new Blob([RENDER_WORKER_SCRIPT], { type: 'application/javascript' });
+    const url = URL.createObjectURL(blob);
+    const worker = new Worker(url, { type: 'classic', name: 'czap-renderer' });
+    URL.revokeObjectURL(url);
+    const frameListeners = new Set();
+    const completeListeners = new Set();
+    worker.addEventListener('message', (e) => {
+        const msg = e.data;
+        if (!msg || typeof msg.type !== 'string')
+            return;
+        switch (msg.type) {
+            case 'frame':
+                for (const cb of frameListeners)
+                    cb(msg.output);
+                break;
+            case 'render-complete':
+                for (const cb of completeListeners)
+                    cb(msg.totalFrames);
+                break;
+            case 'error':
+                Diagnostics.error({
+                    source: 'czap/worker.render-worker',
+                    code: 'worker-message-error',
+                    message: 'Render worker reported an error.',
+                    detail: msg.message,
+                });
+                break;
+        }
+    });
+    worker.addEventListener('error', (e) => {
+        Diagnostics.error({
+            source: 'czap/worker.render-worker',
+            code: 'worker-unhandled-error',
+            message: 'Render worker raised an unhandled error.',
+            detail: e.message,
+        });
+    });
+    // Initialize
+    _send(worker, { type: 'init' });
+    return {
+        get worker() {
+            return worker;
+        },
+        transferCanvas(canvas) {
+            // The canvas is Transferable -- it must be in the transfer list
+            _send(worker, { type: 'transfer-canvas', canvas }, [canvas]);
+        },
+        startRender(config) {
+            _send(worker, { type: 'start-render', config });
+        },
+        stopRender() {
+            _send(worker, { type: 'stop-render' });
+        },
+        onFrame(callback) {
+            frameListeners.add(callback);
+            return () => {
+                frameListeners.delete(callback);
+            };
+        },
+        onComplete(callback) {
+            completeListeners.add(callback);
+            return () => {
+                completeListeners.delete(callback);
+            };
+        },
+        dispose() {
+            _send(worker, { type: 'dispose' });
+            frameListeners.clear();
+            completeListeners.clear();
+            worker.terminate();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+/**
+ * Factory namespace for the render worker.
+ *
+ * Call {@link RenderWorker.create} on the main thread to mint a worker
+ * that owns an `OffscreenCanvas` and renders `VideoFrameOutput` frames
+ * off the main thread. Transfer control via
+ * {@link RenderWorkerShape.transferCanvas} before calling `startRender`.
+ *
+ * @example
+ * ```ts
+ * import { RenderWorker } from '@czap/worker';
+ *
+ * const renderer = RenderWorker.create();
+ * const offscreen = canvas.transferControlToOffscreen();
+ * renderer.transferCanvas(offscreen);
+ * renderer.onFrame((frame) => {
+ *   // stream frame.image / frame.timestampMs somewhere
+ * });
+ * renderer.startRender({ durationMs: 4000, fps: 30, width: 640, height: 360 });
+ * ```
+ */
+export const RenderWorker = {
+    /**
+     * Spin up a render worker. The worker starts idle; transfer an
+     * `OffscreenCanvas` via
+     * {@link RenderWorkerShape.transferCanvas} before calling
+     * `startRender`.
+     */
+    create: _createRenderWorker,
+};
+//# sourceMappingURL=render-worker.js.map

package/dist/render-worker.js.map

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

package/dist/spsc-ring.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 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
+ */
+/**
+ * Producer- or consumer-side handle to a single-producer/single-consumer
+ * ring buffer backed by `SharedArrayBuffer`. Created by
+ * {@link SPSCRing.attachProducer} or {@link SPSCRing.attachConsumer}.
+ */
+export interface SPSCRingBufferShape {
+    /**
+     * Push a data slot into the ring buffer.
+     * Returns `false` if the buffer is full (non-blocking).
+     */
+    push(data: Float64Array): boolean;
+    /**
+     * Pop a data slot from the ring buffer into the provided output array.
+     * Returns `false` if the buffer is empty (non-blocking).
+     */
+    pop(out: Float64Array): boolean;
+    /** Number of slots in the ring buffer. */
+    readonly capacity: number;
+    /** Current number of occupied slots. */
+    readonly count: number;
+}
+/**
+ * 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
+ */
+declare function _createPair(slotCount: number, slotSize: number): {
+    buffer: SharedArrayBuffer;
+    producer: SPSCRingBufferShape;
+    consumer: SPSCRingBufferShape;
+};
+/**
+ * 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}
+ */
+declare function _attachProducer(sab: SharedArrayBuffer, slotCount: number, slotSize: number): SPSCRingBufferShape;
+/**
+ * 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}
+ */
+declare function _attachConsumer(sab: SharedArrayBuffer, slotCount: number, slotSize: number): SPSCRingBufferShape;
+/**
+ * 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 declare const SPSCRing: {
+    readonly createPair: typeof _createPair;
+    readonly attachProducer: typeof _attachProducer;
+    readonly attachConsumer: typeof _attachConsumer;
+};
+export declare namespace SPSCRing {
+    /** Producer- or consumer-facing view of a SPSC ring buffer. */
+    type Shape = SPSCRingBufferShape;
+}
+export {};
+//# sourceMappingURL=spsc-ring.d.ts.map

package/dist/spsc-ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spsc-ring.d.ts","sourceRoot":"","sources":["../src/spsc-ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAoBH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC;IAElC;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC;IAEhC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAiGD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,WAAW,CAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf;IACD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,mBAAmB,CAAC;CAC/B,CAOA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,eAAe,CAAC,GAAG,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAEzG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iBAAS,eAAe,CAAC,GAAG,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAEzG;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,QAAQ;;;;CAIX,CAAC;AAEX,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC,+DAA+D;IAC/D,KAAY,KAAK,GAAG,mBAAmB,CAAC;CACzC"}