rn-gamekit 0.1.0 → 0.2.1

package/src/tilemap/movement.ts

@@ -0,0 +1,368 @@
+
+import type {
+  PlatformerContact2D,
+  PlatformerMoveResult2D,
+  TileCell2D,
+  TileMap2D,
+} from './types';
+import { cellsInAabb, cellsInSweptBounds } from './queries';
+import { tileError } from './errors';
+import type { Aabb2D, Vector2D } from '../geometry/types';
+import { assertValidAabb2D, assertValidVector2D } from '../geometry/validation';
+
+/** Frozen v1 movement semantics (T16.0). */
+export const PLATFORMER_MAX_ITERATIONS = 4;
+export const PLATFORMER_SKIN = 1e-6;
+/** Previous-bottom must be at or above the platform top by this tolerance. */
+export const ONE_WAY_TOLERANCE = 1e-4;
+
+export interface PlatformerMoveOptions2D {
+  /** Explicit per-call drop-through intent; the helper owns no timer. */
+  readonly dropThroughOneWay?: boolean;
+  /**
+   * Snap downward onto floor tops within this many world units when the
+   * body ends the step falling or resting and no floor contact was resolved.
+   * Default 0 (disabled).
+   */
+  readonly floorSnapDistance?: number;
+}
+
+function isSolid(kind: string | undefined): boolean {
+  return kind === 'solid';
+}
+
+function isOneWay(kind: string | undefined): boolean {
+  return kind === 'one-way-up';
+}
+
+function overlaps(a: Aabb2D, b: Aabb2D): boolean {
+  return (
+    a.x < b.x + b.width && a.x + a.width > b.x &&
+    a.y < b.y + b.height && a.y + a.height > b.y
+  );
+}
+
+/**
+ * Pure fixed-step AABB platformer movement (T16.3, T16-F5).
+ *
+ * Frozen semantics:
+ * - Axis order X then Y.
+ * - Solid tiles block both axes; one-way tiles block descent only when the
+ *   previous bottom was at/above the platform top (ONE_WAY_TOLERANCE) and
+ *   `dropThroughOneWay` is not set.
+ * - Starting overlap resolves along the least-penetration face preferring UP
+ *   on ties (up = negative y in y-down space), up to PLATFORMER_MAX_ITERATIONS;
+ *   unresolved spawn overlap throws deterministically. The reported contact is
+ *   always the tile that supplied the winning face.
+ * - Each axis resolves against the NEAREST blocking plane and reports contacts
+ *   ONLY for tiles touching that winning plane — farther crossed rows/columns
+ *   are never reported.
+ * - Floor snap pulls a falling/resting body down onto tops within
+ *   `floorSnapDistance`.
+ * - Candidate order is layer order then row-major cell order; equal physical
+ *   candidates preserve that deterministic order.
+ *
+ * Displacement contract (GS-TILE-03): `displacement` reports requested-motion
+ * resolution only — starting-overlap recovery moves the body and reports its
+ * contact, but never contributes to displacement. The caller's body object is
+ * never mutated or frozen; every returned body/contact/normal is an owned
+ * frozen value.
+ */
+export function movePlatformerBody2D(options: {
+  readonly body: Aabb2D;
+  readonly velocity: Vector2D;
+  readonly deltaSeconds: number;
+  readonly map: TileMap2D;
+  /** Layer ids that contribute collision; others render only. */
+  readonly collisionLayers: readonly string[];
+} & PlatformerMoveOptions2D): PlatformerMoveResult2D {
+  const { map, deltaSeconds, collisionLayers } = options;
+  // GS-TILE-03: validate author inputs once at the public boundary, and
+  // copy the body — the caller's object is never mutated or frozen.
+  assertValidAabb2D(options.body, 'body');
+  assertValidVector2D(options.velocity, 'velocity');
+  let body: Aabb2D = { ...options.body };
+  let vx = options.velocity.x;
+  let vy = options.velocity.y;
+  if (!Number.isFinite(deltaSeconds) || deltaSeconds < 0) {
+    throw tileError('deltaSeconds', `must be a finite number >= 0; got ${String(deltaSeconds)}`);
+  }
+  const dropThrough = options.dropThroughOneWay ?? false;
+  if (typeof dropThrough !== 'boolean') {
+    throw tileError('dropThroughOneWay', `must be a boolean or omitted; got ${String(options.dropThroughOneWay)}`);
+  }
+  const snapDistance = options.floorSnapDistance ?? 0;
+  if (typeof snapDistance !== 'number' || !Number.isFinite(snapDistance) || snapDistance < 0) {
+    throw tileError('floorSnapDistance', `must be a finite number >= 0 or omitted; got ${String(options.floorSnapDistance)}`);
+  }
+  // GS-TILE-02: layer selection is explicit and exact — unknown ids fail
+  // here instead of silently colliding with nothing (a typo would otherwise
+  // drop the player through the world). Duplicates are harmless: queries
+  // iterate map layers, so an id can never report twice.
+  if (!Array.isArray(collisionLayers)) {
+    throw tileError('collisionLayers', `must be an array of layer ids; got ${String(collisionLayers)}`);
+  }
+  for (const layerId of collisionLayers) {
+    if (typeof layerId !== 'string' || map.layerById[layerId] === undefined) {
+      throw tileError('collisionLayers', `unknown collision layer ${JSON.stringify(layerId)}`);
+    }
+  }
+  const intendedX = vx * deltaSeconds;
+  const intendedY = vy * deltaSeconds;
+
+  const contacts: PlatformerContact2D[] = [];
+  let appliedX = 0;
+  let appliedY = 0;
+
+  /** Report one owned frozen contact (GS-TILE-03: nested values immutable). */
+  const report = (cell: TileCell2D, normal: { x: number; y: number }): void => {
+    contacts.push(
+      Object.freeze({ cell, normal: Object.freeze({ ...normal }) }),
+    );
+  };
+
+  // --- Starting-overlap recovery ---
+  // Track the winning tile TOGETHER with its face so the reported contact
+  // always names the tile that supplied the resolved plane (T16-F5).
+  for (let iter = 0; iter < PLATFORMER_MAX_ITERATIONS; iter++) {
+    const overlapping = cellsInAabb(map, body, collisionLayers)
+      .filter((c) => isSolid(c.collision) && overlaps(body, c.aabb));
+    if (overlapping.length === 0) break;
+    // Least-penetration FACE wins; ties prefer pushing UP (negative y).
+    let bestAxis: 'x' | 'y' = 'y';
+    let bestSign = -1;
+    let bestDepth = Number.POSITIVE_INFINITY;
+    let bestCell: TileCell2D | undefined;
+    const consider = (axis: 'x' | 'y', sign: number, depth: number, cell: TileCell2D): void => {
+      // Deterministic tie rule: prefer y over x, and prefer negative-y (up)
+      // over positive-y. Otherwise first-evaluated (row-major) wins.
+      const better =
+        depth < bestDepth ||
+        (depth === bestDepth &&
+          (axis === 'y' ? bestAxis !== 'y' || sign === -1 : false));
+      if (better) {
+        bestAxis = axis;
+        bestSign = sign;
+        bestDepth = depth;
+        bestCell = cell;
+      }
+    };
+    for (const c of overlapping) {
+      const pushLeft = (c.aabb.x - body.width) - body.x;
+      const pushRight = (c.aabb.x + c.aabb.width) - body.x;
+      const pushUp = c.aabb.y - body.height - body.y;
+      const pushDown = (c.aabb.y + c.aabb.height) - body.y;
+      consider('x', -1, Math.abs(pushLeft), c);
+      consider('x', 1, Math.abs(pushRight), c);
+      consider('y', -1, Math.abs(pushUp), c);
+      consider('y', 1, Math.abs(pushDown), c);
+    }
+    if (bestCell === undefined) break;
+    // Closure mutation defeats TS narrowing here; assert the union.
+    const axis = bestAxis as 'x' | 'y';
+    body =
+      axis === 'x'
+        ? { ...body, x: body.x + bestSign * bestDepth }
+        : { ...body, y: body.y + bestSign * bestDepth };
+    // Negative-y push lands the body ON a tile top (floor); positive-y hits
+    // a ceiling. The contact names the winning tile.
+    if (axis === 'y') {
+      report(bestCell, { x: 0, y: bestSign });
+      vy = 0;
+    } else {
+      report(bestCell, { x: bestSign, y: 0 });
+      vx = 0;
+    }
+  }
+  // Final check: unresolved spawn overlap is a deterministic error.
+  const stillOverlapping = cellsInAabb(map, body, collisionLayers).some(
+    (c) => isSolid(c.collision) && overlaps(body, c.aabb),
+  );
+  if (stillOverlapping) {
+    throw tileError('body', 'starting overlap could not be resolved within PLATFORMER_MAX_ITERATIONS');
+  }
+
+  const prevBottom = body.y + body.height;
+  // --- X axis sweep ---
+  {
+    const dx = intendedX;
+    if (dx !== 0) {
+      const newX = body.x + dx;
+      let clamped = newX;
+      const yOverlap = (aabb: Aabb2D): boolean =>
+        body.y < aabb.y + aabb.height && body.y + body.height > aabb.y;
+      const solids = cellsInSweptBounds(map, body, { x: dx, y: 0 }, collisionLayers)
+        .filter((c) => isSolid(c.collision));
+      // Phase 1: resolve against the NEAREST blocking plane only.
+      if (dx > 0) {
+        let planeX = Number.POSITIVE_INFINITY;
+        for (const c of solids) {
+          if (!yOverlap(c.aabb)) continue;
+          if (body.x + body.width > c.aabb.x + PLATFORMER_SKIN) continue;
+          if (c.aabb.x < planeX) planeX = c.aabb.x;
+        }
+        if (planeX !== Number.POSITIVE_INFINITY) {
+          clamped = Math.min(clamped, planeX - body.width);
+          // Phase 2: emit contacts ONLY for tiles touching the winning plane.
+          for (const c of solids) {
+            if (!yOverlap(c.aabb)) continue;
+            if (Math.abs(c.aabb.x - planeX) > PLATFORMER_SKIN) continue;
+            report(c, { x: -1, y: 0 });
+          }
+        }
+      } else {
+        let planeX = Number.NEGATIVE_INFINITY;
+        for (const c of solids) {
+          if (!yOverlap(c.aabb)) continue;
+          if (body.x < c.aabb.x + c.aabb.width - PLATFORMER_SKIN) continue;
+          if (c.aabb.x + c.aabb.width > planeX) planeX = c.aabb.x + c.aabb.width;
+        }
+        if (planeX !== Number.NEGATIVE_INFINITY) {
+          clamped = Math.max(clamped, planeX);
+          for (const c of solids) {
+            if (!yOverlap(c.aabb)) continue;
+            if (Math.abs(c.aabb.x + c.aabb.width - planeX) > PLATFORMER_SKIN) continue;
+            report(c, { x: 1, y: 0 });
+          }
+        }
+      }
+      if (clamped !== newX) vx = 0;
+      appliedX = clamped - body.x;
+      body = { ...body, x: clamped };
+    }
+  }
+  // --- Y axis sweep ---
+  {
+    const dy = intendedY;
+    if (dy !== 0) {
+      const newY = body.y + dy;
+      let clamped = newY;
+      const prevBottomY = body.y + body.height;
+      const prevTop = body.y;
+      const xOverlap = (aabb: Aabb2D): boolean =>
+        body.x < aabb.x + aabb.width && body.x + body.width > aabb.x;
+      const candidates = cellsInSweptBounds(map, body, { x: 0, y: dy }, collisionLayers);
+      interface FloorCandidate { cell: TileCell2D }
+      const floors: FloorCandidate[] = [];
+      const ceilings: TileCell2D[] = [];
+      for (const c of candidates) {
+        const solid = isSolid(c.collision);
+        const oneWay = isOneWay(c.collision);
+        if (!solid && !oneWay) continue;
+        if (!xOverlap(c.aabb)) continue;
+        if (dy > 0) {
+          // Descending: floor candidate.
+          if (oneWay && (dropThrough || prevBottomY > c.aabb.y + ONE_WAY_TOLERANCE)) continue;
+          // Swept crossing: started above/on the top and reached past it.
+          if (prevBottomY <= c.aabb.y + PLATFORMER_SKIN && newY + body.height >= c.aabb.y) {
+            floors.push({ cell: c });
+          }
+        } else {
+          // Ascending: only solids block ceilings.
+          if (!solid) continue;
+          if (
+            prevTop >= c.aabb.y + c.aabb.height - PLATFORMER_SKIN &&
+            newY <= c.aabb.y + c.aabb.height
+          ) {
+            ceilings.push(c);
+          }
+        }
+      }
+      if (dy > 0 && floors.length > 0) {
+        // Nearest plane wins; report only tiles touching it.
+        let planeY = Number.POSITIVE_INFINITY;
+        for (const f of floors) {
+          if (f.cell.aabb.y < planeY) planeY = f.cell.aabb.y;
+        }
+        clamped = Math.min(clamped, planeY - body.height);
+        for (const f of floors) {
+          if (f.cell.aabb.y !== planeY) continue;
+          report(f.cell, { x: 0, y: -1 });
+        }
+      } else if (dy < 0 && ceilings.length > 0) {
+        let planeBottom = Number.NEGATIVE_INFINITY;
+        for (const c of ceilings) {
+          if (c.aabb.y + c.aabb.height > planeBottom) planeBottom = c.aabb.y + c.aabb.height;
+        }
+        clamped = Math.max(clamped, planeBottom);
+        for (const c of ceilings) {
+          if (Math.abs(c.aabb.y + c.aabb.height - planeBottom) > PLATFORMER_SKIN) continue;
+          report(c, { x: 0, y: 1 });
+        }
+      }
+      if (clamped !== newY) vy = 0;
+      appliedY = clamped - body.y;
+      body = { ...body, y: clamped };
+    }
+  }
+
+  // --- Floor snap ---
+  // GS-TILE-03: drop-through suppresses one-way floors without disabling
+  // snap onto solid floors.
+  {
+    const hasFloor = contacts.some((c) => c.normal.y === -1);
+    if (!hasFloor && vy >= 0 && snapDistance > 0) {
+      const probeBottom = body.y + body.height + snapDistance;
+      const probe: Aabb2D = { x: body.x, y: body.y + body.height, width: body.width, height: snapDistance };
+      const near = cellsInAabb(map, probe, collisionLayers);
+      let bestTop = Number.POSITIVE_INFINITY;
+      let bestCell: TileCell2D | undefined;
+      for (const c of near) {
+        const top = c.aabb.y;
+        if (top < body.y + body.height - PLATFORMER_SKIN) continue;
+        if (top > probeBottom) continue;
+        const ok = isSolid(c.collision) ||
+          (!dropThrough && isOneWay(c.collision) && prevBottom <= top + ONE_WAY_TOLERANCE);
+        if (!ok) continue;
+        if (top < bestTop) {
+          bestTop = top;
+          bestCell = c;
+        }
+      }
+      if (bestCell !== undefined && bestTop < Number.POSITIVE_INFINITY) {
+        const snapDelta = bestTop - body.height - body.y;
+        body = { ...body, y: bestTop - body.height };
+        report(bestCell, { x: 0, y: -1 });
+        vy = 0;
+        appliedY += snapDelta;
+      }
+    }
+  }
+
+  const classified = classify(contacts);
+  return Object.freeze({
+    body: Object.freeze(body),
+    velocity: Object.freeze({ x: vx, y: vy }),
+    displacement: Object.freeze({ x: appliedX, y: appliedY }),
+    remainingDisplacement: Object.freeze({
+      x: intendedX - appliedX,
+      y: intendedY - appliedY,
+    }),
+    contacts: Object.freeze({
+      floor: classified.floor,
+      ceiling: classified.ceiling,
+      leftWall: classified.leftWall,
+      rightWall: classified.rightWall,
+      all: Object.freeze(contacts),
+    }),
+  });
+}
+
+function classify(contacts: PlatformerContact2D[]): {
+  floor: PlatformerContact2D | undefined;
+  ceiling: PlatformerContact2D | undefined;
+  leftWall: PlatformerContact2D | undefined;
+  rightWall: PlatformerContact2D | undefined;
+} {
+  let floor: PlatformerContact2D | undefined;
+  let ceiling: PlatformerContact2D | undefined;
+  let leftWall: PlatformerContact2D | undefined;
+  let rightWall: PlatformerContact2D | undefined;
+  for (const c of contacts) {
+    if (c.normal.y === -1 && floor === undefined) floor = c;
+    else if (c.normal.y === 1 && ceiling === undefined) ceiling = c;
+    else if (c.normal.x === 1 && leftWall === undefined) leftWall = c;
+    else if (c.normal.x === -1 && rightWall === undefined) rightWall = c;
+  }
+  return { floor, ceiling, leftWall, rightWall };
+}

