@polycode-projects/the-mechanical-code-talker 2.7.12 → 2.7.13

package/corpus/worlds/manifest.json

@@ -3,7 +3,7 @@
   "generated": "by scripts/build-worlds-pack.mjs from corpus/worlds/src/",
   "counts": {
     "worlds": 2,
-    "facts": 527,
+    "facts": 528,
     "rules": 19
   },
   "budgets": {
@@ -14,8 +14,8 @@
   "sources": [
     {
       "file": "src/ashcombe-hall.jsonl",
-      "bytes": 8352,
-      "sha256": "f141da008edb6abfe025ddf4753fc374ccf44bdf23e3a414741f33f7246a3c9a"
+      "bytes": 8458,
+      "sha256": "79332b0700a8c8289ca4d8b5a9cf3dcff4c869fb1b45a72dd291617f61bdd184"
     },
     {
       "file": "src/spider-fly.jsonl",
@@ -31,8 +31,8 @@
     },
     {
       "file": "shards/ashcombe-hall.jsonl.gz",
-      "bytes": 948,
-      "sha256": "49bbdf7bd0008c916145e866cd174d334c97ec449bd8ec850d10985468653c25"
+      "bytes": 963,
+      "sha256": "d44e229d8f30dc43e8801443d426c315b43a6758adb11ad332c84e7108268746"
     },
     {
       "file": "shards/spider-fly.jsonl.gz",

package/corpus/worlds/src/ashcombe-hall.jsonl

@@ -33,6 +33,7 @@
 {"world":"ashcombe-hall","kind":"fact","subject":"portrait","predicate":"mgx:fixed-in","object":"drawing-room"}
 {"world":"ashcombe-hall","kind":"fact","subject":"key","predicate":"mgx:hidden-in","object":"portrait"}
 {"world":"ashcombe-hall","kind":"fact","subject":"letter","predicate":"mgx:hidden-in","object":"cabinet"}
+{"world":"ashcombe-hall","kind":"fact","subject":"letter","predicate":"mgx:is-objective","object":"true"}
 {"world":"ashcombe-hall","kind":"fact","subject":"housekeeper","predicate":"mgx:currently-in","object":"kitchen"}
 {"world":"ashcombe-hall","kind":"fact","subject":"cook","predicate":"mgx:currently-in","object":"kitchen"}
 {"world":"ashcombe-hall","kind":"fact","subject":"butler","predicate":"mgx:currently-in","object":"drawing-room"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.7.12",
+  "version": "2.7.13",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",

package/src/domain/spider-fly-world.mjs

@@ -16,6 +16,19 @@ export const GRID_SIZE = 10;
 export const WEB_HOME = Object.freeze({ x: 2, y: 2 });
 export const WEB_RADIUS = 1;
 
+// A spider-built dynamic web (src/services/spider-fly.mjs's hasActiveWebAt)
+// stays active for this many turns past the turn it was built, mirroring the
+// static home zone's own always-on web without needing separate code paths.
+export const WEB_DURATION_TURNS = 10;
+
+// Spider mass mirrors a fly's own (src/services/spider-fly.mjs's
+// FLY_INITIAL_MASS/FLY_MASS_DECREMENT_PER_TURN): a spider starves like a fly
+// does, and gains exactly a fly's remaining mass on an eat. Heavier starting
+// mass than a single fly's worth on purpose — a spider that eats nothing for
+// a while has some runway before starving.
+export const SPIDER_INITIAL_MASS = 15;
+export const SPIDER_MASS_DECREMENT_PER_TURN = 1;
+
 export const cellId = (x, y) => `cell-${x}-${y}`;
 
 const CELL_ID_RE = /^cell-(\d+)-(\d+)$/;

package/src/domain/sprite-map.mjs

@@ -79,11 +79,53 @@ const ANIMAL_SVG =
   + '<g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="7" y1="17" x2="7" y2="21"/><line x1="17" y1="17" x2="17" y2="21"/></g>'
   + "</svg>";
 
+// ---- the adventure world's own class family (PLAN_GAMES_UPLIFT_V2.md Part B)
+// — a room's floor plan, a piece of furniture, a portable, a person, the
+// player's own adventurer sprite, and a container. Ashcombe Hall's own
+// classes resolve to these directly (no ancestor walk needed, since the
+// shipped world has no rdfs:subClassOf chain at all yet); the walk stays
+// ready for a future world whose taxonomy goes deeper, the same "poodle IsA
+// dog" mechanism spider-fly already exercises.
+
+const ROOM_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="currentColor" stroke-width="1.6"/>'
+  + '<path d="M9 21 L9 13 A3 3 0 0 1 15 13 L15 21" fill="none" stroke="currentColor" stroke-width="1.6"/></svg>';
+
+const FURNITURE_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="4" y="5" width="16" height="3" rx="1" fill="currentColor"/>'
+  + '<rect x="4" y="8" width="3" height="12" fill="currentColor"/>'
+  + '<rect x="17" y="8" width="3" height="12" fill="currentColor"/></svg>';
+
+const PORTABLE_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="5" y="9" width="14" height="11" rx="1.5" fill="currentColor"/>'
+  + '<path d="M9 9 V6.5 A3 3 0 0 1 15 6.5 V9" fill="none" stroke="currentColor" stroke-width="1.6"/></svg>';
+
+const PERSON_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.5" r="3.2" fill="currentColor"/>'
+  + '<path d="M6 21 C6 15.5 8.7 13 12 13 C15.3 13 18 15.5 18 21 Z" fill="currentColor"/></svg>';
+
+// The adventurer is the player's own sprite — the same silhouette as `person`
+// plus a small satchel, so the one individual the player controls always
+// reads as visually distinct from the cast of NPCs sharing the room.
+const ADVENTURER_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.5" r="3.2" fill="currentColor"/>'
+  + '<path d="M6 21 C6 15.5 8.7 13 12 13 C15.3 13 18 15.5 18 21 Z" fill="currentColor"/>'
+  + '<rect x="15.5" y="13.5" width="4.5" height="5" rx="1" fill="currentColor" opacity="0.6"/></svg>';
+
+const CONTAINER_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="10" width="18" height="10" rx="1.2" fill="currentColor"/>'
+  + '<path d="M3 10 L5 5 H19 L21 10 Z" fill="currentColor" opacity="0.7"/>'
+  + '<rect x="10.6" y="9.4" width="2.8" height="2.2" rx="0.4" fill="currentColor" opacity="0.35"/></svg>';
+
 /** The sprite registry: class name (normFactTerm-normalized) -> inline SVG
  *  markup. `animal` is this world's declared root fallback (PLAN_SPIDER_FLY.md
  *  §7 names "animal"/"object"/"plant" as the family of possible roots — a
  *  spider-and-fly board only ever needs "animal") — resolveSpriteForClass
- *  falls back to it once the ancestor walk exhausts with no closer hit. */
+ *  falls back to it once the ancestor walk exhausts with no closer hit. The
+ *  adventure world's classes (room/furniture/portable/person/adventurer/
+ *  container) are a second, unrelated root family sharing the one flat table —
+ *  a board only ever resolves classes from its own world, so the two never
+ *  collide in practice. */
 export const SPRITE_REGISTRY = Object.freeze({
   spider: SPIDER_SVG,
   fly: FLY_SVG,
@@ -91,6 +133,12 @@ export const SPRITE_REGISTRY = Object.freeze({
   poodle: POODLE_SVG,
   dog: DOG_SVG,
   animal: ANIMAL_SVG,
+  room: ROOM_SVG,
+  furniture: FURNITURE_SVG,
+  portable: PORTABLE_SVG,
+  person: PERSON_SVG,
+  adventurer: ADVENTURER_SVG,
+  container: CONTAINER_SVG,
 });
 
 /** Every direct rdfs:subClassOf superclass of `term`, from a flat fact-row

package/src/services/adventure-autoplay.mjs

@@ -0,0 +1,192 @@
+// adventure-autoplay.mjs — a sibling layer over adventure.mjs (never edited
+// for this: this session's own in-flight rule-shape work owns that file)
+// that plays a loaded world by itself: infer a goal from one generic marker
+// fact, explore toward it, fetch it, and report an honest stall the moment no
+// further move is justified. It is a CALLER of the existing command
+// interpreter (adventureTurn), never a second one — every move it makes is
+// the same plain command string a human types ("go north", "take letter"),
+// executed through the identical turn a real chat session runs.
+//
+// The one hard constraint: auto-play only ever reasons over what it has
+// actually seen. `exposedRoomIds` is the set of rooms this auto-play run has
+// itself moved into (the opening room included from turn 0) — it is the sole
+// caller making every move, so it always knows this, and threads the set
+// forward turn to turn exactly like spider-fly.mjs threads its own agents
+// shape. `exposedFacts` turns that set into the actual filtered view: a fact
+// is exposed when its subject's CURRENT placement resolves into an exposed
+// room, when the subject is the player, or when the fact IS the world's
+// objective marker (told to the player unconditionally at turn 0, the same
+// way the opening line's prose already is). A hidden object's reveal falls
+// out of this automatically — no `mgx:hidden-in` special case is needed, the
+// placement-resolution walk already returns null for anything still hidden.
+//
+// The objective marker is one new, generic world-pack fact,
+// `{"subject":"letter","predicate":"mgx:is-objective","object":"true"}` —
+// deliberately not hard-coded to any one world. A world that ships no such
+// fact simply has nothing for this module to infer a goal toward.
+import { findActionPath } from "../domain/planning.mjs";
+import { loadMemory, readFactRows } from "../adapters/memory/core.mjs";
+import { foldWorldState, adventureTurn } from "./adventure.mjs";
+
+const SNAPSHOT_RE = /^(.+)@turn(\d+)$/;
+const baseSubjectOf = (subject) => SNAPSHOT_RE.exec(subject)?.[1] ?? subject;
+
+const isTypedRow = (rows, subject, type) =>
+  (rows || []).some((r) => r.subject === subject && r.predicate === "rdf:type" && r.object === type);
+
+/** The room a subject's CURRENT placement resolves into — a room resolves to
+ *  itself; an object placed directly in a room resolves to that room; an
+ *  object one containment hop inside an OPEN container resolves to the
+ *  container's own room; anything hidden, carried, or inside a closed
+ *  container resolves to nothing (null). This mirrors adventure.mjs's own
+ *  private `visibleRoomOf` exactly (that helper isn't exported, so the walk
+ *  is re-derived here against the same `foldWorldState` placements map,
+ *  never a second notion of visibility). */
+function roomOfSubject(subject, rows, state) {
+  if (isTypedRow(rows, subject, "room")) return subject;
+  const place = state.placements.get(subject);
+  if (!place || place.predicate === "mgx:hidden-in") return null;
+  if (place.predicate === "mgx:currently-in" || isTypedRow(rows, place.object, "room")) return place.object;
+  const holder = place.object;
+  if (holder === "player") return null; // carried, not resolvable to a room
+  if (!state.openness.get(holder)?.open) return null;
+  const holderPlace = state.placements.get(holder);
+  return holderPlace && holderPlace.predicate !== "mgx:hidden-in" ? holderPlace.object : null;
+}
+
+/**
+ * The subset of `allRows` this auto-play run may reason over, given the
+ * rooms it has actually moved into so far (`exposedRoomIds`). Pure — folds
+ * `allRows` itself rather than taking a precomputed state, so a caller never
+ * has to keep a fold in step with the exposure set by hand.
+ */
+export function exposedFacts(allRows, exposedRoomIds) {
+  const rows = allRows || [];
+  const state = foldWorldState(rows);
+  const exposed = new Set(exposedRoomIds || []);
+  return rows.filter((row) => {
+    if (baseSubjectOf(row.subject) === "player") return true;
+    if (row.predicate === "mgx:is-objective") return true;
+    const room = roomOfSubject(baseSubjectOf(row.subject), rows, state);
+    return room != null && exposed.has(room);
+  });
+}
+
+/** One hop per exposed room's own has-exit-* facts, sorted by direction name
+ *  for deterministic tie-breaking — the applyActions closure findActionPath
+ *  needs, built from the EXPOSED fold only, so a search over this graph can
+ *  never plan through an edge auto-play hasn't itself walked into. */
+function exposedExitApplyActions(exposedState) {
+  return (room) => {
+    const dirs = exposedState.exits.get(room);
+    if (!dirs) return [];
+    return [...dirs.keys()].sort().map((direction) => ({ action: direction, nextState: dirs.get(direction) }));
+  };
+}
+
+const unexposedExitsOf = (room, exposedState, exposed) =>
+  [...(exposedState.exits.get(room)?.entries() ?? [])].filter(([, target]) => !exposed.has(target));
+
+/**
+ * One auto-play tick over a live, loaded adventure: fold the world, infer a
+ * goal from the one generic objective marker under the exposure constraint,
+ * and execute exactly the one move that goal implies through `adventureTurn`
+ * — the same public entry point a real chat turn calls. Returns
+ * `{ turn, goal, plan, done, stalled, exposedRoomIds }`, mirroring
+ * spider-fly.mjs's own tick shape: `plan` is the remaining multi-step route a
+ * `findActionPath` search found this tick (or null when the move was a
+ * single, immediate step — an adjacent unexposed exit, or a take), `goal` is
+ * a short line describing what this tick did, `done` means the objective is
+ * now carried, `stalled` means no move could be justified without guessing.
+ */
+export async function runAdventureAutoplayTick(memoryDir, opts = {}) {
+  const { exposedRoomIds, planHolder, sessionId = "", env = {}, graph = null, cache = null } = opts;
+  const rows = readFactRows(await loadMemory(memoryDir));
+  const state = foldWorldState(rows);
+  const here = state.placements.get("player")?.object ?? null;
+  const exposed = new Set(exposedRoomIds || []);
+
+  if (!here) {
+    return {
+      turn: state.turnCount, goal: "stalled — no player position is written for this world.",
+      plan: null, done: false, stalled: true, exposedRoomIds: exposed,
+    };
+  }
+  exposed.add(here);
+
+  const runCommand = (line) => adventureTurn(line, { planHolder, memoryDir, sessionId, env, graph, cache });
+
+  const exposedRows = exposedFacts(rows, exposed);
+  const exposedState = foldWorldState(exposedRows);
+  const objectiveId = exposedRows.find((r) => r.predicate === "mgx:is-objective" && r.object === "true")?.subject ?? null;
+
+  // Win: the objective is already carried — checked against the FULL fold,
+  // since what the player itself carries is always self-evidently known,
+  // the same unconditional "OR the subject is player" exposure the marker
+  // fact itself gets (worldDigestRows shows carried items regardless of
+  // room visibility too — carrying was never gated on being seen).
+  const carried = objectiveId
+    && state.placements.get(objectiveId)?.predicate === "mgx:located-in"
+    && state.placements.get(objectiveId)?.object === "player";
+  if (objectiveId && carried) {
+    return {
+      turn: state.turnCount, goal: `carrying the ${objectiveId} — the adventure is won.`,
+      plan: [], done: true, stalled: false, exposedRoomIds: exposed,
+    };
+  }
+
+  const objectiveRoom = objectiveId ? roomOfSubject(objectiveId, exposedRows, exposedState) : null;
+
+  if (objectiveId && objectiveRoom) {
+    if (objectiveRoom === here) {
+      await runCommand(`take ${objectiveId}`);
+      return {
+        turn: state.turnCount + 1, goal: `in the ${here} — taking the ${objectiveId}.`,
+        plan: null, done: false, stalled: false, exposedRoomIds: exposed,
+      };
+    }
+    const path = findActionPath(here, (room) => room === objectiveRoom, exposedExitApplyActions(exposedState));
+    if (!path || !path.actions.length) {
+      return {
+        turn: state.turnCount, goal: `stalled — no seen path from the ${here} to the ${objectiveRoom}.`,
+        plan: null, done: false, stalled: true, exposedRoomIds: exposed,
+      };
+    }
+    await runCommand(`go ${path.actions[0]}`);
+    exposed.add(path.states[1]);
+    return {
+      turn: state.turnCount + 1, goal: `heading toward the ${objectiveRoom} for the ${objectiveId}.`,
+      plan: path.actions, done: false, stalled: false, exposedRoomIds: exposed,
+    };
+  }
+
+  // Explore: the objective either doesn't exist in this world, or its room
+  // isn't known yet. Prefer an immediate unexposed exit from here (the
+  // lowest-sorted direction); otherwise path toward the nearest exposed room
+  // that still has one.
+  const unexposedHere = unexposedExitsOf(here, exposedState, exposed).sort(([a], [b]) => a.localeCompare(b));
+  if (unexposedHere.length) {
+    const [direction, target] = unexposedHere[0];
+    await runCommand(`go ${direction}`);
+    exposed.add(target);
+    return {
+      turn: state.turnCount + 1, goal: `exploring — heading ${direction} into unseen ground.`,
+      plan: null, done: false, stalled: false, exposedRoomIds: exposed,
+    };
+  }
+
+  const hasUnexposedExit = (room) => unexposedExitsOf(room, exposedState, exposed).length > 0;
+  const path = findActionPath(here, hasUnexposedExit, exposedExitApplyActions(exposedState));
+  if (!path || !path.actions.length) {
+    return {
+      turn: state.turnCount, goal: "stalled — every reachable room is already explored, and no goal was ever found.",
+      plan: null, done: false, stalled: true, exposedRoomIds: exposed,
+    };
+  }
+  await runCommand(`go ${path.actions[0]}`);
+  exposed.add(path.states[1]);
+  return {
+    turn: state.turnCount + 1, goal: "exploring — backtracking toward unseen ground.",
+    plan: path.actions, done: false, stalled: false, exposedRoomIds: exposed,
+  };
+}

package/src/services/adventure-viz.mjs

@@ -0,0 +1,262 @@
+// adventure-viz.mjs — the adventure's own full-screen/home-page hero
+// (PLAN_GAMES_UPLIFT_V2.md Part B), styled directly after
+// spider-fly-viz.mjs's own self-contained page-builder: one inlined <style>
+// importing viz-theme.mjs's shared tokens, behaviour as an inlined IIFE, the
+// shared `createTicker` primitive spliced in via `.toString()` exactly the
+// way that page splices its own render-glue helpers.
+//
+// Where this page's data-loading DIVERGES from spider-fly's, on purpose:
+// spider-fly-world.mjs is itself a plain, dependency-free JS module (no I/O),
+// so its browser entry can call it directly to bootstrap a board. Ashcombe
+// Hall's canonical definition is a JSONL corpus source
+// (corpus/worlds/src/ashcombe-hall.jsonl), read through a Node fs/gzip
+// provider the browser cannot run. Rather than hand-duplicating the world as
+// a second, hardcoded JS copy (exactly the kind of drift this project's
+// worlds-pack build step exists to prevent), the real facts+rules are read
+// ONCE at build time (scripts/build-demo-site.mjs, the same Node path
+// test/services/adventure.test.mjs's own loadShippedWorldInto uses) and
+// embedded into this page as plain JSON — the same posture ledger.html
+// already takes with its own precomputed memory payload, just applied to a
+// second kind of build-time data.
+//
+// Two pure, `.toString()`-splice-safe pieces are exported as real functions
+// (not raw inline-script text) so they can be pinned directly by tests, the
+// same discipline spider-fly-viz.mjs holds classOfAgentId/
+// threadCellsForSpiderPlan to: `spriteClassForObject` (an object's sprite
+// class, from its own rdf:type or mgx:is-container fact — NOT from
+// adventure.mjs's private isContainer/isTyped, which this module cannot
+// import without duplicating adventure.mjs's own closed vocabulary reading)
+// and `roomSceneObjects` (every subject actually visible in a room, mirrored
+// from adventure.mjs's private `visibleRoomOf` the same way
+// adventure-autoplay.mjs's own `roomOfSubject` already has to). `roomCaptionText`
+// is a third pure helper, exported for testing, but NOT spliced — it calls
+// `worldDigestRows` via a real ES import, since Node/test callers have one,
+// while the in-page script instead calls the browser bundle's own exposed
+// copy (mirroring how the inline script calls `tmctSpiderFly.*` rather than
+// re-importing spider-fly-world.mjs).
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson } from "./viz-theme.mjs";
+import { createTicker } from "./viz-ticker.mjs";
+import { worldDigestRows } from "./adventure.mjs";
+
+const DEFAULT_TITLE = "tmct — the adventure";
+const PREVIEW_MAX_TICKS = 30;
+const TICK_WAIT_MS = 900;
+
+/** An object's sprite class: `container` when it carries mgx:is-container
+ *  (a distinct icon from plain furniture, since Ashcombe's own cabinet and
+ *  portrait are typed "furniture" but read more clearly as a container on
+ *  screen), else its own rdf:type object, else the generic "portable"
+ *  fallback for anything a world places with no type fact at all. Pure,
+ *  self-contained — no reference to adventure.mjs's own private isContainer/
+ *  isTyped, since those aren't exported. */
+export function spriteClassForObject(rows, subject) {
+  const isContainer = (rows || []).some(
+    (r) => r.subject === subject && r.predicate === "mgx:is-container" && r.object === "true",
+  );
+  if (isContainer) return "container";
+  const typeRow = (rows || []).find((r) => r.subject === subject && r.predicate === "rdf:type");
+  return typeRow ? typeRow.object : "portable";
+}
+
+/** Every subject actually visible in `here`, sorted, each with its sprite
+ *  class — mirroring adventure.mjs's own private `visibleRoomOf` walk (one
+ *  containment hop through an OPEN container) so this can never draw a
+ *  hidden or carried object the text digest wouldn't also mention. `player`
+ *  is excluded; the caller draws the player's own adventurer sprite
+ *  separately. Pure. */
+export function roomSceneObjects(rows, state, here) {
+  const isTypedRoom = (subject) =>
+    (rows || []).some((r) => r.subject === subject && r.predicate === "rdf:type" && r.object === "room");
+  const visibleRoomOf = (subject) => {
+    const place = state.placements.get(subject);
+    if (!place || place.predicate === "mgx:hidden-in") return null;
+    if (place.predicate === "mgx:currently-in" || isTypedRoom(place.object)) return place.object;
+    const holder = place.object;
+    if (holder === "player") return null;
+    if (!state.openness.get(holder)?.open) return null;
+    const holderPlace = state.placements.get(holder);
+    return holderPlace && holderPlace.predicate !== "mgx:hidden-in" ? holderPlace.object : null;
+  };
+  const out = [];
+  for (const subject of [...state.placements.keys()].sort()) {
+    if (subject === "player") continue;
+    if (visibleRoomOf(subject) !== here) continue;
+    out.push({ subject, spriteClass: spriteClassForObject(rows, subject) });
+  }
+  return out;
+}
+
+/** A short caption for `here`, built ONLY from the rows worldDigestRows
+ *  itself already produces (the exact same view the chat reply's own digest
+ *  reads) — every row already reads as a plain sentence
+ *  (`${subject} ${predicate} ${object}.`), so this never invents a phrase
+ *  the text digest doesn't already carry. Filters to rows about the room
+ *  itself (its own exits) or about something placed IN it — the same
+ *  "visible here" boundary `roomSceneObjects` draws from. The player's own
+ *  "is in the" row is excluded: the room frame already IS the current room,
+ *  so restating "you are here" is redundant, never informative. */
+export function roomCaptionText(rows, state, here) {
+  const hereCased = here.charAt(0).toUpperCase() + here.slice(1);
+  const lines = worldDigestRows(rows, state)
+    .filter((row) => row.subject !== "Player" && (row.object === here || row.subject === hereCased))
+    .map((row) => `${row.subject} ${row.predicate} ${row.object}.`);
+  return lines.length ? lines.join(" ") : `Nothing more about the ${here} is written down yet.`;
+}
+
+/** The self-contained adventure page. Pure given `worldPayload` (the build
+ *  step's own read of the real Ashcombe Hall world — `{ facts, rules,
+ *  opening }`), the same "byte-identical for identical input" invariant
+ *  every other viz page in this project holds. `?preview=1` switches into
+ *  the small, auto-playing, non-interactive mode the home page's hero iframe
+ *  embeds, matching spider-fly.html's own dual-purpose file. */
+export function renderAdventureHtml({ title = DEFAULT_TITLE, worldPayload = { facts: [], rules: [], opening: "" } } = {}) {
+  const pageData = embedJson({
+    world: worldPayload,
+    previewMaxTicks: PREVIEW_MAX_TICKS,
+    tickWaitMs: TICK_WAIT_MS,
+  });
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+${THEME_TOKENS_CSS}
+  html { background: var(--bg); }
+  body { margin: 0; background: var(--bg); color: var(--ink); font-family: ${SERIF_STACK}; font-size: 16px; line-height: 1.5; }
+  .mono { font-family: ${MONO_STACK}; }
+  main { max-width: 860px; 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(--muted); }
+  h1 { font-size: 1.4rem; margin: .3rem 0 .9rem; text-wrap: balance; }
+  button { font: inherit; color: inherit; background: none; cursor: pointer; }
+  button:focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
+  .room-frame { position: relative; min-height: 210px; background: var(--taught-soft); border: 1px solid var(--line); padding: 1rem; display: flex; flex-direction: column; gap: .8rem; justify-content: flex-end; }
+  .sprite-row { display: flex; flex-wrap: wrap; gap: .6rem; align-items: flex-end; }
+  .sprite { width: 44px; height: 44px; }
+  .sprite svg { width: 100%; height: 100%; display: block; }
+  .sprite[data-cls="adventurer"] { color: var(--taught); }
+  .sprite[data-cls="person"] { color: var(--corpus); }
+  .sprite[data-cls="container"], .sprite[data-cls="furniture"] { color: var(--entail); }
+  .sprite[data-cls="portable"] { color: var(--alert); }
+  .sprite[data-cls="room"] { color: var(--muted); }
+  .sprite-label { font-family: ${MONO_STACK}; font-size: .62rem; text-align: center; color: var(--muted); margin-top: .15rem; }
+  .caption { background: var(--card); border: 1px solid var(--line); padding: .6rem .75rem; font-size: .9rem; }
+  .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); }
+  .controls-row button:disabled { opacity: .4; cursor: default; }
+  .controls-row .turn { margin-left: auto; font-family: ${MONO_STACK}; font-size: .78rem; color: var(--muted); font-variant-numeric: tabular-nums; }
+  .goal-line { font-family: ${MONO_STACK}; font-size: .78rem; color: var(--muted); margin-top: .5rem; }
+  .status { font-family: ${MONO_STACK}; font-size: .74rem; color: var(--muted); margin-top: .3rem; }
+  body.preview .controls-row, body.preview .status { display: none; }
+  body.preview main { padding: 0; max-width: none; }
+  body.preview .eyebrow, body.preview h1 { display: none; }
+</style>
+</head>
+<body>
+<main>
+  <div class="eyebrow">tmct &middot; the adventure</div>
+  <h1>A room, drawn from exactly what the text already says is there</h1>
+  <div class="room-frame" id="roomFrame">
+    <div class="sprite-row" id="spriteRow"></div>
+  </div>
+  <div class="caption" id="caption"></div>
+  <div class="goal-line" id="goalLine"></div>
+  <div class="controls-row">
+    <button id="resetBtn" type="button" disabled>reset</button>
+    <button id="playBtn" type="button" disabled>&#9654; play</button>
+    <button id="stepBtn" type="button" disabled>step</button>
+    <span class="turn mono" id="turnLabel">turn: 0</span>
+  </div>
+  <div class="status" id="status">loading the engine&hellip;</div>
+</main>
+<script>
+const ADVENTURE = ${pageData};
+</script>
+<script src="./adventure-browser.bundle.js"></script>
+<script>
+(function () {
+  "use strict";
+  const createTicker = ${createTicker.toString()};
+  const spriteClassForObject = ${spriteClassForObject.toString()};
+  const roomSceneObjects = ${roomSceneObjects.toString()};
+  const esc = ${escapeHtml.toString()};
+  const el = (id) => document.getElementById(id);
+  const spriteRow = el("spriteRow");
+  const captionEl = el("caption");
+  const goalLineEl = el("goalLine");
+  const statusEl = el("status");
+  const turnLabelEl = el("turnLabel");
+  const resetBtn = el("resetBtn");
+  const playBtn = el("playBtn");
+  const stepBtn = el("stepBtn");
+
+  const params = new URLSearchParams(location.search);
+  const preview = params.get("preview") === "1";
+  document.body.classList.toggle("preview", preview);
+
+  let session = null;
+  let lastTicks = 0;
+
+  function captionFor(rows, state, here) {
+    const hereCased = here.charAt(0).toUpperCase() + here.slice(1);
+    const lines = tmctAdventure.worldDigestRows(rows, state)
+      .filter((row) => row.subject !== "Player" && (row.object === here || row.subject === hereCased))
+      .map((row) => row.subject + " " + row.predicate + " " + row.object + ".");
+    return lines.length ? lines.join(" ") : "Nothing more about the " + here + " is written down yet.";
+  }
+
+  function redraw(snap) {
+    const objects = roomSceneObjects(snap.rows, snap.state, snap.here);
+    const sprites = [{ subject: "you", spriteClass: "adventurer" }, ...objects];
+    spriteRow.innerHTML = sprites.map((s) => {
+      const svg = tmctAdventure.resolveSpriteForClass(s.spriteClass, [], tmctAdventure.SPRITE_REGISTRY);
+      return '<div><div class="sprite" data-cls="' + esc(s.spriteClass) + '">' + svg + '</div>'
+        + '<div class="sprite-label">' + esc(s.subject) + "</div></div>";
+    }).join("");
+    captionEl.textContent = captionFor(snap.rows, snap.state, snap.here);
+    turnLabelEl.textContent = "turn: " + snap.turn;
+  }
+
+  async function boot() {
+    session = await tmctAdventure.createAdventureSession(ADVENTURE.world);
+    lastTicks = 0;
+    const snap = await session.snapshot();
+    redraw(snap);
+    goalLineEl.textContent = "";
+    statusEl.textContent = ADVENTURE.world.opening || "";
+    resetBtn.disabled = false; playBtn.disabled = false; stepBtn.disabled = false;
+  }
+
+  const ticker = createTicker({
+    onTick: async () => {
+      const result = await session.autoplayTick();
+      lastTicks += 1;
+      const snap = await session.snapshot();
+      redraw(snap);
+      goalLineEl.textContent = result.goal || "";
+      if (result.done || result.stalled) ticker.pause();
+    },
+    onRender: (state) => {
+      playBtn.textContent = state.playing ? "\\u23f8 pause" : "\\u25b6 play";
+      playBtn.disabled = state.animating;
+      stepBtn.disabled = state.animating || state.playing;
+      resetBtn.disabled = state.animating;
+    },
+    onReset: () => boot(),
+    hasNext: () => !preview || lastTicks < ADVENTURE.previewMaxTicks,
+    waitMs: ADVENTURE.tickWaitMs,
+  });
+  playBtn.addEventListener("click", () => ticker.play());
+  stepBtn.addEventListener("click", () => ticker.stepOnce());
+  resetBtn.addEventListener("click", () => ticker.reset());
+
+  boot().then(() => { if (preview) ticker.play(); });
+})();
+</script>
+</body>
+</html>
+`;
+}