beardos-toolbox 0.1.0

package/dist/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../s3.ts", "../jsonl.ts", "../misc-js-funcs.ts", "../tile-map.ts", "../index.ts"],
+  "sourcesContent": ["/* eslint-disable no-console */\r\nimport { S3Client, PutObjectCommand, GetObjectCommand, ListObjectsV2Command, ListObjectsV2CommandInput, DeleteObjectCommand } from \"@aws-sdk/client-s3\";\r\nlet client: S3Client;\r\n\r\nexport interface IS3Config {\r\n  region: string;\r\n  bucket: string;\r\n  accessKeyId: string;\r\n  secretAccessKey: string;\r\n}\r\n\r\nexport const getClient = ({ region, accessKeyId, secretAccessKey }: IS3Config) => {\r\n  if (!client) {\r\n    client = new S3Client({ region, credentials: { accessKeyId, secretAccessKey } });\r\n  }\r\n\r\n  return client;\r\n};\r\n\r\nexport const putObject = async(config: IS3Config, data: Buffer | string, key: string, contentType?: string) => {\r\n  try {\r\n    const cl = getClient(config);\r\n\r\n    const params: { Bucket: string; Key: string; Body: Buffer | string; ContentType?: string } = {\r\n      Bucket: config.bucket,\r\n      Key: key,\r\n      Body: typeof data === 'string' ? Buffer.from(data, \"utf-8\") : data\r\n    };\r\n    if(contentType) {\r\n      params.ContentType = contentType\r\n    }\r\n\r\n    return await cl.send(new PutObjectCommand(params));\r\n  } catch (e) {\r\n    console.error('Could not upload json file', { error: e });\r\n    throw e;\r\n  }\r\n};\r\n\r\nexport const getObject = async(config: IS3Config, key: string) => {\r\n  const params = {\r\n    Bucket: config.bucket,\r\n    Key: key,\r\n  };\r\n\r\n  try {\r\n    const cl = getClient(config);\r\n\r\n    return await cl.send(new GetObjectCommand(params));\r\n  } catch (e) {\r\n    console.error('Could not get object from s3', { error: e, params });\r\n    throw e;\r\n  }\r\n};\r\n\r\nexport const listObjects = async(config: IS3Config, prefix: string, Marker?: string) => {\r\n  const params: ListObjectsV2CommandInput = {\r\n    Bucket: config.bucket,\r\n    Prefix: prefix,\r\n  };\r\n  if (Marker) {\r\n    params.StartAfter = Marker;\r\n  }\r\n  try {\r\n    const cl = getClient(config);\r\n\r\n    const response = await cl.send(new ListObjectsV2Command(params));\r\n    return { Objects: (response.Contents ?? []), Marker: response.NextContinuationToken };\r\n  } catch (e) {\r\n    console.error('Could not upload json file', { error: e });\r\n    throw e;\r\n  }\r\n};\r\n\r\nexport const deleteObject = async(config: IS3Config, Key: string) => {\r\n  const params = {\r\n    Bucket: config.bucket,\r\n    Key,\r\n  };\r\n\r\n  try {\r\n    const cl = getClient(config);\r\n\r\n    return await cl.send(new DeleteObjectCommand(params));\r\n  } catch (e) {\r\n    console.error('Could not delete object from s3', { error: e, params });\r\n    throw e;\r\n  }\r\n};\r\n", "import { EOL } from 'os'\r\n\r\n/**\r\n * made fairly specifically for arrays when dealing with larger qunatities of data that you may need to concat later\r\n */\r\n\r\nexport default {\r\n  stringify: (data: any[]): string => {\r\n    return data.map((d) => JSON.stringify(d)).join(EOL);\r\n  },\r\n\r\n  parse: (data: string): any[] => {\r\n    return data.split(EOL).map((d, i) => {\r\n      try{\r\n        return JSON.parse(d);\r\n      } catch (e: any) {\r\n        console.error('Could not parse JSONL on line: ' + i, { error: e.message, line: i });\r\n      }\r\n    });\r\n  },\r\n}\r\n  \r\n", "const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));\r\n\r\nconst chunkArray = (source: Array<any>, chunkSize: number = 10) => {\r\n  const chunks = source.reduce((resultArray, item, index) => { \r\n    const chunkIndex = Math.floor(index/chunkSize)\r\n  \r\n    if(!resultArray[chunkIndex]) {\r\n      resultArray[chunkIndex] = []\r\n    }\r\n  \r\n    resultArray[chunkIndex].push(item)\r\n  \r\n    return resultArray\r\n  }, [])\r\n  return chunks\r\n}\r\n\r\nconst settledSeparator = (result: Array<PromiseSettledResult<any>>) => {\r\n  const settled = result.filter((r) => r.status === 'fulfilled')\r\n  const rejected = result.filter((r) => r.status === 'rejected')\r\n  return { settled, rejected, total: result.length }\r\n}\r\n  \r\nconst timeFormat = (ms: number) => {\r\n  if (ms < 1000) return `${ms} ms`;\r\n  if (ms < 60000) return `${(ms / 1000).toFixed(2)} secs`;\r\n  if (ms < 3600000) return `${(ms / 60000).toFixed(2)} mins`;\r\n  return `${(ms / 3600000).toFixed(2)} hrs`;\r\n}\r\n\r\nconst timeSinceString = (ms: number) => {\r\n  return timeFormat(Date.now() - ms);\r\n}\r\n\r\nconst generateRandomString = (length = 8) => {\r\n  return Math.random().toString(36).substring(2, 2 + length);\r\n}\r\n\r\n\r\nexport {\r\n  sleep,\r\n  chunkArray,\r\n  settledSeparator,\r\n  timeFormat,\r\n  timeSinceString,\r\n  generateRandomString\r\n}\r\n\r\nexport default {\r\n  sleep,\r\n  chunkArray,\r\n  settledSeparator,\r\n  timeFormat,\r\n  timeSinceString,\r\n  generateRandomString\r\n}\r\n", "// --- types ---\n\n/** A 2-D grid of tiles. `T` is the entity type stored per tile. */\nexport type TileMap<T = unknown> = {\n  readonly width: number\n  readonly height: number\n  readonly size: number\n  flags: Uint8Array\n  entities: Map<number, T[]>\n}\n\n/**\n * A snapshot of a single tile's state.\n * `index` is the flat array position (`y * width + x`).\n */\nexport type TileInfo<T> = {\n  readonly index: number\n  readonly x: number\n  readonly y: number\n  flags: number\n  entities: T[]\n}\n\n/** Shape used when collecting tiles or entities within a radius. */\nexport type RangeShape = 'square' | 'circle'\n\n/** Return `true` to pass, `false` to fail. Used by `validateTile` and `validateRange`. */\nexport type TileValidator<T> = (tile: TileInfo<T>) => boolean\n\n/**\n * Predefined single-bit flag constants.\n * Combine multiple flags with the bitwise OR operator:\n * ```ts\n * setFlag(map, x, y, TileFlags.BLOCKED | TileFlags.HAZARD)\n * ```\n * You can define additional custom flags as any unused power-of-two number\n * up to `0b10000000` (Uint8 supports 8 independent bits total).\n */\nexport const TileFlags = {\n  NONE:       0b00000000,\n  BLOCKED:    0b00000001,\n  OCCUPIED:   0b00000010,\n  VISIBLE:    0b00000100,\n  EXPLORED:   0b00001000,\n  WATER:      0b00010000,\n  HAZARD:     0b00100000,\n} as const\n\n// --- internal helpers ---\n\nconst _idx = (width: number, x: number, y: number): number => y * width + x\n\nconst _inBounds = (width: number, height: number, x: number, y: number): boolean =>\n  x >= 0 && x < width && y >= 0 && y < height\n\n// Packed dx/dy pairs for cardinal then diagonal neighbours\nconst _CARDINAL = new Int8Array([-1, 0, 1, 0, 0, -1, 0, 1])\nconst _ALL_ADJ  = new Int8Array([-1, 0, 1, 0, 0, -1, 0, 1, -1, -1, -1, 1, 1, -1, 1, 1])\n\n// --- creation ---\n\n/**\n * Create a new tile map of the given dimensions.\n * All flags start at 0 and no entities are placed.\n * @param width  Number of columns.\n * @param height Number of rows.\n * @returns A fresh `TileMap<T>`.\n * @example\n * type Unit = { id: string }\n * const map = createTileMap<Unit>(64, 64)\n */\nexport const createTileMap = <T>(width: number, height: number): TileMap<T> => ({\n  width,\n  height,\n  size: width * height,\n  flags: new Uint8Array(width * height),\n  entities: new Map(),\n})\n\n// --- tile access ---\n\n/**\n * Convert grid coordinates to a flat array index.\n * Returns `-1` when the coordinates are out of bounds.\n * @param map The tile map.\n * @param x   Column.\n * @param y   Row.\n */\nexport const getTileIndex = (map: TileMap<unknown>, x: number, y: number): number =>\n  _inBounds(map.width, map.height, x, y) ? _idx(map.width, x, y) : -1\n\n/**\n * Return a `TileInfo` snapshot for the tile at `(x, y)`.\n * Returns `null` when the coordinates are out of bounds.\n * @param map The tile map.\n * @param x   Column.\n * @param y   Row.\n */\nexport const getTileInfo = <T>(map: TileMap<T>, x: number, y: number): TileInfo<T> | null => {\n  if (!_inBounds(map.width, map.height, x, y)) return null\n  const index = _idx(map.width, x, y)\n  return {\n    index,\n    x,\n    y,\n    flags: map.flags[index],\n    entities: map.entities.get(index) ?? [],\n  }\n}\n\n/**\n * Convert a flat array index back to `{ x, y }` grid coordinates.\n * @param map   The tile map (used for its `width`).\n * @param index Flat tile index.\n */\nexport const indexToCoords = (map: TileMap<unknown>, index: number): { x: number; y: number } => ({\n  x: index % map.width,\n  y: (index / map.width) | 0,\n})\n\n// --- flag operations (bitwise, Uint8 supports 8 independent flags) ---\n\n/**\n * Set one or more flags on a tile using bitwise OR.\n * Out-of-bounds coordinates are silently ignored.\n * @param map  The tile map.\n * @param x    Column.\n * @param y    Row.\n * @param flag Flag bit(s) from `TileFlags` or a custom power-of-two constant.\n * @example\n * setFlag(map, 3, 5, TileFlags.BLOCKED)\n */\nexport const setFlag = (map: TileMap<unknown>, x: number, y: number, flag: number): void => {\n  if (_inBounds(map.width, map.height, x, y)) map.flags[_idx(map.width, x, y)] |= flag\n}\n\n/**\n * Clear one or more flags on a tile using bitwise AND NOT.\n * Out-of-bounds coordinates are silently ignored.\n * @param map  The tile map.\n * @param x    Column.\n * @param y    Row.\n * @param flag Flag bit(s) to clear.\n */\nexport const clearFlag = (map: TileMap<unknown>, x: number, y: number, flag: number): void => {\n  if (_inBounds(map.width, map.height, x, y)) map.flags[_idx(map.width, x, y)] &= ~flag\n}\n\n/**\n * Toggle one or more flags on a tile using bitwise XOR.\n * Out-of-bounds coordinates are silently ignored.\n * @param map  The tile map.\n * @param x    Column.\n * @param y    Row.\n * @param flag Flag bit(s) to toggle.\n */\nexport const toggleFlag = (map: TileMap<unknown>, x: number, y: number, flag: number): void => {\n  if (_inBounds(map.width, map.height, x, y)) map.flags[_idx(map.width, x, y)] ^= flag\n}\n\n/**\n * Return `true` if **all** supplied flag bits are set on the tile.\n * Returns `false` for out-of-bounds coordinates.\n * @param map  The tile map.\n * @param x    Column.\n * @param y    Row.\n * @param flag Flag bit(s) to test.\n * @example\n * if (hasFlag(map, x, y, TileFlags.BLOCKED)) { ... }\n */\nexport const hasFlag = (map: TileMap<unknown>, x: number, y: number, flag: number): boolean => {\n  if (!_inBounds(map.width, map.height, x, y)) return false\n  return (map.flags[_idx(map.width, x, y)] & flag) !== 0\n}\n\n// --- entity operations ---\n\n/**\n * Add an entity to the tile at `(x, y)`.\n * Returns `false` when the coordinates are out of bounds (entity is not added).\n * @param map    The tile map.\n * @param x      Column.\n * @param y      Row.\n * @param entity The entity to place on the tile.\n */\nexport const addEntity = <T>(map: TileMap<T>, x: number, y: number, entity: T): boolean => {\n  if (!_inBounds(map.width, map.height, x, y)) return false\n  const index = _idx(map.width, x, y)\n  const bucket = map.entities.get(index)\n  if (bucket) bucket.push(entity)\n  else map.entities.set(index, [entity])\n  return true\n}\n\n/**\n * Remove the **first** entity on the tile at `(x, y)` for which `predicate` returns `true`.\n * Returns `false` when out of bounds or no matching entity is found.\n * @param map       The tile map.\n * @param x         Column.\n * @param y         Row.\n * @param predicate Selector \u2014 return `true` for the entity to remove.\n * @example\n * removeEntity(map, x, y, e => e.id === 'hero')\n */\nexport const removeEntity = <T>(\n  map: TileMap<T>,\n  x: number,\n  y: number,\n  predicate: (e: T) => boolean\n): boolean => {\n  if (!_inBounds(map.width, map.height, x, y)) return false\n  const index = _idx(map.width, x, y)\n  const bucket = map.entities.get(index)\n  if (!bucket) return false\n  for (let i = 0; i < bucket.length; i++) {\n    if (predicate(bucket[i])) {\n      bucket.splice(i, 1)\n      if (bucket.length === 0) map.entities.delete(index)\n      return true\n    }\n  }\n  return false\n}\n\n/**\n * Atomically move the **first** matching entity from one tile to another.\n * Returns `false` when either coordinate is out of bounds or no matching entity is found.\n * @param map       The tile map.\n * @param fromX     Source column.\n * @param fromY     Source row.\n * @param toX       Destination column.\n * @param toY       Destination row.\n * @param predicate Selector \u2014 return `true` for the entity to move.\n * @example\n * moveEntity(map, 2, 3, 2, 4, e => e.id === 'hero')\n */\nexport const moveEntity = <T>(\n  map: TileMap<T>,\n  fromX: number,\n  fromY: number,\n  toX: number,\n  toY: number,\n  predicate: (e: T) => boolean\n): boolean => {\n  const { width, height } = map\n  if (!_inBounds(width, height, fromX, fromY) || !_inBounds(width, height, toX, toY)) return false\n  const srcIndex = _idx(width, fromX, fromY)\n  const src = map.entities.get(srcIndex)\n  if (!src) return false\n  for (let i = 0; i < src.length; i++) {\n    if (predicate(src[i])) {\n      const entity = src[i]\n      src.splice(i, 1)\n      if (src.length === 0) map.entities.delete(srcIndex)\n      const dstIndex = _idx(width, toX, toY)\n      const dst = map.entities.get(dstIndex)\n      if (dst) dst.push(entity)\n      else map.entities.set(dstIndex, [entity])\n      return true\n    }\n  }\n  return false\n}\n\n/**\n * Return all entities on the tile at `(x, y)`.\n * Returns an empty array for out-of-bounds coordinates or tiles with no entities.\n * @param map The tile map.\n * @param x   Column.\n * @param y   Row.\n */\nexport const getEntitiesAt = <T>(map: TileMap<T>, x: number, y: number): T[] => {\n  if (!_inBounds(map.width, map.height, x, y)) return []\n  return map.entities.get(_idx(map.width, x, y)) ?? []\n}\n\n/**\n * Remove all entities from the tile at `(x, y)`.\n * Out-of-bounds coordinates are silently ignored.\n * @param map The tile map.\n * @param x   Column.\n * @param y   Row.\n */\nexport const clearEntitiesAt = <T>(map: TileMap<T>, x: number, y: number): void => {\n  if (_inBounds(map.width, map.height, x, y)) map.entities.delete(_idx(map.width, x, y))\n}\n\n// --- adjacency ---\n\n/**\n * Return the flat indices of tiles adjacent to `(x, y)`.\n * Only in-bounds neighbours are included.\n * @param map              The tile map.\n * @param x                Column.\n * @param y                Row.\n * @param includeDiagonals When `true`, returns up to 8 neighbours; otherwise up to 4 (cardinal only).\n */\nexport const getAdjacentIndices = (\n  map: TileMap<unknown>,\n  x: number,\n  y: number,\n  includeDiagonals = false\n): number[] => {\n  const { width, height } = map\n  const offsets = includeDiagonals ? _ALL_ADJ : _CARDINAL\n  const result: number[] = []\n  for (let i = 0; i < offsets.length; i += 2) {\n    const nx = x + offsets[i]\n    const ny = y + offsets[i + 1]\n    if (nx >= 0 && nx < width && ny >= 0 && ny < height) result.push(_idx(width, nx, ny))\n  }\n  return result\n}\n\n/**\n * Return full `TileInfo` snapshots for all tiles adjacent to `(x, y)`.\n * Only in-bounds neighbours are included.\n * @param map              The tile map.\n * @param x                Column.\n * @param y                Row.\n * @param includeDiagonals When `true`, returns up to 8 neighbours; otherwise up to 4 (cardinal only).\n */\nexport const getAdjacentTiles = <T>(\n  map: TileMap<T>,\n  x: number,\n  y: number,\n  includeDiagonals = false\n): TileInfo<T>[] => {\n  const { width, height } = map\n  const offsets = includeDiagonals ? _ALL_ADJ : _CARDINAL\n  const result: TileInfo<T>[] = []\n  for (let i = 0; i < offsets.length; i += 2) {\n    const nx = x + offsets[i]\n    const ny = y + offsets[i + 1]\n    if (nx >= 0 && nx < width && ny >= 0 && ny < height) {\n      const index = _idx(width, nx, ny)\n      result.push({ index, x: nx, y: ny, flags: map.flags[index], entities: map.entities.get(index) ?? [] })\n    }\n  }\n  return result\n}\n\n// --- range queries ---\n\n/**\n * Return the flat indices of all tiles within `range` of `(x, y)`.\n * The origin tile is excluded unless `includeOrigin` is `true`.\n * Circle shape uses integer `dx\u00B2 + dy\u00B2 \u2264 range\u00B2` \u2014 no `Math.sqrt`.\n * @param map           The tile map.\n * @param x             Center column.\n * @param y             Center row.\n * @param range         Radius in tiles.\n * @param shape         `'square'` (default) or `'circle'`.\n * @param includeOrigin Include the center tile itself (default `false`).\n */\nexport const getIndicesInRange = (\n  map: TileMap<unknown>,\n  x: number,\n  y: number,\n  range: number,\n  shape: RangeShape = 'square',\n  includeOrigin = false\n): number[] => {\n  const { width, height } = map\n  const r2 = range * range\n  const result: number[] = []\n  for (let dy = -range; dy <= range; dy++) {\n    const ny = y + dy\n    if (ny < 0 || ny >= height) continue\n    for (let dx = -range; dx <= range; dx++) {\n      if (!includeOrigin && dx === 0 && dy === 0) continue\n      if (shape === 'circle' && dx * dx + dy * dy > r2) continue\n      const nx = x + dx\n      if (nx >= 0 && nx < width) result.push(_idx(width, nx, ny))\n    }\n  }\n  return result\n}\n\n/**\n * Return full `TileInfo` snapshots for all tiles within `range` of `(x, y)`.\n * The origin tile is excluded unless `includeOrigin` is `true`.\n * @param map           The tile map.\n * @param x             Center column.\n * @param y             Center row.\n * @param range         Radius in tiles.\n * @param shape         `'square'` (default) or `'circle'`.\n * @param includeOrigin Include the center tile itself (default `false`).\n */\nexport const getTilesInRange = <T>(\n  map: TileMap<T>,\n  x: number,\n  y: number,\n  range: number,\n  shape: RangeShape = 'square',\n  includeOrigin = false\n): TileInfo<T>[] => {\n  const { width, height } = map\n  const r2 = range * range\n  const result: TileInfo<T>[] = []\n  for (let dy = -range; dy <= range; dy++) {\n    const ny = y + dy\n    if (ny < 0 || ny >= height) continue\n    for (let dx = -range; dx <= range; dx++) {\n      if (!includeOrigin && dx === 0 && dy === 0) continue\n      if (shape === 'circle' && dx * dx + dy * dy > r2) continue\n      const nx = x + dx\n      if (nx >= 0 && nx < width) {\n        const index = _idx(width, nx, ny)\n        result.push({ index, x: nx, y: ny, flags: map.flags[index], entities: map.entities.get(index) ?? [] })\n      }\n    }\n  }\n  return result\n}\n\n/**\n * Collect and return every entity on every tile within `range` of `(x, y)`.\n * The origin tile is excluded unless `includeOrigin` is `true`.\n * Tiles with no entities contribute nothing to the result.\n * @param map           The tile map.\n * @param x             Center column.\n * @param y             Center row.\n * @param range         Radius in tiles.\n * @param shape         `'square'` (default) or `'circle'`.\n * @param includeOrigin Include entities on the center tile itself (default `false`).\n * @example\n * const enemies = getEntitiesInRange(map, heroX, heroY, 3, 'circle')\n */\nexport const getEntitiesInRange = <T>(\n  map: TileMap<T>,\n  x: number,\n  y: number,\n  range: number,\n  shape: RangeShape = 'square',\n  includeOrigin = false\n): T[] => {\n  const { width, height } = map\n  const r2 = range * range\n  const result: T[] = []\n  for (let dy = -range; dy <= range; dy++) {\n    const ny = y + dy\n    if (ny < 0 || ny >= height) continue\n    for (let dx = -range; dx <= range; dx++) {\n      if (!includeOrigin && dx === 0 && dy === 0) continue\n      if (shape === 'circle' && dx * dx + dy * dy > r2) continue\n      const nx = x + dx\n      if (nx < 0 || nx >= width) continue\n      const bucket = map.entities.get(_idx(width, nx, ny))\n      if (bucket) for (let i = 0; i < bucket.length; i++) result.push(bucket[i])\n    }\n  }\n  return result\n}\n\n// --- validation ---\n\n/**\n * Test whether the tile at `(x, y)` is in bounds and passes an optional validator.\n * When no `validator` is provided, returns `true` for any in-bounds coordinate.\n * @param map       The tile map.\n * @param x         Column.\n * @param y         Row.\n * @param validator Optional predicate; receives a `TileInfo` snapshot.\n * @example\n * const passable = validateTile(map, x, y, t => !(t.flags & TileFlags.BLOCKED))\n */\nexport const validateTile = <T>(\n  map: TileMap<T>,\n  x: number,\n  y: number,\n  validator?: TileValidator<T>\n): boolean => {\n  if (!_inBounds(map.width, map.height, x, y)) return false\n  if (!validator) return true\n  const index = _idx(map.width, x, y)\n  return validator({ index, x, y, flags: map.flags[index], entities: map.entities.get(index) ?? [] })\n}\n\n/**\n * Test whether **every** tile within `range` of `(x, y)` passes `validator`.\n * Short-circuits on the first failing tile. Out-of-bounds tiles are skipped entirely.\n * The origin tile is excluded unless `includeOrigin` is `true`.\n * @param map           The tile map.\n * @param x             Center column.\n * @param y             Center row.\n * @param range         Radius in tiles.\n * @param validator     Predicate; receives a `TileInfo` snapshot.\n * @param shape         `'square'` (default) or `'circle'`.\n * @param includeOrigin Include the center tile in validation (default `false`).\n * @example\n * const areaClear = validateRange(map, x, y, 2, t => t.entities.length === 0)\n */\nexport const validateRange = <T>(\n  map: TileMap<T>,\n  x: number,\n  y: number,\n  range: number,\n  validator: TileValidator<T>,\n  shape: RangeShape = 'square',\n  includeOrigin = false\n): boolean => {\n  const { width, height } = map\n  const r2 = range * range\n  for (let dy = -range; dy <= range; dy++) {\n    const ny = y + dy\n    if (ny < 0 || ny >= height) continue\n    for (let dx = -range; dx <= range; dx++) {\n      if (!includeOrigin && dx === 0 && dy === 0) continue\n      if (shape === 'circle' && dx * dx + dy * dy > r2) continue\n      const nx = x + dx\n      if (nx < 0 || nx >= width) continue\n      const index = _idx(width, nx, ny)\n      if (!validator({ index, x: nx, y: ny, flags: map.flags[index], entities: map.entities.get(index) ?? [] })) return false\n    }\n  }\n  return true\n}\n\n// --- spatial / screen-space ---\n\n/**\n * Pixel dimensions of a single tile and an optional world-space origin offset.\n * Create once and reuse; it never mutates.\n *\n * - `tileWidth` / `tileHeight`: pixels per tile (e.g. 32 for a 32\u00D732 sprite sheet).\n * - `originX` / `originY`: world-pixel offset of tile (0, 0)'s top-left corner.\n *   Use this to add margins or align the grid inside a larger world.\n *\n * Non-square tiles (e.g. 64\u00D732 isometric projections) are fully supported.\n */\nexport type SpatialConfig = {\n  readonly tileWidth: number\n  readonly tileHeight: number\n  readonly originX: number\n  readonly originY: number\n}\n\n/**\n * Fractional tile-grid position for an entity at an arbitrary world coordinate.\n * `tileX` / `tileY` are the integer grid cell; `fracX` / `fracY` are 0..1 offsets\n * within that cell \u2014 useful for smooth movement interpolation and collision checks.\n */\nexport type TilePosition = {\n  tileX: number\n  tileY: number\n  fracX: number\n  fracY: number\n}\n\n/**\n * Create a `SpatialConfig`.\n * @param tileWidth  Pixels per tile column.\n * @param tileHeight Pixels per tile row.\n * @param originX    World-pixel X of the grid's top-left corner (default `0`).\n * @param originY    World-pixel Y of the grid's top-left corner (default `0`).\n * @example\n * const spatial = createSpatialConfig(32, 32)\n * const spatial = createSpatialConfig(64, 32, 128, 64) // offset grid\n */\nexport const createSpatialConfig = (\n  tileWidth: number,\n  tileHeight: number,\n  originX = 0,\n  originY = 0\n): SpatialConfig => ({ tileWidth, tileHeight, originX, originY })\n\n/**\n * Convert world-pixel coordinates to integer tile grid coordinates.\n * Fractions are floored, so the result is always the tile the point falls inside.\n * Returns `{ x: -1, y: -1 }` when the world position is before the grid origin.\n * @param spatial World-to-grid mapping config.\n * @param wx      World X in pixels.\n * @param wy      World Y in pixels.\n */\nexport const worldToTile = (\n  spatial: SpatialConfig,\n  wx: number,\n  wy: number\n): { x: number; y: number } => ({\n  x: ((wx - spatial.originX) / spatial.tileWidth)  | 0,\n  y: ((wy - spatial.originY) / spatial.tileHeight) | 0,\n})\n\n/**\n * Convert tile grid coordinates to the world-pixel position of the tile's **top-left corner**.\n * @param spatial World-to-grid mapping config.\n * @param tx      Tile column.\n * @param ty      Tile row.\n */\nexport const tileToWorld = (\n  spatial: SpatialConfig,\n  tx: number,\n  ty: number\n): { x: number; y: number } => ({\n  x: tx * spatial.tileWidth  + spatial.originX,\n  y: ty * spatial.tileHeight + spatial.originY,\n})\n\n/**\n * Convert tile grid coordinates to the world-pixel position of the tile's **center**.\n * Useful for placing sprites, projectile origins, or distance calculations.\n * @param spatial World-to-grid mapping config.\n * @param tx      Tile column.\n * @param ty      Tile row.\n */\nexport const tileCenterWorld = (\n  spatial: SpatialConfig,\n  tx: number,\n  ty: number\n): { x: number; y: number } => ({\n  x: tx * spatial.tileWidth  + spatial.originX + (spatial.tileWidth  >> 1),\n  y: ty * spatial.tileHeight + spatial.originY + (spatial.tileHeight >> 1),\n})\n\n/**\n * Convert screen-pixel coordinates to world-pixel coordinates using the camera offset.\n * The camera position is the world-space coordinate of the screen's top-left corner.\n * @param cameraX Camera world X (scroll offset).\n * @param cameraY Camera world Y (scroll offset).\n * @param sx      Screen X in pixels.\n * @param sy      Screen Y in pixels.\n */\nexport const screenToWorld = (\n  cameraX: number,\n  cameraY: number,\n  sx: number,\n  sy: number\n): { x: number; y: number } => ({\n  x: sx + cameraX,\n  y: sy + cameraY,\n})\n\n/**\n * Convert world-pixel coordinates to screen-pixel coordinates using the camera offset.\n * @param cameraX Camera world X (scroll offset).\n * @param cameraY Camera world Y (scroll offset).\n * @param wx      World X in pixels.\n * @param wy      World Y in pixels.\n */\nexport const worldToScreen = (\n  cameraX: number,\n  cameraY: number,\n  wx: number,\n  wy: number\n): { x: number; y: number } => ({\n  x: wx - cameraX,\n  y: wy - cameraY,\n})\n\n/**\n * Convert screen-pixel coordinates directly to tile grid coordinates,\n * accounting for both the camera offset and the grid origin.\n * @param spatial World-to-grid mapping config.\n * @param cameraX Camera world X (scroll offset).\n * @param cameraY Camera world Y (scroll offset).\n * @param sx      Screen X in pixels.\n * @param sy      Screen Y in pixels.\n */\nexport const screenToTile = (\n  spatial: SpatialConfig,\n  cameraX: number,\n  cameraY: number,\n  sx: number,\n  sy: number\n): { x: number; y: number } => ({\n  x: ((sx + cameraX - spatial.originX) / spatial.tileWidth)  | 0,\n  y: ((sy + cameraY - spatial.originY) / spatial.tileHeight) | 0,\n})\n\n/**\n * Convert tile grid coordinates to screen-pixel coordinates (top-left of the tile),\n * accounting for the camera offset and grid origin.\n * @param spatial World-to-grid mapping config.\n * @param cameraX Camera world X (scroll offset).\n * @param cameraY Camera world Y (scroll offset).\n * @param tx      Tile column.\n * @param ty      Tile row.\n */\nexport const tileToScreen = (\n  spatial: SpatialConfig,\n  cameraX: number,\n  cameraY: number,\n  tx: number,\n  ty: number\n): { x: number; y: number } => ({\n  x: tx * spatial.tileWidth  + spatial.originX - cameraX,\n  y: ty * spatial.tileHeight + spatial.originY - cameraY,\n})\n\n/**\n * Return the exact fractional tile-grid position for a world coordinate.\n * `tileX` / `tileY` are the integer grid cell the point is inside.\n * `fracX` / `fracY` are 0..1 fractions representing how far into the tile the point is \u2014\n * essential for smooth cross-tile movement, linear interpolation animations, and sub-tile collision.\n * @param spatial World-to-grid mapping config.\n * @param wx      World X in pixels.\n * @param wy      World Y in pixels.\n * @example\n * // Entity smoothly walking; determine which tile it's in and how far across\n * const pos = worldToTileExact(spatial, entity.x, entity.y)\n * // pos.fracX === 0.5 means entity is horizontally centred in its tile\n */\nexport const worldToTileExact = (\n  spatial: SpatialConfig,\n  wx: number,\n  wy: number\n): TilePosition => {\n  const fx = (wx - spatial.originX) / spatial.tileWidth\n  const fy = (wy - spatial.originY) / spatial.tileHeight\n  const tileX = fx | 0\n  const tileY = fy | 0\n  return { tileX, tileY, fracX: fx - tileX, fracY: fy - tileY }\n}\n\n/**\n * Convenience: return the `TileInfo` for whatever tile a world-pixel position falls on.\n * Returns `null` when out of bounds.\n * @param map     The tile map.\n * @param spatial World-to-grid mapping config.\n * @param wx      World X in pixels.\n * @param wy      World Y in pixels.\n * @example\n * const tile = getTileAtWorld(map, spatial, entity.x, entity.y)\n * if (tile && tile.flags & TileFlags.HAZARD) takeDamage(entity)\n */\nexport const getTileAtWorld = <T>(\n  map: TileMap<T>,\n  spatial: SpatialConfig,\n  wx: number,\n  wy: number\n): TileInfo<T> | null => {\n  const tx = ((wx - spatial.originX) / spatial.tileWidth)  | 0\n  const ty = ((wy - spatial.originY) / spatial.tileHeight) | 0\n  return getTileInfo(map, tx, ty)\n}\n\n/**\n * Convenience: return the `TileInfo` for whatever tile a screen-pixel position falls on,\n * accounting for the camera offset and grid origin.\n * Returns `null` when out of bounds.\n * @param map     The tile map.\n * @param spatial World-to-grid mapping config.\n * @param cameraX Camera world X (scroll offset).\n * @param cameraY Camera world Y (scroll offset).\n * @param sx      Screen X in pixels.\n * @param sy      Screen Y in pixels.\n * @example\n * // Mouse click \u2192 tile lookup\n * const tile = getTileAtScreen(map, spatial, camera.x, camera.y, mouseX, mouseY)\n */\nexport const getTileAtScreen = <T>(\n  map: TileMap<T>,\n  spatial: SpatialConfig,\n  cameraX: number,\n  cameraY: number,\n  sx: number,\n  sy: number\n): TileInfo<T> | null => {\n  const tx = ((sx + cameraX - spatial.originX) / spatial.tileWidth)  | 0\n  const ty = ((sy + cameraY - spatial.originY) / spatial.tileHeight) | 0\n  return getTileInfo(map, tx, ty)\n}\n\n// --- default export ---\n\nexport default {\n  TileFlags,\n  createTileMap,\n  getTileIndex,\n  getTileInfo,\n  indexToCoords,\n  setFlag,\n  clearFlag,\n  toggleFlag,\n  hasFlag,\n  addEntity,\n  removeEntity,\n  moveEntity,\n  getEntitiesAt,\n  clearEntitiesAt,\n  getAdjacentIndices,\n  getAdjacentTiles,\n  getIndicesInRange,\n  getTilesInRange,\n  getEntitiesInRange,\n  validateTile,\n  validateRange,\n  createSpatialConfig,\n  worldToTile,\n  tileToWorld,\n  tileCenterWorld,\n  screenToWorld,\n  worldToScreen,\n  screenToTile,\n  tileToScreen,\n  worldToTileExact,\n  getTileAtWorld,\n  getTileAtScreen,\n}\n", "import * as s3 from './s3'\r\nexport * from './s3'\r\nimport JSONL from './jsonl'\r\nimport * as jsMisc from './misc-js-funcs'\r\nexport * from './misc-js-funcs'\r\nimport tileMap from './tile-map'\r\nexport * from './tile-map'\r\n\r\nexport {\r\n  s3,\r\n  JSONL,\r\n  tileMap\r\n}\r\n\r\nexport default {\r\n  s3,\r\n  JSONL,\r\n  tileMap,\r\n  utils: {\r\n    ...jsMisc\r\n  }\r\n}\r\n"],
+  "mappings": ";;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,SAAS,UAAU,kBAAkB,kBAAkB,sBAAiD,2BAA2B;AACnI,IAAI;AASG,IAAM,YAAY,CAAC,EAAE,QAAQ,aAAa,gBAAgB,MAAiB;AAChF,MAAI,CAAC,QAAQ;AACX,aAAS,IAAI,SAAS,EAAE,QAAQ,aAAa,EAAE,aAAa,gBAAgB,EAAE,CAAC;AAAA,EACjF;AAEA,SAAO;AACT;AAEO,IAAM,YAAY,OAAM,QAAmB,MAAuB,KAAa,gBAAyB;AAC7G,MAAI;AACF,UAAM,KAAK,UAAU,MAAM;AAE3B,UAAM,SAAuF;AAAA,MAC3F,QAAQ,OAAO;AAAA,MACf,KAAK;AAAA,MACL,MAAM,OAAO,SAAS,WAAW,OAAO,KAAK,MAAM,OAAO,IAAI;AAAA,IAChE;AACA,QAAG,aAAa;AACd,aAAO,cAAc;AAAA,IACvB;AAEA,WAAO,MAAM,GAAG,KAAK,IAAI,iBAAiB,MAAM,CAAC;AAAA,EACnD,SAAS,GAAG;AACV,YAAQ,MAAM,8BAA8B,EAAE,OAAO,EAAE,CAAC;AACxD,UAAM;AAAA,EACR;AACF;AAEO,IAAM,YAAY,OAAM,QAAmB,QAAgB;AAChE,QAAM,SAAS;AAAA,IACb,QAAQ,OAAO;AAAA,IACf,KAAK;AAAA,EACP;AAEA,MAAI;AACF,UAAM,KAAK,UAAU,MAAM;AAE3B,WAAO,MAAM,GAAG,KAAK,IAAI,iBAAiB,MAAM,CAAC;AAAA,EACnD,SAAS,GAAG;AACV,YAAQ,MAAM,gCAAgC,EAAE,OAAO,GAAG,OAAO,CAAC;AAClE,UAAM;AAAA,EACR;AACF;AAEO,IAAM,cAAc,OAAM,QAAmB,QAAgB,WAAoB;AACtF,QAAM,SAAoC;AAAA,IACxC,QAAQ,OAAO;AAAA,IACf,QAAQ;AAAA,EACV;AACA,MAAI,QAAQ;AACV,WAAO,aAAa;AAAA,EACtB;AACA,MAAI;AACF,UAAM,KAAK,UAAU,MAAM;AAE3B,UAAM,WAAW,MAAM,GAAG,KAAK,IAAI,qBAAqB,MAAM,CAAC;AAC/D,WAAO,EAAE,SAAU,SAAS,YAAY,CAAC,GAAI,QAAQ,SAAS,sBAAsB;AAAA,EACtF,SAAS,GAAG;AACV,YAAQ,MAAM,8BAA8B,EAAE,OAAO,EAAE,CAAC;AACxD,UAAM;AAAA,EACR;AACF;AAEO,IAAM,eAAe,OAAM,QAAmB,QAAgB;AACnE,QAAM,SAAS;AAAA,IACb,QAAQ,OAAO;AAAA,IACf;AAAA,EACF;AAEA,MAAI;AACF,UAAM,KAAK,UAAU,MAAM;AAE3B,WAAO,MAAM,GAAG,KAAK,IAAI,oBAAoB,MAAM,CAAC;AAAA,EACtD,SAAS,GAAG;AACV,YAAQ,MAAM,mCAAmC,EAAE,OAAO,GAAG,OAAO,CAAC;AACrE,UAAM;AAAA,EACR;AACF;;;ACxFA,SAAS,WAAW;AAMpB,IAAO,gBAAQ;AAAA,EACb,WAAW,CAAC,SAAwB;AAClC,WAAO,KAAK,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,EAAE,KAAK,GAAG;AAAA,EACpD;AAAA,EAEA,OAAO,CAAC,SAAwB;AAC9B,WAAO,KAAK,MAAM,GAAG,EAAE,IAAI,CAAC,GAAG,MAAM;AACnC,UAAG;AACD,eAAO,KAAK,MAAM,CAAC;AAAA,MACrB,SAAS,GAAQ;AACf,gBAAQ,MAAM,oCAAoC,GAAG,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;AAAA,MACpF;AAAA,IACF,CAAC;AAAA,EACH;AACF;;;ACpBA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAM,QAAQ,CAAC,OAAe,IAAI,QAAQ,aAAW,WAAW,SAAS,EAAE,CAAC;AAE5E,IAAM,aAAa,CAAC,QAAoB,YAAoB,OAAO;AACjE,QAAM,SAAS,OAAO,OAAO,CAAC,aAAa,MAAM,UAAU;AACzD,UAAM,aAAa,KAAK,MAAM,QAAM,SAAS;AAE7C,QAAG,CAAC,YAAY,UAAU,GAAG;AAC3B,kBAAY,UAAU,IAAI,CAAC;AAAA,IAC7B;AAEA,gBAAY,UAAU,EAAE,KAAK,IAAI;AAEjC,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AACL,SAAO;AACT;AAEA,IAAM,mBAAmB,CAAC,WAA6C;AACrE,QAAM,UAAU,OAAO,OAAO,CAAC,MAAM,EAAE,WAAW,WAAW;AAC7D,QAAM,WAAW,OAAO,OAAO,CAAC,MAAM,EAAE,WAAW,UAAU;AAC7D,SAAO,EAAE,SAAS,UAAU,OAAO,OAAO,OAAO;AACnD;AAEA,IAAM,aAAa,CAAC,OAAe;AACjC,MAAI,KAAK,IAAM,QAAO,GAAG,EAAE;AAC3B,MAAI,KAAK,IAAO,QAAO,IAAI,KAAK,KAAM,QAAQ,CAAC,CAAC;AAChD,MAAI,KAAK,KAAS,QAAO,IAAI,KAAK,KAAO,QAAQ,CAAC,CAAC;AACnD,SAAO,IAAI,KAAK,MAAS,QAAQ,CAAC,CAAC;AACrC;AAEA,IAAM,kBAAkB,CAAC,OAAe;AACtC,SAAO,WAAW,KAAK,IAAI,IAAI,EAAE;AACnC;AAEA,IAAM,uBAAuB,CAAC,SAAS,MAAM;AAC3C,SAAO,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,UAAU,GAAG,IAAI,MAAM;AAC3D;AAYA,IAAO,wBAAQ;AAAA,EACb;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;;;ACjBO,IAAM,YAAY;AAAA,EACvB,MAAY;AAAA,EACZ,SAAY;AAAA,EACZ,UAAY;AAAA,EACZ,SAAY;AAAA,EACZ,UAAY;AAAA,EACZ,OAAY;AAAA,EACZ,QAAY;AACd;AAIA,IAAM,OAAO,CAAC,OAAe,GAAW,MAAsB,IAAI,QAAQ;AAE1E,IAAM,YAAY,CAAC,OAAe,QAAgB,GAAW,MAC3D,KAAK,KAAK,IAAI,SAAS,KAAK,KAAK,IAAI;AAGvC,IAAM,YAAY,IAAI,UAAU,CAAC,IAAI,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC;AAC1D,IAAM,WAAY,IAAI,UAAU,CAAC,IAAI,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,IAAI,IAAI,IAAI,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC;AAc/E,IAAM,gBAAgB,CAAI,OAAe,YAAgC;AAAA,EAC9E;AAAA,EACA;AAAA,EACA,MAAM,QAAQ;AAAA,EACd,OAAO,IAAI,WAAW,QAAQ,MAAM;AAAA,EACpC,UAAU,oBAAI,IAAI;AACpB;AAWO,IAAM,eAAe,CAAC,KAAuB,GAAW,MAC7D,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,IAAI,KAAK,IAAI,OAAO,GAAG,CAAC,IAAI;AAS5D,IAAM,cAAc,CAAI,KAAiB,GAAW,MAAkC;AAC3F,MAAI,CAAC,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,QAAO;AACpD,QAAM,QAAQ,KAAK,IAAI,OAAO,GAAG,CAAC;AAClC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA,OAAO,IAAI,MAAM,KAAK;AAAA,IACtB,UAAU,IAAI,SAAS,IAAI,KAAK,KAAK,CAAC;AAAA,EACxC;AACF;AAOO,IAAM,gBAAgB,CAAC,KAAuB,WAA6C;AAAA,EAChG,GAAG,QAAQ,IAAI;AAAA,EACf,GAAI,QAAQ,IAAI,QAAS;AAC3B;AAcO,IAAM,UAAU,CAAC,KAAuB,GAAW,GAAW,SAAuB;AAC1F,MAAI,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,KAAI,MAAM,KAAK,IAAI,OAAO,GAAG,CAAC,CAAC,KAAK;AAClF;AAUO,IAAM,YAAY,CAAC,KAAuB,GAAW,GAAW,SAAuB;AAC5F,MAAI,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,KAAI,MAAM,KAAK,IAAI,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC;AACnF;AAUO,IAAM,aAAa,CAAC,KAAuB,GAAW,GAAW,SAAuB;AAC7F,MAAI,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,KAAI,MAAM,KAAK,IAAI,OAAO,GAAG,CAAC,CAAC,KAAK;AAClF;AAYO,IAAM,UAAU,CAAC,KAAuB,GAAW,GAAW,SAA0B;AAC7F,MAAI,CAAC,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,QAAO;AACpD,UAAQ,IAAI,MAAM,KAAK,IAAI,OAAO,GAAG,CAAC,CAAC,IAAI,UAAU;AACvD;AAYO,IAAM,YAAY,CAAI,KAAiB,GAAW,GAAW,WAAuB;AACzF,MAAI,CAAC,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,QAAO;AACpD,QAAM,QAAQ,KAAK,IAAI,OAAO,GAAG,CAAC;AAClC,QAAM,SAAS,IAAI,SAAS,IAAI,KAAK;AACrC,MAAI,OAAQ,QAAO,KAAK,MAAM;AAAA,MACzB,KAAI,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;AACrC,SAAO;AACT;AAYO,IAAM,eAAe,CAC1B,KACA,GACA,GACA,cACY;AACZ,MAAI,CAAC,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,QAAO;AACpD,QAAM,QAAQ,KAAK,IAAI,OAAO,GAAG,CAAC;AAClC,QAAM,SAAS,IAAI,SAAS,IAAI,KAAK;AACrC,MAAI,CAAC,OAAQ,QAAO;AACpB,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,QAAI,UAAU,OAAO,CAAC,CAAC,GAAG;AACxB,aAAO,OAAO,GAAG,CAAC;AAClB,UAAI,OAAO,WAAW,EAAG,KAAI,SAAS,OAAO,KAAK;AAClD,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAcO,IAAM,aAAa,CACxB,KACA,OACA,OACA,KACA,KACA,cACY;AACZ,QAAM,EAAE,OAAO,OAAO,IAAI;AAC1B,MAAI,CAAC,UAAU,OAAO,QAAQ,OAAO,KAAK,KAAK,CAAC,UAAU,OAAO,QAAQ,KAAK,GAAG,EAAG,QAAO;AAC3F,QAAM,WAAW,KAAK,OAAO,OAAO,KAAK;AACzC,QAAM,MAAM,IAAI,SAAS,IAAI,QAAQ;AACrC,MAAI,CAAC,IAAK,QAAO;AACjB,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,QAAI,UAAU,IAAI,CAAC,CAAC,GAAG;AACrB,YAAM,SAAS,IAAI,CAAC;AACpB,UAAI,OAAO,GAAG,CAAC;AACf,UAAI,IAAI,WAAW,EAAG,KAAI,SAAS,OAAO,QAAQ;AAClD,YAAM,WAAW,KAAK,OAAO,KAAK,GAAG;AACrC,YAAM,MAAM,IAAI,SAAS,IAAI,QAAQ;AACrC,UAAI,IAAK,KAAI,KAAK,MAAM;AAAA,UACnB,KAAI,SAAS,IAAI,UAAU,CAAC,MAAM,CAAC;AACxC,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AASO,IAAM,gBAAgB,CAAI,KAAiB,GAAW,MAAmB;AAC9E,MAAI,CAAC,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,QAAO,CAAC;AACrD,SAAO,IAAI,SAAS,IAAI,KAAK,IAAI,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC;AACrD;AASO,IAAM,kBAAkB,CAAI,KAAiB,GAAW,MAAoB;AACjF,MAAI,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,KAAI,SAAS,OAAO,KAAK,IAAI,OAAO,GAAG,CAAC,CAAC;AACvF;AAYO,IAAM,qBAAqB,CAChC,KACA,GACA,GACA,mBAAmB,UACN;AACb,QAAM,EAAE,OAAO,OAAO,IAAI;AAC1B,QAAM,UAAU,mBAAmB,WAAW;AAC9C,QAAM,SAAmB,CAAC;AAC1B,WAAS,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK,GAAG;AAC1C,UAAM,KAAK,IAAI,QAAQ,CAAC;AACxB,UAAM,KAAK,IAAI,QAAQ,IAAI,CAAC;AAC5B,QAAI,MAAM,KAAK,KAAK,SAAS,MAAM,KAAK,KAAK,OAAQ,QAAO,KAAK,KAAK,OAAO,IAAI,EAAE,CAAC;AAAA,EACtF;AACA,SAAO;AACT;AAUO,IAAM,mBAAmB,CAC9B,KACA,GACA,GACA,mBAAmB,UACD;AAClB,QAAM,EAAE,OAAO,OAAO,IAAI;AAC1B,QAAM,UAAU,mBAAmB,WAAW;AAC9C,QAAM,SAAwB,CAAC;AAC/B,WAAS,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK,GAAG;AAC1C,UAAM,KAAK,IAAI,QAAQ,CAAC;AACxB,UAAM,KAAK,IAAI,QAAQ,IAAI,CAAC;AAC5B,QAAI,MAAM,KAAK,KAAK,SAAS,MAAM,KAAK,KAAK,QAAQ;AACnD,YAAM,QAAQ,KAAK,OAAO,IAAI,EAAE;AAChC,aAAO,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,OAAO,IAAI,MAAM,KAAK,GAAG,UAAU,IAAI,SAAS,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;AAAA,IACvG;AAAA,EACF;AACA,SAAO;AACT;AAeO,IAAM,oBAAoB,CAC/B,KACA,GACA,GACA,OACA,QAAoB,UACpB,gBAAgB,UACH;AACb,QAAM,EAAE,OAAO,OAAO,IAAI;AAC1B,QAAM,KAAK,QAAQ;AACnB,QAAM,SAAmB,CAAC;AAC1B,WAAS,KAAK,CAAC,OAAO,MAAM,OAAO,MAAM;AACvC,UAAM,KAAK,IAAI;AACf,QAAI,KAAK,KAAK,MAAM,OAAQ;AAC5B,aAAS,KAAK,CAAC,OAAO,MAAM,OAAO,MAAM;AACvC,UAAI,CAAC,iBAAiB,OAAO,KAAK,OAAO,EAAG;AAC5C,UAAI,UAAU,YAAY,KAAK,KAAK,KAAK,KAAK,GAAI;AAClD,YAAM,KAAK,IAAI;AACf,UAAI,MAAM,KAAK,KAAK,MAAO,QAAO,KAAK,KAAK,OAAO,IAAI,EAAE,CAAC;AAAA,IAC5D;AAAA,EACF;AACA,SAAO;AACT;AAYO,IAAM,kBAAkB,CAC7B,KACA,GACA,GACA,OACA,QAAoB,UACpB,gBAAgB,UACE;AAClB,QAAM,EAAE,OAAO,OAAO,IAAI;AAC1B,QAAM,KAAK,QAAQ;AACnB,QAAM,SAAwB,CAAC;AAC/B,WAAS,KAAK,CAAC,OAAO,MAAM,OAAO,MAAM;AACvC,UAAM,KAAK,IAAI;AACf,QAAI,KAAK,KAAK,MAAM,OAAQ;AAC5B,aAAS,KAAK,CAAC,OAAO,MAAM,OAAO,MAAM;AACvC,UAAI,CAAC,iBAAiB,OAAO,KAAK,OAAO,EAAG;AAC5C,UAAI,UAAU,YAAY,KAAK,KAAK,KAAK,KAAK,GAAI;AAClD,YAAM,KAAK,IAAI;AACf,UAAI,MAAM,KAAK,KAAK,OAAO;AACzB,cAAM,QAAQ,KAAK,OAAO,IAAI,EAAE;AAChC,eAAO,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,OAAO,IAAI,MAAM,KAAK,GAAG,UAAU,IAAI,SAAS,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;AAAA,MACvG;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAeO,IAAM,qBAAqB,CAChC,KACA,GACA,GACA,OACA,QAAoB,UACpB,gBAAgB,UACR;AACR,QAAM,EAAE,OAAO,OAAO,IAAI;AAC1B,QAAM,KAAK,QAAQ;AACnB,QAAM,SAAc,CAAC;AACrB,WAAS,KAAK,CAAC,OAAO,MAAM,OAAO,MAAM;AACvC,UAAM,KAAK,IAAI;AACf,QAAI,KAAK,KAAK,MAAM,OAAQ;AAC5B,aAAS,KAAK,CAAC,OAAO,MAAM,OAAO,MAAM;AACvC,UAAI,CAAC,iBAAiB,OAAO,KAAK,OAAO,EAAG;AAC5C,UAAI,UAAU,YAAY,KAAK,KAAK,KAAK,KAAK,GAAI;AAClD,YAAM,KAAK,IAAI;AACf,UAAI,KAAK,KAAK,MAAM,MAAO;AAC3B,YAAM,SAAS,IAAI,SAAS,IAAI,KAAK,OAAO,IAAI,EAAE,CAAC;AACnD,UAAI,OAAQ,UAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,IAAK,QAAO,KAAK,OAAO,CAAC,CAAC;AAAA,IAC3E;AAAA,EACF;AACA,SAAO;AACT;AAcO,IAAM,eAAe,CAC1B,KACA,GACA,GACA,cACY;AACZ,MAAI,CAAC,UAAU,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC,EAAG,QAAO;AACpD,MAAI,CAAC,UAAW,QAAO;AACvB,QAAM,QAAQ,KAAK,IAAI,OAAO,GAAG,CAAC;AAClC,SAAO,UAAU,EAAE,OAAO,GAAG,GAAG,OAAO,IAAI,MAAM,KAAK,GAAG,UAAU,IAAI,SAAS,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;AACpG;AAgBO,IAAM,gBAAgB,CAC3B,KACA,GACA,GACA,OACA,WACA,QAAoB,UACpB,gBAAgB,UACJ;AACZ,QAAM,EAAE,OAAO,OAAO,IAAI;AAC1B,QAAM,KAAK,QAAQ;AACnB,WAAS,KAAK,CAAC,OAAO,MAAM,OAAO,MAAM;AACvC,UAAM,KAAK,IAAI;AACf,QAAI,KAAK,KAAK,MAAM,OAAQ;AAC5B,aAAS,KAAK,CAAC,OAAO,MAAM,OAAO,MAAM;AACvC,UAAI,CAAC,iBAAiB,OAAO,KAAK,OAAO,EAAG;AAC5C,UAAI,UAAU,YAAY,KAAK,KAAK,KAAK,KAAK,GAAI;AAClD,YAAM,KAAK,IAAI;AACf,UAAI,KAAK,KAAK,MAAM,MAAO;AAC3B,YAAM,QAAQ,KAAK,OAAO,IAAI,EAAE;AAChC,UAAI,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,OAAO,IAAI,MAAM,KAAK,GAAG,UAAU,IAAI,SAAS,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC,EAAG,QAAO;AAAA,IACpH;AAAA,EACF;AACA,SAAO;AACT;AA2CO,IAAM,sBAAsB,CACjC,WACA,YACA,UAAU,GACV,UAAU,OACS,EAAE,WAAW,YAAY,SAAS,QAAQ;AAUxD,IAAM,cAAc,CACzB,SACA,IACA,QAC8B;AAAA,EAC9B,IAAK,KAAK,QAAQ,WAAW,QAAQ,YAAc;AAAA,EACnD,IAAK,KAAK,QAAQ,WAAW,QAAQ,aAAc;AACrD;AAQO,IAAM,cAAc,CACzB,SACA,IACA,QAC8B;AAAA,EAC9B,GAAG,KAAK,QAAQ,YAAa,QAAQ;AAAA,EACrC,GAAG,KAAK,QAAQ,aAAa,QAAQ;AACvC;AASO,IAAM,kBAAkB,CAC7B,SACA,IACA,QAC8B;AAAA,EAC9B,GAAG,KAAK,QAAQ,YAAa,QAAQ,WAAW,QAAQ,aAAc;AAAA,EACtE,GAAG,KAAK,QAAQ,aAAa,QAAQ,WAAW,QAAQ,cAAc;AACxE;AAUO,IAAM,gBAAgB,CAC3B,SACA,SACA,IACA,QAC8B;AAAA,EAC9B,GAAG,KAAK;AAAA,EACR,GAAG,KAAK;AACV;AASO,IAAM,gBAAgB,CAC3B,SACA,SACA,IACA,QAC8B;AAAA,EAC9B,GAAG,KAAK;AAAA,EACR,GAAG,KAAK;AACV;AAWO,IAAM,eAAe,CAC1B,SACA,SACA,SACA,IACA,QAC8B;AAAA,EAC9B,IAAK,KAAK,UAAU,QAAQ,WAAW,QAAQ,YAAc;AAAA,EAC7D,IAAK,KAAK,UAAU,QAAQ,WAAW,QAAQ,aAAc;AAC/D;AAWO,IAAM,eAAe,CAC1B,SACA,SACA,SACA,IACA,QAC8B;AAAA,EAC9B,GAAG,KAAK,QAAQ,YAAa,QAAQ,UAAU;AAAA,EAC/C,GAAG,KAAK,QAAQ,aAAa,QAAQ,UAAU;AACjD;AAeO,IAAM,mBAAmB,CAC9B,SACA,IACA,OACiB;AACjB,QAAM,MAAM,KAAK,QAAQ,WAAW,QAAQ;AAC5C,QAAM,MAAM,KAAK,QAAQ,WAAW,QAAQ;AAC5C,QAAM,QAAQ,KAAK;AACnB,QAAM,QAAQ,KAAK;AACnB,SAAO,EAAE,OAAO,OAAO,OAAO,KAAK,OAAO,OAAO,KAAK,MAAM;AAC9D;AAaO,IAAM,iBAAiB,CAC5B,KACA,SACA,IACA,OACuB;AACvB,QAAM,MAAO,KAAK,QAAQ,WAAW,QAAQ,YAAc;AAC3D,QAAM,MAAO,KAAK,QAAQ,WAAW,QAAQ,aAAc;AAC3D,SAAO,YAAY,KAAK,IAAI,EAAE;AAChC;AAgBO,IAAM,kBAAkB,CAC7B,KACA,SACA,SACA,SACA,IACA,OACuB;AACvB,QAAM,MAAO,KAAK,UAAU,QAAQ,WAAW,QAAQ,YAAc;AACrE,QAAM,MAAO,KAAK,UAAU,QAAQ,WAAW,QAAQ,aAAc;AACrE,SAAO,YAAY,KAAK,IAAI,EAAE;AAChC;AAIA,IAAO,mBAAQ;AAAA,EACb;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;;;ACjxBA,IAAO,gBAAQ;AAAA,EACb;AAAA,EACA;AAAA,EACA;AAAA,EACA,OAAO;AAAA,IACL,GAAG;AAAA,EACL;AACF;",
+  "names": []
+}

