@polycode-projects/the-mechanical-code-talker 5.0.6 → 5.0.7

package/src/services/mudiii-viz.mjs

@@ -1,5 +1,5 @@
-// mudiii-viz.mjs — mudiii.html: the one-player town-square demo PLAN_MUD_MUDIII.md
-// describes, over a real three.js scene rather than mud.html's canvas-drawn
+// mudiii-viz.mjs — mudiii.html: the one-player town-square demo, over a real
+// three.js scene rather than mud.html's canvas-drawn
 // room boxes. mud.html's whole control deck carries over unchanged (same
 // ids, same ranges, same defaults — see MUDIII_STYLE and renderMudiiiHtml's
 // own header below for the two sliders' new labels); what mudiii adds is a
@@ -23,27 +23,23 @@
 // the map panel, the HUD, the deck or the chat down with it.
 //
 // Deliberately absent, all P2P (mud.html's #statePill, share/join buttons,
-// the share overlay, the wave button, the compass ring): this is the
-// 1-player page. A later document adds sharing back from the same bundle.
+// the share overlay, the wave button): this is the 1-player page. A later
+// document adds sharing back from the same bundle.
 //
-// Two corrections applied against PLAN_MUD_MUDIII.md's own text (see
-// AGENTS.md/the dispatch brief this track was built from): the page
-// publishes through the ONE `globalThis.tmct` surface (tmct-surface.mjs),
-// never a page-scoped `tmctMudiii` bag; and `createTicker`/`createSerialQueue`
-// are spliced into the page script from viz-ticker.mjs, not carried by the
-// browser entry.
+// The page publishes through the ONE `globalThis.tmct` surface
+// (tmct-surface.mjs), never a page-scoped bag of its own, and
+// `createTicker`/`createSerialQueue` are spliced into the page script from
+// viz-ticker.mjs rather than carried by the browser entry.
 //
-// A THIRD correction, found while wiring the deck's own play control: the
-// brief's "one createTicker per agent" does not fit the engine contract it
-// was written against. `runPredatorPreyTick(memoryDir, opts)` returns
+// One ticker drives the whole world, not one per agent:
+// `runPredatorPreyTick(memoryDir, opts)` returns
 // `{ turn, agents, items, ecology }` for the WHOLE WORLD in one call — it has
 // no per-character entry point the way mud-turn.mjs's `runMudTurn(character,
 // ...)` does, so there is nothing for a second or third ticker to drive that
 // the first one has not already advanced. This page runs ONE shared ticker
 // for the whole simulation, serialized through the same createSerialQueue
