@taole/giftstage 0.2.2 → 0.3.1

package/README.md

@@ -142,8 +142,20 @@ mounted.destroy();
 - `preload()`：复用 GiftStage 的 SVGA/Image 缓存并返回引用计数资源租约。
 - `createPlaybackScope()`：使用 GiftStage 唯一 RAF、逻辑时钟和作用域清理；SVGA、WebCodecs、HTMLVideo 回退与定时图片均按 Scope 绝对时间定位，不叠加 RenderManager 的全局 `dt`。SVGA 的可见帧、`onFrame` 与嵌入音频由同一个绝对时间入口同步，跨帧、seek、循环和暂停恢复会重建正确音频偏移，且 `start()` 前不会触发首帧音频/回调。HTMLVideo 在 Scope 内保持暂停并使用独立实例，显式暂停和页面隐藏期间逻辑时间冻结。
 - `createMotionTrack()`：接收 8-float TypedArray/SoA 父级轨道。WebGPU 可把它与核心 SVGA 帧表在同一顶点着色器中合成；WebGL2 的 SVGA 内部帧仍可走 GPU Direct/Hybrid，但父级 MotionTrack 继续使用确定性 CPU reference sampler。图片与 WebGL1 同样使用 CPU reference。
-- `createParticleBatch()`：WebGPU/WebGL2 使用持久实例缓冲和 GPU 弹道求值；WebGL1 明确不可用，不提供 Canvas2D 粒子后端。粒子统一在媒体礼物之后合成，`zIndex` 只控制粒子批次之间的顺序。
-- `stage.capabilities`：插件可在播放前判断实际后端、GPU 轨道媒体范围和粒子能力。
+- `createParticleBatch()`：保留 16-float `ballistic-v1` ABI，WebGPU/WebGL2 使用持久实例缓冲和 GPU 弹道求值；缺省仍在媒体之后合成。
+- `host.createParticleAtlas()` + `scope.createParticleBatchGroup()`：可选 `sprite-v2` 能力。插件上传一次不可变预乘 RGBA8 atlas，再以原子 group 发布多个 24-float sprite batch。group 任一 draw 失败会 abort 整帧并以同一权威时间重放，不会显示 smoke-only 等局部结果。
+- 粒子 `compositeLayer` 支持 `behind-media` / `above-media`；正式帧顺序为 `begin → behind particles → media → above particles → end`，`zIndex` 只在同一 phase 内排序。WebGL1 明确不可用，不提供 Canvas2D 粒子后端。
+- `stage.capabilities`：插件可在播放前判断实际后端、GPU 轨道媒体范围和粒子能力。
+
+### ParticleBatch v2 迁移
+
+`stage.capabilities.particles.formats` 包含 `sprite-v2`，且同时具备 `spriteAtlas`、`compositeLayers`、`batchEnvelope`、`atomicBatchGroup` 和 `maxInstancesPerBatch` 时，插件才能启用纹理粒子；不得只按 `apiVersion` 判断。旧核心缺少这些可选字段时继续使用原有 v1 或明确跳过效果。
+
+`sprite-v2` 每实例为 24 floats：`0–15` 完全延续 birth/lifetime/弹道/scale/rotation/RGBA，`16–17` 是 CSS 逻辑宽高，`18–19` 是归一化 anchor，`20–23` 是 atlas UV。header 为 8 floats：秒制时间、已求值 opacity、已求值 size、fade mode、`sx/sy` 与两个零 padding。WebGL2 的实例 stride 为 96 bytes、header 为 32 bytes；WebGPU 从 `8 + instanceIndex × 24` 读取。非均匀 backing scale 只在最终顶点应用，不能再用 `sqrt(sx × sy)` 近似 v2 尺寸。
+
+atlas descriptor 必须提供 `width × height × 4` 的不可变 `Uint8Array`，声明 `colorSpace:'srgb'` 与 `alphaMode:'premultiplied'`。透明像素 RGB 应为零；shader 不会再次乘采样 alpha。`ParticleAtlasHandle.destroy()` 只释放调用方 lease，存活 group 会保留内部引用；context/device loss 后旧 handle 的 `lost` 为 true，不能在新设备上复活。
+
+envelope 使用绝对毫秒半开区间 `[startMs,endMs)`，支持 `linear` / `hold`，边界右连续，因此可以表达中心闪光的瞬时跳变。`setTime()` 仅更新每 batch header，实例 buffer 创建后保持不变；pause 不产生写入，seek 直接求值绝对时间。
 
 ## 核心 API
 
@@ -230,7 +242,7 @@ SVGA 礼物在加载阶段被 `destroy()` / `removeGift()` 时，会取消排队
   当 SVGA 礼物完成资格分析、帧表上传、原子晋升或发生回退时通知路径变化。除资源与路径字段外，`info` 还包含 `pathState`、`frameTableBytes`、`commandTableBytes`、`drawBatchMode` 和 `drawCompatibleInstanceCount`。
 
 - `onRuntimeDiagnostic?: (event) => void`