package/dist/jsonl.d.ts

@@ -0,0 +1,8 @@
+/**
+ * made fairly specifically for arrays when dealing with larger qunatities of data that you may need to concat later
+ */
+declare const _default: {
+    stringify: (data: any[]) => string;
+    parse: (data: string) => any[];
+};
+export default _default;

package/dist/misc-js-funcs.d.ts

@@ -0,0 +1,24 @@
+declare const sleep: (ms: number) => Promise<unknown>;
+declare const chunkArray: (source: Array<any>, chunkSize?: number) => any;
+declare const settledSeparator: (result: Array<PromiseSettledResult<any>>) => {
+    settled: PromiseFulfilledResult<any>[];
+    rejected: PromiseRejectedResult[];
+    total: number;
+};
+declare const timeFormat: (ms: number) => string;
+declare const timeSinceString: (ms: number) => string;
+declare const generateRandomString: (length?: number) => string;
+export { sleep, chunkArray, settledSeparator, timeFormat, timeSinceString, generateRandomString };
+declare const _default: {
+    sleep: (ms: number) => Promise<unknown>;
+    chunkArray: (source: Array<any>, chunkSize?: number) => any;
+    settledSeparator: (result: Array<PromiseSettledResult<any>>) => {
+        settled: PromiseFulfilledResult<any>[];
+        rejected: PromiseRejectedResult[];
+        total: number;
+    };
+    timeFormat: (ms: number) => string;
+    timeSinceString: (ms: number) => string;
+    generateRandomString: (length?: number) => string;
+};
+export default _default;

