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

package/src/domain/sprite-templates.mjs

@@ -30,6 +30,33 @@
 //     `bear-facing-left.toml` for mgx:faces = left) — the `[match]` table,
 //     never the name, is what selects it.
 //
+// A variant can require MORE THAN ONE fact at once, written as repeated
+// `[[match]]` tables (the array-of-tables idiom data/templates/
+// grammar-rules.toml's own `[[rule]]` already uses) instead of a single
+// `[match]` one. Every entry must hold for the variant to be selected, so
+// `bear-facing-left-moving.toml` asks for mgx:faces = left AND
+// mgx:pose = moving and draws the left profile mid-stride. The two spellings
+// are one constraint or many, never a different meaning: a lone `[match]`
+// table is exactly a one-entry list, which is why every file authored before
+// the plural spelling existed still resolves byte-for-byte as it did.
+//
+// Where two satisfied variants overlap, the one requiring MORE facts wins —
+// an instance taught both the facing and the pose gets the combined art, and
+// the same instance taught only the facing gets the plain profile, because
+// the combined variant's second constraint no longer holds. Specificity is
+// counted from the constraints, never read off the filename, so adding a
+// file can't silently reorder what an existing instance resolves to.
+//
+// The two kinds compose rather than exclude each other: a VARIANT may also
+// declare its own `[parameters.*]` tables, and once its `[match]` selects
+// it those parameters fill from the instance's OTHER facts (the facing pair
+// files each carry `[face]` + `[parameters.emotion]`, so a bear taught both
+// mgx:faces = left and mgx:feels = happy renders the left profile wearing
+// the happy face). A satisfied `[match]` is the instance naming this art
+// directly, so a variant is never allowed to fall through the way an
+// unfilled parameterized template is — any placeholder no fact filled is
+// dropped instead, which keeps the returned markup complete.
+//
 // A parameterized template's `[parameters.<name>]` table comes in two
 // shapes, picked by which of `placeholder`/`placeholders` it declares:
 //   - single-placeholder (the shape above): one `placeholder` token, and
@@ -59,9 +86,10 @@
 //
 // Specificity order, checked at EACH term of the class's ancestor chain
 // (nearest first, sprite-map.mjs's own classAncestorChain) before moving to
-// the next ancestor: an exact fully-specific variant whose [match] is
-// satisfied > a parameterized template filled with an observed matching
-// value > a plain class template > (repeat at the next ancestor) > the
+// the next ancestor: the satisfied fully-specific variant requiring the most
+// facts (filled from its own [parameters.*] if it declares any) > a
+// parameterized template filled with an observed matching value > a plain
+// class template > (repeat at the next ancestor) > the
 // existing flat spriteRegistry entry for that same term (so a class not yet
 // migrated to its own template keeps resolving exactly as it did before this
 // module existed) > once the chain is exhausted, the same three-step check
@@ -70,14 +98,77 @@
 import { classAncestorChain } from "./sprite-map.mjs";
 import { namespaceSvgIds } from "./svg-instance-ids.mjs";
 
+/** The predicate a variant matches on to pick a facing angle. */
+export const FACING_PROPERTY = "mgx:faces";
+
+/** The predicate a variant matches on to pick a pose. */
+export const POSE_PROPERTY = "mgx:pose";
+
+/** The facing angles a variant's [match] may require of mgx:faces — a
+ *  turntable read as five steps, of which four are named. Centre is the
+ *  ABSENT fact, never a word here: a figure with nothing on record about
+ *  which way it faces already renders its own front-facing art, so spending
+ *  a value on that would give one picture two names and let an instance ask
+ *  for the front view two different ways. */
+export const FACING_VALUES = Object.freeze(["left", "half-left", "half-right", "right"]);
+
+/** The poses a variant's [match] may require of mgx:pose. At rest is the
+ *  ABSENT fact, the same reasoning centre-facing gets above: a figure with no
+ *  pose on record is standing still, and that is what every plain template
+ *  already draws. "moving" is the one intermediate frame between two rests —
+ *  the read a walk cycle needs and the only pose that has to exist before
+ *  movement can be animated at all. */
+export const POSE_VALUES = Object.freeze(["moving"]);
+
 /** Every template in `templates` whose `classes` list names `term`. */
 function templatesForClass(term, templates) {
   return (templates || []).filter((t) => Array.isArray(t?.classes) && t.classes.includes(term));
 }
 
