@taole/giftstage 0.1.27 → 0.1.29

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

@@ -0,0 +1,19 @@
+import type { GiftSlot, GiftHandle } from '../types';
+export declare class AudioManager {
+    private ctx;
+    private decodedCache;
+    private activeSources;
+    private globalMute;
+    private gainNode;
+    private ensureContext;
+    decodeAudio(key: string, data: ArrayBuffer): Promise<void>;
+    /**
+     * Frame-synced playback: start audio on startFrame, stop on endFrame.
+     * Matches SVGAPlayer-Web-master Canvas/renderer.js playAudio() pattern.
+     */
+    tickFrame(slot: GiftSlot, currentFrame: number, _handle: GiftHandle): void;
+    private startAudio;
+    stopAllForGift(giftId: string): void;
+    setMute(mute: boolean): void;
+    destroy(): void;
+}

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

@@ -0,0 +1,117 @@
+import type { GiftStageOptions, AddGiftOptions, GiftHandle, BackendType } from '../types';
+export declare function resolveResourcePipelineConcurrency(explicit: number | undefined, hardwareConcurrency?: number | undefined): number;
+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 DEFAULT_RESOURCE_CACHE_MEMORY_BYTES;
+    private static readonly DEFAULT_RESOURCE_CACHE_PERSISTENT_BYTES;
+    private readonly sharedSVGAEntities;
+    private readonly pendingSharedSVGAEntities;
+    private readonly sharedVideoSources;
+    private readonly sharedHtmlVideos;
+    private readonly sharedVideoTextures;
+    private readonly pendingSharedHtmlVideos;
+    private readonly sharedImageTextures;
+    private readonly pendingSharedImageTextures;
+    private readonly sharedWebCodecsPlaybacks;
+    private readonly pendingSharedWebCodecsPlaybacks;
+    private readonly sharedWebCodecsSurfaces;
+    private readonly completedPlaybackSlots;
+    private readonly playbackCompleteWaiters;
+    private canvas;
+    private backend;
+    private manager;
+    private options;
+    /** Resolves when WebGPU/WebGL backend + WASM are ready; safe to `await` before `addGift`. */
+    readonly ready: Promise<void>;
+    private destroyed;
+    private resizeObserver;
+    private nextRenderOrder;
+    private nextSharedWebCodecsPlaybackId;
+    private nextSharedWebCodecsSurfaceId;
+    private readonly onWindowLayout;
+    constructor(options: GiftStageOptions);
+    private backingStoreDpr;
+    private syncCanvasSize;
+    private resourcePipelineConcurrency;
+    private init;
+    private svgaParseOptions;
+    private svgaAtlasFrameBudgetMs;
+    private svgaClipFrameBudgetMs;
+    private isSlotLoadActive;
+    private assertSlotLoadActive;
+    private isLoadCanceled;
+    private currentCanvasCssSize;
+    private resolveGiftIntrinsicSize;
+    private normalizeAddGiftOptions;
+    private resolveAnimationStepTarget;
+    private runGiftAnimationStep;
+    private createGiftAnimationChain;
+    addGift(options: AddGiftOptions): Promise<GiftHandle>;
+    private loadSVGA;
+    private acquireSharedSVGAEntity;
+    private waitForPendingSharedSVGAEntity;
+    private buildSharedSVGAEntity;
+    private releaseSharedSVGAEntity;
+    private createCachedSVGAAtlasTextures;
+    private deleteSVGAAtlasTextures;
+    private deleteSVGAAtlasResultTextures;
+    private finishLoadSVGA;
+    private svgaAtlasMaxSize;
+    private buildSVGAAtlasIfNeeded;
+    private svgaAtlasMaxPages;
+    private shouldTryWebCodecs;
+    /** DevTools: filter by `[GiftStage]` to see WebCodecs vs &lt;video&gt; per gift. */
+    private logPlaybackBackend;
+    private tryWebCodecsPlayback;
+    private acquireWebCodecsPlayback;
+    private acquireSharedWebCodecsPlayback;
+    private createPendingSharedWebCodecsPlayback;
+    private waitForPendingSharedWebCodecsPlayback;
+    private releaseSharedWebCodecsPlayback;
+    private attachWebCodecsPlayback;
+    private releaseAttachedWebCodecsPlayback;
+    private acquireSharedWebCodecsSurface;
+    private retainSharedWebCodecsSurface;
+    private createSharedWebCodecsSurface;
+    private releaseSharedWebCodecsSurface;
+    private attachSharedWebCodecsSurface;
+    private loadVAP;
+    private createVAPMixResourceTextures;
+    private loadAlphaVideo;
+    /**
+     * Some mobile WebKit builds ignore or partially apply `video.loop`; `ended` still fires once.
+     * Drive repeat / infinite playback explicitly from `ended` (aligns with SVGA `loop`: 0 = ∞, default 1).
+     */
+    private bindVideoLoopOnEnded;
+    private createVideo;
+    private waitVideoMetadata;
+    private probeVideoNaturalSize;
+    private acquireVideoPlaybackSource;
+    private normalizeSharedVideoSourceKey;
+    private fetchSharedVideoSource;
+    private releaseSharedVideoSource;
+    private tryAcquireSharedHtmlVideo;
+    private acquireSharedVideoTexture;
+    private acquireImageTexture;
+    private releaseSharedImageTexture;
+    private releaseSharedVideoTexture;
+    private releaseSharedHtmlVideo;
+    /**
+     * After `play()`, wait until at least one frame is presented so WebGPU
+     * `copyExternalImageToTexture(<video>)` can import (avoids “no back resource” / early return).
+     */
+    private waitForFirstVideoFrame;
+    private waitVideoReady;
+    removeGift(id: string): void;
+    removeAll(): void;
+    pause(): void;
+    resume(): void;
+    get activeCount(): number;
+    get backendType(): BackendType;
+    destroy(): void;
+    private markGiftPlaybackComplete;
+    private resolveGiftPlaybackWaiters;
+    private waitForGiftPlaybackComplete;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { GiftStage } from './gift-stage';
+export { RenderManager } from './render-manager';
+export { AudioManager } from './audio-manager';
+export { PostAnimator } from './post-animator';

