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

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

@@ -45,7 +45,7 @@
 // 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 { resolveSpriteAsset, matchConstraints } from "../domain/sprite-templates.mjs";
 import { MATERIAL_PALETTE } from "../domain/sprite-materials.mjs";
 import { spriteFactRows } from "../domain/sprite-facts.mjs";
 import { SEED_TAXONOMY } from "../domain/spider-fly-world.mjs";
@@ -247,7 +247,16 @@ export function parameterVariantsFor(template) {
  *  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
+ *  resolveSpriteAsset with the exact property facts it declares — and a
+ *  parameter sitting ON a [match] variant is rendered with BOTH facts, so a
+ *  facing profile's mood swatch shows the profile wearing that mood and is
+ *  labeled for the pair ("left + happy"). Rendering it on the parameter fact
+ *  alone would resolve a different template altogether (the front-facing
+ *  one) and label it as if it belonged to the profile. A value that a
+ *  match-free template of the same class already offers is listed once, from
+ *  that template: the facing pair and the `*-with-emotion.toml` file both
+ *  carry all six moods, and one swatch per mood is the catalog's unit. 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
@@ -264,19 +273,33 @@ export function tierSwatchesFor(cls, templates, registry, tier) {
       svg: resolveSpriteAsset(cls, [], [], templates, registry, { instanceKey: `${cls}-${tier}-plain` }),
     });
   }
+  const valueKey = (v) => `${v.paramName}:${v.rawValue}`;
+  const shownByUnmatchedTemplate = new Set(
+    forClass.filter((t) => !t.match).flatMap((t) => parameterVariantsFor(t).map(valueKey)),
+  );
   for (const t of forClass) {
-    if (t.match) {
-      const propertyFacts = [{ predicate: t.match.property, object: t.match.value }];
+    // A variant may require several facts at once (sprite-templates.mjs's own
+    // matchConstraints), so the swatch is rendered with EVERY fact its
+    // [match] asks for and labeled for the whole set — "left + moving" for a
+    // combined facing-and-pose file. A one-constraint variant reads exactly
+    // as it did before the plural spelling existed.
+    const constraints = matchConstraints(t);
+    const matchFact = constraints.map((c) => ({ predicate: c.property, object: c.value }));
+    const variantLabel = constraints.map((c) => c.value).join(" + ");
+    const variantKey = constraints.map((c) => c.value).join("-");
+    const matchPrefix = constraints.length ? `${variantLabel} + ` : "";
+    if (constraints.length) {
       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}` }),
+        tier, label: variantLabel, kind: "variant", property: constraints.map((c) => c.property).join(" + "),
+        svg: resolveSpriteAsset(cls, [], matchFact, templates, registry, { instanceKey: `${cls}-${tier}-match-${variantKey}` }),
       });
     }
     for (const v of parameterVariantsFor(t)) {
-      const propertyFacts = [{ predicate: v.property, object: v.rawValue }];
+      if (constraints.length && shownByUnmatchedTemplate.has(valueKey(v))) continue;
+      const propertyFacts = [...matchFact, { 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}` }),
+        tier, label: `${matchPrefix}${v.rawValue}`, kind: "material", property: v.property, treatment: v.treatment,
+        svg: resolveSpriteAsset(cls, [], propertyFacts, templates, registry, { instanceKey: `${cls}-${tier}-${matchPrefix ? `${variantKey}-` : ""}${v.paramName}-${v.rawValue}` }),
       });
     }
   }
@@ -311,121 +334,95 @@ export function buildSpriteCatalogEntries({ iconTemplates = [], largeTemplates =
   });
 }
 
-// ---- scene composer (pure) ----
+// ---- scene composer ----
 //
-// The free-text "there is a..." box (PLAN_GAMES_UPLIFT_V3.md's own precedent:
-// adventure-viz.mjs's roomSceneObjects/room-frame) over THIS page's own
-// already-real classes — never a general NLU pass. extractSceneItems is the
-// one pure, unit-testable piece; the DOM index it's matched against
-// (className -> real swatch labels, read straight off this page's own
+// The free-text "there is a..." box (adventure-viz.mjs's roomSceneObjects/
+// room-frame is the same shape) over THIS page's own already-real classes.
+// The parser itself is scene-compose.mjs, which resolves a typed class name
+// through the real resolver; this page owns only the class index it is matched
+// against (className -> real swatch labels, read straight off this page's own
 // already-rendered `.card`/`.swatch-label` markup at load time — see this
 // module's own header for why that beats re-embedding the same SVG data a
