@auraindustry/aurajs 0.0.6 → 0.1.0

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

@@ -0,0 +1,1514 @@
+import { existsSync } from 'node:fs';
+
+import {
+  GAME_ACTION_SCHEMA_VERSION,
+  GAME_ACTION_REQUEST_SCHEMA_VERSION,
+  GAME_ACTION_RESULT_SCHEMA_VERSION,
+  createGameActionRuntimeHooks,
+} from '../game-action-runtime.mjs';
+import {
+  GAME_STATE_SCHEMA_VERSION,
+  createGameStateRuntimeHooks,
+} from '../game-state-runtime.mjs';
+import { createHeadlessAnimationRuntime } from './runtime-animation.mjs';
+import { createHeadlessPrimitiveRuntime } from './runtime-primitives.mjs';
+import { createHeadlessWorldRuntime } from './runtime-world.mjs';
+
+export 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() },
+  };
+}
+
+export function createHeadlessAura({ width, height, testState, projectRoot = process.cwd() }) {
+let nextDraw2dRenderTargetHandle = 1;
+const draw2dRenderTargets = new Map();
+const draw2dClipStack = [];
+let activeDraw2dRenderTarget = null;
+let activeDraw2dMaskCapture = null;
+
+const drawNoop = () => {
+  testState.drawCalls += 1;
+  if (activeDraw2dRenderTarget) {
+    activeDraw2dRenderTarget.commandCount += 1;
+  }
+  if (activeDraw2dMaskCapture) {
+    activeDraw2dMaskCapture.commandCount += 1;
+  }
+};
+const stateNoop = () => {};
+
+  const {
+    resolveHeadlessAssetPath,
+    measureHeadlessText,
+    vec2,
+    vec3,
+    collision,
+    collide,
+    math,
+    timer,
+    color,
+    rgb,
+    rgba,
+    Color,
+    colors,
+  } = createHeadlessPrimitiveRuntime({ projectRoot });
+  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,
+    },
+  });
+  let assets = null;
+  const { ecs, scene, scene3d, tilemap } = createHeadlessWorldRuntime({
+    loadJsonAsset: (source) => {
+      if (assets && typeof assets.loadJson === 'function') return assets.loadJson(source);
+      if (assets && typeof assets.json === 'function') return assets.json(source);
+      return {};
+    },
+  });
+  const { animation, anim2d, material } = createHeadlessAnimationRuntime();
+
+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 normalizeDraw2dRenderTargetHandle = (value) => {
+  const handle = Number(
+    value && typeof value === 'object' && value.__renderTarget === true
+      ? value.handle
+      : value,
+  );
+  if (!Number.isInteger(handle) || handle <= 0) return null;
+  return handle;
+};
+const normalizeClipRect = (xOrRect, y, widthValue, heightValue) => {
+  if (isObject(xOrRect)) {
+    const normalizedWidth = toFinite(xOrRect.width, Number.NaN);
+    const normalizedHeight = toFinite(xOrRect.height, Number.NaN);
+    if (!(normalizedWidth > 0) || !(normalizedHeight > 0)) return null;
+    return {
+      x: toFinite(xOrRect.x, 0),
+      y: toFinite(xOrRect.y, 0),
+      width: normalizedWidth,
+      height: normalizedHeight,
+    };
+  }
+  const normalizedX = toFinite(xOrRect, Number.NaN);
+  const normalizedY = toFinite(y, Number.NaN);
+  const normalizedWidth = toFinite(widthValue, Number.NaN);
+  const normalizedHeight = toFinite(heightValue, Number.NaN);
+  if (![normalizedX, normalizedY, normalizedWidth, normalizedHeight].every(Number.isFinite)) {
+    return null;
+  }
+  if (!(normalizedWidth > 0) || !(normalizedHeight > 0)) return null;
+  return {
+    x: normalizedX,
+    y: normalizedY,
+    width: normalizedWidth,
+    height: normalizedHeight,
+  };
+};
+const draw2dOk = (reasonCode, extra = {}) => ({ ok: true, reasonCode, ...extra });
+const draw2dErr = (reasonCode, extra = {}) => ({ ok: false, reasonCode, ...extra });
+const normalizeDraw2dSource = (value) => {
+  if (typeof value === 'string') {
+    return value.length > 0 ? value : null;
+  }
+  const handle = normalizeDraw2dRenderTargetHandle(value);
+  if (handle == null) return null;
+  return { handle };
+};
+const normalizeSpriteFxShadow = (options) => {
+  if (!options || typeof options !== 'object') return { ok: false, reasonCode: 'missing_sprite_fx_effect' };
+  const shadow = options.shadow;
+  if (shadow == null) return { ok: false, reasonCode: 'missing_sprite_fx_effect' };
+  if (typeof shadow !== 'object') return { ok: false, reasonCode: 'invalid_sprite_fx_shadow' };
+  const offsetX = shadow.offsetX == null ? 2 : Number(shadow.offsetX);
+  const offsetY = shadow.offsetY == null ? 2 : Number(shadow.offsetY);
+  const blur = shadow.blur == null ? 0 : Number(shadow.blur);
+  if (!Number.isFinite(offsetX) || !Number.isFinite(offsetY) || !Number.isFinite(blur)) {
+    return { ok: false, reasonCode: 'invalid_sprite_fx_shadow' };
+  }
+  return { ok: true, shadow: { offsetX, offsetY, blur: Math.max(0, blur) } };
+};
+const runSpriteFxNoop = (options = {}) => {
+  const shadowResult = normalizeSpriteFxShadow(options);
+  if (!shadowResult.ok) return shadowResult;
+  let submittedFxDrawCount = 1;
+  if (shadowResult.shadow.blur > 0) {
+    submittedFxDrawCount += 24;
+  }
+  for (let i = 0; i < submittedFxDrawCount; i += 1) {
+    drawNoop();
+  }
+  drawNoop();
+  return { ok: true, submittedFxDrawCount };
+};
+
+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: () => {},
+    setCursorVisible: () => {},
+    setCursorLocked: () => {},
+    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,
+    tileSprite: drawNoop,
+    nineSlice: drawNoop,
+    text: drawNoop,
+    measureText: measureHeadlessText,
+    push: drawNoop,
+    pop: drawNoop,
+    pushTransform: drawNoop,
+    popTransform: drawNoop,
+    translate: drawNoop,
+    rotate: drawNoop,
+    scale: drawNoop,
+    createRenderTarget: (widthValue, heightValue) => {
+      const normalizedWidth = Number(widthValue);
+      const normalizedHeight = Number(heightValue);
+      if (!Number.isFinite(normalizedWidth) || normalizedWidth <= 0) {
+        return draw2dErr('invalid_render_target_width');
+      }
+      if (!Number.isFinite(normalizedHeight) || normalizedHeight <= 0) {
+        return draw2dErr('invalid_render_target_height');
+      }
+      const handle = nextDraw2dRenderTargetHandle++;
+      const target = {
+        handle,
+        width: Math.floor(normalizedWidth),
+        height: Math.floor(normalizedHeight),
+      };
+      draw2dRenderTargets.set(handle, target);
+      return draw2dOk('draw2d_render_target_created', {
+        handle,
+        width: target.width,
+        height: target.height,
+        created: true,
+        type: 'renderTarget',
+        __renderTarget: true,
+      });
+    },
+    resizeRenderTarget: (targetValue, widthValue, heightValue) => {
+      const handle = normalizeDraw2dRenderTargetHandle(targetValue);
+      if (handle == null) return draw2dErr('invalid_render_target_handle');
+      const target = draw2dRenderTargets.get(handle);
+      if (!target) return draw2dErr('missing_render_target');
+      const normalizedWidth = Number(widthValue);
+      const normalizedHeight = Number(heightValue);
+      if (!Number.isFinite(normalizedWidth) || normalizedWidth <= 0) {
+        return draw2dErr('invalid_render_target_width');
+      }
+      if (!Number.isFinite(normalizedHeight) || normalizedHeight <= 0) {
+        return draw2dErr('invalid_render_target_height');
+      }
+      const width = Math.floor(normalizedWidth);
+      const height = Math.floor(normalizedHeight);
+      const resized = target.width !== width || target.height !== height;
+      target.width = width;
+      target.height = height;
+      return draw2dOk('draw2d_render_target_resized', { handle, width, height, resized });
+    },
+    destroyRenderTarget: (targetValue) => {
+      const handle = normalizeDraw2dRenderTargetHandle(targetValue);
+      if (handle == null) return draw2dErr('invalid_render_target_handle');
+      const destroyed = draw2dRenderTargets.delete(handle);
+      if (!destroyed) return draw2dErr('missing_render_target');
+      if (activeDraw2dRenderTarget && activeDraw2dRenderTarget.handle === handle) {
+        activeDraw2dRenderTarget = null;
+      }
+      return draw2dOk('draw2d_render_target_destroyed', { handle, destroyed: true });
+    },
+    withRenderTarget: (targetValue, callback) => {
+      const handle = normalizeDraw2dRenderTargetHandle(targetValue);
+      if (handle == null) return draw2dErr('invalid_render_target_handle');
+      if (!draw2dRenderTargets.has(handle)) return draw2dErr('missing_render_target');
+      if (typeof callback !== 'function') return draw2dErr('invalid_render_target_callback');
+      if (activeDraw2dRenderTarget) return draw2dErr('nested_render_target_capture');
+      const savedClipDepth = draw2dClipStack.length;
+      activeDraw2dRenderTarget = { handle, commandCount: 0 };
+      draw2dClipStack.length = 0;
+      try {
+        callback();
+      } catch {
+        activeDraw2dRenderTarget = null;
+        draw2dClipStack.length = savedClipDepth;
+        return draw2dErr('render_target_callback_threw');
+      }
+      const commandCount = activeDraw2dRenderTarget.commandCount;
+      activeDraw2dRenderTarget = null;
+      draw2dClipStack.length = savedClipDepth;
+      return draw2dOk('draw2d_render_target_captured', { handle, commandCount });
+    },
+    withRenderTargets: (stages) => {
+      if (!Array.isArray(stages) || stages.length === 0) return draw2dErr('invalid_render_target_stages');
+      const handles = [];
+      let commandCount = 0;
+      const seenHandles = new Set();
+      for (const stage of stages) {
+        if (!stage || typeof stage !== 'object') return draw2dErr('invalid_render_target_stages');
+        const handle = normalizeDraw2dRenderTargetHandle(stage.target);
+        if (handle == null) return draw2dErr('invalid_render_target_handle');
+        if (!draw2dRenderTargets.has(handle)) return draw2dErr('missing_render_target');
+        if (typeof stage.draw !== 'function') return draw2dErr('invalid_render_target_stages');
+        if (seenHandles.has(handle)) return draw2dErr('duplicate_render_target_stage');
+        seenHandles.add(handle);
+        const result = aura.draw2d.withRenderTarget(handle, stage.draw);
+        if (!result?.ok) return result;
+        handles.push(handle);
+        commandCount += Number(result.commandCount || 0);
+      }
+      return draw2dOk('draw2d_render_targets_captured', {
+        stageCount: handles.length,
+        commandCount,
+        handles,
+      });
+    },
+    withMask: (sourceValue, xValue, yValue, widthValue, heightValue, callback) => {
+      const source = normalizeDraw2dSource(sourceValue);
+      if (!source) return draw2dErr('invalid_mask_source');
+      if (typeof source === 'object' && !draw2dRenderTargets.has(source.handle)) {
+        return draw2dErr('invalid_mask_source_handle');
+      }
+      if (!Number.isFinite(Number(xValue))) return draw2dErr('invalid_mask_x');
+      if (!Number.isFinite(Number(yValue))) return draw2dErr('invalid_mask_y');
+      if (!Number.isFinite(Number(widthValue)) || Number(widthValue) <= 0) return draw2dErr('invalid_mask_width');
+      if (!Number.isFinite(Number(heightValue)) || Number(heightValue) <= 0) return draw2dErr('invalid_mask_height');
+      if (typeof callback !== 'function') return draw2dErr('invalid_mask_callback');
+      if (activeDraw2dRenderTarget) return draw2dErr('mask_capture_inside_render_target_unsupported');
+      const savedClipDepth = draw2dClipStack.length;
+      activeDraw2dMaskCapture = { commandCount: 0 };
+      draw2dClipStack.length = 0;
+      try {
+        callback();
+      } catch {
+        activeDraw2dMaskCapture = null;
+        draw2dClipStack.length = savedClipDepth;
+        return draw2dErr('mask_callback_threw');
+      }
+      const commandCount = activeDraw2dMaskCapture.commandCount;
+      activeDraw2dMaskCapture = null;
+      draw2dClipStack.length = savedClipDepth;
+      drawNoop();
+      return draw2dOk('draw2d_mask_captured', { commandCount });
+    },
+    spriteFx: (sourceValue, xValue, yValue, options = {}) => {
+      const source = normalizeDraw2dSource(sourceValue);
+      if (!source) return draw2dErr('invalid_sprite_fx_source');
+      if (typeof source === 'object' && !draw2dRenderTargets.has(source.handle)) {
+        return draw2dErr('invalid_sprite_fx_source_handle');
+      }
+      if (!Number.isFinite(Number(xValue))) return draw2dErr('invalid_sprite_fx_x');
+      if (!Number.isFinite(Number(yValue))) return draw2dErr('invalid_sprite_fx_y');
+      const result = runSpriteFxNoop(options);
+      if (!result.ok) return draw2dErr(result.reasonCode);
+      return draw2dOk('draw2d_sprite_fx_queued', {
+        submittedFxDrawCount: result.submittedFxDrawCount,
+      });
+    },
+    pushClipRect: (xOrRect, y, widthValue, heightValue) => {
+      const clipRect = normalizeClipRect(xOrRect, y, widthValue, heightValue);
+      if (!clipRect) return draw2dErr('invalid_clip_rect');
+      draw2dClipStack.push(clipRect);
+      return draw2dOk('draw2d_clip_pushed');
+    },
+    popClipRect: () => {
+      if (draw2dClipStack.length === 0) return draw2dErr('draw2d_clip_stack_underflow');
+      draw2dClipStack.pop();
+      return draw2dOk('draw2d_clip_popped');
+    },
+  },
+
+  draw3d: {
+    drawMesh: drawNoop,
+    clear3d: drawNoop,
+    drawSkybox: drawNoop,
+    billboard: drawNoop,
+    mesh: drawNoop,
+    setEnvironmentMap: stateNoop,
+    setFog: stateNoop,
+    clearFog: stateNoop,
+  },
+
+  material,
+
+  audio,
+
+  audio,
+
+  assets: {
+    load: async () => {},
+    exists: (name) => {
+      const assetPath = resolveHeadlessAssetPath(name);
+      return assetPath ? existsSync(assetPath) : false;
+    },
+    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 }),
+    getMouseDelta: () => ({ x: 0, y: 0 }),
+    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,
+
+  timer,
+
+  collision,
+
+  collision,
+  collide,
+
+  ecs,
+
+  animation,
+
+  animation,
+
+  anim2d,
+
+  scene,
+
+  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,
+  rgb,
+  rgba,
+  Color,
+  colors,
+  camera,
+  camera,
+  camera3d: { position: [0, 0, 0], fov: 60, lookAt: () => {} },
+  light: { ambient: () => {}, directional: () => {}, point: () => {} },
+  vec2,
+  vec3,
+};
+
+  assets = aura.assets;
+
+  const gameStateHooks = createGameStateRuntimeHooks({ aura, mode: 'headless' });
+  const gameActionHooks = createGameActionRuntimeHooks({ aura });
+  aura.action = {
+    schemaVersion: GAME_ACTION_SCHEMA_VERSION,
+    requestSchemaVersion: GAME_ACTION_REQUEST_SCHEMA_VERSION,
+    resultSchemaVersion: GAME_ACTION_RESULT_SCHEMA_VERSION,
+    define: (contract) => gameActionHooks.defineActionContract(contract),
+    schema: () => {
+      const result = gameActionHooks.getActionSchema();
+      return result && result.ok === true ? result.payload : result;
+    },
+    getSchema: () => gameActionHooks.getActionSchema(),
+    run: (request) => gameActionHooks.runAction(request),
+    runAction: (request) => gameActionHooks.runAction(request),
+  };
+  aura.state = {
+    schemaVersion: GAME_STATE_SCHEMA_VERSION,
+    export: (options = {}) => {
+      const result = gameStateHooks.exportState(options);
+      return result && result.ok === true ? result.payload : result;
+    },
+    apply: (payload, options = {}) => gameStateHooks.applyState(payload, options),
+    diff: (beforePayload, afterPayload) => gameStateHooks.diffState(beforePayload, afterPayload),
+    patch: (payload, patchPayload, options = {}) => gameStateHooks.patchState(payload, patchPayload, options),
+    exportState: (options = {}) => gameStateHooks.exportState(options),
+    applyState: (payload, options = {}) => gameStateHooks.applyState(payload, options),
+    diffState: (beforePayload, afterPayload) => gameStateHooks.diffState(beforePayload, afterPayload),
+    patchState: (payload, patchPayload, options = {}) => gameStateHooks.patchState(payload, patchPayload, options),
+  };
+
+  return aura;
+}
+
+async function executeLifecycle(aura, frames) {
+  await executeSetup(aura);
+  await executeFrameSteps(aura, frames);
+}
+
+export async function executeSetup(aura) {
+  if (typeof aura.setup === 'function') {
+    await Promise.resolve(aura.setup());
+  }
+}
+
+export async function executeFrameSteps(aura, frames) {
+  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());
+    }
+  }
+}