@haiyue/extensions 0.1.0 → 0.2.0

package/src/animation-state-machine/runtime/AnimationStateMachineMixerPort.ts

@@ -1,54 +0,0 @@
-import type {
-  AnimationStateMachineBindingMask,
-  AnimationStateMachineBlendMode,
-  AnimationStateMachineLoopMode,
-} from '../AnimationStateMachine.js';
-
-/**
- * The only action shape the state-machine runtime needs. Concrete mixer
- * actions are adapted to this interface by the integration layer.
- */
-export interface AnimationStateMachineActionHandle {
-  /** Source clip duration in seconds. */
-  readonly duration: number;
-}
-
-export interface AnimationStateMachineActionOptions {
-  readonly layerId: string;
-  readonly stateId: string;
-  readonly loop: AnimationStateMachineLoopMode;
-  readonly blendMode: AnimationStateMachineBlendMode;
-  readonly mask: AnimationStateMachineBindingMask | null;
-}
-
-/**
- * Internal boundary between the state-machine controller and an animation
- * mixer. It deliberately has no dependency on Animation3DMixer or
- * Animation3DAction.
- */
-export interface AnimationStateMachineMixerPort<
-  TAction extends AnimationStateMachineActionHandle =
-    AnimationStateMachineActionHandle,
-> {
-  createAction(
-    clipId: string,
-    options: AnimationStateMachineActionOptions,
-  ): TAction;
-  play(action: TAction): void;
-  stop(action: TAction): void;
-  fade(action: TAction, targetWeight: number, durationSeconds: number): void;
-  setWeight(action: TAction, weight: number): void;
-  setTime(action: TAction, timeSeconds: number): void;
-  setTimeScale(action: TAction, timeScale: number): void;
-  destroyAction(action: TAction): void;
-}
-
-/** Compatibility aliases for the original 3D-prefixed runtime boundary. */
-export type Animation3DStateMachineActionHandle =
-  AnimationStateMachineActionHandle;
-export type Animation3DStateMachineActionOptions =
-  AnimationStateMachineActionOptions;
-export type Animation3DStateMachineMixerPort<
-  TAction extends AnimationStateMachineActionHandle =
-    AnimationStateMachineActionHandle,
-> = AnimationStateMachineMixerPort<TAction>;

package/src/animation-state-machine/runtime/index.ts

@@ -1,47 +0,0 @@
-export {
-  evaluateAnimation3DBlend1DWeights as evaluateAnimationBlend1DWeights,
-  evaluateAnimation3DBlend2DWeights as evaluateAnimationBlend2DWeights,
-} from './AnimationStateMachineBlendTreeWeights.js';
-export {
-  AnimationStateMachineValidationError,
-  compileAnimationStateMachineDefinition as compileAnimationStateMachine,
-  compileAnimationStateMachineDefinition,
-  validateAnimationStateMachineDefinition,
-} from './AnimationStateMachineCompiler.js';
-export type {
-  Animation3DStateMachineValidationCode as AnimationStateMachineValidationCode,
-  Animation3DStateMachineValidationIssue as AnimationStateMachineValidationIssue,
-  CompiledAnimation3DBlend1DChild as CompiledAnimationBlend1DChild,
-  CompiledAnimation3DBlend1DMotion as CompiledAnimationBlend1DMotion,
-  CompiledAnimation3DBlend2DChild as CompiledAnimationBlend2DChild,
-  CompiledAnimation3DBlend2DMotion as CompiledAnimationBlend2DMotion,
-  CompiledAnimation3DClipMotion as CompiledAnimationClipMotion,
-  CompiledAnimation3DCondition as CompiledAnimationCondition,
-  CompiledAnimation3DConditionOperator as CompiledAnimationConditionOperator,
-  CompiledAnimation3DLayer as CompiledAnimationLayer,
-  CompiledAnimation3DMotion as CompiledAnimationMotion,
-  CompiledAnimation3DParameter as CompiledAnimationParameter,
-  CompiledAnimation3DParameterType as CompiledAnimationParameterType,
-  CompiledAnimation3DState as CompiledAnimationState,
-  CompiledAnimation3DStateMachine as CompiledAnimationStateMachine,
-  CompiledAnimation3DTransition as CompiledAnimationTransition,
-} from './AnimationStateMachineCompiler.js';
-export {
-  Animation3DStateMachineController as AnimationStateMachineController,
-  createAnimation3DStateMachineController as createAnimationStateMachineController,
-  runAnimationStateMachineControllerUpdateTransaction,
-} from './AnimationStateMachineController.js';
-export type {
-  Animation3DStateMachineControllerOptions as AnimationStateMachineControllerOptions,
-  Animation3DStateMachineControllerStatus as AnimationStateMachineControllerStatus,
-  Animation3DStateMachineLayerSnapshot as AnimationStateMachineLayerSnapshot,
-} from './AnimationStateMachineController.js';
-export type {
-  AnimationStateMachineActionHandle,
-  AnimationStateMachineActionOptions,
-  AnimationStateMachineMixerPort,
-} from './AnimationStateMachineMixerPort.js';
-export {
-  Animation2DStateMachineActionRuntimeHandle,
-  Animation2DStateMachineMixerAdapter,
-} from './Animation2DStateMachineMixerAdapter.js';

