@polycode-projects/the-mechanical-code-talker 2.8.0 → 2.8.1

package/README.md

@@ -120,10 +120,11 @@ tmct> /exit
 
 **[Try it live in your browser →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/)**
 is a real, interactive chat demo running client-side. Your browser runs the
-actual query engine against a small example codebase, no server, no install.
-The page leads with the **memory ledger**: every fact as a readable sentence,
-drill by clicking the terms inside them, and an in-page chat whose answers
-focus the ledger.
+actual query engine, no server, no install. The page opens with a live chat
+you can talk to directly, then embeds the **memory ledger** (every fact as a
+readable sentence, drill by clicking the terms inside them), a Towers-of-Hanoi
+plan replayed move by move, and the two live games above — spider-fly and the
+text adventure — each with a link to open it full-screen.
 
 From a clone, two build scripts regenerate that demo so you can check it
 offline before it deploys. The example graph, the ledger page, and the
@@ -183,7 +184,7 @@ resolves to a real graph traversal or declines cleanly:
   (*because/although/while*), conditionals, and false-premise flags ("why
   does X still import Y" when it no longer does).
 
-The full catalog with measured coverage lives in `CAPABILITIES_2.0.3.md` and
+The full catalog with measured coverage lives in `CAPABILITIES_2.7.12.md` and
 the `BENCHMARK_*.md` reports.
 
 **Response finishing.** Before an answer prints, it is segmented into typed
@@ -371,7 +372,7 @@ the plan as a self-contained animated page (see "Two more surfaces" above).
 
 ## Play a game with it
 
-Two games run inside an ordinary chat session, no setup.
+Three games run inside an ordinary chat session, no setup.
 
 **Guess the number.** Say `I'm thinking of a number between 1 and 100` and
 tmct guesses by narrowing an interval — answer `higher`, `lower`, or
@@ -393,6 +394,19 @@ a blocked action declines by name, and one of the household moves on its own
 schedule whether you are there to see it or not. The full worked mystery is
 pinned step by step in `test/corpus/games/adventure.jsonl`.
 
+**Two agents, planning against each other.** Say `play spider and fly` (or
+`watch the spider and the fly`) and tmct runs both sides itself — neither is
+player-controlled. A spider hunts a fly across a 10×10 web; each side only
+believes what it can currently see (`vision_radius`, tunable), a fly wanders
+when nothing threatens it and evades when something does, a spider avoids
+other spiders, chases what it believes it sees, and builds a web when it
+holds position. Mass is real: both sides waste away each turn they don't
+eat, and a spider gains exactly the mass of what it catches. You can address
+either side directly (`@spider the fly is east`) to feed it a belief — true
+or false — and watch a wrong assertion mislead it for as long as the real
+target stays out of sight. `tmct.toml`'s `[games.spider-fly]` table tunes
+every rate; the full mechanic is pinned in `test/corpus/games/spider-fly.jsonl`.
+
 ## Learning on a miss
 
 A question tmct cannot ground is still an honest miss — but on the cleanest
@@ -1035,18 +1049,18 @@ service. The LLM agent stays outside tmct, as the no-LLM ethos requires.
 
 ## Measuring it
 
-What the 2.0.3 cycle measured, on 2026-07-16. Each figure links to its method
-and carries, in the same row, the caveat that changes what it means. The full
-tables, judge scores, and transcripts are in the linked write-ups.
+What the 2.7.11/2.7.12 cycle measured, on 2026-07-19. Each figure links to its
+method and carries, in the same row, the caveat that changes what it means.
+The full tables, judge scores, and transcripts are in the linked write-ups.
 
-| What it does | Result (2.0.3) | Read the number with this | Method |
+| What it does | Result (2.7.12) | Read the number with this | Method |
 |---|---|---|---|
-| Multi-hop entailment | 219/219 chat cases and 80/80 kernel cases, 0% fabrication, all six bands pass | 50 of the 219 greens (23%) are graded against a declared floor, not the classical answer. INF-C2's 20/20 grades that the engine answers contradictory memory without fabricating, never that it detects the clash. | `BENCHMARK_INFERENCE_2.0.3.md` |
-| Tool-call planning | 56/56 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. All 11 C2 cases pass, so the ladder now has more headroom than the case set exercises. | `BENCHMARK_AGENT_2.0.3.md` |
-| Groundedness | Every answer carries a source, and an empty graph reports itself empty (`bootstrap-empty` 2.000/2). Judge-scored groundedness 1.857/2 over 98 cases. | The 1.857 is judged (`claude-haiku-4-5-20251001`, `judge-prompt-v1`) at N=1 over 9 of 23 construction shapes, so read it as indicative. The judge runs in the offline eval harness, never in the product. | `BENCHMARK_CEFR_ENGLISH_2.0.3.md` |
-| Abstention (the honest miss) | 0% fabrication across 299 inference rows and 0% hallucination across 168 agent rows | Structural, not a tuned threshold. tmct abstains because nothing matched, so the rows test a property of a no-model design rather than a score. | `BENCHMARK_INFERENCE_2.0.3.md`, `BENCHMARK_AGENT_2.0.3.md` |
-| Determinism | Byte-identical on rerun, 0 verdict changes across 299 inference rows against the prior cycle, a 109-case replay in 877ms at $0 per turn | A property of the no-model pipeline. | `BENCHMARK_INFERENCE_2.0.3.md`, `CAPABILITIES_2.0.3.md` |
-| Dialogue robustness (role and polarity) | An adversarial persona sweep could not force a single role or polarity inversion in 55 probes — active/passive, forward/reverse, negation and the converse trap all compiled to the correct canonical shape | The same five-frame sweep (~200 probes) surfaced 25 dialogue dead-ends, eight of them confidently wrong, all from words dropped before the parser rather than from the reasoning. | `BENCHMARK_CONVERSATION_2.0.3.md` |
+| Multi-hop entailment | 379/379 chat cases and 100/100 kernel cases, 0% fabrication, all bands pass | The case set is unchanged from 2.6.0 (same templates, same counts) — the one real move this cycle is INF-4's ceiling-graded count dropping 35→30, five cases that now pass as genuine capability instead of against the declared honest-miss floor. | `BENCHMARK_INFERENCE_2.7.12.md` |
+| Tool-call planning | 68/68 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. 2.6.0 gated at TOOL-7 (62/66, 94%) — this cycle's router uplift (a guarded RECOVER step, a tied-candidate composer) cleared it, a real capability move, not a ruler change. | `BENCHMARK_AGENT_2.7.12.md` |
+| Groundedness | Every answer carries a source, and an empty graph reports itself empty. Judge-scored mean 1.809/2 over 138 cases, 5 hard fails, 136/138 tier-1. | Judged (`claude-haiku-4-5-20251001`, `judge-prompt-v2`) at N=1. The judge prompt moved v1→v2 since 2.6.0, so this is a measurement, not a clean lever comparison against the prior cycle. The judge runs in the offline eval harness, never in the product. | `BENCHMARK_CEFR_ENGLISH_2.7.12.md` |
+| Abstention (the honest miss) | 0% fabrication across 479 inference rows (379 chat + 100 kernel) and 0% hallucination across 272 agent rows | Structural, not a tuned threshold. tmct abstains because nothing matched, so the rows test a property of a no-model design rather than a score. | `BENCHMARK_INFERENCE_2.7.12.md`, `BENCHMARK_AGENT_2.7.12.md` |
+| Determinism | Byte-identical on rerun — a 379-case `--replay` clean across 2 runs, no LLM, no network, $0 per turn | A property of the no-model pipeline. | `BENCHMARK_INFERENCE_2.7.12.md` |
+| Dialogue robustness (persona sweep) | A 6-persona sweep (textbook logician, casual newcomer, new developer, adversarial sceptic, returning user, planning user) fixed 25 of the prior cycle's 29 routed findings (21 clean, 4 with a residual noted); 4 remain broken, 2 in a shape distinct from the original complaint | Free exploration across all six personas surfaced roughly 60 fresh findings beyond the ratchet check — the single highest-signal pattern: tmct's own suggested repair text was itself frequently broken when followed verbatim (since fixed, see `HANDOVER.md`). | `BENCHMARK_CONVERSATION_2.7.11.md` |
 
 Three offline benchmark rigs live in a clone (they are not in the npm
 package). Each replays a committed case set through the real product and

package/corpus/tier2/generate.mjs

@@ -665,6 +665,7 @@ export const CORPUSES = {
       ["hope", "/r/IsA", "emotion"], ["hope", "/r/CapableOf", "inspire_action"],
       ["surprise", "/r/IsA", "emotion"], ["surprise", "/r/CapableOf", "cause_astonishment"],
       ["pride", "/r/IsA", "emotion"], ["pride", "/r/CapableOf", "bring_satisfaction"],
+      ["sad", "/r/IsA", "emotion"],
       ["name", "/r/UsedFor", "identifying_a_person"], ["name", "/r/PartOf", "identity"],
       ["song", "/r/HasA", "word"], ["song", "/r/UsedFor", "entertaining"],
       ["music", "/r/HasA", "song"], ["music", "/r/CapableOf", "bring_joy"],

package/corpus/tier2/human.jsonl

@@ -622,6 +622,7 @@
 {"start":"/c/en/surprise","rel":"/r/CapableOf","end":"/c/en/cause_astonishment","weight":1,"surfaceText":"[[surprise]] CapableOf [[cause astonishment]]"}
 {"start":"/c/en/pride","rel":"/r/IsA","end":"/c/en/emotion","weight":1,"surfaceText":"[[pride]] IsA [[emotion]]"}
 {"start":"/c/en/pride","rel":"/r/CapableOf","end":"/c/en/bring_satisfaction","weight":1,"surfaceText":"[[pride]] CapableOf [[bring satisfaction]]"}
+{"start":"/c/en/sad","rel":"/r/IsA","end":"/c/en/emotion","weight":1,"surfaceText":"[[sad]] IsA [[emotion]]"}
 {"start":"/c/en/name","rel":"/r/UsedFor","end":"/c/en/identifying_a_person","weight":1,"surfaceText":"[[name]] UsedFor [[identifying a person]]"}
 {"start":"/c/en/name","rel":"/r/PartOf","end":"/c/en/identity","weight":1,"surfaceText":"[[name]] PartOf [[identity]]"}
 {"start":"/c/en/song","rel":"/r/HasA","end":"/c/en/word","weight":1,"surfaceText":"[[song]] HasA [[word]]"}

package/corpus/tier2/manifest.json

@@ -67,9 +67,9 @@
         "tool": "corpus/tier2/generate.mjs"
       },
       "file": "human.jsonl",
-      "facts": 664,
-      "bytes": 81430,
-      "sha256": "040e6d1f6761a29a080f7825ff8aae60caf879125c1f7a1480340ef04129bcd5",
+      "facts": 665,
+      "bytes": 81540,
+      "sha256": "7710c88c4c96a73fbbae19fe1989b0be40fed5ed40205016e90cc221bcb79607",
       "license": "MPL-2.0"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "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.",

package/src/adapters/corpus/sprite-large-template-files.mjs

@@ -23,6 +23,7 @@ import { fileURLToPath } from "node:url";
 import { join, dirname } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { expandMaterialReferences } from "../../domain/sprite-materials.mjs";
+import { expandExpressionReferences } from "../../domain/sprite-expressions.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 /** The sprite-tier template directory (data, not code) — every *.toml file
@@ -41,7 +42,10 @@ export const SPRITE_LARGE_TEMPLATES_DIR = join(HERE, "..", "..", "..", "data", "
  *  never go blank because one hand-authored sprite has a typo.
  *  test/adapters/sprite-large-template-files.test.mjs parses the real files
  *  directly (not through this lenient loader) so a broken file still fails a
- *  test loudly. */
+ *  test loudly. Material references expand first, expression references
+ *  second — the two indirections are independent (a template can carry
+ *  either, both, or neither) so the order between them never matters to the
+ *  result, only that both run before a template reaches a caller. */
 export function readSpriteLargeTemplateFiles(dir = SPRITE_LARGE_TEMPLATES_DIR) {
   let files;
   try {
@@ -58,5 +62,5 @@ export function readSpriteLargeTemplateFiles(dir = SPRITE_LARGE_TEMPLATES_DIR) {
       continue; // one malformed file never takes the others down
     }
   }
-  return expandMaterialReferences(templates);
+  return expandExpressionReferences(expandMaterialReferences(templates));
 }

package/src/domain/sprite-expressions.mjs

@@ -0,0 +1,120 @@
+// sprite-expressions.mjs — the shared face-fragment scheme the sprite tier's
+// mgx:feels parameter draws from, one small dot/curve-eyes-plus-mouth
+// drawing per curated emotion word, mirroring sprite-materials.mjs's own
+// by-name-reference shape exactly: a frozen palette of raw treatment data,
+// and a pure expand function that turns a short by-name reference in a
+// template's own [parameters.emotion.values] table into the full
+// substitution — so a face fragment is authored ONCE here and referenced by
+// name from every data/sprites-large/*-with-emotion.toml file, rather than
+// six-plus files each hand-copying the same eyes-and-mouth paths.
+//
+// The one real difference from a material treatment: a hex triple needs no
+// context to drop into a template's placeholder, but a face fragment does —
+// classes vary enough in head geometry (a dog's head circle is
+// cx=7 cy=9 r=3.6, a cat's is cx=9 cy=9.4 r=4.4, a person's is
+// cx=12 cy=6.6 r=3.3) that one universal anchor position would misplace the
+// eyes on at least one of them. So EXPRESSION_PALETTE's own fragments are
+// authored in a UNIT face — eyes and mouth drawn as if the head were a
+// radius-1 circle centred on the origin — and expandExpressionReferences
+// wraps the matched fragment in `<g transform="translate({cx} {cy})
+// scale({scale})">` using the SAME template's own required `[face]` table
+// (cx/cy/scale) to place and size it for that one class's real head. A
+// template with a [parameters.emotion] table but no [face] table is left
+// unexpanded (spriteTemplateProblems flags the pairing as a real problem —
+// see sprite-templates.mjs — this function itself stays defensive, never
+// throws on a malformed template).
+//
+// Every fragment uses a fixed dark ink colour rather than currentColor —
+// a face needs to read against ANY body fill (a gold lamp's flame stays a
+// fixed amber for the same reason: what the face/flame looks like doesn't
+// come from what the body is made of or coloured).
+//
+// Convention for every future `*-with-emotion.toml` file (content-authoring
+// agents: read this before copying the shape) — `{{FACE}}` is always the
+// LAST child before `</svg>`, so the resolved face fragment paints over
+// the body/highlight shapes beneath it, never the reverse.
+
+/** The dark ink colour every face fragment draws its eyes/mouth in,
+ *  regardless of the sprite's own body fill — the same fixed-colour
+ *  reasoning lamp.toml's flame already uses (sprite-templates.mjs's own
+ *  header explains the precedent). */
+const FACE_INK = "#000000";
+
+/** One `<g>`-ready fragment per curated emotion word, dot/curve eyes plus a
+ *  mouth curve, authored in a unit face (radius 1, centred on the origin) —
+ *  expandExpressionReferences positions and scales it per class. Distinct
+ *  by more than mouth curvature alone: scared/surprised both open wide, but
+ *  scared's mouth stays a small tense "o" while surprised's is a large
+ *  dropped-jaw oval; calm's eyes are closed contented arcs where happy's
+ *  are open dots, so no two of the six collapse into the same read at a
+ *  glance. */
+export const EXPRESSION_PALETTE = Object.freeze({
+  happy:
+    `<circle cx="-0.4" cy="-0.15" r="0.11" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.4" cy="-0.15" r="0.11" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<path d="M -0.4 0.35 Q 0 0.68 0.4 0.35" fill="none" stroke="${FACE_INK}" stroke-width="0.09" stroke-linecap="round" opacity="0.85"/>`,
+  sad:
+    `<circle cx="-0.4" cy="-0.1" r="0.1" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.4" cy="-0.1" r="0.1" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<path d="M -0.38 0.55 Q 0 0.3 0.38 0.55" fill="none" stroke="${FACE_INK}" stroke-width="0.09" stroke-linecap="round" opacity="0.85"/>`,
+  angry:
+    `<path d="M -0.58 -0.32 L -0.22 -0.16" stroke="${FACE_INK}" stroke-width="0.09" stroke-linecap="round" opacity="0.85"/>`
+    + `<path d="M 0.58 -0.32 L 0.22 -0.16" stroke="${FACE_INK}" stroke-width="0.09" stroke-linecap="round" opacity="0.85"/>`
+    + `<circle cx="-0.32" cy="-0.02" r="0.09" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.32" cy="-0.02" r="0.09" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<path d="M -0.36 0.5 L 0.36 0.42" stroke="${FACE_INK}" stroke-width="0.1" stroke-linecap="round" opacity="0.85"/>`,
+  scared:
+    `<circle cx="-0.4" cy="-0.12" r="0.2" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`
+    + `<circle cx="-0.4" cy="-0.12" r="0.07" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.4" cy="-0.12" r="0.2" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`
+    + `<circle cx="0.4" cy="-0.12" r="0.07" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0" cy="0.42" r="0.09" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`,
+  surprised:
+    `<circle cx="-0.38" cy="-0.12" r="0.17" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`
+    + `<circle cx="-0.38" cy="-0.12" r="0.06" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.38" cy="-0.12" r="0.17" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`
+    + `<circle cx="0.38" cy="-0.12" r="0.06" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<ellipse cx="0" cy="0.42" rx="0.16" ry="0.22" fill="${FACE_INK}" opacity="0.7"/>`,
+  calm:
+    `<path d="M -0.5 -0.1 Q -0.4 -0.2 -0.3 -0.1" fill="none" stroke="${FACE_INK}" stroke-width="0.08" stroke-linecap="round" opacity="0.85"/>`
+    + `<path d="M 0.3 -0.1 Q 0.4 -0.2 0.5 -0.1" fill="none" stroke="${FACE_INK}" stroke-width="0.08" stroke-linecap="round" opacity="0.85"/>`
+    + `<path d="M -0.3 0.4 Q 0 0.5 0.3 0.4" fill="none" stroke="${FACE_INK}" stroke-width="0.08" stroke-linecap="round" opacity="0.85"/>`,
+});
+
+/** The mgx:feels property name every emotion-bearing template's
+ *  `[parameters.emotion]` table names — sprite-templates.mjs never needs
+ *  to know this constant exists (it reads `param.property` generically),
+ *  this module only uses it to recognise which parameter table is ITS OWN
+ *  to expand, the same role sprite-materials.mjs's `param.placeholders`
+ *  shape check plays for a material table. */
+const FEELS_PROPERTY = "mgx:feels";
+
+/**
+ * Every `[parameters.emotion].values` string entry, in every template,
+ * expanded from a curated emotion-word KEY (e.g. "happy") to the full
+ * `<g transform="translate(cx cy) scale(scale)">…</g>` substitution for
+ * THIS template's own required `[face]` table — but only for a template
+ * whose `[parameters.emotion]` table names `mgx:feels` as its property
+ * (sprite-templates.mjs's `param.property`) and that also carries a
+ * `[face]` table; a template missing either is left alone (defensive, never
+ * throws — spriteTemplateProblems is what flags that pairing as a real
+ * authoring mistake). A values entry naming no known palette word is left
+ * as the plain string it was, the same never-guess posture
+ * expandMaterialReferences already uses for an unknown treatment name.
+ * Pure; `templates` is read only.
+ */
+export function expandExpressionReferences(templates, palette = EXPRESSION_PALETTE) {
+  return (templates || []).map((t) => {
+    const emotion = t?.parameters?.emotion;
+    if (!emotion?.property || emotion.property !== FEELS_PROPERTY) return t;
+    if (!emotion.placeholder || !emotion.values || !t.face) return t;
+    const { cx, cy, scale } = t.face;
+    const values = {};
+    for (const [key, value] of Object.entries(emotion.values)) {
+      values[key] = typeof value === "string" && palette[value]
+        ? `<g transform="translate(${cx} ${cy}) scale(${scale})">${palette[value]}</g>`
+        : value;
+    }
+    return { ...t, parameters: { ...t.parameters, emotion: { ...emotion, values } } };
+  });
+}

package/src/domain/sprite-templates.mjs

@@ -96,20 +96,31 @@ function fillFromValue(svg, param, value) {
   return null;
 }
 
-/** Fill a parameterized template's `svg` from the first of its own
- *  `[parameters.*]` whose observed property value maps to a substitution —
- *  or null when no property fact names a mapped value (never a guess). */
-function parameterizedFill(template, propertyFacts) {
+/** Fill a parameterized template's `svg` from EVERY one of its own
+ *  `[parameters.*]` whose observed property value maps to a substitution,
+ *  accumulating each successful fill onto the RUNNING svg string rather
+ *  than stopping at the first hit — so a template declaring both e.g.
+ *  `[parameters.material]` and `[parameters.emotion]` fills both dimensions
+ *  in one pass, one parameter's substitution never undoing another's.
+ *  Returns null when not even one parameter filled (never a guess, and
+ *  never a half-filled template with a leftover placeholder token) — the
+ *  caller (resolveAtTerm) falls through to a less specific template exactly
+ *  as it did before this function tried more than one dimension. */
+function parameterizedFillAll(template, propertyFacts) {
+  let svg = template.svg;
+  let filledCount = 0;
   for (const param of Object.values(template.parameters || {})) {
     const values = param?.values || {};
     const hit = (propertyFacts || []).find(
       (f) => f.predicate === param.property && Object.prototype.hasOwnProperty.call(values, f.object),
     );
     if (!hit) continue;
-    const filled = fillFromValue(template.svg, param, values[hit.object]);
-    if (filled) return filled;
+    const filled = fillFromValue(svg, param, values[hit.object]);
+    if (!filled) continue;
+    svg = filled;
+    filledCount += 1;
   }
-  return null;
+  return filledCount > 0 ? svg : null;
 }
 
 /** Resolve ONE class term (no ancestor walk here — the caller repeats this
@@ -123,7 +134,7 @@ function resolveAtTerm(term, propertyFacts, templates) {
   if (matched) return matched.svg;
   for (const t of candidates) {
     if (t.match || !t.parameters) continue;
-    const filled = parameterizedFill(t, propertyFacts);
+    const filled = parameterizedFillAll(t, propertyFacts);
     if (filled) return filled;
   }
   const plain = candidates.find((t) => !t.match && !t.parameters);
@@ -174,7 +185,12 @@ export function resolveSpriteAsset(className, factRows, propertyFacts, templates
  *  names a `property` and exactly one of `placeholder`/`placeholders` (every
  *  token named appears in `svg`), its `values` map is non-empty and every
  *  entry matches the shape its own `placeholder`/`placeholders` choice
- *  expects, and a `[match]` table names both `property` and `value`. */
+ *  expects, a `[match]` table names both `property` and `value`, and
+ *  `[face]`/`[parameters.emotion]` are always declared TOGETHER — a face
+ *  anchor with nothing to select it, or an emotion parameter with nowhere to
+ *  position its face fragment, is a real authoring mistake either way
+ *  (sprite-expressions.mjs's own header explains why the face fragment
+ *  needs the pairing). */
 export function spriteTemplateProblems(template) {
   const problems = [];
   const t = template || {};
@@ -218,5 +234,11 @@ export function spriteTemplateProblems(template) {
   if (t.match && (!t.match.property || t.match.value === undefined)) {
     problems.push("match is missing property or value");
   }
+  if (t.face && !t.parameters?.emotion) {
+    problems.push("face is declared without parameters.emotion — a face anchor with nothing to select it is dead data");
+  }
+  if (t.parameters?.emotion && !t.face) {
+    problems.push("parameters.emotion is declared without a face — an emotion parameter needs its own [face] anchor to position the fragment it fills");
+  }
   return problems;
 }

package/src/services/chat-page-viz.mjs

@@ -0,0 +1,398 @@
+// chat-page-viz.mjs — "Talk to it"'s full-screen destination
+// (PLAN_GAMES_UPLIFT_V3.md Part C.4 item 1): a self-contained document shaped
+// exactly like spider-fly-viz.mjs/adventure-viz.mjs's own page-builders — one
+// inlined <style> importing viz-theme.mjs's shared tokens, behaviour as an
+// inlined IIFE — reusing the SAME chat engine the home page's embedded
+// #tmct-chat widget runs (chat-browser.bundle.js's globalThis.tmctChat,
+// chat-seed.json, public/reference-pack/), referenced by the same same-origin
+// relative paths chat-ui.mjs already uses. This module does not import or
+// re-render chat-ui.mjs — it is a second, independent consumer of the same
+// engine/bundle, the same relationship spider-fly-viz.mjs's own inlined chat
+// dock already has with createSpiderFlySession (both call the shared
+// session.turn(line), neither reimplements it).
+//
+// What's actually new here, versus the embedded widget: full-screen
+// post-ChatGPT-style chrome (centered message column, bottom-fixed composer,
+// message bubbles) and this page's own signature element — a quiet
+// per-message PROVENANCE CHIP (taught / corpus / entailed) next to every
+// grounded answer, tmct's actual differentiator versus an LLM chatbot. The
+// chip is read straight off the SAME "(source: ...)" citation chat.mjs's own
+// factPhrase/renderFactLine convention already appends to most answers (see
+// e.g. `dog is a kind of animal (source: corpus:conceptnet ...)` — already
+// asserted by e2e/pages-chat.test.mjs against the embedded widget), never a
+// second provenance computation against memory internals: `provBucketFor`
+// (ledger-viz.mjs) is spliced in unmodified and applied to whatever citation
+// text the answer already carries, so this page's chip and the ledger's own
+// per-row color always agree by construction. A miss carries no citation and
+// gets no chip — the absence IS the signal, matching the product's own
+// honest-miss posture rather than inventing a fourth "trust tier" to badge it.
+//
+// renderChatHtml() is pure: no I/O, deterministic output for identical
+// input. scripts/build-demo-site.mjs calls it directly and writes the result
+// to public/chat.html, after chat-browser.bundle.js/chat-seed.json already
+// exist (both built earlier in that same script, for the embedded widget).
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml } from "./viz-theme.mjs";
+import { provBucketFor } from "./ledger-viz.mjs";
+
+const DEFAULT_TITLE = "tmct — talk to it";
+
+// Reads left-to-right as the reader meets each tier: what you taught it
+// directly, what its bundled corpus already knew, what it worked out itself.
+// Mirrors ledger-viz.mjs's own PROVS legend labels verbatim, so the same
+// three words mean the same thing on both pages.
+const PROV_LEGEND = [
+  ["taught", "you taught"],
+  ["corpus", "corpus"],
+  ["entailed", "entailed"],
+];
+
+/** This page's own tiny CSS-class fold — ledger-viz.mjs's `--entail` CSS
+ *  custom property (viz-theme.mjs's own token name) is one letter short of
+ *  the "entailed" bucket provBucketFor returns; every other tier's token name
+ *  already matches its bucket name exactly. */
+function provKey(tier) {
+  return tier === "entailed" ? "entail" : tier;
+}
+
+/**
+ * The chip tier for one chat turn — "taught" | "corpus" | "entailed" | null
+ * (no chip: a miss, or an answer that grounds in nothing citable, e.g. /help
+ * output or a focus-set confirmation).
+ *
+ * Reads the SAME "(source: ...)" citation(s) the visible answer text already
+ * carries, via `bucketFor` (the page's own spliced copy of ledger-viz.mjs's
+ * `provBucketFor`, injected rather than imported so this function stays
+ * `.toString()`-splice safe — the same discipline spider-fly-viz.mjs's own
+ * `threadCellsForSpiderPlan` holds its own injected `geometry` to).
+ * `provBucketFor`'s fallback branch (empty sourceTypes) classifies a raw
+ * legacy provenance TAG string directly — exactly the string chat.mjs embeds
+ * after "(source: " (memory/trust.mjs's `provenanceTagToSource` parses the
+ * identical shape) — so no Fact/individuals lookup is needed here at all.
+ *
+ * A teach-lane confirmation ("noted — remembered: ...") cites no fact yet to
+ * read back — nothing has been asked of it — so its own `record.via ===
+ * "assert"` stands in for a citation: the user just taught this, "taught" is
+ * the whole point of the reply.
+ *
+ * Multiple citations (a multi-step proof chain) resolve by the same
+ * taught-over-entailed-over-corpus precedence provBucketFor's own header
+ * documents for one fact's sourceTypes, applied across citations instead:
+ * a chain resting on any taught premise reads as "taught" overall.
+ *
+ * Self-contained (no outer refs beyond the injected `bucketFor`),
+ * `.toString()`-splice safe.
+ */
+export function provenanceChipFor(answer, record, bucketFor) {
+  if (!record || record.miss) return null;
+  const cites = [...String(answer || "").matchAll(/\(source: ([^)]+)\)/g)].map((m) => m[1]);
+  if (!cites.length) return record.via === "assert" ? "taught" : null;
+  const buckets = cites.map((c) => bucketFor([], c));
+  if (buckets.includes("taught")) return "taught";
+  if (buckets.includes("entailed")) return "entailed";
+  return "corpus";
+}
+
+/** The self-contained "talk to it" full-screen page. Pure — the same output
+ *  for the same `title` every time; every other piece of state (the session,
+ *  every message, every chip) is computed live in the browser once the
+ *  sibling chat bundle loads, exactly as the embedded widget already works. */
+export function renderChatHtml({ title = DEFAULT_TITLE } = {}) {
+  const legendHtml = PROV_LEGEND.map(
+    ([key, label]) => `<span class="legend-item"><i class="dot dot-${provKey(key)}"></i>${escapeHtml(label)}</span>`,
+  ).join("");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+${THEME_TOKENS_CSS}
+  html, body { height: 100%; }
+  body { margin: 0; background: var(--bg); color: var(--ink); font-family: ${SERIF_STACK}; font-size: 16px; line-height: 1.5; display: flex; flex-direction: column; overflow: hidden; }
+  .mono { font-family: ${MONO_STACK}; }
+  button { font: inherit; color: inherit; background: none; cursor: pointer; border: none; }
+  button:focus-visible, input:focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
+  a { color: var(--corpus); }
+
+  .topbar { flex: 0 0 auto; display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; padding: .7rem 1.1rem; border-bottom: 1px solid var(--line); flex-wrap: wrap; }
+  .brand { display: flex; align-items: baseline; gap: .55rem; }
+  .eyebrow { font-family: ${MONO_STACK}; font-size: .68rem; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); }
+  .topbar h1 { font-size: 1.05rem; margin: 0; font-weight: 600; }
+  .legend { display: flex; gap: .8rem; font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); }
+  .legend-item { display: inline-flex; align-items: center; gap: .32rem; white-space: nowrap; }
+  .dot { width: 7px; height: 7px; border-radius: 50%; display: inline-block; }
+  .dot-taught { background: var(--taught); } .dot-corpus { background: var(--corpus); } .dot-entail { background: var(--entail); }
+
+  main.chatMain { flex: 1 1 auto; overflow-y: auto; overscroll-behavior: contain; }
+  .messages { max-width: 720px; margin: 0 auto; padding: 1.2rem 1rem 1.6rem; display: flex; flex-direction: column; gap: .15rem; min-height: 100%; }
+
+  .msg-row { display: flex; flex-direction: column; margin: .35rem 0; max-width: 100%; }
+  .msg-row.user { align-items: flex-end; }
+  .msg-row.assistant { align-items: flex-start; }
+  .msg-row.system { align-items: center; margin: .6rem 0; }
+
+  .bubble { max-width: 80%; padding: .55rem .85rem; border-radius: 16px; white-space: pre-wrap; word-break: break-word; }
+  .bubble.user { background: var(--ink); color: var(--bg); border-bottom-right-radius: 4px; }
+  .bubble.user .prompt { opacity: .6; font-family: ${MONO_STACK}; font-size: .82em; }
+  .bubble.assistant { background: var(--card); border: 1px solid var(--line); border-bottom-left-radius: 4px; }
+  .bubble.assistant.pending { color: var(--muted); font-style: italic; }
+  .bubble.assistant.miss { color: var(--muted); border-style: dashed; }
+  .bubble.system { max-width: 100%; background: none; border: none; color: var(--muted); font-family: ${MONO_STACK}; font-size: .76rem; text-align: center; padding: .2rem .5rem; }
+
+  .provchip { align-self: flex-start; margin: .28rem 0 0 .15rem; font-family: ${MONO_STACK}; font-size: .64rem; letter-spacing: .05em; text-transform: uppercase; padding: .12rem .55rem; border-radius: 99px; cursor: default; }
+  .pc-taught { color: var(--taught); background: var(--taught-soft); }
+  .pc-corpus { color: var(--corpus); background: var(--corpus-soft); }
+  .pc-entail { color: var(--entail); background: var(--entail-soft); }
+
+  form.composer { flex: 0 0 auto; border-top: 1px solid var(--line); background: var(--bg); }
+  .composer-inner { max-width: 720px; margin: 0 auto; padding: .7rem 1rem; display: flex; gap: .5rem; align-items: center; }
+  .composer-inner input { flex: 1; min-width: 0; font-family: ${SERIF_STACK}; font-size: .95rem; background: var(--card); color: var(--ink); border: 1px solid var(--line); border-radius: 20px; padding: .55rem 1rem; }
+  .composer-inner input::placeholder { color: var(--muted); }
+  .composer-inner input:disabled { opacity: .55; }
+  .composer-inner button[type="submit"] { width: 2.3rem; height: 2.3rem; border-radius: 50%; background: var(--ink); color: var(--bg); display: flex; align-items: center; justify-content: center; font-size: 1rem; flex: 0 0 auto; }
+  .composer-inner button[type="submit"]:disabled { opacity: .4; cursor: default; }
+  .statusline { max-width: 720px; margin: 0 auto; padding: 0 1.1rem .6rem; font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); }
+
+  @media (max-width: 560px) {
+    .legend { display: none; }
+    .bubble { max-width: 92%; }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    * { scroll-behavior: auto !important; }
+  }
+</style>
+</head>
+<body>
+  <header class="topbar">
+    <div class="brand">
+      <span class="eyebrow">tmct</span>
+      <h1>Talk to it</h1>
+    </div>
+    <div class="legend" aria-hidden="true">${legendHtml}</div>
+  </header>
+  <main class="chatMain">
+    <div class="messages" id="messages" role="log" aria-live="polite" aria-label="Conversation"></div>
+  </main>
+  <form class="composer" id="composer">
+    <div class="composer-inner">
+      <input id="composerInput" type="text" autocomplete="off" autocapitalize="off" spellcheck="false"
+        placeholder="loading the engine…" aria-label="Ask tmct something" disabled>
+      <button type="submit" id="composerSend" aria-label="Send" disabled>&#8594;</button>
+    </div>
+  </form>
+  <div class="statusline" id="status">loading the engine&hellip;</div>
+<script src="./chat-browser.bundle.js"></script>
+<script>
+(function () {
+  "use strict";
+  const provBucketFor = ${provBucketFor.toString()};
+  const provenanceChipFor = ${provenanceChipFor.toString()};
+  const el = (id) => document.getElementById(id);
+
+  const messagesEl = el("messages");
+  const composerForm = el("composer");
+  const inputEl = el("composerInput");
+  const sendBtn = el("composerSend");
+  const statusEl = el("status");
+
+  function scrollToEnd() {
+    messagesEl.parentElement.scrollTop = messagesEl.parentElement.scrollHeight;
+  }
+
+  function addSystemLine(text) {
+    const row = document.createElement("div");
+    row.className = "msg-row system";
+    const bubble = document.createElement("div");
+    bubble.className = "bubble system";
+    bubble.textContent = text;
+    row.appendChild(bubble);
+    messagesEl.appendChild(row);
+    scrollToEnd();
+  }
+
+  function addUserBubble(text) {
+    const row = document.createElement("div");
+    row.className = "msg-row user";
+    const bubble = document.createElement("div");
+    bubble.className = "bubble user";
+    const prompt = document.createElement("span");
+    prompt.className = "prompt";
+    prompt.textContent = "tmct> ";
+    bubble.appendChild(prompt);
+    bubble.appendChild(document.createTextNode(text));
+    row.appendChild(bubble);
+    messagesEl.appendChild(row);
+    scrollToEnd();
+    return row;
+  }
+
+  function addPendingAssistantBubble() {
+    const row = document.createElement("div");
+    row.className = "msg-row assistant";
+    const bubble = document.createElement("div");
+    bubble.className = "bubble assistant pending";
+    bubble.textContent = "thinking\\u2026";
+    row.appendChild(bubble);
+    messagesEl.appendChild(row);
+    scrollToEnd();
+    return row;
+  }
+
+  const CHIP_TITLE = {
+    taught: "you taught tmct this fact directly",
+    corpus: "grounded in tmct's bundled corpus",
+    entailed: "tmct derived this from taught facts, not read back verbatim",
+  };
+
+  function settleAssistantBubble(row, answer, record) {
+    const bubble = row.querySelector(".bubble");
+    bubble.classList.remove("pending");
+    const missed = !record || Boolean(record.miss);
+    bubble.classList.toggle("miss", missed);
+    bubble.textContent = answer;
+    const tier = provenanceChipFor(answer, record, provBucketFor);
+    if (tier) {
+      const key = tier === "entailed" ? "entail" : tier;
+      const chip = document.createElement("span");
+      chip.className = "provchip pc-" + key;
+      chip.title = CHIP_TITLE[tier] || "";
+      chip.textContent = tier;
+      row.appendChild(chip);
+    }
+    scrollToEnd();
+  }
+
+  // ---- engine boot -------------------------------------------------------
+  // Mirrors chat-ui.mjs's own boot sequence against the SAME bundle/seed/pack
+  // — a second consumer of the shared engine, not a fork of it.
+  const WINK_LOAD_TIMEOUT_MS = 8000;
+  const timeoutAfter = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(new Error(reason)), ms));
+
+  let winkStatus = "pending";
+  async function tryLoadWink() {
+    try {
+      const [{ default: winkNLP }, { default: model }] = await Promise.race([
+        Promise.all([import("wink-nlp"), import("wink-eng-lite-web-model")]),
+        timeoutAfter(WINK_LOAD_TIMEOUT_MS, "wink-nlp CDN load timed out"),
+      ]);
+      window.tmctChat.registerWinkModel(() => ({ winkNLP, model }));
+      winkStatus = "loaded";
+    } catch (err) {
+      winkStatus = "unavailable";
+      console.warn("tmct chat: wink-nlp CDN load failed, continuing without the lemma/POS tier", err);
+    }
+  }
+
+  let seedPayload = null;
+  let seedFacts = 0;
+  async function fetchSeed() {
+    try {
+      const res = await fetch("./chat-seed.json");
+      if (!res.ok) throw new Error("HTTP " + res.status);
+      seedPayload = await res.json();
+      seedFacts = (seedPayload.individuals || []).filter((i) => i.class === "Fact").length;
+    } catch (err) {
+      seedPayload = null;
+      console.warn("tmct chat: chat-seed.json unavailable — starting unseeded", err);
+    }
+  }
+  const cloneSeed = () => {
+    if (!seedPayload) return null;
+    try { return structuredClone(seedPayload); } catch { return JSON.parse(JSON.stringify(seedPayload)); }
+  };
+  function newSession() {
+    return window.tmctChat.createChatSession({ seedPayload: cloneSeed(), vocabSeeded: Boolean(seedPayload) });
+  }
+
+  let packIndexPromise = null;
+  function fetchPackIndex() {
+    if (!packIndexPromise) {
+      packIndexPromise = fetch("./reference-pack/index.json")
+        .then((res) => (res.ok ? res.json() : null))
+        .catch(() => null);
+    }
+    return packIndexPromise;
+  }
+  const fetchPackProvider = {
+    async lookup(normTerm) {
+      const index = await fetchPackIndex();
+      const id = index && index.terms ? index.terms[String(normTerm || "")] : null;
+      if (!id) return null;
+      try {
+        const res = await fetch("./reference-pack/articles/" + id + ".json");
+        return res.ok ? await res.json() : null;
+      } catch {
+        return null;
+      }
+    },
+  };
+
+  function renderStatus() {
+    const seedPart = seedPayload
+      ? "starter memory: " + seedFacts + " facts"
+      : "starter memory unavailable — starting empty";
+    const winkPart = winkStatus === "loaded"
+      ? "wink-nlp lemma/POS tier: loaded"
+      : winkStatus === "unavailable"
+        ? "wink-nlp unavailable — curated + fuzzy tiers only (still zero guesses, zero LLM)"
+        : "wink-nlp: loading\\u2026";
+    statusEl.textContent = seedPart + " \\u00b7 " + winkPart;
+  }
+
+  let busy = true;
+  function setBusy(v) {
+    busy = v;
+    const ready = Boolean(window.tmctChatSession);
+    inputEl.disabled = v || !ready;
+    sendBtn.disabled = v || !ready;
+  }
+
+  composerForm.addEventListener("submit", (e) => {
+    e.preventDefault();
+    const q = inputEl.value.trim();
+    if (!q || busy || !window.tmctChatSession) return;
+    inputEl.value = "";
+    addUserBubble(q);
+    const pendingRow = addPendingAssistantBubble();
+    setBusy(true);
+    window.tmctChatSession.turn(q)
+      .then((result) => settleAssistantBubble(pendingRow, result.answer, result.record))
+      .catch((err) => settleAssistantBubble(pendingRow,
+        "something went wrong answering that (" + (err && err.message ? err.message : err) + ") \\u2014 try rephrasing",
+        { miss: true }))
+      .finally(() => {
+        setBusy(false);
+        inputEl.focus();
+      });
+  });
+
+  async function boot() {
+    if (!window.tmctChat) {
+      statusEl.textContent = "the chat engine didn't load \\u2014 this page needs its build step (npm run demo:build)";
+      inputEl.placeholder = "chat engine unavailable";
+      return;
+    }
+    await Promise.all([fetchSeed(), tryLoadWink()]);
+    window.tmctChat.registerReferencePackProvider(fetchPackProvider);
+    window.tmctChatSession = newSession();
+    addSystemLine(seedPayload
+      ? "tmct \\u2014 the real engine, running in this page \\u2014 " + seedFacts + " starter facts loaded"
+      : "tmct \\u2014 the real engine, running in this page \\u2014 no starter memory; starting empty");
+    inputEl.placeholder = seedPayload ? 'try "what is a dog"' : window.tmctChat.vocabExampleHint(false);
+    renderStatus();
+    setBusy(false);
+    inputEl.focus();
+  }
+
+  window.tmctChatReady = boot().catch((err) => {
+    console.error("tmct chat failed to boot", err);
+    statusEl.textContent = "the chat failed to start (" + (err && err.message ? err.message : err) + ")";
+  });
+})();
+</script>
+</body>
+</html>
+`;
+}

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

@@ -0,0 +1,395 @@
+// sprite-catalog-viz.mjs — `public/sprites.html` (PLAN_GAMES_UPLIFT_V3.md
+// Part C.2's "Sprite library" link-card item): every class the sprite
+// library actually resolves a sprite for, at both tiers (data/sprites/
+// *-icon.toml, 44px; data/sprites-large/*.toml, 400px), grouped for
+// browsing, each swatch carrying its own real ontology mapping — the class
+// name, its resolved template, and the rdfs:subClassOf ancestor chain the
+// engine would actually walk to reach it — computed through the SAME
+// resolver code the product itself runs (src/domain/sprite-map.mjs's
+// classAncestorChain, src/domain/sprite-templates.mjs's resolveSpriteAsset),
+// never a hand-simulated stand-in.
+//
+// Three pure/impure-separated pieces, mirroring ledger-viz.mjs's own
+// computeLedgerData / computeLedgerDataFromPayload / renderLedgerHtml split:
+//   - loadSpriteOntologyFactRows()   — I/O: the real ancestor-fact source
+//   - buildSpriteCatalogEntries(...) — pure derivation over templates+facts
+//   - renderSpriteCatalogHtml(...)   — pure string builder
+//
+// ---- Ancestor facts: real, not invented ----
+// classAncestorChain needs a flat {subject, predicate:"rdfs:subClassOf",
+// object} row set to walk. Two REAL, already-committed sources are combined:
+//   - the spider-and-fly world's own SEED_TAXONOMY (src/domain/
+//     spider-fly-world.mjs) — poodle/dog/animal, spider/arachnid/animal,
+//     fly/insect/animal — the exact worked example sprite-map.mjs's own
+//     header names.
+//   - corpus/wordnet/wordnet-xl.jsonl (23,805 rows), the SAME opt-in
+//     "wordnet-xl" corpus extension the product itself ships (src/services/
+//     extensions.mjs), converted to rdfs:subClassOf facts through the
+//     existing src/adapters/corpus/conceptnet.mjs loader (loadSlice/loadMap/
+//     toFacts) — no bespoke parsing invented for this page.
+// corpus/wordnet/wordnet-full.jsonl (192k rows, every WordNet sense
+// unfiltered) was tried and rejected: with no word-sense disambiguation its
+// hypernym graph conflates a word's every sense onto one node, so a class as
+// ordinary as "poodle" walks into 3000+ unrelated ancestors and the walk
+// itself takes minutes. wordnet-xl's own "prioritized subset" curation
+// avoids most of that; what's left is capped for DISPLAY (see
+// MAX_CHAIN_DISPLAY below) rather than hidden — still the real chain,
+// just not printed to its full, occasionally very long, length.
+//
+// Every class catalogued here already carries its own template (that's
+// what put it in the catalog), so live sprite resolution always stops at
+// the chain's own first link — the fuller ancestor chain this page prints
+// is real ancestry ON RECORD in the corpus, not a claim that resolution
+// walks that far for THESE classes (it would, for an unregistered subtype
+// like "sheepdog" — sprite-map.mjs's own worked example — which is exactly
+// why the mechanism exists, just not exercised by any class shown here).
+
+import { classAncestorChain, SPRITE_REGISTRY } from "../domain/sprite-map.mjs";
+import { resolveSpriteAsset } from "../domain/sprite-templates.mjs";
+import { MATERIAL_PALETTE } from "../domain/sprite-materials.mjs";
+import { SEED_TAXONOMY } from "../domain/spider-fly-world.mjs";
+import { loadSlice, loadMap, toFacts, WORDNET_DIR } from "../adapters/corpus/conceptnet.mjs";
+import { join } from "node:path";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson } from "./viz-theme.mjs";
+
+const DEFAULT_TITLE = "tmct — the sprite library";
+const MAX_CHAIN_DISPLAY = 6;
+
+/** The real rdfs:subClassOf fact rows this catalog's ancestor chains walk —
+ *  see this module's own header for why these two sources and not a third.
+ *  I/O (reads corpus/wordnet/wordnet-xl.jsonl + its relation map); never
+ *  called from renderSpriteCatalogHtml itself, which stays pure. */
+export async function loadSpriteOntologyFactRows() {
+  const seedRows = SEED_TAXONOMY.map(([subject, object]) => ({ subject, predicate: "rdfs:subClassOf", object }));
+  const assertions = await loadSlice(join(WORDNET_DIR, "wordnet-xl.jsonl"));
+  const map = await loadMap();
+  const wordnetRows = toFacts(assertions, map, "corpus:wordnet-xl")
+    .filter((f) => f.predicate === "rdfs:subClassOf")
+    .map((f) => ({ subject: f.subject, predicate: f.predicate, object: f.object }));
+  return [...seedRows, ...wordnetRows];
+}
+
+// ---- grouping (presentation only — every class still resolves through the
+// real resolver above; this only decides which section of the page a
+// class's card lands in) ----
+
+// The icon tier's own two world families (sprite-map.mjs's header): the
+// spider-and-fly board's creatures share the flat SPRITE_REGISTRY with the
+// adventure world's own props. The creatures fold into "physical objects,
+// creatures & places" below with every other animal; what's left after
+// removing them (and "person", generic to both worlds) is Ashcombe Hall's
+// own unique cast and furniture — never shared with another game.
+const SPIDER_FLY_CREATURE_CLASSES = Object.freeze(["spider", "fly", "egg", "poodle", "dog", "animal"]);
+
+// A curated closed list (the SOURCE_PRIOR/SPRITE_REGISTRY flat-table idiom
+// this project already uses elsewhere) of every data/sprites-large/ class
+// that reads as a person, a family relation, a social role/occupation, or a
+// collective of people. A class named neither here nor an icon-tier
+// adventure prop nor detected as an emoji-fallback class (both below) falls
+// through to "physical objects, creatures & places" by default, so a future
+// added class is never left uncategorized — it just lands in the generic
+// bucket rather than vanishing.
+export const PERSON_ROLE_CLASSES = Object.freeze([
+  "person", "human", "adult", "baby", "child", "boy", "girl", "man", "woman",
+  "mother", "father", "parent", "grandfather", "grandmother", "brother", "sister",
+  "son", "daughter", "husband", "wife", "family", "friend", "neighbor", "stranger",
+  "guest", "visitor", "customer", "employee", "boss", "manager", "leader",
+  "president", "king", "queen", "judge", "lawyer", "priest", "doctor", "nurse",
+  "teacher", "student", "engineer", "artist", "writer", "farmer", "driver",
+  "soldier", "officer", "servant", "worker", "volunteer", "citizen", "resident",
+  "champion", "crowd", "audience", "team",
+]);
+
+export const GROUP_ADVENTURE = "adventure";
+export const GROUP_PERSON = "person";
+export const GROUP_OBJECT = "object";
+export const GROUP_EMOJI = "emoji";
+
+export const CATALOG_GROUPS = Object.freeze([
+  Object.freeze({ id: GROUP_ADVENTURE, label: "Ashcombe Hall's own adventure props", note: "the icon tier's own named cast and furniture — a dedicated 44px sprite exists for each" }),
+  Object.freeze({ id: GROUP_PERSON, label: "Person roles" }),
+  Object.freeze({ id: GROUP_OBJECT, label: "Physical objects, creatures & places" }),
+  Object.freeze({ id: GROUP_EMOJI, label: "Emotions & events", note: "abstract concepts with no honest single physical picture — rendered as the ubiquitous emoji instead" }),
+]);
+
+/** Which catalog section `cls` belongs in. Pure. `isIconTierClass`/`isEmoji`
+ *  are handed in rather than recomputed here so this stays a one-line
+ *  decision over already-known facts about the class. */
+export function groupForClass(cls, { isIconTierClass, isEmoji }) {
+  if (isEmoji) return GROUP_EMOJI;
+  if (isIconTierClass && !SPIDER_FLY_CREATURE_CLASSES.includes(cls) && cls !== "person") return GROUP_ADVENTURE;
+  if (PERSON_ROLE_CLASSES.includes(cls)) return GROUP_PERSON;
+  return GROUP_OBJECT;
+}
+
+function templatesForClass(cls, templates) {
+  return (templates || []).filter((t) => Array.isArray(t?.classes) && t.classes.includes(cls));
+}
+
+/** The MATERIAL_PALETTE treatment key whose {light,base,dark} triple exactly
+ *  matches `value` — the reverse of sprite-materials.mjs's own
+ *  expandMaterialReferences, so a swatch can show e.g. "gold -> metal
+ *  treatment" (sprite-materials.mjs's own header: "gold and metal both read
+ *  as the same warm shiny-metal treatment"). null for a plain single-
+ *  placeholder colour value (a string, not an object) or a one-off hand-
+ *  authored triple that matches no shared treatment. Pure. */
+export function paletteTreatmentFor(value) {
+  if (!value || typeof value !== "object") return null;
+  for (const [name, triple] of Object.entries(MATERIAL_PALETTE)) {
+    if (triple.light === value.light && triple.base === value.base && triple.dark === value.dark) return name;
+  }
+  return null;
+}
+
+/** Every real value a template's own [parameters.*] declares, as
+ *  {paramName, property, rawValue, treatment} rows — one row per value key,
+ *  read directly off the template's own data, never invented. Pure. */
+export function parameterVariantsFor(template) {
+  const out = [];
+  for (const [paramName, param] of Object.entries(template?.parameters || {})) {
+    for (const [rawValue, value] of Object.entries(param?.values || {})) {
+      out.push({ paramName, property: param.property, rawValue, treatment: paletteTreatmentFor(value) });
+    }
+  }
+  return out;
+}
+
+/** Swatches for one tier's template set: a plain swatch ONLY when a real
+ *  `{class}.toml`-shaped plain template exists (no [parameters]/[match] at
+ *  all) — never a synthesized "plain" label for a material-only class,
+ *  since with zero taught facts that class's real resolved output is the
+ *  generic root-fallback shape, not its own silhouette (this module's own
+ *  header names the 19 large-tier classes this applies to). Every
+ *  [parameters.*] value and every [match] variant renders through the real
+ *  resolveSpriteAsset with the exact property fact it declares. A class
+ *  with templates but no plain among them also gets one extra swatch,
+ *  labeled `fallback: true`, showing exactly what the real resolver returns
+ *  for that class with NO taught fact — honest engine behaviour, never
+ *  hidden, just never mislabeled "plain". Pure given `templates` (already
+ *  loaded) and `registry` (SPRITE_REGISTRY). */
+export function tierSwatchesFor(cls, templates, registry, tier) {
+  const forClass = templatesForClass(cls, templates);
+  if (!forClass.length) return [];
+  const plain = forClass.find((t) => !t.parameters && !t.match);
+  const swatches = [];
+  if (plain) {
+    swatches.push({
+      tier, label: "plain", kind: "plain",
+      svg: resolveSpriteAsset(cls, [], [], templates, registry, { instanceKey: `${cls}-${tier}-plain` }),
+    });
+  }
+  for (const t of forClass) {
+    if (t.match) {
+      const propertyFacts = [{ predicate: t.match.property, object: t.match.value }];
+      swatches.push({
+        tier, label: t.match.value, kind: "variant", property: t.match.property,
+        svg: resolveSpriteAsset(cls, [], propertyFacts, templates, registry, { instanceKey: `${cls}-${tier}-match-${t.match.value}` }),
+      });
+    }
+    for (const v of parameterVariantsFor(t)) {
+      const propertyFacts = [{ predicate: v.property, object: v.rawValue }];
+      swatches.push({
+        tier, label: v.rawValue, kind: "material", property: v.property, treatment: v.treatment,
+        svg: resolveSpriteAsset(cls, [], propertyFacts, templates, registry, { instanceKey: `${cls}-${tier}-${v.paramName}-${v.rawValue}` }),
+      });
+    }
+  }
+  if (!plain && swatches.length) {
+    swatches.push({
+      tier, label: "no material taught", kind: "fallback", fallback: true,
+      svg: resolveSpriteAsset(cls, [], [], templates, registry, { instanceKey: `${cls}-${tier}-fallback` }),
+    });
+  }
+  return swatches;
+}
+
+/** The full catalog: one entry per class the icon and/or large tier
+ *  actually carries a template for, each with its real ancestor chain and
+ *  every real tier/material swatch. Pure given the three loaded inputs.
+ *  `factRows` defaults to `[]` (every chain then reads as just the class's
+ *  own name — an honest, if less illustrative, chain rather than a crash)
+ *  so a caller that hasn't loaded the ontology facts yet still gets a
+ *  working catalog. */
+export function buildSpriteCatalogEntries({ iconTemplates = [], largeTemplates = [], factRows = [] } = {}) {
+  const iconClasses = new Set(iconTemplates.flatMap((t) => t?.classes || []));
+  const largeClasses = new Set(largeTemplates.flatMap((t) => t?.classes || []));
+  const allClasses = [...new Set([...iconClasses, ...largeClasses])].sort();
+
+  return allClasses.map((cls) => {
+    const chain = classAncestorChain(cls, factRows);
+    const iconSwatches = tierSwatchesFor(cls, iconTemplates, SPRITE_REGISTRY, "icon");
+    const largeSwatches = tierSwatchesFor(cls, largeTemplates, SPRITE_REGISTRY, "large");
+    const isEmoji = [...iconSwatches, ...largeSwatches].some((s) => s.svg.includes("<text"));
+    const group = groupForClass(cls, { isIconTierClass: iconClasses.has(cls), isEmoji });
+    return { className: cls, group, chain, iconSwatches, largeSwatches };
+  });
+}
+
+// ---- rendering ----
+
+function chainHtml(chain) {
+  const shown = chain.slice(0, MAX_CHAIN_DISPLAY);
+  const rest = chain.length - shown.length;
+  const links = shown
+    .map((term, i) => `<span class="chain-link${i === 0 ? " own" : ""}">${escapeHtml(term)}</span>`)
+    .join('<span class="chain-arrow">&rsaquo;</span>');
+  const more = rest > 0 ? `<span class="chain-more">+${rest} more on record</span>` : "";
+  return `<div class="chain">${links}${more}</div>`;
+}
+
+function swatchHtml(s) {
+  const parts = [`<span class="swatch-label">${escapeHtml(s.label)}</span>`];
+  if (s.treatment) parts.push(`<span class="swatch-treat">&rarr; ${escapeHtml(s.treatment)} treatment</span>`);
+  const title = s.property ? `${s.property} = ${s.label}` : s.label;
+  const cls = ["swatch", s.tier, s.kind].filter(Boolean).join(" ");
+  return `<div class="${cls}" title="${escapeHtml(title)}"><div class="swatch-img">${s.svg}</div><div class="swatch-caption">${parts.join("")}</div></div>`;
+}
+
+function tierRowHtml(tierName, swatches) {
+  if (!swatches.length) return "";
+  return `<div class="tier-row" data-tier="${tierName}">
+      <span class="tier-label">${tierName === "icon" ? "icon &middot; 44px" : "sprite &middot; 400px"}</span>
+      <div class="swatches">${swatches.map(swatchHtml).join("")}</div>
+    </div>`;
+}
+
+function cardHtml(entry) {
+  return `<article class="card" data-cls="${escapeHtml(entry.className)}" data-group="${escapeHtml(entry.group)}">
+    <h3 class="card-name">${escapeHtml(entry.className)}</h3>
+    ${chainHtml(entry.chain)}
+    ${tierRowHtml("icon", entry.iconSwatches)}
+    ${tierRowHtml("large", entry.largeSwatches)}
+  </article>`;
+}
+
+function sectionHtml(group, entries) {
+  const rows = entries.filter((e) => e.group === group.id);
+  if (!rows.length) return "";
+  const note = group.note ? `<p class="section-note">${escapeHtml(group.note)}</p>` : "";
+  return `<section class="group" id="g-${group.id}" aria-label="${escapeHtml(group.label)}">
+    <h2>${escapeHtml(group.label)} <span class="count">${rows.length}</span></h2>
+    ${note}
+    <div class="cards">${rows.map(cardHtml).join("")}</div>
+  </section>`;
+}
+
+/** The self-contained sprite-catalog page. Pure given `iconTemplates`
+ *  (readSpriteTemplateFiles' own output), `largeTemplates`
+ *  (readSpriteLargeTemplateFiles' own output) and `factRows`
+ *  (loadSpriteOntologyFactRows' own output) — the same "byte-identical for
+ *  identical input" invariant every other viz page in this project holds.
+ *  All three default to `[]` so a caller mid-migration (no ontology facts
+ *  loaded yet, say) still gets a page that renders, just with plainer
+ *  ancestor chains. */
+export function renderSpriteCatalogHtml({ title = DEFAULT_TITLE, iconTemplates = [], largeTemplates = [], factRows = [] } = {}) {
+  const entries = buildSpriteCatalogEntries({ iconTemplates, largeTemplates, factRows });
+  const totalSwatches = entries.reduce((n, e) => n + e.iconSwatches.length + e.largeSwatches.length, 0);
+  const pageData = embedJson({ classCount: entries.length, swatchCount: totalSwatches });
+  const navHtml = CATALOG_GROUPS
+    .map((g) => `<a class="jump" href="#g-${g.id}">${escapeHtml(g.label)} <span class="count">${entries.filter((e) => e.group === g.id).length}</span></a>`)
+    .join("");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+${THEME_TOKENS_CSS}
+  html { background: var(--bg); }
+  body { margin: 0; background: var(--bg); color: var(--ink); font-family: ${SERIF_STACK}; font-size: 16px; line-height: 1.5; }
+  .mono { font-family: ${MONO_STACK}; }
+  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; }
+  .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); }
+  .jump .count { color: var(--muted); }
+  .filter { margin-left: auto; display: flex; align-items: center; gap: .4rem; }
+  .filter input { font-family: ${MONO_STACK}; font-size: .8rem; background: var(--card); color: var(--ink); border: 1px solid var(--line); border-radius: 6px; padding: .32rem .6rem; width: 200px; }
+  .filter .n { font-family: ${MONO_STACK}; font-size: .7rem; color: var(--muted); white-space: nowrap; }
+  .group { margin: 2rem 0; content-visibility: auto; contain-intrinsic-size: 800px; }
+  .group h2 { font-size: 1.05rem; margin: 0 0 .2rem; display: flex; align-items: baseline; gap: .5rem; }
+  .group h2 .count { font-family: ${MONO_STACK}; font-size: .72rem; color: var(--muted); font-weight: 400; }
+  .section-note { color: var(--muted); font-size: .82rem; margin: 0 0 .8rem; max-width: 68ch; }
+  .cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(230px, 1fr)); gap: .7rem; }
+  .card { background: var(--card); border: 1px solid var(--line); border-radius: 8px; padding: .6rem .7rem .7rem; content-visibility: auto; contain-intrinsic-size: 220px; }
+  .card[hidden] { display: none; }
+  .card-name { font-size: .92rem; margin: 0 0 .3rem; font-weight: 600; }
+  .chain { font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); margin-bottom: .5rem; display: flex; flex-wrap: wrap; align-items: center; gap: .15rem; }
+  .chain-link { padding: .04rem .35rem; border: 1px solid var(--line); border-radius: 99px; }
+  .chain-link.own { border-color: var(--taught); color: var(--taught); }
+  .chain-arrow { color: var(--muted); opacity: .6; }
+  .chain-more { font-style: italic; opacity: .75; }
+  .tier-row { margin-top: .4rem; }
+  .tier-row:first-of-type { margin-top: 0; }
+  .tier-label { font-family: ${MONO_STACK}; font-size: .62rem; letter-spacing: .04em; text-transform: uppercase; color: var(--muted); }
+  .swatches { display: flex; flex-wrap: wrap; gap: .4rem; margin-top: .25rem; }
+  .swatch { width: 64px; text-align: center; }
+  .swatch.large .swatch-img { width: 64px; height: 64px; }
+  .swatch.icon .swatch-img { width: 34px; height: 34px; margin: 0 auto; }
+  .swatch-img svg { width: 100%; height: 100%; display: block; }
+  .swatch.fallback { opacity: .55; }
+  .swatch.fallback .swatch-img { outline: 1px dashed var(--line); outline-offset: 2px; }
+  .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; } }
+</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>
+  <div class="topbar">
+    <nav aria-label="Jump to group">${navHtml}</nav>
+    <div class="filter">
+      <input id="q" type="text" placeholder="filter by class or group&hellip;" aria-label="Filter the catalog">
+      <span class="n mono" id="qcount"></span>
+    </div>
+  </div>
+  ${CATALOG_GROUPS.map((g) => sectionHtml(g, entries)).join("")}
+  <footer class="page">${entries.length} classes &middot; ${totalSwatches} swatches &middot; icon tier 44px, sprite tier 400px</footer>
+</main>
+<script>
+const SPRITE_CATALOG = ${pageData};
+</script>
+<script>
+(function () {
+  "use strict";
+  const q = document.getElementById("q");
+  const qcount = document.getElementById("qcount");
+  const cards = Array.from(document.querySelectorAll(".card"));
+  function apply() {
+    const needle = q.value.trim().toLowerCase();
+    let shown = 0;
+    for (const card of cards) {
+      const hit = !needle || card.dataset.cls.includes(needle) || card.dataset.group.includes(needle);
+      card.hidden = !hit;
+      if (hit) shown += 1;
+    }
+    for (const section of document.querySelectorAll(".group")) {
+      const anyShown = section.querySelectorAll(".card:not([hidden])").length > 0;
+      section.style.display = anyShown ? "" : "none";
+    }
+    qcount.textContent = needle ? shown + " / " + cards.length : "";
+  }
+  q.addEventListener("input", apply);
+  apply();
+})();
+</script>
+</body>
+</html>
+`;
+}