@polycode-projects/the-mechanical-code-talker 5.0.3 → 5.0.5

package/src/services/mudiii-viz.mjs

@@ -497,32 +497,41 @@ ${scenarioList.map((s, i) => `          <option value="${i}"${i === 0 ? " select
         <button type="button" class="deck-info-btn" id="deckInfoBtn" aria-expanded="false" aria-controls="deckInfoPopup" aria-label="about this demo">?</button>
         <span class="mono deck-turns" id="globalTurnCount">turns: 0</span>
       </div>
-      <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-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>
+        <section class="map-panel" id="mapPanel" aria-label="the town square, from above">
+          <div class="map-panel-head">
+            <span class="map-panel-title">the square, from above</span>
+            <span class="mono map-panel-turn" id="mapPanelTurn">turn 0</span>
+          </div>
+          <div class="map-panel-board" id="mapPanelBoard"></div>
+        </section>
       </div>
       <div class="deck-camera">
         <label class="deck-slider">follow
@@ -542,13 +551,6 @@ ${openingAgents.map((a) => `            <option value="${escapeHtml(a.id)}">${es
         <button type="button" class="deck-info-popup-close" id="deckInfoClose" aria-label="close">&times;</button>
       </div>
     </section>
-    <section class="map-panel" id="mapPanel" aria-label="the town square, from above">
-      <div class="map-panel-head">
-        <span class="map-panel-title">the square, from above</span>
-        <span class="mono map-panel-turn" id="mapPanelTurn">turn 0</span>
-      </div>
-      <div class="map-panel-board" id="mapPanelBoard"></div>
-    </section>
   </div>
   <section class="scene-stage" id="sceneStage" aria-label="the town square, in three dimensions">
     <canvas id="sceneCanvas"></canvas>
@@ -628,7 +630,7 @@ const MUDIII_STYLE = `
   }
   .mudiii-topbar-help:hover { border-color: var(--square-accent); }
 
-  .deck-row { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; align-items: stretch; margin-bottom: 1rem; }
+  .deck-row { margin-bottom: 1rem; }
   .deck {
     position: relative;
     background: var(--parchment); border: 1px solid var(--square-stone-dark); border-radius: 4px;
@@ -656,9 +658,10 @@ const MUDIII_STYLE = `
   .deck-play { background: var(--square-ink) !important; color: var(--parchment); border-color: var(--square-ink) !important; padding: .38rem 1.1rem !important; }
   .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-sliders { display: flex; flex-wrap: wrap; gap: 1rem; }
-  .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); }
-  .deck-slider input[type="range"] { accent-color: var(--square-accent); width: 8rem; max-width: 34vw; }
+  .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-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; }
   .camera-mode { display: inline-flex; gap: .25rem; }
   .camera-mode button[aria-pressed="true"] { background: var(--square-accent); border-color: var(--square-accent); color: var(--square-ink); }
   .deck-info-popup {
@@ -678,13 +681,14 @@ const MUDIII_STYLE = `
 
   .map-panel {
     background: var(--square-stone-dark); color: var(--parchment);
-    border: 1px solid var(--square-accent); border-radius: 4px; padding: .55rem .65rem .6rem;
-    display: flex; flex-direction: column; gap: .4rem; min-width: 0;
+    border: 1px solid var(--square-accent); border-radius: 4px; padding: .5rem .55rem .55rem;
+    display: flex; flex-direction: column; gap: .35rem; min-width: 0;
+    flex: 0 0 50%; max-width: 50%;
   }
-  .map-panel-head { display: flex; justify-content: space-between; align-items: baseline; gap: .5rem; }
-  .map-panel-title { font-family: ${MONO_STACK}; font-size: .58rem; text-transform: uppercase; letter-spacing: .12em; opacity: .85; }
-  .map-panel-turn { font-size: .62rem; opacity: .7; }
-  .map-panel-board { position: relative; flex: 1; min-height: 200px; background: rgba(124,154,91,.25); border: 1px solid rgba(233,217,182,.35); border-radius: 3px; }
+  .map-panel-head { display: flex; justify-content: space-between; align-items: baseline; gap: .4rem; }
+  .map-panel-title { font-family: ${MONO_STACK}; font-size: .54rem; text-transform: uppercase; letter-spacing: .1em; opacity: .85; }
+  .map-panel-turn { font-size: .58rem; opacity: .7; }
+  .map-panel-board { position: relative; flex: 1; min-height: 110px; aspect-ratio: 1; background: rgba(124,154,91,.25); border: 1px solid rgba(233,217,182,.35); border-radius: 3px; }
   .map-dot { position: absolute; width: .55rem; height: .55rem; margin: -.28rem 0 0 -.28rem; border-radius: 50%; border: 1px solid rgba(0,0,0,.4); }
   .map-dot-predator { background: var(--square-predator); }
   .map-dot-prey { background: var(--square-prey); }
@@ -716,7 +720,6 @@ const MUDIII_STYLE = `
 
   .edit-stage { display: none; grid-template-columns: minmax(0, 1.15fr) minmax(0, 1fr); gap: 1rem; align-items: start; margin-bottom: 1rem; }
   body.editing .mudiii-chat, body.editing .scene-stage, body.editing .hud-row, body.editing .deck-row .map-panel { display: none; }
-  body.editing .deck-row { grid-template-columns: 1fr; }
   body.editing .edit-stage { display: grid; }
   #editModeBtn[aria-pressed="true"] { background: var(--square-accent); border-color: var(--square-accent); }
   .edit-text, .edit-panel {
@@ -769,10 +772,22 @@ const MUDIII_STYLE = `
   .pill.affordance[aria-pressed="true"] { background: var(--square-accent); border-style: solid; }
 
   @media (max-width: 900px) {
-    .deck-row { grid-template-columns: 1fr; }
     .edit-stage { grid-template-columns: 1fr; }
     #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; }
+  }
 `;
 
 /** The inlined page script, spliced the same way mud-viz.mjs's own
@@ -813,6 +828,7 @@ function pageScript() {
   const el = (id) => document.getElementById(id);
   let scenarioIndex = 0;
   const scenario = function () { return DATA.scenarios[scenarioIndex]; };
+  const gridSizeOf = function () { return scenario().gridSize || DATA.gridSize; };
   const rosterOf = function (s, role) {
     return (s.agents || []).filter(function (a) { return !role || a.role === role; }).map(function (a) { return a.id; });
   };
@@ -881,6 +897,9 @@ function pageScript() {
 
   function applyTickResult(result) {
     if (!result) return;
+    // The engine owns the count. Anything that advances a turn — the deck, a
+    // chat frame — lands here, so the page never keeps a rival tally.
+    if (typeof result.turn === "number") globalTurn = result.turn;
     if (result.agents) agentsById = result.agents;
     if (result.items) itemsById = result.items;
     callScene("applyTick", { agents: result.agents, items: result.items, ecology: result.ecology });
@@ -892,8 +911,7 @@ function pageScript() {
   async function runOneTick() {
     return serializeTick(async function () {
       if (!session) return null;
-      globalTurn += 1;
-      const result = await session.tick(globalTurn);
+      const result = await session.tick();
       applyTickResult(result);
       renderAll();
       return result;
@@ -921,8 +939,16 @@ function pageScript() {
   function sendCommand(line) {
     appendChat("u", line);
     if (!session) { appendChat("a", "no session is open yet \\u2014 reset to start one."); return Promise.resolve(); }
-    return serializeTick(function () { return tmct.turn(line); }).then(function (res) {
+    // A chat line can run a real turn. An addressed told-fact does, and the
+    // visitor should watch the lie land, so the board is read back in the same
+    // queue slot. board() spends no turn, so a line that ran none costs
+    // nothing. It reports no goal or plan either, because a resting board has
+    // decided nothing, which is the blank boot() already draws at turn 0.
+    return serializeTick(async function () {
+      const res = await tmct.turn(line);
+      const board = await session.board();
       appendChat("a", res.answer);
+      applyTickResult(board);
       renderAll();
       return res;
     });
@@ -1027,7 +1053,7 @@ function pageScript() {
 
   // ---- the top-down map panel ---------------------------------------------
   function renderMapPanel() {
-    const dots = mapDotsFor(agentsList(), itemsList(), DATA.gridSize);
+    const dots = mapDotsFor(agentsList(), itemsList(), gridSizeOf());
     el("mapPanelBoard").innerHTML = dots.map(function (d) {
       return '<span class="map-dot map-dot-' + esc(d.kind) + '" style="left:' + d.xPct + '%;top:' + d.yPct + '%" title="' + esc(d.id) + '"></span>';
     }).join("");
@@ -1216,7 +1242,7 @@ function pageScript() {
     agentsById = {};
     itemsById = {};
     el("chatInput").disabled = false;
-    await callScene("boot", { propPlacements: props, assetManifest: DATA.assetManifest, gridSize: DATA.gridSize, cellSize: 1 });
+    await callScene("boot", { propPlacements: props, assetManifest: DATA.assetManifest, gridSize: gridSizeOf(), cellSize: 1 });
 
     // The opening board, drawn through the very path a tick takes. Without
     // this the page's first sight of where anything stands is the first tick,
@@ -1225,7 +1251,6 @@ function pageScript() {
     // the cells both come back from it rather than being guessed here.
     const opening = await session.board();
     if (seq !== bootSeq) return;
-    globalTurn = opening.turn || 0;
     camera.selectedId = Object.keys(opening.agents || {}).sort()[0] || null;
     applyTickResult(opening);
     renderAll();

package/src/services/predator-prey.mjs

@@ -58,6 +58,12 @@ const PLACEMENT_PREDICATE = "mgx:currently-in";
 const MASS_PREDICATE = "mgx:hasMass";
 const MOOD_PREDICATE = "mgx:feels";
 const FACING_PREDICATE = "mgx:facing";
+// The facing a visitor's own hand turned an agent to, written only on a driven
+// turn. It folds into the same facing map as the ordinary row below, which is
+// what makes a hand turn hold while the agent stands still and lose the moment
+// the planner takes a step of its own: the step's own facing row is stamped
+// with a later turn, and a later turn outranks.
+const DRIVEN_FACING_PREDICATE = "mgx:driven-facing";
 const EATEN_BY_PREDICATE = "mgx:eaten-by";
 const STARVED_PREDICATE = "mgx:starved";
 const PLACED_BY_PREDICATE = "mgx:placed-by";
@@ -86,7 +92,7 @@ const TURN_PLAYED_PREDICATE = "mgx:turn-played";
 const BOARD_SUBJECT = "square";
 
 const MUDIII_STATE_PREDICATE_SET = new Set([
-  PLACEMENT_PREDICATE, MASS_PREDICATE, MOOD_PREDICATE, FACING_PREDICATE,
+  PLACEMENT_PREDICATE, MASS_PREDICATE, MOOD_PREDICATE, FACING_PREDICATE, DRIVEN_FACING_PREDICATE,
   EATEN_BY_PREDICATE, STARVED_PREDICATE, PLACED_BY_PREDICATE,
   MODEL_PREDICATE, ROTATION_PREDICATE, TURN_PLAYED_PREDICATE,
   CARRYING_PREDICATE, PREY_EATEN_PREDICATE, WEB_BUILT_PREDICATE,
@@ -208,6 +214,7 @@ export function foldTownSquareState(factRows) {
         if (snap && rowEpoch === epoch) tickCount = Math.max(tickCount, turn);
         break;
       case FACING_PREDICATE:
+      case DRIVEN_FACING_PREDICATE:
         if (outranks(rowEpoch, turn, facing.get(base))) facing.set(base, { value: row.object, turn, epoch: rowEpoch });
         break;
       case EATEN_BY_PREDICATE:
@@ -448,6 +455,29 @@ function stepPlan(fromCell, toCell) {
   return direction ? [direction] : [];
 }
 
+/**
+ * The hand-driven move `entry` asks of an agent standing at `fromCell`, as
+ * `{ cell, facing }` with `cell` a parsed cell — or null when nothing was
+ * asked, or when what was asked is not a legal one-step move.
+ *
+ * `entry` is a target cell id, or `{ cell, facing }` with both parts optional:
+ * no cell holds the agent where it stands, which is what a turn on the spot
+ * is, and no facing leaves the facing to the step itself.
+ *
+ * The legality table is oneStepOptions — the very list the wander, evade and
+ * chase rungs pick from — so a wall or a prop is a missing exit here too,
+ * never a second notion of blocked, and a refusal reads as "no such move"
+ * rather than as a rule this seam invented. Pure.
+ */
+function acceptedManualMove(entry, fromCell, applyActions) {
+  if (!entry) return null;
+  const request = typeof entry === "string" ? { cell: entry } : entry;
+  const facing = typeof request.facing === "string" && request.facing ? request.facing : null;
+  const target = typeof request.cell === "string" && request.cell ? request.cell : cellId(fromCell.x, fromCell.y);
+  const cell = oneStepOptions(fromCell, applyActions).find((option) => cellId(option.x, option.y) === target);
+  return cell ? { cell, facing } : null;
+}
+
 const round2 = (n) => Math.round(n * 100) / 100;
 
 // ---- the goal line and the mood word -------------------------------------------
@@ -457,8 +487,9 @@ const round2 = (n) => Math.round(n * 100) / 100;
 // is scared, anything wandering or foraging is calm, and anything that just ate
 // is happy.
 
-function goalLine(kind, { subject, cell, arrived, boardNoun = "square", catches = false } = {}) {
+function goalLine(kind, { subject, cell, arrived, boardNoun = "square", catches = false, facing = null, held = false } = {}) {
   switch (kind) {
+    case "driven": return held ? `driven by hand — holding at ${cell}, facing ${facing}.` : `driven by hand — stepping to ${cell}.`;
     case "avoid": return `avoiding ${subject}, last seen at ${cell}.`;
     case "chase":
       if (!arrived) return `chasing ${subject}, last seen at ${cell}.`;
@@ -980,11 +1011,20 @@ function itemsPayload(liveItemIds, { state, itemCellOf, roles, taken = null }) {
  * to where the predator was when it looked), while eating resolves on the
  * post-move ones (it is caught where the predator actually ends up).
  *
+ * `manualMoves` is the one place a visitor's own hand reaches the world:
+ * `{ agentId: cellId }`, or `{ agentId: { cell, facing } }`, checked before
+ * that agent's belief chain runs. A legal request moves the agent under the
+ * `driven` rung; an illegal one is refused and that agent decides for itself
+ * this turn, so a rejected press never freezes it. A driven turn spends a
+ * turn like any other: the ecology pass runs, and every other agent decides
+ * and moves in this same call.
+ *
  * Returns `{ turn, epoch, agents, items, ecology, rungs, activeWebs, writes }`.
  * `agents` and `items` and `ecology` are the frozen render payload — see
  * townSquareTickPayload, which projects exactly those three plus the turn.
- * `rungs` is the decision each live agent reached this turn ("chase", "evade",
- * "forage", "avoid", "wander", and — on a cast that carries or spins webs —
+ * `rungs` is the decision each live agent reached this turn ("driven" for a
+ * hand-driven move, then "chase", "evade", "forage", "avoid", "wander", and —
+ * on a cast that carries or spins webs —
  * "carry", "deliver", "carried", "trapped", "hold-web", "build-web"); an agent
  * that decided and then died still has a rung and no longer has an `agents`
  * entry, which is the difference between a decision and a survivor.
@@ -993,6 +1033,7 @@ function itemsPayload(liveItemIds, { state, itemCellOf, roles, taken = null }) {
  */
 export async function runTownSquareTick(memoryDir, {
   layout, toldFacts = [], config = DEFAULT_GAME_CONFIG.mudiii, roles = MUDIII_ROLES,
+  manualMoves = {},
 } = {}) {
   const lay = typeof layout === "string" ? TOWN_SQUARE_LAYOUTS[layout] : layout;
   if (!lay) throw new Error(`runTownSquareTick: no such layout "${layout}"`);
@@ -1031,6 +1072,11 @@ export async function runTownSquareTick(memoryDir, {
 
   const decide = (agentId, role) => {
     const fromCell = parseCellId(state.placements.get(agentId).cell);
+    // The visitor's hand, checked before any of the belief chain below. A
+    // refused request leaves `driven` null, and the chain then runs exactly as
+    // it would have on a turn nobody touched.
+    const driven = acceptedManualMove(manualMoves?.[agentId], fromCell, applyActions);
+    const restingFacing = state.facing.get(agentId)?.value ?? DEFAULT_FACING;
     const visionRadius = role === "predator" ? config.predatorVisionRadius : config.preyVisionRadius;
     const beliefOpts = { visionRadius, toldFacts };
     // True unless a caller explicitly turns it off. A config object built by
@@ -1045,13 +1091,14 @@ export async function runTownSquareTick(memoryDir, {
     // lookup below stays on beliefOpts either way: this switch is about food.
     const foodBeliefOpts = foodVisionGated ? beliefOpts : { ...beliefOpts, visionRadius: Infinity };
     const rivals = role === "predator" ? predators.filter((id) => id !== agentId) : predators;
-    const threat = nearestBelievedTarget(agentId, fromCell, rivals, state, beliefOpts);
+    const threat = driven ? null : nearestBelievedTarget(agentId, fromCell, rivals, state, beliefOpts);
 
     let rung;
     let nextCell;
     let plan;
     let goal;
     let mood;
+    let drivenFacing = null;
     // A carried prey and its captor both leave the ordinary chain. A carrying
     // predator never drops its catch to dodge a rival or chase a second one:
     // nothing here eats a predator, so "avoid" is contention, not survival.
@@ -1060,7 +1107,18 @@ export async function runTownSquareTick(memoryDir, {
     const captorId = (carriesPrey && role === "prey") ? (captorOfPrey.get(agentId) ?? null) : null;
     let beliefCell = fromCell;
 
-    if (isCarrying && webbedAt(fromCell)) {
+    if (driven) {
+      rung = "driven";
+      nextCell = driven.cell;
+      plan = stepPlan(fromCell, nextCell);
+      drivenFacing = driven.facing;
+      goal = goalLine("driven", {
+        cell: cellId(nextCell.x, nextCell.y),
+        facing: driven.facing ?? restingFacing,
+        held: plan.length === 0,
+      });
+      mood = "calm";
+    } else if (isCarrying && webbedAt(fromCell)) {
       // Already standing in a web: hold, so the pass's own eat gate reads this
       // same cell and resolves the delivery on this exact tick.
       rung = "deliver";
@@ -1166,7 +1224,10 @@ export async function runTownSquareTick(memoryDir, {
       const foodCandidates = beliefCandidates.filter((id) => foodIds.has(id));
       Object.assign(belief, beliefSnapshotFor(agentId, beliefCell, foodCandidates, state, foodBeliefOpts));
     }
-    const facing = plan[0] ?? state.facing.get(agentId)?.value ?? DEFAULT_FACING;
+    // A hand-picked facing beats the step it came with, which is what lets the
+    // page walk an agent backwards without spinning it round.
+    const facing = drivenFacing ?? plan[0] ?? restingFacing;
+    if (rung === "driven") movementWrites.push({ subject: stamp(agentId), predicate: DRIVEN_FACING_PREDICATE, object: facing });
     postMovePlacements.set(agentId, nextCell);
     rungs[agentId] = rung;
     agents[agentId] = { role, cell: cellId(nextCell.x, nextCell.y), facing, goal, mood, plan, mass: 0, belief };

package/src/services/spider-fly-viz.mjs

@@ -1,18 +1,17 @@
-// spider-fly-viz.mjs — the spider-and-fly full-screen page (PLAN_SPIDER_FLY.md
-// §8/§9/§11): a self-contained document shaped exactly like ledger-viz.mjs/
-// plan-viz.mjs — one inlined <style> (importing viz-theme.mjs's shared
-// tokens), behaviour as an inlined IIFE — but unlike those two, almost
-// nothing is embedded as build-time data: the whole game is LIVE client-side
-// state (spider-fly-browser-entry.mjs's createSpiderFlySession), so
-// renderSpiderFlyHtml only needs the page's own static grid geometry (which
-// never changes) plus a title. The engine, sprite resolver and chat turn
-// engine all arrive via ./spider-fly-browser.bundle.js, referenced with a
-// plain same-origin <script src> — the same sibling-file arrangement
-// index.html already uses for chat-browser.bundle.js (both are the FULL
-// turn engine, both generated fresh per build, neither meant to be
-// committed), not memory-ask-browser.bundle.js's inlined-text arrangement
-// (that bundle is small and inlined specifically so ledger.html stays
-// portable on its own — that reason doesn't apply here).
+// spider-fly-viz.mjs — the spider-and-fly full-screen page: a self-contained
+// document shaped exactly like ledger-viz.mjs/plan-viz.mjs — one inlined <style>
+// (importing viz-theme.mjs's shared tokens), behaviour as an inlined IIFE — but
+// unlike those two, almost nothing is embedded as build-time data: the whole
+// game is LIVE client-side state (spider-fly-browser-entry.mjs's
+// createSpiderFlySession), so renderSpiderFlyHtml only needs the page's own
+// static grid geometry (which never changes) plus a title. The engine, sprite
+// resolver and chat turn engine all arrive via ./spider-fly-browser.bundle.js,
+// referenced with a plain same-origin <script src> — the same sibling-file
+// arrangement index.html already uses for chat-browser.bundle.js (both are the
+// FULL turn engine, both generated fresh per build, neither meant to be
+// committed), not memory-ask-browser.bundle.js's inlined-text arrangement (that
+// bundle is small and inlined specifically so ledger.html stays portable on its
+// own — that reason doesn't apply here).
 //
 // renderSpiderFlyHtml() is pure: no I/O, deterministic output for identical
 // input. scripts/build-demo-site.mjs calls it directly and writes the result
@@ -125,19 +124,17 @@ export function facingDegreesFor(plan, previousDegrees) {
 }
 
 /**
- * The updated corpse set for one redraw (§A.2.5 — visual-only, entirely
- * client-side; the actual starve/eat removal already happened in the
- * engine). Every id present in `prevAgents` but absent from `agents` died
- * THIS tick — eaten or starved are the only two ways an agent ever leaves
- * the engine's own returned roster — and is added at its last-known cell
- * and class; every corpse already older than `lingerTurns` past its own
- * death turn is dropped first, so the set never grows without bound.
- * Returns a plain `{ [id]: { cls, cell, diedAtTurn } }` map. Pure.
- * `lingerTurns` defaults to a literal 4 (not the module-level
- * CORPSE_LINGER_TURNS constant) so this function stays fully
- * `.toString()`-splice safe — every real caller (both the inlined page and
- * CORPSE_LINGER_TURNS's own callers elsewhere in this module) passes it
- * explicitly anyway.
+ * The updated corpse set for one redraw — visual-only, entirely client-side;
+ * the actual starve/eat removal already happened in the engine. Every id
+ * present in `prevAgents` but absent from `agents` died THIS tick — eaten or
+ * starved are the only two ways an agent ever leaves the engine's own returned
+ * roster — and is added at its last-known cell and class; every corpse already
+ * older than `lingerTurns` past its own death turn is dropped first, so the set
+ * never grows without bound. Returns a plain `{ [id]: { cls, cell, diedAtTurn }
+ * }` map. Pure. `lingerTurns` defaults to a literal 4 (not the module-level
+ * CORPSE_LINGER_TURNS constant) so this function stays fully `.toString()`-splice
+ * safe — every real caller (both the inlined page and CORPSE_LINGER_TURNS's own
+ * callers elsewhere in this module) passes it explicitly anyway.
  */
 export function nextCorpses(prevCorpses, prevAgents, agents, turn, lingerTurns = 4) {
   const out = {};
@@ -166,9 +163,9 @@ export function nextCorpses(prevCorpses, prevAgents, agents, turn, lingerTurns =
  *  back to the flat SPRITE_REGISTRY, unchanged from before this module
  *  existed).
  *  `?preview=1` on the page's own URL switches it into the small, auto-
- *  playing, non-interactive mode the home page's hero iframe embeds (§11) —
- *  one file serves both the hero and the "open full-screen" link, matching
- *  how ledger.html/plan.html are each one file embedded two ways.
+ *  playing, non-interactive mode the home page's hero iframe embeds — one file
+ *  serves both the hero and the "open full-screen" link, matching how
+ *  ledger.html/plan.html are each one file embedded two ways.
  *  `engineBundleJs` (the built spider-fly-browser bundle's own text) inlines
  *  the engine into the page instead of the sibling `<script src>`, for the
  *  CLI's standalone export — one downloadable file that runs from file://
@@ -344,11 +341,11 @@ ${THEME_TOKENS_CSS}
   .hud-id.spider { color: var(--taught); } .hud-id.fly { color: var(--fly); } .hud-id.egg { color: var(--muted); }
   .hud-goal { font-size: .85rem; }
   .hud-plan, .hud-belief { font-family: ${MONO_STACK}; font-size: .66rem; color: var(--muted); margin-top: .25rem; line-height: 1.4; padding-left: .5rem; border-left: 2px solid var(--chrome-accent); }
-  /* the click-expand facts panel (§28): beside the clicked spider/fly's own
-     row, never a separate popover or a second panel elsewhere on the page —
-     the same believedCellOf/beliefSnapshotFor read path spider-fly-turn.mjs
-     already computes every tick for planning, rendered here as full
-     sentences instead of the compact believes:-line above. */
+  /* the click-expand facts panel: beside the clicked spider/fly's own row,
+     never a separate popover or a second panel elsewhere on the page — the same
+     believedCellOf/beliefSnapshotFor read path spider-fly-turn.mjs already
+     computes every tick for planning, rendered here as full sentences instead of
+     the compact believes:-line above. */
   .hud-detail { flex: 1 1 auto; min-width: 0; font-family: ${MONO_STACK}; font-size: .64rem; line-height: 1.5; color: var(--chrome-well-ink); background: var(--chrome-well); border: 1px solid var(--chrome-edge-lo); box-shadow: var(--chrome-shadow-inset); border-radius: 2px; padding: .35rem .5rem; }
   .hud-detail-title { text-transform: uppercase; letter-spacing: .06em; opacity: .75; margin-bottom: .2rem; }
   /* A stat-readout track: an inset "LCD" well, filled with a segmented pip
@@ -378,11 +375,11 @@ ${THEME_TOKENS_CSS}
   .pill:hover:not(:disabled) { border-color: var(--chrome-accent); }
   .pill:disabled { opacity: .45; cursor: default; }
   .pill[data-role="addr"].active { border-color: var(--taught); color: var(--taught); }
-  /* The dynamic deception-pill rail (§A.2.4): a true/false tag shown ONLY
-     here, via border style/color and a small human-facing glyph — the
-     submitted sentence itself (data-sentence, filled into #chatq on click)
-     never carries the tag, so a clicked pill is indistinguishable from a
-     hand-typed claim once it's in the input. */
+  /* The dynamic deception-pill rail: a true/false tag shown ONLY here, via
+     border style/color and a small human-facing glyph — the submitted sentence
+     itself (data-sentence, filled into #chatq on click) never carries the tag,
+     so a clicked pill is indistinguishable from a hand-typed claim once it's in
+     the input. */
   .dynpills { display: flex; flex-wrap: wrap; gap: .3rem; margin-top: .5rem; padding-top: .5rem; border-top: 1px solid var(--chrome-edge-lo); }
   .dynpills:empty { display: none; padding-top: 0; border-top: none; }
   .pill[data-role="dyn-addr"][data-active="1"] { border-color: var(--taught); color: var(--taught); }
@@ -745,13 +742,13 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
     lastAgents = agents;
   }
 
-  // ---- corpses (§A.2.5): visual-only — the actual starve/eat removal
-  // already happened in the engine before this redraw ever sees "agents".
-  // A corpse sinks to the bottom row of the SAME board column it died in
-  // ("drops to the bottom" — spider-fly-world.mjs's own x/y convention,
-  // y = GRID_SIZE is the bottom row) and fades out once CORPSE_LINGER_TURNS
-  // passes, drawn in the same sprite layer as every live sprite, just
-  // grayscaled and non-interactive (see the .sprite.corpse CSS rule).
+  // ---- corpses: visual-only — the actual starve/eat removal already happened
+  // in the engine before this redraw ever sees "agents". A corpse sinks to the
+  // bottom row of the SAME board column it died in ("drops to the bottom" —
+  // spider-fly-world.mjs's own x/y convention, y = GRID_SIZE is the bottom row)
+  // and fades out once CORPSE_LINGER_TURNS passes, drawn in the same sprite
+  // layer as every live sprite, just grayscaled and non-interactive (see the
+  // .sprite.corpse CSS rule).
   function renderCorpses() {
     for (const id of Object.keys(corpseEls)) {
       if (!corpses[id]) { corpseEls[id].remove(); delete corpseEls[id]; }
@@ -793,12 +790,12 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
     return '<div class="hud-plan">plan: ' + text + ".</div>";
   }
 
-  // The agent's own current world-knowledge-graph snapshot (§A.2.7) — every
-  // OTHER live individual it believes it knows the position of, or
-  // "unseen" when it has no belief at all. Deliberately never ground truth:
-  // this is what the agent would actually ACT on, which a false pill or a
-  // told fact can make visibly wrong compared to where that individual
-  // really is — the gap IS the demonstration.
+  // The agent's own current world-knowledge-graph snapshot — every OTHER live
+  // individual it believes it knows the position of, or "unseen" when it has no
+  // belief at all. Deliberately never ground truth: this is what the agent
+  // would actually ACT on, which a false pill or a told fact can make visibly
+  // wrong compared to where that individual really is — the gap IS the
+  // demonstration.
   function beliefLineHtml(belief) {
     const entries = Object.entries(belief || {});
     if (!entries.length) return "";
@@ -1023,12 +1020,12 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   chatqEl.addEventListener("input", refreshPills);
   refreshPills();
 
-  // ---- deception pills (§A.2.4): a SEPARATE dynamic rail, alongside (never
-  // replacing) the static one above. tmct.page.pillsForSpiderFly is the
-  // exact same pure function spider-fly-turn.mjs exports — this page never
-  // reimplements the true/false claim logic, only renders its output and
-  // fills #chatq on click, same click-to-fill discipline as every other
-  // pill on this page (never auto-submits).
+  // ---- deception pills: a SEPARATE dynamic rail, alongside (never replacing)
+  // the static one above. tmct.page.pillsForSpiderFly is the exact same pure
+  // function spider-fly-turn.mjs exports — this page never reimplements the
+  // true/false claim logic, only renders its output and fills #chatq on click,
+  // same click-to-fill discipline as every other pill on this page (never
+  // auto-submits).
   function renderDynamicPills() {
     if (!session || !Object.keys(lastAgents).length) { dynamicPillsEl.innerHTML = ""; return; }
     const result = tmct.page.pillsForSpiderFly(lastAgents, selectedAddresseeId, {});