package/dist/core/post-animator.d.ts

@@ -0,0 +1,43 @@
+import type { GiftSlot } from '../types';
+export interface PostAnimationTarget {
+    targetX: number;
+    targetY: number;
+    targetScale: number;
+    targetOpacity: number;
+    targetRotation?: number;
+    duration: number;
+    easing: (t: number) => number;
+    onComplete?: () => void;
+}
+export declare class PostAnimator {
+    private animations;
+    private completedScratch;
+    private individuallyPaused;
+    private globallyPaused;
+    startFly(slot: GiftSlot, targetX: number, targetY: number, targetScale: number, duration: number, easing: (t: number) => number, onComplete?: () => void, targetOpacity?: number, targetRotation?: number): void;
+    startTween(slot: GiftSlot, targetX: number, targetY: number, targetScale: number, duration: number, easing: (t: number) => number, onComplete?: () => void, onCancel?: () => void, targetOpacity?: number, targetRotation?: number): void;
+    startTweenPromise(slot: GiftSlot, targetX: number, targetY: number, targetScale: number, duration: number, easing: (t: number) => number, onComplete?: () => void, targetOpacity?: number, targetRotation?: number): Promise<void>;
+    startSequence(slot: GiftSlot, targets: PostAnimationTarget[]): Promise<void>;
+    update(now: number): void;
+    /**
+     * Get the current animated position/scale for a gift.
+     * Returns null if no active animation.
+     */
+    getAnimatedState(giftId: string, now: number): {
+        x: number;
+        y: number;
+        scale: number;
+        opacity: number;
+        rotation: number;
+    } | null;
+    applyAnimatedState(slot: GiftSlot, now: number): boolean;
+    hasAnimation(giftId: string): boolean;
+    hasActiveAnimations(): boolean;
+    pauseForGift(giftId: string, now?: number): void;
+    resumeForGift(giftId: string, now?: number): void;
+    pauseAll(now?: number): void;
+    resumeAll(now?: number): void;
+    cancelForGift(giftId: string): void;
+    releaseGift(giftId: string): void;
+    destroy(): void;
+}

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

