@polycode-projects/the-mechanical-code-talker 2.8.9 → 2.8.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.8.9",
+  "version": "2.8.11",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
@@ -138,6 +138,7 @@
     "build:chat-bundle": "node scripts/build-chat-bundle.mjs",
     "build:spider-fly-bundle": "node scripts/build-spider-fly-bundle.mjs",
     "build:plan-bundle": "node scripts/build-plan-bundle.mjs",
+    "build:ledger-bundle": "node scripts/build-ledger-bundle.mjs",
     "build:chat-seed": "node scripts/build-chat-seed.mjs",
     "build:demo-graph": "node scripts/build-demo-graph.mjs",
     "build:demo-pack": "node scripts/build-demo-pack.mjs",

package/src/services/ledger-viz.mjs

@@ -393,12 +393,20 @@ function microbarsHtml(items) {
 /** The dashboard strip: fact/term totals, the tier bar, graph density, a data-
  *  quality tile keyed off the SAME contradiction count worthALook surfaces,
  *  and the corpus-bundle/predicate leaderboards. Every tile reads straight
- *  off `stats` (computeLedgerStats) — no client-side recomputation. */
-function dashboardHtml(stats) {
+ *  off `stats` (computeLedgerStats) — no client-side recomputation.
+ *
+ *  Also the live dock's own re-render target: `id="dash"` gives a post-teach
+ *  refresh a single element to replace (`el("dash").outerHTML = dashboardHtml(...)`
+ *  — see renderLedgerHtml's inline script), and `fresh: true` marks that
+ *  replacement with a quiet settle-fade (`.dash.fresh`, below) rather than a
+ *  silent swap — the SAME function serves the server-rendered initial paint
+ *  (fresh omitted) and every live update after it, so the two can never drift. */
+function dashboardHtml(stats, { fresh = false } = {}) {
   const s = stats || {};
   const total = s.totalFacts || 0;
+  const freshCls = fresh ? " fresh" : "";
   if (!total) {
-    return `<section class="dash" aria-label="Ledger metrics"><div class="tile"><span class="tile-label">facts.total</span><span class="tile-value">0</span><span class="tile-sub">nothing taught yet</span></div></section>`;
+    return `<section class="dash${freshCls}" id="dash" aria-label="Ledger metrics"><div class="tile"><span class="tile-label">facts.total</span><span class="tile-value">0</span><span class="tile-sub">nothing taught yet</span></div></section>`;
   }
   const terms = s.totalTerms || 0;
   const qualityCls = s.contradictionCount > 0 ? " tile-alert" : "";
@@ -406,7 +414,7 @@ function dashboardHtml(stats) {
   const predicatesHtml = s.predicates?.length
     ? microbarsHtml(s.predicates.map((p) => ({ label: p.phrase || p.predicate, count: p.count })))
     : `<span class="tile-sub">none yet</span>`;
-  return `<section class="dash" aria-label="Ledger metrics">
+  return `<section class="dash${freshCls}" id="dash" aria-label="Ledger metrics">
     <div class="tile">
       <span class="tile-label">facts.total</span>
       <span class="tile-value">${total}</span>
@@ -462,11 +470,40 @@ function sparklineSvg(stats) {
   </svg>`;
 }
 
+/** The sparkline's own caption — "learned <date>" for a single-day graph,
+ *  "first … last …" once it spans more than one, or the generic fallback
+ *  before any dated fact exists. Its own named function (not inlined at the
+ *  one server call site) so the live dock's post-teach refresh can call the
+ *  identical logic client-side — see renderLedgerHtml's `sparkCaptionHtml`
+ *  toString-embed, below. */
+function sparkCaptionHtml(stats) {
+  return stats?.firstLearned && stats?.lastLearned
+    ? (stats.firstLearned.slice(0, 10) === stats.lastLearned.slice(0, 10)
+        ? `learned ${escapeHtml(stats.lastLearned.slice(0, 10))}`
+        : `first ${escapeHtml(stats.firstLearned.slice(0, 10))} &middot; last ${escapeHtml(stats.lastLearned.slice(0, 10))}`)
+    : "cumulative facts, teach order";
+}
+
 /** One complete, self-contained document: the ledger, segment rail,
  *  worth-a-look panel, breadcrumb/search, two-hop minimap, and (when the
  *  memory-ask bundle is present) the ask-the-graph chat dock, all over the
- *  embedded LEDGER/PAYLOAD data. */
-export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, worthALook, payload, meta, memoryAskBundle, stats } = {}) {
+ *  embedded LEDGER/PAYLOAD data.
+ *
+ *  `ledgerBundleAvailable` (default false — every existing caller, including
+ *  bin/tmct.mjs's `tmct viz` and every test that doesn't pass it) governs
+ *  ONE thing: whether an external `<script src="./ledger-browser.bundle.js">`
+ *  reference is emitted at all. That bundle carries the full runTurn engine
+ *  (teach AND ask) and is Pages-demo-site-only — never built or shipped
+ *  alongside the CLI's own output — so the CLI's `renderLedgerHtml` call
+ *  never sets this and the page stays exactly as documented above, one
+ *  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
+ *  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. */
+export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, worthALook, payload, meta, memoryAskBundle, stats, ledgerBundleAvailable = false } = {}) {
   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 } });
   const payloadJson = embedJson(payload || { individuals: [], objectProperties: [] });
   const shown = meta?.shown ?? (rows || []).length;
@@ -474,7 +511,10 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
   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.
+  // 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).
   const termSet = new Set((terms || []).map((t) => t.term));
   const placeholder = termSet.has("ishmael")
     ? "who is the grandfather of ishmael"
@@ -488,11 +528,6 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
         </form>
       </div>`
     : `<div class="chat chat-off"><p class="chatnote">chat unavailable — run <span class="mono">npm run build:ask-bundle</span> to enable the in-page ask engine.</p></div>`;
-  const sparkCaption = stats?.firstLearned && stats?.lastLearned
-    ? (stats.firstLearned.slice(0, 10) === stats.lastLearned.slice(0, 10)
-        ? `learned ${escapeHtml(stats.lastLearned.slice(0, 10))}`
-        : `first ${escapeHtml(stats.firstLearned.slice(0, 10))} &middot; last ${escapeHtml(stats.lastLearned.slice(0, 10))}`)
-    : "cumulative facts, teach order";
 
   return `<!doctype html>
 <html lang="en">
@@ -594,12 +629,26 @@ ${THEME_TOKENS_CSS}
   .chatlog .a { font-size: .9rem; line-height: 1.45; }
   .chatlog .a.miss { color: var(--muted); }
   .chatlog .a.goal { font-family: ${MONO_STACK}; font-size: .72rem; color: var(--muted); }
+  .chatlog .a.pending { color: var(--muted); font-style: italic; }
+  .chatlog .a.taught { border-left: 2px solid var(--taught); padding-left: .55rem; }
+  .chatlog .a.taught .tag { display: block; font-family: ${MONO_STACK}; font-size: .62rem; letter-spacing: .06em; text-transform: uppercase; color: var(--taught); margin-bottom: .18rem; }
   .chatask { display: flex; align-items: center; gap: .5rem; }
   .chatlog:not(:empty) + .chatask { border-top: 1px solid var(--line); margin-top: .55rem; padding-top: .55rem; }
   .chatask .prompt { color: var(--taught); font-size: .78rem; }
   .chatask input { flex: 1; font-family: ${MONO_STACK}; font-size: .78rem; background: var(--bg); color: var(--ink); border: 1px solid var(--line); border-radius: 6px; padding: .32rem .6rem; min-width: 0; }
+  .chatask input:disabled { opacity: .6; }
   .chatnote { font-family: ${MONO_STACK}; font-size: .72rem; color: var(--muted); margin: 0; }
-  @media (prefers-reduced-motion: no-preference) { .seg, .chip, .look { transition: border-color .12s ease, background-color .12s ease; } }
+  @media (prefers-reduced-motion: no-preference) {
+    .seg, .chip, .look { transition: border-color .12s ease, background-color .12s ease; }
+    /* A live teach re-render swaps the dash section wholesale (dashboardHtml
+       is called again in full — see the inline script below), so the "this
+       just changed" signal has to be an animation on the fresh markup itself,
+       never a transition (which needs an old and new state on the SAME node
+       to interpolate between). Off entirely under reduced motion — the
+       numbers still update, just without the settle-fade. */
+    .dash.fresh .tile { animation: freshsettle 1.6s ease-out; }
+    @keyframes freshsettle { from { background: var(--taught-soft); } to { background: var(--card); } }
+  }
 </style>
 </head>
 <body>
@@ -632,18 +681,22 @@ ${THEME_TOKENS_CSS}
         <p class="mapnote">dots = terms &middot; click to refocus &middot; dim = filtered out</p>
       </div>
       <h2>ingestion</h2>
-      <div class="mapwrap sparkwrap">
+      <div class="mapwrap sparkwrap" id="sparkWrap">
         ${sparklineSvg(stats)}
-        <p class="mapnote">${sparkCaption}</p>
+        <p class="mapnote">${sparkCaptionHtml(stats)}</p>
       </div>
     </aside>
   </div>
 </main>
 <script>
-const LEDGER = ${ledgerJson};
+// let, not const: a successful live teach reassigns this wholesale
+// (applyLedgerData, in the script below) so the page re-renders the graph
+// it actually holds, not the snapshot from the moment the page loaded.
+let LEDGER = ${ledgerJson};
 const PAYLOAD = ${payloadJson};
 </script>
 ${hasMemChat ? `<script>\n${bundleStr}\n</script>` : ""}
+${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` : ""}
 <script>
 (function () {
   "use strict";
@@ -651,15 +704,39 @@ ${hasMemChat ? `<script>\n${bundleStr}\n</script>` : ""}
   const facetCounts = ${facetCounts.toString()};
   const el = (id) => document.getElementById(id);
   const esc = ${escapeHtml.toString()};
+  // Aliased so the dashboard/sparkline builders below (toString-embedded
+  // verbatim from ledger-viz.mjs's own Node-side source, which calls
+  // escapeHtml/pct by their real names) resolve without a second copy.
+  const escapeHtml = esc;
+  const pct = ${pct.toString()};
+  const tierTileHtml = ${tierTileHtml.toString()};
+  const microbarsHtml = ${microbarsHtml.toString()};
+  const dashboardHtml = ${dashboardHtml.toString()};
+  const sparklineSvg = ${sparklineSvg.toString()};
+  const sparkCaptionHtml = ${sparkCaptionHtml.toString()};
   const FAMS = ["is-a", "has", "can", "used-for", "rests-on", "role", "other"];
   const FAM_LABEL = { "is-a": "is a kind of", has: "has", can: "can", "used-for": "used for", "rests-on": "rests on", role: "role / property", other: "other" };
   const PROVS = [["taught", "you taught"], ["corpus", "corpus"], ["entail", "entailed"]];
   const RECS = ["today", "this week", "older"];
   const provKey = (p) => (p === "entailed" ? "entail" : p); // css class key
-  const termIndex = new Map(LEDGER.terms.map((t) => [t.term, t]));
-  const rowById = new Map(LEDGER.rows.map((r) => [r.id, r]));
-  const contraById = new Map();
-  LEDGER.contradictions.forEach((ids, gi) => ids.forEach((id) => contraById.set(id, gi)));
+
+  // LEDGER (declared "let" in the embed script above this one — a classic,
+  // non-module script's top-level bindings are reachable as bare identifiers
+  // by every later script tag in the document, never as window.LEDGER; see
+  // e2e/pages-ledger.test.mjs's own note on this) and its indexes start as
+  // the server-rendered snapshot but are REASSIGNED wholesale after a live
+  // teach (applyLedgerData, below) — a successful teach through the dock
+  // changes the underlying graph, and the page has to show that, not keep
+  // rendering the page-load snapshot next to a chat log that merely SAYS
+  // something new was learned.
+  let termIndex, rowById, contraById;
+  function rebuildIndexes() {
+    termIndex = new Map(LEDGER.terms.map((t) => [t.term, t]));
+    rowById = new Map(LEDGER.rows.map((r) => [r.id, r]));
+    contraById = new Map();
+    LEDGER.contradictions.forEach((ids, gi) => ids.forEach((id) => contraById.set(id, gi)));
+  }
+  rebuildIndexes();
 
   let focus = LEDGER.focus;
   let trail = focus ? [{ term: focus, label: null }] : [];
@@ -845,10 +922,133 @@ ${hasMemChat ? `<script>\n${bundleStr}\n</script>` : ""}
     else el("qmiss").textContent = "no such term";
   });
 
-  // ---- the chat dock: the SAME engine + payload the CLI answers from ------
+  // A successful live teach re-derives the WHOLE ledger (computeLedgerDataFromPayload,
+  // the sibling bundle's own re-export of the exact function this page's build
+  // step called) and re-mounts it here — the same view a fresh page load
+  // would render, never a stale snapshot next to a chat log that only SAYS
+  // something new was learned. The dashboard/sparkline sections are replaced
+  // wholesale (dashboardHtml/sparklineSvg, toString-embedded above, are the
+  // SAME functions the server used for the very first paint) rather than
+  // patched, so they can never drift from what a fresh render would produce.
+  function applyLedgerData(freshData) {
+    LEDGER = {
+      rows: freshData.rows, terms: freshData.terms, edges: freshData.edges,
+      focus: freshData.focus, contradictions: freshData.contradictions,
+      worthALook: freshData.worthALook, meta: freshData.meta,
+    };
+    rebuildIndexes();
+    el("dash").outerHTML = dashboardHtml(freshData.stats, { fresh: true });
+    el("sparkWrap").innerHTML = sparklineSvg(freshData.stats) + '<p class="mapnote">' + sparkCaptionHtml(freshData.stats) + "</p>";
+    // computeLedgerDataFromPayload resolves an unset focus to the newest
+    // taught row's own subject — passing no explicit term (below) means every
+    // successful teach naturally jumps the view to what was just learned.
+    if (freshData.focus) refocusWithLabel(freshData.focus, null);
+    else render();
+  }
+
+  // ---- 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.
+  // 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.
   const resolveAnsweredTerm = ${resolveAnsweredTerm.toString()};
   const chatForm = el("chatform");
-  if (chatForm && typeof tmctMemoryAsk !== "undefined") {
+  if (chatForm && typeof tmctLedger !== "undefined" && typeof tmctLedger.createLedgerSession === "function") {
+    const log = el("chatlog");
+    const chatqEl = el("chatq");
+    chatqEl.placeholder = 'ask or teach the graph\\u2026 e.g. "blue is a peg"';
+    const addLine = (cls, html) => {
+      const d = document.createElement("div");
+      d.className = cls; d.innerHTML = html;
+      log.appendChild(d); log.scrollTop = log.scrollHeight;
+      return d;
+    };
+
+    let session = null;
+    // Serializes every engine-touching call through this one dock — the same
+    // posture plan-viz.mjs's own chat-assert dock takes with its withLock,
+    // so a fast double-submit can never race two turns over one session.
+    let lock = Promise.resolve();
+    const withLock = (fn) => { const run = lock.then(fn, fn); lock = run.catch(() => {}); return run; };
+
+    // The SAME bounded-race wink-nlp CDN load plan-viz.mjs's own chat-assert
+    // dock uses: a cross-origin dynamic import() can neither resolve nor
+    // reject on some failures, so an unbounded await would leave a session
+    // stuck forever. Best-effort — a teach sentence that needs the lemma tier
+    // just declines honestly without it, same as a checkout missing the
+    // optional deps.
+    const WINK_LOAD_TIMEOUT_MS = 8000;
+    const winkTimeout = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(new Error(reason)), ms));
+    let winkReady = null;
+    function tryLoadWink() {
+      if (winkReady) return winkReady;
+      winkReady = (async () => {
+        try {
+          const mods = await Promise.race([
+            Promise.all([import("wink-nlp"), import("wink-eng-lite-web-model")]),
+            winkTimeout(WINK_LOAD_TIMEOUT_MS, "wink-nlp CDN load timed out"),
+          ]);
+          const winkNLP = mods[0].default;
+          const model = mods[1].default;
+          tmctLedger.registerWinkModel(() => ({ winkNLP: winkNLP, model: model }));
+        } catch (err) {
+          // eslint-disable-next-line no-console
+          console.warn("tmct ledger: wink-nlp CDN load failed, continuing without the lemma/POS tier", err);
+        }
+      })();
+      return winkReady;
+    }
+    tryLoadWink(); // fire eagerly at load, so it is likely settled by the first interaction
+
+    async function ensureSession() {
+      if (session) return session;
+      await tryLoadWink();
+      session = await tmctLedger.createLedgerSession({ seedPayload: PAYLOAD });
+      return session;
+    }
+
+    chatForm.addEventListener("submit", (e) => {
+      e.preventDefault();
+      const q = chatqEl.value.trim();
+      if (!q) return;
+      chatqEl.value = "";
+      addLine("u", esc(q));
+      const pending = addLine("a pending", "computing\\u2026");
+      chatqEl.disabled = true;
+      withLock(async () => {
+        try {
+          const s = await ensureSession();
+          const result = await s.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, {});
+            applyLedgerData(fresh);
+          } else if (!(record && record.miss)) {
+            // Only a genuine answer (never a miss) tries to resolve a
+            // refocus target — the honest-miss cascade's own boilerplate
+            // ("Run \`tmct init\`…") can contain a real term as an
+            // 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);
+            if (hit) refocusWithLabel(hit, q);
+          }
+        } catch {
+          pending.className = "a miss";
+          pending.textContent = "Something went wrong answering that. Try rephrasing, or reload the page.";
+        } finally {
+          chatqEl.disabled = false;
+          chatqEl.focus();
+        }
+      });
+    });
+  } else if (chatForm && typeof tmctMemoryAsk !== "undefined") {
     const memHandle = tmctMemoryAsk.createInMemoryStore();
     memHandle.payload = PAYLOAD;
     const log = el("chatlog");

package/src/services/sprite-catalog-viz.mjs

@@ -283,6 +283,78 @@ export function buildSpriteCatalogEntries({ iconTemplates = [], largeTemplates =
   });
 }
 
+// ---- scene composer (pure) ----
+//
+// The free-text "there is a..." box (PLAN_GAMES_UPLIFT_V3.md's own precedent:
+// adventure-viz.mjs's roomSceneObjects/room-frame) over THIS page's own
+// already-real classes — never a general NLU pass. extractSceneItems is the
+// one pure, unit-testable piece; the DOM index it's matched against
+// (className -> real swatch labels, read straight off this page's own
+// already-rendered `.card`/`.swatch-label` markup at load time — see this
+// module's own header for why that beats re-embedding the same SVG data a
+// second time) is built client-side in the inline script below, since
+// walking rendered DOM has no meaning in this pure module.
+
+/** `text`'s lowercase word runs with their token index, the unit
+ *  extractSceneItems matches class names against — punctuation never fuses
+ *  two real words into one token nor splits one real word into two. */
+function tokenizeSceneText(text) {
+  const tokens = [];
+  const re = /[A-Za-z]+/g;
+  let m;
+  while ((m = re.exec(String(text ?? "")))) tokens.push({ word: m[0].toLowerCase() });
+  return tokens;
+}
+
+/** Every real catalog class the free-typed `text` names, in the order each
+ *  first appears, paired with the real material label (one of that SAME
+ *  class's own swatch labels — never another class's, never a fabricated
+ *  one) immediately preceding it, or `null`. `classIndex` is
+ *  `{className: {materials}}` with `materials` keyed by lowercase label
+ *  (sprite-catalog-viz's own client-side `buildClassIndexFromDom` output, or
+ *  an equivalent test fixture) — a class name absent from `classIndex` can
+ *  never match, and a modifier word that isn't one of ITS matched class's
+ *  own material labels is silently dropped rather than guessed at, the same
+ *  honest-miss posture an unrecognized class name gets (an unmatched word,
+ *  e.g. "red" before a lamp with no red material, is never an error, just
+ *  silently not drawn). A multi-word class name (e.g. "body of water") is
+ *  checked, at every token position, before any shorter class that would
+ *  otherwise claim part of it — candidates are tried longest-word-count
+ *  first, so the longer name always wins the position it starts at. Pure. */
+export function extractSceneItems(text, classIndex) {
+  const index = classIndex || {};
+  const candidates = Object.keys(index)
+    .map((name) => ({ name, words: name.toLowerCase().split(/\s+/).filter(Boolean) }))
+    .filter((c) => c.words.length)
+    .sort((a, b) => b.words.length - a.words.length || b.name.length - a.name.length);
+  const tokens = tokenizeSceneText(text);
+  const used = new Array(tokens.length).fill(false);
+  const items = [];
+  for (let i = 0; i < tokens.length; i += 1) {
+    if (used[i]) continue;
+    const hit = candidates.find(({ words }) => {
+      if (i + words.length > tokens.length) return false;
+      for (let k = 0; k < words.length; k += 1) {
+        if (used[i + k] || tokens[i + k].word !== words[k]) return false;
+      }
+      return true;
+    });
+    if (!hit) continue;
+    let materialLabel = null;
+    if (i > 0 && !used[i - 1]) {
+      const materials = index[hit.name]?.materials || {};
+      const prevWord = tokens[i - 1].word;
+      if (Object.prototype.hasOwnProperty.call(materials, prevWord)) {
+        materialLabel = prevWord;
+        used[i - 1] = true;
+      }
+    }
+    for (let k = 0; k < hit.words.length; k += 1) used[i + k] = true;
+    items.push({ className: hit.name, materialLabel });
+  }
+  return items;
+}
+
 // ---- rendering ----
 
 function chainHtml(chain) {
@@ -361,7 +433,26 @@ ${THEME_TOKENS_CSS}
   main { max-width: 1180px; margin: 0 auto; padding: 1.4rem 1.2rem 3rem; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .7rem; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); }
   h1 { font-size: 1.4rem; margin: .3rem 0 .6rem; text-wrap: balance; }
-  .intro { max-width: 74ch; color: var(--muted); font-size: .92rem; }
+
+  .composer { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: .6rem 0 1.3rem; }
+  @media (max-width: 700px) { .composer { grid-template-columns: 1fr; } }
+  .composer .panel { background: var(--card); border: 1px solid var(--line); border-top: 2px solid var(--taught); padding: .75rem .85rem; min-width: 0; }
+  .composer h2 { font-family: ${SERIF_STACK}; font-variant: small-caps; font-size: .82rem; letter-spacing: .04em; color: var(--muted); font-weight: 600; margin: 0 0 .55rem; }
+  .composeform { display: flex; align-items: center; gap: .5rem; }
+  .composeform .prompt { color: var(--taught); font-size: .8rem; white-space: nowrap; }
+  .composeform input { flex: 1; font-family: ${MONO_STACK}; font-size: .82rem; background: var(--bg); color: var(--ink); border: 1px solid var(--line); border-radius: 4px; padding: .38rem .6rem; min-width: 0; }
+  .composeform input:focus-visible { outline: 2px solid var(--taught); outline-offset: 2px; }
+  .pills { display: flex; flex-wrap: wrap; gap: .35rem; margin-top: .6rem; }
+  .pill { font-family: ${MONO_STACK}; font-size: .7rem; padding: .22rem .55rem; border: 1px solid var(--line); border-radius: 999px; background: var(--bg); color: var(--ink); cursor: pointer; }
+  .pill:hover { border-color: var(--taught); }
+  .pill:focus-visible { outline: 2px solid var(--taught); outline-offset: 2px; }
+  .scene-frame { min-height: 5.6rem; display: flex; align-items: center; }
+  .scene-row { display: flex; flex-wrap: wrap; gap: .8rem; align-items: flex-start; width: 100%; }
+  .scene-card { display: flex; flex-direction: column; align-items: center; width: 74px; }
+  .scene-sprite { width: 60px; height: 60px; border-radius: 8px; background: var(--bg); border: 1px solid var(--line); display: flex; align-items: center; justify-content: center; padding: 8px; box-sizing: border-box; }
+  .scene-sprite svg { width: 100%; height: 100%; display: block; }
+  .scene-label { font-size: .7rem; text-align: center; color: var(--ink); margin-top: .3rem; line-height: 1.2; }
+  .empty-note { font-family: ${MONO_STACK}; font-size: .78rem; color: var(--muted); }
   .topbar { position: sticky; top: 0; z-index: 2; background: var(--bg); display: flex; flex-wrap: wrap; align-items: center; gap: .5rem .9rem; border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); padding: .6rem 0; margin: 1rem 0 1.2rem; }
   .jump { font-family: ${MONO_STACK}; font-size: .72rem; padding: .18rem .55rem; border: 1px solid var(--line); border-radius: 99px; background: var(--card); color: var(--ink); text-decoration: none; }
   .jump:hover { border-color: var(--taught); }
@@ -395,21 +486,39 @@ ${THEME_TOKENS_CSS}
   .swatch-caption { font-family: ${MONO_STACK}; font-size: .58rem; color: var(--muted); line-height: 1.25; margin-top: .15rem; word-break: break-word; }
   .swatch-treat { display: block; opacity: .8; }
   footer.page { max-width: 74ch; margin: 2.5rem 0 0; padding-top: 1rem; border-top: 1px solid var(--line); font-family: ${MONO_STACK}; font-size: .74rem; color: var(--muted); }
-  @media (prefers-reduced-motion: no-preference) { .jump, .swatch { transition: border-color .12s ease, opacity .12s ease; } }
+  @media (prefers-reduced-motion: no-preference) { .jump, .swatch, .pill { transition: border-color .12s ease, opacity .12s ease; } }
 </style>
 </head>
 <body>
 <main>
   <div class="eyebrow">tmct &middot; the sprite library</div>
-  <h1>Every shape the sprite library can draw, and why</h1>
-  <p class="intro">Two tiers share one resolver: a 44px icon set for the live games, a 400px
-    gradient-shaded set for a closer look. Each card below shows a class's real
-    <span class="mono">rdfs:subClassOf</span> ancestor chain and every swatch the real resolver
-    (<span class="mono">resolveSpriteAsset</span>) actually returns for it &mdash; a material-bearing
-    class shows its real taught-material variants, never an invented one. Every class shown here
-    already carries its own template, so live resolution always stops at the chain's own first
-    link (marked); the fuller chain is real ancestry on record in this catalog's corpus slice, kept
-    for context.</p>
+  <h1>Sprites</h1>
+  <div class="composer">
+    <section class="panel compose-panel" aria-label="Describe a scene">
+      <h2>describe a scene</h2>
+      <form class="composeform" id="composeForm">
+        <span class="prompt mono">there is a</span>
+        <input id="composeq" type="text" autocomplete="off"
+          placeholder="red lamp, a doctor with a hat, and a cabinet"
+          aria-label="Continue the sentence: there is a&hellip;">
+      </form>
+      <div class="pills" id="composePills" role="group" aria-label="quick words to add">
+        <button type="button" class="pill" data-fill="doctor">doctor</button>
+        <button type="button" class="pill" data-fill="hat">hat</button>
+        <button type="button" class="pill" data-fill="wood cabinet">wood cabinet</button>
+        <button type="button" class="pill" data-fill="glass lamp">glass lamp</button>
+        <button type="button" class="pill" data-fill="cat">cat</button>
+        <button type="button" class="pill" data-fill="garden">garden</button>
+      </div>
+    </section>
+    <section class="panel viewer-panel" aria-label="The composed scene">
+      <h2>the scene</h2>
+      <div class="scene-frame" id="sceneFrame">
+        <div class="scene-row" id="sceneRow" aria-live="polite"></div>
+        <span class="empty-note" id="sceneEmpty">nothing recognized yet &mdash; try &ldquo;a doctor with a hat, and a cabinet&rdquo;.</span>
+      </div>
+    </section>
+  </div>
   <div class="topbar">
     <nav aria-label="Jump to group">${navHtml}</nav>
     <div class="filter">
@@ -445,6 +554,77 @@ const SPRITE_CATALOG = ${pageData};
   }
   q.addEventListener("input", apply);
   apply();
