@taole/giftstage 0.3.4 → 0.3.6

package/dist/index.d.ts

@@ -34,3 +34,4 @@ export { WebCodecsMp4Playback } from './video/webcodecs-mp4-playback.js';
 export type { WebCodecsMp4CreateOptions } from './video/webcodecs-mp4-playback.js';
 export type { WebCodecsPlaybackHandle, GPUBackend, BackendOperationFailureReason, BackendOperationResult, GPUBufferHandle, GPUTextureHandle, TextureOpts, BufferUsage, DrawCommand, ShaderType, BackendType, ParentMotionMode, SVGADrawBatchMode, SVGAFrameEvaluation, SVGAFrameEvaluationStrategy, SVGAFrameTableBinding, SVGAFrameTableBindingBase, SVGAFrameTableCreateOptions, SVGAFrameTableState, SVGAFrameTimelineFallbackReason, SVGAFrameTimelinePath, SVGAFrameTimelineRenderInfo, SVGAFrameTimelineStrategy, SVGAFrameTimelineTransport, SVGARenderFallbackReason, SVGARenderInfo, SVGARenderPath, SVGARenderPathState, SVGARenderPathChangeInfo, GiftStageRuntimeDiagnosticType, GiftStageRuntimeDiagnosticEvent, GiftStageRuntimeDiagnostics, SVGAHybridCommandTable, SVGAHybridOperation, SVGAHybridOperationType, SVGATimelineDrawRun, WebGL2FrameTableBinding, WebGPUFrameTableBinding, GiftStageOptions, AddGiftOptions, GiftHandle, GiftSlot, GiftType, GiftObjectFit, GiftCoordinate, GiftState, GiftAnimationStep, GiftAnimationChain, SVGAMovieEntity, SVGAParams, SVGASpriteTable, SVGAAudio, SVGATransform, SVGAShape, VideoEntity, UVRect, FrameJobData, FlyAnimation, VAPConfig, VAPSrcItem, VAPFrameItem, VAPFrameObj, } from './types/index.js';
 export type { GiftAssetLease, GiftAssetMetadata, GiftStageCapabilities, SVGAFrameTimelineCapabilities, GiftStagePlugin, GiftStagePluginHost, MountedGiftStagePlugin, MotionBindingOptions, MotionTrackDescriptor, MotionTrackLease, BallisticV1ParticleBatchDescriptor, ParticleAtlasDescriptor, ParticleAtlasHandle, ParticleBatchDescriptor, ParticleBatchEnvelope, ParticleBatchGroupHandle, ParticleBatchHandle, ParticleEnvelopeSegment, SpriteV2ParticleBatchDescriptor, PlaybackFrame, PlaybackScope, PlaybackScopeStartOptions, PlaybackScopeState, ReadonlyTableDescriptor, ReadonlyTableLease, } from './plugin/types.js';
+export type { SVGAPreparationProfile, SVGAPreparationPhase, SVGAPreparationStageProfile } from './types/index.js';

package/dist/renderers/svga-batch-renderer.d.ts

