@taole/giftstage 0.1.28 → 0.1.30

package/dist/utils/atlas-constants.d.ts

@@ -0,0 +1,9 @@
+/** Normalized atlas sub-rect: min (0,0) + extent (1,1) = full texture. */
+export declare const ATLAS_REMAP_IDENTITY: Float32Array<ArrayBuffer>;
+/** Writes normalized `u_atlasRemap` for a sub-rect in an `tw×th` texture. Reuses `out` when provided. */
+export declare function wcAtlasRemap(tw: number, th: number, rect: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | undefined, out?: Float32Array): Float32Array;

package/dist/utils/buffer-pool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reusable typed-array pool to avoid per-frame allocation.
+ * Grows as needed; never shrinks.
+ * Keeps separate pools for frame data and vertex data to prevent aliasing.
+ */
+export declare class BufferPool {
+    private floatPoolA;
+    private floatPoolB;
+    private uint32Pool;
+    getFloat32(minLength: number): Float32Array;
+    getFloat32B(minLength: number): Float32Array;
+    getUint32(minLength: number): Uint32Array;
+    destroy(): void;
+}

package/dist/utils/canvas-dpr.d.ts

@@ -0,0 +1,37 @@
+export interface MaxRenderSize {
+    width: number;
+    height: number;
+}
+/** Default backing-store cap on phones / tablets. */
+export declare const DEFAULT_MAX_RENDER_SIZE_MOBILE: MaxRenderSize;
+/** Default backing-store cap on desktop / laptop. */
+export declare const DEFAULT_MAX_RENDER_SIZE_DESKTOP: MaxRenderSize;
+/**
+ * @deprecated Prefer {@link resolveDefaultMaxRenderSize}; kept as the mobile default for callers
+ * that still import a single constant.
+ */
+export declare const DEFAULT_MAX_RENDER_SIZE: MaxRenderSize;
+/**
+ * Heuristic: treat classic mobile UA and iPadOS-as-Mac (touch Mac) as mobile.
+ * Used only to pick the default render-size cap; explicit `maxRenderSize` always wins.
+ */
+export declare function isMobileLikeDevice(nav?: Pick<Navigator, 'userAgent' | 'maxTouchPoints'> | null | undefined): boolean;
+/** Platform-aware default: mobile 1920×1080, desktop 2560×1440. */
+export declare function resolveDefaultMaxRenderSize(nav?: Pick<Navigator, 'userAgent' | 'maxTouchPoints'> | null): MaxRenderSize;
+/**
+ * Sync canvas bitmap size to CSS layout × DPR so one buffer pixel maps to one physical pixel.
+ * Uses integer dimensions to avoid inconsistent rounding blur on mobile.
+ *
+ * The backing store is additionally capped by `maxRenderSize` (orientation-adaptive: the
+ * long edge is limited by the larger dimension, the short edge by the smaller one).
+ * When capped, the CSS size stays unchanged and the browser scales the buffer up.
+ * Pass `false` to disable the cap. When omitted, uses {@link resolveDefaultMaxRenderSize}.
+ */
+export declare function syncCanvasBackingStore(canvas: HTMLCanvasElement, dpr: number, maxRenderSize?: MaxRenderSize | false): void;
+/**
+ * `addGift` layout (x, y, width, height) is in CSS pixels; rendering uses the bitmap size.
+ */
+export declare function canvasBufferCssScale(canvas: HTMLCanvasElement): {
+    sx: number;
+    sy: number;
+};

package/dist/utils/clip-mesh.d.ts

@@ -0,0 +1,6 @@
+export interface ClipMeshData {
+    vertices: Float32Array;
+    indices: Uint32Array;
+}
+export type ClipMeshTriangulator = (vertices: Float64Array, polygonStarts: Uint32Array) => Uint32Array | null;
+export declare function buildClipMeshFromPath(clipPath: string, triangulator?: ClipMeshTriangulator): ClipMeshData | null;

package/dist/utils/detect.d.ts

