@haiyue/extensions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HypnosNova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @haiyue/extensions
+
+Optional runtime capabilities for `@haiyue/engine`.
+
+## Stable entrypoints
+
+- `@haiyue/extensions/gltf` — glTF loading, runtime components, compatibility reports, materials, and the engine plugin.
+- `@haiyue/extensions/animation3d` — source-independent 3D clips, mixers, pose buffers, layers, masks, events, state machines, and the HYA adapter.
+- `@haiyue/extensions/gltf-animation3d` — adapts glTF clips to the source-independent Animation3D runtime.
+- `@haiyue/extensions/animation` — HYA Animation2D components, systems, loading, rendering, and state-machine integration.
+- `@haiyue/extensions/hya-state-machine` — the focused HYA 2D state-machine runtime.
+- `@haiyue/extensions/spine` — Spine component, render system, plugin, and the stable worker interface seam.
+- `@haiyue/extensions/tilemap` — Tilemap2D component, render system, and plugin.
+- `@haiyue/extensions/canvas-text` — Canvas text component and render system.
+- `@haiyue/extensions/tween` — Tween2D component and update system.
+- `@haiyue/extensions/grid` — Grid2D component contract.
+
+```ts
+import { HaiyueEngine } from '@haiyue/engine';
+import { createGltfPlugin } from '@haiyue/extensions/gltf';
+import { Animation3DMixer } from '@haiyue/extensions/animation3d';
+import { createGltfAnimation3DRuntime } from '@haiyue/extensions/gltf-animation3d';
+
+const engine = new HaiyueEngine({ canvas: '#app' });
+engine.installPlugin(createGltfPlugin());
+```
+
+The package root remains a minimal experimental authoring base. Worker transport and low-level parsing are explicitly available from `@haiyue/extensions/experimental/gltf-worker` and `@haiyue/extensions/experimental/spine-worker`; they may change without stable-API compatibility guarantees.
+
+WebGPU is required by the runtime; there is no WebGL fallback.

package/dist/animation/Animation2DComponent.d.ts

@@ -0,0 +1,46 @@
+import type { AnimationSource, ParsedAnimation } from '@haiyue/animation-spec';
+import { Component, type Entity, type World } from '@haiyue/engine';
+import type { Animation2DRuntime } from './Animation2DRuntime';
+import type { Animation2DExtensionRegistry } from './Animation2DExtensionRegistry';
+export interface Animation2DComponentOptions {
+    autoplay?: boolean;
+    loop?: boolean;
+    speed?: number;
+    startTime?: number;
+    runtimeExtensions?: Animation2DExtensionRegistry;
+}
+export interface Animation2DRuntimeStats {
+    readonly nodeCount: number;
+    readonly visualCount: number;
+    readonly unsupportedComponentCount: number;
+    readonly pendingResourceCount: number;
+    readonly failedResourceCount: number;
+    readonly textCount: number;
+    readonly particleCount: number;
+    readonly audioCount: number;
+}
+export declare class Animation2DComponent extends Component {
+    static UniqueCheckType: number;
+    static UniqueSymbol: symbol;
+    static Lifecycle: number;
+    readonly animation: ParsedAnimation;
+    playing: boolean;
+    loop: boolean;
+    speed: number;
+    currentTime: number;
+    completed: boolean;
+    readonly runtimeExtensions: Animation2DExtensionRegistry | undefined;
+    _runtime: Animation2DRuntime | null;
+    _needsApply: boolean;
+    _forceParticleSeek: boolean;
+    constructor(source: AnimationSource | ParsedAnimation, options?: Animation2DComponentOptions);
+    get runtimeStats(): Animation2DRuntimeStats;
+    play(): this;
+    pause(): this;
+    seek(seconds: number): this;
+    setSpeed(speed: number): this;
+    onEntityRemoveComponent(_entity: Entity, component: Component): void;
+    onEntityRemoveFromWorld(_entity: Entity, _world: World): void;
+    clone(): Animation2DComponent;
+    _disposeRuntime(): void;
+}

package/dist/animation/Animation2DExtensionRegistry.d.ts

