@haiyue/extensions 0.1.0

package/src/animation/runtime/mixer/Sampler.ts

@@ -0,0 +1,252 @@
+import type {
+  Animation2DBinding,
+  Animation2DDiscreteTrack,
+  Animation2DNumericTrack,
+  Animation2DTrack,
+} from './Types.js';
+
+/**
+ * Stateful allocation-free sampler. Rotation values are radians and LINEAR
+ * sampling follows the shortest signed arc in [-PI, PI).
+ */
+export class Animation2DSampler {
+  readonly track: Animation2DTrack;
+  readonly output: Float32Array;
+  discreteValue: unknown;
+
+  private _cursor = 0;
+
+  constructor(track: Animation2DTrack) {
+    validateTrack(track);
+    this.track = track;
+    this.output = new Float32Array(isNumericBinding(track.binding)
+      ? track.binding.valueSize!
+      : 0);
+  }
+
+  sample(timeSeconds: number, out: Float32Array = this.output): Float32Array | unknown {
+    if (!Number.isFinite(timeSeconds)) {
+      throw new RangeError(`Animation2D sample time must be finite; received ${timeSeconds}.`);
+    }
+    const keyIndex = this._findKey(timeSeconds);
+    if (!isNumericBinding(this.track.binding)) {
+      this.discreteValue = (this.track as Animation2DDiscreteTrack).values[keyIndex];
+      return this.discreteValue;
+    }
+
+    const track = this.track as Animation2DNumericTrack;
+    const size = track.binding.valueSize!;
+    if (out.length < size) {
+      throw new RangeError(`Animation2D sampler output requires ${size} values; received ${out.length}.`);
+    }
+    const times = track.times;
+    if (keyIndex >= times.length - 1 || track.interpolation === 'step') {
+      copyNumericKey(track, keyIndex, out);
+      return out;
+    }
+    const startTime = times[keyIndex]!;
+    const linearAlpha = (timeSeconds - startTime) / (times[keyIndex + 1]! - startTime);
+    const alpha = track.interpolation === 'cubic-bezier'
+      ? sampleCubicEasing(track.easings!, keyIndex, linearAlpha)
+      : linearAlpha;
+    const startOffset = keyIndex * size;
+    const endOffset = startOffset + size;
+    if (track.binding.strategy === 'rotation') {
+      const start = track.values[startOffset]!;
+      const delta = wrapAngle(track.values[endOffset]! - start);
+      out[0] = wrapAngle(start + delta * alpha);
+      return out;
+    }
+    if (track.spatialTangents) {
+      const tangentOffset = keyIndex * 4;
+      for (let component = 0; component < 2; component++) {
+        const start = track.values[startOffset + component]!;
+        const end = track.values[endOffset + component]!;
+        out[component] = cubicSpatialCoordinate(
+          alpha,
+          start,
+          start + track.spatialTangents[tangentOffset + component]!,
+          end + track.spatialTangents[tangentOffset + 2 + component]!,
+          end,
+        );
+      }
+      return out;
+    }
+    for (let component = 0; component < size; component++) {
+      const start = track.values[startOffset + component]!;
+      out[component] = start
+        + (track.values[endOffset + component]! - start) * alpha;
+    }
+    return out;
+  }
+
+  resetCursor(): void {
+    this._cursor = 0;
+  }
+
+  private _findKey(timeSeconds: number): number {
+    const times = this.track.times;
+    const last = times.length - 1;
+    if (last === 0 || timeSeconds <= times[0]!) {
+      this._cursor = 0;
+      return 0;
+    }
+    if (timeSeconds >= times[last]!) {
+      this._cursor = Math.max(0, last - 1);
+      return last;
+    }
+    let cursor = Math.min(this._cursor, last - 1);
+    if (timeSeconds >= times[cursor]! && timeSeconds < times[cursor + 1]!) return cursor;
+    if (timeSeconds >= times[cursor + 1]!) {
+      while (cursor + 1 < last && timeSeconds >= times[cursor + 1]!) cursor++;
+      this._cursor = cursor;
+      return cursor;
+    }
+    let low = 0;
+    let high = cursor;
+    while (low <= high) {
+      const middle = (low + high) >>> 1;
+      if (timeSeconds < times[middle]!) {
+        high = middle - 1;
+      } else if (timeSeconds >= times[middle + 1]!) {
+        low = middle + 1;
+      } else {
+        this._cursor = middle;
+        return middle;
+      }
+    }
+    this._cursor = Math.max(0, low);
+    return this._cursor;
+  }
+}
+
+export function wrapAngle(value: number): number {
+  const twoPi = Math.PI * 2;
+  let wrapped = (value + Math.PI) % twoPi;
+  if (wrapped < 0) wrapped += twoPi;
+  return wrapped - Math.PI;
+}
+
+export function isNumericBinding(binding: Animation2DBinding): boolean {
+  return binding.strategy === 'continuous' || binding.strategy === 'rotation';
+}
+
+function copyNumericKey(
+  track: Animation2DNumericTrack,
+  keyIndex: number,
+  out: Float32Array,
+): void {
+  const size = track.binding.valueSize!;
+  const offset = keyIndex * size;
+  for (let component = 0; component < size; component++) {
+    out[component] = track.values[offset + component]!;
+  }
+  if (track.binding.strategy === 'rotation') out[0] = wrapAngle(out[0]!);
+}
+
+function validateTrack(track: Animation2DTrack): void {
+  if (!track.id) throw new RangeError('Animation2D track id must not be empty.');
+  if (!track.binding.id) throw new RangeError('Animation2D binding id must not be empty.');
+  if (track.times.length === 0) {
+    throw new RangeError(`Animation2D track "${track.id}" must contain at least one key.`);
+  }
+  for (let index = 0; index < track.times.length; index++) {
+    const time = track.times[index]!;
+    if (!Number.isFinite(time) || (index > 0 && time <= track.times[index - 1]!)) {
+      throw new RangeError(`Animation2D track "${track.id}" times must be finite and strictly increasing.`);
+    }
+  }
+  if (isNumericBinding(track.binding)) {
+    const numericTrack = track as Animation2DNumericTrack;
+    const size = track.binding.valueSize ?? 0;
+    if (!Number.isInteger(size) || size <= 0) {
+      throw new RangeError(`Animation2D numeric binding "${track.binding.id}" requires a positive valueSize.`);
+    }
+    if (track.binding.strategy === 'rotation' && size !== 1) {
+      throw new RangeError(`Animation2D rotation binding "${track.binding.id}" must have valueSize 1.`);
+    }
+    const expected = track.times.length * size;
+    if (!(track.values instanceof Float32Array) || track.values.length !== expected) {
+      throw new RangeError(`Animation2D track "${track.id}" requires ${expected} numeric values.`);
+    }
+    if (numericTrack.interpolation === 'cubic-bezier') {
+      const expectedEasings = Math.max(0, track.times.length - 1) * 4;
+      if (!(numericTrack.easings instanceof Float32Array) || numericTrack.easings.length !== expectedEasings) {
+        throw new RangeError(`Animation2D track "${track.id}" requires ${expectedEasings} cubic easing values.`);
+      }
+      for (let index = 0; index < numericTrack.easings.length; index += 4) {
+        const x1 = numericTrack.easings[index]!;
+        const x2 = numericTrack.easings[index + 2]!;
+        if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1) {
+          throw new RangeError(`Animation2D track "${track.id}" cubic easing x controls must be in [0, 1].`);
+        }
+      }
+    } else if (numericTrack.easings !== undefined) {
+      throw new RangeError(`Animation2D track "${track.id}" easings require cubic-bezier interpolation.`);
+    }
+    if (numericTrack.spatialTangents !== undefined) {
+      const expectedTangents = Math.max(0, track.times.length - 1) * 4;
+      if (track.binding.path !== 'transform.position' || size !== 2) {
+        throw new RangeError(`Animation2D track "${track.id}" spatialTangents require transform.position/2.`);
+      }
+      if (numericTrack.interpolation === 'step') {
+        throw new RangeError(`Animation2D track "${track.id}" spatialTangents cannot use step.`);
+      }
+      if (!(numericTrack.spatialTangents instanceof Float32Array)
+        || numericTrack.spatialTangents.length !== expectedTangents) {
+        throw new RangeError(`Animation2D track "${track.id}" requires ${expectedTangents} spatialTangents.`);
+      }
+    }
+    return;
+  }
+  if (track.interpolation !== 'step') {
+    throw new RangeError(`Animation2D ${track.binding.strategy} track "${track.id}" must use step interpolation.`);
+  }
+  if (track.values.length !== track.times.length) {
+    throw new RangeError(`Animation2D track "${track.id}" requires one discrete value per key.`);
+  }
+}
+
+function sampleCubicEasing(easings: Float32Array, segment: number, x: number): number {
+  const offset = segment * 4;
+  const x1 = easings[offset]!;
+  const y1 = easings[offset + 1]!;
+  const x2 = easings[offset + 2]!;
+  const y2 = easings[offset + 3]!;
+  let parameter = x;
+  for (let iteration = 0; iteration < 6; iteration++) {
+    const estimate = cubicCoordinate(parameter, x1, x2) - x;
+    const derivative = cubicDerivative(parameter, x1, x2);
+    if (Math.abs(derivative) < 1e-6) break;
+    parameter = Math.min(1, Math.max(0, parameter - estimate / derivative));
+  }
+  return cubicCoordinate(parameter, y1, y2);
+}
+
+function cubicCoordinate(value: number, first: number, second: number): number {
+  const inverse = 1 - value;
+  return 3 * inverse * inverse * value * first
+    + 3 * inverse * value * value * second
+    + value * value * value;
+}
+
+function cubicDerivative(value: number, first: number, second: number): number {
+  const inverse = 1 - value;
+  return 3 * inverse * inverse * first
+    + 6 * inverse * value * (second - first)
+    + 3 * value * value * (1 - second);
+}
+
+function cubicSpatialCoordinate(
+  value: number,
+  start: number,
+  first: number,
+  second: number,
+  end: number,
+): number {
+  const inverse = 1 - value;
+  return inverse * inverse * inverse * start
+    + 3 * inverse * inverse * value * first
+    + 3 * inverse * value * value * second
+    + value * value * value * end;
+}

