@czap/worker 0.1.0

package/dist/compositor-startup.js

@@ -0,0 +1,490 @@
+/**
+ * Startup packet building, startup mode management, and compositor lease
+ * lifecycle helpers for the CompositorWorker module.
+ *
+ * @module
+ */
+import { RuntimeCoordinator } from '@czap/core';
+import { COMPOSITOR_WORKER_SCRIPT } from './compositor-script.js';
+// ---------------------------------------------------------------------------
+// Module-level cached state
+// ---------------------------------------------------------------------------
+let cachedCompositorWorkerUrl = null;
+let cachedCreateObjectUrl = null;
+let cleanupRegistered = false;
+let standbyCompositorLease = null;
+// ---------------------------------------------------------------------------
+// Timing helpers
+// ---------------------------------------------------------------------------
+/**
+ * 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 function currentTimeNs() {
+    const currentTimeMs = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    return currentTimeMs * 1e6;
+}
+/**
+ * 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 function recordStartupDiagnosticStage(telemetry, stage, durationNs) {
+    const recordDiagnosticStage = telemetry?.recordDiagnosticStage;
+    recordDiagnosticStage?.(stage, durationNs);
+}
+/**
+ * Notify a telemetry sink that the worker acknowledged a resolved-state
+ * hydration. Safe to call when the sink does not implement
+ * `onResolvedStateSettled`.
+ */
+export function notifyResolvedStateSettled(telemetry, states) {
+    const onResolvedStateSettled = telemetry?.onResolvedStateSettled;
+    onResolvedStateSettled?.(states);
+}
+// ---------------------------------------------------------------------------
+// Startup packet state management
+// ---------------------------------------------------------------------------
+/**
+ * Project a set of bootstrap registrations down to the minimal
+ * `{ name, states }` shape the runtime coordinator needs to seed its
+ * quantizer registry.
+ */
+export function registrationsToRuntimeSeed(registrations) {
+    return registrations.map((registration) => ({
+        name: registration.name,
+        states: registration.states,
+    }));
+}
+/**
+ * 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 function createStartupPacketState(bootstrapMode, initialRegistrations = []) {
+    return {
+        bootstrapMode,
+        registrations: new Map(initialRegistrations.map((registration) => [registration.name, registration])),
+        registrationList: initialRegistrations.length > 0 ? [...initialRegistrations] : [],
+        runtimeSeedList: initialRegistrations.length > 0 ? registrationsToRuntimeSeed(initialRegistrations) : [],
+        updates: [],
+        runtimeSeedDirty: false,
+    };
+}
+/**
+ * Snapshot a {@link StartupPacketState} into an immutable
+ * {@link StartupComputePacket} suitable for `postMessage`.
+ */
+export function buildStartupComputePacket(packet) {
+    const builtPacket = {
+        bootstrapMode: packet.bootstrapMode,
+        registrations: getStartupPacketRegistrations(packet),
+        updates: packet.updates,
+    };
+    return builtPacket;
+}
+/**
+ * Return the ordered list of registrations in the startup packet,
+ * caching the result so repeated reads are O(1).
+ */
+export function getStartupPacketRegistrations(packet) {
+    if (packet.registrationList !== null) {
+        return packet.registrationList;
+    }
+    packet.registrationList = Array.from(packet.registrations.values());
+    return packet.registrationList;
+}
+/**
+ * Return the runtime-seed projection of the startup packet's
+ * registrations, recomputing on demand if invalidated.
+ */
+export function getStartupPacketRuntimeSeed(packet) {
+    if (packet.runtimeSeedList !== null && !packet.runtimeSeedDirty) {
+        return packet.runtimeSeedList;
+    }
+    packet.runtimeSeedList = registrationsToRuntimeSeed(getStartupPacketRegistrations(packet));
+    packet.runtimeSeedDirty = false;
+    return packet.runtimeSeedList;
+}
+/**
+ * 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 function runtimeMatchesStartupSeed(runtime, runtimeSeed) {
+    const registeredNames = runtime.registeredNames();
+    if (!sameArray(registeredNames, runtimeSeed.map((registration) => registration.name))) {
+        return false;
+    }
+    for (const registration of runtimeSeed) {
+        if (!runtime.hasQuantizer(registration.name)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 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 function setStartupPacketRegistration(packet, registration, invalidateRuntimeSeed = true) {
+    packet.registrations.set(registration.name, registration);
+    packet.registrationList = null;
+    if (invalidateRuntimeSeed) {
+        packet.runtimeSeedList = null;
+        packet.runtimeSeedDirty = true;
+    }
+}
+/**
+ * Drop a registration by name from the startup packet and invalidate
+ * derived caches.
+ */
+export function removeStartupPacketRegistration(packet, name) {
+    packet.registrations.delete(name);
+    packet.registrationList = null;
+    packet.runtimeSeedList = null;
+    packet.runtimeSeedDirty = true;
+}
+/**
+ * Queue a {@link WorkerUpdate} to be replayed after bootstrap. Order is
+ * preserved to match main-thread issue order.
+ */
+export function pushStartupPacketUpdate(packet, update) {
+    packet.updates.push(update);
+}
+/**
+ * Filter the packet's pending update queue in-place. Typically used to
+ * drop redundant updates (e.g. newer `set-blend` supersedes older ones).
+ */
+export function filterStartupPacketUpdates(packet, keep) {
+    if (packet.updates.length === 0) {
+        return;
+    }
+    const filtered = packet.updates.filter(keep);
+    if (filtered.length !== packet.updates.length) {
+        packet.updates = filtered;
+    }
+}
+/**
+ * Structural equality check for `Record<string, number>` blend-weight
+ * maps. `undefined === undefined` is true; mismatched presence is false.
+ */
+export function sameNumericRecord(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (!left || !right) {
+        return left === right;
+    }
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    if (leftKeys.length !== rightKeys.length) {
+        return false;
+    }
+    for (const key of leftKeys) {
+        if (left[key] !== right[key]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 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 function setStartupPacketInitialState(packet, registration, state) {
+    const currentRegistration = packet.registrations.get(registration.name);
+    const defaultState = currentRegistration.states[0];
+    const nextRegistration = state === defaultState
+        ? (() => {
+            const { initialState: _initialState, ...withoutInitialState } = currentRegistration;
+            return withoutInitialState;
+        })()
+        : { ...currentRegistration, initialState: state };
+    const nextInitialState = 'initialState' in nextRegistration ? nextRegistration.initialState : undefined;
+    if (currentRegistration.boundaryId !== nextRegistration.boundaryId ||
+        !sameArray(currentRegistration.states, nextRegistration.states) ||
+        !sameArray(currentRegistration.thresholds, nextRegistration.thresholds) ||
+        currentRegistration.initialState !== nextInitialState ||
+        !sameNumericRecord(currentRegistration.blendWeights, nextRegistration.blendWeights)) {
+        setStartupPacketRegistration(packet, nextRegistration, false);
+    }
+    filterStartupPacketUpdates(packet, (update) => !(update.type === 'evaluate' && update.name === registration.name));
+}
+/**
+ * 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 function setStartupPacketBlendWeights(packet, name, weights) {
+    const registration = packet.registrations.get(name);
+    if (!registration) {
+        return false;
+    }
+    if (!sameNumericRecord(registration.blendWeights, weights)) {
+        setStartupPacketRegistration(packet, {
+            ...registration,
+            blendWeights: weights,
+        }, false);
+    }
+    filterStartupPacketUpdates(packet, (update) => !(update.type === 'set-blend' && update.name === name));
+    return true;
+}
+/**
+ * Remove a registration and every pending update targeting it.
+ * Equivalent to undoing `add-quantizer` + any in-flight mutations.
+ */
+export function removeStartupPacketEntries(packet, name) {
+    removeStartupPacketRegistration(packet, name);
+    if (packet.updates.length === 0) {
+        return;
+    }
+    const filtered = packet.updates.filter((update) => update.name !== name);
+    if (filtered.length !== packet.updates.length) {
+        packet.updates = filtered;
+    }
+}
+/**
+ * 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 function resetStartupPacketTransientState(packet) {
+    packet.registrations.clear();
+    packet.registrationList = [];
+    packet.runtimeSeedList = [];
+    packet.updates = [];
+    packet.runtimeSeedDirty = false;
+}
+// ---------------------------------------------------------------------------
+// Compositor worker URL and blob management
+// ---------------------------------------------------------------------------
+function revokeCachedCompositorWorkerUrl() {
+    if (!cachedCompositorWorkerUrl) {
+        return;
+    }
+    URL.revokeObjectURL(cachedCompositorWorkerUrl);
+    cachedCompositorWorkerUrl = null;
+    cachedCreateObjectUrl = null;
+}
+function disposeStandbyCompositorLease() {
+    standbyCompositorLease?.worker.terminate();
+    standbyCompositorLease = null;
+}
+/** Typed helper that extracts globalThis.process without casting at call sites. */
+function getNodeProcess() {
+    /* v8 ignore next — `globalThis` is available in every ES2020+ host (Node, browsers,
+       workers). The guard is defense-in-depth in case the module is ever loaded in a
+       pre-ES2020 sandbox where `globalThis` is missing. */
+    if (typeof globalThis === 'undefined' || !('process' in globalThis))
+        return null;
+    const p = globalThis.process;
+    /* v8 ignore next — Node's `process` is always the NodeJS.Process object; this guard
+       covers hosts that define `process` as a non-object (e.g. a compatibility shim that
+       sets it to `undefined` while still keeping the property slot). */
+    if (typeof p !== 'object' || p === null)
+        return null;
+    return p;
+}
+function registerCachedWorkerCleanup() {
+    if (cleanupRegistered) {
+        return;
+    }
+    cleanupRegistered = true;
+    const cleanup = () => {
+        disposeStandbyCompositorLease();
+        revokeCachedCompositorWorkerUrl();
+    };
+    if (typeof globalThis.addEventListener === 'function') {
+        globalThis.addEventListener('pagehide', cleanup, { once: true });
+        return;
+    }
+    const proc = getNodeProcess();
+    if (proc !== null && typeof proc.once === 'function')
+        proc.once('exit', cleanup);
+}
+function getCompositorWorkerUrl() {
+    if (cachedCompositorWorkerUrl && cachedCreateObjectUrl === URL.createObjectURL) {
+        return cachedCompositorWorkerUrl;
+    }
+    if (cachedCompositorWorkerUrl) {
+        revokeCachedCompositorWorkerUrl();
+    }
+    cachedCompositorWorkerUrl = URL.createObjectURL(new Blob([COMPOSITOR_WORKER_SCRIPT], { type: 'application/javascript' }));
+    cachedCreateObjectUrl = URL.createObjectURL;
+    registerCachedWorkerCleanup();
+    return cachedCompositorWorkerUrl;
+}
+function createRawCompositorWorker() {
+    const url = getCompositorWorkerUrl();
+    return new Worker(url, { type: 'classic', name: 'czap-compositor' });
+}
+function createRuntimeCoordinator(capacity) {
+    return RuntimeCoordinator.create({
+        capacity,
+        name: 'czap-worker-runtime',
+    });
+}
+// ---------------------------------------------------------------------------
+// Compositor lease lifecycle
+// ---------------------------------------------------------------------------
+/**
+ * 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 function claimCompositorLease(capacity, startupTelemetry) {
+    if (standbyCompositorLease &&
+        (standbyCompositorLease.workerConstructor !== Worker ||
+            standbyCompositorLease.createObjectUrl !== URL.createObjectURL ||
+            standbyCompositorLease.capacity !== capacity)) {
+        disposeStandbyCompositorLease();
+    }
+    const claimStartNs = currentTimeNs();
+    const claimedLease = standbyCompositorLease;
+    standbyCompositorLease = null;
+    const worker = claimedLease?.worker ?? createRawCompositorWorker();
+    startupTelemetry?.recordStage('claim-or-create', currentTimeNs() - claimStartNs);
+    const coordinatorStartNs = currentTimeNs();
+    const runtime = claimedLease?.runtime ?? createRuntimeCoordinator(capacity);
+    const bootstrapSnapshot = claimedLease?.bootstrapSnapshot ?? [];
+    if (claimedLease) {
+        const runtimeResetStartNs = currentTimeNs();
+        runtime.reset();
+        recordStartupDiagnosticStage(startupTelemetry, 'coordinator-reset-or-create:runtime-reset-reuse', currentTimeNs() - runtimeResetStartNs);
+    }
+    startupTelemetry?.recordStage('coordinator-reset-or-create', currentTimeNs() - coordinatorStartNs);
+    return {
+        worker,
+        runtime,
+        bootstrapSnapshot,
+    };
+}
+/**
+ * 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 function parkOrDisposeCompositorLease(lease) {
+    if (!standbyCompositorLease &&
+        typeof Worker !== 'undefined' &&
+        Worker === lease.worker.constructor &&
+        typeof URL.createObjectURL === 'function' &&
+        URL.createObjectURL === cachedCreateObjectUrl) {
+        standbyCompositorLease = {
+            ...lease,
+            workerConstructor: Worker,
+            createObjectUrl: URL.createObjectURL,
+        };
+        return;
+    }
+    _send(lease.worker, { type: 'dispose' });
+    lease.worker.terminate();
+}
+// ---------------------------------------------------------------------------
+// Utility helpers
+// ---------------------------------------------------------------------------
+/**
+ * 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 function _send(worker, msg, transfer) {
+    worker.postMessage(msg, transfer ?? []);
+}
+/**
+ * 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 function prepareRegistrationForTransfer(registration) {
+    const f64 = new Float64Array(registration.thresholds);
+    return {
+        registration: { ...registration, thresholds: f64 },
+        buffer: f64.buffer,
+    };
+}
+/**
+ * Prepare a list of registrations for transfer, returning new registrations
+ * and the collected ArrayBuffers to include in the transfer list.
+ */
+export function prepareRegistrationsForTransfer(registrations) {
+    const buffers = [];
+    const prepared = registrations.map((reg) => {
+        const { registration, buffer } = prepareRegistrationForTransfer(reg);
+        buffers.push(buffer);
+        return registration;
+    });
+    return { registrations: prepared, buffers };
+}
+/**
+ * Structural equality for two `ArrayLike` sequences (same length, same
+ * `===` elements at every index). Works for both plain arrays and typed
+ * arrays.
+ */
+export function sameArray(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    for (let index = 0; index < left.length; index++) {
+        if (left[index] !== right[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 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 function sameBootstrapRegistration(left, right) {
+    if (!left) {
+        return false;
+    }
+    return (left.boundaryId === right.boundaryId &&
+        sameArray(left.states, right.states) &&
+        sameArray(left.thresholds, right.thresholds));
+}
+/**
+ * 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 function evaluateRegistrationState(registration, value) {
+    for (let index = registration.thresholds.length - 1; index >= 0; index--) {
+        if (value >= registration.thresholds[index]) {
+            return registration.states[index] ?? registration.states[0];
+        }
+    }
+    return registration.states[0];
+}
+/**
+ * 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 function toResolvedStateEntriesFromAck(ack) {
+    return ack.states.map((state) => ({
+        name: state.name,
+        state: state.state,
+        generation: ack.generation,
+    }));
+}
+//# sourceMappingURL=compositor-startup.js.map

package/dist/compositor-startup.js.map

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

package/dist/compositor-types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Type definitions for the CompositorWorker module.
+ *
+ * @module
+ */
+import type { RuntimeCoordinator, CompositeState } from '@czap/core';
+import type { WorkerUpdate, BootstrapQuantizerRegistration, StartupComputePacket, ResolvedStateEntry } from './messages.js';
+/**
+ * A `CompositeState` snapshot emitted by the compositor worker, optionally
+ * annotated with per-quantizer generation counters. The generation map
+ * enables receivers to drop stale out-of-order messages.
+ */
+export type CompositorWorkerState = CompositeState & {
+    readonly resolvedStateGenerations?: Record<string, number>;
+};
+/**
+ * Acknowledgement payload emitted by the worker after it applies a
+ * resolved-state update from the main thread.
+ */
+export interface ResolvedStateAckPayload {
+    /** Generation counter the worker acknowledges. */
+    readonly generation: number;
+    /** The state transitions the worker actually observed. */
+    readonly states: readonly {
+        readonly name: string;
+        readonly state: string;
+    }[];
+    /** Whether non-discrete outputs (blend, CSS, etc.) changed in this round. */
+    readonly additionalOutputsChanged: boolean;
+}
+/**
+ * Host-facing surface of a compositor worker. Returned by
+ * {@link CompositorWorker} as the public control/observation API. Owns
+ * the underlying `Worker` -- call {@link CompositorWorkerShape.dispose}
+ * to terminate and release resources.
+ */
+export interface CompositorWorkerShape {
+    /** The underlying Worker instance. */
+    readonly worker: Worker;
+    /** Shared runtime coordination surface reflecting host-side worker state. */
+    readonly runtime: RuntimeCoordinator.Shape;
+    /** Register a quantizer in the worker. */
+    addQuantizer(name: string, boundary: {
+        readonly id: string;
+        readonly states: readonly string[];
+        readonly thresholds: readonly number[];
+    }): void;
+    /** Remove a quantizer from the worker. */
+    removeQuantizer(name: string): void;
+    /** Evaluate a quantizer with a numeric value (threshold-based). */
+    evaluate(name: string, value: number): void;
+    /** Override blend weights for a quantizer. */
+    setBlendWeights(name: string, weights: Record<string, number>): void;
+    /** Seed resolved quantizer state into the worker without raw threshold evaluation. */
+    bootstrapResolvedState(states: readonly ResolvedStateEntry[]): void;
+    /** Mirror resolved quantizer state updates into the worker without raw threshold evaluation. */
+    applyResolvedState(states: readonly ResolvedStateEntry[]): void;
+    /** Request the worker to compute and return a CompositeState. */
+    requestCompute(): void;
+    /** Subscribe to state updates from the worker. Returns an unsubscribe function. */
+    onState(callback: (state: CompositorWorkerState) => void): () => void;
+    /** Subscribe to resolved-state acknowledgement updates. Returns an unsubscribe function. */
+    onResolvedStateAck(callback: (ack: ResolvedStateAckPayload) => void): () => void;
+    /** Subscribe to metrics updates. Returns an unsubscribe function. */
+    onMetrics(callback: (fps: number, budgetUsed: number) => void): () => void;
+    /** Terminate the worker and clean up resources. */
+    dispose(): void;
+}
+/**
+ * Named stages of the compositor-worker startup handshake. Used for
+ * structured telemetry so hosts can instrument how long each phase took.
+ */
+export type CompositorWorkerStartupStage = 'claim-or-create' | 'coordinator-reset-or-create' | 'listener-bind';
+/**
+ * Pluggable telemetry sink invoked during compositor-worker startup.
+ * `recordStage` is called once per stage with an elapsed-time sample;
+ * `onResolvedStateSettled` (optional) fires once the worker confirms a
+ * resolved-state hydration.
+ */
+export interface CompositorWorkerStartupTelemetry {
+    /** Record how long a startup stage took. `durationNs` is in nanoseconds. */
+    recordStage(stage: CompositorWorkerStartupStage, durationNs: number): void;
+    /** Fired when the worker acknowledges the resolved-state bootstrap. */
+    onResolvedStateSettled?(states: readonly ResolvedStateEntry[]): void;
+}
+/**
+ * Finer-grained diagnostic stages emitted during startup and compute
+ * dispatch. Useful for pinpointing message-queue / callback latency in
+ * profiling builds.
+ */
+export type CompositorWorkerStartupDiagnosticStage = 'coordinator-reset-or-create:runtime-reset-reuse' | 'request-compute:packet-finalize' | 'request-compute:dispatch-send' | 'request-compute:post-send-bookkeeping' | 'state-delivery:message-receipt' | 'state-delivery:callback-queue-turn' | 'state-delivery:host-callback-delivery';
+/**
+ * A pre-warmed compositor worker held in a standby pool, ready to be
+ * claimed by a new host without paying the Worker+Blob-URL boot cost.
+ *
+ * The lease exposes both the raw `Worker` and its associated coordinator,
+ * plus the constructors used to mint more workers if the pool is empty.
+ */
+export interface StandbyCompositorLease {
+    /** The warm Worker instance. */
+    readonly worker: Worker;
+    /** Shared runtime coordinator already attached to the worker. */
+    readonly runtime: RuntimeCoordinator.Shape;
+    /** Pooled pool capacity advertised by the lease. */
+    readonly capacity: number;
+    /** Worker constructor used to mint peers. */
+    readonly workerConstructor: typeof Worker;
+    /** Blob URL factory used to mint worker sources. */
+    readonly createObjectUrl: typeof URL.createObjectURL;
+    /** Previously-bootstrapped registrations the lease already knows about. */
+    readonly bootstrapSnapshot: readonly BootstrapQuantizerRegistration[];
+}
+/**
+ * Mutable scratch state used while coalescing startup messages into a
+ * single {@link StartupComputePacket}. Internal to the startup pipeline;
+ * exported for tests and host-side diagnostic inspectors.
+ */
+export interface StartupPacketState {
+    /** The bootstrap mode the packet will advertise. */
+    bootstrapMode: StartupComputePacket['bootstrapMode'];
+    /** Deduplicated registrations keyed by quantizer name. */
+    registrations: Map<string, BootstrapQuantizerRegistration>;
+    /** Cached ordered registration list (invalidated when the map mutates). */
+    registrationList: readonly BootstrapQuantizerRegistration[] | null;
+    /** Cached runtime seed list derived from registrations. */
+    runtimeSeedList: readonly {
+        readonly name: string;
+        readonly states: readonly string[];
+    }[] | null;
+    /** Pending updates to replay after bootstrap. */
+    updates: WorkerUpdate[];
+    /** Whether `runtimeSeedList` needs to be recomputed. */
+    runtimeSeedDirty: boolean;
+}
+//# sourceMappingURL=compositor-types.d.ts.map

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

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

package/dist/compositor-types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the CompositorWorker module.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=compositor-types.js.map

package/dist/compositor-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compositor-types.js","sourceRoot":"","sources":["../src/compositor-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}