package/dist/s3.d.ts

@@ -0,0 +1,15 @@
+import { S3Client } from "@aws-sdk/client-s3";
+export interface IS3Config {
+    region: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+export declare const getClient: ({ region, accessKeyId, secretAccessKey }: IS3Config) => S3Client;
+export declare const putObject: (config: IS3Config, data: Buffer | string, key: string, contentType?: string) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput>;
+export declare const getObject: (config: IS3Config, key: string) => Promise<import("@aws-sdk/client-s3").GetObjectCommandOutput>;
+export declare const listObjects: (config: IS3Config, prefix: string, Marker?: string) => Promise<{
+    Objects: import("@aws-sdk/client-s3")._Object[];
+    Marker: string | undefined;
+}>;
+export declare const deleteObject: (config: IS3Config, Key: string) => Promise<import("@aws-sdk/client-s3").DeleteObjectCommandOutput>;

package/dist/tile-map.d.ts

@@ -0,0 +1,475 @@
+/** A 2-D grid of tiles. `T` is the entity type stored per tile. */
+export type TileMap<T = unknown> = {
+    readonly width: number;
+    readonly height: number;
+    readonly size: number;
+    flags: Uint8Array;
+    entities: Map<number, T[]>;
+};
+/**
+ * A snapshot of a single tile's state.
+ * `index` is the flat array position (`y * width + x`).
+ */
+export type TileInfo<T> = {
+    readonly index: number;
+    readonly x: number;
+    readonly y: number;
+    flags: number;
+    entities: T[];
+};
+/** Shape used when collecting tiles or entities within a radius. */
+export type RangeShape = 'square' | 'circle';
+/** Return `true` to pass, `false` to fail. Used by `validateTile` and `validateRange`. */
+export type TileValidator<T> = (tile: TileInfo<T>) => boolean;
+/**
+ * Predefined single-bit flag constants.
+ * Combine multiple flags with the bitwise OR operator:
+ * ```ts
+ * setFlag(map, x, y, TileFlags.BLOCKED | TileFlags.HAZARD)
+ * ```
+ * You can define additional custom flags as any unused power-of-two number
+ * up to `0b10000000` (Uint8 supports 8 independent bits total).
+ */
+export declare const TileFlags: {
+    readonly NONE: 0;
+    readonly BLOCKED: 1;
+    readonly OCCUPIED: 2;
+    readonly VISIBLE: 4;
+    readonly EXPLORED: 8;
+    readonly WATER: 16;
+    readonly HAZARD: 32;
+};
+/**
+ * Create a new tile map of the given dimensions.
+ * All flags start at 0 and no entities are placed.
+ * @param width  Number of columns.
+ * @param height Number of rows.
+ * @returns A fresh `TileMap<T>`.
+ * @example
+ * type Unit = { id: string }
+ * const map = createTileMap<Unit>(64, 64)
+ */
+export declare const createTileMap: <T>(width: number, height: number) => TileMap<T>;
+/**
+ * Convert grid coordinates to a flat array index.
+ * Returns `-1` when the coordinates are out of bounds.
+ * @param map The tile map.
+ * @param x   Column.
+ * @param y   Row.
+ */
+export declare const getTileIndex: (map: TileMap<unknown>, x: number, y: number) => number;
+/**
+ * Return a `TileInfo` snapshot for the tile at `(x, y)`.
+ * Returns `null` when the coordinates are out of bounds.
+ * @param map The tile map.
+ * @param x   Column.
+ * @param y   Row.
+ */
+export declare const getTileInfo: <T>(map: TileMap<T>, x: number, y: number) => TileInfo<T> | null;
+/**
+ * Convert a flat array index back to `{ x, y }` grid coordinates.
+ * @param map   The tile map (used for its `width`).
+ * @param index Flat tile index.
+ */
+export declare const indexToCoords: (map: TileMap<unknown>, index: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Set one or more flags on a tile using bitwise OR.
+ * Out-of-bounds coordinates are silently ignored.
+ * @param map  The tile map.
+ * @param x    Column.
+ * @param y    Row.
+ * @param flag Flag bit(s) from `TileFlags` or a custom power-of-two constant.
+ * @example
+ * setFlag(map, 3, 5, TileFlags.BLOCKED)
+ */
+export declare const setFlag: (map: TileMap<unknown>, x: number, y: number, flag: number) => void;
+/**
+ * Clear one or more flags on a tile using bitwise AND NOT.
+ * Out-of-bounds coordinates are silently ignored.
+ * @param map  The tile map.
+ * @param x    Column.
+ * @param y    Row.
+ * @param flag Flag bit(s) to clear.
+ */
+export declare const clearFlag: (map: TileMap<unknown>, x: number, y: number, flag: number) => void;
+/**
+ * Toggle one or more flags on a tile using bitwise XOR.
+ * Out-of-bounds coordinates are silently ignored.
+ * @param map  The tile map.
+ * @param x    Column.
+ * @param y    Row.
+ * @param flag Flag bit(s) to toggle.
+ */
+export declare const toggleFlag: (map: TileMap<unknown>, x: number, y: number, flag: number) => void;
+/**
+ * Return `true` if **all** supplied flag bits are set on the tile.
+ * Returns `false` for out-of-bounds coordinates.
+ * @param map  The tile map.
+ * @param x    Column.
+ * @param y    Row.
+ * @param flag Flag bit(s) to test.
+ * @example
+ * if (hasFlag(map, x, y, TileFlags.BLOCKED)) { ... }
+ */
+export declare const hasFlag: (map: TileMap<unknown>, x: number, y: number, flag: number) => boolean;
+/**
+ * Add an entity to the tile at `(x, y)`.
+ * Returns `false` when the coordinates are out of bounds (entity is not added).
+ * @param map    The tile map.
+ * @param x      Column.
+ * @param y      Row.
+ * @param entity The entity to place on the tile.
+ */
+export declare const addEntity: <T>(map: TileMap<T>, x: number, y: number, entity: T) => boolean;
+/**
+ * Remove the **first** entity on the tile at `(x, y)` for which `predicate` returns `true`.
+ * Returns `false` when out of bounds or no matching entity is found.
+ * @param map       The tile map.
+ * @param x         Column.
+ * @param y         Row.
+ * @param predicate Selector — return `true` for the entity to remove.
+ * @example
+ * removeEntity(map, x, y, e => e.id === 'hero')
+ */
+export declare const removeEntity: <T>(map: TileMap<T>, x: number, y: number, predicate: (e: T) => boolean) => boolean;
+/**
+ * Atomically move the **first** matching entity from one tile to another.
+ * Returns `false` when either coordinate is out of bounds or no matching entity is found.
+ * @param map       The tile map.
+ * @param fromX     Source column.
+ * @param fromY     Source row.
+ * @param toX       Destination column.
+ * @param toY       Destination row.
+ * @param predicate Selector — return `true` for the entity to move.
+ * @example
+ * moveEntity(map, 2, 3, 2, 4, e => e.id === 'hero')
+ */
+export declare const moveEntity: <T>(map: TileMap<T>, fromX: number, fromY: number, toX: number, toY: number, predicate: (e: T) => boolean) => boolean;
+/**
+ * Return all entities on the tile at `(x, y)`.
+ * Returns an empty array for out-of-bounds coordinates or tiles with no entities.
+ * @param map The tile map.
+ * @param x   Column.
+ * @param y   Row.
+ */
+export declare const getEntitiesAt: <T>(map: TileMap<T>, x: number, y: number) => T[];
+/**
+ * Remove all entities from the tile at `(x, y)`.
+ * Out-of-bounds coordinates are silently ignored.
+ * @param map The tile map.
+ * @param x   Column.
+ * @param y   Row.
+ */
+export declare const clearEntitiesAt: <T>(map: TileMap<T>, x: number, y: number) => void;
+/**
+ * Return the flat indices of tiles adjacent to `(x, y)`.
+ * Only in-bounds neighbours are included.
+ * @param map              The tile map.
+ * @param x                Column.
+ * @param y                Row.
+ * @param includeDiagonals When `true`, returns up to 8 neighbours; otherwise up to 4 (cardinal only).
+ */
+export declare const getAdjacentIndices: (map: TileMap<unknown>, x: number, y: number, includeDiagonals?: boolean) => number[];
+/**
+ * Return full `TileInfo` snapshots for all tiles adjacent to `(x, y)`.
+ * Only in-bounds neighbours are included.
+ * @param map              The tile map.
+ * @param x                Column.
+ * @param y                Row.
+ * @param includeDiagonals When `true`, returns up to 8 neighbours; otherwise up to 4 (cardinal only).
+ */
+export declare const getAdjacentTiles: <T>(map: TileMap<T>, x: number, y: number, includeDiagonals?: boolean) => TileInfo<T>[];
+/**
+ * Return the flat indices of all tiles within `range` of `(x, y)`.
+ * The origin tile is excluded unless `includeOrigin` is `true`.
+ * Circle shape uses integer `dx² + dy² ≤ range²` — no `Math.sqrt`.
+ * @param map           The tile map.
+ * @param x             Center column.
+ * @param y             Center row.
+ * @param range         Radius in tiles.
+ * @param shape         `'square'` (default) or `'circle'`.
+ * @param includeOrigin Include the center tile itself (default `false`).
+ */
+export declare const getIndicesInRange: (map: TileMap<unknown>, x: number, y: number, range: number, shape?: RangeShape, includeOrigin?: boolean) => number[];
+/**
+ * Return full `TileInfo` snapshots for all tiles within `range` of `(x, y)`.
+ * The origin tile is excluded unless `includeOrigin` is `true`.
+ * @param map           The tile map.
+ * @param x             Center column.
+ * @param y             Center row.
+ * @param range         Radius in tiles.
+ * @param shape         `'square'` (default) or `'circle'`.
+ * @param includeOrigin Include the center tile itself (default `false`).
+ */
+export declare const getTilesInRange: <T>(map: TileMap<T>, x: number, y: number, range: number, shape?: RangeShape, includeOrigin?: boolean) => TileInfo<T>[];
+/**
+ * Collect and return every entity on every tile within `range` of `(x, y)`.
+ * The origin tile is excluded unless `includeOrigin` is `true`.
+ * Tiles with no entities contribute nothing to the result.
+ * @param map           The tile map.
+ * @param x             Center column.
+ * @param y             Center row.
+ * @param range         Radius in tiles.
+ * @param shape         `'square'` (default) or `'circle'`.
+ * @param includeOrigin Include entities on the center tile itself (default `false`).
+ * @example
+ * const enemies = getEntitiesInRange(map, heroX, heroY, 3, 'circle')
+ */
+export declare const getEntitiesInRange: <T>(map: TileMap<T>, x: number, y: number, range: number, shape?: RangeShape, includeOrigin?: boolean) => T[];
+/**
+ * Test whether the tile at `(x, y)` is in bounds and passes an optional validator.
+ * When no `validator` is provided, returns `true` for any in-bounds coordinate.
+ * @param map       The tile map.
+ * @param x         Column.
+ * @param y         Row.
+ * @param validator Optional predicate; receives a `TileInfo` snapshot.
+ * @example
+ * const passable = validateTile(map, x, y, t => !(t.flags & TileFlags.BLOCKED))
+ */
+export declare const validateTile: <T>(map: TileMap<T>, x: number, y: number, validator?: TileValidator<T>) => boolean;
+/**
+ * Test whether **every** tile within `range` of `(x, y)` passes `validator`.
+ * Short-circuits on the first failing tile. Out-of-bounds tiles are skipped entirely.
+ * The origin tile is excluded unless `includeOrigin` is `true`.
+ * @param map           The tile map.
+ * @param x             Center column.
+ * @param y             Center row.
+ * @param range         Radius in tiles.
+ * @param validator     Predicate; receives a `TileInfo` snapshot.
+ * @param shape         `'square'` (default) or `'circle'`.
+ * @param includeOrigin Include the center tile in validation (default `false`).
+ * @example
+ * const areaClear = validateRange(map, x, y, 2, t => t.entities.length === 0)
+ */
+export declare const validateRange: <T>(map: TileMap<T>, x: number, y: number, range: number, validator: TileValidator<T>, shape?: RangeShape, includeOrigin?: boolean) => boolean;
+/**
+ * Pixel dimensions of a single tile and an optional world-space origin offset.
+ * Create once and reuse; it never mutates.
+ *
+ * - `tileWidth` / `tileHeight`: pixels per tile (e.g. 32 for a 32×32 sprite sheet).
+ * - `originX` / `originY`: world-pixel offset of tile (0, 0)'s top-left corner.
+ *   Use this to add margins or align the grid inside a larger world.
+ *
+ * Non-square tiles (e.g. 64×32 isometric projections) are fully supported.
+ */
+export type SpatialConfig = {
+    readonly tileWidth: number;
+    readonly tileHeight: number;
+    readonly originX: number;
+    readonly originY: number;
+};
+/**
+ * Fractional tile-grid position for an entity at an arbitrary world coordinate.
+ * `tileX` / `tileY` are the integer grid cell; `fracX` / `fracY` are 0..1 offsets
+ * within that cell — useful for smooth movement interpolation and collision checks.
+ */
+export type TilePosition = {
+    tileX: number;
+    tileY: number;
+    fracX: number;
+    fracY: number;
+};
+/**
+ * Create a `SpatialConfig`.
+ * @param tileWidth  Pixels per tile column.
+ * @param tileHeight Pixels per tile row.
+ * @param originX    World-pixel X of the grid's top-left corner (default `0`).
+ * @param originY    World-pixel Y of the grid's top-left corner (default `0`).
+ * @example
+ * const spatial = createSpatialConfig(32, 32)
+ * const spatial = createSpatialConfig(64, 32, 128, 64) // offset grid
+ */
+export declare const createSpatialConfig: (tileWidth: number, tileHeight: number, originX?: number, originY?: number) => SpatialConfig;
+/**
+ * Convert world-pixel coordinates to integer tile grid coordinates.
+ * Fractions are floored, so the result is always the tile the point falls inside.
+ * Returns `{ x: -1, y: -1 }` when the world position is before the grid origin.
+ * @param spatial World-to-grid mapping config.
+ * @param wx      World X in pixels.
+ * @param wy      World Y in pixels.
+ */
+export declare const worldToTile: (spatial: SpatialConfig, wx: number, wy: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Convert tile grid coordinates to the world-pixel position of the tile's **top-left corner**.
+ * @param spatial World-to-grid mapping config.
+ * @param tx      Tile column.
+ * @param ty      Tile row.
+ */
+export declare const tileToWorld: (spatial: SpatialConfig, tx: number, ty: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Convert tile grid coordinates to the world-pixel position of the tile's **center**.
+ * Useful for placing sprites, projectile origins, or distance calculations.
+ * @param spatial World-to-grid mapping config.
+ * @param tx      Tile column.
+ * @param ty      Tile row.
+ */
+export declare const tileCenterWorld: (spatial: SpatialConfig, tx: number, ty: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Convert screen-pixel coordinates to world-pixel coordinates using the camera offset.
+ * The camera position is the world-space coordinate of the screen's top-left corner.
+ * @param cameraX Camera world X (scroll offset).
+ * @param cameraY Camera world Y (scroll offset).
+ * @param sx      Screen X in pixels.
+ * @param sy      Screen Y in pixels.
+ */
+export declare const screenToWorld: (cameraX: number, cameraY: number, sx: number, sy: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Convert world-pixel coordinates to screen-pixel coordinates using the camera offset.
+ * @param cameraX Camera world X (scroll offset).
+ * @param cameraY Camera world Y (scroll offset).
+ * @param wx      World X in pixels.
+ * @param wy      World Y in pixels.
+ */
+export declare const worldToScreen: (cameraX: number, cameraY: number, wx: number, wy: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Convert screen-pixel coordinates directly to tile grid coordinates,
+ * accounting for both the camera offset and the grid origin.
+ * @param spatial World-to-grid mapping config.
+ * @param cameraX Camera world X (scroll offset).
+ * @param cameraY Camera world Y (scroll offset).
+ * @param sx      Screen X in pixels.
+ * @param sy      Screen Y in pixels.
+ */
+export declare const screenToTile: (spatial: SpatialConfig, cameraX: number, cameraY: number, sx: number, sy: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Convert tile grid coordinates to screen-pixel coordinates (top-left of the tile),
+ * accounting for the camera offset and grid origin.
+ * @param spatial World-to-grid mapping config.
+ * @param cameraX Camera world X (scroll offset).
+ * @param cameraY Camera world Y (scroll offset).
+ * @param tx      Tile column.
+ * @param ty      Tile row.
+ */
+export declare const tileToScreen: (spatial: SpatialConfig, cameraX: number, cameraY: number, tx: number, ty: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Return the exact fractional tile-grid position for a world coordinate.
+ * `tileX` / `tileY` are the integer grid cell the point is inside.
+ * `fracX` / `fracY` are 0..1 fractions representing how far into the tile the point is —
+ * essential for smooth cross-tile movement, linear interpolation animations, and sub-tile collision.
+ * @param spatial World-to-grid mapping config.
+ * @param wx      World X in pixels.
+ * @param wy      World Y in pixels.
+ * @example
+ * // Entity smoothly walking; determine which tile it's in and how far across
+ * const pos = worldToTileExact(spatial, entity.x, entity.y)
+ * // pos.fracX === 0.5 means entity is horizontally centred in its tile
+ */
+export declare const worldToTileExact: (spatial: SpatialConfig, wx: number, wy: number) => TilePosition;
+/**
+ * Convenience: return the `TileInfo` for whatever tile a world-pixel position falls on.
+ * Returns `null` when out of bounds.
+ * @param map     The tile map.
+ * @param spatial World-to-grid mapping config.
+ * @param wx      World X in pixels.
+ * @param wy      World Y in pixels.
+ * @example
+ * const tile = getTileAtWorld(map, spatial, entity.x, entity.y)
+ * if (tile && tile.flags & TileFlags.HAZARD) takeDamage(entity)
+ */
+export declare const getTileAtWorld: <T>(map: TileMap<T>, spatial: SpatialConfig, wx: number, wy: number) => TileInfo<T> | null;
+/**
+ * Convenience: return the `TileInfo` for whatever tile a screen-pixel position falls on,
+ * accounting for the camera offset and grid origin.
+ * Returns `null` when out of bounds.
+ * @param map     The tile map.
+ * @param spatial World-to-grid mapping config.
+ * @param cameraX Camera world X (scroll offset).
+ * @param cameraY Camera world Y (scroll offset).
+ * @param sx      Screen X in pixels.
+ * @param sy      Screen Y in pixels.
+ * @example
+ * // Mouse click → tile lookup
+ * const tile = getTileAtScreen(map, spatial, camera.x, camera.y, mouseX, mouseY)
+ */
+export declare const getTileAtScreen: <T>(map: TileMap<T>, spatial: SpatialConfig, cameraX: number, cameraY: number, sx: number, sy: number) => TileInfo<T> | null;
+declare const _default: {
+    TileFlags: {
+        readonly NONE: 0;
+        readonly BLOCKED: 1;
+        readonly OCCUPIED: 2;
+        readonly VISIBLE: 4;
+        readonly EXPLORED: 8;
+        readonly WATER: 16;
+        readonly HAZARD: 32;
+    };
+    createTileMap: <T>(width: number, height: number) => TileMap<T>;
+    getTileIndex: (map: TileMap<unknown>, x: number, y: number) => number;
+    getTileInfo: <T>(map: TileMap<T>, x: number, y: number) => TileInfo<T> | null;
+    indexToCoords: (map: TileMap<unknown>, index: number) => {
+        x: number;
+        y: number;
+    };
+    setFlag: (map: TileMap<unknown>, x: number, y: number, flag: number) => void;
+    clearFlag: (map: TileMap<unknown>, x: number, y: number, flag: number) => void;
+    toggleFlag: (map: TileMap<unknown>, x: number, y: number, flag: number) => void;
+    hasFlag: (map: TileMap<unknown>, x: number, y: number, flag: number) => boolean;
+    addEntity: <T>(map: TileMap<T>, x: number, y: number, entity: T) => boolean;
+    removeEntity: <T>(map: TileMap<T>, x: number, y: number, predicate: (e: T) => boolean) => boolean;
+    moveEntity: <T>(map: TileMap<T>, fromX: number, fromY: number, toX: number, toY: number, predicate: (e: T) => boolean) => boolean;
+    getEntitiesAt: <T>(map: TileMap<T>, x: number, y: number) => T[];
+    clearEntitiesAt: <T>(map: TileMap<T>, x: number, y: number) => void;
+    getAdjacentIndices: (map: TileMap<unknown>, x: number, y: number, includeDiagonals?: boolean) => number[];
+    getAdjacentTiles: <T>(map: TileMap<T>, x: number, y: number, includeDiagonals?: boolean) => TileInfo<T>[];
+    getIndicesInRange: (map: TileMap<unknown>, x: number, y: number, range: number, shape?: RangeShape, includeOrigin?: boolean) => number[];
+    getTilesInRange: <T>(map: TileMap<T>, x: number, y: number, range: number, shape?: RangeShape, includeOrigin?: boolean) => TileInfo<T>[];
+    getEntitiesInRange: <T>(map: TileMap<T>, x: number, y: number, range: number, shape?: RangeShape, includeOrigin?: boolean) => T[];
+    validateTile: <T>(map: TileMap<T>, x: number, y: number, validator?: TileValidator<T>) => boolean;
+    validateRange: <T>(map: TileMap<T>, x: number, y: number, range: number, validator: TileValidator<T>, shape?: RangeShape, includeOrigin?: boolean) => boolean;
+    createSpatialConfig: (tileWidth: number, tileHeight: number, originX?: number, originY?: number) => SpatialConfig;
+    worldToTile: (spatial: SpatialConfig, wx: number, wy: number) => {
+        x: number;
+        y: number;
+    };
+    tileToWorld: (spatial: SpatialConfig, tx: number, ty: number) => {
+        x: number;
+        y: number;
+    };
+    tileCenterWorld: (spatial: SpatialConfig, tx: number, ty: number) => {
+        x: number;
+        y: number;
+    };
+    screenToWorld: (cameraX: number, cameraY: number, sx: number, sy: number) => {
+        x: number;
+        y: number;
+    };
+    worldToScreen: (cameraX: number, cameraY: number, wx: number, wy: number) => {
+        x: number;
+        y: number;
+    };
+    screenToTile: (spatial: SpatialConfig, cameraX: number, cameraY: number, sx: number, sy: number) => {
+        x: number;
+        y: number;
+    };
+    tileToScreen: (spatial: SpatialConfig, cameraX: number, cameraY: number, tx: number, ty: number) => {
+        x: number;
+        y: number;
+    };
+    worldToTileExact: (spatial: SpatialConfig, wx: number, wy: number) => TilePosition;
+    getTileAtWorld: <T>(map: TileMap<T>, spatial: SpatialConfig, wx: number, wy: number) => TileInfo<T> | null;
+    getTileAtScreen: <T>(map: TileMap<T>, spatial: SpatialConfig, cameraX: number, cameraY: number, sx: number, sy: number) => TileInfo<T> | null;
+};
+export default _default;