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

package/src/services/mudiii-scene.mjs

@@ -11,11 +11,8 @@
 // this file renders is a read of one of those two — never a second, locally
 // invented notion of where an agent stands.
 //
-// PLAN_MUD_MUDIII.md's own render-layer section is corrected in two places
-// this file follows rather than the doc's original text: GLTFLoader ships in
-// the vendor bundle (handles KHR_mesh_quantization and EXT_texture_webp
-// natively; only EXT_meshopt_compression needs a decoder line), and there is
-// no globalThis.tmctMudiii — pages publish one globalThis.tmct.
+// GLTFLoader ships in the vendor bundle, and handles KHR_mesh_quantization and
+// EXT_texture_webp natively; only EXT_meshopt_compression needs a decoder line.
 //
 // The page-shell <-> scene handshake, since the two scripts share no scope:
 //   - the page shell already defines `window.mudiiiHandleSceneClick(cellId)`
@@ -68,6 +65,12 @@ import { prefersReducedMotion } from "./viz-ticker.mjs";
  *  own `transition: left .25s ease` becomes in a requestAnimationFrame loop. */
 export const TWEEN_DURATION_MS = 250;
 
+/** The vertical field of view the page's one perspective camera is built with.
+ *  Every rig this scene asks `cameraRigFor` for is measured against the live
+ *  `camera3.fov`, so this number is only ever the camera's own starting value
+ *  rather than a second copy a rig could drift from. */
+export const CAMERA_FIELD_OF_VIEW_DEGREES = 55;
+
 // ---------------------------------------------------------------------------
 // Pure geometry/tween helpers — unit-tested directly in Node, then spliced
 // via `.toString()` into the standalone browser IIFE below, the same
@@ -100,8 +103,11 @@ export function tweenStep(tween, now) {
   return { ...point, t, done: false };
 }
 
