@maka/maka-cli 5.49.0 → 5.51.0

package/bundle/typescript/src/commands/game/sideQuest/utilities/spots.js

@@ -1,5 +1,7 @@
+import { Direction } from '../types/shared/direction-enum.js';
 import { significantWords, wordsAreCloseEnough } from './fuzzy-match.js';
 import { hint } from './hints.js';
+import { findPath, distanceMeters, coverBetween, blockingRegionFor, pathClimbSteps, levelFootprint, key, isCellBlocked, pathSqueezes, } from './room-grid.js';
 /**
  * Intra-room locations ("at" spots -- player request: every room felt
  * like everything stood at your elbow; walking into the bar had both
@@ -24,10 +26,6 @@ import { hint } from './hints.js';
  * Every spot comparison in the game goes through these helpers -- no
  * call site rolls its own.
  */
-/** Movement distance between spots, scaled by the room's size. */
-export const SIZE_COST = {
-    small: 1, medium: 2, large: 4,
-};
 export function spotsActive(room) {
     return (room?.spots?.length ?? 0) > 0;
 }
@@ -69,10 +67,17 @@ export function resolveSpot(room, name) {
  */
 export function spotOf(actor) {
     const room = actor.currentLocation;
-    if (!spotsActive(room) || actor.plane !== 'meat' || !actor.atSpot)
+    if (actor.plane !== 'meat' || !actor.atSpot)
         return undefined;
+    // The OPEN FLOOR is bare ground, and bare ground exists in every room
+    // -- including one with no named places at all. Checked BEFORE
+    // spotsActive so a street can position its people (every room is
+    // matrixed now; see Room.ensureGrid). Named spots still have to be
+    // real, which is what keeps a stale name from reading as a position.
     if (actor.atSpot === OPEN_FLOOR)
         return OPEN_FLOOR;
+    if (!spotsActive(room))
+        return undefined;
     return room.spots.some(s => s.name === actor.atSpot) ? actor.atSpot : undefined;
 }
 /** Whether two actors share a spot (callers already gate same-room). */
@@ -98,8 +103,627 @@ export function canReach(actor, targetSpot) {
         return true;
     return mine === targetSpot;
 }
-export function moveCost(room) {
-    return SIZE_COST[room.size ?? 'medium'];
+/**
+ * ROOM GRIDS (spatial wave 2026-08-25): the spot-name-level wrappers
+ * around utilities/room-grid.ts's coordinate primitives -- everything
+ * ABOVE this line still only ever touches spot NAMES; nothing but
+ * these three functions (and Room.ensureGrid itself) ever sees a
+ * GridCoord. All three return undefined/0 when the room has no grid
+ * (THE COMPAT RULE: a spotless room never synthesizes one) or the
+ * named spot doesn't exist in it.
+ */
+export function spotCell(room, spotName) {
+    return room.ensureGrid()?.spotCells.get(spotName);
+}
+/**
+ * SEATING (player ruling 2026-08-25: "you can only be adjacent, and
+ * cannot move through, only around"). A spot's cell is the FURNITURE --
+ * the bar, the crates, the console. Nobody stands inside it, and no two
+ * bodies share a cell: each actor is seated on the nearest free ground
+ * to their spot, deterministically, so the map shows people ringed
+ * around a place instead of stacked on top of it.
+ *
+ * THE KEYSTONE IS INTACT. Nothing here is stored: `Player.atSpot` is
+ * still the only position an actor owns, and "at the bar" is still one
+ * interaction zone -- two people seated in different cells around the
+ * bar remain `sameSpot`, so talking, trading, and melee are untouched.
+ * This layer only answers "given who is where by NAME, where do their
+ * bodies physically sit", and it is recomputed on demand.
+ *
+ * Determinism: actors are seated in name order, so the same room state
+ * always produces the same seating on every machine and after any
+ * reload -- the same contract the grid itself keeps.
+ *
+ * THE OPEN FLOOR is not furniture (it is bare ground that moves, see
+ * reseatOpenFloor), so its cell seats a body like any other.
+ */
+/** Whether this exit is shut -- a Door that reports itself locked.
+ *  Duck-typed rather than `instanceof Door`: spots.ts is imported BY
+ *  models/room.ts, and a value import back into models would close a
+ *  runtime cycle. */
+function exitIsLocked(room, direction) {
+    const exit = room.exits.get(direction);
+    return typeof exit === 'object' && typeof exit?.checkIfLocked === 'function' && exit.checkIfLocked();
+}
+/** The cells of OPEN doorways -- thresholds, which a body may stand in
+ *  (player ruling 2026-08-25: "a player/npc can exist in the same
+ *  location as an unlocked door... this is essentially the threshold").
+ *  A LOCKED door is solid and stays furniture. */
+function openThresholds(room) {
+    const out = new Set();
+    const grid = room.ensureGrid();
+    if (!grid)
+        return out;
+    for (const [dir, c] of grid.exitCells.entries()) {
+        if (!exitIsLocked(room, dir))
+            out.add(key(c));
+    }
+    return out;
+}
+/** Every cell physically filled by furniture -- the full footprint of
+ *  each named place (a bar runs several cells), minus the open floor
+ *  (bare ground) and minus any OPEN doorway (a threshold you stand in,
+ *  see openThresholds). Nobody stands here and movement goes around. */
+export function furnitureCells(room) {
+    const out = new Set();
+    const grid = room.ensureGrid();
+    if (!grid)
+        return out;
+    const thresholds = openThresholds(room);
+    for (const [name, cells] of grid.spotFootprints.entries()) {
+        if (name === OPEN_FLOOR)
+            continue;
+        for (const c of cells) {
+            if (!thresholds.has(key(c)))
+                out.add(key(c));
+        }
+    }
+    return out;
+}
+/** The ONE cell a doorway is reached from: directly opposite the door,
+ *  one step in from its wall (player ruling 2026-08-25 -- "a south door
+ *  requires you can move through the cell one unit north of it"). This
+ *  is what makes a doorway a chokepoint worth holding. Undefined for
+ *  up/down exits, which have no wall to stand off, and for an approach
+ *  that would fall outside the room. */
+export function approachCellFor(room, direction) {
+    const grid = room.ensureGrid();
+    const door = grid?.exitCells.get(direction);
+    if (!grid || !door)
+        return undefined;
+    const inward = {
+        [Direction.NORTH]: [0, 1], [Direction.SOUTH]: [0, -1],
+        [Direction.WEST]: [1, 0], [Direction.EAST]: [-1, 0],
+    };
+    const step = inward[direction];
+    if (!step)
+        return undefined;
+    const c = { x: door.x + step[0], y: door.y + step[1], z: door.z };
+    if (c.x < 0 || c.y < 0 || c.x >= grid.dims.x || c.y >= grid.dims.y)
+        return undefined;
+    return c;
+}
+/**
+ * Where a body standing "at" this spot wants to be (player ruling
+ * 2026-08-25): an UNLOCKED door you stand IN -- the threshold is the
+ * place -- while a LOCKED one you stand BEFORE, on its single approach
+ * cell, which is exactly where you'd have to be to pick or force it.
+ * Every other spot seats on its own anchor. Callers still fall through
+ * nearestSeat, so a taken preference just rings outward from here.
+ */
+function seatAnchorFor(room, spotName) {
+    const grid = room.ensureGrid();
+    const anchor = grid?.spotCells.get(spotName);
+    if (!grid || !anchor)
+        return undefined;
+    for (const [dir, c] of grid.exitCells.entries()) {
+        if (key(c) !== key(anchor))
+            continue;
+        return exitIsLocked(room, dir) ? (approachCellFor(room, dir) ?? anchor) : anchor;
+    }
+    return anchor;
+}
+/**
+ * Who is standing in the way of this doorway -- in the threshold itself
+ * or in its single approach cell. A body in either one holds the door
+ * (the 2026-08-25 ruling): squeezing past is not on offer here the way
+ * it is in open floor, because there is no second route to a doorway.
+ *
+ * `mover` never blocks themselves, and neither do their OWN companions:
+ * a spirit that follows you at your heel gets seated beside you, which
+ * would routinely park it on your approach cell and wall you into the
+ * room you just walked into.
+ */
+/**
+ * A FIXTURE sitting in a doorway or on its single approach cell -- the
+ * non-living half of doorwayBlocker (playtest 2026-08-25: "I shouldn't
+ * be able to 'go' a direction if something is in the way of it").
+ * Synthesis reserves those cells so this should never fire on a
+ * generated room; it stays as the guard for hand-authored seeds, which
+ * can declare a spot anywhere they like.
+ */
+export function doorwayFurniture(room, direction) {
+    const grid = room.ensureGrid();
+    const door = grid?.exitCells.get(direction);
+    if (!grid || !door)
+        return undefined;
+    const approach = approachCellFor(room, direction);
+    const guarded = [key(door), ...(approach ? [key(approach)] : [])];
+    for (const [name, cells] of grid.spotFootprints.entries()) {
+        if (name === OPEN_FLOOR)
+            continue;
+        for (const c of cells) {
+            // A spot sitting ON an open threshold is the doorway itself
+            // (Mama Wu's "door"), not an obstruction.
+            if (key(c) === key(door))
+                continue;
+            if (guarded.includes(key(c)))
+                return name;
+        }
+    }
+    return undefined;
+}
+export function doorwayBlocker(room, direction, mover) {
+    const grid = room.ensureGrid();
+    if (!grid)
+        return undefined;
+    const door = grid.exitCells.get(direction);
+    if (!door)
+        return undefined;
+    const approach = approachCellFor(room, direction);
+    const guarded = new Set([key(door), ...(approach ? [key(approach)] : [])]);
+    const seats = seatingIn(room);
+    for (const a of room.getActors()) {
+        const other = a;
+        if (other === mover)
+            continue;
+        if (other.allyOf === mover.name)
+            continue;
+        const seat = seats.get(other.name);
+        if (seat && guarded.has(key(seat)))
+            return other;
+    }
+    return undefined;
+}
+export function seatingIn(room) {
+    const seats = new Map();
+    const grid = room.ensureGrid();
+    if (!grid)
+        return seats;
+    const standable = new Set();
+    for (let z = 0; z < grid.dims.z; z++) {
+        for (const c of levelFootprint(grid, z)) {
+            if (!isCellBlocked(grid, c))
+                standable.add(key(c));
+        }
+    }
+    const furniture = furnitureCells(room);
+    const taken = new Set();
+    const seated = [...room.getActors()]
+        .filter(a => spotOf(a) !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    // Anyone who STEPPED somewhere exact keeps that cell (Player.atCell)
+    // and is seated first, so a derived seat can never be handed the
+    // square they are already standing in.
+    for (const a of seated) {
+        const exact = a.atCell;
+        if (!exact)
+            continue;
+        const k = key(exact);
+        if (!standable.has(k) || furniture.has(k) || taken.has(k))
+            continue;
+        taken.add(k);
+        seats.set(a.name, exact);
+    }
+    for (const a of seated) {
+        if (seats.has(a.name))
+            continue;
+        const spot = spotOf(a);
+        const anchor = seatAnchorFor(room, spot);
+        if (!anchor)
+            continue;
+        // Staff stand BEHIND their fixture, customers in front of it.
+        const bias = serviceBias(room, spot, a.homeSpot === spot);
+        const seat = nearestSeat(anchor, standable, furniture, taken, bias);
+        if (!seat)
+            continue;
+        taken.add(key(seat));
+        seats.set(a.name, seat);
+    }
+    return seats;
+}
+/**
+ * Which way to lean when seating someone at a fixture (player nitpick
+ * 2026-08-25: "when furniture is placed in a room, the bartender should
+ * be on one side of it"). The service side is the one facing the
+ * NEAREST WALL -- that is where a bar's staff stand, with the room in
+ * front of them -- so staff bias that way and everyone else the
+ * opposite way. Returns undefined for the open floor and for anything
+ * with no footprint to have sides.
+ */
+function serviceBias(room, spotName, isStaff) {
+    if (spotName === OPEN_FLOOR)
+        return undefined;
+    const grid = room.ensureGrid();
+    const cells = grid?.spotFootprints.get(spotName);
+    if (!grid || !cells || cells.length === 0)
+        return undefined;
+    const cx = cells.reduce((s, c) => s + c.x, 0) / cells.length;
+    const cy = cells.reduce((s, c) => s + c.y, 0) / cells.length;
+    // Distance to each wall; the closest one is "behind" the fixture.
+    const gaps = [
+        [cx, { x: -1, y: 0, z: 0 }],
+        [grid.dims.x - 1 - cx, { x: 1, y: 0, z: 0 }],
+        [cy, { x: 0, y: -1, z: 0 }],
+        [grid.dims.y - 1 - cy, { x: 0, y: 1, z: 0 }],
+    ];
+    gaps.sort((p, q) => p[0] - q[0]);
+    const behind = gaps[0][1];
+    return isStaff ? behind : { x: -behind.x, y: -behind.y, z: 0 };
+}
+/**
+ * One tactical step (player request 2026-08-25: "move south 2"). Walks
+ * up to `count` cells in a cardinal direction from wherever the actor's
+ * body actually is, stopping at the first square it cannot enter -- a
+ * wall, furniture, uncleared terrain, or somebody standing there. No
+ * squeezing: this is a deliberate step, so it stops rather than
+ * shouldering through.
+ *
+ * Returns the cell reached and how many steps were actually taken, plus
+ * what stopped it short. Nothing is mutated -- commands/move.ts commits
+ * the result.
+ */
+export function stepFrom(room, mover, direction, count) {
+    const grid = room.ensureGrid();
+    if (!grid)
+        return { taken: 0 };
+    const start = actorCell(room, mover);
+    if (!start)
+        return { taken: 0 };
+    const delta = {
+        [Direction.NORTH]: [0, -1], [Direction.SOUTH]: [0, 1],
+        [Direction.WEST]: [-1, 0], [Direction.EAST]: [1, 0],
+    };
+    const step = delta[direction];
+    if (!step)
+        return { taken: 0 };
+    const standable = new Set();
+    for (const c of levelFootprint(grid, start.z)) {
+        if (!isCellBlocked(grid, c))
+            standable.add(key(c));
+    }
+    const furniture = furnitureCells(room);
+    const bodies = occupiedCells(room, mover);
+    let cur = start;
+    let taken = 0;
+    for (let i = 0; i < count; i++) {
+        const next = { x: cur.x + step[0], y: cur.y + step[1], z: cur.z };
+        const k = key(next);
+        if (!standable.has(k)) {
+            // Out of the footprint is a wall; inside it but unstandable is
+            // terrain (isCellBlocked is the only other thing that removes a
+            // cell from `standable`).
+            const inBounds = next.x >= 0 && next.y >= 0 && next.x < grid.dims.x && next.y < grid.dims.y;
+            return { cell: cur, taken, blockedBy: inBounds ? 'terrain' : 'wall' };
+        }
+        if (furniture.has(k))
+            return { cell: cur, taken, blockedBy: 'furniture' };
+        if (bodies.has(k))
+            return { cell: cur, taken, blockedBy: 'someone' };
+        cur = next;
+        taken++;
+    }
+    return { cell: cur, taken };
+}
+/**
+ * The named place a stepped-to cell counts as being "at" -- whichever
+ * fixture the cell touches (its own footprint or any neighbour of it),
+ * else the open floor. This is what keeps `atSpot` authoritative for
+ * every interaction while the body stands on an arbitrary square:
+ * step up beside the bar and you are AT the bar, step away and you are
+ * on open ground.
+ */
+export function spotForCell(room, cell) {
+    const grid = room.ensureGrid();
+    if (!grid)
+        return OPEN_FLOOR;
+    let best;
+    let bestDist = Infinity;
+    for (const [name, cells] of grid.spotFootprints.entries()) {
+        if (name === OPEN_FLOOR)
+            continue;
+        for (const c of cells) {
+            if (c.z !== cell.z)
+                continue;
+            const d = Math.max(Math.abs(c.x - cell.x), Math.abs(c.y - cell.y));
+            if (d <= 1 && d < bestDist) {
+                bestDist = d;
+                best = name;
+            }
+        }
+    }
+    return best ?? OPEN_FLOOR;
+}
+/** Closest free ground to `anchor`, rings outward, deterministic within
+ *  a ring. Returns undefined only if the room has no free ground at all
+ *  -- callers treat that as "no body to draw", never as an error. */
+function nearestSeat(anchor, standable, furniture, taken, bias) {
+    const free = (c) => {
+        const k = key(c);
+        return standable.has(k) && !furniture.has(k) && !taken.has(k);
+    };
+    if (free(anchor))
+        return anchor;
+    for (let r = 1; r <= 12; r++) {
+        const ring = [];
+        for (let dx = -r; dx <= r; dx++) {
+            for (let dy = -r; dy <= r; dy++) {
+                if (Math.max(Math.abs(dx), Math.abs(dy)) !== r)
+                    continue;
+                ring.push({ x: anchor.x + dx, y: anchor.y + dy, z: anchor.z });
+            }
+        }
+        // Within a ring, prefer the side the caller asked for -- higher dot
+        // product with the bias vector wins. Ties keep ring order, so the
+        // result stays deterministic.
+        const ordered = bias
+            ? [...ring].sort((p, q) => ((q.x - anchor.x) * bias.x + (q.y - anchor.y) * bias.y)
+                - ((p.x - anchor.x) * bias.x + (p.y - anchor.y) * bias.y))
+            : ring;
+        const hit = ordered.find(free);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * A cell `mover` could stand in at or beside `target` -- the general
+ * form of seating, for walking to something that is not a named place.
+ * Used by "move to <body>": the fallen keep a cell but no spot, and you
+ * still need to be able to walk over and go through their pockets.
+ */
+export function standingRoomNear(room, target, mover) {
+    const grid = room.ensureGrid();
+    if (!grid)
+        return undefined;
+    const standable = new Set();
+    for (let z = 0; z < grid.dims.z; z++) {
+        for (const c of levelFootprint(grid, z)) {
+            if (!isCellBlocked(grid, c))
+                standable.add(key(c));
+        }
+    }
+    const taken = new Set();
+    for (const [name, c] of seatingIn(room).entries()) {
+        if (name !== mover.name)
+            taken.add(key(c));
+    }
+    return nearestSeat(target, standable, furnitureCells(room), taken);
+}
+/** Where this actor's BODY sits (see seatingIn) -- undefined when they
+ *  are circulating, off-meat, or the room has no grid. Pass a seating
+ *  map when resolving several actors, so it's computed once. */
+export function actorCell(room, actor, seats) {
+    if (spotOf(actor) === undefined)
+        return undefined;
+    return (seats ?? seatingIn(room)).get(actor.name);
+}
+/** Everything you have to walk AROUND rather than through: other
+ *  people's bodies and the furniture itself. findPath treats these as a
+ *  soft block (see its pass order) so they steer a route without ever
+ *  making a destination unreachable. `mover` is always excluded -- you
+ *  never block yourself. */
+export function occupiedCells(room, mover) {
+    const out = furnitureCells(room);
+    // THE FALLEN DON'T BLOCK (player ruling 2026-08-25: "bodies don't
+    // block movement, they can just be walked over") -- neither corpses
+    // nor the knocked-out, who are lying in the same square for the same
+    // reason. Only people still on their feet are something to go around.
+    const down = new Set(room.getActors().filter(a => a.isIncapacitated()).map(a => a.name));
+    for (const [name, c] of seatingIn(room).entries()) {
+        if (mover && name === mover.name)
+            continue;
+        if (down.has(name))
+            continue;
+        out.add(key(c));
+    }
+    return out;
+}
+/** The cell `mover` would end up in on arriving at `spotName` -- their
+ *  seat around that fixture, with everyone else's seats already taken.
+ *  This, not the fixture's anchor, is where movement actually paths to:
+ *  the anchor is furniture now, and nobody stands inside the bar. */
+export function seatFor(room, spotName, mover) {
+    const grid = room.ensureGrid();
+    const anchor = seatAnchorFor(room, spotName);
+    if (!grid || !anchor)
+        return undefined;
+    const taken = new Set();
+    for (const [name, c] of seatingIn(room).entries()) {
+        if (name !== mover.name)
+            taken.add(key(c));
+    }
+    const standable = new Set();
+    for (let z = 0; z < grid.dims.z; z++) {
+        for (const c of levelFootprint(grid, z)) {
+            if (!isCellBlocked(grid, c))
+                standable.add(key(c));
+        }
+    }
+    return nearestSeat(anchor, standable, furnitureCells(room), taken);
+}
+/** Straight-line meters between two actors' BODIES -- the distance
+ *  combat should use, now that people stand beside their furniture
+ *  rather than inside it. Falls back to their spots' own separation
+ *  when either has no seat (circulating, or a gridless room). */
+export function actorDistanceMeters(room, a, b) {
+    const seats = seatingIn(room);
+    const ca = actorCell(room, a, seats);
+    const cb = actorCell(room, b, seats);
+    if (ca && cb)
+        return distanceMeters(ca, cb);
+    const sa = spotOf(a);
+    const sb = spotOf(b);
+    return sa && sb ? spotDistanceMeters(room, sa, sb) : 0;
+}
+/** The walkable route between two spots, or undefined when terrain
+ *  blocks every route (see move.ts / ensureAtSpot for the refusal).
+ *  Purely geometric -- bodies and furniture are NOT considered, because
+ *  the only thing that may hard-refuse a crossing is terrain; see
+ *  routeForMove for the version movement actually walks. */
+export function pathBetweenSpots(room, from, to) {
+    const grid = room.ensureGrid();
+    const a = grid?.spotCells.get(from);
+    const b = grid?.spotCells.get(to);
+    if (!grid || !a || !b)
+        return undefined;
+    return findPath(grid, a, b);
+}
+/**
+ * The route a body actually walks: seat to seat, steering around other
+ * people and around the furniture (player ruling 2026-08-25 -- "cannot
+ * move through, only around"). Reports whether it had to SQUEEZE past
+ * somebody, which move.ts narrates.
+ *
+ * Bodies and furniture are soft blocks by design (see findPath's pass
+ * order): a crowded room slows you down and makes you go the long way,
+ * but it can never strand you. Only terrain hard-refuses, and that
+ * check stays in pathBetweenSpots where it always was.
+ */
+export function routeForMove(room, mover, toSpot) {
+    const grid = room.ensureGrid();
+    const mine = spotOf(mover);
+    if (!grid || mine === undefined)
+        return { squeezed: false };
+    const from = actorCell(room, mover) ?? grid.spotCells.get(mine);
+    const to = seatFor(room, toSpot, mover) ?? grid.spotCells.get(toSpot);
+    if (!from || !to)
+        return { squeezed: false };
+    const bodies = occupiedCells(room, mover);
+    bodies.delete(key(to)); // your own destination is never in your way
+    const path = findPath(grid, from, to, bodies);
+    return { path, squeezed: path ? pathSqueezes(path, bodies) : false };
+}
+export function spotDistanceMeters(room, from, to) {
+    const grid = room.ensureGrid();
+    const a = grid?.spotCells.get(from);
+    const b = grid?.spotCells.get(to);
+    if (!grid || !a || !b)
+        return 0;
+    return distanceMeters(a, b);
+}
+/** Cover between two spots (see room-grid.ts coverBetween) -- honors a
+ *  cover-tagged DEFENDER spot first (the same check combat-exchange.ts
+ *  makes), falling back to a terrain occluder on the line between. */
+export function spotCoverBetween(room, from, to) {
+    const grid = room.ensureGrid();
+    const tagged = (room.spots ?? []).find(s => s.name === to)?.tags?.find(t => t.startsWith('cover'));
+    if (tagged)
+        return tagged === 'cover-good' ? 'good' : 'partial';
+    const a = grid?.spotCells.get(from);
+    const b = grid?.spotCells.get(to);
+    if (!grid || !a || !b)
+        return undefined;
+    return coverBetween(grid, a, b);
+}
+/** How many z-levels the route between two spots climbs via a risky
+ *  'climb' link (stairs/ladder never roll anything) -- undefined when
+ *  the crossing never touches one. See move.ts's Athletics check. */
+export function spotClimbSteps(room, from, to) {
+    const grid = room.ensureGrid();
+    const a = grid?.spotCells.get(from);
+    const b = grid?.spotCells.get(to);
+    if (!grid || !a || !b)
+        return undefined;
+    const path = findPath(grid, a, b);
+    return path ? pathClimbSteps(grid, path) : undefined;
+}
+/**
+ * Re-seats the OPEN FLOOR on the emptiest ground in the room, and
+ * returns whether it moved (playtest 2026-08-25: "'move away' is an
+ * actual location" -- it was pinned to one synthesized cell near the
+ * centroid, so peeling off always put you in the same square no matter
+ * who was standing where). "Away" should mean AWAY: the cell that
+ * maximises distance from the people you're stepping back from, then
+ * from the room's fixtures.
+ *
+ * Scored lexicographically -- people first, furniture as the
+ * tie-break -- over cells that exist, aren't sealed behind terrain,
+ * and that `mover` can actually reach. Anyone ALREADY on the open
+ * floor is excluded from the avoid-set: they're the ones this cell
+ * belongs to, and counting them would have it flee itself.
+ *
+ * Callers must invoke this BEFORE setting `atSpot = OPEN_FLOOR`; the
+ * grid is transient display/geometry state (never serialized), so a
+ * reload simply re-derives the synthesized default -- see the
+ * determinism contract in room-grid.ts.
+ */
+export function reseatOpenFloor(room, mover) {
+    const grid = room.ensureGrid();
+    if (!grid)
+        return false;
+    const current = grid.spotCells.get(OPEN_FLOOR);
+    const fromSpot = spotOf(mover);
+    const from = fromSpot ? grid.spotCells.get(fromSpot) : undefined;
+    const spotCells = [];
+    for (const [name, c] of grid.spotCells.entries()) {
+        if (name !== OPEN_FLOOR)
+            spotCells.push(c);
+    }
+    const peopleCells = [];
+    for (const a of room.getActors()) {
+        const other = a;
+        if (other === mover)
+            continue;
+        const s = spotOf(other);
+        if (!s || s === OPEN_FLOOR)
+            continue;
+        const c = grid.spotCells.get(s);
+        if (c)
+            peopleCells.push(c);
+    }
+    const minTo = (c, set) => set.length === 0 ? Infinity : Math.min(...set.map(o => distanceMeters(c, o)));
+    let best;
+    let bestScore = [-1, -1];
+    for (const c of levelFootprint(grid, 0)) {
+        if (spotCells.some(s => key(s) === key(c)))
+            continue; // a named place isn't open floor
+        if (from && !findPath(grid, from, c))
+            continue; // sealed off, or unreachable
+        const score = [minTo(c, peopleCells), minTo(c, spotCells)];
+        if (score[0] > bestScore[0] || (score[0] === bestScore[0] && score[1] > bestScore[1])) {
+            bestScore = score;
+            best = c;
+        }
+    }
+    if (!best)
+        return false;
+    grid.spotCells.set(OPEN_FLOOR, best);
+    return current === undefined || key(current) !== key(best);
+}
+/** Which terrain region is sealing the route from `from` to `to`, and
+ *  the Puzzle that clears it (for the bypass verb) -- undefined when
+ *  the room has no grid, or (a synthesis edge case) a region blocks
+ *  the path but its puzzle can no longer be found. */
+export function blockingRegion(room, from, to) {
+    const grid = room.ensureGrid();
+    const a = grid?.spotCells.get(from);
+    const b = grid?.spotCells.get(to);
+    if (!grid || !a || !b)
+        return undefined;
+    const region = blockingRegionFor(grid, a, b);
+    if (!region)
+        return undefined;
+    const target = room.getPuzzleTargets().find(t => t.puzzle.name === region.puzzleName);
+    return target ? { region, puzzle: target.puzzle } : undefined;
+}
+/** One refusal voice for a terrain-blocked crossing -- always names
+ *  the obstacle AND the mechanism (the safe "solve" route, plus the
+ *  puzzle's own bypass verb when it has one). */
+export function terrainRefusal(region, targetLabel, puzzle) {
+    const verb = puzzle?.getBypassVerb();
+    const altRoute = verb ? `, or "${verb}" past it` : '';
+    return `The ${region.label} seals the way to the ${targetLabel} -- clear it ("solve")${altRoute}.`;
 }
 /**
  * The spot an exit is reachable from. Seed-declared (room.exitSpots)
@@ -112,24 +736,88 @@ export function exitSpot(room, direction) {
     const declared = room.exitSpots.get(direction);
     if (declared && room.spots.some(s => s.name === declared))
         return declared;
-    const doorish = room.spots.find(s => /door|entrance|entry|threshold|gate/i.test(s.name));
-    return doorish?.name;
+    // One doorway-named spot, one exit (Room.namedDoorwayFor). Answering
+    // "door" for EVERY direction is what put Circuit Bazaar's door in the
+    // middle of the floor; an exit this spot doesn't belong to is simply
+    // ungated, which is the pre-spots behaviour and safe.
+    return room.namedDoorwayFor(direction);
 }
 /** Where an arrival through `direction` (the direction WALKED, from the
  * far side) stands: at this room's matching exit spot; else the room's
  * doorway-named spot; else its first spot (a positioned room always
  * positions the arriving player -- that's what makes gating bite). */
+/**
+ * Where you physically land walking in through `arrivedFrom`: IN the
+ * doorway you just came through (player ruling 2026-08-25 -- "when I
+ * enter the night market from the east, I should arrive on the western
+ * entrance"). The threshold is a standable cell now, so arrival no
+ * longer has to be rounded to whichever named place happens to own that
+ * exit -- Night Market's seed puts three of its exits "at the stalls",
+ * which is right for LEAVING (that's the spot you must stand at to go)
+ * but wrong for arriving, and used to materialise you ten metres inside
+ * the room.
+ *
+ * Returns the exact cell plus the spot it counts as, or undefined when
+ * the room has no grid, the direction has no doorway, or someone is
+ * already standing in it -- all of which fall back to entrySpotFor.
+ */
+export function arrivalAt(room, arrivedFrom) {
+    if (arrivedFrom === undefined)
+        return undefined;
+    const grid = room.ensureGrid();
+    if (!grid)
+        return undefined;
+    const door = grid.exitCells.get(room.getOppositeDirection(arrivedFrom));
+    if (!door)
+        return undefined;
+    const k = key(door);
+    if (isCellBlocked(grid, door) || furnitureCells(room).has(k))
+        return undefined;
+    for (const c of seatingIn(room).values()) {
+        if (key(c) === k)
+            return undefined; // someone's in the doorway
+    }
+    return { cell: door, spot: spotForCell(room, door) };
+}
 export function entrySpotFor(room, arrivedFrom) {
     if (!spotsActive(room))
         return undefined;
     if (arrivedFrom !== undefined) {
-        const viaExit = exitSpot(room, room.getOppositeDirection(arrivedFrom));
+        const back = room.getOppositeDirection(arrivedFrom);
+        const viaExit = exitSpot(room, back);
         if (viaExit)
             return viaExit;
+        // No spot owns the door you just came through -- so land at
+        // whichever place is NEAREST it, rather than at some unrelated
+        // doorway on the far wall (playtest 2026-08-25: walking west into
+        // Circuit Bazaar dropped the player at the north of the room).
+        const nearest = nearestSpotToExit(room, back);
+        if (nearest)
+            return nearest;
     }
     const doorish = room.spots.find(s => /door|entrance|entry|threshold|gate/i.test(s.name));
     return doorish?.name ?? room.spots[0]?.name;
 }
+/** The named place closest to a given exit's doorway cell. */
+function nearestSpotToExit(room, direction) {
+    const grid = room.ensureGrid();
+    const door = grid?.exitCells.get(direction);
+    if (!grid || !door)
+        return undefined;
+    let best;
+    let bestDist = Infinity;
+    for (const spot of room.spots ?? []) {
+        const c = grid.spotCells.get(spot.name);
+        if (!c)
+            continue;
+        const d = distanceMeters(c, door);
+        if (d < bestDist) {
+            bestDist = d;
+            best = spot.name;
+        }
+    }
+    return best;
+}
 /** One refusal voice for every spot gate -- always names the cure. */
 export function spotRefusal(targetLabel, spotName) {
     return `${targetLabel} is across the room at the ${spotName} -- "move to ${spotName}" first.`;
@@ -140,16 +828,34 @@ export function spotRefusal(targetLabel, spotName) {
  * that you CAN'T do it from across the room, not that you must type two
  * commands). Mid-exchange nobody strolls: refuse like go.ts does, and
  * the Phase-2 crossing machinery will make it cost instead.
+ *
+ * ROOM GRIDS (spatial wave 2026-08-25): checks the route FIRST -- an
+ * uncleared barrier refuses the crossing even out of combat, always
+ * naming the obstacle and the mechanism (utilities/room-grid.ts /
+ * terrainRefusal). Rooms with no synthesized grid (still the common
+ * case -- most spotted rooms carry no terrain hints) never pay for the
+ * pathfind: spotDistanceMeters/pathBetweenSpots short-circuit to
+ * "reachable" the same instant canReach already would have.
  */
 export function ensureAtSpot(actor, targetSpot) {
     if (canReach(actor, targetSpot))
         return {};
+    const room = actor.currentLocation;
+    const mine = spotOf(actor); // canReach's own check guarantees this is defined here
+    if (room.ensureGrid() && !pathBetweenSpots(room, mine, targetSpot)) {
+        const blocked = blockingRegion(room, mine, targetSpot);
+        if (blocked)
+            return { refusal: terrainRefusal(blocked.region, targetSpot, blocked.puzzle) };
+    }
     if (actor.inExchange) {
         return { refusal: `That's over at the ${targetSpot} -- and you're mid-exchange. Crossing open floor now means eating lead.` };
     }
+    if (targetSpot === OPEN_FLOOR)
+        reseatOpenFloor(room, actor);
+    const long = room.ensureGrid() && spotDistanceMeters(room, mine, targetSpot) >= 12;
     actor.atSpot = targetSpot;
     actor.performAction('moves to', `the ${targetSpot}`);
-    return { line: `You cross to the ${targetSpot}.` };
+    return { line: long ? `You cross the long way to the ${targetSpot}.` : `You cross to the ${targetSpot}.` };
 }
 // Place names render in this color wherever they appear -- the classic
 // MUD "interactive keyword" convention (player request: places should
@@ -201,6 +907,166 @@ export function highlightSpots(room, text) {
 // People render in this color wherever prose names them -- green, the
 // color NPC speech already wears.
 export const ACTOR_COLOR = 'green';
+/** The RAW cover threshold guarding a spot (p.135-136: Normal 2 for
+ *  partial cover, Hidden 4 for good) -- 0 when nothing tucks there. */
+export function coverThreshold(room, spotName) {
+    if (spotName === undefined || spotName === OPEN_FLOOR)
+        return 0;
+    const tags = (room.spots ?? []).find(s => s.name === spotName)?.tags ?? [];
+    if (tags.includes('cover-good'))
+        return 4;
+    return tags.some(t => t.startsWith('cover')) ? 2 : 0;
+}
+/**
+ * PERCEPTION AT RANGE (SR5 p.135-136 Perception Test Modifiers,
+ * RAG-verified): "object/sound not in immediate vicinity" -2, "object/
+ * sound far away" -3. Canon names the bands but never puts meters on
+ * them, so the metre cuts are OURS -- pinned to the scale the game
+ * already speaks in, SR5 p.185's pistol brackets: short range 5 m is
+ * "immediate vicinity", medium 20 m is where "far away" begins.
+ *
+ * This became load-bearing with the 2026-08-25 room resize: a `huge`
+ * room is 32x22 m, so a stallholder clocking a runner the instant they
+ * step through the far door was the room being too small, not the NPC
+ * being sharp (playtest: "would Skitter even notice me?").
+ */
+export const IMMEDIATE_VICINITY_M = 5;
+export const FAR_AWAY_M = 20;
+export function perceptionRangeModifier(meters) {
+    if (meters <= IMMEDIATE_VICINITY_M)
+        return 0;
+    return meters >= FAR_AWAY_M ? -3 : -2;
+}
+/**
+ * The Perception threshold to pick someone out: p.136's "Normal" 2 for
+ * a pedestrian, 4 for anyone in good cover -- and ZERO for a person
+ * standing in the open inside `FAR_AWAY_M`, where seeing them is not a
+ * test at all.
+ *
+ * That last clause is deliberate calibration, not laziness. Requiring a
+ * test past `IMMEDIATE_VICINITY_M` was tried first and was far too
+ * blind: it had the regulars in a 24x16 m bar failing to register
+ * someone walking in twelve metres away. Canon's -2/-3 are about
+ * resolving DETAIL at range, not about whether a human body registers
+ * at all, so the test starts where "far away" does. A 32x22 m market
+ * still hides you from the far stall; a bar does not.
+ */
+export function noticeThreshold(room, target, meters) {
+    const cover = coverThreshold(room, spotOf(target));
+    if (cover > 0)
+        return cover;
+    return meters < FAR_AWAY_M ? 0 : 2;
+}
+/**
+ * Whether `observer` would register `target` at all right now, WITHOUT
+ * rolling -- the passive read used by NPC reactions and by the room
+ * map. Their Perception pool stands in for an average roll (pool/4,
+ * SR5's own rule of thumb of one hit per four dice) so a sharp-eyed
+ * fixer notices what a distracted teenager misses, and the range
+ * modifier from p.135-136 applies.
+ *
+ * Deliberately NOT a dice roll: this fires on every movement event in
+ * the room, and a random result would have NPCs blinking in and out of
+ * awareness between one step and the next.
+ */
+export function wouldNotice(observer, target) {
+    if (!observer.canPerceive(target))
+        return false;
+    const room = observer.currentLocation;
+    if (!spotsActive(room) || room !== target.currentLocation)
+        return true;
+    if (spotOf(observer) === undefined || spotOf(target) === undefined)
+        return true;
+    const meters = actorDistanceMeters(room, observer, target);
+    const threshold = noticeThreshold(room, target, meters);
+    if (threshold === 0)
+        return true;
+    const perception = observer.skillRating('perception');
+    const pool = Math.max(1, observer.intuition + (perception > 0 ? perception : -1)
+        + observer.augBonus('perception'));
+    return Math.floor(pool / 4) + perceptionRangeModifier(meters) >= threshold;
+}
+export function voiceBandFor(meters) {
+    if (meters <= IMMEDIATE_VICINITY_M)
+        return 'conversation';
+    if (meters <= 12)
+        return 'raised';
+    if (meters < FAR_AWAY_M)
+        return 'shout';
+    return 'yell';
+}
+/** The tag appended to speech that has to travel -- empty at
+ *  conversational range, where it would just be noise. */
+export function voiceTag(band) {
+    switch (band) {
+        case 'conversation': return '';
+        case 'raised': return ' (raising their voice across the gap)';
+        case 'shout': return ' (shouting across the room)';
+        case 'yell': return ' (bellowing the length of the room)';
+    }
+}
+/** Records that `viewer` has picked `target` out of their cover here --
+ *  a spot they keep (Room.revealedBy) so every later read, the room
+ *  map included, knows they've been seen. */
+export function revealActor(room, viewer, target) {
+    const seen = room.revealedBy.get(viewer.name) ?? new Set();
+    seen.add(target.name);
+    room.revealedBy.set(viewer.name, seen);
+}
+/** Everyone `viewer` has already picked out of cover in this room. */
+export function revealedTo(room, viewer) {
+    return room.revealedBy.get(viewer.name) ?? new Set();
+}
+/** Runs a Perception result against every covered occupant, banking
+ *  whoever it beats. Called by the verbs that constitute LOOKING (look,
+ *  search) so the room map reflects what the player has actually made
+ *  out. Returns the newly-revealed actors, for callers that narrate. */
+export function revealWithPerception(room, viewer, hits) {
+    if (!spotsActive(room))
+        return [];
+    const already = revealedTo(room, viewer);
+    const found = [];
+    for (const a of room.getActors()) {
+        const other = a;
+        if (other === viewer || already.has(other.name) || !viewer.canPerceive(other))
+            continue;
+        const meters = actorDistanceMeters(room, viewer, other);
+        const threshold = noticeThreshold(room, other, meters);
+        // Range is a DICE modifier in canon (p.135-136), applied here to
+        // the hits already rolled -- one roll covers the whole sweep, and
+        // re-rolling per target would let a single "look" produce a
+        // different Perception result for every person in the room.
+        if (threshold === 0 || hits + perceptionRangeModifier(meters) < threshold)
+            continue;
+        revealActor(room, viewer, other);
+        found.push(other);
+    }
+    return found;
+}
+/**
+ * Actors in `room` visible to `viewer` without a fresh roll: the viewer
+ * first, then anyone perceivable who is either standing in the open or
+ * has ALREADY been picked out of their cover (Room.revealedBy -- see
+ * revealWithPerception). Shared by highlightActors (prose) and
+ * utilities/room-view.ts (the room minimap). Coloring or drawing
+ * someone still unspotted would hand over a presence the Perception
+ * test is there to guard.
+ */
+export function visibleActorsIn(room, viewer) {
+    const out = [viewer];
+    const revealed = revealedTo(room, viewer);
+    for (const a of room.getActors()) {
+        if (a === viewer || !viewer.canPerceive(a))
+            continue;
+        const other = a;
+        // Already picked out once, stays picked out -- you don't un-see
+        // someone. Otherwise they must be close enough (and clear enough of
+        // cover) to register without a deliberate look.
+        if (revealed.has(other.name) || wouldNotice(viewer, other))
+            out.push(other);
+    }
+    return out;
+}
 /**
  * Colors the names of PRESENT, OBVIOUS people in a room's prose (player
  * request: places got the keyword treatment; actual NPCs deserve one
@@ -214,16 +1080,9 @@ export function highlightActors(room, text, viewer) {
     let out = text;
     const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const paint = (m) => `{${ACTOR_COLOR}-fg}${m}{/${ACTOR_COLOR}-fg}`;
-    for (const a of room.getActors()) {
-        if (a === viewer || !viewer.canPerceive(a))
+    for (const a of visibleActorsIn(room, viewer)) {
+        if (a === viewer)
             continue;
-        // Obvious only: circulating, on the open floor, or at an untagged spot.
-        const s = spotOf(a);
-        if (s !== undefined && s !== OPEN_FLOOR) {
-            const covered = (room.spots ?? []).some(sp => sp.name === s && (sp.tags ?? []).some(t => t.startsWith('cover')));
-            if (covered)
-                continue;
-        }
         const full = new RegExp(`\\b(${esc(a.name)})\\b`);
         if (full.test(out)) {
             out = out.replace(full, paint);
@@ -254,16 +1113,23 @@ export function highlightActors(room, text, viewer) {
 export function whoIsWhereLine(room, viewer, hits) {
     if (!spotsActive(room))
         return '';
+    // A read that CLEARS the threshold is banked, not just printed: the
+    // room map has no roll of its own and reads Room.revealedBy instead
+    // (player request 2026-08-25 -- someone you've spotted should stay
+    // spotted). Anyone already revealed stays visible on later looks even
+    // if this particular roll was poor -- you don't un-see a sniper.
+    if (hits !== undefined)
+        revealWithPerception(room, viewer, hits);
+    const revealed = revealedTo(room, viewer);
     const actors = room.getActors().filter(a => a === viewer || viewer.canPerceive(a));
     const viewerSpot = spotOf(viewer);
     const parts = [];
     for (const s of room.spots) {
         let here = actors.filter(a => a.atSpot === s.name);
         if (hits !== undefined && s.name !== viewerSpot) {
-            const covered = (s.tags ?? []).some(t => t.startsWith('cover'));
-            const threshold = (s.tags ?? []).includes('cover-good') ? 4 : covered ? 2 : 0;
-            if (threshold > 0 && hits < threshold) {
-                here = here.filter(a => a === viewer);
+            const threshold = coverThreshold(room, s.name);
+            if (threshold > 0) {
+                here = here.filter(a => a === viewer || revealed.has(a.name));
             }
         }
         if (here.length === 0)