package/src/animation/runtime/mixer/Types.ts

@@ -0,0 +1,138 @@
+import type {
+  AnimationStateMachineBindingMask,
+  AnimationStateMachineBlendMode,
+  AnimationStateMachineLoopMode,
+} from '../../../animation-state-machine/AnimationStateMachine.js';
+
+export type Animation2DBindingStrategy =
+  | 'continuous'
+  | 'rotation'
+  | 'discrete'
+  | 'dominant';
+
+export interface Animation2DBinding {
+  /** Stable mask and pose channel id. */
+  readonly id: string;
+  /** Stable node, slot, component, or graph target id. */
+  readonly targetId: string;
+  /** Examples: transform.position, opacity, text, sprite, composite, mask. */
+  readonly path: string;
+  readonly strategy: Animation2DBindingStrategy;
+  /** Required for continuous and rotation bindings; rotation must use one value. */
+  readonly valueSize?: number;
+  /** Base used when a continuous layer has less than unit weight. */
+  readonly defaultValue?: Readonly<ArrayLike<number>> | unknown;
+}
+
+export type Animation2DInterpolation = 'step' | 'linear' | 'cubic-bezier';
+
+export interface Animation2DNumericTrack {
+  readonly id: string;
+  readonly binding: Animation2DBinding;
+  readonly interpolation: Animation2DInterpolation;
+  readonly times: Float32Array;
+  /** Tightly packed key values by binding.valueSize. */
+  readonly values: Float32Array;
+  /** Per-segment x1, y1, x2, y2 tuples for cubic-bezier interpolation. */
+  readonly easings?: Float32Array;
+  /** Relative outgoing/incoming spatial controls for transform.position. */
+  readonly spatialTangents?: Float32Array;
+}
+
+export interface Animation2DDiscreteTrack {
+  readonly id: string;
+  readonly binding: Animation2DBinding;
+  readonly interpolation: 'step';
+  /** One immutable/reference-stable value per key. */
+  readonly times: Float32Array;
+  readonly values: readonly unknown[];
+}
+
+export type Animation2DTrack =
+  | Animation2DNumericTrack
+  | Animation2DDiscreteTrack;
+
+export type Animation2DEffectKind = 'audio' | 'particle';
+export type Animation2DEffectLoopBehavior = 'continue' | 'restart';
+
+export interface Animation2DEffectCue {
+  readonly id: string;
+  readonly kind: Animation2DEffectKind;
+  readonly start: number;
+  /** Defaults to clip duration. The interval is [start, end). */
+  readonly end?: number;
+  /** Audio defaults to continue; particle defaults to restart. */
+  readonly loopBehavior?: Animation2DEffectLoopBehavior;
+  readonly payload?: unknown;
+}
+
+export interface Animation2DClip {
+  readonly format: 'haiyue-animation2d-clip@1';
+  readonly id: string;
+  readonly name: string;
+  readonly duration: number;
+  readonly tracks: readonly Animation2DTrack[];
+  readonly effects?: readonly Animation2DEffectCue[];
+}
+
+export type Animation2DEffectLifecycle =
+  | 'enter'
+  | 'exit'
+  | 'restart'
+  | 'loop'
+  | 'seek';
+
+export interface Animation2DEffectEvent {
+  readonly actionId: string;
+  readonly clipId: string;
+  readonly cue: Animation2DEffectCue;
+  readonly lifecycle: Animation2DEffectLifecycle;
+}
+
+export interface Animation2DPoseChannel {
+  readonly binding: Animation2DBinding;
+  /**
+   * Continuous and rotation channels expose a reused Float32Array. Discrete
+   * and dominant channels expose the winning authored value by reference.
+   */
+  readonly value: Readonly<Float32Array> | unknown;
+}
+
+export interface Animation2DPose {
+  readonly sequence: number;
+  readonly mixerTime: number;
+  readonly channels: readonly Animation2DPoseChannel[];
+  readonly effects: readonly Animation2DEffectEvent[];
+}
+
+export interface Animation2DMutablePose {
+  reset(mixerTime: number): void;
+  writeNumeric(binding: Animation2DBinding, value: ArrayLike<number>): void;
+  writeDiscrete(binding: Animation2DBinding, value: unknown): void;
+  emit(effect: Animation2DEffectEvent): void;
+  seal(): Animation2DPose;
+}
+
+export interface Animation2DActionOptions {
+  readonly id?: string;
+  readonly loop?: AnimationStateMachineLoopMode;
+  readonly repetitions?: number;
+  readonly clampWhenFinished?: boolean;
+  readonly timeScale?: number;
+  readonly weight?: number;
+  /** Ascending layers are applied in order; a higher layer overrides a lower one. */
+  readonly layer?: number;
+  readonly blendMode?: AnimationStateMachineBlendMode;
+  readonly mask?: AnimationStateMachineBindingMask;
+}
+
+export type Animation2DActionStatus =
+  | 'idle'
+  | 'running'
+  | 'paused'
+  | 'finished'
+  | 'stopped';
+
+export type Animation2DLoopMode = AnimationStateMachineLoopMode;
+export type Animation2DBlendMode = AnimationStateMachineBlendMode;
+export type Animation2DBindingMask = AnimationStateMachineBindingMask;

