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

package/src/services/ledger-viz.mjs

@@ -15,8 +15,10 @@
 // doesn't do: it reads the checked-in chat-dock engine bundle.
 
 import { loadMemory, readFactRows, findContradictions, normFactTerm } from "../adapters/memory/core.mjs";
-import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, embedJson } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, embedJson, countLabel, TOKENS } from "./viz-theme.mjs";
 import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
+import { bfsLevels } from "../domain/planning.mjs";
+import { pluralOf } from "../domain/inflect.mjs";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -33,23 +35,33 @@ const DASH_SANS_STACK = `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
 // themes — a deliberate departure from THEME_TOKENS_CSS's light/dark switch,
 // which every other generated page still follows. --taught/--corpus/--entail/
 // --alert stay the shared semantic provenance tokens; here they're pinned to
-// their dark-theme-friendly values (viz-theme.mjs's own dark token table) so
-// the palette that ships in dark mode elsewhere is what this page always
-// shows. viz-theme.mjs exports only the assembled THEME_TOKENS_CSS string,
-// not its per-mode token table, so the dark set is restated here from that
-// table rather than recomputed.
-const DASH_DARK_CHROME_CSS = `
+// their dark-theme-friendly values, read straight off viz-theme.mjs's own
+// exported TOKENS.dark table so this page's palette can never drift from the
+// one every other generated page's dark mode uses. The tier alphas (.35/.65/1)
+// match TOKENS's own tier scale; the four "soft" tints use higher alphas than
+// THEME_TOKENS_CSS's shared soft tokens on purpose — this dashboard chrome
+// wants a more visible tint against its always-dark background than the
+// light/dark-switching pages need, so those four alphas stay page-specific.
+function hexRgb(hex) {
+  const n = parseInt(hex.slice(1), 16);
+  return `${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}`;
+}
+const DASH_DARK_CHROME_CSS = (() => {
+  const t = TOKENS.dark;
+  const [taught, corpus, entail] = [hexRgb(t.taught), hexRgb(t.corpus), hexRgb(t.entail)];
+  return `
   :root { color-scheme: dark; }
   body {
-    --bg: #15181C; --ink: #E7E5DF; --muted: #9A9E95; --line: #2B3036; --card: #1C2126;
-    --taught: #5FBE8B; --corpus: #6C93BF; --entail: #D9A554; --alert: #D08070;
-    --taught-t1: rgba(95,190,139,.35); --taught-t2: rgba(95,190,139,.65); --taught-t3: rgba(95,190,139,1);
-    --corpus-t1: rgba(108,147,191,.35); --corpus-t2: rgba(108,147,191,.65); --corpus-t3: rgba(108,147,191,1);
-    --entail-t1: rgba(217,165,84,.35); --entail-t2: rgba(217,165,84,.65); --entail-t3: rgba(217,165,84,1);
-    --taught-soft: rgba(95,190,139,.14); --corpus-soft: rgba(108,147,191,.14);
-    --entail-soft: rgba(217,165,84,.16); --alert-soft: rgba(208,128,112,.16);
+    --bg: ${t.bg}; --ink: ${t.ink}; --muted: ${t.muted}; --line: ${t.line}; --card: ${t.card};
+    --taught: ${t.taught}; --corpus: ${t.corpus}; --entail: ${t.entail}; --alert: ${t.alert};
+    --taught-t1: rgba(${taught},.35); --taught-t2: rgba(${taught},.65); --taught-t3: rgba(${taught},1);
+    --corpus-t1: rgba(${corpus},.35); --corpus-t2: rgba(${corpus},.65); --corpus-t3: rgba(${corpus},1);
+    --entail-t1: rgba(${entail},.35); --entail-t2: rgba(${entail},.65); --entail-t3: rgba(${entail},1);
+    --taught-soft: rgba(${taught},.14); --corpus-soft: rgba(${corpus},.14);
+    --entail-soft: rgba(${entail},.16); --alert-soft: rgba(${hexRgb(t.alert)},.16);
   }
 `;
+})();
 
 /** Read the checked-in browser memory-ask-engine bundle
  *  (`src/surfaces/web/memory-ask-browser.bundle.js`) — the real memory-graph answer engine
@@ -453,7 +465,7 @@ function dashboardHtml(stats, { fresh = false } = {}) {
       <div class="tile">
         <span class="tile-label">facts.total</span>
         <span class="tile-value">${total}</span>
-        <span class="tile-sub">${terms} term${terms === 1 ? "" : "s"} tracked</span>
+        <span class="tile-sub">${countLabel(terms, "term")} tracked</span>
       </div>
       <div class="tile tile-tier">
         <span class="tile-label">facts.by-tier</span>
@@ -467,7 +479,7 @@ function dashboardHtml(stats, { fresh = false } = {}) {
       <div class="tile${qualityCls}">
         <span class="tile-label">data.quality</span>
         <span class="tile-value">${s.contradictionCount || 0}</span>
-        <span class="tile-sub">term${s.contradictionCount === 1 ? "" : "s"} with more than one answer</span>
+        <span class="tile-sub">${s.contradictionCount === 1 ? "term" : pluralOf("term")} with more than one answer</span>
       </div>
     </div>
     <div class="barpanels">
@@ -537,7 +549,7 @@ function sparkCaptionHtml(stats) {
  *  self-contained document with no external requests. Only
  *  scripts/build-demo-site.mjs, which builds the sibling bundle itself
  *  first, passes `true`. The dock's own runtime code below ALSO gates on
- *  `typeof tmctLedger !== "undefined"` regardless — the two checks answer
+ *  `typeof tmct !== "undefined"` regardless — the two checks answer
  *  different questions (did this render even offer the reference; did the
  *  browser actually manage to load it), and both must hold for the live
  *  path to run. */
