@taole/giftstage 0.1.28 → 0.1.30

package/dist/gpu/detect.d.ts

@@ -0,0 +1,2 @@
+import type { GPUBackend } from '../types';
+export declare function createBackend(canvas: HTMLCanvasElement, preferWebGPU?: boolean, antialias?: boolean, forceWebGL1?: boolean): Promise<GPUBackend>;

package/dist/gpu/gl-utils.d.ts

@@ -0,0 +1,10 @@
+export declare function compileShader(gl: WebGL2RenderingContext, type: number, source: string): WebGLShader;
+export declare function createProgram(gl: WebGL2RenderingContext, vertSource: string, fragSource: string): WebGLProgram;
+export declare function createTexture(gl: WebGL2RenderingContext, filter?: number, wrap?: number): WebGLTexture;
+/**
+ * iOS/iPadOS WebKit has historically been less reliable for direct video-to-WebGL uploads.
+ * Keep the canvas bridge there, while other WebGL2 implementations probe the direct path first.
+ */
+export declare function preferWebGLVideoCanvasBridge(nav?: Pick<Navigator, 'userAgent' | 'maxTouchPoints'> | null | undefined): boolean;
+export declare function texImageSourceWidth(source: TexImageSource): number;
+export declare function texImageSourceHeight(source: TexImageSource): number;

package/dist/gpu/index.d.ts

@@ -0,0 +1,3 @@
+export { createBackend } from './detect';
+export { WebGL2Backend } from './webgl2-backend';
+export { WebGPUBackend } from './webgpu-backend';

package/dist/gpu/webgl1-backend.d.ts

@@ -0,0 +1,43 @@
+import type { GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, GPUBufferSource } from '../types';
+export declare class WebGL1Backend implements GPUBackend {
+    readonly type: "webgl1";
+    readonly canvas: HTMLCanvasElement;
+    maxTextureSize: number;
+    private antialias;
+    private gl;
+    private nextId;
+    private buffers;
+    private textures;
+    private programs;
+    private cachedDrawProgram;
+    private cachedTex0Id;
+    private cachedProjectionRef;
+    private cachedProjectionShader;
+    private videoUploadCanvas;
+    private videoUploadCtx;
+    private supportsUintIndices;
+    constructor(canvas: HTMLCanvasElement, antialias?: boolean);
+    init(): Promise<void>;
+    private initPrograms;
+    private getUniforms;
+    beginFrame(): void;
+    endFrame(): void;
+    private getBufferSourceByteLength;
+    private normalizeIndexSource;
+    createBuffer(data: GPUBufferSource, usage: BufferUsage): GPUBufferHandle;
+    updateBuffer(handle: GPUBufferHandle, data: GPUBufferSource, offset?: number): void;
+    deleteBuffer(handle: GPUBufferHandle): void;
+    private ensureVideoUploadCanvas;
+    private uploadVideoFrameToTexture;
+    createTexture(source: TexImageSource | ArrayBuffer, opts: TextureOpts): GPUTextureHandle;
+    createEmptyTexture(width: number, height: number, opts?: TextureOpts): GPUTextureHandle;
+    updateTexture(handle: GPUTextureHandle, source: TexImageSource): void;
+    updateTextureRegion(handle: GPUTextureHandle, source: TexImageSource, x: number, y: number, destWidth?: number, destHeight?: number): void;
+    deleteTexture(handle: GPUTextureHandle): void;
+    draw(cmd: DrawCommand): void;
+    clearStencil(): void;
+    setScissor(x: number, y: number, w: number, h: number): void;
+    resetScissor(): void;
+    private setupAttributes;
+    destroy(): void;
+}

package/dist/gpu/webgl2-backend.d.ts

