@polycode-projects/the-mechanical-code-talker 4.0.1 → 4.1.1

package/src/services/viz-boot.mjs

@@ -0,0 +1,71 @@
+// viz-boot.mjs — the shared wink-nlp vendor loader six-plus-one viz modules
+// each hand-rolled with the same bounded-race shape (`research-viz.mjs`,
+// `ingest-viz.mjs`, `plan-viz.mjs`, `ledger-viz.mjs`, `sprite-catalog-viz.mjs`,
+// `chat-page-viz.mjs`, each commenting that it uses "the same pattern" as a
+// sibling; `code-explorer-viz.mjs` is a seventh with no timeout at all).
+// `import()` can fail in a way that neither resolves nor rejects (a stalled
+// network request, an old cached asset), so every copy already raced it
+// against a timeout rather than awaiting it unbounded.
+//
+// This converges the seven onto ONE failure behaviour: a fixed timer from
+// the call, memoized so a second boot path awaiting the same load (every
+// caller here has at least two — an eager fire-and-forget at page load, then
+// an `await` inside its own session-ensuring function) resolves immediately
+// rather than racing the import a second time. That is the shape five of the
+// seven already shared; `chat-page-viz.mjs`'s own richer variant measures the
+// timeout from the last downloaded byte instead of the call, so a slow-but-
+// progressing multi-megabyte download is never abandoned mid-stream — a real
+// improvement this shared version does not attempt to fold in, so that page
+// keeps its own version rather than losing the nuance to this one.
+//
+// Self-contained (no closure over page state beyond its own options),
+// `.toString()`-splice safe: `importVendor`'s default is a literal dynamic
+// `import()` expression, so when this factory's returned function is spliced
+// into a page's own inline `<script>` via `Function.prototype.toString()`,
+// the import path resolves relative to that page, exactly like every one of
+// the seven originals.
+
+/**
+ * `loadWinkVendor({ timeoutMs, register, importVendor })` returns a memoized
+ * loader function — call it with no arguments, as many times as needed (an
+ * eager fire at boot, then an awaited call before the first session needs
+ * it); every call after the first resolves the SAME promise rather than
+ * importing again.
+ *
+ * `register(factory)` is called once, only on a successful load, with a
+ * factory returning `{ winkNLP, model }` — the shape every one of the seven
+ * originals hands to their own page's `registerWinkModel`. `importVendor`
+ * (default: `() => import("./vendor/wink.js")`) is the dynamic import call
+ * itself, injectable so a test can supply a resolved/rejected/never-settling
+ * promise without a real vendor asset on disk.
+ *
+ * The loader never throws: a timeout or a load failure logs a warning and
+ * resolves `"unavailable"` — the lemma/POS tier is optional everywhere it is
+ * used, so a caller that awaits this is never blocked by its own boot.
+ * Resolves `"loaded"` on success.
+ */
+export function loadWinkVendor({
+  timeoutMs = 8000,
+  register,
+  importVendor = () => import("./vendor/wink.js"),
+} = {}) {
+  let ready = null;
+  return function loadWinkVendorOnce() {
+    if (ready) return ready;
+    ready = (async () => {
+      const timeout = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error("wink vendor asset load timed out")), timeoutMs);
+      });
+      try {
+        const mod = await Promise.race([importVendor(), timeout]);
+        if (register) register(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
+        return "loaded";
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn("tmct: the wink vendor asset failed to load, continuing without the lemma/POS tier", err);
+        return "unavailable";
+      }
+    })();
+    return ready;
+  };
+}

package/src/services/viz-room-graph.mjs