@@ -545,14 +557,14 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
   const ledgerJson = embedJson({ rows: rows || [], terms: terms || [], edges: edges || [], focus: focus || null, contradictions: contradictions || [], worthALook: worthALook || null, meta: meta || { shown: 0, total: 0, truncated: false }, focusDigest: focusDigest || null, digestStructures: Array.isArray(digestStructures) ? digestStructures : [] });
   const payloadJson = embedJson(payload || { individuals: [], objectProperties: [] });
   const shown = meta?.shown ?? (rows || []).length;
-  const title = `tmct ledger — ${shown} fact${shown === 1 ? "" : "s"}${focus ? ` (focus: ${escapeHtml(focus)})` : ""}`;
+  const title = `tmct ledger — ${countLabel(shown, "fact")}${focus ? ` (focus: ${escapeHtml(focus)})` : ""}`;
   const bundleStr = typeof memoryAskBundle === "string" ? memoryAskBundle : "";
   const hasMemChat = bundleStr.length > 0;
   // The placeholder is honest: the canonical exchange only when its terms are
   // really in this payload, otherwise a real term from this graph. Left as
   // the query-only wording even when the live bundle is offered — the dock's
   // own script swaps it for a teach-aware placeholder the moment it confirms
-  // tmctLedger actually loaded (never claimed ahead of that confirmation).
+  // the live engine actually loaded (never claimed ahead of that confirmation).
   // The example term skips anything under 3 characters — the SAME floor the
   // dock's own miss-tips apply below — so a graph whose highest-degree term
   // is a short stopword-shaped fragment (init:large corpora carry plenty:
@@ -563,7 +575,7 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
     ? "who is the grandfather of ishmael"
     : (exampleTerm ? `ask the graph… e.g. what is ${exampleTerm.term}` : "ask the graph…");
   // The paste-and-drop ingest panel plus the JSONL export ride the LIVE
-  // engine (window.tmctLedger): both teach into and read the dock's own
+  // engine (window.tmct): both teach into and read the dock's own
   // session store, so they appear only where that bundle is offered — the
   // demo site, never the CLI's self-contained tmct viz page.
   const ingestHtml = ledgerBundleAvailable
@@ -833,6 +845,11 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
   // escapeHtml/pct by their real names) resolve without a second copy.
   const escapeHtml = esc;
   const pct = ${pct.toString()};
