@taole/giftstage 0.1.36 → 0.2.1

package/README.md

@@ -1,719 +1,795 @@
-# GiftStage
-
-统一的 Web 礼物播放框架，支持：
-
-- `SVGA`
-- `VAP / VAPX`
-- 透明视频 `AlphaVideo`
-- 静态图片 `Image`
-
-底层支持：
-
-- `WebGPU`
-- `WebGL2`
-- `WebGL1` 兼容兜底
-
-适用场景：
-
-- 直播间礼物
-- 大批同屏动画
-- 需要统一接入 `SVGA / VAP / 透明视频 / 图片` 的业务场景
-
-## npm 包信息
-
-- 包名：`@taole/giftstage`
-- npm：`npm i @taole/giftstage`
-- ESM 导入：
-
-```ts
-import { GiftStage } from '@taole/giftstage';
-```
-
-- CommonJS 导入：
-
-```js
-const { GiftStage } = require('@taole/giftstage');
-```
-
-## 特性
-
-- 统一 API：`addGift()` 即可播放四类礼物
-- `SVGA` 支持 Worker 解析、atlas 缓存、slot 替换
-- `VAP / AlphaVideo` 支持实验性的 `WebCodecs` 和稳定的 `HTMLVideoElement` 双路径
-- 同源视频播放实例、纹理、资源复用
-- 内存 LRU 缓存，默认 `128MB`
-- `IndexedDB` 磁盘 LRU 缓存，默认 `2048MB`
-- `x / y` 支持百分比定位
-- `width / height` 支持按礼物原始尺寸自动补全
-- 四类礼物共用位移、缩放、透明度、旋转、层级和销毁生命周期
-
-## 安装
-
-```bash
-npm install
-```
-
-安装发布包：
-
-```bash
-npm i @taole/giftstage
-```
-
-## 开发
-
-```bash
-npm run dev
-```
-
-## 构建
-
-```bash
-npm run build
-```
-
-Demo 构建：
-
-```bash
-npm run build:demo
-```
-
-## 性能基线
-
-```bash
-# 在当前机器记录 WebGL2 / WebGPU 基线
-npm run perf:record
-
-# 与同浏览器主版本、硬件并发数、DPR 和视口的基线比较
-npm run test:perf
-```
-
-基线覆盖冷/热启动、100 个静态图片、50 个共享 SVGA、20 个共享 VAP 和 20 个共享 AlphaVideo，
-记录首帧、P50/P95 帧间隔、长任务、堆变化、提交帧、draw、纹理上传与 stencil 帧数。
-基线保存在 `tests/performance/baselines/`；Windows 会自动探测系统 Chrome，也可通过
-`PLAYWRIGHT_CHROME_EXECUTABLE_PATH` 指定浏览器。
-
-## 快速开始
-
-```ts
-import { GiftStage } from '@taole/giftstage';
-
-const container = document.getElementById('app')!;
-
-const stage = new GiftStage({
-  container,
-  preferWebGPU: true,
-});
-
-await stage.ready;
-
-await stage.addGift({
-  type: 'svga',
-  source: 'https://example.com/demo.svga',
-  x: 100,
-  y: 100,
-  loop: 0,
-});
-```
-
-## 核心 API
-
-### `new GiftStage(options)`
-
-创建礼物舞台。
-
-常用配置：
-
-- `container: HTMLElement`
-  挂载容器。
-
-- `resolution?: number`
-  指定 canvas backing store 分辨率倍率。默认跟随 `devicePixelRatio`。
-
-- `antialias?: boolean`
-  是否开启抗锯齿，WebGL 和 WebGPU 均默认开启；WebGPU 使用 4× MSAA。大量透明视频同时播放时可显式设为 `false`。
-
-- `preferWebGPU?: boolean`
-  是否优先使用 `WebGPU`。
-
-- `forceWebGL1?: boolean`
-  强制走 `WebGL1`，用于兼容性验证。
-
-- `preferWebCodecs?: boolean`
-  实验性特性。默认关闭；显式传 `true` 时才会尝试用 `WebCodecs` 播放 `VAP / AlphaVideo`。
-
-- `shareIdenticalVideoPlayback?: boolean`
-  是否复用近同时起播的同源视频播放实例。默认开启。
-
-- `sharedVideoPlaybackWindowMs?: number`
-  同源视频共享播放窗口，默认 `100ms`。
-
-- `webCodecsVideoAtlas?: { width: number; height: number }`
-  实验性 `WebCodecs` 视频共享 atlas 配置。
-
-- `webCodecsDecodeInWorker?: boolean`
-  实验性 `WebCodecs` 选项，控制是否在 Worker 中执行解码。
-
-- `webCodecsMaxDecodedFrames?: number`
-  实验性 `WebCodecs` 选项，控制保留的最大解码帧数。
-
-- `webCodecsDecodeAheadFrames?: number`
-  实验性 `WebCodecs` 选项，控制前向解码帧数。
-
-- `svgaParseInWorker?: boolean`
-  是否在 Worker 中解析 SVGA。
-
-- `maxConcurrentParse?: number`
-  资源下载 / 解析 / 图像解码的并发数。
-  不传时自动跟随 `navigator.hardwareConcurrency`。
-
-- `svgaAtlasFrameBudgetMs?: number`
-  SVGA atlas 在主线程组合或逐页上传时的单帧时间片上限，默认 `12ms`。
-  实际时间片会按当前刷新周期的一半动态调整，避免高刷新率设备上的加载任务挤占渲染帧。
-
-- `svgaLoadFrameBudgetMs?: number`
-  SVGA 主线程加载任务的共享时间片上限，默认 `12ms`。图片 fallback、atlas、clip、音频、slot 纹理和二进制缓存共用同一帧预算。
-
-- `svgaWorkerFrameBudgetMs?: number`
-  SVGA Worker 连续执行 JS 循环的时间片上限，默认 `4ms`，范围 `1-8ms`。单次 WASM protobuf 调用和单次原生 API 调用仍不可抢占。
-
-- `svgaWorkerTaskConcurrency?: number`
-  parser、图片解码、atlas 和 clip 等 CPU 密集 Worker 的全局并发上限，默认 `1`。Atlas 首帧页面可提前返回，但后台 PNG 编码完成前仍持有该名额，避免与其他重载 Worker 叠加。
-
+# GiftStage
+
+统一的 Web 礼物播放框架，支持：
+
+- `SVGA`
+- `VAP / VAPX`
+- 透明视频 `AlphaVideo`
+- 静态图片 `Image`
+
+底层支持：
+
+- `WebGPU`
+- `WebGL2`
+- `WebGL1` 兼容兜底
+
+适用场景：
+
+- 直播间礼物
+- 大批同屏动画
+- 需要统一接入 `SVGA / VAP / 透明视频 / 图片` 的业务场景
+
+## npm 包信息
+
+- 包名：`@taole/giftstage`
+- npm：`npm i @taole/giftstage`
+- ESM 导入：
+
+```ts
+import { GiftStage } from '@taole/giftstage';
+```
+
+- CommonJS 导入：
+
+```js
+const { GiftStage } = require('@taole/giftstage');
+```
+
+## 特性
+
+- 统一 API：`addGift()` 即可播放四类礼物
+- `SVGA` 支持 Worker 解析、atlas 缓存、slot 替换
+- `VAP / AlphaVideo` 支持实验性的 `WebCodecs` 和稳定的 `HTMLVideoElement` 双路径
+- 同源视频播放实例、纹理、资源复用
+- 内存 LRU 缓存，默认 `128MB`
+- `IndexedDB` 磁盘 LRU 缓存，默认 `2048MB`
+- `x / y` 支持百分比定位
+- `width / height` 支持按礼物原始尺寸自动补全
+- 四类礼物共用位移、缩放、透明度、旋转、层级和销毁生命周期
+
+## 安装
+
+```bash
+npm install
+```
+
+安装发布包：
+
+```bash
+npm i @taole/giftstage
+```
+
+## 开发
+
+```bash
+npm run dev
+```
+
+## 构建
+
+```bash
+npm run build
+```
+
+Demo 构建：
+
+```bash
+npm run build:demo
+```
+
+## 性能基线
+
+```bash
+# 在当前机器记录 WebGL2 / WebGPU 基线
+npm run perf:record
+
+# 与同浏览器主版本、硬件并发数、DPR 和视口的基线比较
+npm run test:perf
+```
+
+基线覆盖冷/热启动、100 个静态图片、SVGA Direct 的 1/2/10/50 个同资源实例、
+复杂 Clip/Shape Hybrid 的 Auto/CPU 对照、20 个共享 VAP 和 20 个共享 AlphaVideo。
+除首帧、P50/P95/P99、长任务、堆变化、draw/Stencil 外，还记录 SVGA CPU Sprite
+展开数、GPU 帧表上传、每帧动态上传字节、路径晋升与回退。可用
+`npm run test:perf -- --project=chromium-webgl2 --scenarios=<逗号分隔场景>` 做聚焦复测。
+基线保存在 `tests/performance/baselines/`；Windows 会自动探测系统 Chrome，也可通过
+`PLAYWRIGHT_CHROME_EXECUTABLE_PATH` 指定浏览器。
+
+## 快速开始
+
+```ts
+import { GiftStage } from '@taole/giftstage';
+
+const container = document.getElementById('app')!;
+
+const stage = new GiftStage({
+  container,
+  preferWebGPU: true,
+});
+
+await stage.ready;
+
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: 100,
+  y: 100,
+  loop: 0,
+});
+```
+
+## 插件运行时（0.2）
+
+聊天室只需要维护一个全屏 `GiftStage`。业务编排包通过 `stage.mount(plugin)` 接入，插件创建的礼物、轨道和粒子都归属于独立 `PlaybackScope`；销毁插件或作用域不会调用 `removeAll()`，也不会影响舞台上的其他礼物。
+
+```ts
+import createMultiGiftPlugin from '@taole/giftstage-plugin-multi-gift';
+
+const mounted = await stage.mount(createMultiGiftPlugin({ playConfig }));
+await mounted.api.preload();
+const playback = await mounted.api.play({ target: null });
+
+playback.pause();
+playback.resume();
+playback.seek(1200);
+await playback.completion;
+
+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 轨道媒体范围和粒子能力。
+
+## 核心 API
+
+### `new GiftStage(options)`
+
+创建礼物舞台。
+
+常用配置：
+
+- `container: HTMLElement`
+  挂载容器。
+
+- `resolution?: number`
+  指定 canvas backing store 分辨率倍率。默认跟随 `devicePixelRatio`。
+
+- `antialias?: boolean`
+  是否开启抗锯齿，WebGL 和 WebGPU 均默认开启；WebGPU 使用 4× MSAA。大量透明视频同时播放时可显式设为 `false`。
+
+- `preferWebGPU?: boolean`
+  是否优先使用 `WebGPU`。
+
+- `forceWebGL1?: boolean`
+  强制走 `WebGL1`，用于兼容性验证。
+
+- `preferWebCodecs?: boolean`
+  实验性特性。默认关闭；显式传 `true` 时才会尝试用 `WebCodecs` 播放 `VAP / AlphaVideo`。
+
+- `shareIdenticalVideoPlayback?: boolean`
+  是否复用近同时起播的同源视频播放实例。默认开启。
+
+- `sharedVideoPlaybackWindowMs?: number`
+  同源视频共享播放窗口，默认 `100ms`。
+
+- `webCodecsVideoAtlas?: { width: number; height: number }`
+  实验性 `WebCodecs` 视频共享 atlas 配置。
+
+- `webCodecsDecodeInWorker?: boolean`
+  实验性 `WebCodecs` 选项，控制是否在 Worker 中执行解码。
+
+- `webCodecsMaxDecodedFrames?: number`
+  实验性 `WebCodecs` 选项，控制保留的最大解码帧数。
+
+- `webCodecsDecodeAheadFrames?: number`
+  实验性 `WebCodecs` 选项，控制前向解码帧数。
+
+- `svgaParseInWorker?: boolean`
+  是否在 Worker 中解析 SVGA。
+
+- `maxConcurrentParse?: number`
+  资源下载 / 解析 / 图像解码的并发数。
+  不传时自动跟随 `navigator.hardwareConcurrency`。
+
+- `svgaAtlasFrameBudgetMs?: number`
+  SVGA atlas 在主线程组合或逐页上传时的单帧时间片上限，默认 `12ms`。
+  实际时间片会按当前刷新周期的一半动态调整，避免高刷新率设备上的加载任务挤占渲染帧。
+
+- `svgaLoadFrameBudgetMs?: number`
+  SVGA 主线程加载任务的共享时间片上限，默认 `12ms`。图片 fallback、atlas、clip、音频、slot 纹理和二进制缓存共用同一帧预算。
+
+- `svgaWorkerFrameBudgetMs?: number`
+  SVGA Worker 连续执行 JS 循环的时间片上限，默认 `4ms`，范围 `1-8ms`。单次 WASM protobuf 调用和单次原生 API 调用仍不可抢占。
+
+- `svgaWorkerTaskConcurrency?: number`
+  parser、图片解码、atlas 和 clip 等 CPU 密集 Worker 的全局并发上限，默认 `1`。Atlas 首帧页面可提前返回，但后台 PNG 编码完成前仍持有该名额，避免与其他重载 Worker 叠加。
+
 - `svgaWorkerImageDecodeConcurrency?: number`
   图片解码 Worker 内 `createImageBitmap` 并发上限，默认 `2`。运行时可按批次耗时收缩并发，负载恢复后回升，但不会超过该上限。
 
-- `svgaParseProfile?: boolean`
-  是否输出 `[GiftStage:SVGA:Profile]` 结构化解析日志，默认 `false`。日志包含 `DecompressionStream` 格式尝试、输入/输出 chunk、解压耗时以及 protobuf/payload 构建耗时；WASM payload 路径还会拆分 `prostDecodeMs`、`metadataAndImagesMs`、`frameTableMs`、`finalizeMs` 和 WASM 边界复制耗时。缓存命中不输出。
-
-SVGA 礼物在加载阶段被 `destroy()` / `removeGift()` 时，会取消排队任务并终止正在执行的 parser、图片解码、atlas 或 clip Worker。相同 URL 的共享加载按消费者计数，单个礼物取消不会中断其他仍在等待的礼物。
-
+- `svgaFrameEvaluation?: 'auto' | 'cpu'`
+  SVGA 帧动画求值策略，默认 `auto`。`auto` 按后端能力、表大小和资源计划选择 `gpu-direct`、`gpu-hybrid` 或 `cpu-reference`；`cpu` 强制使用 CPU reference。普通单礼物和同资源多实例都经过同一策略。
+
+- `svgaGpuFrameTableBudgetBytes?: number`
+  所有活动 SVGA GPU 帧表、静态 Sprite metadata 和 Hybrid Command Table 共享的全局预算，默认 `32 MiB`。预算不足时仅当前资源回退到 `cpu-reference`，不会影响已存在的其他礼物。
+
+- `svgaParseProfile?: boolean`
+  是否输出 `[GiftStage:SVGA:Profile]` 结构化解析日志，默认 `false`。日志包含 `DecompressionStream` 格式尝试、输入/输出 chunk、解压耗时以及 protobuf/payload 构建耗时；WASM payload 路径还会拆分 `prostDecodeMs`、`metadataAndImagesMs`、`frameTableMs`、`finalizeMs` 和 WASM 边界复制耗时。缓存命中不输出。
+
+SVGA 礼物在加载阶段被 `destroy()` / `removeGift()` 时，会取消排队任务并终止正在执行的 parser、图片解码、atlas 或 clip Worker。相同 URL 的共享加载按消费者计数，单个礼物取消不会中断其他仍在等待的礼物。
+
 - `onError?: (error: Error) => void`
   统一错误回调。
 
-### `await stage.ready`
-
-等待底层后端和运行环境初始化完成。建议在第一次 `addGift()` 前等待。
+- `onSVGARenderPathChange?: (info) => void`
+  当 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 上传；回调异常会被隔离，不能中断渲染降级事务。
+
+### `await stage.ready`
+
+等待底层后端和运行环境初始化完成。建议在第一次 `addGift()` 前等待。
+
 ### `stage.addGift(options)`
-
-插入一个礼物，返回：
-
-```ts
+
+插入一个礼物，返回：
+
+```ts
 Promise<GiftHandle>;
 ```
 