@@ -0,0 +1,203 @@
+// viz-room-graph.mjs — the room-graph layout and SVG renderer mud-viz.mjs
+// (`burrowGraph`/`burrowSvg`) and adventure-viz.mjs (`visitedRoomGraph`/its
+// own inline `roomMapSvg`) each wrote separately, unified into one
+// parametrized pair. mud-viz.mjs's own header already admits the copy.
+//
+// The two originals genuinely differ, not just in name: mud's burrow can be
+// dug two ways into the same cell (down AND south from one room), so it
+// nudges a colliding placement right rather than overlapping it, and it
+// tracks each room's surface/soil `level` for the turf line; adventure's
+// manor is fixed at authoring time and never collides, and marks the
+// player's current room instead of a level. `opts` below select each
+// behaviour rather than assuming one world's shape:
+//   - `opts.root`, if given, is placed before every other room (a stable
+//     anchor for one entry point) and turns on `level` (an "up"/"down" exit
+//     moves the level by ∓1, tracked via a BFS from `root`).
+//   - `opts.actingSubject`, if given, attaches `.current` (whether that
+//     subject's own room is this node) instead of `.level`.
+//   - `opts.nudgeCollisions` (default false) pushes a colliding placement
+//     right instead of overlapping it.
+// An edge is drawn only between two rooms BOTH in `roomIds`; `hints` names
+// every exit from an included room toward one that is not — the direction
+// only, never the excluded room's own name, so a fog-of-war caller can draw
+// "there's a way on" and nothing more. Disconnected components lay out as
+// separate side-by-side blocks. Pure.
+
+import { escapeHtml } from "./viz-theme.mjs";
+
+// Exported (not just used internally) so a caller splicing directedGridLayout/
+// roomGraphSvg into its own inline page script — as data, via JSON.stringify,
+// never `.toString()` — can carry this table along too: a spliced function's
+// source text is its own body only, never a module-level const it closes over.
+export const EXIT_DELTA = { north: [0, -1], south: [0, 1], east: [1, 0], west: [-1, 0], up: [0, -1], down: [0, 1] };
+
+/** Every room's depth level, BFS from `root` at level 0: an "up"/"down" exit
+ *  moves the level by ∓1, any other direction keeps it unchanged. A room
+ *  unreachable from `root` is absent from the returned map. Pure. */
+export function levelsOf(state, root) {
+  const levels = new Map([[root, 0]]);
+  const queue = [root];
+  while (queue.length) {
+    const room = queue.shift();
+    const level = levels.get(room);
+    for (const [direction, target] of state.exits.get(room) ?? []) {
+      if (levels.has(target)) continue;
+      const delta = direction === "down" ? -1 : direction === "up" ? 1 : 0;
+      levels.set(target, level + delta);
+      queue.push(target);
+    }
+  }
+  return levels;
+}
+
+/** Lay `roomIds` out on an integer grid FROM the world's own has-exit-*
+ *  directions — never a force-directed guess, so a room north of another
+ *  sits one row above it and a room dug down sits one row below. See the
+ *  file header for what `opts.root`/`opts.actingSubject`/
+ *  `opts.nudgeCollisions` each turn on. Pure. */
+export function directedGridLayout(state, roomIds, opts = {}) {
+  const { root = null, actingSubject = null, nudgeCollisions = false } = opts;
+  const known = new Set(roomIds || []);
+  const here = actingSubject ? (state.placements.get(actingSubject)?.object ?? null) : null;
+  const positions = new Map();
+  const taken = new Set();
+  const edges = [];
+  const edgeKeys = new Set();
+  const hints = [];
+  const place = (room, x, y) => {
+    let px = x;
+    if (nudgeCollisions) {
+      for (let guard = 0; taken.has(px + "," + y) && guard < 64; guard += 1) px += 1;
+    }
+    positions.set(room, { x: px, y });
+    taken.add(px + "," + y);
+  };
+  const seeds = root ? [root, ...[...known].sort()] : [...known].sort();
+  let offsetX = 0;
+  for (const start of seeds) {
+    if (!known.has(start) || positions.has(start)) continue;
+    place(start, offsetX, 0);
+    const queue = [start];
+    const component = [start];
+    while (queue.length) {
+      const room = queue.shift();
+      const pos = positions.get(room);
+      const dirs = state.exits.get(room);
+      for (const direction of [...(dirs?.keys() ?? [])].sort()) {
+        const target = dirs.get(direction);
+        if (!known.has(target)) { hints.push({ from: room, direction }); continue; }
+        const key = [room, target].sort().join("\0");
+        if (!edgeKeys.has(key)) { edgeKeys.add(key); edges.push({ from: room, to: target, direction }); }
+        if (positions.has(target)) continue;
+        const [dx, dy] = EXIT_DELTA[direction] ?? [0, 0];
+        place(target, pos.x + dx, pos.y + dy);
+        component.push(target);
+        queue.push(target);
+      }
+    }
+    offsetX = Math.max(...component.map((r) => positions.get(r).x)) + 2;
+  }
+  const levels = root ? levelsOf(state, root) : null;
+  const xs = [...positions.values()].map((p) => p.x);
+  const ys = [...positions.values()].map((p) => p.y);
+  const minX = Math.min(0, ...xs);
+  const minY = Math.min(0, ...ys);
+  const nodes = [...known].filter((room) => positions.has(room)).sort().map((room) => {
+    const p = positions.get(room);
+    const node = { id: room, x: p.x - minX, y: p.y - minY };
+    if (levels) node.level = levels.has(room) ? levels.get(room) : null;
+    if (actingSubject) node.current = room === here;
+    return node;
+  });
+  return { nodes, edges, hints };
+}
+
+/** Render a `directedGridLayout` graph as an inline SVG: one rect+label per
+ *  room, a line per edge, a small dot per hint (an exit toward a room not in
+ *  the graph). Returns `""` for an empty graph, so `roomGraphSvg(...) ||
+ *  fallbackHtml` reads naturally either way.
+ *
+ *  `opts.compact` picks the smaller of two built-in cell/room size tiers
+ *  (each overridable via `opts.cellX`/`cellY`/`roomW`/`roomH`).
+ *  `opts.turf` switches on the burrow-flavoured rendering: a ground line
+ *  between the surface and soil levels (wherever the graph's nodes carry
+ *  `.level` and the layout genuinely splits level 0 from every other level),
+ *  a "shaft" class on up/down edges, and `opts.occupants` (a `Map` or plain
+ *  object keyed by room id to an array of `{ character, color }`) drawing a
+ *  coloured, titled dot per occupant inside its room. Without `opts.turf`,
+ *  rendering is the manor-board style instead: `opts.clickable` adds a
+ *  `data-room` attribute and a `clickable` class, plus `selected` on
+ *  `opts.selectedRoomId`. `opts.here`, if given, marks that room id as the
+ *  current one (falling back to a node's own `.current` field from
+ *  `directedGridLayout`'s `actingSubject` option); `opts.fresh` marks one
+ *  room id as freshly created. `opts.wrapClass`, if given, wraps the `<svg>`
+ *  in a `<div class="...">`; omit it for a bare `<svg>`. `opts.label` is the
+ *  SVG's `aria-label`. Pure. */
+export function roomGraphSvg(graph, opts = {}) {
+  if (!graph.nodes.length) return "";
+  const compact = !!opts.compact;
+  const turf = !!opts.turf;
+  const cellX = opts.cellX ?? (compact ? 44 : 76);
+  const cellY = opts.cellY ?? (compact ? 26 : 54);
+  const roomW = opts.roomW ?? (compact ? 34 : 62);
+  const roomH = opts.roomH ?? (compact ? 14 : 26);
+  const maxX = Math.max(...graph.nodes.map((n) => n.x));
+  const maxY = Math.max(...graph.nodes.map((n) => n.y));
+  const w = (maxX + 1) * cellX, h = (maxY + 1) * cellY;
+  const byRoom = new Map(graph.nodes.map((n) => [n.id, n]));
+  const cx = (n) => (n.x + 0.5) * cellX;
+  const cy = (n) => (n.y + 0.5) * cellY;
+  const occupants = opts.occupants instanceof Map ? opts.occupants : new Map(Object.entries(opts.occupants || {}));
+
+  let groundBand = "";
+  if (turf) {
+    const surfaceRows = graph.nodes.filter((n) => n.level === 0).map((n) => n.y);
+    const soilRows = graph.nodes.filter((n) => n.level != null && n.level !== 0).map((n) => n.y);
+    if (surfaceRows.length && soilRows.length && Math.max(...surfaceRows) < Math.min(...soilRows)) {
+      const groundY = (Math.max(...surfaceRows) + 0.5) * cellY + roomH / 2 + (compact ? 3 : 7);
+      groundBand = `<rect class="turf" x="0" y="0" width="${w}" height="${groundY}"></rect>`
+        + `<line class="ground-line" x1="0" y1="${groundY}" x2="${w}" y2="${groundY}"></line>`;
+    }
+  }
+
+  const edgesSvg = graph.edges.map((e) => {
+    const a = byRoom.get(e.from), b = byRoom.get(e.to);
+    if (!a || !b) return "";
+    const cls = turf ? "tunnel" + (e.direction === "up" || e.direction === "down" ? " shaft" : "") : "room-edge";
+    return `<line class="${cls}" x1="${cx(a)}" y1="${cy(a)}" x2="${cx(b)}" y2="${cy(b)}"></line>`;
+  }).join("");
+
+  const hintsSvg = graph.hints.map((hi) => {
+    const from = byRoom.get(hi.from);
+    if (!from) return "";
+    const [dx, dy] = EXIT_DELTA[hi.direction] || [0, 0];
+    const reach = turf ? 0.36 : 0.42;
+    const radius = compact ? 2 : turf ? 3.2 : 3.5;
+    return `<circle class="${turf ? "hint" : "room-hint"}" cx="${cx(from) + dx * cellX * reach}" cy="${cy(from) + dy * cellY * reach}" r="${radius}"></circle>`;
+  }).join("");
+
+  const nodesSvg = graph.nodes.map((n) => {
+    const label = escapeHtml(n.id);
+    const isHere = opts.here !== undefined ? opts.here === n.id : !!n.current;
+    if (turf) {
+      const cast = occupants.get(n.id) || [];
+      const step = Math.min(compact ? 6 : 9, (roomW - 6) / Math.max(1, cast.length));
+      const dots = cast.map((c, i) => {
+        const spread = (i - (cast.length - 1) / 2) * step;
+        return `<circle class="occupant" cx="${cx(n) + spread}" cy="${cy(n) + roomH / 2}" r="${compact ? 2.4 : 3.6}" fill="${c.color}"><title>${escapeHtml(c.character)}</title></circle>`;
+      }).join("");
+      const fit = label.length * (compact ? 3.6 : 4.3) > roomW - 6
+        ? ` textLength="${roomW - 6}" lengthAdjust="spacingAndGlyphs"` : "";
+      const cls = "room" + (n.level === 0 ? " surface" : "") + (isHere ? " here" : "") + (opts.fresh === n.id ? " freshly-dug" : "");
+      return `<g class="${cls}" data-room="${label}"><rect x="${cx(n) - roomW / 2}" y="${cy(n) - roomH / 2}" width="${roomW}" height="${roomH}" rx="3"></rect>`
+        + `<text x="${cx(n)}" y="${cy(n) + (compact ? 2 : 2.5)}"${fit}>${label}</text>${dots}</g>`;
+    }
+    const cls = "room-node" + (isHere ? " current" : "") + (opts.clickable ? " clickable" : "") + (opts.clickable && n.id === opts.selectedRoomId ? " selected" : "");
+    const attr = opts.clickable ? ` data-room="${label}"` : "";
+    return `<g class="${cls}"${attr}><rect x="${cx(n) - roomW / 2}" y="${cy(n) - roomH / 2}" width="${roomW}" height="${roomH}" rx="3"></rect>`
+      + `<text x="${cx(n)}" y="${cy(n) + 2.5}">${label}</text></g>`;
+  }).join("");
+
+  const svg = `<svg viewBox="0 0 ${w} ${h}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="${escapeHtml(opts.label || "the room graph")}">${groundBand}${edgesSvg}${hintsSvg}${nodesSvg}</svg>`;
+  return opts.wrapClass ? `<div class="${opts.wrapClass}">${svg}</div>` : svg;
+}

