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

package/src/services/spider-fly-viz.mjs

@@ -265,42 +265,48 @@ ${THEME_TOKENS_CSS}
   @media (prefers-color-scheme: dark) { :root { --fly: #D9A94B; } }
   :root[data-theme="dark"] { --fly: #D9A94B; }
   :root[data-theme="light"] { --fly: #A6791F; }
-  /* The dashboard chrome (Part C.4.2): a beveled control-panel palette
-     WRAPPING the dusty-window board scene above, never touching it — every
-     rule below this block styles .side/.controls-row/.tuning/.status only,
-     all of which are hidden in ?preview=1 mode alongside .side itself, so
-     none of this bleeds into the embedded home-page hero. --chrome-face is
-     the panel's own warm plastic face; --chrome-edge-hi/-lo are its raised-
-     bevel light/shadow edges; --chrome-brass is the console's metal accent
-     (borders, active/hover states); --chrome-well/-well-ink are the dark
-     "LCD" readout a real panel's numeric window would use, deliberately
-     near-black in both themes (a lit readout reads dark-with-a-glow whether
-     the room around it is light or dark). --chrome-shadow-raised/-inset
-     compose the two bevel directions once so every panel/button/well below
-     just references one of them, never re-deriving the edge colors. */
+  /* The console chrome, in this page's own gothic-whimsical register (a
+     Charles Addams cartoon: india-ink line work over aged paper, spooky-cute
+     rather than scary) WRAPPING the window-corner board scene above, never
+     touching it — every rule below this block styles
+     .side/.controls-row/.tuning/.status only, all of which are hidden in
+     ?preview=1 mode alongside .side itself, so none of this bleeds into the
+     embedded home-page hero. --chrome-face is the panel's aged-ivory (night
+     slate in dark) face, textured by --chrome-hatch, a two-direction ink
+     cross-hatch; --chrome-edge-hi/-lo are its raised-bevel light/shadow
+     edges; --chrome-accent is the ink-plum accent (borders, active/hover
+     states); --chrome-well/-well-ink are the near-black readout well with
+     bone-pale numerals, deliberately dark in both themes (a lit readout
+     reads dark-with-a-glow whether the room around it is light or dark).
+     --chrome-shadow-raised/-inset compose the two bevel directions once so
+     every panel/button/well below just references one of them. */
   :root {
-    --chrome-face: #DCD3B8; --chrome-face-hi: #EFE8CC; --chrome-edge-hi: #FBF7E6; --chrome-edge-lo: #8B7F5C;
-    --chrome-brass: #8A6A26; --chrome-brass-soft: rgba(138, 106, 38, .16);
-    --chrome-well: #201A10; --chrome-well-ink: #E8C876;
+    --chrome-face: #E7E1D3; --chrome-face-hi: #F2EDE0; --chrome-edge-hi: #FAF6EA; --chrome-edge-lo: #6E6A5E;
+    --chrome-accent: #5C4B66; --chrome-accent-soft: rgba(92, 75, 102, .14);
+    --chrome-well: #1A171C; --chrome-well-ink: #E4DDCB;
+    --chrome-hatch: repeating-linear-gradient(55deg, rgba(28, 23, 32, .05) 0 1px, transparent 1px 6px), repeating-linear-gradient(-35deg, rgba(28, 23, 32, .04) 0 1px, transparent 1px 9px);
     --chrome-shadow-raised: inset 0 1px 0 var(--chrome-edge-hi), inset 0 -1px 0 var(--chrome-edge-lo), 0 1px 2px rgba(0, 0, 0, .18);
     --chrome-shadow-inset: inset 0 1px 3px var(--chrome-edge-lo), inset 0 -1px 0 var(--chrome-edge-hi);
   }
   @media (prefers-color-scheme: dark) {
-    :root { --chrome-face: #2B2E23; --chrome-face-hi: #363A29; --chrome-edge-hi: #4C5138; --chrome-edge-lo: #14150D;
-      --chrome-brass: #D3AE5C; --chrome-brass-soft: rgba(211, 174, 92, .16);
-      --chrome-well: #0B0904; --chrome-well-ink: #F0D392; }
+    :root { --chrome-face: #262230; --chrome-face-hi: #302B3D; --chrome-edge-hi: #453E57; --chrome-edge-lo: #121016;
+      --chrome-accent: #A995BD; --chrome-accent-soft: rgba(169, 149, 189, .16);
+      --chrome-well: #0C0A10; --chrome-well-ink: #E0D8C6;
+      --chrome-hatch: repeating-linear-gradient(55deg, rgba(240, 235, 220, .04) 0 1px, transparent 1px 6px), repeating-linear-gradient(-35deg, rgba(240, 235, 220, .03) 0 1px, transparent 1px 9px); }
   }
-  :root[data-theme="dark"] { --chrome-face: #2B2E23; --chrome-face-hi: #363A29; --chrome-edge-hi: #4C5138; --chrome-edge-lo: #14150D;
-    --chrome-brass: #D3AE5C; --chrome-brass-soft: rgba(211, 174, 92, .16);
-    --chrome-well: #0B0904; --chrome-well-ink: #F0D392; }
-  :root[data-theme="light"] { --chrome-face: #DCD3B8; --chrome-face-hi: #EFE8CC; --chrome-edge-hi: #FBF7E6; --chrome-edge-lo: #8B7F5C;
-    --chrome-brass: #8A6A26; --chrome-brass-soft: rgba(138, 106, 38, .16);
-    --chrome-well: #201A10; --chrome-well-ink: #E8C876; }
+  :root[data-theme="dark"] { --chrome-face: #262230; --chrome-face-hi: #302B3D; --chrome-edge-hi: #453E57; --chrome-edge-lo: #121016;
+    --chrome-accent: #A995BD; --chrome-accent-soft: rgba(169, 149, 189, .16);
+    --chrome-well: #0C0A10; --chrome-well-ink: #E0D8C6;
+    --chrome-hatch: repeating-linear-gradient(55deg, rgba(240, 235, 220, .04) 0 1px, transparent 1px 6px), repeating-linear-gradient(-35deg, rgba(240, 235, 220, .03) 0 1px, transparent 1px 9px); }
+  :root[data-theme="light"] { --chrome-face: #E7E1D3; --chrome-face-hi: #F2EDE0; --chrome-edge-hi: #FAF6EA; --chrome-edge-lo: #6E6A5E;
+    --chrome-accent: #5C4B66; --chrome-accent-soft: rgba(92, 75, 102, .14);
+    --chrome-well: #1A171C; --chrome-well-ink: #E4DDCB;
+    --chrome-hatch: repeating-linear-gradient(55deg, rgba(28, 23, 32, .05) 0 1px, transparent 1px 6px), repeating-linear-gradient(-35deg, rgba(28, 23, 32, .04) 0 1px, transparent 1px 9px); }
   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: 1120px; margin: 0 auto; padding: 1.4rem 1.2rem 2.2rem; }
-  .eyebrow { font-family: ${MONO_STACK}; font-size: .7rem; letter-spacing: .08em; text-transform: uppercase; color: var(--chrome-brass); }
+  .eyebrow { font-family: ${MONO_STACK}; font-size: .7rem; letter-spacing: .08em; text-transform: uppercase; color: var(--chrome-accent); }
   h1 { font-size: 1.4rem; margin: .3rem 0 .9rem; text-wrap: balance; }
   button { font: inherit; color: inherit; background: none; cursor: pointer; }
   button:focus-visible, input:focus-visible, .sprite:focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
@@ -310,7 +316,7 @@ ${THEME_TOKENS_CSS}
      needing to sum to a full width. */
   .stage { display: grid; grid-template-columns: minmax(0, 8fr) minmax(280px, 3fr); gap: 1.2rem; align-items: start; }
   @media (max-width: 760px) { .stage { grid-template-columns: minmax(0, 1fr); } }
-  /* A dusty window corner: a soft light glow near the top-left (WEB_HOME
+  /* A moonlit window corner: a cool pale glow near the top-left (WEB_HOME
      already sits near that corner — spider-fly-world.mjs's own header
      comment), and a faint diagonal weave standing in for dust/silk caught
      in the light. Decoration only — the 10x10 game grid itself is drawn by
@@ -319,20 +325,26 @@ ${THEME_TOKENS_CSS}
     margin: 0 auto;
     position: relative; width: ${BOARD_PX}px; max-width: 100%; aspect-ratio: 1 / 1;
     background:
-      radial-gradient(140% 140% at 6% 6%, rgba(255, 241, 199, .55), transparent 52%),
-      repeating-linear-gradient(115deg, rgba(120, 110, 90, .06) 0 1px, transparent 1px 30px),
+      radial-gradient(140% 140% at 6% 6%, rgba(224, 224, 240, .55), transparent 52%),
+      repeating-linear-gradient(115deg, rgba(100, 95, 110, .06) 0 1px, transparent 1px 30px),
       var(--card);
     border: 1px solid var(--line);
     box-shadow: inset 0 0 0 6px var(--bg), inset 0 0 0 7px var(--line);
   }
-  @media (prefers-color-scheme: dark) { .board-frame { background: radial-gradient(140% 140% at 6% 6%, rgba(130, 112, 60, .32), transparent 52%), repeating-linear-gradient(115deg, rgba(255, 255, 255, .045) 0 1px, transparent 1px 30px), var(--card); } }
-  :root[data-theme="dark"] .board-frame { background: radial-gradient(140% 140% at 6% 6%, rgba(130, 112, 60, .32), transparent 52%), repeating-linear-gradient(115deg, rgba(255, 255, 255, .045) 0 1px, transparent 1px 30px), var(--card); }
+  @media (prefers-color-scheme: dark) { .board-frame { background: radial-gradient(140% 140% at 6% 6%, rgba(126, 120, 158, .30), transparent 52%), repeating-linear-gradient(115deg, rgba(255, 255, 255, .045) 0 1px, transparent 1px 30px), var(--card); } }
+  :root[data-theme="dark"] .board-frame { background: radial-gradient(140% 140% at 6% 6%, rgba(126, 120, 158, .30), transparent 52%), repeating-linear-gradient(115deg, rgba(255, 255, 255, .045) 0 1px, transparent 1px 30px), var(--card); }
   .board-frame canvas { position: absolute; inset: 0; width: 100%; height: 100%; }
+  /* The cobweb in the window corner — pure decoration over the moonlit
+     glow (never a game element; the ACTIVE web block is still drawn by
+     drawBoard() on the canvas). It sits under the sprite layer so agents
+     always pass in front of it. */
+  .cobweb { position: absolute; top: 7px; left: 7px; width: 36%; height: 36%; color: var(--ink); opacity: .26; pointer-events: none; }
+  .cobweb svg { width: 100%; height: 100%; display: block; }
   .sprite-layer { position: absolute; inset: 0; }
   .sprite { position: absolute; width: 7.6%; height: 7.6%; transform: translate(-50%, -50%); transition: left .25s ease, top .25s ease; }
   @media (prefers-reduced-motion: reduce) { .sprite, .sprite-face { transition: none !important; } }
   .sprite-face { width: 100%; height: 100%; transition: transform .25s ease; }
-  .sprite-face svg { width: 100%; height: 100%; display: block; }
+  .sprite-face svg { width: 100%; height: 100%; display: block; filter: var(--sprite-pop); }
   .sprite[data-cls="spider"] { color: var(--taught); }
   .sprite[data-cls="fly"] { color: var(--fly); }
   .sprite[data-cls="egg"] { color: var(--muted); }
@@ -350,7 +362,7 @@ ${THEME_TOKENS_CSS}
      nameplate header below bleeds to this same panel's own edges via a
      negative margin equal to this padding, so it reads as one welded unit,
      not a label floating inside a box. */
-  .hud, .chat, .tuning { background: var(--chrome-face); border: 1px solid var(--chrome-edge-lo); box-shadow: var(--chrome-shadow-raised); border-radius: 2px; padding: .6rem .75rem; }
+  .hud, .chat, .tuning { background: var(--chrome-hatch), var(--chrome-face); border: 1px solid var(--chrome-edge-lo); box-shadow: var(--chrome-shadow-raised); border-radius: 2px; padding: .6rem .75rem; }
   /* Both the controls strip above the board and the tuning strip below it
      match the board's own width (not the wider stage-left column they sit
      in), so all three line up as one visual stack. */
@@ -380,12 +392,12 @@ ${THEME_TOKENS_CSS}
   .hud-row { display: flex; align-items: flex-start; gap: .6rem; padding: .4rem 0; border-top: 1px solid var(--chrome-edge-lo); box-shadow: inset 0 1px 0 var(--chrome-edge-hi); }
   .hud-row:first-of-type { border-top: none; box-shadow: none; }
   .hud-row.clickable { cursor: pointer; }
-  .hud-row.clickable:hover, .hud-row.clickable:focus-visible { background: var(--chrome-brass-soft); }
+  .hud-row.clickable:hover, .hud-row.clickable:focus-visible { background: var(--chrome-accent-soft); }
   .hud-main { display: flex; flex-direction: column; gap: .1rem; flex: 1 1 auto; min-width: 0; }
   .hud-id { font-family: ${MONO_STACK}; font-size: .74rem; font-weight: 600; }
   .hud-id.spider { color: var(--taught); } .hud-id.fly { color: var(--fly); } .hud-id.egg { color: var(--muted); }
   .hud-goal { font-size: .85rem; }
-  .hud-plan, .hud-belief { font-family: ${MONO_STACK}; font-size: .66rem; color: var(--muted); margin-top: .25rem; line-height: 1.4; padding-left: .5rem; border-left: 2px solid var(--chrome-brass); }
+  .hud-plan, .hud-belief { font-family: ${MONO_STACK}; font-size: .66rem; color: var(--muted); margin-top: .25rem; line-height: 1.4; padding-left: .5rem; border-left: 2px solid var(--chrome-accent); }
   /* the click-expand facts panel (§28): beside the clicked spider/fly's own
      row, never a separate popover or a second panel elsewhere on the page —
      the same believedCellOf/beliefSnapshotFor read path spider-fly.mjs
@@ -417,7 +429,7 @@ ${THEME_TOKENS_CSS}
   .chatask input:disabled { opacity: .5; }
   .chatpills { display: flex; flex-wrap: wrap; gap: .3rem; margin-top: .5rem; }
   .pill { font-family: ${MONO_STACK}; font-size: .68rem; padding: .2rem .6rem; border: 1px solid var(--chrome-edge-lo); border-radius: 99px; background: var(--chrome-face); color: var(--ink); box-shadow: inset 0 1px 0 var(--chrome-edge-hi); white-space: nowrap; }
-  .pill:hover:not(:disabled) { border-color: var(--chrome-brass); }
+  .pill:hover:not(:disabled) { border-color: var(--chrome-accent); }
   .pill:disabled { opacity: .45; cursor: default; }
   .pill[data-role="addr"].active { border-color: var(--taught); color: var(--taught); }
   /* The dynamic deception-pill rail (§A.2.4): a true/false tag shown ONLY
@@ -437,7 +449,7 @@ ${THEME_TOKENS_CSS}
   .tuning-col.spider h3 { color: var(--taught); } .tuning-col.fly h3 { color: var(--fly); }
   .tuning-col label { display: block; font-size: .68rem; color: var(--muted); margin-bottom: .6rem; }
   /* Every live number on this page (this readout, the turn plaque below)
-     shares the same brass-on-well "LED" treatment — one readout language,
+     shares the same bone-on-ink readout treatment — one readout language,
      not a one-off flourish. */
   .tuning-col .tuning-val { font-family: ${MONO_STACK}; font-variant-numeric: tabular-nums; color: var(--chrome-well-ink); background: var(--chrome-well); border: 1px solid var(--chrome-edge-lo); box-shadow: var(--chrome-shadow-inset); border-radius: 2px; padding: 0 .35rem; float: right; }
   .tuning-col input[type="range"] {
@@ -446,7 +458,7 @@ ${THEME_TOKENS_CSS}
     -webkit-appearance: none; appearance: none;
   }
   .tuning-col.fly input[type="range"] { accent-color: var(--fly); }
-  /* A lever-look thumb (a molded brass-edged cap) — appearance: none above
+  /* A lever-look thumb (a molded, ink-edged cap) — appearance: none above
      drops the OS's own native slider look in browsers that honor it;
      accent-color just above is the fallback for any that don't. */
   .tuning-col input[type="range"]::-webkit-slider-thumb {
@@ -469,14 +481,14 @@ ${THEME_TOKENS_CSS}
      control panel", and it costs nothing under reduced-motion since neither
      state involves a transition, just an instant bevel swap. */
   .controls-row button { font-family: ${MONO_STACK}; font-size: .78rem; letter-spacing: .03em; text-transform: uppercase; padding: .4rem .85rem; border-radius: 2px; border: 1px solid var(--chrome-edge-lo); background: var(--chrome-face); box-shadow: var(--chrome-shadow-raised); color: var(--ink); }
-  .controls-row button:hover:not(:disabled) { border-color: var(--chrome-brass); }
+  .controls-row button:hover:not(:disabled) { border-color: var(--chrome-accent); }
   .controls-row button:active:not(:disabled) { box-shadow: var(--chrome-shadow-inset); }
   .controls-row button:disabled { opacity: .4; cursor: default; box-shadow: none; }
-  /* The signature element: a brass-framed digital turn counter, the same
+  /* The turn counter plaque: an accent-framed readout, the same
      inset-well readout language as every stat above it — the one thing this
      page is remembered by. */
-  .controls-row .turn { margin-left: auto; font-family: ${MONO_STACK}; font-size: .82rem; letter-spacing: .05em; text-transform: uppercase; font-variant-numeric: tabular-nums; color: var(--chrome-well-ink); background: var(--chrome-well); border: 1px solid var(--chrome-brass); box-shadow: var(--chrome-shadow-inset); border-radius: 2px; padding: .3rem .7rem; }
-  .status { font-family: ${MONO_STACK}; font-size: .74rem; color: var(--muted); margin-top: .5rem; padding-left: .5rem; border-left: 2px solid var(--chrome-brass); }
+  .controls-row .turn { margin-left: auto; font-family: ${MONO_STACK}; font-size: .82rem; letter-spacing: .05em; text-transform: uppercase; font-variant-numeric: tabular-nums; color: var(--chrome-well-ink); background: var(--chrome-well); border: 1px solid var(--chrome-accent); box-shadow: var(--chrome-shadow-inset); border-radius: 2px; padding: .3rem .7rem; }
+  .status { font-family: ${MONO_STACK}; font-size: .74rem; color: var(--muted); margin-top: .5rem; padding-left: .5rem; border-left: 2px solid var(--chrome-accent); }
   body.preview .side, body.preview .controls-panel, body.preview .tuning { display: none; }
   body.preview main { padding: 0; max-width: none; }
   body.preview .stage, body.preview .stage-left { display: block; }
@@ -507,11 +519,23 @@ ${THEME_TOKENS_CSS}
     <div class="board-frame" id="boardFrame">
       <canvas id="board" width="${BOARD_PX}" height="${BOARD_PX}" aria-label="the 10x10 board"></canvas>
       <canvas id="pov" width="${BOARD_PX}" height="${BOARD_PX}" aria-hidden="true"></canvas>
+      <div class="cobweb" aria-hidden="true"><svg viewBox="0 0 100 100" fill="none" stroke="currentColor" stroke-linecap="round">
+        <g stroke-width="0.7">
+          <path d="M0 0 L73.8 5.2"/><path d="M0 0 L68.6 27.7"/><path d="M0 0 L52.3 52.3"/><path d="M0 0 L27.7 68.6"/><path d="M0 0 L5.2 73.8"/>
+        </g>
+        <g stroke-width="0.55">
+          <path d="M20 1.4 Q16.8 3.9 18.5 7.5 Q14.3 9.5 14.1 14.1 Q9.5 14.3 7.5 18.5 Q3.9 16.8 1.4 20"/>
+          <path d="M33.9 2.4 Q28.4 6.6 31.5 12.7 Q24.4 16.1 24 24 Q16.1 24.4 12.7 31.5 Q6.6 28.4 2.4 33.9"/>
+          <path d="M49.9 3.5 Q41.9 9.7 46.4 18.7 Q35.9 23.7 35.4 35.4 Q23.7 35.9 18.7 46.4 Q9.7 41.9 3.5 49.9"/>
+          <path d="M67.8 4.8 Q57 13.2 63 25.5 Q48.8 32.3 48.1 48.1 Q32.3 48.8 25.5 63 Q13.2 57 4.8 67.8"/>
+        </g>
+        <path d="M48.1 48.1 Q49.5 54 48.6 59.5" stroke-width="0.5"/>
+      </svg></div>
       <div class="sprite-layer" id="spriteLayer"></div>
       <div class="thread-tip" id="threadTip"></div>
     </div>
     <div class="tuning" id="tuning">
-      <h2>live tuning &mdash; mass loss, spawn rate, vision, per class</h2>
+      <h2>live tuning &middot; mass loss, spawn rate, vision, per class</h2>
       <div class="tuning-grid">
         <div class="tuning-col spider">
           <h3>spider</h3>

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

@@ -165,10 +165,10 @@ 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_ADVENTURE, label: "Ashcombe Hall's own adventure props", note: "the icon tier's named cast and furniture. Each has its own 44px sprite." }),
   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" }),
+  Object.freeze({ id: GROUP_EMOJI, label: "Emotions & events", note: "abstract concepts with no single physical picture, drawn as the familiar emoji instead" }),
 ]);
 
 /** Which catalog section `cls` belongs in. Pure. `isIconTierClass`/`isEmoji`
@@ -181,6 +181,33 @@ export function groupForClass(cls, { isIconTierClass, isEmoji }) {
   return GROUP_OBJECT;
 }
 
+/** Cluster one presentation group's entries under each class's nearest
+ *  ILLUSTRATED ancestor — the first term after the class itself, walking its
+ *  own real chain outward, that carries a sprite template at either tier. A
+ *  new leaf attached under that ancestor later resolves to the ancestor's
+ *  own sprite through the same walk, so these headings show exactly where
+ *  the graph can grow with no new art needed. A cluster needs two members
+ *  to earn a heading; singletons (and classes whose chain reaches no
+ *  illustrated ancestor) fold into one trailing `ancestor: null` bucket so
+ *  the section never shreds into one-card headings. Pure. */
+export function clusterEntriesByAncestor(entries, spritedClasses) {
+  const byKey = new Map();
+  for (const e of entries || []) {
+    const key = (e.chain || []).slice(1).find((t) => spritedClasses.has(t)) || "";
+    if (!byKey.has(key)) byKey.set(key, []);
+    byKey.get(key).push(e);
+  }
+  const clusters = [];
+  const rest = [];
+  for (const [key, list] of byKey) {
+    if (key && list.length >= 2) clusters.push({ ancestor: key, entries: list });
+    else rest.push(...list);
+  }
+  clusters.sort((a, b) => b.entries.length - a.entries.length || a.ancestor.localeCompare(b.ancestor));
+  if (rest.length) clusters.push({ ancestor: null, entries: [...rest].sort((a, b) => a.className.localeCompare(b.className)) });
+  return clusters;
+}
+
 function templatesForClass(cls, templates) {
   return (templates || []).filter((t) => Array.isArray(t?.classes) && t.classes.includes(cls));
 }
@@ -418,7 +445,8 @@ function swatchHtml(s) {
   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>`;
+  const property = s.property ? ` data-property="${escapeHtml(s.property)}"` : "";
+  return `<div class="${cls}"${property} title="${escapeHtml(title)}"><div class="swatch-img">${s.svg}</div><div class="swatch-caption">${parts.join("")}</div></div>`;
 }
 
 function tierRowHtml(tierName, swatches) {
@@ -438,14 +466,32 @@ function cardHtml(entry) {
   </article>`;
 }
 
-function sectionHtml(group, entries) {
+/** One ancestor cluster inside a section: a heading that carries the
+ *  ancestor's OWN resolved sprite (the proof the fallback has art to land
+ *  on), then that cluster's cards. `ancestorSvg` is null for the trailing
+ *  no-illustrated-ancestor bucket. */
+function clusterHtml(cluster, ancestorSvg) {
+  const name = cluster.ancestor || "everything else";
+  const chip = ancestorSvg ? `<span class="cluster-chip">${ancestorSvg}</span>` : "";
+  return `<div class="cluster">
+    <h3 class="cluster-head">${chip}<span class="cluster-name">${escapeHtml(name)}</span><span class="count">${cluster.entries.length}</span></h3>
+    <div class="cards">${cluster.entries.map(cardHtml).join("")}</div>
+  </div>`;
+}
+
+function sectionHtml(group, entries, { clusterBy = null } = {}) {
   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>` : "";
+  const body = clusterBy
+    ? clusterEntriesByAncestor(rows, clusterBy.spritedClasses)
+        .map((c) => clusterHtml(c, c.ancestor ? clusterBy.resolveChip(c.ancestor) : null))
+        .join("")
+    : `<div class="cards">${rows.map(cardHtml).join("")}</div>`;
   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>
+    ${body}
   </section>`;
 }
 
@@ -471,6 +517,15 @@ export function renderSpriteCatalogHtml({ title = DEFAULT_TITLE, iconTemplates =
   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 });
+  // Ancestor clustering for the two big sections: the heading chip is the
+  // ancestor's OWN resolved sprite — visible proof that a new subclass
+  // attached there already has fallback art waiting for it.
+  const spritedClasses = new Set([...iconTemplates, ...largeTemplates].flatMap((t) => t?.classes || []));
+  const clusterBy = {
+    spritedClasses,
+    resolveChip: (ancestor) =>
+      resolveSpriteAsset(ancestor, [], [], largeTemplates, SPRITE_REGISTRY, { instanceKey: `cluster-${ancestor}` }),
+  };
   const dockRows = spritesBundleAvailable ? spriteFactRows({ iconTemplates, largeTemplates }) : [];
   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>`)
@@ -478,8 +533,6 @@ export function renderSpriteCatalogHtml({ title = DEFAULT_TITLE, iconTemplates =
 
   const dockCss = !spritesBundleAvailable ? "" : `
   .dockwrap { margin: .2rem 0 1.3rem; }
-  .dockwrap .panel { background: var(--card); border: 1px solid var(--line); border-top: 2px solid var(--taught); padding: .75rem .85rem; }
-  .dockwrap h2 { font-family: ${SERIF_STACK}; font-variant: small-caps; font-size: .82rem; letter-spacing: .04em; color: var(--muted); font-weight: 600; margin: 0 0 .55rem; }
   .dock-note { color: var(--muted); font-size: .8rem; margin: 0 0 .6rem; max-width: 72ch; }
   .docklog { display: flex; flex-direction: column; gap: .4rem; max-height: 240px; overflow-y: auto; margin-bottom: .5rem; }
   .docklog:empty { display: none; margin-bottom: 0; }
@@ -490,8 +543,8 @@ export function renderSpriteCatalogHtml({ title = DEFAULT_TITLE, iconTemplates =
   .docklog .a.grounded { border-left: 2px solid var(--taught); padding-left: .5rem; }
   .dockask { display: flex; align-items: center; gap: .5rem; }
   .dockask .prompt { color: var(--taught); font-size: .78rem; }
-  .dockask input { flex: 1; font-family: ${MONO_STACK}; font-size: .82rem; background: var(--bg); color: var(--ink); border: 1px solid var(--line); border-radius: 4px; padding: .38rem .6rem; min-width: 0; }
-  .dockask input:focus-visible { outline: 2px solid var(--taught); outline-offset: 2px; }
+  .dockask input { flex: 1; font-family: ${MONO_STACK}; font-size: .82rem; background: var(--ai-panel-hi); color: var(--ink); border: 1px solid var(--ai-edge); border-radius: 3px; padding: .38rem .6rem; min-width: 0; }
+  .dockask input:focus-visible { outline: 2px solid var(--corpus); outline-offset: 2px; }
   .dockask input:disabled { opacity: .5; }
   .dock-status { font-size: .72rem; color: var(--muted); margin-top: .55rem; }
 `;
@@ -499,7 +552,7 @@ export function renderSpriteCatalogHtml({ title = DEFAULT_TITLE, iconTemplates =
   const dockHtml = !spritesBundleAvailable ? "" : `<div class="dockwrap">
     <section class="panel" aria-label="Ask about the sprite catalog">
       <h2>ask the catalog</h2>
-      <p class="dock-note">every answer is read from the sprite templates&rsquo; own facts &mdash; a question they can&rsquo;t ground gets a refusal, never a guess.</p>
+      <p class="dock-note">every answer is read from the sprite templates&rsquo; own facts. A question they can&rsquo;t ground gets a refusal, never a guess.</p>
       <div class="docklog" id="dockLog" aria-live="polite"></div>
       <form class="dockask" id="dockForm">
         <span class="prompt mono">tmct&gt;</span>
@@ -575,7 +628,7 @@ const SPRITE_CHAT = ${embedJson({ rows: dockRows })};
     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 \\u2014 try again in a moment."); 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);
@@ -594,9 +647,9 @@ const SPRITE_CHAT = ${embedJson({ rows: dockRows })};
       await tryLoadWink();
       session = await tmctSprites.createSpriteCatalogSession({ factRows: SPRITE_CHAT.rows });
       dockqEl.disabled = false;
-      dockStatusEl.textContent = SPRITE_CHAT.rows.length + " sprite facts on record \\u2014 ask away, or use a quick question.";
+      dockStatusEl.textContent = SPRITE_CHAT.rows.length + " sprite facts on record. Ask away, or use a quick question.";
     } catch (err) {
-      dockStatusEl.textContent = "the chat engine failed to load \\u2014 the catalog below still works.";
+      dockStatusEl.textContent = "the chat engine failed to load. The catalog below still works.";
       console.error("tmct sprites: dock boot failed", err);
     }
   })();
@@ -614,49 +667,67 @@ ${spritesBundleAvailable ? `<link rel="icon" href="./favicon.svg" type="image/sv
 <link rel="apple-touch-icon" href="./apple-touch-icon.png">` : ""}
 <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; }
+  html { background: var(--ai-canvas); }
+  /* Creative-app chrome: a dark document bar in BOTH themes (the app-window
+     read), panels and a recessed canvas that follow the theme, and a
+     transparency checker under every drawn swatch so each sprite proves it
+     holds its own boundary with nothing behind it. */
+  :root {
+    --ai-bar: #26272B; --ai-bar-ink: #E7E5DF;
+    --ai-panel: #EDECE8; --ai-panel-hi: #F4F3F0; --ai-canvas: #DFDEDA; --ai-edge: #C8C6C0;
+    --checker: rgba(0, 0, 0, .07);
+  }
+  @media (prefers-color-scheme: dark) { :root { --ai-panel: #26272B; --ai-panel-hi: #2D2E33; --ai-canvas: #1A1B1F; --ai-edge: #34363C; --checker: rgba(255, 255, 255, .055); } }
+  :root[data-theme="dark"] { --ai-panel: #26272B; --ai-panel-hi: #2D2E33; --ai-canvas: #1A1B1F; --ai-edge: #34363C; --checker: rgba(255, 255, 255, .055); }
+  :root[data-theme="light"] { --ai-panel: #EDECE8; --ai-panel-hi: #F4F3F0; --ai-canvas: #DFDEDA; --ai-edge: #C8C6C0; --checker: rgba(0, 0, 0, .07); }
+  body { margin: 0; background: var(--ai-canvas); 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; }
-
-  .composer { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: .6rem 0 1.3rem; }
+  main { max-width: 1240px; margin: 0 auto; padding: 0 1.2rem 3rem; }
+  button:focus-visible, input:focus-visible, a:focus-visible { outline: 2px solid var(--corpus); outline-offset: 2px; }
+  .appbar { display: flex; align-items: flex-end; gap: 1rem; margin: 0 -1.2rem; padding: .6rem 1.2rem 0; background: var(--ai-bar); }
+  .appbar h1 { font-family: ${MONO_STACK}; font-size: .84rem; font-weight: 600; letter-spacing: .02em; margin: 0; padding: .32rem .8rem .38rem; background: var(--ai-panel); color: var(--ink); border-radius: 4px 4px 0 0; }
+  .appbar .doc-sub { font-family: ${MONO_STACK}; font-size: .66rem; letter-spacing: .07em; text-transform: uppercase; color: color-mix(in srgb, var(--ai-bar-ink) 65%, transparent); padding-bottom: .5rem; }
+  .topbar { position: sticky; top: 0; z-index: 2; display: flex; flex-wrap: wrap; align-items: center; gap: .5rem .9rem; background: var(--ai-panel); border-bottom: 1px solid var(--ai-edge); margin: 0 -1.2rem 1.4rem; padding: .5rem 1.2rem; }
+  .jump { font-family: ${MONO_STACK}; font-size: .7rem; padding: .2rem .6rem; border: 1px solid var(--ai-edge); border-radius: 3px; background: transparent; color: var(--ink); text-decoration: none; }
+  .jump:hover { border-color: var(--corpus); color: var(--corpus); }
+  .jump .count { color: var(--muted); }
+  .filter { margin-left: auto; display: flex; align-items: center; gap: .4rem; }
+  .filter input { font-family: ${MONO_STACK}; font-size: .78rem; background: var(--ai-panel-hi); color: var(--ink); border: 1px solid var(--ai-edge); border-radius: 3px; padding: .3rem .6rem; width: 200px; }
+  .filter .n { font-family: ${MONO_STACK}; font-size: .7rem; color: var(--muted); white-space: nowrap; }
+  .composer { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1.2rem 0 1.3rem; }
   @media (max-width: 700px) { .composer { grid-template-columns: 1fr; } }
-  .composer .panel { background: var(--card); border: 1px solid var(--line); border-top: 2px solid var(--taught); padding: .75rem .85rem; min-width: 0; }
-  .composer h2 { font-family: ${SERIF_STACK}; font-variant: small-caps; font-size: .82rem; letter-spacing: .04em; color: var(--muted); font-weight: 600; margin: 0 0 .55rem; }
+  .composer .panel, .dockwrap .panel { background: var(--ai-panel); border: 1px solid var(--ai-edge); border-radius: 4px; padding: .75rem .85rem; min-width: 0; box-shadow: 0 1px 2px rgba(0, 0, 0, .08); }
+  .composer h2, .dockwrap h2 { font-family: ${MONO_STACK}; font-size: .66rem; letter-spacing: .09em; text-transform: uppercase; color: var(--muted); font-weight: 600; margin: -.75rem -.85rem .6rem; padding: .42rem .85rem; background: var(--ai-panel-hi); border-bottom: 1px solid var(--ai-edge); border-radius: 4px 4px 0 0; }
   .composeform { display: flex; align-items: center; gap: .5rem; }
   .composeform .prompt { color: var(--taught); font-size: .8rem; white-space: nowrap; }
-  .composeform input { flex: 1; font-family: ${MONO_STACK}; font-size: .82rem; background: var(--bg); color: var(--ink); border: 1px solid var(--line); border-radius: 4px; padding: .38rem .6rem; min-width: 0; }
-  .composeform input:focus-visible { outline: 2px solid var(--taught); outline-offset: 2px; }
+  .composeform input { flex: 1; font-family: ${MONO_STACK}; font-size: .82rem; background: var(--ai-panel-hi); color: var(--ink); border: 1px solid var(--ai-edge); border-radius: 3px; padding: .38rem .6rem; min-width: 0; }
   .pills { display: flex; flex-wrap: wrap; gap: .35rem; margin-top: .6rem; }
-  .pill { font-family: ${MONO_STACK}; font-size: .7rem; padding: .22rem .55rem; border: 1px solid var(--line); border-radius: 999px; background: var(--bg); color: var(--ink); cursor: pointer; }
-  .pill:hover { border-color: var(--taught); }
-  .pill:focus-visible { outline: 2px solid var(--taught); outline-offset: 2px; }
+  .pill { font-family: ${MONO_STACK}; font-size: .7rem; padding: .22rem .55rem; border: 1px solid var(--ai-edge); border-radius: 999px; background: var(--ai-panel-hi); color: var(--ink); cursor: pointer; }
+  .pill:hover { border-color: var(--corpus); color: var(--corpus); }
   .scene-frame { min-height: 5.6rem; display: flex; align-items: center; }
   .scene-row { display: flex; flex-wrap: wrap; gap: .8rem; align-items: flex-start; width: 100%; }
+  .scene-row:empty { display: none; }
   .scene-card { display: flex; flex-direction: column; align-items: center; width: 74px; }
-  .scene-sprite { width: 60px; height: 60px; border-radius: 8px; background: var(--bg); border: 1px solid var(--line); display: flex; align-items: center; justify-content: center; padding: 8px; box-sizing: border-box; }
-  .scene-sprite svg { width: 100%; height: 100%; display: block; }
+  .scene-sprite { width: 60px; height: 60px; border-radius: 3px; border: 1px solid var(--ai-edge); display: flex; align-items: center; justify-content: center; padding: 6px; box-sizing: border-box; background-image: linear-gradient(45deg, var(--checker) 25%, transparent 25% 75%, var(--checker) 75%), linear-gradient(45deg, var(--checker) 25%, transparent 25% 75%, var(--checker) 75%); background-position: 0 0, 5px 5px; background-size: 10px 10px; background-color: var(--card); }
+  .scene-sprite svg { width: 100%; height: 100%; display: block; filter: var(--sprite-pop); }
   .scene-label { font-size: .7rem; text-align: center; color: var(--ink); margin-top: .3rem; line-height: 1.2; }
   .empty-note { font-family: ${MONO_STACK}; font-size: .78rem; color: var(--muted); }
-  .topbar { position: sticky; top: 0; z-index: 2; background: var(--bg); display: flex; flex-wrap: wrap; align-items: center; gap: .5rem .9rem; border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); padding: .6rem 0; margin: 1rem 0 1.2rem; }
-  .jump { font-family: ${MONO_STACK}; font-size: .72rem; padding: .18rem .55rem; border: 1px solid var(--line); border-radius: 99px; background: var(--card); color: var(--ink); text-decoration: none; }
-  .jump:hover { border-color: var(--taught); }
-  .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; }
+  .group { margin: 2.2rem 0; content-visibility: auto; contain-intrinsic-size: 800px; }
+  .group h2 { font-family: ${MONO_STACK}; font-size: .78rem; text-transform: uppercase; letter-spacing: .09em; margin: 0 0 .2rem; display: flex; align-items: baseline; gap: .5rem; }
+  .group h2 .count { font-size: .7rem; color: var(--muted); font-weight: 400; }
   .section-note { color: var(--muted); font-size: .82rem; margin: 0 0 .8rem; max-width: 68ch; }
+  .cluster { margin: 1rem 0 1.5rem; }
+  .cluster-head { display: flex; align-items: center; gap: .45rem; font-family: ${MONO_STACK}; font-size: .7rem; font-weight: 600; text-transform: uppercase; letter-spacing: .07em; color: var(--muted); margin: 0 0 .55rem; }
+  .cluster-head .count { font-weight: 400; opacity: .75; }
+  .cluster-head::after { content: ""; flex: 1; height: 1px; background: var(--ai-edge); }
+  .cluster-chip { width: 26px; height: 26px; display: inline-flex; padding: 2px; box-sizing: border-box; border: 1px solid var(--ai-edge); border-radius: 3px; background-image: linear-gradient(45deg, var(--checker) 25%, transparent 25% 75%, var(--checker) 75%), linear-gradient(45deg, var(--checker) 25%, transparent 25% 75%, var(--checker) 75%); background-position: 0 0, 4px 4px; background-size: 8px 8px; background-color: var(--card); }
+  .cluster-chip svg { width: 100%; height: 100%; display: block; filter: var(--sprite-pop); }
   .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 { background: var(--card); border: 1px solid var(--ai-edge); border-radius: 4px; padding: .55rem .7rem .7rem; box-shadow: 0 1px 2px rgba(0, 0, 0, .08); content-visibility: auto; contain-intrinsic-size: 220px; }
   .card[hidden] { display: none; }
-  .card-name { font-size: .92rem; margin: 0 0 .3rem; font-weight: 600; }
+  .card-name { font-family: ${MONO_STACK}; font-size: .7rem; font-weight: 600; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin: 0 0 .35rem; }
   .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 { padding: .04rem .35rem; border: 1px solid var(--ai-edge); 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; }
@@ -665,21 +736,27 @@ ${THEME_TOKENS_CSS}
   .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-img { border: 1px solid var(--ai-edge); border-radius: 3px; box-sizing: border-box; padding: 3px; background-image: linear-gradient(45deg, var(--checker) 25%, transparent 25% 75%, var(--checker) 75%), linear-gradient(45deg, var(--checker) 25%, transparent 25% 75%, var(--checker) 75%); background-position: 0 0, 5px 5px; background-size: 10px 10px; background-color: var(--card); }
   .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.icon .swatch-img { width: 36px; height: 36px; margin: 0 auto; }
+  .swatch-img svg { width: 100%; height: 100%; display: block; filter: var(--sprite-pop); }
   .swatch.fallback { opacity: .55; }
-  .swatch.fallback .swatch-img { outline: 1px dashed var(--line); outline-offset: 2px; }
+  .swatch.fallback .swatch-img { border-style: dashed; }
   .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, .pill { transition: border-color .12s ease, opacity .12s ease; } }
+  .swatch.cycle .swatch-img { border-color: var(--taught); cursor: pointer; display: block; }
+  .swatch.cycle .swatch-img:hover { border-color: var(--corpus); }
+  .swatch.cycle .swatch-caption { color: var(--taught); }
+  footer.page { max-width: 74ch; margin: 2.5rem 0 0; padding-top: 1rem; border-top: 1px solid var(--ai-edge); font-family: ${MONO_STACK}; font-size: .74rem; color: var(--muted); }
+  @media (prefers-reduced-motion: no-preference) { .jump, .swatch, .pill { transition: border-color .12s ease, color .12s ease, opacity .12s ease; } }
 ${dockCss}</style>
 </head>
 <body>
 <main>
-  <div class="eyebrow">tmct &middot; the sprite library</div>
-  <h1>Sprites</h1>
+  <header class="appbar">
+    <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>
@@ -702,7 +779,7 @@ ${dockCss}</style>
       <h2>the scene</h2>
       <div class="scene-frame" id="sceneFrame">
         <div class="scene-row" id="sceneRow" aria-live="polite"></div>
-        <span class="empty-note" id="sceneEmpty">nothing recognized yet &mdash; try &ldquo;a doctor with a hat, and a cabinet&rdquo;.</span>
+        <span class="empty-note" id="sceneEmpty">nothing recognized yet. Try &ldquo;a doctor with a hat, and a cabinet&rdquo;.</span>
       </div>
     </section>
   </div>
@@ -714,7 +791,7 @@ ${dockCss}</style>
       <span class="n mono" id="qcount"></span>
     </div>
   </div>
-  ${CATALOG_GROUPS.map((g) => sectionHtml(g, entries)).join("")}
+  ${CATALOG_GROUPS.map((g) => sectionHtml(g, entries, { clusterBy: g.id === GROUP_PERSON || g.id === GROUP_OBJECT ? clusterBy : null })).join("")}
   <footer class="page">${entries.length} classes &middot; ${totalSwatches} swatches &middot; icon tier 44px, sprite tier 400px</footer>
 </main>
 <script>
@@ -813,6 +890,53 @@ const SPRITE_CATALOG = ${pageData};
     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"];
+  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 });
+    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>';
+    const frameImgEl = holder.querySelector(".swatch-img");
+    const frameLabelEl = holder.querySelector(".swatch-label");
+    let frameIndex = 0;
+    const showFrame = () => {
+      frameImgEl.innerHTML = frames[frameIndex].svg;
+      frameLabelEl.textContent = frames[frameIndex].label;
+    };
+    const stepFrame = () => { frameIndex = (frameIndex + 1) % frames.length; showFrame(); };
+    frameImgEl.addEventListener("click", stepFrame);
+    showFrame();
+    swatchRow.insertBefore(holder, swatchRow.firstChild);
+    cycleSteppers.push(stepFrame);
+  }
+  const reducedMotion = window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  if (cycleSteppers.length && !reducedMotion) {
+    setInterval(() => { for (const stepFrame of cycleSteppers) stepFrame(); }, 800);
+  }
 })();
 </script>
 ${dockScripts}