-### `GiftHandle` API
-
-`addGift()` 返回的句柄可用于控制单个礼物：
+### `stage.getDiagnostics()`
 
-- `gift.id`
-- `gift.type`
-- `gift.pause()`
-- `gift.resume()`
-  - 暂停期间礼物播放时钟、图片 `duration` 和后置动画都会冻结
+返回当前 Stage 生命周期内的累计运行诊断快照，包括 frame abort/replay/retry、FastPath fallback、native submitted/rejected draw、WebGPU uncaptured error、backend loss、observer error 以及最后一个结构化事件。该快照不会被性能测试采样窗口重置，返回对象可安全交给业务遥测系统；GiftStage 自身不上传数据。
+
+### `GiftHandle` API
+
+`addGift()` 返回的句柄可用于控制单个礼物：
+
+- `gift.id`
+- `gift.type`
+- `gift.pause()`
+- `gift.resume()`
+  - 暂停期间礼物播放时钟、图片 `duration` 和后置动画都会冻结
 - `gift.destroy()`
   - 立即移除当前礼物
+- `gift.getRenderInfo()`
+  - 返回 SVGA 的实时路径诊断；非 SVGA 或尚未形成资源计划时返回 `null`。`pathState` 为 `preparing | settled | fallback`，`drawBatchMode` 为 `multi-slot | per-slot | hybrid-scheduled`，可直接区分资源共享与实际 Draw 合批状态。
 - `gift.animate(stepOrSteps?)`
