@taole/giftstage 0.1.33 → 0.1.35

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

@@ -19,7 +19,23 @@ export declare class WebGL1Backend implements GPUBackend {
     constructor(canvas: HTMLCanvasElement, antialias?: boolean);
     init(): Promise<void>;
     private initPrograms;
-    private getUniforms;
+    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;

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

@@ -22,8 +22,16 @@ export declare class WebGL2Backend implements GPUBackend {
     private videoElementDirectUploadValidated;
     /** DYNAMIC_DRAW upload target for `svga-instanced-premul` (`FrameJobData` per instance). */
     private static readonly INST_SVGA_GL_MAX;
+    private static readonly INST_SVGA_GL_FLOATS;
+    private static readonly INST_SVGA_GL_STRIDE;
     private static readonly INST_SVGA_GL_BYTES;
     private instancedSvgaInstanceGLBuffer;
+    /** 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;
+    private static readonly INST_CLIP_MASK_GL_STRIDE;
+    private static readonly INST_CLIP_MASK_GL_BYTES;
+    private instancedClipMaskGLBuffer;
     /** DYNAMIC_DRAW upload target for `alpha-video-instanced` (rect+atlasRemap+opacity per instance). */
     private static readonly INST_ALPHA_GL_MAX;
     private static readonly INST_ALPHA_GL_BYTES;
@@ -34,7 +42,25 @@ export declare class WebGL2Backend implements GPUBackend {
     constructor(canvas: HTMLCanvasElement, antialias?: boolean);
     init(): Promise<void>;
     private initPrograms;
-    private getUniforms;
+    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;
@@ -63,6 +89,8 @@ export declare class WebGL2Backend implements GPUBackend {
     private deleteAllVertexArrays;
     private ensureInstancedSvgaInstanceBuffer;
     private drawInstancedSvgaGL;
+    private ensureInstancedClipMaskBuffer;
+    private drawInstancedClipMaskGL;
     private ensureInstancedAlphaInstanceBuffer;
     private drawInstancedAlphaGL;
     private ensureInstancedVapInstanceBuffer;

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

@@ -27,6 +27,19 @@ export declare class WebGPUBackend implements GPUBackend {
     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;
@@ -72,18 +85,16 @@ export declare class WebGPUBackend implements GPUBackend {
     private dualTexturedBindGroupCache;
     /** All instanced pipelines also share one texture layout. */
     private instancedTextureBindGroupCache;
-    /** Batched SVGA sprites (FrameJobData packed as 13 floats per instance). */
+    /** 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 CLIP_MASK_INSTANCED_MAX;
+    private static readonly CLIP_MASK_INSTANCED_STRIDE;
     /** Batched alpha-video (storage instances + projection uniform). */
     private static readonly ALPHA_INSTANCED_MAX;
     private static readonly ALPHA_INSTANCED_STRIDE;
     private static readonly VAP_INSTANCED_MAX;
     private static readonly VAP_INSTANCED_STRIDE;
-    /** One draw may bind up to this many bytes of instance storage (max instances × stride). */
-    private static readonly INSTANCED_SVGA_CHUNK_BYTES;
-    private static readonly INSTANCED_ALPHA_CHUNK_BYTES;
-    private static readonly INSTANCED_VAP_CHUNK_BYTES;
     /**
      * Multiple `queue.writeBuffer(..., offset 0)` to the same storage buffer before one `submit` only keep the
      * last write; one shared ring + dynamic offsets keeps all instanced paths non-overlapping until submit.
@@ -94,9 +105,19 @@ export declare class WebGPUBackend implements GPUBackend {
     private storageBindOffsetAlign;
     /** Reset in `beginFrame`; all instanced draw types reserve non-overlapping chunks. */
     private instancedStorageRingOffset;
+    /** Grow-only CPU mirror; expands to the frame's actual storage high-water mark. */
+    private instancedStorageShadow;
+    private instancedStorageShadowDirtyMax;
     private readonly instancedProjectionCache;
     private instancedProjectionValid;
+    /** Storage range written by the latest instanced clip-mask write pass; reused by its clear. */
+    private lastClipMaskStorageBase;
+    private lastClipMaskStorageByteLength;
     private lastInstancedTextureBindGroup;
+    private performanceBufferWrites;
+    private performanceBufferWriteBytes;
+    private performanceStorageBufferWrites;
+    private performanceStorageBufferWriteBytes;
     constructor(canvas: HTMLCanvasElement, adapter: GPUAdapter, wantAntialias?: boolean);
     init(): Promise<void>;
     private configureCanvasContext;
@@ -105,10 +126,13 @@ export declare class WebGPUBackend implements GPUBackend {
     private ensureStencilPipelines;
     private ensureInstancedProjectionBuffer;
     private ensureInstancedStorageBuffer;
+    private ensureInstancedDataBindGroup;
     private ensureInstancedSvgaPipeline;
+    private ensureInstancedClipMaskPipeline;
     private ensureInstancedAlphaPipeline;
     private ensureInstancedVapPipeline;
     private createInstancedSvgaPipeline;
+    private createInstancedClipMaskPipeline;
     private createVapInstancedPipeline;
     private createInstancedAlphaVideoPipeline;
     private createTexturedPipeline;
@@ -117,6 +141,21 @@ export declare class WebGPUBackend implements GPUBackend {
         stencil?: boolean;
     }): void;
     endFrame(): void;
+    getPerformanceSnapshot(): {
+        bufferWrites: number;
+        bufferWriteBytes: number;
+        storageBufferWrites: number;
+        storageBufferWriteBytes: number;
+    };
+    resetPerformanceSnapshot(): void;
+    private writeBuffer;
+    /** Uploads the touched range of `uniformShadow` in one call — must run before `queue.submit`. */
+    private flushUniformShadow;
+    /** Uploads every instanced draw's non-overlapping shadow range in one call before submit. */
+    private flushInstancedStorageShadow;
+    private writeInstancedStorageShadow;
+    /** Records a per-draw uniform write into the CPU shadow instead of touching the GPU buffer. */
+    private writeUniformShadow;
     private ensureInstancedProjection;
     private gpuBufferUsage;
     private bufferSourceByteLength;
@@ -150,6 +189,7 @@ export declare class WebGPUBackend implements GPUBackend {
     draw(cmd: DrawCommand): void;
     /** One `drawIndexed` with `instanceCount` for all SVGA sprites sharing the same atlas. */
     private drawInstancedSvga;
+    private drawInstancedClipMask;
     /** One `drawIndexed` with `instanceCount` for all gifts sharing the same video texture (e.g. atlas). */
     private drawInstancedAlpha;
     private drawInstancedVap;

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 { SVGAShape, SVGATransform } from '../types';
+import type { SVGAParams, SVGAShape, SVGATransform } from '../types';
 /** Floats per frame in `frameData`: layoutW, layoutH, a, b, c, d, tx, ty, alpha. */
 export declare const SPRITE_FRAME_FLOATS = 9;
 export interface SVGASpriteTable {
@@ -20,6 +20,7 @@ export interface SVGASpriteTable {
     /** spriteCount × frameCount; -1 = none. */
     shapesIndex: Int32Array;
     hasAnyShapes: boolean;
+    allFramesInsideViewBox?: boolean;
 }
 /** Loose frame shape used when converting from AoS decode (JS proto / fixtures). */
 export interface SVGAFrameLike {
@@ -55,5 +56,10 @@ export declare function getSpriteClipPath(table: SVGASpriteTable, spriteIndex: n
  * Resolves shape `keep` chains to shared array references.
  */
 export declare function spriteTableFromSprites(sprites: SVGASpriteLike[], frameCountHint?: number): SVGASpriteTable;
+/**
+ * Compute the renderer's scissor-elision flag before the entity becomes renderable. Shapes are
+ * conservative because their geometry is not represented by the sprite layout rectangle.
+ */
+export declare function ensureAllFramesInsideViewBox(params: Pick<SVGAParams, 'viewBoxWidth' | 'viewBoxHeight'>, table: SVGASpriteTable): boolean;
 /** Empty table used when there are no sprites. */
 export declare function emptySpriteTable(frameCount?: number): SVGASpriteTable;

package/dist/parsers/vap-config-parser.d.ts

@@ -1,20 +1,22 @@
 import type { VAPConfig, VAPFrameItem } from '../types';
 export declare function parseVAPConfig(config: string | object): Promise<VAPConfig>;
 export declare function getVAPFrame(config: VAPConfig, frameIndex: number): VAPFrameItem | undefined;
-/**
- * Logical content size for layout/aspect (matches visible RGB frame, not full mp4 frame).
- * `videoW`/`videoH` often include separate alpha bands; use `w`/`h` or `rgbFrame` w×h.
- */
-export declare function getVAPContentSize(info: VAPConfig['info']): {
+export interface VAPContentSize {
     w: number;
     h: number;
-};
+}
 /**
- * Compute normalized UV coordinates for a frame region within the video texture.
+ * Logical content size for layout/aspect (matches visible RGB frame, not full mp4 frame).
+ * `videoW`/`videoH` often include separate alpha bands; use `w`/`h` or `rgbFrame` w×h.
  */
-export declare function computeVAPUV(region: [number, number, number, number], videoW: number, videoH: number): {
+export declare function getVAPContentSize(info: VAPConfig['info'], out?: VAPContentSize): VAPContentSize;
+export interface VAPUVRect {
     left: number;
     right: number;
     top: number;
     bottom: number;
-};
+}
+/**
+ * Compute normalized UV coordinates for a frame region within the video texture.
+ */
+export declare function computeVAPUV(region: [number, number, number, number], videoW: number, videoH: number, out?: VAPUVRect): VAPUVRect;

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;

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

@@ -3,9 +3,14 @@ export declare class ImageRenderer {
     private quadVB;
     private quadIB;
     private readonly scratchTransform;
+    private readonly layoutScratch;
+    private readonly clipScratch;
     private projCacheW;
     private projCacheH;
     private projCache;
+    private readonly texturesScratch;
+    private readonly uniformsScratch;
+    private readonly drawCommand;
     private static readonly QUAD_VERTS;
     private static readonly QUAD_INDICES;
     drawSlot(backend: GPUBackend, slot: GiftSlot): void;

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

@@ -12,6 +12,13 @@ export interface ClipMeshCache {
         w: number;
         h: number;
     } | null;
+    /** Local-space bounds cached for conservative instanced stencil safety checks. */
+    bounds?: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
     /** Lazily created static GPU buffers (local-space vertices, transformed via u_transform). */
     vertexBuf?: GPUBufferHandle | null;
     indexBuf?: GPUBufferHandle | null;
@@ -25,8 +32,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,60 +57,202 @@ 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 instancedFrameDataWords;
     private clipSpriteVertsScratch;
     private clipSpriteIndicesScratch;
-    private shapeVertsScratch;
+    private clipMaskBatchTransformsScratch;
     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;
+    private slotClipX0;
+    private slotClipY0;
+    private slotClipX1;
+    private slotClipY1;
+    /**
+     * 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
+     * `spriteTable.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;
     /** Reused scratch arrays (consumed synchronously). */
     private batchSpritesScratch;
     private drawGroupScratch;
+    private sharedSlotLayerWorkPool;
+    private sharedSlotLayerWorksScratch;
+    private clipLayerBatchPool;
+    private clipLayerBatchesScratch;
     /** 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;
     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;
+    private readonly clipMaskInstancedUniformsScratch;
+    private readonly clipMaskInstancedDrawCommand;
+    /**
+     * `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;
+    /**
+     * Returns the target frame only when every clip path referenced by its visible sprites has a
+     * resolved cache entry. A miss queues background triangulation and keeps the previous complete
+     * frame on screen, preventing a partially built frame from being drawn without clipping.
+     */
+    private resolveRenderableFrame;
+    private isFrameClipReady;
     private getFrameClipMode;
     prewarmClipMeshes(entity: Pick<VideoEntity, 'spriteTable'>, options?: SVGAClipPrewarmOptions): Promise<number>;
+    prewarmClipMeshesForFrame(entity: Pick<VideoEntity, 'spriteTable'>, frame: number, options?: SVGAClipPrewarmOptions): Promise<number>;
+    private collectFrameClipPaths;
+    /** 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;
+    /**
+     * Transposes disjoint slots sharing one entity into sprite layers. Reordering across slots is
+     * safe because their outer clip bounds do not overlap; order within every slot remains sprite
+     * index order. Non-rect clips sharing one mesh become write -> instanced test -> clear.
+     */
+    private tryFlushDisjointSharedEntityLayers;
+    private resetClipLayerBatches;
+    private acquireClipLayerBatch;
+    private resolveClipTransform;
+    private intersectWorkClipRect;
+    private drawBatchedClipLayer;
     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;
+    private updateSlotClipBounds;
+    private copyCurrentSlotClipToWork;
     /** 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;
     private getClipRect;
+    private getClipMeshBounds;
     private ensureClipMeshBuffers;
     private packClipTransform;
     private drawSingleSprite;
     private clearClipStencil;
     private rotateTransform;
     private packFrameData;
+    private packInstancedFrameData;
+    private packClipCoordinatePair;
+    private packFrameDataAt;
     /** 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;
     private getWhiteTexture;
@@ -107,6 +264,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

@@ -15,8 +15,32 @@ export declare class VAPRenderer {
     private readonly scratchAtlasRemap;
     private instancePackScratch;
     private scratchTransform;
+    private readonly contentSizeScratch;
+    private readonly rgbUVScratch;
+    private readonly alphaUVScratch;
+    private readonly maskUVScratch;
     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;

package/dist/shaders/index.d.ts

@@ -35,6 +35,10 @@ export declare const glsl: {
         readonly vert: string;
         readonly frag: string;
     };
+    readonly clipMaskInstanced: {
+        readonly vert: string;
+        readonly frag: string;
+    };
 };
 export declare const wgsl: {
     readonly svgaBatchPremul: string;
@@ -46,4 +50,5 @@ export declare const wgsl: {
     readonly alphaVideoInstanced: string;
     readonly rgbaTextured: string;
     readonly clipMask: string;
+    readonly clipMaskInstanced: string;
 };