@polycode-projects/the-mechanical-code-talker 5.0.4 → 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,
@@ -58,6 +63,12 @@ const PLACEMENT_PREDICATE = "mgx:currently-in";
 const MASS_PREDICATE = "mgx:hasMass";
 const MOOD_PREDICATE = "mgx:feels";
 const FACING_PREDICATE = "mgx:facing";
+// The facing a visitor's own hand turned an agent to, written only on a driven
+// turn. It folds into the same facing map as the ordinary row below, which is
+// what makes a hand turn hold while the agent stands still and lose the moment
+// the planner takes a step of its own: the step's own facing row is stamped
+// with a later turn, and a later turn outranks.
+const DRIVEN_FACING_PREDICATE = "mgx:driven-facing";
 const EATEN_BY_PREDICATE = "mgx:eaten-by";
 const STARVED_PREDICATE = "mgx:starved";
 const PLACED_BY_PREDICATE = "mgx:placed-by";
@@ -86,7 +97,7 @@ const TURN_PLAYED_PREDICATE = "mgx:turn-played";
 const BOARD_SUBJECT = "square";
 
 const MUDIII_STATE_PREDICATE_SET = new Set([
-  PLACEMENT_PREDICATE, MASS_PREDICATE, MOOD_PREDICATE, FACING_PREDICATE,
+  PLACEMENT_PREDICATE, MASS_PREDICATE, MOOD_PREDICATE, FACING_PREDICATE, DRIVEN_FACING_PREDICATE,
   EATEN_BY_PREDICATE, STARVED_PREDICATE, PLACED_BY_PREDICATE,
   MODEL_PREDICATE, ROTATION_PREDICATE, TURN_PLAYED_PREDICATE,
   CARRYING_PREDICATE, PREY_EATEN_PREDICATE, WEB_BUILT_PREDICATE,
@@ -208,6 +219,7 @@ export function foldTownSquareState(factRows) {
         if (snap && rowEpoch === epoch) tickCount = Math.max(tickCount, turn);
         break;
       case FACING_PREDICATE:
+      case DRIVEN_FACING_PREDICATE:
         if (outranks(rowEpoch, turn, facing.get(base))) facing.set(base, { value: row.object, turn, epoch: rowEpoch });
         break;
       case EATEN_BY_PREDICATE:
@@ -389,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. */
@@ -448,6 +483,29 @@ function stepPlan(fromCell, toCell) {
   return direction ? [direction] : [];
 }
 
+/**
+ * The hand-driven move `entry` asks of an agent standing at `fromCell`, as
+ * `{ cell, facing }` with `cell` a parsed cell — or null when nothing was
+ * asked, or when what was asked is not a legal one-step move.
+ *
+ * `entry` is a target cell id, or `{ cell, facing }` with both parts optional:
+ * no cell holds the agent where it stands, which is what a turn on the spot
+ * is, and no facing leaves the facing to the step itself.
+ *
+ * The legality table is oneStepOptions — the very list the wander, evade and
+ * chase rungs pick from — so a wall or a prop is a missing exit here too,
+ * never a second notion of blocked, and a refusal reads as "no such move"
+ * rather than as a rule this seam invented. Pure.
+ */
+function acceptedManualMove(entry, fromCell, applyActions) {
+  if (!entry) return null;
+  const request = typeof entry === "string" ? { cell: entry } : entry;
+  const facing = typeof request.facing === "string" && request.facing ? request.facing : null;
+  const target = typeof request.cell === "string" && request.cell ? request.cell : cellId(fromCell.x, fromCell.y);
+  const cell = oneStepOptions(fromCell, applyActions).find((option) => cellId(option.x, option.y) === target);
+  return cell ? { cell, facing } : null;
+}
+
 const round2 = (n) => Math.round(n * 100) / 100;
 
 // ---- the goal line and the mood word -------------------------------------------
@@ -457,8 +515,9 @@ const round2 = (n) => Math.round(n * 100) / 100;
 // 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 } = {}) {
+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}.`;
@@ -980,11 +1039,20 @@ function itemsPayload(liveItemIds, { state, itemCellOf, roles, taken = null }) {
  * to where the predator was when it looked), while eating resolves on the
  * post-move ones (it is caught where the predator actually ends up).
  *
+ * `manualMoves` is the one place a visitor's own hand reaches the world:
+ * `{ agentId: cellId }`, or `{ agentId: { cell, facing } }`, checked before
+ * that agent's belief chain runs. A legal request moves the agent under the
+ * `driven` rung; an illegal one is refused and that agent decides for itself
+ * this turn, so a rejected press never freezes it. A driven turn spends a
+ * turn like any other: the ecology pass runs, and every other agent decides
+ * and moves in this same call.
+ *
  * Returns `{ turn, epoch, agents, items, ecology, rungs, activeWebs, writes }`.
  * `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 ("chase", "evade",
- * "forage", "avoid", "wander", and — on a cast that carries or spins webs —
+ * `rungs` is the decision each live agent reached this turn ("driven" for a
+ * hand-driven move, then "chase", "evade", "forage", "avoid", "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`
  * entry, which is the difference between a decision and a survivor.
@@ -993,6 +1061,7 @@ function itemsPayload(liveItemIds, { state, itemCellOf, roles, taken = null }) {
  */
 export async function runTownSquareTick(memoryDir, {
   layout, toldFacts = [], config = DEFAULT_GAME_CONFIG.mudiii, roles = MUDIII_ROLES,
+  manualMoves = {},
 } = {}) {
   const lay = typeof layout === "string" ? TOWN_SQUARE_LAYOUTS[layout] : layout;
   if (!lay) throw new Error(`runTownSquareTick: no such layout "${layout}"`);
@@ -1012,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
@@ -1031,6 +1104,11 @@ export async function runTownSquareTick(memoryDir, {
 
   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
+    // refused request leaves `driven` null, and the chain then runs exactly as
+    // it would have on a turn nobody touched.
+    const driven = acceptedManualMove(manualMoves?.[agentId], fromCell, applyActions);
+    const restingFacing = state.facing.get(agentId)?.value ?? DEFAULT_FACING;
     const visionRadius = role === "predator" ? config.predatorVisionRadius : config.preyVisionRadius;
     const beliefOpts = { visionRadius, toldFacts };
     // True unless a caller explicitly turns it off. A config object built by
@@ -1045,13 +1123,14 @@ export async function runTownSquareTick(memoryDir, {
     // 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 = nearestBelievedTarget(agentId, fromCell, rivals, state, beliefOpts);
+    const threat = driven ? null : nearestBelievedTarget(agentId, fromCell, rivals, state, beliefOpts);
 
     let rung;
     let nextCell;
     let plan;
     let goal;
     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.
@@ -1060,7 +1139,18 @@ export async function runTownSquareTick(memoryDir, {
     const captorId = (carriesPrey && role === "prey") ? (captorOfPrey.get(agentId) ?? null) : null;
     let beliefCell = fromCell;
 
-    if (isCarrying && webbedAt(fromCell)) {
+    if (driven) {
+      rung = "driven";
+      nextCell = driven.cell;
+      plan = stepPlan(fromCell, nextCell);
+      drivenFacing = driven.facing;
+      goal = goalLine("driven", {
+        cell: cellId(nextCell.x, nextCell.y),
+        facing: driven.facing ?? restingFacing,
+        held: plan.length === 0,
+      });
+      mood = "calm";
+    } else if (isCarrying && webbedAt(fromCell)) {
       // Already standing in a web: hold, so the pass's own eat gate reads this
       // same cell and resolves the delivery on this exact tick.
       rung = "deliver";
@@ -1094,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)
@@ -1166,7 +1279,10 @@ export async function runTownSquareTick(memoryDir, {
       const foodCandidates = beliefCandidates.filter((id) => foodIds.has(id));
       Object.assign(belief, beliefSnapshotFor(agentId, beliefCell, foodCandidates, state, foodBeliefOpts));
     }
-    const facing = plan[0] ?? state.facing.get(agentId)?.value ?? DEFAULT_FACING;
+    // A hand-picked facing beats the step it came with, which is what lets the
+    // page walk an agent backwards without spinning it round.
+    const facing = drivenFacing ?? plan[0] ?? restingFacing;
+    if (rung === "driven") movementWrites.push({ subject: stamp(agentId), predicate: DRIVEN_FACING_PREDICATE, object: facing });
     postMovePlacements.set(agentId, nextCell);
     rungs[agentId] = rung;
     agents[agentId] = { role, cell: cellId(nextCell.x, nextCell.y), facing, goal, mood, plan, mass: 0, belief };

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