@@ -0,0 +1,27 @@
+import type { AnimationComponent, AnimationNode, ParsedAnimation } from '@haiyue/animation-spec';
+import type { Entity } from '@haiyue/engine';
+export interface Animation2DExtensionContext {
+    readonly animation: ParsedAnimation;
+    readonly node: Readonly<AnimationNode>;
+    readonly component: Readonly<AnimationComponent>;
+    /** Anchor-adjusted parent for entities created by the extension. */
+    readonly parent: Entity;
+}
+export interface Animation2DExtensionInstance {
+    /** Deterministic composition-time update; implementations must tolerate seeks and loop wrap. */
+    apply?(timeSeconds: number, opacity: number): void;
+    setOpacity?(opacity: number): void;
+    destroy?(): void;
+}
+export interface Animation2DExtensionHandler {
+    /** Component type or namespaced extension id implemented by this handler. */
+    readonly id: string;
+    create(context: Animation2DExtensionContext): Animation2DExtensionInstance | void;
+}
+/** Instance-owned registry; unregister tokens only remove the handler that created them. */
+export declare class Animation2DExtensionRegistry {
+    private readonly _handlers;
+    register(handler: Animation2DExtensionHandler): () => void;
+    get(id: string): Animation2DExtensionHandler | undefined;
+    has(id: string): boolean;
+}

package/dist/animation/Animation2DRenderSystem.d.ts

@@ -0,0 +1,89 @@
+import { type IEngine, type RenderCommandContext } from '@haiyue/engine/extension-authoring';
+import { Entity, type World } from '@haiyue/engine/ecs';
+import { RenderSystem2DBase, type RenderSystem2DBaseOptions } from '../utils/RenderSystem2DBase';
+export interface Animation2DRenderSystemOptions extends RenderSystem2DBaseOptions {
+    /** Bounds view-sized alpha targets used by masks and mattes. */
+    maxMaskTargets?: number;
+}
+export interface Animation2DRenderStats {
+    readonly visualCount: number;
+    readonly maskTargetCount: number;
+    readonly compositeLayerCount: number;
+    readonly droppedCompositeCount: number;
+    readonly maskPixels: number;
+    readonly effectTargetCount: number;
+    readonly droppedEffectCount: number;
+    /** Counts the reusable ping-pong RGBA targets owned by each active view. */
+    readonly effectPixels: number;
+}
+export declare class Animation2DRenderSystem extends RenderSystem2DBase {
+    private readonly maxMaskTargets;
+    private rendererReady;
+    private cameraGpu;
+    private objectLayout;
+    private textureLayout;
+    private compositeLayout;
+    private sampler;
+    private whiteTexture;
+    private whiteBindGroup;
+    private emptyCompositeBindGroup;
+    private transparentTexture;
+    private transparentBindGroup;
+    private shader;
+    private pipelineLayout;
+    private pipelines;
+    private readonly entityGpu;
+    private readonly geometryGpu;
+    private textureBindGroups;
+    private readonly maskTargets;
+    private readonly effectTargets;
+    private readonly items;
+    private readonly sourceItems;
+    private readonly sourceGroupPool;
+    private readonly activeMaskTargets;
+    private readonly compositeBindGroups;
+    private readonly liveGeometryIds;
+    private _visualCount;
+    private _maskTargetCount;
+    private _compositeLayerCount;
+    private _droppedCompositeCount;
+    private _maskPixels;
+    private _effectTargetCount;
+    private _droppedEffectCount;
+    private _effectPixels;
+    constructor(engine: IEngine, cameraEntity: Entity, options?: Animation2DRenderSystemOptions);
+    get stats(): Animation2DRenderStats;
+    get renderPipelineOptions(): {
+        pass: "isolated";
+        loadOp: "clear" | "load";
+        sort: number;
+    };
+    record(world: World, context: RenderCommandContext): this;
+    destroy(): this;
+    protected releaseGpuResourcesForRecovery(): void;
+    private prepare;
+    private beginMaskSegment;
+    private beginOutputSegment;
+    private getPipeline;
+    private getEffectPipeline;
+    private getPresentPipeline;
+    private draw;
+    private renderEffectStack;
+    private drawEffectResult;
+    private getEntityGpu;
+    private getVisualTextureBindGroup;
+    private getGeometryGpu;
+    private getTextureBindGroup;
+    private createTextureBindGroup;
+    private resolveCompositeBindGroup;
+    private createCompositeBindGroup;
+    private getMaskTarget;
+    private getEffectTarget;
+    private sweepMaskTargets;
+    private sweepEffectTargets;
+    private sweepGeometryGpu;
+    private destroyEntityGpu;
+    private destroyGeometryGpu;
+    private destroyMaskTarget;
+    private destroyEffectTarget;
+}

