@haiyue/extensions 0.1.0

package/dist/animation3d/Animation3DAction.d.ts

@@ -0,0 +1,46 @@
+import type { Animation3DBindingMask } from './Animation3DBinding';
+import type { Animation3DClip } from './Animation3DClip';
+export type Animation3DLoopMode = 'once' | 'repeat' | 'ping-pong';
+export type Animation3DBlendMode = 'override' | 'additive';
+export type Animation3DActionStatus = 'idle' | 'scheduled' | 'running' | 'paused' | 'finished' | 'stopped';
+export interface Animation3DActionOptions {
+    readonly id?: string;
+    readonly loop?: Animation3DLoopMode;
+    /** Infinity is valid for repeat and ping-pong. */
+    readonly repetitions?: number;
+    readonly clampWhenFinished?: boolean;
+    readonly timeScale?: number;
+    readonly weight?: number;
+    readonly blendMode?: Animation3DBlendMode;
+    readonly mask?: Animation3DBindingMask;
+}
+/**
+ * One mutable playback instance of an immutable clip.
+ * Actions are mixer-owned and become invalid after removal or mixer destroy.
+ */
+export interface Animation3DAction {
+    readonly id: string;
+    readonly clip: Animation3DClip;
+    readonly status: Animation3DActionStatus;
+    enabled: boolean;
+    paused: boolean;
+    time: number;
+    timeScale: number;
+    weight: number;
+    loop: Animation3DLoopMode;
+    repetitions: number;
+    clampWhenFinished: boolean;
+    blendMode: Animation3DBlendMode;
+    mask: Animation3DBindingMask | null;
+    readonly effectiveTimeScale: number;
+    readonly effectiveWeight: number;
+    play(): this;
+    stop(): this;
+    reset(): this;
+    startAt(mixerTimeSeconds: number): this;
+    fadeIn(durationSeconds: number): this;
+    fadeOut(durationSeconds: number): this;
+    crossFadeFrom(source: Animation3DAction, durationSeconds: number, warp?: boolean): this;
+    crossFadeTo(destination: Animation3DAction, durationSeconds: number, warp?: boolean): this;
+    stopFading(): this;
+}

package/dist/animation3d/Animation3DBinding.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Logical targets keep authored clips independent from a concrete ECS World.
+ * A runtime resolver maps one of these stable references to an actual target.
+ */
+export type Animation3DBindingTarget = Readonly<{
+    kind: 'node-id';
+    nodeId: string;
+}> | Readonly<{
+    kind: 'node-path';
+    segments: readonly string[];
+}> | Readonly<{
+    kind: 'slot';
+    slot: string;
+}>;
+export type Animation3DFixedValueType = 'scalar' | 'vec2' | 'vec3' | 'vec4' | 'quaternion';
+export type Animation3DValueType = Animation3DFixedValueType | 'weights';
+export interface Animation3DTranslationBinding {
+    readonly id: string;
+    readonly target: Animation3DBindingTarget;
+    readonly path: 'transform.translation';
+    readonly valueType: 'vec3';
+    readonly valueSize: 3;
+}
+export interface Animation3DRotationBinding {
+    readonly id: string;
+    readonly target: Animation3DBindingTarget;
+    readonly path: 'transform.rotation';
+    readonly valueType: 'quaternion';
+    readonly valueSize: 4;
+}
+export interface Animation3DScaleBinding {
+    readonly id: string;
+    readonly target: Animation3DBindingTarget;
+    readonly path: 'transform.scale';
+    readonly valueType: 'vec3';
+    readonly valueSize: 3;
+}
+export interface Animation3DMorphWeightsBinding {
+    readonly id: string;
+    readonly target: Animation3DBindingTarget;
+    readonly path: 'morph.weights';
+    readonly valueType: 'weights';
+    /** Positive morph target count. Loaders must reject zero or negative values. */
+    readonly valueSize: number;
+}
+export type Animation3DFixedValueSize = {
+    readonly scalar: 1;
+    readonly vec2: 2;
+    readonly vec3: 3;
+    readonly vec4: 4;
+    readonly quaternion: 4;
+};
+export type Animation3DPropertyBinding = {
+    [TValueType in Animation3DFixedValueType]: Readonly<{
+        id: string;
+        target: Animation3DBindingTarget;
+        path: 'property';
+        /** Stable component or adapter namespace, never a constructor reference. */
+        component: string;
+        property: string;
+        valueType: TValueType;
+        valueSize: Animation3DFixedValueSize[TValueType];
+    }>;
+}[Animation3DFixedValueType];
+export type Animation3DBinding = Animation3DTranslationBinding | Animation3DRotationBinding | Animation3DScaleBinding | Animation3DMorphWeightsBinding | Animation3DPropertyBinding;
+export interface Animation3DResolvedBinding<TBinding extends Animation3DBinding = Animation3DBinding> {
+    readonly binding: TBinding;
+    /** Writes exactly binding.valueSize values into out. */
+    read(out: Float32Array): void;
+    /** Reads exactly binding.valueSize values from value. */
+    write(value: ArrayLike<number>): void;
+}
+/**
+ * Resolver revisions invalidate cached resolved bindings after hierarchy or
+ * component structure changes.
+ */
+export interface Animation3DBindingResolver {
+    readonly revision: number;
+    resolve<TBinding extends Animation3DBinding>(binding: TBinding): Animation3DResolvedBinding<TBinding> | null;
+}
+export interface Animation3DBindingMask {
+    /** Empty or omitted include means all bindings are eligible. */
+    readonly include?: readonly string[];
+    readonly exclude?: readonly string[];
+}

