@taole/giftstage 0.1.27 → 0.1.29

package/README.md

@@ -1,636 +1,698 @@
-# GiftStage
-
-统一的 Web 礼物播放框架，支持：
-
-- `SVGA`
-- `VAP / VAPX`
+# GiftStage
+
+统一的 Web 礼物播放框架，支持：
+
+- `SVGA`
+- `VAP / VAPX`
 - 透明视频 `AlphaVideo`
-
-底层支持：
-
-- `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`
+- 静态图片 `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
-```
-
-## 快速开始
-
-```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`
-  是否开启抗锯齿。
-
-- `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 的共享加载按消费者计数，单个礼物取消不会中断其他仍在等待的礼物。
-
-- `onError?: (error: Error) => void`
-  统一错误回调。
-
-### `await stage.ready`
-
-等待底层后端和运行环境初始化完成。建议在第一次 `addGift()` 前等待。
-
-### `stage.addGift(options)`
-
-插入一个礼物，返回：
-
-```ts
-Promise<GiftHandle>;
-```
-
-### `GiftHandle` API
-
-`addGift()` 返回的句柄可用于控制单个礼物：
-
-- `gift.id`
-- `gift.type`
+- 四类礼物共用位移、缩放、透明度、旋转、层级和销毁生命周期
+
+## 安装
+
+```bash
+npm install
+```
+
+安装发布包：
+
+```bash
+npm i @taole/giftstage
+```
+
+## 开发
+
+```bash
+npm run dev
+```
+
+## 构建
+
+```bash
+npm run build
+```
+
+Demo 构建：
+
+```bash
+npm run build:demo
+```
+
+## 快速开始
+
+```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`
+  是否开启抗锯齿。
+
+- `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 的共享加载按消费者计数，单个礼物取消不会中断其他仍在等待的礼物。
+
+- `onError?: (error: Error) => void`
+  统一错误回调。
+
+### `await stage.ready`
+
+等待底层后端和运行环境初始化完成。建议在第一次 `addGift()` 前等待。
+
+### `stage.addGift(options)`
+
+插入一个礼物，返回：
+
+```ts
+Promise<GiftHandle>;
+```
+
+### `GiftHandle` API
+
+`addGift()` 返回的句柄可用于控制单个礼物：
+
+- `gift.id`
+- `gift.type`
 - `gift.pause()`
 - `gift.resume()`
-- `gift.destroy()`
-  - 立即移除当前礼物
-- `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()`
-
-恢复舞台。
-
-### `stage.destroy()`
-
-销毁舞台并释放资源。
-
-## `addGift()` 参数
-
-### 通用参数
-
-- `type: 'svga' | 'vap' | 'alphaVideo'`
-- `source: string | ArrayBuffer`
-- `x: number | \`${number}%\``
-- `y: number | \`${number}%\``
-- `zIndex?: number`
-- `width?: number`
-- `height?: number`
-- `useOriginalSize?: boolean`
-- `objectFit?: 'contain' | 'cover' | 'fill'`
-- `loop?: number`
-  - `0` 表示无限循环
+  - 暂停期间礼物播放时钟、图片 `duration` 和后置动画都会冻结
+- `gift.destroy()`
+  - 立即移除当前礼物
+- `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()`
+
+恢复舞台。
+
+### `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` 表示无限循环
 - `opacity?: number`
   - 全局透明度，范围 `0 ~ 1`，默认 `1`
-- `clearsAfterStop?: boolean`
-  - 播放结束后，是否自动移除礼物
-  - 默认 `true`，传 `false` 时会停留最后一帧，方便后续继续调用 `gift.animate(...).start()`
+- `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`
 - `onComplete?: (gift) => void`
 
-层级规则：
-
-- `zIndex` 在 `SVGA / VAP / AlphaVideo` 三种礼物间通用
-- 数值越大，渲染越靠上
-- 同层级下，后 `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,
+图片专用参数：
+
+- `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,
 });
 ```
 
-这时会按舞台尺寸做等比适配，并保持礼物原始宽高比。
+### 播放图片
 
-如果希望礼物铺满整个画布，并按中心裁剪超出的部分，可以使用 `cover`：
+`source` 首版支持 URL 和 `ArrayBuffer`。URL 图片会按地址共享 GPU 纹理并引用计数；图片按静态帧处理，不保证 GIF / WebP 动画播放。跨域 URL 必须允许匿名 CORS 读取。
 
 ```ts
-await stage.addGift({
-  type: 'svga',
-  source: 'https://example.com/demo.svga',
+const avatar = await stage.addGift({
+  type: 'image',
+  source: 'https://example.com/avatar.png',
   x: '50%',
   y: '50%',
+  width: 100,
+  height: 100,
   objectFit: 'cover',
-  loop: 0,
+  duration: 5000,
 });
 ```
-
-当 `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,
-  loop: 0,
-});
-```
-
-### 播放透明视频
-
-```ts
-await stage.addGift({
-  type: 'alphaVideo',
-  source: 'https://example.com/demo.mp4',
-  x: 20,
-  y: 20,
-  width: 400,
-  height: 220,
-  loop: 0,
-});
-```
-
-## 动画控制
-
-### 链式动画
-
-`addGift()` 返回的 `GiftHandle` 支持 `animate()`。一次 `to()` 是组合动画，同一步里可以同时移动、缩放和改变透明度；多个 `to()` / `then()` 会按顺序播放：
-
-```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 },
+
+## 动画控制
+
+### 链式动画
+
+`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,
-    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();
-```
-
-也可以传入单步或数组：
-
-```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();
+    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();
 ```
 
-## Slot 替换
+### 绕外部中心旋转
 
-### SVGA
-
-使用 `svgaSlots`：
+下面的礼物初始位于舞台中心右侧 200px，旋转中心通过框外坐标指回舞台中心：
 
 ```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',
-    },
-  },
+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%' },
 });
-```
-
-支持：
-
-- `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',
-  },
-});
+await orbitGift
+  .animate({ rotationTo: Math.PI * 2, duration: 1200 })
+  .start();
 ```
-
-支持：
-
-- 文本字符串
-- 图片 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`
-- 相关类型定义
-
-## 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)
+
+也可以传入单步或数组：
+
+```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`
+- 相关类型定义
+
+## 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)