-  - 创建链式动画并返回 `GiftAnimationChain`
-
-`GiftAnimationChain` 支持：
-
-- `.to(step)` / `.then(step)`
-  - 追加动画步骤（两者等价）
-- `.delay(milliseconds)`
-  - 在链中插入等待，不改变位置、缩放和透明度
-- `.onComplete((gift) => void)`
-  - 整条链执行完成后的回调
-- `.start(mode?)`
-  - `mode: 'immediate' | 'afterGiftComplete'`
-  - `immediate`：立即开始（默认）
-  - `afterGiftComplete`：等待礼物主播放结束后再执行链
-- `.cancel()`
-  - 取消当前礼物正在执行的链式动画
-
-### `stage.removeGift(id)`
-
-按 ID 移除礼物。
-
-### `stage.removeAll()`
-
-移除全部礼物。
-
-### `stage.pause()`
-
-暂停舞台。
-
-### `stage.resume()`
-
-恢复舞台。
-
+  - 创建链式动画并返回 `GiftAnimationChain`
+
+`GiftAnimationChain` 支持：
+
+- `.to(step)` / `.then(step)`
+  - 追加动画步骤（两者等价）
+- `.delay(milliseconds)`
+  - 在链中插入等待，不改变位置、缩放和透明度
+- `.onComplete((gift) => void)`
+  - 整条链执行完成后的回调
+- `.start(mode?)`
+  - `mode: 'immediate' | 'afterGiftComplete'`
+  - `immediate`：立即开始（默认）
+  - `afterGiftComplete`：等待礼物主播放结束后再执行链
+- `.cancel()`
+  - 取消当前礼物正在执行的链式动画
+
+### `stage.removeGift(id)`
+
+按 ID 移除礼物。
+
+### `stage.removeAll()`
+
+移除全部礼物。
+
+### `stage.pause()`
+
+暂停舞台。
+
+### `stage.resume()`
+
+恢复舞台。
+
 ### `stage.destroy()`
 
 销毁舞台并释放资源。
 