package/dist/animation/Animation2DRuntime.d.ts

@@ -0,0 +1,99 @@
+import { type AnimationComposite, type AnimationLayerEffect, type AnimationNode, type AnimationPath2DComponent, type AnimationShape2DComponent, type AnimationSprite2DComponent, type AnimationText2DComponent, type AnimationVectorShapeComponent, type AnimationVectorValueTrack, type ParsedAnimation } from '@haiyue/animation-spec';
+import { Entity, Transform2D } from '@haiyue/engine';
+import { ParticleEmitter2D } from '@haiyue/engine/components';
+import type { AssetManager } from '@haiyue/engine/assets';
+import type { Animation2DRuntimeStats } from './Animation2DComponent.js';
+import type { Animation2DExtensionInstance, Animation2DExtensionRegistry } from './Animation2DExtensionRegistry.js';
+import { type VectorPathMorphComponent, type VectorStrokePathComponent } from './AnimationPathTessellator.js';
+import { AnimationVisual2D } from './AnimationVisual2D.js';
+import { AnimationTextRasterizer } from './AnimationTextRasterizer.js';
+import { AnimationAudioClip } from './AnimationAudioClip.js';
+export interface Animation2DRuntimeVisual {
+    readonly component: AnimationVisual2D;
+    readonly sourceComponentIndex: number;
+    readonly color: [number, number, number, number];
+    readonly baseAlpha: number;
+    lastAlpha: number;
+    readonly pathMorph?: VectorPathMorphComponent;
+    lastMorphTime?: number;
+    readonly vectorShape?: AnimationVectorShapeComponent;
+    readonly vectorPaint?: 'fill' | 'stroke';
+    styleAlpha: number;
+    lastVectorTime?: number;
+    readonly textRasterizer?: AnimationTextRasterizer;
+    readonly sourceEffects?: readonly Readonly<AnimationLayerEffect>[];
+    lastEffectTime?: number;
+    readonly compositeExpansionTracks?: readonly (Readonly<AnimationVectorValueTrack> | undefined)[];
+    lastCompositeTime?: number;
+    readonly spriteUvRectTrack?: AnimationVectorValueTrack;
+    spriteUvRectFrame?: number;
+}
+type CoreVisualComponent = AnimationShape2DComponent | AnimationPath2DComponent | AnimationSprite2DComponent | AnimationText2DComponent | AnimationVectorShapeComponent | VectorPathMorphComponent | VectorStrokePathComponent;
+interface DeferredCoreVisual {
+    readonly component: CoreVisualComponent;
+    readonly componentIndex: number;
+    readonly order: number;
+    readonly sourceGroup: string | undefined;
+    readonly composite: Readonly<AnimationComposite> | undefined;
+    readonly effects: readonly Readonly<AnimationLayerEffect>[] | undefined;
+}
+export interface Animation2DRuntimeNode {
+    readonly source: Readonly<AnimationNode>;
+    readonly entity: Entity;
+    readonly content: Entity;
+    readonly transform: Transform2D;
+    readonly visuals: Animation2DRuntimeVisual[];
+    readonly deferredVisuals: DeferredCoreVisual[];
+    readonly extensions: Animation2DExtensionInstance[];
+    readonly particles: ParticleEmitter2D[];
+    readonly audio: AnimationAudioClip[];
+    readonly initialX: number;
+    readonly initialY: number;
+    readonly initialRotation: number;
+    readonly initialScaleX: number;
+    readonly initialScaleY: number;
+    readonly initialOpacity: number;
+    opacity: number;
+}
+export declare class Animation2DRuntime {
+    private readonly _animation;
+    private readonly _assetManager?;
+    private readonly _root;
+    protected readonly _nodes: Animation2DRuntimeNode[];
+    protected readonly _nodesById: Map<string, Animation2DRuntimeNode>;
+    private readonly _tracksByNode;
+    private readonly _trackCursors;
+    private readonly _trackIndices;
+    protected readonly _opacityMemo: Map<string, number>;
+    private readonly _abortController;
+    private readonly _assetHandles;
+    private readonly _fontLoads;
+    private readonly _fontFaces;
+    private readonly _instanceId;
+    private _visualCount;
+    private _unsupportedComponentCount;
+    private _pendingResourceCount;
+    private _failedResourceCount;
+    private _textCount;
+    private _particleCount;
+    private _audioCount;
+    private _destroyed;
+    protected _playing: boolean;
+    protected _speed: number;
+    protected _lastAppliedTime: number;
+    get stats(): Animation2DRuntimeStats;
+    constructor(owner: Entity, _animation: ParsedAnimation, runtimeExtensions?: Animation2DExtensionRegistry, _assetManager?: AssetManager | undefined);
+    apply(time: number, playing?: boolean, speed?: number, forceParticleSeek?: boolean): void;
+    destroy(): void;
+    setPlaying(playing: boolean): void;
+    private _loadTexture;
+    protected _materializeCoreVisual(node: Animation2DRuntimeNode, deferred: DeferredCoreVisual): void;
+    private _loadTextFonts;
+    private _loadFont;
+    private _applyTrack;
+    protected _resolveOpacity(node: Animation2DRuntimeNode): number;
+    protected _isNodeActive(node: Animation2DRuntimeNode): boolean;
+    /** @internal Applies state-machine-only component channels to the shared visual instance. */
+    protected _applyStateMachineVisualChannel(node: Animation2DRuntimeNode, path: string, value: unknown): boolean;
+}
+export {};

