@taole/giftstage 0.1.36 → 0.2.2

package/dist/types/index.d.ts

@@ -1,5 +1,65 @@
 export type BackendType = 'webgpu' | 'webgl2' | 'webgl1';
-export type BufferUsage = 'vertex' | 'index' | 'uniform';
+/**
+ * How an SVGA slot obtains its per-frame transform/alpha state.
+ *
+ * `gpu-direct` evaluates the complete atlas-sprite frame row in the vertex
+ * shader. `gpu-hybrid` keeps the same GPU frame-table evaluation but lets the
+ * CPU precompile/schedule shape and clip draws. `cpu-reference` is the
+ * deterministic compatibility path.
+ */
+export type SVGARenderPath = 'gpu-direct' | 'gpu-hybrid' | 'cpu-reference';
+export type SVGAFrameTimelinePath = SVGARenderPath;
+/** Public policy used by the stage and by an individual gift. */
+export type SVGAFrameEvaluation = 'auto' | 'cpu';
+/** Descriptive alias used by utility APIs. GPU selection is intentionally auto-only. */
+export type SVGAFrameEvaluationStrategy = SVGAFrameEvaluation;
+export type SVGAFrameTimelineStrategy = SVGAFrameEvaluation;
+export type SVGAFrameTimelineTransport = 'storage-buffer' | 'float-texture' | 'unavailable';
+export type ParentMotionMode = 'gpu-table' | 'cpu-reference';
+export type SVGARenderPathState = 'preparing' | 'settled' | 'fallback';
+export type SVGADrawBatchMode = 'multi-slot' | 'per-slot' | 'hybrid-scheduled';
+/** Why a slot did not use the direct SVGA GPU frame-table path. */
+export type SVGARenderFallbackReason = 'device-capability' | 'table-too-large-or-budget' | 'table-preparing' | 'upload-failed' | 'slot-overrides' | 'plan-not-ready-or-unsupported' | 'validation-failed' | 'policy-disabled';
+export type SVGAFrameTimelineFallbackReason = SVGARenderFallbackReason;
+export type GiftStageRuntimeDiagnosticType = 'svga-frame-abort' | 'svga-frame-replay-failed' | 'svga-frame-retry' | 'svga-runtime-fallback' | 'gpu-uncaptured-error' | 'backend-lost' | 'observer-error' | 'clip-protocol-error' | 'clip-mesh-invalid' | 'stencil-transaction-failure' | 'backend-operation-rejected' | 'atlas-command-invalid' | 'backend-quarantined';
+/** One production-safe runtime event. GiftStage never uploads these events. */
+export interface GiftStageRuntimeDiagnosticEvent {
+    type: GiftStageRuntimeDiagnosticType;
+    timestampMs: number;
+    backend: BackendType;
+    source?: string | null;
+    giftIds?: string[];
+    reason?: SVGAFrameTimelineFallbackReason;
+    message?: string;
+}
+/** Monotonic diagnostics accumulated for one GiftStage lifetime. */
+export interface GiftStageRuntimeDiagnostics {
+    backend: BackendType;
+    frameAbortCount: number;
+    replayFailureCount: number;
+    retryFrameCount: number;
+    runtimeFallbackCount: number;
+    submittedDrawCalls: number;
+    rejectedDrawCalls: number;
+    webgpuUncapturedErrorCount: number;
+    backendLossCount: number;
+    observerErrorCount: number;
+    lastEvent: GiftStageRuntimeDiagnosticEvent | null;
+}
+export type BufferUsage = 'vertex' | 'index' | 'uniform' | 'storage';
+/** Stable reason reported when a backend operation cannot be completed. */
+export type BackendOperationFailureReason = 'backend-lost' | 'invalid-command' | 'missing-resource' | 'capacity' | 'validation-error' | 'submission-error';
+/**
+ * Explicit result for frame and draw operations. Built-in backends reuse the
+ * successful singleton, so the hot draw path does not allocate per command.
+ */
+export type BackendOperationResult = {
+    readonly submitted: true;
+} | {
+    readonly submitted: false;
+    readonly reason: BackendOperationFailureReason;
+    readonly message?: string;
+};
 export type GPUBufferSource = ArrayBufferLike | ArrayBufferView;
 export interface GPUBufferHandle {
     readonly id: number;
@@ -10,6 +70,110 @@ export interface GPUTextureHandle {
     readonly width: number;
     readonly height: number;
 }
+/** Packed SVGA frame-table layout consumed by the production GPU FastPaths. */
+export declare const SVGA_FRAME_TABLE_FLOATS = 12;
+/** Default cap for one resident SVGA frame table (32 MiB). */
+export declare const SVGA_GPU_FRAME_TABLE_BUDGET_BYTES: number;
+/** Backward/descriptive alias; use the GPU-prefixed name in stage options. */
+export declare const SVGA_FRAME_TABLE_BUDGET_BYTES: number;
+/** Floats per sprite in the immutable UV/page metadata table. */
+export declare const SVGA_SPRITE_METADATA_FLOATS = 8;
+/** Three vec4 values per sparse Hybrid operation, including an optional local clip rect. */
+export declare const SVGA_HYBRID_SPRITE_METADATA_FLOATS = 12;
+export interface SVGAFrameTableCreateOptions {
+    /** Number of logical sprites represented by the table. */
+    spriteCount: number;
+    /** Number of frames represented for each sprite. */
+    frameCount: number;
+    /** One packed 2-vec4 row per sprite: uvMin/uvMax and atlasPage/flags. */
+    spriteMetadata?: Float32Array;
+    /** Operation-ordered metadata used by sparse Hybrid texture runs. */
+    hybridSpriteMetadata?: Float32Array;
+    /** Compatibility alias for backend adapters during the migration. */
+    metadata?: Float32Array;
+    /** Optional pre-created metadata texture for a WebGL2 adapter. */
+    metadataTexture?: GPUTextureHandle;
+    /** Number of atlas pages represented by `spriteMetadata`. */
+    atlasPageCount?: number;
+    /** Optional backend/debug label. */
+    label?: string;
+}
+export interface SVGAFrameTableBindingBase {
+    readonly spriteCount: number;
+    readonly frameCount: number;
+    /** Set by the backend when metadata/table planning knows the page count. */
+    readonly atlasPageCount?: number;
+    /** Packed row width. Always three vec4 values / twelve floats. */
+    readonly strideFloats: typeof SVGA_FRAME_TABLE_FLOATS;
+    readonly byteLength: number;
+}
+/** WebGPU stores the packed rows in a storage buffer. */
+export interface WebGPUFrameTableBinding extends SVGAFrameTableBindingBase {
+    readonly backend: 'webgpu';
+    readonly kind: 'webgpu-buffer';
+    readonly buffer: GPUBufferHandle;
+    readonly spriteMetadataBuffer?: GPUBufferHandle;
+    readonly hybridSpriteMetadataBuffer?: GPUBufferHandle;
+}
+/** WebGL2 stores the same rows in a float texture because it has no storage buffer path here. */
+export interface WebGL2FrameTableBinding extends SVGAFrameTableBindingBase {
+    readonly backend: 'webgl2';
+    readonly kind: 'webgl2-texture';
+    readonly texture: GPUTextureHandle;
+    readonly spriteMetadataTexture?: GPUTextureHandle;
+    readonly hybridSpriteMetadataTexture?: GPUTextureHandle;
+    /** Width/height in texels when a backend uses a packed 2D table texture. */
+    readonly textureWidth?: number;
+    readonly textureHeight?: number;
+}
+export type SVGAFrameTableBinding = WebGPUFrameTableBinding | WebGL2FrameTableBinding;
+/** Public diagnostic state shared by an asset and its active slots. */
+export interface SVGARenderInfo {
+    selectedPath: SVGARenderPath;
+    /** Explicit alias for the actual core SVGA frame path. */
+    svgaFramePath?: SVGARenderPath;
+    /** Actual parent-track evaluator when a playback scope has bound one. */
+    parentMotionMode?: ParentMotionMode;
+    backend: BackendType;
+    requested: SVGAFrameEvaluation;
+    spriteCount: number;
+    frameCount: number;
+    /** Number of simultaneously compatible instances included by the planner. */
+    compatibleInstanceCount: number;
+    /** Number of atlas pages referenced by the planned resource. */
+    atlasPageCount: number;
+    tableBytes: number;
+    /** Resident immutable child-frame table bytes. */
+    frameTableBytes?: number;
+    /** Resident immutable Hybrid command-table bytes. Zero for Direct. */
+    commandTableBytes?: number;
+    budgetBytes: number;
+    pathState?: SVGARenderPathState;
+    drawBatchMode?: SVGADrawBatchMode;
+    /** Instances that are compatible with the draw batch containing this slot. */
+    drawCompatibleInstanceCount?: number;
+    /** Present when the direct path was rejected or policy selected a fallback. */
+    fallbackReasons: SVGARenderFallbackReason[];
+    /** Primary fallback reason, when the selected path is CPU reference. */
+    fallbackReason?: SVGAFrameTimelineFallbackReason;
+}
+export interface SVGARenderPathChangeInfo extends SVGARenderInfo {
+    giftId: string;
+}
+/** Extended diagnostic shape retained for the frame-table planner. */
+export interface SVGAFrameTimelineRenderInfo extends SVGARenderInfo {
+    /** Alias for `selectedPath` used by frame-table-specific callers. */
+    path: SVGAFrameTimelinePath;
+    /** Alias for `requested` used by frame-table-specific callers. */
+    requestedStrategy: SVGAFrameEvaluation;
+}
+/** Runtime frame-table state. The binding is null until GPU allocation completes. */
+export interface SVGAFrameTableState {
+    binding: SVGAFrameTableBinding | null;
+    renderInfo: SVGAFrameTimelineRenderInfo;
+    currentTimeMs: number;
+    frameIndex: number;
+}
 export interface TextureOpts {
     width?: number;
     height?: number;
@@ -27,7 +191,11 @@ export interface TextureOpts {
 }
 export type ShaderType = 'svga-batch-premul'
 /** WebGPU / WebGL2: SVGA premultiplied atlas sprites batched as packed instances. */
- | 'svga-instanced-premul' | 'vap'
+ | 'svga-instanced-premul' | 'svga-motion-instanced-premul'
+/** GPU frame-table path; backend-specific fields carry slot state. */
+ | 'svga-frame-table-instanced-premul' | 'svga-frame-table-shape-premul' | 'svga-frame-table-clip-mask'
+/** Migration alias used by the table-aware renderer. */
+ | 'svga-timeline-instanced-premul' | 'vap'
 /** Main-context VAP mixed resource draw: resource texture multiplied by raw-video mask. */
  | 'vap-mix-overlay'
 /** WebGPU / WebGL2: batched VAP sharing one texture; see `instanceCount` / `instanceData` (32 floats/instance). */
@@ -35,7 +203,9 @@ export type ShaderType = 'svga-batch-premul'
 /** WebGPU: batched draws sharing one texture (e.g. atlas); see `instanceCount` / `instanceData`. */
  | 'alpha-video-instanced' | 'rgba-textured' | 'clip-mask'
 /** WebGPU / WebGL2: one local-space clip mesh transformed by per-instance affine data. */
- | 'clip-mask-instanced';
+ | 'clip-mask-instanced'
+/** WebGPU / WebGL2: immutable ballistic particle instances evaluated in the vertex shader. */
+ | 'particle-instanced';
 export type StencilMode = 'none' | 'write' | 'test' | 'clear';
 export interface DrawCommand {
     shader: ShaderType;
@@ -55,24 +225,93 @@ export interface DrawCommand {
      * (mat4 + atlasRemap + rgb/alpha rects + opacity/source-alpha-mode vec4).
      * `clip-mask-instanced`: the first `instanceCount * 6` floats are consumed
      * (a, b, c, d, tx, ty affine transform).
+     * `svga-frame-table-instanced-premul` may carry `instanceCount * 16`
+     * floats for Hybrid batches spanning multiple slots (parent affine,
+     * translate/opacity/frame, clip rect, metadata row/page). The SVGA-local
+     * transform and alpha still come from the resident GPU frame table.
      * Renderers may pass a larger reused scratch array to avoid allocating a subarray view per draw.
      */
     instanceCount?: number;
     instanceData?: Float32Array;
+    /** Persistent instance table used by particle batches; avoids re-uploading immutable particles per frame. */
+    instanceBuffer?: GPUBufferHandle;
+    particleBlend?: 'normal' | 'additive';
+    motionTrackBuffer?: GPUBufferHandle;
+    motionTrackGlobalsBuffer?: GPUBufferHandle;
+    motionTrackSampleCount?: number;
+    motionTrackSampleIntervalMs?: number;
+    motionTrackTimeMs?: number;
+    motionTrackCssScaleX?: number;
+    motionTrackCssScaleY?: number;
+    /** Parent MotionTrack row selected for this slot; omitted when no parent track is bound. */
+    motionTrackIndex?: number;
+    /**
+     * O(slot) SVGA frame-table state. Immutable frame rows and sprite metadata
+     * live in the binding; only the current slot/frame state belongs here.
+     */
+    svgaFrameTable?: SVGAFrameTableBinding | GPUBufferHandle | GPUTextureHandle | null;
+    svgaFrameTableBuffer?: GPUBufferHandle | null;
+    svgaFrameTableTexture?: GPUTextureHandle | null;
+    svgaSpriteMetadata?: GPUBufferHandle | GPUTextureHandle | null;
+    svgaSpriteMetadataBuffer?: GPUBufferHandle | null;
+    svgaSpriteMetadataTexture?: GPUTextureHandle | null;
+    /** Float stride of the selected metadata table; Direct=8, Hybrid=12. */
+    svgaSpriteMetadataStrideFloats?: number;
+    /** Canonical table-aware slot fields. */
+    svgaFrameIndex?: number;
+    svgaSpriteBase?: number;
+    /** [parent a,b,c,d,tx,ty,opacity,clip x0,y0,x1,y1]. */
+    svgaSlotState?: Float32Array;
+    svgaFrameTableFrameCount?: number;
+    svgaFrameTableSpriteCount?: number;
+    svgaFrameTableFrameIndex?: number;
+    svgaFrameTableSpriteBase?: number;
+    svgaFrameTableAtlasPage?: number;
+    svgaFrameTableParentAffine?: Float32Array;
+    svgaFrameTableParentTranslate?: Float32Array;
+    svgaFrameTableOpacity?: number;
+    svgaFrameTableClipRect?: Float32Array;
+    /** Packed slot-state alias used by backend adapters. */
+    svgaFrameTableSlotState?: Float32Array;
+    /**
+     * Compact four-vec4 state per slot for Direct multi-slot draws. The shader
+     * derives slot/sprite indices from the GPU instance index, so this array is
+     * uploaded once per slot rather than once per visible sprite.
+     */
+    svgaFrameTableSlotStates?: Float32Array;
+    svgaFrameTableSlotStateCount?: number;
+    svgaFrameTableSpritesPerSlot?: number;
+    /** Monotonic renderer token allowing backends to upload one compact slot block once per frame. */
+    svgaFrameTableSlotStateUploadId?: number;
 }
 export interface GPUBackend {
     readonly type: BackendType;
     readonly canvas: HTMLCanvasElement;
     /** Maximum supported 2D texture dimension for this backend/device. */
     readonly maxTextureSize?: number;
+    /** Built-in backends set this when an unsubmitted frame can be discarded and replayed. */
+    readonly supportsAtomicFrameReplay?: boolean;
     init(): Promise<void>;
     beginFrame(options?: {
         stencil?: boolean;
-    }): void;
-    endFrame(): void;
+    }): BackendOperationResult;
+    endFrame(): BackendOperationResult;
+    /** Discards the current unsubmitted frame. */
+    abortFrame(): BackendOperationResult;
     createBuffer(data: GPUBufferSource, usage: BufferUsage): GPUBufferHandle;
     updateBuffer(handle: GPUBufferHandle, data: GPUBufferSource, offset?: number): void;
     deleteBuffer(handle: GPUBufferHandle): void;
+    /**
+     * Creates a resident packed SVGA frame table. Implementations may use a
+     * WebGPU storage buffer or a WebGL2 float texture; older backends can omit
+     * this optional capability and remain on the CPU reference path.
+     *
+     * `packedData` contains `spriteCount × frameCount` rows of three vec4s
+     * (twelve floats per row), as produced by `packSVGAFrameTable`.
+     */
+    createSVGAFrameTable?(packedData: Float32Array, options: SVGAFrameTableCreateOptions): SVGAFrameTableBinding;
+    /** Releases a frame table returned by `createSVGAFrameTable`. */
+    deleteSVGAFrameTable?(binding: SVGAFrameTableBinding): void;
     createTexture(source: TexImageSource | ArrayBuffer, opts: TextureOpts): GPUTextureHandle;
     /** Uninitialized RGBA texture (e.g. WebCodecs atlas backing store). */
     createEmptyTexture(width: number, height: number, opts?: TextureOpts): GPUTextureHandle;
@@ -80,7 +319,7 @@ export interface GPUBackend {
     /** When `destWidth`/`destHeight` differ from source size, uploads a uniformly scaled copy into the region. */
     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;
     clearStencil?(): void;
     setScissor(x: number, y: number, w: number, h: number): void;
     resetScissor(): void;
@@ -90,9 +329,28 @@ export interface GPUBackend {
         bufferWriteBytes: number;
         storageBufferWrites: number;
         storageBufferWriteBytes: number;
+        /** Draw calls that reached the backend's native drawElements/drawIndexed call. */
+        submittedDrawCalls?: number;
+        /** Draw calls rejected by backend validation before native submission. */
+        rejectedDrawCalls?: number;
+        /** Dynamic SVGA CPU-reference/slot-state uploads performed by the backend. */
+        svgaDynamicUploadWrites?: number;
+        svgaDynamicUploadBytes?: number;
     };
     /** Resets the internal performance-harness diagnostics for a new sampling window. */
     resetPerformanceSnapshot?(): void;
+    /** Monotonic production diagnostics; unlike performance counters these are never reset. */
+    getRuntimeDiagnosticsSnapshot?(): {
+        submittedDrawCalls: number;
+        rejectedDrawCalls: number;
+        webgpuUncapturedErrors: number;
+        backendLosses: number;
+    };
+    /** Internal bridge used by GiftStage to surface asynchronous backend faults. */
+    setRuntimeDiagnosticHandler?(handler: ((event: {
+        type: 'gpu-uncaptured-error' | 'backend-lost';
+        message?: string;
+    }) => void) | null): void;
     destroy(): void;
 }
 export interface SVGAParams {
@@ -186,6 +444,12 @@ export interface UVRect {
     /** Atlas page index. Omitted means page 0 for older single-atlas data. */
     textureIndex?: number;
 }
+/** Consecutive sprite range that can share one atlas-page draw. */
+export interface SVGATimelineDrawRun {
+    spriteBase: number;
+    spriteCount: number;
+    textureIndex: number;
+}
 export interface VideoEntity {
     params: SVGAParams;
     spriteTable: SVGASpriteTable;
@@ -194,6 +458,39 @@ export interface VideoEntity {
     atlasTextureHandles?: GPUTextureHandle[];
     atlasRects: Map<string, UVRect>;
     audioBuffers: Map<string, ArrayBuffer>;
+    /** Shared immutable GPU frame table for this parsed SVGA asset, when eligible. */
+    svgaFrameTableState?: SVGAFrameTableState | null;
+    /** Resource-level draw plan preserving sprite order across atlas pages. */
+    svgaTimelineDrawRuns?: SVGATimelineDrawRun[];
+    /** Immutable Hybrid paint schedule; populated before atomic GPU promotion. */
+    svgaHybridCommandTable?: SVGAHybridCommandTable;
+}
+export type SVGAHybridOperationType = 'texture' | 'shape' | 'clip-write' | 'clip-test' | 'clip-clear';
+export interface SVGAHybridOperation {
+    type: SVGAHybridOperationType;
+    spriteIndex: number;
+    atlasPage: number;
+    shapeIndex: number;
+    clipPathIndex: number;
+}
+/** Resource-level immutable, frame-addressable Hybrid paint schedule. */
+export interface SVGAHybridCommandTable {
+    frameOffsets: Uint32Array;
+    /** Canonical ID for structurally identical frame command slices. */
+    frameScheduleIds: Uint32Array;
+    /** Numeric SVGAHybridOperationType code per operation. */
+    operations: Uint8Array;
+    spriteIndices: Uint32Array;
+    /** shapeIndex, clipPathIndex, atlasPage packed as three i32 values per operation. */
+    meshReferences: Int32Array;
+    /** UV/page/source-sprite rows in operation order for immutable sparse texture draws. */
+    spriteMetadata: Float32Array;
+    /** Frame-addressable immutable execution runs over the operation arrays. */
+    runFrameOffsets: Uint32Array;
+    runOperationStarts: Uint32Array;
+    runOperationCounts: Uint32Array;
+    runTypes: Uint8Array;
+    byteLength: number;
 }
 export declare const FRAME_DATA_FLOATS = 13;
 export declare const VERTEX_FLOATS = 9;
@@ -321,6 +618,8 @@ export interface SVGAStaticBatchCache {
     width: number;
     height: number;
     scale: number;
+    motionScaleX: number;
+    motionScaleY: number;
     rotation: number;
     sx: number;
     sy: number;
@@ -480,6 +779,14 @@ export interface GiftStageOptions {
      * Default: 2; the worker may temporarily reduce concurrency under load.
      */
     svgaWorkerImageDecodeConcurrency?: number;
+    /**
+     * SVGA frame-animation policy. `auto` selects the GPU direct/hybrid path
+     * when the backend and table budget allow it; `cpu` disables frame-table
+     * allocation. Default: `auto`.
+     */
+    svgaFrameEvaluation?: SVGAFrameEvaluation;
+    /** Global active-table budget for SVGA GPU frame evaluation. Default: 32 MiB. */
+    svgaGpuFrameTableBudgetBytes?: number;
     /**
      * Emit one structured parser profile for each actual SVGA parse. Default:
      * false. Cache hits do not emit a profile.
@@ -501,6 +808,10 @@ export interface GiftStageOptions {
      * Default: true.
      */
     svgaClipPrewarmInWorker?: boolean;
+    /** Called when a gift's selected SVGA rendering path changes. */
+    onSVGARenderPathChange?: (info: SVGARenderPathChangeInfo) => void;
+    /** Receives production runtime diagnostics. GiftStage does not upload these events. */
+    onRuntimeDiagnostic?: (event: GiftStageRuntimeDiagnosticEvent) => void;
     /**
      * Global web-side concurrent resource pipeline limit (download / parse / image decode).
      * Omit to auto-derive from `navigator.hardwareConcurrency`.
@@ -512,9 +823,20 @@ export interface GiftStageOptions {
 export interface AddGiftOptions {
     type: GiftType;
     source: string | ArrayBuffer;
+    /** Abort pending decode/upload work without affecting other consumers of the same shared asset. */
+    signal?: AbortSignal;
+    /** Keep media and its timeline paused until the caller explicitly resumes the returned handle. */
+    startPaused?: boolean;
+    /**
+     * @internal PlaybackScope owns this gift's media clock and seeks it from the
+     * shared absolute timeline. Ordinary RenderManager deltas must not advance it.
+     */
+    playbackScopeControlled?: boolean;
     config?: string | object;
     /** SVGA imageKey -> replacement source (TexImageSource or generated text). */
     svgaSlots?: Record<string, SVGASlotContent>;
+    /** Per-gift override for the stage-level SVGA frame-animation policy. */
+    svgaFrameEvaluation?: SVGAFrameEvaluation;
     /** VAPX srcTag/srcId -> replacement source (text string, image URL, TexImageSource, or structured text/image). */
     vapSlots?: Record<string, VAPSlotContent>;
     /**
@@ -600,6 +922,8 @@ export interface GiftHandle {
     pause(): void;
     resume(): void;
     destroy(): void;
+    /** Snapshot of the selected SVGA path and its planner diagnostics. */
+    getRenderInfo(): SVGARenderInfo | null;
     animate(options?: GiftAnimationStep | GiftAnimationStep[]): GiftAnimationChain;
 }
 export type GiftState = 'loading' | 'playing' | 'fly' | 'stopped' | 'finished';
@@ -615,13 +939,36 @@ export interface GiftSlot {
     width: number;
     height: number;
     scale: number;
+    /** Optional non-uniform parent scale supplied by a plugin motion track. */
+    motionScaleX?: number;
+    /** Optional non-uniform parent scale supplied by a plugin motion track. */
+    motionScaleY?: number;
+    /** WebGPU renderer binding for an immutable parent-motion table. */
+    motionTrackBinding?: {
+        buffer: GPUBufferHandle;
+        globalsBuffer: GPUBufferHandle;
+        trackIndex: number;
+        sampleCount: number;
+        sampleIntervalMs: number;
+        currentTimeMs: number;
+    } | null;
     opacity: number;
     rotation?: number;
     paused: boolean;
+    /** @internal True when a PlaybackScope owns the media clock. */
+    playbackScopeControlled?: boolean;
+    /** @internal Tracks the public/audio frame-0 priming contract. */
+    svgaInitialFrameEmitted?: boolean;
     currentFrame: number;
     accumulatedTime: number;
     lastTickTime: number;
     loopCount: number;
+    /** Per-instance SVGA frame-table binding and path diagnostics. */
+    svgaFrameTableState?: SVGAFrameTableState | null;
+    /** @internal Last draw batching decision, surfaced through getRenderInfo(). */
+    svgaDrawBatchMode?: SVGADrawBatchMode;
+    /** @internal Number of slots in the last compatible Direct/Hybrid batch. */
+    svgaDrawCompatibleInstanceCount?: number;
     /**
      * SVGABatchRenderer internal: most recent frame whose complete set of referenced clip meshes
      * is ready. A later frame with a mesh miss renders this frame until the missing meshes land.
@@ -629,6 +976,8 @@ export interface GiftSlot {
     svgaClipReadyFrame?: number | null;
     videoEntity: VideoEntity | null;
     loadAbortController?: AbortController | null;
+    /** Removes the caller AbortSignal bridge installed while loading. */
+    detachLoadAbortSignal?: (() => void) | null;
     /** HTMLVideoElement finite-playback watchdog; cleared on normal completion or resource release. */
     videoPlaybackWatchdogTimer?: ReturnType<typeof setTimeout> | null;
     /** Guards the HTMLVideo ended/watchdog race so completion is dispatched exactly once. */
@@ -647,6 +996,8 @@ export interface GiftSlot {
     releaseWebCodecsPlayback?: (() => void) | null;
     /** Playback time in seconds for {@link webcodecsPlayback}. */
     wcPlaybackTime: number;
+    /** Per-slot offset from a shared WebCodecs wall clock, used by playback-scope seek. */
+    wcSharedTimeOffset?: number;
     videoTextureHandle: GPUTextureHandle | null;
     imageTextureHandle?: GPUTextureHandle | null;
     releaseSharedImageTexture?: (() => void) | null;

package/dist/utils/clip-mesh.d.ts

@@ -2,5 +2,18 @@ export interface ClipMeshData {
     vertices: Float32Array;
     indices: Uint32Array;
 }
+/** Returns a stable validation failure, or null for a renderable triangle mesh. */
+export declare function validateClipMeshData(mesh: ClipMeshData): string | null;
 export type ClipMeshTriangulator = (vertices: Float64Array, polygonStarts: Uint32Array) => Uint32Array | null;
+export type ClipPathGeometryKind = 'empty' | 'fillable' | 'invalid';
+/**
+ * Classifies SVG clip geometry before mesh preparation. Canvas/SVG define a
+ * MoveTo-only, line-only, duplicate-point, or zero-area clip as an empty clip
+ * region; it must hide the sprite rather than degrade to "no clip".
+ *
+ * A non-collinear contour is deliberately reported as `fillable` even when
+ * its signed area is zero (for example a bow-tie). The triangulator/mesh
+ * validation remains authoritative for those genuinely malformed contours.
+ */
+export declare function classifyClipPathGeometry(clipPath: string): ClipPathGeometryKind;
 export declare function buildClipMeshFromPath(clipPath: string, triangulator?: ClipMeshTriangulator): ClipMeshData | null;

package/dist/utils/gift-object-fit.d.ts

@@ -1,4 +1,4 @@
-import type { GiftObjectFit, GiftSlot } from '../types';
+import type { GiftObjectFit, GiftSlot } from '../types/index.js';
 /**
  * Default when `objectFit` is omitted: all gift types use `contain` (uniform fit inside width×height).
  */
@@ -11,4 +11,4 @@ export interface GiftObjectFitLayout {
     offsetX: number;
     offsetY: number;
 }
-export declare function resolveGiftObjectFitLayout(slot: GiftSlot, contentWidth: number, contentHeight: number, out?: GiftObjectFitLayout): GiftObjectFitLayout;
+export declare function resolveGiftObjectFitLayout(slot: GiftSlot, contentWidth: number, contentHeight: number, out?: GiftObjectFitLayout, ignoreMotionScale?: boolean): GiftObjectFitLayout;

package/dist/utils/gift-transform.d.ts

@@ -1,4 +1,4 @@
-import type { GiftSlot } from '../types';
+import type { GiftSlot } from '../types/index.js';
 export interface GiftTransformOrigin {
     x: number;
     y: number;
@@ -11,6 +11,8 @@ export interface Affine2D {
     tx: number;
     ty: number;
 }
+export declare function effectiveGiftScaleX(slot: GiftSlot): number;
+export declare function effectiveGiftScaleY(slot: GiftSlot): number;
 /** Resolve the fixed local origin to stage buffer pixels for the slot's current scale. */
 export declare function resolveGiftTransformOrigin(slot: GiftSlot, out?: GiftTransformOrigin): GiftTransformOrigin;
 /**

package/dist/utils/resource-cache.d.ts

@@ -1,4 +1,4 @@
-import type { SVGAWorkerMoviePayload } from '../parsers/svga-parser-worker-client';
+import type { SVGAWorkerMoviePayload } from '../parsers/svga-parser-worker-client.js';
 type PersistKind = 'arrayBuffer' | 'text';
 type MemoryKind = PersistKind | 'json' | 'svga-payload' | 'svga-asset';
 export declare class AsyncLimiter {

package/dist/utils/slot-content.d.ts

@@ -1,4 +1,4 @@
-import type { GPUBackend, ResolvedSVGASlotTexture, ResolvedVAPResource, SVGASlotContent, VAPConfig, VAPFrameObj, VAPMixState, VAPSlotContent, VAPSrcItem, VideoEntity } from '../types';
+import type { GPUBackend, ResolvedSVGASlotTexture, ResolvedVAPResource, SVGASlotContent, VAPConfig, VAPFrameObj, VAPMixState, VAPSlotContent, VAPSrcItem, VideoEntity } from '../types/index.js';
 export declare function resolveSVGASlotTextures(backend: GPUBackend, entity: VideoEntity, slots: Record<string, SVGASlotContent> | undefined, options?: {
     frameBudgetMs?: number;
     checkActive?: () => void;

package/dist/utils/svga-binary-cache.d.ts

@@ -1,5 +1,5 @@
-import type { SVGAParams, SVGAAudio, SVGASpriteTable, UVRect } from '../types';
-import type { ClipMeshData } from './clip-mesh';
+import type { SVGAParams, SVGAAudio, SVGASpriteTable, UVRect } from '../types/index.js';
+import type { ClipMeshData } from './clip-mesh.js';
 export interface SVGACachedAsset {
     params: SVGAParams;
     spriteTable: SVGASpriteTable;

package/dist/utils/svga-frame-timeline.d.ts

@@ -0,0 +1,95 @@
+import type { BackendType, GiftObjectFit, SVGAFrameEvaluation, SVGAFrameTimelineRenderInfo, SVGASpriteTable, UVRect } from '../types/index.js';
+import { SVGA_FRAME_TABLE_BUDGET_BYTES, SVGA_FRAME_TABLE_FLOATS, SVGA_GPU_FRAME_TABLE_BUDGET_BYTES, SVGA_SPRITE_METADATA_FLOATS } from '../types/index.js';
+/** Result of the pure frame-table eligibility check. */
+export interface SVGAFrameTimelineEligibility extends SVGAFrameTimelineRenderInfo {
+    /** `true` for either GPU path; `false` means use the CPU reference path. */
+    eligible: boolean;
+}
+/**
+ * Input accepted by {@link analyzeSVGAFrameTimelineEligibility}.
+ *
+ * Callers can pass a parsed `spriteTable`, or the counts/flags directly when
+ * the asset is represented by a lightweight metadata object. Explicit flags
+ * override values read from `spriteTable`.
+ */
+export interface SVGAFrameTimelineEligibilityInput {
+    backend: BackendType;
+    spriteTable?: Pick<SVGASpriteTable, 'spriteCount' | 'frameCount' | 'frameData' | 'hasAnyShapes' | 'clipPaths' | 'clipPathIndex' | 'allFramesInsideViewBox'>;
+    spriteCount?: number;
+    frameCount?: number;
+    /** Optional source length check without retaining the full frame array. */
+    frameDataLength?: number;
+    hasAnyShapes?: boolean;
+    hasClipPaths?: boolean;
+    allFramesInsideViewBox?: boolean;
+    /** Defaults to true when omitted; false means the asset has no usable atlas. */
+    hasAtlas?: boolean;
+    hasSlotTextureOverride?: boolean;
+    objectFit?: GiftObjectFit;
+    hasTransformOrigin?: boolean;
+    strategy?: SVGAFrameEvaluation;
+    budgetBytes?: number;
+    /** Planner has not finished producing an immutable packed table yet. */
+    tablePreparing?: boolean;
+    /** Backend allocation/upload failed after validation. */
+    uploadFailed?: boolean;
+    /** Number of compatible active instances currently sharing this plan. */
+    compatibleInstanceCount?: number;
+    /** Number of atlas pages used by the asset. */
+    atlasPageCount?: number;
+}
+/**
+ * Packs the nine-float SVGA frame row into three vec4 rows.
+ *
+ * The first nine values retain the existing layout exactly:
+ * `[layoutW, layoutH, a, b]`, `[c, d, tx, ty]`, `[alpha, 0, 0, 0]`.
+ * The zero padding makes every row naturally addressable as storage-buffer
+ * vec4 data and as RGBA float texels on WebGL2.
+ */
+export declare function packSVGAFrameTable(frameData: ArrayLike<number>, output?: Float32Array): Float32Array;
+/** Descriptive alias for callers that want to emphasize the source layout. */
+export declare function packSVGAFrameDataToVec4(frameData: ArrayLike<number>, output?: Float32Array): Float32Array;
+/** Returns the byte size of a packed frame table. */
+export declare function estimateSVGAFrameTableBytes(spriteCount: number, frameCount: number, strideFloats?: number): number;
+/** Checks whether one packed table fits the default or caller-supplied cap. */
+export declare function isSVGAFrameTableWithinBudget(spriteCount: number, frameCount: number, budgetBytes?: number): boolean;
+/** Checks whether a new table can be added to the stage-wide active-table budget. */
+export declare function isSVGAFrameTableBudgetAvailable(activeBytes: number, spriteCount: number, frameCount: number, budgetBytes?: number): boolean;
+export interface SVGASpriteMetadataPackOptions {
+    /** Atlas page dimensions in texels, used to normalize UV rectangles. */
+    atlasPageSizes?: ReadonlyArray<{
+        width: number;
+        height: number;
+    }>;
+    /** Used when all rectangles belong to one known page. */
+    fallbackPageSize?: {
+        width: number;
+        height: number;
+    };
+}
+/** Metadata flags stored in the second vec4's `flags` component. */
+export declare const SVGA_SPRITE_METADATA_FLAG_MISSING_RECT = 1;
+/** Hybrid operation carries an axis-aligned clip rectangle in its third vec4. */
+export declare const SVGA_SPRITE_METADATA_FLAG_LOCAL_RECT_CLIP = 2;
+/**
+ * Packs one two-vec4 metadata row for every SVGA sprite.
+ *
+ * `imageKeys` is the sprite-table order and `atlasRects` uses GiftStage's
+ * normalized UV convention. The second vec4 stores
+ * `[sourceSpriteIndex, atlasPage, flags, 0]`.
+ */
+export declare function packSVGASpriteMetadata(imageKeys: readonly string[], atlasRects: ReadonlyMap<string, UVRect>, _options?: SVGASpriteMetadataPackOptions): Float32Array;
+/** Computes the atlas page count represented by sprite metadata inputs. */
+export declare function countSVGASpriteAtlasPages(imageKeys: readonly string[], atlasRects: ReadonlyMap<string, UVRect>): number;
+/**
+ * Determines the safe SVGA frame-table path without touching renderer state.
+ *
+ * Direct mode owns the complete sprite transform and supports the normal
+ * object-fit, parent-transform and out-of-viewBox cases. Shape/clip geometry
+ * and runtime slot texture overrides remain eligible for `gpu-hybrid`, where
+ * CPU draw scheduling can coexist with GPU frame-row evaluation. Invalid
+ * data, missing atlas data, unsupported backends and budget overflow use the
+ * `cpu-reference` path.
+ */
+export declare function analyzeSVGAFrameTimelineEligibility(input: SVGAFrameTimelineEligibilityInput): SVGAFrameTimelineEligibility;
+export { SVGA_FRAME_TABLE_BUDGET_BYTES, SVGA_FRAME_TABLE_FLOATS, SVGA_GPU_FRAME_TABLE_BUDGET_BYTES, SVGA_SPRITE_METADATA_FLOATS, };