+  // pluralOf underlies countLabel's own default-parameter lookup — spliced
+  // ahead of it so that lookup resolves the same way it does node-side.
+  const pluralOf = ${pluralOf.toString()};
+  const countLabel = ${countLabel.toString()};
+  const bfsLevels = ${bfsLevels.toString()};
   const tierTileHtml = ${tierTileHtml.toString()};
   const microbarsHtml = ${microbarsHtml.toString()};
   const dashboardHtml = ${dashboardHtml.toString()};
@@ -871,14 +888,13 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
   // exists it points at that session's store, which teach/research grow in
   // place, so a digest of a just-taught term reads the fresh facts.
   let getLivePayload = () => PAYLOAD;
-  // Whichever loaded bundle carries the browser digest helper — the demo
-  // ledger's own live engine (tmctLedger) or the committed memory-ask engine
-  // the CLI viz page inlines (tmctMemoryAsk). Null before either loads, and the
-  // focus card then keeps whatever server-computed digest it shipped.
+  // The browser digest helper, from whichever engine this page loaded — the
+  // demo ledger's live one or the committed query-only one the CLI viz page
+  // inlines. Both publish it in the same place now, so there is one lookup
+  // rather than two. Null before either loads, and the focus card then keeps
+  // whatever server-computed digest it shipped.
   const digestHelper = () =>
-    (typeof tmctLedger !== "undefined" && tmctLedger && tmctLedger.digestTermFromPayloadBrowser)
-    || (typeof tmctMemoryAsk !== "undefined" && tmctMemoryAsk && tmctMemoryAsk.digestTermFromPayloadBrowser)
-    || null;
+    (typeof tmct !== "undefined" && tmct.page && tmct.page.digestTermFromPayloadBrowser) || null;
   // The digest for one term, computed live in the browser from the embedded
   // structure table, or null when no structures were embedded, no engine has
   // loaded, or the term holds nothing to compose.
@@ -965,7 +981,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
       : "";
     let html = '<div class="focuscard"><div class="term">' + esc(focus) + "</div>" +
       '<div class="klass">' + (klass ? esc(klass.phrase + " " + klass.o) : "no class recorded") + "</div>" +
-      '<div class="stats">' + all.length + " facts &middot; " + srcs.size + " source" + (srcs.size === 1 ? "" : "s") +
+      '<div class="stats">' + countLabel(all.length, "fact") + " &middot; " + countLabel(srcs.size, "source") +
       (dates.length ? " &middot; first " + esc(dates[0].slice(0, 10)) + " &middot; last " + esc(dates[dates.length - 1].slice(0, 10)) : "") + "</div>" + digestHtml + "</div>";
     const bracketed = new Set();
     for (const fam of FAMS) {
@@ -1028,13 +1044,16 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
     if (!focus) return;
     const color = { taught: cssVar("--taught"), corpus: cssVar("--corpus"), entailed: cssVar("--entail"), entail: cssVar("--entail") };
     const lineC = cssVar("--line"), inkC = cssVar("--ink");
-    const hop1 = new Set(), hop2 = new Set();
-    for (const e of LEDGER.edges) { if (e.s === focus) hop1.add(e.o); if (e.o === focus) hop1.add(e.s); }
-    hop1.delete(focus);
-    for (const e of LEDGER.edges) {
-      if (hop1.has(e.s) && e.o !== focus && !hop1.has(e.o)) hop2.add(e.o);
-      if (hop1.has(e.o) && e.s !== focus && !hop1.has(e.s)) hop2.add(e.s);
-    }
+    const neighborsOf = (term) => {
+      const out = [];
+      for (const e of LEDGER.edges) {
+        if (e.s === term) out.push(e.o);
+        else if (e.o === term) out.push(e.s);
+      }
+      return out;
+    };
+    const [hop1Level, hop2Level] = bfsLevels(focus, neighborsOf, { maxDepth: 2 });
+    const hop1 = new Set(hop1Level || []), hop2 = new Set(hop2Level || []);
     const cx = w / 2, cy = h / 2, r1 = 42, r2 = 68;
     const pos = { [focus]: { x: cx, y: cy } };
     const place = (set, r) => { const a = [...set].sort(); a.forEach((t, i) => { const ang = (2 * Math.PI * i) / a.length - Math.PI / 2; pos[t] = { x: cx + r * Math.cos(ang), y: cy + r * Math.sin(ang) }; }); };
@@ -1118,9 +1137,9 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
   }
 
   // ---- the chat dock: LIVE teach+ask over the sibling ledger-browser.bundle.js