package/dist/animation/Animation2DStateMachine.d.ts

@@ -0,0 +1,13 @@
+import type { AnimationStateMachineDefinition } from '../animation-state-machine/AnimationStateMachine.js';
+import { AnimationStateMachineController, type AnimationStateMachineActionHandle, type AnimationStateMachineControllerOptions, type AnimationStateMachineMixerPort } from '../animation-state-machine/runtime/index.js';
+export type Animation2DStateMachineActionHandle = AnimationStateMachineActionHandle;
+export type Animation2DStateMachineMixerPort<TAction extends Animation2DStateMachineActionHandle = Animation2DStateMachineActionHandle> = AnimationStateMachineMixerPort<TAction>;
+/**
+ * Creates a shared state-machine controller for a 2D mixer adapter.
+ *
+ * Animation2DComponent remains a single-composition player. A port must own
+ * the 2D pose sampling, blending, discrete-property policy, and side-effect
+ * lifecycle; this factory intentionally does not emulate those semantics by
+ * switching component timelines.
+ */
+export declare function createAnimation2DStateMachineController<TAction extends Animation2DStateMachineActionHandle>(definition: AnimationStateMachineDefinition, port: Animation2DStateMachineMixerPort<TAction>, options?: AnimationStateMachineControllerOptions): AnimationStateMachineController<TAction>;

package/dist/animation/Animation2DStateMachineComponent.d.ts

