@aelionsdk/renderer-worker 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FoyonaCZY and AelionSDK contributors
+
+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,7 @@
+# @aelionsdk/renderer-worker
+
+Off-main-thread WebGL2 and WebGPU compositor for AelionSDK
+
+Install with `npm install @aelionsdk/renderer-worker@next`.
+
+Version 0.1.0-beta.1 is a prerelease and its API may change before the first stable release. This package is part of [AelionSDK](https://github.com/FoyonaCZY/AelionSDK); see the repository README for supported browsers, examples and deployment requirements.

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+import { type Disposable } from '@aelionsdk/core';
+import type { JsonValue } from '@aelionsdk/core';
+import type { WebGl2MaterialProgram } from '@aelionsdk/material-compiler';
+import type { ComposeSuccess, FrameGraphNode } from './protocol.js';
+export interface ComposeOptions {
+    readonly inputs: Readonly<Record<string, VideoFrame>>;
+    readonly program: WebGl2MaterialProgram;
+    readonly parameters?: Readonly<Record<string, JsonValue>>;
+    readonly systems?: Readonly<Record<string, number>>;
+    readonly width: number;
+    readonly height: number;
+    readonly preferredBackend?: 'webgpu' | 'webgl2';
+    readonly allowFallback?: boolean;
+    readonly signal?: AbortSignal;
+    /** @internal Used only by backend loss conformance tests. */
+    readonly debugSimulateLoss?: 'webgpu-device' | 'webgl2-context';
+}
+export interface ComposeFrameGraphOptions {
+    readonly inputs: Readonly<Record<string, VideoFrame>>;
+    readonly nodes: readonly FrameGraphNode[];
+    readonly outputNodeId: string;
+    readonly width: number;
+    readonly height: number;
+    readonly preferredBackend?: 'webgpu' | 'webgl2';
+    readonly allowFallback?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface WorkerCompositorSnapshot {
+    readonly disposed: boolean;
+    /** All client-admitted requests awaiting a terminal Worker response. */
+    readonly pendingRequests: number;
+    /** Admitted requests that have not been cancelled by their caller. */
+    readonly activeRequests: number;
+    /** Cancellation tombstones retained until the Worker acknowledges cleanup. */
+    readonly cancelledRequests: number;
+    readonly maxPendingRequests: number;
+}
+export interface WorkerCompositorOptions {
+    readonly maxPendingRequests?: number;
+    /** Host-resolved Worker URL for standard ESM/CDN deployments. */
+    readonly workerUrl?: string | URL;
+    /** Advanced host integration and deterministic tests. */
+    readonly workerFactory?: () => Worker;
+}
+export declare class WorkerCompositor implements Disposable {
+    #private;
+    constructor(options?: WorkerCompositorOptions);
+    get disposed(): boolean;
+    snapshot(): WorkerCompositorSnapshot;
+    compose(options: ComposeOptions): Promise<ComposeSuccess>;
+    composeFrameGraph(options: ComposeFrameGraphOptions): Promise<ComposeSuccess>;
+    dispose(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE1E,OAAO,KAAK,EAIV,cAAc,EACd,cAAc,EAEf,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,eAAe,GAAG,gBAAgB,CAAC;CACjE;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAClC,yDAAyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;CACvC;AA2BD,qBAAa,gBAAiB,YAAW,UAAU;;gBAO9B,OAAO,GAAE,uBAA4B;IAgBxD,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAEM,QAAQ,IAAI,wBAAwB;IAgBpC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IA2EzD,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC;IAqE7E,OAAO,IAAI,IAAI;CA+DvB"}

package/dist/client.js

@@ -0,0 +1,264 @@
+import { AelionError } from '@aelionsdk/core';
+function failureError(response) {
+    return new AelionError([
+        {
+            code: response.code,
+            severity: 'error',
+            message: response.message,
+            recoverable: true,
+        },
+    ]);
+}
+export class WorkerCompositor {
+    #worker;
+    #pending = new Map();
+    #nextId = 1;
+    #disposed = false;
+    #maxPendingRequests;
+    constructor(options = {}) {
+        const maxPendingRequests = options.maxPendingRequests ?? 8;
+        if (!Number.isSafeInteger(maxPendingRequests) || maxPendingRequests <= 0) {
+            throw new RangeError('maxPendingRequests must be a positive safe integer');
+        }
+        this.#maxPendingRequests = maxPendingRequests;
+        this.#worker =
+            options.workerFactory?.() ??
+                new Worker(options.workerUrl ?? new URL('./webgl2-worker.js', import.meta.url), {
+                    type: 'module',
+                    name: 'aelion-renderer-webgl2',
+                });
+        this.#worker.addEventListener('message', this.#handleMessage);
+        this.#worker.addEventListener('error', this.#handleWorkerError);
+    }
+    get disposed() {
+        return this.#disposed;
+    }
+    snapshot() {
+        let activeRequests = 0;
+        let cancelledRequests = 0;
+        for (const request of this.#pending.values()) {
+            if (request.state === 'pending')
+                activeRequests += 1;
+            else
+                cancelledRequests += 1;
+        }
+        return {
+            disposed: this.#disposed,
+            pendingRequests: this.#pending.size,
+            activeRequests,
+            cancelledRequests,
+            maxPendingRequests: this.#maxPendingRequests,
+        };
+    }
+    compose(options) {
+        if (this.#disposed)
+            return Promise.reject(new ReferenceError('WorkerCompositor is disposed'));
+        if (options.signal?.aborted) {
+            Object.values(options.inputs).forEach(frame => frame.close());
+            return Promise.reject(new DOMException('Composition aborted', 'AbortError'));
+        }
+        if (this.#pending.size >= this.#maxPendingRequests) {
+            Object.values(options.inputs).forEach(frame => frame.close());
+            return Promise.reject(new AelionError([
+                {
+                    code: 'RENDERER_QUEUE_FULL',
+                    severity: 'error',
+                    message: `Worker compositor queue reached its ${this.#maxPendingRequests.toString()} request limit`,
+                    recoverable: true,
+                },
+            ]));
+        }
+        const id = this.#nextId;
+        this.#nextId += 1;
+        const request = {
+            type: 'compose',
+            id,
+            inputs: options.inputs,
+            program: options.program,
+            parameters: options.parameters ?? {},
+            systems: options.systems ?? {},
+            width: options.width,
+            height: options.height,
+            preferredBackend: options.preferredBackend ?? 'webgpu',
+            allowFallback: options.allowFallback ?? true,
+            ...(options.debugSimulateLoss === undefined
+                ? {}
+                : { debugSimulateLoss: options.debugSimulateLoss }),
+        };
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const pending = this.#pending.get(id);
+                if (pending === undefined || pending.state === 'cancelled')
+                    return;
+                pending.signal?.removeEventListener('abort', onAbort);
+                // Keep a lightweight tombstone in the admission map until the Worker
+                // confirms that the transferred frames/GPU work reached a terminal
+                // state. Otherwise cancel/retry loops can bypass maxPendingRequests.
+                this.#pending.set(id, { state: 'cancelled' });
+                try {
+                    this.#worker.postMessage({ type: 'cancel', id });
+                }
+                catch {
+                    // A failed cancel post means no acknowledgement can arrive. Terminate
+                    // the Worker so its in-flight resources are reclaimed, then drain all
+                    // client admission state through the shared fatal-error path.
+                    this.#failAll(new Error('Renderer Worker cancellation failed'));
+                }
+                pending.reject(new DOMException('Composition aborted', 'AbortError'));
+            };
+            this.#pending.set(id, {
+                state: 'pending',
+                resolve,
+                reject,
+                ...(options.signal === undefined ? {} : { signal: options.signal, onAbort }),
+            });
+            options.signal?.addEventListener('abort', onAbort, { once: true });
+            try {
+                this.#worker.postMessage(request, Object.values(options.inputs));
+            }
+            catch (error) {
+                this.#pending.delete(id);
+                options.signal?.removeEventListener('abort', onAbort);
+                Object.values(options.inputs).forEach(frame => frame.close());
+                this.#failAll(error instanceof Error ? error : new Error('Renderer Worker request failed'));
+                reject(error instanceof Error ? error : new Error('Renderer Worker request failed'));
+            }
+        });
+    }
+    composeFrameGraph(options) {
+        if (this.#disposed)
+            return Promise.reject(new ReferenceError('WorkerCompositor is disposed'));
+        if (options.signal?.aborted) {
+            Object.values(options.inputs).forEach(frame => frame.close());
+            return Promise.reject(new DOMException('Frame graph aborted', 'AbortError'));
+        }
+        if (options.nodes.length === 0) {
+            Object.values(options.inputs).forEach(frame => frame.close());
+            return Promise.reject(new RangeError('Frame graph must contain at least one node'));
+        }
+        if (this.#pending.size >= this.#maxPendingRequests) {
+            Object.values(options.inputs).forEach(frame => frame.close());
+            return Promise.reject(new AelionError([
+                {
+                    code: 'RENDERER_QUEUE_FULL',
+                    severity: 'error',
+                    message: `Worker compositor queue reached its ${this.#maxPendingRequests.toString()} request limit`,
+                    recoverable: true,
+                },
+            ]));
+        }
+        const id = this.#nextId;
+        this.#nextId += 1;
+        const request = {
+            type: 'compose-frame-graph',
+            id,
+            inputs: options.inputs,
+            nodes: options.nodes,
+            outputNodeId: options.outputNodeId,
+            width: options.width,
+            height: options.height,
+            preferredBackend: options.preferredBackend ?? 'webgl2',
+            allowFallback: options.allowFallback ?? true,
+        };
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const pending = this.#pending.get(id);
+                if (pending === undefined || pending.state === 'cancelled')
+                    return;
+                pending.signal?.removeEventListener('abort', onAbort);
+                this.#pending.set(id, { state: 'cancelled' });
+                try {
+                    this.#worker.postMessage({ type: 'cancel', id });
+                }
+                catch {
+                    this.#failAll(new Error('Renderer Worker cancellation failed'));
+                }
+                pending.reject(new DOMException('Frame graph aborted', 'AbortError'));
+            };
+            this.#pending.set(id, {
+                state: 'pending',
+                resolve,
+                reject,
+                ...(options.signal === undefined ? {} : { signal: options.signal, onAbort }),
+            });
+            options.signal?.addEventListener('abort', onAbort, { once: true });
+            try {
+                this.#worker.postMessage(request, Object.values(options.inputs));
+            }
+            catch (error) {
+                this.#pending.delete(id);
+                options.signal?.removeEventListener('abort', onAbort);
+                Object.values(options.inputs).forEach(frame => frame.close());
+                this.#failAll(error instanceof Error ? error : new Error('Renderer Worker request failed'));
+                reject(error instanceof Error ? error : new Error('Renderer Worker request failed'));
+            }
+        });
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        try {
+            this.#worker.postMessage({ type: 'dispose' });
+        }
+        catch {
+            // Termination below is the authoritative cleanup path.
+        }
+        this.#worker.terminate();
+        this.#detachWorkerListeners();
+        for (const pending of this.#pending.values()) {
+            if (pending.state === 'pending' && pending.onAbort !== undefined) {
+                pending.signal?.removeEventListener('abort', pending.onAbort);
+            }
+            if (pending.state === 'pending') {
+                pending.reject(new ReferenceError('WorkerCompositor was disposed'));
+            }
+        }
+        this.#pending.clear();
+    }
+    #handleMessage = (event) => {
+        const response = event.data;
+        const pending = this.#pending.get(response.id);
+        if (pending === undefined) {
+            if (response.type === 'composed')
+                response.bitmap.close();
+            return;
+        }
+        this.#pending.delete(response.id);
+        if (pending.state === 'cancelled') {
+            if (response.type === 'composed')
+                response.bitmap.close();
+            return;
+        }
+        if (pending.onAbort !== undefined) {
+            pending.signal?.removeEventListener('abort', pending.onAbort);
+        }
+        if (response.type === 'failed')
+            pending.reject(failureError(response));
+        else if (response.type === 'cancelled') {
+            pending.reject(new DOMException('Composition cancelled by Worker', 'AbortError'));
+        }
+        else
+            pending.resolve(response);
+    };
+    #handleWorkerError = (event) => {
+        this.#failAll(new Error(event.message));
+    };
+    #failAll(error) {
+        this.#disposed = true;
+        this.#worker.terminate();
+        this.#detachWorkerListeners();
+        for (const pending of this.#pending.values()) {
+            if (pending.state === 'pending' && pending.onAbort !== undefined) {
+                pending.signal?.removeEventListener('abort', pending.onAbort);
+            }
+            if (pending.state === 'pending')
+                pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+    #detachWorkerListeners() {
+        this.#worker.removeEventListener('message', this.#handleMessage);
+        this.#worker.removeEventListener('error', this.#handleWorkerError);
+    }
+}

