@taole/giftstage 0.2.2 → 0.3.1

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

@@ -144,6 +144,7 @@ export declare class WebGL2Backend implements GPUBackend {
     private recordSubmittedDraw;
     private rejectSVGAFastPathDraw;
     private initPrograms;
+    private ensureParticleSpriteProgram;
     private makeProgramEntry;
     /**
      * `u_transform` on `svga-batch-premul` defaults to identity; shape draws overwrite it and
@@ -238,6 +239,7 @@ export declare class WebGL2Backend implements GPUBackend {
     /** Shape/clip meshes fetch their child transform from the same resident frame table. */
     private drawSVGAFrameTableMeshGL;
     private drawInstancedParticlesGL;
+    private drawInstancedParticleSpritesGL;
     private drawInstancedSvgaGL;
     private ensureInstancedClipMaskBuffer;
     private drawInstancedClipMaskGL;

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

@@ -214,6 +214,7 @@ export declare class WebGPUBackend implements GPUBackend {
     private ensureSVGAFrameTableMeshPipeline;
     private ensureMotionSvgaPipeline;
     private ensureParticlePipeline;
+    private ensureParticleSpritePipeline;
     private createInstancedSvgaPipeline;
     private createInstancedClipMaskPipeline;
     private createVapInstancedPipeline;

package/dist/index.d.ts

@@ -33,4 +33,4 @@ export { initWasm, isWasmReady } from './wasm/wasm-bridge.js';
 export { WebCodecsMp4Playback } from './video/webcodecs-mp4-playback.js';
 export type { WebCodecsMp4CreateOptions } from './video/webcodecs-mp4-playback.js';
 export type { WebCodecsPlaybackHandle, GPUBackend, BackendOperationFailureReason, BackendOperationResult, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, ShaderType, BackendType, ParentMotionMode, SVGADrawBatchMode, SVGAFrameEvaluation, SVGAFrameEvaluationStrategy, SVGAFrameTableBinding, SVGAFrameTableBindingBase, SVGAFrameTableCreateOptions, SVGAFrameTableState, SVGAFrameTimelineFallbackReason, SVGAFrameTimelinePath, SVGAFrameTimelineRenderInfo, SVGAFrameTimelineStrategy, SVGAFrameTimelineTransport, SVGARenderFallbackReason, SVGARenderInfo, SVGARenderPath, SVGARenderPathState, SVGARenderPathChangeInfo, GiftStageRuntimeDiagnosticType, GiftStageRuntimeDiagnosticEvent, GiftStageRuntimeDiagnostics, SVGAHybridCommandTable, SVGAHybridOperation, SVGAHybridOperationType, SVGATimelineDrawRun, WebGL2FrameTableBinding, WebGPUFrameTableBinding, GiftStageOptions, AddGiftOptions, GiftHandle, GiftSlot, GiftType, GiftObjectFit, GiftCoordinate, GiftState, GiftAnimationStep, GiftAnimationChain, SVGAMovieEntity, SVGAParams, SVGASpriteTable, SVGAAudio, SVGATransform, SVGAShape, VideoEntity, UVRect, FrameJobData, FlyAnimation, VAPConfig, VAPSrcItem, VAPFrameItem, VAPFrameObj, } from './types/index.js';
-export type { GiftAssetLease, GiftAssetMetadata, GiftStageCapabilities, SVGAFrameTimelineCapabilities, GiftStagePlugin, GiftStagePluginHost, MountedGiftStagePlugin, MotionBindingOptions, MotionTrackDescriptor, MotionTrackLease, ParticleBatchDescriptor, ParticleBatchHandle, PlaybackFrame, PlaybackScope, PlaybackScopeStartOptions, PlaybackScopeState, ReadonlyTableDescriptor, ReadonlyTableLease, } from './plugin/types.js';
+export type { GiftAssetLease, GiftAssetMetadata, GiftStageCapabilities, SVGAFrameTimelineCapabilities, GiftStagePlugin, GiftStagePluginHost, MountedGiftStagePlugin, MotionBindingOptions, MotionTrackDescriptor, MotionTrackLease, BallisticV1ParticleBatchDescriptor, ParticleAtlasDescriptor, ParticleAtlasHandle, ParticleBatchDescriptor, ParticleBatchEnvelope, ParticleBatchGroupHandle, ParticleBatchHandle, ParticleEnvelopeSegment, SpriteV2ParticleBatchDescriptor, PlaybackFrame, PlaybackScope, PlaybackScopeStartOptions, PlaybackScopeState, ReadonlyTableDescriptor, ReadonlyTableLease, } from './plugin/types.js';

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

@@ -1,5 +1,5 @@
 import type { AddGiftOptions, GiftHandle } from '../types/index.js';
-import type { MotionBindingOptions, MotionTrackDescriptor, MotionTrackLease, ParticleBatchDescriptor, ParticleBatchHandle, PlaybackFrame, PlaybackFrameController, PlaybackScope, PlaybackScopeHost, PlaybackScopeStartOptions, PlaybackScopeState } from './types.js';
+import type { MotionBindingOptions, MotionTrackDescriptor, MotionTrackLease, ParticleBatchDescriptor, ParticleBatchGroupHandle, ParticleBatchHandle, PlaybackFrame, PlaybackFrameController, PlaybackScope, PlaybackScopeHost, PlaybackScopeStartOptions, PlaybackScopeState } from './types.js';
 export declare class PlaybackScopeImpl implements PlaybackScope, PlaybackFrameController {
     readonly id: string;
     private readonly host;
@@ -8,6 +8,7 @@ export declare class PlaybackScopeImpl implements PlaybackScope, PlaybackFrameCo
     private readonly tracks;
     private readonly bindings;
     private readonly particleBatches;
+    private readonly particleBatchGroups;
     private readonly frameListeners;
     private readonly finishListeners;
     private unregisterController;
@@ -23,6 +24,7 @@ export declare class PlaybackScopeImpl implements PlaybackScope, PlaybackFrameCo
     addGift(options: AddGiftOptions): Promise<GiftHandle>;
     createMotionTrack(descriptor: MotionTrackDescriptor): MotionTrackLease;
     createParticleBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
+    createParticleBatchGroup(descriptors: readonly ParticleBatchDescriptor[]): ParticleBatchGroupHandle;
     bindMotion(gift: GiftHandle, track: MotionTrackLease, trackIndex: number, options?: MotionBindingOptions): () => void;
     onFrame(listener: (frame: PlaybackFrame) => void): () => void;
     onFinish(listener: () => void): () => void;

package/dist/plugin/types.d.ts

@@ -51,6 +51,16 @@ export interface GiftStageCapabilities {
     particles: {
         backend: 'webgpu' | 'webgl2' | 'unavailable';
         canvas2D: false;
+        /** Optional feature negotiation. Absent on pre-sprite-v2 hosts. */
+        formats?: Array<'ballistic-v1' | 'sprite-v2'>;
+        spriteAtlas?: {
+            source: 'rgba8-premultiplied';
+            maxSize: number;
+        };
+        compositeLayers?: Array<'behind-media' | 'above-media'>;
+        batchEnvelope?: boolean;
+        atomicBatchGroup?: boolean;
+        maxInstancesPerBatch?: number;
     };
     /** Public SVGA frame-table path support exposed to playback plugins. */
     svgaFrameTimeline?: SVGAFrameTimelineCapabilities;
@@ -107,16 +117,65 @@ export interface PlaybackFrame {
  * 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 {
+export interface BallisticV1ParticleBatchDescriptor {
+    /** Omitted for backward compatibility. */
+    format?: 'ballistic-v1';
     count: number;
     instances: Float32Array;
     particleSize?: number;
     opacity?: number;
-    /** Sorts particle batches only. Particle batches composite after all media gift slots. */
+    /** Sorts particle batches inside their composite phase only. */
     zIndex?: number;
     blend?: 'normal' | 'additive';
+    /** v1 remains above media unless explicitly requested otherwise. */
+    compositeLayer?: 'behind-media' | 'above-media';
     label?: string;
 }
+export interface ParticleAtlasDescriptor {
+    width: number;
+    height: number;
+    pixels: Uint8Array;
+    colorSpace: 'srgb';
+    alphaMode: 'premultiplied';
+    filter?: 'linear';
+    label?: string;
+}
+export interface ParticleAtlasHandle {
+    readonly width: number;
+    readonly height: number;
+    /** The caller lease was released. Existing groups may retain the GPU resource. */
+    readonly destroyed: boolean;
+    /** The owning backend generation was lost. Lost handles cannot be reused. */
+    readonly lost: boolean;
+    destroy(): void;
+}
+export interface ParticleEnvelopeSegment {
+    /** Absolute playback milliseconds. Segments use the half-open interval [startMs, endMs). */
+    startMs: number;
+    endMs: number;
+    from: number;
+    to: number;
+    interpolation?: 'linear' | 'hold';
+}
+export interface ParticleBatchEnvelope {
+    opacity?: readonly ParticleEnvelopeSegment[];
+    size?: readonly ParticleEnvelopeSegment[];
+}
+export interface SpriteV2ParticleBatchDescriptor {
+    format: 'sprite-v2';
+    atlas: ParticleAtlasHandle;
+    count: number;
+    /** 24 floats per instance; the first 16 preserve ballistic-v1 semantics. */
+    instances: Float32Array;
+    opacity?: number;
+    fadeMode?: 'none' | 'lifetime';
+    envelope?: ParticleBatchEnvelope;
+    compositeLayer?: 'behind-media' | 'above-media';
+    zIndex?: number;
+    blend?: 'normal' | 'additive';
+    label?: string;
+}
+export type ParticleBatchDescriptor = BallisticV1ParticleBatchDescriptor | SpriteV2ParticleBatchDescriptor;
 export interface ParticleBatchHandle {
     readonly count: number;
     readonly destroyed: boolean;
@@ -124,6 +183,14 @@ export interface ParticleBatchHandle {
     setOpacity(opacity: number): void;
     destroy(): void;
 }
+export interface ParticleBatchGroupHandle {
+    readonly count: number;
+    readonly destroyed: boolean;
+    readonly faulted: boolean;
+    setTime(timeMs: number): void;
+    setOpacity(opacity: number): void;
+    destroy(): void;
+}
 export interface PlaybackScope {
     readonly id: string;
     readonly signal: AbortSignal;
@@ -132,6 +199,8 @@ export interface PlaybackScope {
     addGift(options: AddGiftOptions): Promise<GiftHandle>;
     createMotionTrack(descriptor: MotionTrackDescriptor): MotionTrackLease;
     createParticleBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
+    /** Optional in API v1; feature-detect through `capabilities.particles.atomicBatchGroup`. */
+    createParticleBatchGroup?(descriptors: readonly ParticleBatchDescriptor[]): ParticleBatchGroupHandle;
     bindMotion(gift: GiftHandle, track: MotionTrackLease, trackIndex: number, options?: MotionBindingOptions): () => void;
     onFrame(listener: (frame: PlaybackFrame) => void): () => void;
     onFinish(listener: () => void): () => void;
@@ -150,6 +219,8 @@ export interface GiftStagePluginHost {
         height: number;
     };
     preload(type: 'svga' | 'image', source: string | ArrayBuffer, signal?: AbortSignal): Promise<GiftAssetLease>;
+    /** Optional in API v1; uploads one immutable premultiplied RGBA8 atlas. */
+    createParticleAtlas?(descriptor: ParticleAtlasDescriptor): Promise<ParticleAtlasHandle>;
     createPlaybackScope(id?: string): PlaybackScope;
 }
 export interface GiftStagePlugin<TApi = unknown> {
@@ -176,6 +247,7 @@ export interface PlaybackScopeHost {
     invalidate(resetClock?: boolean): void;
     registerFrameController(controller: PlaybackFrameController): () => void;
     createParticleBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
+    createParticleBatchGroup?(descriptors: readonly ParticleBatchDescriptor[]): ParticleBatchGroupHandle;
 }
 export interface PlaybackFrameController {
     readonly active: boolean;

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

@@ -1,19 +1,62 @@
 import type { GPUBackend } from '../types/index.js';
-import type { ParticleBatchDescriptor, ParticleBatchHandle } from '../plugin/types.js';
+import type { ParticleAtlasDescriptor, ParticleAtlasHandle, ParticleBatchDescriptor, ParticleBatchGroupHandle, ParticleBatchHandle } from '../plugin/types.js';
+type ParticleCompositeLayer = 'behind-media' | 'above-media';
+export declare class ParticleBatchGroupDrawError extends Error {
+    readonly group: ParticleBatchGroupHandle;
+    constructor(group: ParticleBatchGroupHandle, message: string);
+}
 export declare class ParticleBatchRenderer {
     private readonly backend;
     private readonly batches;
+    private readonly groups;
+    private readonly atlases;
+    private readonly onRuntimeDiagnostic?;
     private quadVB;
     private quadIB;
     private nextOrder;
     private projW;
     private projH;
     private projection;
+    private backendLost;
+    private destroyed;
+    private drawOrderDirty;
+    private readonly behindDrawOrder;
+    private readonly aboveDrawOrder;
+    private readonly cssScaleUniform;
     private readonly uniforms;
     private readonly command;
-    constructor(backend: GPUBackend);
+    constructor(backend: GPUBackend, onRuntimeDiagnostic?: (event: {
+        type: 'particle-group-failure';
+        message?: string;
+    }) => void);
+    createAtlas(descriptor: ParticleAtlasDescriptor): Promise<ParticleAtlasHandle>;
     createBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
+    createBatchGroup(descriptors: readonly ParticleBatchDescriptor[]): ParticleBatchGroupHandle;
     get activeCount(): number;
-    draw(): void;
+    private rebuildDrawOrder;
+    draw(compositeLayer?: ParticleCompositeLayer): void;
+    /** Uploads complete dirty groups inside the active framebuffer transaction. */
+    prepareFrame(): void;
+    onBackendLoss(): void;
     destroy(): void;
+    private assertAvailable;
+    private validateDescriptor;
+    private validateEnvelope;
+    private cloneEnvelope;
+    private createGroupRecord;
+    private stageRecord;
+    private setRecordTime;
+    private setRecordOpacity;
+    private updateRecordHeader;
+    private syncRecordCssScale;
+    private evaluateEnvelope;
+    private faultGroup;
+    private destroyGroup;
+    private destroyRecord;
+    private disposeStagedRecord;
+    private retainAtlas;
+    private releaseAtlasCaller;
+    private releaseAtlasRetain;
+    private releaseAtlasRef;
 }
+export {};

package/dist/shaders/index.d.ts

@@ -55,6 +55,10 @@ export declare const glsl: {
         readonly vert: string;
         readonly frag: string;
     };
+    readonly particleSpriteInstanced: {
+        readonly vert: string;
+        readonly frag: string;
+    };
 };
 export declare const wgsl: {
     readonly svgaBatchPremul: string;
@@ -68,6 +72,7 @@ export declare const wgsl: {
     readonly clipMask: string;
     readonly clipMaskInstanced: string;
     readonly particleInstanced: string;
+    readonly particleSpriteInstanced: string;
     readonly svgaMotionInstancedPremul: string;
     readonly svgaFrameTableShape: string;
     readonly svgaFrameTableClipMask: string;

package/dist/types/index.d.ts

@@ -21,7 +21,7 @@ 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';
+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' | 'frame-controller-failure' | 'particle-group-failure';
 /** One production-safe runtime event. GiftStage never uploads these events. */
 export interface GiftStageRuntimeDiagnosticEvent {
     type: GiftStageRuntimeDiagnosticType;
@@ -205,7 +205,9 @@ export type ShaderType = 'svga-batch-premul'
 /** WebGPU / WebGL2: one local-space clip mesh transformed by per-instance affine data. */
  | 'clip-mask-instanced'
 /** WebGPU / WebGL2: immutable ballistic particle instances evaluated in the vertex shader. */
- | 'particle-instanced';
+ | 'particle-instanced'
+/** WebGPU / WebGL2: immutable textured sprite-v2 particles sampled from an explicit atlas. */
+ | 'particle-sprite-instanced';
 export type StencilMode = 'none' | 'write' | 'test' | 'clear';
 export interface DrawCommand {
     shader: ShaderType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taole/giftstage",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "High-performance WebGPU/WebGL gift animation player unifying SVGA, VAP, AlphaVideo, and images",
   "type": "module",
   "main": "dist/gift-stage.cjs",