@@ -0,0 +1,7 @@
+export declare function canCopyExternalImageToTexture(): boolean;
+export declare function canWebGPU(): boolean;
+export declare function canWebGL2(): boolean;
+export declare function canWebGL1(): boolean;
+export declare function canSharedArrayBuffer(): boolean;
+export declare function canOffscreenCanvas(): boolean;
+export declare function canVideoFrameCallback(): boolean;

package/dist/utils/easing.d.ts

@@ -0,0 +1,7 @@
+export declare function linear(t: number): number;
+export declare function easeInQuad(t: number): number;
+export declare function easeOutQuad(t: number): number;
+export declare function easeInOutQuad(t: number): number;
+export declare function easeOutCubic(t: number): number;
+export declare function easeInOutCubic(t: number): number;
+export declare function easeOutBack(t: number): number;

package/dist/utils/frame-budget.d.ts

@@ -0,0 +1,36 @@
+export interface MainThreadFrameBudgetOptions {
+    /** Maximum work time before yielding. Defaults to 12ms. */
+    maxBudgetMs?: number;
+    /** Minimum work time before yielding. Defaults to 2ms. */
+    minBudgetMs?: number;
+    /** Fraction of the observed frame interval reserved for this task. Defaults to 0.5. */
+    frameFraction?: number;
+}
+export declare function resolveFrameBudgetMs(frameIntervalMs: number, options?: MainThreadFrameBudgetOptions): number;
+export declare function smoothFrameInterval(previousMs: number, observedMs: number): number;
+export interface SharedFrameBudget {
+    readonly budgetMs: number;
+    shouldYield(): boolean;
+    yield(): Promise<void>;
+}
+/**
+ * Returns a process-shared SVGA load budget. Each caller may provide a more
+ * restrictive cap while still sharing the same observed display-frame slice.
+ */
+export declare function createSharedSVGAFrameBudget(options?: MainThreadFrameBudgetOptions): SharedFrameBudget;
+/**
+ * Time-slices load work against half of the observed display frame interval.
+ * The estimate is updated after every rAF yield, so 120Hz displays receive
+ * shorter slices while slower displays avoid excessive yield overhead.
+ */
+export declare class MainThreadFrameBudget {
+    private frameIntervalMs;
+    private lastFrameAt;
+    private sliceStartedAt;
+    private readonly options;
+    constructor(options?: MainThreadFrameBudgetOptions);
+    get budgetMs(): number;
+    shouldYield(): boolean;
+    resetSlice(): void;
+    yield(): Promise<void>;
+}

package/dist/utils/gift-object-fit.d.ts

@@ -0,0 +1,14 @@
+import type { GiftObjectFit, GiftSlot } from '../types';
+/**
+ * Default when `objectFit` is omitted: all gift types use `contain` (uniform fit inside width×height).
+ */
+export declare function resolveGiftObjectFit(slot: GiftSlot): GiftObjectFit;
+export interface GiftObjectFitLayout {
+    scaleX: number;
+    scaleY: number;
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+}
+export declare function resolveGiftObjectFitLayout(slot: GiftSlot, contentWidth: number, contentHeight: number, out?: GiftObjectFitLayout): GiftObjectFitLayout;

package/dist/utils/gift-position.d.ts

@@ -0,0 +1,5 @@
+export type GiftCoordinate = number | `${number}%`;
+export declare function resolveGiftPosition(x: GiftCoordinate, y: GiftCoordinate, width: number, height: number, containerWidth: number, containerHeight: number): {
+    x: number;
+    y: number;
+};

package/dist/utils/gift-size.d.ts

@@ -0,0 +1,11 @@
+export declare function resolveIntrinsicAlphaVideoSize(videoWidth: number, videoHeight: number): GiftIntrinsicSize;
+export interface GiftIntrinsicSize {
+    width: number;
+    height: number;
+}
+export interface GiftDisplaySizeInput {
+    width?: number;
+    height?: number;
+    useOriginalSize?: boolean;
+}
+export declare function resolveGiftDisplaySize(requested: GiftDisplaySizeInput, intrinsic: GiftIntrinsicSize, stageWidth: number, stageHeight: number): GiftIntrinsicSize;