@@ -0,0 +1,54 @@
+import { type AnimationSource, type HyaStateMachineExtension, type ParsedAnimation } from '@haiyue/animation-spec';
+import { Component, type Entity, type World } from '@haiyue/engine';
+import type { AnimationStateMachineLayerSnapshot } from '../animation-state-machine/runtime/index.js';
+import type { AnimationStateMachineChannelDiagnostic } from '../animation-state-machine/AnimationStateMachineChannels.js';
+import type { Animation2DExtensionRegistry } from './Animation2DExtensionRegistry.js';
+import type { Animation2DStateMachineParameterValue, Animation2DStateMachineRuntime } from './Animation2DStateMachineRuntime.js';
+import type { Animation2DRuntimeStats } from './Animation2DComponent.js';
+export interface Animation2DStateMachineComponentOptions {
+    autoplay?: boolean;
+    speed?: number;
+    runtimeExtensions?: Animation2DExtensionRegistry;
+}
+/**
+ * Plays multiple named animation ranges and a state machine from one HYA
+ * asset. Transitions blend one pose onto one generated scene hierarchy.
+ */
+export declare class Animation2DStateMachineComponent extends Component {
+    static UniqueCheckType: number;
+    static UniqueSymbol: symbol;
+    static Lifecycle: number;
+    readonly animation: ParsedAnimation;
+    readonly stateMachineExtension: HyaStateMachineExtension;
+    readonly runtimeExtensions: Animation2DExtensionRegistry | undefined;
+    playing: boolean;
+    speed: number;
+    _runtime: Animation2DStateMachineRuntime | null;
+    _needsUpdate: boolean;
+    private readonly _parametersByName;
+    private readonly _parameterValues;
+    constructor(source: AnimationSource | ParsedAnimation, options?: Animation2DStateMachineComponentOptions);
+    get runtimeStats(): Animation2DRuntimeStats;
+    get layerSnapshots(): readonly AnimationStateMachineLayerSnapshot[];
+    get channelDiagnostics(): readonly AnimationStateMachineChannelDiagnostic[];
+    get liveActionCount(): number;
+    get liveBindingCount(): number;
+    get sideEffectOwnerCount(): number;
+    play(): this;
+    pause(): this;
+    setSpeed(speed: number): this;
+    setFloat(name: string, value: number): this;
+    setInteger(name: string, value: number): this;
+    setBoolean(name: string, value: boolean): this;
+    setTrigger(name: string): this;
+    resetTrigger(name: string): this;
+    getParameter(name: string): number | boolean;
+    reset(): this;
+    onEntityRemoveComponent(_entity: Entity, component: Component): void;
+    onEntityRemoveFromWorld(_entity: Entity, _world: World): void;
+    clone(): Animation2DStateMachineComponent;
+    _getParameterValues(): ReadonlyMap<string, Animation2DStateMachineParameterValue>;
+    _disposeRuntime(): void;
+    private _setParameter;
+    private _requireParameter;
+}

package/dist/animation/Animation2DStateMachineRuntime.d.ts

@@ -0,0 +1,30 @@
+import type { HyaStateMachineExtension, ParsedAnimation } from '@haiyue/animation-spec';
+import type { Entity } from '@haiyue/engine';
+import type { AssetManager } from '@haiyue/engine/assets';
+import type { AnimationStateMachineController, AnimationStateMachineLayerSnapshot } from '../animation-state-machine/runtime/index.js';
+import { type Animation2DStateMachineActionRuntimeHandle } from '../animation-state-machine/runtime/index.js';
+import type { AnimationStateMachineChannelDiagnostic } from '../animation-state-machine/AnimationStateMachineChannels.js';
+import type { Animation2DExtensionRegistry } from './Animation2DExtensionRegistry.js';
+import type { Animation2DRuntimeStats } from './Animation2DComponent.js';
+export type Animation2DStateMachineParameterValue = number | boolean;
+export declare class Animation2DStateMachineRuntime {
+    readonly extension: HyaStateMachineExtension;
+    private readonly _mixer;
+    private readonly _adapter;
+    private readonly _pose;
+    private readonly _visual;
+    private _destroyed;
+    readonly controller: AnimationStateMachineController<Animation2DStateMachineActionRuntimeHandle>;
+    constructor(owner: Entity, animation: ParsedAnimation, extension: HyaStateMachineExtension, parameterValues: ReadonlyMap<string, Animation2DStateMachineParameterValue>, runtimeExtensions?: Animation2DExtensionRegistry, assetManager?: AssetManager);
+    get stats(): Animation2DRuntimeStats;
+    get diagnostics(): readonly AnimationStateMachineChannelDiagnostic[];
+    get liveActionCount(): number;
+    get liveBindingCount(): number;
+    get sideEffectOwnerCount(): number;
+    get layerSnapshots(): readonly AnimationStateMachineLayerSnapshot[];
+    update(deltaSeconds: number, playing: boolean, speed: number): void;
+    setPlaying(playing: boolean): void;
+    reset(): void;
+    destroy(): void;
+    private _requireActive;
+}