+
+  // ---- the scene composer — reads the class/material index straight off
+  // THIS page's own already-rendered card and swatch-label markup (this
+  // module's own header explains why: never a second embedded copy of the
+  // same swatch data), so the composed scene below only ever shows a sprite
+  // this same page already proved the resolver draws.
+  const esc = ${escapeHtml.toString()};
+  const tokenizeSceneText = ${tokenizeSceneText.toString()};
+  const extractSceneItems = ${extractSceneItems.toString()};
+
+  function buildClassIndexFromDom() {
+    const index = {};
+    for (const card of cards) {
+      const largeRow = card.querySelector('.tier-row[data-tier="large"]');
+      if (!largeRow) continue;
+      let defaultSvg = null;
+      const materials = {};
+      for (const swatch of largeRow.querySelectorAll(".swatch")) {
+        const labelEl = swatch.querySelector(".swatch-label");
+        const svgEl = swatch.querySelector(".swatch-img");
+        if (!labelEl || !svgEl) continue;
+        const svg = svgEl.innerHTML;
+        if (swatch.classList.contains("plain")) defaultSvg = svg;
+        else if (swatch.classList.contains("fallback")) { if (!defaultSvg) defaultSvg = svg; }
+        else materials[labelEl.textContent.trim().toLowerCase()] = svg;
+      }
+      if (!defaultSvg) {
+        const firstSvg = largeRow.querySelector(".swatch-img");
+        if (firstSvg) defaultSvg = firstSvg.innerHTML;
+      }
+      index[card.dataset.cls] = { defaultSvg, materials };
+    }
+    return index;
+  }
+
+  const classIndex = buildClassIndexFromDom();
+  const composeqEl = document.getElementById("composeq");
+  const composeFormEl = document.getElementById("composeForm");
+  const composePillsEl = document.getElementById("composePills");
+  const sceneRowEl = document.getElementById("sceneRow");
+  const sceneEmptyEl = document.getElementById("sceneEmpty");
+
+  function renderScene(text) {
+    const items = extractSceneItems(text, classIndex);
+    if (!items.length) {
+      sceneRowEl.innerHTML = "";
+      sceneEmptyEl.hidden = false;
+      return;
+    }
+    sceneEmptyEl.hidden = true;
+    sceneRowEl.innerHTML = items.map((item) => {
+      const entry = classIndex[item.className];
+      if (!entry) return "";
+      const svg = (item.materialLabel && entry.materials[item.materialLabel]) || entry.defaultSvg || "";
+      const label = item.materialLabel ? item.materialLabel + " " + item.className : item.className;
+      return '<div class="scene-card"><div class="scene-sprite">' + svg + '</div><div class="scene-label">' + esc(label) + "</div></div>";
+    }).join("");
+  }
+
+  composeqEl.addEventListener("input", () => renderScene(composeqEl.value));
+  composeFormEl.addEventListener("submit", (e) => { e.preventDefault(); renderScene(composeqEl.value); });
+  composePillsEl.addEventListener("click", (e) => {
+    const btn = e.target.closest(".pill");
+    if (!btn) return;
+    const phrase = btn.dataset.fill || "";
+    const current = composeqEl.value.trim();
+    composeqEl.value = current ? current + ", a " + phrase : phrase;
+    composeqEl.focus();
+    renderScene(composeqEl.value);
+  });
+  renderScene("");
 })();
 </script>
 </body>

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