package/dist/animation3d/Animation3DClip.d.ts

@@ -0,0 +1,20 @@
+import type { Animation3DTrack } from './Animation3DTrack';
+export interface Animation3DEvent {
+    readonly id: string;
+    readonly time: number;
+    readonly name: string;
+    /** Loader-validated, structured-cloneable event data. */
+    readonly payload?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Immutable, source-format-independent CPU animation resource.
+ * Times are seconds; rotations are normalized XYZW quaternions.
+ */
+export interface Animation3DClip {
+    readonly format: 'haiyue-animation3d-clip@1';
+    readonly id: string;
+    readonly name: string;
+    readonly duration: number;
+    readonly tracks: readonly Animation3DTrack[];
+    readonly events: readonly Animation3DEvent[];
+}

package/dist/animation3d/Animation3DError.d.ts

@@ -0,0 +1,13 @@
+export type Animation3DErrorCode = 'mixer-destroyed' | 'invalid-clip' | 'invalid-track' | 'invalid-action' | 'duplicate-action-id' | 'resolver-miss';
+export type Animation3DErrorDetails = Readonly<Record<string, string | number | boolean | null>>;
+/**
+ * Stable domain error for the Animation3D facade.
+ *
+ * Callers should branch on `code`; messages remain diagnostic and may gain
+ * additional context without changing the error contract.
+ */
+export declare class Animation3DError extends Error {
+    readonly code: Animation3DErrorCode;
+    readonly details: Animation3DErrorDetails;
+    constructor(code: Animation3DErrorCode, message: string, details?: Animation3DErrorDetails);
+}

package/dist/animation3d/Animation3DMixer.d.ts

@@ -0,0 +1,27 @@
+import type { Animation3DBindingResolver } from './Animation3DBinding.js';
+import type { Animation3DAction, Animation3DActionOptions } from './Animation3DAction.js';
+import type { Animation3DClip } from './Animation3DClip.js';
+import type { Animation3DMutablePose, Animation3DPose } from './Animation3DPose.js';
+export type Animation3DMixerState = 'active' | 'destroyed';
+/**
+ * Public mixer facade. Controller-only clock/transaction hooks remain on the
+ * internal runtime and are intentionally absent from this surface.
+ */
+export declare class Animation3DMixer {
+    #private;
+    constructor(resolver: Animation3DBindingResolver);
+    get state(): Animation3DMixerState;
+    get resolver(): Animation3DBindingResolver;
+    get actions(): readonly Animation3DAction[];
+    get time(): number;
+    get timeScale(): number;
+    set timeScale(value: number);
+    createAction(clip: Animation3DClip, options?: Animation3DActionOptions): Animation3DAction;
+    getAction(actionId: string): Animation3DAction | null;
+    removeAction(action: Animation3DAction | string): boolean;
+    stopAllActions(): this;
+    update(deltaSeconds: number, out: Animation3DMutablePose): Animation3DPose;
+    evaluate(out: Animation3DMutablePose): Animation3DPose;
+    setTime(timeSeconds: number, out: Animation3DMutablePose): Animation3DPose;
+    destroy(): void;
+}

package/dist/animation3d/Animation3DPose.d.ts

@@ -0,0 +1,40 @@
+import type { Animation3DBinding, Animation3DBindingResolver } from './Animation3DBinding.js';
+import type { Animation3DEvent } from './Animation3DClip.js';
+export interface Animation3DPoseChannel<TBinding extends Animation3DBinding = Animation3DBinding> {
+    readonly binding: TBinding;
+    /** Exactly binding.valueSize sampled and blended values. */
+    readonly value: Readonly<Float32Array>;
+}
+export interface Animation3DPoseEvent {
+    readonly actionId: string;
+    readonly clipId: string;
+    readonly event: Animation3DEvent;
+}
+/**
+ * Frame-transient mixer output. Implementations may reuse its arrays on the
+ * next evaluate/update call; callers must copy values they need to retain.
+ */
+export interface Animation3DPose {
+    readonly sequence: number;
+    readonly mixerTime: number;
+    readonly channels: readonly Animation3DPoseChannel[];
+    readonly events: readonly Animation3DPoseEvent[];
+}
+/**
+ * Caller-provided scratch target used to keep mixer evaluation allocation-free.
+ * reset() begins a new pose and seal() returns the current read-only view.
+ */
+export interface Animation3DMutablePose {
+    reset(mixerTime: number): void;
+    write(binding: Animation3DBinding, value: ArrayLike<number>): void;
+    emit(event: Animation3DPoseEvent): void;
+    seal(): Animation3DPose;
+}
+/**
+ * Applies pose channels through a revision-aware binding resolver cache.
+ * Resolver misses fail explicitly and never write to a fallback target.
+ */
+export declare class Animation3DPoseApplier {
+    constructor(resolver: Animation3DBindingResolver);
+    apply(pose: Animation3DPose): void;
+}

package/dist/animation3d/Animation3DPoseBuffer.d.ts

@@ -0,0 +1,24 @@
+import type { Animation3DBinding } from './Animation3DBinding.js';
+import type { Animation3DMutablePose, Animation3DPose, Animation3DPoseChannel, Animation3DPoseEvent } from './Animation3DPose.js';
+/**
+ * Reusable caller-owned mixer output.
+ *
+ * Channel records and value arrays are pooled after first use. seal() returns
+ * this object as the read-only pose view rather than allocating a snapshot.
+ */
+export declare class Animation3DPoseBuffer implements Animation3DMutablePose, Animation3DPose {
+    private readonly _channelPool;
+    private readonly _channels;
+    private readonly _events;
+    private _sequence;
+    private _mixerTime;
+    private _sealed;
+    get sequence(): number;
+    get mixerTime(): number;
+    get channels(): readonly Animation3DPoseChannel[];
+    get events(): readonly Animation3DPoseEvent[];
+    reset(mixerTime: number): void;
+    write(binding: Animation3DBinding, value: ArrayLike<number>): void;
+    emit(event: Animation3DPoseEvent): void;
+    seal(): Animation3DPose;
+}

package/dist/animation3d/Animation3DResource.d.ts

@@ -0,0 +1,28 @@
+import type { AssetHandle, AssetJobPriority, AssetOwnerScope } from '@haiyue/engine/assets';
+import type { Animation3DClip } from './Animation3DClip';
+import type { Animation3DStateMachineDefinition } from './Animation3DStateMachine';
+export type Animation3DClipHandle = AssetHandle<Animation3DClip>;
+export type Animation3DStateMachineHandle = AssetHandle<Animation3DStateMachineDefinition>;
+export type Animation3DResourceSource = Readonly<{
+    kind: 'url';
+    url: string;
+    cacheKey?: string;
+}> | Readonly<{
+    kind: 'buffer';
+    data: ArrayBuffer;
+    /** Required because ArrayBuffer identity is not a persistent cache key. */
+    cacheKey: string;
+}>;
+export interface Animation3DResourceLoadOptions {
+    readonly signal?: AbortSignal;
+    readonly owner?: AssetOwnerScope;
+    readonly priority?: AssetJobPriority | number;
+}
+/**
+ * Contract for an AssetManager-backed loader. Implementations must return a
+ * distinct handle per acquisition and make handle.release() idempotent.
+ */
+export interface Animation3DResourceLoader {
+    loadClip(source: Animation3DResourceSource, options?: Animation3DResourceLoadOptions): Promise<Animation3DClipHandle>;
+    loadStateMachine(source: Animation3DResourceSource, options?: Animation3DResourceLoadOptions): Promise<Animation3DStateMachineHandle>;
+}

package/dist/animation3d/Animation3DStateMachine.d.ts

@@ -0,0 +1,95 @@
+import type { Animation3DBindingMask } from './Animation3DBinding.js';
+import type { Animation3DBlendMode, Animation3DLoopMode } from './Animation3DAction.js';
+export type Animation3DParameterDefinition = Readonly<{
+    name: string;
+    type: 'float';
+    defaultValue: number;
+}> | Readonly<{
+    name: string;
+    type: 'integer';
+    defaultValue: number;
+}> | Readonly<{
+    name: string;
+    type: 'boolean';
+    defaultValue: boolean;
+}> | Readonly<{
+    name: string;
+    type: 'trigger';
+}>;
+export type Animation3DTransitionCondition = Readonly<{
+    parameter: string;
+    operator: 'greater' | 'greater-or-equal' | 'less' | 'less-or-equal';
+    value: number;
+}> | Readonly<{
+    parameter: string;
+    operator: 'equal' | 'not-equal';
+    value: number | boolean;
+}> | Readonly<{
+    parameter: string;
+    operator: 'is-true' | 'is-false' | 'triggered';
+}>;
+export interface Animation3DClipMotion {
+    readonly kind: 'clip';
+    readonly clipId: string;
+}
+export interface Animation3DBlend1DChild {
+    readonly threshold: number;
+    readonly motion: Animation3DMotionDefinition;
+}
+export interface Animation3DBlend1DMotion {
+    readonly kind: 'blend-1d';
+    readonly parameter: string;
+    readonly children: readonly Animation3DBlend1DChild[];
+}
+export interface Animation3DBlend2DChild {
+    readonly position: readonly [number, number];
+    readonly motion: Animation3DMotionDefinition;
+}
+export interface Animation3DBlend2DMotion {
+    readonly kind: 'blend-2d';
+    readonly algorithm: 'cartesian' | 'directional';
+    readonly parameterX: string;
+    readonly parameterY: string;
+    readonly children: readonly Animation3DBlend2DChild[];
+}
+export type Animation3DMotionDefinition = Animation3DClipMotion | Animation3DBlend1DMotion | Animation3DBlend2DMotion;
+export interface Animation3DStateDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly motion: Animation3DMotionDefinition;
+    readonly speed?: number;
+    readonly speedParameter?: string;
+    readonly loop?: Animation3DLoopMode;
+}
+export type Animation3DTransitionInterruption = 'none' | 'source' | 'destination' | 'source-then-destination' | 'destination-then-source';
+export interface Animation3DTransitionDefinition {
+    readonly id: string;
+    /** '*' means any state in the same layer. */
+    readonly from: string | '*';
+    readonly to: string;
+    readonly conditions: readonly Animation3DTransitionCondition[];
+    readonly duration: number;
+    readonly hasExitTime?: boolean;
+    readonly exitTime?: number;
+    readonly destinationOffset?: number;
+    readonly interruption?: Animation3DTransitionInterruption;
+}
+export interface Animation3DStateMachineLayer {
+    readonly id: string;
+    readonly name: string;
+    readonly initialStateId: string;
+    readonly states: readonly Animation3DStateDefinition[];
+    /** Declaration order is transition priority. */
+    readonly transitions: readonly Animation3DTransitionDefinition[];
+    readonly blendMode?: Animation3DBlendMode;
+    readonly weight?: number;
+    readonly mask?: Animation3DBindingMask;
+}
+/** Serializable definition; controller state is always stored separately. */
+export interface Animation3DStateMachineDefinition {
+    readonly format: 'haiyue-animation3d-state-machine@1';
+    readonly id: string;
+    readonly name: string;
+    readonly parameters: readonly Animation3DParameterDefinition[];
+    readonly layers: readonly Animation3DStateMachineLayer[];
+}

