@polycode-projects/the-mechanical-code-talker 4.0.0 → 4.1.0

package/src/domain/scene-compose.mjs

@@ -0,0 +1,117 @@
+// scene-compose.mjs — the sprite catalog's "there is a…" box: which real
+// catalog classes a free-typed sentence names, and with which of that class's
+// own material labels.
+//
+// Naming a class is the engine's own job. This module segments the sentence
+// into candidate spans and hands each one to ask.mjs's resolveObject — the same
+// resolver the chat lanes use — over a graph whose individuals are the caller's
+// real classes. So the caller owns where a name might start and stop, and
+// nothing else: casing, leading articles and grain words come from the
+// resolver's own tiers, and a span carrying a word the index has no reading for
+// declines there rather than resolving past it.
+//
+// It lives in domain/ rather than beside the page that draws the scene because
+// the page's browser bundle needs it: routing through the real resolver means
+// the parser can't be spliced into the page as self-contained text any more.
+
+import { resolveObject } from "./ask.mjs";
+import { parseEntities } from "./codegraph.mjs";
+
+/** `text`'s lowercase word runs, the unit class names are matched against —
+ *  punctuation never fuses two real words into one token nor splits one real
+ *  word into two. */
+export 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;
+}
+
+const sceneClassGraphCache = new WeakMap();
+
+/** The `classIndex`'s own class names as a resolvable graph, one individual per
+ *  class, plus the longest class name's word count (the widest span worth
+ *  offering the resolver). Cached per index object: a page builds its index once
+ *  at load and then composes on every keystroke. */
+function sceneClassGraph(classIndex) {
+  const cached = sceneClassGraphCache.get(classIndex);
+  if (cached) return cached;
+  const names = Object.keys(classIndex).filter((name) => String(name).trim());
+  const built = {
+    graph: parseEntities({
+      individuals: names.map((name) => ({ id: `sprite-class:${name}`, label: name, class: "Class" })),
+      objectProperties: [],
+    }),
+    longestClassWordCount: names.reduce((max, name) => Math.max(max, name.trim().split(/\s+/).length), 0),
+  };
+  sceneClassGraphCache.set(classIndex, built);
+  return built;
+}
+
+/** The one resolver tier the composer draws on. Composing paints a picture, and
+ *  painting the wrong sprite is a silent lie the visitor can't audit, so only an
+ *  exact-grade resolution (resolveObject's tier 1, which its own leading-article
+ *  and grain-word retries reach too) earns a swatch. The containment and fuzzy
+ *  tiers below it read "wood" as the food class and "glass" as grass — right for
+ *  a question the engine answers in words and cites, wrong for a picture drawn
+ *  without comment. */
+const SCENE_EXACT_TIER = 1;
+
+/** The catalog class named by the longest still-unclaimed token span starting at
+ *  `start`, as `{className, wordCount}`, or null when the resolver grounds none
+ *  of them. Spans are offered widest-first, so a multi-word class name ("body of
+ *  water") always wins the position it starts at over a shorter class that would
+ *  otherwise fragment it. An ambiguous resolution is a miss: a span that reads as
+ *  several real classes names none of them. */
+function resolveSpanToClass(graph, classIndex, tokens, used, start, longestClassWordCount) {
+  const widest = Math.min(longestClassWordCount, tokens.length - start);
+  for (let wordCount = widest; wordCount >= 1; wordCount -= 1) {
+    let free = true;
+    for (let k = 0; k < wordCount && free; k += 1) free = !used[start + k];
+    if (!free) continue;
+    const span = tokens.slice(start, start + wordCount).map((t) => t.word).join(" ");
+    const resolved = resolveObject(graph, span);
+    const label = resolved?.match?.label;
+    if (!label || resolved.ambiguous || resolved.tier !== SCENE_EXACT_TIER) continue;
+    if (Object.prototype.hasOwnProperty.call(classIndex, label)) return { className: label, wordCount };
+  }
+  return null;
+}
+
+/** 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 (sprites.html'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). Pure. */
+export function extractSceneItems(text, classIndex) {
+  const index = classIndex || {};
+  const { graph, longestClassWordCount } = sceneClassGraph(index);
+  if (!longestClassWordCount) return [];
+  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 = resolveSpanToClass(graph, index, tokens, used, i, longestClassWordCount);
+    if (!hit) continue;
+    let materialLabel = null;
+    if (i > 0 && !used[i - 1]) {
+      const materials = index[hit.className]?.materials || {};
+      const prevWord = tokens[i - 1].word;
+      if (Object.prototype.hasOwnProperty.call(materials, prevWord)) {
+        materialLabel = prevWord;
+        used[i - 1] = true;
+      }
+    }
+    for (let k = 0; k < hit.wordCount; k += 1) used[i + k] = true;
+    items.push({ className: hit.className, materialLabel });
+  }
+  return items;
+}

