@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/headless-test/runtime-animation.mjs

@@ -0,0 +1,1173 @@
+export function createHeadlessAnimationRuntime() {
+  let nextAnimationTimelineId = 1;
+  let nextAnimationListenerSeq = 1;
+  const animationTimelines = new Map();
+  const ANIMATION_PHASE_TRANSITION_COMPLETE = 0;
+  const ANIMATION_PHASE_MARKER_EVENT = 1;
+  const ANIMATION_PHASE_CLIP_COMPLETE = 2;
+  const animationResultOk = (extra = {}) => ({ ok: true, reason: null, ...extra });
+  const animationResultErr = (reason) => ({ ok: false, reason });
+  const animationIsValidTimelineId = (value) => Number.isInteger(value) && value > 0;
+  const animationNormalizeDuration = (value) => (
+    Number.isFinite(value) && Number(value) > 0 ? Number(value) : null
+  );
+  const animationNormalizeTime = (value) => (
+    Number.isFinite(value) && Number(value) >= 0 ? Number(value) : null
+  );
+  const animationNormalizeSpeed = (value) => (
+    Number.isFinite(value) && Number(value) >= 0 ? Number(value) : null
+  );
+  const animationNormalizeOrder = (value) => (
+    Number.isFinite(value) ? Number(value) : 0
+  );
+  const animationNormalizeTransitionDuration = (value) => (
+    Number.isFinite(value) && Number(value) > 0 ? Number(value) : null
+  );
+  const animationNormalizeEventTag = (value) => (
+    typeof value === 'string' && value.length > 0 ? value : null
+  );
+  const animationClampTime = (time, duration) => Math.max(0, Math.min(time, duration));
+  const animationSortedTimelineIds = () => [...animationTimelines.keys()].sort((a, b) => a - b);
+  const animationResolveTimeline = (timelineId) => {
+    if (!animationIsValidTimelineId(timelineId)) {
+      return { timeline: null, reason: 'invalid_timeline_id' };
+    }
+    const timeline = animationTimelines.get(timelineId);
+    if (!timeline) {
+      return { timeline: null, reason: 'missing_timeline' };
+    }
+    return { timeline, reason: null };
+  };
+  const animationTransitionSnapshot = (transition) => {
+    if (!transition) return null;
+    const blend = transition.duration > 0
+      ? Math.max(0, Math.min(1, transition.elapsed / transition.duration))
+      : 1;
+    return {
+      active: true,
+      duration: transition.duration,
+      elapsed: transition.elapsed,
+      targetTime: transition.targetTime,
+      blend,
+      paused: transition.paused,
+    };
+  };
+  const animationSnapshot = (timeline) => ({
+    timelineId: timeline.id,
+    duration: timeline.duration,
+    time: timeline.time,
+    normalizedTime: timeline.duration > 0 ? timeline.time / timeline.duration : 0,
+    playing: timeline.playing,
+    loop: timeline.loop,
+    speed: timeline.speed,
+    completed: timeline.completed,
+    loops: timeline.loops,
+    transition: animationTransitionSnapshot(timeline.transition),
+  });
+  const animationEnqueueCallbacks = (pending, timeline, phase, callbacks, payload) => {
+    for (const callback of callbacks) {
+      pending.push({
+        timelineId: timeline.id,
+        phase,
+        order: callback.order,
+        seq: callback.seq,
+        fn: callback.fn,
+        payload,
+      });
+    }
+  };
+  const animationSortPendingCallbacks = (pending) => {
+    pending.sort((a, b) => (
+      (a.timelineId - b.timelineId)
+      || (a.phase - b.phase)
+      || (a.order - b.order)
+      || (a.seq - b.seq)
+    ));
+  };
+  const animationDispatchPendingCallbacks = (pending) => {
+    for (const entry of pending) {
+      try {
+        entry.fn(entry.payload);
+      } catch (_) {
+        // callback exceptions are swallowed to preserve deterministic progression
+      }
+    }
+  };
+  let nextAtlasId = 1;
+  let nextAtlasClipId = 1;
+  const animationAtlases = new Map();
+  const animationAtlasClips = new Map();
+  const ANIMATION_ATLAS_DEFAULT_FRAME_DURATION = 1 / 12;
+  const ANIMATION_ATLAS_EPSILON = 1e-9;
+  const ANIMATION_ATLAS_MAX_STEP_ITERATIONS = 2048;
+  const animationIsPlainObject = (value) => (
+    !!value && typeof value === 'object' && !Array.isArray(value)
+  );
+  const animationNormalizeAtlasImage = (value) => {
+    if (typeof value !== 'string') return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  };
+  const animationNormalizeAtlasKey = (value) => (
+    typeof value === 'string' && value.length > 0 ? value : null
+  );
+  const animationNormalizeAtlasFrameDuration = (value) => (
+    Number.isFinite(value) && Number(value) > 0 ? Number(value) : null
+  );
+  const animationNormalizeAtlasFrameRect = (value) => {
+    if (!animationIsPlainObject(value)) return null;
+    const x = Number(value.x);
+    const y = Number(value.y);
+    const w = Number(value.w);
+    const h = Number(value.h);
+    if (![x, y, w, h].every((entry) => Number.isFinite(entry))) return null;
+    if (x < 0 || y < 0 || w <= 0 || h <= 0) return null;
+    return { x, y, w, h };
+  };
+  const animationParseAtlasFrameEntry = (entry) => {
+    if (!animationIsPlainObject(entry)) return { ok: false, reason: 'invalid_atlas_frame_entry' };
+    if (entry.rotated === true || entry.trimmed === true) {
+      return { ok: false, reason: 'unsupported_atlas_frame_flags' };
+    }
+    const rectSource = animationIsPlainObject(entry.frame) ? entry.frame : entry;
+    const rect = animationNormalizeAtlasFrameRect(rectSource);
+    if (!rect) return { ok: false, reason: 'invalid_atlas_frame_rect' };
+    const hasDuration = Object.prototype.hasOwnProperty.call(entry, 'duration');
+    const duration = hasDuration
+      ? animationNormalizeAtlasFrameDuration(entry.duration)
+      : null;
+    if (hasDuration && duration == null) {
+      return { ok: false, reason: 'invalid_atlas_frame_duration' };
+    }
+    return { ok: true, rect, duration };
+  };
+  const animationParseAtlasFrames = (value) => {
+    if (!animationIsPlainObject(value)) return { ok: false, reason: 'invalid_atlas_frames' };
+    const entries = Object.entries(value);
+    if (entries.length === 0) return { ok: false, reason: 'invalid_atlas_frames' };
+    const frames = new Map();
+    const frameKeys = [];
+    for (const [rawKey, rawEntry] of entries) {
+      const frameKey = animationNormalizeAtlasKey(rawKey);
+      if (frameKey == null) return { ok: false, reason: 'invalid_atlas_frame_key' };
+      const parsedEntry = animationParseAtlasFrameEntry(rawEntry);
+      if (!parsedEntry.ok) return parsedEntry;
+      frames.set(frameKey, {
+        key: frameKey,
+        x: parsedEntry.rect.x,
+        y: parsedEntry.rect.y,
+        w: parsedEntry.rect.w,
+        h: parsedEntry.rect.h,
+        duration: parsedEntry.duration,
+      });
+      frameKeys.push(frameKey);
+    }
+    return { ok: true, frames, frameKeys };
+  };
+  const animationParseAtlasClipFrames = (value, frames) => {
+    if (!Array.isArray(value) || value.length === 0) {
+      return { ok: false, reason: 'invalid_atlas_clip_frames' };
+    }
+    const keys = [];
+    for (const rawEntry of value) {
+      const key = animationNormalizeAtlasKey(rawEntry);
+      if (key == null) return { ok: false, reason: 'invalid_atlas_clip_frames' };
+      if (!frames.has(key)) return { ok: false, reason: 'missing_atlas_frame' };
+      keys.push(key);
+    }
+    return { ok: true, keys };
+  };
+  const animationParseAtlasClips = (value, frames) => {
+    if (value == null) return { ok: true, clips: new Map() };
+    if (!animationIsPlainObject(value)) return { ok: false, reason: 'invalid_atlas_clips' };
+    const clips = new Map();
+    for (const [rawClipKey, rawClip] of Object.entries(value)) {
+      const clipKey = animationNormalizeAtlasKey(rawClipKey);
+      if (clipKey == null) return { ok: false, reason: 'invalid_atlas_clip_key' };
+      if (!animationIsPlainObject(rawClip)) return { ok: false, reason: 'invalid_atlas_clip' };
+      const frameParse = animationParseAtlasClipFrames(rawClip.frames, frames);
+      if (!frameParse.ok) return frameParse;
+      let frameDuration = null;
+      if (Object.prototype.hasOwnProperty.call(rawClip, 'frameDuration')) {
+        frameDuration = animationNormalizeAtlasFrameDuration(rawClip.frameDuration);
+        if (frameDuration == null) return { ok: false, reason: 'invalid_atlas_clip_duration' };
+      }
+      const loop = Object.prototype.hasOwnProperty.call(rawClip, 'loop')
+        ? rawClip.loop
+        : true;
+      if (typeof loop !== 'boolean') return { ok: false, reason: 'invalid_atlas_clip_loop' };
+      clips.set(clipKey, {
+        key: clipKey,
+        frames: frameParse.keys,
+        frameDuration,
+        loop,
+      });
+    }
+    return { ok: true, clips };
+  };
+  const animationResolveAtlas = (atlasId) => {
+    if (!Number.isInteger(atlasId) || atlasId <= 0) {
+      return { atlas: null, reason: 'invalid_atlas_id' };
+    }
+    const atlas = animationAtlases.get(atlasId);
+    if (!atlas) return { atlas: null, reason: 'missing_atlas' };
+    return { atlas, reason: null };
+  };
+  const animationResolveAtlasFrame = (atlas, frameKey) => {
+    const normalizedFrameKey = animationNormalizeAtlasKey(frameKey);
+    if (normalizedFrameKey == null) return { frame: null, reason: 'invalid_frame_key' };
+    const frame = atlas.frames.get(normalizedFrameKey);
+    if (!frame) return { frame: null, reason: 'missing_frame' };
+    return { frame, reason: null };
+  };
+  const animationAtlasFrameSnapshot = (atlas, frameKey) => {
+    const frame = atlas.frames.get(frameKey);
+    if (!frame) return null;
+    const duration = frame.duration != null
+      ? frame.duration
+      : ANIMATION_ATLAS_DEFAULT_FRAME_DURATION;
+    return {
+      atlasId: atlas.id,
+      frameKey,
+      image: atlas.image,
+      frameX: frame.x,
+      frameY: frame.y,
+      frameW: frame.w,
+      frameH: frame.h,
+      duration,
+    };
+  };
+  const animationResolveAtlasClip = (clipId) => {
+    if (!Number.isInteger(clipId) || clipId <= 0) {
+      return { clip: null, reason: 'invalid_clip_id' };
+    }
+    const clip = animationAtlasClips.get(clipId);
+    if (!clip) return { clip: null, reason: 'missing_clip' };
+    return { clip, reason: null };
+  };
+  const animationAtlasClipFrameDuration = (clip, frameKey) => {
+    if (clip.frameDuration != null) return clip.frameDuration;
+    const frame = clip.atlas.frames.get(frameKey);
+    if (frame && frame.duration != null) return frame.duration;
+    return ANIMATION_ATLAS_DEFAULT_FRAME_DURATION;
+  };
+  const animationAtlasClipSnapshot = (clip) => {
+    if (!clip || clip.frameKeys.length === 0) return null;
+    const boundedFrameIndex = Math.max(0, Math.min(clip.frameIndex, clip.frameKeys.length - 1));
+    const frameKey = clip.frameKeys[boundedFrameIndex];
+    const frame = clip.atlas.frames.get(frameKey);
+    if (!frame) return null;
+    const frameDuration = animationAtlasClipFrameDuration(clip, frameKey);
+    return {
+      clipId: clip.id,
+      atlasId: clip.atlas.id,
+      clipKey: clip.clipKey,
+      image: clip.atlas.image,
+      frameKey,
+      frameIndex: boundedFrameIndex,
+      frameCount: clip.frameKeys.length,
+      frameX: frame.x,
+      frameY: frame.y,
+      frameW: frame.w,
+      frameH: frame.h,
+      frameDuration,
+      elapsedInFrame: Math.max(0, Math.min(clip.elapsed, frameDuration)),
+      playing: clip.playing,
+      loop: clip.loop,
+      completed: clip.completed,
+      loops: clip.loops,
+    };
+  };
+  const animation = {
+    create: (options = {}) => {
+      if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        return animationResultErr('invalid_options');
+      }
+
+      const duration = animationNormalizeDuration(options.duration);
+      if (duration == null) return animationResultErr('invalid_duration');
+
+      const time = Object.prototype.hasOwnProperty.call(options, 'time')
+        ? animationNormalizeTime(options.time)
+        : 0;
+      if (time == null) return animationResultErr('invalid_time');
+
+      const loop = Object.prototype.hasOwnProperty.call(options, 'loop')
+        ? options.loop
+        : false;
+      if (typeof loop !== 'boolean') return animationResultErr('invalid_loop_flag');
+
+      const speed = Object.prototype.hasOwnProperty.call(options, 'speed')
+        ? animationNormalizeSpeed(options.speed)
+        : 1;
+      if (speed == null) return animationResultErr('invalid_speed');
+
+      const playing = Object.prototype.hasOwnProperty.call(options, 'playing')
+        ? options.playing
+        : false;
+      if (typeof playing !== 'boolean') return animationResultErr('invalid_playing_flag');
+
+      const timelineId = nextAnimationTimelineId++;
+      const timeline = {
+        id: timelineId,
+        duration,
+        time: animationClampTime(time, duration),
+        loop,
+        speed,
+        playing,
+        completed: false,
+        loops: 0,
+        completionNotified: false,
+        transition: null,
+        completeCallbacks: [],
+        eventCallbacks: [],
+      };
+
+      if (!timeline.loop && timeline.time >= timeline.duration) {
+        timeline.time = timeline.duration;
+        timeline.completed = true;
+        timeline.playing = false;
+        timeline.completionNotified = true;
+      }
+
+      animationTimelines.set(timelineId, timeline);
+      return animationResultOk({ timelineId });
+    },
+    play: (timelineId) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return animationResultErr(resolved.reason);
+
+      const timeline = resolved.timeline;
+      if (!timeline.loop && timeline.completed && timeline.time >= timeline.duration) {
+        timeline.time = 0;
+        timeline.completed = false;
+        timeline.completionNotified = false;
+      }
+      timeline.playing = true;
+      if (timeline.transition) timeline.transition.paused = false;
+      return animationResultOk({ timelineId: timeline.id });
+    },
+    pause: (timelineId) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return animationResultErr(resolved.reason);
+      const timeline = resolved.timeline;
+      timeline.playing = false;
+      if (timeline.transition) timeline.transition.paused = true;
+      return animationResultOk({ timelineId: timeline.id });
+    },
+    resume: (timelineId) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return animationResultErr(resolved.reason);
+      const timeline = resolved.timeline;
+      timeline.playing = true;
+      if (timeline.transition) timeline.transition.paused = false;
+      return animationResultOk({ timelineId: timeline.id });
+    },
+    seek: (timelineId, time) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return animationResultErr(resolved.reason);
+      const normalizedTime = animationNormalizeTime(time);
+      if (normalizedTime == null) return animationResultErr('invalid_time');
+
+      const timeline = resolved.timeline;
+      timeline.time = animationClampTime(normalizedTime, timeline.duration);
+      timeline.transition = null;
+      if (!timeline.loop && timeline.time >= timeline.duration) {
+        timeline.completed = true;
+        timeline.playing = false;
+        timeline.completionNotified = true;
+      } else {
+        timeline.completed = false;
+        timeline.completionNotified = false;
+      }
+      return animationResultOk({ timelineId: timeline.id, time: timeline.time });
+    },
+    transition: (timelineId, options = {}) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return animationResultErr(resolved.reason);
+      if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        return animationResultErr('invalid_transition_options');
+      }
+
+      const duration = animationNormalizeTransitionDuration(options.duration);
+      if (duration == null) return animationResultErr('invalid_transition_duration');
+      const targetTime = Object.prototype.hasOwnProperty.call(options, 'targetTime')
+        ? animationNormalizeTime(options.targetTime)
+        : resolved.timeline.time;
+      if (targetTime == null) return animationResultErr('invalid_time');
+      const eventTag = Object.prototype.hasOwnProperty.call(options, 'eventTag')
+        ? animationNormalizeEventTag(options.eventTag)
+        : null;
+
+      const timeline = resolved.timeline;
+      timeline.transition = {
+        startTime: timeline.time,
+        targetTime: animationClampTime(targetTime, timeline.duration),
+        duration,
+        elapsed: 0,
+        paused: !timeline.playing,
+        eventTag,
+      };
+      timeline.completed = false;
+      timeline.completionNotified = false;
+      return animationResultOk({
+        timelineId: timeline.id,
+        targetTime: timeline.transition.targetTime,
+        duration: timeline.transition.duration,
+      });
+    },
+    onComplete: (timelineId, callback, order = 0) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return animationResultErr(resolved.reason);
+      if (typeof callback !== 'function') return animationResultErr('invalid_callback');
+      const listenerId = nextAnimationListenerSeq++;
+      resolved.timeline.completeCallbacks.push({
+        id: listenerId,
+        fn: callback,
+        order: animationNormalizeOrder(order),
+        seq: listenerId,
+      });
+      return animationResultOk({ timelineId: resolved.timeline.id, listenerId });
+    },
+    onEvent: (timelineId, callback, order = 0) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return animationResultErr(resolved.reason);
+      if (typeof callback !== 'function') return animationResultErr('invalid_callback');
+      const listenerId = nextAnimationListenerSeq++;
+      resolved.timeline.eventCallbacks.push({
+        id: listenerId,
+        fn: callback,
+        order: animationNormalizeOrder(order),
+        seq: listenerId,
+      });
+      return animationResultOk({ timelineId: resolved.timeline.id, listenerId });
+    },
+    setLoop: (timelineId, loop) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return animationResultErr(resolved.reason);
+      if (typeof loop !== 'boolean') return animationResultErr('invalid_loop_flag');
+
+      const timeline = resolved.timeline;
+      timeline.loop = loop;
+      if (!timeline.loop && timeline.time >= timeline.duration) {
+        timeline.time = timeline.duration;
+        timeline.completed = true;
+        timeline.playing = false;
+        timeline.completionNotified = true;
+      } else if (timeline.loop && timeline.time >= timeline.duration) {
+        timeline.time = timeline.duration > 0 ? (timeline.time % timeline.duration) : 0;
+        timeline.completed = false;
+        timeline.completionNotified = false;
+      }
+      return animationResultOk({ timelineId: timeline.id, loop: timeline.loop });
+    },
+    setSpeed: (timelineId, speed) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return animationResultErr(resolved.reason);
+      const normalizedSpeed = animationNormalizeSpeed(speed);
+      if (normalizedSpeed == null) return animationResultErr('invalid_speed');
+      resolved.timeline.speed = normalizedSpeed;
+      return animationResultOk({ timelineId: resolved.timeline.id, speed: resolved.timeline.speed });
+    },
+    update: (dt) => {
+      const stepDt = Number.isFinite(dt) && Number(dt) > 0 ? Number(dt) : null;
+      if (stepDt == null) return animationResultErr('invalid_dt');
+      const pendingCallbacks = [];
+
+      for (const timelineId of animationSortedTimelineIds()) {
+        const timeline = animationTimelines.get(timelineId);
+        if (!timeline) continue;
+        if (timeline.transition) {
+          if (
+            timeline.playing
+            && !timeline.transition.paused
+            && timeline.speed > 0
+          ) {
+            const transitionAdvanced = stepDt * timeline.speed;
+            if (transitionAdvanced > 0) {
+              const transition = timeline.transition;
+              transition.elapsed = Math.min(
+                transition.duration,
+                transition.elapsed + transitionAdvanced,
+              );
+              const blend = transition.duration > 0
+                ? (transition.elapsed / transition.duration)
+                : 1;
+              timeline.time = animationClampTime(
+                transition.startTime
+                  + ((transition.targetTime - transition.startTime) * blend),
+                timeline.duration,
+              );
+              timeline.completed = false;
+              if (blend >= 1) {
+                timeline.transition = null;
+                animationEnqueueCallbacks(
+                  pendingCallbacks,
+                  timeline,
+                  ANIMATION_PHASE_TRANSITION_COMPLETE,
+                  timeline.eventCallbacks,
+                  {
+                    type: 'transition_complete',
+                    timelineId: timeline.id,
+                    time: timeline.time,
+                    targetTime: transition.targetTime,
+                    tag: transition.eventTag,
+                  },
+                );
+                if (transition.eventTag != null) {
+                  animationEnqueueCallbacks(
+                    pendingCallbacks,
+                    timeline,
+                    ANIMATION_PHASE_MARKER_EVENT,
+                    timeline.eventCallbacks,
+                    {
+                      type: 'marker',
+                      timelineId: timeline.id,
+                      time: timeline.time,
+                      tag: transition.eventTag,
+                    },
+                  );
+                }
+                if (!timeline.loop && timeline.time >= timeline.duration) {
+                  timeline.completed = true;
+                  timeline.playing = false;
+                  if (!timeline.completionNotified) {
+                    timeline.completionNotified = true;
+                    animationEnqueueCallbacks(
+                      pendingCallbacks,
+                      timeline,
+                      ANIMATION_PHASE_CLIP_COMPLETE,
+                      timeline.completeCallbacks,
+                      animationSnapshot(timeline),
+                    );
+                  }
+                }
+              }
+            }
+          }
+          if (timeline.transition) continue;
+        }
+        if (!timeline.playing || timeline.speed <= 0) continue;
+
+        const advanced = stepDt * timeline.speed;
+        if (!(advanced > 0)) continue;
+
+        if (timeline.loop) {
+          const next = timeline.time + advanced;
+          const wraps = timeline.duration > 0
+            ? Math.floor(next / timeline.duration)
+            : 0;
+          timeline.time = timeline.duration > 0
+            ? (next % timeline.duration)
+            : 0;
+          if (wraps > 0) {
+            timeline.loops += wraps;
+            animationEnqueueCallbacks(
+              pendingCallbacks,
+              timeline,
+              ANIMATION_PHASE_MARKER_EVENT,
+              timeline.eventCallbacks,
+              {
+                type: 'loop',
+                timelineId: timeline.id,
+                loops: wraps,
+                time: timeline.time,
+                tag: null,
+              },
+            );
+          }
+          timeline.completed = false;
+          timeline.completionNotified = false;
+          continue;
+        }
+
+        timeline.time = animationClampTime(timeline.time + advanced, timeline.duration);
+        if (timeline.time >= timeline.duration) {
+          timeline.completed = true;
+          timeline.playing = false;
+          if (!timeline.completionNotified) {
+            timeline.completionNotified = true;
+            animationEnqueueCallbacks(
+              pendingCallbacks,
+              timeline,
+              ANIMATION_PHASE_CLIP_COMPLETE,
+              timeline.completeCallbacks,
+              animationSnapshot(timeline),
+            );
+          }
+        } else {
+          timeline.completed = false;
+          timeline.completionNotified = false;
+        }
+      }
+
+      animationSortPendingCallbacks(pendingCallbacks);
+      animationDispatchPendingCallbacks(pendingCallbacks);
+      return animationResultOk({ dispatchedCallbacks: pendingCallbacks.length });
+    },
+    getState: (timelineId) => {
+      const resolved = animationResolveTimeline(timelineId);
+      if (!resolved.timeline) return null;
+      return animationSnapshot(resolved.timeline);
+    },
+    registerAtlas: (payload) => {
+      if (!animationIsPlainObject(payload)) return animationResultErr('invalid_atlas_payload');
+      const image = animationNormalizeAtlasImage(payload.image);
+      if (image == null) return animationResultErr('invalid_atlas_image');
+      const parsedFrames = animationParseAtlasFrames(payload.frames);
+      if (!parsedFrames.ok) return animationResultErr(parsedFrames.reason);
+      const parsedClips = animationParseAtlasClips(payload.clips, parsedFrames.frames);
+      if (!parsedClips.ok) return animationResultErr(parsedClips.reason);
+
+      const atlasId = nextAtlasId++;
+      animationAtlases.set(atlasId, {
+        id: atlasId,
+        image,
+        frames: parsedFrames.frames,
+        frameKeys: parsedFrames.frameKeys,
+        clips: parsedClips.clips,
+      });
+
+      return animationResultOk({
+        atlasId,
+        frameCount: parsedFrames.frameKeys.length,
+        clipCount: parsedClips.clips.size,
+      });
+    },
+    resolveAtlasFrame: (atlasId, frameKey) => {
+      const resolvedAtlas = animationResolveAtlas(atlasId);
+      if (!resolvedAtlas.atlas) return animationResultErr(resolvedAtlas.reason);
+      const resolvedFrame = animationResolveAtlasFrame(resolvedAtlas.atlas, frameKey);
+      if (!resolvedFrame.frame) return animationResultErr(resolvedFrame.reason);
+      const snapshot = animationAtlasFrameSnapshot(resolvedAtlas.atlas, resolvedFrame.frame.key);
+      return animationResultOk(snapshot || {});
+    },
+    createAtlasClip: (options = {}) => {
+      if (!animationIsPlainObject(options)) return animationResultErr('invalid_clip_options');
+      const resolvedAtlas = animationResolveAtlas(options.atlasId);
+      if (!resolvedAtlas.atlas) return animationResultErr(resolvedAtlas.reason);
+      const atlas = resolvedAtlas.atlas;
+
+      const hasClipKey = Object.prototype.hasOwnProperty.call(options, 'clipKey');
+      const hasFrames = Object.prototype.hasOwnProperty.call(options, 'frames');
+      if (hasClipKey && hasFrames) return animationResultErr('invalid_clip_options');
+
+      let clipKey = null;
+      let frameKeys = null;
+      let frameDuration = null;
+      let loop = true;
+
+      if (hasClipKey) {
+        clipKey = animationNormalizeAtlasKey(options.clipKey);
+        if (clipKey == null) return animationResultErr('invalid_clip_key');
+        const clipMeta = atlas.clips.get(clipKey);
+        if (!clipMeta) return animationResultErr('missing_clip');
+        frameKeys = clipMeta.frames.slice();
+        frameDuration = clipMeta.frameDuration;
+        loop = clipMeta.loop;
+      } else {
+        const parsedFrames = animationParseAtlasClipFrames(options.frames, atlas.frames);
+        if (!parsedFrames.ok) return animationResultErr(parsedFrames.reason);
+        frameKeys = parsedFrames.keys;
+      }
+
+      if (Object.prototype.hasOwnProperty.call(options, 'frameDuration')) {
+        const normalizedFrameDuration = animationNormalizeAtlasFrameDuration(options.frameDuration);
+        if (normalizedFrameDuration == null) return animationResultErr('invalid_clip_duration');
+        frameDuration = normalizedFrameDuration;
+      }
+
+      if (Object.prototype.hasOwnProperty.call(options, 'loop')) {
+        if (typeof options.loop !== 'boolean') return animationResultErr('invalid_clip_loop');
+        loop = options.loop;
+      }
+
+      const playing = Object.prototype.hasOwnProperty.call(options, 'playing')
+        ? options.playing
+        : true;
+      if (typeof playing !== 'boolean') return animationResultErr('invalid_playing_flag');
+
+      const frameIndex = Object.prototype.hasOwnProperty.call(options, 'frameIndex')
+        ? options.frameIndex
+        : 0;
+      if (
+        !Number.isInteger(frameIndex)
+        || frameIndex < 0
+        || frameIndex >= frameKeys.length
+      ) {
+        return animationResultErr('invalid_clip_frame_index');
+      }
+
+      const clipId = nextAtlasClipId++;
+      animationAtlasClips.set(clipId, {
+        id: clipId,
+        atlas,
+        clipKey,
+        frameKeys,
+        frameDuration,
+        frameIndex,
+        elapsed: 0,
+        playing,
+        loop,
+        completed: false,
+        loops: 0,
+      });
+
+      const clipState = animationAtlasClipSnapshot(animationAtlasClips.get(clipId));
+      return animationResultOk({
+        clipId,
+        atlasId: atlas.id,
+        frameKey: clipState ? clipState.frameKey : null,
+      });
+    },
+    stepAtlasClip: (clipId, dt) => {
+      const resolvedClip = animationResolveAtlasClip(clipId);
+      if (!resolvedClip.clip) return animationResultErr(resolvedClip.reason);
+
+      const stepDt = Number.isFinite(dt) && Number(dt) > 0 ? Number(dt) : null;
+      if (stepDt == null) return animationResultErr('invalid_dt');
+
+      const clip = resolvedClip.clip;
+      if (clip.playing && !clip.completed) {
+        let remaining = stepDt;
+        let iterations = 0;
+        while (remaining > ANIMATION_ATLAS_EPSILON && iterations < ANIMATION_ATLAS_MAX_STEP_ITERATIONS) {
+          iterations += 1;
+          const frameKey = clip.frameKeys[clip.frameIndex];
+          const frameDuration = animationAtlasClipFrameDuration(clip, frameKey);
+          const available = Math.max(ANIMATION_ATLAS_EPSILON, frameDuration - clip.elapsed);
+          if (remaining + ANIMATION_ATLAS_EPSILON < available) {
+            clip.elapsed += remaining;
+            remaining = 0;
+            break;
+          }
+
+          remaining -= available;
+          clip.elapsed = 0;
+
+          if (clip.frameIndex + 1 < clip.frameKeys.length) {
+            clip.frameIndex += 1;
+            clip.completed = false;
+            continue;
+          }
+
+          if (clip.loop) {
+            clip.frameIndex = 0;
+            clip.loops += 1;
+            clip.completed = false;
+            continue;
+          }
+
+          clip.frameIndex = clip.frameKeys.length - 1;
+          clip.playing = false;
+          clip.completed = true;
+          remaining = 0;
+          break;
+        }
+      }
+
+      const clipState = animationAtlasClipSnapshot(clip);
+      return animationResultOk({
+        clipId: clip.id,
+        frameKey: clipState ? clipState.frameKey : null,
+        frameIndex: clipState ? clipState.frameIndex : null,
+        loops: clip.loops,
+        completed: clip.completed,
+      });
+    },
+    getAtlasClipState: (clipId) => {
+      const resolvedClip = animationResolveAtlasClip(clipId);
+      if (!resolvedClip.clip) return null;
+      return animationAtlasClipSnapshot(resolvedClip.clip);
+    },
+  };
+
+  const normalizeMachineId = (value) => (
+    Number.isInteger(value) && value > 0 ? value : null
+  );
+
+  let nextAnim2dMachineId = 1;
+  let nextAnim2dCallbackSeq = 1;
+  const anim2dClips = new Map();
+  const anim2dMachines = new Map();
+  const normalizeAnim2dName = (value) => (
+    typeof value === 'string' && value.length > 0 ? value : null
+  );
+  const normalizeAnim2dFrames = (value) => {
+    if (Array.isArray(value) && value.length > 0) return value.slice();
+    if (Number.isInteger(value) && value > 0) {
+      return Array.from({ length: value }, (_, index) => index);
+    }
+    return null;
+  };
+  const normalizeAnim2dFrameDuration = (value) => (
+    Number.isFinite(value) && value > 0 ? Number(value) : (1 / 12)
+  );
+  const normalizeAnim2dOrder = (value) => (
+    Number.isFinite(value) ? Number(value) : 0
+  );
+  const sortedAnim2dMachineIds = () => (
+    [...anim2dMachines.keys()].sort((a, b) => a - b)
+  );
+  const anim2dSnapshot = (machine) => {
+    if (!machine) return null;
+    if (machine.currentState == null) {
+      return {
+        machineId: machine.id,
+        state: null,
+        frameIndex: 0,
+        frame: null,
+        completed: false,
+        loops: machine.loops,
+        frameDuration: 1 / 12,
+        loop: true,
+      };
+    }
+    const state = machine.states.get(machine.currentState);
+    if (!state) {
+      return {
+        machineId: machine.id,
+        state: machine.currentState,
+        frameIndex: 0,
+        frame: null,
+        completed: false,
+        loops: machine.loops,
+        frameDuration: 1 / 12,
+        loop: true,
+      };
+    }
+    const boundedFrameIndex = Math.max(0, Math.min(machine.frameIndex, state.frames.length - 1));
+    return {
+      machineId: machine.id,
+      state: machine.currentState,
+      frameIndex: boundedFrameIndex,
+      frame: state.frames[boundedFrameIndex],
+      completed: machine.completed,
+      loops: machine.loops,
+      frameDuration: state.frameDuration,
+      loop: state.loop,
+    };
+  };
+
+  let nextMaterialHandle = 1;
+  const defaultMaterialState = Object.freeze({
+    color: { r: 1, g: 1, b: 1, a: 1 },
+    emissive: { r: 0, g: 0, b: 0 },
+    metallic: 0,
+    roughness: 1,
+    texture: null,
+    normalMap: null,
+    metallicRoughnessTexture: null,
+    occlusionTexture: null,
+    emissiveTexture: null,
+    alphaMode: 'opaque',
+    alphaCutoff: 0.5,
+    doubleSided: false,
+    clearcoat: 0,
+    clearcoatRoughness: 0,
+    sheenColor: { r: 0, g: 0, b: 0 },
+    sheenRoughness: 0,
+    occlusionStrength: 1,
+  });
+  const materialStore = new Map([[0, { ...defaultMaterialState }]]);
+  const normalizeMaterialHandle = (value) => (
+    Number.isInteger(value) && value >= 0 ? value : null
+  );
+  const normalizeMaterialColor = (value) => {
+    if (!value || typeof value !== 'object') return null;
+    const { r, g, b, a = 1 } = value;
+    if (![r, g, b, a].every((entry) => Number.isFinite(entry))) return null;
+    return { r: Number(r), g: Number(g), b: Number(b), a: Number(a) };
+  };
+  const normalizeMaterialRgb = (value) => {
+    if (!value || typeof value !== 'object') return null;
+    const { r, g, b } = value;
+    if (![r, g, b].every((entry) => Number.isFinite(entry))) return null;
+    return { r: Number(r), g: Number(g), b: Number(b) };
+  };
+  const normalizeTexturePath = (value) => (
+    typeof value === 'string' && value.length > 0 ? value : null
+  );
+  const normalizeAlphaMode = (value) => {
+    if (typeof value !== 'string') return defaultMaterialState.alphaMode;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'mask' || normalized === 'blend') return normalized;
+    return 'opaque';
+  };
+  const clampUnit = (value, fallback) => {
+    if (!Number.isFinite(value)) return fallback;
+    return Math.max(0, Math.min(1, Number(value)));
+  };
+  const getMaterialState = (handle) => {
+    const normalized = normalizeMaterialHandle(handle);
+    if (normalized == null) return null;
+    return materialStore.get(normalized) || null;
+  };
+  const createMaterialState = (options = undefined) => {
+    if (options === undefined) return { ...defaultMaterialState };
+    if (options === null || typeof options !== 'object') {
+      throw new TypeError('aura.material.create: options must be an object or undefined');
+    }
+    return {
+      color: normalizeMaterialColor(options.color) || { ...defaultMaterialState.color },
+      emissive: normalizeMaterialRgb(options.emissive) || { ...defaultMaterialState.emissive },
+      metallic: clampUnit(options.metallic, defaultMaterialState.metallic),
+      roughness: clampUnit(options.roughness, defaultMaterialState.roughness),
+      texture: normalizeTexturePath(options.texture),
+      normalMap: normalizeTexturePath(options.normalMap ?? options.normalTexture),
+      metallicRoughnessTexture: normalizeTexturePath(options.metallicRoughnessTexture),
+      occlusionTexture: normalizeTexturePath(options.aoTexture ?? options.occlusionTexture),
+      emissiveTexture: normalizeTexturePath(options.emissiveTexture),
+      alphaMode: normalizeAlphaMode(options.alphaMode),
+      alphaCutoff: clampUnit(options.alphaCutoff, defaultMaterialState.alphaCutoff),
+      doubleSided: options.doubleSided === true,
+      clearcoat: clampUnit(options.clearcoat, defaultMaterialState.clearcoat),
+      clearcoatRoughness: clampUnit(
+        options.clearcoatRoughness,
+        defaultMaterialState.clearcoatRoughness,
+      ),
+      sheenColor: normalizeMaterialRgb(options.sheenColor) || { ...defaultMaterialState.sheenColor },
+      sheenRoughness: clampUnit(options.sheenRoughness, defaultMaterialState.sheenRoughness),
+      occlusionStrength: clampUnit(
+        options.occlusionStrength ?? options.aoStrength,
+        defaultMaterialState.occlusionStrength,
+      ),
+    };
+  };
+  const material = {
+    create: (options = undefined) => {
+      const handle = nextMaterialHandle++;
+      materialStore.set(handle, createMaterialState(options));
+      return handle;
+    },
+    setColor: (handle, color) => {
+      const materialState = getMaterialState(handle);
+      if (!materialState) return;
+      const normalized = normalizeMaterialColor(color);
+      if (!normalized) return;
+      materialState.color = normalized;
+    },
+    setTexture: (handle, texturePath) => {
+      const materialState = getMaterialState(handle);
+      if (!materialState) return;
+      if (texturePath === null) {
+        materialState.texture = null;
+        return;
+      }
+      if (typeof texturePath !== 'string') {
+        throw new Error('aura.material.setTexture: texturePath must be a string or null');
+      }
+      materialState.texture = texturePath.length > 0 ? texturePath : null;
+    },
+    setMetallic: (handle, metallic) => {
+      const materialState = getMaterialState(handle);
+      if (!materialState) return;
+      materialState.metallic = clampUnit(metallic, materialState.metallic);
+    },
+    setRoughness: (handle, roughness) => {
+      const materialState = getMaterialState(handle);
+      if (!materialState) return;
+      materialState.roughness = clampUnit(roughness, materialState.roughness);
+    },
+    setMetallicRoughness: (handle, metallic, roughness) => {
+      const materialState = getMaterialState(handle);
+      if (!materialState) return;
+      materialState.metallic = clampUnit(metallic, materialState.metallic);
+      materialState.roughness = clampUnit(roughness, materialState.roughness);
+    },
+    reset: (handle) => {
+      const materialState = getMaterialState(handle);
+      if (!materialState) return;
+      materialState.color = { ...defaultMaterialState.color };
+      materialState.emissive = { ...defaultMaterialState.emissive };
+      materialState.metallic = defaultMaterialState.metallic;
+      materialState.roughness = defaultMaterialState.roughness;
+      materialState.texture = defaultMaterialState.texture;
+      materialState.normalMap = defaultMaterialState.normalMap;
+      materialState.metallicRoughnessTexture = defaultMaterialState.metallicRoughnessTexture;
+      materialState.occlusionTexture = defaultMaterialState.occlusionTexture;
+      materialState.emissiveTexture = defaultMaterialState.emissiveTexture;
+      materialState.alphaMode = defaultMaterialState.alphaMode;
+      materialState.alphaCutoff = defaultMaterialState.alphaCutoff;
+      materialState.doubleSided = defaultMaterialState.doubleSided;
+      materialState.clearcoat = defaultMaterialState.clearcoat;
+      materialState.clearcoatRoughness = defaultMaterialState.clearcoatRoughness;
+      materialState.sheenColor = { ...defaultMaterialState.sheenColor };
+      materialState.sheenRoughness = defaultMaterialState.sheenRoughness;
+      materialState.occlusionStrength = defaultMaterialState.occlusionStrength;
+    },
+    clone: (handle) => {
+      const materialState = getMaterialState(handle);
+      if (!materialState) throw new Error('Invalid material handle');
+      const newHandle = nextMaterialHandle++;
+      materialStore.set(newHandle, {
+        color: { ...materialState.color },
+        emissive: { ...materialState.emissive },
+        metallic: materialState.metallic,
+        roughness: materialState.roughness,
+        texture: materialState.texture,
+        normalMap: materialState.normalMap,
+        metallicRoughnessTexture: materialState.metallicRoughnessTexture,
+        occlusionTexture: materialState.occlusionTexture,
+        emissiveTexture: materialState.emissiveTexture,
+        alphaMode: materialState.alphaMode,
+        alphaCutoff: materialState.alphaCutoff,
+        doubleSided: materialState.doubleSided,
+        clearcoat: materialState.clearcoat,
+        clearcoatRoughness: materialState.clearcoatRoughness,
+        sheenColor: { ...materialState.sheenColor },
+        sheenRoughness: materialState.sheenRoughness,
+        occlusionStrength: materialState.occlusionStrength,
+      });
+      return newHandle;
+    },
+    unload: (handle) => {
+      const normalized = normalizeMaterialHandle(handle);
+      if (normalized == null || normalized === 0) return;
+      materialStore.delete(normalized);
+    },
+  };
+
+  const anim2d = {
+    registerClip: (name, frames, options = {}) => {
+      const clipName = normalizeAnim2dName(name);
+      const normalizedFrames = normalizeAnim2dFrames(frames);
+      if (clipName == null || normalizedFrames == null) return false;
+      anim2dClips.set(clipName, {
+        name: clipName,
+        frames: normalizedFrames,
+        frameDuration: normalizeAnim2dFrameDuration(options?.frameDuration),
+        loop: options?.loop !== false,
+      });
+      return true;
+    },
+    createMachine: (initialState = null) => {
+      const id = nextAnim2dMachineId++;
+      anim2dMachines.set(id, {
+        id,
+        states: new Map(),
+        currentState: normalizeAnim2dName(initialState),
+        frameIndex: 0,
+        elapsed: 0,
+        completed: false,
+        loops: 0,
+        callbacks: [],
+      });
+      return id;
+    },
+    defineState: (machineId, stateName, clipOrFrames, options = {}) => {
+      const id = normalizeMachineId(machineId);
+      const normalizedStateName = normalizeAnim2dName(stateName);
+      if (id == null || normalizedStateName == null) return false;
+      const machine = anim2dMachines.get(id);
+      if (!machine) return false;
+
+      let resolvedFrames = null;
+      let resolvedFrameDuration = normalizeAnim2dFrameDuration(options?.frameDuration);
+      let resolvedLoop = options?.loop !== false;
+
+      if (typeof clipOrFrames === 'string') {
+        const clip = anim2dClips.get(clipOrFrames);
+        if (!clip) return false;
+        resolvedFrames = clip.frames.slice();
+        resolvedFrameDuration = clip.frameDuration;
+        resolvedLoop = clip.loop;
+        if (Object.prototype.hasOwnProperty.call(options, 'frameDuration')) {
+          resolvedFrameDuration = normalizeAnim2dFrameDuration(options.frameDuration);
+        }
+        if (Object.prototype.hasOwnProperty.call(options, 'loop')) {
+          resolvedLoop = options.loop !== false;
+        }
+      } else {
+        resolvedFrames = normalizeAnim2dFrames(clipOrFrames);
+        if (resolvedFrames == null) return false;
+      }
+
+      machine.states.set(normalizedStateName, {
+        name: normalizedStateName,
+        frames: resolvedFrames,
+        frameDuration: resolvedFrameDuration,
+        loop: resolvedLoop,
+      });
+      if (machine.currentState == null) {
+        machine.currentState = normalizedStateName;
+      }
+      return true;
+    },
+    play: (machineId, stateName) => {
+      const id = normalizeMachineId(machineId);
+      const normalizedStateName = normalizeAnim2dName(stateName);
+      if (id == null || normalizedStateName == null) return false;
+      const machine = anim2dMachines.get(id);
+      if (!machine) return false;
+      if (!machine.states.has(normalizedStateName)) return false;
+      machine.currentState = normalizedStateName;
+      machine.frameIndex = 0;
+      machine.elapsed = 0;
+      machine.completed = false;
+      machine.loops = 0;
+      return true;
+    },
+    onComplete: (machineId, callback, order = 0) => {
+      const id = normalizeMachineId(machineId);
+      if (id == null || typeof callback !== 'function') return false;
+      const machine = anim2dMachines.get(id);
+      if (!machine) return false;
+      machine.callbacks.push({
+        fn: callback,
+        order: normalizeAnim2dOrder(order),
+        seq: nextAnim2dCallbackSeq++,
+      });
+      machine.callbacks.sort((a, b) => (a.order - b.order) || (a.seq - b.seq));
+      return true;
+    },
+    getState: (machineId) => {
+      const id = normalizeMachineId(machineId);
+      if (id == null) return null;
+      return anim2dSnapshot(anim2dMachines.get(id));
+    },
+    update: (dt) => {
+      const stepDt = Number.isFinite(dt) && dt > 0 ? Number(dt) : 0;
+      if (stepDt <= 0) return;
+      for (const machineId of sortedAnim2dMachineIds()) {
+        const machine = anim2dMachines.get(machineId);
+        if (!machine || machine.currentState == null) continue;
+        const state = machine.states.get(machine.currentState);
+        if (!state || state.frames.length === 0) continue;
+        machine.elapsed += stepDt;
+        const frameDuration = normalizeAnim2dFrameDuration(state.frameDuration);
+        while (machine.elapsed >= frameDuration) {
+          machine.elapsed -= frameDuration;
+          if (machine.frameIndex + 1 < state.frames.length) {
+            machine.frameIndex += 1;
+            continue;
+          }
+          if (state.loop) {
+            machine.frameIndex = 0;
+            machine.loops += 1;
+            continue;
+          }
+          machine.frameIndex = state.frames.length - 1;
+          if (!machine.completed) {
+            machine.completed = true;
+            const snapshot = anim2dSnapshot(machine);
+            for (const callback of machine.callbacks) {
+              try {
+                callback.fn(snapshot);
+              } catch {
+                // Keep update loop deterministic even if callbacks throw.
+              }
+            }
+          }
+          break;
+        }
+      }
+    },
+  };
+
+  return {
+    animation,
+    anim2d,
+    material,
+  };
+}