package/src/tilemap/queries.ts

@@ -0,0 +1,136 @@
+import type { Aabb2D, Point2D } from '../geometry/types';
+import type { TileCell2D, TileMap2D } from './types';
+import { forEachCellInSpan, makeCell } from './definitions';
+
+/**
+ * Bounded cell queries (T16.2, T16-F6).
+ *
+ * Deterministic order: layer order (map declaration), then row-major within
+ * a layer. Spans are clamped to the finite map before iteration; queries
+ * outside the map return an empty frozen array. All reads flow through the
+ * private chunk index — each overlapped 16x16 chunk region is fetched once.
+ */
+
+function clampSpan(
+  layer: { width: number; height: number },
+  minCx: number, minCy: number, maxCx: number, maxCy: number,
+): { x0: number; y0: number; x1: number; y1: number } | undefined {
+  const x0 = Math.max(0, minCx);
+  const y0 = Math.max(0, minCy);
+  const x1 = Math.min(layer.width - 1, maxCx);
+  const y1 = Math.min(layer.height - 1, maxCy);
+  if (x0 > x1 || y0 > y1) return undefined;
+  return { x0, y0, x1, y1 };
+}
+
+function collectSpan(
+  map: TileMap2D,
+  layerId: string,
+  span: { x0: number; y0: number; x1: number; y1: number },
+  out: TileCell2D[],
+): void {
+  forEachCellInSpan(map, layerId, span.x0, span.y0, span.x1, span.y1, (cx, cy, id) => {
+    out.push(makeCell(map, layerId, cx, cy, id));
+  });
+}
+
+/** All non-empty cells in the given layers overlapping the point. */
+export function cellsAtPoint(
+  map: TileMap2D,
+  point: Point2D,
+  layerIds?: readonly string[],
+): readonly TileCell2D[] {
+  const out: TileCell2D[] = [];
+  const cx = Math.floor((point.x - map.origin.x) / map.cellSize.width);
+  const cy = Math.floor((point.y - map.origin.y) / map.cellSize.height);
+  for (const layer of map.layers) {
+    if (layerIds !== undefined && !layerIds.includes(layer.id)) continue;
+    const span = clampSpan(layer, cx, cy, cx, cy);
+    if (span === undefined) continue;
+    collectSpan(map, layer.id, span, out);
+  }
+  return Object.freeze(out);
+}
+
+/** All non-empty cells whose AABBs intersect the query AABB. */
+export function cellsInAabb(
+  map: TileMap2D,
+  aabb: Aabb2D,
+  layerIds?: readonly string[],
+): readonly TileCell2D[] {
+  const out: TileCell2D[] = [];
+  const minCx = Math.floor((aabb.x - map.origin.x) / map.cellSize.width);
+  const minCy = Math.floor((aabb.y - map.origin.y) / map.cellSize.height);
+  // GS-TILE-05: half-open tile areas, exact arithmetic — no shared epsilon.
+  // The maximum corner selects ceil(max/cell) - 1, so exact boundaries
+  // exclude the next cell and tiny positive extents still select their
+  // own. A zero/negative extent is a point query for the cell containing
+  // the minimum corner (documented divergence from inclusive contact).
+  const maxCx = maxCellIndex(aabb.x, aabb.width, map.origin.x, map.cellSize.width);
+  const maxCy = maxCellIndex(aabb.y, aabb.height, map.origin.y, map.cellSize.height);
+  for (const layer of map.layers) {
+    if (layerIds !== undefined && !layerIds.includes(layer.id)) continue;
+    const span = clampSpan(layer, minCx, minCy, maxCx, maxCy);
+    if (span === undefined) continue;
+    collectSpan(map, layer.id, span, out);
+  }
+  return Object.freeze(out);
+}
+
+/**
+ * Last cell index covered by the half-open span [min, min + extent).
+ * Exact boundaries exclude the next cell; zero/negative extents fall back
+ * to the cell containing the minimum corner (point-query semantics).
+ */
+function maxCellIndex(min: number, extent: number, origin: number, cell: number): number {
+  if (!(min + extent > min)) {
+    return Math.floor((min - origin) / cell);
+  }
+  return Math.ceil((min + extent - origin) / cell) - 1;
+}
+
+/**
+ * Cells overlapped by the swept bounds of a body moving by `displacement`.
+ * The swept bounds are the union AABB of start and end positions — bounded,
+ * never unbounded even for very large displacements (clamped to the map).
+ */
+export function cellsInSweptBounds(
+  map: TileMap2D,
+  body: Aabb2D,
+  displacement: { x: number; y: number },
+  layerIds?: readonly string[],
+): readonly TileCell2D[] {
+  const minX = Math.min(body.x, body.x + displacement.x);
+  const minY = Math.min(body.y, body.y + displacement.y);
+  return cellsInAabb(
+    map,
+    { x: minX, y: minY, width: body.width + Math.abs(displacement.x), height: body.height + Math.abs(displacement.y) },
+    layerIds,
+  );
+}
+
+/**
+ * Non-empty cells inside the visible region (camera bounds + overscan).
+ * Same deterministic ordering as `cellsInAabb`.
+ */
+export function visibleCells(
+  map: TileMap2D,
+  visibleBounds: Aabb2D,
+  overscanCells: number,
+  layerIds?: readonly string[],
+): readonly TileCell2D[] {
+  const out: TileCell2D[] = [];
+  const minCx = Math.floor((visibleBounds.x - map.origin.x) / map.cellSize.width) - overscanCells;
+  const minCy = Math.floor((visibleBounds.y - map.origin.y) / map.cellSize.height) - overscanCells;
+  const maxCx =
+    Math.ceil((visibleBounds.x + visibleBounds.width - map.origin.x) / map.cellSize.width) - 1 + overscanCells;
+  const maxCy =
+    Math.ceil((visibleBounds.y + visibleBounds.height - map.origin.y) / map.cellSize.height) - 1 + overscanCells;
+  for (const layer of map.layers) {
+    if (layerIds !== undefined && !layerIds.includes(layer.id)) continue;
+    const span = clampSpan(layer, minCx, minCy, maxCx, maxCy);
+    if (span === undefined) continue;
+    collectSpan(map, layer.id, span, out);
+  }
+  return Object.freeze(out);
+}