package/src/domain/spider-fly-world.mjs

@@ -122,7 +122,7 @@ export const SEED_TAXONOMY = Object.freeze([
 ]);
 
 export const WORLD_OPENING =
-  "a spider waits in its web; a fly drifts in from the edge of the board. Neither is yours to move — watch, or address one by name in chat.";
+  "a spider waits in its web; a fly drifts in from the edge of the board. Neither is yours to move. Watch, or address one by name in chat.";
 
 /** Every fact row the shipped world source carries: cell typing, grid
  *  adjacency (mgx:has-exit-<direction>), the web block (mgx:in-web) and the
@@ -207,6 +207,42 @@ export function worldMetaRow() {
   return { world: WORLD_NAME, kind: "meta", opening: WORLD_OPENING };
 }
 
+/** The class an agent id names — "spider-2" -> "spider", "fly-10" -> "fly",
+ *  "egg-1" -> "egg" — the one regex every caller that needs an individual's
+ *  kind from its id string shares. Self-contained (no outer refs),
+ *  `.toString()`-splice safe. */
+export function agentKindOf(id) {
+  return String(id).replace(/-\d+$/, "");
+}
+
+/** Every live id of `kind` among `agents`, sorted. `agents` is either a
+ *  plain `{ id: ... }` roster (runSpiderFlyTick's/foldSpiderFlyState's own
+ *  agents map, already excluding anything dead) or a `Map` keyed by id
+ *  (foldSpiderFlyState's own `state.placements`, which still carries a dead
+ *  individual's last-known cell) — pass the matching `state.removed` Set as
+ *  `removed` in the Map case to exclude those; omit it for a plain roster
+ *  that has no such concept. Pure. */
+export function liveIdsOfKind(agents, kind, removed = null) {
+  const re = new RegExp(`^${kind}-\\d+$`);
+  const ids = agents instanceof Map ? [...agents.keys()] : Object.keys(agents || {});
+  return ids.filter((id) => re.test(id) && !(removed && removed.has(id))).sort();
+}
+
+/** True for a web individual's own id ("web-3") — a spider-built web is
+ *  placed via mgx:currently-in exactly like a live agent, but it is never
+ *  one. */
+export function isWebIndividualId(id) {
+  return /^web-\d+$/.test(id);
+}
+
+/** Whether `id` belongs on a rendered agent roster built from `state`
+ *  (foldSpiderFlyState's own shape): live (not in `state.removed`) and not a
+ *  web individual. The one world rule a browser-side snapshot needs to skip
+ *  the same two things every renderer of `state.placements` must skip. */
+export function isLiveRenderableAgent(id, state) {
+  return !state.removed.has(id) && !isWebIndividualId(id);
+}
+
 /** A minimal, inert rule-row family, so scripts/build-worlds-pack.mjs's
  *  shared validator ("every world needs at least one rule row") passes.
  *  src/services/spider-fly.mjs never reads these back: grid movement is

package/src/domain/sprite-request.mjs

@@ -0,0 +1,156 @@
+// sprite-request.mjs — one sprite request ("the large sprite for a happy
+// spider") resolved to markup PLUS the chain that found it. This is the pure
+// core the tmct_sprite tool handler wraps and the spider-and-fly page splices,
+// so the page and the tool answer the same question with the same code instead
+// of two hand-kept call sites drifting apart.
+//
+// Every collaborator is INJECTED rather than imported — sprite-templates.mjs's
+// resolveSpriteAsset, sprite-map.mjs's classAncestorChain, sprite-size.mjs's
+// sizeScaleFor, sprite-expressions.mjs's EXPRESSION_PALETTE. Same reason
+// spider-fly-viz.mjs's threadCellsForSpiderPlan takes its grid geometry as an
+// argument: a function with no module-scope references survives `.toString()`
+// splicing into a page script, and the browser already holds its own copies of
+// those primitives on window.tmctSpiderFly.
+//
+// The resolution CHAIN is derived by OBSERVATION, never by re-implementing
+// sprite-templates.mjs's specificity order. At each term of the ancestor chain
+// the same resolver is asked to resolve that ONE term against an empty
+// registry, so "did this level match" is answered by the real resolver rather
+// than by a copy of its rules that can drift out of step with it. Whether a
+// requested expression was actually honoured is observed the same way: resolve
+// once with the mgx:feels fact and once without, and compare.
+//
+// The two optional slots carry two different senses:
+//   - `expression` becomes an `mgx:feels` fact, the parameter every
+//     *-with-emotion template selects on.
+//   - `size` becomes an `mgx:hasProperty` fact and resolves to a numeric render
+//     SCALE (sprite-size.mjs's own closed scale table). It is the taught size of
+//     the thing being drawn, not a choice of template tier — the caller picks
+//     the tier by which template set it hands in.
+//
+// Nothing here refuses. A caller that needs a miss wall (the tool does) reads
+// `fellBackToRoot` / `expressionApplied` / `sizeKnown` / `expressionKnown` and
+// decides; a caller that wants today's fall-through-to-the-root-sprite
+// behaviour (the page does) just reads `svg`.
+
+/**
+ * Resolve `request` (`{ class, expression?, size? }`) against a template set.
+ *
+ * `deps` carries the injected collaborators and the state to resolve against:
+ * `resolveSpriteAsset` (required), `templates`, `spriteRegistry`, `factRows`
+ * (the taxonomy rows the ancestor walk reads), `rootFallback`, `instanceKey`,
+ * and — for the reported chain and vocabulary checks — `classAncestorChain`,
+ * `sizeScaleFor` and `expressionPalette`. Omit any of the last three and the
+ * fields they feed come back `null` rather than guessed.
+ *
+ * Returns `{ class, expression, size, svg, scale, sizeKnown, expressionKnown,
+ * expressionApplied, rootFallback, fellBackToRoot, chain, matched }`. Pure.
+ */
+export function resolveSpriteRequest(request, deps) {
+  const FEELS_PREDICATE = "mgx:feels";
+  const PROPERTY_PREDICATE = "mgx:hasProperty";
+
+  const className = String((request && request.class) || "").trim();
+  const expression = String((request && request.expression) || "").trim();
+  const size = String((request && request.size) || "").trim();
+
+  const options = deps || {};
+  const resolveAsset = options.resolveSpriteAsset;
+  if (typeof resolveAsset !== "function") {
+    throw new TypeError("resolveSpriteRequest needs deps.resolveSpriteAsset");
+  }
+  const templates = options.templates || [];
+  const registry = options.spriteRegistry || {};
+  const factRows = options.factRows || [];
+  const rootFallback = options.rootFallback || "animal";
+  const walkAncestors = options.classAncestorChain;
+  const scaleFor = options.sizeScaleFor;
+  const palette = options.expressionPalette;
+
+  const propertyFacts = [];
+  if (expression) propertyFacts.push({ predicate: FEELS_PREDICATE, object: expression });
+  if (size) propertyFacts.push({ predicate: PROPERTY_PREDICATE, object: size });
+
+  const assetOptions = { rootFallback };
+  if (options.instanceKey) assetOptions.instanceKey = options.instanceKey;
+  const svg = resolveAsset(className, factRows, propertyFacts, templates, registry, assetOptions);
+
+  // One resolve of a SINGLE term against an empty registry and its own root:
+  // the real resolver's answer to "does this level of the chain match", with no
+  // ancestor walk and no fall-through of its own.
+  const templateAt = (term) => resolveAsset(term, [], propertyFacts, templates, {}, { rootFallback: term });
+  const carriedByRegistry = (term) => Object.prototype.hasOwnProperty.call(registry, term);
+
+  // The template that produced `hit` at `term`: a fully-specific variant and a
+  // plain class template both hand their `svg` through untouched, so equality
+  // finds them; a parameterized template's substitutions change the string, and
+  // it is the only remaining candidate shape resolveAtTerm can have used.
+  const templateBehind = (term, hit) => {
+    const candidates = templates.filter((t) => t && Array.isArray(t.classes) && t.classes.indexOf(term) >= 0);
+    const authored = candidates.find((t) => t.svg === hit);
+    const template = authored || candidates.find((t) => !t.match && t.parameters) || null;
+    if (!template) return null;
+    return {
+      classes: template.classes.slice(),
+      parameters: Object.keys(template.parameters || {}).sort(),
+      match: template.match || null,
+    };
+  };
+
+  let chain = null;
+  let matched = null;
+  if (typeof walkAncestors === "function") {
+    chain = [];
+    for (const term of walkAncestors(className, factRows)) {
+      const hit = templateAt(term);
+      chain.push({ term, template: Boolean(hit), registry: carriedByRegistry(term) });
+      if (hit) {
+        matched = { term, via: "template", hops: chain.length - 1, root: false, template: templateBehind(term, hit) };
+        break;
+      }
+      if (carriedByRegistry(term)) {
+        matched = { term, via: "registry", hops: chain.length - 1, root: false, template: null };
+        break;
+      }
+    }
+    if (!matched) {
+      const rootHit = templateAt(rootFallback);
+      chain.push({ term: rootFallback, template: Boolean(rootHit), registry: carriedByRegistry(rootFallback), root: true });
+      matched = {
+        term: rootFallback,
+        via: rootHit ? "template" : "registry",
+        hops: chain.length - 1,
+        root: true,
+        template: rootHit ? templateBehind(rootFallback, rootHit) : null,
+      };
+    }
+  }
+
+  // Compared without the instance-id namespacing, which rewrites gradient ids
+  // and would make two otherwise identical resolutions look different.
+  const plainSvg = options.instanceKey
+    ? resolveAsset(className, factRows, propertyFacts, templates, registry, { rootFallback })
+    : svg;
+  const withoutExpression = expression
+    ? resolveAsset(className, factRows, propertyFacts.filter((f) => f.predicate !== FEELS_PREDICATE), templates, registry, { rootFallback })
+    : null;
+
+  return {
+    class: className,
+    expression: expression || null,
+    size: size || null,
+    svg,
+    scale: typeof scaleFor === "function" ? scaleFor(propertyFacts) : 1,
+    sizeKnown: size && typeof scaleFor === "function"
+      ? scaleFor([{ predicate: PROPERTY_PREDICATE, object: size }]) !== 1
+      : null,
+    expressionKnown: expression && palette
+      ? Object.prototype.hasOwnProperty.call(palette, expression)
+      : null,
+    expressionApplied: expression ? plainSvg !== withoutExpression : null,
+    rootFallback,
+    fellBackToRoot: matched ? Boolean(matched.root) : null,
+    chain,
+    matched,
+  };
+}