@@ -0,0 +1,69 @@
+import type { GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, GPUBufferSource } from '../types';
+export declare class WebGL2Backend implements GPUBackend {
+    readonly type: "webgl2";
+    readonly canvas: HTMLCanvasElement;
+    maxTextureSize: number;
+    private antialias;
+    private gl;
+    private nextId;
+    private buffers;
+    private textures;
+    private programs;
+    private vertexArrays;
+    /** Per-frame GL state caches (aligned with WebGPU bind-group / uniform write dedup). */
+    private cachedDrawProgram;
+    private cachedTex0Id;
+    private cachedProjectionRef;
+    private cachedProjectionShader;
+    /** Canvas bridge retained for iOS/iPadOS WebKit and as a one-way runtime fallback. */
+    private videoUploadCanvas;
+    private videoUploadCtx;
+    private videoElementPreferCanvasBridge;
+    private videoElementDirectUploadValidated;
+    /** DYNAMIC_DRAW upload target for `svga-instanced-premul` (`FrameJobData` per instance). */
+    private static readonly INST_SVGA_GL_MAX;
+    private static readonly INST_SVGA_GL_BYTES;
+    private instancedSvgaInstanceGLBuffer;
+    /** DYNAMIC_DRAW upload target for `alpha-video-instanced` (rect+atlasRemap+opacity per instance). */
+    private static readonly INST_ALPHA_GL_MAX;
+    private static readonly INST_ALPHA_GL_BYTES;
+    private instancedAlphaInstanceGLBuffer;
+    private static readonly INST_VAP_GL_MAX;
+    private static readonly INST_VAP_GL_BYTES;
+    private instancedVapInstanceGLBuffer;
+    constructor(canvas: HTMLCanvasElement, antialias?: boolean);
+    init(): Promise<void>;
+    private initPrograms;
+    private getUniforms;
+    beginFrame(): void;
+    endFrame(): void;
+    private getBufferSourceByteLength;
+    createBuffer(data: GPUBufferSource, usage: BufferUsage): GPUBufferHandle;
+    updateBuffer(handle: GPUBufferHandle, data: GPUBufferSource, offset?: number): void;
+    deleteBuffer(handle: GPUBufferHandle): void;
+    private uploadVideoFrameToTexture;
+    createTexture(source: TexImageSource | ArrayBuffer, opts: TextureOpts): GPUTextureHandle;
+    createEmptyTexture(width: number, height: number, opts?: TextureOpts): GPUTextureHandle;
+    updateTexture(handle: GPUTextureHandle, source: TexImageSource): void;
+    updateTextureRegion(handle: GPUTextureHandle, source: TexImageSource, x: number, y: number, destWidth?: number, destHeight?: number): void;
+    deleteTexture(handle: GPUTextureHandle): void;
+    draw(cmd: DrawCommand): void;
+    clearStencil(): void;
+    setScissor(x: number, y: number, w: number, h: number): void;
+    resetScissor(): void;
+    private setupAttributes;
+    /**
+     * Bind a VAO for the exact shader + vertex/index buffer tuple.
+     * Returns true when the VAO was just created and still needs attribute setup.
+     */
+    private bindCachedVertexArray;
+    private deleteVertexArraysForBuffer;
+    private deleteAllVertexArrays;
+    private ensureInstancedSvgaInstanceBuffer;
+    private drawInstancedSvgaGL;
+    private ensureInstancedAlphaInstanceBuffer;
+    private drawInstancedAlphaGL;
+    private ensureInstancedVapInstanceBuffer;
+    private drawInstancedVapGL;
+    destroy(): void;
+}

package/dist/gpu/webgpu-backend.d.ts

