@polycode-projects/the-mechanical-code-talker 2.9.6 → 2.10.1

package/src/services/chat.mjs

@@ -21,7 +21,7 @@ import { join, dirname } from "node:path";
 import { dispatchTool, loadGraph, TOOLS } from "../tools/server.mjs";
 import { ToolError } from "../adapters/config.mjs";
 import { parseEntities, edgesOfKind, moduleCountOf, renderAuthorCard, renderAuthorTouches, renderCommitAuthor, resolveSymbol, renderCompare } from "../domain/codegraph.mjs";
-import { classDisplayName } from "../domain/ask.mjs";
+import { classDisplayName, DYNAMIC_TAIL_OK_RE } from "../domain/ask.mjs";
 import { uuidv7 } from "../adapters/uuid.mjs";
 import * as defaultSource from "../adapters/source.mjs";
 import { loadTemplates, render as renderTemplate } from "../adapters/corpus/templates.mjs";
@@ -811,7 +811,7 @@ async function answerMemoryCount(memoryDir, query) {
   // the bare "how many do you know" (no explicit noun) defaults to remembered facts
   if (/\bhow many(?:\s+(?:things?|facts?))?\s+(?:do|d'?)\s+(?:you|u)\s+know\b/.test(q)) cls = "Fact";
   if (!cls) {
-    const m = q.match(/\b(?:how many|number of|count(?:\s+the)?)\s+([a-z]+)\b(.*)$/);
+    const m = q.match(/\b(?:how many|number of|count(?:\s+the)?)\s+(?:all\s+)?([a-z]+)\b(.*)$/);
     if (m) {
       cls = MEMORY_COUNT_NOUNS[m[1]] || null;
       tail = m[2].trim();
@@ -844,6 +844,160 @@ async function answerMemoryCount(memoryDir, query) {
   return said((mem.individuals || []).filter((i) => (i.class || "") === cls).length);
 }
 
+// ---- memory-store LIST + meta-class count ("list facts", "list utterances",
+// "how many sessions are there") — the same reified individuals answerMemoryCount
+// tallies, but enumerated, and reaching the meta-classes (Session/Source/Rule) the
+// count lane skips. dynamicClassQuery (ask.mjs) already answers these when handed a
+// memory-shaped graph, but the chat path hands ask() the CODE graph, so the store's
+// own individuals were never reachable from a chat turn. This reads the store
+// directly, mirroring answerMemoryCount's own lazy/failure-tolerated load. ----
+
+/** Chat-phrasing nouns → the memory-store class they name. Fact/Utterance are
+ *  shared with answerMemoryCount (which owns their counts); the meta-classes are
+ *  reachable only here. */
+const MEMORY_CLASS_QUERY_NOUNS = {
+  fact: "Fact", facts: "Fact",
+  utterance: "Utterance", utterances: "Utterance",
+  session: "Session", sessions: "Session",
+  source: "Source", sources: "Source",
+  rule: "Rule", rules: "Rule",
+};
+const MEMORY_CLASS_PLURALS = {
+  Fact: "facts", Utterance: "utterances", Session: "sessions", Source: "sources", Rule: "rules",
+};
+const MEMORY_CLASS_LIST_TRIGGER_RE = /^(?:list|show(?:\s+me)?)\s+(?:all\s+|the\s+)?([a-z][a-z-]*)\s*(.*)$/i;
+const MEMORY_CLASS_COUNT_TRIGGER_RE = /^(?:how\s+many|number\s+of|count(?:\s+the)?)\s+(?:all\s+)?([a-z][a-z-]*)\s*(.*)$/i;
+
+/** One display line per stored individual of a class: a Fact reads back through
+ *  the same renderFactLine every other fact list uses; the other classes show
+ *  their own label. */
+function memoryClassLine(cls, ind, factByLabel) {
+  if (cls === "Fact") {
+    const row = factByLabel.get(ind.id);
+    if (row) return renderFactLine(row);
+  }
+  return String(ind.label || ind.id || "").trim();
+}
+
+/** Recognise "list <memory-class>" (any class) and "how many <meta-class>"
+ *  (Session/Source/Rule — Fact/Utterance counts stay with answerMemoryCount) and
+ *  answer off the store. Returns { text, pending } or null (→ the next lane owns
+ *  it). A real restrictor tail declines rather than answering a shorter question
+ *  nobody asked. */
+async function answerMemoryClassQuery(memoryDir, query) {
+  if (!memoryDir) return null;
+  const q = String(query).trim();
+  const listM = q.match(MEMORY_CLASS_LIST_TRIGGER_RE);
+  const countM = listM ? null : q.match(MEMORY_CLASS_COUNT_TRIGGER_RE);
+  const m = listM || countM;
+  if (!m) return null;
+  const cls = MEMORY_CLASS_QUERY_NOUNS[m[1].toLowerCase()];
+  if (!cls) return null;
+  // Fact/Utterance counts carry answerMemoryCount's own about-tail discipline;
+  // never re-answer them from this simpler lane.
+  if (countM && (cls === "Fact" || cls === "Utterance")) return null;
+  const plural = MEMORY_CLASS_PLURALS[cls];
+  const tail = (m[2] || "").trim();
+  if (!DYNAMIC_TAIL_OK_RE.test(tail)) {
+    const verb = listM ? "list" : "count";
+    return {
+      text: `I can ${verb} the ${plural} I hold, but not the "${tail}" part of that question — `
+        + `so I won't answer as if you hadn't asked it. `
+        + `Ask "${verb} ${plural}" for all of them.`,
+      miss: true,
+    };
+  }
+  let loadMemory;
+  let readFactRows;
+  try { ({ loadMemory, readFactRows } = await import("../adapters/memory/core.mjs")); } catch { return null; }
+  let mem;
+  try { mem = await loadMemory(memoryDir); } catch { return null; }
+  const inds = (mem.individuals || []).filter((i) => (i.class || "") === cls);
+  if (countM) return { text: `${inds.length} ${inds.length === 1 ? plural.replace(/s$/, "") : plural}.` };
+  if (!inds.length) return { text: `I don't have any ${plural} stored yet.`, miss: true };
+  const factByLabel = cls === "Fact" ? new Map(readFactRows(mem).map((r) => [r.id, r])) : new Map();
+  const lines = inds.map((ind) => memoryClassLine(cls, ind, factByLabel));
+  const shown = lines.slice(0, FACT_ANSWER_CAP);
+  const rest = lines.slice(FACT_ANSWER_CAP);
+  const extra = rest.length ? `\n…and ${rest.length} more — say 'more' to see them.` : "";
+  return {
+    text: shown.join("\n") + extra,
+    ...(rest.length ? { pending: { items: rest, noun: plural } } : {}),
+  };
+}
+
+// "how many animals are there" — a real count of a TAUGHT class's members
+// (every "X is a kind of animal" fact), distinct from answerQuantifierRecall's
+// literal quantifier lookup. Placed ahead of it in runTurn: HOW_MANY_ARE_RE
+// reads "there" as a second noun and answers "I was never told a quantifier",
+// stealing the phrasing before a member count ever runs.
+const TAUGHT_CLASS_COUNT_RE = /^how\s+many\s+([a-z][\w-]*)\s*(.*)$/i;
+
+/** Count the taught members of a class named by a plain noun ("how many animals
+ *  are there" → every "X is a kind of animal"). Declines (null) for a real
+ *  code-countable class (answerCount owns it) or a class nothing was taught
+ *  about, so structural counts and the quantifier lane are unaffected. */
+async function answerTaughtClassCount(memoryDir, query, biasByBundle = {}, cache = null) {
+  if (!memoryDir) return null;
+  const m = String(query).trim().match(TAUGHT_CLASS_COUNT_RE);
+  if (!m) return null;
+  if (!DYNAMIC_TAIL_OK_RE.test((m[2] || "").trim())) return null;
+  const asked = m[1].toLowerCase();
+  if (COUNT_NOUNS[asked]) return null; // a real graph-countable class — answerCount owns it
+  let normFactTerm;
+  try { ({ normFactTerm } = await import("../adapters/memory/core.mjs")); } catch { return null; }
+  const rows = await factRows(memoryDir, cache);
+  const isa = rows.filter((f) => ISA_PREDICATES.has(f.predicate));
+  const variants = factTermVariants(normFactTerm, asked);
+  const members = rankByBiasThenTrust(isa.filter((f) => variants.has(f.object)), biasByBundle);
+  if (!members.length) return null; // nothing taught under this class name — later lanes own it
+  // A member whose SUBJECT is itself a countable graph class ("every class is a
+  // component") is an asserted-vocabulary cardinality, not a member enumeration —
+  // countFromFacts counts the real class, so defer to it rather than tallying the
+  // one class-level fact.
+  if (members.some((f) => COUNT_NOUNS[String(f.subject).toLowerCase()])) return null;
+  return `${members.length} ${members.length === 1 ? asked.replace(/s$/, "") : asked}.`;
+}
+
+// "list all animals" / "list the animals" — enumerate a taught class's members,
+// with its OWN trigger rather than the "what is an animal" definition lane's
+// leftovers: at scale the definition lane fills its cap with forward corpus facts
+// before the reverse-membership listing ever shows, and the conversational
+// orientation lane claims the bare "list …" phrasing before factReadBack runs.
+const MEMBERSHIP_LIST_RE = /^(?:list|show(?:\s+me)?)\s+(?:all\s+|the\s+)?([a-z][\w-]*)\s*(.*)$/i;
+
+/** List the taught members of a class named by a plain noun ("list all animals"
+ *  → every "X is a kind of animal"). Declines (null) for a code-countable class
+ *  or a class nothing was taught about; declines with a message for a real
+ *  restrictor tail rather than answering as if it weren't there. */
+async function answerMembershipList(memoryDir, query, biasByBundle = {}, cache = null) {
+  if (!memoryDir) return null;
+  const m = String(query).trim().match(MEMBERSHIP_LIST_RE);
+  if (!m) return null;
+  const asked = m[1].toLowerCase();
+  if (COUNT_NOUNS[asked]) return null; // a real graph-countable class — the code list lane owns it
+  const tail = (m[2] || "").trim();
+  let normFactTerm;
+  try { ({ normFactTerm } = await import("../adapters/memory/core.mjs")); } catch { return null; }
+  const rows = await factRows(memoryDir, cache);
+  const isa = rows.filter((f) => ISA_PREDICATES.has(f.predicate));
+  const variants = factTermVariants(normFactTerm, asked);
+  const members = rankByBiasThenTrust(isa.filter((f) => variants.has(f.object)), biasByBundle);
+  if (!members.length) return null; // nothing taught under this class name — later lanes own it
+  if (!DYNAMIC_TAIL_OK_RE.test(tail)) {
+    return {
+      text: `I can list the ${asked}, but not the "${tail}" part of that question — `
+        + `so I won't answer as if you hadn't asked it. Ask "list ${asked}" for all of them.`,
+      miss: true,
+    };
+  }
+  const lines = members.map(renderFactLine);
+  const shown = lines.slice(0, FACT_ANSWER_CAP);
+  const rest = lines.slice(FACT_ANSWER_CAP);
+  const extra = rest.length ? `\n…and ${rest.length} more — say 'more' to see them.` : "";
+  return { text: shown.join("\n") + extra, ...(rest.length ? { pending: { items: rest, noun: asked } } : {}) };
+}
+
 /** `/stats`: a one-screen overview of the graph — class counts, relationship
  *  (predicate) counts, and module/package totals — read straight off the header. */
 export function renderStats(graph) {
@@ -2975,6 +3129,13 @@ const quantifiedHasSubject = (m) => (/^all$/i.test(m[1]) ? singularizeSurface(m[
 const quantifiedHasObject = (m) => (/^all$/i.test(m[1])
   ? m[3].replace(/[\w'-]+$/, (w) => singularizeSurface(w))
   : m[3]);
+/** The determiner-led possession teach ("the tower has 3 disks", "the robot has
+ *  2 arms", "my car has 4 wheels") — the closed has/have verb pins the split the
+ *  same way the universal quantifier pins QUANTIFIED_HAS_TEACH_RE's, so a leading
+ *  definite/possessive determiner needs no verb-position guessing. The subject is
+ *  the single noun between the determiner and the verb; a two-token subject stays
+ *  declined, like the preposition-pinned frame, because nothing names its head. */
+const DETERMINER_HAS_TEACH_RE = /^(?:the|an?|my|your|our|their|his|her|its)\s+([\w'-]+)\s+(?:has|have|had)\s+(.+?)[.!?]*$/i;
 /** Verbs owned by an earlier, more specific recognizer in this lane — is/are
  *  (class-membership/property, above) and owns/maintains (ownership, above).
  *  generalVerbTeach declines outright on these so it can never race a more
@@ -3142,10 +3303,15 @@ async function generalVerbTeach(payload) {
   // declines here exactly as it always has.
   if (GENERAL_VERB_DETERMINER_RE.test(subjectRaw)) {
     const quantHas = p.match(QUANTIFIED_HAS_TEACH_RE);
+    const detHas = !quantHas ? p.match(DETERMINER_HAS_TEACH_RE) : null;
     if (quantHas) {
       subjectRaw = quantifiedHasSubject(quantHas);
       verbRaw = "has";
       objectRaw = quantifiedHasObject(quantHas);
+    } else if (detHas) {
+      subjectRaw = detHas[1];
+      verbRaw = "has";
+      objectRaw = detHas[2];
     } else {
       const det = p.match(GENERAL_VERB_DETERMINER_TEACH_RE);
       if (!det) return null; // not a bare-name subject, and no preposition to pin the verb
@@ -4579,17 +4745,20 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null, cac
     // of THAT subject — the same word generalVerbTeach will store — and leave
     // every other sentence reading its first word exactly as before.
     const detLed = raw.match(GENERAL_VERB_DETERMINER_TEACH_RE);
-    const quantHasLed = detLed ? null : raw.match(QUANTIFIED_HAS_TEACH_RE);
+    const detHasLed = detLed ? null : raw.match(DETERMINER_HAS_TEACH_RE);
+    const quantHasLed = (detLed || detHasLed) ? null : raw.match(QUANTIFIED_HAS_TEACH_RE);
     const subjectWord = detLed ? detLed[1].split(/\s+/).pop()
-      : (quantHasLed ? quantifiedHasSubject(quantHasLed) : raw.match(/^([\w'-]+)/)?.[1]);
+      : (detHasLed ? detHasLed[1]
+        : (quantHasLed ? quantifiedHasSubject(quantHasLed) : raw.match(/^([\w'-]+)/)?.[1]));
     // The quantifier lead ("every … has …") is itself a strong declarative
     // signal, so it overrides the single-token POS gate: a noun that doubles
     // as a verb ("every overbid has a gouger" — wink tags "overbid" VERB)
-    // used to be a SILENT no-op and a later miss. NON_DECLARATIVE_OPENER_RE
-    // runs even for a quantifier lead — "every umm has a thing" isn't a real
-    // quantified sentence, just filler that happens to fit the shape.
+    // used to be a SILENT no-op and a later miss. A determiner-led possession
+    // ("the tower has 3 disks") pins the same way, so it gets the same override.
+    // NON_DECLARATIVE_OPENER_RE runs even for these leads — "every umm has a
+    // thing" isn't a real quantified sentence, just filler that fits the shape.
     if (subjectWord && !NON_DECLARATIVE_OPENER_RE.test(subjectWord)
-      && (quantHasLed || (await subjectIsNounOrPropn(subjectWord)))) {
+      && (quantHasLed || detHasLed || (await subjectIsNounOrPropn(subjectWord)))) {
       // A PLURAL explicit-capability surface ("wrens can hum") whose
       // SINGULAR is a grounded term stores under the singular first — the
       // spelling the grounding fact and every query-side variant fold use —
@@ -13429,6 +13598,46 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
       return withLast(plainTurn(workingLine, memCount, { via: "count", focus }), "get a count of a memory-store kind");
     }
   }
+  // "list facts"/"list utterances"/"how many sessions are there" — enumerate the
+  // stored individuals answerMemoryCount only tallies, and reach the meta-classes
+  // (Session/Source/Rule) it skips. Placed here so ask()'s CODE-graph lanes never
+  // steal the phrasing; declines cleanly for a code-graph noun or a real restrictor.
+  if (memoryDir) {
+    const memClass = await answerMemoryClassQuery(memoryDir, workingLine);
+    if (memClass != null) {
+      const goal = "list or count a memory-store kind (facts/utterances/sessions/sources/rules)";
+      note(trace, `goal: ${goal}`);
+      note(trace, "lane: answerMemoryClassQuery — matched a memory-store class noun, answered off the .tmct/memory store's own individuals");
+      const turn = plainTurn(workingLine, memClass.text, { via: memClass.miss ? "miss" : "fact", miss: !!memClass.miss, focus });
+      if (memClass.pending) turn.detail = { traversal: null, matches: [], pending: memClass.pending };
+      return withLast(turn, goal);
+    }
+  }
+  // "how many animals are there" — count a taught class's members, ahead of the
+  // quantifier lane (which reads "there" as a second noun and answers "I was never
+  // told a quantifier" for the exact same phrasing).
+  if (memoryDir) {
+    const taughtCount = await answerTaughtClassCount(memoryDir, workingLine, biasByBundle, factRowsCache);
+    if (taughtCount != null) {
+      note(trace, 'goal: count the taught members of a class ("how many animals are there")');
+      note(trace, "lane: answerTaughtClassCount — matched a plain-noun count over taught isa-facts whose OBJECT is that class");
+      return withLast(plainTurn(workingLine, taughtCount, { via: "count", focus }), "count a taught class's members");
+    }
+  }
+  // "list all animals"/"list the animals" — enumerate a taught class's members
+  // from its own trigger, ahead of the conversational orientation lane that would
+  // otherwise claim the bare "list …" phrasing.
+  if (memoryDir) {
+    const memberList = await answerMembershipList(memoryDir, workingLine, biasByBundle, factRowsCache);
+    if (memberList != null) {
+      const goal = "list the taught members of a class";
+      note(trace, `goal: ${goal}`);
+      note(trace, "lane: answerMembershipList — matched a bare 'list <noun>' over taught isa-facts whose OBJECT is that class");
+      const turn = plainTurn(workingLine, memberList.text, { via: memberList.miss ? "miss" : "fact", miss: !!memberList.miss, focus });
+      if (memberList.pending) turn.detail = { traversal: null, matches: [], pending: memberList.pending };
+      return withLast(turn, goal);
+    }
+  }
   // "how many Xs are Ys" — a taught-quantifier RECALL, checked explicitly
   // ahead of answerCount. Its own authority gate declines for anything
   // answerCount should own, so ordinary structural counts are unaffected.

package/src/services/code-explorer-viz.mjs

@@ -0,0 +1,343 @@
+// code-explorer-viz.mjs — the code-graph "ledger" the desktop shell renders:
+// each import/call/contains edge read back as a plain sentence, a hint rail of
+// suggested next queries, and a live chat dock over the same graph. The two
+// derivations are pure so the shell, the packaging script, and the unit tests
+// all share one code path; renderCodeExplorerHtml builds one self-contained
+// document with no external requests.
+//
+// The channel is deliberately thin: this is the SAME ledger-pattern UI the
+// browser ledger page uses, refocused on a code graph, and it stays servable
+// as a plain page — only the Electron shell around it (electron/) is desktop.
+
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText } from "./viz-theme.mjs";
+import { generateCodeHints } from "../domain/code-explorer-hints.mjs";
+
+// Third-person verb for each stored relation kind, symbol grain folded onto its
+// coarse sibling. A kind with no row here reads back as itself, never breaking
+// the sentence.
+const EDGE_PHRASE = new Map([
+  ["imports", "imports"],
+  ["calls", "calls"], ["callsSymbol", "calls"],
+  ["contains", "contains"],
+  ["defines", "defines"],
+  ["inherits", "inherits from"],
+  ["tests", "tests"],
+  ["touches", "touches"], ["touchesSymbol", "touches"],
+  ["cochange", "co-changes with"],
+  ["reexports", "re-exports"],
+]);
+
+export function edgePhrase(kind) {
+  return EDGE_PHRASE.get(String(kind || "")) || String(kind || "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+}
+
+const LEDGER_ROW_LIMIT_DEFAULT = 4000;
+
+/** Pure derivation over an entities payload (individuals + objectProperties).
+ *  Returns { rows, terms, focus, stats, meta } — rows are one readable
+ *  sentence per example edge, terms is the degree-ranked label index, and the
+ *  neighbourhood of `focus` survives a row cap first so a huge graph degrades
+ *  to "local + rest" rather than truncating the centre. */
+export function computeCodeLedger(payload, { focus = null, rowLimit = LEDGER_ROW_LIMIT_DEFAULT } = {}) {
+  const individuals = Array.isArray(payload?.individuals) ? payload.individuals : [];
+  const classOf = new Map();
+  for (const ind of individuals) if (ind?.label && !classOf.has(ind.label)) classOf.set(ind.label, ind.class || "");
+
+  const groups = Array.isArray(payload?.objectProperties) ? payload.objectProperties : [];
+  const rows = [];
+  const degree = new Map();
+  const kindCounts = new Map();
+  const bumpTerm = (t) => { if (t) degree.set(t, (degree.get(t) || 0) + 1); };
+  for (const g of groups) {
+    if (!g?.predicate) continue;
+    const kind = String(g.predicate);
+    kindCounts.set(kind, (kindCounts.get(kind) || 0) + (Number(g.count) || 0));
+    for (const e of Array.isArray(g.examples) ? g.examples : []) {
+      const s = e?.subjectLabel || e?.subject;
+      const o = e?.objectLabel || e?.object;
+      if (!s || !o) continue;
+      rows.push({ s, kind, phrase: edgePhrase(kind), o, sClass: classOf.get(s) || "", oClass: classOf.get(o) || "" });
+      bumpTerm(s); bumpTerm(o);
+    }
+  }
+
+  const terms = [...degree.entries()]
+    .map(([term, deg]) => ({ term, degree: deg, class: classOf.get(term) || "" }))
+    .sort((a, b) => b.degree - a.degree || a.term.localeCompare(b.term));
+
+  let focusTerm = focus && degree.has(focus) ? focus : null;
+  if (!focusTerm && terms.length) focusTerm = terms[0].term;
+
+  const classCounts = new Map();
+  for (const ind of individuals) if (ind?.class) classCounts.set(ind.class, (classCounts.get(ind.class) || 0) + 1);
+  const stats = {
+    individuals: individuals.length,
+    edges: rows.length,
+    classes: [...classCounts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])),
+    kinds: [...kindCounts.entries()].filter(([, c]) => c > 0).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])),
+  };
+
+  const total = rows.length;
+  let shown = rows;
+  if (total > rowLimit) {
+    const near = new Set([focusTerm]);
+    for (const r of rows) { if (r.s === focusTerm) near.add(r.o); if (r.o === focusTerm) near.add(r.s); }
+    const inHood = (r) => near.has(r.s) || near.has(r.o);
+    shown = [...rows.filter(inHood), ...rows.filter((r) => !inHood(r))].slice(0, rowLimit);
+  }
+  return { rows: shown, terms, focus: focusTerm, stats, meta: { shown: shown.length, total, truncated: shown.length < total } };
+}
+
+/** Everything the page embeds, derived once from a payload: the ledger, the
+ *  degree-ranked terms, the suggested queries, and the focus symbol. */
+export function computeCodeExplorerData(payload, opts = {}) {
+  const ledger = computeCodeLedger(payload, opts);
+  const { focus, hints } = generateCodeHints(payload, { focus: ledger.focus });
+  return { payload, ledger, hints, focus: ledger.focus || focus, meta: { title: opts.title || "code graph" } };
+}
+
+const CLIENT_JS = String.raw`
+(function () {
+  var DATA = window.__CODE_EXPLORER__;
+  var api = window.tmctCodeExplorer || null;
+  var els = {
+    focus: document.getElementById("focus-name"),
+    ledger: document.getElementById("ledger"),
+    hints: document.getElementById("hints"),
+    stats: document.getElementById("stats"),
+    log: document.getElementById("chat-log"),
+    form: document.getElementById("chat-form"),
+    input: document.getElementById("chat-input"),
+    dockNote: document.getElementById("dock-note"),
+    source: document.getElementById("source-name"),
+  };
+  var session = null;
+
+  function esc(s) {
+    return String(s == null ? "" : s).replace(/[&<>"']/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c];
+    });
+  }
+
+  function renderStats(data) {
+    var s = data.ledger.stats;
+    var parts = [s.individuals + " individuals", s.edges + " edges"];
+    var cls = s.classes.slice(0, 4).map(function (c) { return c[1] + " " + c[0]; });
+    els.stats.textContent = parts.concat(cls).join("  ·  ");
+  }
+
+  function renderFocusRows(data) {
+    var focus = data.focus;
+    var rows = data.ledger.rows;
+    var near = rows.filter(function (r) { return r.s === focus || r.o === focus; });
+    var rest = rows.filter(function (r) { return r.s !== focus && r.o !== focus; });
+    var ordered = near.concat(rest);
+    els.ledger.innerHTML = ordered.map(function (r) {
+      var hot = (r.s === focus || r.o === focus) ? " row-focus" : "";
+      return '<li class="row' + hot + '">'
+        + '<button class="term" data-term="' + esc(r.s) + '">' + esc(r.s) + '</button> '
+        + '<span class="verb">' + esc(r.phrase) + '</span> '
+        + '<button class="term" data-term="' + esc(r.o) + '">' + esc(r.o) + '</button>'
+        + '</li>';
+    }).join("") || '<li class="row muted">no edges in this graph.</li>';
+    els.focus.textContent = focus || "—";
+  }
+
+  function renderHints(data) {
+    els.hints.innerHTML = data.hints.map(function (h) {
+      return '<button class="hint" data-q="' + esc(h.text) + '" title="' + esc(h.rationale) + '">'
+        + esc(h.text) + '</button>';
+    }).join("") || '<span class="muted">nothing to suggest for this graph.</span>';
+  }
+
+  function focusOn(term) {
+    if (!api || !api.computeCodeExplorerData) return;
+    DATA = api.computeCodeExplorerData(DATA.payload, { focus: term, title: DATA.meta.title });
+    window.__CODE_EXPLORER__ = DATA;
+    mountView(DATA);
+  }
+
+  function mountView(data) {
+    renderStats(data);
+    renderFocusRows(data);
+    renderHints(data);
+  }
+
+  function appendLog(role, text) {
+    var div = document.createElement("div");
+    div.className = "turn turn-" + role;
+    div.innerHTML = '<span class="who">' + (role === "you" ? "you" : "tmct") + '</span><span class="said">' + esc(text) + '</span>';
+    els.log.appendChild(div);
+    els.log.scrollTop = els.log.scrollHeight;
+  }
+
+  async function ensureSession() {
+    if (session || !api || !api.createCodeExplorerSession) return session;
+    var winkLoaded = true;
+    if (api.registerWinkModel && window.__WINK_LOADER__) {
+      try { var mod = await window.__WINK_LOADER__(); api.registerWinkModel(function () { return mod; }); }
+      catch (e) { winkLoaded = false; }
+    }
+    session = api.createCodeExplorerSession({ graphPayload: DATA.payload });
+    return session;
+  }
+
+  async function ask(q) {
+    appendLog("you", q);
+    var s = await ensureSession();
+    if (!s) { appendLog("tmct", "the live dock is not loaded on this page."); return; }
+    var res = await s.turn(q);
+    appendLog("tmct", res.answer);
+  }
+
+  // Delegate term + hint clicks.
+  document.addEventListener("click", function (ev) {
+    var t = ev.target.closest ? ev.target.closest("[data-term]") : null;
+    if (t) { focusOn(t.getAttribute("data-term")); return; }
+    var h = ev.target.closest ? ev.target.closest("[data-q]") : null;
+    if (h) { els.input.value = h.getAttribute("data-q"); els.input.focus(); if (api) ask(h.getAttribute("data-q")); return; }
+  });
+
+  if (els.form) {
+    els.form.addEventListener("submit", function (ev) {
+      ev.preventDefault();
+      var q = els.input.value.trim();
+      if (!q) return;
+      els.input.value = "";
+      ask(q);
+    });
+  }
+
+  // Desktop pickers, present only under the Electron shell.
+  function wirePicker(id, method, updateSource) {
+    var btn = document.getElementById(id);
+    if (!btn) return;
+    if (!window.tmctDesktop || typeof window.tmctDesktop[method] !== "function") { btn.disabled = true; return; }
+    btn.addEventListener("click", async function () {
+      btn.disabled = true;
+      try {
+        var picked = await window.tmctDesktop[method]();
+        if (picked && picked.payload) {
+          session = null;
+          DATA = (api && api.computeCodeExplorerData)
+            ? api.computeCodeExplorerData(picked.payload, { title: picked.name || "code graph" })
+            : DATA;
+          window.__CODE_EXPLORER__ = DATA;
+          if (updateSource && els.source) els.source.textContent = picked.name || "(loaded graph)";
+          els.log.innerHTML = "";
+          mountView(DATA);
+        }
+      } finally { btn.disabled = false; }
+    });
+  }
+  wirePicker("open-graph", "openGraph", true);
+  wirePicker("open-repo", "openRepo", true);
+
+  if (!api) {
+    if (els.dockNote) els.dockNote.textContent = "static view — the live chat dock is unavailable on this page.";
+    if (els.input) els.input.disabled = true;
+  }
+
+  mountView(DATA);
+})();
+`;
+
+/**
+ * One self-contained HTML document for the code explorer. `data` is
+ * computeCodeExplorerData's output. `bundleInline` inlines the dock engine
+ * (for a single-file page / a data: URL); otherwise `bundleAvailable` links
+ * `./code-explorer.bundle.js`. `winkLoaderInline` optionally inlines a wink
+ * model loader as `window.__WINK_LOADER__`.
+ */
+export function renderCodeExplorerHtml(data, { bundleInline = "", bundleAvailable = false, winkLoaderInline = "", sourceName = "demo code graph" } = {}) {
+  const payloadJson = embedJson(data.payload);
+  const dataJson = embedJson({ ledger: data.ledger, hints: data.hints, focus: data.focus, meta: data.meta });
+  const title = escapeHtml(data.meta?.title || "code explorer");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>tmct code explorer</title>
+<style>
+${THEME_TOKENS_CSS}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--ink); font-family: ${SERIF_STACK}; }
+header { display: flex; align-items: baseline; gap: 1rem; flex-wrap: wrap; padding: 0.8rem 1.1rem; border-bottom: 1px solid var(--line); }
+header h1 { font-size: 1.05rem; margin: 0; font-weight: 600; }
+header .sub { color: var(--muted); font-size: 0.85rem; }
+header .pickers { margin-left: auto; display: flex; gap: 0.5rem; }
+button { font: inherit; cursor: pointer; }
+button:disabled { cursor: default; opacity: 0.5; }
+.pickers button { background: var(--card); color: var(--ink); border: 1px solid var(--line); border-radius: 6px; padding: 0.35rem 0.7rem; font-size: 0.85rem; }
+#stats { padding: 0.4rem 1.1rem; color: var(--muted); font-size: 0.8rem; font-family: ${MONO_STACK}; border-bottom: 1px solid var(--line); }
+main { display: grid; grid-template-columns: minmax(0, 1.7fr) minmax(260px, 1fr); gap: 0; align-items: stretch; }
+@media (max-width: 720px) { main { grid-template-columns: 1fr; } }
+.ledger-pane { padding: 0.6rem 1.1rem 2rem; min-height: 60vh; }
+.rail { border-left: 1px solid var(--line); padding: 0.6rem 1rem 2rem; display: flex; flex-direction: column; gap: 1rem; }
+h2 { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin: 0 0 0.4rem; }
+ul.rows { list-style: none; margin: 0; padding: 0; }
+.row { padding: 0.28rem 0.4rem; border-radius: 5px; font-size: 0.95rem; line-height: 1.5; }
+.row-focus { background: var(--corpus-soft); }
+.row.muted, .muted { color: var(--muted); }
+.term { background: none; border: none; padding: 0; color: var(--corpus); font-family: ${MONO_STACK}; font-size: 0.85rem; text-decoration: underline; text-decoration-color: var(--line); }
+.term:hover { text-decoration-color: var(--corpus); }
+.verb { color: var(--muted); }
+.hints { display: flex; flex-direction: column; gap: 0.35rem; }
+.hint { text-align: left; background: var(--card); border: 1px solid var(--line); border-radius: 6px; padding: 0.35rem 0.55rem; font-size: 0.85rem; color: var(--ink); }
+.hint:hover { border-color: var(--corpus); }
+.dock { display: flex; flex-direction: column; gap: 0.4rem; }
+#chat-log { display: flex; flex-direction: column; gap: 0.4rem; max-height: 40vh; overflow-y: auto; }
+.turn { font-size: 0.9rem; line-height: 1.45; }
+.turn .who { display: block; font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted); }
+.turn-you .said { color: var(--ink); }
+.turn-tmct .said { color: var(--taught); white-space: pre-wrap; }
+#chat-form { display: flex; gap: 0.4rem; }
+#chat-input { flex: 1; font: inherit; padding: 0.4rem 0.5rem; border: 1px solid var(--line); border-radius: 6px; background: var(--card); color: var(--ink); }
+#chat-form button { background: var(--corpus); color: #fff; border: none; border-radius: 6px; padding: 0.4rem 0.8rem; }
+#dock-note { color: var(--muted); font-size: 0.78rem; }
+.focus-line { font-family: ${MONO_STACK}; font-size: 0.85rem; }
+</style>
+</head>
+<body>
+<header>
+  <h1>tmct code explorer</h1>
+  <span class="sub">source: <span id="source-name">${escapeHtml(sourceName)}</span></span>
+  <div class="pickers">
+    <button id="open-graph">Open graph…</button>
+    <button id="open-repo">Open repo…</button>
+  </div>
+</header>
+<div id="stats"></div>
+<main>
+  <section class="ledger-pane">
+    <h2>Facts around <span class="focus-line" id="focus-name">—</span></h2>
+    <ul class="rows" id="ledger"></ul>
+  </section>
+  <aside class="rail">
+    <div>
+      <h2>Try asking</h2>
+      <div class="hints" id="hints"></div>
+    </div>
+    <div class="dock">
+      <h2>Chat</h2>
+      <div id="chat-log"></div>
+      <form id="chat-form">
+        <input id="chat-input" type="text" autocomplete="off" placeholder="ask about this graph…">
+        <button type="submit">Ask</button>
+      </form>
+      <div id="dock-note"></div>
+    </div>
+  </aside>
+</main>
+<script>window.__CODE_EXPLORER__ = Object.assign({ payload: ${payloadJson} }, ${dataJson});</script>
+${winkLoaderInline ? `<script>\n${embedScriptText(winkLoaderInline)}\n</script>` : ""}
+${bundleInline ? `<script>\n${embedScriptText(bundleInline)}\n</script>` : ""}
+${bundleAvailable && !bundleInline ? `<script src="./code-explorer.bundle.js"></script>` : ""}
+<script>
+${embedScriptText(CLIENT_JS)}
+</script>
+</body>
+</html>`;
+}