kgames

lib.js (26965B)

---

 (function (root) {
   const HEADINGS = ['north', 'east', 'south', 'west'];
   const CARDINALS = ['N', 'E', 'S', 'W'];
   const DX = { north: 0, east: 1, south: 0, west: -1 };
   const DY = { north: -1, east: 0, south: 1, west: 0 };
   const TO_CARD = { north: 'N', east: 'E', south: 'S', west: 'W' };
   const OPPOSITE = { north: 'south', east: 'west', south: 'north', west: 'east' };
   const LEFT = { north: 'west', west: 'south', south: 'east', east: 'north' };
   const RIGHT = { north: 'east', east: 'south', south: 'west', west: 'north' };
 
   const CARD_TO_HEADING = { N: 'north', E: 'east', S: 'south', W: 'west' };
   const HEADING_TO_CARD = TO_CARD;
 
   const ISLAND_WIDTH = 50;
   const ISLAND_HEIGHT = 50;
   const MIN_BLOCK = 4;
   const ROUTE_COUNT = 200;
   const ROUTE_EXTENSION_COUNT = 36;
 
   const CELL_TYPES = {
     WATER: 'water',
     BEACH: 'beach',
     ROAD: 'road',
     BUILDING: 'building',
   };
 
   const DIRS = {
     N: { dx: 0, dy: -1, heading: 'north' },
     E: { dx: 1, dy: 0, heading: 'east' },
     S: { dx: 0, dy: 1, heading: 'south' },
     W: { dx: -1, dy: 0, heading: 'west' },
   };
 
   function createSeededRng(seed) {
     let state = (seed == null ? 0x12345678 : seed) >>> 0;
     return {
       next() {
         state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
         return state / 0x100000000;
       },
       pick(arr) {
         return arr[Math.floor(this.next() * arr.length)];
       },
     };
   }
 
   function getRng(opts, rng) {
     if (rng) return rng;
     return createSeededRng(opts && opts.seed);
   }
 
   function randInt(rand, min, max) {
     return min + Math.floor(rand.next() * (max - min + 1));
   }
 
   function randPick(rand, arr) {
     if (rand.pick) return rand.pick(arr);
     return arr[Math.floor(rand.next() * arr.length)];
   }
 
   function cloneExits(exits) {
     const out = { N: false, E: false, S: false, W: false };
     CARDINALS.forEach(card => { out[card] = !!exits[card]; });
     return out;
   }
 
   function turnHeading(heading, move) {
     if (move === 'straight') return heading;
     if (move === 'left') return LEFT[heading];
     if (move === 'right') return RIGHT[heading];
     throw new Error('Invalid move: ' + move);
   }
 
   function getRelativeMove(fromHeading, toHeading) {
     if (toHeading === fromHeading) return 'straight';
     if (toHeading === LEFT[fromHeading]) return 'left';
     if (toHeading === RIGHT[fromHeading]) return 'right';
     throw new Error('Unsupported heading transition');
   }
 
   function stepPosition(pos, heading) {
     return { x: pos.x + DX[heading], y: pos.y + DY[heading] };
   }
 
   function classifyIntersection(exits) {
     const norm = cloneExits(exits);
     const dirs = CARDINALS.filter(card => norm[card]);
     const degree = dirs.length;
     let kind = 'dead-end';
     if (degree === 4) kind = 'four';
     else if (degree === 3) kind = 't';
     else if (degree === 2) {
       kind = (norm.N && norm.S) || (norm.E && norm.W) ? 'straight' : 'corner';
     } else if (degree === 1) {
       kind = 'dead-end';
     }
     return { degree, kind, exits: norm };
   }
 
   function getLegalMoves(cell, heading) {
     const exits = cloneExits(cell.exits || {});
     const legal = [];
     if (exits[TO_CARD[heading]]) legal.push('straight');
     if (exits[TO_CARD[LEFT[heading]]]) legal.push('left');
     if (exits[TO_CARD[RIGHT[heading]]]) legal.push('right');
     return legal;
   }
 
   function pickPromptMove(legalMoves, rng) {
     if (!legalMoves.length) throw new Error('No legal moves');
     return (rng && rng.pick ? rng : createSeededRng()).pick(legalMoves);
   }
 
   function summarizeKinds(cells) {
     return cells.reduce((acc, cell) => {
       const kind = classifyIntersection(cell.exits).kind;
       acc[kind] = (acc[kind] || 0) + 1;
       return acc;
     }, {});
   }
 
   // ------------------------------------------------------------------
   // Island grid
   // ------------------------------------------------------------------
 
   function allocateGrid(width, height) {
     const grid = [];
     for (let y = 0; y < height; y++) {
       const row = [];
       for (let x = 0; x < width; x++) {
         row.push({
           x,
           y,
           type: CELL_TYPES.WATER,
           exits: { N: false, E: false, S: false, W: false },
           meta: null,
         });
       }
       grid.push(row);
     }
     return grid;
   }
 
   function layOutRings(grid, width, height) {
     for (let y = 0; y < height; y++) {
       for (let x = 0; x < width; x++) {
         if (x === 0 || y === 0 || x === width - 1 || y === height - 1) {
           grid[y][x].type = CELL_TYPES.WATER;
         } else if (x === 1 || y === 1 || x === width - 2 || y === height - 2) {
           grid[y][x].type = CELL_TYPES.BEACH;
         } else if (x === 2 || y === 2 || x === width - 3 || y === height - 3) {
           grid[y][x].type = CELL_TYPES.ROAD;
         } else {
           grid[y][x].type = CELL_TYPES.BUILDING;
         }
       }
     }
   }
 
   function drawRoadH(grid, x1, x2, y) {
     for (let x = x1; x <= x2; x++) grid[y][x].type = CELL_TYPES.ROAD;
   }
 
   function drawRoadV(grid, x, y1, y2) {
     for (let y = y1; y <= y2; y++) grid[y][x].type = CELL_TYPES.ROAD;
   }
 
   function pickSplitCoord(rand, start, size) {
     return randInt(rand, start + MIN_BLOCK, start + size - MIN_BLOCK - 1);
   }
 
   function subdivideInteriorRoads(grid, rand) {
     function subdivide(x, y, w, h) {
       const canSplitW = w >= MIN_BLOCK * 2 + 1;
       const canSplitH = h >= MIN_BLOCK * 2 + 1;
       if (!canSplitW && !canSplitH) return;
 
       let splitType;
       if (canSplitW && canSplitH) {
         const r = rand.next();
         splitType = r < 0.40 ? 'quad' : (r < 0.70 ? 'horiz' : 'vert');
       } else if (canSplitH) {
         splitType = 'horiz';
       } else {
         splitType = 'vert';
       }
 
       const right = x + w - 1;
       const bottom = y + h - 1;
 
       if (splitType === 'quad') {
         const cx = pickSplitCoord(rand, x, w);
         const cy = pickSplitCoord(rand, y, h);
         drawRoadH(grid, x, right, cy);
         drawRoadV(grid, cx, y, bottom);
         subdivide(x, y, cx - x, cy - y);
         subdivide(cx + 1, y, right - cx, cy - y);
         subdivide(x, cy + 1, cx - x, bottom - cy);
         subdivide(cx + 1, cy + 1, right - cx, bottom - cy);
         return;
       }
 
       if (splitType === 'horiz') {
         const cy = pickSplitCoord(rand, y, h);
         drawRoadH(grid, x, right, cy);
         subdivide(x, y, w, cy - y);
         subdivide(x, cy + 1, w, bottom - cy);
         return;
       }
 
       const cx = pickSplitCoord(rand, x, w);
       drawRoadV(grid, cx, y, bottom);
       subdivide(x, y, cx - x, h);
       subdivide(cx + 1, y, right - cx, h);
     }
 
     subdivide(3, 3, 44, 44);
   }
 
   function stitchRoadExits(grid, width, height) {
     for (let y = 0; y < height; y++) {
       for (let x = 0; x < width; x++) {
         const cell = grid[y][x];
         cell.exits = { N: false, E: false, S: false, W: false };
         cell.meta = null;
         if (cell.type !== CELL_TYPES.ROAD) continue;
 
         for (const dir of ['N', 'E', 'S', 'W']) {
           const nx = x + DIRS[dir].dx;
           const ny = y + DIRS[dir].dy;
           cell.exits[dir] = !!grid[ny] && !!grid[ny][nx] && grid[ny][nx].type === CELL_TYPES.ROAD;
         }
         cell.meta = classifyIntersection(cell.exits);
       }
     }
   }
 
   function validateConnectedRoads(grid, width, height) {
     const roads = [];
     for (let y = 0; y < height; y++) {
       for (let x = 0; x < width; x++) {
         if (grid[y][x].type === CELL_TYPES.ROAD) roads.push(grid[y][x]);
       }
     }
     if (!roads.length) throw new Error('Island has no roads');
 
     for (const cell of roads) {
       const degree = Object.values(cell.exits).filter(Boolean).length;
       if (degree < 2) throw new Error('Dead-end road at ' + cell.x + ',' + cell.y);
     }
 
     const seen = new Set();
     const queue = [roads[0]];
     seen.add(roads[0].x + ',' + roads[0].y);
 
     while (queue.length) {
       const cell = queue.shift();
       for (const dir of ['N', 'E', 'S', 'W']) {
         if (!cell.exits[dir]) continue;
         const nx = cell.x + DIRS[dir].dx;
         const ny = cell.y + DIRS[dir].dy;
         const key = nx + ',' + ny;
         if (!seen.has(key)) {
           seen.add(key);
           queue.push(grid[ny][nx]);
         }
       }
     }
 
     if (seen.size !== roads.length) {
       throw new Error('Disconnected road graph: reached ' + seen.size + ' of ' + roads.length);
     }
   }
 
   function flattenGrid(grid) {
     const out = [];
     for (let y = 0; y < grid.length; y++) {
       for (let x = 0; x < grid[y].length; x++) {
         out.push(grid[y][x]);
       }
     }
     return out;
   }
 
   function pickRandomRouteStart(roads, rand) {
     const candidates = roads.filter(c => {
       const meta = c.meta || classifyIntersection(c.exits);
       return meta.degree >= 2;
     });
     const cell = randPick(rand, candidates);
     const cards = ['N', 'E', 'S', 'W'].filter(c => cell.exits[c]);
     const card = randPick(rand, cards);
     return { x: cell.x, y: cell.y, heading: CARD_TO_HEADING[card] };
   }
 
   function headingFromTo(a, b) {
     const dx = b.x - a.x, dy = b.y - a.y;
     if (dx === 1) return 'east';
     if (dx === -1) return 'west';
     if (dy === 1) return 'south';
     return 'north';
   }
 
   function bfsRoadPath(grid, startCell, targetCell) {
     if (startCell === targetCell) return [startCell];
     const queue = [startCell];
     const parent = new Map();
     parent.set(startCell, null);
     while (queue.length) {
       const cell = queue.shift();
       for (const card of ['N', 'E', 'S', 'W']) {
         if (!cell.exits[card]) continue;
         const nx = cell.x + DIRS[card].dx;
         const ny = cell.y + DIRS[card].dy;
         const next = grid[ny] && grid[ny][nx];
         if (!next || next.type !== CELL_TYPES.ROAD) continue;
         if (parent.has(next)) continue;
         parent.set(next, cell);
         if (next === targetCell) {
           const path = [];
           let cur = next;
           while (cur) {
             path.push(cur);
             cur = parent.get(cur);
           }
           return path.reverse();
         }
         queue.push(next);
       }
     }
     return null;
   }
 
   function pathToRouteSteps(grid, cellPath, startIndex) {
     if (!cellPath || cellPath.length <= 2) return [];
     const steps = [];
     for (let i = 1; i < cellPath.length - 1; i++) {
       const decision = cellPath[i];
       if (!isDecisionCell(decision)) continue;
       const approach = cellPath[i - 1];
       const exitCell = cellPath[i + 1];
       const headingIn = headingFromTo(approach, decision);
       const headingOut = headingFromTo(decision, exitCell);
       steps.push({
         index: (startIndex ?? 0) + steps.length,
         x: decision.x,
         y: decision.y,
         approachX: approach.x,
         approachY: approach.y,
         headingIn,
         headingOut,
         move: getRelativeMove(headingIn, headingOut),
         exitX: exitCell.x,
         exitY: exitCell.y,
       });
     }
     return steps;
   }
 
   function bfsRoadDistances(grid, startCell) {
     const dist = new Map();
     dist.set(startCell, 0);
     const queue = [startCell];
     while (queue.length) {
       const cell = queue.shift();
       const d = dist.get(cell);
       for (const card of ['N', 'E', 'S', 'W']) {
         if (!cell.exits[card]) continue;
         const nx = cell.x + DIRS[card].dx;
         const ny = cell.y + DIRS[card].dy;
         const next = grid[ny] && grid[ny][nx];
         if (!next || next.type !== CELL_TYPES.ROAD) continue;
         if (dist.has(next)) continue;
         dist.set(next, d + 1);
         queue.push(next);
       }
     }
     return dist;
   }
 
   // Cardinal ('N'/'E'/'S'/'W') that moves from `cell` to the road neighbour
   // closest to the distMap origin (see bfsRoadDistances), or null if no
   // neighbour improves on the current cell — e.g. when already at the origin.
   function bestRoadDirection(grid, cell, distMap) {
     let best = null;
     let bestDist = distMap.has(cell) ? distMap.get(cell) : Infinity;
     for (const card of CARDINALS) {
       if (!cell.exits[card]) continue;
       const row = grid[cell.y + DIRS[card].dy];
       const next = row && row[cell.x + DIRS[card].dx];
       if (!next || !distMap.has(next)) continue;
       const d = distMap.get(next);
       if (d < bestDist) { bestDist = d; best = card; }
     }
     return best;
   }
 
   function pickFireDestination(island, rng, opts) {
     const rand = rng || createSeededRng();
     const targetDistance = opts && opts.targetDistance != null ? opts.targetDistance : 0;
     const variance = opts && opts.variance != null ? opts.variance : 5;
     const fromCell = opts && opts.fromCell;
 
     const candidates = island.roads.filter(cell => {
       for (const card of ['N', 'E', 'S', 'W']) {
         const nx = cell.x + DIRS[card].dx;
         const ny = cell.y + DIRS[card].dy;
         const neighbor = island.grid[ny] && island.grid[ny][nx];
         if (neighbor && neighbor.type === CELL_TYPES.BUILDING && !neighbor.park) return true;
       }
       return false;
     });
     if (!candidates.length) return null;
 
     let chosen;
     if (fromCell && targetDistance > 0) {
       const dists = bfsRoadDistances(island.grid, fromCell);
       const minD = targetDistance - variance;
       const maxD = targetDistance + variance;
       const inRange = candidates.filter(c => {
         const d = dists.get(c);
         return d != null && d >= minD && d <= maxD;
       });
       if (inRange.length) {
         chosen = randPick(rand, inRange);
       } else {
         let bestDiff = Infinity;
         for (const c of candidates) {
           const d = dists.get(c);
           if (d == null) continue;
           const diff = Math.abs(d - targetDistance);
           if (diff < bestDiff) { bestDiff = diff; chosen = c; }
         }
         if (!chosen) chosen = randPick(rand, candidates);
       }
     } else {
       chosen = randPick(rand, candidates);
     }
 
     if (!chosen) return null;
     for (const card of ['N', 'E', 'S', 'W']) {
       const nx = chosen.x + DIRS[card].dx;
       const ny = chosen.y + DIRS[card].dy;
       const neighbor = island.grid[ny] && island.grid[ny][nx];
       if (neighbor && neighbor.type === CELL_TYPES.BUILDING && !neighbor.park) {
         return { roadCell: chosen, buildingCell: neighbor };
       }
     }
     return null;
   }
 
   // ------------------------------------------------------------------
   // Decoration helpers (pure, deterministic) — drive all baked/ambient
   // variety so the island renders identically every run.
   // ------------------------------------------------------------------
 
   // Deterministic hash → float in [0,1). All decor variety derives from this.
   function hashCell(x, y, salt) {
     let h = Math.imul(((x | 0) + 0x9e3779b9) >>> 0, 0x85ebca6b);
     h = (h ^ Math.imul(((y | 0) + 0x165667b1) >>> 0, 0xc2b2ae35)) >>> 0;
     h = (h ^ Math.imul(((salt | 0) + 0x27d4eb2f) >>> 0, 0x2545f491)) >>> 0;
     h ^= h >>> 15;
     h = Math.imul(h, 0x2c1b3c6d) >>> 0;
     h ^= h >>> 13;
     return (h >>> 0) / 0x100000000;
   }
 
   // Greedily cover all BUILDING cells with disjoint rectangles. BSP road
   // subdivision guarantees building cells form road-bounded rectangular blocks,
   // so this yields one rectangle per block — render each as ONE building.
   function findBuildingBlocks(grid) {
     const h = grid.length;
     const w = grid[0].length;
     const covered = [];
     for (let y = 0; y < h; y++) covered.push(new Array(w).fill(false));
     const isB = (x, y) => !!(grid[y] && grid[y][x] && grid[y][x].type === CELL_TYPES.BUILDING);
     const blocks = [];
     for (let y = 0; y < h; y++) {
       for (let x = 0; x < w; x++) {
         if (!isB(x, y) || covered[y][x]) continue;
         let bw = 1;
         while (isB(x + bw, y) && !covered[y][x + bw]) bw++;
         let bh = 1;
         let canGrow = true;
         while (canGrow) {
           const ny = y + bh;
           for (let xx = x; xx < x + bw; xx++) {
             if (!isB(xx, ny) || covered[ny][xx]) { canGrow = false; break; }
           }
           if (canGrow) bh++;
         }
         for (let yy = y; yy < y + bh; yy++) {
           for (let xx = x; xx < x + bw; xx++) covered[yy][xx] = true;
         }
         blocks.push({ x, y, w: bw, h: bh });
       }
     }
     return blocks;
   }
 
   // Tag ~fraction of building blocks as parks (cell.park = true), preferring
   // larger (≥2×2) blocks. Type stays 'building' so grid/route tests are
   // untouched. Deterministic ordering via hashCell. Returns the block list.
   function assignParks(island, opts) {
     const fraction = (opts && opts.fraction != null) ? opts.fraction : 0.15;
     const grid = island.grid;
     const blocks = findBuildingBlocks(grid);
     const scored = blocks.map(b => ({
       b,
       big: (b.w >= 2 && b.h >= 2) ? 1 : 0,
       r: hashCell(b.x, b.y, 7),
     }));
     scored.sort((a, c) => (c.big - a.big) || (a.r - c.r) || (a.b.y - c.b.y) || (a.b.x - c.b.x));
     const target = Math.round(blocks.length * fraction);
     let count = 0;
     for (const s of scored) {
       if (count >= target) break;
       for (let yy = s.b.y; yy < s.b.y + s.b.h; yy++) {
         for (let xx = s.b.x; xx < s.b.x + s.b.w; xx++) {
           if (grid[yy] && grid[yy][xx]) grid[yy][xx].park = true;
         }
       }
       count++;
     }
     return blocks;
   }
 
   // Next {cell, heading} for an ambient car: reuse road exits, prefer going
   // straight, never reverse unless it's the only option (dead-end).
   function advanceCarPlan(grid, cell, heading, rand) {
     const back = OPPOSITE[heading];
     const options = [];
     for (const card of ['N', 'E', 'S', 'W']) {
       if (cell.exits && cell.exits[card]) {
         const hd = CARD_TO_HEADING[card];
         if (hd !== back) options.push(hd);
       }
     }
     let chosen;
     if (!options.length) {
       chosen = back;
     } else if (options.indexOf(heading) !== -1 && rand.next() < 0.7) {
       chosen = heading;
     } else {
       chosen = randPick(rand, options);
     }
     const next = cellAhead(grid, cell, chosen);
     if (!next || next.type !== CELL_TYPES.ROAD) {
       const rev = cellAhead(grid, cell, back);
       return { cell: (rev && rev.type === CELL_TYPES.ROAD) ? rev : cell, heading: back };
     }
     return { cell: next, heading: chosen };
   }
 
   // Which edges of a road cell abut a building/park (drives sidewalk baking
   // and pedestrian paths). Parks are type 'building' so they're included.
   function sidewalkEdges(grid, x, y) {
     const out = { N: false, E: false, S: false, W: false };
     for (const card of ['N', 'E', 'S', 'W']) {
       const nx = x + DIRS[card].dx;
       const ny = y + DIRS[card].dy;
       const nb = grid[ny] && grid[ny][nx];
       if (nb && nb.type === CELL_TYPES.BUILDING) out[card] = true;
     }
     return out;
   }
 
   function buildIsland(opts, rng) {
     const width = (opts && opts.width) ?? ISLAND_WIDTH;
     const height = (opts && opts.height) ?? ISLAND_HEIGHT;
     const routeCount = (opts && opts.routeCount) ?? ROUTE_COUNT;
     const rand = getRng(opts, rng);
 
     if (width !== 50 || height !== 50) {
       throw new Error('Only 50x50 islands are supported by this layout');
     }
 
     const grid = allocateGrid(width, height);
     layOutRings(grid, width, height);
     subdivideInteriorRoads(grid, rand);
     stitchRoadExits(grid, width, height);
     validateConnectedRoads(grid, width, height);
 
     const cells = flattenGrid(grid);
     const roads = cells.filter(c => c.type === CELL_TYPES.ROAD);
     const routeStart = (opts && opts.routeStart)
       ? opts.routeStart
       : pickRandomRouteStart(roads, rand);
     const route = buildRouteOnGraph(grid, { count: routeCount, startCell: routeStart, startHeading: routeStart.heading }, rand);
 
     return {
       width,
       height,
       grid,
       cells,
       roads,
       buildings: cells.filter(c => c.type === CELL_TYPES.BUILDING),
       beach: cells.filter(c => c.type === CELL_TYPES.BEACH),
       water: cells.filter(c => c.type === CELL_TYPES.WATER),
       route,
       routeStart,
       bounds: { minX: -0.5, minY: -0.5, maxX: width - 0.5, maxY: height - 0.5, width, height },
     };
   }
 
   // ------------------------------------------------------------------
   // Route walking on road graph
   // ------------------------------------------------------------------
 
   function isDecisionCell(cell) {
     if (!cell || cell.type !== CELL_TYPES.ROAD) return false;
     const meta = cell.meta || classifyIntersection(cell.exits);
     return meta.degree >= 3 || meta.kind === 'corner';
   }
 
   function outboundHeadings(cell, headingIn) {
     const back = OPPOSITE[headingIn];
     const all = [];
     for (const card of ['N', 'E', 'S', 'W']) {
       if (cell.exits[card]) all.push(CARD_TO_HEADING[card]);
     }
     const withoutBack = all.filter(heading => heading !== back);
     return withoutBack.length ? withoutBack : all;
   }
 
   function cellAhead(grid, cell, heading) {
     const next = stepPosition(cell, heading);
     return grid[next.y] && grid[next.y][next.x];
   }
 
   function findNextDecision(grid, fromCell, heading) {
     let previous = fromCell;
     let current = cellAhead(grid, fromCell, heading);
 
     while (current && current.type === CELL_TYPES.ROAD) {
       if (isDecisionCell(current)) {
         return { decision: current, approach: previous };
       }
 
       const outCard = HEADING_TO_CARD[heading];
       if (!current.exits[outCard]) {
         throw new Error('Straight road ended before a decision at ' + current.x + ',' + current.y);
       }
 
       previous = current;
       current = cellAhead(grid, current, heading);
     }
 
     throw new Error('Route left the road graph from ' + fromCell.x + ',' + fromCell.y + ' heading ' + heading);
   }
 
   function chooseHeading(rand, visitCounts, decision, options) {
     let lowest = Infinity;
     let candidates = [];
 
     for (const heading of options) {
       const key = decision.x + ',' + decision.y + '>' + heading;
       const count = visitCounts[key] || 0;
       if (count < lowest) {
         lowest = count;
         candidates = [heading];
       } else if (count === lowest) {
         candidates.push(heading);
       }
     }
 
     return randPick(rand, candidates);
   }
 
   function buildRouteOnGraph(grid, opts, rng) {
     const rand = rng || createSeededRng(opts && opts.seed);
     const count = (opts && opts.count) ?? ROUTE_COUNT;
     const route = [];
     const visitCounts = (opts && opts.visitCounts) || Object.create(null);
 
     let fromCell = (opts && opts.startCell) || { x: 3, y: 2 };
     let heading = (opts && opts.startHeading) || fromCell.heading || 'east';
     fromCell = grid[fromCell.y][fromCell.x];
     if (!fromCell || fromCell.type !== CELL_TYPES.ROAD) {
       throw new Error('Route start is not a road cell');
     }
 
     for (let i = 0; i < count; i++) {
       const found = findNextDecision(grid, fromCell, heading);
       const decision = found.decision;
       const approach = found.approach;
       const options = outboundHeadings(decision, heading);
       const headingOut = chooseHeading(rand, visitCounts, decision, options);
       const exit = cellAhead(grid, decision, headingOut);
 
       if (!exit || exit.type !== CELL_TYPES.ROAD) {
         throw new Error('Route chose non-road exit from ' + decision.x + ',' + decision.y);
       }
 
       const edgeKey = decision.x + ',' + decision.y + '>' + headingOut;
       visitCounts[edgeKey] = (visitCounts[edgeKey] || 0) + 1;
 
       route.push({
         index: ((opts && opts.startIndex) ?? 0) + i,
         x: decision.x,
         y: decision.y,
         approachX: approach.x,
         approachY: approach.y,
         headingIn: heading,
         headingOut,
         move: getRelativeMove(heading, headingOut),
         exitX: exit.x,
         exitY: exit.y,
       });
 
       fromCell = exit;
       heading = headingOut;
     }
 
     return route;
   }
 
   function visitCountsFromRoute(route) {
     const visitCounts = Object.create(null);
     for (const step of route) {
       const key = step.x + ',' + step.y + '>' + step.headingOut;
       visitCounts[key] = (visitCounts[key] || 0) + 1;
     }
     return visitCounts;
   }
 
   function extendRouteOnGraph(islandOrGrid, existingRoute, additional, rng) {
     const grid = Array.isArray(islandOrGrid) ? islandOrGrid : islandOrGrid.grid;
     if (!existingRoute.length) {
       return buildRouteOnGraph(grid, { count: additional }, rng);
     }
 
     const last = existingRoute[existingRoute.length - 1];
     return buildRouteOnGraph(grid, {
       count: additional,
       startCell: { x: last.exitX, y: last.exitY },
       startHeading: last.headingOut,
       startIndex: existingRoute.length,
       visitCounts: visitCountsFromRoute(existingRoute),
     }, rng);
   }
 
   // ── Fire-hose minigame facade ───────────────────────────────────────────
   // Pure layout for the street-view hose minigame: a cols×rows window grid
   // plus which windows start on fire. fireNumber (0-based, how many fires the
   // player has already put out) ramps the count up gently.
   function buildFacade(rng, opts) {
     const o = opts || {};
     const rand = rng || createSeededRng(o.seed);
     const cols = o.cols || randInt(rand, 4, 6);
     const rows = o.rows || randInt(rand, 3, 4);
     const total = cols * rows;
     const maxFires = Math.max(2, Math.floor(total / 2));
     const want = Math.min(3 + (o.fireNumber || 0), maxFires);
 
     const indices = [];
     for (let i = 0; i < total; i++) indices.push(i);
     for (let i = indices.length - 1; i > 0; i--) {
       const j = Math.floor(rand.next() * (i + 1));
       const tmp = indices[i]; indices[i] = indices[j]; indices[j] = tmp;
     }
     const fires = indices.slice(0, want).sort((a, b) => a - b)
       .map((i) => ({ index: i, col: i % cols, row: Math.floor(i / cols) }));
 
     return { cols, rows, fires };
   }
 
   const api = {
     HEADINGS,
     buildFacade,
     CELL_TYPES,
     turnHeading,
     getRelativeMove,
     stepPosition,
     classifyIntersection,
     getLegalMoves,
     pickPromptMove,
     summarizeKinds,
     createSeededRng,
     getRng,
     randInt,
     randPick,
     buildIsland,
     buildRouteOnGraph,
     extendRouteOnGraph,
     visitCountsFromRoute,
     allocateGrid,
     layOutRings,
     flattenGrid,
     stitchRoadExits,
     validateConnectedRoads,
     isDecisionCell,
     outboundHeadings,
     findNextDecision,
     cellAhead,
     chooseHeading,
     drawRoadH,
     drawRoadV,
     subdivideInteriorRoads,
     OPPOSITE,
     CARD_TO_HEADING,
     HEADING_TO_CARD,
     DIRS,
     pickRandomRouteStart,
     headingFromTo,
     bfsRoadPath,
     bfsRoadDistances,
     bestRoadDirection,
     pathToRouteSteps,
     pickFireDestination,
     hashCell,
     findBuildingBlocks,
     assignParks,
     advanceCarPlan,
     sidewalkEdges,
   };
 
   if (typeof module !== 'undefined' && module.exports) module.exports = api;
   root.FireTruckLib = api;
 })(typeof window !== 'undefined' ? window : globalThis);