-// second time) is built client-side in the inline script below, since
-// walking rendered DOM has no meaning in this pure module.
-
-/** `text`'s lowercase word runs with their token index, the unit
- *  extractSceneItems matches class names against — punctuation never fuses
- *  two real words into one token nor splits one real word into two. */
-function tokenizeSceneText(text) {
-  const tokens = [];
-  const re = /[A-Za-z]+/g;
-  let m;
-  while ((m = re.exec(String(text ?? "")))) tokens.push({ word: m[0].toLowerCase() });
-  return tokens;
+// second time), which is built client-side, since walking rendered DOM has no
+// meaning in this pure module.
+
+export { extractSceneItems } from "../domain/scene-compose.mjs";
+
+// ---- the catalog question lane ----
+//
+// There isn't one. Every catalog-shaped question the dock takes — "how many
+// sprite classes are there", "list the sprite classes", "what parameters does
+// a person sprite take", "what emotions does a person sprite accept" — is
+// answered by the ordinary chat engine reading the same sprite-facts rows this
+// page embeds, through the membership, count and property lanes it already runs
+// for every other caller. The predicate spellings sprite-facts.mjs mints
+// (mgx:take-parameter, mgx:accept-emotion, mgx:offer-variant) are what those
+// lanes read, so the page hands the line over and renders what comes back.
+
+// ---- the animated swatches (pure) ----
+//
+// Each card's large tier carries three animated swatches, one per axis the
+// sprite tier actually varies on: mood (mgx:feels), facing (mgx:faces) and
+// pose (mgx:pose). The page builds their frames client-side out of its own
+// already-rendered swatches (see the inline script below — the same
+// read-the-DOM posture the scene composer's class index takes), but the
+// frame ORDER and the tempo are real logic worth pinning on their own, so
+// they live here as pure functions the page splices in by `.toString()`.
+// One delay constant serves all three, so the three can't drift apart into
+// three tempos.
+//
+// A `frame` is `{svg, label}`. An empty return means there is nothing worth
+// animating for that class, and the page leaves its static swatch alone.
+
+/** The step between animated swatch frames, in milliseconds — the mood
+ *  cycle's own established tempo, shared by the facing sweep and the pose
+ *  toggle. */
+export const CYCLE_FRAME_DELAY_MS = 800;
+
+/** The turntable order the facing sweep steps through: one continuous
+ *  rotation from the sprite's own left profile round to its right. `null`
+ *  is the centre pose — the plain sprite, no mgx:faces fact at all — which
+ *  sits in the middle of the sweep exactly where the geometry puts it, so
+ *  the turn reads as a rotation rather than a jump back through front. */
+export const FACING_TURN_ORDER = Object.freeze(["left", "half-left", null, "half-right", "right"]);
+
+/** The mood cycle's frames: the class's plain sprite, then every mood it
+ *  has a rendered swatch for, in the order the templates declare them. Two
+ *  moods is the floor — one mood alternating with plain is a blink, not a
+ *  cycle. Pure; self-contained (no outer refs), `.toString()`-splice safe. */
+export function moodFrameSequence(plainFrame, moodFrames) {
+  const moods = (moodFrames || []).filter(Boolean);
+  if (moods.length < 2) return [];
+  return plainFrame ? [plainFrame, ...moods] : moods;
 }
 
-/** Every real catalog class the free-typed `text` names, in the order each
- *  first appears, paired with the real material label (one of that SAME
- *  class's own swatch labels — never another class's, never a fabricated
- *  one) immediately preceding it, or `null`. `classIndex` is
- *  `{className: {materials}}` with `materials` keyed by lowercase label
- *  (sprite-catalog-viz's own client-side `buildClassIndexFromDom` output, or
- *  an equivalent test fixture) — a class name absent from `classIndex` can
- *  never match, and a modifier word that isn't one of ITS matched class's
- *  own material labels is silently dropped rather than guessed at, the same
- *  honest-miss posture an unrecognized class name gets (an unmatched word,
- *  e.g. "red" before a lamp with no red material, is never an error, just
- *  silently not drawn). A multi-word class name (e.g. "body of water") is
- *  checked, at every token position, before any shorter class that would
- *  otherwise claim part of it — candidates are tried longest-word-count
- *  first, so the longer name always wins the position it starts at. Pure. */
-export function extractSceneItems(text, classIndex) {
-  const index = classIndex || {};
-  const candidates = Object.keys(index)
-    .map((name) => ({ name, words: name.toLowerCase().split(/\s+/).filter(Boolean) }))
-    .filter((c) => c.words.length)
-    .sort((a, b) => b.words.length - a.words.length || b.name.length - a.name.length);
-  const tokens = tokenizeSceneText(text);
-  const used = new Array(tokens.length).fill(false);
-  const items = [];
-  for (let i = 0; i < tokens.length; i += 1) {
-    if (used[i]) continue;
-    const hit = candidates.find(({ words }) => {
-      if (i + words.length > tokens.length) return false;
-      for (let k = 0; k < words.length; k += 1) {
-        if (used[i + k] || tokens[i + k].word !== words[k]) return false;
-      }
-      return true;
-    });
-    if (!hit) continue;
-    let materialLabel = null;
-    if (i > 0 && !used[i - 1]) {
-      const materials = index[hit.name]?.materials || {};
-      const prevWord = tokens[i - 1].word;
-      if (Object.prototype.hasOwnProperty.call(materials, prevWord)) {
-        materialLabel = prevWord;
-        used[i - 1] = true;
-      }
+/** The facing sweep's frames: `order` (FACING_TURN_ORDER) filtered down to
+ *  the facings this class actually has a rendered swatch for, with
+ *  `centreFrame` — the plain, undirected sprite — dropped into the centre
+ *  slot. `facingFrames` is keyed by each swatch's own label, which is its
+ *  real mgx:faces value. A class with one facing or none has no sweep.
+ *  Pure; self-contained, `.toString()`-splice safe. */
+export function turnFrameSequence(order, centreFrame, facingFrames) {
+  const byFacing = facingFrames || {};
+  const frames = [];
+  for (const facing of order || []) {
+    if (facing === null) {
+      if (centreFrame) frames.push({ svg: centreFrame.svg, label: "centre" });
+    } else if (byFacing[facing]) {
+      frames.push({ svg: byFacing[facing].svg, label: facing });
     }
-    for (let k = 0; k < hit.words.length; k += 1) used[i + k] = true;
-    items.push({ className: hit.name, materialLabel });
   }
-  return items;
+  return frames.length >= 2 ? frames : [];
 }
 
-// ---- catalog question lane (pure) ----
-
-/** The closed set of catalog-shaped questions the chat dock answers straight
- *  off THIS page's own embedded sprite-facts rows (src/domain/
- *  sprite-facts.mjs's output), before a line ever reaches the full engine —
- *  the same closed-template posture extractSceneItems takes for the scene
- *  composer. Returns { answer, grounding } (grounding = how many real rows
- *  the answer was read from) or null for ANY question this lane doesn't own,
- *  including a catalog-shaped question about a class with no rows on record —
- *  the caller falls through to the engine, whose refusal is the honest miss.
- *  Self-contained (no outer refs), `.toString()`-splice safe. Pure. */
-export function answerSpriteQuestion(text, rows) {
-  const all = Array.isArray(rows) ? rows : [];
-  const q = String(text ?? "").trim().toLowerCase().replace(/[?.!\s]+$/, "");
-
-  if (/^what (?:classes|sprites|sprite classes) (?:can you|do you|are there)(?:\s+(?:render|draw|show))?$/.test(q)) {
-    const classes = all
-      .filter((r) => r.predicate === "rdf:type" && r.object === "sprite class")
-      .map((r) => String(r.subject).replace(/ sprite$/, ""));
-    if (!classes.length) return null;
-    const sample = classes.slice(0, 10).join(", ");
-    return {
-      answer: `${classes.length} sprite classes are on record — ${sample}, … (the catalog below lists every one).`,
-      grounding: classes.length,
-    };
-  }
-
-  const m = q.match(/^(?:what|which) parameters? (?:does|do|can|will) (?:a |an |the )?(.+?)(?: sprite)? (?:take|accept|use)s?$/);
-  if (m) {
-    const subject = `${m[1]} sprite`;
-    const params = all.filter((r) => r.subject === subject && r.predicate === "mgx:take-parameter").map((r) => r.object);
-    if (!params.length) return null;
-    let grounding = params.length;
-    const parts = params.map((p) => {
-      const values = all.filter((r) => r.subject === subject && r.predicate === `mgx:accept-${p}`).map((r) => r.object);
-      grounding += values.length;
-      return values.length ? `${p} (${values.join(", ")})` : p;
-    });
-    const lead = params.length === 1 ? "one parameter" : `${params.length} parameters`;
-    return { answer: `a ${subject} takes ${lead}: ${parts.join("; ")}.`, grounding };
-  }
-
-  return null;
+/** The pose toggle's frames: the class's plain idle sprite alternating with
+ *  its mgx:pose = "moving" one. Both have to be there — a class with no
+ *  moving sprite has no second state to toggle into, and gets nothing
+ *  rather than a still frame pretending to animate. Pure; self-contained,
+ *  `.toString()`-splice safe. */
+export function movingFrameSequence(idleFrame, movingFrame) {
+  if (!idleFrame || !movingFrame) return [];
+  return [{ svg: idleFrame.svg, label: "idle" }, { svg: movingFrame.svg, label: "moving" }];
 }
 
 // ---- rendering ----
@@ -505,14 +502,16 @@ function sectionHtml(group, entries, { clusterBy = null } = {}) {
  *  ancestor chains.
  *
  *  `spritesBundleAvailable: true` (ledger-viz.mjs's own ledgerBundleAvailable
- *  idiom) is what adds the chat dock at all: the page then embeds the
- *  sprite-facts rows (src/domain/sprite-facts.mjs, derived purely from the
+ *  idiom) is what adds the two interactive panels at all: the page then embeds
+ *  the sprite-facts rows (src/domain/sprite-facts.mjs, derived purely from the
  *  same two template sets) and references the sibling
  *  ./sprites-browser.bundle.js scripts/build-demo-site.mjs builds alongside
- *  it. Left false, the page renders exactly as before — no dock, no bundle
- *  reference, nothing extra to 404 — including the favicon links, since the
- *  CLI's standalone export (also `spritesBundleAvailable: false`) can't carry
- *  a dangling relative ./favicon.svg either. */
+ *  it. Both panels need that bundle — the dock for its chat session, the scene
+ *  composer for the resolver its parser asks. Left false, the page is the
+ *  catalog alone: no dock, no composer, no bundle reference, nothing extra to
+ *  404 — including the favicon links, since the CLI's standalone export (also
+ *  `spritesBundleAvailable: false`) can't carry a dangling relative
+ *  ./favicon.svg either. */
 export function renderSpriteCatalogHtml({ title = DEFAULT_TITLE, iconTemplates = [], largeTemplates = [], factRows = [], spritesBundleAvailable = false } = {}) {
   const entries = buildSpriteCatalogEntries({ iconTemplates, largeTemplates, factRows });
   const totalSwatches = entries.reduce((n, e) => n + e.iconSwatches.length + e.largeSwatches.length, 0);
@@ -562,22 +561,56 @@ export function renderSpriteCatalogHtml({ title = DEFAULT_TITLE, iconTemplates =
       </form>
       <div class="pills" id="dockPills" role="group" aria-label="quick questions to ask">
         <button type="button" class="pill" data-q="what parameters does a person sprite take?">person parameters</button>
-        <button type="button" class="pill" data-q="what parameters does a cabinet sprite take?">cabinet parameters</button>
-        <button type="button" class="pill" data-q="what classes can you render?">classes on record</button>
+        <button type="button" class="pill" data-q="what emotions does a person sprite accept?">person emotions</button>
+        <button type="button" class="pill" data-q="what materials does a cabinet sprite accept?">cabinet materials</button>
+        <button type="button" class="pill" data-q="how many sprite classes are there?">classes on record</button>
         <button type="button" class="pill" data-q="what is a portrait sprite?">about the portrait sprite</button>
       </div>
       <div class="dock-status mono" id="dockStatus">loading the engine&hellip;</div>
     </section>
   </div>`;
 
+  // The bundle carries the scene composer's parser as well as the dock's
+  // session, and the catalog script below calls it directly, so it loads ahead
+  // of that script rather than beside the dock's own wiring at the end.
+  const spriteBundleScript = !spritesBundleAvailable ? "" : `<script src="./sprites-browser.bundle.js"></script>`;
+
+  // The composer resolves a typed class name through the real resolver, which
+  // reaches the page in that bundle. Without it there is nothing to type into,
+  // so the panel stays out rather than rendering a box that can't answer.
+  const composerHtml = !spritesBundleAvailable ? "" : `<div class="composer">
+    <section class="panel compose-panel" aria-label="Describe a scene">
+      <h2>describe a scene</h2>
+      <form class="composeform" id="composeForm">
+        <span class="prompt mono">there is a</span>
+        <input id="composeq" type="text" autocomplete="off"
+          placeholder="red lamp, a doctor with a hat, and a cabinet"
+          aria-label="Continue the sentence: there is a&hellip;">
+      </form>
+      <div class="pills" id="composePills" role="group" aria-label="quick words to add">
+        <button type="button" class="pill" data-fill="doctor">doctor</button>
+        <button type="button" class="pill" data-fill="hat">hat</button>
+        <button type="button" class="pill" data-fill="wood cabinet">wood cabinet</button>
+        <button type="button" class="pill" data-fill="glass lamp">glass lamp</button>
+        <button type="button" class="pill" data-fill="cat">cat</button>
+        <button type="button" class="pill" data-fill="garden">garden</button>
+      </div>
+    </section>
+    <section class="panel viewer-panel" aria-label="The composed scene">
+      <h2>the scene</h2>
+      <div class="scene-frame" id="sceneFrame">
+        <div class="scene-row" id="sceneRow" aria-live="polite"></div>
+        <span class="empty-note" id="sceneEmpty">nothing recognized yet. Try &ldquo;a doctor with a hat, and a cabinet&rdquo;.</span>
+      </div>
+    </section>
+  </div>`;
+
   const dockScripts = !spritesBundleAvailable ? "" : `<script>
 const SPRITE_CHAT = ${embedJson({ rows: dockRows })};
 </script>
-<script src="./sprites-browser.bundle.js"></script>
 <script>
 (function () {
   "use strict";
-  const answerSpriteQuestion = ${answerSpriteQuestion.toString()};
   const dockLogEl = document.getElementById("dockLog");
   const dockFormEl = document.getElementById("dockForm");
   const dockqEl = document.getElementById("dockq");
@@ -598,7 +631,7 @@ const SPRITE_CHAT = ${embedJson({ rows: dockRows })};
           import("./vendor/wink.js"),
           winkTimeout(WINK_LOAD_TIMEOUT_MS, "wink vendor asset load timed out"),
         ]);
-        tmctSprites.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
+        tmct.page.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
       } catch (err) {
         console.warn("tmct sprites: the wink vendor asset failed to load, continuing without the lemma/POS tier", err);
       }
@@ -626,12 +659,11 @@ const SPRITE_CHAT = ${embedJson({ rows: dockRows })};
     if (!q) return;
     dockqEl.value = "";
     addDockLine("u", q);
-    const local = answerSpriteQuestion(q, SPRITE_CHAT.rows);
-    if (local) { addDockLine("a grounded", local.answer); return; }
     if (!session) { addDockLine("a miss", "the engine is still loading. Try again in a moment."); return; }
     withLock(async () => {
-      const result = await session.turn(q);
-      addDockLine(result.record && result.record.miss ? "a miss" : "a", result.answer);
+      const result = await tmct.turn(q);
+      const missed = !!(result.record && result.record.miss);
+      addDockLine(missed ? "a miss" : "a grounded", result.answer);
     });
   });
 
@@ -645,7 +677,7 @@ const SPRITE_CHAT = ${embedJson({ rows: dockRows })};
   (async () => {
     try {
       await tryLoadWink();
-      session = await tmctSprites.createSpriteCatalogSession({ factRows: SPRITE_CHAT.rows });
+      session = await tmct.open({ factRows: SPRITE_CHAT.rows });
       dockqEl.disabled = false;
       dockStatusEl.textContent = SPRITE_CHAT.rows.length + " sprite facts on record. Ask away, or use a quick question.";
     } catch (err) {
@@ -757,32 +789,7 @@ ${dockCss}</style>
     <h1>Sprites</h1>
     <span class="doc-sub">tmct &middot; the sprite library</span>
   </header>
-  <div class="composer">
-    <section class="panel compose-panel" aria-label="Describe a scene">
-      <h2>describe a scene</h2>
-      <form class="composeform" id="composeForm">
-        <span class="prompt mono">there is a</span>
-        <input id="composeq" type="text" autocomplete="off"
-          placeholder="red lamp, a doctor with a hat, and a cabinet"
-          aria-label="Continue the sentence: there is a&hellip;">
-      </form>
-      <div class="pills" id="composePills" role="group" aria-label="quick words to add">
-        <button type="button" class="pill" data-fill="doctor">doctor</button>
-        <button type="button" class="pill" data-fill="hat">hat</button>
-        <button type="button" class="pill" data-fill="wood cabinet">wood cabinet</button>
-        <button type="button" class="pill" data-fill="glass lamp">glass lamp</button>
-        <button type="button" class="pill" data-fill="cat">cat</button>
-        <button type="button" class="pill" data-fill="garden">garden</button>
-      </div>
-    </section>
-    <section class="panel viewer-panel" aria-label="The composed scene">
-      <h2>the scene</h2>
-      <div class="scene-frame" id="sceneFrame">
-        <div class="scene-row" id="sceneRow" aria-live="polite"></div>
-        <span class="empty-note" id="sceneEmpty">nothing recognized yet. Try &ldquo;a doctor with a hat, and a cabinet&rdquo;.</span>
-      </div>
-    </section>
-  </div>
+  ${composerHtml}
   ${dockHtml}
   <div class="topbar">
     <nav aria-label="Jump to group">${navHtml}</nav>
@@ -797,6 +804,7 @@ ${dockCss}</style>
 <script>
 const SPRITE_CATALOG = ${pageData};
 </script>
+${spriteBundleScript}
 <script>
 (function () {
   "use strict";
@@ -824,10 +832,10 @@ const SPRITE_CATALOG = ${pageData};
   // THIS page's own already-rendered card and swatch-label markup (this
   // module's own header explains why: never a second embedded copy of the
   // same swatch data), so the composed scene below only ever shows a sprite
-  // this same page already proved the resolver draws.
+  // this same page already proved the resolver draws. Which class a typed
+  // word names is the bundle's extractSceneItems, which asks the real
+  // resolver — the page never matches a class name itself.
   const esc = ${escapeHtml.toString()};
-  const tokenizeSceneText = ${tokenizeSceneText.toString()};
-  const extractSceneItems = ${extractSceneItems.toString()};
 
   function buildClassIndexFromDom() {
     const index = {};
@@ -854,72 +862,83 @@ const SPRITE_CATALOG = ${pageData};
     return index;
   }
 
-  const classIndex = buildClassIndexFromDom();
-  const composeqEl = document.getElementById("composeq");
-  const composeFormEl = document.getElementById("composeForm");
-  const composePillsEl = document.getElementById("composePills");
-  const sceneRowEl = document.getElementById("sceneRow");
-  const sceneEmptyEl = document.getElementById("sceneEmpty");
-
-  function renderScene(text) {
-    const items = extractSceneItems(text, classIndex);
-    if (!items.length) {
-      sceneRowEl.innerHTML = "";
-      sceneEmptyEl.hidden = false;
-      return;
+  function wireSceneComposer() {
+    const composeqEl = document.getElementById("composeq");
+    if (!composeqEl) return;
+    const extractSceneItems = tmct.page.extractSceneItems;
+    const composeFormEl = document.getElementById("composeForm");
+    const composePillsEl = document.getElementById("composePills");
+    const sceneRowEl = document.getElementById("sceneRow");
+    const sceneEmptyEl = document.getElementById("sceneEmpty");
+    const classIndex = buildClassIndexFromDom();
+
+    function renderScene(text) {
+      const items = extractSceneItems(text, classIndex);
+      if (!items.length) {
+        sceneRowEl.innerHTML = "";
+        sceneEmptyEl.hidden = false;
+        return;
+      }
+      sceneEmptyEl.hidden = true;
+      sceneRowEl.innerHTML = items.map((item) => {
+        const entry = classIndex[item.className];
+        if (!entry) return "";
+        const svg = (item.materialLabel && entry.materials[item.materialLabel]) || entry.defaultSvg || "";
+        const label = item.materialLabel ? item.materialLabel + " " + item.className : item.className;
+        return '<div class="scene-card"><div class="scene-sprite">' + svg + '</div><div class="scene-label">' + esc(label) + "</div></div>";
+      }).join("");
     }
-    sceneEmptyEl.hidden = true;
-    sceneRowEl.innerHTML = items.map((item) => {
-      const entry = classIndex[item.className];
-      if (!entry) return "";
-      const svg = (item.materialLabel && entry.materials[item.materialLabel]) || entry.defaultSvg || "";
-      const label = item.materialLabel ? item.materialLabel + " " + item.className : item.className;
-      return '<div class="scene-card"><div class="scene-sprite">' + svg + '</div><div class="scene-label">' + esc(label) + "</div></div>";
-    }).join("");
-  }
 
-  composeqEl.addEventListener("input", () => renderScene(composeqEl.value));
-  composeFormEl.addEventListener("submit", (e) => { e.preventDefault(); renderScene(composeqEl.value); });
-  composePillsEl.addEventListener("click", (e) => {
-    const btn = e.target.closest(".pill");
-    if (!btn) return;
-    const phrase = btn.dataset.fill || "";
-    const current = composeqEl.value.trim();
-    composeqEl.value = current ? current + ", a " + phrase : phrase;
-    composeqEl.focus();
-    renderScene(composeqEl.value);
-  });
-  renderScene("");
-
-  // ---- the variant cycle — a card whose large tier carries expression
-  // (mgx:feels) or direction (mgx:faces) variants gains one extra swatch
-  // that steps through them: plain, then each direction, then each face.
-  // Frames are the card's own already-rendered swatches (the same
-  // read-the-DOM posture classIndex takes above — never a second embedded
-  // copy), and one shared interval steps every cycle in sync. Reduced
-  // motion disables the auto-step only; the frame itself is a button, so a
-  // click or Enter always advances one frame by hand. Injected AFTER
-  // buildClassIndexFromDom ran, so a cycle frame never leaks into the
-  // composer's material index.
-  const CYCLE_PROPERTIES = ["mgx:faces", "mgx:feels"];
+    composeqEl.addEventListener("input", () => renderScene(composeqEl.value));
+    composeFormEl.addEventListener("submit", (e) => { e.preventDefault(); renderScene(composeqEl.value); });
+    composePillsEl.addEventListener("click", (e) => {
+      const btn = e.target.closest(".pill");
+      if (!btn) return;
+      const phrase = btn.dataset.fill || "";
+      const current = composeqEl.value.trim();
+      composeqEl.value = current ? current + ", a " + phrase : phrase;
+      composeqEl.focus();
+      renderScene(composeqEl.value);
+    });
+    renderScene("");
+  }
+  wireSceneComposer();
+
+  // ---- the animated swatches — a card's large tier gains one moving
+  // swatch per axis its own templates actually vary on: mood (mgx:feels),
+  // facing (mgx:faces) and pose (mgx:pose). Frames are the card's own
+  // already-rendered swatches (the same read-the-DOM posture classIndex
+  // takes above — never a second embedded copy), ordered by the pure
+  // *FrameSequence functions spliced in below, and one shared interval
+  // steps every cycle in sync at one shared delay. The mood cycle leads the
+  // row; the facing sweep and the pose toggle take over the static plain
+  // and happy swatches' own places rather than adding cells, so the row
+  // keeps its width. Reduced motion disables the auto-step only; each frame
+  // is a button, so a click or Enter always advances one frame by hand.
+  // Injected AFTER buildClassIndexFromDom ran, so a moving frame never
+  // leaks into the composer's material index.
+  const CYCLE_FRAME_DELAY_MS = ${CYCLE_FRAME_DELAY_MS};
+  const FACING_TURN_ORDER = ${embedJson(FACING_TURN_ORDER)};
+  const MOOD_PROPERTY = "mgx:feels";
+  const FACING_PROPERTY = "mgx:faces";
+  const POSE_PROPERTY = "mgx:pose";
+  const moodFrameSequence = ${moodFrameSequence.toString()};
+  const turnFrameSequence = ${turnFrameSequence.toString()};
+  const movingFrameSequence = ${movingFrameSequence.toString()};
   const cycleSteppers = [];
-  for (const card of cards) {
-    const swatchRow = card.querySelector('.tier-row[data-tier="large"] .swatches');
-    if (!swatchRow) continue;
-    const frames = [];
-    for (const swatch of swatchRow.querySelectorAll(".swatch")) {
-      if (CYCLE_PROPERTIES.indexOf(swatch.dataset.property || "") === -1) continue;
-      const img = swatch.querySelector(".swatch-img");
-      const label = swatch.querySelector(".swatch-label");
-      if (img && label) frames.push({ svg: img.innerHTML, label: label.textContent.trim() });
-    }
-    if (frames.length < 2) continue;
-    const baseImg = swatchRow.querySelector(".swatch.plain .swatch-img, .swatch.fallback .swatch-img");
-    if (baseImg) frames.unshift({ svg: baseImg.innerHTML, label: card.dataset.cls });
+
+  function frameFromSwatch(swatch) {
+    const img = swatch && swatch.querySelector(".swatch-img");
+    const label = swatch && swatch.querySelector(".swatch-label");
+    if (!img || !label) return null;
+    return { svg: img.innerHTML, label: label.textContent.trim() };
+  }
+
+  function makeCycleSwatch(frames, ariaLabel, kind) {
     const holder = document.createElement("div");
-    holder.className = "swatch large cycle";
-    holder.innerHTML = '<button type="button" class="swatch-img" aria-label="step through the '
-      + esc(card.dataset.cls) + ' variants"></button><div class="swatch-caption"><span class="swatch-label"></span></div>';
+    holder.className = "swatch large cycle cycle-" + kind;
+    holder.innerHTML = '<button type="button" class="swatch-img" aria-label="' + esc(ariaLabel)
+      + '"></button><div class="swatch-caption"><span class="swatch-label"></span></div>';
     const frameImgEl = holder.querySelector(".swatch-img");
     const frameLabelEl = holder.querySelector(".swatch-label");
     let frameIndex = 0;
@@ -930,12 +949,43 @@ const SPRITE_CATALOG = ${pageData};
     const stepFrame = () => { frameIndex = (frameIndex + 1) % frames.length; showFrame(); };
     frameImgEl.addEventListener("click", stepFrame);
     showFrame();
-    swatchRow.insertBefore(holder, swatchRow.firstChild);
     cycleSteppers.push(stepFrame);
+    return holder;
+  }
+
+  for (const card of cards) {
+    const swatchRow = card.querySelector('.tier-row[data-tier="large"] .swatches');
+    if (!swatchRow) continue;
+    const cls = card.dataset.cls;
+    const rows = Array.from(swatchRow.querySelectorAll(".swatch"))
+      .map((el) => ({ el, property: el.dataset.property || "", frame: frameFromSwatch(el) }))
+      .filter((r) => r.frame);
+    const baseSwatch = swatchRow.querySelector(".swatch.plain, .swatch.fallback");
+    const baseFrame = frameFromSwatch(baseSwatch);
+
+    const moodRows = rows.filter((r) => r.property === MOOD_PROPERTY);
+    const moodFrames = moodFrameSequence(baseFrame && { svg: baseFrame.svg, label: cls }, moodRows.map((r) => r.frame));
+    if (moodFrames.length) {
+      swatchRow.insertBefore(makeCycleSwatch(moodFrames, "step through the " + cls + " expressions", "mood"), swatchRow.firstChild);
+    }
+
+    const facingFrames = {};
+    for (const r of rows) { if (r.property === FACING_PROPERTY) facingFrames[r.frame.label] = r.frame; }
+    const turnFrames = turnFrameSequence(FACING_TURN_ORDER, baseFrame, facingFrames);
+    if (turnFrames.length && baseSwatch) {
+      swatchRow.replaceChild(makeCycleSwatch(turnFrames, "watch the " + cls + " turn through every direction", "turn"), baseSwatch);
+    }
+
+    const movingRow = rows.find((r) => r.property === POSE_PROPERTY && r.frame.label === "moving");
+    const movingFrames = movingFrameSequence(baseFrame, movingRow && movingRow.frame);
+    if (movingFrames.length) {
+      const happyRow = moodRows.find((r) => r.frame.label === "happy");
+      swatchRow.replaceChild(makeCycleSwatch(movingFrames, "watch the " + cls + " move", "moving"), (happyRow || movingRow).el);
+    }
   }
   const reducedMotion = window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
   if (cycleSteppers.length && !reducedMotion) {
-    setInterval(() => { for (const stepFrame of cycleSteppers) stepFrame(); }, 800);
+    setInterval(() => { for (const stepFrame of cycleSteppers) stepFrame(); }, CYCLE_FRAME_DELAY_MS);
   }
 })();
 </script>