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

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)`
@@ -42,12 +39,10 @@
 //         agent or item, never the mid-lerp position. This is what an e2e
 //         assertion reads, and what a later screenshot ready-check reads too
 //         (see test-e2e/pages-mudiii.test.mjs's own header).
+//       .flashCell(cellId) / .showRoute(cells) / .clearRoute() — the clicked
+//         cell and the route the followed agent is walking to it, drawn along
+//         the cells the world's own exit search returned.
 //       .ready() — whether boot() has finished at least once.
-//   These three calls are not yet wired into mudiii-viz.mjs's own
-//   boot()/applyTickResult()/camera handlers — that file is owned by the viz
-//   track, not this one; the coordinator's own report names the exact call
-//   sites needed, mirroring how window.mudiiiHandleSceneClick was already
-//   added for the reverse direction.
 //
 // Reused from mudiii-viz.mjs rather than re-derived, off its own frozen
 // exports: `roleOfAgentId`, `cellToWorld`, `cellFromGroundPoint`,
@@ -70,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
@@ -102,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 };
 }
 
@@ -113,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);
@@ -130,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
@@ -144,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. */
@@ -319,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()};
@@ -366,8 +435,38 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
   // removal (source "ecology") apart from applyTick's own diff no-op
   // (source "diff") without guessing from a vanished mesh alone.
   var removalLog = [];
+  var routeLine = null, routeCells = [];
+  var flashMesh = null, flashUntil = 0;
+  var FLASH_MS = 600;
+  // The floor a one-shot flourish is held for when its own clip is shorter,
+  // long enough that a bite reads as a bite at the deck's fastest tick.
+  var ONE_SHOT_HOLD_MIN_MS = 450;
+  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;
 
@@ -404,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));
@@ -423,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();
@@ -445,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) {
@@ -461,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);
@@ -557,10 +744,8 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     }
   }
 
-  // ---- items: crumbs and morsels, the committed hay bale at two target
-  // heights (food-crumb 0.16, food-morsel 0.36 in data/mudiii-assets.json),
-  // matching the on-ground footprint the primitive spheres they replace were
-  // already tuned to. ---------------------------------------------------------
+  // ---- items: crumbs and morsels, both the committed hay bale, each at
+  // whatever targetHeight its own data/mudiii-assets.json row names. ----------
   function itemAssetKeyFor(kind) { return kind === "morsel" ? "food-morsel" : "food-crumb"; }
 
   function animateScaleTo(object3D, target, now) {
@@ -635,21 +820,56 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
   // correctly clone a SkinnedMesh, and at this roster size — a handful of
   // foxes and goblins — the extra memory of a separate load per agent is
   // trivial next to that whole class of bug). ---------------------------------
+  // The id, drawn to a canvas and hung above the agent as a sprite. Parenting
+  // it to the agent's own group means it rides the movement tween with no
+  // per-frame bookkeeping, and a sprite always faces the camera, so there is
+  // no facing maths either. sizeAttenuation off holds it at a constant size on
+  // screen — an id that shrinks to nothing as the camera pulls back is worse
+  // than no id at all — which is why the scale below is in screen fractions
+  // rather than world units.
+  var LABEL_SCREEN_WIDTH = 0.13;
+  function makeAgentLabel(id, height) {
+    var canvas = document.createElement("canvas");
+    canvas.width = 256;
+    canvas.height = 64;
+    var ctx = canvas.getContext("2d");
+    ctx.font = "bold 38px ui-monospace, SFMono-Regular, Menlo, monospace";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.lineWidth = 8;
+    ctx.lineJoin = "round";
+    ctx.strokeStyle = "rgba(20,16,10,.85)";
+    ctx.strokeText(id, 128, 34);
+    ctx.fillStyle = "#F3ECDD";
+    ctx.fillText(id, 128, 34);
+    var material = new THREE.SpriteMaterial({
+      map: new THREE.CanvasTexture(canvas), transparent: true, sizeAttenuation: false, depthWrite: false,
+    });
+    var sprite = new THREE.Sprite(material);
+    sprite.scale.set(LABEL_SCREEN_WIDTH, LABEL_SCREEN_WIDTH / 4, 1);
+    sprite.position.y = height + 0.3;
+    sprite.name = "label-" + id;
+    return sprite;
+  }
+
   function ensureAgent(id, agent) {
     if (agentGroups[id]) return agentGroups[id];
     var kind = roleOfAgentId(id);
     var entry = {
       group: new THREE.Group(), tween: null, cell: null, facing: agent.facing, role: agent.role,
       kind: kind, mixer: null, actions: {}, currentClip: null, clipMap: null, oneShotAction: null,
+      oneShotUntil: 0, model: null,
     };
     entry.group.visible = false;
     scene.add(entry.group);
     agentGroups[id] = entry;
     var asset = manifestByKind[kind];
+    entry.group.add(makeAgentLabel(id, asset ? asset.targetHeight : 1));
     if (asset) {
       loadGlbRaw(modelUrlFor(asset.destPath)).then(function (gltf) {
         normalizeToHeight(gltf.scene, asset.targetHeight);
         entry.group.add(gltf.scene);
+        entry.model = gltf.scene;
         entry.group.visible = true;
         entry.clipMap = asset.clips || {};
         entry.mixer = new THREE.AnimationMixer(gltf.scene);
@@ -671,6 +891,12 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     // keep blending into every clip after it, forever). Fade it out before
     // any of the guards below can skip the rest of this call.
     if (entry.oneShotAction) {
+      // A flourish holds for its own clip length, floored, before anything may
+      // fade it out. At the deck's 220ms default the next tick otherwise
+      // landed during the wind-up and a bite read as a twitch. This holds the
+      // ANIMATION only: the tick that arrived has already moved the agent, so
+      // the simulation never waits on a flourish.
+      if (performance.now() < entry.oneShotUntil) return;
       entry.oneShotAction.fadeOut(0.15);
       entry.oneShotAction = null;
     }
@@ -702,6 +928,9 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     action.fadeIn(0.15).play();
     if (prev) prev.fadeOut(0.15);
     entry.oneShotAction = action;
+    var clip = typeof action.getClip === "function" ? action.getClip() : null;
+    entry.oneShotUntil = performance.now()
+      + Math.max(ONE_SHOT_HOLD_MIN_MS, clip && clip.duration ? clip.duration * 1000 : 0);
     entry.currentClip = null;
   }
 
@@ -731,7 +960,10 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     }
     if (entry.clipMap) {
       var moving = singleHop;
-      playClip(entry, clipForAction(agent.role, currentActionFor(id, lastAgentsById, moving), entry.clipMap));
+      // A hand-driven step is a walk, whatever the agent believes: it did not
+      // choose to chase or flee, the visitor chose for it.
+      var action = moving && tickRungs[id] === "driven" ? "driven" : currentActionFor(id, lastAgentsById, moving);
+      playClip(entry, clipForAction(agent.role, action, entry.clipMap));
     }
   }
 
@@ -766,21 +998,101 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     }
   }
 
+  // ---- the clicked cell, and the route to it --------------------------------
+  // The line follows the cells the world's own exit search returned, never a
+  // straight segment from agent to target: a straight one cuts through
+  // buildings and promises a walk the board would refuse.
+  function clearRoute() {
+    routeCells = [];
+    if (!routeLine) return;
+    if (routeLine.parent) routeLine.parent.remove(routeLine);
+    routeLine.geometry.dispose();
+    routeLine.material.dispose();
+    routeLine = null;
+  }
+
+  function showRoute(cells) {
+    clearRoute();
+    if (!scene || !cells || cells.length < 2) return;
+    var points = [];
+    for (var i = 0; i < cells.length; i += 1) {
+      var world = cellToWorld(cells[i], GRID_SIZE, CELL_SIZE);
+      if (!world) return;
+      points.push(new THREE.Vector3(world.x, 0.09, world.z));
+    }
+    routeLine = new THREE.Line(
+      new THREE.BufferGeometry().setFromPoints(points),
+      new THREE.LineBasicMaterial({ color: 0xd98a2b }),
+    );
+    routeLine.name = "route";
+    scene.add(routeLine);
+    routeCells = cells.slice();
+  }
+
+  function clearFlash() {
+    if (!flashMesh) return;
+    if (flashMesh.parent) flashMesh.parent.remove(flashMesh);
+    flashMesh.geometry.dispose();
+    flashMesh.material.dispose();
+    flashMesh = null;
+  }
+
+  function flashCell(cell) {
+    if (!scene) return;
+    var world = cellToWorld(cell, GRID_SIZE, CELL_SIZE);
+    if (!world) return;
+    clearFlash();
+    flashMesh = new THREE.Mesh(
+      new THREE.PlaneGeometry(CELL_SIZE, CELL_SIZE),
+      new THREE.MeshBasicMaterial({ color: 0xd98a2b, transparent: true, opacity: 0.75 }),
+    );
+    flashMesh.name = "cell-flash";
+    flashMesh.rotation.x = -Math.PI / 2;
+    flashMesh.position.set(world.x, 0.03, world.z);
+    scene.add(flashMesh);
+    flashUntil = performance.now() + FLASH_MS;
+  }
+
   // ---- camera ---------------------------------------------------------------
   function agentSnapshotFor(id) {
     var entry = agentGroups[id];
     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
@@ -790,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 --------------------------------------------
@@ -817,9 +1128,15 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     itemMeshes = {};
     lastAgentsById = {};
     lastItemsById = {};
+    tickRungs = {};
+    clearRoute();
+    clearFlash();
     removalLog = [];
     manifestByKind = buildManifestByKind(input && input.assetManifest);
     await placeProps((input && input.propPlacements) || []);
+    cameraRigged = false;
+    lookTarget = null;
+    drag = null;
     setCamera({ mode: "overhead", selectedId: null });
     booted = true;
   }
@@ -829,6 +1146,7 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     var now = performance.now();
     var agents = (tick && tick.agents) || {};
     var items = (tick && tick.items) || {};
+    tickRungs = (tick && tick.rungs) || {};
     for (var id in agents) if (Object.prototype.hasOwnProperty.call(agents, id)) applyAgentTick(id, agents[id], now);
     for (var itemId in items) if (Object.prototype.hasOwnProperty.call(items, itemId)) applyItemTick(itemId, items[itemId], now);
     // Ecology first: an eaten agent/item is already gone from this tick's own
@@ -859,8 +1177,34 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
       }
       if (entry.mixer) entry.mixer.update(deltaSec);
     }
-    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); }
+    if (flashMesh) {
+      var flashLeft = flashUntil - performance.now();
+      if (flashLeft <= 0) clearFlash();
+      else flashMesh.material.opacity = 0.75 * (flashLeft / FLASH_MS);
+    }
+    // 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);
   }
@@ -869,6 +1213,13 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     boot: boot,
     applyTick: applyTick,
     setCamera: setCamera,
+    flashCell: flashCell,
+    showRoute: showRoute,
+    clearRoute: clearRoute,
+    // The route currently drawn, cell by cell — an e2e assertion's read, so
+    // it can check the line follows the board's own exits rather than
+    // counting pixels on a software renderer.
+    routeCellsDrawn: function () { return routeCells.slice(); },
     cellOf: function (id) {
       if (agentGroups[id]) return agentGroups[id].cell;
       if (itemMeshes[id]) return itemMeshes[id].cell;
@@ -886,10 +1237,13 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     // manifest's own targetHeight to compare it against — an e2e assertion's
     // read, so it goes through the group actually in the scene rather than a
     // second, locally invented measurement.
+    // Measured through the loaded MODEL, never the whole group: the group
+    // also carries the id label, whose sprite geometry would widen the box
+    // and report a height nobody rendered.
     meshHeightOf: function (id) {
       var entry = agentGroups[id];
-      if (!entry || !entry.group || entry.group.children.length === 0) return null;
-      var box = new THREE.Box3().setFromObject(entry.group);
+      if (!entry || !entry.model) return null;
+      var box = new THREE.Box3().setFromObject(entry.model);
       var size = new THREE.Vector3();
       box.getSize(size);
       var asset = manifestByKind[entry.kind];
@@ -904,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; },
   };
 })();`;