package/src/animation/runtime/mixer/index.ts

@@ -0,0 +1,31 @@
+export { Animation2DActionRuntime } from './Action.js';
+export type {
+  Animation2DActionOwner,
+  Animation2DActionSynchronizedState,
+  Animation2DActionTrackRuntime,
+} from './Action.js';
+export { Animation2DMixerRuntime } from './Mixer.js';
+export { Animation2DPoseBuffer } from './PoseBuffer.js';
+export { Animation2DSampler, wrapAngle } from './Sampler.js';
+export type {
+  Animation2DActionOptions,
+  Animation2DActionStatus,
+  Animation2DBinding,
+  Animation2DBindingMask,
+  Animation2DBindingStrategy,
+  Animation2DBlendMode,
+  Animation2DClip,
+  Animation2DDiscreteTrack,
+  Animation2DEffectCue,
+  Animation2DEffectEvent,
+  Animation2DEffectKind,
+  Animation2DEffectLifecycle,
+  Animation2DEffectLoopBehavior,
+  Animation2DInterpolation,
+  Animation2DLoopMode,
+  Animation2DMutablePose,
+  Animation2DNumericTrack,
+  Animation2DPose,
+  Animation2DPoseChannel,
+  Animation2DTrack,
+} from './Types.js';

package/src/animation-state-machine/AnimationStateMachine.ts

