@taole/giftstage 0.1.36 → 0.2.2

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

@@ -1,9 +1,10 @@
-import type { GiftSlot } from '../types';
+import type { GiftSlot } from '../types/index.js';
 export declare class AudioManager {
     private ctx;
     private decodedCache;
     private activeSources;
     private globalMute;
+    private suspended;
     private gainNode;
     private ensureContext;
     decodeAudio(key: string, data: ArrayBuffer): Promise<void>;
@@ -19,8 +20,16 @@ export declare class AudioManager {
      * sibling audio that already played this frame if called again with an unchanged frame number.
      */
     tickFrameForKey(slot: GiftSlot, currentFrame: number, audioKey: string): void;
+    /**
+     * Reconciles SVGA audio with a PlaybackScope-owned absolute frame clock. Unlike the ordinary
+     * frame-edge trigger, this also restores an audio clip at the correct offset after a seek,
+     * resume or skipped start frame, and replaces sources when the absolute loop changes.
+     */
+    syncPlaybackScopeFrame(slot: GiftSlot, absoluteFrame: number, discontinuous?: boolean): void;
     private startAudio;
+    private stopSourceAt;
     stopAllForGift(giftId: string): void;
     setMute(mute: boolean): void;
+    setSuspended(suspended: boolean): void;
     destroy(): void;
 }

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

@@ -1,4 +1,5 @@
-import type { GiftStageOptions, AddGiftOptions, GiftHandle, BackendType } from '../types';
+import type { GiftStageOptions, AddGiftOptions, GiftHandle, BackendType, GiftStageRuntimeDiagnostics } from '../types/index.js';
+import { type GiftAssetLease, type GiftStageCapabilities, type GiftStagePlugin, type MountedGiftStagePlugin, type PlaybackScope } from '../plugin/types.js';
 export declare function resolveResourcePipelineConcurrency(explicit: number | undefined, hardwareConcurrency?: number | undefined): number;
 export declare class GiftStage {
     private static readonly SVGA_ATLAS_MAX_SIZE;
@@ -40,6 +41,25 @@ export declare class GiftStage {
     private nextRenderOrder;
     private nextSharedWebCodecsPlaybackId;
     private nextSharedWebCodecsSurfaceId;
+    private readonly playbackScopes;
+    private readonly mountedPlugins;
+    /** Last path reported per slot, so asynchronous table promotion emits exactly once. */
+    private svgaReportedPathKeys;
+    /** One asynchronous table preparation per shared parsed entity. */
+    private svgaFrameTablePromises;
+    private svgaFrameTableResidentBytes;
+    private svgaFrameTableReservedBytes;
+    private releasedSVGATimelineEntities;
+    private activeSVGAGpuFrameTableBytes;
+    private reservedSVGAGpuFrameTableBytes;
+    private svgaBackendLost;
+    private svgaPreparingEntities;
+    private activeSVGATimelineEntities;
+    private svgaEntitySources;
+    private runtimeFallbackCount;
+    private runtimeObserverErrorCount;
+    private lastRuntimeDiagnostic;
+    private playbackPaused;
     private readonly onWindowLayout;
     private readonly onVisibilityChange;
     constructor(options: GiftStageOptions);
@@ -59,6 +79,8 @@ export declare class GiftStage {
     private resolveAnimationStepTarget;
     private runGiftAnimationStep;
     private createGiftAnimationChain;
+    private getGiftRenderInfo;
+    private reportSVGARenderPath;
     addGift(options: AddGiftOptions): Promise<GiftHandle>;
     private loadSVGA;
     private acquireSharedSVGAEntity;
@@ -66,6 +88,34 @@ export declare class GiftStage {
     private buildSharedSVGAEntity;
     private releaseSharedSVGAEntity;
     private createCachedSVGAAtlasTextures;
+    private svgaGpuFrameTableBudgetBytes;
+    /**
+     * A few integration tests intentionally construct a lightweight stage via
+     * `Object.create(GiftStage.prototype)`. Keep the resource bookkeeping lazy
+     * so those focused harnesses exercise SVGA loading without having to mirror
+     * every constructor-only field.
+     */
+    private ensureSVGATimelineBookkeeping;
+    private emitRuntimeDiagnostic;
+    private recordObserverError;
+    private runtimeErrorMessage;
+    private handleSVGABackendLoss;
+    private reserveSVGAFrameTableBytes;
+    private rollbackSVGAFrameTableReservation;
+    private commitSVGAFrameTableReservation;
+    private buildSVGATimelineDrawPlan;
+    private createSVGATimelineState;
+    /**
+     * Starts one resource-level immutable table upload. The first addGift frame
+     * remains on the reference path; preload awaits this same promise so later
+     * playbacks can start directly on the selected GPU path.
+     */
+    private ensureSVGAFrameTable;
+    private refreshSVGATimelineSlots;
+    private assignSVGATimelineStateToSlot;
+    private releaseSVGAFrameTable;
+    private fallbackSVGAFrameTable;
+    private getSVGAEntityDiagnosticContext;
     private deleteSVGAAtlasTextures;
     private deleteSVGAAtlasResultTextures;
     private finishLoadSVGA;
@@ -88,6 +138,11 @@ export declare class GiftStage {
      * slot's abort signal: shared entities can outlive the slot that first requested the work.
      */
     private ensureSVGAFullClipPrewarm;
+    /**
+     * Completes the immutable CPU draw schedule required by Hybrid before the
+     * resource is atomically promoted from the reference renderer.
+     */
+    private ensureSVGAHybridSchedulePrepared;
     private queueSVGAPersistentCacheWrite;
     private svgaAtlasMaxSize;
     private buildSVGAAtlasIfNeeded;
@@ -117,6 +172,8 @@ export declare class GiftStage {
      */
     private bindVideoLoopOnEnded;
     private clearHtmlVideoPlaybackWatchdog;
+    private clearAllHtmlVideoPlaybackWatchdogs;
+    private rearmHtmlVideoPlaybackWatchdogs;
     private completeHtmlVideoPlayback;
     private armHtmlVideoPlaybackWatchdog;
     private createVideo;
@@ -138,12 +195,17 @@ export declare class GiftStage {
      */
     private waitForFirstVideoFrame;
     private waitVideoReady;
+    get capabilities(): GiftStageCapabilities;
+    preload(type: 'svga' | 'image', source: string | ArrayBuffer, signal?: AbortSignal): Promise<GiftAssetLease>;
+    createPlaybackScope(id?: string): PlaybackScope;
+    mount<TApi>(plugin: GiftStagePlugin<TApi>): Promise<MountedGiftStagePlugin<TApi>>;
     removeGift(id: string): void;
     removeAll(): void;
     pause(): void;
     resume(): void;
     get activeCount(): number;
     get backendType(): BackendType;
+    getDiagnostics(): GiftStageRuntimeDiagnostics;
     destroy(): void;
     private markGiftPlaybackComplete;
     private resolveGiftPlaybackWaiters;

package/dist/core/index.d.ts

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

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

@@ -1,4 +1,4 @@
-import type { GiftSlot } from '../types';
+import type { GiftSlot } from '../types/index.js';
 export interface PostAnimationTarget {
     targetX: number;
     targetY: number;

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

@@ -1,14 +1,26 @@
-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';
+import type { GPUBackend, GiftSlot, GiftHandle, GPUTextureHandle, VideoEntity } from '../types/index.js';
+import { type SVGAClipMeshMap } from '../renderers/svga-batch-renderer.js';
+import { PostAnimator } from './post-animator.js';
+import { AudioManager } from './audio-manager.js';
+import { type WebCodecsAtlasRect } from './webcodecs-video-atlas.js';
+import type { PlaybackFrameController } from '../plugin/types.js';
+import type { ParticleBatchDescriptor, ParticleBatchHandle } from '../plugin/types.js';
+export interface RenderManagerRuntimeDiagnostics {
+    frameAbortCount: number;
+    replayFailureCount: number;
+    retryFrameCount: number;
+}
+export interface RenderManagerRuntimeDiagnosticEvent {
+    type: 'svga-frame-abort' | 'svga-frame-replay-failed' | 'svga-frame-retry' | 'backend-operation-rejected' | 'backend-quarantined' | 'stencil-transaction-failure' | 'clip-protocol-error' | 'clip-mesh-invalid' | 'atlas-command-invalid';
+    message?: string;
+}
 export declare class RenderManager {
     private backend;
     private svgaBatch;
     private vapRenderer;
     private alphaVideoRenderer;
     private imageRenderer;
+    private particleBatchRenderer;
     readonly postAnimator: PostAnimator;
     readonly audioManager: AudioManager;
     private slots;
@@ -16,10 +28,19 @@ export declare class RenderManager {
     private rafId;
     private lastTime;
     private running;
+    private destroyed;
     private globallyPaused;
     /** Set while the document is hidden (`GiftStage.setHidden`); suppresses rAF independent of `globallyPaused`. */
     private suspendedForHidden;
     private forceNextDraw;
+    private pendingAtomicFrameRetry;
+    private atomicRetryUsedForGenericFailure;
+    private readonly atomicRetryProgressEntities;
+    private runtimeFrameAbortCount;
+    private runtimeReplayFailureCount;
+    private runtimeRetryFrameCount;
+    private backendQuarantined;
+    private readonly onRuntimeDiagnostic?;
     private readonly onAnimationFrame;
     private readonly onHtmlVideoFrame;
     private readonly finishedSlotIdsScratch;
@@ -35,7 +56,11 @@ export declare class RenderManager {
     private readonly wcDbgTickOnce;
     private readonly advancedSharedWebCodecsScratch;
     private readonly activeSharedWebCodecsScratch;
-    constructor(backend: GPUBackend);
+    private readonly frameControllers;
+    constructor(backend: GPUBackend, onSVGAHybridValidationFailure?: (entity: NonNullable<GiftSlot['videoEntity']>) => void, onRuntimeDiagnostic?: (event: RenderManagerRuntimeDiagnosticEvent) => void);
+    getRuntimeDiagnosticsSnapshot(): RenderManagerRuntimeDiagnostics;
+    /** Runtime diagnostics are observational and must never change frame transaction control flow. */
+    private emitRuntimeDiagnostic;
     addSlot(slot: GiftSlot, handle: GiftHandle): void;
     getHandle(id: string): GiftHandle | undefined;
     releaseSlotResources(slot: GiftSlot): void;
@@ -43,6 +68,10 @@ export declare class RenderManager {
     getSlot(id: string): GiftSlot | undefined;
     get activeCount(): number;
     getSlotIds(): string[];
+    /** Number of active, table-compatible SVGA instances sharing one parsed entity. */
+    countCompatibleSVGAInstances(entity: VideoEntity): number;
+    registerFrameController(controller: PlaybackFrameController): () => void;
+    createParticleBatch(descriptor: ParticleBatchDescriptor): ParticleBatchHandle;
     /**
      * 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.
@@ -88,6 +117,13 @@ export declare class RenderManager {
      * group has gone inactive, so one paused copy never stalls playback for the rest.
      */
     syncVideoPlaybackForSlot(slot: GiftSlot): void;
+    private syncAudioSuspension;
+    /**
+     * Applies the single absolute media clock owned by PlaybackScope. SVGA frame state, public
+     * frame callbacks and embedded audio are deliberately updated together here so the scope
+     * cannot bypass media side effects while seeking the visual frame.
+     */
+    applyPlaybackScopeMediaTime(id: string, timeMs: number, emitInitialFrame?: boolean, discontinuous?: boolean): void;
     prewarmSVGAClipMeshes(entity: NonNullable<GiftSlot['videoEntity']>, options?: {
         frameBudgetMs?: number;
         workerTimeSliceMs?: number;
@@ -102,9 +138,21 @@ export declare class RenderManager {
         checkActive?: () => void;
         signal?: AbortSignal;
     }): Promise<number>;
+    prewarmSVGAShapeMeshes(entity: NonNullable<GiftSlot['videoEntity']>): number;
+    retainSVGAHybridMeshes(entity: NonNullable<GiftSlot['videoEntity']>): void;
+    releaseSVGAHybridMeshes(entity: NonNullable<GiftSlot['videoEntity']>): void;
     hydrateSVGAClipMeshes(meshes: SVGAClipMeshMap | null | undefined): void;
     snapshotSVGAClipMeshes(entity: NonNullable<GiftSlot['videoEntity']>): SVGAClipMeshMap;
     private renderLoop;
+    private drawPreparedFrameWithReplay;
+    private abortPreparedFrame;
+    private recordReplayFailure;
+    private shouldScheduleAtomicRetry;
+    private resetAtomicRetryCycle;
+    private runtimeErrorMessage;
+    private scheduleNextFrame;
+    private drawPreparedFrame;
+    private assertBackendOperation;
     /**
      * Fixed-step frame advancement matching Unity SvgaLitePlayer.Update()
      */
@@ -134,6 +182,7 @@ export declare class RenderManager {
     private getSVGASlotTextureKey;
     private drawLayer;
     private needsContinuousFrame;
+    private hasActiveFrameController;
     private insertSortedSlot;
     private static compareSlots;
     private drawSlotRun;