package/dist/utils/gift-transform.d.ts

@@ -0,0 +1,29 @@
+import type { GiftSlot } from '../types';
+export interface GiftTransformOrigin {
+    x: number;
+    y: number;
+}
+export interface Affine2D {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    tx: number;
+    ty: number;
+}
+/** Resolve the fixed local origin to stage buffer pixels for the slot's current scale. */
+export declare function resolveGiftTransformOrigin(slot: GiftSlot, out?: GiftTransformOrigin): GiftTransformOrigin;
+/**
+ * Build a column-major mat4 mapping a unit quad to the supplied stage-space rectangle,
+ * then rotating it clockwise (in the screen's y-down coordinate system) around the gift origin.
+ */
+export declare function fillGiftTransformMatrix(slot: GiftSlot, x: number, y: number, width: number, height: number, out: Float32Array): Float32Array;
+/** Apply the gift's parent rotation to an existing local-to-stage affine transform. */
+export declare function rotateGiftAffine(slot: GiftSlot, transform: Affine2D, out?: Affine2D): Affine2D;
+/** AABB of a rotated stage-space rectangle, suitable for the backend scissor. */
+export declare function getRotatedRectAABB(slot: GiftSlot, x: number, y: number, width: number, height: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};

package/dist/utils/html-video-upload-gate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Aligns GPU texture uploads with decoded video frames using `HTMLVideoElement.requestVideoFrameCallback`.
+ * Using only `currentTime` / rAF misses real decode timing under load and causes "high FPS counter but choppy video"
+ * when many `<video>` elements run together (especially with WebGPU texture copies).
+ */
+export declare class HtmlVideoUploadGate {
+    private readonly frameInfo;
+    private readonly pending;
+    private readonly lastHandle;
+    private readonly started;
+    private readonly firstUploaded;
+    private readonly forceTimeFallback;
+    private readonly lastArmAt;
+    private readonly lastCallbackAt;
+    private readonly lastProgressAt;
+    private readonly lastRecoveryAt;
+    private readonly stallLogged;
+    private readonly stagnationLogged;
+    /** When `requestVideoFrameCallback` is missing, fall back to `currentTime` changes (coarser than rVFC). */
+    private readonly lastTimeFallback;
+    /**
+     * Returns true when `updateTexture` should run for this slot: first time, or a new decoded frame was signaled.
+     */
+    preUpload(slotId: string, video: HTMLVideoElement): boolean;
+    getFrameInfo(slotId: string): VideoFrameCallbackMetadata | undefined;
+    private ensureRvf;
+    private consumeTimeAdvance;
+    private markProgress;
+    private tryRecoverStalledPlayback;
+    private debugInfo;
+    private debugWarn;
+    private snapshot;
+    release(slotId: string, video: HTMLVideoElement | null | undefined): void;
+    private cleanup;
+}

package/dist/utils/image-source.d.ts

@@ -0,0 +1,9 @@
+export interface DecodedImageSource {
+    source: TexImageSource;
+    width: number;
+    height: number;
+    sourcePremultiplied: boolean;
+    dispose(): void;
+}
+/** Decode a supported image gift source without retaining the encoded bytes. */
+export declare function decodeImageSource(source: string | ArrayBuffer, signal?: AbortSignal): Promise<DecodedImageSource>;

package/dist/utils/math.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates an orthographic projection matrix (column-major Float32Array).
+ * Maps (left..right, bottom..top, near..far) to clip space [-1,1].
+ * Y-down convention: top < bottom maps SVGA viewBox style.
+ */
+export declare function ortho(left: number, right: number, bottom: number, top: number, near: number, far: number): Float32Array;
+export declare function lerp(a: number, b: number, t: number): number;
+export declare function clamp(v: number, min: number, max: number): number;
+export declare function generateId(): string;

package/dist/utils/resource-cache.d.ts