package/dist/font-manager.d.ts

@@ -0,0 +1,30 @@
+import { type Disposable } from '@aelionsdk/core';
+export interface FontAssetRegistration {
+    readonly id: string;
+    readonly family: string;
+    readonly source: ArrayBuffer;
+    readonly descriptors?: FontFaceDescriptors;
+}
+export interface FontManagerSnapshot {
+    readonly loadedFonts: number;
+    readonly loadedBytes: number;
+    readonly maxFonts: number;
+    readonly maxBytes: number;
+}
+/** Bounded explicit font loader. Export can fail closed instead of using an unknown system fallback. */
+export declare class BrowserFontManager implements Disposable {
+    #private;
+    get disposed(): boolean;
+    constructor(options?: {
+        readonly fontSet?: FontFaceSet;
+        readonly maxFonts?: number;
+        readonly maxBytes?: number;
+    });
+    snapshot(): FontManagerSnapshot;
+    load(registration: FontAssetRegistration, signal?: AbortSignal): Promise<void>;
+    resolveFallback(families: readonly string[], sample?: string, fontSizePx?: number): string;
+    requireAvailable(families: readonly string[], sample?: string): string;
+    unload(id: string): boolean;
+    dispose(): void;
+}
+//# sourceMappingURL=font-manager.d.ts.map

