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

package/src/services/chat.mjs

@@ -1413,6 +1413,35 @@ export function isConversational(query) {
   return expandContractions(q).split(/\s+/).filter(Boolean).length <= 3 && !codeish;
 }
 
+/** The words that, in the slot of a short "what is X" / "who is X", name the
+ *  SESSION rather than a term to look up ("what is this", "what is up").
+ *  Closed and hand-curated, the same discipline every small-talk set in this
+ *  file uses: a word listed here keeps today's orientation card, and anything
+ *  else is a question about a term. */
+const SESSION_REFERENT_TERMS = new Set([
+  "this", "that", "it", "they", "them", "you", "u", "yours", "tmct",
+  "up", "new", "next", "now", "here", "there", "left", "wrong", "more", "else",
+  "all", "everything", "anything", "something", "nothing",
+  "going", "happening", "possible", "available", "supported", "included",
+]);
+
+/** The term a short "what is X" / "who is X" asks about, or null when the line
+ *  isn't that shape or names the session itself.
+ *
+ *  isConversational's catch-all counts words, so "what is grelb" (three) took
+ *  the orientation card while "what is a grelb" (four, one article apart)
+ *  refused — the same question answered two different ways, and the shorter
+ *  one answered with a paragraph about tmct that reads as if the term had been
+ *  looked up. A term question that resolves to nothing belongs on the miss
+ *  wall; only the closed set above is really about the product. */
+function shortTermQuestionTerm(query) {
+  const m = String(query).trim().replace(/[?.!]+\s*$/, "")
+    .match(/^(?:what|who)\s+(?:is|are|was|were)\s+([a-z][\w'-]*)$/i);
+  if (!m) return null;
+  const term = m[1].toLowerCase();
+  return SESSION_REFERENT_TERMS.has(term) ? null : term;
+}
+
 /** The tmct tools dispatchTool can back (the set a tool-emitting caller may use).
  *  A declared tool outside this set is never emitted — the request falls through
  *  to a text answer. The COMMANDS map names the richer graph tools; TOOLS names
@@ -2959,6 +2988,23 @@ function singularizeSurface(word) {
 
 export { singularizeSurface };
 
+/** Does the complement of this payload wear its own article ("all foxes are A
+ *  SPECIES")? An article marks the complement singular already, so the plural
+ *  fold below must leave it alone. */
+const objectCarriesArticle = (payload) => /\s(?:is|are)\s+(?:an?\s+)/i.test(String(payload || ""));
+
+/** The complement as it should be STORED. The subject of a plural membership
+ *  sentence has always folded ("all foxes are mammals" stores "fox"); the
+ *  object had not, so the pair landed as fox ⊑ mammals and the next turn's
+ *  "is a fox a mammal" looked up a class spelled a different way and missed
+ *  the fact it had just been told. Gated exactly as the subject fold is: only
+ *  a genuinely plural "are" phrasing, and only where no article already marks
+ *  the complement singular. */
+function storedObjectTerm(objectRaw, { verb, payload, lex, lookupNoun }) {
+  if (!/^are$/i.test(verb) || objectCarriesArticle(payload)) return objectRaw;
+  return lookupNoun(lex, objectRaw)?.lemma || singularizeSurface(objectRaw);
+}
+
 /** "(every|each|all|a|an )?X is/are (a|an )?Y" — the shape the unknown-subject
  *  fallback recognizes (group 2 = X, group 4 = Y); group 1 (when present)
  *  names the determiner, so the caller can tell a genuine "every" universal
@@ -3103,19 +3149,25 @@ async function ungroundedPairHint(payload, lexicon, memoryDir, cache = null, gra
   if (!memoryDir) return "";
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return "";
-  const [, , subjectRaw, , objectRaw] = m;
-  const { loadLexicon } = await import("../domain/grammar/lexicon.mjs");
+  const [, , subjectRaw, verb, objectRaw] = m;
+  const { loadLexicon, lookupNoun } = await import("../domain/grammar/lexicon.mjs");
   const lex = lexicon || loadLexicon();
   if (await isGroundedTerm(subjectRaw, lex, memoryDir, cache, graph)) return "";
   if (await isGroundedTerm(objectRaw, lex, memoryDir, cache, graph)) return "";
+  // The sentences suggested here have to be the ones that actually store, so
+  // both sides fold to the singular a plural surface named ("all zorps are
+  // florbs" → "every zorp is a thing"). Following the plural verbatim teaches
+  // a second class under a spelling nothing else uses.
+  const subject = /^are$/i.test(verb) ? singularOf(subjectRaw, lex, lookupNoun) : subjectRaw;
+  const object = storedObjectTerm(objectRaw, { verb, payload, lex, lookupNoun });
   // Chaining the second term UNDER the first's now-grounded proper name
   // ("every man is a john") is technically accepted by the grammar (once
   // "john" is grounded, ANY term can be taught as a kind of it), but reads as
   // nonsense to a human, since a proper name is never a category. Ground both
   // sides independently instead — two clear, parallel, semantically sane
   // suggestions, not a confusing chain through an arbitrary first term.
-  return ` I don't know "${subjectRaw}" or "${objectRaw}" yet. Try grounding each one first, e.g. `
-    + `"every ${subjectRaw} is a thing" and "every ${objectRaw} is a thing", then re-teach the`
+  return ` I don't know "${subject}" or "${object}" yet. Try grounding each one first, e.g. `
+    + `"every ${subject} is a thing" and "every ${object} is a thing", then re-teach the`
     + ` original fact.`;
 }
 
@@ -3192,7 +3244,12 @@ async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon,
   if (lookupNoun(lex, objectRaw) || GENERIC_ANCHOR_NOUNS.has(String(objectRaw).toLowerCase())
     || (await isGroundedByFact(objectRaw, memoryDir, cache))) {
     return teachFact(memoryDir, sessionId, {
-      subject, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier, observedAt, dateText,
+      subject,
+      predicate: SUBCLASS_PREDICATE,
+      object: storedObjectTerm(objectRaw, { verb, payload, lex, lookupNoun }),
+      quantifier,
+      observedAt,
+      dateText,
     });
   }
   if (lookupAdjective(lex, objectRaw)) {
@@ -3321,7 +3378,12 @@ async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon, c
     ? (lookupNoun(lex, subjectRaw)?.lemma || singularizeSurface(subjectRaw))
     : subjectRaw;
   return teachFact(memoryDir, sessionId, {
-    subject, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier, observedAt, dateText,
+    subject,
+    predicate: SUBCLASS_PREDICATE,
+    object: storedObjectTerm(objectRaw, { verb, payload, lex, lookupNoun }),
+    quantifier,
+    observedAt,
+    dateText,
   });
 }
 
@@ -4160,9 +4222,20 @@ function matchBareCanTeach(text) {
 function teachSuggestion(payload) {
   const m = String(payload).match(/^(?:every |each |all |a |an )?([\w-]+) (is|are) (a |an )?([\w-]+)[.!?]*$/i);
   if (!m) return null;
-  const subject = (/^are$/i.test(m[2]) ? singularizeSurface(m[1]) : m[1]).toLowerCase();
-  const object = m[4].toLowerCase();
-  if (!m[3]) return `every ${subject} is ${object}`;
+  const plural = /^are$/i.test(m[2]);
+  const subject = (plural ? singularizeSurface(m[1]) : m[1]).toLowerCase();
+  let object = m[4].toLowerCase();
+  let articled = !!m[3];
+  // A plural complement with no article of its own ("all lynxes are mammals")
+  // folds like the subject does, and the fold itself is what proves it was a
+  // plural NOUN rather than a bare adjective — so it earns the article the
+  // singular membership sentence needs. Without this the repair suggested the
+  // very spelling the same sentence had just called unrecognized.
+  if (plural && !articled) {
+    const folded = singularizeSurface(object);
+    if (folded !== object) { object = folded; articled = true; }
+  }
+  if (!articled) return `every ${subject} is ${object}`;
   const articleRule = grammarRules().find((r) => r.kind === "article");
   const article = articleRule && beginsWithVowelSound(object, articleRule) ? "an" : "a";
   return `every ${subject} is ${article} ${object}`;
@@ -4799,9 +4872,11 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null, cac
     // the SHAPE of a retraction sentence — it says nothing about whether
     // subject⊑object was ever actually taught, or taught by THIS session.
     // retractSubClassOf is asked for real and is the only thing that decides:
-    //   - found:false  → subject⊑object was never a stored fact, and this
-    //     falls through to the rest of teachLane's ordinary cascade below
-    //     rather than claiming a specific, possibly-wrong reason.
+    //   - found:false  → subject⊑object was never a stored fact, so there is
+    //     nothing to withdraw and the turn says exactly that. It must NOT
+    //     fall through to the rest of the cascade: the teach frames below
+    //     read the unconsumed sentence from the top, take "forget bertha" as
+    //     a two-word subject, and confirm a fact the user asked to destroy.
     //   - found:true, ownRecord:false → some OTHER source taught it; this
     //     session has nothing of its own to withdraw.
     //   - found:true, stillStands:true → this session's own record is gone,
@@ -4849,7 +4924,10 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null, cac
           via: "retract", miss: false,
         };
       }
-      // found:false — fall through to the rest of the cascade (see docblock above).
+      return {
+        text: `"${retractSubject} is a kind of ${retractObject}" isn't stored, so there's nothing to forget.`,
+        via: "retract", miss: true,
+      };
     }
   }
 
@@ -13336,9 +13414,11 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     dialogueLaneOverride = "game-inform";
     note(trace, "lane: (2) MID-GAME NUDGE — an unparsed short turn stayed inside the live game frame instead of the identity card");
     note(trace, "goal: keep the running guess-the-number game on track");
-  } else if (isConversationalCandidate) {
+  } else if (isConversationalCandidate && !shortTermQuestionTerm(gateQuery) && !shortTermQuestionTerm(query)) {
     // A conversational miss (a greeting, "what can you do", a very short non-code
     // line) gets the friendly orientation (module-aware: empty → --repo/tmct init).
+    // A short question naming a TERM is excluded: nothing above resolved it, so
+    // it belongs on the miss wall its four-word twin already reaches.
     // This branch carries via:"template" and never reaches the composed-only
     // wall-shortening gate below, so it needs its own repeat collapse,
     // mirroring WALL_REPEAT_ONELINER.
@@ -13530,7 +13610,10 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       // all, so it would otherwise be confidently WRONG or silently absent.
       // Every successfully-recognized teach attempt gets this consistent goal
       // line instead.
-      deduced = "teach/remember a new fact";
+      // A retraction reaches this lane too, and its goal is the opposite one:
+      // saying "teach/remember a new fact" under a sentence asking for a fact
+      // to go describes the turn backwards.
+      deduced = taught.via === "retract" ? "withdraw a remembered fact" : "teach/remember a new fact";
       note(trace, `goal: ${deduced} (revised — the teach lane recognized this shape where the raw structural parse never should have)`);
       // A canonical whose verb only matched through the fuzzy edit-distance
       // tier ("disk-1 rests on peg-a." read as an ask about "tests") restates
@@ -13791,7 +13874,12 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     // does. Both shapes below anchor on the written-out copula.
     const offerSrc = expandContractions(String(query).trim());
     const knowAboutTerm = offerSrc.match(KNOW_ABOUT_RE)?.[1]?.trim();
-    const offerTerm = knowAboutTerm || metaTermOf(offerSrc, envelope);
+    // "who is grelb" asks about a term the same way "what is grelb" does, and
+    // a name is exactly what a person teaches next — without this the who-form
+    // dead-ends on the bare grammar wall while its what-form twin offers the
+    // teach phrasing.
+    const whoTerm = shortTermQuestionTerm(offerSrc) ? offerSrc.match(WHO_IS_BARE_RE)?.[1]?.trim() : null;
+    const offerTerm = knowAboutTerm || metaTermOf(offerSrc, envelope) || whoTerm;
     // A term that LEADS with a bindable anaphor ("it used for", from an
     // unresolved "what is it used for") is a pronoun that failed to bind,
     // not a teachable subject — offering to learn facts about it would echo

package/src/services/code-explorer-viz.mjs

@@ -19,7 +19,7 @@
 // sidebar/centre grid, so a later panel is one more <section class="panel">,
 // not a re-architecture.
 
-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";
 import { generateCodeHints } from "../domain/code-explorer-hints.mjs";
 import { phraseForRelation } from "../domain/ask-vocab.mjs";
 import { fetchWithProgress } from "./memory-panel-viz.mjs";
@@ -483,6 +483,7 @@ body { margin: 0; overflow: hidden; background: var(--bg); color: var(--ink); fo
 .titlebar { display: flex; align-items: center; gap: 0.7rem; flex-wrap: wrap; padding: 0.5rem 0.9rem; background: var(--card); border-bottom: 1px solid var(--line); box-shadow: inset 0 -2px 0 var(--entail-soft); }
 .titlebar .mark { width: 15px; height: 15px; color: var(--entail); flex: none; }
 .titlebar h1 { font-size: 0.95rem; margin: 0; font-weight: 600; letter-spacing: 0.02em; }
+${EYEBROW_LINKS_CSS}
 .titlebar .sub { color: var(--muted); font-size: 0.76rem; font-family: ${MONO_STACK}; }
 .titlebar .sub a { color: var(--corpus); }
 /* the fact count sits in the titlebar, not the footer status bar: it is what
@@ -544,7 +545,7 @@ ul.rows { list-style: none; margin: 0; padding: 0; }
 <div class="shell">
   <header class="titlebar">
     <svg class="mark" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 0l1 2.3a5.8 5.8 0 0 1 1.9.8L13.3 2l.7.7-1.1 2.4c.4.6.6 1.2.8 1.9L16 8l-2.3 1a5.8 5.8 0 0 1-.8 1.9l1.1 2.4-.7.7-2.4-1.1a5.8 5.8 0 0 1-1.9.8L8 16l-1-2.3a5.8 5.8 0 0 1-1.9-.8L2.7 14l-.7-.7 1.1-2.4a5.8 5.8 0 0 1-.8-1.9L0 8l2.3-1c.2-.7.4-1.3.8-1.9L2 2.7l.7-.7 2.4 1.1A5.8 5.8 0 0 1 7 2.3L8 0zm0 5.2A2.8 2.8 0 1 0 8 10.8 2.8 2.8 0 0 0 8 5.2z"/></svg>
-    <h1>tmct code explorer</h1>
+    <h1>${demoEyebrowHtml("code", "code explorer")}</h1>
     <span class="sub">source: <span id="source-name">${escapeHtml(sourceName)}</span></span>
     <span class="factpill" id="fact-total" aria-live="polite" title="every fact this page's chat can draw on — the code graph's own edges plus the general-knowledge seed once it lands">
       <span class="factpill-value" id="fact-total-value">&mdash;</span> facts loaded

package/src/services/ingest-viz.mjs

@@ -25,7 +25,7 @@
 // renderIngestHtml() is pure: no I/O, deterministic output for identical
 // input. scripts/build-demo-site.mjs calls it directly and writes the result
 // to public/ingest.html, after ingest-browser.bundle.js already exists.
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import {
   bandLabelFor,
   statsSummaryLine,
@@ -75,7 +75,8 @@ ${THEME_TOKENS_CSS}
   header.topbar { flex: 0 0 auto; display: flex; align-items: center; justify-content: space-between; gap: 1rem; padding: .7rem 1.1rem; border-bottom: 1px solid var(--line); flex-wrap: wrap; }
   .brand { display: flex; flex-direction: column; gap: .1rem; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .78rem; letter-spacing: .08em; color: var(--muted); }
-  .subtitle { font-size: .82rem; color: var(--muted); }
+  ${EYEBROW_LINKS_CSS}
+  .subtitle { margin: 0; font-size: .82rem; font-weight: 400; color: var(--muted); }
 
   /* the live memory count, in the topbar rather than the status line: it is
      the one number that says what this page's memory actually holds, and the
@@ -181,8 +182,8 @@ ${THEME_TOKENS_CSS}
   <div class="ingestCol">
     <header class="topbar">
       <div class="brand">
-        <span class="eyebrow">the-mechanical-code-talker</span>
-        <span class="subtitle">ingest &mdash; paste or drop text. It keeps the facts it can ground and skips the rest.</span>
+        <span class="eyebrow">${demoEyebrowHtml("ingest", "ingest")}</span>
+        <h1 class="subtitle">ingest &mdash; paste or drop text. It keeps the facts it can ground and skips the rest.</h1>
       </div>
       <div class="topbar-right">
         <span class="fact-pill" id="factPill" aria-live="polite"

package/src/services/ledger-viz.mjs

@@ -15,7 +15,7 @@
 // doesn't do: it reads the checked-in chat-dock engine bundle.
 
 import { loadMemory, readFactRows, findContradictions, normFactTerm } from "../adapters/memory/core.mjs";
-import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, embedJson, countLabel, TOKENS } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, embedJson, countLabel, TOKENS, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
 import { bfsLevels } from "../domain/planning.mjs";
 import { pluralOf } from "../domain/inflect.mjs";
@@ -644,7 +644,9 @@ ${DASH_DARK_CHROME_CSS}
   body { margin: 0; background: var(--bg); color: var(--ink); font-family: ${DASH_SANS_STACK}; font-size: 15px; line-height: 1.5; }
   .mono { font-family: ${MONO_STACK}; }
   main { max-width: 1200px; margin: 0 auto; padding: 1.4rem 1.2rem 3rem; }
+  .visually-hidden { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .7rem; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); display: flex; flex-wrap: wrap; gap: .4em 1.2em; margin-bottom: .9rem; }
+  ${EYEBROW_LINKS_CSS}
   button { font: inherit; color: inherit; background: none; border: none; padding: 0; cursor: pointer; }
   button:focus-visible, input:focus-visible { outline: 2px solid var(--corpus); outline-offset: 2px; border-radius: 4px; }
   .topbar { display: flex; flex-wrap: wrap; align-items: center; gap: .8rem; background: var(--card); border: 1px solid var(--line); border-radius: 6px; padding: .5rem .7rem; margin-bottom: 1.1rem; }
@@ -789,7 +791,8 @@ ${DASH_DARK_CHROME_CSS}
 </head>
 <body>
 <main>
-  <div class="eyebrow"><span>tmct &middot; memory ledger</span><span id="counts"></span></div>
+  <h1 class="visually-hidden">memory ledger</h1>
+  <div class="eyebrow"><span>${demoEyebrowHtml("ledger", "memory ledger")}</span><span id="counts"></span></div>
   ${dashboardHtml(stats)}
   <div class="topbar">
     <nav class="crumbs" id="crumbs" aria-label="Focus trail"></nav>

package/src/services/mud-viz.mjs

@@ -76,7 +76,7 @@
 // actually executed, never a race between panes.
 import {
   THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, scenarioLabel,
-  wordBeforeCursor, rowsForWorld, appendLogLine,
+  wordBeforeCursor, rowsForWorld, appendLogLine, demoEyebrowHtml, EYEBROW_LINKS_CSS,
 } from "./viz-theme.mjs";
 import { createTicker, createSerialQueue } from "./viz-ticker.mjs";
 import { directedGridLayout, roomGraphSvg, levelsOf, EXIT_DELTA } from "./viz-room-graph.mjs";
@@ -392,7 +392,7 @@ ${MUD_SHARE_SKIN}
 <body>
 <main>
   <header class="mud-topbar">
-    <h1 class="eyebrow">tmct &middot; mud</h1>
+    <h1 class="eyebrow">${demoEyebrowHtml("mud", "mud")}</h1>
     <div class="mud-topbar-actions">
       <button type="button" class="state-pill" id="statePill" aria-expanded="false" aria-controls="netPanel"
               title="whether this burrow is shared with anyone"><i class="state-dot"></i><span id="statePillWord">not shared</span></button>
@@ -411,7 +411,7 @@ ${scenarioList.length > 1 ? `        <select id="scenarioSelect" class="deck-sel
 ${scenarioList.map((s, i) => `          <option value="${i}"${i === 0 ? " selected" : ""}>${escapeHtml(s.label || scenarioLabel(s.worldPayload?.name))}</option>`).join("\n")}
         </select>` : ""}
         <button type="button" id="editModeBtn" aria-pressed="false">edit</button>
-        <label class="deck-teach" title="With this on, a sentence like &quot;Candle is in the study.&quot; writes a fact into the world instead of running as a command.">
+        <label class="deck-teach" title="With this on, a sentence like &quot;Pebble lies in the garden.&quot; writes a fact into the world instead of running as a command.">
           <input type="checkbox" id="teachToggle">
           teach
         </label>
@@ -590,6 +590,7 @@ const MUD_STYLE = `
   .mono { font-family: ${MONO_STACK}; }
   main { max-width: 1280px; margin: 0 auto; padding: 1.1rem 1.2rem 2.4rem; }
   .eyebrow { font-family: ${MONO_STACK}; font-weight: 500; font-size: .72rem; letter-spacing: .16em; text-transform: uppercase; color: var(--parchment); opacity: .9; margin: 0 0 .8rem; }
+  ${EYEBROW_LINKS_CSS}
 
   /* ---- the header: brand on the left, the sharing chrome on the right ----
      The same arrangement chat.html's topbar holds — sharing is page chrome,

package/src/services/mudiii-scene.mjs

@@ -42,12 +42,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`,
@@ -366,6 +364,13 @@ 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;
   var lastFrameTs = null;
@@ -557,10 +562,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 +638,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 +709,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 +746,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 +778,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,6 +816,61 @@ 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];
@@ -817,6 +922,9 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
     itemMeshes = {};
     lastAgentsById = {};
     lastItemsById = {};
+    tickRungs = {};
+    clearRoute();
+    clearFlash();
     removalLog = [];
     manifestByKind = buildManifestByKind(input && input.assetManifest);
     await placeProps((input && input.propPlacements) || []);
@@ -829,6 +937,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,6 +968,11 @@ export function mudiiiSceneScript({ canvasId, statusId, gridSize, cellSize } = {
       }
       if (entry.mixer) entry.mixer.update(deltaSec);
     }
+    if (flashMesh) {
+      var flashLeft = flashUntil - performance.now();
+      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); }
     if (orbitControls && orbitControls.enabled) orbitControls.update();
@@ -869,6 +983,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 +1007,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];