-function matchSatisfied(match, propertyFacts) {
-  if (!match || !match.property || match.value === undefined) return false;
-  return (propertyFacts || []).some((f) => f.predicate === match.property && f.object === match.value);
+/** One template's `[match]`/`[[match]]` tables as a flat list of raw entries,
+ *  whichever of the two spellings it used — the shape every reader wants
+ *  before it decides anything, so no caller re-answers "did I get a table or
+ *  a list of them" for itself. */
+function matchEntries(template) {
+  const match = template?.match;
+  if (!match) return [];
+  return Array.isArray(match) ? match : [match];
+}
+
+/**
+ * Every `{property, value}` fact one template's `[match]` requires, all of
+ * which must hold for the variant to apply. A single `[match]` table yields
+ * one constraint, repeated `[[match]]` tables one each, and a template with
+ * no `[match]` at all yields none. An entry missing either half is dropped
+ * rather than treated as a wildcard — a half-written constraint must never
+ * widen what a variant claims to match (spriteTemplateProblems reports it as
+ * the authoring mistake it is). Pure.
+ */
+export function matchConstraints(template) {
+  return matchEntries(template).filter((c) => c?.property && c.value !== undefined);
+}
+
+function matchSatisfied(constraints, propertyFacts) {
+  if (!constraints.length) return false;
+  return constraints.every((c) => (propertyFacts || []).some((f) => f.predicate === c.property && f.object === c.value));
+}
+
+/** The satisfied `[match]` variant among `candidates` requiring the MOST
+ *  facts, or null when none is satisfied — so a combined facing-and-pose
+ *  variant outranks the facing-only one it shares an angle with, and drops
+ *  back to it the moment the instance stops carrying the pose. A tie keeps
+ *  the earliest candidate, which is the load order the caller handed in. */
+function bestSatisfiedVariant(candidates, propertyFacts) {
+  let best = null;
+  let bestCount = 0;
+  for (const t of candidates) {
+    const constraints = matchConstraints(t);
+    if (constraints.length <= bestCount) continue;
+    if (!matchSatisfied(constraints, propertyFacts)) continue;
+    best = t;
+    bestCount = constraints.length;
+  }
+  return best;
 }
 
 /** Substitute one matched `[parameters.*.values]` entry into `svg`: a plain
@@ -125,15 +216,47 @@ function parameterizedFillAll(template, propertyFacts) {
   return filledCount > 0 ? svg : null;
 }
 
+/** Every placeholder token a template's own `[parameters.*]` tables name,
+ *  across both shapes — the single `placeholder` and every token in a
+ *  `placeholders` table. */
+function declaredPlaceholderTokens(template) {
+  const tokens = [];
+  for (const param of Object.values(template.parameters || {})) {
+    if (param?.placeholder) tokens.push(param.placeholder);
+    for (const token of Object.values(param?.placeholders || {})) tokens.push(token);
+  }
+  return tokens;
+}
+
+/** `svg` with every token `template` declares that no observed fact filled
+ *  dropped outright. Only the [match]-selected path wants this: a satisfied
+ *  [match] means the instance asked for THIS art by name, so the variant
+ *  can't fall through to a less specific template the way an unfilled
+ *  parameterized template does, and dropping the leftover token is what
+ *  keeps the returned markup complete rather than shipping a literal
+ *  "{{FACE}}" into the page. */
+function withUnfilledPlaceholdersDropped(template, svg) {
+  let out = svg;
+  for (const token of declaredPlaceholderTokens(template)) out = out.split(token).join("");
+  return out;
+}
+
 /** Resolve ONE class term (no ancestor walk here — the caller repeats this
  *  at every level of the chain) against the template set, in specificity
  *  order: fully-specific match variant > parameterized template filled with
- *  an observed value > plain class template. Returns the SVG string, or null
- *  when nothing at this level matches. */
+ *  an observed value > plain class template. Among satisfied match variants
+ *  the most demanding one wins (bestSatisfiedVariant). A match variant that
+ *  declares its own `[parameters.*]` is filled from them first, so a facing
+ *  profile also carrying `[face]`/`[parameters.emotion]` renders the mood the
+ *  instance's own mgx:feels fact names. Returns the SVG string, or null when
+ *  nothing at this level matches. */
 function resolveAtTerm(term, propertyFacts, templates) {
   const candidates = templatesForClass(term, templates);
-  const matched = candidates.find((t) => t.match && matchSatisfied(t.match, propertyFacts));
-  if (matched) return matched.svg;
+  const matched = bestSatisfiedVariant(candidates, propertyFacts);
+  if (matched && !matched.parameters) return matched.svg;
+  if (matched) {
+    return withUnfilledPlaceholdersDropped(matched, parameterizedFillAll(matched, propertyFacts) || matched.svg);
+  }
   for (const t of candidates) {
     if (t.match || !t.parameters) continue;
     const filled = parameterizedFillAll(t, propertyFacts);
@@ -187,12 +310,22 @@ export function resolveSpriteAsset(className, factRows, propertyFacts, templates
  *  names a `property` and exactly one of `placeholder`/`placeholders` (every
  *  token named appears in `svg`), its `values` map is non-empty and every
  *  entry matches the shape its own `placeholder`/`placeholders` choice
- *  expects, a `[match]` table names both `property` and `value`, and
+ *  expects, every `[match]`/`[[match]]` entry names both `property` and
+ *  `value`, no two entries demand different values of the SAME property (a
+ *  constraint set no instance can ever satisfy is dead art, not a stricter
+ *  variant), a constraint on one of the two CLOSED axes names a value that
+ *  axis actually has (mgx:faces one of FACING_VALUES, mgx:pose one of
+ *  POSE_VALUES — every other predicate stays open, since a variant may match
+ *  on any fact at all, mgx:hasProperty included), and
  *  `[face]`/`[parameters.emotion]` are always declared TOGETHER — a face
  *  anchor with nothing to select it, or an emotion parameter with nowhere to
  *  position its face fragment, is a real authoring mistake either way
  *  (sprite-expressions.mjs's own header explains why the face fragment
- *  needs the pairing). */
+ *  needs the pairing). Every check reads the tables a template actually
+ *  declares and none of them cares whether a `[match]` sits alongside, so a
+ *  facing variant carrying `[match]` + `[face]` + `[parameters.emotion]` is
+ *  held to exactly the same pairing and placeholder rules as a plain
+ *  `*-with-emotion.toml` file. */
 export function spriteTemplateProblems(template) {
   const problems = [];
   const t = template || {};
@@ -233,8 +366,22 @@ export function spriteTemplateProblems(template) {
       }
     }
   }
-  if (t.match && (!t.match.property || t.match.value === undefined)) {
-    problems.push("match is missing property or value");
+  const entries = matchEntries(t);
+  for (const entry of entries) {
+    if (!entry?.property || entry?.value === undefined) problems.push("match is missing property or value");
+  }
+  const requiredBy = new Map();
+  for (const { property, value } of matchConstraints(t)) {
+    if (requiredBy.has(property) && requiredBy.get(property) !== value) {
+      problems.push(`match requires ${property} to be both "${requiredBy.get(property)}" and "${value}" — no instance can satisfy that`);
+    }
+    requiredBy.set(property, value);
+    if (property === FACING_PROPERTY && !FACING_VALUES.includes(value)) {
+      problems.push(`match requires ${FACING_PROPERTY} "${value}", which is not one of the turntable's angles (${FACING_VALUES.join(", ")}; the centre view is the absent fact)`);
+    }
+    if (property === POSE_PROPERTY && !POSE_VALUES.includes(value)) {
+      problems.push(`match requires ${POSE_PROPERTY} "${value}", which is not one of the known poses (${POSE_VALUES.join(", ")}; at rest is the absent fact)`);
+    }
   }
   if (t.face && !t.parameters?.emotion) {
     problems.push("face is declared without parameters.emotion — a face anchor with nothing to select it is dead data");

package/src/services/adventure-editor.mjs

@@ -14,10 +14,13 @@
 // mgx:acts-toward, mgx:is-objective) — an editor has to show and change
 // exactly the facts a player is never told.
 //
-// No imports: every export here is .toString()-splice-safe, the same
-// discipline adventure-viz.mjs's own render-glue functions hold (see that
-// module's header) — this module's functions get spliced directly into the
-// adventure page's inline script the same way.
+// No imports of its own logic: every export here is .toString()-splice-safe,
+// the same discipline adventure-viz.mjs's own render-glue functions hold (see
+// that module's header) — this module's functions get spliced directly into
+// the adventure page's inline script the same way. The one exception,
+// wordBeforeCursor, re-exports viz-theme.mjs's own shared copy (byte-identical
+// to what used to live here, and to mud-editor.mjs's own copy) rather than
+// keep a third copy of the same regex.
 //
 // Two predicate families get different sync strategies, on purpose:
 //   - PLACEMENT/OPENNESS (mgx:currently-in/located-in/fixed-in/stands-
@@ -357,13 +360,4 @@ export function planWorldEditorSync(rows, state, triples) {
 
 // ---- cursor-driven suggestions ---------------------------------------------
 
-/** The word immediately before `cursorPos` in `text` — a run of letters/
- *  digits/hyphens, the same token shape this vocabulary's own terms use
- *  (kebab-case room names like "drawing-room"). Empty string when the
- *  cursor sits after whitespace/punctuation with no word directly behind
- *  it. Pure. */
-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() : "";
-}
+export { wordBeforeCursor } from "./viz-theme.mjs";

package/src/services/adventure-viz.mjs

@@ -19,7 +19,7 @@
 // already takes with its own precomputed memory payload, just applied to a
 // second kind of build-time data.
 //
-// Eight pure, `.toString()`-splice-safe pieces are exported as real functions
+// Seven 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
@@ -33,27 +33,35 @@
 // ancestor walk, then floor), `roomSceneLayout` (the room split into a wall
 // band and floor stacks, over `roomSceneObjects` and `scenePlacement`),
 // `roomKindForRoom` (a room's border treatment, from its own rdf:type),
-// `carriedItems` (every object placed with the player), `exitDoorways` (the
-// written ways out of one room, in compass order, each marked with whether
-// this session has walked it — what the room view's own door plates are
-// drawn from), and `visitedRoomGraph`
-// (a directions-only layout of the rooms a session has actually visited —
-// see its own header for the exposure discipline). None of these import
-// anything beyond this module's own exports, which is what keeps a raw
-// `.toString()` splice safe. Three further pure helpers are exported for
-// testing but NOT spliced, because each calls another module's export the
-// in-page script instead reaches through the browser bundle's own
-// `tmctAdventure` global (mirroring how the inline script calls
-// `tmctSpiderFly.*` rather than re-importing spider-fly-world.mjs):
-// `roomCaptionText` (calls `worldDigestRows`; the in-page `captionFor`
-// mirrors it against `tmctAdventure.worldDigestRows`), `pillsForRoom` (a thin
-// wrapper over adventure.mjs's own exported `roomAffordances`, whose header
-// explains why its list can never promise an action one of take/open/talk/
-// examine would then refuse; the in-page `pillsFor` mirrors it against
-// `tmctAdventure.roomAffordances`), and `goalStatusLines` (calls
-// `foldWorldState` and adventure-autoplay.mjs's own `exposedFacts`; the
-// in-page `goalStatusLinesFor` mirrors both against the `tmctAdventure`
-// global too).
+// `carriedItems` (every object currently placed with a `holder`, "player" by
+// default), and `exitDoorways` (the written ways out of one room, in compass
+// order, each marked with whether this session has walked it — what the room
+// view's own door plates are drawn from). None of these import anything
+// beyond this module's own exports, which is what keeps a raw `.toString()`
+// splice safe.
+//
+// Four further pure helpers are exported for testing but NOT spliced,
+// because each calls another module's export — the in-page script instead
+// reaches through the browser bundle's own `tmctAdventure` global (mirroring
+// how the inline script calls `tmctSpiderFly.*` rather than re-importing
+// spider-fly-world.mjs): `roomCaptionText` (calls `worldDigestRows`; the
+// in-page `captionFor` mirrors it against `tmctAdventure.worldDigestRows`),
+// `pillsForRoom` (a thin wrapper over adventure.mjs's own exported
+// `roomAffordances`, whose header explains why its list can never promise an
+// action one of take/open/talk/examine would then refuse; the in-page
+// `pillsFor` mirrors it against `tmctAdventure.roomAffordances`),
+// `goalStatusLines` (calls `foldWorldState` and adventure-autoplay.mjs's own
+// `exposedFacts`; the in-page `goalStatusLinesFor` mirrors both against the
+// `tmctAdventure` global too), and `visitedRoomGraph` (a directions-only
+// layout of the rooms a session has actually visited, now a thin wrapper over
+// viz-room-graph.mjs's shared `directedGridLayout` — mud-viz.mjs's own
+// burrowGraph wrote the same BFS-grid layout a second time under its own
+// name, and that shared module is where the layout lives now; see its own
+// header for the algorithm and what `hints`/disconnected components mean).
+// The in-page script never splices `directedGridLayout`/`roomGraphSvg`
+// either, for the same not-self-contained reason: it calls
+// `tmctAdventure.directedGridLayout`/`tmctAdventure.roomGraphSvg` straight
+// through the bundle instead of re-implementing the room map a second time.
 //
 // The chat dock (chatlog/chatform/chatq/pills, below) mirrors
 // spider-fly-viz.mjs's own side panel: every manual exchange (via
@@ -84,13 +92,14 @@
 // an edit implies run through the browser bundle's own `session.applyEdit`
 // (adventure-browser-entry.mjs), never here — this module only renders and
 // reads.
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, scenarioLabel } from "./viz-theme.mjs";
-import { createTicker } from "./viz-ticker.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, scenarioLabel, rowsForWorld, wordBeforeCursor } from "./viz-theme.mjs";
+import { createTicker, createSerialQueue } from "./viz-ticker.mjs";
+import { directedGridLayout } from "./viz-room-graph.mjs";
 import { worldDigestRows, roomAffordances, foldWorldState } from "./adventure.mjs";
 import { exposedFacts } from "./adventure-autoplay.mjs";
 import { relatedForTerm } from "../domain/skos-view.mjs";
 import { classAncestorChain } from "../domain/sprite-map.mjs";
-import { renderWorldEditorText, wordBeforeCursor } from "./adventure-editor.mjs";
+import { renderWorldEditorText } from "./adventure-editor.mjs";
 
 const DEFAULT_TITLE = "tmct — the adventure";
 const PREVIEW_MAX_TICKS = 30;
@@ -336,13 +345,16 @@ export function roomKindForRoom(rows, roomId) {
   return "indoor";
 }
 
-/** Every object currently `mgx:located-in` `actingSubject` (default
- *  "player"), sorted, each with its sprite class — the exact placement
+/** Every object currently `mgx:located-in` `holder` (default "player"),
+ *  sorted, each with its sprite class — the exact placement
  *  `worldDigestRows`'/`inventoryAnswer`'s own "carries the" branch already
- *  reads, just returned as a plain list instead of prose. Pure. */
-export function carriedItems(rows, state, actingSubject = "player") {
+ *  reads, just returned as a plain list instead of prose. `holder` is a real
+ *  parameter, not a name baked into the function — mud-viz.mjs's own
+ *  `carriedItemsFor` used to hardcode "player" instead, so a differently-
+ *  named character's own satchel never read correctly there. Pure. */
+export function carriedItems(rows, state, holder = "player") {
   return [...state.placements]
-    .filter(([, p]) => p.predicate === "mgx:located-in" && p.object === actingSubject)
+    .filter(([, p]) => p.predicate === "mgx:located-in" && p.object === holder)
     .map(([subject]) => ({ subject, spriteClass: spriteClassForObject(rows, subject) }))
     .sort((a, b) => a.subject.localeCompare(b.subject));
 }
@@ -361,47 +373,13 @@ export function carriedItems(rows, state, actingSubject = "player") {
  *  caller can draw at most "there's an exit that way" and nothing more.
  *  Disconnected visited rooms (not reachable from each other by traveled
  *  edges) lay out as separate side-by-side blocks rather than overlapping.
- *  Pure. */
+ *
+ *  A thin wrapper over viz-room-graph.mjs's shared `directedGridLayout`: no
+ *  `root` (Ashcombe Hall is never dug two ways into one cell, so there is no
+ *  level/turf to track) and no collision nudging (a manor fixed at authoring
+ *  time never collides). Pure. */
 export function visitedRoomGraph(state, visitedRoomIds, actingSubject = "player") {
-  const DELTA = { north: [0, -1], south: [0, 1], east: [1, 0], west: [-1, 0], up: [0, -1], down: [0, 1] };
-  const visited = new Set(visitedRoomIds || []);
-  const here = state.placements.get(actingSubject)?.object ?? null;
-  const positions = new Map();
-  const edges = [];
-  const edgeKeys = new Set();
-  const hints = [];
-  let offsetX = 0;
-  for (const start of [...visited].sort()) {
-    if (positions.has(start)) continue;
-    positions.set(start, { x: offsetX, y: 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 (!visited.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)) {
-          const [dx, dy] = DELTA[direction] ?? [0, 0];
-          positions.set(target, { x: pos.x + dx, y: pos.y + dy });
-          component.push(target);
-          queue.push(target);
-        }
-      }
-    }
-    offsetX = Math.max(...component.map((r) => positions.get(r).x)) + 2;
-  }
-  const minX = Math.min(0, ...[...positions.values()].map((p) => p.x));
-  const minY = Math.min(0, ...[...positions.values()].map((p) => p.y));
-  const nodes = [...visited].sort().map((room) => {
-    const p = positions.get(room) || { x: 0, y: 0 };
-    return { id: room, x: p.x - minX, y: p.y - minY, current: room === here };
-  });
-  return { nodes, edges, hints };
+  return directedGridLayout(state, visitedRoomIds, { actingSubject });
 }
 
 /** Every room the world DEFINES at all (every subject the fact rows type as
@@ -528,11 +506,19 @@ export function suggestionsForTerm(rows, term) {
  *  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) {
+ *  so restating "you are here" is redundant, never informative.
+ *
+ *  `{ caseInsensitive }` folds the room-id match to lowercase before
+ *  comparing. Ashcombe Hall's own room ids are already lowercase, so this is
+ *  a no-op here by default — it exists so mud-viz.mjs's own case-insensitive
+ *  `roomCaptionFor` variant can share this one function instead of keeping a
+ *  near-duplicate. */
+export function roomCaptionText(rows, state, here, { caseInsensitive = false } = {}) {
   const hereCased = here.charAt(0).toUpperCase() + here.slice(1);
+  const objectMatches = (value) => (caseInsensitive ? String(value).toLowerCase() === here.toLowerCase() : value === here);
+  const subjectMatches = (value) => (caseInsensitive ? String(value).toLowerCase() === here.toLowerCase() : value === hereCased);
   const lines = worldDigestRows(rows, state)
-    .filter((row) => row.subject !== "Player" && (row.object === here || row.subject === hereCased))
+    .filter((row) => row.subject !== "Player" && (objectMatches(row.object) || subjectMatches(row.subject)))
     .map((row) => `${row.subject} ${row.predicate} ${row.object}.`);
   return lines.length ? lines.join(" ") : `Nothing more about the ${here} is written down yet.`;
 }
@@ -886,7 +872,7 @@ ${THEME_TOKENS_CSS}
      this just keeps the board's own footprint stable and click-to-enlarge
      honest about what it's enlarging. */
   .map-viewport-fixed { width: 190px; margin: 0 auto; cursor: zoom-in; }
-  /* the lights-down map lightbox — the same board, the same roomMapSvg
+  /* the lights-down map lightbox — the same board, the same room-graph svg
      output, just drawn bigger over a dimmed backdrop. Closes on a click
      anywhere outside the enlarged board, or Escape. */
   .map-lightbox { position: fixed; inset: 0; z-index: 60; display: flex; align-items: center; justify-content: center; padding: 2.4rem; background: rgba(10, 8, 4, .74); }
@@ -1123,6 +1109,7 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
 (function () {
   "use strict";
   const createTicker = ${createTicker.toString()};
+  const createSerialQueue = ${createSerialQueue.toString()};
   const spriteClassForObject = ${spriteClassForObject.toString()};
   const visibleRoomOf = ${visibleRoomOf.toString()};
   const roomSceneObjects = ${roomSceneObjects.toString()};
@@ -1130,7 +1117,6 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   const roomSceneLayout = ${roomSceneLayout.toString()};
   const roomKindForRoom = ${roomKindForRoom.toString()};
   const carriedItems = ${carriedItems.toString()};
-  const visitedRoomGraph = ${visitedRoomGraph.toString()};
   const allRoomIds = ${allRoomIds.toString()};
   const groundedPlaceholder = ${groundedPlaceholder.toString()};
   const exitDoorways = ${exitDoorways.toString()};
@@ -1138,6 +1124,7 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   const factsForSubject = ${factsForSubject.toString()};
   const renderWorldEditorText = ${renderWorldEditorText.toString()};
   const wordBeforeCursor = ${wordBeforeCursor.toString()};
+  const rowsForWorld = ${rowsForWorld.toString()};
   const esc = ${escapeHtml.toString()};
   // The identity Ashcombe Hall's own world facts place as the carrier/viewer
   // — one named constant standing in for what was six separate "player"
@@ -1258,13 +1245,10 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
 
   // ---- serialize every engine-touching call: the ticker, the chat dock and
   // the editor sync all share one in-memory store, and any overlapping pair
-  // could race against the same write.
-  let lock = Promise.resolve();
-  function withLock(fn) {
-    const run = lock.then(fn, fn);
-    lock = run.catch(() => {});
-    return run;
-  }
+  // could race against the same write. createSerialQueue is the shared
+  // primitive mud-viz.mjs's own tickChain/serializeTick and spider-fly-viz.mjs's
+  // own inlined withLock each duplicated under a different name.
+  const { run: withLock } = createSerialQueue();
 
   // ---- large-sprite-tier wiring — the gradient-shaded 400px tier
   // (data/sprites-large/*.toml) arrives embedded at build time as
@@ -1349,53 +1333,39 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   }
 
   // ---- room map — ONE svg-building routine shared by play mode's visited-
-  // only map and edit mode's whole-map (visitedRoomGraph fed allRoomIds
+  // only map and edit mode's whole-map (visitedRoomGraphFor fed allRoomIds
   // instead of the exposure set — a parameter, not a second layout), so the
   // fixed-size-viewport CSS treatment and the node layout can never drift
   // between the two. clickable adds a data-room attribute and a pointer
   // cursor per node; play mode's own map stays purely informational.
-  function roomMapSvg(graph, clickable) {
-    if (!graph.nodes.length) return null;
-    // Board-game footprints: each room a named rectangle (the name INSIDE
-    // it, the way a Cluedo board prints its rooms), corridors as wide paths
-    // between the footprints, direction-only hints as path stubs fading
-    // toward rooms not yet visited.
-    const cell = 64, roomW = 56, roomH = 26;
-    const maxX = Math.max.apply(null, graph.nodes.map((n) => n.x));
-    const maxY = Math.max.apply(null, graph.nodes.map((n) => n.y));
-    const w = (maxX + 1) * cell, h = (maxY + 1) * cell;
-    const cx = (n) => (n.x + 0.5) * cell;
-    const cy = (n) => (n.y + 0.5) * cell;
-    const byRoom = new Map(graph.nodes.map((n) => [n.id, n]));
-    const edgesSvg = graph.edges.map((e) => {
-      const a = byRoom.get(e.from), b = byRoom.get(e.to);
-      return '<line class="room-edge" x1="' + cx(a) + '" y1="' + cy(a) + '" x2="' + cx(b) + '" y2="' + cy(b) + '"></line>';
-    }).join("");
-    const HINT_DELTA = { north: [0, -1], south: [0, 1], east: [1, 0], west: [-1, 0], up: [0, -1], down: [0, 1] };
-    const hintsSvg = graph.hints.map((hi) => {
-      const from = byRoom.get(hi.from);
-      const d = HINT_DELTA[hi.direction] || [0, 0];
-      return '<circle class="room-hint" cx="' + (cx(from) + d[0] * cell * 0.42) + '" cy="' + (cy(from) + d[1] * cell * 0.42) + '" r="3.5"></circle>';
-    }).join("");
-    const nodesSvg = graph.nodes.map((n) => {
-      const cls = "room-node" + (n.current ? " current" : "") + (clickable ? " clickable" : "") + (clickable && n.id === selectedRoomId ? " selected" : "");
-      const attr = clickable ? ' data-room="' + esc(n.id) + '"' : "";
-      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) + '">' + esc(n.id) + "</text></g>";
-    }).join("");
-    return '<svg viewBox="0 0 ' + w + " " + h + '" preserveAspectRatio="xMidYMid meet" role="img" aria-label="' + (clickable ? "the whole manor \\u2014 click a room to inspect it" : "the rooms visited so far") + '">'
-      + edgesSvg + hintsSvg + nodesSvg + "</svg>";
+  // roomGraphSvgFor mirrors the OLD inline roomMapSvg's own board-game sizing
+  // (a 64px square cell, 56x26px room footprints) through the shared
+  // viz-room-graph.mjs renderer, reached via the tmctAdventure global the
+  // same way captionFor/pillsFor already reach their own adventure.mjs
+  // calls: roomGraphSvg needs escapeHtml and a module-level exit-delta table
+  // this splice-safe script carries neither of, so it runs through the
+  // bundle rather than being spliced as text (see this page's own module
+  // header). visitedRoomGraphFor is the same posture for the layout half.
+  function roomGraphSvgFor(graph, clickable) {
+    return tmctAdventure.roomGraphSvg(graph, {
+      cellX: 64, cellY: 64, roomW: 56, roomH: 26,
+      clickable, selectedRoomId,
+      label: clickable ? "the whole manor \\u2014 click a room to inspect it" : "the rooms visited so far",
+    });
+  }
+  function visitedRoomGraphFor(state, visitedIds) {
+    return tmctAdventure.directedGridLayout(state, visitedIds, { actingSubject: ACTING_SUBJECT });
   }
   function renderRoomMap(rows, state, visitedRoomIds) {
-    mapWrapEl.innerHTML = roomMapSvg(visitedRoomGraph(state, visitedRoomIds, ACTING_SUBJECT), false) || '<span class="empty-note">nowhere yet</span>';
+    mapWrapEl.innerHTML = roomGraphSvgFor(visitedRoomGraphFor(state, visitedRoomIds), false) || '<span class="empty-note">nowhere yet</span>';
   }
 
   // ---- the map lightbox — clicking the fixed-square play-mode map redraws
-  // the SAME roomMapSvg output larger, over a dimmed backdrop; clicking the
-  // backdrop (not the board itself) or pressing Escape closes it.
+  // the SAME roomGraphSvgFor output larger, over a dimmed backdrop; clicking
+  // the backdrop (not the board itself) or pressing Escape closes it.
   function openMapLightbox() {
     if (!lastSnapshot) return;
-    const svg = roomMapSvg(visitedRoomGraph(lastSnapshot.state, lastSnapshot.visitedRoomIds, ACTING_SUBJECT), false);
+    const svg = roomGraphSvgFor(visitedRoomGraphFor(lastSnapshot.state, lastSnapshot.visitedRoomIds), false);
     if (!svg) return;
     mapLightboxInnerEl.innerHTML = svg;
     mapLightboxEl.hidden = false;
@@ -1503,7 +1473,7 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   document.addEventListener("keydown", (e) => { if (e.key === "Escape" && !objLightboxEl.hidden) closeObjectLightbox(); });
 
   function renderEditMap(rows, state) {
-    editMapWrapEl.innerHTML = roomMapSvg(visitedRoomGraph(state, allRoomIds(rows), ACTING_SUBJECT), true) || '<span class="empty-note">this world defines no rooms</span>';
+    editMapWrapEl.innerHTML = roomGraphSvgFor(visitedRoomGraphFor(state, allRoomIds(rows)), true) || '<span class="empty-note">this world defines no rooms</span>';
   }
   editMapWrapEl.addEventListener("click", (e) => {
     const g = e.target.closest("[data-room]");
@@ -1701,8 +1671,7 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   // diff + write; this page only ever reads its result back.
 
   function worldOnlyRows(rows) {
-    const prefix = "world:" + world().name;
-    return (rows || []).filter((r) => typeof r.provenance === "string" && r.provenance.indexOf(prefix) === 0);
+    return rowsForWorld(rows, world().name);
   }
 
   function renderRoomDetail() {