@taole/giftstage 0.1.32 → 0.1.34

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

@@ -19,8 +19,26 @@ export declare class WebGL1Backend implements GPUBackend {
     constructor(canvas: HTMLCanvasElement, antialias?: boolean);
     init(): Promise<void>;
     private initPrograms;
-    private getUniforms;
-    beginFrame(): void;
+    private makeProgramEntry;
+    /**
+     * `u_transform` on `svga-batch-premul` defaults to identity; shape draws overwrite it and
+     * this re-upload restores it for the next plain batch draw. Uploaded unconditionally because
+     * renderers mutate their scratch transform arrays in place (reference never changes).
+     */
+    private applyIdentityTransform;
+    /** Sampler uniforms are constant per shader; set them once instead of every draw. */
+    private bindProgramSamplers;
+    /**
+     * `u_transform` always comes from a renderer-owned scratch `Float32Array` that gets
+     * overwritten in place per draw, so its reference never changes — only its content does.
+     * Skipping the upload based on reference equality would silently apply a stale transform,
+     * so unlike `u_projection` (whose cached arrays are replaced, not mutated, on resize) it is
+     * uploaded unconditionally here.
+     */
+    private applyDrawUniforms;
+    beginFrame(options?: {
+        stencil?: boolean;
+    }): void;
     endFrame(): void;
     private getBufferSourceByteLength;
     private normalizeIndexSource;

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

@@ -34,8 +34,28 @@ export declare class WebGL2Backend implements GPUBackend {
     constructor(canvas: HTMLCanvasElement, antialias?: boolean);
     init(): Promise<void>;
     private initPrograms;
-    private getUniforms;
-    beginFrame(): void;
+    private makeProgramEntry;
+    /**
+     * `u_transform` on `svga-batch-premul` defaults to identity; shape draws overwrite it and
+     * this re-upload restores it for the next plain batch draw. Uploaded unconditionally because
+     * renderers mutate their scratch transform arrays in place (reference never changes).
+     */
+    private applyIdentityTransform;
+    /** Sampler uniforms are constant per shader; set them once instead of every draw. */
+    private bindProgramSamplers;
+    /** Shared by `draw()` and the instanced draw paths, which only ever supply `u_projection`. */
+    private applyProjectionUniform;
+    /**
+     * `u_transform` always comes from a renderer-owned scratch `Float32Array` that gets
+     * overwritten in place per draw, so its reference never changes — only its content does.
+     * Skipping the upload based on reference equality would silently apply a stale transform,
+     * so unlike `u_projection` (whose cached arrays are replaced, not mutated, on resize) it is
+     * uploaded unconditionally here.
+     */
+    private applyDrawUniforms;
+    beginFrame(options?: {
+        stencil?: boolean;
+    }): void;
     endFrame(): void;
     private getBufferSourceByteLength;
     createBuffer(data: GPUBufferSource, usage: BufferUsage): GPUBufferHandle;

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

@@ -20,15 +20,30 @@ export declare class WebGPUBackend implements GPUBackend {
     private texturedBindGroupLayout;
     private dualTexturedBindGroupLayout;
     private instancedTextureBindGroupLayout;
+    private uniformOnlyBindGroupLayout;
     /** `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;
+    /**
+     * CPU-side mirror of `uniformBuffer`, sized identically. Per-draw uniform writes go here
+     * instead of `queue.writeBuffer` directly; `endFrame` uploads the touched byte range in one
+     * `writeBuffer` call before `submit`, cutting dozens of JS→native calls per frame down to one
+     * (writes are visible to the frame's command buffer as long as they land before `submit`).
+     * Eagerly sized from the default stride/slot count so it's always usable even before `init()`
+     * creates the real GPU buffer (matching size); `init()` reallocates it to the device's actual
+     * uniform offset alignment.
+     */
+    private uniformShadow;
+    /** Half-open touched range `[min, max)` in `uniformShadow`; reset each `beginFrame`. */
+    private uniformShadowDirtyMin;
+    private uniformShadowDirtyMax;
     /** Skip redundant `setPipeline` / stencil / VB-IB when drawing many quads with the same geometry. */
     private lastDrawPipeline;
     private lastStencilRef;
+    private frameUsesStencil;
     private lastVertexBufferId;
     private lastIndexBufferId;
     /** Single 160-byte upload for textured draws (replaces multiple `writeBuffer` calls). */
@@ -98,8 +113,9 @@ export declare class WebGPUBackend implements GPUBackend {
     constructor(canvas: HTMLCanvasElement, adapter: GPUAdapter, wantAntialias?: boolean);
     init(): Promise<void>;
     private configureCanvasContext;
-    private ensureDepthStencil;
+    private ensureFrameAttachments;
     private initPipelines;
+    private ensureStencilPipelines;
     private ensureInstancedProjectionBuffer;
     private ensureInstancedStorageBuffer;
     private ensureInstancedSvgaPipeline;
@@ -110,8 +126,14 @@ export declare class WebGPUBackend implements GPUBackend {
     private createInstancedAlphaVideoPipeline;
     private createTexturedPipeline;
     private createClipMaskPipeline;
-    beginFrame(): void;
+    beginFrame(options?: {
+        stencil?: boolean;
+    }): void;
     endFrame(): void;
+    /** Uploads the touched range of `uniformShadow` in one call — must run before `queue.submit`. */
+    private flushUniformShadow;
+    /** Records a per-draw uniform write into the CPU shadow instead of touching the GPU buffer. */
+    private writeUniformShadow;
     private ensureInstancedProjection;
     private gpuBufferUsage;
     private bufferSourceByteLength;

package/dist/renderers/alpha-video-renderer.d.ts

@@ -10,6 +10,7 @@ export declare class AlphaVideoRenderer {
     private scratchTransform;
     private readonly contentSizeScratch;
     private readonly layoutScratch;
+    private readonly clipScratch;
     private readonly wcDbgFirstDraw;
     private readonly wcDbgNullWarns;
     private readonly htmlGate;
@@ -18,6 +19,7 @@ export declare class AlphaVideoRenderer {
     private readonly processedHtmlGatesScratch;
     private readonly instancedTexturesScratch;
     private readonly instancedUniformsScratch;
+    constructor(onHtmlVideoFrame?: (video: HTMLVideoElement) => void);
     private readonly instancedDrawCommand;
     private readonly geometryTexturesScratch;
     private readonly geometryUniformsScratch;

package/dist/renderers/image-renderer.d.ts

@@ -3,6 +3,8 @@ export declare class ImageRenderer {
     private quadVB;
     private quadIB;
     private readonly scratchTransform;
+    private readonly layoutScratch;
+    private readonly clipScratch;
     private projCacheW;
     private projCacheH;
     private projCache;

package/dist/renderers/svga-batch-renderer.d.ts

@@ -25,8 +25,16 @@ interface SVGAClipPrewarmOptions {
 }
 export type SVGAClipMeshMap = Map<string, ClipMeshCache>;
 export declare class SVGABatchRenderer {
+    private readonly onClipMeshReady?;
     private static readonly INSTANCED_QUAD_VERTS;
     private static readonly INSTANCED_QUAD_INDICES;
+    /**
+     * @param onClipMeshReady Called once a background clip mesh build (queued by the hot-path
+     * lookup in `getClipMeshForSprite`, see `queueClipMeshBuild`) finishes, so the owner can
+     * `invalidate()` a redraw — otherwise a slot whose animation has stopped dirtying may never
+     * pick up the now-available precise clip.
+     */
+    constructor(onClipMeshReady?: (() => void) | undefined);
     private pool;
     private vertexBufHandles;
     private indexBufHandles;
@@ -42,19 +50,42 @@ export declare class SVGABatchRenderer {
     private clipMeshCache;
     /** Meshes with lazily created GPU buffers (released in destroy). */
     private clipMeshesWithBuffers;
+    /** Clip paths queued by `queueClipMeshBuild`, awaiting the next background build flush. */
+    private pendingClipMeshPaths;
+    /** True while a background build (worker or frame-budgeted main thread) is in flight. */
+    private clipMeshBuildInFlight;
     private clipFrameDataScratch;
+    /** One-off scratch used only to capture a row for `svgaStaticBatchCache` (P1-10); never read
+     * back — each captured entry clones out of it immediately via `.slice()`. */
+    private staticBatchCacheRowScratch;
     private instancedFrameDataScratch;
     private clipSpriteVertsScratch;
     private clipSpriteIndicesScratch;
-    private shapeVertsScratch;
     private instancedQuadVB;
     private instancedQuadIB;
     private whiteTexture;
     private shapeMeshCache;
+    /** Shape meshes with lazily created static GPU buffers (released in destroy). */
+    private shapeMeshesWithBuffers;
     /** Column-major mat4 scratch for clip-mask u_transform (uploaded synchronously per draw). */
     private clipTransformMat;
+    /** Column-major mat4 scratch for the shape draw's u_transform (consumed synchronously). */
+    private shapeTransformMat;
     /** Scissor rect of the slot currently being drawn (canvas pixels), for clip intersection/restore. */
     private slotScissor;
+    /**
+     * Whether `slotScissor` is currently the *active* GPU scissor rect (vs. the outer scissor
+     * having been intentionally skipped for a slot that cannot draw outside its own box — see
+     * `allFramesInsideViewBox`). Drives `restoreSlotScissor`'s fallback target.
+     */
+    private slotScissorActive;
+    /**
+     * True while a clip stencil mask written for a shape is still live for its sprite sibling
+     * (texture + clip + shape single-write merge, P1-3). `drawClippedSprite` checks this to
+     * skip its own stencil write/clear.
+     */
+    private sharedClipStencilActive;
+    private readonly layoutScratch;
     /** Grow-only SpriteWork pool; cursor resets each flushGroup. */
     private spriteWorkPool;
     private spriteWorkCursor;
@@ -63,22 +94,109 @@ export declare class SVGABatchRenderer {
     private drawGroupScratch;
     /** Per-entity result of the "any frame has shapes" scan (no-atlas render check). */
     private entityHasShapesCache;
+    /** 0=no clip, 1=scissor-compatible clips only, 2=stencil required, 255=not analyzed. */
+    private entityFrameClipModeCache;
+    /**
+     * Per-entity `ClipMeshCache` lookup aligned with `spriteTable.clipPaths` (index = `clipPathIndex`
+     * value), so the hot per-sprite loop can resolve a clip mesh with a direct array read instead of
+     * `getSpriteClipPath` (string build) + a string-keyed `Map` lookup. `undefined` = not yet resolved;
+     * resolution always goes through `getClipMesh`'s string cache, so array entries never go stale.
+     */
+    private entityClipMeshArrayCache;
+    /**
+     * Per-entity result of scanning every sprite×frame layout AABB (in local viewBox space) to see
+     * whether it ever draws outside the entity's own viewBox. Entities with vector shapes are
+     * excluded (`false`) since shape geometry isn't covered by this scan. Used by `flushGroup` to
+     * skip the redundant outer scissor for contain/fill, non-rotated slots — such slots structurally
+     * cannot paint outside their own box, so consecutive same-atlas slots can share one scissor-free
+     * batch run instead of forcing a draw call per slot.
+     */
+    private entityAllFramesInsideViewBoxCache;
     private readonly affineScratch;
+    /**
+     * Reused DrawCommand/uniforms/textures per rendering branch (never allocated per draw).
+     * Backends consume `DrawCommand` synchronously inside `backend.draw`, so mutating these
+     * shared objects between calls is safe as long as no reference is retained past the call.
+     * Grouped by branch (plain instanced sprite / plain batch sprite / clipped instanced /
+     * clipped batch / clip-mask stencil / shape) per the uniform field sets each shader expects.
+     */
+    private readonly plainInstancedTexturesScratch;
+    private readonly plainInstancedUniformsScratch;
+    private readonly plainInstancedDrawCommand;
+    private readonly plainBatchTexturesScratch;
+    private readonly plainBatchUniformsScratch;
+    private readonly plainBatchDrawCommand;
+    /** `drawClippedSprite`'s stencil-test pass on instanced backends (webgl2/webgpu). */
+    private readonly clipInstancedTexturesScratch;
+    private readonly clipInstancedUniformsScratch;
+    private readonly clipInstancedDrawCommand;
+    /** `drawClippedSprite`'s stencil-test pass on the WebGL1 fallback. */
+    private readonly clipBatchTexturesScratch;
+    private readonly clipBatchUniformsScratch;
+    private readonly clipBatchDrawCommand;
+    /**
+     * Clip-mask stencil write/clear, shared by `drawClippedSprite`'s pass-1 write,
+     * `drawShapeFrame`'s non-rect-clip write, and `clearClipStencil`'s clear (all mutate then
+     * synchronously `backend.draw`, never concurrently).
+     */
+    private readonly clipMaskTexturesScratch;
+    private readonly clipMaskUniformsScratch;
+    private readonly clipMaskDrawCommand;
+    /**
+     * `drawShapeFrame`'s fill/stroke draw (always the shared white texture). `u_transform`
+     * carries the per-frame sprite x slot transform so the static shape mesh stays on the GPU;
+     * `u_opacity` carries slot opacity (per-vertex alpha is baked into the mesh).
+     */
+    private readonly shapeTexturesScratch;
+    private readonly shapeUniformsScratch;
+    private readonly shapeDrawCommand;
     beginFrame(backend: GPUBackend): void;
     flush(backend: GPUBackend, slots: Map<string, GiftSlot>): void;
     drawSlot(backend: GPUBackend, slot: GiftSlot): void;
     drawSlots(backend: GPUBackend, slots: Iterable<GiftSlot>): void;
+    requiresStencil(slots: Iterable<GiftSlot>): boolean;
+    private getFrameClipMode;
     prewarmClipMeshes(entity: Pick<VideoEntity, 'spriteTable'>, options?: SVGAClipPrewarmOptions): Promise<number>;
+    /** Builds every not-yet-cached path in `paths`, worker-first with a frame-budgeted fallback. */
+    private buildMissingClipMeshes;
+    /**
+     * Called from the render-loop hot path (`getClipMeshForSprite`) when a clip path has no cached
+     * mesh yet — instead of triangulating synchronously inline, queue it and build it in the
+     * background (batched with any other paths queued in the same tick) so the current frame keeps
+     * moving. Safe to call repeatedly: paths already cached or already queued are no-ops.
+     */
+    private queueClipMeshBuild;
+    private scheduleClipMeshBuildFlush;
+    private flushPendingClipMeshBuilds;
     hydrateClipMeshes(meshes: SVGAClipMeshMap | null | undefined): void;
     snapshotClipMeshes(entity: Pick<VideoEntity, 'spriteTable'>): SVGAClipMeshMap;
     private flushGroup;
     private acquireSpriteWork;
+    /**
+     * Like `acquireSpriteWork`, but for a P1-10 static batch cache replay entry: only `handle` and
+     * `cachedRow` matter, since `packFrameData` short-circuits on `cachedRow` and every other draw
+     * call only reads `work.handle`.
+     */
+    private acquireCachedSpriteWork;
     /** Drop object references so removed slots/entities are not retained by the pool. */
     private releaseSpriteWorks;
+    /** Snapshot check for a P1-10 static batch cache: any mismatch means rebuild, never a stale hit. */
+    private staticBatchCacheMatches;
+    /** Clones the packed row for `work` into a fresh array so it survives past this frame's scratch reuse. */
+    private captureStaticBatchCacheEntry;
+    /** Replays a P1-10 static batch cache hit: same override/batch branching as the live loop, just
+     * sourced from pre-packed rows instead of recomputing layout/transform/texture lookups. */
+    private drawFromStaticBatchCache;
     private getProjection;
     private drawBatch;
     private drawBatchInstancedWebGL;
     private drawClippedSprite;
+    /**
+     * WebGL1 clipped-sprite draw: pack + upload the quad, then draw with stencil 'test'.
+     * Caller is responsible for the surrounding stencil write/clear. Uses separate buffers to
+     * avoid WebGPU writeBuffer aliasing with the batch draw.
+     */
+    private drawBatchSpriteWithStencilTest;
     /** Rect clip in canvas space intersected with the slot scissor. Returns false when fully clipped. */
     private applyClipRectScissor;
     private restoreSlotScissor;
@@ -92,8 +210,23 @@ export declare class SVGABatchRenderer {
     /** Resolve atlas/override texture into a pooled SpriteWork entry. Returns false when missing. */
     private resolveSpriteTextureInto;
     private drawShapeFrame;
+    /**
+     * Clear the shared mask after a shape-first clip merge once the sprite sibling has drawn.
+     * Called by `drawClippedSprite`'s shared-mask branch.
+     */
+    private clearSharedClipStencil;
+    private ensureShapeMeshBuffers;
+    private packShapeTransform;
     private hasAtlasTexture;
     private hasRenderableSVGA;
+    /**
+     * True when every sprite frame's transformed layout rect stays within the entity's own
+     * viewBox (with a small epsilon for float error). Computed once per entity and cached — the
+     * scan touches every sprite×frame combination, which is only affordable as a one-time cost.
+     * Entities with vector shapes always return `false`: shape geometry has its own coordinate
+     * system that this scan does not cover, so we conservatively keep per-slot scissoring for them.
+     */
+    private allFramesInsideViewBox;
     private getWhiteTexture;
     private getShapeMesh;
     private appendShape;
@@ -103,6 +236,20 @@ export declare class SVGABatchRenderer {
     private clamp01;
     private cleanupPoints;
     private getClipMesh;
+    /**
+     * Hot-path clip mesh lookup: reads `clipPathIndex` directly (no string build/compare) and
+     * memoizes the resolved mesh per (entity, clipPathIndex) so repeat frames skip the string-keyed
+     * `clipMeshCache` lookup too.
+     *
+     * Returns `undefined` (rather than triangulating inline) when the path hasn't been built yet —
+     * prewarm normally finishes before an entity is ever drawn, but with `svgaPrewarmClipMeshes:
+     * false`, an aborted/partially failed prewarm, or a slot rendered before prewarm completes, this
+     * lookup would otherwise pay a synchronous SVG-parse + triangulate cost inside the render loop.
+     * The path is queued for a background build instead (see `queueClipMeshBuild`); callers already
+     * treat a falsy return as "no clip this frame" (draw unclipped / assume stencil conservatively),
+     * and a redraw is requested once the build lands so later frames clip precisely.
+     */
+    private getClipMeshForSprite;
     private ensureVertexBuffer;
     private ensureIndexBuffer;
     private ensureClipSpriteVertexBuffer;

package/dist/renderers/vap-renderer.d.ts

@@ -17,6 +17,27 @@ export declare class VAPRenderer {
     private scratchTransform;
     private readonly processedHtmlGatesScratch;
     private readonly vapVertexScratch;
+    private readonly layoutScratch;
+    private readonly clipScratch;
+    /** `drawInstancedVapBatches` grow-only scratch: avoids a fresh array/Map per frame. */
+    private readonly instancedListScratch;
+    private readonly instancedByTexScratch;
+    private readonly instancedTexturesScratch;
+    private readonly instancedUniformsScratch;
+    private readonly instancedDrawCommand;
+    /** `drawGeometry` (plain VAP quad) reused command/uniforms/textures. */
+    private readonly geometryTexturesScratch;
+    private readonly geometryUniformsScratch;
+    private readonly geometryDrawCommand;
+    /** `drawMixedGeometry` (composited rgba overlay) reused command/uniforms/textures. */
+    private readonly mixedGeometryTexturesScratch;
+    private readonly mixedGeometryUniformsScratch;
+    private readonly mixedGeometryDrawCommand;
+    /** `drawMixedDirectGeometry` per-frame-object overlay reused command/uniforms/textures. */
+    private readonly overlayTexturesScratch;
+    private readonly overlayUniformsScratch;
+    private readonly overlayDrawCommand;
+    constructor(onHtmlVideoFrame?: (video: HTMLVideoElement) => void);
     private projCacheW;
     private projCacheH;
     private projCache;

package/dist/types/index.d.ts

@@ -62,7 +62,9 @@ export interface GPUBackend {
     /** Maximum supported 2D texture dimension for this backend/device. */
     readonly maxTextureSize?: number;
     init(): Promise<void>;
-    beginFrame(): void;
+    beginFrame(options?: {
+        stencil?: boolean;
+    }): void;
     endFrame(): void;
     createBuffer(data: GPUBufferSource, usage: BufferUsage): GPUBufferHandle;
     updateBuffer(handle: GPUBufferHandle, data: GPUBufferSource, offset?: number): void;
@@ -269,6 +271,47 @@ export interface ResolvedSVGASlotTexture {
     logicalWidth: number;
     logicalHeight: number;
 }
+/**
+ * SVGABatchRenderer-internal: one packed instance row for a `stopped` slot's static batch
+ * cache (P1-10). `row` mirrors the exact `FRAME_DATA_FLOATS` layout `packFrameData` produces.
+ * `isOverride` mirrors whether the sprite used a `svgaSlots` texture override (drawn immediately,
+ * breaking any running atlas batch) vs. a normal atlas sprite (batched with same-texture sprites).
+ */
+export interface SVGAStaticBatchCacheEntry {
+    row: Float32Array;
+    handle: GPUTextureHandle;
+    isOverride: boolean;
+}
+/**
+ * SVGABatchRenderer-internal: cached packed-instance-row list for a `stopped` SVGA slot, plus
+ * the exact snapshot of every input it was built from. Any mismatch against the slot's current
+ * values invalidates the cache (see `SVGABatchRenderer`'s match check) — favors over-invalidating
+ * to guarantee correctness over maximizing hit rate.
+ */
+export interface SVGAStaticBatchCache {
+    entries: SVGAStaticBatchCacheEntry[];
+    /** `VideoEntity` reference the cache was built against (covers spriteTable/atlasRects identity). */
+    entity: unknown;
+    /** `entity.atlasTextureHandles` (if any) or `entity.atlasTextureHandle`, whichever is in use. */
+    atlasHandlesDep: unknown;
+    /**
+     * `slot.svgaSlotTextures` map reference. `svgaSlots` overrides are immutable post-load, but
+     * tracked defensively so a future change to that invariant can't silently go stale here.
+     */
+    svgaSlotTextures: unknown;
+    currentFrame: number;
+    opacity: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scale: number;
+    rotation: number;
+    sx: number;
+    sy: number;
+    offsetX: number;
+    offsetY: number;
+}
 export interface ResolvedVAPResource {
     source: CanvasImageSource;
     width: number;
@@ -318,9 +361,9 @@ export interface GiftStageOptions {
     } | false;
     /**
      * Edge smoothing: WebGL2 uses the context multisampled framebuffer; WebGPU uses 4× MSAA + resolve.
-     * Default: **true** for WebGL2, **false** for WebGPU (MSAA is expensive with large transparent-video fills).
-     * Set `true` explicitly when using WebGPU + sharp SVGA edges.
-     * Many concurrent transparent videos: keep WebGPU `antialias` off (default) and consider lowering {@link resolution}.
+     * Default: **true** for WebGL2 and WebGPU.
+     * Many concurrent transparent videos: consider setting `antialias: false` and lowering {@link resolution}
+     * when fill-rate or framebuffer bandwidth becomes the bottleneck.
      */
     antialias?: boolean;
     /**
@@ -611,6 +654,32 @@ export interface GiftSlot {
         map: unknown;
         size: number;
     };
+    /**
+     * RenderManager internal: cached coincident-visual-duplicate key + the exact field snapshot it
+     * was built from. Rebuilt only when one of those fields actually changes, avoiding a template
+     * string array + `join('|')` allocation on every dirty frame for every visible slot.
+     */
+    coincidentVisualKeyCache?: {
+        key: string;
+        resourceKey: string;
+        frameKey: string;
+        svgaSlotKey: string;
+        objectFit: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        scale: number;
+        opacity: number;
+        rotation: number | undefined;
+        originX: string | number;
+        originY: string | number;
+    };
+    /**
+     * SVGABatchRenderer internal: cached packed instance rows for a `stopped` slot with no
+     * shape/clip sprites this frame (P1-10). Rebuilt whenever any tracked input changes.
+     */
+    svgaStaticBatchCache?: SVGAStaticBatchCache | null;
     onFrame?: (frame: number, gift: GiftHandle) => void;
     onComplete?: (gift: GiftHandle) => void;
 }
@@ -652,6 +721,8 @@ export interface VAPFrameObj {
     mt?: number;
     frame: [number, number, number, number];
     mFrame: [number, number, number, number];
+    /** `String(srcId)` precomputed once by `buildVAPFrameMap` to avoid per-draw re-stringification. */
+    srcKey?: string;
 }
 export interface FlyAnimation {
     giftId: string;

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

@@ -20,10 +20,11 @@ export declare function resolveGiftTransformOrigin(slot: GiftSlot, out?: GiftTra
 export declare function fillGiftTransformMatrix(slot: GiftSlot, x: number, y: number, width: number, height: number, out: Float32Array): Float32Array;
 /** Apply the gift's parent rotation to an existing local-to-stage affine transform. */
 export declare function rotateGiftAffine(slot: GiftSlot, transform: Affine2D, out?: Affine2D): Affine2D;
-/** AABB of a rotated stage-space rectangle, suitable for the backend scissor. */
-export declare function getRotatedRectAABB(slot: GiftSlot, x: number, y: number, width: number, height: number): {
+export interface RectAABB {
     x: number;
     y: number;
     w: number;
     h: number;
-};
+}
+/** AABB of a rotated stage-space rectangle, suitable for the backend scissor. */
+export declare function getRotatedRectAABB(slot: GiftSlot, x: number, y: number, width: number, height: number, out?: RectAABB): RectAABB;

package/dist/utils/html-video-upload-gate.d.ts

@@ -4,6 +4,7 @@
  * when many `<video>` elements run together (especially with WebGPU texture copies).
  */
 export declare class HtmlVideoUploadGate {
+    private readonly onFrameAvailable?;
     private readonly frameInfo;
     private readonly pending;
     private readonly lastHandle;
@@ -18,12 +19,16 @@ export declare class HtmlVideoUploadGate {
     private readonly stagnationLogged;
     /** When `requestVideoFrameCallback` is missing, fall back to `currentTime` changes (coarser than rVFC). */
     private readonly lastTimeFallback;
+    /** Low-frequency wake-up used to detect browsers that stop delivering rVFC callbacks. */
+    private readonly healthTimers;
+    constructor(onFrameAvailable?: (video: HTMLVideoElement) => void);
     /**
      * Returns true when `updateTexture` should run for this slot: first time, or a new decoded frame was signaled.
      */
     preUpload(slotId: string, video: HTMLVideoElement): boolean;
     getFrameInfo(slotId: string): VideoFrameCallbackMetadata | undefined;
     private ensureRvf;
+    private ensureHealthTimer;
     private consumeTimeAdvance;
     private markProgress;
     private tryRecoverStalledPlayback;

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

@@ -1,6 +1,65 @@
 import type { SVGAWorkerMoviePayload } from '../parsers/svga-parser-worker-client';
 type PersistKind = 'arrayBuffer' | 'text';
 type MemoryKind = PersistKind | 'json' | 'svga-payload' | 'svga-asset';
+export declare class AsyncLimiter {
+    private maxConcurrent;
+    private active;
+    private queue;
+    constructor(maxConcurrent: number);
+    setMaxConcurrent(maxConcurrent: number): void;
+    run<T>(task: () => Promise<T>): Promise<T>;
+    private drain;
+}
+/**
+ * Structural estimate; avoids JSON.stringify of the whole sprites tree (main-thread spike).
+ *
+ * When the worker-binary path is used, `imageBlob` is the *entire* deserialized SGPB buffer
+ * (see `deserializeSVGAWorkerPayload`), not just the image bytes — `spriteTable.frameData`/
+ * `clipPathIndex`/`shapesIndex` are typed-array *views* sharing that same underlying
+ * `ArrayBuffer` (see `readSpriteTable` in `svga-sprite-table-binary.ts`). Adding their
+ * `byteLength` again on top of `imageBlob.byteLength` would double-count them, systematically
+ * inflating the estimate and causing the memory LRU to evict/re-parse too eagerly. Only add
+ * them when they do *not* share `imageBlob`'s buffer (the legacy `images` record path, where
+ * the sprite table is a separate allocation).
+ */
+export declare function estimateSVGAWorkerPayloadBytes(payload: SVGAWorkerMoviePayload): number;
+export declare class ResourceCacheManager {
+    private readonly limiter;
+    private readonly pending;
+    private readonly memory;
+    private memoryBytes;
+    private maxMemoryBytes;
+    private maxPersistentBytes;
+    private dbPromise;
+    private persistentTrimPromise;
+    configure(opts?: {
+        maxConcurrent?: number;
+        maxMemoryBytes?: number;
+        maxPersistentBytes?: number;
+    }): void;
+    runLimited<T>(task: () => Promise<T>): Promise<T>;
+    fetchArrayBuffer(url: string, signal?: AbortSignal): Promise<ArrayBuffer>;
+    fetchText(url: string, signal?: AbortSignal): Promise<string>;
+    fetchJSON<T>(url: string, signal?: AbortSignal): Promise<T>;
+    getSVGAWorkerPayload(cacheKey: string): SVGAWorkerMoviePayload | null;
+    setSVGAWorkerPayload(cacheKey: string, payload: SVGAWorkerMoviePayload): void;
+    getMemoryValue<T>(key: string, kind: MemoryKind): T | null;
+    setMemoryValue<T>(key: string, kind: MemoryKind, value: T, size: number): void;
+    getPersistedArrayBuffer(key: string): Promise<ArrayBuffer | null>;
+    setPersistedArrayBuffer(key: string, value: ArrayBuffer): Promise<void>;
+    deletePersistedValue(key: string): Promise<void>;
+    private getOrCreatePending;
+    private getMemory;
+    private setMemory;
+    private trimMemory;
+    private openDb;
+    private getPersistent;
+    private setPersistent;
+    private touchPersistent;
+    private schedulePersistentTrim;
+    private trimPersistent;
+    private deletePersistent;
+}
 export declare function configureResourceCache(opts?: {
     maxConcurrent?: number;
     maxMemoryBytes?: number;

package/dist/video/webcodecs-mp4-core.d.ts

@@ -32,6 +32,53 @@ export declare function decodeH264ToFrames(codec: string, description: ArrayBuff
     frames: VideoFrame[];
     timesSec: Float64Array;
 }>;
+export interface IncrementalH264DecoderCallbacks {
+    onFrame: (index: number, frame: VideoFrame) => void;
+    onEos?: () => void;
+    onError?: (error: unknown) => void;
+}
+/**
+ * Playhead-driven incremental H.264 decode: feeds chunks in decode order only up to
+ * `needIdx + decodeAheadFrames` (via {@link ensure}), so memory stays bounded by how far ahead
+ * of playback the caller asks for instead of decoding (and retaining) the entire clip upfront.
+ * Originally the Worker's demux/decode pump (see `webcodecs-mp4.worker.ts`); lifted here so the
+ * main-thread WebCodecs fallback (no Worker available, or `useWorker: false`) can reuse the exact
+ * same backpressure/rewind semantics instead of decoding the whole file into memory at once —
+ * see P1-10 optimization notes / `WebCodecsMp4Playback.createOnMainThread`.
+ */
+export declare class IncrementalH264Decoder {
+    private readonly decodeOrder;
+    private readonly presTimes;
+    private readonly timescale;
+    private readonly codec;
+    private readonly description;
+    private readonly duration;
+    private readonly callbacks;
+    private decoder;
+    private nextChunk;
+    private chunksFed;
+    private targetNeedIdx;
+    private lastPostedMax;
+    private minPosted;
+    private playbackNeedFloor;
+    private freeSlots;
+    private eosClosed;
+    private pumpScheduled;
+    private pumping;
+    private destroyed;
+    constructor(decodeOrder: Sample[], presTimes: Float64Array, timescale: number, codec: string, description: ArrayBuffer | undefined, duration: number, callbacks: IncrementalH264DecoderCallbacks, initialNeedIdx: number);
+    /** Raise the decode target and/or update main-thread ring headroom; resumes the pump if idle. */
+    ensure(needIdx: number, freeSlots: number): void;
+    /** Restart decode from the nearest keyframe at/before t=0 (backward seek / loop wrap). */
+    rewind(): void;
+    destroy(): void;
+    private schedulePump;
+    private doRewind;
+    private openDecoder;
+    private feedOneChunk;
+    private finalizeEos;
+    private runPump;
+}
 export declare function frameIndexForTime(timesSec: Float64Array, clipDurationSec: number, t: number): number;
 export declare function computeClipDurationSeconds(metaDurationSec: number, timesSec: Float64Array, frames: VideoFrame[]): number;
 /** Clip duration from demux metadata + presentation timeline only (no decoded frames). */