-// mud.html uses for its own multi-pane writes; every HUD card still reads
-// its own agent's slice of the one tick result, which is what "per agent"
-// was actually asking for.
+// mud.html uses for its own multi-pane writes; every HUD card reads its own
+// agent's slice of the one tick result.
 import {
   THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, scenarioLabel,
   rowsForWorld, appendLogLine, wordBeforeCursor, demoEyebrowHtml, EYEBROW_LINKS_CSS,
@@ -54,6 +50,7 @@ import {
   pillCandidates, matchPills, pillCompleteMarkup, createPillComplete, PILL_COMPLETE_CSS,
 } from "./pill-complete.mjs";
 import { DEFAULT_GAME_CONFIG } from "../domain/game-config.mjs";
+import { DEFAULT_FACING, DEFAULT_GRID_SIZE } from "../domain/town-square-world.mjs";
 import { believedFactSentence } from "./mudiii-turn.mjs";
 
 // The scene module and this one import each other: this file embeds the
@@ -79,11 +76,10 @@ const NPC_COUNT_LABELLED = [1, 5, 10];
 const DEFAULT_NPC_COUNT = 2;
 const DEFAULT_DELAY_MS = 220;
 const DEFAULT_MAX_TURNS = 400;
-// test/fixtures/mudiii-ticks.json's own board size — the fallback for a
-// scenario that names no gridSize of its own.
-const DEFAULT_GRID_SIZE = 12;
-const DEFAULT_FACING = "south";
 const CAMERA_MODES = ["follow", "pov", "overhead"];
+// Every export below except renderMudiiiHtml is spliced by `.toString()` into
+// a generated script that shares no scope with this module, so none of them
+// may read a binding declared up here. mudiii-viz.test.mjs holds the line.
 // The ring reads ABSOLUTE, not relative to whichever way an agent happens to
 // face: every other direction word on this page is a compass point (a told
 // fact says "the goblin is east", the map is north-up), and driveRequest takes
@@ -221,6 +217,48 @@ export function occupiedCells(agents, items) {
   return cells;
 }
 
+/** Who and what stands where right now, as `{ subject, cell }[]` sorted by
+ *  subject — the edit panel's own read of a fact list that carries the whole
+ *  tape rather than a board.
+ *
+ *  The engine stamps each turn's placement row `<id>@turn<N>`, or
+ *  `<id>@epoch<E>@turn<N>` once a reset has moved the epoch on, so a raw
+ *  `mgx:currently-in` sweep returns one row per agent per turn played. This
+ *  folds them to the latest row per base subject by `(epoch, turn)`, the same
+ *  order the engine's own fold ranks by. A bare subject is the world's
+ *  authored placement — every prop is one — and ranks below any stamped row
+ *  for the same base rather than competing with it.
+ *
+ *  Anything carrying `mgx:eaten-by` or `mgx:starved` is dropped: it stood
+ *  somewhere once, and the panel is asked where things stand now. Pure,
+ *  self-contained. */
+export function currentPlacementsFrom(rows) {
+  const STAMP = /^(.*?)(?:@epoch(\d+))?@turn(\d+)$/;
+  const latest = new Map();
+  const gone = new Set();
+  for (const row of rows || []) {
+    if (!row || !row.subject) continue;
+    const match = STAMP.exec(String(row.subject));
+    const base = match ? match[1] : String(row.subject);
+    if (row.predicate === "mgx:eaten-by" || row.predicate === "mgx:starved") {
+      gone.add(base);
+      continue;
+    }
+    if (row.predicate !== "mgx:currently-in") continue;
+    const epoch = match ? Number(match[2] || 0) : -1;
+    const turn = match ? Number(match[3]) : -1;
+    const prior = latest.get(base);
+    if (prior && (prior.epoch > epoch || (prior.epoch === epoch && prior.turn > turn))) continue;
+    latest.set(base, { epoch, turn, cell: row.object });
+  }
+  const placements = [];
+  for (const [subject, entry] of latest) {
+    if (!gone.has(subject)) placements.push({ subject, cell: entry.cell });
+  }
+  placements.sort((a, b) => a.subject.localeCompare(b.subject));
+  return placements;
+}
+
 /** Why a click-to-move or a food placement on `cell` would be refused, or
  *  null when it is clear — `"cell-4-3 is blocked"`, worded once so both the
  *  3D raycast click and a typed "go there" chat verb read the same refusal.
@@ -246,16 +284,40 @@ export function blockedCellReason(cell, props, agents) {
  *  `cellToWorld` does.
  *
  *  "overhead" ignores `agent` entirely and looks straight down at the
- *  board's own centre. "follow" sits back and above the agent's cell, offset
- *  opposite its facing, looking at the agent. "pov" sits AT the agent's cell
- *  at eye height, looking the way it is facing. Returns null when a
- *  non-overhead mode is asked for with no agent (or an agent standing on no
- *  cell) to rig against. Pure, self-contained — calls `cellToWorld` by bare
- *  name, spliced alongside it. */
-export function cameraRigFor(mode, agent, gridSize) {
+ *  board's own centre, high enough that the whole board fits the canvas
+ *  `view` describes (`{ aspect, fovDegrees }`, the live camera's own two
+ *  numbers). "follow" sits back and above the agent's cell, offset opposite
+ *  its facing, looking at the agent. "pov" sits AT the agent's cell at eye
+ *  height, looking the way it is facing. Returns null when a non-overhead
+ *  mode is asked for with no agent (or an agent standing on no cell) to rig
+ *  against. Pure, self-contained — calls `cellToWorld` by bare name, spliced
+ *  alongside it. */
+export function cameraRigFor(mode, agent, gridSize, view) {
   const cellSize = 1;
+  // Every fallback here is written out rather than read from this module's own
+  // constants: the browser runs a `.toString()` copy of this function in a
+  // script that declares none of them, and the drive ring's diagonals set
+  // exactly the intercardinal facing that reaches the facing one.
+  const FALLBACK_GRID_SIZE = 12;
   if (mode === "overhead") {
-    const height = Math.max(4, Number(gridSize) || DEFAULT_GRID_SIZE) * 1.4;
+    const FALLBACK_FOV_DEGREES = 55;
+    // Looking straight down pushes the TOP of a standing model outward from
+    // the centre of frame, so a fit measured on the flat ground plane alone
+    // cuts the head off whoever stands in an outermost cell. This is the room
+    // the tallest of the cast needs out there, counting the id label floating
+    // above it, which is the part a visitor most needs to read. Props run
+    // taller still and are allowed to overhang.
+    const EDGE_ROOM = 1.2;
+    const board = Math.max(4, Number(gridSize) || FALLBACK_GRID_SIZE) * cellSize;
+    const fovDegrees = Number(view && view.fovDegrees) > 0 ? Number(view.fovDegrees) : FALLBACK_FOV_DEGREES;
+    const aspect = Number(view && view.aspect) > 0 ? Number(view.aspect) : 1;
+    const tanHalfVertical = Math.tan((Math.min(fovDegrees, 175) * Math.PI) / 360);
+    const tanHalfHorizontal = tanHalfVertical * aspect;
+    // Fit the TIGHTER axis. A wide canvas runs out of height first, a tall one
+    // runs out of width, and taking the larger of the two distances is what
+    // stops a portrait window cropping the board's own left and right edges.
+    const fitsBothAxes = Math.max(1 / tanHalfVertical, 1 / tanHalfHorizontal);
+    const height = (board / 2) * EDGE_ROOM * fitsBothAxes;
     return { mode: "overhead", position: { x: 0, y: height, z: 0 }, lookAt: { x: 0, y: 0, z: 0 } };
   }
   if (!agent || !agent.cell) return null;
@@ -264,7 +326,7 @@ export function cameraRigFor(mode, agent, gridSize) {
   const FACING_VECTOR = {
     north: { x: 0, z: -1 }, south: { x: 0, z: 1 }, east: { x: 1, z: 0 }, west: { x: -1, z: 0 },
   };
-  const dir = FACING_VECTOR[agent.facing] || FACING_VECTOR[DEFAULT_FACING];
+  const dir = FACING_VECTOR[agent.facing] || FACING_VECTOR.south;
   if (mode === "pov") {
     return {
       mode: "pov",
@@ -320,6 +382,28 @@ export function nextCameraSelection(prev, agents, ecology) {
   };
 }
 
+/** What one press on a camera-mode button should do, as
+ *  `{ mode, selectedId, status }`.
+ *
+ *  `overhead` needs nobody and keeps whatever was selected, so switching back
+ *  to `follow` resumes the same agent. The other two need one, and after a
+ *  fallback there is none: the agent that was followed has been eaten and the
+ *  selection was cleared. The dropdown, meanwhile, still lists the survivors
+ *  and shows its first one, so a press that did nothing left the deck naming
+ *  an agent the camera was not on. `offered` is that dropdown value, and a
+ *  press adopts it when it is still live.
+ *
+ *  With nobody left to adopt the press stays overhead and says why, rather
+ *  than lighting a button over a camera that did not move. `liveIds` is this
+ *  turn's roster. Pure, self-contained. */
+export function cameraSelectionForMode(mode, selectedId, offered, liveIds) {
+  const live = liveIds || [];
+  if (mode === "overhead") return { mode: "overhead", selectedId: selectedId || null, status: null };
+  if (selectedId && live.indexOf(selectedId) !== -1) return { mode, selectedId, status: null };
+  if (offered && live.indexOf(offered) !== -1) return { mode, selectedId: offered, status: null };
+  return { mode: "overhead", selectedId: null, status: "nobody left to follow — staying overhead." };
+}
+
 /** Every agent and item's own dot for the 2D top-down map panel, as
  *  percentage coordinates within a square panel (`{ id, kind, xPct, yPct
  *  }[]`) — never pixel values, so the panel's own CSS controls its actual
@@ -530,6 +614,8 @@ ${PILL_COMPLETE_CSS}
     <section class="deck" aria-label="simulation controls">
       <div class="deck-controls">
         <button type="button" class="deck-play" id="autoToggle" aria-pressed="false">&#9654; play</button>
+        <button type="button" id="stepBtn">step</button>
+        <span class="deck-hint" id="stepHint" hidden>pause to step</span>
         <button type="button" id="resetBtn">reset</button>
 ${scenarioList.length > 1 ? `        <select id="scenarioSelect" class="deck-select" aria-label="which town square to play">
 ${scenarioList.map((s, i) => `          <option value="${i}"${i === 0 ? " selected" : ""}>${escapeHtml(s.label || scenarioLabel(s.worldPayload?.name))}</option>`).join("\n")}
@@ -539,32 +625,55 @@ ${scenarioList.map((s, i) => `          <option value="${i}"${i === 0 ? " select
         <span class="mono deck-turns" id="globalTurnCount">turns: 0</span>
       </div>
       <div class="deck-body">
-        <div class="deck-sliders">
-          <label class="deck-slider">foxes
-            <input type="range" id="playerCountSlider" min="0" max="${PLAYER_COUNTS.length - 1}" step="1"
-                   value="${Math.max(0, PLAYER_COUNTS.indexOf(DEFAULT_PLAYER_COUNT))}"
-                   list="playerCountTicks" aria-valuetext="${DEFAULT_PLAYER_COUNT} foxes">
-            <datalist id="playerCountTicks">${PLAYER_COUNTS.map((n, i) => `<option value="${i}" label="${n}"></option>`).join("")}</datalist>
-            <span class="mono" id="playerCountValue">${DEFAULT_PLAYER_COUNT}</span>
-          </label>
-          <label class="deck-slider">goblins
-            <input type="range" id="npcCountSlider" min="${NPC_COUNT_MIN}" max="${NPC_COUNT_MAX}" step="1"
-                   value="${DEFAULT_NPC_COUNT}"
-                   list="npcCountTicks" aria-valuetext="${DEFAULT_NPC_COUNT} goblins">
-            <datalist id="npcCountTicks">${Array.from({ length: NPC_COUNT_MAX - NPC_COUNT_MIN + 1 }, (_, i) => {
-              const n = NPC_COUNT_MIN + i;
-              return NPC_COUNT_LABELLED.includes(n) ? `<option value="${n}" label="${n}"></option>` : `<option value="${n}"></option>`;
-            }).join("")}</datalist>
-            <span class="mono" id="npcCountValue">${DEFAULT_NPC_COUNT}</span>
-          </label>
-          <label class="deck-slider">delay
-            <input type="range" id="delaySlider" min="80" max="2000" step="20" value="${DEFAULT_DELAY_MS}">
-            <span class="mono" id="delayValue">${DEFAULT_DELAY_MS}ms</span>
-          </label>
-          <label class="deck-slider">max turns
-            <input type="range" id="maxTurnsSlider" min="20" max="2000" step="20" value="${DEFAULT_MAX_TURNS}">
-            <span class="mono" id="maxTurnsValue">${DEFAULT_MAX_TURNS}</span>
-          </label>
+        <div class="deck-panels">
+          <div class="deck-stack deck-stack-1">
+            <label class="deck-slider">foxes
+              <input type="range" id="playerCountSlider" min="0" max="${PLAYER_COUNTS.length - 1}" step="1"
+                     value="${Math.max(0, PLAYER_COUNTS.indexOf(DEFAULT_PLAYER_COUNT))}"
+                     list="playerCountTicks" aria-valuetext="${DEFAULT_PLAYER_COUNT} foxes">
+              <datalist id="playerCountTicks">${PLAYER_COUNTS.map((n, i) => `<option value="${i}" label="${n}"></option>`).join("")}</datalist>
+              <span class="mono" id="playerCountValue">${DEFAULT_PLAYER_COUNT}</span>
+            </label>
+            <label class="deck-slider">goblins
+              <input type="range" id="npcCountSlider" min="${NPC_COUNT_MIN}" max="${NPC_COUNT_MAX}" step="1"
+                     value="${DEFAULT_NPC_COUNT}"
+                     list="npcCountTicks" aria-valuetext="${DEFAULT_NPC_COUNT} goblins">
+              <datalist id="npcCountTicks">${Array.from({ length: NPC_COUNT_MAX - NPC_COUNT_MIN + 1 }, (_, i) => {
+                const n = NPC_COUNT_MIN + i;
+                return NPC_COUNT_LABELLED.includes(n) ? `<option value="${n}" label="${n}"></option>` : `<option value="${n}"></option>`;
+              }).join("")}</datalist>
+              <span class="mono" id="npcCountValue">${DEFAULT_NPC_COUNT}</span>
+            </label>
+            <label class="deck-slider">follow
+              <select id="agentSelect" class="deck-select" aria-label="which agent to follow"
+                      aria-describedby="agentSelectHint">
+${openingAgents.map((a) => `                <option value="${escapeHtml(a.id)}">${escapeHtml(a.id)}</option>`).join("\n")}
+              </select>
+            </label>
+            <span class="deck-hint" id="agentSelectHint" hidden>pause to swap</span>
+          </div>
+          <div class="deck-stack deck-stack-2">
+            <label class="deck-slider">delay
+              <input type="range" id="delaySlider" min="80" max="2000" step="20" value="${DEFAULT_DELAY_MS}">
+              <span class="mono" id="delayValue">${DEFAULT_DELAY_MS}ms</span>
+            </label>
+            <label class="deck-slider">max turns
+              <input type="range" id="maxTurnsSlider" min="20" max="2000" step="20" value="${DEFAULT_MAX_TURNS}">
+              <span class="mono" id="maxTurnsValue">${DEFAULT_MAX_TURNS}</span>
+            </label>
+            <div class="camera-mode" id="cameraMode" role="group" aria-label="camera mode">
+              <button type="button" data-mode="follow" aria-pressed="true">follow</button>
+              <button type="button" data-mode="pov" aria-pressed="false">pov</button>
+              <button type="button" data-mode="overhead" aria-pressed="false">overhead</button>
+            </div>
+          </div>
+          <div class="deck-stack deck-stack-3">
+            <button type="button" class="pill affordance" id="foodPill" data-command="place food" aria-pressed="false">place food</button>
+            <label class="deck-teach" title="With this on, a sentence like &quot;The fox is at cell-3-4.&quot; writes a fact into the square instead of running as a command.">
+              <input type="checkbox" id="teachToggle">
+              teach
+            </label>
+          </div>
         </div>
         <section class="map-panel" id="mapPanel" aria-label="the town square, from above">
           <div class="map-panel-head">
@@ -580,25 +689,6 @@ ${scenarioList.map((s, i) => `          <option value="${i}"${i === 0 ? " select
           </div>
         </section>
       </div>
-      <div class="deck-camera">
-        <label class="deck-slider">follow
-          <select id="agentSelect" class="deck-select" aria-label="which agent to follow"
-                  aria-describedby="agentSelectHint">
-${openingAgents.map((a) => `            <option value="${escapeHtml(a.id)}">${escapeHtml(a.id)}</option>`).join("\n")}
-          </select>
-        </label>
-        <span class="deck-hint" id="agentSelectHint" hidden>pause to swap</span>
-        <div class="camera-mode" id="cameraMode" role="group" aria-label="camera mode">
-          <button type="button" data-mode="follow" aria-pressed="true">follow</button>
-          <button type="button" data-mode="pov" aria-pressed="false">pov</button>
-          <button type="button" data-mode="overhead" aria-pressed="false">overhead</button>
-        </div>
-        <button type="button" class="pill affordance" id="foodPill" data-command="place food" aria-pressed="false">place food</button>
-        <label class="deck-teach" title="With this on, a sentence like &quot;The fox is at cell-3-4.&quot; writes a fact into the square instead of running as a command.">
-          <input type="checkbox" id="teachToggle">
-          teach
-        </label>
-      </div>
       <div class="deck-info-popup mudiii-note" id="deckInfoPopup" role="dialog" aria-label="about this demo" hidden>
         ${MUDIII_NOTE_LINES.map((line) => `<p>${escapeHtml(line)}</p>`).join("\n        ")}
         <button type="button" class="deck-info-popup-close" id="deckInfoClose" aria-label="close">&times;</button>
@@ -694,7 +784,7 @@ const MUDIII_STYLE = `
     box-shadow: 0 2px 0 rgba(0,0,0,.18), inset 0 1px 0 rgba(255,255,255,.35);
     padding: .8rem .9rem; display: flex; flex-direction: column; gap: .55rem; min-width: 0;
   }
-  .deck-controls, .deck-camera { display: flex; flex-wrap: wrap; align-items: center; gap: .5rem; }
+  .deck-controls { display: flex; flex-wrap: wrap; align-items: center; gap: .5rem; }
   .deck-info-btn {
     font-family: ${MONO_STACK}; font-size: .78rem; line-height: 1; width: 1.5rem; height: 1.5rem;
     border-radius: 50%; border: 1px solid var(--square-stone-dark); background: rgba(255,255,255,.5);
@@ -725,12 +815,19 @@ const MUDIII_STYLE = `
   .deck-play[aria-pressed="true"] { background: var(--square-accent) !important; border-color: var(--square-accent) !important; color: var(--square-ink); }
   .deck-turns { margin-left: auto; font-size: .74rem; color: var(--square-stone-dark); background: var(--square-stone-dark); background: rgba(43,35,24,.9); color: var(--square-accent); border-radius: 2px; padding: .1rem .5rem; }
   .deck-body { display: flex; gap: .7rem; align-items: flex-start; }
-  .deck-sliders { display: flex; flex-wrap: wrap; gap: 1rem; flex: 1 1 auto; min-width: 0; }
+  .deck-panels { display: flex; flex-wrap: wrap; gap: .6rem 1rem; flex: 1 1 auto; min-width: 0; }
+  /* On a narrow viewport a stack is just a grouping label, not a real box:
+     its controls flow straight into .deck-panels' own wrap, one per row
+     beside the map. Wider breakpoints turn it back into a real column. */
+  .deck-stack { display: contents; }
   .deck-slider { display: flex; align-items: center; gap: .35rem; font-family: ${MONO_STACK}; font-size: .62rem; text-transform: uppercase; letter-spacing: .08em; color: var(--square-stone-dark); min-width: 0; }
   .deck-slider input[type="range"] { accent-color: var(--square-accent); flex: 1 1 4rem; min-width: 2.5rem; width: auto; max-width: 8rem; }
   .deck-teach { display: flex; align-items: center; gap: .3rem; font-family: ${MONO_STACK}; font-size: .72rem; text-transform: uppercase; letter-spacing: .05em; color: var(--square-stone-dark); cursor: pointer; }
   .deck-teach input[type="checkbox"] { accent-color: var(--square-accent); }
-  .camera-mode { display: inline-flex; gap: .25rem; }
+  /* A narrow stack column can be too tight for all three button labels on
+     one line, and a nowrap row would rather overflow into the next column
+     than shrink — wrap keeps it inside its own box. */
+  .camera-mode { display: inline-flex; flex-wrap: wrap; gap: .25rem; }
   .camera-mode button[aria-pressed="true"] { background: var(--square-accent); border-color: var(--square-accent); color: var(--square-ink); }
   .deck-info-popup {
     position: absolute; left: .9rem; right: .9rem; top: calc(100% + 8px); z-index: 8;
@@ -908,37 +1005,53 @@ const MUDIII_STYLE = `
     #editorText { min-height: 16rem; }
   }
 
-  /* A landscape phone and a narrow desktop window are both under 900px but
-     want different slider/map arrangements, so the split has to key off
-     orientation as well as width. */
-  @media (max-width: 900px) and (orientation: landscape) {
-    .deck-sliders { display: grid; grid-template-columns: 1fr 1fr; gap: .4rem 1rem; }
-    .deck-body { align-items: stretch; }
-    .map-panel { flex-basis: 33%; max-width: 33%; }
-    /* The square aspect-ratio that suits a tall portrait column would blow
-       the map back up to full column width in a short landscape viewport —
-       here it follows the two-row slider stack's own height instead. */
-    .map-panel-board { aspect-ratio: auto; min-height: 90px; }
-  }
-
   /* Half the deck is right on a phone and absurd on a 2000px window: a
      percentage has no ceiling, so a square board grew to roughly 950px tall
      and pushed the 3D view off the screen. Wide viewports get an absolute
      size instead, and keep the square — there is room for it here.
 
-     The map is also taller than the sliders beside it, which left a tall
-     empty stripe of parchment under them. On a wide screen the deck becomes
-     one grid so the map can stand beside the sliders AND the camera row at
-     once, and the space under the controls closes up. display:contents lifts
-     .deck-sliders and .map-panel out of .deck-body so both are grid items of
-     the deck itself. */
+     The map is also taller than a single row of controls, which used to
+     leave a tall empty stripe of parchment under them. On a landscape phone
+     and a desktop window alike, the deck becomes one grid with three control
+     columns beside the map. display:contents lifts .deck-panels' three
+     .deck-stack children, and .map-panel, out of .deck-body so all four are
+     grid items of the deck itself. A stack sits at its own natural height,
+     top-aligned, rather than stretching its items apart to match the map —
+     stretching them just traded the empty stripe for gaps between controls
+     that belong together, and a hint drifting away from the select it
+     describes. A shorter stack beside a taller map is fine; the leftover
+     space stays honest whitespace instead. */
+  @media (min-width: 901px), (max-width: 900px) and (orientation: landscape) {
+    .deck-body, .deck-panels { display: contents; }
+    .deck-stack {
+      display: flex; flex-direction: column; gap: .5rem;
+      grid-row: 2; align-self: start;
+    }
+    .deck-stack-1 { grid-column: 1; }
+    .deck-stack-2 { grid-column: 2; }
+    .deck-stack-3 { grid-column: 3; }
+    /* Stretch is the flex column's default cross-axis behaviour, and the
+       food pill is the one control here with a visible border — without
+       this it grows to the stack's full width as a wide dashed box. */
+    .deck-stack .pill.affordance { align-self: flex-start; }
+    .map-panel { grid-column: 4; grid-row: 2; flex: 0 0 auto; max-width: none; }
+  }
+
   @media (min-width: 901px) {
-    .deck { display: grid; grid-template-columns: minmax(0, 1fr) 240px; grid-template-rows: auto 1fr auto; column-gap: .8rem; }
+    .deck { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)) 240px; grid-template-rows: auto auto; column-gap: .8rem; }
     .deck-controls { grid-column: 1 / -1; grid-row: 1; }
-    .deck-body { display: contents; }
-    .deck-sliders { grid-column: 1; grid-row: 2; align-self: start; }
-    .deck-camera { grid-column: 1; grid-row: 3; align-self: end; }
-    .map-panel { grid-column: 2; grid-row: 2 / 4; flex: 0 0 auto; max-width: none; align-self: start; }
+    .map-panel { align-self: start; }
+  }
+
+  /* A landscape phone is under 900px but wants the same four-column
+     treatment as desktop — just narrower columns and a map that stretches
+     to the stacks' height rather than holding a fixed square, the same
+     trade this breakpoint always made before the grid switch. */
+  @media (max-width: 900px) and (orientation: landscape) {
+    .deck { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)) minmax(140px, 220px); grid-template-rows: auto auto; column-gap: .6rem; }
+    .deck-controls { grid-column: 1 / -1; grid-row: 1; }
+    .map-panel { align-self: stretch; }
+    .map-panel-board { aspect-ratio: auto; min-height: 90px; }
   }
 
 `;
@@ -972,9 +1085,11 @@ function pageScript() {
   const cellFromGroundPoint = ${cellFromGroundPoint.toString()};
   const propPlacementsFrom = ${propPlacementsFrom.toString()};
   const occupiedCells = ${occupiedCells.toString()};
+  const currentPlacementsFrom = ${currentPlacementsFrom.toString()};
   const blockedCellReason = ${blockedCellReason.toString()};
   const cameraRigFor = ${cameraRigFor.toString()};
   const nextCameraSelection = ${nextCameraSelection.toString()};
+  const cameraSelectionForMode = ${cameraSelectionForMode.toString()};
   const mapDotsFor = ${mapDotsFor.toString()};
   const mapBlocksFor = ${mapBlocksFor.toString()};
   const hudCardFieldsFor = ${hudCardFieldsFor.toString()};
@@ -1022,6 +1137,14 @@ function pageScript() {
   // another agent. Without it, choosing someone new after a fox ate your
   // goblin leaves the camera overhead and the follow button unlit.
   let cameraModeBeforeFallback = null;
+  // The cut to overhead the scene has been told to make NEXT tick. The page's
+  // own camera state moves the moment the followed agent leaves the board,
+  // because the deck must never offer an agent that is gone; the 3D camera
+  // holds one more turn so the visitor watches the kill from the animal they
+  // were riding instead of cutting away from it. A rig with nobody to aim at
+  // freezes rather than drifting, which is what makes the held turn read as a
+  // held shot.
+  let deferredSceneCamera = null;
   let foodArmed = false;
   let livePills = [];
   let selectedAddresseeId = null;
@@ -1062,6 +1185,13 @@ function pageScript() {
     }
   }
 
+  // Every camera change the visitor asks for goes through here, so a pending
+  // one-turn-late cut can never land on top of a mode they picked in between.
+  function sendCameraToScene(state) {
+    deferredSceneCamera = null;
+    callScene("setCamera", state);
+  }
+
   function applyTickResult(result) {
     if (!result) return;
     // The engine owns the count. Anything that advances a turn — the deck, a
@@ -1075,7 +1205,16 @@ function pageScript() {
     const nextCamera = nextCameraSelection(camera, agentsList(), result.ecology || []);
     if (nextCamera.status && camera.mode !== "overhead") cameraModeBeforeFallback = camera.mode;
     camera = nextCamera;
-    callScene("setCamera", camera);
+    if (deferredSceneCamera) {
+      const cut = deferredSceneCamera;
+      deferredSceneCamera = null;
+      callScene("setCamera", cut);
+    } else if (nextCamera.status) {
+      // The status line names the kill NOW; the wide shot lands next turn.
+      deferredSceneCamera = { mode: camera.mode, selectedId: camera.selectedId };
+    } else {
+      callScene("setCamera", camera);
+    }
     if (camera.status) setSceneStatus(camera.status);
   }
 
@@ -1103,6 +1242,10 @@ function pageScript() {
         // on top of the open dropdown and loses the pick.
         el("agentSelect").disabled = state.playing;
         el("agentSelectHint").hidden = !state.playing;
+        // Step reads the same ticker state for the same reason: a hand-driven
+        // turn while the board plays itself lands in the middle of one.
+        el("stepBtn").disabled = state.playing || state.animating;
+        el("stepHint").hidden = !state.playing;
       },
       hasNext: hasNext,
       wait: liveWait,
@@ -1432,7 +1575,7 @@ function pageScript() {
     camera = { mode: mode, selectedId: id, status: null };
     renderCameraButtons();
     renderDriveRing();
-    callScene("setCamera", camera);
+    sendCameraToScene(camera);
   });
 
   function renderCameraButtons() {
@@ -1445,9 +1588,14 @@ function pageScript() {
     const btn = e.target.closest("button[data-mode]");
     if (!btn) return;
     cameraModeBeforeFallback = null;
-    camera = { mode: btn.getAttribute("data-mode"), selectedId: camera.selectedId, status: null };
+    camera = cameraSelectionForMode(
+      btn.getAttribute("data-mode"), camera.selectedId, el("agentSelect").value, Object.keys(agentsById),
+    );
     renderCameraButtons();
-    callScene("setCamera", camera);
+    renderAgentSelect();
+    renderDriveRing();
+    setSceneStatus(camera.status || "");
+    sendCameraToScene(camera);
   });
 
   // ---- the control deck ----------------------------------------------------
@@ -1480,6 +1628,13 @@ function pageScript() {
     el("playerCountSlider").addEventListener("change", function () { boot(); });
     el("npcCountSlider").addEventListener("input", function () { showGoblinCount(chosenGoblinCount()); });
     el("npcCountSlider").addEventListener("change", function () { boot(); });
+    // One whole turn: every agent decides and moves, the ecology pass runs,
+    // and the turn counter reads exactly one higher. It goes through the same
+    // ticker play() uses, so the two can never run a turn on top of each other.
+    el("stepBtn").addEventListener("click", function () {
+      if (!session || autoOn) return;
+      ensureTicker().stepOnce();
+    });
     el("resetBtn").addEventListener("click", function () { resetBoard(); });
     const scenarioSelect = el("scenarioSelect");
     if (scenarioSelect) {
@@ -1520,15 +1675,10 @@ function pageScript() {
   let allStoreRows = [];
 
   function renderEditPlacements() {
-    const placements = {};
-    for (const row of editRows) {
-      if (row.predicate !== "mgx:currently-in") continue;
-      placements[row.subject] = row.object;
-    }
-    const subjects = Object.keys(placements).sort();
-    el("editPlacements").innerHTML = subjects.length
-      ? subjects.map(function (s) {
-        return '<div class="edit-placement-row"><span class="mono">' + esc(s) + '</span><span>' + esc(placements[s]) + "</span></div>";
+    const placements = currentPlacementsFrom(editRows);
+    el("editPlacements").innerHTML = placements.length
+      ? placements.map(function (p) {
+        return '<div class="edit-placement-row"><span class="mono">' + esc(p.subject) + '</span><span>' + esc(p.cell) + "</span></div>";
       }).join("")
       : '<span class="edit-empty">nothing placed yet</span>';
   }
@@ -1623,7 +1773,7 @@ function pageScript() {
     await callScene("boot", {
       propPlacements: props, assetManifest: DATA.assetManifest, gridSize: gridSizeOf(), cellSize: 1,
     });
-    callScene("setCamera", camera);
+    sendCameraToScene(camera);
     callScene("applyTick", { agents: agentsById, items: itemsById, ecology: [] });
   }
 
@@ -1656,6 +1806,32 @@ function pageScript() {
   // reduced motion gets the opening board drawn and left still — the play
   // control is right there — because an autoplaying board is exactly the
   // unasked-for movement that setting is about.
+
+  // The camera opens riding a goblin. The goblins are the prey, so the first
+  // thing a visitor sees is a chase from inside the animal being chased; when
+  // it is caught the camera cuts wide and the rest of the round plays out
+  // overhead. Falls back to whoever is first by id on a square with no prey.
+  function openingFollowId(agents) {
+    const ids = Object.keys(agents || {}).sort();
+    for (let i = 0; i < ids.length; i += 1) {
+      if (agents[ids[i]] && agents[ids[i]].role === "prey") return ids[i];
+    }
+    return ids[0] || null;
+  }
+
+  // The play control put back to a stopped board. The ticker draws this
+  // itself while it lives, but a Reset throws the ticker away, so the button
+  // would keep reading "pause" over a board that is standing still.
+  function showStopped() {
+    const playBtn = el("autoToggle");
+    playBtn.setAttribute("aria-pressed", "false");
+    playBtn.textContent = "\\u25B6 play";
+    el("agentSelect").disabled = false;
+    el("agentSelectHint").hidden = true;
+    el("stepBtn").disabled = false;
+    el("stepHint").hidden = true;
+  }
+
   let bootSeq = 0;
   async function boot() {
     const seq = bootSeq += 1;
@@ -1665,6 +1841,7 @@ function pageScript() {
     tickQueue = createSerialQueue();
     camera = { mode: "follow", selectedId: null, status: null };
     cameraModeBeforeFallback = null;
+    deferredSceneCamera = null;
     expandedAgents.clear();
     const s = scenario();
     const foxes = mintRoster(rosterPrefixFor(s, "predator"), chosenFoxCount());
@@ -1692,7 +1869,7 @@ function pageScript() {
     // the cells both come back from it rather than being guessed here.
     const opening = await session.board();
     if (seq !== bootSeq) return;
-    camera.selectedId = Object.keys(opening.agents || {}).sort()[0] || null;
+    camera.selectedId = openingFollowId(opening.agents);
     applyTickResult(opening);
     renderAll();
     if (!prefersReducedMotion()) {
@@ -1705,9 +1882,11 @@ function pageScript() {
   // the world's facts, everything taught into it and every editor change all
   // stand, and only the animals are minted again. Re-opening would throw the
   // taught facts away with the cast, which is not what "reset the board" says.
-  // The engine owns the turn count, so a re-cast does not rewind it — the
-  // status line says as much, because a counter that keeps climbing after a
-  // Reset otherwise reads as a bug.
+  //
+  // A Reset leaves the board STOPPED, whatever it was doing before. Opening
+  // the page is the one time the square starts itself; after that the visitor
+  // says when it runs. The shared ticker in viz-ticker.mjs already resets this
+  // way, and this page keeps its own play flag, so it says so here too.
   async function resetBoard() {
     if (!session) return boot();
     autoOn = false;
@@ -1720,15 +1899,13 @@ function pageScript() {
     showFoxCount(foxes.length);
     showGoblinCount(goblins.length);
     const board = await serializeTick(function () { return session.recast({ agents: cast }); });
-    camera = { mode: "follow", selectedId: Object.keys(board.agents || {}).sort()[0] || null, status: null };
+    camera = { mode: "follow", selectedId: openingFollowId(board.agents), status: null };
     cameraModeBeforeFallback = null;
+    deferredSceneCamera = null;
     applyTickResult(board);
     renderAll();
-    setSceneStatus("re-cast \\u2014 the square's own facts stand, and its clock keeps running.");
-    if (!prefersReducedMotion()) {
-      autoOn = true;
-      ensureTicker().play();
-    }
+    showStopped();
+    setSceneStatus("re-cast and stopped \\u2014 the square's own facts stand, and everything taught into it. Press play.");
   }
 
   function renderAll() {