-## `addGift()` 参数
-
-### 通用参数
-
-- `type: 'svga' | 'vap' | 'alphaVideo' | 'image'`
-- `source: string | ArrayBuffer`
-- `x: number | \`${number}%\``
-- `y: number | \`${number}%\``
-- `zIndex?: number`
-- `width?: number`
-- `height?: number`
-- `useOriginalSize?: boolean`
-- `objectFit?: 'contain' | 'cover'`
-- `loop?: number`
-  - `0` 表示无限循环
-  - VAP / AlphaVideo 的 HTMLVideo 回退路径会为有限循环设置“媒体总时长 + 容错窗口”的超时保护；即使浏览器未触发 `ended`，也会进入正常完成和清理流程
-- `opacity?: number`
-  - 全局透明度，范围 `0 ~ 1`，默认 `1`
-- `rotation?: number`
-  - 初始旋转弧度；屏幕坐标中正值为顺时针
-- `transformOrigin?: { x: number | \`${number}%\`; y: number | \`${number}%\` }`
-  - 相对未缩放礼物框左上角，默认 `50% / 50%`
-  - 数值使用 CSS 像素；允许负值或超过礼物宽高，用于绕框外点公转
-- `videoRGBAlphaMode?: 'straight' | 'premultiplied'`
-  - 仅用于 `vap` / `alphaVideo` 分离 Alpha 视频源，默认 `premultiplied`
-  - `straight`：RGB 区域尚未乘独立 Alpha，播放器负责预乘
-  - `premultiplied`：RGB 区域在制作阶段已经乘过独立 Alpha，播放器不会再次相乘
-  - 该参数只描述输入视频；最终画布仍统一输出预乘 Alpha
-- `clearsAfterStop?: boolean`
-  - 播放结束后，是否自动移除礼物
-  - 默认 `true`，传 `false` 时会停留最后一帧，方便后续继续调用 `gift.animate(...).start()`
-- `mute?: boolean`
-  - `VAP / AlphaVideo` 传 `false` 时使用 `HTMLVideoElement` 播放声音；该礼物不会进入仅解码视频帧的 WebCodecs 路径
-  - 如果浏览器阻止有声自动播放，会自动回退静音播放，保证画面正常完成
-- `onFrame?: (frame, gift) => void`
-  - 仅用于 SVGA；画面帧推进时触发
-  - 性能不足时可能跨帧，业务应使用 `frame >= target` 的阈值判断
-- `onComplete?: (gift) => void`
-
-图片专用参数：
-
-- `duration?: number`
-  - 单位毫秒；正数到期后触发 `onComplete`，并遵循 `clearsAfterStop`
-  - 不传或传非正数时持续显示到 `destroy()`；加载完成后 `afterGiftComplete` 可立即继续，但不会自动触发 `onComplete`
-  - `image` 忽略 `loop` 和 `mute`
-
-层级规则：
-
-- `zIndex` 在 `SVGA / VAP / AlphaVideo / Image` 四种礼物间通用
-- 数值越大，渲染越靠上
-- 同层级下，后 `addGift()` 的礼物会覆盖先添加的礼物
-
-### 宽高默认行为
-
-`width / height` 现在是可选参数，规则如下：
-
-- 两个都传：按传入值显示
-- 只传 `width`：`height` 按礼物原始宽高比自动补全
-- 只传 `height`：`width` 按礼物原始宽高比自动补全
-- 两个都不传：默认按当前画布尺寸做等比 `contain`
-- 如果 `objectFit: 'cover'` 且两个都不传：按整个画布作为显示区域做等比 `cover`
-- 也就是会在画布内尽可能放大或缩小，并保持礼物原始宽高比
-- 如果 `useOriginalSize: true`，且礼物原始尺寸本身小于画布，则优先使用礼物原始尺寸
-- 如果 `useOriginalSize: true`，但礼物原始尺寸超出画布，则仍会按画布尺寸等比缩小
-
-例如：
-
-```ts
-await stage.addGift({
-  type: 'svga',
-  source: 'https://example.com/demo.svga',
-  x: '50%',
-  y: '50%',
-  loop: 0,
-});
-```
-
-这时会按舞台尺寸做等比适配，并保持礼物原始宽高比。
-
-如果希望礼物铺满整个画布，并按中心裁剪超出的部分，可以使用 `cover`：
-
-```ts
-await stage.addGift({
-  type: 'svga',
-  source: 'https://example.com/demo.svga',
-  x: '50%',
-  y: '50%',
-  objectFit: 'cover',
-  loop: 0,
-});
-```
-
-当 `x: '50%'`、`y: '50%'` 且未传 `width / height` 时，显示区域会居中放在整个画布上；`cover` 会保持礼物原始宽高比铺满该区域，并从中心裁剪溢出的部分。
-
-如果你希望“小礼物保持原始尺寸，大礼物再缩小”，可以这样：
-
-```ts
-await stage.addGift({
-  type: 'svga',
-  source: 'https://example.com/demo.svga',
-  x: '50%',
-  y: '50%',
-  useOriginalSize: true,
-  loop: 0,
-});
-```
-
-### 百分比坐标
-
-`x / y` 支持百分比，例如：
-
-```ts
-await stage.addGift({
-  type: 'svga',
-  source: 'https://example.com/demo.svga',
-  x: '50%',
-  y: '50%',
-  width: 300,
-  height: 300,
-  loop: 0,
-});
-```
-
-语义是：
-
-- `x: '50%'` 按容器宽度的 `50%` 定位，并减去自身一半宽度
-- `y: '50%'` 按容器高度的 `50%` 定位，并减去自身一半高度
-
-也就是接近：
-
-```css
-left: 50%;
-top: 50%;
-transform: translate(-50%, -50%);
-```
-
-如果是数值，则继续按原来的像素坐标语义处理。
-
-## 四类礼物示例
-
-### 播放 SVGA
-
-```ts
-await stage.addGift({
-  type: 'svga',
-  source: 'https://example.com/demo.svga',
-  x: 20,
-  y: 20,
-  width: 300,
-  height: 300,
-  loop: 1,
-});
-```
-
-### 播放 VAP
-
-```ts
-await stage.addGift({
-  type: 'vap',
-  source: 'https://example.com/demo.mp4',
-  config: 'https://example.com/demo.json',
-  x: 20,
-  y: 20,
-  width: 400,
-  height: 220,
-  // 默认 premultiplied；RGB 尚未乘独立 Alpha 的视频源需显式传 straight
-  videoRGBAlphaMode: 'premultiplied',
-  loop: 0,
-});
-```
-
-### 播放透明视频
-
-```ts
-await stage.addGift({
-  type: 'alphaVideo',
-  source: 'https://example.com/demo.mp4',
-  x: 20,
-  y: 20,
-  width: 400,
-  height: 220,
-  // 默认 premultiplied；未预乘的视频源改为 straight
-  videoRGBAlphaMode: 'premultiplied',
-  loop: 0,
-});
-```
-
-### 播放图片
-
-`source` 首版支持 URL 和 `ArrayBuffer`。URL 图片会按地址共享 GPU 纹理并引用计数；图片按静态帧处理，不保证 GIF / WebP 动画播放。跨域 URL 必须允许匿名 CORS 读取。
-
-```ts
-const avatar = await stage.addGift({
-  type: 'image',
-  source: 'https://example.com/avatar.png',
-  x: '50%',
-  y: '50%',
-  width: 100,
-  height: 100,
-  objectFit: 'cover',
-  duration: 5000,
-});
-```
-
-## 动画控制
-
-### 链式动画
-
-`addGift()` 返回的 `GiftHandle` 支持 `animate()`。一次 `to()` 是组合动画，同一步里可以同时移动、缩放、改变透明度和旋转；多个 `to()` / `then()` 会按顺序播放。`rotationTo` 直接按数值线性插值，不做最短角度归一化，因此可以明确表达多圈旋转：
-
-```ts
-const gift = await stage.addGift({
-  type: 'svga',
-  source: 'https://example.com/demo.svga',
-  x: '50%',
-  y: '50%',
-  width: 300,
-  height: 300,
-  loop: 0,
-});
-
-await gift
-  .animate()
-  .to({
-    flyTo: { x: 200, y: 240 },
-    scaleTo: 0.8,
-    opacity: 0.6,
-    rotationTo: Math.PI * 4,
-    duration: 500,
-  })
-  .then({
-    flyTo: { x: 600, y: 320 },
-    scaleTo: 1.1,
-    opacity: 1,
-    duration: 700,
-  })
-  .delay(300)
-  .then({
-    opacity: 0,
-    duration: 400,
-  })
-  .onComplete((g) => {
-    console.log('chain complete', g.id);
-  })
-  .start();
-```
-
-### 绕外部中心旋转
-
-下面的礼物初始位于舞台中心右侧 200px，旋转中心通过框外坐标指回舞台中心：
-
-```ts
-const orbitGift = await stage.addGift({
-  type: 'image',
-  source: 'https://example.com/gift.png',
-  x: container.clientWidth / 2 + 150,
-  y: '50%',
-  width: 100,
-  height: 100,
-  transformOrigin: { x: -150, y: '50%' },
-});
-
-await orbitGift
-  .animate({ rotationTo: Math.PI * 2, duration: 1200 })
-  .start();
-```
-
-也可以传入单步或数组：
-
-```ts
-gift.animate({ flyTo: { x: 300, y: 300 }, scaleTo: 0.5, opacity: 0.3 }).start();
-
-gift
-  .animate([
-    { flyTo: { x: 300, y: 300 }, duration: 400 },
-    { scaleTo: 1, opacity: 1, duration: 300 },
-  ])
-  .start();
-```
-
-## Slot 替换
-
-### SVGA
-
-使用 `svgaSlots`：
-
-```ts
-await stage.addGift({
-  type: 'svga',
-  source: 'https://example.com/demo.svga',
-  x: 0,
-  y: 0,
-  width: 400,
-  height: 400,
-  svgaSlots: {
-    avatar: { image: avatarImage },
-    title: {
-      text: 'Hello',
-      color: '#ff0000',
-      fontSize: 28,
-      mode: 'dynamic',
-    },
-  },
-});
-```
-
-支持：
-
-- `TexImageSource`
-- 文本配置
-- 图片配置
-
-SVGA 文本配置会按目标 frame 自动适配字号，避免文字超出槽位：
-
-- `mode: 'dynamic'`：默认行为。生成文字自身尺寸的纹理，渲染时按自身逻辑尺寸居中到 frame 内，不会被拉伸。
-- `mode: 'replace'`：生成和 frame 一样大的纹理，按替换图逻辑铺满 frame。
-- `fontSize?: number`：期望字号；如果文字放不下，会自动缩小。
-- `minFontSize?: number` / `maxFontSize?: number`：限制自适应字号范围。
-- `padding?: number`：文字纹理内边距，默认 `2`。
-- `scale?: number`：文字纹理栅格倍率，SVGA 默认 `3`，用于保持清晰度。
-- `fontStyle?: string | { font?: string; color?: string }`：字体样式，SVGA / VAP 都支持。
-
-`fontStyle` 可以直接传 canvas font 字符串：
-
-```ts
-svgaSlots: {
-  title: {
-    text: 'Hello',
-    fontStyle: 'bold 40px Arial',
-  },
-}
-```
-
-也可以传对象：
-
-```ts
-vapSlots: {
-  welcome01: {
-    text: '欢迎进入房间',
-    fontStyle: {
-      font: 'bold 40px Arial',
-      color: '#ffffff',
-    },
-  },
-}
-```
-
-对象形式目前生效字段是 `font` 和 `color`。如果同时传了外层 `color` 和 `fontStyle.color`，以 `fontStyle.color` 为准。VAP 文本如果没有传 `fontStyle`，会回退使用 VAP 配置里的 `src.fontStyle`。
-
-### VAP / VAPX
-
-使用 `vapSlots`：
-
-```ts
-await stage.addGift({
-  type: 'vap',
-  source: 'https://example.com/demo.mp4',
-  config: 'https://example.com/demo.json',
-  x: 0,
-  y: 0,
-  width: 400,
-  height: 400,
-  vapSlots: {
-    welcome01: '欢迎进入房间',
-    avatar_left: 'https://example.com/avatar.png',
-  },
-});
-```
-
-支持：
-
-- 文本字符串
-- 图片 URL
-- `TexImageSource`
-- 结构化文本 / 图片对象
-
-## 后端策略
-
-默认回退顺序：
-
-1. `WebGPU`
-2. `WebGL2`
-3. `WebGL1`
-
-说明：
-
-- `WebGPU` 仅在浏览器支持相关必要能力时启用
-- `WebGL1` 主要用于兼容兜底，不以性能最优为目标
-- demo 中可手动强制切换到 `WebGL1`
-
-## 缓存策略
-
-### 内存缓存
-
-- 默认 `128MB`
-- LRU 淘汰
-
-缓存内容包括：
-
-- 原始资源字节
-- 文本 / JSON
-- `SVGA` worker payload
-- `SVGA` atlas 资产
-
-### `IndexedDB` 磁盘缓存
-
-- 默认 `2048MB`
-- LRU 淘汰
-- 读取命中会刷新最近访问时间
-- 超出预算时按最久未使用记录淘汰
-
-异常情况处理：
-
-- `IndexedDB` 不可用、事务失败、写入失败、容量不足时，会自动降级
-- 损坏的 `SVGA` 磁盘缓存会自动删除并重新生成
-
-## 项目结构
-
-主要目录：
-
-- `src/`
-  核心源码
-- `docs/`
-  设计与汇总文档
-- `publish/`
-  发布脚本
-- `static/`
-  demo 依赖资源
-- `tests/`
-  测试
-
-## 对外导出
-
-入口文件：
-
-- [src/index.ts](/D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/src/index.ts)
-
+### SVGA 帧动画路径
+
+SVGA 资源的 9-float 帧行会在准备阶段打包为 3 个 `vec4`。WebGPU 使用持久 storage buffer，WebGL2 使用 `RGBA32F + NEAREST + texelFetch` 数据纹理。CPU 始终权威维护帧号、循环、暂停、Seek、音频与回调；GPU 根据该帧号读取子 Sprite 矩阵、透明度和可见性。
+
+Direct 对连续且兼容的同资源 slot 使用 4 个 `vec4`/slot 的父级状态并进行 slot-major 实例化合批；多 Atlas、不同 MotionTrack binding 或无法证明重排安全的区间继续使用 per-slot Direct，不回退 CPU。Hybrid 在资源准备期生成 `frameOffsets + operations + spriteIndices + meshReferences` 不可变命令表，并把连续同 Atlas 的纹理操作进一步预编译为 execution run；运行时只读取当前帧 run slice。Texture、Shape 和 Clip Mask Shader 读取同一核心帧表，每帧动态上传仍只有 slot 父级状态。结构相同的不同权威帧可通过 `frameScheduleIds` 共用一次合批；矩形纹理 Clip 使用静态本地裁剪 metadata，不增加 Stencil pass。MoveTo-only、线段、重复点或零面积 Clip 按 SVG/Canvas 的空裁剪语义直接隐藏对应 Sprite，不创建 Mesh/Stencil，也不会触发资源回退。
+
+- `gpu-direct`：普通 atlas sprite 的帧变换、透明度和布局由 GPU 求值。
+- `gpu-hybrid`：Shape/Clip 的精确 paint order 与 Draw/Stencil 提交由 CPU 按不可变命令表调度，Texture、Shape、Clip Mask 的动画属性都由 GPU 帧表求值。
+- `cpu-reference`：WebGL1、动态 `svgaSlots`、表校验/上传失败、预算不足或策略为 `cpu` 时使用确定性的 CPU 路径。
+
+插件可通过 `stage.capabilities.svgaFrameTimeline` 判断 `transport`（`storage-buffer`、`float-texture` 或 `unavailable`）、正式 `direct`/`hybrid` 能力、`supportedPaths` 和 `maxTableBytes`，不需要启用 experimental policy。同一解析资源的多个实例共享帧表、静态 metadata 和 Hybrid Command Table；`compatibleInstanceCount` 表示资源共享数，实际本帧合批数量由 `drawCompatibleInstanceCount` 报告。
+
+`addGift()` 不等待 GPU 帧表：非预加载礼物先显示 CPU reference 首帧，再在完整帧边界原子晋升。`preload('svga')` 会等待同一资源级帧表与调度准备完成。FastPath 提交若被后端拒绝，会丢弃未提交帧、同步降级该资源，并在同一 RAF 以原顺序完整重放一次；重放再次失败时 WebGL2 会清成透明帧，并在下一 RAF 不推进 CPU 权威时间轴地重试。不支持该帧事务的自定义 Backend 会直接使用 CPU Reference。WebGL1、动态 `svgaSlots`、能力/尺寸/预算校验失败和上传失败均按资源缓存回退，不逐帧重试；Stage 与单礼物都可用 `svgaFrameEvaluation: 'cpu'` 强制关闭。
+
+性能诊断中的 `submittedDrawCalls` 仅表示命令已经到达 WebGL `drawElements*` 或 WebGPU `drawIndexed` 调用/编码；它不表示 GPU 已经执行完成。`rejectedDrawCalls` 表示在原生提交前被后端校验或容量检查拒绝。GPU error scope、pipeline validation 与 framebuffer 像素门禁用于补充验证执行结果。
+
+## `addGift()` 参数
+
+### 通用参数
+
+- `type: 'svga' | 'vap' | 'alphaVideo' | 'image'`
+- `source: string | ArrayBuffer`
+- `x: number | \`${number}%\``
+- `y: number | \`${number}%\``
+- `zIndex?: number`
+- `width?: number`
+- `height?: number`
+- `useOriginalSize?: boolean`
+- `objectFit?: 'contain' | 'cover'`
+- `loop?: number`
+  - `0` 表示无限循环
+  - VAP / AlphaVideo 的 HTMLVideo 回退路径会为有限循环设置“媒体总时长 + 容错窗口”的超时保护；即使浏览器未触发 `ended`，也会进入正常完成和清理流程
+- `opacity?: number`
+  - 全局透明度，范围 `0 ~ 1`，默认 `1`
+- `rotation?: number`
+  - 初始旋转弧度；屏幕坐标中正值为顺时针
+- `transformOrigin?: { x: number | \`${number}%\`; y: number | \`${number}%\` }`
+  - 相对未缩放礼物框左上角，默认 `50% / 50%`
+  - 数值使用 CSS 像素；允许负值或超过礼物宽高，用于绕框外点公转
+- `videoRGBAlphaMode?: 'straight' | 'premultiplied'`
+  - 仅用于 `vap` / `alphaVideo` 分离 Alpha 视频源，默认 `premultiplied`
+  - `straight`：RGB 区域尚未乘独立 Alpha，播放器负责预乘
+  - `premultiplied`：RGB 区域在制作阶段已经乘过独立 Alpha，播放器不会再次相乘
+  - 该参数只描述输入视频；最终画布仍统一输出预乘 Alpha
+- `clearsAfterStop?: boolean`
+  - 播放结束后，是否自动移除礼物
+  - 默认 `true`，传 `false` 时会停留最后一帧，方便后续继续调用 `gift.animate(...).start()`
+- `mute?: boolean`
+  - `VAP / AlphaVideo` 传 `false` 时使用 `HTMLVideoElement` 播放声音；该礼物不会进入仅解码视频帧的 WebCodecs 路径
+  - 如果浏览器阻止有声自动播放，会自动回退静音播放，保证画面正常完成
+- `onFrame?: (frame, gift) => void`
+  - 仅用于 SVGA；画面帧推进时触发
+  - 性能不足时可能跨帧，业务应使用 `frame >= target` 的阈值判断
+- `onComplete?: (gift) => void`
+
+图片专用参数：
+
+- `duration?: number`
+  - 单位毫秒；正数到期后触发 `onComplete`，并遵循 `clearsAfterStop`
+  - 不传或传非正数时持续显示到 `destroy()`；加载完成后 `afterGiftComplete` 可立即继续，但不会自动触发 `onComplete`
+  - `image` 忽略 `loop` 和 `mute`
+
+层级规则：
+
+- `zIndex` 在 `SVGA / VAP / AlphaVideo / Image` 四种礼物间通用
+- 数值越大，渲染越靠上
+- 同层级下，后 `addGift()` 的礼物会覆盖先添加的礼物
+
+### 宽高默认行为
+
+`width / height` 现在是可选参数，规则如下：
+
+- 两个都传：按传入值显示
+- 只传 `width`：`height` 按礼物原始宽高比自动补全
+- 只传 `height`：`width` 按礼物原始宽高比自动补全
+- 两个都不传：默认按当前画布尺寸做等比 `contain`
+- 如果 `objectFit: 'cover'` 且两个都不传：按整个画布作为显示区域做等比 `cover`
+- 也就是会在画布内尽可能放大或缩小，并保持礼物原始宽高比
+- 如果 `useOriginalSize: true`，且礼物原始尺寸本身小于画布，则优先使用礼物原始尺寸
+- 如果 `useOriginalSize: true`，但礼物原始尺寸超出画布，则仍会按画布尺寸等比缩小
+
+例如：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  loop: 0,
+});
+```
+
+这时会按舞台尺寸做等比适配，并保持礼物原始宽高比。
+
+如果希望礼物铺满整个画布，并按中心裁剪超出的部分，可以使用 `cover`：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  objectFit: 'cover',
+  loop: 0,
+});
+```
+
+当 `x: '50%'`、`y: '50%'` 且未传 `width / height` 时，显示区域会居中放在整个画布上；`cover` 会保持礼物原始宽高比铺满该区域，并从中心裁剪溢出的部分。
+
+如果你希望“小礼物保持原始尺寸，大礼物再缩小”，可以这样：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  useOriginalSize: true,
+  loop: 0,
+});
+```
+
+### 百分比坐标
+
+`x / y` 支持百分比，例如：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  width: 300,
+  height: 300,
+  loop: 0,
+});
+```
+
+语义是：
+
+- `x: '50%'` 按容器宽度的 `50%` 定位，并减去自身一半宽度
+- `y: '50%'` 按容器高度的 `50%` 定位，并减去自身一半高度
+
+也就是接近：
+
+```css
+left: 50%;
+top: 50%;
+transform: translate(-50%, -50%);
+```
+
+如果是数值，则继续按原来的像素坐标语义处理。
+
+## 四类礼物示例
+
+### 播放 SVGA
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: 20,
+  y: 20,
+  width: 300,
+  height: 300,
+  loop: 1,
+});
+```
+
+### 播放 VAP
+
+```ts
+await stage.addGift({
+  type: 'vap',
+  source: 'https://example.com/demo.mp4',
+  config: 'https://example.com/demo.json',
+  x: 20,
+  y: 20,
+  width: 400,
+  height: 220,
+  // 默认 premultiplied；RGB 尚未乘独立 Alpha 的视频源需显式传 straight
+  videoRGBAlphaMode: 'premultiplied',
+  loop: 0,
+});
+```
+
+### 播放透明视频
+
+```ts
+await stage.addGift({
+  type: 'alphaVideo',
+  source: 'https://example.com/demo.mp4',
+  x: 20,
+  y: 20,
+  width: 400,
+  height: 220,
+  // 默认 premultiplied；未预乘的视频源改为 straight
+  videoRGBAlphaMode: 'premultiplied',
+  loop: 0,
+});
+```
+
+### 播放图片
+
+`source` 首版支持 URL 和 `ArrayBuffer`。URL 图片会按地址共享 GPU 纹理并引用计数；图片按静态帧处理，不保证 GIF / WebP 动画播放。跨域 URL 必须允许匿名 CORS 读取。
+
+```ts
+const avatar = await stage.addGift({
+  type: 'image',
+  source: 'https://example.com/avatar.png',
+  x: '50%',
+  y: '50%',
+  width: 100,
+  height: 100,
+  objectFit: 'cover',
+  duration: 5000,
+});
+```
+
+## 动画控制
+
+### 链式动画
+
+`addGift()` 返回的 `GiftHandle` 支持 `animate()`。一次 `to()` 是组合动画，同一步里可以同时移动、缩放、改变透明度和旋转；多个 `to()` / `then()` 会按顺序播放。`rotationTo` 直接按数值线性插值，不做最短角度归一化，因此可以明确表达多圈旋转：
+
+```ts
+const gift = await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  width: 300,
+  height: 300,
+  loop: 0,
+});
+
+await gift
+  .animate()
+  .to({
+    flyTo: { x: 200, y: 240 },
+    scaleTo: 0.8,
+    opacity: 0.6,
+    rotationTo: Math.PI * 4,
+    duration: 500,
+  })
+  .then({
+    flyTo: { x: 600, y: 320 },
+    scaleTo: 1.1,
+    opacity: 1,
+    duration: 700,
+  })
+  .delay(300)
+  .then({
+    opacity: 0,
+    duration: 400,
+  })
+  .onComplete((g) => {
+    console.log('chain complete', g.id);
+  })
+  .start();
+```
+
+### 绕外部中心旋转
+
+下面的礼物初始位于舞台中心右侧 200px，旋转中心通过框外坐标指回舞台中心：
+
+```ts
+const orbitGift = await stage.addGift({
+  type: 'image',
+  source: 'https://example.com/gift.png',
+  x: container.clientWidth / 2 + 150,
+  y: '50%',
+  width: 100,
+  height: 100,
+  transformOrigin: { x: -150, y: '50%' },
+});
+
+await orbitGift
+  .animate({ rotationTo: Math.PI * 2, duration: 1200 })
+  .start();
+```
+
+也可以传入单步或数组：
+
+```ts
+gift.animate({ flyTo: { x: 300, y: 300 }, scaleTo: 0.5, opacity: 0.3 }).start();
+
+gift
+  .animate([
+    { flyTo: { x: 300, y: 300 }, duration: 400 },
+    { scaleTo: 1, opacity: 1, duration: 300 },
+  ])
+  .start();
+```
+
+## Slot 替换
+
+### SVGA
+
+使用 `svgaSlots`：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: 0,
+  y: 0,
+  width: 400,
+  height: 400,
+  svgaSlots: {
+    avatar: { image: avatarImage },
+    title: {
+      text: 'Hello',
+      color: '#ff0000',
+      fontSize: 28,
+      mode: 'dynamic',
+    },
+  },
+});
+```
+
+支持：
+
+- `TexImageSource`
+- 文本配置
+- 图片配置
+
+SVGA 文本配置会按目标 frame 自动适配字号，避免文字超出槽位：
+
+- `mode: 'dynamic'`：默认行为。生成文字自身尺寸的纹理，渲染时按自身逻辑尺寸居中到 frame 内，不会被拉伸。
+- `mode: 'replace'`：生成和 frame 一样大的纹理，按替换图逻辑铺满 frame。
+- `fontSize?: number`：期望字号；如果文字放不下，会自动缩小。
+- `minFontSize?: number` / `maxFontSize?: number`：限制自适应字号范围。
+- `padding?: number`：文字纹理内边距，默认 `2`。
+- `scale?: number`：文字纹理栅格倍率，SVGA 默认 `3`，用于保持清晰度。
+- `fontStyle?: string | { font?: string; color?: string }`：字体样式，SVGA / VAP 都支持。
+
+`fontStyle` 可以直接传 canvas font 字符串：
+
+```ts
+svgaSlots: {
+  title: {
+    text: 'Hello',
+    fontStyle: 'bold 40px Arial',
+  },
+}
+```
+
+也可以传对象：
+
+```ts
+vapSlots: {
+  welcome01: {
+    text: '欢迎进入房间',
+    fontStyle: {
+      font: 'bold 40px Arial',
+      color: '#ffffff',
+    },
+  },
+}
+```
+
+对象形式目前生效字段是 `font` 和 `color`。如果同时传了外层 `color` 和 `fontStyle.color`，以 `fontStyle.color` 为准。VAP 文本如果没有传 `fontStyle`，会回退使用 VAP 配置里的 `src.fontStyle`。
+
+### VAP / VAPX
+
+使用 `vapSlots`：
+
+```ts
+await stage.addGift({
+  type: 'vap',
+  source: 'https://example.com/demo.mp4',
+  config: 'https://example.com/demo.json',
+  x: 0,
+  y: 0,
+  width: 400,
+  height: 400,
+  vapSlots: {
+    welcome01: '欢迎进入房间',
+    avatar_left: 'https://example.com/avatar.png',
+  },
+});
+```
+
+支持：
+
+- 文本字符串
+- 图片 URL
+- `TexImageSource`
+- 结构化文本 / 图片对象
+
+## 后端策略
+
+默认回退顺序：
+
+1. `WebGPU`
+2. `WebGL2`
+3. `WebGL1`
+
+说明：
+
+- `WebGPU` 仅在浏览器支持相关必要能力时启用
+- `WebGL1` 主要用于兼容兜底，不以性能最优为目标
+- demo 中可手动强制切换到 `WebGL1`
+
+## 缓存策略
+
+### 内存缓存
+
+- 默认 `128MB`
+- LRU 淘汰
+
+缓存内容包括：
+
+- 原始资源字节
+- 文本 / JSON
+- `SVGA` worker payload
+- `SVGA` atlas 资产
+
+### `IndexedDB` 磁盘缓存
+
+- 默认 `2048MB`
+- LRU 淘汰
+- 读取命中会刷新最近访问时间
+- 超出预算时按最久未使用记录淘汰
+
+异常情况处理：
+
+- `IndexedDB` 不可用、事务失败、写入失败、容量不足时，会自动降级
+- 损坏的 `SVGA` 磁盘缓存会自动删除并重新生成
+
+## 项目结构
+
+主要目录：
+
+- `src/`
+  核心源码
+- `docs/`
+  设计与汇总文档
+- `publish/`
+  发布脚本
+- `static/`
+  demo 依赖资源
+- `tests/`
+  测试
+
+## 对外导出
+
+入口文件：
+
+- [src/index.ts](/D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/src/index.ts)
+
 主要导出：
