@auraindustry/aurajs 0.0.7 → 0.1.0

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

@@ -0,0 +1,2253 @@
+export function createHeadlessWorldRuntime({ loadJsonAsset } = {}) {
+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 tilemapToPositiveInteger = (value) => {
+  if (!Number.isFinite(value)) return null;
+  const parsed = Math.floor(Number(value));
+  return parsed > 0 ? parsed : null;
+};
+const tilemapToFinite = (value) => (
+  Number.isFinite(value) ? Number(value) : null
+);
+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 tilemapParseTilePointArgs = (args, offset = 0) => {
+  const value = args[offset];
+  let x = null;
+  let y = null;
+  let nextIndex = offset;
+  if (value && typeof value === 'object') {
+    x = Number(value.x);
+    y = Number(value.y);
+    nextIndex = offset + 1;
+  } else {
+    x = Number(args[offset]);
+    y = Number(args[offset + 1]);
+    nextIndex = offset + 2;
+  }
+  if (!Number.isInteger(x) || !Number.isInteger(y)) return null;
+  return { x, y, nextIndex };
+};
+const tilemapParseTileOrRegionArgs = (args, offset = 0) => {
+  const value = args[offset];
+  if (value && typeof value === 'object') {
+    const x = Number(value.x);
+    const y = Number(value.y);
+    const hasRegion = Object.hasOwn(value, 'w') || Object.hasOwn(value, 'h');
+    if (hasRegion) {
+      const w = Number(value.w);
+      const h = Number(value.h);
+      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: offset + 1 };
+    }
+    if (!Number.isInteger(x) || !Number.isInteger(y)) return null;
+    return { x, y, w: 1, h: 1, nextIndex: offset + 1 };
+  }
+
+  const x = Number(args[offset]);
+  const y = Number(args[offset + 1]);
+  if (!Number.isInteger(x) || !Number.isInteger(y)) return null;
+
+  const w = Number(args[offset + 2]);
+  const h = Number(args[offset + 3]);
+  if (Number.isInteger(w) && Number.isInteger(h) && w > 0 && h > 0 && args[offset + 4] !== undefined) {
+    return { x, y, w, h, nextIndex: offset + 4 };
+  }
+  return { x, y, w: 1, h: 1, nextIndex: offset + 2 };
+};
+const tilemapTileIndexOrNull = (layer, x, y) => {
+  if (!Number.isInteger(x) || !Number.isInteger(y)) return null;
+  if (x < 0 || y < 0 || x >= layer.width || y >= layer.height) return null;
+  return (y * layer.width) + x;
+};
+const tilemapEnsureCollisionOverrideMap = (layer) => {
+  if (!(layer.collisionOverrides instanceof Map)) {
+    layer.collisionOverrides = new Map();
+  }
+  return layer.collisionOverrides;
+};
+const tilemapNormalizeLayerNameSet = (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 tilemapSortQueryHits = (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 tilemapNormalizeQueryModel = (model) => {
+  if (!model || typeof model !== 'object') {
+    return { ok: false, error: 'invalid tilemap model', reasonCode: 'invalid_model' };
+  }
+
+  const width = tilemapToPositiveInteger(model.width);
+  const height = tilemapToPositiveInteger(model.height);
+  const tileWidth = tilemapToFinite(model.tileWidth ?? model.tilewidth);
+  const tileHeight = tilemapToFinite(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 = tilemapNormalizeLayerNameSet(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 = tilemapToPositiveInteger(layer.width) ?? width;
+      const layerHeight = tilemapToPositiveInteger(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 (!Array.isArray(layer.data)) continue;
+      const overrideMap = layer.collisionOverrides instanceof Map
+        ? layer.collisionOverrides
+        : null;
+      const hasOverrides = !!overrideMap && overrideMap.size > 0;
+      if (!layerSolid && !hasOverrides) continue;
+
+      const maxEntries = Math.min(layer.data.length, width * height);
+      for (let index = 0; index < maxEntries; index += 1) {
+        const collisionOverride = overrideMap && overrideMap.has(index)
+          ? overrideMap.get(index)
+          : null;
+        const collidable = typeof collisionOverride === 'boolean'
+          ? collisionOverride
+          : layerSolid;
+        if (!collidable) continue;
+        const gid = Number(layer.data[index]);
+        if (!Number.isFinite(gid) || gid <= 0) continue;
+        const x = index % width;
+        const y = Math.floor(index / width);
+        pushCell(x, y, layerIndex, layerName);
+      }
+    }
+  }
+
+  tilemapSortQueryHits(cells);
+  return {
+    ok: true,
+    width,
+    height,
+    tileWidth,
+    tileHeight,
+    cells,
+  };
+};
+const tilemapResolveQueryModelInput = (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 tilemapParsePointArgs = (args, offset = 0) => {
+  const value = args[offset];
+  if (value && typeof value === 'object') {
+    const x = tilemapToFinite(value.x);
+    const y = tilemapToFinite(value.y);
+    if (x == null || y == null) return null;
+    return { x, y };
+  }
+  const x = tilemapToFinite(args[offset]);
+  const y = tilemapToFinite(args[offset + 1]);
+  if (x == null || y == null) return null;
+  return { x, y };
+};
+const tilemapParseAabbArgs = (args, offset = 0) => {
+  const value = args[offset];
+  if (value && typeof value === 'object') {
+    const x = tilemapToFinite(value.x);
+    const y = tilemapToFinite(value.y);
+    const w = tilemapToFinite(value.w);
+    const h = tilemapToFinite(value.h);
+    if (x == null || y == null || w == null || h == null) return null;
+    return { x, y, w, h };
+  }
+  const x = tilemapToFinite(args[offset]);
+  const y = tilemapToFinite(args[offset + 1]);
+  const w = tilemapToFinite(args[offset + 2]);
+  const h = tilemapToFinite(args[offset + 3]);
+  if (x == null || y == null || w == null || h == null) return null;
+  return { x, y, w, h };
+};
+const tilemapParseRayArgs = (args, offset = 0) => {
+  const value = args[offset];
+  if (value && typeof value === 'object') {
+    const x = tilemapToFinite(value.x);
+    const y = tilemapToFinite(value.y);
+    const dx = tilemapToFinite(value.dx);
+    const dy = tilemapToFinite(value.dy);
+    const maxDistance = tilemapToFinite(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 = tilemapToFinite(args[offset]);
+  const y = tilemapToFinite(args[offset + 1]);
+  const dx = tilemapToFinite(args[offset + 2]);
+  const dy = tilemapToFinite(args[offset + 3]);
+  const maxDistance = tilemapToFinite(args[offset + 4] ?? 10000);
+  if (x == null || y == null || dx == null || dy == null || maxDistance == null) return null;
+  return { x, y, dx, dy, maxDistance };
+};
+const tilemapParsePointArgsWithNext = (args, offset = 0) => {
+  const point = tilemapParsePointArgs(args, offset);
+  if (!point) return null;
+  const value = args[offset];
+  return {
+    ...point,
+    nextIndex: value && typeof value === 'object' ? offset + 1 : offset + 2,
+  };
+};
+const tilemapParseAabbArgsWithNext = (args, offset = 0) => {
+  const rect = tilemapParseAabbArgs(args, offset);
+  if (!rect) return null;
+  const value = args[offset];
+  return {
+    ...rect,
+    nextIndex: value && typeof value === 'object' ? offset + 1 : offset + 4,
+  };
+};
+const tilemapIsPrimitivePropertyValue = (value) => (
+  value == null
+  || typeof value === 'string'
+  || typeof value === 'boolean'
+  || (typeof value === 'number' && Number.isFinite(value))
+);
+const tilemapParseObjectPropertyFilter = (rawFilter) => {
+  if (typeof rawFilter === 'string') {
+    const name = rawFilter.trim();
+    if (!name) return null;
+    return { name, hasValue: false, value: null };
+  }
+  if (!rawFilter || typeof rawFilter !== 'object' || Array.isArray(rawFilter)) {
+    return null;
+  }
+  const name = typeof rawFilter.name === 'string' ? rawFilter.name.trim() : '';
+  if (!name) return null;
+  if (Object.hasOwn(rawFilter, 'value')) {
+    if (!tilemapIsPrimitivePropertyValue(rawFilter.value)) return null;
+    return { name, hasValue: true, value: rawFilter.value };
+  }
+  return { name, hasValue: false, value: null };
+};
+const tilemapParseObjectPropertiesFilter = (rawFilter) => {
+  if (!rawFilter || typeof rawFilter !== 'object' || Array.isArray(rawFilter)) {
+    return null;
+  }
+  const entries = Object.entries(rawFilter);
+  const normalized = {};
+  for (const [key, value] of entries) {
+    const normalizedKey = typeof key === 'string' ? key.trim() : '';
+    if (!normalizedKey || !tilemapIsPrimitivePropertyValue(value)) {
+      return null;
+    }
+    normalized[normalizedKey] = value;
+  }
+  return normalized;
+};
+const tilemapParseObjectQueryOptions = (rawOptions) => {
+  if (rawOptions == null) {
+    return {
+      ok: true,
+      options: {
+        includeHidden: false,
+        layerRef: null,
+        name: null,
+        type: null,
+        className: null,
+        visible: null,
+        propertyFilter: null,
+        propertiesFilter: null,
+      },
+    };
+  }
+  if (!rawOptions || typeof rawOptions !== 'object' || Array.isArray(rawOptions)) {
+    return { ok: false, error: 'invalid object query options', reasonCode: 'invalid_object_query_options' };
+  }
+
+  let layerRef = null;
+  if (Object.hasOwn(rawOptions, 'layer')) {
+    const rawLayer = rawOptions.layer;
+    if (typeof rawLayer === 'string') {
+      const trimmed = rawLayer.trim();
+      if (!trimmed) {
+        return { ok: false, error: 'invalid tilemap object layer', reasonCode: 'invalid_object_layer_ref' };
+      }
+      layerRef = trimmed;
+    } else if (Number.isInteger(rawLayer) && rawLayer >= 0) {
+      layerRef = Number(rawLayer);
+    } else {
+      return { ok: false, error: 'invalid tilemap object layer', reasonCode: 'invalid_object_layer_ref' };
+    }
+  }
+
+  let includeHidden = false;
+  if (Object.hasOwn(rawOptions, 'includeHidden')) {
+    if (typeof rawOptions.includeHidden !== 'boolean') {
+      return { ok: false, error: 'invalid object query options', reasonCode: 'invalid_object_query_options' };
+    }
+    includeHidden = rawOptions.includeHidden;
+  }
+
+  let visible = null;
+  if (Object.hasOwn(rawOptions, 'visible')) {
+    if (typeof rawOptions.visible !== 'boolean') {
+      return { ok: false, error: 'invalid object query options', reasonCode: 'invalid_object_query_options' };
+    }
+    visible = rawOptions.visible;
+    includeHidden = true;
+  }
+
+  const name = typeof rawOptions.name === 'string' && rawOptions.name.trim().length > 0
+    ? rawOptions.name.trim()
+    : null;
+  const type = typeof rawOptions.type === 'string' && rawOptions.type.trim().length > 0
+    ? rawOptions.type.trim()
+    : null;
+  const classNameRaw = typeof rawOptions.className === 'string'
+    ? rawOptions.className
+    : (typeof rawOptions.class === 'string' ? rawOptions.class : '');
+  const className = classNameRaw.trim().length > 0 ? classNameRaw.trim() : null;
+
+  let propertyFilter = null;
+  if (Object.hasOwn(rawOptions, 'property')) {
+    propertyFilter = tilemapParseObjectPropertyFilter(rawOptions.property);
+    if (!propertyFilter) {
+      return { ok: false, error: 'invalid object property filter', reasonCode: 'invalid_object_property_filter' };
+    }
+  }
+
+  let propertiesFilter = null;
+  if (Object.hasOwn(rawOptions, 'properties')) {
+    propertiesFilter = tilemapParseObjectPropertiesFilter(rawOptions.properties);
+    if (!propertiesFilter) {
+      return { ok: false, error: 'invalid object property filter', reasonCode: 'invalid_object_property_filter' };
+    }
+  }
+
+  return {
+    ok: true,
+    options: {
+      includeHidden,
+      layerRef,
+      name,
+      type,
+      className,
+      visible,
+      propertyFilter,
+      propertiesFilter,
+    },
+  };
+};
+const tilemapResolveObjectLayerRef = (map, layerRef) => {
+  if (!map || !Array.isArray(map.objectLayers)) return null;
+  if (typeof layerRef === 'number' && Number.isInteger(layerRef)) {
+    if (layerRef < 0) return null;
+    let selected = map.objectLayers.find((layer) => layer && layer.index === layerRef) || null;
+    if (!selected && layerRef >= 0 && layerRef < map.objectLayers.length) {
+      selected = map.objectLayers[layerRef] || null;
+    }
+    if (!selected) return null;
+    const resolvedIndex = Number.isInteger(selected.index)
+      ? selected.index
+      : map.objectLayers.indexOf(selected);
+    return { layer: selected, layerIndex: resolvedIndex };
+  }
+  if (typeof layerRef === 'string') {
+    const selected = map.objectLayers.find((layer) => layer && layer.name === layerRef) || null;
+    if (!selected) return null;
+    const resolvedIndex = Number.isInteger(selected.index)
+      ? selected.index
+      : map.objectLayers.indexOf(selected);
+    return { layer: selected, layerIndex: resolvedIndex };
+  }
+  return null;
+};
+const tilemapCollectObjectLayers = (map, layerRef) => {
+  if (!map || !Array.isArray(map.objectLayers)) {
+    return { ok: false, error: 'invalid tilemap handle', reasonCode: 'invalid_map_handle' };
+  }
+  if (layerRef == null) {
+    const layers = map.objectLayers
+      .map((layer, index) => ({
+        layer,
+        layerIndex: Number.isInteger(layer?.index) ? layer.index : index,
+      }))
+      .filter((entry) => !!entry.layer);
+    layers.sort((a, b) => {
+      if (a.layerIndex !== b.layerIndex) return a.layerIndex - b.layerIndex;
+      const aName = typeof a.layer.name === 'string' ? a.layer.name : '';
+      const bName = typeof b.layer.name === 'string' ? b.layer.name : '';
+      if (aName === bName) return 0;
+      return aName < bName ? -1 : 1;
+    });
+    return { ok: true, layers };
+  }
+  const resolved = tilemapResolveObjectLayerRef(map, layerRef);
+  if (!resolved) {
+    return { ok: false, error: 'invalid tilemap object layer', reasonCode: 'invalid_object_layer_ref' };
+  }
+  return { ok: true, layers: [resolved] };
+};
+const tilemapCloneObjectProperties = (properties) => {
+  if (!properties || typeof properties !== 'object' || Array.isArray(properties)) {
+    return {};
+  }
+  const out = {};
+  for (const key of Object.keys(properties).sort()) {
+    out[key] = properties[key];
+  }
+  return out;
+};
+const tilemapSortObjectQueryHits = (hits) => {
+  hits.sort((a, b) => {
+    if (a.layerIndex !== b.layerIndex) return a.layerIndex - b.layerIndex;
+    if (a.id !== b.id) return a.id - b.id;
+    if (a.objectIndex !== b.objectIndex) return a.objectIndex - b.objectIndex;
+    if (a.name !== b.name) return a.name < b.name ? -1 : 1;
+    if (a.type !== b.type) return a.type < b.type ? -1 : 1;
+    if (a.className !== b.className) return a.className < b.className ? -1 : 1;
+    if (a.y !== b.y) return a.y - b.y;
+    if (a.x !== b.x) return a.x - b.x;
+    return 0;
+  });
+  return hits;
+};
+const tilemapNormalizeObjectHit = (layer, layerIndex, object, objectIndex) => ({
+  layerName: typeof layer.name === 'string' ? layer.name : `layer_${layerIndex}`,
+  layerIndex,
+  objectIndex,
+  id: Number.isInteger(object.id) ? object.id : 0,
+  name: typeof object.name === 'string' ? object.name : '',
+  type: typeof object.type === 'string' ? object.type : '',
+  className: typeof object.className === 'string' ? object.className : '',
+  shape: typeof object.shape === 'string' ? object.shape : 'rectangle',
+  x: tilemapToFinite(object.x) ?? 0,
+  y: tilemapToFinite(object.y) ?? 0,
+  width: Math.max(0, tilemapToFinite(object.width) ?? 0),
+  height: Math.max(0, tilemapToFinite(object.height) ?? 0),
+  rotation: tilemapToFinite(object.rotation) ?? 0,
+  visible: object.visible !== false,
+  gid: Number.isInteger(object.gid) ? object.gid : 0,
+  properties: tilemapCloneObjectProperties(object.properties),
+});
+const tilemapObjectBounds = (object) => {
+  let minX = tilemapToFinite(object.x) ?? 0;
+  let minY = tilemapToFinite(object.y) ?? 0;
+  let maxX = minX + Math.max(0, tilemapToFinite(object.width) ?? 0);
+  let maxY = minY + Math.max(0, tilemapToFinite(object.height) ?? 0);
+  const points = Array.isArray(object.polygon)
+    ? object.polygon
+    : (Array.isArray(object.polyline) ? object.polyline : null);
+  if (points && points.length > 0) {
+    minX = Number.POSITIVE_INFINITY;
+    minY = Number.POSITIVE_INFINITY;
+    maxX = Number.NEGATIVE_INFINITY;
+    maxY = Number.NEGATIVE_INFINITY;
+    for (const point of points) {
+      if (!point || typeof point !== 'object') continue;
+      const px = (tilemapToFinite(object.x) ?? 0) + (tilemapToFinite(point.x) ?? 0);
+      const py = (tilemapToFinite(object.y) ?? 0) + (tilemapToFinite(point.y) ?? 0);
+      minX = Math.min(minX, px);
+      minY = Math.min(minY, py);
+      maxX = Math.max(maxX, px);
+      maxY = Math.max(maxY, py);
+    }
+    if (!Number.isFinite(minX) || !Number.isFinite(minY) || !Number.isFinite(maxX) || !Number.isFinite(maxY)) {
+      const fallbackX = tilemapToFinite(object.x) ?? 0;
+      const fallbackY = tilemapToFinite(object.y) ?? 0;
+      minX = fallbackX;
+      minY = fallbackY;
+      maxX = fallbackX;
+      maxY = fallbackY;
+    }
+  }
+  return { minX, minY, maxX, maxY };
+};
+const tilemapPointInObject = (object, point) => {
+  const bounds = tilemapObjectBounds(object);
+  const epsilon = 1e-9;
+  if (Math.abs(bounds.maxX - bounds.minX) <= epsilon && Math.abs(bounds.maxY - bounds.minY) <= epsilon) {
+    return Math.abs(point.x - bounds.minX) <= epsilon && Math.abs(point.y - bounds.minY) <= epsilon;
+  }
+  return point.x >= (bounds.minX - epsilon)
+    && point.x <= (bounds.maxX + epsilon)
+    && point.y >= (bounds.minY - epsilon)
+    && point.y <= (bounds.maxY + epsilon);
+};
+const tilemapAabbIntersectsObject = (object, rect) => {
+  const bounds = tilemapObjectBounds(object);
+  if (rect.w <= 0 || rect.h <= 0) return false;
+  const epsilon = 1e-9;
+  const rectMaxX = rect.x + rect.w;
+  const rectMaxY = rect.y + rect.h;
+  const isPoint = Math.abs(bounds.maxX - bounds.minX) <= epsilon && Math.abs(bounds.maxY - bounds.minY) <= epsilon;
+  if (isPoint) {
+    return bounds.minX >= (rect.x - epsilon)
+      && bounds.minX <= (rectMaxX + epsilon)
+      && bounds.minY >= (rect.y - epsilon)
+      && bounds.minY <= (rectMaxY + epsilon);
+  }
+  return bounds.minX < rectMaxX
+    && bounds.maxX > rect.x
+    && bounds.minY < rectMaxY
+    && bounds.maxY > rect.y;
+};
+const tilemapObjectMatchesFilter = (object, options) => {
+  if (typeof options.visible === 'boolean' && (object.visible !== options.visible)) {
+    return false;
+  }
+  if (options.name && object.name !== options.name) return false;
+  if (options.type && object.type !== options.type) return false;
+  if (options.className && object.className !== options.className) return false;
+
+  const properties = object && typeof object.properties === 'object' && !Array.isArray(object.properties)
+    ? object.properties
+    : {};
+
+  if (options.propertyFilter) {
+    const key = options.propertyFilter.name;
+    if (!Object.hasOwn(properties, key)) return false;
+    if (options.propertyFilter.hasValue && properties[key] !== options.propertyFilter.value) {
+      return false;
+    }
+  }
+  if (options.propertiesFilter) {
+    for (const [key, value] of Object.entries(options.propertiesFilter)) {
+      if (!Object.hasOwn(properties, key) || properties[key] !== value) return false;
+    }
+  }
+  return true;
+};
+const tilemapCollectFilteredObjectHits = (map, rawOptions, geometryPredicate = null) => {
+  const parsedOptions = tilemapParseObjectQueryOptions(rawOptions);
+  if (!parsedOptions.ok) return parsedOptions;
+  const options = parsedOptions.options;
+  const layerResult = tilemapCollectObjectLayers(map, options.layerRef);
+  if (!layerResult.ok) return layerResult;
+
+  const hits = [];
+  for (const entry of layerResult.layers) {
+    const layer = entry.layer;
+    const layerIndex = entry.layerIndex;
+    if (!options.includeHidden && layer.visible === false) continue;
+    if (!Array.isArray(layer.objects)) continue;
+
+    for (let objectIndex = 0; objectIndex < layer.objects.length; objectIndex += 1) {
+      const object = layer.objects[objectIndex];
+      if (!object || typeof object !== 'object') continue;
+      if (!options.includeHidden && object.visible === false) continue;
+      if (!tilemapObjectMatchesFilter(object, options)) continue;
+      if (geometryPredicate && !geometryPredicate(object)) continue;
+      hits.push(tilemapNormalizeObjectHit(layer, layerIndex, object, objectIndex));
+    }
+  }
+  tilemapSortObjectQueryHits(hits);
+  return { ok: true, hits };
+};
+const tilemapQueryHitsAtTile = (normalizedModel, tileX, tileY) => {
+  if (!Number.isInteger(tileX) || !Number.isInteger(tileY)) return [];
+  return normalizedModel.cells.filter((cell) => cell.x === tileX && cell.y === tileY);
+};
+const tilemapQueryFailResult = (error, reasonCode) => ({
+  ok: false,
+  hit: false,
+  hits: [],
+  error,
+  reasonCode,
+});
+const tilemapQueryOkResult = (payload = {}) => ({
+  ok: true,
+  error: null,
+  reasonCode: null,
+  ...payload,
+});
+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;
+      const draw2d = globalThis.aura?.draw2d;
+      if (draw2d && typeof draw2d.sprite === 'function') {
+        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,
+    };
+  },
+  queryPoint: (mapOrModel, ...args) => {
+    const resolvedModel = tilemapResolveQueryModelInput(mapOrModel);
+    if (!resolvedModel.ok) return tilemapQueryFailResult(resolvedModel.error, resolvedModel.reasonCode);
+    const normalizedModel = tilemapNormalizeQueryModel(resolvedModel.model);
+    if (!normalizedModel.ok) return tilemapQueryFailResult(normalizedModel.error, normalizedModel.reasonCode);
+    const point = tilemapParsePointArgs(args, 0);
+    if (!point) return tilemapQueryFailResult('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 = tilemapQueryHitsAtTile(normalizedModel, tileX, tileY);
+    return tilemapQueryOkResult({ hit: hits.length > 0, hits, tileX, tileY });
+  },
+  queryAABB: (mapOrModel, ...args) => {
+    const resolvedModel = tilemapResolveQueryModelInput(mapOrModel);
+    if (!resolvedModel.ok) return tilemapQueryFailResult(resolvedModel.error, resolvedModel.reasonCode);
+    const normalizedModel = tilemapNormalizeQueryModel(resolvedModel.model);
+    if (!normalizedModel.ok) return tilemapQueryFailResult(normalizedModel.error, normalizedModel.reasonCode);
+    const rect = tilemapParseAabbArgs(args, 0);
+    if (!rect || rect.w <= 0 || rect.h <= 0) {
+      return tilemapQueryFailResult('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 tilemapQueryOkResult({
+      hit: hits.length > 0,
+      hits,
+      range: { minTileX, minTileY, maxTileX, maxTileY },
+    });
+  },
+  queryRay: (mapOrModel, ...args) => {
+    const resolvedModel = tilemapResolveQueryModelInput(mapOrModel);
+    if (!resolvedModel.ok) return tilemapQueryFailResult(resolvedModel.error, resolvedModel.reasonCode);
+    const normalizedModel = tilemapNormalizeQueryModel(resolvedModel.model);
+    if (!normalizedModel.ok) return tilemapQueryFailResult(normalizedModel.error, normalizedModel.reasonCode);
+    const ray = tilemapParseRayArgs(args, 0);
+    const directionMagnitude = ray ? Math.hypot(ray.dx, ray.dy) : 0;
+    if (!ray || !Number.isFinite(directionMagnitude) || directionMagnitude <= 0 || ray.maxDistance <= 0) {
+      return tilemapQueryFailResult('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 = tilemapQueryHitsAtTile(normalizedModel, tileX, tileY);
+      if (hits.length > 0) {
+        return tilemapQueryOkResult({
+          hit: true,
+          hits,
+          hitCell: hits[0],
+          distance,
+          point: { x: sampleX, y: sampleY },
+          tileX,
+          tileY,
+        });
+      }
+    }
+    return tilemapQueryOkResult({
+      hit: false,
+      hits: [],
+      hitCell: null,
+      distance: null,
+      point: null,
+      tileX: null,
+      tileY: null,
+    });
+  },
+  queryRaycast: (mapOrModel, ...args) => tilemap.queryRay(mapOrModel, ...args),
+  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,
+    };
+  },
+  setTile: (mapId, layerRef, ...args) => {
+    const target = tilemapResolveLayerMutationTarget(mapId, layerRef);
+    if (!target.ok) return tilemapMutationFailResult(target.error, target.reasonCode);
+    const point = tilemapParseTilePointArgs(args, 0);
+    if (!point) return tilemapMutationFailResult('invalid tile coords args', 'invalid_tile_args');
+    const gid = tilemapParseNonNegGid(args[point.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 index = tilemapTileIndexOrNull(target.layer, point.x, point.y);
+    if (index == null) {
+      return tilemapMutationFailResult('tile coordinates out of bounds', 'tile_out_of_bounds');
+    }
+    const previousGid = Number(target.layer.data[index]) || 0;
+    const changed = previousGid !== gid;
+    if (changed) {
+      target.layer.data[index] = gid;
+    }
+    return tilemapMutationOkResult({
+      mapId: target.mapId,
+      layerName: target.layer.name,
+      layerIndex: target.layerIndex,
+      x: point.x,
+      y: point.y,
+      previousGid,
+      gid,
+      changed,
+      mutatedTiles: 1,
+      changedTiles: changed ? 1 : 0,
+    });
+  },
+  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,
+    });
+  },
+  setTileCollision: (mapId, layerRef, ...args) => {
+    const target = tilemapResolveLayerMutationTarget(mapId, layerRef);
+    if (!target.ok) return tilemapMutationFailResult(target.error, target.reasonCode);
+    const region = tilemapParseTileOrRegionArgs(args, 0);
+    if (!region) return tilemapMutationFailResult('invalid tile collision args', 'invalid_tile_collision_args');
+    const nextCollision = tilemapParseBooleanFlag(args[region.nextIndex]);
+    if (nextCollision == null) {
+      return tilemapMutationFailResult('invalid tile collision flag', 'invalid_collision_flag');
+    }
+    const overrides = tilemapEnsureCollisionOverrideMap(target.layer);
+    const startX = Math.max(0, region.x);
+    const startY = Math.max(0, region.y);
+    const endX = Math.min(target.layer.width, region.x + region.w);
+    const endY = Math.min(target.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 * target.layer.width) + x;
+        const previous = overrides.has(index) ? overrides.get(index) : null;
+        if (previous === nextCollision) continue;
+        overrides.set(index, nextCollision);
+        changedTiles += 1;
+      }
+    }
+
+    return tilemapMutationOkResult({
+      mapId: target.mapId,
+      layerName: target.layer.name,
+      layerIndex: target.layerIndex,
+      collision: nextCollision,
+      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),
+      },
+    });
+  },
+  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 },
+  ),
+  queryObjects: (mapId, options = null) => {
+    const map = tilemapResolveMap(mapId);
+    if (!map) return tilemapQueryFailResult('invalid tilemap handle', 'invalid_map_handle');
+    const result = tilemapCollectFilteredObjectHits(map, options, null);
+    if (!result.ok) return tilemapQueryFailResult(result.error, result.reasonCode);
+    return tilemapQueryOkResult({
+      hit: result.hits.length > 0,
+      count: result.hits.length,
+      hits: result.hits,
+    });
+  },
+  queryObjectsAtPoint: (mapId, ...args) => {
+    const map = tilemapResolveMap(mapId);
+    if (!map) return tilemapQueryFailResult('invalid tilemap handle', 'invalid_map_handle');
+    const point = tilemapParsePointArgsWithNext(args, 0);
+    if (!point) return tilemapQueryFailResult('invalid object point query args', 'invalid_object_point_args');
+    const options = args[point.nextIndex] ?? null;
+    const result = tilemapCollectFilteredObjectHits(
+      map,
+      options,
+      (object) => tilemapPointInObject(object, point),
+    );
+    if (!result.ok) return tilemapQueryFailResult(result.error, result.reasonCode);
+    return tilemapQueryOkResult({
+      hit: result.hits.length > 0,
+      count: result.hits.length,
+      hits: result.hits,
+      point: { x: point.x, y: point.y },
+    });
+  },
+  queryObjectsInAABB: (mapId, ...args) => {
+    const map = tilemapResolveMap(mapId);
+    if (!map) return tilemapQueryFailResult('invalid tilemap handle', 'invalid_map_handle');
+    const rect = tilemapParseAabbArgsWithNext(args, 0);
+    if (!rect || rect.w <= 0 || rect.h <= 0) {
+      return tilemapQueryFailResult('invalid object aabb query args', 'invalid_object_aabb_args');
+    }
+    const options = args[rect.nextIndex] ?? null;
+    const result = tilemapCollectFilteredObjectHits(
+      map,
+      options,
+      (object) => tilemapAabbIntersectsObject(object, rect),
+    );
+    if (!result.ok) return tilemapQueryFailResult(result.error, result.reasonCode);
+    return tilemapQueryOkResult({
+      hit: result.hits.length > 0,
+      count: result.hits.length,
+      hits: result.hits,
+      range: {
+        x: rect.x,
+        y: rect.y,
+        w: rect.w,
+        h: rect.h,
+      },
+    });
+  },
+};
+
+const 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);
+      }
+    },
+  };
+
+  return {
+    ecs,
+    scene,
+    scene3d,
+    tilemap,
+  };
+}