@@ -0,0 +1,20 @@
+import type { SVGAWorkerMoviePayload } from '../parsers/svga-parser-worker-client';
+type PersistKind = 'arrayBuffer' | 'text';
+type MemoryKind = PersistKind | 'json' | 'svga-payload' | 'svga-asset';
+export declare function configureResourceCache(opts?: {
+    maxConcurrent?: number;
+    maxMemoryBytes?: number;
+    maxPersistentBytes?: number;
+}): void;
+export declare function runResourceTaskLimited<T>(task: () => Promise<T>): Promise<T>;
+export declare function fetchCachedArrayBuffer(url: string, signal?: AbortSignal): Promise<ArrayBuffer>;
+export declare function fetchCachedText(url: string, signal?: AbortSignal): Promise<string>;
+export declare function fetchCachedJSON<T>(url: string, signal?: AbortSignal): Promise<T>;
+export declare function getCachedSVGAWorkerPayload(cacheKey: string): SVGAWorkerMoviePayload | null;
+export declare function setCachedSVGAWorkerPayload(cacheKey: string, payload: SVGAWorkerMoviePayload): void;
+export declare function getCachedMemoryValue<T>(cacheKey: string, kind: MemoryKind): T | null;
+export declare function setCachedMemoryValue<T>(cacheKey: string, kind: MemoryKind, value: T, size: number): void;
+export declare function getPersistedArrayBuffer(cacheKey: string): Promise<ArrayBuffer | null>;
+export declare function setPersistedArrayBuffer(cacheKey: string, value: ArrayBuffer): Promise<void>;
+export declare function deletePersistedValue(cacheKey: string): Promise<void>;
+export {};

package/dist/utils/slot-content.d.ts

@@ -0,0 +1,17 @@
+import type { GPUBackend, ResolvedSVGASlotTexture, ResolvedVAPResource, SVGASlotContent, VAPConfig, VAPFrameObj, VAPMixState, VAPSlotContent, VAPSrcItem, VideoEntity } from '../types';
+export declare function resolveSVGASlotTextures(backend: GPUBackend, entity: VideoEntity, slots: Record<string, SVGASlotContent> | undefined, options?: {
+    frameBudgetMs?: number;
+    checkActive?: () => void;
+}): Promise<Map<string, ResolvedSVGASlotTexture>>;
+export declare function getVAPSlotOverride(item: VAPSrcItem, slots: Record<string, VAPSlotContent> | undefined): VAPSlotContent | undefined;
+export declare function resolveVAPResources(config: VAPConfig, slots: Record<string, VAPSlotContent> | undefined): Promise<Map<string, ResolvedVAPResource>>;
+export declare function buildVAPFrameMap(config: VAPConfig): Map<number, VAPFrameObj[]>;
+export declare function createVAPMixCanvasState(width: number, height: number): {
+    compositeCanvas: HTMLCanvasElement;
+    compositeCtx: CanvasRenderingContext2D;
+    rawCanvas: HTMLCanvasElement;
+    rawCtx: CanvasRenderingContext2D;
+    scratchCanvas: HTMLCanvasElement;
+    scratchCtx: CanvasRenderingContext2D;
+};
+export declare function compositeVAPFrame(state: VAPMixState, config: VAPConfig, source: CanvasImageSource, frameIndex: number, rgbPremultiplied?: boolean): HTMLCanvasElement;

package/dist/utils/svg-path-parser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal SVG path parser for SVGA clipPath strings.
+ * Converts an SVG path `d` attribute into an array of 2D polygon points
+ * by flattening curves into line segments.
+ */
+interface Point {
+    x: number;
+    y: number;
+}
+export declare function parseSvgPath(d: string): Point[][];
+export {};

package/dist/utils/svga-binary-cache.d.ts