package/src/tilemap/tiledAdapter.ts

@@ -0,0 +1,165 @@
+import { tileError } from './errors';
+import type { TileMapInput2D, TileSet2D } from './types';
+
+/**
+ * Narrow Tiled JSON adapter (T16.5, hardened per T16-F6).
+ *
+ * Accepts ONLY the finite orthogonal subset used by the reference level:
+ * - `orientation: "orthogonal"`, `infinite: false`
+ * - `layers` of `type: "tilelayer"` with inline numeric `data` (no base64,
+ *   no compression, no chunks)
+ * - EVERY other layer type (objectgroup, group, imagelayer, ...) is rejected
+ *   with its exact source path — nothing silently disappears
+ * - Nonzero `offsetx`/`offsety` are rejected (v1 has no layer offsets)
+ * - No per-tile flips (high GID bits) — rejected with a source path
+ *
+ * The root value, options object, and every layer entry are validated BEFORE
+ * any property access, so malformed input always surfaces as a structured
+ * TileMapError instead of a TypeError. Raw Tiled JSON never enters
+ * fixed-step or rendering hot paths; the output is a normalized Gamekit map
+ * input.
+ */
+export interface TiledAdapterOptions {
+  /**
+   * Map Tiled global tile ids to Gamekit tile names. The referenced names
+   * must exist on the provided tileset.
+   */
+  readonly gidToTileName: Readonly<Record<number, string>>;
+  /** Layers to convert, in order. Defaults to every tilelayer. */
+  readonly layerIds?: readonly string[];
+  /** Layers that contribute collision; unlisted layers stay decorative. */
+  readonly collidableLayers?: readonly string[];
+}
+
+function reject(cond: boolean, path: string, message: string): void {
+  if (cond) throw tileError(path, message);
+}
+
+function assertPlainObject(value: unknown, path: string): asserts value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw tileError(path, `expected an object; got ${value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value}`);
+  }
+}
+
+export function parseTiledMap2D(
+  json: unknown,
+  tileset: TileSet2D,
+  options: TiledAdapterOptions,
+): TileMapInput2D {
+  // Validate inputs BEFORE any property access (T16-F6).
+  assertPlainObject(json, 'root');
+  assertPlainObject(options as unknown, 'options');
+  const gidMap = options.gidToTileName as Record<string, string> | null;
+  if (gidMap === null || typeof gidMap !== 'object' || Array.isArray(gidMap)) {
+    throw tileError('options.gidToTileName', 'must be an object mapping gids to tile names');
+  }
+  if (options.layerIds !== undefined) {
+    if (!Array.isArray(options.layerIds)) throw tileError('options.layerIds', 'must be an array of layer names');
+    for (let i = 0; i < options.layerIds.length; i++) {
+      if (typeof options.layerIds[i] !== 'string') {
+        throw tileError(`options.layerIds[${i}]`, 'must be a string');
+      }
+    }
+  }
+  if (options.collidableLayers !== undefined) {
+    if (!Array.isArray(options.collidableLayers)) throw tileError('options.collidableLayers', 'must be an array of layer names');
+    for (let i = 0; i < options.collidableLayers.length; i++) {
+      if (typeof options.collidableLayers[i] !== 'string') {
+        throw tileError(`options.collidableLayers[${i}]`, 'must be a string');
+      }
+    }
+  }
+  if (tileset === undefined || tileset.idOfName === undefined) {
+    throw tileError('tileset', 'must be a value produced by defineTileSet2D');
+  }
+
+  const root = json as Record<string, unknown>;
+  reject(root.orientation !== 'orthogonal', 'root.orientation', `only "orthogonal" is supported; got ${JSON.stringify(root.orientation)}`);
+  reject(root.infinite === true, 'root.infinite', 'infinite maps are not supported in v1');
+  const width = root.width;
+  const height = root.height;
+  reject(typeof width !== 'number' || !Number.isSafeInteger(width) || width <= 0, 'root.width', 'must be a positive integer');
+  reject(typeof height !== 'number' || !Number.isSafeInteger(height) || height <= 0, 'root.height', 'must be a positive integer');
+  const tw = root.tilewidth;
+  const th = root.tileheight;
+  reject(typeof tw !== 'number' || !Number.isFinite(tw) || tw <= 0, 'root.tilewidth', 'must be finite and > 0');
+  reject(typeof th !== 'number' || !Number.isFinite(th) || th <= 0, 'root.tileheight', 'must be finite and > 0');
+
+  reject(!Array.isArray(root.layers), 'root.layers', 'must be an array of layer objects');
+  const layersRaw = root.layers as unknown[];
+  const wanted = options.layerIds;
+  const collidableLayers = options.collidableLayers;
+
+  const layers: TileMapInput2D['layers'] = [];
+  layersRaw.forEach((rawLayerUnknown, index) => {
+    assertPlainObject(rawLayerUnknown, `layers[${index}]`);
+    const layer = rawLayerUnknown as Record<string, unknown>;
+    const rawType = layer.type;
+    reject(
+      typeof rawType !== 'string',
+      `layers[${index}].type`,
+      `must be a string layer type; got ${JSON.stringify(rawType)}`,
+    );
+    // T16-F6: tilelayer is the ONLY accepted type — every other layer type
+    // (objectgroup, group, imagelayer, unknown future types) is rejected
+    // with its exact source path instead of being silently skipped.
+    reject(
+      rawType !== 'tilelayer',
+      `layers[${index}](${JSON.stringify(String(layer.name ?? ''))}).type`,
+      `"${String(rawType)}" layers are not supported in v1`,
+    );
+    const name = typeof layer.name === 'string' && layer.name.length > 0 ? layer.name : `layer${index}`;
+    if (wanted !== undefined && !wanted.includes(name)) return;
+    const p = `layers[${index}](${JSON.stringify(name)})`;
+    // T16-F6: nonzero layer offsets change cell placement — rejected, not ignored.
+    reject(layer.offsetx !== undefined && layer.offsetx !== 0, `${p}.offsetx`, `nonzero layer offsets are not supported in v1; got ${JSON.stringify(layer.offsetx)}`);
+    reject(layer.offsety !== undefined && layer.offsety !== 0, `${p}.offsety`, `nonzero layer offsets are not supported in v1; got ${JSON.stringify(layer.offsety)}`);
+    reject(layer.encoding !== undefined && layer.encoding !== 'csv', `${p}.encoding`, `only inline CSV-free numeric arrays are supported; got ${JSON.stringify(layer.encoding)}`);
+    reject(layer.compression !== undefined, `${p}.compression`, 'compressed layers are not supported in v1');
+    reject(layer.chunks !== undefined, `${p}.chunks`, 'chunked (infinite) layers are not supported in v1');
+    reject(!Array.isArray(layer.data), `${p}.data`, 'must be an inline array of gids');
+    const layerWidth = layer.width;
+    const layerHeight = layer.height;
+    reject(layerWidth !== width, `${p}.width`, `must equal map width ${String(width)}`);
+    reject(layerHeight !== height, `${p}.height`, `must equal map height ${String(height)}`);
+
+    const gidData = layer.data as unknown[];
+    reject(gidData.length !== (width as number) * (height as number), `${p}.data`, `length must equal width*height (${String(width)}*${String(height)})`);
+
+    // Convert gids -> Gamekit ids. Flip bits unsupported.
+    const out: number[] = new Array(gidData.length);
+    for (let i = 0; i < gidData.length; i++) {
+      const rawUnknown = gidData[i];
+      const raw = typeof rawUnknown === 'number' ? rawUnknown : -1;
+      reject(!Number.isSafeInteger(raw) || raw < 0, `${p}.data[${i}]`, `must be a non-negative safe integer; got ${JSON.stringify(rawUnknown)}`);
+      if (raw === 0) {
+        out[i] = 0;
+        continue;
+      }
+      const FLIP_BITS = 0x80000000 | 0x40000000 | 0x20000000;
+      reject((raw & FLIP_BITS) !== 0, `${p}.data[${i}]`, 'per-tile flip/rotation flags are not supported in v1');
+      const mapped = gidMap[raw];
+      reject(mapped === undefined, `${p}.data[${i}]`, `gid ${raw} has no mapping in gidToTileName`);
+      const gamekitId = tileset.idOfName[mapped as string] ?? -1;
+      reject(gamekitId === -1, `${p}.data[${i}]`, `mapped tile name ${JSON.stringify(mapped)} is missing from the bound tileset`);
+      out[i] = gamekitId;
+    }
+
+    layers.push({
+      id: name,
+      width: width as number,
+      height: height as number,
+      data: out,
+      collidable: collidableLayers ? collidableLayers.includes(name) : true,
+    });
+  });
+
+  reject(layers.length === 0, 'layers', 'no tilelayers matched; at least one is required');
+
+  return {
+    cellSize: { width: tw as number, height: th as number },
+    tileset,
+    layers,
+    origin: { x: 0, y: 0 },
+  };
+}