@taole/giftstage 0.3.3 → 0.3.4

package/README.md

@@ -153,7 +153,9 @@ mounted.destroy();
 
 `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，不能在新设备上复活。
+atlas descriptor 必须提供 `width × height × 4` 的不可变 `Uint8Array`，声明 `colorSpace:'srgb'` 与 `alphaMode:'premultiplied'`。透明像素 RGB 应为零；shader 不会再次乘采样 alpha。`ParticleAtlasHandle.destroy()` 只释放调用方 lease，存活 group 会保留内部引用；context/device loss 后旧 handle 的 `lost` 为 true，不能在新设备上复活。
+
+`await host.createParticleAtlas()` 同时等待 sprite-v2 管线准备完成，建议放在插件预加载阶段、`scope.start()` 之前。WebGPU 使用异步编译并缓存普通/叠加混合及有/无 stencil 的四种管线；WebGL2 提前编译并链接粒子程序。预加载不会绘制舞台或推进时钟，重复创建 atlas 会复用管线；准备失败时 atlas 创建会拒绝，不发布半就绪资源。此优化移除粒子管线首次编译造成的播放期停顿，不改变动画时长，也不保证其他素材或驱动工作完全没有长帧。
 
 envelope 使用绝对毫秒半开区间 `[startMs,endMs)`，支持 `linear` / `hold`，边界右连续，因此可以表达中心闪光的瞬时跳变。`setTime()` 仅更新每 batch header，实例 buffer 创建后保持不变；pause 不产生写入，seek 直接求值绝对时间。
 
@@ -212,8 +214,9 @@ envelope 使用绝对毫秒半开区间 `[startMs,endMs)`，支持 `linear` / `h
   SVGA atlas 在主线程组合或逐页上传时的单帧时间片上限，默认 `12ms`。
   实际时间片会按当前刷新周期的一半动态调整，避免高刷新率设备上的加载任务挤占渲染帧。
 
-- `svgaLoadFrameBudgetMs?: number`
-  SVGA 主线程加载任务的共享时间片上限，默认 `12ms`。图片 fallback、atlas、clip、音频、slot 纹理和二进制缓存共用同一帧预算。
+- `svgaLoadFrameBudgetMs?: number`
+  SVGA 主线程加载任务的共享时间片上限，默认 `12ms`。图片 fallback、atlas、clip、音频、slot 纹理、二进制缓存和 Hybrid 命令表构建共用同一帧预算。
+  Hybrid 的路径解析、裁剪检查、逐帧计划和命令打包会分片执行；同一资源的重复裁剪路径复用分类和矩形结果，避免视频与复杂 SVGA 同播时被同步准备工作阻塞。资源释放或后端丢失后会取消未完成的构建。
 
 - `svgaWorkerFrameBudgetMs?: number`
   SVGA Worker 连续执行 JS 循环的时间片上限，默认 `4ms`，范围 `1-8ms`。单次 WASM protobuf 调用和单次原生 API 调用仍不可抢占。

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

@@ -111,6 +111,7 @@ export declare class GiftStage {
      * playbacks can start directly on the selected GPU path.
      */
     private ensureSVGAFrameTable;
+    private assertSVGAFrameTableActive;
     private refreshSVGATimelineSlots;
     private assignSVGATimelineStateToSlot;
     private releaseSVGAFrameTable;