@@ -0,0 +1,26 @@
+import type { SVGAParams, SVGAAudio, SVGASpriteTable, UVRect } from '../types';
+import type { ClipMeshData } from './clip-mesh';
+export interface SVGACachedAsset {
+    params: SVGAParams;
+    spriteTable: SVGASpriteTable;
+    audios: SVGAAudio[];
+    audioBlobs: Map<string, ArrayBuffer>;
+    atlasRects: Map<string, UVRect>;
+    atlasPages: SVGACachedAtlasPage[];
+    clipMeshes?: Map<string, ClipMeshData>;
+}
+export interface SVGACachedAtlasPage {
+    width: number;
+    height: number;
+    imageBytes: ArrayBuffer;
+}
+export declare function serializeSVGACachedAsset(asset: SVGACachedAsset): ArrayBuffer;
+export declare function serializeSVGACachedAssetCooperative(asset: SVGACachedAsset, frameBudgetMs?: number): Promise<ArrayBuffer>;
+export declare function deserializeSVGACachedAsset(buffer: ArrayBuffer): SVGACachedAsset;
+export declare function deserializeSVGACachedAssetCooperative(buffer: ArrayBuffer, frameBudgetMs?: number): Promise<SVGACachedAsset>;
+export declare function loadSVGACachedAsset(sourceUrl: string, options?: {
+    frameBudgetMs?: number;
+}): Promise<SVGACachedAsset | null>;
+export declare function storeSVGACachedAsset(sourceUrl: string, asset: SVGACachedAsset, options?: {
+    frameBudgetMs?: number;
+}): Promise<void>;