-/** A fresh tween from `from` to `to`, starting at `now`. Pure. */
-export function startTween(from, to, now, durationMs = TWEEN_DURATION_MS) {
+/** A fresh tween from `from` to `to`, starting at `now`. Pure — the default
+ *  duration is written out rather than read from `TWEEN_DURATION_MS`, because
+ *  the browser runs a `.toString()` copy of this function in a script that
+ *  declares no such binding. mudiii-viz.test.mjs holds the two together. */
+export function startTween(from, to, now, durationMs = 250) {
   return { from, to, startedAt: now, durationMs };
 }
 
@@ -111,7 +117,7 @@ export function startTween(from, to, now, durationMs = TWEEN_DURATION_MS) {
  *  tweening); `to` is the new destination point. Pure — `tweenStep` is
  *  called on the OLD tween at `now` to read the current position before
  *  building the new one. */
-export function reseedTween(existingTween, to, now, durationMs = TWEEN_DURATION_MS) {
+export function reseedTween(existingTween, to, now, durationMs = 250) {
   const current = existingTween ? tweenStep(existingTween, now) : null;
   const from = current ? Object.fromEntries(Object.keys(to).map((k) => [k, current[k]])) : to;
   return startTween(from, to, now, durationMs);
@@ -128,6 +134,69 @@ export function chebyshevDistanceBetweenCells(a, b) {
   return Math.max(Math.abs(Number(ma[1]) - Number(mb[1])), Math.abs(Number(ma[2]) - Number(mb[2])));
 }
 
+/** Where the camera should aim once the visitor's own drag is applied on top
+ *  of the rig's aim. `position` is where the rig put the camera, `lookAt` is
+ *  where the rig wants it pointed, and `offset` is `{ yaw, pitch }` in radians
+ *  — the drag's accumulated turn, held apart from the rig so a tick that
+ *  recomputes the rig leaves the visitor's view alone.
+ *
+ *  The offset turns the rig's own aim rather than replacing it, so the view
+ *  swings with the agent when it turns: in POV that reads as the animal
+ *  turning its head, which is the whole point of riding one.
+ *
+ *  Pitch is clamped to 1.2 radians (about 69 degrees) either side of level, so
+ *  a long upward drag can never carry the view past vertical and roll the
+ *  board upside down. The returned `pitchOffset` is what survived that clamp,
+ *  which the caller writes back over its own accumulator — otherwise a drag
+ *  held past the clamp banks up an offset the view never shows, and the next
+ *  drag back the other way does nothing until it has spent it.
+ *
+ *  Returns `{ x, y, z, pitchOffset }`. Pure, self-contained. */
+export function lookTargetWithOffset(position, lookAt, offset) {
+  const MAX_PITCH_RADIANS = 1.2;
+  const yaw = Number(offset && offset.yaw) || 0;
+  const pitch = Number(offset && offset.pitch) || 0;
+  if (!yaw && !pitch) return { x: lookAt.x, y: lookAt.y, z: lookAt.z, pitchOffset: 0 };
+  const dx = lookAt.x - position.x;
+  const dy = lookAt.y - position.y;
+  const dz = lookAt.z - position.z;
+  const radius = Math.sqrt(dx * dx + dy * dy + dz * dz);
+  if (!radius) return { x: lookAt.x, y: lookAt.y, z: lookAt.z, pitchOffset: 0 };
+  const basePitch = Math.asin(Math.max(-1, Math.min(1, dy / radius)));
+  const aimedPitch = Math.max(-MAX_PITCH_RADIANS, Math.min(MAX_PITCH_RADIANS, basePitch + pitch));
+  const aimedYaw = Math.atan2(dx, dz) + yaw;
+  const flat = Math.cos(aimedPitch) * radius;
+  return {
+    x: position.x + flat * Math.sin(aimedYaw),
+    y: position.y + radius * Math.sin(aimedPitch),
+    z: position.z + flat * Math.cos(aimedYaw),
+    pitchOffset: aimedPitch - basePitch,
+  };
+}
+
+/** The town square's own sky, as gradient stops running from straight up
+ *  (`at` 0) to straight down (`at` 1), each `{ at, color }`.
+ *
+ *  The colours are the page's own `--square-sky`, `--square-horizon`,
+ *  `--square-stone` and `--square-stone-dark`, in the order the page body's
+ *  own background already reads them, so the canvas continues the page it
+ *  sits in rather than cutting a dark hole in it. The board is twelve units
+ *  across with nothing beyond it, so a camera aimed anywhere off it — the
+ *  opening follow shot, an overhead orbit, a long look-drag in POV — is
+ *  looking at this and nothing else.
+ *
+ *  The band sits at 0.5 because that is the horizon in an equirectangular
+ *  projection, where the caller maps these onto a sphere. Pure,
+ *  self-contained. */
+export function skyGradientStops() {
+  return [
+    { at: 0, color: "#BFE3F0" },
+    { at: 0.46, color: "#E9D9B6" },
+    { at: 0.52, color: "#8C8172" },
+    { at: 1, color: "#59503F" },
+  ];
+}
+
 /** A facing word to a Y rotation in radians. Assumes a model's own local
  *  forward is +Z (true for fox and goblin, the two rigs in the current
  *  manifest, checked by walking each GLB's own bind-pose bone chain) so a
@@ -142,7 +211,7 @@ export function yawForFacing(facing) {
 /** Whether `agentId` (predator or prey) currently believes an agent of the
  *  opposing role — the one belief-derived bit that separates a predator's
  *  "chase" rung from "wander", and a prey's "evade" rung from "forage"/
- *  "wander" (PLAN_MUD_MUDIII.md's own priority chains). Read entirely off
+ *  "wander". Read entirely off
  *  the tick payload's own `role`/`belief` fields — no rung name travels on
  *  the wire, so this reconstructs which rung applied rather than trusting a
  *  label. Pure. */
@@ -317,6 +386,8 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
   var startTween = ${startTween.toString()};
   var reseedTween = ${reseedTween.toString()};
   var chebyshevDistanceBetweenCells = ${chebyshevDistanceBetweenCells.toString()};
+  var lookTargetWithOffset = ${lookTargetWithOffset.toString()};
+  var skyGradientStops = ${skyGradientStops.toString()};
   var yawForFacing = ${yawForFacing.toString()};
   var threatEngagedFor = ${threatEngagedFor.toString()};
   var movementRungFor = ${movementRungFor.toString()};
@@ -373,6 +444,29 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
   var tickRungs = {};
   var cameraState = { mode: "overhead", selectedId: null };
   var cameraTween = null, lookAtTween = null;
+  // Where the rig last wanted the camera pointed. Held past the end of its own
+  // tween because the visitor's look is re-applied every frame, not only while
+  // the tween runs.
+  var lookTarget = null;
+  // Whether setCamera has rigged the camera at least once. Without it the very
+  // first call — boot's own overhead call, which changes nothing — would read
+  // as "no change" and leave the camera at its construction position.
+  var cameraRigged = false;
+  // Whether the visitor has turned or zoomed the overhead view themselves.
+  // OrbitControls writes straight to the camera, so a resize cannot tell an
+  // orbited view from a rigged one by reading the camera back.
+  var overheadOrbited = false;
+  // The visitor's own look, turned by dragging the canvas and applied on top
+  // of whatever rig the camera mode computes. It survives every tick: a tick
+  // re-issues setCamera with the same mode and the same agent, so clearing it
+  // there would snap the view back a fifth of a second after every drag.
+  var lookOffset = { yaw: 0, pitch: 0 };
+  var LOOK_RADIANS_PER_PIXEL = 0.005;
+  // How far a pointer may travel and still count as a click on a cell rather
+  // than a drag. Without it every look-around also walked the followed agent
+  // to whatever cell the drag started over.
+  var CLICK_SLOP_PX = 6;
+  var drag = null;
   var lastFrameTs = null;
   var booted = false;
 
@@ -409,10 +503,31 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     return true;
   }
 
+  // Equirectangular, not a flat screen-space backdrop: three maps this onto a
+  // sphere around the camera, so the horizon stays put as the visitor turns
+  // instead of sliding with the view. Eight pixels wide is enough for a
+  // gradient with no horizontal variation, and wraps with no seam.
+  function buildSkyTexture() {
+    var swatch = document.createElement("canvas");
+    swatch.width = 8;
+    swatch.height = 256;
+    var ctx = swatch.getContext("2d");
+    var gradient = ctx.createLinearGradient(0, 0, 0, swatch.height);
+    var stops = skyGradientStops();
+    for (var i = 0; i < stops.length; i += 1) gradient.addColorStop(stops[i].at, stops[i].color);
+    ctx.fillStyle = gradient;
+    ctx.fillRect(0, 0, swatch.width, swatch.height);
+    var texture = new THREE.CanvasTexture(swatch);
+    texture.mapping = THREE.EquirectangularReflectionMapping;
+    if (THREE.SRGBColorSpace) texture.colorSpace = THREE.SRGBColorSpace;
+    texture.needsUpdate = true;
+    return texture;
+  }
+
   function setUpScene() {
     scene = new THREE.Scene();
-    scene.background = new THREE.Color(0x10161b);
-    camera3 = new THREE.PerspectiveCamera(55, (canvas.clientWidth || 640) / Math.max(1, canvas.clientHeight || 360), 0.1, 500);
+    scene.background = buildSkyTexture();
+    camera3 = new THREE.PerspectiveCamera(${CAMERA_FIELD_OF_VIEW_DEGREES}, canvasAspect(), 0.1, 500);
     camera3.position.set(0, 8, 8);
     renderer = new THREE.WebGLRenderer({ canvas: canvas, antialias: true });
     scene.add(new THREE.HemisphereLight(0xffffff, 0x444444, 1.2));
@@ -428,6 +543,15 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     orbitControls.target.set(0, 0, 0);
 
     canvas.addEventListener("pointerdown", onPointerDown);
+    canvas.addEventListener("wheel", function () {
+      if (cameraState.mode === "overhead") overheadOrbited = true;
+    }, { passive: true });
+    // On the window, not the canvas: a look-around that runs off the edge of
+    // the 3D stage must keep turning, and must still end when the button comes
+    // up over the deck.
+    window.addEventListener("pointermove", onPointerMove);
+    window.addEventListener("pointerup", onPointerUp);
+    window.addEventListener("pointercancel", onPointerCancel);
     window.addEventListener("resize", onResize);
     watchFoodPill();
     onResize();
@@ -450,12 +574,35 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     scene.add(grid);
   }
 
+  function canvasAspect() {
+    return (canvas.clientWidth || 640) / Math.max(1, canvas.clientHeight || 360);
+  }
+
+  // What the overhead rig has to fit the board into. Read off the LIVE camera
+  // so one field of view drives both the projection and the distance chosen to
+  // suit it.
+  function cameraView() {
+    return { aspect: canvasAspect(), fovDegrees: camera3 ? camera3.fov : ${CAMERA_FIELD_OF_VIEW_DEGREES} };
+  }
+
   function onResize() {
     if (!renderer || !camera3) return;
     var w = canvas.clientWidth || 640, h = canvas.clientHeight || 360;
     renderer.setSize(w, h, false);
-    camera3.aspect = w / Math.max(1, h);
+    camera3.aspect = canvasAspect();
     camera3.updateProjectionMatrix();
+    refitOverheadCamera();
+  }
+
+  // A new canvas shape fits a different amount of board, so the overhead rig is
+  // recomputed for it — a phone turned on its side otherwise keeps the height
+  // the old shape earned and crops the board's edges. A visitor who has already
+  // orbited keeps the view they made: pulling it back to the board's centre
+  // would undo their own gesture.
+  function refitOverheadCamera() {
+    if (!cameraRigged || cameraState.mode !== "overhead" || overheadOrbited) return;
+    var rig = cameraRigFor("overhead", null, GRID_SIZE, cameraView());
+    if (rig) tweenCameraToRig(rig, performance.now());
   }
 
   function pointFromEvent(evt) {
@@ -466,11 +613,46 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     };
   }
 
+  // A press starts a drag rather than resolving a cell. Which of the two it
+  // turns out to be is only known when the button comes up, and until then
+  // pointermove turns the camera.
+  function onPointerDown(evt) {
+    if (!scene || !camera3 || !groundMesh) return;
+    drag = { pointerId: evt.pointerId, startX: evt.clientX, startY: evt.clientY, lastX: evt.clientX, lastY: evt.clientY, travelled: 0 };
+  }
+
+  function onPointerMove(evt) {
+    if (!drag || (drag.pointerId != null && evt.pointerId !== drag.pointerId)) return;
+    var dx = evt.clientX - drag.lastX;
+    var dy = evt.clientY - drag.lastY;
+    drag.lastX = evt.clientX;
+    drag.lastY = evt.clientY;
+    drag.travelled += Math.abs(dx) + Math.abs(dy);
+    // Overhead is OrbitControls' own drag, and two things turning one camera
+    // fight each other.
+    if (cameraState.mode === "overhead") { overheadOrbited = true; return; }
+    lookOffset.yaw -= dx * LOOK_RADIANS_PER_PIXEL;
+    lookOffset.pitch -= dy * LOOK_RADIANS_PER_PIXEL;
+  }
+
+  function onPointerUp(evt) {
+    if (!drag || (drag.pointerId != null && evt.pointerId !== drag.pointerId)) return;
+    var straightLine = Math.abs(evt.clientX - drag.startX) + Math.abs(evt.clientY - drag.startY);
+    var wasDrag = drag.travelled > CLICK_SLOP_PX || straightLine > CLICK_SLOP_PX;
+    drag = null;
+    if (wasDrag) return;
+    resolveCellClick(evt);
+  }
+
+  function onPointerCancel() { drag = null; }
+
   // The raycast target is the ground mesh ALONE — never scene.children — so
   // a click a hair off a prop or an agent still resolves to the cell under
   // the cursor rather than hitting whatever mesh happens to sit in front.
-  function onPointerDown(evt) {
+  function resolveCellClick(evt) {
     if (!scene || !camera3 || !groundMesh) return;
+    var rect = canvas.getBoundingClientRect();
+    if (evt.clientX < rect.left || evt.clientX > rect.right || evt.clientY < rect.top || evt.clientY > rect.bottom) return;
     var ndc = pointFromEvent(evt);
     raycaster.setFromCamera(ndc, camera3);
     var hits = raycaster.intersectObject(groundMesh, false);
@@ -877,15 +1059,40 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     return entry ? { cell: entry.cell, facing: entry.facing } : null;
   }
 
+  // Both tweens start from where the camera ACTUALLY is, never from the old
+  // tween's own endpoint: the visitor may have dragged or orbited it somewhere
+  // else since, and a tween seeded off the rig alone teleports past that.
+  function tweenCameraToRig(rig, now) {
+    var from = camera3
+      ? { x: camera3.position.x, y: camera3.position.y, z: camera3.position.z }
+      : rig.position;
+    cameraTween = startTween(from, rig.position, now, tweenDurationMs);
+    lookAtTween = startTween(lookTarget || rig.lookAt, rig.lookAt, now, tweenDurationMs);
+  }
+
+  // Re-rigs the camera ONLY when the mode or the followed agent actually
+  // changed. Every tick calls this with the state it already had, and re-rigging
+  // on those calls is what snapped a dragged view back a fifth of a second
+  // after every drag, and what undid an overhead orbit a frame after it was
+  // made. Tracking the agent as it moves is refreshCameraTween's job below,
+  // which leaves the visitor's own look alone.
   function setCamera(state) {
-    cameraState = { mode: (state && state.mode) || "overhead", selectedId: (state && state.selectedId) || null };
+    var next = { mode: (state && state.mode) || "overhead", selectedId: (state && state.selectedId) || null };
+    var changed = !cameraRigged || next.mode !== cameraState.mode || next.selectedId !== cameraState.selectedId;
+    cameraState = next;
+    if (orbitControls) orbitControls.enabled = cameraState.mode === "overhead";
+    if (!changed) return;
+    // A new mode or a new agent is a request for a fresh view, so the drag's
+    // own turn goes with the old one.
+    lookOffset.yaw = 0;
+    lookOffset.pitch = 0;
+    overheadOrbited = false;
     var agent = cameraState.selectedId ? agentSnapshotFor(cameraState.selectedId) : null;
-    var rig = cameraRigFor(cameraState.mode, agent, GRID_SIZE) || cameraRigFor("overhead", null, GRID_SIZE);
+    var view = cameraView();
+    var rig = cameraRigFor(cameraState.mode, agent, GRID_SIZE, view) || cameraRigFor("overhead", null, GRID_SIZE, view);
     if (!rig) return;
-    var now = performance.now();
-    cameraTween = reseedTween(cameraTween, rig.position, now, tweenDurationMs);
-    lookAtTween = reseedTween(lookAtTween, rig.lookAt, now, tweenDurationMs);
-    if (orbitControls) orbitControls.enabled = cameraState.mode === "overhead";
+    cameraRigged = true;
+    tweenCameraToRig(rig, performance.now());
   }
 
   // Re-tween the camera toward its own rig after a tick lands, in case the
@@ -895,10 +1102,9 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     if (cameraState.mode === "overhead") return;
     if (!cameraState.selectedId) return;
     var agent = agentSnapshotFor(cameraState.selectedId);
-    var rig = cameraRigFor(cameraState.mode, agent, GRID_SIZE);
+    var rig = cameraRigFor(cameraState.mode, agent, GRID_SIZE, cameraView());
     if (!rig) return;
-    cameraTween = reseedTween(cameraTween, rig.position, now, tweenDurationMs);
-    lookAtTween = reseedTween(lookAtTween, rig.lookAt, now, tweenDurationMs);
+    tweenCameraToRig(rig, now);
   }
 
   // ---- boot / tick / render loop --------------------------------------------
@@ -928,6 +1134,9 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     removalLog = [];
     manifestByKind = buildManifestByKind(input && input.assetManifest);
     await placeProps((input && input.propPlacements) || []);
+    cameraRigged = false;
+    lookTarget = null;
+    drag = null;
     setCamera({ mode: "overhead", selectedId: null });
     booted = true;
   }