-  // (window.tmctLedger) when the demo build offered it AND it actually
-  // loaded; falls back to the read-only tmctMemoryAsk engine below —
-  // unchanged from before this page could teach at all — otherwise.
+  // (window.tmct) when the demo build offered it AND it actually
+  // loaded; falls back to the read-only engine below, which publishes the
+  // same surface as a stand-in and says so through tmct.fallback.
   // bin/tmct.mjs's own \`tmct viz\` output never offers the live bundle
   // (renderLedgerHtml's own ledgerBundleAvailable defaults false there), so
   // this branch is simply never reachable on a CLI-generated page.
@@ -1128,7 +1147,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
   const createTicker = ${createTicker.toString()};
   const prefersReducedMotion = ${prefersReducedMotion.toString()};
   const chatForm = el("chatform");
-  if (chatForm && typeof tmctLedger !== "undefined" && typeof tmctLedger.createLedgerSession === "function") {
+  if (chatForm && typeof tmct !== "undefined" && !tmct.fallback) {
     const log = el("chatlog");
     const chatqEl = el("chatq");
     chatqEl.placeholder = 'ask or teach the graph\\u2026 e.g. "blue is a peg"';
@@ -1163,7 +1182,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
             import("./vendor/wink.js"),
             winkTimeout(WINK_LOAD_TIMEOUT_MS, "wink vendor asset load timed out"),
           ]);
