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

package/src/services/p2p-room.mjs

@@ -266,7 +266,7 @@ export function createP2pRoom({
   // is a change worth broadcasting even though its provenance never moved.
   let cachedRetractions = [];
   const seenRetractionValueById = new Map();
-  const retractionDiffValue = (fact) => `${fact.provenance}${fact.object}`;
+  const retractionDiffValue = (fact) => `${fact.provenance}\u0000${fact.object}`;
 
   // Store-touching work runs one job at a time, in arrival order. Every path
   // that reads or writes memoryDir/seenProvenanceById/cachedRows crosses at

package/src/services/plan-viz.mjs

@@ -18,7 +18,7 @@
 // inline script degrades honestly when that sibling script is absent or
 // fails to load — the live controls disable themselves rather than pretend
 // to work.
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, countLabel } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, countLabel, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import { planToPddl } from "./plan-pddl.mjs";
 
 const BOARD_W = 640;
@@ -334,6 +334,7 @@ button { font: inherit; }
 /* ---- head strip: the nameplate ---- */
 .headStrip { display: flex; justify-content: space-between; align-items: flex-end; gap: .6rem; flex-wrap: wrap; padding: .9rem 1.1rem .75rem; background: linear-gradient(180deg, var(--strip2), var(--strip)); border-bottom: 1px solid var(--line); border-radius: 9px 9px 0 0; }
 .eyebrow { font-family: ${MONO_STACK}; font-size: .64rem; letter-spacing: .16em; text-transform: uppercase; color: var(--muted); margin: 0 0 .35rem; }
+${EYEBROW_LINKS_CSS}
 h1 { font-family: ${SERIF_STACK}; font-size: 1.2rem; font-weight: 600; margin: 0; color: var(--ink); }
 .chip { font-family: ${MONO_STACK}; font-size: .64rem; letter-spacing: .02em; color: var(--muted); border: 1px solid var(--line); border-radius: 3px; padding: .22rem .6rem; background: var(--well); text-align: right; }
 
@@ -432,7 +433,7 @@ h1 { font-family: ${SERIF_STACK}; font-size: 1.2rem; font-weight: 600; margin: 0
 <div class="rack">
   <div class="headStrip">
     <div>
-      <div class="eyebrow">tmct &middot; plan</div>
+      <div class="eyebrow">${demoEyebrowHtml("plan", "plan")}</div>
       <h1 id="pageTitle">${escapeHtml(pageTitle)}</h1>
     </div>
     <span class="chip">blocks archetype · ${pageData.layouts.length} snapshots · plan: findActionPath</span>
@@ -529,6 +530,11 @@ const PLAN = ${embedded};
   // server-rendered embed, for a plain renderPlanHtml() caller with no live
   // bundle nearby).
   let plan = null, N = 0, blockEls = {}, step = 0, playing = false, animating = false;
+  // The promise of whatever animateMove() call is currently in flight, or
+  // null between moves — reset() awaits this instead of declining outright
+  // when it is clicked mid-move, so a reset can never be silently dropped
+  // (see the reset handler below for why that mattered).
+  let animatingPromise = null;
 
   const posIn = (snap, id) => snap.items.find((i) => i.id === id && i.kind === "block");
   function drawState(i) {
@@ -608,7 +614,11 @@ const PLAN = ${embedded};
   }
   async function forward() {
     if (animating || step >= N) return;
-    render(); await animateMove(step); step += 1; render();
+    render();
+    animatingPromise = animateMove(step);
+    await animatingPromise;
+    animatingPromise = null;
+    step += 1; render();
   }
   async function playRange(from, to) {
     if (animating) return;
@@ -674,7 +684,19 @@ const PLAN = ${embedded};
 
   btn.next.addEventListener("click", () => { playing = false; forward(); });
   btn.back.addEventListener("click", () => { if (animating) return; playing = false; step = Math.max(0, step - 1); drawState(step); render(); });
-  btn.reset.addEventListener("click", () => { if (animating) return; playing = false; step = 0; drawState(0); render(); });
+  // playing drops the instant reset is clicked, even mid-move — a click
+  // that landed while animating used to bail out before touching playing
+  // at all, which left playRange's own loop free to run one more step the
+  // moment the in-flight move settled, so a fast play-then-reset click could
+  // reset the board and have it immediately start moving again. Waiting on
+  // animatingPromise (rather than declining) means the reset itself still
+  // never fires while a move might be touching the same block elements, but
+  // it is never dropped either.
+  btn.reset.addEventListener("click", async () => {
+    playing = false;
+    if (animatingPromise) await animatingPromise;
+    step = 0; drawState(0); render();
+  });
   btn.play.addEventListener("click", async () => {
     if (animating) return;
     if (playing) { playing = false; render(); return; }

package/src/services/predator-prey.mjs

@@ -14,7 +14,7 @@
 // which is board-size agnostic and models vision as plain Chebyshev distance
 // with no line of sight — a building blocks movement, never sight.
 //
-// Three mechanics are OPT-IN, off unless `config` asks for them by name, so a
+// Four mechanics are OPT-IN, off unless `config` asks for them by name, so a
 // cast that does not want them sees the same board it always did:
 //
 //   - `carryPreyToWeb` splits catching from eating. A predator that shares a
@@ -27,6 +27,11 @@
 //   - `layEggs` adds the reproduction stage: an egg (mgx:laid-at-turn) laid in
 //     a web once mass crosses a threshold, hatching (mgx:hatched-into) into
 //     hatchlings that split the egg's mass.
+//   - `blendPreyDecision` replaces the prey's strict evade-then-forage order
+//     with one weighted score over both distances (`preyThreatWeight`), so a
+//     prey can take a crumb that costs it nothing. Off, prey abandon food the
+//     moment anything is in view. scripts/compare-prey-decision.mjs measures
+//     the two against each other.
 
 import {
   DEFAULT_FACING, TOWN_SQUARE_LAYOUTS,
@@ -47,13 +52,36 @@ import { objectClassChain, parseSnapshotSubject, snapshotSubject, worldEpochFact
 export { DEFAULT_VISION_RADIUS, believedCellOf, nearestBelievedTarget, beliefSnapshotFor };
 
 /** The v1 cast. Keyed by role, never by species — every knob this engine reads
- *  is role-keyed too, so swapping the pair is data. */
+ *  is role-keyed too, so swapping the pair is data. `hunts` is the cast's own
+ *  statement of who preys on whom, and it is the only thing the decision chain
+ *  reads to tell a threat from a bystander. */
 export const MUDIII_ROLES = Object.freeze({
-  predator: { role: "predator", kind: "fox", idPrefix: "fox" },
-  prey: { role: "prey", kind: "goblin", idPrefix: "goblin" },
+  predator: { role: "predator", kind: "fox", idPrefix: "fox", hunts: "prey" },
+  prey: { role: "prey", kind: "goblin", idPrefix: "goblin", hunts: null },
   food: { spawnedKind: "crumb", placedKind: "morsel" },
 });
 
+const CAST_ROLES = Object.freeze(["predator", "prey"]);
+
+/** Which roles `role` hunts, as the cast declares it: a role name, a list of
+ *  them, or null for a role that hunts nothing. A roles object that states no
+ *  link at all keeps the pairing its two role names already name, so a cast
+ *  written before `hunts` existed hunts exactly as it did. Pure. */
+export function rolesHuntedBy(role, roles = MUDIII_ROLES) {
+  const entry = roles?.[role];
+  if (!entry) return [];
+  const declared = "hunts" in entry ? entry.hunts : (role === "predator" ? "prey" : null);
+  if (declared === null || declared === undefined) return [];
+  return [].concat(declared).filter((named) => CAST_ROLES.includes(named));
+}
+
+/** Which roles hunt `role`, read back off those same links. Empty for a role
+ *  nothing preys on, which is what keeps a predator hunting when it catches
+ *  sight of another predator rather than fleeing its own kind. Pure. */
+export function rolesHunting(role, roles = MUDIII_ROLES) {
+  return CAST_ROLES.filter((other) => rolesHuntedBy(other, roles).includes(role));
+}
+
 const PLACEMENT_PREDICATE = "mgx:currently-in";
 const MASS_PREDICATE = "mgx:hasMass";
 const MOOD_PREDICATE = "mgx:feels";
@@ -366,15 +394,14 @@ function bestOneStepBy(fromCell, applyActions, scoreOf, isBetter, tieBreakScoreO
 }
 
 /** One-ply greedy: the reachable cell (or staying put) furthest in Chebyshev
- *  terms from `awayFrom`. Both the prey's evade rung and the predator's avoid
- *  rung are this function.
+ *  terms from `awayFrom`. The evade rung is this function.
  *
  *  `opts.towardCell`, when given, breaks a tie among equally-safe cells in
  *  favor of whichever is closest to it — a fleeing prey that knows where food
  *  is should flee toward it, not toward whichever direction DIRECTION_DELTA's
  *  key order happens to check first. Opt-in and null by default, so a caller
- *  that never passes it (the predator's own avoid rung) sees no change at
- *  all: same options, same scores, same first-wins tie order. */
+ *  that never passes it sees no change at all: same options, same scores, same
+ *  first-wins tie order. */
 export function greedyAway(fromCell, awayFrom, applyActions, { towardCell = null } = {}) {
   if (!awayFrom) return fromCell;
   return bestOneStepBy(
@@ -396,6 +423,29 @@ export function greedyToward(fromCell, towardCell, applyActions) {
   );
 }
 
+/** One-ply greedy over BOTH distances at once, rather than one rung after the
+ *  other: the reachable cell (or staying put) that maximizes
+ *
+ *      weight * distance-from-`awayFrom` - (1 - weight) * distance-to-`towardCell`
+ *
+ *  At weight 1 this is greedyAway and at weight 0 it is greedyToward. In
+ *  between it lets an agent take a step toward food that costs it little or no
+ *  distance from the thing hunting it, which strict priority rungs cannot do.
+ *
+ *  Falls back to whichever single term it still has when the other cell is
+ *  null, so a caller never has to check first. */
+export function greedyBlend(fromCell, awayFrom, towardCell, applyActions, weight) {
+  if (!awayFrom) return greedyToward(fromCell, towardCell, applyActions);
+  if (!towardCell) return greedyAway(fromCell, awayFrom, applyActions);
+  const w = Number.isFinite(Number(weight)) ? Number(weight) : DEFAULT_GAME_CONFIG.mudiii.preyThreatWeight;
+  return bestOneStepBy(
+    fromCell, applyActions,
+    (cell) => w * chebyshevDistance(cell.x, cell.y, awayFrom.x, awayFrom.y)
+      - (1 - w) * chebyshevDistance(cell.x, cell.y, towardCell.x, towardCell.y),
+    (score, bestScore) => score > bestScore,
+  );
+}
+
 /** A seeded, uniform pick among staying put or any one-ply reachable cell.
  *  Deterministic and replayable, and it looks random to somebody watching.
  *  Both roles' last rung: a motionless predator reads as a broken page. */
@@ -483,14 +533,13 @@ const round2 = (n) => Math.round(n * 100) / 100;
 // ---- the goal line and the mood word -------------------------------------------
 // Every branch assigns a mood beside the goal sentence it renders, and that
 // word is written as a real mgx:feels fact for the turn. The words are the four
-// spider-fly already uses: a predator mid-chase is angry, one avoiding a rival
-// is scared, anything wandering or foraging is calm, and anything that just ate
-// is happy.
+// spider-fly already uses: an agent mid-chase is angry, one fleeing something
+// that hunts it 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, 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}.`;
       return catches ? `co-located with ${subject} — catching it.` : `standing over ${subject} — taking it.`;
@@ -874,22 +923,41 @@ export async function recastTownSquare(memoryDir, {
   });
 }
 
+/** The opening cast, seeded: predators on open cells, prey on the perimeter
+ *  they wander in from, and NO cell handed out twice.
+ *
+ *  Every other placement path in this engine already refuses a cell something
+ *  stands on — spawn-prey and spawn-food both filter the occupied set and
+ *  simply don't spawn when nothing is left, and placeFood refuses a prop or
+ *  another item. The page's own blocked-cell rule counts a single agent as
+ *  enough to block a cell too, so a mint that stacked two would put the board
+ *  in breach of the rule it opens under.
+ *
+ *  Prey prefer the perimeter, but a perimeter with no room left puts one a
+ *  cell inside rather than inside another animal. An agent goes unminted only
+ *  when the whole board is full, which is the same answer spawn-prey gives. */
 function seededRoster(layout, { predators, prey, roles, epoch }) {
   const roster = {};
   const taken = new Set();
   const open = openCells(layout);
   const edge = perimeterCells(layout);
+  const pickFreeCell = (preferred, id) => {
+    const free = preferred.filter((c) => !taken.has(c));
+    const options = free.length ? free : open.filter((c) => !taken.has(c));
+    if (!options.length) return null;
+    return seededPick(options, seedKey(layout.name, epoch, 0, id, "spawn"));
+  };
   for (let i = 1; i <= predators; i += 1) {
     const id = `${roles.predator.idPrefix}-${i}`;
-    const free = open.filter((c) => !taken.has(c));
-    const cell = seededPick(free.length ? free : open, seedKey(layout.name, epoch, 0, id, "spawn"));
+    const cell = pickFreeCell(open, id);
+    if (!cell) break;
     taken.add(cell);
     roster[id] = { role: "predator", cell, facing: DEFAULT_FACING };
   }
   for (let i = 1; i <= prey; i += 1) {
     const id = `${roles.prey.idPrefix}-${i}`;
-    const free = edge.filter((c) => !taken.has(c));
-    const cell = seededPick(free.length ? free : edge, seedKey(layout.name, epoch, 0, id, "spawn"));
+    const cell = pickFreeCell(edge, id);
+    if (!cell) break;
     taken.add(cell);
     roster[id] = { role: "prey", cell, facing: DEFAULT_FACING };
   }
@@ -1023,7 +1091,7 @@ function itemsPayload(liveItemIds, { state, itemCellOf, roles, taken = null }) {
  * `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 ("driven" for a
- * hand-driven move, then "chase", "evade", "forage", "avoid", "wander", and —
+ * hand-driven move, then "chase", "evade", "forage", "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`
@@ -1053,6 +1121,10 @@ export async function runTownSquareTick(memoryDir, {
 
   const carriesPrey = config.carryPreyToWeb === true;
   const buildsWebs = config.buildWebs === true;
+  const blendsPreyDecision = config.blendPreyDecision === true;
+  const preyThreatWeight = Number.isFinite(Number(config.preyThreatWeight))
+    ? Number(config.preyThreatWeight)
+    : DEFAULT_GAME_CONFIG.mudiii.preyThreatWeight;
   const boardNoun = lay.boardNoun ?? "square";
   const webbedAt = (c) => hasActiveWebAt(lay, state, k, c.x, c.y, config.webDurationTurns);
   // Widened in place as predators spin webs this tick, for the renderer's own
@@ -1070,6 +1142,10 @@ export async function runTownSquareTick(memoryDir, {
     }
   }
 
+  const liveIdsOfRole = { predator: predators, prey };
+  const agentsOfRoles = (roleList, exceptId) =>
+    roleList.flatMap((r) => liveIdsOfRole[r] ?? []).filter((id) => id !== exceptId).sort();
+
   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
@@ -1090,8 +1166,14 @@ export async function runTownSquareTick(memoryDir, {
     // visionRadius: Infinity call, not new belief machinery. The rival-threat
     // 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 = driven ? null : nearestBelievedTarget(agentId, fromCell, rivals, state, beliefOpts);
+    // Who counts as a threat and who counts as quarry both come off the cast's
+    // own hunts links. Nothing hunts a predator on either shipped board, so a
+    // predator's threat list is empty and a second predator in view is just
+    // another animal on the square.
+    const huntedRoles = rolesHuntedBy(role, roles);
+    const huntsAgents = huntedRoles.length > 0;
+    const hunters = agentsOfRoles(rolesHunting(role, roles), agentId);
+    const threat = driven ? null : nearestBelievedTarget(agentId, fromCell, hunters, state, beliefOpts);
 
     let rung;
     let nextCell;
@@ -1100,8 +1182,7 @@ export async function runTownSquareTick(memoryDir, {
     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.
+    // predator never drops its catch to chase a second one.
     const carriedPreyId = (carriesPrey && role === "predator") ? (state.carrying.get(agentId)?.prey ?? null) : null;
     const isCarrying = Boolean(carriedPreyId) && prey.includes(carriedPreyId);
     const captorId = (carriesPrey && role === "prey") ? (captorOfPrey.get(agentId) ?? null) : null;
@@ -1152,24 +1233,47 @@ export async function runTownSquareTick(memoryDir, {
       goal = goalLine("trapped");
       mood = "scared";
     } else if (threat) {
-      rung = role === "predator" ? "avoid" : "evade";
-      // A fleeing prey that already knows where food is should flee toward
-      // it, not away from it — among cells that are equally safe, break the
-      // tie toward the nearest believed crumb. Prey-only: the predator's own
-      // avoid rung passes nothing, so its ties still resolve the old way.
-      const towardFood = role === "prey"
-        ? nearestBelievedTarget(agentId, fromCell, [...foodIds].sort(), state, foodBeliefOpts)
-        : null;
-      nextCell = greedyAway(fromCell, threat.cell, applyActions, { towardCell: towardFood?.cell ?? null });
-      plan = stepPlan(fromCell, nextCell);
-      goal = goalLine(rung, { subject: threat.subject, cell: cellId(threat.cell.x, threat.cell.y) });
-      mood = "scared";
+      const towardFood = huntsAgents
+        ? null
+        : nearestBelievedTarget(agentId, fromCell, [...foodIds].sort(), state, foodBeliefOpts);
+      if (blendsPreyDecision && !huntsAgents && towardFood) {
+        // The one case the two rungs disagree about: this prey believes a
+        // predator AND food, so a strict order has to pick between them and a
+        // score does not.
+        nextCell = greedyBlend(fromCell, threat.cell, towardFood.cell, applyActions, preyThreatWeight);
+        const closedOnFood = chebyshevDistance(fromCell.x, fromCell.y, towardFood.cell.x, towardFood.cell.y)
+          > chebyshevDistance(nextCell.x, nextCell.y, towardFood.cell.x, towardFood.cell.y);
+        // The score is one number, but the step it buys is still one of two
+        // legible things: this move closed on the crumb, or it did not. The
+        // rung and the goal line say which, so no surface has to render
+        // "mostly evading, somewhat hungry".
+        rung = closedOnFood ? "forage" : "evade";
+        plan = stepPlan(fromCell, nextCell);
+        goal = closedOnFood
+          ? goalLine("forage", {
+            subject: towardFood.subject,
+            cell: cellId(towardFood.cell.x, towardFood.cell.y),
+            arrived: nextCell.x === towardFood.cell.x && nextCell.y === towardFood.cell.y,
+          })
+          : goalLine("evade", { subject: threat.subject, cell: cellId(threat.cell.x, threat.cell.y) });
+        mood = closedOnFood ? "calm" : "scared";
+      } else {
+        rung = "evade";
+        // An agent that already knows where food is should flee toward it, not
+        // away from it — among cells that are equally safe, break the tie
+        // toward the nearest believed crumb. An agent that hunts has no food
+        // cell to offer, so its ties resolve on first-wins order alone.
+        nextCell = greedyAway(fromCell, threat.cell, applyActions, { towardCell: towardFood?.cell ?? null });
+        plan = stepPlan(fromCell, nextCell);
+        goal = goalLine(rung, { subject: threat.subject, cell: cellId(threat.cell.x, threat.cell.y) });
+        mood = "scared";
+      }
     } else {
-      const quarry = role === "predator"
-        ? nearestBelievedTarget(agentId, fromCell, prey, state, beliefOpts)
+      const quarry = huntsAgents
+        ? nearestBelievedTarget(agentId, fromCell, agentsOfRoles(huntedRoles, agentId), state, beliefOpts)
         : nearestBelievedTarget(agentId, fromCell, [...foodIds].sort(), state, foodBeliefOpts);
       if (quarry) {
-        rung = role === "predator" ? "chase" : "forage";
+        rung = huntsAgents ? "chase" : "forage";
         const path = findActionPath(fromCell, (s) => s.x === quarry.cell.x && s.y === quarry.cell.y, applyActions, { stateKey: pathStateKey });
         if (path && path.actions.length) {
           nextCell = path.states[1];
@@ -1183,7 +1287,7 @@ export async function runTownSquareTick(memoryDir, {
         }
         const arrived = nextCell.x === quarry.cell.x && nextCell.y === quarry.cell.y;
         goal = goalLine(rung, { subject: quarry.subject, cell: cellId(quarry.cell.x, quarry.cell.y), arrived, catches: carriesPrey });
-        mood = role === "predator" ? "angry" : "calm";
+        mood = huntsAgents ? "angry" : "calm";
       } else if (role === "predator" && buildsWebs) {
         // A web-spinning predator with nothing in sight has something better to
         // do than wander: hold this cell, and spin a web here unless a live one

package/src/services/research-viz.mjs

@@ -19,8 +19,8 @@
 // renderResearchHtml() is pure: no I/O, deterministic output for identical
 // input. scripts/build-demo-site.mjs calls it directly and writes the result to
 // public/research.html, after research-browser.bundle.js already exists.
-import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml } from "./viz-theme.mjs";
-import { fetchWithProgress, loadProgressLine, factTripleParts } from "./memory-panel-viz.mjs";
+import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
+import { fetchWithProgress, loadSeedPayload, loadProgressLine, factTripleParts } from "./memory-panel-viz.mjs";
 import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
 import { loadWinkVendor } from "./viz-boot.mjs";
 import { cloneMemoryPayload } from "../adapters/memory/core.mjs";
@@ -108,7 +108,8 @@ ${DASH_DARK_CHROME_CSS}
   header.topbar { display: flex; align-items: flex-start; justify-content: space-between; gap: 1.4rem; flex-wrap: wrap; padding: .6rem 0 1rem; border-bottom: 1px solid var(--line); margin-bottom: 1.3rem; }
   .brand { display: flex; flex-direction: column; gap: .3rem; max-width: 640px; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .72rem; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); }
-  .subtitle { font-size: .92rem; color: var(--ink); opacity: .82; max-width: 58ch; }
+  ${EYEBROW_LINKS_CSS}
+  .subtitle { margin: 0; font-size: .92rem; font-weight: 400; color: var(--ink); opacity: .82; max-width: 58ch; }
   .statuspanel { display: flex; flex-wrap: wrap; gap: .5rem 1.1rem; background: var(--card); border: 1px solid var(--line); border-radius: 6px; padding: .5rem .9rem; }
   .statuspanel .stat { display: flex; flex-direction: column; gap: .14rem; min-width: 7rem; }
   .statuspanel .stat-label { font-family: ${MONO_STACK}; font-size: .6rem; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); }
@@ -240,8 +241,8 @@ ${DASH_DARK_CHROME_CSS}
   <div class="wrap">
     <header class="topbar">
       <div class="brand">
-        <span class="eyebrow">the-mechanical-code-talker &middot; research</span>
-        <span class="subtitle">Grow one graph three ways. Watch what it learns, then ask a question scoped to the sources you trust.</span>
+        <span class="eyebrow">${demoEyebrowHtml("research", "research")}</span>
+        <h1 class="subtitle">Grow one graph three ways. Watch what it learns, then ask a question scoped to the sources you trust.</h1>
       </div>
       <div class="statuspanel" id="statusPanel" aria-live="polite">
         <div class="stat stat-facts"><span class="stat-label">facts in the graph</span><span class="stat-value" id="statFacts">&mdash;</span></div>
@@ -353,6 +354,7 @@ ${DASH_DARK_CHROME_CSS}
   const sourceLabelFor = ${sourceLabelFor.toString()};
   const factTripleParts = ${factTripleParts.toString()};
   const fetchWithProgress = ${fetchWithProgress.toString()};
+  const loadSeedPayload = ${loadSeedPayload.toString()};
   const createTicker = ${createTicker.toString()};
   const prefersReducedMotion = ${prefersReducedMotion.toString()};
   const loadWinkVendor = ${loadWinkVendor.toString()};
@@ -396,25 +398,17 @@ ${DASH_DARK_CHROME_CSS}
 
   let seedPayload = null;
   let seedFacts = 0;
-  // One retry with a cache-busting query param: a CDN edge can serve a
-  // corrupted or truncated precompressed response (a transient bad cache
-  // entry, not a code defect — real bytes decompress fine, and the same URL
-  // fetched moments later is clean), and JSON.parse throwing is the only
-  // signal of that. The bust param forces a fresh fetch past that one entry.
+  // The same starter memory chat.html and ingest.html load, reported the same
+  // way: tmct.seed carries whether it arrived, so a page with an empty store
+  // can say which kind of empty it is.
+  window.tmct.seed = { state: "loading", facts: 0 };
   async function fetchSeed() {
-    for (let attempt = 1; attempt <= 2; attempt++) {
-      try {
-        const bust = attempt === 1 ? "" : (SEED_QUERY ? "&" : "?") + "retry=1";
-        const blob = await fetchWithProgress("./chat-seed.json" + SEED_QUERY + bust, (loaded, total) => noteProgress("seed", loaded, total));
-        seedPayload = JSON.parse(await blob.text());
-        seedFacts = (seedPayload.individuals || []).filter((i) => i.class === "Fact").length;
-        return;
-      } catch (err) {
-        if (attempt === 2) {
-          seedPayload = null;
-          console.warn("tmct research: chat-seed.json unavailable — starting unseeded", err);
-        }
-      }
+    const outcome = await loadSeedPayload(fetchWithProgress, "./chat-seed.json", SEED_QUERY, (loaded, total) => noteProgress("seed", loaded, total));
+    seedPayload = outcome.payload;
+    seedFacts = outcome.status.facts;
+    window.tmct.seed = outcome.status;
+    if (outcome.status.state === "failed") {
+      console.error("tmct research: chat-seed.json unavailable — starting unseeded (" + outcome.status.error + ")");
     }
   }
   async function newSession() {

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

@@ -130,6 +130,12 @@ const SPIDER_FLY_SEE_RE = /^what (?:does|can) the (spider|fly)(?:-(\d+))?\s+see[
 const WORLD_OPENING_FALLBACK =
   "a spider waits in its web; a fly drifts in from the edge of the board. Neither is yours to move. Watch, or address one by name in chat.";
 
+/** The word that steps the board, said on the OPENING turn. It used to appear
+ *  only on re-entry, so a first-time player was told to watch a board that
+ *  never moved. Appended to whatever opening the worlds pack carries, so the
+ *  pack owns the scene and this owns the control. */
+const ADVANCE_HINT = 'Say "tick" to advance a turn.';
+
 // ---- the opening turn: load the shipped board through the worlds pack -------
 
 async function openSpiderFlyGame({ planHolder, memoryDir, env, cache, gameConfig = DEFAULT_GAME_CONFIG }) {
@@ -164,7 +170,7 @@ async function openSpiderFlyGame({ planHolder, memoryDir, env, cache, gameConfig
   const { started } = await startSpiderFlyGame(memoryDir, { flyCount: 1, config: gameConfig?.spiderFly });
   planHolder.state = { spiderFly: { turn: 0 } };
   const opener = started
-    ? (payload.meta?.opening || WORLD_OPENING_FALLBACK)
+    ? `${payload.meta?.opening || WORLD_OPENING_FALLBACK} ${ADVANCE_HINT}`
     : 'back to the spider-and-fly board — the spider and fly are already in play. Say "tick" to advance, or address one, e.g. "@spider the fly is east".';
   return {
     text: opener,

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

@@ -32,7 +32,7 @@
 // bundle's own real ES exports instead, since (unlike ledger-viz, which
 // reuses a FIXED shared bundle it can't extend for one page's own needs) this
 // page ships its own dedicated bundle and can just export what it needs.
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, meterBarHtml } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, meterBarHtml, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import { createTicker } from "./viz-ticker.mjs";
 import { loadWinkVendor } from "./viz-boot.mjs";
 import { GRID_SIZE, WEB_HOME, WEB_RADIUS, isInWebBlock, cellId, agentKindOf } from "../domain/spider-fly-world.mjs";
@@ -250,6 +250,7 @@ ${THEME_TOKENS_CSS}
   .mono { font-family: ${MONO_STACK}; }
   main { max-width: 1120px; margin: 0 auto; padding: 1.4rem 1.2rem 2.2rem; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .7rem; letter-spacing: .08em; text-transform: uppercase; color: var(--chrome-accent); }
+  ${EYEBROW_LINKS_CSS}
   h1 { font-size: 1.4rem; margin: .3rem 0 .9rem; text-wrap: balance; }
   button { font: inherit; color: inherit; background: none; cursor: pointer; }
   button:focus-visible, input:focus-visible, .sprite:focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
@@ -443,7 +444,7 @@ ${THEME_TOKENS_CSS}
 <main>
   <div class="stage page-head">
     <div class="head-inner">
-      <div class="eyebrow">tmct &middot; spider and fly</div>
+      <div class="eyebrow">${demoEyebrowHtml("spider-fly", "spider and fly")}</div>
       <h1>Multiple competing planning agents</h1>
     </div>
     <div></div>
@@ -1007,12 +1008,19 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
       chatqEl.focus();
     });
   }
+  // A direction pill REPLACES the claim rather than appending to it — unlike
+  // adventure.html/mud.html's claim pills, which are meant to compose ("look
+  // at" then "the book"), these four are mutually exclusive readings of the
+  // SAME fact (where one agent is), so a second click was building
+  // "@spider the fly is north the fly is east", which the grammar has never
+  // accepted and never will: a thing has one position, not several at once.
+  // The address prefix survives a direction click (so "@fly" then a
+  // direction still addresses the fly), the same way it already did before
+  // this fix — only the claim after it is replaced rather than grown.
   for (const btn of directionPillEls) {
     btn.addEventListener("click", () => {
       const kind = addresseeKindOf(chatqEl.value) || "spider";
-      let value = chatqEl.value;
-      if (!addresseeKindOf(value)) value = "@" + kind + " " + value.trimStart();
-      chatqEl.value = value.replace(/\\s+$/, "") + " " + btn.textContent;
+      chatqEl.value = "@" + kind + " " + btn.textContent;
       refreshPills();
       chatqEl.focus();
     });

package/src/services/sprite-catalog-viz.mjs

@@ -51,7 +51,7 @@ import { spriteFactRows } from "../domain/sprite-facts.mjs";
 import { SEED_TAXONOMY } from "../domain/spider-fly-world.mjs";
 import { loadSlice, loadMap, toFacts, WORDNET_DIR } from "../adapters/corpus/conceptnet.mjs";
 import { join } from "node:path";
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 
 const DEFAULT_TITLE = "tmct — the sprite library";
 const MAX_CHAIN_DISPLAY = 6;
@@ -905,6 +905,7 @@ ${THEME_TOKENS_CSS}
   .appbar { display: flex; align-items: flex-end; gap: 1rem; margin: 0 -1.2rem; padding: .6rem 1.2rem 0; background: var(--ai-bar); }
   .appbar h1 { font-family: ${MONO_STACK}; font-size: .84rem; font-weight: 600; letter-spacing: .02em; margin: 0; padding: .32rem .8rem .38rem; background: var(--ai-panel); color: var(--ink); border-radius: 4px 4px 0 0; }
   .appbar .doc-sub { font-family: ${MONO_STACK}; font-size: .66rem; letter-spacing: .07em; text-transform: uppercase; color: color-mix(in srgb, var(--ai-bar-ink) 65%, transparent); padding-bottom: .5rem; }
+  ${EYEBROW_LINKS_CSS}
   .topbar { position: sticky; top: 0; z-index: 2; display: flex; flex-wrap: wrap; align-items: center; gap: .5rem .9rem; background: var(--ai-panel); border-bottom: 1px solid var(--ai-edge); margin: 0 -1.2rem 1.4rem; padding: .5rem 1.2rem; }
   .jump { font-family: ${MONO_STACK}; font-size: .7rem; padding: .2rem .6rem; border: 1px solid var(--ai-edge); border-radius: 3px; background: transparent; color: var(--ink); text-decoration: none; }
   .jump:hover { border-color: var(--corpus); color: var(--corpus); }
@@ -982,7 +983,7 @@ ${dockCss}</style>
 <main>
   <header class="appbar">
     <h1>Sprites</h1>
-    <span class="doc-sub">tmct &middot; the sprite library</span>
+    <span class="doc-sub">${demoEyebrowHtml("sprites", "the sprite library")}</span>
   </header>
   ${composerHtml}
   ${dockHtml}

package/src/services/viz-theme.mjs

@@ -32,6 +32,26 @@ export function embedScriptText(js) {
   return String(js ?? "").replaceAll("</script", "<\\/script");
 }
 
+/** The three-link nav every demo page's header opens with: the site's own
+ *  name (home), the demo's own name (its own page) and "about" (its about
+ *  page). `page` is the demo's key in scripts/site-pages.mjs's DEMO_PAGES,
+ *  which is also its filename stem (e.g. "mud" -> mud.html); the about-page
+ *  suffix below mirrors that same file's `aboutPageOf`, restated rather than
+ *  imported since scripts/ sits outside src/ and never ships with the
+ *  published package. Returns the inner markup only — the caller supplies
+ *  the wrapping element (div/h1/span) and keeps whatever class and
+ *  neighbouring markup its own header already carries. Style hook:
+ *  EYEBROW_LINKS_CSS. */
+export function demoEyebrowHtml(page, label) {
+  return `<span class="eyebrow-links"><a href="./index.html">tmct</a> &middot; <a href="./${page}.html">${escapeHtml(label)}</a> &middot; <a href="./${page}-about.html">about</a></span>`;
+}
+
+/** Styling every page that calls demoEyebrowHtml splices into its own inline
+ *  <style>: the links read in the eyebrow's own colour (each page sets that
+ *  colour itself), underlining only on hover/focus. */
+export const EYEBROW_LINKS_CSS = `.eyebrow-links a { color: inherit; text-decoration: none; }
+.eyebrow-links a:hover, .eyebrow-links a:focus-visible { text-decoration: underline; }`;
+
 /** A world name read as a name in a scenario dropdown: "mud-garden" ->
  *  "mud garden". The world's own hyphenated id is the only thing every caller
  *  is guaranteed to have, so a scenario that wants a hand-written label passes

package/src/services/viz-ticker.mjs

@@ -55,6 +55,10 @@ export function createTicker({
 } = {}) {
   const state = { playing: false, animating: false };
   const render = () => onRender({ ...state });
+  // The promise of whatever onTick() call is currently in flight, or null
+  // between ticks — reset() awaits this (see below) rather than bailing out
+  // when a click lands mid-tick, so a reset can never be silently dropped.
+  let inFlight = null;
 
   /** Advance exactly one step, honoring `hasNext`/`animating` guards. Returns
    *  whether it actually advanced. */
@@ -62,7 +66,9 @@ export function createTicker({
     if (state.animating || !hasNext()) return false;
     state.animating = true;
     render();
-    await onTick();
+    inFlight = Promise.resolve(onTick());
+    await inFlight;
+    inFlight = null;
     state.animating = false;
     render();
     return true;
@@ -95,9 +101,16 @@ export function createTicker({
     render();
   }
 
+  /** Stop and rewind. `state.playing` drops immediately, even mid-tick, so
+   *  `play()`'s own loop can never start one more tick once this has been
+   *  called — a reset clicked while a tick is animating used to return here
+   *  before touching `playing` at all, which left the loop running right
+   *  past it. If a tick IS in flight, this waits for it to actually settle
+   *  (never calling `onReset` while `onTick` might still be touching the
+   *  same state/DOM) before rewinding, rather than dropping the reset. */
   async function reset() {
-    if (state.animating) return;
     state.playing = false;
+    if (inFlight) await inFlight;
     if (onReset) await onReset();
     render();
   }