@@ -0,0 +1,99 @@
+import type { GPUBackend, GiftSlot, GiftHandle, GPUTextureHandle } from '../types';
+import { type SVGAClipMeshMap } from '../renderers/svga-batch-renderer';
+import { PostAnimator } from './post-animator';
+import { AudioManager } from './audio-manager';
+import { type WebCodecsAtlasRect } from './webcodecs-video-atlas';
+export declare class RenderManager {
+    private backend;
+    private svgaBatch;
+    private vapRenderer;
+    private alphaVideoRenderer;
+    private imageRenderer;
+    readonly postAnimator: PostAnimator;
+    readonly audioManager: AudioManager;
+    private slots;
+    private handles;
+    private rafId;
+    private lastTime;
+    private running;
+    private forceNextDraw;
+    private readonly onAnimationFrame;
+    private readonly finishedSlotIdsScratch;
+    private readonly videoRunMapScratch;
+    /** Shared WebCodecs RGBA atlas (optional); multiple slots may reference `handle` with distinct `wcAtlasRect`. */
+    private wcAtlas;
+    /** One-shot logs for WebCodecs clock debugging (filter console by `[GiftStage:WC]`). */
+    private readonly wcDbgTickOnce;
+    private readonly advancedSharedWebCodecsScratch;
+    private readonly activeSharedWebCodecsScratch;
+    constructor(backend: GPUBackend);
+    addSlot(slot: GiftSlot, handle: GiftHandle): void;
+    releaseSlotResources(slot: GiftSlot): void;
+    removeSlot(id: string): void;
+    getSlot(id: string): GiftSlot | undefined;
+    get activeCount(): number;
+    getSlotIds(): string[];
+    /**
+     * 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.
+     */
+    tryAllocateWebCodecsAtlas(slotId: string, frameW: number, frameH: number, cfg: {
+        width: number;
+        height: number;
+    } | undefined): {
+        handle: GPUTextureHandle;
+        rect: WebCodecsAtlasRect;
+    } | null;
+    releaseWebCodecsAtlasAllocation(slotId: string): void;
+    /** Re-apply CSS-space options when canvas backing store or layout changes (skips active fly animations). */
+    syncSlotLayoutFromOptions(): void;
+    private start;
+    private stop;
+    private clearFrameOnce;
+    pause(): void;
+    resume(): void;
+    prewarmSVGAClipMeshes(entity: NonNullable<GiftSlot['videoEntity']>, options?: {
+        frameBudgetMs?: number;
+        workerTimeSliceMs?: number;
+        useWorker?: boolean;
+        checkActive?: () => void;
+        signal?: AbortSignal;
+    }): Promise<number>;
+    hydrateSVGAClipMeshes(meshes: SVGAClipMeshMap | null | undefined): void;
+    snapshotSVGAClipMeshes(entity: NonNullable<GiftSlot['videoEntity']>): SVGAClipMeshMap;
+    private renderLoop;
+    /**
+     * Fixed-step frame advancement matching Unity SvgaLitePlayer.Update()
+     */
+    /**
+     * Advance WebCodecs playback clock (mirrors HTMLVideoElement time + `ended` loop semantics).
+     */
+    private tickSharedWebCodecs;
+    private tickWebCodecs;
+    private wcDbgLogTickOnce;
+    /** Same completion path as `GiftStage.bindVideoLoopOnEnded` for &lt;video&gt;. */
+    private onWebCodecsPlaybackComplete;
+    private tickSVGA;
+    private onGiftPlayComplete;
+    private tickImage;
+    private removeFinished;
+    /** Reused scratch to avoid a per-frame array allocation; consumed synchronously by getRenderLayers. */
+    private orderedSlotsScratch;
+    private getRenderOrderedSlots;
+    private getRenderLayers;
+    /**
+     * Multiple copies of the same gift are often added together before each copy
+     * flies to a different target. While their visual state is exactly identical,
+     * drawing every copy only increases overdraw and changes translucent pixels.
+     * Keep the top-most copy until a transform or frame diverges.
+     */
+    private collapseCoincidentVisualDuplicates;
+    private getCoincidentVisualKey;
+    private getSVGASlotTextureKey;
+    private drawLayer;
+    private drawSlotRun;
+    /** Batch keys are cached on the slot and only rebuilt when their inputs change. */
+    private getBatchKey;
+    private deleteSVGAAtlasTextures;
+    destroy(): void;
+}

package/dist/core/webcodecs-video-atlas.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Row-packs decoded WebCodecs frames into one RGBA atlas to share a single texture bind across many gifts.
+ * Falls back to per-gift textures when allocation fails (returns null).
+ */
+export interface WebCodecsAtlasRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export declare class WebCodecsVideoAtlasAllocator {
+    private readonly atlasW;
+    private readonly atlasH;
+    /** Current row: y offset and row height. */
+    private rowY;
+    private rowH;
+    private rowX;
+    private readonly slots;
+    constructor(atlasW: number, atlasH: number);
+    get size(): {
+        w: number;
+        h: number;
+    };
+    /**
+     * Reserve a `w×h` rectangle (texels). Returns null if it does not fit.
+     */
+    tryAllocate(slotId: string, w: number, h: number): WebCodecsAtlasRect | null;
+    release(slotId: string): void;
+    getRect(slotId: string): WebCodecsAtlasRect | undefined;
+}