package/src/domain/sprite-templates.mjs

@@ -21,12 +21,41 @@
 //     substitution (e.g. `black = "#22201d"`). A value with no entry in that
 //     map is not a match for this template at all — it falls through to a
 //     less specific one, never a guessed/invented substitution.
-//   - a fully-specific hand-authored VARIANT — `{class}-with-{property}-
-//     {value}.toml` (e.g. a hypothetical `dog-with-colour-black.toml`, not
-//     authored this pass) — carries the same `classes` as the class it
-//     specializes, plus a `[match]` table (`property`, `value`) naming the
-//     exact fact it requires, so it outranks the parameterized template
-//     when both would otherwise apply.
+//   - a fully-specific hand-authored VARIANT — carries the same `classes`
+//     as the class it specializes, plus a `[match]` table (`property`,
+//     `value`) naming the exact fact it requires, so it outranks the
+//     parameterized template when both would otherwise apply. The filename
+//     is free-form and reads `{class}-{what it shows}` in practice
+//     (`portrait-round.toml` for mgx:hasProperty = round,
+//     `bear-facing-left.toml` for mgx:faces = left) — the `[match]` table,
+//     never the name, is what selects it.
+//
+// A variant can require MORE THAN ONE fact at once, written as repeated
+// `[[match]]` tables (the array-of-tables idiom data/templates/
+// grammar-rules.toml's own `[[rule]]` already uses) instead of a single
+// `[match]` one. Every entry must hold for the variant to be selected, so
+// `bear-facing-left-moving.toml` asks for mgx:faces = left AND
+// mgx:pose = moving and draws the left profile mid-stride. The two spellings
+// are one constraint or many, never a different meaning: a lone `[match]`
+// table is exactly a one-entry list, which is why every file authored before
+// the plural spelling existed still resolves byte-for-byte as it did.
+//
+// Where two satisfied variants overlap, the one requiring MORE facts wins —
+// an instance taught both the facing and the pose gets the combined art, and
+// the same instance taught only the facing gets the plain profile, because
+// the combined variant's second constraint no longer holds. Specificity is
+// counted from the constraints, never read off the filename, so adding a
+// file can't silently reorder what an existing instance resolves to.
+//
+// The two kinds compose rather than exclude each other: a VARIANT may also
+// declare its own `[parameters.*]` tables, and once its `[match]` selects
+// it those parameters fill from the instance's OTHER facts (the facing pair
+// files each carry `[face]` + `[parameters.emotion]`, so a bear taught both
+// mgx:faces = left and mgx:feels = happy renders the left profile wearing
+// the happy face). A satisfied `[match]` is the instance naming this art
+// directly, so a variant is never allowed to fall through the way an
+// unfilled parameterized template is — any placeholder no fact filled is
+// dropped instead, which keeps the returned markup complete.
 //
 // A parameterized template's `[parameters.<name>]` table comes in two
 // shapes, picked by which of `placeholder`/`placeholders` it declares:
