Add map inspector that emits a human-readable stats report

Counts set vs empty cells per layer, lists the top-10 most frequent
non-empty GIDs with decoded components, and reports roof coverage.
When an atlas registry is supplied, atlas-id+tile-name annotations
are added; without one the report still works using indices only.

tests/fixtures/atlases-inspector/atlas_a/tiles.atlas.json

@@ -0,0 +1,10 @@
+{
+  "atlas_id": "atlas_a",
+  "atlas_version": 1,
+  "atlas_size_px": [64, 64],
+  "tile_size_px": 32,
+  "tiles": [
+    { "id": 1, "name": "grass", "uv": [0, 0, 32, 32], "walkable": true },
+    { "id": 2, "name": "stone", "uv": [32, 0, 32, 32], "walkable": false, "blocks_sight": true }
+  ]
+}

tests/fixtures/maps/inspect_sample.map.json

@@ -0,0 +1,30 @@
+{
+  "schema_version": 2,
+  "id": "inspect_sample",
+  "size": { "w": 4, "h": 4 },
+  "atlases": ["atlas_a", "atlas_b"],
+  "layers": {
+    "surface": {
+      "tiles": [
+        16, 16, 16, 16,
+        16, 32, 32, 16,
+        16, 32, 32, 16,
+        16, 16, 16, 16
+      ]
+    },
+    "wall": {
+      "tiles": [
+        16777232, 16777232, 16777232, 16777232,
+        16777232,        0,        0, 16777232,
+        16777232,        0,        0, 16777232,
+        16777232, 16777232, 16777232, 16777232
+      ]
+    }
+  },
+  "roof": [
+    0, 0, 0, 0,
+    0, 1, 1, 0,
+    0, 1, 1, 0,
+    0, 0, 0, 0
+  ]
+}

tests/inspector.test.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { inspectMap } = require('../src/inspector');
+const { loadAtlasDirs } = require('../src/atlas-loader');
+
+const FIX_MAP = path.join(__dirname, 'fixtures', 'maps', 'inspect_sample.map.json');
+const FIX_ATLAS = path.join(__dirname, 'fixtures', 'atlases-inspector');
+const loadMap = () => JSON.parse(fs.readFileSync(FIX_MAP, 'utf8'));
+
+test('inspectMap: header lists id, schema_version, size', () => {
+  const text = inspectMap(loadMap(), {});
+  assert.match(text, /Map: inspect_sample/);
+  assert.match(text, /schema_version=2/);
+  assert.match(text, /size=4x4/);
+});
+
+test('inspectMap: atlas section lists each declared atlas with resolved/not-found marker', () => {
+  const { registry } = loadAtlasDirs([FIX_ATLAS]);
+  const text = inspectMap(loadMap(), registry);
+  assert.match(text, /\[0\] atlas_a.*resolved/);
+  // atlas_b is not in the FIX_ATLAS fixture dir
+  assert.match(text, /\[1\] atlas_b.*not found/);
+});
+
+test('inspectMap: without registry, atlases show "no registry" marker', () => {
+  const text = inspectMap(loadMap(), {});
+  assert.match(text, /\[0\] atlas_a.*no registry/);
+});
+
+test('inspectMap: per-layer cell counts are correct', () => {
+  const text = inspectMap(loadMap(), {});
+  // surface has all 16 cells set
+  assert.match(text, /surface\s+16 cells set,\s+0 empty/);
+  // wall has 12 set, 4 empty (the 2x2 hole)
+  assert.match(text, /wall\s+12 cells set,\s+4 empty/);
+});
+
+test('inspectMap: top tiles include atlas/tile components', () => {
+  const text = inspectMap(loadMap(), {});
+  // surface tile (0,1,0) = grass appears 12 times
+  assert.match(text, /atlas=0 tile=1.*× ?12/);
+  // surface tile (0,2,0) = stone appears 4 times
+  assert.match(text, /atlas=0 tile=2.*× ?4/);
+});
+
+test('inspectMap: with registry, top tiles show resolved name', () => {
+  const { registry } = loadAtlasDirs([FIX_ATLAS]);
+  const text = inspectMap(loadMap(), registry);
+  assert.match(text, /atlas_a:grass/);
+  assert.match(text, /atlas_a:stone/);
+});
+
+test('inspectMap: roof line shows flagged-cell count', () => {
+  const text = inspectMap(loadMap(), {});
+  assert.match(text, /Roof: 4 cells flagged/);
+});
+
+test('inspectMap: map without roof omits roof section gracefully', () => {
+  const m = loadMap();
+  delete m.roof;
+  const text = inspectMap(m, {});
+  assert.match(text, /Roof:\s*0 cells flagged|Roof: \(none\)/);
+});
+
+test('inspectMap: empty layers are not listed as top-tile groups', () => {
+  const m = loadMap();
+  m.layers.topsurface = { tiles: new Array(16).fill(0) };
+  const text = inspectMap(m, {});
+  assert.match(text, /topsurface\s+0 cells set,\s+16 empty/);
+  // The "top tiles" block under topsurface should be absent (or "none")
+  assert.doesNotMatch(text.split('topsurface')[1].split(/\n[a-z]/)[0], /atlas=\d+ tile=\d+/);
+});