@@ -0,0 +1,85 @@
+// ledger-browser-entry.mjs — the esbuild entry for the memory-ledger page's
+// LIVE chat dock (public/ledger-browser.bundle.js, built by
+// scripts/build-ledger-bundle.mjs), mirroring chat-browser-entry.mjs's own
+// createChatSession shape exactly. The ledger dock is general free-text
+// teach+ask, the same shape chat.html's own dock is — not board-game
+// specific like plan-browser-entry.mjs's createPlanSession, which has to
+// teach and solve a puzzle up front.
+//
+// Gitignored, Pages-demo-site-only output (scripts/build-demo-site.mjs
+// builds it fresh on every deploy, never committed) — see
+// memory-ask-browser-entry.mjs's own header for the contrast: THAT bundle
+// (factAnswer/factReadBack only, ~1.0MB) is the one COMMITTED under src/ and
+// packed by `npm publish`, because `tmct viz` is a real CLI command run
+// against a user's own local .tmct store and must ship with the package.
+// This bundle carries the FULL runTurn engine (~1.5MB, the same weight
+// class as chat/spider-fly/adventure/plan's own browser bundles) and is
+// never published — only the hosted demo site's public/ledger.html links to
+// it, as an optional sibling script the page degrades honestly without.
+import { runTurn, vocabExampleHint } from "../../services/chat.mjs";
+import { createInMemoryStore, normFactTerm } from "../../adapters/memory/core.mjs";
+import { parseEntities } from "../../domain/codegraph.mjs";
+import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
+import { registerWinkModel } from "../../adapters/wink-model.mjs";
+import { computeLedgerDataFromPayload } from "../../services/ledger-viz.mjs";
+
+/**
+ * A browser ledger-dock session over the real turn engine — createChatSession's
+ * exact shape, seeded from the ledger page's own embedded PAYLOAD (the same
+ * loadMemory()-shaped object renderLedgerHtml embeds as `const PAYLOAD`), so
+ * a fact taught through the dock extends the SAME graph the page renders
+ * from, never a disconnected one.
+ *
+ * Returns { memoryDir, sessionId, turn }, identical to createChatSession.
+ * ledger-viz.mjs's own inline script calls computeLedgerDataFromPayload
+ * (re-exported below) on `memoryDir.payload` after a turn whose record shows
+ * a successful write (`via: "assert"` or `via: "retract"`, `miss: false`) to
+ * re-derive the page's rows/terms/edges/stats and re-mount the same view a
+ * fresh page load would have rendered — a plain query never re-derives.
+ */
+export function createLedgerSession({ seedPayload = null, vocabSeeded = false } = {}) {
+  const memoryDir = createInMemoryStore();
+  // Spread onto the store's own empty payload so a partial seed still
+  // carries the classes/prefixes scaffolding the write path recounts —
+  // teach turns must work regardless of what the seed payload carries.
+  if (seedPayload) memoryDir.payload = { ...memoryDir.payload, ...seedPayload };
+
+  const graph = parseEntities({ individuals: [], objectProperties: [] });
+  const lexicon = loadLexicon();
+  const vocabHint = vocabExampleHint(vocabSeeded);
+  const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
+
+  let focus = null;
+  let last = null;
+  let planState = null;
+
+  return {
+    memoryDir,
+    sessionId,
+
+    /** One dispatched turn. A throwing runTurn must never kill the session —
+     *  the page has no other chance to show this turn's answer. */
+    async turn(line) {
+      let result;
+      try {
+        result = await runTurn(line, {
+          config: null, source: null, graph, focus, last, memoryDir, sessionId,
+          env: {}, lexicon, vocabHint, planState,
+        });
+      } 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 };
+      }
+      focus = result.focus;
+      last = result.last;
+      if ("planState" in result) planState = result.planState;
+      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null };
+    },
+  };
+}
+
+// Re-exported so ledger-viz.mjs's own inline script never has to duplicate
+// the derivation logic that builds rows/terms/edges/contradictions/
+// worthALook/stats from a payload — the same posture chat-browser-entry.mjs
+// takes re-exporting registerWinkModel for its own page's CDN wink load.
+globalThis.tmctLedger = { createLedgerSession, computeLedgerDataFromPayload, normFactTerm, registerWinkModel };