package/dist/utils/svga-work-scheduler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SVGA parser, image decode, atlas and clip workers share this gate so they
+ * do not create a multi-core CPU burst while real-time media is active.
+ */
+export declare function configureSVGAWorkerTaskConcurrency(maxConcurrent?: number): void;
+export declare function runSVGAWorkerTask<T>(task: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function acquireSVGAWorkerTask(signal?: AbortSignal): Promise<() => void>;

package/dist/utils/triangulate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ear-clipping polygon triangulation.
+ * Input: array of 2D polygon vertices (CCW or CW winding).
+ * Output: array of triangle index triples.
+ */
+interface Vec2 {
+    x: number;
+    y: number;
+}
+export declare function triangulate(polygon: Vec2[]): number[];
+export {};

package/dist/utils/utf8.d.ts

@@ -0,0 +1,2 @@
+export declare function encodeUTF8(value: string): Uint8Array;
+export declare function decodeUTF8(input: Uint8Array | ArrayBuffer): string;

package/dist/utils/vap-mix-composer.d.ts

@@ -0,0 +1,26 @@
+import type { ResolvedVAPResource, VAPConfig, VAPFrameObj } from '../types';
+export declare function buildVAPMixShaderSources(textureCount: number, positionSlotCount: number, webgl2: boolean): {
+    vertex: string;
+    fragment: string;
+};
+export declare function buildVAPMixImagePositions(config: VAPConfig, frameMap: Map<number, VAPFrameObj[]>, textureUnitBySrcId: Map<string, number>, frameIndex: number, out?: Float32Array): Float32Array;
+export declare class VAPMixComposer {
+    private readonly config;
+    private readonly frameMap;
+    readonly canvas: HTMLCanvasElement;
+    private readonly gl;
+    private readonly program;
+    private readonly vertexShader;
+    private readonly fragmentShader;
+    private readonly vertexBuffer;
+    private readonly videoTexture;
+    private readonly imagePosLoc;
+    private readonly imagePositionsScratch;
+    private readonly resourceEntries;
+    private readonly textureUnitBySrcId;
+    private videoTextureWidth;
+    private videoTextureHeight;
+    constructor(config: VAPConfig, frameMap: Map<number, VAPFrameObj[]>, resources: Map<string, ResolvedVAPResource>, width: number, height: number, rgbPremultiplied?: boolean);
+    render(source: TexImageSource, frameIndex: number): HTMLCanvasElement;
+    destroy(): void;
+}

package/dist/utils/wc-atlas-upload-size.d.ts

@@ -0,0 +1,9 @@
+import type { GiftSlot, VAPConfig } from '../types';
+/**
+ * Atlas texel size for a WebCodecs frame: uniform downscale so the full frame matches
+ * on-screen footprint (same scale factor as gift renderers use for layout).
+ */
+export declare function wcAtlasUploadTexelSize(slot: GiftSlot, frameW: number, frameH: number, kind: 'alphaVideo' | 'vap', vapConfig: VAPConfig | undefined): {
+    w: number;
+    h: number;
+};

package/dist/video/mp4box-loader.d.ts

@@ -0,0 +1,2 @@
+export type MP4BoxModule = typeof import('mp4box');
+export declare function loadMp4Box(): Promise<MP4BoxModule>;

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

@@ -0,0 +1,49 @@
+/**
+ * Shared mp4box demux + WebCodecs H.264 decode (used on main thread fallback or inside Worker).
+ */
+import type { DataStream, Sample } from 'mp4box';
+/** Avoid decoding huge clips entirely into VideoFrame[] (memory). */
+export declare const MAX_WEBCODECS_FRAMES = 800;
+export declare function isH264Codec(codec: string): boolean;
+export declare function stripAvccBoxWrapperIfPresent(recordOrBox: ArrayBuffer): ArrayBuffer;
+export declare function avcDescriptionFromSampleEntry(entry: {
+    avcC?: {
+        write: (s: DataStream) => void;
+    };
+}): Promise<ArrayBuffer | undefined>;
+export type MP4BoxBuffer = ArrayBuffer & {
+    fileStart: number;
+};
+export declare function collectMp4Samples(ab: ArrayBuffer): Promise<{
+    codec: string;
+    timescale: number;
+    durationSec: number;
+    videoWidth: number;
+    videoHeight: number;
+    samples: Sample[];
+}>;
+export declare function waitDecodeQueueDrained(decoder: VideoDecoder, label: string, maxWaitMs: number): Promise<void>;
+export declare function flushDecoderOrThrow(decoder: VideoDecoder, meta: {
+    chunksDecoded: number;
+    outputsBeforeFlush: number;
+    queueBeforeFlush: number;
+}): Promise<void>;
+export declare function decodeH264ToFrames(codec: string, description: ArrayBuffer | undefined, samples: Sample[], timescale: number): Promise<{
+    frames: VideoFrame[];
+    timesSec: Float64Array;
+}>;
+export declare function frameIndexForTime(timesSec: Float64Array, clipDurationSec: number, t: number): number;
+export declare function computeClipDurationSeconds(metaDurationSec: number, timesSec: Float64Array, frames: VideoFrame[]): number;
+/** Clip duration from demux metadata + presentation timeline only (no decoded frames). */
+export declare function computeClipDurationSecondsFromTimes(metaDurationSec: number, timesSec: Float64Array): number;
+/**
+ * Presentation order timestamps (sorted by CTS/DTS), one entry per sample — matches decoder output order after sort-by-timestamp.
+ */
+export declare function buildPresentationTimesSec(samples: Sample[], timescale: number): Float64Array;
+/** Decode order: DTS (then stable index). */
+export declare function sortSamplesDecodeOrder(samples: Sample[]): Sample[];
+/** Map decoder output timestamp (µs) to presentation index using precomputed timeline. */
+export declare function presentationIndexFromTimestampUs(presentationTimesSec: Float64Array, timestampUs: number): number;
+export declare function findFirstSyncChunkIndexInDecodeOrder(decodeOrder: Sample[]): number;
+/** Shared config resolution for H.264 WebCodecs (same logic as {@link decodeH264ToFrames}). */
+export declare function resolveH264DecoderConfig(codec: string, description: ArrayBuffer | undefined): Promise<VideoDecoderConfig>;

package/dist/video/webcodecs-mp4-playback.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Presentation-index → VideoFrame with bounded size.
+ * Eviction follows the playhead (see {@link setPlaybackHint}) so we keep a window around the
+ * current time — pure "evict global min" would leave only the last N decoded frames after a fast
+ * full decode, making middle-of-timeline playback return null.
+ */
+export declare class VideoFrameRing {
+    private readonly maxSize;
+    private readonly map;
+    /** Last known presentation index from the clock (updated from ensure / getFrameForTime). */
+    private playbackHint;
+    constructor(maxSize: number);
+    setPlaybackHint(idx: number): void;
+    minKey(): number | undefined;
+    set(idx: number, frame: VideoFrame): void;
+    private evictDownToCapacity;
+    private closeKey;
+    bestAtOrBefore(idx: number): VideoFrame | null;
+    /**
+     * Prefer latest frame at or before `idx`; if none (decode lag / gap), use nearest at or after;
+     * if still only lower indices exist, use the highest held (best effort).
+     */
+    frameForDisplay(idx: number): VideoFrame | null;
+    clear(): void;
+    get size(): number;
+}
+export interface WebCodecsMp4CreateOptions {
+    /**
+     * When true (default), demux+decode run in a Dedicated Worker and VideoFrames are transferred to the main thread.
+     * Set false to force main-thread decode (tests, environments without Workers).
+     */
+    useWorker?: boolean;
+    /**
+     * Max presentation frames retained on the main thread (ring). Older indices are closed when exceeded.
+     * Default {@link DEFAULT_MAX_DECODED_FRAMES}.
+     */
+    maxDecodedFrames?: number;
+    /**
+     * How many frames ahead of the playhead the worker tries to decode after demux / on each ensure.
+     * Default {@link DEFAULT_DECODE_AHEAD_FRAMES}.
+     */
+    decodeAheadFrames?: number;
+}
+export declare class WebCodecsMp4Playback {
+    readonly duration: number;
+    readonly videoWidth: number;
+    readonly videoHeight: number;
+    private readonly timesSec;
+    private readonly worker;
+    private readonly workerMsgId;
+    private readonly streaming;
+    private readonly ring;
+    private readonly frames;
+    private readonly maxDecodedFrames;
+    private readonly decodeAheadFrames;
+    private lastWrapped;
+    private lastEnsureNeedIdx;
+    private lastEnsureFreeSlots;
+    private destroyed;
+    private constructor();
+    /**
+     * Fetch MP4 (if URL) → demux + H.264 decode in Worker (default) or main thread.
+     * Call {@link destroy} when done.
+     */
+    static create(source: string | ArrayBuffer, signal?: AbortSignal, opts?: WebCodecsMp4CreateOptions): Promise<WebCodecsMp4Playback>;
+    private static createViaWorker;
+    private static createOnMainThread;
+    ensureDecodedThrough(tSec: number): void;
+    getFrameForTime(tSec: number): VideoFrame | null;
+    destroy(): void;
+}

package/dist/video/webcodecs-mp4.worker.d.ts

@@ -0,0 +1,18 @@
+export type MainToWorker = {
+    type: 'init';
+    id: number;
+    buffer: ArrayBuffer;
+    maxDecodedFrames: number;
+    decodeAheadFrames: number;
+} | {
+    type: 'ensure';
+    id: number;
+    needIdx: number;
+    freeSlots: number;
+} | {
+    type: 'rewind';
+    id: number;
+} | {
+    type: 'destroy';
+    id: number;
+};

package/dist/wasm/wasm-bridge.d.ts

@@ -0,0 +1,36 @@
+import type { SVGAMovieEntity } from '../types';
+export interface WasmSVGAPayloadProfile {
+    inputBytes: number;
+    outputBytes: number;
+    prostDecodeMs: number;
+    metadataAndImagesMs: number;
+    frameTableMs: number;
+    finalizeMs: number;
+    payloadBuildMs: number;
+    rustTotalMs: number;
+    wasmBoundaryAndGlueMs: number;
+    jsCallTotalMs: number;
+    imageBytes: number;
+    imageCount: number;
+    spriteCount: number;
+    frameCount: number;
+    cellCount: number;
+    clipPathCount: number;
+    shapeCount: number;
+    shapeGroupCount: number;
+    shapeBytes: number;
+    writerInitialCapacity: number;
+    writerFinalCapacity: number;
+}
+export interface WasmSVGAPayloadDecodeResult {
+    payload: Uint8Array;
+    profile?: WasmSVGAPayloadProfile;
+}
+export declare function isWasmReady(): boolean;
+export declare function initWasm(): Promise<boolean>;
+export declare function wasmInflate(data: Uint8Array): Uint8Array | null;
+export declare function wasmDecodeSVGA(data: Uint8Array): SVGAMovieEntity | null;
+export declare function wasmDecodeSVGAPayload(data: Uint8Array): Uint8Array | null;
+export declare function wasmDecodeSVGAPayloadProfiled(data: Uint8Array): WasmSVGAPayloadDecodeResult | null;
+export declare function wasmBuildBatchVertices(frames: Float32Array, outVertices: Float32Array, outIndices: Uint32Array): number | null;
+export declare function wasmTriangulateClipPolygons(vertices: Float64Array, polygonStarts: Uint32Array): Uint32Array | null;

package/dist/workers/parser-worker.d.ts

@@ -0,0 +1,13 @@
+export interface ParserWorkerRequest {
+    type: 'parse-svga';
+    id: number;
+    data: ArrayBuffer;
+    profile?: boolean;
+    workerTimeSliceMs?: number;
+}
+export interface ParserWorkerResponse {
+    type: 'parse-svga-result';
+    id: number;
+    result?: unknown;
+    error?: string;
+}

package/dist/workers/svga-atlas-worker-client.d.ts

@@ -0,0 +1,25 @@
+import type { SVGAAtlasWorkerPageResult, SVGAAtlasWorkerRect } from './svga-atlas-worker';
+export interface SVGAAtlasWorkerBuildOptions {
+    maxSize: number;
+    padding: number;
+    maxPages: number;
+    captureEncodedPng: boolean;
+    workerTimeSliceMs?: number;
+    signal?: AbortSignal;
+}
+export interface SVGAAtlasWorkerBuildResult {
+    pages: Array<SVGAAtlasWorkerPageResult & {
+        pngBytesPromise?: Promise<ArrayBuffer | null>;
+    }>;
+    rects: SVGAAtlasWorkerRect[];
+}
+/** The worker has consumed the transferred ImageBitmaps, so callers must rebuild the image set. */
+export declare class SVGAAtlasWorkerBuildError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function canUseSVGAAtlasWorker(): boolean;
+/**
+ * Transfer ImageBitmaps to the atlas worker (consumes / closes them on success or failure).
+ * Caller must not use the bitmaps after calling.
+ */
+export declare function buildSVGAAtlasInWorker(images: Map<string, ImageBitmap>, options: SVGAAtlasWorkerBuildOptions): Promise<SVGAAtlasWorkerBuildResult>;

package/dist/workers/svga-atlas-worker.d.ts

@@ -0,0 +1,37 @@
+export interface SVGAAtlasWorkerRequest {
+    type: 'build-svga-atlas';
+    id: number;
+    keys: string[];
+    bitmaps: ImageBitmap[];
+    maxSize: number;
+    padding: number;
+    maxPages: number;
+    captureEncodedPng: boolean;
+    workerTimeSliceMs?: number;
+}
+export interface SVGAAtlasWorkerPageResult {
+    width: number;
+    height: number;
+    bitmap: ImageBitmap;
+}
+export interface SVGAAtlasWorkerRect {
+    key: string;
+    textureIndex: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface SVGAAtlasWorkerResponse {
+    type: 'build-svga-atlas-result';
+    id: number;
+    pages?: SVGAAtlasWorkerPageResult[];
+    rects?: SVGAAtlasWorkerRect[];
+    error?: string;
+}
+export interface SVGAAtlasWorkerPngResponse {
+    type: 'build-svga-atlas-png-result';
+    id: number;
+    pageIndex: number;
+    pngBytes: ArrayBuffer | null;
+}