package/dist/animation3d/Animation3DStateMachineRuntime.d.ts

@@ -0,0 +1,70 @@
+import type { Animation3DClip } from './Animation3DClip.js';
+import { Animation3DMixer } from './Animation3DMixer.js';
+import type { Animation3DMutablePose, Animation3DPose } from './Animation3DPose.js';
+import type { Animation3DStateMachineDefinition } from './Animation3DStateMachine.js';
+declare const COMPILED_ANIMATION3D_STATE_MACHINE: unique symbol;
+/**
+ * Opaque compiler output. Compiled nodes and lookup tables are deliberately
+ * hidden so validation/compiler internals can evolve without expanding the
+ * facade.
+ */
+export interface Animation3DCompiledStateMachine {
+    readonly format: 'haiyue-animation-state-machine-compiled@1';
+    readonly id: string;
+    readonly name: string;
+    readonly [COMPILED_ANIMATION3D_STATE_MACHINE]: true;
+}
+export type Animation3DStateMachineValidationCode = 'invalid-value' | 'duplicate-id' | 'missing-reference' | 'parameter-type-mismatch' | 'invalid-operator' | 'empty-blend-tree' | 'invalid-thresholds' | 'recursive-motion';
+export interface Animation3DStateMachineValidationIssue {
+    readonly code: Animation3DStateMachineValidationCode;
+    readonly path: string;
+    readonly message: string;
+}
+export declare class Animation3DStateMachineValidationError extends Error {
+    readonly issues: readonly Animation3DStateMachineValidationIssue[];
+    constructor(issues: readonly Animation3DStateMachineValidationIssue[]);
+}
+export declare function validateAnimation3DStateMachineDefinition(definition: Animation3DStateMachineDefinition): readonly Animation3DStateMachineValidationIssue[];
+export declare function compileAnimation3DStateMachineDefinition(definition: Animation3DStateMachineDefinition): Animation3DCompiledStateMachine;
+export interface Animation3DStateMachineClipResolver {
+    resolve(clipId: string): Animation3DClip | null;
+}
+export interface Animation3DStateMachineControllerOptions {
+    readonly maxTransitionsPerUpdate?: number;
+}
+export type Animation3DStateMachineControllerStatus = 'active' | 'destroyed';
+export interface Animation3DStateMachineLayerSnapshot {
+    readonly layerId: string;
+    readonly currentStateId: string;
+    readonly currentTime: number;
+    readonly transitionId: string | null;
+    readonly sourceStateId: string | null;
+    readonly destinationStateId: string | null;
+    readonly transitionProgress: number;
+}
+/**
+ * Public closed-loop controller and minimal Mixer integration.
+ *
+ * The internal mixer port, action handles, controller transactions and
+ * compiled nodes never cross this boundary.
+ */
+export declare class Animation3DStateMachineController {
+    #private;
+    readonly mixer: Animation3DMixer;
+    constructor(compiled: Animation3DCompiledStateMachine, mixer: Animation3DMixer, clipResolver: Animation3DStateMachineClipResolver, options?: Animation3DStateMachineControllerOptions);
+    get status(): Animation3DStateMachineControllerStatus;
+    get time(): number;
+    get layerSnapshots(): readonly Animation3DStateMachineLayerSnapshot[];
+    getLayerSnapshot(layerId: string): Animation3DStateMachineLayerSnapshot;
+    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;
+    update(deltaSeconds: number, out: Animation3DMutablePose): Animation3DPose;
+    evaluate(out: Animation3DMutablePose): Animation3DPose;
+    reset(out: Animation3DMutablePose): Animation3DPose;
+    destroy(): void;
+}
+export {};