-
-- `GiftStage`
-- `createBackend`
-- `WebGPUBackend`
-- `WebGL2Backend`
-- `WebGL1Backend`
-- `parseSVGA`
-- `buildAtlas`
-- `parseVAPConfig`
+
+- `GiftStage`
+- `createBackend`
+- `WebGPUBackend`
+- `WebGL2Backend`
+- `WebGL1Backend`
+- `parseSVGA`
+- `buildAtlas`
+- `parseVAPConfig`
 - 相关类型定义
 
-## Demo
-
-Demo 入口：
-
-- [index.html](/D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/index.html)
+### 第三方 `GPUBackend` 迁移
 
-可用于验证：
+`GPUBackend` 的帧与提交操作使用显式结果契约。第三方实现必须让 `beginFrame()`、`draw(command)`、`endFrame()` 和 `abortFrame()` 返回：
 
-- `SVGA / VAP / AlphaVideo` 播放
-- slot 替换
-- `WebGPU / WebGL2 / WebGL1` 切换
-- 大批同屏压测
-
-## 相关文档
+```ts
+{ submitted: true }
+// 或
+{ submitted: false, reason, message? }
+```
 
-- 优化汇总：
-  [docs/giftstage-optimization-summary.md](/D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/docs/giftstage-optimization-summary.md)
+稳定的 `reason` 为 `backend-lost | invalid-command | missing-resource | capacity | validation-error | submission-error`。只有真正到达原生 `drawElements` / `drawIndexed` 或成功完成对应帧操作时才能返回 `submitted: true`；不得再实现或依赖 `wasLastDrawSubmitted()`，也不得用性能计数差值推断提交结果。`abortFrame()` 拒绝表示无法保证失败帧被丢弃，Stage 会立即隔离该 Backend。
+
+## Demo
+
+Demo 入口：
+
+- [index.html](/D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/index.html)
+
+可用于验证：
+
+- `SVGA / VAP / AlphaVideo` 播放
+- slot 替换
+- `WebGPU / WebGL2 / WebGL1` 切换
+- 大批同屏压测
+
+## 相关文档
+
+- 优化汇总：
+  [docs/giftstage-optimization-summary.md](/D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/docs/giftstage-optimization-summary.md)