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

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>
+`;
+}

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

@@ -31,14 +31,16 @@
 // like a real CLI session.
 import { runTurn } from "../../services/chat.mjs";
 import {
-  createInMemoryStore, appendFacts, appendRule, loadMemory, readFactRows,
+  createInMemoryStore, appendFacts, appendRule, loadMemory, readFactRows, removeFacts,
 } from "../../adapters/memory/core.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { foldWorldState, worldDigestRows, roomAffordances } from "../../services/adventure.mjs";
 import { runAdventureAutoplayTick, exposedFacts } from "../../services/adventure-autoplay.mjs";
-import { resolveSpriteForClass, SPRITE_REGISTRY } from "../../domain/sprite-map.mjs";
+import { parseWorldEditorText, planWorldEditorSync } from "../../services/adventure-editor.mjs";
+import { resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain } from "../../domain/sprite-map.mjs";
 import { resolveSpriteAsset } from "../../domain/sprite-templates.mjs";
+import { relatedForTerm } from "../../domain/skos-view.mjs";
 
 /** A live in-memory adventure this page's ticker AND chat dock can both
  *  drive. Returns `{ memoryDir, autoplayTick, turn, snapshot }`.
@@ -137,6 +139,30 @@ export async function createAdventureSession(worldPayload) {
       const here = state.placements.get("player")?.object ?? null;
       return { rows, state, here, turn: state.turnCount, visitedRoomIds: [...visitedRoomIds] };
     },
+
+    /** The world editor's own store sync: parse `text` (adventure-editor.mjs's
+     *  own parseWorldEditorText), plan the implied writes (planWorldEditorSync),
+     *  and apply them — scoped to THIS world's own provenance tag only, never
+     *  the default persona's background corpus that shares the same live
+     *  memory store (an unscoped diff would read every unrelated background
+     *  fact as "not in this text" and try to retract it). Retractions
+     *  (removeFacts) only ever run when the WHOLE document parsed cleanly —
+     *  see adventure-editor.mjs's own header for why a typo must never be
+     *  read as "this fact is gone". Returns `{ unrecognized, added, removed }`. */
+    async applyEdit(text) {
+      const allRows = readFactRows(await loadMemory(memoryDir));
+      const worldRows = allRows.filter((r) => typeof r.provenance === "string" && r.provenance.indexOf(tag) === 0);
+      const state = foldWorldState(worldRows);
+      const { triples, unrecognized } = parseWorldEditorText(text, worldRows);
+      const { toAppend, toRemoveIds } = planWorldEditorSync(worldRows, state, triples);
+      if (toAppend.length) {
+        await appendFacts(memoryDir, toAppend.map((f) => ({ subject: f.subject, predicate: f.predicate, object: f.object, provenance: tag })));
+      }
+      const removedCount = unrecognized.length === 0 && toRemoveIds.length ? (await removeFacts(memoryDir, toRemoveIds)).removed.length : 0;
+      const here = foldWorldState(readFactRows(await loadMemory(memoryDir))).placements.get("player")?.object ?? null;
+      if (here) visitedRoomIds.add(here);
+      return { unrecognized, added: toAppend.length, removed: removedCount };
+    },
   };
 }
 
@@ -145,8 +171,13 @@ export async function createAdventureSession(worldPayload) {
 // affordances the chat dock's own pills read from, or (foldWorldState,
 // exposedFacts) the exposure-filtered fold the goal-status panel mirrors —
 // the same posture spider-fly-browser-entry.mjs's own
-// globalThis.tmctSpiderFly re-export takes.
+// globalThis.tmctSpiderFly re-export takes. `relatedForTerm`/
+// `classAncestorChain` back the edit mode's own cursor-suggestion pills
+// (adventure-viz.mjs's suggestionsForTerm mirrors this same pairing against
+// the global, the same reach-through-the-global pattern captionFor/pillsFor
+// already use for their own adventure.mjs calls).
 globalThis.tmctAdventure = {
   createAdventureSession, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
   worldDigestRows, roomAffordances, foldWorldState, exposedFacts,
+  relatedForTerm, classAncestorChain,
 };

package/src/surfaces/web/memory-ask-browser.bundle.js

@@ -23594,10 +23594,13 @@ ${JSON.stringify(envelope, null, 2)}`;
       spiderMassDecrementPerTurn: 0.5,
       flyInitialMass: 10,
       flyMassDecrementPerTurn: 1,