-  接收 frame abort、replay failure、无时钟 retry、运行期 fallback、Clip 协议/网格异常、Stencil 事务失败、Atlas 命令无效、Backend 操作拒绝/隔离、WebGPU uncaptured error、backend loss 和 observer error 等结构化事件。事件只在本地回调，不会由 GiftStage 上传；回调异常会被隔离，不能中断渲染降级事务。
+  接收 frame abort、replay failure、无时钟 retry、frame controller failure、运行期 fallback、Clip 协议/网格异常、Stencil 事务失败、Atlas 命令无效、Particle group 原子失败、Backend 操作拒绝/隔离、WebGPU uncaptured error、backend loss 和 observer error 等结构化事件。事件只在本地回调，不会由 GiftStage 上传；回调异常会被隔离，不能中断渲染降级事务。
 
 ### `await stage.ready`
 

package/dist/core/gift-stage.d.ts

@@ -1,5 +1,5 @@
 import type { GiftStageOptions, AddGiftOptions, GiftHandle, BackendType, GiftStageRuntimeDiagnostics } from '../types/index.js';
-import { type GiftAssetLease, type GiftStageCapabilities, type GiftStagePlugin, type MountedGiftStagePlugin, type PlaybackScope } from '../plugin/types.js';
+import { type GiftAssetLease, type GiftStageCapabilities, type GiftStagePlugin, type MountedGiftStagePlugin, type ParticleAtlasDescriptor, type ParticleAtlasHandle, type PlaybackScope } from '../plugin/types.js';
 export declare function resolveResourcePipelineConcurrency(explicit: number | undefined, hardwareConcurrency?: number | undefined): number;
 export declare class GiftStage {
     private static readonly SVGA_ATLAS_MAX_SIZE;
@@ -197,6 +197,7 @@ export declare class GiftStage {
     private waitVideoReady;
     get capabilities(): GiftStageCapabilities;
     preload(type: 'svga' | 'image', source: string | ArrayBuffer, signal?: AbortSignal): Promise<GiftAssetLease>;
+    createParticleAtlas(descriptor: ParticleAtlasDescriptor): Promise<ParticleAtlasHandle>;
     createPlaybackScope(id?: string): PlaybackScope;
     mount<TApi>(plugin: GiftStagePlugin<TApi>): Promise<MountedGiftStagePlugin<TApi>>;
     removeGift(id: string): void;

package/dist/core/render-manager.d.ts

@@ -4,14 +4,14 @@ import { PostAnimator } from './post-animator.js';
 import { AudioManager } from './audio-manager.js';
 import { type WebCodecsAtlasRect } from './webcodecs-video-atlas.js';
 import type { PlaybackFrameController } from '../plugin/types.js';
-import type { ParticleBatchDescriptor, ParticleBatchHandle } from '../plugin/types.js';
+import type { ParticleAtlasDescriptor, ParticleAtlasHandle, ParticleBatchDescriptor, ParticleBatchGroupHandle, ParticleBatchHandle } from '../plugin/types.js';
 export interface RenderManagerRuntimeDiagnostics {
     frameAbortCount: number;
     replayFailureCount: number;
     retryFrameCount: number;
 }
 export interface RenderManagerRuntimeDiagnosticEvent {
-    type: 'svga-frame-abort' | 'svga-frame-replay-failed' | 'svga-frame-retry' | 'backend-operation-rejected' | 'backend-quarantined' | 'stencil-transaction-failure' | 'clip-protocol-error' | 'clip-mesh-invalid' | 'atlas-command-invalid';
+    type: 'svga-frame-abort' | 'svga-frame-replay-failed' | 'svga-frame-retry' | 'backend-operation-rejected' | 'backend-quarantined' | 'stencil-transaction-failure' | 'clip-protocol-error' | 'clip-mesh-invalid' | 'atlas-command-invalid' | 'frame-controller-failure' | 'particle-group-failure';
     message?: string;
 }
 export declare class RenderManager {
@@ -72,6 +72,9 @@ export declare class RenderManager {
     countCompatibleSVGAInstances(entity: VideoEntity): number;
     registerFrameController(controller: PlaybackFrameController): () => void;
     createParticleBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
+    createParticleAtlas(descriptor: ParticleAtlasDescriptor): Promise<ParticleAtlasHandle>;
+    createParticleBatchGroup(descriptors: readonly ParticleBatchDescriptor[]): ParticleBatchGroupHandle;
+    handleBackendLoss(): void;
     /**
      * Reserve a sub-rectangle in the shared WebCodecs atlas (when `webCodecsVideoAtlas` is configured).
      * Returns null if disabled, full, or size mismatch while the atlas is still in use.