package/src/animation.ts

@@ -1,33 +0,0 @@
-export { Animation2DComponent } from './animation/Animation2DComponent';
-export type { Animation2DComponentOptions, Animation2DRuntimeStats } from './animation/Animation2DComponent';
-export { Animation2DSystem } from './animation/Animation2DSystem';
-export type { Animation2DSystemOptions } from './animation/Animation2DSystem';
-export { Animation2DRenderSystem } from './animation/Animation2DRenderSystem';
-export type { Animation2DRenderStats, Animation2DRenderSystemOptions } from './animation/Animation2DRenderSystem';
-export { tessellateAnimationPath } from './animation/AnimationPathTessellator';
-export { createAnimationAssetLoader, HAIYUE_ANIMATION_ASSET_TYPE } from './animation/AnimationAssetLoader';
-export type { AnimationAssetLoaderOptions } from './animation/AnimationAssetLoader';
-export { Animation2DExtensionRegistry } from './animation/Animation2DExtensionRegistry';
-export type {
-  Animation2DExtensionContext,
-  Animation2DExtensionHandler,
-  Animation2DExtensionInstance,
-} from './animation/Animation2DExtensionRegistry';
-export {
-  createAnimation2DStateMachineController,
-} from './animation/Animation2DStateMachine';
-export type {
-  AnimationStateMachineDefinition,
-} from './animation-state-machine/AnimationStateMachine';
-export {
-  AnimationStateMachineController,
-  AnimationStateMachineValidationError,
-  compileAnimationStateMachine,
-  validateAnimationStateMachineDefinition,
-} from './animation-state-machine/runtime/index';
-export type {
-  AnimationStateMachineControllerOptions,
-  AnimationStateMachineLayerSnapshot,
-  AnimationStateMachineMixerPort,
-  AnimationStateMachineValidationIssue,
-} from './animation-state-machine/runtime/index';

package/src/animation3d/Animation3DAction.ts

@@ -1,73 +0,0 @@
-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/src/animation3d/Animation3DBinding.ts

@@ -1,116 +0,0 @@
-/**
- * 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/src/animation3d/Animation3DClip.ts

@@ -1,22 +0,0 @@
-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/src/animation3d/Animation3DError.ts

@@ -1,34 +0,0 @@
-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 class Animation3DError extends Error {
-  readonly code: Animation3DErrorCode;
-  readonly details: Animation3DErrorDetails;
-
-  constructor(
-    code: Animation3DErrorCode,
-    message: string,
-    details: Animation3DErrorDetails = {},
-  ) {
-    super(message);
-    this.name = 'Animation3DError';
-    this.code = code;
-    this.details = Object.freeze({ ...details });
-  }
-}

package/src/animation3d/Animation3DMixer.ts

@@ -1,82 +0,0 @@
-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';
-import { Animation3DMixerRuntime } from './runtime/mixer/Mixer.js';
-import {
-  registerAnimation3DMixerRuntime,
-} from './runtime/mixer/Animation3DMixerRuntimeStore.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 class Animation3DMixer {
-  #runtime: Animation3DMixerRuntime;
-
-  constructor(resolver: Animation3DBindingResolver) {
-    this.#runtime = new Animation3DMixerRuntime(resolver);
-    registerAnimation3DMixerRuntime(this, this.#runtime);
-  }
-
-  get state(): Animation3DMixerState { return this.#runtime.state; }
-  get resolver(): Animation3DBindingResolver { return this.#runtime.resolver; }
-  get actions(): readonly Animation3DAction[] { return this.#runtime.actions; }
-  get time(): number { return this.#runtime.time; }
-  get timeScale(): number { return this.#runtime.timeScale; }
-  set timeScale(value: number) { this.#runtime.timeScale = value; }
-
-  createAction(
-    clip: Animation3DClip,
-    options?: Animation3DActionOptions,
-  ): Animation3DAction {
-    return this.#runtime.createAction(clip, options);
-  }
-
-  getAction(actionId: string): Animation3DAction | null {
-    return this.#runtime.getAction(actionId);
-  }
-
-  removeAction(action: Animation3DAction | string): boolean {
-    return this.#runtime.removeAction(action);
-  }
-
-  stopAllActions(): this {
-    this.#runtime.stopAllActions();
-    return this;
-  }
-
-  update(
-    deltaSeconds: number,
-    out: Animation3DMutablePose,
-  ): Animation3DPose {
-    return this.#runtime.update(deltaSeconds, out);
-  }
-
-  evaluate(out: Animation3DMutablePose): Animation3DPose {
-    return this.#runtime.evaluate(out);
-  }
-
-  setTime(
-    timeSeconds: number,
-    out: Animation3DMutablePose,
-  ): Animation3DPose {
-    return this.#runtime.setTime(timeSeconds, out);
-  }
-
-  destroy(): void {
-    this.#runtime.destroy();
-  }
-}

package/src/animation3d/Animation3DPose.ts

@@ -1,100 +0,0 @@
-import type {
-  Animation3DBinding,
-  Animation3DBindingResolver,
-  Animation3DResolvedBinding,
-} from './Animation3DBinding.js';
-import type { Animation3DEvent } from './Animation3DClip.js';
-import { Animation3DError } from './Animation3DError.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;
-}
-
-interface Animation3DPoseApplierState {
-  readonly resolver: Animation3DBindingResolver;
-  resolverRevision: number;
-  readonly resolvedBindings: Map<
-    string,
-    Animation3DResolvedBinding | null
-  >;
-}
-
-const POSE_APPLIER_STATES = new WeakMap<
-  Animation3DPoseApplier,
-  Animation3DPoseApplierState
->();
-
-/**
- * Applies pose channels through a revision-aware binding resolver cache.
- * Resolver misses fail explicitly and never write to a fallback target.
- */
-export class Animation3DPoseApplier {
-  constructor(resolver: Animation3DBindingResolver) {
-    POSE_APPLIER_STATES.set(this, {
-      resolver,
-      resolverRevision: Number.NaN,
-      resolvedBindings: new Map(),
-    });
-  }
-
-  apply(pose: Animation3DPose): void {
-    const state = POSE_APPLIER_STATES.get(this)!;
-    const { resolver } = state;
-    if (state.resolverRevision !== resolver.revision) {
-      state.resolverRevision = resolver.revision;
-      state.resolvedBindings.clear();
-    }
-    for (let index = 0; index < pose.channels.length; index++) {
-      const channel = pose.channels[index]!;
-      const bindingId = channel.binding.id;
-      let resolved = state.resolvedBindings.get(bindingId);
-      if (resolved === undefined && !state.resolvedBindings.has(bindingId)) {
-        resolved = resolver.resolve(channel.binding);
-        state.resolvedBindings.set(bindingId, resolved);
-      }
-      if (!resolved) {
-        throw new Animation3DError(
-          'resolver-miss',
-          `Animation3D binding resolver could not resolve "${bindingId}".`,
-          { resolver: 'binding', bindingId },
-        );
-      }
-      resolved.write(channel.value);
-    }
-  }
-}