@@ -0,0 +1,146 @@
+export type AnimationStateMachineLoopMode =
+  | 'once'
+  | 'repeat'
+  | 'ping-pong';
+
+export type AnimationStateMachineBlendMode =
+  | 'override'
+  | 'additive';
+
+/**
+ * A state-machine mask addresses logical animation bindings. The concrete 2D
+ * or 3D mixer decides how those stable ids resolve to runtime targets.
+ */
+export interface AnimationStateMachineBindingMask {
+  /** Empty or omitted include means all bindings are eligible. */
+  readonly include?: readonly string[];
+  readonly exclude?: readonly string[];
+}
+
+export type AnimationStateMachineParameterDefinition =
+  | 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 AnimationStateMachineTransitionCondition =
+  | 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 AnimationStateMachineClipMotion {
+  readonly kind: 'clip';
+  /**
+   * Mixer-owned source id. It may identify a 3D clip, a HYA composition, or
+   * another animation source understood by the selected mixer port.
+   */
+  readonly clipId: string;
+}
+
+export interface AnimationStateMachineBlend1DChild {
+  readonly threshold: number;
+  readonly motion: AnimationStateMachineMotionDefinition;
+}
+
+export interface AnimationStateMachineBlend1DMotion {
+  readonly kind: 'blend-1d';
+  readonly parameter: string;
+  readonly children: readonly AnimationStateMachineBlend1DChild[];
+}
+
+export interface AnimationStateMachineBlend2DChild {
+  readonly position: readonly [number, number];
+  readonly motion: AnimationStateMachineMotionDefinition;
+}
+
+export interface AnimationStateMachineBlend2DMotion {
+  readonly kind: 'blend-2d';
+  readonly algorithm: 'cartesian' | 'directional';
+  readonly parameterX: string;
+  readonly parameterY: string;
+  readonly children: readonly AnimationStateMachineBlend2DChild[];
+}
+
+export type AnimationStateMachineMotionDefinition =
+  | AnimationStateMachineClipMotion
+  | AnimationStateMachineBlend1DMotion
+  | AnimationStateMachineBlend2DMotion;
+
+export interface AnimationStateMachineStateDefinition {
+  readonly id: string;
+  readonly name: string;
+  readonly motion: AnimationStateMachineMotionDefinition;
+  readonly speed?: number;
+  readonly speedParameter?: string;
+  readonly loop?: AnimationStateMachineLoopMode;
+}
+
+export type AnimationStateMachineTransitionInterruption =
+  | 'none'
+  | 'source'
+  | 'destination'
+  | 'source-then-destination'
+  | 'destination-then-source';
+
+export interface AnimationStateMachineTransitionDefinition {
+  readonly id: string;
+  /** '*' means any state in the same layer. */
+  readonly from: string | '*';
+  readonly to: string;
+  readonly conditions: readonly AnimationStateMachineTransitionCondition[];
+  readonly duration: number;
+  readonly hasExitTime?: boolean;
+  readonly exitTime?: number;
+  readonly destinationOffset?: number;
+  readonly interruption?: AnimationStateMachineTransitionInterruption;
+}
+
+export interface AnimationStateMachineLayer {
+  readonly id: string;
+  readonly name: string;
+  readonly initialStateId: string;
+  readonly states: readonly AnimationStateMachineStateDefinition[];
+  /** Declaration order is transition priority. */
+  readonly transitions: readonly AnimationStateMachineTransitionDefinition[];
+  readonly blendMode?: AnimationStateMachineBlendMode;
+  readonly weight?: number;
+  readonly mask?: AnimationStateMachineBindingMask;
+}
+
+/**
+ * Dimension-neutral serializable state-machine definition. Runtime controller
+ * state and concrete mixer objects are intentionally not stored here.
+ */
+export interface AnimationStateMachineDefinition {
+  readonly format: 'haiyue-animation-state-machine@1';
+  readonly id: string;
+  readonly name: string;
+  readonly parameters: readonly AnimationStateMachineParameterDefinition[];
+  readonly layers: readonly AnimationStateMachineLayer[];
+}

