@taole/giftstage 0.1.28 → 0.1.30

package/dist/types/index.d.ts

@@ -0,0 +1,699 @@
+export type BackendType = 'webgpu' | 'webgl2' | 'webgl1';
+export type BufferUsage = 'vertex' | 'index' | 'uniform';
+export type GPUBufferSource = ArrayBufferLike | ArrayBufferView;
+export interface GPUBufferHandle {
+    readonly id: number;
+    readonly usage: BufferUsage;
+}
+export interface GPUTextureHandle {
+    readonly id: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface TextureOpts {
+    width?: number;
+    height?: number;
+    format?: 'rgba8' | 'rgb8';
+    filter?: 'linear' | 'nearest';
+    wrap?: 'clamp' | 'repeat';
+    /** Upload external image sources as premultiplied RGBA. ArrayBuffer sources are assumed already in final pixel format. */
+    premultiplyAlpha?: boolean;
+    /**
+     * When true, the external source (e.g. `ImageBitmap` from `createImageBitmap(…, { premultiplyAlpha: 'premultiply' })`)
+     * is already premultiplied; WebGL must not set `UNPACK_PREMULTIPLY_ALPHA_WEBGL` for this upload (avoids double
+     * premultiply). WebGPU infers from the `ImageBitmap`; this flag is mainly for the GL path.
+     */
+    sourcePremultiplied?: boolean;
+}
+export type ShaderType = 'svga-batch-premul'
+/** WebGPU / WebGL2: SVGA premultiplied atlas sprites batched as instances using `FrameJobData` payloads. */
+ | 'svga-instanced-premul' | 'vap'
+/** Main-context VAP mixed resource draw: resource texture multiplied by raw-video mask. */
+ | 'vap-mix-overlay'
+/** WebGPU / WebGL2: batched VAP sharing one texture; see `instanceCount` / `instanceData` (32 floats/instance). */
+ | 'vap-instanced' | 'alpha-video'
+/** WebGPU: batched draws sharing one texture (e.g. atlas); see `instanceCount` / `instanceData`. */
+ | 'alpha-video-instanced' | 'rgba-textured' | 'clip-mask';
+export type StencilMode = 'none' | 'write' | 'test' | 'clear';
+export interface DrawCommand {
+    shader: ShaderType;
+    vertexBuffer: GPUBufferHandle;
+    indexBuffer: GPUBufferHandle;
+    indexCount: number;
+    textures: GPUTextureHandle[];
+    uniforms: Record<string, Float32Array | number>;
+    stencil?: StencilMode;
+    /**
+     * `svga-instanced-premul`: the first `instanceCount * 13` floats are consumed
+     * (layout + transform + alpha + uv rect).
+     *
+     * `alpha-video-instanced`: the first `instanceCount * 12` floats are consumed
+     * (display rect + atlasRemap + opacity/source-alpha-mode vec4).
+     * `vap-instanced`: the first `instanceCount * 32` floats are consumed
+     * (mat4 + atlasRemap + rgb/alpha rects + opacity/source-alpha-mode vec4).
+     * Renderers may pass a larger reused scratch array to avoid allocating a subarray view per draw.
+     */
+    instanceCount?: number;
+    instanceData?: Float32Array;
+}
+export interface GPUBackend {
+    readonly type: BackendType;
+    readonly canvas: HTMLCanvasElement;
+    /** Maximum supported 2D texture dimension for this backend/device. */
+    readonly maxTextureSize?: number;
+    init(): Promise<void>;
+    beginFrame(): void;
+    endFrame(): void;
+    createBuffer(data: GPUBufferSource, usage: BufferUsage): GPUBufferHandle;
+    updateBuffer(handle: GPUBufferHandle, data: GPUBufferSource, offset?: number): void;
+    deleteBuffer(handle: GPUBufferHandle): void;
+    createTexture(source: TexImageSource | ArrayBuffer, opts: TextureOpts): GPUTextureHandle;
+    /** Uninitialized RGBA texture (e.g. WebCodecs atlas backing store). */
+    createEmptyTexture(width: number, height: number, opts?: TextureOpts): GPUTextureHandle;
+    updateTexture(handle: GPUTextureHandle, source: TexImageSource): void;
+    /** When `destWidth`/`destHeight` differ from source size, uploads a uniformly scaled copy into the region. */
+    updateTextureRegion(handle: GPUTextureHandle, source: TexImageSource, x: number, y: number, destWidth?: number, destHeight?: number): void;
+    deleteTexture(handle: GPUTextureHandle): void;
+    draw(cmd: DrawCommand): void;
+    clearStencil?(): void;
+    setScissor(x: number, y: number, w: number, h: number): void;
+    resetScissor(): void;
+    destroy(): void;
+}
+export interface SVGAParams {
+    viewBoxWidth: number;
+    viewBoxHeight: number;
+    fps: number;
+    frames: number;
+}
+export interface SVGATransform {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    tx: number;
+    ty: number;
+}
+export type SVGAShapeKind = 'path' | 'rect' | 'ellipse';
+export interface SVGAColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export interface SVGAShapeStyle {
+    fill: SVGAColor | null;
+    stroke: SVGAColor | null;
+    strokeWidth: number;
+    lineCap?: number;
+    lineJoin?: number;
+    miterLimit?: number;
+    lineDash?: number[];
+}
+export interface SVGAShape {
+    kind: SVGAShapeKind;
+    pathData?: string;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        cornerRadius?: number;
+    };
+    ellipse?: {
+        x: number;
+        y: number;
+        radiusX: number;
+        radiusY: number;
+    };
+    style: SVGAShapeStyle;
+    transform: SVGATransform;
+}
+/** Floats per frame in SVGASpriteTable.frameData. */
+export declare const SPRITE_FRAME_FLOATS = 9;
+/**
+ * SoA sprite table: contiguous frame floats + deduped clip/shapes side tables.
+ * Replaces per-sprite `frames: SVGAFrame[]` object graphs.
+ */
+export interface SVGASpriteTable {
+    spriteCount: number;
+    frameCount: number;
+    imageKeys: string[];
+    /** spriteCount × frameCount × 9: layoutW, layoutH, a, b, c, d, tx, ty, alpha. */
+    frameData: Float32Array;
+    clipPaths: string[];
+    clipPathIndex: Int32Array;
+    shapesTable: SVGAShape[][];
+    shapesIndex: Int32Array;
+    hasAnyShapes: boolean;
+}
+export interface SVGAAudio {
+    audioKey: string;
+    startFrame: number;
+    endFrame: number;
+    startTime: number;
+    totalTime: number;
+}
+export interface SVGAMovieEntity {
+    version: string;
+    params: SVGAParams;
+    images: Map<string, Uint8Array>;
+    spriteTable: SVGASpriteTable;
+    audios: SVGAAudio[];
+}
+export interface UVRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Atlas page index. Omitted means page 0 for older single-atlas data. */
+    textureIndex?: number;
+}
+export interface VideoEntity {
+    params: SVGAParams;
+    spriteTable: SVGASpriteTable;
+    audios: SVGAAudio[];
+    atlasTextureHandle: GPUTextureHandle | null;
+    atlasTextureHandles?: GPUTextureHandle[];
+    atlasRects: Map<string, UVRect>;
+    audioBuffers: Map<string, ArrayBuffer>;
+}
+export declare const FRAME_DATA_FLOATS = 13;
+export declare const VERTEX_FLOATS = 9;
+export declare const VERTS_PER_QUAD = 4;
+export declare const INDICES_PER_QUAD = 6;
+export interface FrameJobData {
+    layoutW: number;
+    layoutH: number;
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    tx: number;
+    ty: number;
+    alpha: number;
+    uvMinX: number;
+    uvMinY: number;
+    uvMaxX: number;
+    uvMaxY: number;
+}
+export type GiftType = 'svga' | 'vap' | 'alphaVideo' | 'image';
+export type GiftCoordinate = number | `${number}%`;
+/** How the RGB region of a split-alpha video is encoded before the separate alpha mask is applied. */
+export type VideoRGBAlphaMode = 'straight' | 'premultiplied';
+/** Narrow interface so `GiftSlot` does not import the mp4/WebCodecs module. */
+export interface WebCodecsPlaybackHandle {
+    readonly duration: number;
+    readonly videoWidth: number;
+    readonly videoHeight: number;
+    getFrameForTime(tSec: number): VideoFrame | null;
+    /** Optional: request decode ahead of `tSec` (Worker streaming + main-thread ring). */
+    ensureDecodedThrough?(tSec: number): void;
+    destroy(): void;
+}
+/** GiftStage-internal shared playback group. All consumers use the same looping clock. */
+export interface WebCodecsSharedPlaybackState {
+    readonly id: number;
+    readonly playback: WebCodecsPlaybackHandle;
+    readonly startedAtMs: number;
+}
+/** GiftStage-internal upload target shared by compatible WebCodecs consumers. */
+export interface WebCodecsTextureSurface {
+    readonly id: number;
+    readonly texture: GPUTextureHandle;
+    readonly atlasRect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    lastUploadedFrame: VideoFrame | null;
+}
+/** `contain`: uniform inside box. `cover`: uniform over box and clipped. `fill`: stretch to box. */
+export type GiftObjectFit = 'contain' | 'cover' | 'fill';
+export type GiftFontStyle = string | Record<string, string>;
+export interface GiftTextSlotContent {
+    text: string;
+    color?: string;
+    style?: 'b' | 'normal';
+    fontStyle?: GiftFontStyle;
+    /** Preferred logical font size in CSS pixels. Omit to auto-fit inside the target slot. */
+    fontSize?: number;
+    /** Minimum auto-fit font size. Default: `8`. */
+    minFontSize?: number;
+    /** Maximum auto-fit font size. Omit to derive from the target slot height. */
+    maxFontSize?: number;
+    /** Logical padding around generated text. Default: `2`. */
+    padding?: number;
+    /**
+     * SVGA only: `dynamic` centers by intrinsic size; `replace` stretches to frame layout.
+     * VAP text resources ignore this and always fit into the configured frame box.
+     */
+    mode?: 'replace' | 'dynamic';
+    /** Raster scale for generated text textures. Default: `3` for SVGA, `1` for VAP. */
+    scale?: number;
+}
+export interface GiftImageSlotContent {
+    image: TexImageSource | string;
+    /** SVGA only; defaults to `replace`. */
+    mode?: 'replace' | 'dynamic';
+}
+export interface VAPImageSlotContent {
+    image: TexImageSource | string;
+}
+export type SVGASlotContent = string | TexImageSource | GiftTextSlotContent | GiftImageSlotContent;
+export type VAPSlotContent = string | TexImageSource | GiftTextSlotContent | VAPImageSlotContent;
+export interface ResolvedSVGASlotTexture {
+    texture: GPUTextureHandle;
+    mode: 'replace' | 'dynamic';
+    logicalWidth: number;
+    logicalHeight: number;
+}
+export interface ResolvedVAPResource {
+    source: CanvasImageSource;
+    width: number;
+    height: number;
+}
+export interface VAPMixComposerHandle {
+    render(source: TexImageSource, frameIndex: number): HTMLCanvasElement;
+    destroy(): void;
+}
+export interface VAPMixState {
+    mode: 'direct' | 'composited';
+    texture?: GPUTextureHandle;
+    width: number;
+    height: number;
+    /** Main-context mixed resource textures, keyed by VAP srcId. */
+    resourceTextures?: Map<string, GPUTextureHandle>;
+    composer?: VAPMixComposerHandle | null;
+    compositeCanvas?: HTMLCanvasElement;
+    compositeCtx?: CanvasRenderingContext2D;
+    rawCanvas?: HTMLCanvasElement;
+    rawCtx?: CanvasRenderingContext2D;
+    scratchCanvas?: HTMLCanvasElement;
+    scratchCtx?: CanvasRenderingContext2D;
+    frameMap: Map<number, VAPFrameObj[]>;
+    /** Retained only by the CPU compositor fallback. */
+    resources?: Map<string, ResolvedVAPResource>;
+    lastFrameIndex: number;
+    lastSourceRef: CanvasImageSource | null;
+}
+export interface GiftStageOptions {
+    container: HTMLElement;
+    /**
+     * Overrides `window.devicePixelRatio` for the canvas backing store (bitmap px = CSS px × ratio).
+     * Omit to use device DPR (capped at 2 by default) so fullscreen overlays stay sharp on retina / mobile.
+     */
+    resolution?: number;
+    /**
+     * Maximum backing-store resolution (orientation-adaptive: long edge ≤ max(width, height),
+     * short edge ≤ min(width, height)).
+     * Default: mobile `{ width: 1920, height: 1080 }`, desktop `{ width: 2560, height: 1440 }`.
+     * When exceeded, the buffer is scaled down proportionally and the browser stretches the
+     * canvas via CSS. Set `false` to disable the cap. Applies even with an explicit {@link resolution}.
+     */
+    maxRenderSize?: {
+        width: number;
+        height: number;
+    } | false;
+    /**
+     * Edge smoothing: WebGL2 uses the context multisampled framebuffer; WebGPU uses 4× MSAA + resolve.
+     * Default: **true** for WebGL2, **false** for WebGPU (MSAA is expensive with large transparent-video fills).
+     * Set `true` explicitly when using WebGPU + sharp SVGA edges.
+     * Many concurrent transparent videos: keep WebGPU `antialias` off (default) and consider lowering {@link resolution}.
+     */
+    antialias?: boolean;
+    /**
+     * Default true. On phones/tablets with WebCodecs video, WebGL2 can still be faster than WebGPU
+     * (driver + MSAA); set `false` to prefer WebGL2 when you measure lower FPS with WebGPU.
+     */
+    preferWebGPU?: boolean;
+    /**
+     * Force WebGL1 backend for compatibility testing.
+     * When enabled, skips WebGPU/WebGL2 probing and uses the WebGL1 fallback directly.
+     */
+    forceWebGL1?: boolean;
+    /**
+     * Experimental.
+     * When explicitly set to `true`, VAP / alphaVideo try WebCodecs + mp4box on H.264 MP4
+     * and fall back to `HTMLVideoElement` if unsupported or on error.
+     * Default: false.
+     */
+    preferWebCodecs?: boolean;
+    /**
+     * Reuse playback resources for identical media sources that start almost together and loop forever.
+     * HTMLVideoElement shares the element; WebCodecs additionally shares its Worker, decoder, frame ring,
+     * looping clock and compatible GPU upload surface. Default: true.
+     */
+    shareIdenticalVideoPlayback?: boolean;
+    /**
+     * Max start-time gap, in milliseconds, for reusing an already-started shared HTMLVideoElement.
+     * Gifts added after this window create their own playback instance so they can still start from frame 0.
+     * Default: 100.
+     */
+    sharedVideoPlaybackWindowMs?: number;
+    /**
+     * Experimental WebCodecs-only option.
+     * When set, WebCodecs VAP / alphaVideo share one RGBA atlas (single texture bind per frame batch when possible).
+     * Reduces bind churn for many concurrent gifts; requires all packed clips to fit in `width×height` (row-packed).
+     * If a clip does not fit, that gift falls back to a dedicated texture (same as no atlas).
+     */
+    webCodecsVideoAtlas?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Experimental WebCodecs-only option.
+     * When true (default), H.264 MP4 demux + WebCodecs decode run in a Dedicated Worker; frames transfer to the main thread.
+     * Set false to force main-thread decode (e.g. tests).
+     */
+    webCodecsDecodeInWorker?: boolean;
+    /**
+     * Experimental WebCodecs-only option.
+     * Max number of decoded VideoFrame instances retained per WebCodecs clip on the main thread (ring).
+     * Default 28. Lower values reduce memory; too low may cause brief stalls until decode catches up.
+     */
+    webCodecsMaxDecodedFrames?: number;
+    /**
+     * Experimental WebCodecs-only option.
+     * How many frames ahead of the playhead the Worker tries to decode (after demux and on each tick).
+     * Default 8. Ignored when {@link webCodecsDecodeInWorker} is false (main-thread path decodes the full clip).
+     */
+    webCodecsDecodeAheadFrames?: number;
+    /**
+     * When true (default), SVGA inflate + protobuf run in a Dedicated Worker.
+     * ImageBitmap decode and atlas compose also prefer workers when available.
+     * Set false to parse SVGA entirely on the main thread (e.g. tests without Workers).
+     */
+    svgaParseInWorker?: boolean;
+    /**
+     * Max dimension for each SVGA atlas page. Large SVGA image sets are split across pages.
+     * Default: 4096, clamped to the backend/device max texture size.
+     */
+    svgaAtlasMaxSize?: number;
+    /**
+     * Max number of SVGA atlas pages before images are globally downscaled.
+     * Default: 4.
+     */
+    svgaAtlasMaxPages?: number;
+    /**
+     * Main-thread SVGA atlas compose/upload slice cap in milliseconds.
+     * The actual slice tracks half of the observed frame interval, capped here.
+     * Default: `12`.
+     */
+    svgaAtlasFrameBudgetMs?: number;
+    /**
+     * Shared main-thread SVGA load slice cap. The actual slice tracks half of
+     * the observed display interval and is capped at this value. Default: 12.
+     */
+    svgaLoadFrameBudgetMs?: number;
+    /**
+     * Worker cooperative CPU slice cap in milliseconds. Default: 4, clamped to
+     * 1-8. This does not split an individual WASM protobuf call.
+     */
+    svgaWorkerFrameBudgetMs?: number;
+    /**
+     * Global concurrency cap for CPU-heavy SVGA worker tasks (parser, image
+     * decode, atlas and clip prewarm). Default: 1.
+     */
+    svgaWorkerTaskConcurrency?: number;
+    /**
+     * Maximum concurrent createImageBitmap calls inside the SVGA image worker.
+     * Default: 2; the worker may temporarily reduce concurrency under load.
+     */
+    svgaWorkerImageDecodeConcurrency?: number;
+    /**
+     * Emit one structured parser profile for each actual SVGA parse. Default:
+     * false. Cache hits do not emit a profile.
+     */
+    svgaParseProfile?: boolean;
+    /**
+     * Prebuild SVGA clip-path stencil meshes during load instead of first use during playback.
+     * Default: true.
+     */
+    svgaPrewarmClipMeshes?: boolean;
+    /**
+     * Main-thread time slice, in milliseconds, used while prewarming SVGA clip meshes.
+     * Used only when worker prewarm is unavailable or disabled. Default: 8.
+     */
+    svgaClipPrewarmFrameBudgetMs?: number;
+    /**
+     * Build SVGA clip-path stencil meshes in a Dedicated Worker during load.
+     * Preserves the same geometry as main-thread mesh building while avoiding playback-frame stalls.
+     * Default: true.
+     */
+    svgaClipPrewarmInWorker?: boolean;
+    /**
+     * Global web-side concurrent resource pipeline limit (download / parse / image decode).
+     * Omit to auto-derive from `navigator.hardwareConcurrency`.
+     * When provided explicitly, the value is respected as-is (minimum `1`).
+     */
+    maxConcurrentParse?: number;
+    onError?: (error: Error) => void;
+}
+export interface AddGiftOptions {
+    type: GiftType;
+    source: string | ArrayBuffer;
+    config?: string | object;
+    /** SVGA imageKey -> replacement source (TexImageSource or generated text). */
+    svgaSlots?: Record<string, SVGASlotContent>;
+    /** VAPX srcTag/srcId -> replacement source (text string, image URL, TexImageSource, or structured text/image). */
+    vapSlots?: Record<string, VAPSlotContent>;
+    /**
+     * Layout relative to the stage canvas element.
+     * Numbers are treated as CSS pixels.
+     * Percentage strings like `50%` use the gift center as anchor on that axis,
+     * equivalent to `left/top: 50%` plus `translate(-50%, -50%)` on that axis.
+     */
+    x: GiftCoordinate;
+    y: GiftCoordinate;
+    /**
+     * Global render order shared across SVGA / VAP / alphaVideo.
+     * Higher values render later and appear above lower values.
+     */
+    zIndex?: number;
+    /**
+     * Display width in CSS pixels. Omit to use the gift's intrinsic width.
+     * If only one of `width` / `height` is provided, the other axis is derived from the intrinsic aspect ratio.
+     */
+    width?: number;
+    /**
+     * Display height in CSS pixels. Omit to use the gift's intrinsic height.
+     * If both are omitted and the gift is larger than the stage, it is uniformly scaled down to fit the stage.
+     */
+    height?: number;
+    /**
+     * When `true`, and both `width` / `height` are omitted, prefer the gift's intrinsic size
+     * if it already fits inside the stage; otherwise scale it down to fit.
+     * Default: `false`.
+     */
+    useOriginalSize?: boolean;
+    /**
+     * Omit: `contain` (uniform fit inside width×height) for all types.
+     * `cover`: uniform scale to cover width×height; if width/height are both omitted,
+     * uses the full stage canvas.
+     */
+    objectFit?: GiftObjectFit;
+    /** SVGA / video: `0` = loop forever. Video uses `ended` + manual restart when `HTMLVideoElement.loop` is unreliable (e.g. some mobile WebKit). */
+    loop?: number;
+    /** Global opacity multiplied into the rendered gift. Default: `1`. */
+    opacity?: number;
+    /** Initial clockwise rotation in radians. Default: `0`. */
+    rotation?: number;
+    /**
+     * Rotation origin inside the unscaled gift box. Numbers are CSS pixels from the
+     * top-left corner; percentages are relative to the gift width / height. Values
+     * outside the box are allowed so a gift can orbit around an external point.
+     * Default: `{ x: '50%', y: '50%' }`.
+     */
+    transformOrigin?: {
+        x: GiftCoordinate;
+        y: GiftCoordinate;
+    };
+    /**
+     * Static image lifetime in milliseconds. Only used by `image` gifts.
+     * A positive value completes the gift after the duration; omitted / non-positive
+     * values keep the image alive until `destroy()`.
+     */
+    duration?: number;
+    /**
+     * How the RGB region of a split-alpha `vap` / `alphaVideo` source is encoded.
+     *
+     * - `premultiplied` (default): RGB was already multiplied by that mask; the renderer only applies global opacity.
+     * - `straight`: RGB is unassociated; the renderer multiplies it by the separate alpha mask.
+     *
+     * The stage framebuffer always remains premultiplied regardless of this input setting.
+     */
+    videoRGBAlphaMode?: VideoRGBAlphaMode;
+    /** Whether to auto-remove after playback stops. Default: true. */
+    clearsAfterStop?: boolean;
+    mute?: boolean;
+    onComplete?: (gift: GiftHandle) => void;
+}
+export interface GiftHandle {
+    readonly id: string;
+    readonly type: GiftType;
+    pause(): void;
+    resume(): void;
+    destroy(): void;
+    animate(options?: GiftAnimationStep | GiftAnimationStep[]): GiftAnimationChain;
+}
+export type GiftState = 'loading' | 'playing' | 'fly' | 'stopped' | 'finished';
+export interface GiftSlot {
+    id: string;
+    type: GiftType;
+    state: GiftState;
+    options: AddGiftOptions;
+    zIndex?: number;
+    renderOrder?: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scale: number;
+    opacity: number;
+    rotation?: number;
+    paused: boolean;
+    currentFrame: number;
+    accumulatedTime: number;
+    lastTickTime: number;
+    loopCount: number;
+    videoEntity: VideoEntity | null;
+    loadAbortController?: AbortController | null;
+    svgaSlotTextures?: Map<string, ResolvedSVGASlotTexture>;
+    videoElement: HTMLVideoElement | null;
+    releaseMediaSource?: (() => void) | null;
+    releaseSharedSVGAAsset?: (() => void) | null;
+    releaseSharedVideoPlayback?: (() => void) | null;
+    releaseSharedVideoTexture?: (() => void) | null;
+    /** WebCodecs path: decoded frames + clock; mutually exclusive with `videoElement` for playback. */
+    webcodecsPlayback: WebCodecsPlaybackHandle | null;
+    /** Shared WebCodecs group, present only for identical infinite-loop sources acquired together. */
+    webcodecsSharedState?: WebCodecsSharedPlaybackState | null;
+    /** Idempotent release for either a shared or dedicated WebCodecs playback acquisition. */
+    releaseWebCodecsPlayback?: (() => void) | null;
+    /** Playback time in seconds for {@link webcodecsPlayback}. */
+    wcPlaybackTime: number;
+    videoTextureHandle: GPUTextureHandle | null;
+    imageTextureHandle?: GPUTextureHandle | null;
+    releaseSharedImageTexture?: (() => void) | null;
+    /** Shared WebCodecs GPU upload target; owns cross-renderer per-frame upload de-duplication. */
+    webcodecsSurface?: WebCodecsTextureSurface | null;
+    releaseWebCodecsSurface?: (() => void) | null;
+    vapMixState?: VAPMixState | null;
+    /** WebCodecs + atlas: sub-rect in shared atlas (texels). Omit when using a dedicated texture. */
+    wcAtlasRect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** RenderManager internal: cached batch key + its dependencies (avoids per-frame string builds). */
+    batchKeyCache?: {
+        key: string;
+        d0: unknown;
+        d1: unknown;
+        d2: unknown;
+    };
+    /** RenderManager internal: cached svga slot-texture key (recomputed when the map ref/size changes). */
+    svgaSlotTextureKeyCache?: {
+        key: string;
+        map: unknown;
+        size: number;
+    };
+    onComplete?: (gift: GiftHandle) => void;
+}
+export interface VAPConfig {
+    info: {
+        v?: number;
+        f?: number;
+        w: number;
+        h: number;
+        fps: number;
+        videoW: number;
+        videoH: number;
+        rgbFrame: [number, number, number, number];
+        aFrame: [number, number, number, number];
+    };
+    src?: VAPSrcItem[];
+    frame?: VAPFrameItem[];
+}
+export interface VAPSrcItem {
+    srcId: string | number;
+    srcType: 'img' | 'txt';
+    srcTag: string;
+    srcUrl?: string;
+    loadType?: string;
+    w?: number;
+    h?: number;
+    color?: string;
+    style?: string;
+    fitType?: string;
+    fontStyle?: Record<string, string>;
+}
+export interface VAPFrameItem {
+    i: number;
+    obj: VAPFrameObj[];
+}
+export interface VAPFrameObj {
+    srcId: string | number;
+    z?: number;
+    mt?: number;
+    frame: [number, number, number, number];
+    mFrame: [number, number, number, number];
+}
+export interface FlyAnimation {
+    giftId: string;
+    startX: number;
+    startY: number;
+    startScale: number;
+    startOpacity: number;
+    startRotation: number;
+    targetX: number;
+    targetY: number;
+    targetScale: number;
+    targetOpacity: number;
+    targetRotation: number;
+    startTime: number;
+    pausedAt?: number;
+    duration: number;
+    easing: (t: number) => number;
+    onComplete?: () => void;
+    onCancel?: () => void;
+}
+export interface GiftAnimationStep {
+    /** Target center position in CSS pixels. Omit to keep the current visual center. */
+    flyTo?: {
+        x: number;
+        y: number;
+    };
+    /** Target render scale. Omit to keep the current scale. */
+    scaleTo?: number;
+    /** Target opacity. Omit to keep the current opacity. */
+    opacity?: number;
+    /** Target clockwise rotation in radians. Values are interpolated without angle normalization. */
+    rotationTo?: number;
+    /** Duration in milliseconds. Default: 600. */
+    duration?: number;
+    /** Easing function receiving normalized time [0, 1]. Default: easeOutCubic. */
+    easing?: (t: number) => number;
+    onComplete?: (gift: GiftHandle) => void;
+}
+export interface GiftAnimationChain {
+    /** Add a step after the current chain. `to` and `then` are aliases. */
+    to(options: GiftAnimationStep): GiftAnimationChain;
+    /** Add a step after the current chain. `to` and `then` are aliases. */
+    then(options: GiftAnimationStep): GiftAnimationChain;
+    /** Insert a wait step into the chain. */
+    delay(milliseconds: number): GiftAnimationChain;
+    /** Callback fired when the whole chain completes. */
+    onComplete(callback: (gift: GiftHandle) => void): GiftAnimationChain;
+    /**
+     * Play the chain and resolve when all steps complete.
+     * - `immediate`: run now (default).
+     * - `afterGiftComplete`: wait until gift playback completes, then run.
+     */
+    start(mode?: 'immediate' | 'afterGiftComplete'): Promise<GiftHandle>;
+    /** Cancel the active animation for this gift. */
+    cancel(): void;
+}

package/dist/utils/abort.d.ts

@@ -0,0 +1,3 @@
+export declare function createAbortError(message?: string): Error;
+export declare function isAbortError(error: unknown): boolean;
+export declare function throwIfAborted(signal?: AbortSignal, message?: string): void;