package/src/services/viz-theme.mjs

@@ -4,6 +4,7 @@
 //
 // Trust tiers are precomputed rgba() values per provenance color so pages
 // render identically on browsers without color-mix() support.
+import { pluralOf } from "../domain/inflect.mjs";
 
 export const SERIF_STACK = `"Charter", "Bitstream Charter", Georgia, "Times New Roman", serif`;
 export const MONO_STACK = `ui-monospace, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace`;
@@ -45,7 +46,10 @@ function rgba(hex, alpha) {
   return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${alpha})`;
 }
 
-const TOKENS = Object.freeze({
+/** The light/dark token table — the raw hex/alpha values `THEME_TOKENS_CSS`
+ *  compiles into CSS custom properties. Exported so a page's own inlined
+ *  dark-mode CSS can read a value directly instead of restating it. */
+export const TOKENS = Object.freeze({
   light: Object.freeze({
     bg: "#F7F6F2", ink: "#23272B", muted: "#6E7168", line: "#DDD9D0", card: "#FFFFFF",
     taught: "#2E7D4F", corpus: "#5A80AC", entail: "#B07C2E", alert: "#B0503F",
@@ -86,3 +90,73 @@ export const THEME_TOKENS_CSS = `
   :root[data-theme="dark"] { ${tokenBlock(TOKENS.dark)} }
   :root[data-theme="light"] { ${tokenBlock(TOKENS.light)} }
 `;
+
+/** "N word"/"N words" — every current hand-pluralized count in the estate
+ *  (`n === 1 ? "" : "s"`) is a regular plural, so this is a clean swap: pass
+ *  `plural` only for the rare irregular noun. Pure. */
+export function countLabel(n, singular, plural = pluralOf(singular)) {
+  return `${n} ${n === 1 ? singular : plural}`;
+}
+
+/** `rows` narrowed to the ones a world's own provenance tag ("world:<name>")
+ *  wrote — the same prefix filter mud.html's and adventure.html's edit modes
+ *  each apply to keep a world's own facts apart from whatever background
+ *  corpus shares the same live store. Pure. */
+export function rowsForWorld(rows, worldName) {
+  const prefix = "world:" + worldName;
+  return (rows || []).filter((r) => typeof r.provenance === "string" && r.provenance.indexOf(prefix) === 0);
+}
+
+/** A generic clamped-percentage meter: `<div class="meter-track"><div
+ *  class="meter-fill <cls>" style="width:N%"></div></div>`, empty when
+ *  `value` isn't a number or `max` is falsy (nothing to show, not a 0%
+ *  bar). `cls` rides on the inner fill for per-kind styling (e.g. a colour
+ *  per creature class). Pure. */
+export function meterBarHtml(cls, value, max) {
+  if (typeof value !== "number" || !max) return "";
+  const pct = Math.max(0, Math.min(100, (value / max) * 100));
+  return `<div class="meter-track"><div class="meter-fill ${escapeHtml(cls)}" style="width:${pct}%"></div></div>`;
+}
+
+/** The identifier-shaped word immediately before `cursorPos` in `text`,
+ *  lowercased — a cursor-suggestion pill's own lookup key. Empty when the
+ *  cursor sits after whitespace/punctuation rather than a word. Pure,
+ *  self-contained (no closure state), `.toString()`-splice safe. */
+export function wordBeforeCursor(text, cursorPos) {
+  const head = String(text || "").slice(0, cursorPos);
+  const m = head.match(/[A-Za-z][A-Za-z0-9-]*$/);
+  return m ? m[0].toLowerCase() : "";
+}
+
+/** Append one line to a chat/event log element: a plain-text line, dropped
+ *  in with `textContent` (never `innerHTML` — the caller's text is untrusted
+ *  chat/answer text, not markup) and the log scrolled to show it. `clip`
+ *  (default false) turns on mud.html's own "read more" affordance: once the
+ *  line is in the DOM, measure its full (unclamped) height against its
+ *  actually-rendered one, and if a CSS line-clamp on `cls` is cutting it off,
+ *  mark the element `clipped` (with a button role/tabindex/title) so a click
+ *  or Enter can open the whole text elsewhere. `clip` is a no-op on a class
+ *  with no clamping rule — nothing to detect, nothing gets marked. Returns
+ *  the created element, so a caller with more to wire (a click handler) can.
+ *  Self-contained, `.toString()`-splice safe. */
+export function appendLogLine(el, cls, text, { clip = false } = {}) {
+  const d = document.createElement("div");
+  d.className = cls;
+  d.textContent = text;
+  el.appendChild(d);
+  if (clip) {
+    // A line-clamped box reports scrollHeight EQUAL to its clamped height, so
+    // the overflow has to be read against the same box with the clamp lifted.
+    d.classList.add("unclamped");
+    const wholeHeight = d.scrollHeight;
+    d.classList.remove("unclamped");
+    if (wholeHeight - d.clientHeight > 2) {
+      d.classList.add("clipped");
+      d.setAttribute("role", "button");
+      d.setAttribute("tabindex", "0");
+      d.setAttribute("title", "read the whole line");
+    }
+  }
+  el.scrollTop = el.scrollHeight;
+  return d;
+}

package/src/services/viz-ticker.mjs

@@ -117,3 +117,25 @@ export function prefersReducedMotion() {
     ? window.matchMedia("(prefers-reduced-motion: reduce)").matches
     : false;
 }
+
+/** A FIFO queue of async jobs that never overlap — the same primitive
+ *  mud-viz.mjs (`tickChain`/`serializeTick`) and adventure-viz.mjs/
+ *  spider-fly-viz.mjs (`lock`/`withLock`) each wrote under a different name,
+ *  for the same reason in all three: a ticker, a chat dock and (mud's case)
+ *  an editor sync all touch the same in-memory store, and any two calls
+ *  overlapping could race the same write.
+ *
+ *  Returns `{ run }`. `run(fn)` chains `fn` onto the queue and returns a
+ *  promise for `fn`'s own settlement — a rejection propagates to THAT
+ *  caller, but never poisons the queue for the jobs queued after it (the
+ *  internal chain swallows the rejection once it has been handed back).
+ *  Self-contained, `.toString()`-splice safe. */
+export function createSerialQueue() {
+  let chain = Promise.resolve();
+  function run(fn) {
+    const settled = chain.then(fn, fn);
+    chain = settled.catch(() => {});
+    return settled;
+  }
+  return { run };
+}

package/src/surfaces/web/adventure-browser-entry.mjs

@@ -18,18 +18,25 @@
 // entry point: `turn(line)` runs the exact same runTurn the CLI and every
 // other viz page's chat dock run, over this session's own memoryDir/graph/
 // lexicon, threading `focus`/`last`/`planState` across calls the same way a
-// real chat session does. `planState` and `autoplayTick`'s own `planHolder`
-// share ONE mutable holder here, so a manual chat command and an auto-play
-// tick can never disagree about whether the adventure is still open, mid a
-// number game, etc. — whichever ran last leaves the holder as the other's
-// starting point. `planHolder.state` starts as adventureTurn's own opened-
+// real chat session does — via turn-session.mjs's shared `createTurnSession`,
+// the wrapper every browser chat dock now hands its own turns through.
+// `planState` and `autoplayTick`'s own `planHolder` share ONE mutable holder
+// here, so a manual chat command and an auto-play tick can never disagree
+// about whether the adventure is still open, mid a number game, etc. —
+// whichever ran last leaves the holder as the other's starting point.
+// `createTurnSession`'s own `buildExtraOptions`/`captureExtraState` seams are
+// what keep the turn session's internal planState and this module's own
+// `planHolder` in sync on every manual turn (see the session factory's own
+// comment below). `planHolder.state` starts as adventureTurn's own opened-
 // world shape, so BOTH entry points treat every call as a live, already-open
 // world rather than a fresh opening line: ordinary in-game commands (look/
 // go/take/open/talk/examine/...) dispatch through adventure.mjs's own
 // adventureTurn exactly as autoplayTick's calls already do, and anything not
 // game-shaped falls through to the ordinary conversational layer, exactly
 // like a real CLI session.
-import { runTurn } from "../../services/chat.mjs";
+import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 import {
   createInMemoryStore, appendFacts, appendRule, loadMemory, readFactRows, removeFacts,
 } from "../../adapters/memory/core.mjs";
@@ -41,6 +48,7 @@ import { parseWorldEditorText, planWorldEditorSync } from "../../services/advent
 import { resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain } from "../../domain/sprite-map.mjs";
 import { resolveSpriteAsset } from "../../domain/sprite-templates.mjs";
 import { relatedForTerm } from "../../domain/skos-view.mjs";
+import { directedGridLayout, roomGraphSvg } from "../../services/viz-room-graph.mjs";
 import { openPersistedStore } from "./idb-persist.mjs";
 
 /** A live in-memory adventure this page's ticker AND chat dock can both
@@ -97,11 +105,31 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
 
   const graph = parseEntities({ individuals: [], objectProperties: [] });
   const lexicon = loadLexicon();
-  let focus = null;
-  let last = null;
+
+  // createTurnSession owns focus/last and the catch fallback; planHolder
+  // stays a SEPARATE object because autoplayTick's own
+  // runAdventureAutoplayTick needs to mutate it directly (see this module's
+  // own header for why the two entry points share one holder).
+  // buildExtraOptions/captureExtraState are the seam that keeps the turn
+  // session's own planState reading from — and writing back to — that same
+  // holder on every manual turn, and captureExtraState is also where
+  // `visitedRoomIds` grows with the player's post-turn room (a no-op add
+  // when the command didn't move anyone) — the manual-play half of the
+  // merged exposure set.
+  const turnSession = createTurnSession({
+    memoryDir, graph, lexicon, sessionId,
+    vocabHint: 'Try a world question ("where is the key"), or teach me: "remember: the moat is a ditch".',
+    buildExtraOptions: () => ({ uiContext: "browser", planState: planHolder.state }),
+    captureExtraState: async (result) => {
+      if ("planState" in result) planHolder.state = result.planState;
+      const here = foldWorldState(worldActionRows(readFactRows(await loadMemory(memoryDir)))).placements.get("player")?.object ?? null;
+      if (here) visitedRoomIds.add(here);
+    },
+  });
 
   return {
     memoryDir,
+    graph,
 
     /** One auto-play tick: infer the goal, execute exactly one move through
      *  adventureTurn (adventure-autoplay.mjs's own contract), thread the
@@ -115,31 +143,15 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
       return result;
     },
 
-    /** One dispatched chat turn — the SAME runTurn the CLI and every other
-     *  viz page's own chat dock run, over this session's own memoryDir. A
-     *  throwing runTurn must never kill the session — the page has no other
-     *  chance to show this turn's answer. Grows `visitedRoomIds` with the
-     *  player's post-turn room (a no-op add when the command didn't move
-     *  anyone) — the manual-play half of the merged exposure set. */
+    /** One dispatched chat turn, through createTurnSession's own shared
+     *  wrapper around the SAME runTurn the CLI and every other viz page's
+     *  chat dock run, over this session's own memoryDir. A throwing runTurn
+     *  must never kill the session — the page has no other chance to show
+     *  this turn's answer; createTurnSession's own catch fallback covers
+     *  that, and its captureExtraState hook above covers everything this
+     *  method used to do by hand. */
     async turn(line) {
-      let result;
-      try {
-        result = await runTurn(line, {
-          config: null, source: null, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, uiContext: "browser",
-          vocabHint: 'Try a world question ("where is the key"), or teach me: "remember: the moat is a ditch".',
-          planState: planHolder.state,
-        });
-      } catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        return { answer: `Something went wrong answering that (${message}). Try rephrasing, or /help.`, end: false, record: null, plan: null };
-      }
-      focus = result.focus;
-      last = result.last;
-      if ("planState" in result) planHolder.state = result.planState;
-      const here = foldWorldState(worldActionRows(readFactRows(await loadMemory(memoryDir)))).placements.get("player")?.object ?? null;
-      if (here) visitedRoomIds.add(here);
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, plan: result.plan ?? null };
+      return turnSession.turn(line);
     },
 
     /** A read-only fold of the current room — no engine advance — for the
@@ -183,18 +195,21 @@ export async function createAdventureSession(worldPayload, { restoredPayload = n
   };
 }
 
-// Re-exported so the page's own rendering script (adventure-viz.mjs) never
-// has to duplicate sprite resolution, the digest reader, the room
-// affordances the chat dock's own pills read from, or (foldWorldState,
-// exposedFacts) the exposure-filtered fold the goal-status panel mirrors —
-// the same posture spider-fly-browser-entry.mjs's own
-// globalThis.tmctSpiderFly re-export takes. `relatedForTerm`/
-// `classAncestorChain` back the edit mode's own cursor-suggestion pills
-// (adventure-viz.mjs's suggestionsForTerm mirrors this same pairing against
-// the global, the same reach-through-the-global pattern captionFor/pillsFor
-// already use for their own adventure.mjs calls).
-globalThis.tmctAdventure = {
-  createAdventureSession, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
-  worldDigestRows, roomAffordances, foldWorldState, exposedFacts,
-  relatedForTerm, classAncestorChain, openPersistedStore,
-};
+// `tmct.page` keeps what the page draws with and the engine has no
+// plain-English form for: sprite resolution, the digest reader, the room
+// affordances the chat pills read from, the exposure-filtered fold the
+// goal-status panel mirrors, the SKOS neighbourhood and is-a chain behind the
+// edit mode's cursor pills, the persisted-store wrapper, and the manor map's
+// own BFS-grid layout and SVG renderer (neither is `.toString()`-splice-safe:
+// roomGraphSvg needs escapeHtml, directedGridLayout its own exit-delta table).
+publishTmctSurface({
+  open: createAdventureSession,
+  ask: graphAsk,
+  plan: enginePlan,
+  page: {
+    resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
+    worldDigestRows, roomAffordances, foldWorldState, exposedFacts,
+    relatedForTerm, classAncestorChain, openPersistedStore,
+    directedGridLayout, roomGraphSvg,
+  },
+});