@@ -973,8 +1182,29 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
       if (flashLeft <= 0) clearFlash();
       else flashMesh.material.opacity = 0.75 * (flashLeft / FLASH_MS);
     }
-    if (cameraTween) { var cp = tweenStep(cameraTween, ts); camera3.position.set(cp.x, cp.y, cp.z); }
-    if (lookAtTween) { var lp = tweenStep(lookAtTween, ts); camera3.lookAt(lp.x, lp.y, lp.z); }
+    // A finished tween is dropped rather than re-applied every frame. Left in
+    // place it pinned the camera to its rig point on every single frame, which
+    // is what stopped an overhead orbit from surviving the frame it was made in.
+    if (cameraTween) {
+      var cp = tweenStep(cameraTween, ts);
+      camera3.position.set(cp.x, cp.y, cp.z);
+      if (cp.done) cameraTween = null;
+    }
+    if (lookAtTween) {
+      var lp = tweenStep(lookAtTween, ts);
+      lookTarget = { x: lp.x, y: lp.y, z: lp.z };
+      if (lp.done) lookAtTween = null;
+    }
+    // Follow and pov aim every frame, tween or no tween, because the visitor's
+    // own drag has to keep showing between ticks. Overhead hands the camera to
+    // OrbitControls once its own tween is spent.
+    if (lookTarget && cameraState.mode !== "overhead") {
+      var aimed = lookTargetWithOffset(camera3.position, lookTarget, lookOffset);
+      lookOffset.pitch = aimed.pitchOffset;
+      camera3.lookAt(aimed.x, aimed.y, aimed.z);
+    } else if (lookTarget && lookAtTween) {
+      camera3.lookAt(lookTarget.x, lookTarget.y, lookTarget.z);
+    }
     if (orbitControls && orbitControls.enabled) orbitControls.update();
     renderer.render(scene, camera3);
   }