-          tmctLedger.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
+          tmct.page.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
         } catch (err) {
           // eslint-disable-next-line no-console
           console.warn("tmct ledger: the wink vendor asset failed to load, continuing without the lemma/POS tier", err);
@@ -1176,7 +1195,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
     async function ensureSession() {
       if (session) return session;
       await tryLoadWink();
-      session = await tmctLedger.createLedgerSession({ seedPayload: PAYLOAD });
+      session = await tmct.open({ seedPayload: PAYLOAD });
       // From here the live store is the source of truth for the digest, so a
       // digest of a term taught this session reads its fresh facts — the store
       // grows in place, so this one closure stays current.
@@ -1194,15 +1213,15 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
       chatqEl.disabled = true;
       withLock(async () => {
         try {
-          const s = await ensureSession();
-          const result = await s.turn(q);
+          const live = await ensureSession();
+          const result = await tmct.turn(q);
           const record = result.record;
           const taught = !!record && record.miss === false && (record.via === "assert" || record.via === "retract");
           const body = esc(result.answer).replace(/\\n/g, "<br>");
           pending.className = "a" + (taught ? " taught" : (record && record.miss ? " miss" : ""));
           pending.innerHTML = taught ? '<span class="tag">taught</span>' + body : body;
           if (taught) {
-            const fresh = tmctLedger.computeLedgerDataFromPayload(s.memoryDir.payload, {});
+            const fresh = tmct.page.computeLedgerDataFromPayload(live.memoryDir.payload, {});
             applyLedgerData(fresh);
           } else if (!(record && record.miss)) {
             // Only a genuine answer (never a miss) tries to resolve a
@@ -1211,7 +1230,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
             // ordinary English word (e.g. "run", if the graph happens to
             // hold it), and resolveAnsweredTerm has no way to tell that
             // apart from the term genuinely being discussed.
-            const hit = resolveAnsweredTerm(result.answer, q, LEDGER.terms, tmctLedger.normFactTerm);
+            const hit = resolveAnsweredTerm(result.answer, q, LEDGER.terms, tmct.page.normFactTerm);
             if (hit) refocusWithLabel(hit, q);
           }
         } catch {
@@ -1226,7 +1245,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
 
     // ---- ingest + export: bring your own text, take the graph away ---------
     // The ingest panel runs pasted/dropped/browsed text through the SAME dock
-    // session, one sentence at a time (tmctLedger.splitSentences, then
+    // session, one sentence at a time (tmct.page.splitSentences, then
     // s.turn), keeping only the sentences the recognizer grounds — then
     // re-derives the whole ledger so the new facts can be examined in place.
     // Export serializes that same session store to canonical JSONL.
@@ -1262,16 +1281,16 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
         withLock(async () => {
           try {
             const s = await ensureSession();
-            const sentences = tmctLedger.splitSentences(text);
+            const sentences = tmct.page.splitSentences(text);
             let grounded = 0;
             for (const sentence of sentences) {
-              const r = await s.turn(sentence);
+              const r = await tmct.turn(sentence);
               if (r.record && r.record.miss === false && r.record.via === "assert") grounded += 1;
             }
-            const fresh = tmctLedger.computeLedgerDataFromPayload(s.memoryDir.payload, {});
+            const fresh = tmct.page.computeLedgerDataFromPayload(s.memoryDir.payload, {});
             applyLedgerData(fresh);
             const skipped = sentences.length - grounded;
-            statusEl.textContent = sentences.length + " sentence" + (sentences.length === 1 ? "" : "s")
+            statusEl.textContent = countLabel(sentences.length, "sentence")
               + ", " + grounded + " added" + (skipped ? ", " + skipped + " skipped" : "");
           } catch {
             statusEl.textContent = "something went wrong ingesting that";
@@ -1288,7 +1307,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
         withLock(async () => {
           try {
             const s = await ensureSession();
-            const jsonl = await tmctLedger.exportFactsJsonl(s.memoryDir);
+            const jsonl = await tmct.page.exportFactsJsonl(s.memoryDir);
             const blob = new Blob([jsonl], { type: "application/x-ndjson" });
             const url = URL.createObjectURL(blob);
             const link = document.createElement("a");
@@ -1323,7 +1342,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
         researchPlayBtn.setAttribute("aria-pressed", String(st.playing));
         researchStatusEl.textContent = !researchQueue ? ""
           : researchQueue.complete
-            ? 'research "' + researchQueue.topic + '" complete \\u2014 ' + researchQueue.done.length + " topic" + (researchQueue.done.length === 1 ? "" : "s")
+            ? 'research "' + researchQueue.topic + '" complete \\u2014 ' + countLabel(researchQueue.done.length, "topic")
             : researchQueue.done.length + " done \\u00b7 " + researchQueue.pending.length + " queued";
       }
 
@@ -1334,8 +1353,8 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
         const pending = addLine("a pending", "researching\\u2026");
         return withLock(async () => {
           try {
-            const s = await ensureSession();
-            const result = await s.turn(q);
+            const live = await ensureSession();
+            const result = await tmct.turn(q);
             const missed = !result.record || Boolean(result.record.miss);
             pending.className = "a" + (missed ? " miss" : "");
             pending.innerHTML = esc(result.answer).replace(/\\n/g, "<br>");
@@ -1343,7 +1362,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
               researchQueue = result.research;
               renderResearchControls();
               if (!missed) {
-                const fresh = tmctLedger.computeLedgerDataFromPayload(s.memoryDir.payload, {});
+                const fresh = tmct.page.computeLedgerDataFromPayload(live.memoryDir.payload, {});
                 applyLedgerData(fresh);
               }
             }
@@ -1386,9 +1405,11 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
         else researchTicker.play();
       });
     }
-  } else if (chatForm && typeof tmctMemoryAsk !== "undefined") {
-    const memHandle = tmctMemoryAsk.createInMemoryStore();
-    memHandle.payload = PAYLOAD;
+  } else if (chatForm && typeof tmct !== "undefined") {
+    // The query-only dock. One session over the page's own embedded payload,
+    // and every line goes to tmct.ask — the cascade that used to be chained
+    // here by hand now lives behind that one call.
+    const opened = tmct.open({ payload: PAYLOAD });
     const log = el("chatlog");
     const addLine = (cls, html) => {
       const d = document.createElement("div");
@@ -1403,20 +1424,16 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
       input.value = "";
       addLine("u", esc(q));
       (async () => {
-        let fact = null;
-        try { fact = await tmctMemoryAsk.factAnswer(memHandle, q, null, true, {}); } catch { fact = null; }
-        // runAsk's own cascade is factAnswer ?? factReadBack; chain the same
-        // way when the bundle exposes the second reader (relation chases —
-        // "who is the grandfather of ishmael" — live there, not in factAnswer).
-        if (!(fact && fact.text) && typeof tmctMemoryAsk.factReadBack === "function") {
-          try { fact = await tmctMemoryAsk.factReadBack(memHandle, q, null, true, null); } catch { fact = null; }
-        }
-        if (fact && fact.text) {
-          addLine("a", esc(fact.text).replace(/\\n/g, "<br>"));
+        await opened;
+        let answer = null;
+        let data = null;
+        try { ({ answer, data } = await tmct.ask(q)); } catch { answer = null; data = null; }
+        if (answer) {
+          addLine("a", esc(answer).replace(/\\n/g, "<br>"));
           // Same formatting contract as chat's withGoalLine: capitalized,
           // full-stop-terminated, rendered only when the engine deduced one.
-          if (fact.goal) addLine("a goal", "Goal (inferred): " + esc(fact.goal.charAt(0).toUpperCase() + fact.goal.slice(1)) + ".");
-          const hit = resolveAnsweredTerm(fact.text, q, LEDGER.terms, tmctMemoryAsk.normFactTerm);
+          if (data && data.goal) addLine("a goal", "Goal (inferred): " + esc(data.goal.charAt(0).toUpperCase() + data.goal.slice(1)) + ".");
+          const hit = resolveAnsweredTerm(answer, q, LEDGER.terms, tmct.page.normFactTerm);
           if (hit) refocusWithLabel(hit, q);
         } else {
           const tips = LEDGER.terms.filter((t) => t.term.length >= 3).slice(0, 2)

package/src/services/memory-panel-viz.mjs

@@ -181,3 +181,41 @@ export function renderStatsPanelInto(panelEl, stats, opts) {
     }
   }
 }
+
+/** The boot statusline while the big engine assets stream in — byte-identical
+ *  across research-viz.mjs and ingest-viz.mjs, each commenting that it uses
+ *  "the same aggregator" as the other. `parts` is an array of { loaded, total }
+ *  byte counts (total 0 when a response carried no Content-Length); with no
+ *  usable total the line shows loaded bytes alone rather than inventing a
+ *  denominator. Self-contained, `.toString()`-splice safe. */
+export function loadProgressLine(parts) {
+  const mb = (n) => (n / 1048576).toFixed(1);
+  let loaded = 0;
+  let total = 0;
+  let totalKnown = true;
+  for (const p of parts || []) {
+    loaded += (p && p.loaded) || 0;
+    if (p && p.total > 0) total += p.total;
+    else totalKnown = false;
+  }
+  return totalKnown && total > 0
+    ? "loading the engine… " + mb(loaded) + " MB / " + mb(total) + " MB"
+    : "loading the engine… " + mb(loaded) + " MB";
+}
+
+/** One learned/grounded fact as its three canonical cells, plus whichever of
+ *  the two per-page provenance fields the caller's fact objects carry: `source`
+ *  (research.html's source key, e.g. "taught"/"seed:conceptnet" — used for the
+ *  tone dot) and `provenance` (ingest.html's raw ' | '-joined tag string —
+ *  shown verbatim). Both default to "" when the fact object doesn't carry
+ *  that field, so either page reads back only the one it populated. Pure,
+ *  `.toString()`-splice safe. */
+export function factTripleParts(fact) {
+  return {
+    subject: String((fact && fact.subject) || ""),
+    predicate: String((fact && fact.predicate) || ""),
+    object: String((fact && fact.object) || ""),
+    source: String((fact && fact.source) || ""),
+    provenance: String((fact && fact.provenance) || ""),
+  };
+}

package/src/services/mud-editor.mjs

@@ -12,11 +12,14 @@
 // point is "change what this world is made of" has to speak the vocabulary the
 // world is actually written in, and neither table is a superset of the other.
 //
-// No imports: every export here is `.toString()`-splice-safe, the same discipline
-// adventure-editor.mjs and the *-viz render-glue functions hold — mud-viz.mjs
-// splices these straight into mud.html's inline script, which captures a
-// function's own source text and nothing it closes over. A splice-safe function
-// carries its whole dependency graph inside its own body.
+// Every export here but wordBeforeCursor is written locally, and is
+// `.toString()`-splice-safe, the same discipline adventure-editor.mjs and the
+// *-viz render-glue functions hold — mud-viz.mjs splices these straight into
+// mud.html's inline script, which captures a function's own source text and
+// nothing it closes over. A splice-safe function carries its whole dependency
+// graph inside its own body. wordBeforeCursor is a re-export of viz-theme.mjs's
+// shared implementation, itself self-contained and splice-safe the same way —
+// this module no longer keeps its own copy of it.
 //
 // Two predicate families sync differently, for the reason adventure-editor.mjs's
 // own header sets out:
@@ -34,6 +37,8 @@
 //     that fails to parse this keystroke must never be read as "this fact is
 //     gone".
 
+export { wordBeforeCursor } from "./viz-theme.mjs";
+
 const PLACEMENT_KIND = "placement";
 const OPENNESS_KIND = "openness";
 const MASS_KIND = "mass";
@@ -301,13 +306,3 @@ export function planMudEditorSync(rows, state, triples) {
   }
   return { toAppend, toRemoveIds };
 }
-
-/** The word immediately before `cursorPos` in `text` — a run of letters, digits
- *  and hyphens, the shape this vocabulary's own terms take ("underground-space",
- *  "mole-1"). Empty when the cursor sits after whitespace or 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() : "";
-}

package/src/services/mud-turn.mjs

@@ -50,10 +50,12 @@ import { fnv1a32 } from "../domain/hash.mjs";
 import { bfsLevels } from "../domain/planning.mjs";
 import { loadMemory, readFactRows } from "../adapters/memory/core.mjs";
 import { DEFAULT_GAME_CONFIG, mudMassDrainPerTurn } from "../domain/game-config.mjs";
+import { predatorSubjects } from "../domain/mud-facts.mjs";
 import {
   foldWorldState, worldActionRows, runWorldCommand, recordTold, recordExamined,
   recordMassDrain, personKnowledgeLines, objectClassChain, diggableDirections,
   isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase, massDrainPerTurnOf,
+  parseSnapshotSubject,
 } from "./adventure.mjs";
 
 const FOOD_CLASS = "food";
@@ -61,7 +63,6 @@ const LATERAL_DIRECTIONS = ["north", "south", "east", "west"];
 // Deep enough to cross a whole burrow without letting one character's
 // pathfinder walk a whole grown world every tick.
 const WALK_SEARCH_DEPTH = 8;
-const SNAPSHOT_RE = /^(.+)@turn(\d+)$/;
 
 const EXIT_TOWARD_FOOD_CHANCE = 0.5;
 const EDGE_FOLLOW_DIG_CHANCE = 0.25;
@@ -208,8 +209,8 @@ function roomsStoodIn(rows, character) {
   const visited = new Set();
   for (const row of worldActionRows(rows)) {
     if (row.predicate !== "mgx:currently-in") continue;
-    const snapshot = SNAPSHOT_RE.exec(row.subject);
-    if ((snapshot ? snapshot[1] : row.subject) !== character) continue;
+    const snapshot = parseSnapshotSubject(row.subject);
+    if ((snapshot ? snapshot.base : row.subject) !== character) continue;
     visited.add(row.object);
   }
   return visited;
@@ -220,9 +221,8 @@ function roomsStoodIn(rows, character) {
  *  funnel straight to the den, since the unvisited room nearest the burrow is
  *  exactly where the fox lives. The den stays reachable by the food gamble
  *  below, which is a gamble and is meant to be. */
-const predatorRooms = (rows, state) => new Set((rows || [])
-  .filter((r) => r.predicate === "mgx:is-predator" && r.object === "true")
-  .map((r) => state.placements.get(r.subject)?.object)
+const predatorRooms = (rows, state) => new Set(predatorSubjects(rows)
+  .map((subject) => state.placements.get(subject)?.object)
   .filter(Boolean));
 
 /**