package/dist/animation3d/Animation3DTrack.d.ts

@@ -0,0 +1,19 @@
+import type { Animation3DBinding } from './Animation3DBinding';
+export type Animation3DInterpolation = 'step' | 'linear' | 'cubic-spline';
+export interface Animation3DTrackFor<TBinding extends Animation3DBinding> {
+    readonly id: string;
+    readonly binding: TBinding;
+    readonly interpolation: Animation3DInterpolation;
+    /**
+     * Strictly increasing key times in seconds.
+     * The clip resource owns the underlying storage; consumers must not mutate it.
+     */
+    readonly times: Readonly<Float32Array>;
+    /**
+     * step/linear: keyCount * binding.valueSize values.
+     * cubic-spline: keyCount groups of [inTangent, value, outTangent], with each
+     * entry containing binding.valueSize values.
+     */
+    readonly values: Readonly<Float32Array>;
+}
+export type Animation3DTrack = Animation3DTrackFor<Animation3DBinding>;

package/dist/animation3d/hya/HyaAnimation3DRuntime.d.ts

@@ -0,0 +1,73 @@
+import { Entity } from '@haiyue/engine';
+import { PbrMaterial } from '@haiyue/engine/material';
+import type { Animation3DClip } from '../Animation3DClip';
+import { Animation3DMixer } from '../Animation3DMixer';
+import { Animation3DPoseBuffer } from '../Animation3DPoseBuffer';
+import type { HyaAnimation3DActionGroup, HyaAnimation3DPlayOptions, HyaAnimation3DRuntimeDiagnostics, HyaAnimation3DRuntimeOptions, HyaAnimation3DStateMachineRuntimeControl } from './HyaAnimation3DTypes';
+type RuntimeState = 'active' | 'destroyed';
+/**
+ * Optional native-3D HYA owner. The caller must pass an already validated
+ * animation-spec payload; no ECS/GPU object is allocated by the parser.
+ */
+export declare class HyaAnimation3DRuntime {
+    readonly root: Entity;
+    readonly mixer: Animation3DMixer;
+    readonly pose: Animation3DPoseBuffer;
+    private readonly _scene;
+    private readonly _payload;
+    private readonly _clips;
+    private readonly _resources;
+    private readonly _entities;
+    private readonly _transforms;
+    private readonly _materials;
+    private readonly _cameras;
+    private readonly _models;
+    private readonly _mainClips;
+    private readonly _modelClips;
+    private readonly _modelBindingIds;
+    private readonly _actionGroups;
+    private readonly _resolver;
+    private readonly _poseApplier;
+    private readonly _owner;
+    private readonly _geometries;
+    private readonly _particles;
+    private readonly _abortController;
+    private readonly _externalSignal;
+    private readonly _externalAbortListener;
+    private readonly _disposeModel;
+    private _state;
+    private _initialized;
+    private _stateMachine;
+    private constructor();
+    static create(options: HyaAnimation3DRuntimeOptions): Promise<HyaAnimation3DRuntime>;
+    get state(): RuntimeState;
+    get initialized(): boolean;
+    get clips(): readonly Animation3DClip[];
+    get authoredCameraIds(): readonly string[];
+    get stateMachine(): HyaAnimation3DStateMachineRuntimeControl | null;
+    getEntity(nodeId: string): Entity | null;
+    getMaterial(materialId: string): PbrMaterial | null;
+    getModelAnimationClips(nodeId: string): readonly Animation3DClip[];
+    select(nodeIds: readonly string[]): void;
+    useAuthoredCamera(nodeId: string): void;
+    playClip(clipId: string, options?: HyaAnimation3DPlayOptions): HyaAnimation3DActionGroup;
+    removeActionGroup(group: HyaAnimation3DActionGroup | string): boolean;
+    update(deltaSeconds: number): void;
+    setTime(timeSeconds: number): void;
+    diagnostics(): HyaAnimation3DRuntimeDiagnostics;
+    destroy(): void;
+    private _initialize;
+    private _createMaterials;
+    private _createNodes;
+    private _createComponent;
+    private _attachHierarchy;
+    private _loadModels;
+    private _buildClipPartitions;
+    private _createStateMachineRuntime;
+    private _createSceneEndpoint;
+    private _matchModelBinding;
+    private _addPreviewLights;
+    private _assertActive;
+}
+export declare function createHyaAnimation3DRuntime(options: HyaAnimation3DRuntimeOptions): Promise<HyaAnimation3DRuntime>;
+export {};

