@polycode-projects/the-mechanical-code-talker 2.7.22 → 2.7.24

package/src/services/chat.mjs

@@ -54,6 +54,7 @@ import { dialogueActForLane } from "../domain/dialogue-acts.mjs";
 import { relatedForTerm } from "../domain/skos-view.mjs";
 import { adventureTurn, unclaimedAdventureOpening } from "./adventure.mjs";
 import { spiderFlyTurn } from "./spider-fly-turn.mjs";
+import { DEFAULT_GAME_CONFIG } from "../domain/game-config.mjs";
 
 // Composition: the chat surface supplies the domain parser's default lemma/POS
 // adapter (the browser bundle's ask-nlp stub carries no factory, so this is a
@@ -1559,6 +1560,16 @@ export function renderVerbose(last) {
 function conversationalTurn(line, ctx) {
   const raw = String(line);
   const q = raw.toLowerCase().replace(/[.!?]+$/, "").replace(/\s+/g, " ").trim();
+  // A live game (adventure/spider-fly/guess-the-number) already recognizes its
+  // OWN exact stop phrase ("stop playing", "I give up", ...) before this lane
+  // ever sees the line, so a bare word reaching here mid-game was never meant
+  // as a farewell — it's an in-game noun that fell through every game-shaped
+  // command check (e.g. "player", the adventure's own subject). The fuzzy-typo
+  // fallback below is a GUESS (bounded edit distance against "later" etc.),
+  // and a wrong guess ends the whole session — too costly a mistake to risk
+  // mid-game. The exact/closed-set farewell just above and below this guard
+  // stays live either way (a real "bye"/"exit" is unambiguous, never a guess).
+  const gameActive = Boolean(ctx.planHolder?.state?.adventure || ctx.planHolder?.state?.spiderFly || ctx.planHolder?.state?.game);
   const t = (id, slots = {}) => tRender(ctx.templates, id, slots) ?? TEMPLATES_UNAVAILABLE;
   const mk = (answer, { end = false, miss = false, via = "template", lane = null } = {}) => {
     const ts = new Date().toISOString();
@@ -1686,8 +1697,10 @@ function conversationalTurn(line, ctx) {
   // Fuzzy-typo fallback (A4): every exact/collapsed closed-set lookup above missed —
   // try a bounded edit-distance match against the flattened conversational phrase
   // pool ("helo", "thnx", "wat r u", "byee"), restricted to short non-code-ish
-  // input so a genuine near-miss structural question is never grabbed.
-  {
+  // input so a genuine near-miss structural question is never grabbed. Skipped
+  // entirely mid-game (see gameActive above) — never reached the CLI's own
+  // process-exit path from a guess before this fix existed.
+  if (!gameActive) {
     const fuzzyHit = fuzzyConversationalMatch(raw);
     if (fuzzyHit) {
       const bucket = classifyConversational(fuzzyHit);
@@ -10054,7 +10067,7 @@ const sameGoalSpec = (a, b) =>
  *  taught action rules (PLAN_HANOI's chat surface). Returns
  *  { text, via, deduced, note, plan? } or null when the query is none of the
  *  three shapes. Mutates planHolder.state (the session's plan slot). */
-async function planLaneAnswer(query, { memoryDir, planHolder, sessionId = "", }) {
+async function planLaneAnswer(query, { memoryDir, planHolder, sessionId = "", gameConfig = DEFAULT_GAME_CONFIG }) {
   let q = String(query).trim();
   // GOAL REVISION — "actually the goal is …", "instead, the goal is …", "the
   // goal is now …": a revision marker ahead of (or inside) a goal frame means
@@ -10349,9 +10362,10 @@ async function planLaneAnswer(query, { memoryDir, planHolder, sessionId = "", })
     return { text: `I can't compile that goal: ${err?.message ?? err}`, via: "plan", deduced: "plan a move sequence (uncompilable goal)", note: "plan lane — goal compile decline" };
   }
   const { findActionPath } = await import("../domain/planning.mjs");
+  const maxDepth = gameConfig?.planning?.maxDepth ?? DEFAULT_GAME_CONFIG.planning.maxDepth;
   let found;
   try {
-    found = findActionPath(state, isGoal, (s) => movesFromRules(s, domain), { maxDepth: 300, stateKey: stateKeyFor });
+    found = findActionPath(state, isGoal, (s) => movesFromRules(s, domain), { maxDepth, stateKey: stateKeyFor });
   } catch (err) {
     if (err instanceof PlanBudgetError) {
       return { text: `the search space is too large (${err.message}) — narrow the classes involved.`, via: "plan", deduced: "plan a move sequence (budget exceeded)", note: "plan lane — budget decline" };
@@ -10360,7 +10374,7 @@ async function planLaneAnswer(query, { memoryDir, planHolder, sessionId = "", })
   }
   if (!found) {
     return {
-      text: `no plan found within 300 moves from the current state to: ${goalText}.`,
+      text: `no plan found within ${maxDepth} moves from the current state to: ${goalText}.`,
       via: "plan", deduced: "plan a move sequence (no path)", note: "plan lane — honest miss: findActionPath returned null",
     };
   }
@@ -10635,7 +10649,7 @@ const DECISION_RECALL_RE = /^(?:remind\s+me\s+)?what\s+(?:did\s+)?(?:we|i|you)\s
  *  than silently accepted alongside the current location. */
 const MOVE_HISTORY_RE = /^where\s+did\s+(.+?)\s+(?:move|get\s+moved|go)(?:\s+to)?[?.!\s]*$/i;
 
-async function runAsk(query, { config, source, graph, focus, last, templates, memoryDir, sessionId = "", lexicon = null, env, trace, vocabHint = null, tel = null, biasByBundle = {}, cache = null, vocabAntecedent = null, planHolder = null }) {
+async function runAsk(query, { config, source, graph, focus, last, templates, memoryDir, sessionId = "", lexicon = null, env, trace, vocabHint = null, tel = null, biasByBundle = {}, cache = null, vocabAntecedent = null, planHolder = null, gameConfig = DEFAULT_GAME_CONFIG }) {
   const ts = new Date().toISOString();
   // DISCOURSE ANAPHORA: a follow-up like "which of those are tested" / "count
   // them" filters or counts the PREVIOUS answer's entity set, threaded as
@@ -11006,7 +11020,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // orientation card before this lane ever ran.
   let planResult = null;
   if (!handled && miss && memoryDir && planHolder) {
-    const planLane = await planLaneAnswer(query, { memoryDir, planHolder, sessionId });
+    const planLane = await planLaneAnswer(query, { memoryDir, planHolder, sessionId, gameConfig });
     if (planLane) {
       answer = planLane.text; via = planLane.via; recordMiss = false; handled = true;
       if (planLane.lane) dialogueLaneOverride = planLane.lane;
@@ -12449,22 +12463,23 @@ async function skosRelatedAnswer(memoryDir, query, cache) {
  *  captures (\S+) so a non-numeric bound is SEEN and declined rather than
  *  silently defaulted. */
 const GAME_BOUNDS_CLAUSE_RE = /\b(?:between\s+(\S+)\s+and\s+(\S+)|up\s+to\s+(\S+))\b/i;
-const GAME_BOUND_MAX = 1_000_000_000;
 
-/** The bounds an opening line states — { lo, hi } (default 1–100), or
- *  { problem } naming why the stated range is unplayable. */
-function parseGameBounds(text) {
+/** The bounds an opening line states — { lo, hi } (default `gameConfig`'s own
+ *  defaultLo/defaultHi), or { problem } naming why the stated range is
+ *  unplayable. `gameConfig` defaults to DEFAULT_GAME_CONFIG.guessNumber. */
+function parseGameBounds(text, gameConfig = DEFAULT_GAME_CONFIG.guessNumber) {
+  const { defaultLo, defaultHi, maxBound } = gameConfig;
   const m = String(text).match(GAME_BOUNDS_CLAUSE_RE);
-  if (!m) return { lo: 1, hi: 100 };
-  const tokens = (m[3] !== undefined ? ["1", m[3]] : [m[1], m[2]])
+  if (!m) return { lo: defaultLo, hi: defaultHi };
+  const tokens = (m[3] !== undefined ? [String(defaultLo), m[3]] : [m[1], m[2]])
     .map((t) => String(t).replace(/[,.?!]+$/, ""));
   if (!tokens.every((t) => /^-?\d+$/.test(t))) {
-    return { problem: 'I can only play with whole-number bounds — say "between 1 and 100".' };
+    return { problem: `I can only play with whole-number bounds — say "between ${defaultLo} and ${defaultHi}".` };
   }
   const lo = Number(tokens[0]);
   const hi = Number(tokens[1]);
-  if (Math.abs(lo) > GAME_BOUND_MAX || Math.abs(hi) > GAME_BOUND_MAX) {
-    return { problem: `that range is too big for a fair game — keep both bounds within ${GAME_BOUND_MAX.toLocaleString("en-US")}.` };
+  if (Math.abs(lo) > maxBound || Math.abs(hi) > maxBound) {
+    return { problem: `that range is too big for a fair game — keep both bounds within ${maxBound.toLocaleString("en-US")}.` };
   }
   if (hi < lo) return { problem: `no number is between ${lo} and ${hi} — that range is empty. Put the smaller bound first.` };
   if (hi === lo) return { problem: `between ${lo} and ${hi} leaves exactly one number, so there is nothing to guess. Pick a wider range.` };
@@ -12485,20 +12500,21 @@ const THINKER_OPEN_TAIL_RE = /^[\s,.!?—-]*(?:and\s+)?(?:i\s*(?:'ll|\s+will)\s+
 const INVITATION_OPEN_LEAD_RE = /^(?:let'?s\s+play|wanna\s+play|want\s+to\s+play|can\s+we\s+play|shall\s+we\s+play|do\s+you\s+want\s+to\s+play|will\s+you\s+play|play)\s+(?:a\s+)?(?:game\s+of\s+)?(?:guess[- ]the[- ]number|number[- ]guessing(?:\s+game)?|guessing\s+game)\b(.*)$/i;
 const INVITATION_OPEN_TAIL_RE = /^[\s,.!?—-]*(?:with\s+me|together)?[\s,.!?—-]*$/i;
 
-/** An opening move — { mode, bounds } — or null. */
-function matchGameOpening(line) {
+/** An opening move — { mode, bounds } — or null. `gameConfig` defaults to
+ *  DEFAULT_GAME_CONFIG.guessNumber and threads through to parseGameBounds. */
+function matchGameOpening(line, gameConfig = DEFAULT_GAME_CONFIG.guessNumber) {
   const l = String(line).trim();
   const guesser = l.match(GUESSER_OPEN_LEAD_RE);
   if (guesser && GUESSER_OPEN_TAIL_RE.test(guesser[1].replace(GAME_BOUNDS_CLAUSE_RE, " "))) {
-    return { mode: "guesser", bounds: parseGameBounds(l) };
+    return { mode: "guesser", bounds: parseGameBounds(l, gameConfig) };
   }
   const thinker = l.match(THINKER_OPEN_LEAD_RE);
   if (thinker && THINKER_OPEN_TAIL_RE.test(thinker[1].replace(GAME_BOUNDS_CLAUSE_RE, " "))) {
-    return { mode: "thinker", bounds: parseGameBounds(l) };
+    return { mode: "thinker", bounds: parseGameBounds(l, gameConfig) };
   }
   const invite = l.match(INVITATION_OPEN_LEAD_RE);
   if (invite && INVITATION_OPEN_TAIL_RE.test(invite[1].replace(GAME_BOUNDS_CLAUSE_RE, " "))) {
-    return { mode: "thinker", bounds: parseGameBounds(l) };
+    return { mode: "thinker", bounds: parseGameBounds(l, gameConfig) };
   }
   return null;
 }
@@ -12611,10 +12627,10 @@ function gameContinuationAnswer(line, game, planHolder) {
 /** The whole game lane for one turn: continuations first (active game only),
  *  then opening moves, with the one-at-a-time declines both ways across the
  *  shared plan slot. Null when the turn is not the game's to answer. */
-function guessNumberTurn(line, { planHolder, env }) {
+function guessNumberTurn(line, { planHolder, env, gameConfig = DEFAULT_GAME_CONFIG }) {
   const state = planHolder?.state ?? null;
   const game = state?.game ?? null;
-  const opening = matchGameOpening(line);
+  const opening = matchGameOpening(line, gameConfig?.guessNumber);
   if (game) {
     const continuation = gameContinuationAnswer(line, game, planHolder);
     if (continuation) return continuation;
@@ -12855,7 +12871,13 @@ function vocabAntecedentFrom(last) {
   return m[1];
 }
 
-export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "", env = process.env, lexicon = null, narrate = false, vocabHint = null, tel = null, biasByBundle = {}, factRowsCache: injectedFactRowsCache = null, planState = null, _noSplit = false } = {}) {
+export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "", env = process.env, lexicon = null, narrate = false, vocabHint = null, tel = null, biasByBundle = {}, factRowsCache: injectedFactRowsCache = null, planState = null, gameConfig = null, _noSplit = false } = {}) {
+  // Every game's tuning knobs (spider-fly's mass economy, guess-the-number's
+  // bounds, the shared plan lane's search-depth cap) — a caller's own
+  // gameConfig (chat-session.mjs resolves one per session from tmct.toml)
+  // wins outright; direct/library callers that omit it get the shipped
+  // defaults, byte-identical to before this seam existed.
+  const resolvedGameConfig = gameConfig ?? DEFAULT_GAME_CONFIG;
   const line = String(input ?? "").trim();
   // ONE fresh, empty cache for this turn only — every factRows() reader
   // reached from this call shares it, so the first reader computes
@@ -12912,7 +12934,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   // the PLAN NEXT block below write planHolder.state; every other path leaves
   // it untouched, and the caller re-threads whatever comes back.
   const planHolder = { state: planState };
-  const ctx = { config, source, graph, focus, last, memoryDir, sessionId, templates, env, lexicon, trace, narrate, vocabHint: resolvedVocabHint, tel, biasByBundle, cache: factRowsCache, vocabAntecedent, planHolder };
+  const ctx = { config, source, graph, focus, last, memoryDir, sessionId, templates, env, lexicon, trace, narrate, vocabHint: resolvedVocabHint, tel, biasByBundle, cache: factRowsCache, vocabAntecedent, planHolder, gameConfig: resolvedGameConfig };
   // A DISPATCHED turn (count / slash-command / ask) becomes the new "last
   // answer" that why/say-more re-renders; a conversational turn does not.
   // Every dispatched turn's result passes through finish() here — the LAST
@@ -12973,7 +12995,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   // line would otherwise read as a declarative to remember. A mid-game line
   // matching no game shape returns null here and the game stands untouched.
   {
-    const gameTurn = guessNumberTurn(workingLine, { planHolder, env });
+    const gameTurn = guessNumberTurn(workingLine, { planHolder, env, gameConfig: resolvedGameConfig });
     if (gameTurn) {
       note(trace, `lane: ${gameTurn.note}`);
       if (gameTurn.goal) note(trace, `goal: ${gameTurn.goal}`);
@@ -13015,7 +13037,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   // opening line would otherwise read as a declarative or an orientation ask.
   {
     const sfTurn = await spiderFlyTurn(workingLine, {
-      planHolder, memoryDir, env, cache: factRowsCache, isPlanFrameLine,
+      planHolder, memoryDir, env, cache: factRowsCache, isPlanFrameLine, gameConfig: resolvedGameConfig,
     });
     if (sfTurn) {
       note(trace, `lane: ${sfTurn.note}`);

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

@@ -22,6 +22,7 @@ import { foldSpiderFlyState, runSpiderFlyTick, startSpiderFlyGame } from "./spid
 import { worldProvenanceTag } from "../domain/worlds-pack.mjs";
 import { getWorldsPackProvider } from "../adapters/corpus/worlds-pack.mjs";
 import { appendFacts, appendRule, loadMemory, readFactRows } from "../adapters/memory/core.mjs";
+import { DEFAULT_GAME_CONFIG } from "../domain/game-config.mjs";
 
 // ---- recognizers: the closed opening/stop/tick/address set -------------------
 
@@ -70,7 +71,7 @@ const WORLD_OPENING_FALLBACK =
 
 // ---- the opening turn: load the shipped board through the worlds pack -------
 
-async function openSpiderFlyGame({ planHolder, memoryDir, env, cache }) {
+async function openSpiderFlyGame({ planHolder, memoryDir, env, cache, gameConfig = DEFAULT_GAME_CONFIG }) {
   if (!memoryDir) {
     return {
       text: "the spider-and-fly game needs a session with a memory store to hold the board — start tmct inside a repo first.",
@@ -99,7 +100,7 @@ async function openSpiderFlyGame({ planHolder, memoryDir, env, cache }) {
   }
   if (cache) cache.rows = null; // the fact-rows cache predates these writes
 
-  const { started } = await startSpiderFlyGame(memoryDir, { flyCount: 1 });
+  const { started } = await startSpiderFlyGame(memoryDir, { flyCount: 1, config: gameConfig?.spiderFly });
   planHolder.state = { spiderFly: { turn: 0 } };
   const opener = started
     ? (payload.meta?.opening || WORLD_OPENING_FALLBACK)
@@ -212,8 +213,8 @@ function describeEcologyNote(eco) {
   return bits.length ? `; ${bits.join(", ")}` : "";
 }
 
-async function runTickAndRender({ planHolder, memoryDir, cache, toldFacts = [], addressedNote = null }) {
-  const tick = await runSpiderFlyTick(memoryDir, { toldFacts });
+async function runTickAndRender({ planHolder, memoryDir, cache, toldFacts = [], addressedNote = null, gameConfig = DEFAULT_GAME_CONFIG }) {
+  const tick = await runSpiderFlyTick(memoryDir, { toldFacts, config: gameConfig?.spiderFly });
   if (cache) cache.rows = null;
   planHolder.state = { spiderFly: { turn: tick.turn } };
   return {
@@ -232,7 +233,7 @@ async function runTickAndRender({ planHolder, memoryDir, cache, toldFacts = [],
  *  current turn's told-facts"). This also matches how runSpiderFlyTick
  *  itself already works: it holds no standing plan or belief between calls,
  *  recomputing everything fresh from the folded fact rows every tick. */
-async function runToldFactTurn(match, { planHolder, memoryDir, cache }) {
+async function runToldFactTurn(match, { planHolder, memoryDir, cache, gameConfig = DEFAULT_GAME_CONFIG }) {
   const [, addrKindRaw, addrNum, subjKindRaw, subjNum, direction, cellLiteral] = match;
   const addrKind = addrKindRaw.toLowerCase();
   const subjKind = subjKindRaw.toLowerCase();
@@ -258,7 +259,7 @@ async function runToldFactTurn(match, { planHolder, memoryDir, cache }) {
   const targetCellId = cellId(targetCell.x, targetCell.y);
   const toldFacts = [{ subject: subjectId, toAgent: addresseeId, cell: targetCellId, turn: state.turnCount + 1 }];
   return runTickAndRender({
-    planHolder, memoryDir, cache, toldFacts,
+    planHolder, memoryDir, cache, toldFacts, gameConfig,
     addressedNote: `told the ${addresseeId} the ${subjectId} is at ${targetCellId}`,
   });
 }
@@ -275,7 +276,7 @@ async function runToldFactTurn(match, { planHolder, memoryDir, cache }) {
  * ordinary lanes unchanged, board untouched (§6.2 — no special-cased
  * spider-fly code path for plain questions).
  */
-export async function spiderFlyTurn(line, { planHolder, memoryDir, env, cache = null, isPlanFrameLine = () => false }) {
+export async function spiderFlyTurn(line, { planHolder, memoryDir, env, cache = null, isPlanFrameLine = () => false, gameConfig = DEFAULT_GAME_CONFIG }) {
   const slot = planHolder?.state ?? null;
   const spiderFly = slot?.spiderFly ?? null;
   const opening = SPIDER_FLY_OPEN_RE.test(line);
@@ -305,7 +306,7 @@ export async function spiderFlyTurn(line, { planHolder, memoryDir, env, cache =
         note: "SPIDER-FLY — an opening arrived while a plan frame is active; the slot holds one thing at a time",
       };
     }
-    return openSpiderFlyGame({ planHolder, memoryDir, env, cache });
+    return openSpiderFlyGame({ planHolder, memoryDir, env, cache, gameConfig });
   }
 
   // A game is live.
@@ -343,11 +344,11 @@ export async function spiderFlyTurn(line, { planHolder, memoryDir, env, cache =
         miss: true,
       };
     }
-    return runToldFactTurn(told, { planHolder, memoryDir, cache });
+    return runToldFactTurn(told, { planHolder, memoryDir, cache, gameConfig });
   }
 
   if (SPIDER_FLY_TICK_RE.test(line)) {
-    return runTickAndRender({ planHolder, memoryDir, cache, toldFacts: [] });
+    return runTickAndRender({ planHolder, memoryDir, cache, toldFacts: [], gameConfig });
   }
 
   return null; // an unaddressed aside — the ordinary lanes answer, board untouched

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

@@ -171,6 +171,11 @@ ${THEME_TOKENS_CSS}
   .chatask .prompt { color: var(--taught); font-size: .78rem; font-family: ${MONO_STACK}; }
   .chatask input { flex: 1; font-family: ${MONO_STACK}; font-size: .78rem; background: var(--bg); color: var(--ink); border: 1px solid var(--line); padding: .32rem .55rem; min-width: 0; }
   .chatask input:disabled { opacity: .5; }
+  .chatpills { display: flex; flex-wrap: wrap; gap: .3rem; margin-top: .5rem; }
+  .pill { font-family: ${MONO_STACK}; font-size: .68rem; padding: .2rem .6rem; border: 1px solid var(--line); border-radius: 99px; background: var(--bg); color: var(--ink); white-space: nowrap; }
+  .pill:hover:not(:disabled) { border-color: var(--taught); }
+  .pill:disabled { opacity: .45; cursor: default; }
+  .pill[data-role="addr"].active { border-color: var(--taught); color: var(--taught); }
   .controls-row { display: flex; align-items: center; gap: .6rem; margin-top: 1rem; flex-wrap: wrap; }
   .controls-row button { font-family: ${MONO_STACK}; font-size: .78rem; padding: .3rem .7rem; border: 1px solid var(--line); background: var(--card); color: var(--ink); }
   .controls-row button:hover:not(:disabled) { border-color: var(--taught); }
@@ -206,6 +211,14 @@ ${THEME_TOKENS_CSS}
           <span class="prompt mono">tmct&gt;</span>
           <input id="chatq" type="text" placeholder="@spider the fly is east" aria-label="Address the spider or the fly" disabled>
         </form>
+        <div class="chatpills" id="chatpills" role="group" aria-label="quick phrases to fill the chat input">
+          <button type="button" class="pill" data-role="addr" data-addressee="spider" disabled>@spider</button>
+          <button type="button" class="pill" data-role="addr" data-addressee="fly" disabled>@fly</button>
+          <button type="button" class="pill" data-role="dir" data-direction="north" disabled>the fly is north</button>
+          <button type="button" class="pill" data-role="dir" data-direction="south" disabled>the fly is south</button>
+          <button type="button" class="pill" data-role="dir" data-direction="east" disabled>the fly is east</button>
+          <button type="button" class="pill" data-role="dir" data-direction="west" disabled>the fly is west</button>
+        </div>
       </div>
     </aside>
   </div>
@@ -238,6 +251,9 @@ const SPIDERFLY = ${gridData};
   const chatlogEl = el("chatlog");
   const chatformEl = el("chatform");
   const chatqEl = el("chatq");
+  const chatpillsEl = el("chatpills");
+  const addressPillEls = [...chatpillsEl.querySelectorAll('[data-role="addr"]')];
+  const directionPillEls = [...chatpillsEl.querySelectorAll('[data-role="dir"]')];
   const statusEl = el("status");
   const turnLabelEl = el("turnLabel");
   const resetBtn = el("resetBtn");
@@ -465,6 +481,42 @@ const SPIDERFLY = ${gridData};
     });
   });
 
+  // ---- chat pills: click-to-fill shortcuts over the SAME #chatq input, never
+  // a second path into the engine — a pill only ever sets/appends text and
+  // focuses the field, exactly what typing the same characters would do, so
+  // free typing keeps working unchanged and every resulting phrase is one the
+  // addressed teach-frame grammar (SPIDER_FLY_TOLD_RE in spider-fly-turn.mjs)
+  // genuinely accepts.
+  function addresseeKindOf(value) {
+    const m = /^@(spider|fly)(?:-\\d+)?\\b/i.exec(String(value).trim());
+    return m ? m[1].toLowerCase() : null;
+  }
+  function refreshPills() {
+    const explicitKind = addresseeKindOf(chatqEl.value);
+    const subject = (explicitKind || "spider") === "spider" ? "fly" : "spider";
+    for (const btn of directionPillEls) btn.textContent = "the " + subject + " is " + btn.dataset.direction;
+    for (const btn of addressPillEls) btn.classList.toggle("active", btn.dataset.addressee === explicitKind);
+  }
+  for (const btn of addressPillEls) {
+    btn.addEventListener("click", () => {
+      chatqEl.value = "@" + btn.dataset.addressee + " ";
+      refreshPills();
+      chatqEl.focus();
+    });
+  }
+  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;
+      refreshPills();
+      chatqEl.focus();
+    });
+  }
+  chatqEl.addEventListener("input", refreshPills);
+  refreshPills();
+
   // ---- serialize every engine-touching call: the ticker and the chat dock
   // share one in-memory store, and an overlapping tick()/turn() pair could
   // race against the same @turnN write.
@@ -481,6 +533,7 @@ const SPIDERFLY = ${gridData};
     statusEl.textContent = session.opening;
     chatqEl.disabled = false;
     resetBtn.disabled = false; playBtn.disabled = false; stepBtn.disabled = false;
+    for (const btn of [...addressPillEls, ...directionPillEls]) btn.disabled = false;
   }
 
   let loopScheduled = false;