@@ -57,9 +86,10 @@
 //
 // Specificity order, checked at EACH term of the class's ancestor chain
 // (nearest first, sprite-map.mjs's own classAncestorChain) before moving to
-// the next ancestor: an exact fully-specific variant whose [match] is
-// satisfied > a parameterized template filled with an observed matching
-// value > a plain class template > (repeat at the next ancestor) > the
+// the next ancestor: the satisfied fully-specific variant requiring the most
+// facts (filled from its own [parameters.*] if it declares any) > a
+// parameterized template filled with an observed matching value > a plain
+// class template > (repeat at the next ancestor) > the
 // existing flat spriteRegistry entry for that same term (so a class not yet
 // migrated to its own template keeps resolving exactly as it did before this
 // module existed) > once the chain is exhausted, the same three-step check
@@ -68,14 +98,77 @@
 import { classAncestorChain } from "./sprite-map.mjs";
 import { namespaceSvgIds } from "./svg-instance-ids.mjs";
 
+/** The predicate a variant matches on to pick a facing angle. */
+export const FACING_PROPERTY = "mgx:faces";
+
+/** The predicate a variant matches on to pick a pose. */
+export const POSE_PROPERTY = "mgx:pose";
+
+/** The facing angles a variant's [match] may require of mgx:faces — a
+ *  turntable read as five steps, of which four are named. Centre is the
+ *  ABSENT fact, never a word here: a figure with nothing on record about
+ *  which way it faces already renders its own front-facing art, so spending
+ *  a value on that would give one picture two names and let an instance ask
+ *  for the front view two different ways. */
+export const FACING_VALUES = Object.freeze(["left", "half-left", "half-right", "right"]);
+
+/** The poses a variant's [match] may require of mgx:pose. At rest is the
+ *  ABSENT fact, the same reasoning centre-facing gets above: a figure with no
+ *  pose on record is standing still, and that is what every plain template
+ *  already draws. "moving" is the one intermediate frame between two rests —
+ *  the read a walk cycle needs and the only pose that has to exist before
+ *  movement can be animated at all. */
+export const POSE_VALUES = Object.freeze(["moving"]);
+
 /** Every template in `templates` whose `classes` list names `term`. */
 function templatesForClass(term, templates) {
   return (templates || []).filter((t) => Array.isArray(t?.classes) && t.classes.includes(term));
 }
 
