@auraindustry/aurajs 0.0.1

package/src/headless-test.mjs

@@ -0,0 +1,4314 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+
+import { bundleProject } from './bundler.mjs';
+
+export class HeadlessTestError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'HeadlessTestError';
+    this.details = details;
+  }
+}
+
+export function parseTestArgs(args) {
+  const parsed = {
+    file: 'src/test.js',
+    width: 1280,
+    height: 720,
+    frames: 1,
+  };
+
+  let positionalSet = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === '--width' && args[i + 1]) {
+      parsed.width = parsePositiveInt(args[i + 1], '--width');
+      i += 1;
+      continue;
+    }
+    if (token === '--height' && args[i + 1]) {
+      parsed.height = parsePositiveInt(args[i + 1], '--height');
+      i += 1;
+      continue;
+    }
+    if (token === '--frames' && args[i + 1]) {
+      parsed.frames = parseNonNegativeInt(args[i + 1], '--frames');
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--')) {
+      throw new HeadlessTestError(`Unknown test option: ${token}`);
+    }
+    if (!positionalSet) {
+      parsed.file = token;
+      positionalSet = true;
+      continue;
+    }
+    throw new HeadlessTestError(`Unexpected argument: ${token}`);
+  }
+
+  return parsed;
+}
+
+export async function runHeadlessTest(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const entryFile = resolve(projectRoot, options.file || 'src/test.js');
+  const width = options.width ?? 1280;
+  const height = options.height ?? 720;
+  const frames = options.frames ?? 1;
+
+  if (!existsSync(entryFile)) {
+    throw new HeadlessTestError(`Test file not found: ${entryFile}`);
+  }
+
+  const bundle = bundleProject({
+    projectRoot,
+    mode: 'test',
+    entryFile,
+    outFile: resolve(projectRoot, '.aura/test/test.bundle.js'),
+  });
+
+  const testState = {
+    failures: [],
+    passes: 0,
+    drawCalls: 0,
+    audioCalls: 0,
+    logs: [],
+  };
+
+  const aura = createHeadlessAura({ width, height, testState });
+  const context = vm.createContext(createRuntimeContext(aura, testState));
+
+  const source = readFileSync(bundle.outFile, 'utf8');
+  const script = new vm.Script(source, {
+    filename: bundle.outFile,
+    displayErrors: true,
+  });
+
+  try {
+    script.runInContext(context, { timeout: 5000 });
+    await executeLifecycle(aura, frames);
+  } catch (error) {
+    throw new HeadlessTestError(`Headless test execution failed: ${error.message}`, {
+      stack: error.stack,
+    });
+  }
+
+  if (testState.failures.length > 0) {
+    throw new HeadlessTestError(`Headless test failed with ${testState.failures.length} assertion error(s).`, {
+      failures: [...testState.failures],
+    });
+  }
+
+  return {
+    ok: true,
+    entryFile,
+    bundle,
+    frames,
+    width,
+    height,
+    passes: testState.passes,
+    drawCalls: testState.drawCalls,
+    audioCalls: testState.audioCalls,
+  };
+}
+
+function createRuntimeContext(aura, testState) {
+  const consoleShim = {
+    log: (...args) => {
+      testState.logs.push(['log', ...args]);
+      console.log(...args);
+    },
+    warn: (...args) => {
+      testState.logs.push(['warn', ...args]);
+      console.warn(...args);
+    },
+    error: (...args) => {
+      testState.logs.push(['error', ...args]);
+      console.error(...args);
+    },
+  };
+
+  return {
+    aura,
+    console: consoleShim,
+    Math,
+    Date,
+    setTimeout,
+    clearTimeout,
+    setInterval,
+    clearInterval,
+    performance: { now: () => Date.now() },
+  };
+}
+
+function createHeadlessAura({ width, height, testState }) {
+  const drawNoop = () => {
+    testState.drawCalls += 1;
+  };
+
+  const makeVec2 = (x = 0, y = 0) => ({ x: Number(x), y: Number(y) });
+  const vec2 = function vec2(x = 0, y = 0) {
+    return makeVec2(x, y);
+  };
+  vec2.create = makeVec2;
+  vec2.add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y });
+  vec2.sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+  vec2.scale = (v, scalar) => ({ x: v.x * scalar, y: v.y * scalar });
+  vec2.normalize = (v) => {
+    const magnitude = Math.hypot(v.x, v.y);
+    if (magnitude === 0) return { x: 0, y: 0 };
+    return { x: v.x / magnitude, y: v.y / magnitude };
+  };
+  vec2.dot = (a, b) => a.x * b.x + a.y * b.y;
+  vec2.distance = (a, b) => Math.hypot(b.x - a.x, b.y - a.y);
+  vec2.lerp = (a, b, t) => ({
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+  });
+  Object.defineProperty(vec2, 'length', {
+    value: (v) => Math.hypot(v.x, v.y),
+    writable: true,
+    configurable: true,
+  });
+  vec2.len = (v) => vec2.length(v);
+
+  const makeVec3 = (x = 0, y = 0, z = 0) => ({ x: Number(x), y: Number(y), z: Number(z) });
+  const vec3 = function vec3(x = 0, y = 0, z = 0) {
+    return makeVec3(x, y, z);
+  };
+  vec3.create = makeVec3;
+  vec3.add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z });
+  vec3.sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z });
+  vec3.scale = (v, scalar) => ({ x: v.x * scalar, y: v.y * scalar, z: v.z * scalar });
+  vec3.dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+  vec3.cross = (a, b) => ({
+    x: a.y * b.z - a.z * b.y,
+    y: a.z * b.x - a.x * b.z,
+    z: a.x * b.y - a.y * b.x,
+  });
+  vec3.normalize = (v) => {
+    const magnitude = Math.hypot(v.x, v.y, v.z);
+    if (magnitude === 0) return { x: 0, y: 0, z: 0 };
+    return { x: v.x / magnitude, y: v.y / magnitude, z: v.z / magnitude };
+  };
+  vec3.distance = (a, b) => Math.hypot(b.x - a.x, b.y - a.y, b.z - a.z);
+  vec3.lerp = (a, b, t) => ({
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+    z: a.z + (b.z - a.z) * t,
+  });
+  Object.defineProperty(vec3, 'length', {
+    value: (v) => Math.hypot(v.x, v.y, v.z),
+    writable: true,
+    configurable: true,
+  });
+
+  const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+  const parseRect = (value) => (
+    value
+    && isFiniteNumber(value.x)
+    && isFiniteNumber(value.y)
+    && isFiniteNumber(value.w)
+    && isFiniteNumber(value.h)
+    ? value
+    : null
+  );
+  const parsePoint = (value) => (
+    value
+    && isFiniteNumber(value.x)
+    && isFiniteNumber(value.y)
+    ? value
+    : null
+  );
+  const parseCircle = (value) => (
+    value
+    && isFiniteNumber(value.x)
+    && isFiniteNumber(value.y)
+    && isFiniteNumber(value.radius)
+    ? value
+    : null
+  );
+
+  const collisionRectRect = (a, b) => a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
+  const collisionRectPoint = (rect, point) => (
+    point.x >= rect.x
+    && point.x <= rect.x + rect.w
+    && point.y >= rect.y
+    && point.y <= rect.y + rect.h
+  );
+  const collisionCircleCircle = (a, b) => Math.hypot(b.x - a.x, b.y - a.y) <= a.radius + b.radius;
+  const collisionCirclePoint = (circle, point) => Math.hypot(point.x - circle.x, point.y - circle.y) <= circle.radius;
+  const collisionCircleRect = (circle, rect) => {
+    const nearestX = Math.max(rect.x, Math.min(circle.x, rect.x + rect.w));
+    const nearestY = Math.max(rect.y, Math.min(circle.y, rect.y + rect.h));
+    return Math.hypot(circle.x - nearestX, circle.y - nearestY) <= circle.radius;
+  };
+
+  const collision = {
+    rectRect: (a, b) => {
+      const lhs = parseRect(a);
+      const rhs = parseRect(b);
+      return !!lhs && !!rhs && collisionRectRect(lhs, rhs);
+    },
+    rectPoint: (rect, point) => {
+      const parsedRect = parseRect(rect);
+      const parsedPoint = parsePoint(point);
+      return !!parsedRect && !!parsedPoint && collisionRectPoint(parsedRect, parsedPoint);
+    },
+    circleCircle: (a, b) => {
+      const lhs = parseCircle(a);
+      const rhs = parseCircle(b);
+      return !!lhs && !!rhs && collisionCircleCircle(lhs, rhs);
+    },
+    circlePoint: (circle, point) => {
+      const parsedCircle = parseCircle(circle);
+      const parsedPoint = parsePoint(point);
+      return !!parsedCircle && !!parsedPoint && collisionCirclePoint(parsedCircle, parsedPoint);
+    },
+    circleRect: (circle, rect) => {
+      const parsedCircle = parseCircle(circle);
+      const parsedRect = parseRect(rect);
+      return !!parsedCircle && !!parsedRect && collisionCircleRect(parsedCircle, parsedRect);
+    },
+    rectRectBatch: (rect, rects) => {
+      const parsedRect = parseRect(rect);
+      if (!parsedRect || !Array.isArray(rects)) return [];
+      return rects.map((candidate) => {
+        const parsedCandidate = parseRect(candidate);
+        return !!parsedCandidate && collisionRectRect(parsedRect, parsedCandidate);
+      });
+    },
+    rectPointBatch: (rect, points) => {
+      const parsedRect = parseRect(rect);
+      if (!parsedRect || !Array.isArray(points)) return [];
+      return points.map((candidate) => {
+        const parsedCandidate = parsePoint(candidate);
+        return !!parsedCandidate && collisionRectPoint(parsedRect, parsedCandidate);
+      });
+    },
+    circleCircleBatch: (circle, circles) => {
+      const parsedCircle = parseCircle(circle);
+      if (!parsedCircle || !Array.isArray(circles)) return [];
+      return circles.map((candidate) => {
+        const parsedCandidate = parseCircle(candidate);
+        return !!parsedCandidate && collisionCircleCircle(parsedCircle, parsedCandidate);
+      });
+    },
+    circlePointBatch: (circle, points) => {
+      const parsedCircle = parseCircle(circle);
+      if (!parsedCircle || !Array.isArray(points)) return [];
+      return points.map((candidate) => {
+        const parsedCandidate = parsePoint(candidate);
+        return !!parsedCandidate && collisionCirclePoint(parsedCircle, parsedCandidate);
+      });
+    },
+    circleRectBatch: (circle, rects) => {
+      const parsedCircle = parseCircle(circle);
+      if (!parsedCircle || !Array.isArray(rects)) return [];
+      return rects.map((candidate) => {
+        const parsedCandidate = parseRect(candidate);
+        return !!parsedCandidate && collisionCircleRect(parsedCircle, parsedCandidate);
+      });
+    },
+  };
+
+  const debugInspectorState = {
+    enabled: false,
+    frameCount: 0,
+    elapsedSeconds: 0,
+  };
+
+  const debugInspectorSnapshot = () => ({
+    enabled: debugInspectorState.enabled,
+    frameCount: debugInspectorState.frameCount,
+    frame: {
+      fps: 60,
+      deltaSeconds: 1 / 60,
+      elapsedSeconds: debugInspectorState.elapsedSeconds,
+    },
+    window: {
+      width,
+      height,
+      pixelRatio: 1,
+    },
+    queues: {
+      draw2dPending: 0,
+      debugOverlayPending: 0,
+    },
+  });
+
+  const collide = {
+    rects: (x1, y1, w1, h1, x2, y2, w2, h2) => collision.rectRect(
+      { x: x1, y: y1, w: w1, h: h1 },
+      { x: x2, y: y2, w: w2, h: h2 },
+    ),
+    circles: (x1, y1, r1, x2, y2, r2) => collision.circleCircle(
+      { x: x1, y: y1, radius: r1 },
+      { x: x2, y: y2, radius: r2 },
+    ),
+    pointRect: (px, py, rx, ry, rw, rh) => collision.rectPoint(
+      { x: rx, y: ry, w: rw, h: rh },
+      { x: px, y: py },
+    ),
+    pointCircle: (px, py, cx, cy, cr) => collision.circlePoint(
+      { x: cx, y: cy, radius: cr },
+      { x: px, y: py },
+    ),
+    rectCircle: (rx, ry, rw, rh, cx, cy, cr) => collision.circleRect(
+      { x: cx, y: cy, radius: cr },
+      { x: rx, y: ry, w: rw, h: rh },
+    ),
+  };
+
+  let nextEcsEntityId = 1;
+  const ecsEntities = new Set();
+  const ecsComponentStores = new Map();
+  const ecsSystems = [];
+  const sortEcsSystems = () => {
+    ecsSystems.sort((a, b) => (a.order - b.order) || a.name.localeCompare(b.name));
+  };
+  const normalizeEntityId = (value) => (
+    Number.isInteger(value) && value > 0 ? value : null
+  );
+  const normalizeComponentName = (value) => (
+    typeof value === 'string' && value.length > 0 ? value : null
+  );
+  const normalizeSystemName = (value) => (
+    typeof value === 'string' && value.length > 0 ? value : null
+  );
+
+  let nextScene3dNodeId = 1;
+  const scene3dNodes = new Map();
+  const scene3dIsValidNodeId = (value) => Number.isInteger(value) && value > 0;
+  const scene3dCloneVec3 = (value, fallback) => ({
+    x: Number.isFinite(value?.x) ? Number(value.x) : fallback.x,
+    y: Number.isFinite(value?.y) ? Number(value.y) : fallback.y,
+    z: Number.isFinite(value?.z) ? Number(value.z) : fallback.z,
+  });
+  const scene3dNormalizeTransform = (input) => {
+    const src = (input && typeof input === 'object') ? input : {};
+    return {
+      position: scene3dCloneVec3(src.position, { x: 0, y: 0, z: 0 }),
+      rotation: scene3dCloneVec3(src.rotation, { x: 0, y: 0, z: 0 }),
+      scale: scene3dCloneVec3(src.scale, { x: 1, y: 1, z: 1 }),
+    };
+  };
+  const scene3dCloneTransform = (transform) => ({
+    position: { ...transform.position },
+    rotation: { ...transform.rotation },
+    scale: { ...transform.scale },
+  });
+  const scene3dSortedChildren = (node) => [...node.children].sort((a, b) => a - b);
+  const scene3dDetachFromParent = (node) => {
+    if (node.parentId == null) return;
+    const parent = scene3dNodes.get(node.parentId);
+    if (parent) parent.children.delete(node.id);
+    node.parentId = null;
+  };
+  const scene3dWouldCreateCycle = (nodeId, parentId) => {
+    let cursor = parentId;
+    while (cursor != null) {
+      if (cursor === nodeId) return true;
+      const cursorNode = scene3dNodes.get(cursor);
+      if (!cursorNode) break;
+      cursor = cursorNode.parentId;
+    }
+    return false;
+  };
+  const scene3dComposeWorldTransform = (nodeId) => {
+    const chain = [];
+    let cursor = scene3dNodes.get(nodeId);
+    while (cursor) {
+      chain.push(cursor);
+      if (cursor.parentId == null) break;
+      cursor = scene3dNodes.get(cursor.parentId);
+    }
+    chain.reverse();
+
+    const world = {
+      position: { x: 0, y: 0, z: 0 },
+      rotation: { x: 0, y: 0, z: 0 },
+      scale: { x: 1, y: 1, z: 1 },
+    };
+
+    for (const node of chain) {
+      world.position.x += node.local.position.x * world.scale.x;
+      world.position.y += node.local.position.y * world.scale.y;
+      world.position.z += node.local.position.z * world.scale.z;
+      world.rotation.x += node.local.rotation.x;
+      world.rotation.y += node.local.rotation.y;
+      world.rotation.z += node.local.rotation.z;
+      world.scale.x *= node.local.scale.x;
+      world.scale.y *= node.local.scale.y;
+      world.scale.z *= node.local.scale.z;
+    }
+    return world;
+  };
+  const scene3dNormalizeRaycastVec3 = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    const x = Number(value.x);
+    const y = Number(value.y);
+    const z = Number(value.z);
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) return null;
+    return { x, y, z };
+  };
+  const scene3dNormalizeRaycastArgs = (originOrOptions, maybeDirection, maybeOptions) => {
+    let origin = null;
+    let direction = null;
+    let options = null;
+    if (
+      originOrOptions
+      && typeof originOrOptions === 'object'
+      && !Array.isArray(originOrOptions)
+      && (
+        Object.prototype.hasOwnProperty.call(originOrOptions, 'origin')
+        || Object.prototype.hasOwnProperty.call(originOrOptions, 'direction')
+      )
+    ) {
+      origin = scene3dNormalizeRaycastVec3(originOrOptions.origin);
+      direction = scene3dNormalizeRaycastVec3(originOrOptions.direction);
+      options = originOrOptions;
+    } else {
+      origin = scene3dNormalizeRaycastVec3(originOrOptions);
+      direction = scene3dNormalizeRaycastVec3(maybeDirection);
+      options = maybeOptions;
+    }
+    if (!origin || !direction) return { ok: false, reason: 'invalid_raycast_args' };
+    const length = Math.hypot(direction.x, direction.y, direction.z);
+    if (!Number.isFinite(length) || length <= 1e-9) return { ok: false, reason: 'invalid_raycast_args' };
+    let maxDistance = 1000;
+    if (options && typeof options === 'object' && !Array.isArray(options) && Object.prototype.hasOwnProperty.call(options, 'maxDistance')) {
+      maxDistance = Number(options.maxDistance);
+    }
+    if (!Number.isFinite(maxDistance) || !(maxDistance > 0)) return { ok: false, reason: 'invalid_raycast_args' };
+    return {
+      ok: true,
+      origin,
+      direction: { x: direction.x / length, y: direction.y / length, z: direction.z / length },
+      maxDistance,
+    };
+  };
+  const scene3d = {
+    createNode: (initialTransform = null) => {
+      const id = nextScene3dNodeId++;
+      scene3dNodes.set(id, {
+        id,
+        parentId: null,
+        children: new Set(),
+        local: scene3dNormalizeTransform(initialTransform),
+      });
+      return id;
+    },
+    removeNode: (nodeId) => {
+      if (!scene3dIsValidNodeId(nodeId)) return false;
+      const node = scene3dNodes.get(nodeId);
+      if (!node) return false;
+      scene3dDetachFromParent(node);
+      for (const childId of scene3dSortedChildren(node)) {
+        const child = scene3dNodes.get(childId);
+        if (child) child.parentId = null;
+      }
+      scene3dNodes.delete(nodeId);
+      return true;
+    },
+    setParent: (nodeId, parentId) => {
+      if (!scene3dIsValidNodeId(nodeId)) return false;
+      const node = scene3dNodes.get(nodeId);
+      if (!node) return false;
+      if (parentId == null) {
+        scene3dDetachFromParent(node);
+        return true;
+      }
+      if (!scene3dIsValidNodeId(parentId) || parentId === nodeId) return false;
+      const parent = scene3dNodes.get(parentId);
+      if (!parent) return false;
+      if (scene3dWouldCreateCycle(nodeId, parentId)) return false;
+      scene3dDetachFromParent(node);
+      node.parentId = parentId;
+      parent.children.add(nodeId);
+      return true;
+    },
+    getParent: (nodeId) => {
+      if (!scene3dIsValidNodeId(nodeId)) return null;
+      const node = scene3dNodes.get(nodeId);
+      if (!node) return null;
+      return node.parentId;
+    },
+    setLocalTransform: (nodeId, transform) => {
+      if (!scene3dIsValidNodeId(nodeId)) return false;
+      const node = scene3dNodes.get(nodeId);
+      if (!node || !transform || typeof transform !== 'object') return false;
+      node.local = scene3dNormalizeTransform(transform);
+      return true;
+    },
+    getLocalTransform: (nodeId) => {
+      if (!scene3dIsValidNodeId(nodeId)) return null;
+      const node = scene3dNodes.get(nodeId);
+      if (!node) return null;
+      return scene3dCloneTransform(node.local);
+    },
+    getWorldTransform: (nodeId) => {
+      if (!scene3dIsValidNodeId(nodeId)) return null;
+      if (!scene3dNodes.has(nodeId)) return null;
+      return scene3dComposeWorldTransform(nodeId);
+    },
+    traverse: (rootOrCallback, maybeCallback) => {
+      let rootId = null;
+      let callback = maybeCallback;
+      if (typeof rootOrCallback === 'function') {
+        callback = rootOrCallback;
+      } else if (rootOrCallback != null) {
+        rootId = rootOrCallback;
+      }
+      if (typeof callback !== 'function') return false;
+      if (rootId != null && (!scene3dIsValidNodeId(rootId) || !scene3dNodes.has(rootId))) {
+        return false;
+      }
+
+      const walk = (nodeId) => {
+        const node = scene3dNodes.get(nodeId);
+        if (!node) return;
+        callback(
+          nodeId,
+          scene3dComposeWorldTransform(nodeId),
+          scene3dCloneTransform(node.local),
+          node.parentId,
+        );
+        for (const childId of scene3dSortedChildren(node)) {
+          walk(childId);
+        }
+      };
+
+      if (rootId != null) {
+        walk(rootId);
+        return true;
+      }
+
+      const roots = [...scene3dNodes.values()]
+        .filter((node) => node.parentId == null)
+        .map((node) => node.id)
+        .sort((a, b) => a - b);
+      for (const nodeId of roots) {
+        walk(nodeId);
+      }
+      return true;
+    },
+    queryRaycast: (originOrOptions, maybeDirection, maybeOptions) => {
+      const parsed = scene3dNormalizeRaycastArgs(originOrOptions, maybeDirection, maybeOptions);
+      if (!parsed.ok) {
+        return { ok: false, reason: parsed.reason };
+      }
+      const hits = [];
+      const nodeIds = [...scene3dNodes.keys()].sort((a, b) => a - b);
+      for (const nodeId of nodeIds) {
+        const world = scene3dComposeWorldTransform(nodeId);
+        const radius = Math.max(
+          0.05,
+          (Math.max(
+            Math.abs(world.scale.x),
+            Math.abs(world.scale.y),
+            Math.abs(world.scale.z),
+          ) * 0.5),
+        );
+        const ox = parsed.origin.x - world.position.x;
+        const oy = parsed.origin.y - world.position.y;
+        const oz = parsed.origin.z - world.position.z;
+        const b = 2 * ((ox * parsed.direction.x) + (oy * parsed.direction.y) + (oz * parsed.direction.z));
+        const c = (ox * ox) + (oy * oy) + (oz * oz) - (radius * radius);
+        const discriminant = (b * b) - (4 * c);
+        if (!Number.isFinite(discriminant) || discriminant < 0) continue;
+        const root = Math.sqrt(discriminant);
+        let toi = (-b - root) / 2;
+        if (toi < 0) toi = (-b + root) / 2;
+        if (!Number.isFinite(toi) || toi < 0 || toi > parsed.maxDistance) continue;
+        hits.push({
+          nodeId,
+          toi: Number(toi.toFixed(6)),
+          point: {
+            x: Number((parsed.origin.x + (parsed.direction.x * toi)).toFixed(6)),
+            y: Number((parsed.origin.y + (parsed.direction.y * toi)).toFixed(6)),
+            z: Number((parsed.origin.z + (parsed.direction.z * toi)).toFixed(6)),
+          },
+          radius: Number(radius.toFixed(6)),
+        });
+      }
+      hits.sort((a, b) => (a.toi - b.toi) || (a.nodeId - b.nodeId));
+      return {
+        ok: true,
+        reason: null,
+        hit: hits.length > 0,
+        hitCount: hits.length,
+        firstHit: hits.length > 0 ? hits[0] : null,
+        hits,
+        maxDistance: Number(parsed.maxDistance.toFixed(6)),
+      };
+    },
+  };
+
+  const createSceneHelper = () => {
+    let lifecycleSeq = 1;
+    let nextTimedEventId = 1;
+    let globalTicks = 0;
+    let activeScene = null;
+    const sceneDefinitions = new Map();
+    const timedEvents = new Map();
+    const lifecycleTrace = [];
+
+    const isPlainObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+    const normalizeSceneKey = (value) => {
+      if (typeof value !== 'string') return null;
+      const trimmed = value.trim();
+      return trimmed.length > 0 ? trimmed : null;
+    };
+    const resultOk = (reasonCode, extra = {}) => ({ ok: true, reasonCode, ...extra });
+    const resultErr = (reasonCode, extra = {}) => ({ ok: false, reasonCode, ...extra });
+    const cloneValue = (value) => {
+      if (value == null) return value;
+      if (Array.isArray(value)) return value.map((entry) => cloneValue(entry));
+      if (typeof value !== 'object') return value;
+      const out = {};
+      for (const key of Object.keys(value)) out[key] = cloneValue(value[key]);
+      return out;
+    };
+    const callbackContext = (sceneRecord) => ({
+      key: sceneRecord.key,
+      state: sceneRecord.state,
+      data: sceneRecord.data,
+      updates: sceneRecord.updates,
+      elapsed: sceneRecord.elapsed,
+    });
+    const recordLifecycle = (sceneKey, phase) => {
+      lifecycleTrace.push({
+        seq: lifecycleSeq++,
+        sceneKey,
+        phase,
+      });
+    };
+    const invokeSceneCallback = (sceneRecord, phase, ...args) => {
+      const callback = sceneRecord.callbacks[phase];
+      if (typeof callback !== 'function') return;
+      recordLifecycle(sceneRecord.key, phase);
+      try {
+        callback(callbackContext(sceneRecord), ...args);
+      } catch {
+        // Preserve deterministic progression when callbacks throw.
+      }
+    };
+    const sortedSceneKeys = () => [...sceneDefinitions.keys()].sort((a, b) => a.localeCompare(b));
+    const sortedEventIds = () => [...timedEvents.keys()].sort((a, b) => a - b);
+    const snapshotEvent = (event) => ({
+      eventId: event.id,
+      delay: event.delay,
+      interval: event.interval,
+      remaining: event.remaining,
+      repeat: event.repeat,
+      paused: event.paused,
+      dispatchCount: event.dispatchCount,
+      sceneKey: event.sceneKey,
+      createdTick: event.createdTick,
+    });
+    const resolveEvent = (eventId) => {
+      if (!Number.isInteger(eventId) || eventId <= 0) {
+        return { event: null, reasonCode: 'invalid_event_id' };
+      }
+      const event = timedEvents.get(eventId);
+      if (!event) {
+        return { event: null, reasonCode: 'missing_event' };
+      }
+      return { event, reasonCode: null };
+    };
+    const normalizeSceneDefinition = (definition) => {
+      if (!isPlainObject(definition)) {
+        return { callbacks: null, reasonCode: 'invalid_scene_definition' };
+      }
+      const callbacks = {};
+      for (const phase of ['preload', 'create', 'update', 'shutdown']) {
+        if (!Object.prototype.hasOwnProperty.call(definition, phase)) continue;
+        const callback = definition[phase];
+        if (callback != null && typeof callback !== 'function') {
+          return { callbacks: null, reasonCode: 'invalid_scene_callbacks' };
+        }
+        callbacks[phase] = callback;
+      }
+      return { callbacks, reasonCode: null };
+    };
+    const startInternal = (sceneKey, data = null, mode = 'start') => {
+      const key = normalizeSceneKey(sceneKey);
+      if (key == null) return resultErr('invalid_scene_key');
+      const definition = sceneDefinitions.get(key);
+      if (!definition) return resultErr('missing_scene_definition');
+
+      if (activeScene) {
+        const previous = activeScene;
+        activeScene = null;
+        invokeSceneCallback(previous, 'shutdown', mode === 'switch' ? 'switch' : 'start');
+      }
+
+      activeScene = {
+        key,
+        callbacks: definition.callbacks,
+        state: {},
+        data: cloneValue(data),
+        updates: 0,
+        elapsed: 0,
+        lastDt: 0,
+        startedTick: globalTicks,
+      };
+      invokeSceneCallback(activeScene, 'preload');
+      invokeSceneCallback(activeScene, 'create');
+      return resultOk(mode === 'switch' ? 'scene_switched' : 'scene_started', {
+        activeScene: key,
+      });
+    };
+    const advanceTimedEvents = (dt) => {
+      const due = [];
+      for (const eventId of sortedEventIds()) {
+        const event = timedEvents.get(eventId);
+        if (!event || event.paused) continue;
+        event.remaining -= dt;
+        while (event.remaining <= 1e-9) {
+          event.dispatchCount += 1;
+          due.push({
+            id: event.id,
+            sceneKey: event.sceneKey,
+            callback: event.callback,
+            dispatchCount: event.dispatchCount,
+          });
+          if (!event.repeat) {
+            timedEvents.delete(event.id);
+            break;
+          }
+          event.remaining += event.interval;
+        }
+      }
+      due.sort((a, b) => a.id - b.id);
+      for (const entry of due) {
+        try {
+          entry.callback({
+            eventId: entry.id,
+            sceneKey: entry.sceneKey,
+            dispatchCount: entry.dispatchCount,
+          });
+        } catch {
+          // Preserve deterministic progression when callbacks throw.
+        }
+      }
+      return due;
+    };
+
+    const scene = {
+      define(sceneKey, definition) {
+        const key = normalizeSceneKey(sceneKey);
+        if (key == null) return resultErr('invalid_scene_key');
+        const parsed = normalizeSceneDefinition(definition);
+        if (!parsed.callbacks) return resultErr(parsed.reasonCode || 'invalid_scene_definition');
+        const replaced = sceneDefinitions.has(key);
+        sceneDefinitions.set(key, {
+          key,
+          callbacks: parsed.callbacks,
+        });
+        return resultOk('scene_defined', { sceneKey: key, replaced });
+      },
+      register(sceneKey, definition) {
+        return scene.define(sceneKey, definition);
+      },
+      start(sceneKey, data = null) {
+        return startInternal(sceneKey, data, 'start');
+      },
+      switchTo(sceneKey, data = null) {
+        return startInternal(sceneKey, data, 'switch');
+      },
+      update(dt) {
+        const stepDt = Number(dt);
+        if (!Number.isFinite(stepDt) || !(stepDt > 0)) {
+          return resultErr('invalid_dt');
+        }
+        if (!activeScene) {
+          return resultErr('no_active_scene');
+        }
+
+        globalTicks += 1;
+        const firedEvents = advanceTimedEvents(stepDt);
+        const current = activeScene;
+        current.updates += 1;
+        current.elapsed += stepDt;
+        current.lastDt = stepDt;
+        invokeSceneCallback(current, 'update', stepDt);
+        return resultOk('scene_updated', {
+          activeScene: activeScene ? activeScene.key : null,
+          firedEvents: firedEvents.length,
+          firedEventIds: firedEvents.map((entry) => entry.id),
+        });
+      },
+      getState() {
+        return {
+          activeScene: activeScene ? activeScene.key : null,
+          sceneCount: sceneDefinitions.size,
+          scenes: sortedSceneKeys(),
+          tick: globalTicks,
+          active: activeScene ? {
+            key: activeScene.key,
+            updates: activeScene.updates,
+            elapsed: activeScene.elapsed,
+            lastDt: activeScene.lastDt,
+            startedTick: activeScene.startedTick,
+            state: cloneValue(activeScene.state),
+            data: cloneValue(activeScene.data),
+          } : null,
+          lifecycle: lifecycleTrace.map((entry) => ({ ...entry })),
+          timedEvents: sortedEventIds()
+            .map((eventId) => timedEvents.get(eventId))
+            .filter(Boolean)
+            .map((event) => snapshotEvent(event)),
+        };
+      },
+      schedule(delaySeconds, callback, options = {}) {
+        const delay = Number(delaySeconds);
+        if (!Number.isFinite(delay) || !(delay > 0)) {
+          return resultErr('invalid_delay');
+        }
+        if (typeof callback !== 'function') {
+          return resultErr('invalid_callback');
+        }
+        const normalizedOptions = options == null ? {} : options;
+        if (!isPlainObject(normalizedOptions)) {
+          return resultErr('invalid_event_options');
+        }
+
+        let repeat = false;
+        if (Object.prototype.hasOwnProperty.call(normalizedOptions, 'repeat')) {
+          if (typeof normalizedOptions.repeat !== 'boolean') {
+            return resultErr('invalid_repeat_flag');
+          }
+          repeat = normalizedOptions.repeat;
+        }
+
+        let interval = delay;
+        if (Object.prototype.hasOwnProperty.call(normalizedOptions, 'interval')) {
+          interval = Number(normalizedOptions.interval);
+          if (!Number.isFinite(interval) || !(interval > 0)) {
+            return resultErr('invalid_interval');
+          }
+        }
+
+        let paused = false;
+        if (Object.prototype.hasOwnProperty.call(normalizedOptions, 'paused')) {
+          if (typeof normalizedOptions.paused !== 'boolean') {
+            return resultErr('invalid_paused_flag');
+          }
+          paused = normalizedOptions.paused;
+        }
+
+        const event = {
+          id: nextTimedEventId++,
+          delay,
+          interval,
+          remaining: delay,
+          repeat,
+          paused,
+          callback,
+          dispatchCount: 0,
+          sceneKey: activeScene ? activeScene.key : null,
+          createdTick: globalTicks,
+        };
+        timedEvents.set(event.id, event);
+        return resultOk('scene_event_scheduled', { eventId: event.id });
+      },
+      pauseEvent(eventId) {
+        const resolved = resolveEvent(eventId);
+        if (!resolved.event) return resultErr(resolved.reasonCode);
+        resolved.event.paused = true;
+        return resultOk('scene_event_paused', {
+          eventId: resolved.event.id,
+          paused: true,
+        });
+      },
+      resumeEvent(eventId) {
+        const resolved = resolveEvent(eventId);
+        if (!resolved.event) return resultErr(resolved.reasonCode);
+        resolved.event.paused = false;
+        return resultOk('scene_event_resumed', {
+          eventId: resolved.event.id,
+          paused: false,
+        });
+      },
+      cancelEvent(eventId) {
+        const resolved = resolveEvent(eventId);
+        if (!resolved.event) return resultErr(resolved.reasonCode);
+        timedEvents.delete(resolved.event.id);
+        return resultOk('scene_event_cancelled', {
+          eventId: resolved.event.id,
+          cancelled: true,
+        });
+      },
+      getEventState(eventId) {
+        const resolved = resolveEvent(eventId);
+        if (!resolved.event) return null;
+        return snapshotEvent(resolved.event);
+      },
+    };
+
+    return scene;
+  };
+  const scene = createSceneHelper();
+
+  let nextTilemapId = 1;
+  const tilemaps = new Map();
+  const tilemapIsPosInt = (value) => Number.isInteger(value) && value > 0;
+  const tilemapIsNonNegInt = (value) => Number.isInteger(value) && value >= 0;
+  const tilemapFiniteOr = (value, fallback) => (Number.isFinite(value) ? Number(value) : fallback);
+  const tilemapIntOr = (value, fallback) => (Number.isInteger(value) ? Number(value) : fallback);
+  const tilemapFail = (reason, detail = '') => {
+    const suffix = detail ? `: ${detail}` : '';
+    throw new Error(`aura.tilemap.import: ${reason}${suffix}`);
+  };
+  const tilemapResolveRawMap = (source) => {
+    if (source && typeof source === 'object') return source;
+    if (typeof source === 'string') {
+      const trimmed = source.trim();
+      if (trimmed.startsWith('{')) {
+        try {
+          return JSON.parse(trimmed);
+        } catch (error) {
+          tilemapFail('invalid-json', String(error));
+        }
+      }
+      if (aura?.assets && typeof aura.assets.loadJson === 'function') {
+        return aura.assets.loadJson(source);
+      }
+      if (aura?.assets && typeof aura.assets.json === 'function') {
+        return aura.assets.json(source);
+      }
+      tilemapFail('unsupported-source-string', 'assets.loadJson/json unavailable');
+    }
+    tilemapFail('invalid-source', 'expected object or string');
+  };
+  const tilemapResolveTilesetForGid = (tilesets, gid) => {
+    let selected = null;
+    for (const tileset of tilesets) {
+      if (tileset.firstGid <= gid) {
+        selected = tileset;
+      } else {
+        break;
+      }
+    }
+    if (!selected) return null;
+    const localIndex = gid - selected.firstGid;
+    if (selected.tileCount != null && localIndex >= selected.tileCount) {
+      return null;
+    }
+    return selected;
+  };
+  const tilemapNormalizePropertyValue = (value, contextLabel) => {
+    if (value == null) return null;
+    if (typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return Number(value);
+    tilemapFail('invalid-property-value', `${contextLabel} must be string/number/boolean/null`);
+  };
+  const tilemapNormalizeProperties = (rawProperties, contextLabel) => {
+    if (rawProperties == null) return {};
+    const normalized = {};
+    if (Array.isArray(rawProperties)) {
+      for (let i = 0; i < rawProperties.length; i += 1) {
+        const entry = rawProperties[i];
+        if (!entry || typeof entry !== 'object') {
+          tilemapFail('invalid-property-entry', `${contextLabel}.properties[${i}] must be an object`);
+        }
+        const name = typeof entry.name === 'string' ? entry.name.trim() : '';
+        if (!name) {
+          tilemapFail('invalid-property-name', `${contextLabel}.properties[${i}].name must be a non-empty string`);
+        }
+        if (Object.hasOwn(normalized, name)) {
+          tilemapFail('duplicate-property-name', `${contextLabel}.properties[${i}] duplicate name ${name}`);
+        }
+        normalized[name] = tilemapNormalizePropertyValue(entry.value, `${contextLabel}.properties[${i}].value`);
+      }
+      return Object.keys(normalized).sort().reduce((acc, key) => {
+        acc[key] = normalized[key];
+        return acc;
+      }, {});
+    }
+    if (typeof rawProperties !== 'object') {
+      tilemapFail('invalid-properties', `${contextLabel}.properties must be an object or array`);
+    }
+    const keys = Object.keys(rawProperties).sort();
+    for (const key of keys) {
+      if (typeof key !== 'string' || key.length === 0) {
+        tilemapFail('invalid-property-name', `${contextLabel}.properties contains an invalid key`);
+      }
+      normalized[key] = tilemapNormalizePropertyValue(rawProperties[key], `${contextLabel}.properties.${key}`);
+    }
+    return normalized;
+  };
+  const tilemapNormalizeObjectPoints = (rawPoints, contextLabel) => {
+    if (!Array.isArray(rawPoints) || rawPoints.length === 0) {
+      tilemapFail('invalid-object-points', `${contextLabel} must be a non-empty array`);
+    }
+    return rawPoints.map((point, pointIndex) => {
+      if (!point || typeof point !== 'object') {
+        tilemapFail('invalid-object-point', `${contextLabel}[${pointIndex}] must be an object`);
+      }
+      const x = tilemapFiniteOr(point.x, Number.NaN);
+      const y = tilemapFiniteOr(point.y, Number.NaN);
+      if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        tilemapFail('invalid-object-point', `${contextLabel}[${pointIndex}] x/y must be finite`);
+      }
+      return { x, y };
+    });
+  };
+  const tilemapNormalizeTilesets = (rawTilesets, mapTileWidth, mapTileHeight) => {
+    if (!Array.isArray(rawTilesets) || rawTilesets.length === 0) {
+      tilemapFail('invalid-tilesets', 'expected non-empty tilesets array');
+    }
+    const normalized = [];
+    for (let i = 0; i < rawTilesets.length; i += 1) {
+      const raw = rawTilesets[i];
+      if (!raw || typeof raw !== 'object') {
+        tilemapFail('invalid-tileset', `tileset[${i}] must be an object`);
+      }
+      const firstGid = Number(raw.firstgid);
+      if (!tilemapIsPosInt(firstGid)) {
+        tilemapFail('invalid-tileset-firstgid', `tileset[${i}].firstgid must be a positive integer`);
+      }
+      const image = typeof raw.image === 'string' && raw.image.length > 0 ? raw.image : null;
+      if (!image) {
+        tilemapFail('invalid-tileset-image', `tileset[${i}].image must be a non-empty string`);
+      }
+      const tileWidth = tilemapIsPosInt(raw.tilewidth) ? Number(raw.tilewidth) : mapTileWidth;
+      const tileHeight = tilemapIsPosInt(raw.tileheight) ? Number(raw.tileheight) : mapTileHeight;
+      const columns = Number(raw.columns);
+      if (!tilemapIsPosInt(columns)) {
+        tilemapFail('invalid-tileset-columns', `tileset[${i}].columns must be a positive integer`);
+      }
+      const tileCount = raw.tilecount == null
+        ? null
+        : (tilemapIsPosInt(raw.tilecount) ? Number(raw.tilecount) : null);
+      if (raw.tilecount != null && tileCount == null) {
+        tilemapFail('invalid-tileset-tilecount', `tileset[${i}].tilecount must be a positive integer`);
+      }
+      normalized.push({
+        firstGid,
+        image,
+        tileWidth,
+        tileHeight,
+        columns,
+        tileCount,
+        margin: tilemapIsNonNegInt(raw.margin) ? Number(raw.margin) : 0,
+        spacing: tilemapIsNonNegInt(raw.spacing) ? Number(raw.spacing) : 0,
+        properties: tilemapNormalizeProperties(raw.properties, `tilesets[${i}]`),
+      });
+    }
+    normalized.sort((a, b) => a.firstGid - b.firstGid);
+    for (let i = 1; i < normalized.length; i += 1) {
+      if (normalized[i - 1].firstGid === normalized[i].firstGid) {
+        tilemapFail('duplicate-tileset-firstgid', String(normalized[i].firstGid));
+      }
+    }
+    return normalized;
+  };
+  const tilemapNormalizeObjectLayer = (rawLayer, layerIndex, mapWidth, mapHeight, tilesets) => {
+    const objectContext = `layers[${layerIndex}]`;
+    if (rawLayer.compression) {
+      tilemapFail('unsupported-layer-compression', `${objectContext} compression is not supported`);
+    }
+    if (rawLayer.encoding && rawLayer.encoding !== 'csv') {
+      tilemapFail('unsupported-layer-encoding', `${objectContext} encoding must be omitted or csv`);
+    }
+    if (rawLayer.objects != null && !Array.isArray(rawLayer.objects)) {
+      tilemapFail('invalid-object-layer-objects', `${objectContext}.objects must be an array when provided`);
+    }
+    const rawObjects = Array.isArray(rawLayer.objects) ? rawLayer.objects : [];
+    const normalizedObjects = [];
+    for (let objectIndex = 0; objectIndex < rawObjects.length; objectIndex += 1) {
+      const rawObject = rawObjects[objectIndex];
+      const context = `${objectContext}.objects[${objectIndex}]`;
+      if (!rawObject || typeof rawObject !== 'object') {
+        tilemapFail('invalid-object', `${context} must be an object`);
+      }
+      if (rawObject.template != null) {
+        tilemapFail('unsupported-object-template', `${context}.template is not supported`);
+      }
+      if (rawObject.text != null) {
+        tilemapFail('unsupported-object-text', `${context}.text is not supported`);
+      }
+
+      const id = rawObject.id == null ? (objectIndex + 1) : Number(rawObject.id);
+      if (!tilemapIsNonNegInt(id)) {
+        tilemapFail('invalid-object-id', `${context}.id must be a non-negative integer`);
+      }
+      const gid = rawObject.gid == null ? 0 : Number(rawObject.gid);
+      if (!tilemapIsNonNegInt(gid)) {
+        tilemapFail('invalid-object-gid', `${context}.gid must be a non-negative integer`);
+      }
+      if (gid > 0 && !tilemapResolveTilesetForGid(tilesets, gid)) {
+        tilemapFail('unmapped-object-gid', `${context}.gid ${gid} has no matching tileset`);
+      }
+
+      const x = tilemapFiniteOr(rawObject.x, Number.NaN);
+      const y = tilemapFiniteOr(rawObject.y, Number.NaN);
+      if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        tilemapFail('invalid-object-position', `${context}.x/y must be finite numbers`);
+      }
+      const width = rawObject.width == null ? 0 : tilemapFiniteOr(rawObject.width, Number.NaN);
+      const height = rawObject.height == null ? 0 : tilemapFiniteOr(rawObject.height, Number.NaN);
+      if (!Number.isFinite(width) || !Number.isFinite(height) || width < 0 || height < 0) {
+        tilemapFail('invalid-object-size', `${context}.width/height must be finite numbers >= 0`);
+      }
+      const rotation = rawObject.rotation == null ? 0 : tilemapFiniteOr(rawObject.rotation, Number.NaN);
+      if (!Number.isFinite(rotation)) {
+        tilemapFail('invalid-object-rotation', `${context}.rotation must be finite`);
+      }
+
+      const hasPolygon = Array.isArray(rawObject.polygon);
+      const hasPolyline = Array.isArray(rawObject.polyline);
+      if (hasPolygon && hasPolyline) {
+        tilemapFail('invalid-object-shape', `${context} cannot include both polygon and polyline`);
+      }
+      const properties = tilemapNormalizeProperties(rawObject.properties, context);
+      normalizedObjects.push({
+        id,
+        name: typeof rawObject.name === 'string' ? rawObject.name : '',
+        className: typeof rawObject.class === 'string'
+          ? rawObject.class
+          : (typeof rawObject.type === 'string' ? rawObject.type : ''),
+        type: typeof rawObject.type === 'string' ? rawObject.type : '',
+        x,
+        y,
+        width,
+        height,
+        rotation,
+        visible: rawObject.visible !== false,
+        gid,
+        point: rawObject.point === true,
+        ellipse: rawObject.ellipse === true,
+        polygon: hasPolygon ? tilemapNormalizeObjectPoints(rawObject.polygon, `${context}.polygon`) : null,
+        polyline: hasPolyline ? tilemapNormalizeObjectPoints(rawObject.polyline, `${context}.polyline`) : null,
+        properties,
+        _seq: objectIndex,
+      });
+    }
+    normalizedObjects.sort((a, b) => (a.id - b.id) || (a._seq - b._seq));
+    const objects = normalizedObjects.map((entry) => {
+      const shape = entry.polygon ? 'polygon'
+        : (entry.polyline ? 'polyline'
+          : (entry.point ? 'point'
+            : (entry.ellipse ? 'ellipse'
+              : (entry.gid > 0 ? 'tile' : 'rectangle'))));
+      return {
+        id: entry.id,
+        name: entry.name,
+        className: entry.className,
+        type: entry.type,
+        x: entry.x,
+        y: entry.y,
+        width: entry.width,
+        height: entry.height,
+        rotation: entry.rotation,
+        visible: entry.visible,
+        gid: entry.gid,
+        point: entry.point,
+        ellipse: entry.ellipse,
+        polygon: entry.polygon,
+        polyline: entry.polyline,
+        properties: entry.properties,
+        shape,
+      };
+    });
+    return {
+      index: layerIndex,
+      name: typeof rawLayer.name === 'string' && rawLayer.name.length > 0 ? rawLayer.name : `layer_${layerIndex}`,
+      width: tilemapIsPosInt(rawLayer.width) ? Number(rawLayer.width) : mapWidth,
+      height: tilemapIsPosInt(rawLayer.height) ? Number(rawLayer.height) : mapHeight,
+      visible: rawLayer.visible !== false,
+      opacity: Number.isFinite(rawLayer.opacity) ? Number(rawLayer.opacity) : 1,
+      offsetX: tilemapFiniteOr(rawLayer.offsetx, 0),
+      offsetY: tilemapFiniteOr(rawLayer.offsety, 0),
+      drawOrder: typeof rawLayer.draworder === 'string' && rawLayer.draworder.length > 0
+        ? rawLayer.draworder
+        : 'topdown',
+      properties: tilemapNormalizeProperties(rawLayer.properties, objectContext),
+      objects,
+    };
+  };
+  const tilemapNormalizeLayers = (rawLayers, mapWidth, mapHeight, tilesets) => {
+    if (!Array.isArray(rawLayers) || rawLayers.length === 0) {
+      tilemapFail('invalid-layers', 'expected non-empty layers array');
+    }
+    const tileLayers = [];
+    const objectLayers = [];
+    for (let i = 0; i < rawLayers.length; i += 1) {
+      const raw = rawLayers[i];
+      if (!raw || typeof raw !== 'object') {
+        tilemapFail('invalid-layer', `layers[${i}] must be an object`);
+      }
+      if (raw.type === 'objectgroup') {
+        objectLayers.push(tilemapNormalizeObjectLayer(raw, i, mapWidth, mapHeight, tilesets));
+        continue;
+      }
+      if (raw.type !== 'tilelayer') continue;
+      if (raw.compression) {
+        tilemapFail('unsupported-layer-compression', `layers[${i}] compression is not supported`);
+      }
+      if (raw.encoding && raw.encoding !== 'csv') {
+        tilemapFail('unsupported-layer-encoding', `layers[${i}] encoding must be omitted or csv`);
+      }
+      const width = tilemapIsPosInt(raw.width) ? Number(raw.width) : mapWidth;
+      const height = tilemapIsPosInt(raw.height) ? Number(raw.height) : mapHeight;
+      if (!Array.isArray(raw.data) || raw.data.length !== width * height) {
+        tilemapFail('invalid-layer-data', `layers[${i}] data length must equal width*height`);
+      }
+      const data = new Array(raw.data.length);
+      for (let index = 0; index < raw.data.length; index += 1) {
+        const gid = Number(raw.data[index]);
+        if (!tilemapIsNonNegInt(gid)) {
+          tilemapFail('invalid-layer-gid', `layers[${i}] gid at index ${index} must be a non-negative integer`);
+        }
+        if (gid > 0 && !tilemapResolveTilesetForGid(tilesets, gid)) {
+          tilemapFail('unmapped-layer-gid', `layers[${i}] gid ${gid} has no matching tileset`);
+        }
+        data[index] = gid;
+      }
+      const properties = tilemapNormalizeProperties(raw.properties, `layers[${i}]`);
+      const layerQueryEnabled = raw.solid === true || raw.collision === true || properties.solid === true;
+      tileLayers.push({
+        index: i,
+        name: typeof raw.name === 'string' && raw.name.length > 0 ? raw.name : `layer_${i}`,
+        width,
+        height,
+        data,
+        solid: layerQueryEnabled,
+        collision: raw.collision === true,
+        queryEnabled: layerQueryEnabled,
+        properties,
+        visible: raw.visible !== false,
+        opacity: Number.isFinite(raw.opacity) ? Number(raw.opacity) : 1,
+        offsetX: tilemapFiniteOr(raw.offsetx, 0),
+        offsetY: tilemapFiniteOr(raw.offsety, 0),
+      });
+    }
+    if (tileLayers.length === 0) {
+      tilemapFail('missing-tile-layers', 'expected at least one tilelayer');
+    }
+    return { tileLayers, objectLayers };
+  };
+  const tilemapNormalizeMap = (rawMap) => {
+    if (!rawMap || typeof rawMap !== 'object') {
+      tilemapFail('invalid-map', 'expected object map payload');
+    }
+    const mapWidth = Number(rawMap.width);
+    const mapHeight = Number(rawMap.height);
+    const tileWidth = Number(rawMap.tilewidth);
+    const tileHeight = Number(rawMap.tileheight);
+    if (!tilemapIsPosInt(mapWidth) || !tilemapIsPosInt(mapHeight)) {
+      tilemapFail('invalid-map-size', 'width and height must be positive integers');
+    }
+    if (!tilemapIsPosInt(tileWidth) || !tilemapIsPosInt(tileHeight)) {
+      tilemapFail('invalid-map-tile-size', 'tilewidth and tileheight must be positive integers');
+    }
+    const tilesets = tilemapNormalizeTilesets(rawMap.tilesets, tileWidth, tileHeight);
+    const layers = tilemapNormalizeLayers(rawMap.layers, mapWidth, mapHeight, tilesets);
+    const solidLayerNames = new Set();
+    const appendSolidLayerNames = (value) => {
+      if (!Array.isArray(value)) return;
+      for (const entry of value) {
+        if (typeof entry === 'string' && entry.length > 0) {
+          solidLayerNames.add(entry);
+        }
+      }
+    };
+    appendSolidLayerNames(rawMap.solidLayerNames);
+    appendSolidLayerNames(rawMap.solidLayers);
+    const normalizedMap = {
+      width: mapWidth,
+      height: mapHeight,
+      tileWidth,
+      tileHeight,
+      tilesets,
+      layers: layers.tileLayers,
+      objectLayers: layers.objectLayers,
+      properties: tilemapNormalizeProperties(rawMap.properties, 'map'),
+      solidLayerNames: [...solidLayerNames],
+    };
+    for (const layer of normalizedMap.layers) {
+      if (solidLayerNames.has(layer.name)) {
+        layer.queryEnabled = true;
+      }
+    }
+    return normalizedMap;
+  };
+  const tilemapResolveMap = (mapId) => {
+    const id = tilemapIntOr(mapId, -1);
+    if (id <= 0) return null;
+    return tilemaps.get(id) || null;
+  };
+  const tilemapResolveLayerRef = (map, layerRef) => {
+    if (!map) return null;
+    if (typeof layerRef === 'number' && Number.isInteger(layerRef)) {
+      if (layerRef < 0 || layerRef >= map.layers.length) return null;
+      return { layer: map.layers[layerRef], layerIndex: layerRef };
+    }
+    if (typeof layerRef === 'string') {
+      const layerIndex = map.layers.findIndex((layer) => layer.name === layerRef);
+      if (layerIndex < 0) return null;
+      return { layer: map.layers[layerIndex], layerIndex };
+    }
+    return null;
+  };
+  const tilemapResolveLayerMutationTarget = (mapId, layerRef) => {
+    const map = tilemapResolveMap(mapId);
+    if (!map) {
+      return { ok: false, error: 'invalid tilemap handle', reasonCode: 'invalid_map_handle' };
+    }
+    const resolved = tilemapResolveLayerRef(map, layerRef);
+    if (!resolved) {
+      return { ok: false, error: 'invalid tilemap layer', reasonCode: 'invalid_layer_ref' };
+    }
+    return {
+      ok: true,
+      map,
+      mapId: tilemapIntOr(mapId, -1),
+      layer: resolved.layer,
+      layerIndex: resolved.layerIndex,
+    };
+  };
+  const tilemapMutationFailResult = (error, reasonCode) => ({
+    ok: false,
+    error,
+    reasonCode,
+    mutatedTiles: 0,
+    changedTiles: 0,
+  });
+  const tilemapMutationOkResult = (payload = {}) => ({
+    ok: true,
+    error: null,
+    reasonCode: null,
+    ...payload,
+  });
+  const tilemapParseBooleanFlag = (value) => (typeof value === 'boolean' ? value : null);
+  const tilemapParseNonNegGid = (value) => {
+    const gid = Number(value);
+    if (!tilemapIsNonNegInt(gid)) return null;
+    return gid;
+  };
+  const tilemapParseRegionArgs = (args, offset = 0) => {
+    const value = args[offset];
+    let x = null;
+    let y = null;
+    let w = null;
+    let h = null;
+    let nextIndex = offset;
+    if (value && typeof value === 'object') {
+      x = Number(value.x);
+      y = Number(value.y);
+      w = Number(value.w);
+      h = Number(value.h);
+      nextIndex = offset + 1;
+    } else {
+      x = Number(args[offset]);
+      y = Number(args[offset + 1]);
+      w = Number(args[offset + 2]);
+      h = Number(args[offset + 3]);
+      nextIndex = offset + 4;
+    }
+    if (!Number.isInteger(x) || !Number.isInteger(y) || !Number.isInteger(w) || !Number.isInteger(h) || w <= 0 || h <= 0) {
+      return null;
+    }
+    return { x, y, w, h, nextIndex };
+  };
+  const tilemapApplyRegionMutation = (layer, region, mutateCell) => {
+    const startX = Math.max(0, region.x);
+    const startY = Math.max(0, region.y);
+    const endX = Math.min(layer.width, region.x + region.w);
+    const endY = Math.min(layer.height, region.y + region.h);
+    let mutatedTiles = 0;
+    let changedTiles = 0;
+
+    for (let y = startY; y < endY; y += 1) {
+      for (let x = startX; x < endX; x += 1) {
+        mutatedTiles += 1;
+        const index = (y * layer.width) + x;
+        const previousGid = layer.data[index];
+        const nextGid = mutateCell(previousGid, x, y);
+        if (nextGid === previousGid) continue;
+        layer.data[index] = nextGid;
+        changedTiles += 1;
+      }
+    }
+
+    return {
+      mutatedTiles,
+      changedTiles,
+      requestedRegion: { x: region.x, y: region.y, w: region.w, h: region.h },
+      appliedRegion: {
+        x: startX,
+        y: startY,
+        w: Math.max(0, endX - startX),
+        h: Math.max(0, endY - startY),
+      },
+    };
+  };
+  const tilemapBuildViewRect = (options) => {
+    if (!options || typeof options !== 'object') return null;
+    if (options.cull === false) return null;
+    const camera = (options.camera && typeof options.camera === 'object')
+      ? options.camera
+      : ((options.view && typeof options.view === 'object') ? options.view : null);
+    if (!camera) return null;
+    const widthValue = tilemapFiniteOr(camera.width, Number.NaN);
+    const heightValue = tilemapFiniteOr(camera.height, Number.NaN);
+    if (!(widthValue > 0) || !(heightValue > 0)) return null;
+    return {
+      x: tilemapFiniteOr(camera.x, 0),
+      y: tilemapFiniteOr(camera.y, 0),
+      width: widthValue,
+      height: heightValue,
+    };
+  };
+  const tilemapIntersects = (x, y, w, h, view) => {
+    if (!view) return true;
+    return x < (view.x + view.width)
+      && (x + w) > view.x
+      && y < (view.y + view.height)
+      && (y + h) > view.y;
+  };
+  const tilemapDrawLayerInternal = (map, mapId, layer, layerIndex, options) => {
+    const includeHidden = options && options.includeHidden === true;
+    const originX = options && Number.isFinite(options.x) ? Number(options.x) : 0;
+    const originY = options && Number.isFinite(options.y) ? Number(options.y) : 0;
+    const view = tilemapBuildViewRect(options);
+    const stats = {
+      mapId,
+      layerName: layer.name,
+      layerIndex,
+      consideredTiles: 0,
+      drawnTiles: 0,
+      culledTiles: 0,
+    };
+    if (!includeHidden && (!layer.visible || layer.opacity <= 0)) {
+      return stats;
+    }
+    for (let y = 0; y < layer.height; y += 1) {
+      for (let x = 0; x < layer.width; x += 1) {
+        const gid = layer.data[(y * layer.width) + x];
+        if (!gid || gid <= 0) continue;
+        stats.consideredTiles += 1;
+        const drawX = originX + layer.offsetX + (x * map.tileWidth);
+        const drawY = originY + layer.offsetY + (y * map.tileHeight);
+        if (!tilemapIntersects(drawX, drawY, map.tileWidth, map.tileHeight, view)) {
+          stats.culledTiles += 1;
+          continue;
+        }
+        const tileset = tilemapResolveTilesetForGid(map.tilesets, gid);
+        if (!tileset) continue;
+        const localIndex = gid - tileset.firstGid;
+        const frameX = tileset.margin + ((localIndex % tileset.columns) * (tileset.tileWidth + tileset.spacing));
+        const frameY = tileset.margin + (Math.floor(localIndex / tileset.columns) * (tileset.tileHeight + tileset.spacing));
+        stats.drawnTiles += 1;
+        if (aura?.draw2d && typeof aura.draw2d.sprite === 'function') {
+          aura.draw2d.sprite(
+            { path: tileset.image },
+            drawX,
+            drawY,
+            {
+              width: map.tileWidth,
+              height: map.tileHeight,
+              frameX,
+              frameY,
+              frameW: tileset.tileWidth,
+              frameH: tileset.tileHeight,
+            },
+          );
+        }
+      }
+    }
+    return stats;
+  };
+  const tilemap = {
+    import: (source) => {
+      const rawMap = tilemapResolveRawMap(source);
+      const normalizedMap = tilemapNormalizeMap(rawMap);
+      const id = nextTilemapId++;
+      tilemaps.set(id, normalizedMap);
+      return id;
+    },
+    unload: (mapId) => {
+      const id = tilemapIntOr(mapId, -1);
+      if (id <= 0) return false;
+      return tilemaps.delete(id);
+    },
+    getInfo: (mapId) => {
+      const map = tilemapResolveMap(mapId);
+      if (!map) return null;
+      const objectLayerCount = Array.isArray(map.objectLayers) ? map.objectLayers.length : 0;
+      const objectCount = objectLayerCount > 0
+        ? map.objectLayers.reduce((sum, layer) => sum + (Array.isArray(layer.objects) ? layer.objects.length : 0), 0)
+        : 0;
+      return {
+        mapId: tilemapIntOr(mapId, -1),
+        width: map.width,
+        height: map.height,
+        tileWidth: map.tileWidth,
+        tileHeight: map.tileHeight,
+        layerCount: map.layers.length,
+        objectLayerCount,
+        objectCount,
+        tilesetCount: map.tilesets.length,
+        mapPropertyCount: map.properties ? Object.keys(map.properties).length : 0,
+      };
+    },
+    drawLayer: (mapId, layerRef, options = {}) => {
+      const map = tilemapResolveMap(mapId);
+      if (!map) return null;
+      const resolved = tilemapResolveLayerRef(map, layerRef);
+      if (!resolved) return null;
+      return tilemapDrawLayerInternal(map, tilemapIntOr(mapId, -1), resolved.layer, resolved.layerIndex, options);
+    },
+    draw: (mapId, options = {}) => {
+      const map = tilemapResolveMap(mapId);
+      if (!map) return null;
+      const includeHidden = options && options.includeHidden === true;
+      const layers = [];
+      const layerOrder = [];
+      for (let i = 0; i < map.layers.length; i += 1) {
+        const layer = map.layers[i];
+        if (!includeHidden && (!layer.visible || layer.opacity <= 0)) continue;
+        const layerStats = tilemapDrawLayerInternal(map, tilemapIntOr(mapId, -1), layer, i, options);
+        layers.push(layerStats);
+        layerOrder.push(layer.name);
+      }
+      let consideredTiles = 0;
+      let drawnTiles = 0;
+      let culledTiles = 0;
+      for (const layerStats of layers) {
+        consideredTiles += layerStats.consideredTiles;
+        drawnTiles += layerStats.drawnTiles;
+        culledTiles += layerStats.culledTiles;
+      }
+      return {
+        mapId: tilemapIntOr(mapId, -1),
+        layerOrder,
+        consideredTiles,
+        drawnTiles,
+        culledTiles,
+        layers,
+      };
+    },
+    setRegion: (mapId, layerRef, ...args) => {
+      const target = tilemapResolveLayerMutationTarget(mapId, layerRef);
+      if (!target.ok) return tilemapMutationFailResult(target.error, target.reasonCode);
+      const region = tilemapParseRegionArgs(args, 0);
+      if (!region) return tilemapMutationFailResult('invalid tilemap region args', 'invalid_region_args');
+      const gid = tilemapParseNonNegGid(args[region.nextIndex]);
+      if (gid == null) return tilemapMutationFailResult('invalid tile gid args', 'invalid_gid_args');
+      if (gid > 0 && !tilemapResolveTilesetForGid(target.map.tilesets, gid)) {
+        return tilemapMutationFailResult('invalid tile gid args', 'unmapped_layer_gid');
+      }
+      const mutation = tilemapApplyRegionMutation(target.layer, region, () => gid);
+      return tilemapMutationOkResult({
+        mapId: target.mapId,
+        layerName: target.layer.name,
+        layerIndex: target.layerIndex,
+        gid,
+        ...mutation,
+      });
+    },
+    removeRegion: (mapId, layerRef, ...args) => {
+      const target = tilemapResolveLayerMutationTarget(mapId, layerRef);
+      if (!target.ok) return tilemapMutationFailResult(target.error, target.reasonCode);
+      const region = tilemapParseRegionArgs(args, 0);
+      if (!region) return tilemapMutationFailResult('invalid tilemap region args', 'invalid_region_args');
+      const mutation = tilemapApplyRegionMutation(target.layer, region, () => 0);
+      return tilemapMutationOkResult({
+        mapId: target.mapId,
+        layerName: target.layer.name,
+        layerIndex: target.layerIndex,
+        gid: 0,
+        ...mutation,
+      });
+    },
+    replaceRegion: (mapId, layerRef, ...args) => {
+      const target = tilemapResolveLayerMutationTarget(mapId, layerRef);
+      if (!target.ok) return tilemapMutationFailResult(target.error, target.reasonCode);
+      const region = tilemapParseRegionArgs(args, 0);
+      if (!region) return tilemapMutationFailResult('invalid tilemap region args', 'invalid_region_args');
+      const fromGid = tilemapParseNonNegGid(args[region.nextIndex]);
+      const toGid = tilemapParseNonNegGid(args[region.nextIndex + 1]);
+      if (fromGid == null || toGid == null) {
+        return tilemapMutationFailResult('invalid replace gid args', 'invalid_replace_args');
+      }
+      if (toGid > 0 && !tilemapResolveTilesetForGid(target.map.tilesets, toGid)) {
+        return tilemapMutationFailResult('invalid replace gid args', 'unmapped_layer_gid');
+      }
+      const mutation = tilemapApplyRegionMutation(
+        target.layer,
+        region,
+        (previousGid) => (previousGid === fromGid ? toGid : previousGid),
+      );
+      return tilemapMutationOkResult({
+        mapId: target.mapId,
+        layerName: target.layer.name,
+        layerIndex: target.layerIndex,
+        fromGid,
+        toGid,
+        replacedTiles: mutation.changedTiles,
+        ...mutation,
+      });
+    },
+    setLayerFlags: (mapId, layerRef, flags = {}) => {
+      const target = tilemapResolveLayerMutationTarget(mapId, layerRef);
+      if (!target.ok) return tilemapMutationFailResult(target.error, target.reasonCode);
+      if (!flags || typeof flags !== 'object') {
+        return tilemapMutationFailResult('invalid layer flags args', 'invalid_layer_flags');
+      }
+      const hasVisible = Object.hasOwn(flags, 'visible');
+      const hasCollision = Object.hasOwn(flags, 'collision');
+      if (!hasVisible && !hasCollision) {
+        return tilemapMutationFailResult('invalid layer flags args', 'invalid_layer_flags');
+      }
+
+      const nextVisible = hasVisible ? tilemapParseBooleanFlag(flags.visible) : target.layer.visible;
+      const nextCollision = hasCollision ? tilemapParseBooleanFlag(flags.collision) : (target.layer.queryEnabled !== false);
+      if (hasVisible && nextVisible == null) {
+        return tilemapMutationFailResult('invalid layer visibility flag', 'invalid_visibility_flag');
+      }
+      if (hasCollision && nextCollision == null) {
+        return tilemapMutationFailResult('invalid layer collision flag', 'invalid_collision_flag');
+      }
+
+      const changed = (target.layer.visible !== nextVisible)
+        || ((target.layer.queryEnabled !== false) !== nextCollision);
+      target.layer.visible = nextVisible;
+      target.layer.collision = nextCollision;
+      target.layer.queryEnabled = nextCollision;
+
+      return tilemapMutationOkResult({
+        mapId: target.mapId,
+        layerName: target.layer.name,
+        layerIndex: target.layerIndex,
+        visible: target.layer.visible,
+        collision: target.layer.queryEnabled !== false,
+        changed,
+        mutatedTiles: 0,
+        changedTiles: 0,
+      });
+    },
+    setLayerVisibility: (mapId, layerRef, visible) => tilemap.setLayerFlags(
+      mapId,
+      layerRef,
+      { visible },
+    ),
+    setLayerCollision: (mapId, layerRef, collision) => tilemap.setLayerFlags(
+      mapId,
+      layerRef,
+      { collision },
+    ),
+  };
+
+  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);
+    },
+  };
+
+  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 },
+    metallic: 0,
+    roughness: 1,
+    texture: null,
+  });
+  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 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 },
+      metallic: clampUnit(options.metallic, defaultMaterialState.metallic),
+      roughness: clampUnit(options.roughness, defaultMaterialState.roughness),
+      texture: typeof options.texture === 'string' && options.texture.length > 0 ? options.texture : null,
+    };
+  };
+
+  const createTilemapQueryBridge = () => {
+    const isFiniteNumber = (value) => Number.isFinite(value);
+    const toPositiveInteger = (value) => {
+      if (!isFiniteNumber(value)) return null;
+      const parsed = Math.floor(Number(value));
+      return parsed > 0 ? parsed : null;
+    };
+    const toFinite = (value) => (
+      isFiniteNumber(value) ? Number(value) : null
+    );
+    const normalizeLayerNameSet = (model) => {
+      const names = new Set();
+      const append = (value) => {
+        if (!Array.isArray(value)) return;
+        for (const entry of value) {
+          if (typeof entry === 'string' && entry.length > 0) {
+            names.add(entry);
+          }
+        }
+      };
+      append(model?.solidLayerNames);
+      append(model?.solidLayers);
+      return names;
+    };
+    const sortHits = (hits) => {
+      hits.sort((a, b) => {
+        if (a.layerIndex !== b.layerIndex) return a.layerIndex - b.layerIndex;
+        if (a.y !== b.y) return a.y - b.y;
+        if (a.x !== b.x) return a.x - b.x;
+        if (a.layerName === b.layerName) return 0;
+        return a.layerName < b.layerName ? -1 : 1;
+      });
+      return hits;
+    };
+    const normalizeModel = (model) => {
+      if (!model || typeof model !== 'object') {
+        return { ok: false, error: 'invalid tilemap model', reasonCode: 'invalid_model' };
+      }
+
+      const width = toPositiveInteger(model.width);
+      const height = toPositiveInteger(model.height);
+      const tileWidth = toFinite(model.tileWidth ?? model.tilewidth);
+      const tileHeight = toFinite(model.tileHeight ?? model.tileheight);
+      if (width == null || height == null || tileWidth == null || tileHeight == null || tileWidth <= 0 || tileHeight <= 0) {
+        return { ok: false, error: 'invalid tilemap model', reasonCode: 'invalid_model' };
+      }
+
+      const solidNameSet = normalizeLayerNameSet(model);
+      const cells = [];
+      const seen = new Set();
+      const pushCell = (x, y, layerIndex, layerName) => {
+        if (!Number.isInteger(x) || !Number.isInteger(y)) return;
+        if (x < 0 || y < 0 || x >= width || y >= height) return;
+        const normalizedLayerIndex = Number.isInteger(layerIndex) ? layerIndex : 0;
+        const normalizedLayerName = typeof layerName === 'string' && layerName.length > 0
+          ? layerName
+          : `layer-${normalizedLayerIndex}`;
+        const key = `${normalizedLayerIndex}|${y}|${x}|${normalizedLayerName}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        cells.push({
+          x,
+          y,
+          layerIndex: normalizedLayerIndex,
+          layerName: normalizedLayerName,
+          worldX: x * tileWidth,
+          worldY: y * tileHeight,
+          worldW: tileWidth,
+          worldH: tileHeight,
+        });
+      };
+
+      if (Array.isArray(model.solidCells)) {
+        for (const entry of model.solidCells) {
+          if (!entry || typeof entry !== 'object') continue;
+          pushCell(
+            Number(entry.x),
+            Number(entry.y),
+            Number(entry.layerIndex),
+            entry.layerName,
+          );
+        }
+      }
+
+      if (Array.isArray(model.layers)) {
+        for (let layerIndex = 0; layerIndex < model.layers.length; layerIndex += 1) {
+          const layer = model.layers[layerIndex];
+          if (!layer || typeof layer !== 'object') continue;
+          const layerName = typeof layer.name === 'string' && layer.name.length > 0
+            ? layer.name
+            : `layer-${layerIndex}`;
+          const layerWidth = toPositiveInteger(layer.width) ?? width;
+          const layerHeight = toPositiveInteger(layer.height) ?? height;
+          if (layerWidth !== width || layerHeight !== height) continue;
+
+          const layerSolid = typeof layer.queryEnabled === 'boolean'
+            ? layer.queryEnabled
+            : (
+              layer.solid === true
+              || layer.collision === true
+              || layer.properties?.solid === true
+              || solidNameSet.has(layerName)
+            );
+          if (!layerSolid) continue;
+          if (!Array.isArray(layer.data)) continue;
+
+          const maxEntries = Math.min(layer.data.length, width * height);
+          for (let index = 0; index < maxEntries; index += 1) {
+            const gid = Number(layer.data[index]);
+            if (!isFiniteNumber(gid) || gid <= 0) continue;
+            const x = index % width;
+            const y = Math.floor(index / width);
+            pushCell(x, y, layerIndex, layerName);
+          }
+        }
+      }
+
+      sortHits(cells);
+      return {
+        ok: true,
+        width,
+        height,
+        tileWidth,
+        tileHeight,
+        cells,
+      };
+    };
+    const resolveQueryModelInput = (input) => {
+      if (typeof input === 'number' && Number.isInteger(input)) {
+        if (input <= 0) {
+          return { ok: false, error: 'invalid tilemap handle', reasonCode: 'invalid_map_handle' };
+        }
+        const map = tilemapResolveMap(input);
+        if (!map) {
+          return { ok: false, error: 'invalid tilemap handle', reasonCode: 'invalid_map_handle' };
+        }
+        return { ok: true, model: map };
+      }
+      if (!input || typeof input !== 'object') {
+        return { ok: false, error: 'invalid tilemap model', reasonCode: 'invalid_model' };
+      }
+      return { ok: true, model: input };
+    };
+    const parsePointArgs = (args, offset) => {
+      const value = args[offset];
+      if (value && typeof value === 'object') {
+        const x = toFinite(value.x);
+        const y = toFinite(value.y);
+        if (x == null || y == null) return null;
+        return { x, y };
+      }
+      const x = toFinite(args[offset]);
+      const y = toFinite(args[offset + 1]);
+      if (x == null || y == null) return null;
+      return { x, y };
+    };
+    const parseAabbArgs = (args, offset) => {
+      const value = args[offset];
+      if (value && typeof value === 'object') {
+        const x = toFinite(value.x);
+        const y = toFinite(value.y);
+        const w = toFinite(value.w);
+        const h = toFinite(value.h);
+        if (x == null || y == null || w == null || h == null) return null;
+        return { x, y, w, h };
+      }
+      const x = toFinite(args[offset]);
+      const y = toFinite(args[offset + 1]);
+      const w = toFinite(args[offset + 2]);
+      const h = toFinite(args[offset + 3]);
+      if (x == null || y == null || w == null || h == null) return null;
+      return { x, y, w, h };
+    };
+    const parseRayArgs = (args, offset) => {
+      const value = args[offset];
+      if (value && typeof value === 'object') {
+        const x = toFinite(value.x);
+        const y = toFinite(value.y);
+        const dx = toFinite(value.dx);
+        const dy = toFinite(value.dy);
+        const maxDistance = toFinite(value.maxDistance ?? value.maxToi ?? 10000);
+        if (x == null || y == null || dx == null || dy == null || maxDistance == null) return null;
+        return { x, y, dx, dy, maxDistance };
+      }
+      const x = toFinite(args[offset]);
+      const y = toFinite(args[offset + 1]);
+      const dx = toFinite(args[offset + 2]);
+      const dy = toFinite(args[offset + 3]);
+      const maxDistance = toFinite(args[offset + 4] ?? 10000);
+      if (x == null || y == null || dx == null || dy == null || maxDistance == null) return null;
+      return { x, y, dx, dy, maxDistance };
+    };
+    const hitsAtTile = (normalizedModel, tileX, tileY) => {
+      if (!Number.isInteger(tileX) || !Number.isInteger(tileY)) return [];
+      return normalizedModel.cells.filter((cell) => cell.x === tileX && cell.y === tileY);
+    };
+    const failResult = (error, reasonCode) => ({
+      ok: false,
+      hit: false,
+      hits: [],
+      error,
+      reasonCode,
+    });
+    const okResult = (payload) => ({
+      ok: true,
+      error: null,
+      reasonCode: null,
+      ...payload,
+    });
+
+    const queryPoint = (mapOrModel, ...args) => {
+      const resolvedModel = resolveQueryModelInput(mapOrModel);
+      if (!resolvedModel.ok) return failResult(resolvedModel.error, resolvedModel.reasonCode);
+      const normalizedModel = normalizeModel(resolvedModel.model);
+      if (!normalizedModel.ok) return failResult(normalizedModel.error, normalizedModel.reasonCode);
+      const point = parsePointArgs(args, 0);
+      if (!point) return failResult('invalid point query args', 'invalid_point_args');
+      const tileX = Math.floor(point.x / normalizedModel.tileWidth);
+      const tileY = Math.floor(point.y / normalizedModel.tileHeight);
+      const hits = hitsAtTile(normalizedModel, tileX, tileY);
+      return okResult({ hit: hits.length > 0, hits, tileX, tileY });
+    };
+
+    const queryAABB = (mapOrModel, ...args) => {
+      const resolvedModel = resolveQueryModelInput(mapOrModel);
+      if (!resolvedModel.ok) return failResult(resolvedModel.error, resolvedModel.reasonCode);
+      const normalizedModel = normalizeModel(resolvedModel.model);
+      if (!normalizedModel.ok) return failResult(normalizedModel.error, normalizedModel.reasonCode);
+      const rect = parseAabbArgs(args, 0);
+      if (!rect || rect.w <= 0 || rect.h <= 0) return failResult('invalid aabb query args', 'invalid_aabb_args');
+
+      const epsilon = 1e-9;
+      const minTileX = Math.floor(rect.x / normalizedModel.tileWidth);
+      const minTileY = Math.floor(rect.y / normalizedModel.tileHeight);
+      const maxTileX = Math.floor((rect.x + rect.w - epsilon) / normalizedModel.tileWidth);
+      const maxTileY = Math.floor((rect.y + rect.h - epsilon) / normalizedModel.tileHeight);
+      const hits = normalizedModel.cells.filter((cell) => (
+        cell.x >= minTileX
+        && cell.x <= maxTileX
+        && cell.y >= minTileY
+        && cell.y <= maxTileY
+      ));
+      return okResult({
+        hit: hits.length > 0,
+        hits,
+        range: { minTileX, minTileY, maxTileX, maxTileY },
+      });
+    };
+
+    const queryRay = (mapOrModel, ...args) => {
+      const resolvedModel = resolveQueryModelInput(mapOrModel);
+      if (!resolvedModel.ok) return failResult(resolvedModel.error, resolvedModel.reasonCode);
+      const normalizedModel = normalizeModel(resolvedModel.model);
+      if (!normalizedModel.ok) return failResult(normalizedModel.error, normalizedModel.reasonCode);
+      const ray = parseRayArgs(args, 0);
+      const directionMagnitude = ray ? Math.hypot(ray.dx, ray.dy) : 0;
+      if (!ray || !isFiniteNumber(directionMagnitude) || directionMagnitude <= 0 || ray.maxDistance <= 0) {
+        return failResult('invalid ray query args', 'invalid_ray_args');
+      }
+
+      const dirX = ray.dx / directionMagnitude;
+      const dirY = ray.dy / directionMagnitude;
+      const step = Math.max(1e-4, Math.min(normalizedModel.tileWidth, normalizedModel.tileHeight) * 0.25);
+      const steps = Math.max(1, Math.ceil(ray.maxDistance / step));
+      for (let index = 0; index <= steps; index += 1) {
+        const distance = Math.min(ray.maxDistance, index * step);
+        const sampleX = ray.x + (dirX * distance);
+        const sampleY = ray.y + (dirY * distance);
+        const tileX = Math.floor(sampleX / normalizedModel.tileWidth);
+        const tileY = Math.floor(sampleY / normalizedModel.tileHeight);
+        const hits = hitsAtTile(normalizedModel, tileX, tileY);
+        if (hits.length > 0) {
+          return okResult({
+            hit: true,
+            hits,
+            hitCell: hits[0],
+            distance,
+            point: { x: sampleX, y: sampleY },
+            tileX,
+            tileY,
+          });
+        }
+      }
+      return okResult({
+        hit: false,
+        hits: [],
+        hitCell: null,
+        distance: null,
+        point: null,
+        tileX: null,
+        tileY: null,
+      });
+    };
+
+    return {
+      queryPoint,
+      queryAABB,
+      queryRay,
+      queryRaycast: queryRay,
+    };
+  };
+  Object.assign(tilemap, createTilemapQueryBridge());
+
+  const clamp01 = (value) => {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric)) return 1;
+    if (numeric <= 0) return 0;
+    if (numeric >= 1) return 1;
+    return numeric;
+  };
+  const toFinite = (value, fallback) => {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : fallback;
+  };
+  const toPositive = (value, fallback) => {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) && numeric > 0 ? numeric : fallback;
+  };
+  const isObject = (value) => value != null && typeof value === 'object';
+
+  let cameraBaseX = 0;
+  let cameraBaseY = 0;
+  let cameraBaseZoom = 1;
+  let cameraBaseRotation = 0;
+  let cameraShakeX = 0;
+  let cameraShakeY = 0;
+  let cameraFollowState = null;
+  let cameraDeadzone = null;
+  let cameraBounds = null;
+  let nextCameraEffectId = 1;
+  let nextCameraListenerId = 1;
+  const cameraEffects = [];
+  const cameraEffectListeners = [];
+
+  const applyCameraBounds = () => {
+    if (!cameraBounds) return;
+    const maxX = cameraBounds.x + cameraBounds.width;
+    const maxY = cameraBounds.y + cameraBounds.height;
+    cameraBaseX = Math.max(cameraBounds.x, Math.min(cameraBaseX, maxX));
+    cameraBaseY = Math.max(cameraBounds.y, Math.min(cameraBaseY, maxY));
+  };
+  const normalizeFollowOptions = (options) => {
+    if (options == null) {
+      return {
+        lerpX: 1,
+        lerpY: 1,
+        offsetX: 0,
+        offsetY: 0,
+      };
+    }
+    if (!isObject(options)) return null;
+    return {
+      lerpX: clamp01(options.lerpX),
+      lerpY: clamp01(options.lerpY),
+      offsetX: toFinite(options.offsetX, 0),
+      offsetY: toFinite(options.offsetY, 0),
+    };
+  };
+  const normalizeDeadzone = (value) => {
+    const input = isObject(value) ? value : null;
+    const zoneWidth = toFinite(input?.width, Number.NaN);
+    const zoneHeight = toFinite(input?.height, Number.NaN);
+    if (!(zoneWidth > 0) || !(zoneHeight > 0)) return null;
+    return {
+      x: toFinite(input?.x, 0),
+      y: toFinite(input?.y, 0),
+      width: zoneWidth,
+      height: zoneHeight,
+    };
+  };
+  const normalizeBounds = (value) => {
+    const input = isObject(value) ? value : null;
+    const zoneWidth = toFinite(input?.width, Number.NaN);
+    const zoneHeight = toFinite(input?.height, Number.NaN);
+    if (!(zoneWidth >= 0) || !(zoneHeight >= 0)) return null;
+    return {
+      x: toFinite(input?.x, 0),
+      y: toFinite(input?.y, 0),
+      width: zoneWidth,
+      height: zoneHeight,
+    };
+  };
+  const resolveFollowTarget = (target) => {
+    let source = target;
+    if (typeof source === 'function') {
+      try {
+        source = source();
+      } catch {
+        return null;
+      }
+    }
+    if (!isObject(source)) return null;
+    const x = toFinite(source.x, Number.NaN);
+    const y = toFinite(source.y, Number.NaN);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+    return { x, y };
+  };
+  const emitCameraEffectEvent = (event) => {
+    if (cameraEffectListeners.length === 0) return;
+    const ordered = [...cameraEffectListeners].sort((a, b) => (a.order - b.order) || (a.id - b.id));
+    for (const listener of ordered) {
+      try {
+        listener.callback(event);
+      } catch {
+        // Keep deterministic execution if listener throws.
+      }
+    }
+  };
+
+  const camera = {};
+  Object.defineProperties(camera, {
+    x: {
+      enumerable: true,
+      configurable: false,
+      get: () => cameraBaseX + cameraShakeX,
+      set(value) {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric)) cameraBaseX = numeric;
+      },
+    },
+    y: {
+      enumerable: true,
+      configurable: false,
+      get: () => cameraBaseY + cameraShakeY,
+      set(value) {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric)) cameraBaseY = numeric;
+      },
+    },
+    zoom: {
+      enumerable: true,
+      configurable: false,
+      get: () => cameraBaseZoom,
+      set(value) {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric) && numeric > 0) cameraBaseZoom = numeric;
+      },
+    },
+    rotation: {
+      enumerable: true,
+      configurable: false,
+      get: () => cameraBaseRotation,
+      set(value) {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric)) cameraBaseRotation = numeric;
+      },
+    },
+  });
+
+  camera.getState = () => ({
+    x: cameraBaseX + cameraShakeX,
+    y: cameraBaseY + cameraShakeY,
+    zoom: cameraBaseZoom,
+    rotation: cameraBaseRotation,
+    following: !!cameraFollowState,
+    activeEffects: cameraEffects.length,
+    deadzone: cameraDeadzone ? { ...cameraDeadzone } : null,
+    bounds: cameraBounds ? { ...cameraBounds } : null,
+  });
+
+  camera.follow = (target, options = null) => {
+    if (!(typeof target === 'function' || isObject(target))) {
+      return { ok: false, reasonCode: 'invalid_follow_target' };
+    }
+    const normalized = normalizeFollowOptions(options);
+    if (!normalized) return { ok: false, reasonCode: 'invalid_follow_options' };
+    cameraFollowState = {
+      target,
+      lerpX: normalized.lerpX,
+      lerpY: normalized.lerpY,
+      offsetX: normalized.offsetX,
+      offsetY: normalized.offsetY,
+    };
+    return { ok: true, reasonCode: 'camera_follow_started' };
+  };
+
+  camera.stopFollow = () => {
+    const stopped = !!cameraFollowState;
+    cameraFollowState = null;
+    return { ok: true, stopped, reasonCode: 'camera_follow_stopped' };
+  };
+
+  camera.setDeadzone = (value, maybeHeight) => {
+    const normalized = isObject(value)
+      ? normalizeDeadzone(value)
+      : normalizeDeadzone({ width: value, height: maybeHeight });
+    if (!normalized) return { ok: false, reasonCode: 'invalid_deadzone' };
+    cameraDeadzone = normalized;
+    return { ok: true, reasonCode: 'camera_deadzone_set' };
+  };
+
+  camera.clearDeadzone = () => {
+    cameraDeadzone = null;
+    return { ok: true, reasonCode: 'camera_deadzone_cleared' };
+  };
+
+  camera.setBounds = (xOrBounds, y, boundsWidth, boundsHeight) => {
+    const normalized = isObject(xOrBounds)
+      ? normalizeBounds(xOrBounds)
+      : normalizeBounds({ x: xOrBounds, y, width: boundsWidth, height: boundsHeight });
+    if (!normalized) return { ok: false, reasonCode: 'invalid_bounds' };
+    cameraBounds = normalized;
+    applyCameraBounds();
+    return { ok: true, reasonCode: 'camera_bounds_set' };
+  };
+
+  camera.clearBounds = () => {
+    cameraBounds = null;
+    return { ok: true, reasonCode: 'camera_bounds_cleared' };
+  };
+
+  camera.pan = (x, y, options = null) => {
+    const targetX = Number(x);
+    const targetY = Number(y);
+    if (!Number.isFinite(targetX) || !Number.isFinite(targetY)) {
+      return { ok: false, reasonCode: 'invalid_pan_target' };
+    }
+    if (options != null && !isObject(options)) return { ok: false, reasonCode: 'invalid_pan_options' };
+    const duration = toPositive(options?.duration, 0.25);
+    if (!(duration > 0)) return { ok: false, reasonCode: 'invalid_pan_duration' };
+    const effectId = nextCameraEffectId++;
+    cameraEffects.push({
+      id: effectId,
+      type: 'pan',
+      duration,
+      elapsed: 0,
+      startX: cameraBaseX,
+      startY: cameraBaseY,
+      targetX,
+      targetY,
+    });
+    return { ok: true, effectId, reasonCode: 'camera_pan_started' };
+  };
+  camera.panTo = camera.pan;
+
+  camera.zoomTo = (value, options = null) => {
+    const targetZoom = Number(value);
+    if (!Number.isFinite(targetZoom) || !(targetZoom > 0)) {
+      return { ok: false, reasonCode: 'invalid_zoom_target' };
+    }
+    if (options != null && !isObject(options)) return { ok: false, reasonCode: 'invalid_zoom_options' };
+    const duration = toPositive(options?.duration, 0.25);
+    if (!(duration > 0)) return { ok: false, reasonCode: 'invalid_zoom_duration' };
+    const effectId = nextCameraEffectId++;
+    cameraEffects.push({
+      id: effectId,
+      type: 'zoom',
+      duration,
+      elapsed: 0,
+      startZoom: cameraBaseZoom,
+      targetZoom,
+    });
+    return { ok: true, effectId, reasonCode: 'camera_zoom_started' };
+  };
+
+  camera.rotateTo = (value, options = null) => {
+    const targetRotation = Number(value);
+    if (!Number.isFinite(targetRotation)) {
+      return { ok: false, reasonCode: 'invalid_rotation_target' };
+    }
+    if (options != null && !isObject(options)) return { ok: false, reasonCode: 'invalid_rotation_options' };
+    const duration = toPositive(options?.duration, 0.25);
+    if (!(duration > 0)) return { ok: false, reasonCode: 'invalid_rotation_duration' };
+    const effectId = nextCameraEffectId++;
+    cameraEffects.push({
+      id: effectId,
+      type: 'rotate',
+      duration,
+      elapsed: 0,
+      startRotation: cameraBaseRotation,
+      targetRotation,
+    });
+    return { ok: true, effectId, reasonCode: 'camera_rotation_started' };
+  };
+
+  camera.shake = (options = null) => {
+    if (options == null) options = {};
+    if (!isObject(options)) return { ok: false, reasonCode: 'invalid_shake_options' };
+    const sharedIntensity = Number.isFinite(Number(options.intensity))
+      ? Number(options.intensity)
+      : null;
+    const intensityX = toFinite(options.intensityX, sharedIntensity != null ? sharedIntensity : 6);
+    const intensityY = toFinite(options.intensityY, sharedIntensity != null ? sharedIntensity : 6);
+    if (!(intensityX >= 0) || !(intensityY >= 0)) {
+      return { ok: false, reasonCode: 'invalid_shake_intensity' };
+    }
+    const duration = toPositive(options.duration, 0.3);
+    if (!(duration > 0)) return { ok: false, reasonCode: 'invalid_shake_duration' };
+    const frequency = toPositive(options.frequency, 30);
+    if (!(frequency > 0)) return { ok: false, reasonCode: 'invalid_shake_frequency' };
+    const effectId = nextCameraEffectId++;
+    cameraEffects.push({
+      id: effectId,
+      type: 'shake',
+      duration,
+      elapsed: 0,
+      intensityX,
+      intensityY,
+      frequency,
+      seed: effectId * 0.61803398875,
+    });
+    return { ok: true, effectId, reasonCode: 'camera_shake_started' };
+  };
+
+  camera.clearEffects = () => {
+    const cleared = cameraEffects.length;
+    cameraEffects.length = 0;
+    cameraShakeX = 0;
+    cameraShakeY = 0;
+    return { ok: true, cleared, reasonCode: 'camera_effects_cleared' };
+  };
+
+  camera.onEffectComplete = (callback, order = 0) => {
+    if (typeof callback !== 'function') {
+      return { ok: false, reasonCode: 'invalid_effect_callback' };
+    }
+    const listener = {
+      id: nextCameraListenerId++,
+      callback,
+      order: Number.isFinite(Number(order)) ? Number(order) : 0,
+    };
+    cameraEffectListeners.push(listener);
+    return { ok: true, listenerId: listener.id, reasonCode: 'camera_effect_listener_registered' };
+  };
+
+  camera.offEffectComplete = (listenerId) => {
+    if (!Number.isInteger(listenerId) || listenerId <= 0) return false;
+    const index = cameraEffectListeners.findIndex((entry) => entry.id === listenerId);
+    if (index < 0) return false;
+    cameraEffectListeners.splice(index, 1);
+    return true;
+  };
+
+  camera.update = (dt) => {
+    const delta = Number(dt);
+    if (!Number.isFinite(delta) || !(delta > 0)) {
+      return { ok: false, reasonCode: 'invalid_dt' };
+    }
+
+    cameraShakeX = 0;
+    cameraShakeY = 0;
+
+    if (cameraFollowState) {
+      const targetPoint = resolveFollowTarget(cameraFollowState.target);
+      if (targetPoint) {
+        let targetX = targetPoint.x + cameraFollowState.offsetX;
+        let targetY = targetPoint.y + cameraFollowState.offsetY;
+
+        if (cameraDeadzone) {
+          const left = cameraBaseX + cameraDeadzone.x;
+          const right = left + cameraDeadzone.width;
+          const top = cameraBaseY + cameraDeadzone.y;
+          const bottom = top + cameraDeadzone.height;
+
+          if (targetX < left) targetX = targetX - cameraDeadzone.x;
+          else if (targetX > right) targetX = targetX - cameraDeadzone.x - cameraDeadzone.width;
+          else targetX = cameraBaseX;
+
+          if (targetY < top) targetY = targetY - cameraDeadzone.y;
+          else if (targetY > bottom) targetY = targetY - cameraDeadzone.y - cameraDeadzone.height;
+          else targetY = cameraBaseY;
+        }
+
+        cameraBaseX += (targetX - cameraBaseX) * cameraFollowState.lerpX;
+        cameraBaseY += (targetY - cameraBaseY) * cameraFollowState.lerpY;
+      }
+    }
+
+    const completedEffects = [];
+    for (const effect of cameraEffects) {
+      effect.elapsed += delta;
+      const progress = effect.duration <= 0 ? 1 : Math.min(effect.elapsed / effect.duration, 1);
+      if (effect.type === 'pan') {
+        cameraBaseX = effect.startX + ((effect.targetX - effect.startX) * progress);
+        cameraBaseY = effect.startY + ((effect.targetY - effect.startY) * progress);
+      } else if (effect.type === 'zoom') {
+        cameraBaseZoom = effect.startZoom + ((effect.targetZoom - effect.startZoom) * progress);
+      } else if (effect.type === 'rotate') {
+        cameraBaseRotation = effect.startRotation + ((effect.targetRotation - effect.startRotation) * progress);
+      } else if (effect.type === 'shake') {
+        const amplitude = 1 - progress;
+        const angle = (effect.seed + (effect.elapsed * effect.frequency)) * 6.283185307179586;
+        cameraShakeX += Math.sin(angle) * effect.intensityX * amplitude;
+        cameraShakeY += Math.cos(angle * 1.17) * effect.intensityY * amplitude;
+      }
+      if (progress >= 1) completedEffects.push(effect);
+    }
+
+    if (completedEffects.length > 0) {
+      for (const completed of completedEffects) {
+        const index = cameraEffects.indexOf(completed);
+        if (index >= 0) cameraEffects.splice(index, 1);
+      }
+      completedEffects.sort((a, b) => a.id - b.id);
+      for (const completed of completedEffects) {
+        emitCameraEffectEvent({
+          type: 'effect_complete',
+          effectType: completed.type,
+          effectId: completed.id,
+          reasonCode: 'camera_effect_complete',
+        });
+      }
+    }
+
+    applyCameraBounds();
+
+    return {
+      ok: true,
+      reasonCode: 'camera_updated',
+      x: cameraBaseX + cameraShakeX,
+      y: cameraBaseY + cameraShakeY,
+      zoom: cameraBaseZoom,
+      rotation: cameraBaseRotation,
+      following: !!cameraFollowState,
+      activeEffects: cameraEffects.length,
+    };
+  };
+
+  const createHeadlessAudioSurface = () => {
+    const normalizeHandle = (value) => {
+      const numeric = Number(value);
+      if (!Number.isFinite(numeric) || numeric <= 0 || Math.floor(numeric) !== numeric) {
+        return null;
+      }
+      return numeric;
+    };
+    const normalizeBus = (value) => {
+      if (typeof value !== 'string') return null;
+      const trimmed = value.trim();
+      return trimmed.length > 0 ? trimmed : null;
+    };
+    const normalizeDuration = (value) => {
+      const numeric = Number(value);
+      return Number.isFinite(numeric) && numeric > 0 ? numeric : null;
+    };
+    const clampAudioVolume = (value, fallback = 0) => {
+      const numeric = Number(value);
+      if (!Number.isFinite(numeric)) return fallback;
+      if (numeric < 0) return 0;
+      if (numeric > 1) return 1;
+      return numeric;
+    };
+    const resultOk = (extra = {}) => ({ ok: true, reasonCode: null, ...extra });
+    const resultErr = (reasonCode, extra = {}) => ({ ok: false, reasonCode, ...extra });
+
+    let nextHandle = 1;
+    const rawTracks = new Map();
+
+    const rawPlay = () => {
+      testState.audioCalls += 1;
+      const handle = nextHandle;
+      nextHandle += 1;
+      rawTracks.set(handle, { paused: false, volume: 1 });
+      return handle;
+    };
+    const rawStop = (handle) => {
+      const normalized = normalizeHandle(handle);
+      if (normalized == null) return;
+      rawTracks.delete(normalized);
+    };
+    const rawPause = (handle) => {
+      const normalized = normalizeHandle(handle);
+      if (normalized == null) return;
+      const track = rawTracks.get(normalized);
+      if (track) track.paused = true;
+    };
+    const rawResume = (handle) => {
+      const normalized = normalizeHandle(handle);
+      if (normalized == null) return;
+      const track = rawTracks.get(normalized);
+      if (track) track.paused = false;
+    };
+    const rawSetVolume = (handle, volume) => {
+      const normalized = normalizeHandle(handle);
+      if (normalized == null) return;
+      const track = rawTracks.get(normalized);
+      if (!track) return;
+      track.volume = clampAudioVolume(volume, track.volume);
+    };
+    const rawSetMasterVolume = (volume, audio) => {
+      const numeric = Number(volume);
+      if (!Number.isFinite(numeric)) return;
+      audio.masterVolume = clampAudioVolume(numeric, audio.masterVolume);
+    };
+    const rawStopAll = () => {
+      rawTracks.clear();
+    };
+
+    const audio = {
+      play: rawPlay,
+      pause: rawPause,
+      resume: rawResume,
+      stop: rawStop,
+      setVolume: rawSetVolume,
+      setMasterVolume(volume) {
+        rawSetMasterVolume(volume, audio);
+      },
+      stopAll: rawStopAll,
+      masterVolume: 1,
+    };
+
+    const DEFAULT_BUS = 'master';
+    const busVolumes = new Map([[DEFAULT_BUS, 1]]);
+    const tracks = new Map();
+    const envelopes = [];
+    let nextEnvelopeId = 1;
+
+    const sortedTrackHandles = () => [...tracks.keys()].sort((a, b) => a - b);
+    const ensureBus = (bus) => {
+      if (!busVolumes.has(bus)) busVolumes.set(bus, 1);
+    };
+    const busVolume = (bus) => busVolumes.get(bus) ?? 1;
+    const effectiveTrackVolume = (track) => clampAudioVolume(track.baseVolume * busVolume(track.bus), 1);
+    const applyTrackVolume = (handle) => {
+      const track = tracks.get(handle);
+      if (!track) return;
+      track.effectiveVolume = effectiveTrackVolume(track);
+      rawSetVolume(handle, track.effectiveVolume);
+    };
+    const applyBusVolume = (bus) => {
+      for (const handle of sortedTrackHandles()) {
+        const track = tracks.get(handle);
+        if (!track || track.bus !== bus) continue;
+        applyTrackVolume(handle);
+      }
+    };
+    const removeTrackEnvelopes = (handle) => {
+      for (let i = envelopes.length - 1; i >= 0; i -= 1) {
+        const envelope = envelopes[i];
+        if (envelope.kind === 'track' && envelope.handle === handle) {
+          envelopes.splice(i, 1);
+        }
+      }
+    };
+    const removeBusEnvelopes = (bus) => {
+      for (let i = envelopes.length - 1; i >= 0; i -= 1) {
+        const envelope = envelopes[i];
+        if (envelope.kind === 'bus' && envelope.bus === bus) {
+          envelopes.splice(i, 1);
+        }
+      }
+    };
+    const dropTrack = (handle) => {
+      tracks.delete(handle);
+      removeTrackEnvelopes(handle);
+    };
+    const appendEnvelope = (envelope) => {
+      envelope.id = nextEnvelopeId;
+      nextEnvelopeId += 1;
+      envelopes.push(envelope);
+      return envelope.id;
+    };
+
+    const rawPlayMethod = audio.play.bind(audio);
+    const rawStopMethod = audio.stop.bind(audio);
+    const rawPauseMethod = audio.pause.bind(audio);
+    const rawResumeMethod = audio.resume.bind(audio);
+    const rawSetVolumeMethod = audio.setVolume.bind(audio);
+    const rawSetMasterVolumeMethod = audio.setMasterVolume.bind(audio);
+    const rawStopAllMethod = audio.stopAll.bind(audio);
+
+    audio.play = (path, options = undefined) => {
+      const normalizedOptions = options && typeof options === 'object' && !Array.isArray(options)
+        ? options
+        : null;
+      const requestedVolume = normalizedOptions && Object.prototype.hasOwnProperty.call(normalizedOptions, 'volume')
+        ? clampAudioVolume(normalizedOptions.volume, 1)
+        : 1;
+      const normalizedBus = normalizedOptions ? normalizeBus(normalizedOptions.bus) : null;
+      const bus = normalizedBus || DEFAULT_BUS;
+      ensureBus(bus);
+
+      let forwardedOptions = options;
+      if (normalizedOptions) {
+        forwardedOptions = { ...normalizedOptions, volume: requestedVolume };
+        delete forwardedOptions.bus;
+      }
+
+      const handle = forwardedOptions === undefined
+        ? rawPlayMethod(path)
+        : rawPlayMethod(path, forwardedOptions);
+      const normalizedHandle = normalizeHandle(handle);
+      if (normalizedHandle != null) {
+        tracks.set(normalizedHandle, {
+          baseVolume: requestedVolume,
+          effectiveVolume: requestedVolume,
+          bus,
+          paused: false,
+        });
+        applyTrackVolume(normalizedHandle);
+      }
+      return handle;
+    };
+
+    audio.stop = (handle) => {
+      rawStopMethod(handle);
+      const normalizedHandle = normalizeHandle(handle);
+      if (normalizedHandle != null) {
+        dropTrack(normalizedHandle);
+      }
+    };
+
+    audio.pause = (handle) => {
+      rawPauseMethod(handle);
+      const normalizedHandle = normalizeHandle(handle);
+      if (normalizedHandle != null && tracks.has(normalizedHandle)) {
+        tracks.get(normalizedHandle).paused = true;
+      }
+    };
+
+    audio.resume = (handle) => {
+      rawResumeMethod(handle);
+      const normalizedHandle = normalizeHandle(handle);
+      if (normalizedHandle != null && tracks.has(normalizedHandle)) {
+        tracks.get(normalizedHandle).paused = false;
+      }
+    };
+
+    audio.setVolume = (handle, volume) => {
+      rawSetVolumeMethod(handle, volume);
+      const normalizedHandle = normalizeHandle(handle);
+      if (normalizedHandle == null) return;
+      const track = tracks.get(normalizedHandle);
+      if (!track) return;
+      const numeric = Number(volume);
+      if (!Number.isFinite(numeric)) return;
+      track.baseVolume = clampAudioVolume(numeric, track.baseVolume);
+      applyTrackVolume(normalizedHandle);
+    };
+
+    audio.setMasterVolume = (volume) => {
+      rawSetMasterVolumeMethod(volume);
+    };
+
+    audio.stopAll = () => {
+      rawStopAllMethod();
+      tracks.clear();
+      envelopes.length = 0;
+    };
+
+    audio.setBusVolume = (bus, volume) => {
+      const normalizedBus = normalizeBus(bus);
+      if (!normalizedBus) return resultErr('invalid_bus');
+      const numeric = Number(volume);
+      if (!Number.isFinite(numeric)) return resultErr('invalid_volume');
+      const clamped = clampAudioVolume(numeric, 1);
+      ensureBus(normalizedBus);
+      busVolumes.set(normalizedBus, clamped);
+      applyBusVolume(normalizedBus);
+      return resultOk({ bus: normalizedBus, volume: clamped });
+    };
+
+    audio.assignBus = (handle, bus) => {
+      const normalizedHandle = normalizeHandle(handle);
+      if (normalizedHandle == null) return resultErr('invalid_track_handle');
+      const track = tracks.get(normalizedHandle);
+      if (!track) return resultErr('missing_track');
+      const normalizedBus = normalizeBus(bus);
+      if (!normalizedBus) return resultErr('invalid_bus');
+      ensureBus(normalizedBus);
+      track.bus = normalizedBus;
+      applyTrackVolume(normalizedHandle);
+      return resultOk({
+        handle: normalizedHandle,
+        bus: normalizedBus,
+        effectiveVolume: track.effectiveVolume,
+      });
+    };
+
+    audio.fadeTrack = (handle, options = null) => {
+      const normalizedHandle = normalizeHandle(handle);
+      if (normalizedHandle == null) return resultErr('invalid_track_handle');
+      const track = tracks.get(normalizedHandle);
+      if (!track) return resultErr('missing_track');
+      if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        return resultErr('invalid_fade_options');
+      }
+      const duration = normalizeDuration(options.duration);
+      if (duration == null) return resultErr('invalid_duration');
+      const targetVolume = Number(options.to);
+      if (!Number.isFinite(targetVolume)) return resultErr('invalid_volume');
+      const stopOnComplete = options.stopOnComplete === true;
+      const target = clampAudioVolume(targetVolume, track.baseVolume);
+      removeTrackEnvelopes(normalizedHandle);
+      const envelopeId = appendEnvelope({
+        kind: 'track',
+        handle: normalizedHandle,
+        start: track.baseVolume,
+        end: target,
+        duration,
+        elapsed: 0,
+        stopOnComplete,
+      });
+      return resultOk({ envelopeId });
+    };
+
+    audio.fadeBus = (bus, options = null) => {
+      const normalizedBus = normalizeBus(bus);
+      if (!normalizedBus) return resultErr('invalid_bus');
+      if (!busVolumes.has(normalizedBus)) return resultErr('missing_bus');
+      if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        return resultErr('invalid_fade_options');
+      }
+      const duration = normalizeDuration(options.duration);
+      if (duration == null) return resultErr('invalid_duration');
+      const targetVolume = Number(options.to);
+      if (!Number.isFinite(targetVolume)) return resultErr('invalid_volume');
+      const target = clampAudioVolume(targetVolume, busVolume(normalizedBus));
+      removeBusEnvelopes(normalizedBus);
+      const envelopeId = appendEnvelope({
+        kind: 'bus',
+        bus: normalizedBus,
+        start: busVolume(normalizedBus),
+        end: target,
+        duration,
+        elapsed: 0,
+      });
+      return resultOk({ envelopeId });
+    };
+
+    audio.crossfade = (fromHandle, toHandle, options = null) => {
+      const normalizedFrom = normalizeHandle(fromHandle);
+      if (normalizedFrom == null) return resultErr('invalid_from_track_handle');
+      const normalizedTo = normalizeHandle(toHandle);
+      if (normalizedTo == null) return resultErr('invalid_to_track_handle');
+      const fromTrack = tracks.get(normalizedFrom);
+      if (!fromTrack) return resultErr('missing_from_track');
+      const toTrack = tracks.get(normalizedTo);
+      if (!toTrack) return resultErr('missing_to_track');
+      if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        return resultErr('invalid_crossfade_options');
+      }
+      const duration = normalizeDuration(options.duration);
+      if (duration == null) return resultErr('invalid_duration');
+
+      const fromTargetRaw = Object.prototype.hasOwnProperty.call(options, 'fromVolume')
+        ? Number(options.fromVolume)
+        : 0;
+      if (!Number.isFinite(fromTargetRaw)) return resultErr('invalid_from_volume');
+      const toTargetRaw = Object.prototype.hasOwnProperty.call(options, 'toVolume')
+        ? Number(options.toVolume)
+        : toTrack.baseVolume;
+      if (!Number.isFinite(toTargetRaw)) return resultErr('invalid_to_volume');
+      const toStartRaw = Object.prototype.hasOwnProperty.call(options, 'toStartVolume')
+        ? Number(options.toStartVolume)
+        : 0;
+      if (!Number.isFinite(toStartRaw)) return resultErr('invalid_to_start_volume');
+
+      const stopFrom = options.stopFrom !== false;
+      const fromTarget = clampAudioVolume(fromTargetRaw, fromTrack.baseVolume);
+      const toTarget = clampAudioVolume(toTargetRaw, toTrack.baseVolume);
+      const toStart = clampAudioVolume(toStartRaw, 0);
+
+      toTrack.baseVolume = toStart;
+      applyTrackVolume(normalizedTo);
+
+      removeTrackEnvelopes(normalizedFrom);
+      removeTrackEnvelopes(normalizedTo);
+      const fromEnvelopeId = appendEnvelope({
+        kind: 'track',
+        handle: normalizedFrom,
+        start: fromTrack.baseVolume,
+        end: fromTarget,
+        duration,
+        elapsed: 0,
+        stopOnComplete: stopFrom,
+      });
+      const toEnvelopeId = appendEnvelope({
+        kind: 'track',
+        handle: normalizedTo,
+        start: toStart,
+        end: toTarget,
+        duration,
+        elapsed: 0,
+        stopOnComplete: false,
+      });
+      return resultOk({ fromEnvelopeId, toEnvelopeId });
+    };
+
+    audio.update = (dt) => {
+      const delta = Number(dt);
+      if (!Number.isFinite(delta) || !(delta > 0)) {
+        return resultErr('invalid_dt');
+      }
+      if (envelopes.length === 0) {
+        return resultOk({ advanced: 0, completed: 0, activeEnvelopes: 0 });
+      }
+
+      const completed = [];
+      envelopes.sort((a, b) => a.id - b.id);
+
+      for (const envelope of envelopes) {
+        envelope.elapsed += delta;
+        const progress = envelope.duration <= 0 ? 1 : Math.min(envelope.elapsed / envelope.duration, 1);
+        const value = envelope.start + ((envelope.end - envelope.start) * progress);
+
+        if (envelope.kind === 'track') {
+          const track = tracks.get(envelope.handle);
+          if (!track) {
+            completed.push(envelope);
+            continue;
+          }
+          track.baseVolume = clampAudioVolume(value, track.baseVolume);
+          applyTrackVolume(envelope.handle);
+        } else if (envelope.kind === 'bus') {
+          if (!busVolumes.has(envelope.bus)) {
+            completed.push(envelope);
+            continue;
+          }
+          busVolumes.set(envelope.bus, clampAudioVolume(value, busVolume(envelope.bus)));
+          applyBusVolume(envelope.bus);
+        }
+
+        if (progress >= 1) {
+          completed.push(envelope);
+        }
+      }
+
+      completed.sort((a, b) => a.id - b.id);
+      for (const envelope of completed) {
+        const index = envelopes.indexOf(envelope);
+        if (index >= 0) envelopes.splice(index, 1);
+        if (envelope.kind === 'track' && envelope.stopOnComplete === true && tracks.has(envelope.handle)) {
+          audio.stop(envelope.handle);
+        }
+      }
+
+      return resultOk({
+        advanced: delta,
+        completed: completed.length,
+        activeEnvelopes: envelopes.length,
+      });
+    };
+
+    audio.clearEnvelopes = () => {
+      const cleared = envelopes.length;
+      envelopes.length = 0;
+      return resultOk({ cleared });
+    };
+
+    audio.getMixerState = () => ({
+      buses: [...busVolumes.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([bus, volume]) => ({ bus, volume })),
+      tracks: sortedTrackHandles()
+        .map((handle) => {
+          const track = tracks.get(handle);
+          if (!track) return null;
+          return {
+            handle,
+            bus: track.bus,
+            baseVolume: track.baseVolume,
+            effectiveVolume: track.effectiveVolume,
+            paused: track.paused === true,
+          };
+        })
+        .filter(Boolean),
+      envelopes: [...envelopes]
+        .sort((a, b) => a.id - b.id)
+        .map((envelope) => ({
+          id: envelope.id,
+          kind: envelope.kind,
+          handle: envelope.kind === 'track' ? envelope.handle : null,
+          bus: envelope.kind === 'bus' ? envelope.bus : null,
+          start: envelope.start,
+          end: envelope.end,
+          duration: envelope.duration,
+          elapsed: envelope.elapsed,
+          stopOnComplete: envelope.kind === 'track' ? envelope.stopOnComplete === true : false,
+        })),
+      nextEnvelopeId,
+    });
+
+    return audio;
+  };
+
+  const audio = createHeadlessAudioSurface();
+
+  const aura = {
+    setup: null,
+    update: null,
+    draw: null,
+    onResize: null,
+    onFocus: null,
+    onBlur: null,
+    onQuit: null,
+
+    window: {
+      width,
+      height,
+      pixelRatio: 1,
+      fps: 60,
+      setTitle: () => {},
+      setSize: (w, h) => {
+        aura.window.width = Number(w) || aura.window.width;
+        aura.window.height = Number(h) || aura.window.height;
+      },
+      setFullscreen: () => {},
+      getSize: () => ({ width: aura.window.width, height: aura.window.height }),
+      getPixelRatio: () => aura.window.pixelRatio,
+      getFPS: () => aura.window.fps,
+      close: () => {},
+    },
+
+    draw2d: {
+      clear: drawNoop,
+      rect: drawNoop,
+      rectOutline: drawNoop,
+      circle: drawNoop,
+      circleOutline: drawNoop,
+      line: drawNoop,
+      triangle: drawNoop,
+      image: drawNoop,
+      sprite: drawNoop,
+      text: drawNoop,
+      push: drawNoop,
+      pop: drawNoop,
+      pushTransform: drawNoop,
+      popTransform: drawNoop,
+      translate: drawNoop,
+      rotate: drawNoop,
+      scale: drawNoop,
+    },
+
+    draw3d: {
+      mesh: drawNoop,
+    },
+
+    material: {
+      create: (options = undefined) => {
+        const handle = nextMaterialHandle++;
+        materialStore.set(handle, createMaterialState(options));
+        return handle;
+      },
+      setColor: (handle, color) => {
+        const material = getMaterialState(handle);
+        if (!material) return;
+        const normalized = normalizeMaterialColor(color);
+        if (!normalized) return;
+        material.color = normalized;
+      },
+      setTexture: (handle, texturePath) => {
+        const material = getMaterialState(handle);
+        if (!material) return;
+        if (texturePath === null) {
+          material.texture = null;
+          return;
+        }
+        if (typeof texturePath !== 'string') {
+          throw new Error('aura.material.setTexture: texturePath must be a string or null');
+        }
+        material.texture = texturePath.length > 0 ? texturePath : null;
+      },
+      setMetallic: (handle, metallic) => {
+        const material = getMaterialState(handle);
+        if (!material) return;
+        material.metallic = clampUnit(metallic, material.metallic);
+      },
+      setRoughness: (handle, roughness) => {
+        const material = getMaterialState(handle);
+        if (!material) return;
+        material.roughness = clampUnit(roughness, material.roughness);
+      },
+      setMetallicRoughness: (handle, metallic, roughness) => {
+        const material = getMaterialState(handle);
+        if (!material) return;
+        material.metallic = clampUnit(metallic, material.metallic);
+        material.roughness = clampUnit(roughness, material.roughness);
+      },
+      reset: (handle) => {
+        const material = getMaterialState(handle);
+        if (!material) return;
+        material.color = { ...defaultMaterialState.color };
+        material.metallic = defaultMaterialState.metallic;
+        material.roughness = defaultMaterialState.roughness;
+        material.texture = defaultMaterialState.texture;
+      },
+      clone: (handle) => {
+        const material = getMaterialState(handle);
+        if (!material) throw new Error('Invalid material handle');
+        const newHandle = nextMaterialHandle++;
+        materialStore.set(newHandle, {
+          color: { ...material.color },
+          metallic: material.metallic,
+          roughness: material.roughness,
+          texture: material.texture,
+        });
+        return newHandle;
+      },
+      unload: (handle) => {
+        const normalized = normalizeMaterialHandle(handle);
+        if (normalized == null || normalized === 0) return;
+        materialStore.delete(normalized);
+      },
+    },
+
+    audio,
+
+    assets: {
+      load: async () => {},
+      image: (name) => ({ kind: 'image', name }),
+      sound: (name) => ({ kind: 'sound', name }),
+      mesh: (name) => ({ kind: 'mesh', name }),
+      json: () => ({}),
+      text: () => '',
+      bytes: () => new Uint8Array(),
+    },
+
+    input: {
+      isDown: () => false,
+      isPressed: () => false,
+      isReleased: () => false,
+      isKeyDown: (...args) => aura.input.isDown(...args),
+      isKeyPressed: (...args) => aura.input.isPressed(...args),
+      isKeyReleased: (...args) => aura.input.isReleased(...args),
+      isMouseDown: (...args) => aura.input.mouse.isDown(...args),
+      isMousePressed: (...args) => aura.input.mouse.isPressed(...args),
+      isMouseReleased: (...args) => aura.input.mouse.isReleased(...args),
+      getMousePosition: () => ({ x: aura.input.mouse.x, y: aura.input.mouse.y }),
+      isGamepadConnected: () => Boolean(aura.input.gamepad.connected),
+      mouse: {
+        x: 0,
+        y: 0,
+        scroll: 0,
+        isDown: () => false,
+        isPressed: () => false,
+        isReleased: () => false,
+      },
+      gamepad: {
+        connected: false,
+        axis: () => 0,
+        isDown: () => false,
+        isPressed: () => false,
+        isReleased: () => false,
+        rumble: () => {},
+      },
+    },
+
+    storage: {
+      _store: new Map(),
+      set(key, value) {
+        this._store.set(key, value);
+      },
+      get(key, fallback = null) {
+        return this._store.has(key) ? this._store.get(key) : fallback;
+      },
+      delete(key) {
+        this._store.delete(key);
+      },
+    },
+
+    math: {
+      lerp: (a, b, t) => a + (b - a) * t,
+      clamp: (value, min, max) => Math.max(min, Math.min(max, value)),
+      random: (...args) => {
+        if (args.length === 0) {
+          return Math.random();
+        }
+        if (args.length === 1) {
+          return Math.random() * args[0];
+        }
+        return args[0] + Math.random() * (args[1] - args[0]);
+      },
+      randomInt: (min, max) => Math.floor(min + Math.random() * (max - min + 1)),
+      randomFloat: (min, max) => min + Math.random() * (max - min),
+      distance: (x1, y1, x2, y2) => Math.hypot(x2 - x1, y2 - y1),
+      angle: (x1, y1, x2, y2) => Math.atan2(y2 - y1, x2 - x1),
+      degToRad: (degrees) => (degrees * Math.PI) / 180,
+      radToDeg: (radians) => (radians * 180) / Math.PI,
+      PI: Math.PI,
+      TAU: Math.PI * 2,
+    },
+
+    timer: {
+      after: (_seconds, callback) => {
+        const id = Symbol('after');
+        if (typeof callback === 'function') callback();
+        return id;
+      },
+      every: (_seconds, callback) => {
+        const id = Symbol('every');
+        if (typeof callback === 'function') callback();
+        return id;
+      },
+      cancel: () => {},
+      getDelta: () => 1 / 60,
+      getTime: () => 0,
+    },
+
+    collision,
+    collide,
+
+    ecs: {
+      createEntity: () => {
+        const id = nextEcsEntityId++;
+        ecsEntities.add(id);
+        return id;
+      },
+      removeEntity: (entityId) => {
+        const id = normalizeEntityId(entityId);
+        if (id == null || !ecsEntities.has(id)) return false;
+        ecsEntities.delete(id);
+        for (const store of ecsComponentStores.values()) {
+          store.delete(id);
+        }
+        return true;
+      },
+      addComponent: (entityId, componentName, componentValue) => {
+        const id = normalizeEntityId(entityId);
+        const name = normalizeComponentName(componentName);
+        if (id == null || name == null || !ecsEntities.has(id)) return false;
+        if (!ecsComponentStores.has(name)) {
+          ecsComponentStores.set(name, new Map());
+        }
+        ecsComponentStores.get(name).set(id, componentValue);
+        return true;
+      },
+      getComponent: (entityId, componentName) => {
+        const id = normalizeEntityId(entityId);
+        const name = normalizeComponentName(componentName);
+        if (id == null || name == null) return undefined;
+        const store = ecsComponentStores.get(name);
+        return store ? store.get(id) : undefined;
+      },
+      system: (name, fn, order = 0) => {
+        const normalizedName = normalizeSystemName(name);
+        if (normalizedName == null || typeof fn !== 'function') return false;
+        const normalizedOrder = Number.isFinite(order) ? Number(order) : 0;
+        const existing = ecsSystems.find((entry) => entry.name === normalizedName);
+        if (existing) {
+          existing.fn = fn;
+          existing.order = normalizedOrder;
+        } else {
+          ecsSystems.push({ name: normalizedName, fn, order: normalizedOrder });
+        }
+        sortEcsSystems();
+        return true;
+      },
+      run: (dt) => {
+        for (const entry of ecsSystems) {
+          entry.fn(dt);
+        }
+      },
+    },
+
+    animation,
+
+    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 = normalizeEntityId(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 = normalizeEntityId(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 = normalizeEntityId(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 = normalizeEntityId(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;
+          }
+        }
+      },
+    },
+
+    scene,
+    scene3d,
+    tilemap,
+
+    test: {
+      assert(condition, message = 'Assertion failed') {
+        if (!condition) {
+          testState.failures.push(message);
+          throw new Error(message);
+        }
+        testState.passes += 1;
+      },
+      equal(actual, expected, message = null) {
+        if (!Object.is(actual, expected)) {
+          const detail = message || `Expected ${JSON.stringify(expected)} but got ${JSON.stringify(actual)}`;
+          testState.failures.push(detail);
+          throw new Error(detail);
+        }
+        testState.passes += 1;
+      },
+      fail(message = 'Test failed') {
+        testState.failures.push(message);
+        throw new Error(message);
+      },
+    },
+
+    debug: {
+      log: (...args) => console.log(...args),
+      drawRect: () => {
+        testState.drawCalls += 1;
+      },
+      drawCircle: () => {
+        testState.drawCalls += 1;
+      },
+      drawText: () => {
+        testState.drawCalls += 1;
+      },
+      cacheStats: () => ({
+        assets: {
+          entryCount: 0,
+          estimatedBytes: 0,
+          handleCount: 0,
+          nextHandleId: 1,
+          cacheHitCount: 0,
+          cacheMissCount: 0,
+          resetCount: 0,
+          lastResetSequence: 0,
+        },
+        audio: {
+          decodedCacheEntries: 0,
+          decodedSampleCount: 0,
+          activeHandleCount: 0,
+          nextHandleId: 1,
+          decodedCacheHitCount: 0,
+          decodedCacheMissCount: 0,
+          resetCount: 0,
+          lastResetSequence: 0,
+        },
+      }),
+      resetCaches: () => {},
+      enableInspector: (enabled = true) => {
+        debugInspectorState.enabled = enabled !== false;
+        if (!debugInspectorState.enabled) {
+          debugInspectorState.frameCount = 0;
+          debugInspectorState.elapsedSeconds = 0;
+        }
+        return debugInspectorState.enabled;
+      },
+      inspectorStats: () => debugInspectorSnapshot(),
+      __inspectorTick: (dt) => {
+        if (!debugInspectorState.enabled) return;
+        debugInspectorState.frameCount += 1;
+        if (Number.isFinite(dt) && dt > 0) {
+          debugInspectorState.elapsedSeconds += Number(dt);
+        }
+      },
+    },
+
+    color: (...args) => ({ kind: 'color', args }),
+    colors: {
+      white: { r: 255, g: 255, b: 255, a: 255 },
+      black: { r: 0, g: 0, b: 0, a: 255 },
+      red: { r: 255, g: 0, b: 0, a: 255 },
+      transparent: { r: 0, g: 0, b: 0, a: 0 },
+    },
+    camera,
+    camera3d: { position: [0, 0, 0], fov: 60, lookAt: () => {} },
+    light: { ambient: () => {}, directional: () => {}, point: () => {} },
+    vec2,
+    vec3,
+  };
+
+  return aura;
+}
+
+async function executeLifecycle(aura, frames) {
+  if (typeof aura.setup === 'function') {
+    await Promise.resolve(aura.setup());
+  }
+
+  for (let i = 0; i < frames; i += 1) {
+    const dt = 1 / 60;
+    if (aura.debug && typeof aura.debug.__inspectorTick === 'function') {
+      aura.debug.__inspectorTick(dt);
+    }
+    if (aura.anim2d && typeof aura.anim2d.update === 'function') {
+      await Promise.resolve(aura.anim2d.update(dt));
+    }
+    if (aura.ecs && typeof aura.ecs.run === 'function') {
+      await Promise.resolve(aura.ecs.run(dt));
+    }
+    if (typeof aura.update === 'function') {
+      await Promise.resolve(aura.update(dt));
+    }
+    if (typeof aura.draw === 'function') {
+      await Promise.resolve(aura.draw());
+    }
+  }
+}
+
+function parsePositiveInt(value, flagName) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+    throw new HeadlessTestError(`${flagName} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+function parseNonNegativeInt(value, flagName) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0 || !Number.isInteger(parsed)) {
+    throw new HeadlessTestError(`${flagName} must be a non-negative integer.`);
+  }
+  return parsed;
+}