package/src/animation3d/Animation3DPoseBuffer.ts

@@ -1,85 +0,0 @@
-import type { Animation3DBinding } from './Animation3DBinding.js';
-import type {
-  Animation3DMutablePose,
-  Animation3DPose,
-  Animation3DPoseChannel,
-  Animation3DPoseEvent,
-} from './Animation3DPose.js';
-
-class ReusablePoseChannel implements Animation3DPoseChannel {
-  binding: Animation3DBinding;
-  value: Float32Array;
-
-  constructor(binding: Animation3DBinding) {
-    this.binding = binding;
-    this.value = new Float32Array(binding.valueSize);
-  }
-
-  write(binding: Animation3DBinding, source: ArrayLike<number>): void {
-    this.binding = binding;
-    if (this.value.length !== binding.valueSize) {
-      this.value = new Float32Array(binding.valueSize);
-    }
-    for (let index = 0; index < binding.valueSize; index++) {
-      this.value[index] = source[index] ?? 0;
-    }
-  }
-}
-
-/**
- * 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 class Animation3DPoseBuffer implements Animation3DMutablePose, Animation3DPose {
-  private readonly _channelPool: ReusablePoseChannel[] = [];
-  private readonly _channels: ReusablePoseChannel[] = [];
-  private readonly _events: Animation3DPoseEvent[] = [];
-  private _sequence = 0;
-  private _mixerTime = 0;
-  private _sealed = true;
-
-  get sequence(): number { return this._sequence; }
-  get mixerTime(): number { return this._mixerTime; }
-  get channels(): readonly Animation3DPoseChannel[] { return this._channels; }
-  get events(): readonly Animation3DPoseEvent[] { return this._events; }
-
-  reset(mixerTime: number): void {
-    if (!Number.isFinite(mixerTime)) {
-      throw new RangeError(`Animation3D pose mixerTime must be finite; received ${mixerTime}.`);
-    }
-    this._mixerTime = mixerTime;
-    this._channels.length = 0;
-    this._events.length = 0;
-    this._sealed = false;
-  }
-
-  write(binding: Animation3DBinding, value: ArrayLike<number>): void {
-    if (value.length < binding.valueSize) {
-      throw new RangeError(
-        `Animation3D pose channel "${binding.id}" requires ${binding.valueSize} values; received ${value.length}.`,
-      );
-    }
-    const index = this._channels.length;
-    let channel = this._channelPool[index];
-    if (!channel) {
-      channel = new ReusablePoseChannel(binding);
-      this._channelPool.push(channel);
-    }
-    channel.write(binding, value);
-    this._channels.push(channel);
-  }
-
-  emit(event: Animation3DPoseEvent): void {
-    this._events.push(event);
-  }
-
-  seal(): Animation3DPose {
-    if (!this._sealed) {
-      this._sequence++;
-      this._sealed = true;
-    }
-    return this;
-  }
-}