package/dist/animation/Animation2DStateMachineSystem.d.ts

@@ -0,0 +1,14 @@
+import { System, type World } from '@haiyue/engine';
+import type { AssetManager } from '@haiyue/engine/assets';
+export interface Animation2DStateMachineSystemOptions {
+    priority?: number;
+    /** Shared engine asset manager used by sprite2d resources. */
+    assetManager?: AssetManager;
+}
+export declare class Animation2DStateMachineSystem extends System {
+    private readonly _assetManager;
+    constructor(options?: Animation2DStateMachineSystemOptions);
+    update(world: World, _time: number, delta: number): this;
+    destroy(): this;
+    private _updateEntity;
+}

package/dist/animation/Animation2DStateMachineVisualRuntime.d.ts

@@ -0,0 +1,27 @@
+import type { Entity } from '@haiyue/engine';
+import type { AssetManager } from '@haiyue/engine/assets';
+import type { ParsedAnimation } from '@haiyue/animation-spec';
+import type { Animation2DExtensionRegistry } from './Animation2DExtensionRegistry.js';
+import { Animation2DRuntime } from './Animation2DRuntime.js';
+import type { Animation2DPose } from './runtime/mixer/index.js';
+import { type AnimationStateMachineChannelDiagnostic } from '../animation-state-machine/AnimationStateMachineChannels.js';
+/** State-machine-only pose writer kept out of the ordinary Animation2D bundle. */
+export declare class Animation2DStateMachineVisualRuntime extends Animation2DRuntime {
+    private readonly _particleOwners;
+    private readonly _audioOwners;
+    private readonly _effectPayloads;
+    private readonly _diagnostics;
+    private readonly _reportedAudioRejections;
+    constructor(owner: Entity, animation: ParsedAnimation, runtimeExtensions?: Animation2DExtensionRegistry, assetManager?: AssetManager);
+    get diagnostics(): readonly AnimationStateMachineChannelDiagnostic[];
+    get sideEffectOwnerCount(): number;
+    resetSideEffects(): void;
+    applyPose(pose: Animation2DPose, playing?: boolean, speed?: number): void;
+    setPlaying(playing: boolean): void;
+    destroy(): void;
+    private _applyVisualOpacity;
+    private _applyEffect;
+    private _particleTarget;
+    private _audioTarget;
+    private _reportAudioRejection;
+}

package/dist/animation/Animation2DSystem.d.ts

@@ -0,0 +1,14 @@
+import { System, type World } from '@haiyue/engine';
+import type { AssetManager } from '@haiyue/engine/assets';
+export interface Animation2DSystemOptions {
+    priority?: number;
+    /** Shared engine asset manager used by sprite2d resources. */
+    assetManager?: AssetManager;
+}
+export declare class Animation2DSystem extends System {
+    private readonly _assetManager;
+    constructor(options?: Animation2DSystemOptions);
+    update(world: World, _time: number, delta: number): this;
+    destroy(): this;
+    private _updateEntity;
+}

package/dist/animation/AnimationAssetLoader.d.ts