package/src/animation-state-machine/AnimationStateMachineChannels.ts

@@ -0,0 +1,116 @@
+import {
+  HYA_STATE_MACHINE_CHANNEL_REGISTRY,
+  hyaStateMachineChannelCapability,
+  type HyaStateMachineChannelCapability,
+  type HyaStateMachineChannelId,
+  type HyaStateMachineDefinition,
+  type HyaStateMachineMotion,
+} from '@haiyue/animation-spec';
+
+export {
+  HYA_STATE_MACHINE_CHANNEL_REGISTRY,
+  hyaStateMachineChannelCapability,
+};
+export type {
+  HyaStateMachineChannelCapability,
+  HyaStateMachineChannelId,
+};
+
+export type AnimationStateMachineChannelDiagnosticCode =
+  | NonNullable<HyaStateMachineChannelCapability['diagnosticCode']>
+  | 'W_STATE_MACHINE_CHANNEL_AUDIO_AUTOPLAY_REJECTED';
+
+export interface AnimationStateMachineChannelDiagnostic {
+  readonly code: AnimationStateMachineChannelDiagnosticCode;
+  readonly severity: 'warning' | 'error';
+  readonly channelId: HyaStateMachineChannelId;
+  readonly path: string;
+  readonly message: string;
+}
+
+export class AnimationStateMachineChannelError extends Error {
+  readonly name = 'AnimationStateMachineChannelError';
+
+  constructor(readonly diagnostic: AnimationStateMachineChannelDiagnostic) {
+    super(`${diagnostic.message} (${diagnostic.path})`);
+  }
+}
+
+/**
+ * Audio owns one HTMLMediaElement playhead and is intentionally not amplitude
+ * mixed. It is executable only when the graph can never overlap two motions.
+ */
+export function audioStateMachineCompatibilityDiagnostic(
+  definition: HyaStateMachineDefinition,
+  path = '$.stateMachine',
+): AnimationStateMachineChannelDiagnostic | null {
+  const capability = hyaStateMachineChannelCapability('audio');
+  if (definition.layers.length !== 1) {
+    return audioRangeDiagnostic(`${path}.layers`, 'Audio requires exactly one state-machine layer.');
+  }
+  const layer = definition.layers[0]!;
+  if ((layer.weight ?? 1) !== 1 || (layer.blendMode ?? 'override') !== 'override') {
+    return audioRangeDiagnostic(
+      `${path}.layers[0]`,
+      'Audio requires one full-weight override layer because media amplitude is not pose-mixable.',
+    );
+  }
+  for (let stateIndex = 0; stateIndex < layer.states.length; stateIndex++) {
+    if (motionContainsBlendTree(layer.states[stateIndex]!.motion)) {
+      return audioRangeDiagnostic(
+        `${path}.layers[0].states[${stateIndex}].motion`,
+        'Audio cannot run inside a Blend Tree because two media playheads would overlap.',
+      );
+    }
+  }
+  for (let transitionIndex = 0; transitionIndex < layer.transitions.length; transitionIndex++) {
+    if (layer.transitions[transitionIndex]!.duration > 0) {
+      return audioRangeDiagnostic(
+        `${path}.layers[0].transitions[${transitionIndex}].duration`,
+        'Audio transitions must be immediate; non-zero cross-fades are an unmixable media range.',
+      );
+    }
+  }
+  if (capability.transition !== 'immediate-only') {
+    throw new Error('The canonical audio channel contract is internally inconsistent.');
+  }
+  return null;
+}
+
+export function assertAudioStateMachineCompatible(
+  definition: HyaStateMachineDefinition,
+  path?: string,
+): void {
+  const diagnostic = audioStateMachineCompatibilityDiagnostic(definition, path);
+  if (diagnostic) throw new AnimationStateMachineChannelError(diagnostic);
+}
+
+export function audioAutoplayRejectedDiagnostic(
+  path: string,
+  reason?: unknown,
+): AnimationStateMachineChannelDiagnostic {
+  const suffix = reason instanceof Error && reason.message
+    ? ` Browser reason: ${reason.message}`
+    : '';
+  return Object.freeze({
+    code: 'W_STATE_MACHINE_CHANNEL_AUDIO_AUTOPLAY_REJECTED',
+    severity: 'warning',
+    channelId: 'audio',
+    path,
+    message: `Audio play() was rejected; the playhead remains paused until a later user-authorized resume.${suffix}`,
+  });
+}
+
+function audioRangeDiagnostic(path: string, message: string): AnimationStateMachineChannelDiagnostic {
+  return Object.freeze({
+    code: 'E_STATE_MACHINE_CHANNEL_AUDIO_UNMIXABLE_RANGE',
+    severity: 'error',
+    channelId: 'audio',
+    path,
+    message,
+  });
+}
+
+function motionContainsBlendTree(motion: HyaStateMachineMotion): boolean {
+  return motion.kind !== 'clip';
+}