package/dist/font-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-manager.d.ts","sourceRoot":"","sources":["../src/font-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wGAAwG;AACxG,qBAAa,kBAAmB,YAAW,UAAU;;IAQnD,IAAW,QAAQ,IAAI,OAAO,CAE7B;gBAGC,OAAO,GAAE;QACP,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;QAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KACvB;IAqBD,QAAQ,IAAI,mBAAmB;IASzB,IAAI,CAAC,YAAY,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBpF,eAAe,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,SAAU,EAAE,UAAU,SAAK,GAAG,MAAM;IAQvF,gBAAgB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;IAQtE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAS3B,OAAO,IAAI,IAAI;CAOvB"}

package/dist/font-manager.js

@@ -0,0 +1,87 @@
+import { throwIfAborted } from '@aelionsdk/core';
+/** Bounded explicit font loader. Export can fail closed instead of using an unknown system fallback. */
+export class BrowserFontManager {
+    #faces = new Map();
+    #fontSet;
+    #maxFonts;
+    #maxBytes;
+    #loadedBytes = 0;
+    #disposed = false;
+    get disposed() {
+        return this.#disposed;
+    }
+    constructor(options = {}) {
+        const defaultFontSet = typeof document === 'undefined' ? undefined : document.fonts;
+        const fontSet = options.fontSet ?? defaultFontSet;
+        if (fontSet === undefined) {
+            throw new DOMException('FontFaceSet is unavailable in this execution context', 'NotSupportedError');
+        }
+        this.#fontSet = fontSet;
+        this.#maxFonts = options.maxFonts ?? 32;
+        this.#maxBytes = options.maxBytes ?? 128 * 1024 * 1024;
+        if (!Number.isSafeInteger(this.#maxFonts) || this.#maxFonts <= 0) {
+            throw new RangeError('FONT_LIMIT_INVALID');
+        }
+        if (!Number.isSafeInteger(this.#maxBytes) || this.#maxBytes <= 0) {
+            throw new RangeError('FONT_BYTE_LIMIT_INVALID');
+        }
+    }
+    snapshot() {
+        return {
+            loadedFonts: this.#faces.size,
+            loadedBytes: this.#loadedBytes,
+            maxFonts: this.#maxFonts,
+            maxBytes: this.#maxBytes,
+        };
+    }
+    async load(registration, signal) {
+        if (this.#disposed)
+            throw new ReferenceError('Font manager is disposed');
+        if (this.#faces.has(registration.id))
+            throw new TypeError('FONT_ID_EXISTS');
+        if (this.#faces.size >= this.#maxFonts ||
+            this.#loadedBytes + registration.source.byteLength > this.#maxBytes) {
+            throw new RangeError('FONT_RESOURCE_LIMIT');
+        }
+        throwIfAborted(signal, 'Font load');
+        const face = new FontFace(registration.family, registration.source.slice(0), registration.descriptors);
+        await face.load();
+        throwIfAborted(signal, 'Font load');
+        this.#fontSet.add(face);
+        this.#faces.set(registration.id, { face, bytes: registration.source.byteLength });
+        this.#loadedBytes += registration.source.byteLength;
+    }
+    resolveFallback(families, sample = 'Aa中🙂', fontSizePx = 16) {
+        for (const family of families) {
+            const escaped = family.replaceAll('"', '\\"');
+            if (this.#fontSet.check(`${fontSizePx.toString()}px "${escaped}"`, sample))
+                return family;
+        }
+        return 'sans-serif';
+    }
+    requireAvailable(families, sample) {
+        const resolved = this.resolveFallback(families, sample);
+        if (resolved === 'sans-serif' && !families.includes('sans-serif')) {
+            throw new ReferenceError(`FONT_MISSING: ${families.join(', ')}`);
+        }
+        return resolved;
+    }
+    unload(id) {
+        const entry = this.#faces.get(id);
+        if (entry === undefined)
+            return false;
+        this.#fontSet.delete(entry.face);
+        this.#faces.delete(id);
+        this.#loadedBytes -= entry.bytes;
+        return true;
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        for (const entry of this.#faces.values())
+            this.#fontSet.delete(entry.face);
+        this.#faces.clear();
+        this.#loadedBytes = 0;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './client.js';
+export * from './ir-renderer.js';
+export * from './protocol.js';
+export * from './font-manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './client.js';
+export * from './ir-renderer.js';
+export * from './protocol.js';
+export * from './font-manager.js';

package/dist/ir-renderer.d.ts

@@ -0,0 +1,62 @@
+import { type Disposable } from '@aelionsdk/core';
+import { type RenderIr } from '@aelionsdk/render-ir';
+import { type WorkerCompositorSnapshot } from './client.js';
+import type { RendererWorkerDiagnostic } from './protocol.js';
+export type RenderMode = 'preview' | 'export';
+export interface IrFrameRequest {
+    readonly purpose: RenderMode;
+    readonly maxDimension: number;
+}
+export interface IrFrameSource {
+    frameAt(assetId: string, streamIndex: number, sourceTimeUs: number, signal?: AbortSignal, request?: IrFrameRequest): Promise<VideoFrame>;
+}
+export interface RenderIrFrameOptions {
+    readonly ir: RenderIr;
+    readonly timeUs: number;
+    readonly source: IrFrameSource;
+    readonly mode: RenderMode;
+    readonly preferredBackend?: 'auto' | 'webgpu' | 'webgl2';
+    readonly allowFallback?: boolean;
+    /** Preview-only output scale. Export always renders at full Project resolution. */
+    readonly renderScale?: number;
+    readonly signal?: AbortSignal;
+}
+export interface RenderIrFrameResult {
+    readonly bitmap: ImageBitmap;
+    readonly backend: 'webgpu' | 'webgl2';
+    readonly diagnostics?: readonly RendererWorkerDiagnostic[];
+    readonly materialIds: readonly string[];
+    readonly width: number;
+    readonly height: number;
+    readonly renderScale: number;
+}
+export interface RenderIrFrameRendererOptions {
+    /** Maximum full frame evaluations in flight. Defaults to 2. */
+    readonly maxPendingFrames?: number;
+    /** Host-resolved renderer Worker URL. */
+    readonly workerUrl?: string | URL;
+}
+export interface RenderIrFrameRendererSnapshot {
+    readonly disposed: boolean;
+    readonly pendingFrames: number;
+    readonly maxPendingFrames: number;
+    readonly adaptiveBackend: AdaptiveBackendSnapshot;
+    readonly worker: WorkerCompositorSnapshot;
+}
+export interface AdaptiveBackendSnapshot {
+    readonly selected: 'webgpu' | 'webgl2';
+    readonly webgpuSamples: number;
+    readonly webgl2Samples: number;
+    readonly webgpuP95Us: number | null;
+    readonly webgl2P95Us: number | null;
+    readonly webgpuCooldownFrames: number;
+}
+export declare class RenderIrFrameRenderer implements Disposable {
+    #private;
+    constructor(options?: RenderIrFrameRendererOptions);
+    get disposed(): boolean;
+    snapshot(): RenderIrFrameRendererSnapshot;
+    render(options: RenderIrFrameOptions): Promise<RenderIrFrameResult>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=ir-renderer.d.ts.map

package/dist/ir-renderer.d.ts.map

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