-      visionRadius: 4,
+      spiderVisionRadius: 4,
+      flyVisionRadius: 4,
       eggHatchDelayTurns: 3,
       flySpawnIntervalTurns: 3,
-      eggsEatenThreshold: 2,
+      eggLayMassThreshold: 25,
+      eggHatchCount: 2,
+      minHatchlingMass: 3,
       webDurationTurns: 10
     }),
     guessNumber: Object.freeze({
@@ -23614,10 +23617,13 @@ ${JSON.stringify(envelope, null, 2)}`;
     spider_mass_decrement_per_turn: "spiderMassDecrementPerTurn",
     fly_initial_mass: "flyInitialMass",
     fly_mass_decrement_per_turn: "flyMassDecrementPerTurn",
-    vision_radius: "visionRadius",
+    spider_vision_radius: "spiderVisionRadius",
+    fly_vision_radius: "flyVisionRadius",
     egg_hatch_delay_turns: "eggHatchDelayTurns",
     fly_spawn_interval_turns: "flySpawnIntervalTurns",
-    eggs_eaten_threshold: "eggsEatenThreshold",
+    egg_lay_mass_threshold: "eggLayMassThreshold",
+    egg_hatch_count: "eggHatchCount",
+    min_hatchling_mass: "minHatchlingMass",
     web_duration_turns: "webDurationTurns"
   });
   var GUESS_NUMBER_KEY_MAP = Object.freeze({

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

@@ -0,0 +1,114 @@
+// plan-browser-entry.mjs — the esbuild entry for the "it plans, and shows
+// the work" page's live session (public/plan-browser.bundle.js, built by
+// scripts/build-plan-bundle.mjs), mirroring spider-fly-browser-entry.mjs's
+// and adventure-browser-entry.mjs's own session-factory shape.
+//
+// Unlike spider-fly's board or Ashcombe Hall's world, hanoi has no
+// structured fact/rule corpus to bootstrap from — its canonical definition
+// (data/games/hanoi-3.txt) IS taught English, one sentence per teach frame.
+// So this session seeds itself the same way `tmct import --file` teaches
+// that file (src/services/import-file.mjs): every sentence
+// hanoi-lesson.mjs's hanoiLessonSentences() generates runs as its own
+// `turn()`, over the exact same runTurn the CLI and every other viz page's
+// chat dock run — not raw appendFacts/appendRule, since there is no
+// structured fact list to append here, only taught English.
+//
+// createPlanSession({ diskCount, maxDepth }) teaches a fresh N-disk puzzle
+// and solves it once (mirroring the "disk-1 rests on disk-2. … the goal is
+// that every disk rests on peg-c. solve it." prompt scripts/build-demo-
+// site.mjs used to shell out to the CLI for), returning `{ plan, turn, ... }`
+// — `plan` is the freshly solved plan (or null on an honest miss, e.g. a
+// max-depth too low to find one), `turn(line, { maxDepth })` is the SAME
+// chat-dock entry point adventure/spider-fly expose, so a visitor's typed
+// fact and a visitor's typed "solve it" both dispatch through the real
+// engine. `maxDepth` is overridable PER CALL (not just at session creation)
+// so the page's own max-search-depth control can re-run "solve it" on the
+// CURRENT board without tearing down and re-teaching the whole puzzle.
+import { runTurn } from "../../services/chat.mjs";
+import { createInMemoryStore } from "../../adapters/memory/core.mjs";
+import { parseEntities } from "../../domain/codegraph.mjs";
+import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
+import { DEFAULT_GAME_CONFIG } from "../../domain/game-config.mjs";
+import { hanoiLessonSentences } from "../../domain/hanoi-lesson.mjs";
+import { computeBlocksLayout, planToPageData, renderInputsFromPlan } from "../../services/plan-viz.mjs";
+import { planToPddl } from "../../services/plan-pddl.mjs";
+// Re-exported so the page can register a CDN-loaded wink-nlp pair before the
+// first teach, the same seam chat-browser-entry.mjs exposes as
+// tmctChat.registerWinkModel — see wink-model.mjs's own header. The hanoi
+// lesson's own "moving a disk onto a target makes the disk rest on the
+// target" sentence needs a REAL lemmatiser (verbLemma reduces "moving" to
+// "move" to match the taught "move onto" action family) — without it, that
+// one sentence honestly declines ("the lemmatizer isn't available"), the
+// action rule never gets its effect, and every later locative fact for the
+// puzzle fails to teach in turn. spider-fly/adventure never register a wink
+// model because their own gameplay never asks a taught rule to reduce a
+// verb; the hanoi lesson is the first live session here that does.
+import { registerWinkModel } from "../../adapters/wink-model.mjs";
+
+/** A live in-memory towers-of-hanoi session this page's live controls AND
+ *  chat dock can both drive. Returns `{ memoryDir, sessionId, diskCount,
+ *  maxDepth, plan, turn }`. `plan` is the puzzle's freshly solved plan (the
+ *  same shape chat.mjs's planLaneAnswer returns, enriched with
+ *  `becauseText` — see `turn()` below), or null when `maxDepth` was too low
+ *  to find one (an honest miss, not an error: `turn()`'s own answer text
+ *  names it). */
+export async function createPlanSession({ diskCount = 3, maxDepth = DEFAULT_GAME_CONFIG.planning.maxDepth } = {}) {
+  const memoryDir = createInMemoryStore();
+  const graph = parseEntities({ individuals: [], objectProperties: [] });
+  const lexicon = loadLexicon();
+  const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
+  const planHolder = { state: null };
+  let focus = null;
+  let last = null;
+
+  /** One dispatched chat turn — the SAME runTurn the CLI and every other
+   *  viz page's own chat dock run, over this session's own memoryDir. A
+   *  throwing runTurn must never kill the session — the page has no other
+   *  chance to show this turn's answer. `maxDepth` overrides the session's
+   *  own default for just this one call (the page's own max-search-depth
+   *  control threads it on every call, including a plain typed "solve
+   *  it"), so raising or lowering it never requires re-teaching the board.
+   *  A returned `plan` carries `becauseText` folded in from the session's
+   *  own plan slot — the plan-lane contract's returned object never carries
+   *  it itself (only planHolder.state does), and the PDDL panel's own
+   *  "because —" line needs it. */
+  async function turn(line, { maxDepth: maxDepthOverride } = {}) {
+    const gameConfig = {
+      ...DEFAULT_GAME_CONFIG,
+      planning: { ...DEFAULT_GAME_CONFIG.planning, maxDepth: maxDepthOverride ?? maxDepth },
+    };
+    let result;
+    try {
+      result = await runTurn(line, {
+        config: null, source: null, graph, focus, last, memoryDir, sessionId,
+        env: {}, lexicon, vocabHint: "", planState: planHolder.state, gameConfig,
+      });
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return { answer: `Something went wrong answering that (${message}). Try rephrasing, or /help.`, end: false, record: null, plan: null };
+    }
+    focus = result.focus;
+    last = result.last;
+    if ("planState" in result) planHolder.state = result.planState;
+    const plan = result.plan
+      ? { ...result.plan, becauseText: planHolder.state?.becauseText ?? null }
+      : null;
+    return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, plan };
+  }
+
+  let plan = null;
+  for (const sentence of hanoiLessonSentences(diskCount)) {
+    const r = await turn(sentence);
+    if (r.plan) plan = r.plan;
+  }
+
+  return { memoryDir, sessionId, diskCount, maxDepth, plan, turn };
+}
+
+// Re-exported so the page's own rendering script (plan-viz.mjs's inlined
+// script) never has to duplicate board layout or PDDL/OWL-RDF formatting —
+// the same posture adventure-browser-entry.mjs/spider-fly-browser-entry.mjs
+// take re-exporting their own engines' pure helpers.
+globalThis.tmctPlan = {
+  createPlanSession, computeBlocksLayout, planToPageData, renderInputsFromPlan, planToPddl, registerWinkModel,
+};