@taole/giftstage 0.1.36 → 0.2.2

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

@@ -1,4 +1,4 @@
-import type { VAPConfig, VAPFrameItem } from '../types';
+import type { VAPConfig, VAPFrameItem } from '../types/index.js';
 export declare function parseVAPConfig(config: string | object): Promise<VAPConfig>;
 export declare function getVAPFrame(config: VAPConfig, frameIndex: number): VAPFrameItem | undefined;
 export interface VAPContentSize {

package/dist/plugin/motion-track.d.ts

@@ -0,0 +1,19 @@
+import type { GPUBackend } from '../types/index.js';
+import { type MotionTrackDescriptor, type MotionTrackLease, type ReadonlyTableLease } from './types.js';
+export declare class MotionTrackLeaseImpl implements MotionTrackLease {
+    readonly trackCount: number;
+    readonly sampleCount: number;
+    readonly sampleIntervalMs: number;
+    readonly durationMs: number;
+    readonly table: ReadonlyTableLease;
+    readonly gpuGlobalsBuffer: import("../index.js").GPUBufferHandle | null;
+    private readonly backend;
+    private readonly gpuGlobals;
+    private readonly scratch;
+    private _released;
+    constructor(backend: GPUBackend | null, descriptor: MotionTrackDescriptor);
+    get released(): boolean;
+    sample(trackIndex: number, timeMs: number, out?: Float32Array<ArrayBuffer>): Float32Array;
+    updateGpuGlobals(timeMs: number, cssScaleX: number, cssScaleY: number): void;
+    release(): void;
+}

package/dist/plugin/playback-scope.d.ts

@@ -0,0 +1,42 @@
+import type { AddGiftOptions, GiftHandle } from '../types/index.js';
+import type { MotionBindingOptions, MotionTrackDescriptor, MotionTrackLease, ParticleBatchDescriptor, ParticleBatchHandle, PlaybackFrame, PlaybackFrameController, PlaybackScope, PlaybackScopeHost, PlaybackScopeStartOptions, PlaybackScopeState } from './types.js';
+export declare class PlaybackScopeImpl implements PlaybackScope, PlaybackFrameController {
+    readonly id: string;
+    private readonly host;
+    private readonly controller;
+    private readonly gifts;
+    private readonly tracks;
+    private readonly bindings;
+    private readonly particleBatches;
+    private readonly frameListeners;
+    private readonly finishListeners;
+    private unregisterController;
+    private _state;
+    private _currentTimeMs;
+    private durationMs;
+    private lastTickAtMs;
+    constructor(host: PlaybackScopeHost, id?: string);
+    get signal(): AbortSignal;
+    get state(): PlaybackScopeState;
+    get currentTimeMs(): number;
+    get active(): boolean;
+    addGift(options: AddGiftOptions): Promise<GiftHandle>;
+    createMotionTrack(descriptor: MotionTrackDescriptor): MotionTrackLease;
+    createParticleBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
+    bindMotion(gift: GiftHandle, track: MotionTrackLease, trackIndex: number, options?: MotionBindingOptions): () => void;
+    onFrame(listener: (frame: PlaybackFrame) => void): () => void;
+    onFinish(listener: () => void): () => void;
+    start(options: PlaybackScopeStartOptions): void;
+    pause(): void;
+    resume(): void;
+    seek(timeMs: number): void;
+    stop(): void;
+    tick(nowMs: number, deltaMs: number): boolean;
+    destroy(): void;
+    private applyAll;
+    private applyParticleTime;
+    private applyBinding;
+    private applyMediaTime;
+    private emitFrame;
+    private assertAlive;
+}

package/dist/plugin/types.d.ts

@@ -0,0 +1,183 @@
+import type { AddGiftOptions, BackendType, SVGAFrameEvaluation, SVGAFrameTimelineTransport, SVGARenderPath, GiftHandle, GiftSlot, GiftType, GPUBackend, GPUBufferHandle } from '../types/index.js';
+/** x, y, scaleX, scaleY, rotation(rad), opacity, visible, interpolateToNext. */
+export declare const MOTION_TRACK_SAMPLE_FLOATS = 8;
+export type PlaybackScopeState = 'idle' | 'playing' | 'paused' | 'stopped' | 'destroyed';
+export interface GiftAssetMetadata {
+    type: GiftType;
+    width: number;
+    height: number;
+    fps?: number;
+    frameCount?: number;
+    spriteCount?: number;
+    atlasPageCount?: number;
+    hasShapes?: boolean;
+    hasClipPaths?: boolean;
+    /** True only when every drawable frame is proven to stay inside the SVGA viewBox. */
+    allFramesInsideViewBox?: boolean;
+}
+export interface GiftAssetLease {
+    readonly metadata: GiftAssetMetadata;
+    readonly released: boolean;
+    release(): void;
+}
+export interface SVGAFrameTimelineCapabilities {
+    transport: SVGAFrameTimelineTransport;
+    direct: boolean;
+    hybrid: boolean;
+    maxTableBytes: number;
+    supportedPaths: SVGARenderPath[];
+    defaultEvaluation: SVGAFrameEvaluation;
+    /** Compatibility aliases for consumers that used the earlier draft shape. */
+    gpuDirect: boolean;
+    gpuHybrid: boolean;
+    cpuReference: true;
+    tableBudgetBytes: number;
+}
+export interface GiftStageCapabilities {
+    backend: BackendType;
+    sharedTimeline: true;
+    scopedPlayback: true;
+    assetLeases: true;
+    motionTrack: {
+        /** `gpu-table` means the immutable table is resident on the GPU; CPU sampling remains the reference fallback. */
+        mode: 'gpu-table' | 'cpu-reference';
+        /** Media paths whose rendered parent transform can sample the table in-shader. */
+        gpuMediaTypes: GiftType[];
+        /** Complex media and older backends retain the deterministic CPU sampler. */
+        cpuReferenceFallback: true;
+        nonUniformScale: true;
+        sampleFloats: typeof MOTION_TRACK_SAMPLE_FLOATS;
+    };
+    particles: {
+        backend: 'webgpu' | 'webgl2' | 'unavailable';
+        canvas2D: false;
+    };
+    /** Public SVGA frame-table path support exposed to playback plugins. */
+    svgaFrameTimeline?: SVGAFrameTimelineCapabilities;
+}
+export interface ReadonlyTableDescriptor {
+    data: Float32Array;
+    stride: number;
+    label?: string;
+}
+export interface ReadonlyTableLease {
+    readonly data: Float32Array;
+    readonly stride: number;
+    readonly gpuBuffer: GPUBufferHandle | null;
+    readonly released: boolean;
+    release(): void;
+}
+export interface MotionTrackDescriptor {
+    /** Number of independent tracks packed in `samples`. */
+    trackCount: number;
+    /** Number of samples for each track. */
+    sampleCount: number;
+    /** Uniform distance between samples, in milliseconds. */
+    sampleIntervalMs: number;
+    /** Track-major samples using {@link MOTION_TRACK_SAMPLE_FLOATS}. */
+    samples: Float32Array;
+    durationMs?: number;
+    label?: string;
+}
+export interface MotionTrackLease {
+    readonly trackCount: number;
+    readonly sampleCount: number;
+    readonly sampleIntervalMs: number;
+    readonly durationMs: number;
+    readonly table: ReadonlyTableLease;
+    readonly released: boolean;
+    sample(trackIndex: number, timeMs: number, out?: Float32Array): Float32Array;
+    release(): void;
+}
+export interface MotionBindingOptions {
+    /** Track x/y represent the visual center. Default: true. */
+    center?: boolean;
+}
+export interface PlaybackScopeStartOptions {
+    durationMs: number;
+    fromMs?: number;
+}
+export interface PlaybackFrame {
+    nowMs: number;
+    /** Active host-timeline delta; excludes explicit pause and hidden-page suspension. */
+    deltaMs: number;
+    progress: number;
+}
+/**
+ * Particle instance layout (16 floats): birth, lifetime, x, y, vx, vy, ax, ay,
+ * scale, scaleSpeed, rotation, spin, r, g, b, a. Times are seconds; positions are CSS pixels.
+ */
+export interface ParticleBatchDescriptor {
+    count: number;
+    instances: Float32Array;
+    particleSize?: number;
+    opacity?: number;
+    /** Sorts particle batches only. Particle batches composite after all media gift slots. */
+    zIndex?: number;
+    blend?: 'normal' | 'additive';
+    label?: string;
+}
+export interface ParticleBatchHandle {
+    readonly count: number;
+    readonly destroyed: boolean;
+    setTime(timeMs: number): void;
+    setOpacity(opacity: number): void;
+    destroy(): void;
+}
+export interface PlaybackScope {
+    readonly id: string;
+    readonly signal: AbortSignal;
+    readonly state: PlaybackScopeState;
+    readonly currentTimeMs: number;
+    addGift(options: AddGiftOptions): Promise<GiftHandle>;
+    createMotionTrack(descriptor: MotionTrackDescriptor): MotionTrackLease;
+    createParticleBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
+    bindMotion(gift: GiftHandle, track: MotionTrackLease, trackIndex: number, options?: MotionBindingOptions): () => void;
+    onFrame(listener: (frame: PlaybackFrame) => void): () => void;
+    onFinish(listener: () => void): () => void;
+    start(options: PlaybackScopeStartOptions): void;
+    pause(): void;
+    resume(): void;
+    seek(timeMs: number): void;
+    stop(): void;
+    destroy(): void;
+}
+export interface GiftStagePluginHost {
+    readonly stage: unknown;
+    readonly capabilities: GiftStageCapabilities;
+    getViewport(): {
+        width: number;
+        height: number;
+    };
+    preload(type: 'svga' | 'image', source: string | ArrayBuffer, signal?: AbortSignal): Promise<GiftAssetLease>;
+    createPlaybackScope(id?: string): PlaybackScope;
+}
+export interface GiftStagePlugin<TApi = unknown> {
+    readonly name: string;
+    /** Host contract version implemented by this plugin. Version 1 plugins may
+     * use PlaybackScope, asset leases, MotionTrack and GPU particle batches. */
+    readonly apiVersion?: 1;
+    setup(host: GiftStagePluginHost): TApi | Promise<TApi>;
+}
+export interface MountedGiftStagePlugin<TApi = unknown> {
+    readonly name: string;
+    readonly api: TApi;
+    readonly destroyed: boolean;
+    destroy(): void;
+}
+/** Internal bridge used by the scope without widening GiftStage's public surface. */
+export interface PlaybackScopeHost {
+    readonly backendType: BackendType;
+    readonly backend: GPUBackend | null;
+    getSlot(id: string): GiftSlot | undefined;
+    addGift(options: AddGiftOptions): Promise<GiftHandle>;
+    removeGift(id: string): void;
+    applyMediaTime(id: string, timeMs: number, emitInitialFrame?: boolean, discontinuous?: boolean): void;
+    invalidate(resetClock?: boolean): void;
+    registerFrameController(controller: PlaybackFrameController): () => void;
+    createParticleBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
+}
+export interface PlaybackFrameController {
+    readonly active: boolean;
+    tick(nowMs: number, deltaMs: number): boolean;
+}

package/dist/public.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="@webgpu/types" />
+export * from './index.js';

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

@@ -1,4 +1,4 @@
-import type { GPUBackend, GiftSlot } from '../types';
+import type { GPUBackend, GiftSlot } from '../types/index.js';
 export declare class AlphaVideoRenderer {
     private quadVB;
     private quadIB;

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

@@ -1,4 +1,4 @@
-import type { GPUBackend, GiftSlot } from '../types';
+import type { GPUBackend, GiftSlot } from '../types/index.js';
 export declare class ImageRenderer {
     private quadVB;
     private quadIB;

package/dist/renderers/index.d.ts

@@ -1,4 +1,4 @@
-export { SVGABatchRenderer } from './svga-batch-renderer';
-export { VAPRenderer } from './vap-renderer';
-export { AlphaVideoRenderer } from './alpha-video-renderer';
-export { buildBatchVerticesJS } from './vertex-builder';
+export { SVGABatchRenderer } from './svga-batch-renderer.js';
+export { VAPRenderer } from './vap-renderer.js';
+export { AlphaVideoRenderer } from './alpha-video-renderer.js';
+export { buildBatchVerticesJS } from './vertex-builder.js';

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

@@ -0,0 +1,19 @@
+import type { GPUBackend } from '../types/index.js';
+import type { ParticleBatchDescriptor, ParticleBatchHandle } from '../plugin/types.js';
+export declare class ParticleBatchRenderer {
+    private readonly backend;
+    private readonly batches;
+    private quadVB;
+    private quadIB;
+    private nextOrder;
+    private projW;
+    private projH;
+    private projection;
+    private readonly uniforms;
+    private readonly command;
+    constructor(backend: GPUBackend);
+    createBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
+    get activeCount(): number;
+    draw(): void;
+    destroy(): void;
+}

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

@@ -1,4 +1,12 @@
-import type { GPUBackend, GPUBufferHandle, GiftSlot, VideoEntity } from '../types';
+import type { GPUBackend, GPUBufferHandle, GiftSlot, VideoEntity } from '../types/index.js';
+/** Signals RenderManager to discard and replay the complete frame after a resource fallback. */
+export declare class SVGAFastPathFrameReplayError extends Error {
+    readonly entity: VideoEntity;
+    constructor(entity: VideoEntity);
+}
+export declare class SVGAStencilTransactionError extends Error {
+    constructor(message: string);
+}
 export interface ClipMeshCache {
     vertices: Float32Array;
     indices: Uint32Array;
@@ -31,8 +39,14 @@ interface SVGAClipPrewarmOptions {
     signal?: AbortSignal;
 }
 export type SVGAClipMeshMap = Map<string, ClipMeshCache>;
+export interface SVGABatchRuntimeDiagnosticEvent {
+    type: 'clip-protocol-error' | 'clip-mesh-invalid' | 'backend-operation-rejected' | 'atlas-command-invalid' | 'stencil-transaction-failure';
+    message?: string;
+}
 export declare class SVGABatchRenderer {
     private readonly onClipMeshReady?;
+    private readonly onHybridValidationFailure?;
+    private readonly onRuntimeDiagnostic?;
     private static readonly INSTANCED_QUAD_VERTS;
     private static readonly INSTANCED_QUAD_INDICES;
     /**
@@ -41,7 +55,10 @@ export declare class SVGABatchRenderer {
      * `invalidate()` a redraw — otherwise a slot whose animation has stopped dirtying may never
      * pick up the now-available precise clip.
      */
-    constructor(onClipMeshReady?: (() => void) | undefined);
+    constructor(onClipMeshReady?: (() => void) | undefined, onHybridValidationFailure?: ((entity: VideoEntity) => void) | undefined, onRuntimeDiagnostic?: ((event: SVGABatchRuntimeDiagnosticEvent) => void) | undefined);
+    /** Observers are downstream of renderer state and may never participate in control flow. */
+    private emitRuntimeDiagnostic;
+    private notifyClipMeshReady;
     private pool;
     private vertexBufHandles;
     private indexBufHandles;
@@ -55,18 +72,39 @@ export declare class SVGABatchRenderer {
     private projCacheH;
     private projCache;
     private clipMeshCache;
+    private clipMeshStates;
+    private clipMeshStateWaiters;
+    private clipMeshGeneration;
+    /** Shared producers outlive individual addGift/preload subscribers. */
+    private clipMeshProducerController;
+    private clipMeshProducerTasks;
+    private destroyed;
+    private clipMeshDestroyed;
+    private clipGeometryKindCache;
     /** Meshes with lazily created GPU buffers (released in destroy). */
     private clipMeshesWithBuffers;
+    private clipMeshRefCounts;
+    private entityRetainedClipMeshes;
     /** 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 stencilTransactionState;
     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;
+    /**
+     * Hybrid table batches can span slots without splitting into one draw per
+     * slot. Each row carries only parent/clip/schedule state; SVGA-local frame
+     * transforms, alpha and visibility remain resident in the frame table.
+     */
+    private timelineBatchDataScratch;
+    private timelineBatchFrameScratch;
+    /** Four vec4 values per Direct slot; child sprite rows remain resident in the frame table. */
+    private timelineDirectSlotDataScratch;
     private clipSpriteVertsScratch;
     private clipSpriteIndicesScratch;
     private clipMaskBatchTransformsScratch;
@@ -76,6 +114,8 @@ export declare class SVGABatchRenderer {
     private shapeMeshCache;
     /** Shape meshes with lazily created static GPU buffers (released in destroy). */
     private shapeMeshesWithBuffers;
+    private shapeMeshRefCounts;
+    private entityRetainedShapeMeshes;
     /** 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). */
@@ -105,6 +145,9 @@ export declare class SVGABatchRenderer {
     /** Reused scratch arrays (consumed synchronously). */
     private batchSpritesScratch;
     private drawGroupScratch;
+    private directSlotsScratch;
+    private hybridSlotsScratch;
+    private timelineSlotStateUploadId;
     private sharedSlotLayerWorkPool;
     private sharedSlotLayerWorksScratch;
     private clipLayerBatchPool;
@@ -113,6 +156,7 @@ export declare class SVGABatchRenderer {
     private entityHasShapesCache;
     /** 0=no clip, 1=scissor-compatible clips only, 2=stencil required, 255=not analyzed. */
     private entityFrameClipModeCache;
+    private gpuMotionEntityEligibilityCache;
     /**
      * 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
@@ -131,6 +175,21 @@ export declare class SVGABatchRenderer {
     private readonly plainInstancedTexturesScratch;
     private readonly plainInstancedUniformsScratch;
     private readonly plainInstancedDrawCommand;
+    /**
+     * GPU frame-table draw. Frame rows and sprite UV metadata are immutable on
+     * the entity; this reusable command uploads only one compact slot state.
+     */
+    private readonly timelineTexturesScratch;
+    private readonly timelineUniformsScratch;
+    private readonly timelineSlotStateScratch;
+    /** Parent/object-fit state is O(slot), even when a Hybrid schedule references
+     * the slot from many sprite layers in the same frame. */
+    private readonly timelineSlotStateCache;
+    private readonly timelineRenderableFrameCache;
+    private readonly timelineOriginScratch;
+    private readonly timelineDrawCommand;
+    private readonly timelineShapeDrawCommand;
+    private readonly timelineClipDrawCommand;
     private readonly plainBatchTexturesScratch;
     private readonly plainBatchUniformsScratch;
     private readonly plainBatchDrawCommand;
@@ -161,9 +220,24 @@ export declare class SVGABatchRenderer {
     private readonly shapeUniformsScratch;
     private readonly shapeDrawCommand;
     beginFrame(backend: GPUBackend): void;
+    endFrame(): void;
+    abortFrame(): void;
     flush(backend: GPUBackend, slots: Map<string, GiftSlot>): void;
     drawSlot(backend: GPUBackend, slot: GiftSlot): void;
     drawSlots(backend: GPUBackend, slots: Iterable<GiftSlot>): void;
+    private submitBackendDraw;
+    private assertRendererAlive;
+    private requireBackendDraw;
+    private areDirectSlotsBatchCompatible;
+    private areHybridSlotsBatchCompatible;
+    private areTimelineMotionBindingsCompatible;
+    private rejectFastPathFrame;
+    /**
+     * Preserves slot-major paint order while collapsing compatible same-resource
+     * Direct slots into one indexed instanced draw. Chunks contain complete slots
+     * so no slot can cross a render-order boundary.
+     */
+    private flushDirectSlots;
     requiresStencil(slots: Iterable<GiftSlot>): boolean;
     /**
      * Returns the target frame only when every clip path referenced by its visible sprites has a
@@ -175,9 +249,32 @@ export declare class SVGABatchRenderer {
     private getFrameClipMode;
     prewarmClipMeshes(entity: Pick<VideoEntity, 'spriteTable'>, options?: SVGAClipPrewarmOptions): Promise<number>;
     prewarmClipMeshesForFrame(entity: Pick<VideoEntity, 'spriteTable'>, frame: number, options?: SVGAClipPrewarmOptions): Promise<number>;
+    /**
+     * Precompiles every immutable Shape group and uploads its static mesh once.
+     * Hybrid table promotion waits for this preparation so the first promoted
+     * frame never pays SVG parsing/triangulation or buffer allocation.
+     */
+    prewarmShapeMeshes(backend: GPUBackend, entity: Pick<VideoEntity, 'spriteTable'>): number;
+    /** Validates every immutable Hybrid mesh reference and retains its GPU buffers for this entity. */
+    retainHybridMeshes(backend: GPUBackend, entity: VideoEntity): void;
+    releaseHybridMeshes(backend: GPUBackend, entity: VideoEntity): void;
     private collectFrameClipPaths;
-    /** Builds every not-yet-cached path in `paths`, worker-first with a frame-budgeted fallback. */
+    /**
+     * Ensures shared producers exist, then waits as the current subscriber. A subscriber signal
+     * never owns or cancels shared mesh production; it only detaches this caller's waiter.
+     */
     private buildMissingClipMeshes;
+    /** Claims paths synchronously so concurrent subscribers can only observe one producer. */
+    private startClipMeshProducer;
+    /** Worker-first shared production with exactly one main-thread fallback. */
+    private runClipMeshProducer;
+    /** No non-destroy producer exit may strand a path in `building`. */
+    private failClipMeshProducer;
+    private emitClipProducerDiagnosticsAfterTerminal;
+    private publishClipMeshState;
+    private waitForClipMeshPaths;
+    private waitForClipMeshPath;
+    private settleClipMeshStateWaiters;
     /**
      * 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
@@ -189,6 +286,24 @@ export declare class SVGABatchRenderer {
     private flushPendingClipMeshBuilds;
     hydrateClipMeshes(meshes: SVGAClipMeshMap | null | undefined): void;
     snapshotClipMeshes(entity: Pick<VideoEntity, 'spriteTable'>): SVGAClipMeshMap;
+    private canUseTimelinePath;
+    private resolveTimelineSlotState;
+    private resolveCachedTimelineSlotState;
+    private drawTimelineRange;
+    private drawTimelineSlot;
+    private getClipMeshByIndex;
+    private handleInvalidClipMesh;
+    private drawTimelineMesh;
+    private flushHybridScheduledSlots;
+    /**
+     * Reordering a shared command slice across slots is legal only when their
+     * conservative outer clip bounds are disjoint. The test also locks the
+     * authoritative frame so one immutable operation sequence serves the group.
+     */
+    private prepareDisjointHybridSlots;
+    /** Executes only the immutable command slice for the CPU-authoritative frame. */
+    private drawHybridScheduledSlot;
+    private drawHybridScheduledOperations;
     private flushGroup;
     /**
      * Transposes disjoint slots sharing one entity into sprite layers. Reordering across slots is
@@ -221,8 +336,26 @@ export declare class SVGABatchRenderer {
     private drawFromStaticBatchCache;
     private getProjection;
     private drawBatch;
+    /**
+     * Hybrid path: CPU keeps the already-established topology/order decisions,
+     * while each contiguous texture run fetches its transform/alpha from the
+     * immutable GPU frame table. A compact per-draw schedule row carries only
+     * parent/clip/frame/metadata routing when the run spans slots or sprite rows.
+     */
+    private tryDrawTimelineBatch;
+    /**
+     * Draws a Hybrid batch whose CPU-precompiled schedule spans multiple slots
+     * or non-contiguous sprite rows. The compact 16-float rows contain no SVGA
+     * child matrix/alpha: the shader fetches those by `(spriteIndex, frame)`.
+     */
+    private drawTimelineWorks;
+    /** Resolves all planner/capacity state before a stencil transaction publishes its mask. */
+    private prepareTimelineWorks;
+    private submitPreparedTimelineWorks;
+    private canUseGpuMotion;
     private drawBatchInstancedWebGL;
     private drawClippedSprite;
+    private drawTimelineStencilTest;
     /**
      * 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
@@ -263,7 +396,7 @@ export declare class SVGABatchRenderer {
     private appendStroke;
     private clamp01;
     private cleanupPoints;
-    private getClipMesh;
+    private getClipGeometryKind;
     /**
      * 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
@@ -273,9 +406,9 @@ export declare class SVGABatchRenderer {
      * 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.
+     * The path is queued for a background build instead (see `queueClipMeshBuild`). Callers discard
+     * the complete frame while it is unresolved; a redraw is requested once the mesh lands, so no
+     * sprite is ever submitted without its authoritative clip.
      */
     private getClipMeshForSprite;
     private ensureVertexBuffer;

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

@@ -1,4 +1,4 @@
-import type { GPUBackend, GiftSlot } from '../types';
+import type { GPUBackend, GiftSlot } from '../types/index.js';
 export declare class VAPRenderer {
     private instancedQuadVB;
     private instancedQuadIB;

package/dist/shaders/index.d.ts

@@ -7,6 +7,18 @@ export declare const glsl: {
         readonly vert: string;
         readonly frag: string;
     };
+    readonly svgaFrameTableInstancedPremul: {
+        readonly vert: string;
+        readonly frag: string;
+    };
+    readonly svgaFrameTableShape: {
+        readonly vert: string;
+        readonly frag: string;
+    };
+    readonly svgaFrameTableClipMask: {
+        readonly vert: string;
+        readonly frag: string;
+    };
     readonly vap: {
         readonly vert: string;
         readonly frag: string;
@@ -39,6 +51,10 @@ export declare const glsl: {
         readonly vert: string;
         readonly frag: string;
     };
+    readonly particleInstanced: {
+        readonly vert: string;
+        readonly frag: string;
+    };
 };
 export declare const wgsl: {
     readonly svgaBatchPremul: string;
@@ -51,4 +67,8 @@ export declare const wgsl: {
     readonly rgbaTextured: string;
     readonly clipMask: string;
     readonly clipMaskInstanced: string;
+    readonly particleInstanced: string;
+    readonly svgaMotionInstancedPremul: string;
+    readonly svgaFrameTableShape: string;
+    readonly svgaFrameTableClipMask: string;
 };