@@ -0,0 +1,9 @@
+import { type AnimationParseOptions, type ParsedAnimation } from '@haiyue/animation-spec';
+import type { AssetLoaderRegistration } from '@haiyue/engine/assets';
+export declare const HAIYUE_ANIMATION_ASSET_TYPE: "animation/haiyue";
+export interface AnimationAssetLoaderOptions {
+    parse?: AnimationParseOptions;
+    fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+/** Creates an AssetManager loader without installing source-format converters in the runtime. */
+export declare function createAnimationAssetLoader(options?: AnimationAssetLoaderOptions): AssetLoaderRegistration<ParsedAnimation>;

package/dist/animation/AnimationAudioClip.d.ts

@@ -0,0 +1,26 @@
+import type { AnimationAudioComponent, AnimationNode } from '@haiyue/animation-spec';
+/** HTML media-backed audio clip with composition-time seek and playback-rate synchronization. */
+export declare class AnimationAudioClip {
+    private readonly element;
+    private readonly nodeStart;
+    private readonly nodeEnd;
+    private readonly startOffset;
+    private readonly baseVolume;
+    private readonly clipRate;
+    private readonly loop;
+    private playPending;
+    private destroyed;
+    private stateMachineActive;
+    private playRequestEpoch;
+    constructor(uri: string, component: AnimationAudioComponent, node: Readonly<AnimationNode>, animationDuration: number);
+    sync(compositionTime: number, playing: boolean, speed: number, opacity: number): void;
+    enterStateMachine(playing: boolean, speed: number, opacity: number, rejected: (reason: unknown) => void): void;
+    restartStateMachine(playing: boolean, speed: number, opacity: number, rejected: (reason: unknown) => void): void;
+    setStateMachinePlaying(playing: boolean, speed: number, rejected: (reason: unknown) => void): void;
+    updateStateMachineProperties(speed: number, opacity: number): void;
+    exitStateMachine(): void;
+    pause(): void;
+    destroy(): void;
+    private _requestPlay;
+    private _cancelPendingPlay;
+}

package/dist/animation/AnimationPathTessellator.d.ts

@@ -0,0 +1,52 @@
+import type { AnimationPath2DComponent } from '@haiyue/animation-spec';
+import { Geometry2D } from '@haiyue/engine';
+export type ResolvedVectorPathModifier = Readonly<{
+    kind: 'trim-path';
+    start: number;
+    end: number;
+    offset: number;
+    mode: 'simultaneous' | 'individual';
+}> | Readonly<{
+    kind: 'round-corners';
+    radius: number;
+}>;
+export interface ResolvedVectorPath {
+    readonly commands: string;
+    readonly values: Float32Array;
+}
+export interface VectorStrokePathComponent {
+    readonly [key: string]: unknown;
+    readonly type: 'org.haiyue.vector-stroke@1';
+    readonly commands?: string;
+    readonly values?: readonly number[] | Float32Array;
+    readonly sourceComponent?: number;
+    readonly color: readonly [number, number, number, number];
+    readonly width: number;
+    readonly lineCap: 'butt' | 'round' | 'square';
+    readonly lineJoin: 'miter' | 'round' | 'bevel';
+    readonly miterLimit: number;
+    readonly dash?: readonly number[] | Float32Array;
+    readonly dashOffset?: number;
+    readonly tolerance?: number;
+}
+export interface VectorPathMorphComponent {
+    readonly [key: string]: unknown;
+    readonly type: 'org.haiyue.vector-path-morph@1';
+    readonly commands: string;
+    readonly times: readonly number[] | Float32Array;
+    readonly values: readonly number[] | Float32Array;
+    readonly valueSize: number;
+    readonly interpolation: 'step' | 'linear' | 'cubic-bezier';
+    readonly easings?: readonly number[] | Float32Array;
+    readonly fill: readonly [number, number, number, number];
+    readonly fillRule: 'nonzero' | 'evenodd';
+    readonly tolerance?: number;
+}
+/** Applies ordered source-neutral modifiers after curve flattening. Empty trim ranges return an empty command stream. */
+export declare function applyVectorPathModifiers(commands: string, values: readonly number[] | Float32Array, tolerance: number, modifiers: readonly ResolvedVectorPathModifier[], closeOpen: boolean): ResolvedVectorPath;
+/** Flattens packed quadratic/cubic commands and triangulates contours with hole nesting. */
+export declare function tessellateAnimationPath(component: AnimationPath2DComponent): Geometry2D;
+/** Tessellates the compact Lottie stroke extension without expanding it in the HYA payload. */
+export declare function tessellateVectorStrokePath(component: VectorStrokePathComponent, allowEmpty?: boolean): Geometry2D;
+/** Samples a topology-stable Lottie path morph into the ordinary path tessellator ABI. */
+export declare function sampleVectorPathMorph(component: VectorPathMorphComponent, time: number): AnimationPath2DComponent;

package/dist/animation/AnimationTextRasterizer.d.ts

@@ -0,0 +1,21 @@
+import type { AnimationText2DComponent } from '@haiyue/animation-spec';
+type TextTexture = HTMLCanvasElement | ImageBitmap;
+/** Runtime-private deterministic grapheme shaper and Canvas atlas uploader. */
+export declare class AnimationTextRasterizer {
+    readonly component: Readonly<AnimationText2DComponent>;
+    texture: TextTexture | null;
+    textureVersion: number;
+    private readonly canvas;
+    private time;
+    private dirty;
+    private updating;
+    private updateToken;
+    private readonly animated;
+    constructor(component: Readonly<AnimationText2DComponent>);
+    setTime(time: number): void;
+    invalidateFont(): void;
+    destroy(): void;
+    updateTexture(): Promise<void>;
+    private draw;
+}
+export {};

package/dist/animation/AnimationVisual2D.d.ts

@@ -0,0 +1,68 @@
+import type { AnimationComposite, AnimationCompositeLayer, AnimationCompositeMode } from '@haiyue/animation-spec';
+import { Component, Geometry2D } from '@haiyue/engine';
+import type { AssetHandle } from '@haiyue/engine/assets';
+import type { AnimationTextRasterizer } from './AnimationTextRasterizer';
+export interface AnimationVisual2DOptions {
+    geometry: Geometry2D;
+    color: readonly [number, number, number, number];
+    instanceId: number;
+    nodeId: string;
+    order: number;
+    sourceOnly?: boolean;
+    composite?: Readonly<AnimationComposite>;
+    texture?: GPUTexture | null;
+    textureHandle?: AssetHandle<GPUTexture> | null;
+    textMaterial?: AnimationTextRasterizer | null;
+    /** Keeps sprites invisible until their asynchronous texture is ready. */
+    requiresTexture?: boolean;
+    uvRect?: readonly [number, number, number, number];
+    gradient?: AnimationVisualGradient | null;
+    effects?: readonly AnimationVisualEffect[];
+}
+export interface AnimationVisualGradient {
+    kind: 'linear' | 'radial';
+    start: [number, number];
+    end: [number, number];
+    /** Mutable packed offset,r,g,b,a tuples, bounded to eight stops. */
+    stops: Float32Array;
+    opacity: number;
+}
+export type AnimationVisualEffectKind = 'tint' | 'fill' | 'opacity' | 'color-matrix' | 'blur' | 'drop-shadow';
+export interface AnimationVisualEffect {
+    readonly kind: AnimationVisualEffectKind;
+    /** Mutable, kind-specific sampled values owned by the animation runtime. */
+    readonly values: Float32Array;
+}
+/** Runtime-private render item consumed by Animation2DRenderSystem. */
+export declare class AnimationVisual2D extends Component {
+    static UniqueCheckType: number;
+    static UniqueSymbol: symbol;
+    readonly geometry: Geometry2D;
+    readonly instanceId: number;
+    readonly nodeId: string;
+    readonly nodeKey: string;
+    readonly order: number;
+    readonly sourceOnly: boolean;
+    readonly compositeLayers: readonly Readonly<AnimationCompositeLayer>[];
+    readonly compositeKeys: readonly string[];
+    /** Compatibility accessors for single-layer renderer diagnostics. */
+    readonly compositeSource: string | undefined;
+    readonly compositeKey: string | undefined;
+    readonly compositeMode: AnimationCompositeMode | undefined;
+    readonly uvRect: [number, number, number, number];
+    readonly color: [number, number, number, number];
+    texture: GPUTexture | null;
+    textureHandle: AssetHandle<GPUTexture> | null;
+    readonly textMaterial: AnimationTextRasterizer | null;
+    readonly requiresTexture: boolean;
+    gradient: AnimationVisualGradient | null;
+    readonly effects: readonly AnimationVisualEffect[];
+    revision: number;
+    constructor(options: AnimationVisual2DOptions);
+    setTexture(texture: GPUTexture | null): void;
+    setTextureHandle(handle: AssetHandle<GPUTexture> | null): void;
+    setUvRect(value: readonly [number, number, number, number]): void;
+    setCompositeExpansion(index: number, value: number): void;
+    resolveTexture(): GPUTexture | null;
+    clone(): AnimationVisual2D;
+}