@taole/giftstage 0.1.36 → 0.2.2

package/dist/gpu/backend-operation-result.d.ts

@@ -0,0 +1,6 @@
+import type { BackendOperationFailureReason, BackendOperationResult } from '../types/index.js';
+/** Shared success result for allocation-free backend hot paths. */
+export declare const BACKEND_OPERATION_SUBMITTED: BackendOperationResult;
+export declare function rejectBackendOperation(reason: BackendOperationFailureReason, message?: string): BackendOperationResult;
+/** Convert a rejected backend operation into the frame-level exception path. */
+export declare function requireBackendOperation(result: BackendOperationResult, operation: string): void;

package/dist/gpu/detect.d.ts

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

package/dist/gpu/index.d.ts

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

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

@@ -1,4 +1,4 @@
-import type { GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, GPUBufferSource } from '../types';
+import type { GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, GPUBufferSource, BackendOperationResult } from '../types/index.js';
 export declare class WebGL1Backend implements GPUBackend {
     readonly type: "webgl1";
     readonly canvas: HTMLCanvasElement;
@@ -13,6 +13,7 @@ export declare class WebGL1Backend implements GPUBackend {
     private cachedTex0Id;
     private cachedProjectionRef;
     private cachedProjectionShader;
+    private lastDrawSubmitted;
     private videoUploadCanvas;
     private videoUploadCtx;
     private supportsUintIndices;
@@ -38,8 +39,10 @@ export declare class WebGL1Backend implements GPUBackend {
     private applyDrawUniforms;
     beginFrame(options?: {
         stencil?: boolean;
-    }): void;
-    endFrame(): void;
+    }): BackendOperationResult;
+    endFrame(): BackendOperationResult;
+    abortFrame(): BackendOperationResult;
+    private errorMessage;
     private getBufferSourceByteLength;
     private normalizeIndexSource;
     createBuffer(data: GPUBufferSource, usage: BufferUsage): GPUBufferHandle;
@@ -52,7 +55,8 @@ export declare class WebGL1Backend implements GPUBackend {
     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;
+    draw(cmd: DrawCommand): BackendOperationResult;
+    private drawInternal;
     clearStencil(): void;
     setScissor(x: number, y: number, w: number, h: number): void;
     resetScissor(): void;

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

@@ -1,6 +1,50 @@
-import type { GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, GPUBufferSource } from '../types';
+import type { GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, GPUBufferSource, SVGAFrameTableBinding, SVGAFrameTableCreateOptions, BackendOperationResult } from '../types/index.js';
+/** The table-aware shader is added by the timeline path without widening the
+ * public ShaderType union during the backend migration. */
+export declare const WEBGL2_SVGA_FRAME_TABLE_SHADER: "svga-frame-table-instanced-premul";
+export declare const WEBGL2_SVGA_FRAME_TABLE_FLOATS_PER_FRAME = 12;
+/** Static UV/page metadata is two RGBA texels per sprite row. */
+export declare const WEBGL2_SVGA_FRAME_METADATA_FLOATS_PER_SPRITE = 8;
+export type WebGL2FrameTableBinding = Extract<SVGAFrameTableBinding, {
+    backend: 'webgl2';
+}> & {
+    /** Static UV/page metadata texture paired with the frame table. */
+    spriteMetadataTexture?: GPUTextureHandle;
+};
+/**
+ * WebGL2 table-aware draw command.  The backend accepts these fields through
+ * structural typing so the public DrawCommand can be widened independently.
+ */
+export interface SVGAFrameTableDrawCommand extends DrawCommand {
+    svgaFrameTable?: WebGL2FrameTableBinding | GPUTextureHandle | null;
+    svgaFrameTableTexture?: GPUTextureHandle | null;
+    svgaSpriteMetadata?: GPUTextureHandle | null;
+    svgaSpriteMetadataTexture?: GPUTextureHandle | null;
+    svgaSpriteMetadataBase?: number;
+    svgaFrameTableMetadataBase?: number;
+    svgaFrameTableSlotState?: Float32Array;
+    svgaSlotState?: Float32Array;
+    svgaFrameIndex?: number;
+    svgaSpriteBase?: number;
+    svgaFrameTableAtlasPage?: number;
+    svgaFrameTableParentAffine?: Float32Array;
+    svgaFrameTableParentTranslate?: Float32Array;
+    svgaFrameTableOpacity?: number;
+    svgaFrameTableClipRect?: Float32Array;
+    svgaFrameTableFrameCount?: number;
+    svgaFrameTableSpriteCount?: number;
+    svgaFrameTableFrameIndex?: number;
+    svgaFrameTableSpriteBase?: number;
+    frameTableTexture?: GPUTextureHandle | null;
+    spriteMetadataTexture?: GPUTextureHandle | null;
+    frameTableFrameCount?: number;
+    frameTableSpriteCount?: number;
+    frameTableFrameIndex?: number;
+    frameTableSpriteBase?: number;
+}
 export declare class WebGL2Backend implements GPUBackend {
     readonly type: "webgl2";
+    readonly supportsAtomicFrameReplay = true;
     readonly canvas: HTMLCanvasElement;
     maxTextureSize: number;
     private antialias;
@@ -8,11 +52,16 @@ export declare class WebGL2Backend implements GPUBackend {
     private nextId;
     private buffers;
     private textures;
+    private frameTables;
+    /** Metadata textures generated by a frame-table create call (external ones are not owned). */
+    private ownedFrameTableMetadataIds;
     private programs;
     private vertexArrays;
     /** Per-frame GL state caches (aligned with WebGPU bind-group / uniform write dedup). */
     private cachedDrawProgram;
     private cachedTex0Id;
+    private cachedFrameTableId;
+    private cachedFrameMetadataId;
     private cachedProjectionRef;
     private cachedProjectionShader;
     /** Canvas bridge retained for iOS/iPadOS WebKit and as a one-way runtime fallback. */
@@ -20,12 +69,24 @@ export declare class WebGL2Backend implements GPUBackend {
     private videoUploadCtx;
     private videoElementPreferCanvasBridge;
     private videoElementDirectUploadValidated;
+    /** WebGL2 float vertex-texture capability used by the SVGA frame-table path. */
+    maxVertexTextureImageUnits: number;
+    /** Set only after the table shader has compiled and vertex texture fetch is available. */
+    svgaFrameTableSupported: boolean;
     /** DYNAMIC_DRAW upload target for `svga-instanced-premul` (`FrameJobData` per instance). */
     private static readonly INST_SVGA_GL_MAX;
     private static readonly INST_SVGA_GL_FLOATS;
     private static readonly INST_SVGA_GL_STRIDE;
     private static readonly INST_SVGA_GL_BYTES;
     private instancedSvgaInstanceGLBuffer;
+    private svgaSlotStateTexture;
+    private svgaSlotStateTextureWidth;
+    private svgaSlotStateTextureHeight;
+    private svgaSlotStateUploadScratch;
+    private svgaSlotStateUploadId;
+    private readonly svgaTableInfoScratch;
+    private readonly svgaTableSizeScratch;
+    private readonly svgaMetadataSizeScratch;
     /** DYNAMIC_DRAW upload target for instanced clip-mask affine transforms. */
     private static readonly INST_CLIP_MASK_GL_MAX;
     private static readonly INST_CLIP_MASK_GL_FLOATS;
@@ -38,9 +99,50 @@ export declare class WebGL2Backend implements GPUBackend {
     private instancedAlphaInstanceGLBuffer;
     private static readonly INST_VAP_GL_MAX;
     private static readonly INST_VAP_GL_BYTES;
+    private performanceBufferWrites;
+    private performanceBufferWriteBytes;
+    private performanceStorageBufferWrites;
+    private performanceStorageBufferWriteBytes;
+    private performanceSubmittedDrawCalls;
+    private performanceRejectedDrawCalls;
+    private performanceSVGADynamicUploadWrites;
+    private performanceSVGADynamicUploadBytes;
+    private runtimeSubmittedDrawCalls;
+    private runtimeRejectedDrawCalls;
+    private currentDrawResult;
+    private currentDrawRecorded;
+    private runtimeBackendLosses;
+    private runtimeDiagnosticHandler;
+    private contextLost;
+    private deviceLostHandler;
+    private readonly onContextLost;
     private instancedVapInstanceGLBuffer;
     constructor(canvas: HTMLCanvasElement, antialias?: boolean);
     init(): Promise<void>;
+    getPerformanceSnapshot(): {
+        bufferWrites: number;
+        bufferWriteBytes: number;
+        storageBufferWrites: number;
+        storageBufferWriteBytes: number;
+        submittedDrawCalls: number;
+        rejectedDrawCalls: number;
+        svgaDynamicUploadWrites: number;
+        svgaDynamicUploadBytes: number;
+    };
+    getRuntimeDiagnosticsSnapshot(): {
+        submittedDrawCalls: number;
+        rejectedDrawCalls: number;
+        webgpuUncapturedErrors: number;
+        backendLosses: number;
+    };
+    setRuntimeDiagnosticHandler(handler: ((event: {
+        type: 'gpu-uncaptured-error' | 'backend-lost';
+        message?: string;
+    }) => void) | null): void;
+    resetPerformanceSnapshot(): void;
+    setDeviceLostHandler(handler: (() => void) | null): void;
+    private recordSubmittedDraw;
+    private rejectSVGAFastPathDraw;
     private initPrograms;
     private makeProgramEntry;
     /**
@@ -63,19 +165,53 @@ export declare class WebGL2Backend implements GPUBackend {
     private applyDrawUniforms;
     beginFrame(options?: {
         stencil?: boolean;
-    }): void;
-    endFrame(): void;
+    }): BackendOperationResult;
+    endFrame(): BackendOperationResult;
+    abortFrame(): BackendOperationResult;
+    private errorMessage;
     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;
+    /**
+     * Returns whether this context can sample the immutable SVGA table from a
+     * vertex shader.  Callers should use this before selecting `gpu-direct`;
+     * a false result leaves the existing CPU-reference path untouched.
+     */
+    canCreateSVGAFrameTable(): boolean;
+    private assertSVGAFrameTableSupport;
+    private createFloatTableTexture;
+    /**
+     * Packs a linear RGBA texel stream into one 2D texture. Width is kept a
+     * multiple of the logical record width (3 frame texels or 2 metadata
+     * texels), while height is allowed to grow up to MAX_TEXTURE_SIZE. This
+     * avoids rejecting wide assets merely because `texelCount` exceeds the
+     * maximum texture height.
+     */
+    private createLinearFloatTableTexture;
+    /**
+     * Creates the resource-level static UV/page metadata texture paired with a
+     * frame table. Input rows may contain either four floats (UV only) or eight
+     * floats (UV + atlas page/flags). The compact four-float form uses page and
+     * flags zero in its second texel; row order remains the sprite index.
+     */
+    createSVGAFrameTableMetadata(metadata: Float32Array, spriteCount: number, strideFloats?: number): GPUTextureHandle;
+    /**
+     * Creates a single, non-paged RGBA32F SVGA frame table. Three texels are
+     * stored per `(sprite, frame)` row. Upload/setup errors throw before a
+     * usable binding is returned, allowing the caller to select CPU fallback.
+     */
+    createSVGAFrameTable(packedData: Float32Array, options: SVGAFrameTableCreateOptions): WebGL2FrameTableBinding;
+    deleteSVGAFrameTable(binding: SVGAFrameTableBinding | null | undefined): void;
     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;
+    draw(cmd: DrawCommand): BackendOperationResult;
+    private completeDrawResult;
+    private rejectDrawResult;
     clearStencil(): void;
     setScissor(x: number, y: number, w: number, h: number): void;
     resetScissor(): void;
@@ -88,6 +224,20 @@ export declare class WebGL2Backend implements GPUBackend {
     private deleteVertexArraysForBuffer;
     private deleteAllVertexArrays;
     private ensureInstancedSvgaInstanceBuffer;
+    /** Uploads four RGBA32F texels per Direct slot for the compact multi-slot path. */
+    private uploadSVGASlotStates;
+    private resolveSVGAFrameTableSlotState;
+    /**
+     * One draw covers all sprites for one slot/atlas-page group. The frame and
+     * UV tables are immutable textures. Direct draws upload no per-sprite rows;
+     * Hybrid draws may upload compact scheduling rows without child matrices or
+     * alpha. A malformed/unsupported command returns without touching the
+     * existing CPU-reference draw path.
+     */
+    private drawSVGAFrameTableGL;
+    /** Shape/clip meshes fetch their child transform from the same resident frame table. */
+    private drawSVGAFrameTableMeshGL;
+    private drawInstancedParticlesGL;
     private drawInstancedSvgaGL;
     private ensureInstancedClipMaskBuffer;
     private drawInstancedClipMaskGL;

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

@@ -1,8 +1,50 @@
-import type { GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, GPUBufferSource } from '../types';
+import type { GPUBackend, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, GPUBufferSource, SVGAFrameTableBinding, SVGAFrameTableCreateOptions, BackendOperationResult } from '../types/index.js';
 export declare const WEBGPU_INSTANCED_STORAGE_RING_BYTES: number;
+/** Three vec4 values per (sprite, frame): layout/affine, translation and alpha. */
+export declare const WEBGPU_SVGA_FRAME_TABLE_FLOATS_PER_FRAME = 12;
+/** Two vec4 values per resident sprite metadata record (UV rect + page/flags). */
+export declare const WEBGPU_SVGA_SPRITE_METADATA_FLOATS = 8;
+export declare const WEBGPU_SVGA_SPRITE_METADATA_STRIDE: number;
+/** Projection plus slot state; the uniform ring still rounds this to 256 bytes. */
+export declare const WEBGPU_SVGA_FRAME_TABLE_SLOT_UNIFORM_BYTES = 160;
+export declare const WEBGPU_SVGA_FRAME_TABLE_SHADER: "svga-frame-table-instanced-premul";
+/**
+ * Draw-command extension consumed by the WebGPU timeline path.  The public
+ * DrawCommand/GPUBackend interfaces are intentionally kept in `src/types` so
+ * other backend work can add the same fields without widening this module's
+ * dependency surface.  The aliases are accepted during the migration window.
+ */
+export interface SVGAFrameTableDrawCommand extends DrawCommand {
+    svgaFrameTable?: GPUBufferHandle | SVGAFrameTableBinding | null;
+    svgaFrameTableBuffer?: GPUBufferHandle | null;
+    svgaFrameTableFrameCount?: number;
+    svgaFrameTableSpriteCount?: number;
+    svgaFrameTableFrameIndex?: number;
+    svgaFrameIndex?: number;
+    svgaSpriteBase?: number;
+    svgaFrameTableAtlasPage?: number;
+    svgaFrameTableParentAffine?: Float32Array;
+    svgaFrameTableParentTranslate?: Float32Array;
+    svgaFrameTableOpacity?: number;
+    svgaFrameTableClipRect?: Float32Array;
+    svgaSpriteMetadata?: GPUBufferHandle | null;
+    svgaSpriteMetadataBuffer?: GPUBufferHandle | null;
+    spriteMetadataBuffer?: GPUBufferHandle | null;
+    svgaFrameTableMetadataBase?: number;
+    svgaFrameTableSpriteBase?: number;
+    frameTableSpriteBase?: number;
+    svgaSpriteMetadataBase?: number;
+    svgaFrameTableSlotState?: Float32Array;
+    svgaSlotState?: Float32Array;
+    frameTableBuffer?: GPUBufferHandle | null;
+    frameTableFrameCount?: number;
+    frameTableSpriteCount?: number;
+    frameTableFrameIndex?: number;
+}
 export declare function alignWebGPUByteLength(byteLength: number, alignment: number): number;
 export declare class WebGPUBackend implements GPUBackend {
     readonly type: "webgpu";
+    readonly supportsAtomicFrameReplay = true;
     readonly canvas: HTMLCanvasElement;
     readonly maxTextureSize: number;
     private adapter;
@@ -21,6 +63,7 @@ export declare class WebGPUBackend implements GPUBackend {
     private dualTexturedBindGroupLayout;
     private instancedTextureBindGroupLayout;
     private uniformOnlyBindGroupLayout;
+    private svgaFrameTableBindGroupLayout;
     /** `device.limits.minUniformBufferOffsetAlignment` (typically 256). */
     private uniformSlotStride;
     /** Ring size for per-draw uniforms (`queue.writeBuffer` must not overwrite before draw — see `draw()`). */
@@ -50,6 +93,9 @@ export declare class WebGPUBackend implements GPUBackend {
     private readonly uniformScratch160;
     /** Single 128-byte upload for uniform-only draws (clip-mask: projection + transform). */
     private readonly uniformScratch128;
+    /** Projection + parent/slot state + table-info for the table-aware SVGA pipeline. */
+    private readonly svgaFrameTableUniformScratch;
+    private readonly svgaFrameTableUniformWords;
     private readonly uniformOpacityScratch;
     private depthStencilTexture;
     private depthStencilView;
@@ -85,9 +131,15 @@ export declare class WebGPUBackend implements GPUBackend {
     private dualTexturedBindGroupCache;
     /** All instanced pipelines also share one texture layout. */
     private instancedTextureBindGroupCache;
+    private particleDataBindGroupCache;
+    private motionDataBindGroupCache;
+    /** Table-aware SVGA bind groups are keyed by immutable frame-table + metadata ids. */
+    private svgaFrameTableDataBindGroupCache;
     /** Batched SVGA sprites (pre-scaled affine, UVs, and packed framebuffer clip rect). */
     private static readonly SVGA_INSTANCED_MAX;
     private static readonly SVGA_INSTANCED_STRIDE;
+    private static readonly SVGA_FRAME_TABLE_INSTANCE_MAX;
+    private static readonly SVGA_FRAME_TABLE_ROW_BYTES;
     private static readonly CLIP_MASK_INSTANCED_MAX;
     private static readonly CLIP_MASK_INSTANCED_STRIDE;
     /** Batched alpha-video (storage instances + projection uniform). */
@@ -95,6 +147,7 @@ export declare class WebGPUBackend implements GPUBackend {
     private static readonly ALPHA_INSTANCED_STRIDE;
     private static readonly VAP_INSTANCED_MAX;
     private static readonly VAP_INSTANCED_STRIDE;
+    private static readonly PARTICLE_INSTANCED_MAX;
     /**
      * 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.
@@ -105,6 +158,9 @@ export declare class WebGPUBackend implements GPUBackend {
     private storageBindOffsetAlign;
     /** Reset in `beginFrame`; all instanced draw types reserve non-overlapping chunks. */
     private instancedStorageRingOffset;
+    private svgaCompactSlotStateUploadId;
+    private svgaCompactSlotStateStorageBase;
+    private svgaCompactSlotStateByteLength;
     /** Grow-only CPU mirror; expands to the frame's actual storage high-water mark. */
     private instancedStorageShadow;
     private instancedStorageShadowDirtyMax;
@@ -118,6 +174,23 @@ export declare class WebGPUBackend implements GPUBackend {
     private performanceBufferWriteBytes;
     private performanceStorageBufferWrites;
     private performanceStorageBufferWriteBytes;
+    private performanceSubmittedDrawCalls;
+    private performanceRejectedDrawCalls;
+    private performanceSVGADynamicUploadWrites;
+    private performanceSVGADynamicUploadBytes;
+    private runtimeSubmittedDrawCalls;
+    private runtimeRejectedDrawCalls;
+    private currentDrawResult;
+    private currentDrawRecorded;
+    private runtimeUncapturedErrors;
+    private runtimeBackendLosses;
+    private runtimeDiagnosticHandler;
+    private deviceLost;
+    /** An uncaptured validation/submission error can surface after queue.submit(). */
+    private uncapturedErrorRequiresQuarantine;
+    private deviceLostHandler;
+    private readonly handleDeviceLoss;
+    private readonly handleUncapturedError;
     constructor(canvas: HTMLCanvasElement, adapter: GPUAdapter, wantAntialias?: boolean);
     init(): Promise<void>;
     private configureCanvasContext;
@@ -131,6 +204,16 @@ export declare class WebGPUBackend implements GPUBackend {
     private ensureInstancedClipMaskPipeline;
     private ensureInstancedAlphaPipeline;
     private ensureInstancedVapPipeline;
+    /**
+     * Lazily creates the table-aware SVGA pipeline. The frame table and sprite
+     * metadata are immutable storage buffers; only the slot/global uniform uses
+     * the per-draw dynamic uniform ring.
+     */
+    private ensureSVGAFrameTableDataLayout;
+    private ensureSVGAFrameTablePipeline;
+    private ensureSVGAFrameTableMeshPipeline;
+    private ensureMotionSvgaPipeline;
+    private ensureParticlePipeline;
     private createInstancedSvgaPipeline;
     private createInstancedClipMaskPipeline;
     private createVapInstancedPipeline;
@@ -139,15 +222,34 @@ export declare class WebGPUBackend implements GPUBackend {
     private createClipMaskPipeline;
     beginFrame(options?: {
         stencil?: boolean;
-    }): void;
-    endFrame(): void;
+    }): BackendOperationResult;
+    endFrame(): BackendOperationResult;
+    abortFrame(): BackendOperationResult;
+    private errorMessage;
     getPerformanceSnapshot(): {
         bufferWrites: number;
         bufferWriteBytes: number;
         storageBufferWrites: number;
         storageBufferWriteBytes: number;
+        submittedDrawCalls: number;
+        rejectedDrawCalls: number;
+        svgaDynamicUploadWrites: number;
+        svgaDynamicUploadBytes: number;
     };
     resetPerformanceSnapshot(): void;
+    getRuntimeDiagnosticsSnapshot(): {
+        submittedDrawCalls: number;
+        rejectedDrawCalls: number;
+        webgpuUncapturedErrors: number;
+        backendLosses: number;
+    };
+    setRuntimeDiagnosticHandler(handler: ((event: {
+        type: 'gpu-uncaptured-error' | 'backend-lost';
+        message?: string;
+    }) => void) | null): void;
+    setDeviceLostHandler(handler: (() => void) | null): void;
+    private recordSubmittedDraw;
+    private rejectSVGAFastPathDraw;
     private writeBuffer;
     /** Uploads the touched range of `uniformShadow` in one call — must run before `queue.submit`. */
     private flushUniformShadow;
@@ -161,6 +263,17 @@ export declare class WebGPUBackend implements GPUBackend {
     private bufferSourceByteLength;
     private mappedUploadView;
     private writeBufferSource;
+    /**
+     * Creates an immutable, long-lived SVGA frame table in device-local storage.
+     *
+     * The table is deliberately not allocated from the per-frame instanced ring:
+     * the same decoded entity can be used by many slots and should be uploaded
+     * once, then referenced by every table-aware draw until the entity is released.
+     * The table layout is three vec4 values (48 bytes) per sprite/frame row.
+     */
+    createSVGAFrameTable(data: Float32Array, options: SVGAFrameTableCreateOptions): SVGAFrameTableBinding;
+    /** Releases a table created by {@link createSVGAFrameTable}. */
+    deleteSVGAFrameTable(binding: SVGAFrameTableBinding): void;
     createBuffer(data: GPUBufferSource, usage: BufferUsage): GPUBufferHandle;
     updateBuffer(handle: GPUBufferHandle, data: GPUBufferSource, offset?: number): void;
     deleteBuffer(handle: GPUBufferHandle): void;
@@ -186,10 +299,23 @@ export declare class WebGPUBackend implements GPUBackend {
     private copyVideoFrameToTextureRegionDirect;
     private drawVideoLikeSourceToTextureRegion;
     deleteTexture(handle: GPUTextureHandle): void;
-    draw(cmd: DrawCommand): void;
+    draw(cmd: DrawCommand): BackendOperationResult;
+    private drawInternal;
     /** One `drawIndexed` with `instanceCount` for all SVGA sprites sharing the same atlas. */
     private drawInstancedSvga;
     private drawInstancedClipMask;
+    /**
+     * Draws table-aware SVGA sprites. The frame table and sprite metadata are
+     * resident storage buffers. `instanceCount` is the number of sprites in
+     * this slot/page draw, while the GPU builtin instance index selects the
+     * metadata record; the animation path never uploads N sprite records per
+     * frame. A malformed command returns so the caller can use CPU fallback.
+     */
+    private drawSVGAFrameTableInstanced;
+    private resolveSVGAFrameTableSlotUniform;
+    private reserveSVGAFrameTableUniform;
+    private drawMotionInstancedSvga;
+    private drawInstancedParticles;
     /** One `drawIndexed` with `instanceCount` for all gifts sharing the same video texture (e.g. atlas). */
     private drawInstancedAlpha;
     private drawInstancedVap;

package/dist/index.d.ts

@@ -1,27 +1,36 @@
-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';
+export { GiftStage } from './core/gift-stage.js';
+export { RenderManager } from './core/render-manager.js';
+export { AudioManager } from './core/audio-manager.js';
+export { PostAnimator } from './core/post-animator.js';
+export { PlaybackScopeImpl } from './plugin/playback-scope.js';
+export { MotionTrackLeaseImpl } from './plugin/motion-track.js';
+export { MOTION_TRACK_SAMPLE_FLOATS } from './plugin/types.js';
+export { WebGL2Backend } from './gpu/webgl2-backend.js';
+export { WebGL1Backend } from './gpu/webgl1-backend.js';
+export { WebGPUBackend } from './gpu/webgpu-backend.js';
+export { createBackend } from './gpu/detect.js';
+export { SVGABatchRenderer } from './renderers/svga-batch-renderer.js';
+export { VAPRenderer } from './renderers/vap-renderer.js';
+export { AlphaVideoRenderer } from './renderers/alpha-video-renderer.js';
+export { ImageRenderer } from './renderers/image-renderer.js';
+export { ParticleBatchRenderer } from './renderers/particle-batch-renderer.js';
+export { buildBatchVerticesJS } from './renderers/vertex-builder.js';
+export { parseSVGA } from './parsers/svga-parser.js';
+export type { ParseSVGAOptions } from './parsers/svga-parser.js';
+export { buildAtlas } from './parsers/atlas-builder.js';
+export { parseVAPConfig } from './parsers/vap-config-parser.js';
+export { inflateJS } from './parsers/inflate-js.js';
+export { decodeSVGAProto } from './parsers/svga-proto-js.js';
+export * from './utils/easing.js';
+export { ortho, lerp, clamp, generateId } from './utils/math.js';
+export { BufferPool } from './utils/buffer-pool.js';
+export { analyzeSVGAFrameTimelineEligibility, countSVGASpriteAtlasPages, estimateSVGAFrameTableBytes, isSVGAFrameTableBudgetAvailable, isSVGAFrameTableWithinBudget, packSVGASpriteMetadata, packSVGAFrameDataToVec4, packSVGAFrameTable, SVGA_FRAME_TABLE_BUDGET_BYTES, SVGA_FRAME_TABLE_FLOATS, SVGA_GPU_FRAME_TABLE_BUDGET_BYTES, SVGA_SPRITE_METADATA_FLAG_MISSING_RECT, SVGA_SPRITE_METADATA_FLOATS, } from './utils/svga-frame-timeline.js';
+export type { SVGAFrameTimelineEligibility, SVGAFrameTimelineEligibilityInput } from './utils/svga-frame-timeline.js';
+export type { SVGASpriteMetadataPackOptions } from './utils/svga-frame-timeline.js';
+export { buildSVGAHybridCommandTable, SVGA_HYBRID_OP_TEXTURE, SVGA_HYBRID_OP_SHAPE, SVGA_HYBRID_OP_CLIP_WRITE, SVGA_HYBRID_OP_CLIP_TEST, SVGA_HYBRID_OP_CLIP_CLEAR, } from './utils/svga-hybrid-command-table.js';
+export { canWebGPU, canWebGL2, canWebGL1, canSharedArrayBuffer } from './utils/detect.js';
+export { initWasm, isWasmReady } from './wasm/wasm-bridge.js';
+export { WebCodecsMp4Playback } from './video/webcodecs-mp4-playback.js';
+export type { WebCodecsMp4CreateOptions } from './video/webcodecs-mp4-playback.js';
+export type { WebCodecsPlaybackHandle, GPUBackend, BackendOperationFailureReason, BackendOperationResult, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, ShaderType, BackendType, ParentMotionMode, SVGADrawBatchMode, SVGAFrameEvaluation, SVGAFrameEvaluationStrategy, SVGAFrameTableBinding, SVGAFrameTableBindingBase, SVGAFrameTableCreateOptions, SVGAFrameTableState, SVGAFrameTimelineFallbackReason, SVGAFrameTimelinePath, SVGAFrameTimelineRenderInfo, SVGAFrameTimelineStrategy, SVGAFrameTimelineTransport, SVGARenderFallbackReason, SVGARenderInfo, SVGARenderPath, SVGARenderPathState, SVGARenderPathChangeInfo, GiftStageRuntimeDiagnosticType, GiftStageRuntimeDiagnosticEvent, GiftStageRuntimeDiagnostics, SVGAHybridCommandTable, SVGAHybridOperation, SVGAHybridOperationType, SVGATimelineDrawRun, WebGL2FrameTableBinding, WebGPUFrameTableBinding, 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/index.js';
+export type { GiftAssetLease, GiftAssetMetadata, GiftStageCapabilities, SVGAFrameTimelineCapabilities, GiftStagePlugin, GiftStagePluginHost, MountedGiftStagePlugin, MotionBindingOptions, MotionTrackDescriptor, MotionTrackLease, ParticleBatchDescriptor, ParticleBatchHandle, PlaybackFrame, PlaybackScope, PlaybackScopeStartOptions, PlaybackScopeState, ReadonlyTableDescriptor, ReadonlyTableLease, } from './plugin/types.js';

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

@@ -1,4 +1,4 @@
-import type { GPUBackend, GPUTextureHandle, UVRect } from '../types';
+import type { GPUBackend, GPUTextureHandle, UVRect } from '../types/index.js';
 export interface AtlasPageResult {
     textureHandle: GPUTextureHandle;
     atlasWidth: number;

package/dist/parsers/index.d.ts

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

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

@@ -2,7 +2,7 @@
  * 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';
+import type { SVGAMovieEntity, SVGASpriteTable } from '../types/index.js';
 export interface SVGAParserWorkerOptions {
     profile?: boolean;
     workerTimeSliceMs?: number;

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

@@ -1,4 +1,4 @@
-import type { SVGAMovieEntity } from '../types';
+import type { SVGAMovieEntity } from '../types/index.js';
 export interface ParseResult {
     movie: SVGAMovieEntity;
     imageBitmaps: Map<string, ImageBitmap>;

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

@@ -3,5 +3,5 @@
  * Falls back to this when WASM is unavailable.
  * Implements just enough proto2 wire format to decode the SVGA schema.
  */
-import type { SVGAMovieEntity } from '../types';
+import type { SVGAMovieEntity } from '../types/index.js';
 export declare function decodeSVGAProto(data: Uint8Array): SVGAMovieEntity;

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

@@ -1,7 +1,7 @@
 /**
  * Shared SoA sprite-table binary section (SGPB v2 / SGBC v14).
  */
-import type { SVGASpriteTable } from '../types';
+import type { SVGASpriteTable } from '../types/index.js';
 declare function align4(offset: number): number;
 export interface SpriteTableBinaryWriter {
     u8(value: number): void;

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

@@ -2,7 +2,7 @@
  * 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 { SVGAParams, SVGAShape, SVGATransform } from '../types';
+import type { SVGAParams, SVGAShape, SVGATransform } from '../types/index.js';
 /** Floats per frame in `frameData`: layoutW, layoutH, a, b, c, d, tx, ty, alpha. */
 export declare const SPRITE_FRAME_FLOATS = 9;
 export interface SVGASpriteTable {

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

@@ -1,6 +1,6 @@
-import type { SVGAMovieEntity } from '../types';
-import type { SVGAWorkerMoviePayload } from './svga-parser-worker-client';
-import { type SpriteTableCheckpoint } from './svga-sprite-table-binary';
+import type { SVGAMovieEntity } from '../types/index.js';
+import type { SVGAWorkerMoviePayload } from './svga-parser-worker-client.js';
+import { type SpriteTableCheckpoint } from './svga-sprite-table-binary.js';
 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;