-function matchSatisfied(match, propertyFacts) {
-  if (!match || !match.property || match.value === undefined) return false;
-  return (propertyFacts || []).some((f) => f.predicate === match.property && f.object === match.value);
+/** One template's `[match]`/`[[match]]` tables as a flat list of raw entries,
+ *  whichever of the two spellings it used — the shape every reader wants
+ *  before it decides anything, so no caller re-answers "did I get a table or
+ *  a list of them" for itself. */
+function matchEntries(template) {
+  const match = template?.match;
+  if (!match) return [];
+  return Array.isArray(match) ? match : [match];
+}
+
+/**
+ * Every `{property, value}` fact one template's `[match]` requires, all of
+ * which must hold for the variant to apply. A single `[match]` table yields
+ * one constraint, repeated `[[match]]` tables one each, and a template with
+ * no `[match]` at all yields none. An entry missing either half is dropped
+ * rather than treated as a wildcard — a half-written constraint must never
+ * widen what a variant claims to match (spriteTemplateProblems reports it as
+ * the authoring mistake it is). Pure.
+ */
+export function matchConstraints(template) {
+  return matchEntries(template).filter((c) => c?.property && c.value !== undefined);
+}
+
+function matchSatisfied(constraints, propertyFacts) {
+  if (!constraints.length) return false;
+  return constraints.every((c) => (propertyFacts || []).some((f) => f.predicate === c.property && f.object === c.value));
+}
+
+/** The satisfied `[match]` variant among `candidates` requiring the MOST
+ *  facts, or null when none is satisfied — so a combined facing-and-pose
+ *  variant outranks the facing-only one it shares an angle with, and drops
+ *  back to it the moment the instance stops carrying the pose. A tie keeps
+ *  the earliest candidate, which is the load order the caller handed in. */
+function bestSatisfiedVariant(candidates, propertyFacts) {
+  let best = null;
+  let bestCount = 0;
+  for (const t of candidates) {
+    const constraints = matchConstraints(t);
+    if (constraints.length <= bestCount) continue;
+    if (!matchSatisfied(constraints, propertyFacts)) continue;
+    best = t;
+    bestCount = constraints.length;
+  }
+  return best;
 }
 
 /** Substitute one matched `[parameters.*.values]` entry into `svg`: a plain
@@ -123,15 +216,47 @@ function parameterizedFillAll(template, propertyFacts) {
   return filledCount > 0 ? svg : null;
 }
 
+/** Every placeholder token a template's own `[parameters.*]` tables name,
+ *  across both shapes — the single `placeholder` and every token in a
+ *  `placeholders` table. */
+function declaredPlaceholderTokens(template) {
+  const tokens = [];
+  for (const param of Object.values(template.parameters || {})) {
+    if (param?.placeholder) tokens.push(param.placeholder);
+    for (const token of Object.values(param?.placeholders || {})) tokens.push(token);
+  }
+  return tokens;
+}
+
+/** `svg` with every token `template` declares that no observed fact filled
+ *  dropped outright. Only the [match]-selected path wants this: a satisfied
+ *  [match] means the instance asked for THIS art by name, so the variant
+ *  can't fall through to a less specific template the way an unfilled
+ *  parameterized template does, and dropping the leftover token is what
+ *  keeps the returned markup complete rather than shipping a literal
+ *  "{{FACE}}" into the page. */
+function withUnfilledPlaceholdersDropped(template, svg) {
+  let out = svg;
+  for (const token of declaredPlaceholderTokens(template)) out = out.split(token).join("");
+  return out;
+}
+
 /** Resolve ONE class term (no ancestor walk here — the caller repeats this
  *  at every level of the chain) against the template set, in specificity
  *  order: fully-specific match variant > parameterized template filled with
- *  an observed value > plain class template. Returns the SVG string, or null
- *  when nothing at this level matches. */
+ *  an observed value > plain class template. Among satisfied match variants
+ *  the most demanding one wins (bestSatisfiedVariant). A match variant that
+ *  declares its own `[parameters.*]` is filled from them first, so a facing
+ *  profile also carrying `[face]`/`[parameters.emotion]` renders the mood the
+ *  instance's own mgx:feels fact names. Returns the SVG string, or null when
+ *  nothing at this level matches. */
 function resolveAtTerm(term, propertyFacts, templates) {
   const candidates = templatesForClass(term, templates);
-  const matched = candidates.find((t) => t.match && matchSatisfied(t.match, propertyFacts));
-  if (matched) return matched.svg;
+  const matched = bestSatisfiedVariant(candidates, propertyFacts);
+  if (matched && !matched.parameters) return matched.svg;
+  if (matched) {
+    return withUnfilledPlaceholdersDropped(matched, parameterizedFillAll(matched, propertyFacts) || matched.svg);
+  }
   for (const t of candidates) {
     if (t.match || !t.parameters) continue;
     const filled = parameterizedFillAll(t, propertyFacts);
@@ -185,12 +310,22 @@ export function resolveSpriteAsset(className, factRows, propertyFacts, templates
  *  names a `property` and exactly one of `placeholder`/`placeholders` (every
  *  token named appears in `svg`), its `values` map is non-empty and every
  *  entry matches the shape its own `placeholder`/`placeholders` choice
- *  expects, a `[match]` table names both `property` and `value`, and
+ *  expects, every `[match]`/`[[match]]` entry names both `property` and
+ *  `value`, no two entries demand different values of the SAME property (a
+ *  constraint set no instance can ever satisfy is dead art, not a stricter
+ *  variant), a constraint on one of the two CLOSED axes names a value that
+ *  axis actually has (mgx:faces one of FACING_VALUES, mgx:pose one of
+ *  POSE_VALUES — every other predicate stays open, since a variant may match
+ *  on any fact at all, mgx:hasProperty included), and
  *  `[face]`/`[parameters.emotion]` are always declared TOGETHER — a face
  *  anchor with nothing to select it, or an emotion parameter with nowhere to
  *  position its face fragment, is a real authoring mistake either way
  *  (sprite-expressions.mjs's own header explains why the face fragment
- *  needs the pairing). */
+ *  needs the pairing). Every check reads the tables a template actually
+ *  declares and none of them cares whether a `[match]` sits alongside, so a
+ *  facing variant carrying `[match]` + `[face]` + `[parameters.emotion]` is
+ *  held to exactly the same pairing and placeholder rules as a plain
+ *  `*-with-emotion.toml` file. */
 export function spriteTemplateProblems(template) {
   const problems = [];
   const t = template || {};
@@ -231,8 +366,22 @@ export function spriteTemplateProblems(template) {
       }
     }
   }
-  if (t.match && (!t.match.property || t.match.value === undefined)) {
-    problems.push("match is missing property or value");
+  const entries = matchEntries(t);
+  for (const entry of entries) {
+    if (!entry?.property || entry?.value === undefined) problems.push("match is missing property or value");
+  }
+  const requiredBy = new Map();
+  for (const { property, value } of matchConstraints(t)) {
+    if (requiredBy.has(property) && requiredBy.get(property) !== value) {
+      problems.push(`match requires ${property} to be both "${requiredBy.get(property)}" and "${value}" — no instance can satisfy that`);
+    }
+    requiredBy.set(property, value);
+    if (property === FACING_PROPERTY && !FACING_VALUES.includes(value)) {
+      problems.push(`match requires ${FACING_PROPERTY} "${value}", which is not one of the turntable's angles (${FACING_VALUES.join(", ")}; the centre view is the absent fact)`);
+    }
+    if (property === POSE_PROPERTY && !POSE_VALUES.includes(value)) {
+      problems.push(`match requires ${POSE_PROPERTY} "${value}", which is not one of the known poses (${POSE_VALUES.join(", ")}; at rest is the absent fact)`);
+    }
   }
   if (t.face && !t.parameters?.emotion) {
     problems.push("face is declared without parameters.emotion — a face anchor with nothing to select it is dead data");

package/src/services/adventure-editor.mjs

@@ -14,10 +14,13 @@
 // mgx:acts-toward, mgx:is-objective) — an editor has to show and change
 // exactly the facts a player is never told.
 //
-// No imports: every export here is .toString()-splice-safe, the same
-// discipline adventure-viz.mjs's own render-glue functions hold (see that
-// module's header) — this module's functions get spliced directly into the
-// adventure page's inline script the same way.
+// No imports of its own logic: every export here is .toString()-splice-safe,
+// the same discipline adventure-viz.mjs's own render-glue functions hold (see
+// that module's header) — this module's functions get spliced directly into
+// the adventure page's inline script the same way. The one exception,
+// wordBeforeCursor, re-exports viz-theme.mjs's own shared copy (byte-identical
+// to what used to live here, and to mud-editor.mjs's own copy) rather than
+// keep a third copy of the same regex.
 //
 // Two predicate families get different sync strategies, on purpose:
 //   - PLACEMENT/OPENNESS (mgx:currently-in/located-in/fixed-in/stands-
@@ -357,13 +360,4 @@ export function planWorldEditorSync(rows, state, triples) {
 
 // ---- cursor-driven suggestions ---------------------------------------------
 
-/** The word immediately before `cursorPos` in `text` — a run of letters/
- *  digits/hyphens, the same token shape this vocabulary's own terms use
- *  (kebab-case room names like "drawing-room"). Empty string when the
- *  cursor sits after whitespace/punctuation with no word directly behind
- *  it. Pure. */
-export function wordBeforeCursor(text, cursorPos) {
-  const head = String(text || "").slice(0, cursorPos);
-  const m = head.match(/[A-Za-z][A-Za-z0-9-]*$/);
-  return m ? m[0].toLowerCase() : "";
-}
+export { wordBeforeCursor } from "./viz-theme.mjs";