package/dist/animation3d/hya/HyaAnimation3DStateMachineRuntime.d.ts

@@ -0,0 +1,65 @@
+import { ParticleEmitter3D } from '@haiyue/engine/components';
+import type { AnimationStateMachineDefinition } from '../../animation-state-machine/AnimationStateMachine.js';
+import { AnimationStateMachineController, type AnimationStateMachineActionOptions } from '../../animation-state-machine/runtime/index.js';
+import type { Animation3DClip } from '../Animation3DClip.js';
+import type { Animation3DPose } from '../Animation3DPose.js';
+import { Animation3DPoseBuffer } from '../Animation3DPoseBuffer.js';
+import type { Animation3DStateMachineDefinition } from '../Animation3DStateMachine.js';
+import { type Animation3DStateMachineActionRuntimeHandle } from '../runtime/integration/Animation3DStateMachineMixerAdapter.js';
+import { Animation3DMixerRuntime } from '../runtime/mixer/Mixer.js';
+export interface HyaAnimation3DStateMachinePartition {
+    readonly id: string;
+    readonly mixer: Animation3DMixerRuntime;
+    readonly clips: ReadonlyMap<string, Animation3DClip>;
+    /** Maps authored HYA binding ids to a model runtime's source binding ids. */
+    readonly bindingIds?: ReadonlyMap<string, string>;
+    readonly pose?: Animation3DPoseBuffer;
+    readonly apply: (pose: Animation3DPose) => void;
+}
+export interface HyaAnimation3DParticleCue {
+    readonly key: string;
+    readonly emitter: ParticleEmitter3D;
+    readonly start: number;
+    readonly end: number;
+}
+export interface HyaAnimation3DStateMachineRuntimeOptions {
+    readonly definition: AnimationStateMachineDefinition | Animation3DStateMachineDefinition;
+    readonly clips: readonly Animation3DClip[];
+    readonly partitions: readonly HyaAnimation3DStateMachinePartition[];
+    readonly particleCues?: ReadonlyMap<string, readonly HyaAnimation3DParticleCue[]>;
+}
+export declare class HyaAnimation3DStateMachineActionHandle {
+    readonly id: string;
+    readonly clipId: string;
+    readonly duration: number;
+    readonly loop: AnimationStateMachineActionOptions['loop'];
+    readonly children: readonly Animation3DStateMachineActionRuntimeHandle[];
+    readonly activeCueKeys: Set<string>;
+    targetTime: number;
+    traversal: number;
+    playing: boolean;
+    destroyed: boolean;
+    pendingDestroy: boolean;
+    constructor(id: string, clipId: string, duration: number, loop: AnimationStateMachineActionOptions['loop'], children: readonly Animation3DStateMachineActionRuntimeHandle[]);
+}
+/** Coordinates native scene, glTF model and Particle3D channels with one controller transaction. */
+export declare class HyaAnimation3DStateMachineRuntime {
+    readonly controller: AnimationStateMachineController<HyaAnimation3DStateMachineActionHandle>;
+    private readonly _partitions;
+    private readonly _port;
+    private _time;
+    private _destroyed;
+    constructor(options: HyaAnimation3DStateMachineRuntimeOptions);
+    get time(): number;
+    get liveActionCount(): number;
+    get liveBindingCount(): number;
+    get sideEffectOwnerCount(): number;
+    update(deltaSeconds: number): void;
+    evaluate(): void;
+    reset(): void;
+    destroy(): void;
+    private _runFrame;
+    private _openFrames;
+    private _cancelFrames;
+    private _requireActive;
+}