@taole/giftstage 0.1.30 → 0.1.32

package/README.md

@@ -249,8 +249,9 @@ Promise<GiftHandle>;
 - `height?: number`
 - `useOriginalSize?: boolean`
 - `objectFit?: 'contain' | 'cover'`
-- `loop?: number`
-  - `0` 表示无限循环
+- `loop?: number`
+  - `0` 表示无限循环
+  - VAP / AlphaVideo 的 HTMLVideo 回退路径会为有限循环设置“媒体总时长 + 容错窗口”的超时保护；即使浏览器未触发 `ended`，也会进入正常完成和清理流程
 - `opacity?: number`
   - 全局透明度，范围 `0 ~ 1`，默认 `1`
 - `rotation?: number`
@@ -267,6 +268,11 @@ Promise<GiftHandle>;
   - 播放结束后，是否自动移除礼物
   - 默认 `true`，传 `false` 时会停留最后一帧，方便后续继续调用 `gift.animate(...).start()`
 - `mute?: boolean`
+  - `VAP / AlphaVideo` 传 `false` 时使用 `HTMLVideoElement` 播放声音；该礼物不会进入仅解码视频帧的 WebCodecs 路径
+  - 如果浏览器阻止有声自动播放，会自动回退静音播放，保证画面正常完成
+- `onFrame?: (frame, gift) => void`
+  - 仅用于 SVGA；画面帧推进时触发
+  - 性能不足时可能跨帧，业务应使用 `frame >= target` 的阈值判断
 - `onComplete?: (gift) => void`
 
 图片专用参数：

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

@@ -4,6 +4,11 @@ export declare class GiftStage {
     private static readonly SVGA_ATLAS_MAX_SIZE;
     private static readonly SVGA_ATLAS_PADDING;
     private static readonly DEFAULT_SHARED_VIDEO_PLAYBACK_WINDOW_MS;
+    private static readonly HTML_VIDEO_READY_TIMEOUT_MS;
+    private static readonly HTML_VIDEO_WATCHDOG_MIN_GRACE_MS;
+    private static readonly HTML_VIDEO_WATCHDOG_MAX_GRACE_MS;
+    private static readonly HTML_VIDEO_WATCHDOG_GRACE_RATIO;
+    private static readonly MAX_TIMER_DELAY_MS;
     private static readonly DEFAULT_RESOURCE_CACHE_MEMORY_BYTES;
     private static readonly DEFAULT_RESOURCE_CACHE_PERSISTENT_BYTES;
     private readonly sharedSVGAEntities;
@@ -85,6 +90,9 @@ export declare class GiftStage {
      * Drive repeat / infinite playback explicitly from `ended` (aligns with SVGA `loop`: 0 = ∞, default 1).
      */
     private bindVideoLoopOnEnded;
+    private clearHtmlVideoPlaybackWatchdog;
+    private completeHtmlVideoPlayback;
+    private armHtmlVideoPlaybackWatchdog;
     private createVideo;
     private waitVideoMetadata;
     private probeVideoNaturalSize;