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

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>

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,
@@ -396,6 +401,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. */
@@ -1053,6 +1081,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
@@ -1152,18 +1184,41 @@ 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";
+      if (blendsPreyDecision && role === "prey" && 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 = 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.
+        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)

package/src/services/research-viz.mjs

@@ -19,7 +19,7 @@
 // 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 { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import { fetchWithProgress, loadProgressLine, factTripleParts } from "./memory-panel-viz.mjs";
 import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
 import { loadWinkVendor } from "./viz-boot.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>

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>

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