@@ -1,3 +1,5 @@
+import { SVGAClipAnalysisCache } from '../utils/svga-clip-analysis.js';
+import { type SVGAPreparationRecorder } from '../utils/svga-preparation-profile.js';
 import type { GPUBackend, GPUBufferHandle, GiftSlot, VideoEntity } from '../types/index.js';
 /** Signals RenderManager to discard and replay the complete frame after a resource fallback. */
 export declare class SVGAFastPathFrameReplayError extends Error {
@@ -32,6 +34,7 @@ export interface ClipMeshCache {
     indexBuf?: GPUBufferHandle | null;
 }
 interface SVGAClipPrewarmOptions {
+    profile?: SVGAPreparationRecorder;
     frameBudgetMs?: number;
     workerTimeSliceMs?: number;
     checkActive?: () => void;
@@ -78,9 +81,13 @@ export declare class SVGABatchRenderer {
     /** Shared producers outlive individual addGift/preload subscribers. */
     private clipMeshProducerController;
     private clipMeshProducerTasks;
+    private clipResourceProducers;
+    private clipPreparationOwners;
+    private liveClipPreparationControllers;
+    private clipTableOwnerCounts;
     private destroyed;
     private clipMeshDestroyed;
-    private clipGeometryKindCache;
+    readonly clipAnalysis: SVGAClipAnalysisCache;
     /** Meshes with lazily created GPU buffers (released in destroy). */
     private clipMeshesWithBuffers;
     private clipMeshRefCounts;
@@ -249,6 +256,8 @@ export declare class SVGABatchRenderer {
     private getFrameClipMode;
     prewarmClipMeshes(entity: Pick<VideoEntity, 'spriteTable'>, options?: SVGAClipPrewarmOptions): Promise<number>;
     prewarmClipMeshesForFrame(entity: Pick<VideoEntity, 'spriteTable'>, frame: number, options?: SVGAClipPrewarmOptions): Promise<number>;
+    private retainClipPreparation;
+    private prewarmEntityClipMeshes;
     /**
      * Precompiles every immutable Shape group and uploads its static mesh once.
      * Hybrid table promotion waits for this preparation so the first promoted
@@ -258,7 +267,8 @@ export declare class SVGABatchRenderer {
     /** Validates every immutable Hybrid mesh reference and retains its GPU buffers for this entity. */
     retainHybridMeshes(backend: GPUBackend, entity: VideoEntity): void;
     releaseHybridMeshes(backend: GPUBackend, entity: VideoEntity): void;
-    private collectFrameClipPaths;
+    releaseClipPreparation(entity: Pick<VideoEntity, 'spriteTable'>): void;
+    private collectClipPathsSteps;
     /**
      * Ensures shared producers exist, then waits as the current subscriber. A subscriber signal
      * never owns or cancels shared mesh production; it only detaches this caller's waiter.
@@ -284,6 +294,7 @@ export declare class SVGABatchRenderer {
     private queueClipMeshBuild;
     private scheduleClipMeshBuildFlush;
     private flushPendingClipMeshBuilds;
+    hydrateClipMeshesCooperative(meshes: SVGAClipMeshMap | null | undefined, options?: SVGAClipPrewarmOptions): Promise<void>;
     hydrateClipMeshes(meshes: SVGAClipMeshMap | null | undefined): void;
     snapshotClipMeshes(entity: Pick<VideoEntity, 'spriteTable'>): SVGAClipMeshMap;
     private canUseTimelinePath;

package/dist/types/index.d.ts

@@ -812,6 +812,10 @@ export interface GiftStageOptions {
      * Default: true.
      */
     svgaClipPrewarmInWorker?: boolean;
+    /** Build immutable GPU command/frame tables in a Worker. Defaults to true. */
+    svgaCommandTableInWorker?: boolean;
+    /** Optional per-resource preparation summary. Detailed sampling is disabled when absent. */
+    onSVGAPreparationProfile?: (profile: SVGAPreparationProfile) => void;
     /** Called when a gift's selected SVGA rendering path changes. */
     onSVGARenderPathChange?: (info: SVGARenderPathChangeInfo) => void;
     /** Receives production runtime diagnostics. GiftStage does not upload these events. */
@@ -1154,3 +1158,23 @@ export interface GiftAnimationChain {
     /** Cancel the active animation for this gift. */
     cancel(): void;
 }
+export type SVGAPreparationPhase = 'clip-prepare' | 'worker-queue' | 'input-copy' | 'command-build' | 'frame-pack' | 'validation' | 'gpu-submit';
+export interface SVGAPreparationStageProfile {
+    /** Combined CPU execution across threads; excludes waits. */
+    executionMs: number;
+    mainThreadExecutionMs: number;
+    workerExecutionMs: number;
+    elapsedMs: number;
+    maxSliceMs: number;
+    slices: number;
+    cacheHits: number;
+    bytes: number;
+}
+export interface SVGAPreparationProfile {
+    resourceId: number;
+    executor: 'worker' | 'main-thread';
+    fallbackReason?: string;
+    status: 'complete' | 'canceled' | 'failed';
+    elapsedMs: number;
+    phases: Partial<Record<SVGAPreparationPhase, SVGAPreparationStageProfile>>;
+}

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

@@ -3,8 +3,8 @@ export interface ClipMeshData {
     vertices: Float32Array;
     indices: Uint32Array;
 }
-/** Returns a stable validation failure, or null for a renderable triangle mesh. */
 export declare function validateClipMeshData(mesh: ClipMeshData): string | null;
+export declare function validateClipMeshDataSteps(mesh: ClipMeshData): Generator<void, string | null>;
 export type ClipMeshTriangulator = (vertices: Float64Array, polygonStarts: Uint32Array) => Uint32Array | null;
 export type ClipPathGeometryKind = 'empty' | 'fillable' | 'invalid';
 /**
@@ -22,3 +22,4 @@ export declare function classifyParsedClipPathGeometry(subPaths: ReturnType<type
 /** Checkpoints also bound work for a single large, collinear contour. */
 export declare function classifyParsedClipPathGeometrySteps(subPaths: ReturnType<typeof parseSvgPath>): Generator<void, ClipPathGeometryKind>;
 export declare function buildClipMeshFromPath(clipPath: string, triangulator?: ClipMeshTriangulator): ClipMeshData | null;
+export declare function buildClipMeshFromParsedPath(subPaths: ReturnType<typeof parseSvgPath>, triangulator?: ClipMeshTriangulator): ClipMeshData | null;

package/dist/utils/svga-clip-analysis.d.ts

@@ -0,0 +1,36 @@
+import type { VideoEntity } from '../types/index.js';
+import { type ClipPathGeometryKind } from './clip-mesh.js';
+import { type parseSvgPath } from './svg-path-parser.js';
+export interface ClipAnalysis {
+    kind: ClipPathGeometryKind;
+    localRect: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    } | null;
+}
+export declare function detectAxisAlignedClipRect(paths: ReturnType<typeof parseSvgPath>): {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+} | null;
+export declare function analyzeParsedClipSteps(points: ReturnType<typeof parseSvgPath>, blank?: boolean): Generator<void, ClipAnalysis>;
+/** One Stage owns this small cache. Meshes and flattened points are not retained here. */
+export declare class SVGAClipAnalysisCache {
+    private paths;
+    private tables;
+    private resourcePaths;
+    private pathUsers;
+    hits: number;
+    trackHits: boolean;
+    retain(table: VideoEntity['spriteTable'], path: string): void;
+    release(table: VideoEntity['spriteTable']): string[];
+    get(path: string): ClipAnalysis | undefined;
+    set(path: string, value: ClipAnalysis): void;
+    getByIndex(table: VideoEntity['spriteTable'], index: number): ClipAnalysis | undefined;
+    analyze(table: VideoEntity['spriteTable'], index: number): Generator<void, ClipAnalysis>;
+    clear(): void;
+}
+export declare function getStandaloneClipAnalysis(table: VideoEntity['spriteTable']): SVGAClipAnalysisCache;

package/dist/utils/svga-command-preparation.d.ts

@@ -0,0 +1,13 @@
+import type { VideoEntity } from '../types/index.js';
+import { type SVGAHybridCommandTableBuildOptions } from './svga-hybrid-command-table.js';
+import { type SVGACommandInput } from './svga-hybrid-command-data.js';
+import type { SVGACommandResult } from '../workers/svga-command-worker.js';
+export interface SVGACommandPreparationOptions extends SVGAHybridCommandTableBuildOptions {
+    useWorker?: boolean;
+    workerTimeSliceMs?: number;
+    signal?: AbortSignal;
+}
+/** Transfer only dedicated copies, in at most 64 KiB copy operations. */
+export declare function copySVGACommandInputSteps(input: SVGACommandInput): Generator<void, SVGACommandInput>;
+export declare function validateSVGACommandResultSteps(result: SVGACommandResult, input: SVGACommandInput, hybrid: boolean): Generator<void, void>;
+export declare function prepareSVGACommandTables(entity: VideoEntity, hybrid: boolean, options?: SVGACommandPreparationOptions): Promise<SVGACommandResult>;

package/dist/utils/svga-hybrid-command-data.d.ts

@@ -0,0 +1,18 @@
+import type { SVGAHybridCommandTable } from '../types/index.js';
+/** Dedicated numeric snapshot; no paths, entity references or GPU handles. */
+export interface SVGACommandInput {
+    frameCount: number;
+    spriteCount: number;
+    frameData: Float32Array;
+    shapesIndex: Int32Array;
+    clipPathIndex: Int32Array;
+    shapePresence: Uint8Array;
+    clipKinds: Uint8Array;
+    clipRects: Float64Array;
+    atlas: Float64Array;
+}
+/** FNV-1a over canonical numeric bytes; -0 and 0 have the same identity. */
+export declare function hashScheduleNumber(hash: number, value: number): number;
+/** All executors drain this same generator. Hashes only select exact-comparison buckets. */
+export declare function buildSVGACommandDataSteps(input: SVGACommandInput, hashNumber?: typeof hashScheduleNumber): Generator<void, SVGAHybridCommandTable>;
+export declare function packSVGAFrameDataSteps(data: Float32Array): Generator<void, Float32Array>;

package/dist/utils/svga-hybrid-command-table.d.ts

@@ -1,16 +1,16 @@
 import type { SVGAHybridCommandTable, VideoEntity } from '../types/index.js';
+import { type SVGAClipAnalysisCache } from './svga-clip-analysis.js';
+import { type SVGACommandInput } from './svga-hybrid-command-data.js';
+import { type PreparationStepOptions } from './svga-preparation-profile.js';
 export declare const SVGA_HYBRID_OP_TEXTURE = 0;
 export declare const SVGA_HYBRID_OP_SHAPE = 1;
 export declare const SVGA_HYBRID_OP_CLIP_WRITE = 2;
 export declare const SVGA_HYBRID_OP_CLIP_TEST = 3;
 export declare const SVGA_HYBRID_OP_CLIP_CLEAR = 4;
-export interface SVGAHybridCommandTableBuildOptions {
-    /** Shares the same main-thread budget as SVGA parsing, atlas and slot work. */
-    frameBudgetMs?: number;
-    /** Throw when the owning resource has been released or its backend is lost. */
-    checkActive?: () => void;
+export interface SVGAHybridCommandTableBuildOptions extends PreparationStepOptions {
+    clipAnalysis?: SVGAClipAnalysisCache;
 }
-/** Compatibility entry point for offline/synchronous callers. Playback uses the cooperative builder. */
+/** Input references remain on the main thread until explicitly copied for a Worker. */
+export declare function prepareSVGACommandInputSteps(entity: VideoEntity, options?: SVGAHybridCommandTableBuildOptions): Generator<void, SVGACommandInput>;
 export declare function buildSVGAHybridCommandTable(entity: VideoEntity): SVGAHybridCommandTable;
-/** Only returns a complete immutable table; partially built state never reaches the renderer. */
 export declare function buildSVGAHybridCommandTableCooperative(entity: VideoEntity, options?: SVGAHybridCommandTableBuildOptions): Promise<SVGAHybridCommandTable>;

package/dist/utils/svga-preparation-profile.d.ts

@@ -0,0 +1,21 @@
+import type { SVGAPreparationPhase, SVGAPreparationProfile, SVGAPreparationStageProfile } from '../types/index.js';
+export declare class SVGAPreparationRecorder {
+    readonly resourceId: number;
+    readonly started: number;
+    readonly phases: Partial<Record<SVGAPreparationPhase, SVGAPreparationStageProfile>>;
+    executor: SVGAPreparationProfile['executor'];
+    fallbackReason?: string;
+    constructor(resourceId: number);
+    phase(name: SVGAPreparationPhase): SVGAPreparationStageProfile;
+    record(name: SVGAPreparationPhase, duration: number, thread?: 'main' | 'worker'): void;
+    measure<T>(name: SVGAPreparationPhase, action: () => T): T;
+    finish(status: SVGAPreparationProfile['status']): SVGAPreparationProfile;
+}
+export interface PreparationStepOptions {
+    signal?: AbortSignal;
+    frameBudgetMs?: number;
+    checkActive?: () => void;
+    profile?: SVGAPreparationRecorder;
+}
+/** Record only execution slices, excluding rAF waits and competing tasks. */
+export declare function runPreparationSteps<T>(steps: Generator<void, T>, options?: PreparationStepOptions, phase?: SVGAPreparationPhase): Promise<T>;

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

@@ -1,7 +1,8 @@
+export type SVGAWorkerTaskPriority = 'foreground' | 'background';
 /**
  * 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>;
+export declare function runSVGAWorkerTask<T>(task: () => Promise<T>, signal?: AbortSignal, priority?: SVGAWorkerTaskPriority): Promise<T>;
+export declare function acquireSVGAWorkerTask(signal?: AbortSignal, priority?: SVGAWorkerTaskPriority): Promise<() => void>;

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

@@ -1,6 +1,11 @@
+import { type SVGAPreparationRecorder } from '../utils/svga-preparation-profile.js';
+import type { ClipAnalysis } from '../utils/svga-clip-analysis.js';
 import { type ClipMeshData } from '../utils/clip-mesh.js';
 export declare function canUseSVGAClipWorker(): boolean;
 export declare function requestSVGAClipMeshesInWorker(paths: string[], options?: {
+    profile?: SVGAPreparationRecorder;
     workerTimeSliceMs?: number;
     signal?: AbortSignal;
+    frameBudgetMs?: number;
+    onAnalysis?: (path: string, analysis: ClipAnalysis) => void;
 }): Promise<Map<string, ClipMeshData | null>>;

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

@@ -1,11 +1,14 @@
+import { type ClipAnalysis } from '../utils/svga-clip-analysis.js';
 export interface SVGAClipWorkerRequest {
     type: 'build-svga-clip-meshes';
     id: number;
     paths: string[];
     workerTimeSliceMs?: number;
+    profile?: boolean;
 }
 export interface SVGAClipWorkerEntry {
     path: string;
+    analysis: ClipAnalysis;
     vertices: Float32Array | null;
     indices: Uint32Array | null;
 }
@@ -14,4 +17,10 @@ export interface SVGAClipWorkerResponse {
     id: number;
     entries?: SVGAClipWorkerEntry[];
     error?: string;
+    profile?: {
+        executionMs: number;
+        elapsedMs: number;
+        maxSliceMs: number;
+        slices: number;
+    };
 }

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

@@ -0,0 +1,8 @@
+import type { SVGACommandResult } from './svga-command-worker.js';
+import type { SVGACommandInput } from '../utils/svga-hybrid-command-data.js';
+import type { PreparationStepOptions } from '../utils/svga-preparation-profile.js';
+export interface CommandWorkerOptions extends PreparationStepOptions {
+    signal?: AbortSignal;
+    workerTimeSliceMs?: number;
+}
+export declare function requestSVGACommandTableInWorker(input: SVGACommandInput, hybrid: boolean, options: CommandWorkerOptions): Promise<SVGACommandResult>;

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

@@ -0,0 +1,27 @@
+import { type SVGACommandInput } from '../utils/svga-hybrid-command-data.js';
+import type { SVGAHybridCommandTable } from '../types/index.js';
+export interface SVGACommandResult {
+    commandTable?: SVGAHybridCommandTable;
+    packed: Float32Array;
+}
+export interface SVGACommandRequest {
+    type: 'start' | 'resume' | 'cancel';
+    id: number;
+    generation: number;
+    input?: SVGACommandInput;
+    hybrid?: boolean;
+    sliceMs?: number;
+    profile?: boolean;
+}
+export interface SVGACommandResponse {
+    id: number;
+    generation: number;
+    type: 'paused' | 'complete' | 'error';
+    result?: SVGACommandResult;
+    error?: string;
+    samples?: Array<{
+        phase: 'command-build' | 'frame-pack';
+        executionMs: number;
+        elapsedMs: number;
+    }>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taole/giftstage",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "High-performance WebGPU/WebGL gift animation player unifying SVGA, VAP, AlphaVideo, and images",
   "type": "module",
   "main": "dist/gift-stage.cjs",