@@ -1028,6 +1258,23 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
       for (var i = 0; i < removalLog.length; i += 1) if (removalLog[i].id === id) out.push(removalLog[i]);
       return out;
     },
+    // How much of the canvas the ground plane actually covers, width and
+    // height, each 0..1 — an e2e assertion's read, so a framing check measures
+    // the projection the visitor sees rather than re-deriving the rig from the
+    // numbers that built it. The four corners are projected through the live
+    // camera, so a cropped board reads over 1 on the axis it runs off.
+    boardFrameFraction: function () {
+      if (!camera3 || !groundMesh) return null;
+      var half = (GRID_SIZE * CELL_SIZE) / 2;
+      var minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+      var corners = [[-half, -half], [-half, half], [half, -half], [half, half]];
+      for (var i = 0; i < corners.length; i += 1) {
+        var ndc = new THREE.Vector3(corners[i][0], 0, corners[i][1]).project(camera3);
+        minX = Math.min(minX, ndc.x); maxX = Math.max(maxX, ndc.x);
+        minY = Math.min(minY, ndc.y); maxY = Math.max(maxY, ndc.y);
+      }
+      return { width: (maxX - minX) / 2, height: (maxY - minY) / 2 };
+    },
     ready: function () { return booted; },
   };
 })();`;

package/src/services/mudiii-turn.mjs

@@ -3,9 +3,9 @@
 // command, the addressed teach-frame (extended to the food channel spider-fly
 // has no equivalent of), the bare "tick" command, the player's own food-
 // placement verb, and the belief and orientation asides. The fifth lane on
-// the shared plan slot, shaped exactly like spider-fly-turn.mjs (PLAN_MUD_
-// MUDIII.md, "The chat lane") with vocabulary from predator-prey.mjs's own
-// MUDIII_ROLES: fox hunts goblin, goblins forage crumbs and morsels.
+// the shared plan slot, shaped exactly like spider-fly-turn.mjs, with
+// vocabulary from predator-prey.mjs's own MUDIII_ROLES: fox hunts goblin,
+// goblins forage crumbs and morsels.
 //
 // This module never plans a move or runs the ecology pass itself — every bit
 // of game logic (fold, pathfinding, belief, ecology, food placement) lives in
@@ -21,7 +21,7 @@ import {
   MUDIII_ROLES, foldTownSquareState, startTownSquareGame, runTownSquareTick,
   placeFood, roleOfId, beliefSnapshotFor,
 } from "./predator-prey.mjs";
-import { snapshotSubject } from "./adventure.mjs";
+import { snapshotSubject, parseSnapshotSubject } from "./adventure.mjs";
 import { correctMisspellings, QUESTION_LEAD_RE } from "../domain/interpret/normalize.mjs";
 import { worldProvenanceTag } from "../domain/worlds-pack.mjs";
 import { getWorldsPackProvider } from "../adapters/corpus/worlds-pack.mjs";
@@ -424,6 +424,63 @@ export function believedFactSentence(id, believedCell) {
   return believedCell ? `${id} is at ${believedCell}.` : `${id} has not been observed.`;
 }
 
+// The mark both visitor-driven write paths stamp on a placement row: the teach
+// lane's `world:<name>:taught:turnK`, and placeFood's own, which builds the
+// same tag. The board's own ticks write the bare world tag with no such mark.
+const TAUGHT_PROVENANCE_MARK = ":taught:";
+
+/** Every subject standing where a VISITOR put it — taught into place by a
+ *  sentence, or dropped there by the food verb. Both write the same
+ *  `:taught:turnK` provenance, and the board's own ticks write none of it.
+ *
+ *  Reads the row that WON, ranked the way foldTownSquareState ranks a
+ *  placement, so a crumb a visitor moved and the board has since moved on from
+ *  no longer counts. `epoch` is the fold's own, which unstamped rows (a
+ *  hand-built fixture, a seed row) are ranked at. Pure. */
+export function taughtPlacementSubjects(factRows, epoch = 0) {
+  const winner = new Map(); // subject -> { epoch, turn, taught }
+  for (const row of factRows || []) {
+    if (row.predicate !== PLACEMENT_PREDICATE) continue;
+    const snap = parseSnapshotSubject(row.subject);
+    const base = snap ? snap.base : row.subject;
+    const rowEpoch = snap ? snap.epoch : epoch;
+    const turn = snap ? snap.turn : 0;
+    const prior = winner.get(base);
+    if (prior && !(rowEpoch > prior.epoch || (rowEpoch === prior.epoch && turn >= prior.turn))) continue;
+    winner.set(base, { epoch: rowEpoch, turn, taught: String(row.provenance || "").includes(TAUGHT_PROVENANCE_MARK) });
+  }
+  const taught = new Set();
+  for (const [subject, entry] of winner) if (entry.taught) taught.add(subject);
+  return taught;
+}
+
+/** One observer's whole belief snapshot as a sentence.
+ *
+ *  Anything the observer can place is named: seen, or told. So is anything the
+ *  visitor put where it stands, seen or not, because the teach lane exists so
+ *  a claim about ONE individual lands where a visitor can watch it, and an
+ *  individual that dissolved into a count would take that with it.
+ *
+ *  Everything else unobserved is counted rather than listed. A square at its
+ *  food cap otherwise answers a question about what a goblin can see with a
+ *  row of crumbs it cannot, and the list grows with the cap.
+ *
+ *  `beliefEntries` is `Object.entries(beliefSnapshotFor(...))` and
+ *  `taughtSubjects` a Set from taughtPlacementSubjects. Pure. */
+export function beliefLineFor(observerId, beliefEntries, taughtSubjects) {
+  const taught = taughtSubjects || new Set();
+  const named = [];
+  let unobserved = 0;
+  for (const [id, cell] of beliefEntries || []) {
+    if (cell || taught.has(id)) named.push(believedFactSentence(id, cell));
+    else unobserved += 1;
+  }
+  if (!named.length && !unobserved) return `${observerId} is alone on the board — nothing else to see.`;
+  const rest = unobserved === 1 ? "1 other has not been observed." : `${unobserved} others have not been observed.`;
+  if (!named.length) return `${observerId} sees nothing yet. ${rest}`;
+  return `${observerId} sees: ${named.join(" ")}${unobserved ? ` ${rest}` : ""}`;
+}
+
 /** "what does the goblin see?" / "what does the fox see?" rendered as plain
  *  text: the same beliefSnapshotFor read predator-prey.mjs's own tick loop
  *  uses, over the CURRENT board state — read-only, no tick runs. Candidates
@@ -431,7 +488,9 @@ export function believedFactSentence(id, believedCell) {
  *  goblin's own forage target), exactly the beliefCandidates set
  *  runTownSquareTick itself builds. toldFacts is empty — a told position only
  *  ever arrives fresh alongside a tick, so there is none standing between
- *  ticks to read back here. */
+ *  ticks to read back here. beliefLineFor turns the snapshot into the
+ *  sentence, naming what the observer can place and what a visitor put where
+ *  it stands, and counting the rest. */
 async function mudiiiBeliefAnswer(match, { memoryDir, gameConfig = DEFAULT_GAME_CONFIG }) {
   const kind = match[1].toLowerCase();
   const num = match[2];
@@ -451,10 +510,7 @@ async function mudiiiBeliefAnswer(match, { memoryDir, gameConfig = DEFAULT_GAME_
     ? gameConfig?.mudiii?.predatorVisionRadius
     : gameConfig?.mudiii?.preyVisionRadius;
   const belief = beliefSnapshotFor(observerId, observerCell, candidateIds, state, { visionRadius });
-  const entries = Object.entries(belief);
-  const text = entries.length
-    ? `${observerId} sees: ${entries.map(([id, cell]) => believedFactSentence(id, cell)).join(" ")}`
-    : `${observerId} is alone on the board — nothing else to see.`;
+  const text = beliefLineFor(observerId, Object.entries(belief), taughtPlacementSubjects(rows, state.epoch));
   return {
     text,
     lane: "game-inform",