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/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+/);
+});