@@ -0,0 +1,155 @@
+import type { GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, GPUBufferSource } from '../types';
+export declare const WEBGPU_INSTANCED_STORAGE_RING_BYTES: number;
+export declare function alignWebGPUByteLength(byteLength: number, alignment: number): number;
+export declare class WebGPUBackend implements GPUBackend {
+    readonly type: "webgpu";
+    readonly canvas: HTMLCanvasElement;
+    readonly maxTextureSize: number;
+    private adapter;
+    private device;
+    private context;
+    private format;
+    private encoder;
+    private passEncoder;
+    private nextId;
+    private buffers;
+    private textures;
+    private pipelines;
+    private sampler;
+    private uniformBuffer;
+    private texturedBindGroupLayout;
+    private dualTexturedBindGroupLayout;
+    private instancedTextureBindGroupLayout;
+    /** `device.limits.minUniformBufferOffsetAlignment` (typically 256). */
+    private uniformSlotStride;
+    /** Ring size for per-draw uniforms (`queue.writeBuffer` must not overwrite before draw — see `draw()`). */
+    private readonly maxUniformSlots;
+    /** Resets each `beginFrame`. */
+    private uniformSlotIndex;
+    /** Skip redundant `setPipeline` / stencil / VB-IB when drawing many quads with the same geometry. */
+    private lastDrawPipeline;
+    private lastStencilRef;
+    private lastVertexBufferId;
+    private lastIndexBufferId;
+    /** Single 160-byte upload for textured draws (replaces multiple `writeBuffer` calls). */
+    private readonly uniformScratch160;
+    /** Single 128-byte upload for uniform-only draws (clip-mask: projection + transform). */
+    private readonly uniformScratch128;
+    private readonly uniformOpacityScratch;
+    private depthStencilTexture;
+    private depthStencilView;
+    private msaaColorTexture;
+    private msaaColorView;
+    private lastCanvasWidth;
+    private lastCanvasHeight;
+    private lastDepthStencilSampleCount;
+    /** 1 = off; 4 = multisampled color + resolve to swapchain when `wantAntialias`. */
+    private msaaSampleCount;
+    private readonly wantAntialias;
+    /** Canvas buffer size last passed to configure(); must reconfigure when it changes. */
+    private configuredCanvasWidth;
+    private configuredCanvasHeight;
+    private dummyTexture;
+    private dummyTextureView;
+    /**
+     * Video / `VideoFrame` → 2D canvas → `copyExternalImageToTexture` (GPU-side upload, matches WebGL2 cost model).
+     * Avoid `getImageData` here — CPU readback tanks FPS vs WebGL2 `texImage2D`.
+     */
+    private videoUploadCanvas;
+    private videoUploadCtx;
+    /**
+     * `<video>` can use `copyExternalImageToTexture(video)` directly (no canvas `drawImage`), which is much cheaper
+     * than the canvas bridge. If a runtime throws (rare), we fall back once and stay on canvas.
+     */
+    private videoElementPreferCanvasBridge;
+    /** Same for WebCodecs `VideoFrame` — direct copy matches WebGL2 `texImage2D(VideoFrame)` cost. */
+    private videoFramePreferCanvasBridge;
+    /** Standard textured pipelines share one layout, so one bind group per texture is sufficient. */
+    private texturedBindGroupCache;
+    /** VAP mixed overlay bind groups, keyed by resource texture id then raw-video texture id. */
+    private dualTexturedBindGroupCache;
+    /** All instanced pipelines also share one texture layout. */
+    private instancedTextureBindGroupCache;
+    /** Batched SVGA sprites (FrameJobData packed as 13 floats per instance). */
+    private static readonly SVGA_INSTANCED_MAX;
+    private static readonly SVGA_INSTANCED_STRIDE;
+    /** Batched alpha-video (storage instances + projection uniform). */
+    private static readonly ALPHA_INSTANCED_MAX;
+    private static readonly ALPHA_INSTANCED_STRIDE;
+    private static readonly VAP_INSTANCED_MAX;
+    private static readonly VAP_INSTANCED_STRIDE;
+    /** One draw may bind up to this many bytes of instance storage (max instances × stride). */
+    private static readonly INSTANCED_SVGA_CHUNK_BYTES;
+    private static readonly INSTANCED_ALPHA_CHUNK_BYTES;
+    private static readonly INSTANCED_VAP_CHUNK_BYTES;
+    /**
+     * Multiple `queue.writeBuffer(..., offset 0)` to the same storage buffer before one `submit` only keep the
+     * last write; one shared ring + dynamic offsets keeps all instanced paths non-overlapping until submit.
+     */
+    private instancedProjectionBuffer;
+    private instancedStorageBuffer;
+    /** `device.limits.minStorageBufferOffsetAlignment` (typically 256). */
+    private storageBindOffsetAlign;
+    /** Reset in `beginFrame`; all instanced draw types reserve non-overlapping chunks. */
+    private instancedStorageRingOffset;
+    private readonly instancedProjectionCache;
+    private instancedProjectionValid;
+    private lastInstancedTextureBindGroup;
+    constructor(canvas: HTMLCanvasElement, adapter: GPUAdapter, wantAntialias?: boolean);
+    init(): Promise<void>;
+    private configureCanvasContext;
+    private ensureDepthStencil;
+    private initPipelines;
+    private ensureInstancedProjectionBuffer;
+    private ensureInstancedStorageBuffer;
+    private ensureInstancedSvgaPipeline;
+    private ensureInstancedAlphaPipeline;
+    private ensureInstancedVapPipeline;
+    private createInstancedSvgaPipeline;
+    private createVapInstancedPipeline;
+    private createInstancedAlphaVideoPipeline;
+    private createTexturedPipeline;
+    private createClipMaskPipeline;
+    beginFrame(): void;
+    endFrame(): void;
+    private ensureInstancedProjection;
+    private gpuBufferUsage;
+    private bufferSourceByteLength;
+    private mappedUploadView;
+    private writeBufferSource;
+    createBuffer(data: GPUBufferSource, usage: BufferUsage): GPUBufferHandle;
+    updateBuffer(handle: GPUBufferHandle, data: GPUBufferSource, offset?: number): void;
+    deleteBuffer(handle: GPUBufferHandle): void;
+    /**
+     * Fast path for decoded `<video>` frames: GPU copy from the element (no 2D canvas), aligned with WebGL `texImage2D(video)`.
+     */
+    private copyHtmlVideoToTextureDirect;
+    private copyVideoFrameToTextureDirect;
+    /**
+     * Fallback: 2D canvas + `copyExternalImageToTexture` (`flipY: true` matches WebGL `UNPACK_FLIP_Y`).
+     */
+    private drawVideoLikeSourceToTexture;
+    /**
+     * Upload ImageBitmap / canvas / video frame to a GPU texture.
+     * `HTMLVideoElement` and `VideoFrame` prefer direct `copyExternalImageToTexture` when supported.
+     */
+    private copyImageSourceToTexture;
+    createTexture(source: TexImageSource | ArrayBuffer, opts: TextureOpts): GPUTextureHandle;
+    createEmptyTexture(width: number, height: number, _opts?: TextureOpts): GPUTextureHandle;
+    updateTexture(handle: GPUTextureHandle, source: TexImageSource): void;
+    updateTextureRegion(handle: GPUTextureHandle, source: TexImageSource, x: number, y: number, destWidth?: number, destHeight?: number): void;
+    private copyHtmlVideoToTextureRegionDirect;
+    private copyVideoFrameToTextureRegionDirect;
+    private drawVideoLikeSourceToTextureRegion;
+    deleteTexture(handle: GPUTextureHandle): void;
+    draw(cmd: DrawCommand): void;
+    /** One `drawIndexed` with `instanceCount` for all SVGA sprites sharing the same atlas. */
+    private drawInstancedSvga;
+    /** One `drawIndexed` with `instanceCount` for all gifts sharing the same video texture (e.g. atlas). */
+    private drawInstancedAlpha;
+    private drawInstancedVap;
+    clearStencil(): void;
+    setScissor(x: number, y: number, w: number, h: number): void;
+    resetScissor(): void;
+    destroy(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export { GiftStage } from './core/gift-stage';
+export { RenderManager } from './core/render-manager';
+export { AudioManager } from './core/audio-manager';
+export { PostAnimator } from './core/post-animator';
+export { WebGL2Backend } from './gpu/webgl2-backend';
+export { WebGL1Backend } from './gpu/webgl1-backend';
+export { WebGPUBackend } from './gpu/webgpu-backend';
+export { createBackend } from './gpu/detect';
+export { SVGABatchRenderer } from './renderers/svga-batch-renderer';
+export { VAPRenderer } from './renderers/vap-renderer';
+export { AlphaVideoRenderer } from './renderers/alpha-video-renderer';
+export { ImageRenderer } from './renderers/image-renderer';
+export { buildBatchVerticesJS } from './renderers/vertex-builder';
+export { parseSVGA } from './parsers/svga-parser';
+export type { ParseSVGAOptions } from './parsers/svga-parser';
+export { buildAtlas } from './parsers/atlas-builder';
+export { parseVAPConfig } from './parsers/vap-config-parser';
+export { inflateJS } from './parsers/inflate-js';
+export { decodeSVGAProto } from './parsers/svga-proto-js';
+export * from './utils/easing';
+export { ortho, lerp, clamp, generateId } from './utils/math';
+export { BufferPool } from './utils/buffer-pool';
+export { canWebGPU, canWebGL2, canWebGL1, canSharedArrayBuffer } from './utils/detect';
+export { initWasm, isWasmReady } from './wasm/wasm-bridge';
+export { WebCodecsMp4Playback } from './video/webcodecs-mp4-playback';
+export type { WebCodecsMp4CreateOptions } from './video/webcodecs-mp4-playback';
+export type { WebCodecsPlaybackHandle, GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, ShaderType, BackendType, GiftStageOptions, AddGiftOptions, GiftHandle, GiftSlot, GiftType, GiftObjectFit, GiftCoordinate, GiftState, GiftAnimationStep, GiftAnimationChain, SVGAMovieEntity, SVGAParams, SVGASpriteTable, SVGAAudio, SVGATransform, SVGAShape, VideoEntity, UVRect, FrameJobData, FlyAnimation, VAPConfig, VAPSrcItem, VAPFrameItem, VAPFrameObj, } from './types';

package/dist/parsers/atlas-builder.d.ts

@@ -0,0 +1,37 @@
+import type { GPUBackend, GPUTextureHandle, UVRect } from '../types';
+export interface AtlasPageResult {
+    textureHandle: GPUTextureHandle;
+    atlasWidth: number;
+    atlasHeight: number;
+    encodedPngBytesPromise?: Promise<ArrayBuffer | null>;
+}
+export interface AtlasResult {
+    /** First page, kept for compatibility with older single-atlas consumers. */
+    textureHandle: GPUTextureHandle;
+    textureHandles: GPUTextureHandle[];
+    pages: AtlasPageResult[];
+    rects: Map<string, UVRect>;
+    /** First page width, kept for compatibility with older single-atlas consumers. */
+    atlasWidth: number;
+    /** First page height, kept for compatibility with older single-atlas consumers. */
+    atlasHeight: number;
+    /** First page PNG promise, kept for compatibility with older single-atlas consumers. */
+    encodedPngBytesPromise?: Promise<ArrayBuffer | null>;
+    encodedPngBytesPromises?: Array<Promise<ArrayBuffer | null>>;
+}
+export interface AtlasBuildOptions {
+    captureEncodedPng?: boolean;
+    maxPages?: number;
+    /**
+     * Main-thread atlas compose/upload slice cap. The actual slice tracks half
+     * of the observed frame interval and is capped at this value. Default: 12.
+     */
+    mainThreadFrameBudgetMs?: number;
+    /** Worker cooperative CPU slice cap. Defaults to 4ms. */
+    workerTimeSliceMs?: number;
+    /** Internal recovery switch: false forces main-thread composition even when the worker is available. */
+    useWorker?: boolean;
+    /** Cancels cooperative work and terminates an active atlas worker request. */
+    signal?: AbortSignal;
+}
+export declare function buildAtlas(images: Map<string, ImageBitmap>, backend: GPUBackend, maxSize?: number, padding?: number, opts?: AtlasBuildOptions): Promise<AtlasResult>;

package/dist/parsers/atlas-packing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure shelf bin-packing for SVGA atlases (shared by main thread and atlas worker).
+ * Mirrors Unity Texture2D.PackTextures: oversized images downscale; many images split across pages.
+ */
+export interface ImageSizeEntry {
+    key: string;
+    width: number;
+    height: number;
+}
+export interface PackedRect {
+    key: string;
+    pageIndex: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface PackedAtlasPage {
+    rects: PackedRect[];
+    atlasW: number;
+    atlasH: number;
+}
+export type AtlasPackingCheckpoint = () => Promise<void>;
+/**
+ * Shelf bin-packing with multiple pages.
+ * Prefer splitting across pages; when page count exceeds maxPages, binary-search a global downscale.
+ */
+export declare function shelfPackPages(images: ImageSizeEntry[], padding: number, maxSize: number, maxPages: number): PackedAtlasPage[];
+export declare function shelfPackPagesCooperative(images: ImageSizeEntry[], padding: number, maxSize: number, maxPages: number, checkpoint: AtlasPackingCheckpoint): Promise<PackedAtlasPage[]>;
+/** Edge bleed for linear filtering (shared by main-thread and worker compose). */
+export declare function extrudeAtlasRect(surface: OffscreenCanvas | HTMLCanvasElement, ctx: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D, rect: PackedRect, atlasW: number, atlasH: number, padding: number): void;

package/dist/parsers/index.d.ts

@@ -0,0 +1,7 @@
+export { parseSVGA } from './svga-parser';
+export type { ParseResult } from './svga-parser';
+export { buildAtlas } from './atlas-builder';
+export type { AtlasResult } from './atlas-builder';
+export { parseVAPConfig, getVAPFrame, computeVAPUV } from './vap-config-parser';
+export { inflateJS } from './inflate-js';
+export { decodeSVGAProto } from './svga-proto-js';

package/dist/parsers/inflate-js.d.ts

@@ -0,0 +1,37 @@
+export declare function canUseNativeInflate(): boolean;
+export interface InflateAttemptProfile {
+    format: CompressionFormat;
+    inputBytes: number;
+    inputChunks: 1;
+    writerSubmitMs: number;
+    readMs: number;
+    concatMs: number;
+    totalMs: number;
+    outputChunks: number;
+    outputBytes: number;
+    status: 'success' | 'failed';
+    error?: string;
+}
+export interface InflateProfile {
+    inputBytes: number;
+    nativeAvailable: boolean;
+    nativeAttempts: InflateAttemptProfile[];
+    selectedPath?: 'native' | 'wasm' | 'native-retry';
+    wasmMs?: number;
+    outputBytes?: number;
+    totalMs?: number;
+    error?: string;
+}
+export type InflateProfileSink = (profile: InflateProfile) => void;
+/**
+ * Inflate preferring the browser-native DecompressionStream (usually faster than WASM
+ * and runs off the JS thread); falls back to the provided WASM inflate, then to
+ * `inflateJS` (which throws a meaningful error when nothing is available).
+ */
+export declare function inflatePreferNative(data: Uint8Array, wasmInflate: () => Uint8Array | null | false, onProfile?: InflateProfileSink): Promise<Uint8Array>;
+/**
+ * JS fallback inflate using DecompressionStream API (no WASM needed).
+ * SVGA files are zlib-compressed (2-byte header + deflate data + 4-byte Adler32).
+ * 'deflate' mode handles the full zlib envelope natively.
+ */
+export declare function inflateJS(data: Uint8Array, profile?: Pick<InflateProfile, 'nativeAttempts'>): Promise<Uint8Array>;

package/dist/parsers/svga-image-decode-worker-client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether the environment can use a worker for ImageBitmap decode (best-effort).
+ */
+export declare function canUseSVGAImageDecodeWorker(): boolean;
+export interface SVGAImageDecodeWorkerOptions {
+    workerTimeSliceMs?: number;
+    maxConcurrency?: number;
+    mainThreadFrameBudgetMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Decode many image blobs to ImageBitmaps in a dedicated worker, in chunks to limit message size.
+ */
+export declare function decodeSVGAImagesInWorker(imageEntries: Array<[string, Uint8Array]>, chunkSize: number, options?: SVGAImageDecodeWorkerOptions): Promise<Map<string, ImageBitmap>>;

package/dist/parsers/svga-parser-worker-client.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Dedicated Worker client for SVGA inflate + protobuf (see ../workers/parser-worker.ts).
+ * ImageBitmap creation stays on the main thread.
+ */
+import type { SVGAMovieEntity, SVGASpriteTable } from '../types';
+export interface SVGAParserWorkerOptions {
+    profile?: boolean;
+    workerTimeSliceMs?: number;
+    mainThreadFrameBudgetMs?: number;
+    signal?: AbortSignal;
+}
+export interface SVGAWorkerMoviePayload {
+    version: string;
+    params: SVGAMovieEntity['params'];
+    spriteTable: SVGASpriteTable;
+    audios: SVGAMovieEntity['audios'];
+    images?: Record<string, ArrayBuffer>;
+    imageBlob?: ArrayBuffer;
+    imageEntries?: Array<{
+        key: string;
+        offset: number;
+        length: number;
+    }>;
+    __debug?: Record<string, unknown>;
+}
+/**
+ * Transfers `fileBuffer` to the parser worker (the buffer is detached — the caller must not
+ * use it afterwards); resolves with decoded movie payload (no ImageBitmaps).
+ */
+export declare function requestSVGAParseInWorker(fileBuffer: ArrayBuffer, options?: SVGAParserWorkerOptions): Promise<SVGAWorkerMoviePayload>;
+export declare function workerPayloadToMovieEntity(payload: SVGAWorkerMoviePayload): SVGAMovieEntity;

package/dist/parsers/svga-parser.d.ts

@@ -0,0 +1,49 @@
+import type { SVGAMovieEntity } from '../types';
+export interface ParseResult {
+    movie: SVGAMovieEntity;
+    imageBitmaps: Map<string, ImageBitmap>;
+    audioBlobs: Map<string, ArrayBuffer>;
+}
+export interface ParseSVGAOptions {
+    /**
+     * When true (default), inflate + protobuf decode run in a Dedicated Worker (main thread only builds ImageBitmaps).
+     * Set false for tests or environments without Workers.
+     */
+    useWorker?: boolean;
+    /**
+     * When true (default), decode embedded images to ImageBitmap in a Dedicated Worker (off main thread).
+     * On failure, falls back to main-thread decode (adaptive batch unless disabled).
+     */
+    useImageBitmapDecodeWorker?: boolean;
+    /**
+     * Max images per postMessage to the image decode worker. Default 32.
+     */
+    imageDecodeWorkerChunkSize?: number;
+    /**
+     * When decoding on the main thread, adjust batch size from measured time and yield when over budget.
+     * Default true.
+     */
+    imageDecodeAdaptiveOnMainThread?: boolean;
+    /**
+     * Target ms per main-thread batch before considering a frame yield (adaptive path). Default 12.
+     */
+    imageDecodeFrameBudgetMs?: number;
+    /**
+     * Fixed batch size on main thread when `imageDecodeAdaptiveOnMainThread` is false. Default 4.
+     */
+    imageDecodeFixedBatchSize?: number;
+    /** Shared SVGA main-thread frame-budget cap. Defaults to 12ms. */
+    svgaLoadFrameBudgetMs?: number;
+    /** Worker cooperative CPU slice cap. Defaults to 4ms and is clamped to 1-8ms. */
+    svgaWorkerFrameBudgetMs?: number;
+    /** Global SVGA heavy-worker concurrency cap. Defaults to 1. */
+    svgaWorkerTaskConcurrency?: number;
+    /** Initial ImageBitmap decode concurrency inside the image worker. Defaults to 2. */
+    svgaWorkerImageDecodeConcurrency?: number;
+    /** Emit a single structured profile for each actual parse. Default false. */
+    svgaParseProfile?: boolean;
+    /** Cancels this parse consumer. Shared payload work stops only after all consumers cancel. */
+    signal?: AbortSignal;
+}
+export declare function parseSVGAParams(source: string | ArrayBuffer, options?: ParseSVGAOptions): Promise<SVGAMovieEntity['params']>;
+export declare function parseSVGA(source: string | ArrayBuffer, options?: ParseSVGAOptions): Promise<ParseResult>;

package/dist/parsers/svga-proto-js.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Lightweight JS protobuf decoder for SVGA MovieEntity.
+ * Falls back to this when WASM is unavailable.
+ * Implements just enough proto2 wire format to decode the SVGA schema.
+ */
+import type { SVGAMovieEntity } from '../types';
+export declare function decodeSVGAProto(data: Uint8Array): SVGAMovieEntity;

package/dist/parsers/svga-sprite-table-binary.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared SoA sprite-table binary section (SGPB v2 / SGBC v14).
+ */
+import type { SVGASpriteTable } from '../types';
+declare function align4(offset: number): number;
+export interface SpriteTableBinaryWriter {
+    u8(value: number): void;
+    u32(value: number): void;
+    i32(value: number): void;
+    f32(value: number): void;
+    string(value: string): void;
+    rawBytes(value: Uint8Array): void;
+    pad4(): void;
+}
+export interface SpriteTableBinaryReader {
+    u8(): number;
+    u32(): number;
+    i32(): number;
+    f32(): number;
+    string(): string;
+    pad4(): void;
+    readonly position: number;
+    skip(bytes: number): void;
+    sourceBuffer(): ArrayBuffer;
+}
+export interface CooperativeSpriteTableBinaryWriter extends SpriteTableBinaryWriter {
+    stringCooperative(value: string, checkpoint: SpriteTableCheckpoint): Promise<void>;
+    rawBytesCooperative(value: Uint8Array, checkpoint: SpriteTableCheckpoint): Promise<void>;
+}
+export type SpriteTableCheckpoint = () => Promise<void>;
+export declare function writeSpriteTable(writer: SpriteTableBinaryWriter, table: SVGASpriteTable): void;
+export declare function writeSpriteTableCooperative(writer: CooperativeSpriteTableBinaryWriter, table: SVGASpriteTable, checkpoint: SpriteTableCheckpoint): Promise<void>;
+export declare function readSpriteTable(reader: SpriteTableBinaryReader): SVGASpriteTable;
+export declare function readSpriteTableCooperative(reader: SpriteTableBinaryReader, checkpoint: SpriteTableCheckpoint): Promise<SVGASpriteTable>;
+/** Pad offset to 4-byte boundary (for standalone writers). */
+export { align4 };

package/dist/parsers/svga-sprite-table.d.ts

@@ -0,0 +1,59 @@
+/**
+ * SVGA sprite SoA table: flat frame floats + deduped clip/shapes side tables.
+ * Replaces per-sprite `frames: SVGAFrame[]` object graphs on the hot path.
+ */
+import type { SVGAShape, SVGATransform } from '../types';
+/** Floats per frame in `frameData`: layoutW, layoutH, a, b, c, d, tx, ty, alpha. */
+export declare const SPRITE_FRAME_FLOATS = 9;
+export interface SVGASpriteTable {
+    spriteCount: number;
+    frameCount: number;
+    imageKeys: string[];
+    /** spriteCount × frameCount × 9, row-major (sprite, then frame). */
+    frameData: Float32Array;
+    /** Deduped non-empty clipPath strings. */
+    clipPaths: string[];
+    /** spriteCount × frameCount; -1 = none. */
+    clipPathIndex: Int32Array;
+    /** Deduped shape groups; keep-chains share the same array reference. */
+    shapesTable: SVGAShape[][];
+    /** spriteCount × frameCount; -1 = none. */
+    shapesIndex: Int32Array;
+    hasAnyShapes: boolean;
+}
+/** Loose frame shape used when converting from AoS decode (JS proto / fixtures). */
+export interface SVGAFrameLike {
+    alpha: number;
+    layout: {
+        width: number;
+        height: number;
+    } | null;
+    transform: SVGATransform | null;
+    clipPath: string;
+    shapes?: SVGAShape[] | null;
+}
+export interface SVGASpriteLike {
+    imageKey: string;
+    frames: SVGAFrameLike[];
+}
+export declare function readSpriteFrameAlpha(table: SVGASpriteTable, spriteIndex: number, frameIndex: number): number;
+export declare function readSpriteFrameTransform(table: SVGASpriteTable, spriteIndex: number, frameIndex: number): {
+    layoutW: number;
+    layoutH: number;
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    tx: number;
+    ty: number;
+    alpha: number;
+};
+export declare function getSpriteShapes(table: SVGASpriteTable, spriteIndex: number, frameIndex: number): SVGAShape[] | null;
+export declare function getSpriteClipPath(table: SVGASpriteTable, spriteIndex: number, frameIndex: number): string;
+/**
+ * Build a SoA table from AoS sprites (JS protobuf decode / test fixtures).
+ * Resolves shape `keep` chains to shared array references.
+ */
+export declare function spriteTableFromSprites(sprites: SVGASpriteLike[], frameCountHint?: number): SVGASpriteTable;
+/** Empty table used when there are no sprites. */
+export declare function emptySpriteTable(frameCount?: number): SVGASpriteTable;

package/dist/parsers/svga-worker-payload-binary.d.ts

@@ -0,0 +1,10 @@
+import type { SVGAMovieEntity } from '../types';
+import type { SVGAWorkerMoviePayload } from './svga-parser-worker-client';
+import { type SpriteTableCheckpoint } from './svga-sprite-table-binary';
+export declare function serializeSVGAWorkerPayload(payload: SVGAWorkerMoviePayload): ArrayBuffer;
+export declare function serializeSVGAWorkerPayloadCooperative(payload: SVGAWorkerMoviePayload, checkpoint: SpriteTableCheckpoint): Promise<ArrayBuffer>;
+export declare function deserializeSVGAWorkerPayload(buffer: ArrayBuffer, debug?: Record<string, unknown>): SVGAWorkerMoviePayload;
+export declare function deserializeSVGAWorkerPayloadCooperative(buffer: ArrayBuffer, debug?: Record<string, unknown>, frameBudgetMs?: number, signal?: AbortSignal): Promise<SVGAWorkerMoviePayload>;
+export declare function movieEntityToWorkerPayloadBinary(movie: SVGAMovieEntity): ArrayBuffer;
+export declare function workerPayloadImageBytes(payload: SVGAWorkerMoviePayload): number;
+export declare function workerPayloadImageCount(payload: SVGAWorkerMoviePayload): number;