@polycode-projects/the-mechanical-code-talker 2.7.24 → 2.7.25

package/data/sprites/adventurer.toml

@@ -0,0 +1,5 @@
+# adventurer — the player's own sprite: the person silhouette plus a
+# strap-and-satchel, so the one individual the player controls always
+# reads as visually distinct from the room's own cast of NPCs.
+classes = ["adventurer"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.6" r="3.3" fill="currentColor"/><path d="M6 21 C6 15.3 8.7 12.8 12 12.8 C15.3 12.8 18 15.3 18 21 Z" fill="currentColor"/><path d="M8.4 13.4 L17 17.6" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" opacity="0.85"/><rect x="14.6" y="15.8" width="5" height="4.6" rx="1" fill="currentColor" opacity="0.6"/><rect x="16.3" y="16.6" width="1.6" height="1.2" rx="0.3" fill="currentColor" opacity="0.9"/></svg>"""

package/data/sprites/animal.toml

@@ -0,0 +1,6 @@
+# animal — the deliberately plainest shape in the set: an unadorned
+# four-legged blob, so an unregistered species reads as "some animal"
+# rather than suggesting one the taxonomy never named. The declared root
+# fallback for the spider-and-fly world.
+classes = ["animal"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="12" cy="13" rx="7" ry="4.4" fill="currentColor"/><circle cx="12" cy="7" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="7" y1="17" x2="7" y2="21"/><line x1="17" y1="17" x2="17" y2="21"/></g></svg>"""

package/data/sprites/butler.toml

@@ -0,0 +1,8 @@
+# butler — Ashcombe Hall's own butler: the person silhouette plus a stiff
+# wing-collar flaring OUT past the shoulder line (changing the outer
+# silhouette, not an internal opacity knockout — an internal light-on-dark
+# accent was tried first and proved invisible once shrunk to 44px; a
+# silhouette change survives shrinking the way gardener.toml's wide brim
+# does) and a bow-tie.
+classes = ["butler"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.6" r="3.3" fill="currentColor"/><path d="M6 21 C6 15.3 8.7 12.8 12 12.8 C15.3 12.8 18 15.3 18 21 Z" fill="currentColor"/><path d="M7.6 11.6 L11.3 13.2 L8.6 15.4 Z" fill="currentColor"/><path d="M16.4 11.6 L12.7 13.2 L15.4 15.4 Z" fill="currentColor"/><path d="M10.6 14.2 L12 16.1 L13.4 14.2 L12 18.6 Z" fill="currentColor" opacity="0.95"/></svg>"""

package/data/sprites/cabinet.toml

@@ -0,0 +1,5 @@
+# cabinet — Ashcombe Hall's own locked cabinet (a container): a two-door
+# wardrobe silhouette, the gap between the doors reading as the seam, with
+# two knobs and a cornice band.
+classes = ["cabinet"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="4.5" y="2.5" width="7.2" height="19" rx="1" fill="currentColor"/><rect x="12.3" y="2.5" width="7.2" height="19" rx="1" fill="currentColor"/><rect x="4.5" y="2.5" width="15" height="1.4" fill="currentColor" opacity="0.4"/><circle cx="10.6" cy="12" r="0.9" fill="currentColor" opacity="0.35"/><circle cx="13.4" cy="12" r="0.9" fill="currentColor" opacity="0.35"/></svg>"""

package/data/sprites/container.toml

@@ -0,0 +1,5 @@
+# container — the generic fallback for any container with no sprite of
+# its own (see cabinet/portrait for Ashcombe Hall's own two): a solid
+# chest silhouette with a carved lid-seam and a latch highlight.
+classes = ["container"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M3 10 L5 5 H19 L21 10 Z" fill="currentColor"/><rect x="3" y="10" width="18" height="10" rx="1.2" fill="currentColor"/><rect x="3" y="10" width="18" height="1.6" fill="currentColor" opacity="0.35"/><rect x="10.6" y="9.2" width="2.8" height="2.6" rx="0.5" fill="currentColor" opacity="0.85"/></svg>"""

package/data/sprites/cook.toml

@@ -0,0 +1,7 @@
+# cook — Ashcombe Hall's own cook: the person silhouette topped with a
+# chef's toque puffing out WIDER than the head (the same "wider than the
+# head reads as a separate garment at 44px" move gardener.toml's brim and
+# housekeeper.toml's cap use — a same-width tall hat read as just an
+# elongated head once shrunk, tried and rejected first).
+classes = ["cook"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="12" cy="3.4" rx="5.4" ry="3" fill="currentColor"/><rect x="8.6" y="5.6" width="6.8" height="2.2" rx="0.6" fill="currentColor"/><circle cx="12" cy="10" r="3.1" fill="currentColor"/><path d="M6 21 C6 15.6 8.7 13.2 12 13.2 C15.3 13.2 18 15.6 18 21 Z" fill="currentColor"/></svg>"""

package/data/sprites/desk.toml

@@ -0,0 +1,4 @@
+# desk — Ashcombe Hall's own study desk: a tabletop bar over two drawer
+# blocks with pull-knobs, on tapered legs.
+classes = ["desk"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="7" width="18" height="2.6" rx="0.6" fill="currentColor"/><rect x="4.4" y="9.6" width="6.6" height="5.6" rx="0.6" fill="currentColor" opacity="0.85"/><rect x="13" y="9.6" width="6.6" height="5.6" rx="0.6" fill="currentColor" opacity="0.85"/><circle cx="9.6" cy="12.4" r="0.55" fill="currentColor" opacity="0.4"/><circle cx="16.4" cy="12.4" r="0.55" fill="currentColor" opacity="0.4"/><path d="M4.6 15.2 L3.8 20.5 L5.6 20.5 L6.2 15.2 Z" fill="currentColor"/><path d="M17.8 15.2 L17.2 20.5 L19 20.5 L18.2 15.2 Z" fill="currentColor"/></svg>"""

package/data/sprites/dog-with-colour.toml

@@ -0,0 +1,20 @@
+# dog-with-colour — the parameterized-property worked example
+# (PLAN target: "a dog that is black"). Same silhouette as dog.toml, but
+# every filled shape takes its color from the instance's OWN observed
+# mgx:hasProperty value rather than the page's currentColor accent, with a
+# thin currentColor stroke kept on each shape so a light value (white)
+# still reads against a light card background. A property value with no
+# entry in [parameters.colour.values] is not a match for this template at
+# all (see sprite-templates.mjs's own header for the naming/specificity
+# convention) — it falls through to the plain dog.toml sprite, never a
+# guessed color.
+classes = ["dog"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="13" cy="15" rx="6.4" ry="4.3" fill="{{FILL}}" stroke="currentColor" stroke-width="0.9"/><circle cx="7" cy="9" r="3.6" fill="{{FILL}}" stroke="currentColor" stroke-width="0.9"/><path d="M4.5 6.5 L2 3 L6 5 Z" fill="{{FILL}}" stroke="currentColor" stroke-width="0.9"/><path d="M19 13 C22 12 22.5 15 20 16 Z" fill="{{FILL}}" stroke="currentColor" stroke-width="0.9"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="9" y1="19" x2="9" y2="22"/><line x1="17" y1="19" x2="17" y2="22"/></g></svg>"""
+
+[parameters.colour]
+property = "mgx:hasProperty"
+placeholder = "{{FILL}}"
+
+[parameters.colour.values]
+black = "#22201d"
+white = "#f5f2ea"

package/data/sprites/dog.toml

@@ -0,0 +1,5 @@
+# dog — the plain-class sprite a taxonomy hop away from poodle/sheepdog.
+# Same body language as poodle's, without the pompom cut, so the family
+# reads as one dog rather than two unrelated animals.
+classes = ["dog"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="13" cy="15" rx="6.4" ry="4.3" fill="currentColor"/><circle cx="7" cy="9" r="3.6" fill="currentColor"/><ellipse cx="6.1" cy="8" rx="1" ry="1.3" fill="currentColor" opacity="0.3"/><path d="M4.5 6.5 L2 3 L6 5 Z" fill="currentColor"/><path d="M19 13 C22 12 22.5 15 20 16 Z" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="9" y1="19" x2="9" y2="22"/><line x1="17" y1="19" x2="17" y2="22"/></g></svg>"""

package/data/sprites/egg.toml

@@ -0,0 +1,4 @@
+# egg — the spider-and-fly board's laid egg. The plain shell silhouette
+# plus one small carved highlight.
+classes = ["egg"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 2 C7 2 4 10 4 15.5 C4 20 7.6 22 12 22 C16.4 22 20 20 20 15.5 C20 10 17 2 12 2 Z" fill="currentColor"/><ellipse cx="9.6" cy="9.5" rx="1.7" ry="2.4" fill="currentColor" opacity="0.28"/></svg>"""

package/data/sprites/fly.toml

@@ -0,0 +1,5 @@
+# fly — the spider-and-fly board's other agent. A round head, a tapered
+# body with a carved highlight, translucent wings, and two thin trailing
+# legs for a touch of character at rest.
+classes = ["fly"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="12" cy="13.6" rx="3.4" ry="5.2" fill="currentColor"/><circle cx="12" cy="7" r="2.7" fill="currentColor"/><ellipse cx="11.1" cy="12" rx="1.1" ry="1.7" fill="currentColor" opacity="0.3"/><g fill="currentColor" opacity="0.55"><path d="M9 10 C3 6 2 4 3 2 C6 2 9 6 10.5 10 Z"/><path d="M15 10 C21 6 22 4 21 2 C18 2 15 6 13.5 10 Z"/></g><g stroke="currentColor" stroke-width="1" stroke-linecap="round"><path d="M9.6 17 L7.4 19.4"/><path d="M14.4 17 L16.6 19.4"/></g></svg>"""

package/data/sprites/furniture.toml

@@ -0,0 +1,5 @@
+# furniture — the generic fallback for any furniture piece with no sprite
+# of its own: a solid console-table silhouette (tapered legs, a carved
+# highlight along the top edge), replacing the old hollow-shelf outline.
+classes = ["furniture"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3.5" y="6.5" width="17" height="3.2" rx="0.8" fill="currentColor"/><rect x="3.5" y="6.5" width="17" height="1" fill="currentColor" opacity="0.35"/><path d="M5.6 9.7 L4.6 20 L6.7 20 L7.2 9.7 Z" fill="currentColor"/><path d="M18.4 9.7 L16.8 20 L18.9 20 L19.4 9.7 Z" fill="currentColor"/></svg>"""

package/data/sprites/gardener.toml

@@ -0,0 +1,4 @@
+# gardener — Ashcombe Hall's own gardener: the person silhouette under a
+# wide sunhat brim.
+classes = ["gardener"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="12" cy="5.6" rx="7.4" ry="2" fill="currentColor"/><path d="M8.8 5.2 C8.8 3.1 10.2 1.6 12 1.6 C13.8 1.6 15.2 3.1 15.2 5.2 C15.2 5.6 15.1 6 15 6.3 L9 6.3 C8.9 6 8.8 5.6 8.8 5.2 Z" fill="currentColor" opacity="0.85"/><circle cx="12" cy="8.6" r="3.1" fill="currentColor"/><path d="M6 21 C6 15.5 8.7 13.1 12 13.1 C15.3 13.1 18 15.5 18 21 Z" fill="currentColor"/></svg>"""

package/data/sprites/housekeeper.toml

@@ -0,0 +1,6 @@
+# housekeeper — Ashcombe Hall's own housekeeper: the person silhouette
+# under a wide mob-cap brim (deliberately WIDER than the head, the same
+# "wide silhouette reads at 44px" move gardener.toml's sunhat uses) and a
+# tied apron line.
+classes = ["housekeeper"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="12" cy="4.6" rx="5.6" ry="2.1" fill="currentColor"/><path d="M8.6 5 C8.6 3 10 1.7 12 1.7 C14 1.7 15.4 3 15.4 5 L15.4 5.6 L8.6 5.6 Z" fill="currentColor" opacity="0.9"/><circle cx="12" cy="7.6" r="3.1" fill="currentColor"/><path d="M6 21 C6 15.5 8.7 13.1 12 13.1 C15.3 13.1 18 15.5 18 21 Z" fill="currentColor"/><path d="M9 16 C10 15.4 14 15.4 15 16" fill="none" stroke="currentColor" stroke-width="1" opacity="0.45" stroke-linecap="round"/></svg>"""

package/data/sprites/key.toml

@@ -0,0 +1,5 @@
+# key — Ashcombe Hall's own key (hidden in the portrait, unlocks the
+# cabinet): a classic round-bow skeleton key, bold strokes so it stays
+# legible at a 44px render.
+classes = ["key"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="7" cy="9" r="4.4" fill="none" stroke="currentColor" stroke-width="2.4"/><path d="M10.4 12 L19.5 21.1" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"/><path d="M16.4 17.1 L18.6 14.9" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><path d="M18.6 19.3 L20.6 17.3" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>"""

package/data/sprites/lamp.toml

@@ -0,0 +1,4 @@
+# lamp — Ashcombe Hall's own study lamp: a Victorian hurricane-lamp
+# silhouette — base, glass globe, a neck, and a small carved flame.
+classes = ["lamp"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M9 21 H15 L14 18 H10 Z" fill="currentColor"/><path d="M8.4 18 C7 15.6 7 12.6 8.6 10.4 H15.4 C17 12.6 17 15.6 15.6 18 Z" fill="currentColor"/><rect x="10.6" y="6.4" width="2.8" height="4.4" fill="currentColor" opacity="0.85"/><path d="M12 3.2 C13.4 4.6 13.8 6 12 7.4 C10.2 6 10.6 4.6 12 3.2 Z" fill="currentColor" opacity="0.55"/></svg>"""

package/data/sprites/letter.toml

@@ -0,0 +1,5 @@
+# letter — Ashcombe Hall's own objective (hidden in the cabinet): an
+# envelope with a folded flap (a lighter overlay, the same carved-highlight
+# trick as the lid on container.toml) and a small wax seal.
+classes = ["letter"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="6" width="18" height="13" rx="1.2" fill="currentColor"/><path d="M3 6 L21 6 L21 6.8 L12 13.8 L3 6.8 Z" fill="currentColor" opacity="0.32"/><circle cx="12" cy="12.4" r="1.15" fill="currentColor" opacity="0.8"/></svg>"""

package/data/sprites/person.toml

@@ -0,0 +1,4 @@
+# person — the generic fallback for anyone with no NPC sprite of their own
+# (see butler/housekeeper/cook/gardener for the named Ashcombe Hall staff).
+classes = ["person"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.6" r="3.3" fill="currentColor"/><path d="M6 21 C6 15.3 8.7 12.8 12 12.8 C15.3 12.8 18 15.3 18 21 Z" fill="currentColor"/><path d="M12 12.8 C13.1 12.8 14.1 13 15 13.4" fill="none" stroke="currentColor" stroke-width="0.9" opacity="0.4" stroke-linecap="round"/></svg>"""

package/data/sprites/poodle.toml

@@ -0,0 +1,5 @@
+# poodle — the seed taxonomy's worked example (poodle IsA dog): its own
+# pompom-cut head and tail, distinct from the plain dog sprite it would
+# otherwise fall back to.
+classes = ["poodle"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="13" cy="15" rx="6.4" ry="4.6" fill="currentColor"/><ellipse cx="10.8" cy="13.2" rx="1.8" ry="1.3" fill="currentColor" opacity="0.28"/><circle cx="7" cy="8.5" r="4" fill="currentColor"/><g fill="currentColor"><circle cx="4" cy="6" r="1.6"/><circle cx="7" cy="4.2" r="1.7"/><circle cx="10" cy="6" r="1.6"/></g><rect x="18.5" y="14" width="2.2" height="6" rx="1.1" fill="currentColor"/><circle cx="19.6" cy="13" r="1.5" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="9" y1="19.5" x2="9" y2="22"/><line x1="17" y1="19.5" x2="17" y2="22"/></g></svg>"""

package/data/sprites/portable.toml

@@ -0,0 +1,6 @@
+# portable — the generic fallback for any carryable object with no sprite
+# of its own: a drawstring parcel silhouette, replacing the old
+# generic-gift-box outline so it reads as "an unspecified small thing"
+# rather than a gift.
+classes = ["portable"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 6 C7.5 6 5 9.4 5 13.4 C5 17.7 8.1 20 12 20 C15.9 20 19 17.7 19 13.4 C19 9.4 16.5 6 12 6 Z" fill="currentColor"/><path d="M9.4 6.4 C9.9 4.6 10.8 3.4 12 3.4 C13.2 3.4 14.1 4.6 14.6 6.4" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"/><ellipse cx="9.8" cy="11.6" rx="1.6" ry="2.1" fill="currentColor" opacity="0.28"/></svg>"""

package/data/sprites/portrait.toml

@@ -0,0 +1,5 @@
+# portrait — Ashcombe Hall's own drawing-room portrait (a container, hiding
+# the key): a gilt arched frame around a lighter canvas, with a bust
+# silhouette so it reads as a picture of someone, not an empty frame.
+classes = ["portrait"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 21 V7 C4 4 6.8 2 12 2 C17.2 2 20 4 20 7 V21 Z" fill="currentColor"/><path d="M6.3 19.4 V8.3 C6.3 6.2 8.4 4.8 12 4.8 C15.6 4.8 17.7 6.2 17.7 8.3 V19.4 Z" fill="currentColor" opacity="0.28"/><circle cx="12" cy="10.4" r="2.3" fill="currentColor" opacity="0.7"/><path d="M8 18.4 C8 15.2 9.6 13.4 12 13.4 C14.4 13.4 16 15.2 16 18.4 Z" fill="currentColor" opacity="0.7"/></svg>"""

package/data/sprites/room.toml

@@ -0,0 +1,5 @@
+# room — a schematic floor plan: a washed interior (a solid tint, not a
+# hollow box) plus a doorway arch, kept abstract since a room is a space
+# to draw, not an object to render literally.
+classes = ["room"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="1" fill="currentColor" opacity="0.14"/><rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="currentColor" stroke-width="1.6"/><path d="M9 21 L9 13 A3 3 0 0 1 15 13 L15 21" fill="none" stroke="currentColor" stroke-width="1.6"/></svg>"""

package/data/sprites/spider.toml

@@ -0,0 +1,5 @@
+# spider — the spider-and-fly board's own agent. A confident two-lobe body
+# (a lighter carved patch on the abdomen for shading) and eight thin
+# outward legs.
+classes = ["spider"]
+svg = """<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="12" cy="16" rx="5.2" ry="4.8" fill="currentColor"/><ellipse cx="10.3" cy="14.3" rx="1.8" ry="1.4" fill="currentColor" opacity="0.3"/><circle cx="12" cy="9.6" r="3.2" fill="currentColor"/><g stroke="currentColor" stroke-width="1.1" fill="none" stroke-linecap="round"><path d="M9.4 8 L2.2 4.4"/><path d="M9 10.2 L1.4 9.4"/><path d="M9.2 12.6 L2 14.2"/><path d="M10 15.4 L3.4 19"/><path d="M14.6 8 L21.8 4.4"/><path d="M15 10.2 L22.6 9.4"/><path d="M14.8 12.6 L22 14.2"/><path d="M14 15.4 L20.6 19"/></g></svg>"""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.7.24",
+  "version": "2.7.25",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",

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

@@ -0,0 +1,52 @@
+// sprite-template-files.mjs — the filesystem side of the sprite template
+// library: read data/sprites/*.toml and hand the raw parsed tables to
+// src/domain/sprite-templates.mjs's pure resolver, mirroring
+// construction-banks.mjs's own readConstructionFiles idiom exactly (same
+// directory-of-toml-files shape, same per-file-defensive load).
+//
+// This module is Node-only (readdirSync/readFileSync) and is never imported
+// by src/surfaces/web/*-browser-entry.mjs — the browser pages get their
+// template set as embedded page JSON instead (adventure-viz.mjs's/
+// spider-fly-viz.mjs's own renderAdventureHtml/renderSpiderFlyHtml already
+// embed the world/grid payload the same way; scripts/build-demo-site.mjs
+// calls this loader once, in Node, and hands the result to those render
+// functions), the same reason Ashcombe Hall's own JSONL world source is read
+// once at build time rather than bundled into the browser.
+
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+import { parse as parseToml } from "smol-toml";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The sprite-template directory (data, not code) — every *.toml file inside
+ *  is loaded, in filename order, so a new sprite is a new committed file,
+ *  never an edit to this loader. */
+export const SPRITE_TEMPLATES_DIR = join(HERE, "..", "..", "..", "data", "sprites");
+
+/** Read every *.toml file in `dir` (sorted, deterministic) and return the raw
+ *  parsed template objects as a flat array. A missing directory or an
+ *  unparseable file is DEFENSIVE (per-file: a broken file is skipped, not
+ *  fatal to the others, the same posture readConstructionFiles takes for its
+ *  own bank) — a production page load can never go blank because one hand-
+ *  authored sprite has a typo. `test/adapters/sprite-templates.test.mjs`
+ *  parses the real files directly (not through this lenient loader) so a
+ *  broken file still fails a test loudly. */
+export function readSpriteTemplateFiles(dir = SPRITE_TEMPLATES_DIR) {
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".toml")).sort();
+  } catch {
+    return [];
+  }
+  const templates = [];
+  for (const file of files) {
+    try {
+      const parsed = parseToml(readFileSync(join(dir, file), "utf8"));
+      templates.push(parsed);
+    } catch {
+      continue; // one malformed file never takes the others down
+    }
+  }
+  return templates;
+}

package/src/domain/sprite-map.mjs

@@ -154,26 +154,41 @@ function directSuperclassesOf(term, factRows) {
   return out;
 }
 
-/**
- * Resolve a class name to a sprite: `className` itself if the registry
- * carries it directly, otherwise the nearest rdfs:subClassOf ancestor
- * (breadth-first, nearest first — styled after ask.mjs's own ancestorsOf)
- * that the registry carries, otherwise `rootFallback` ("animal" by default —
- * override it for a registry whose own declared root is "object" or "plant").
- * Pure; `factRows` is read only, never mutated.
- */
-export function resolveSpriteForClass(className, factRows, spriteRegistry, { rootFallback = "animal" } = {}) {
+/** The full rdfs:subClassOf ancestor chain for `className`, nearest-first,
+ *  INCLUDING the starting term itself as `chain[0]` — the same breadth-first
+ *  walk resolveSpriteForClass performs below, extracted so
+ *  sprite-templates.mjs's richer, property-aware resolver can repeat the
+ *  same specificity check at each level (fully-specific variant >
+ *  parameterized template > plain class sprite) without re-deriving the BFS.
+ *  Pure; `factRows` is read only, never mutated. */
+export function classAncestorChain(className, factRows) {
   const start = normFactTerm(className);
   const seen = new Set();
   const queue = [start];
+  const chain = [];
   while (queue.length) {
     const term = queue.shift();
     if (seen.has(term)) continue;
     seen.add(term);
-    if (Object.prototype.hasOwnProperty.call(spriteRegistry, term)) return spriteRegistry[term];
+    chain.push(term);
     for (const parent of directSuperclassesOf(term, factRows)) {
       if (!seen.has(parent)) queue.push(parent);
     }
   }
+  return chain;
+}
+
+/**
+ * Resolve a class name to a sprite: `className` itself if the registry
+ * carries it directly, otherwise the nearest rdfs:subClassOf ancestor
+ * (breadth-first, nearest first — styled after ask.mjs's own ancestorsOf)
+ * that the registry carries, otherwise `rootFallback` ("animal" by default —
+ * override it for a registry whose own declared root is "object" or "plant").
+ * Pure; `factRows` is read only, never mutated.
+ */
+export function resolveSpriteForClass(className, factRows, spriteRegistry, { rootFallback = "animal" } = {}) {
+  for (const term of classAncestorChain(className, factRows)) {
+    if (Object.prototype.hasOwnProperty.call(spriteRegistry, term)) return spriteRegistry[term];
+  }
   return spriteRegistry[rootFallback];
 }

package/src/domain/sprite-templates.mjs

@@ -0,0 +1,131 @@
+// sprite-templates.mjs — the property-aware sprite resolver, layered ON TOP
+// of sprite-map.mjs's flat class registry rather than replacing it (its own
+// header explains why the ancestor walk stays exactly as-is). Where
+// resolveSpriteForClass only ever asks "what class is this", this module also
+// asks "what does this INSTANCE'S OWN mgx:hasProperty-shaped fact say about
+// it" — the operator's own worked example: a dog typed "dog" with a taught
+// "black" property resolves to a filled-in coloured template, one typed
+// "sheepdog" with the same property resolves through the ordinary ancestor
+// walk to the SAME template, and a dog with no colour property at all falls
+// through to the plain dog sprite.
+//
+// Naming convention for the two template kinds a specific class can carry
+// beyond its own plain `{class}.toml` (data/sprites/*.toml, one file per
+// sprite):
+//   - a PARAMETERIZED template — `{class}-with-{property}.toml` (this pass
+//     ships `dog-with-colour.toml`) — declares a `[parameters.<name>]` table
+//     naming the fact predicate that carries the value (`property`, e.g.
+//     "mgx:hasProperty"), a placeholder token the `svg` string contains
+//     (`placeholder`, e.g. "{{FILL}}"), and a `[parameters.<name>.values]`
+//     table translating an observed property VALUE into the literal
+//     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.
+//
+// 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
+// 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
+// against `rootFallback`, falling back to spriteRegistry's own root entry
+// only if nothing there matches either.
+import { classAncestorChain } from "./sprite-map.mjs";
+
+/** 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);
+}
+
+/** Fill a parameterized template's `svg` from the first of its own
+ *  `[parameters.*]` whose observed property value maps to a substitution —
+ *  or null when no property fact names a mapped value (never a guess). */
+function parameterizedFill(template, propertyFacts) {
+  for (const param of Object.values(template.parameters || {})) {
+    const values = param?.values || {};
+    const hit = (propertyFacts || []).find(
+      (f) => f.predicate === param.property && Object.prototype.hasOwnProperty.call(values, f.object),
+    );
+    if (hit) return template.svg.split(param.placeholder).join(values[hit.object]);
+  }
+  return null;
+}
+
+/** 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. */
+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;
+  for (const t of candidates) {
+    if (t.match || !t.parameters) continue;
+    const filled = parameterizedFill(t, propertyFacts);
+    if (filled) return filled;
+  }
+  const plain = candidates.find((t) => !t.match && !t.parameters);
+  return plain ? plain.svg : null;
+}
+
+/**
+ * Resolve `className` to sprite SVG markup, property-aware: the ancestor
+ * chain (from `factRows`, sprite-map.mjs's own walk) is checked nearest-
+ * first, and at each term the template set (`templates`, the parsed
+ * data/sprites/*.toml set) is tried before falling back to `spriteRegistry`
+ * for that same term — so a class with no template at all resolves exactly
+ * as resolveSpriteForClass already does. `propertyFacts` is the instance's
+ * own small `{predicate, object}` fact set (e.g. its mgx:hasProperty rows) —
+ * read only, never required to be non-empty. Pure.
+ */
+export function resolveSpriteAsset(className, factRows, propertyFacts, templates, spriteRegistry, { rootFallback = "animal" } = {}) {
+  for (const term of classAncestorChain(className, factRows)) {
+    const hit = resolveAtTerm(term, propertyFacts, templates);
+    if (hit) return hit;
+    if (Object.prototype.hasOwnProperty.call(spriteRegistry, term)) return spriteRegistry[term];
+  }
+  const rootHit = resolveAtTerm(rootFallback, propertyFacts, templates);
+  if (rootHit) return rootHit;
+  return spriteRegistry[rootFallback];
+}
+
+/** Every internal-consistency problem with one parsed template, as plain
+ *  strings — empty when the template is well-formed. Used both by
+ *  test/adapters/sprite-templates.test.mjs (against the real loaded
+ *  data/sprites/ directory) and available to any future loader that wants to
+ *  warn rather than silently drop a broken file. Checks: `classes` is a
+ *  non-empty array, `svg` is a real `<svg` string, a `[parameters.*]` table
+ *  names a `property` and a non-empty `values` map, and a `[match]` table
+ *  names both `property` and `value`. */
+export function spriteTemplateProblems(template) {
+  const problems = [];
+  const t = template || {};
+  if (!Array.isArray(t.classes) || t.classes.length === 0) problems.push("classes is missing or empty");
+  if (typeof t.svg !== "string" || !t.svg.trim().startsWith("<svg")) problems.push("svg is missing or not an <svg> string");
+  for (const [name, param] of Object.entries(t.parameters || {})) {
+    if (!param?.property) problems.push(`parameters.${name}.property is missing`);
+    if (!param?.placeholder) problems.push(`parameters.${name}.placeholder is missing`);
+    else if (typeof t.svg === "string" && !t.svg.includes(param.placeholder)) {
+      problems.push(`parameters.${name}.placeholder ${JSON.stringify(param.placeholder)} does not appear in svg`);
+    }
+    if (!param?.values || Object.keys(param.values).length === 0) problems.push(`parameters.${name}.values is empty`);
+  }
+  if (t.match && (!t.match.property || t.match.value === undefined)) {
+    problems.push("match is missing property or value");
+  }
+  return problems;
+}

package/src/services/adventure-viz.mjs

@@ -72,6 +72,31 @@ export function spriteClassForObject(rows, subject) {
   return typeRow ? typeRow.object : "portable";
 }
 
+/** `rows` plus one synthetic rdfs:subClassOf edge from `subject`'s own name
+ *  to its declared sprite class (spriteClassForObject's own result) — never
+ *  written back to the corpus, just handed to sprite-templates.mjs's
+ *  resolver so a NAMED object (`cabinet`, `butler`) can carry its own sprite
+ *  template while an unauthored object of the same declared class still
+ *  falls back through it cleanly. Ashcombe Hall's own objects have no
+ *  rdfs:subClassOf chain of their own (each is directly typed, e.g. `cabinet
+ *  rdf:type furniture`); this is the exact same ancestor-walk mechanism
+ *  spider-fly's real poodle-IsA-dog taxonomy already exercises, just
+ *  synthesized at render time for a world whose taxonomy doesn't reach this
+ *  deep. A no-op when the subject's own name already IS its declared class
+ *  (nothing to synthesize). Pure. */
+export function spriteAncestryRows(rows, subject) {
+  const declaredClass = spriteClassForObject(rows, subject);
+  if (subject === declaredClass) return rows;
+  return [...(rows || []), { subject, predicate: "rdfs:subClassOf", object: declaredClass }];
+}
+
+/** Every fact row belonging to `subject` — the small `{predicate, object}`
+ *  set sprite-templates.mjs's resolver checks a parameterized/match template
+ *  against (e.g. an mgx:hasProperty row). Pure. */
+export function factsForSubject(rows, subject) {
+  return (rows || []).filter((r) => r.subject === subject);
+}
+
 /** Every subject actually visible in `here`, sorted, each with its sprite
  *  class — mirroring adventure.mjs's own private `visibleRoomOf` walk (one
  *  containment hop through an OPEN container) so this can never draw a
@@ -133,14 +158,26 @@ export function roomCaptionText(rows, state, here) {
 /** The self-contained adventure page. Pure given `worldPayload` (the build
  *  step's own read of the real Ashcombe Hall world — `{ facts, rules,
  *  opening }`), the same "byte-identical for identical input" invariant
- *  every other viz page in this project holds. `?preview=1` switches into
- *  the small, auto-playing, non-interactive mode the home page's hero iframe
- *  embeds, matching spider-fly.html's own dual-purpose file. */
-export function renderAdventureHtml({ title = DEFAULT_TITLE, worldPayload = { facts: [], rules: [], opening: "" } } = {}) {
+ *  every other viz page in this project holds. `spriteTemplates` is the
+ *  build step's own read of data/sprites/*.toml (sprite-template-files.mjs's
+ *  readSpriteTemplateFiles), embedded as page data the same way the world
+ *  payload is — the browser cannot read the filesystem, so the parsed
+ *  templates travel as JSON rather than as a bundled fs read. Defaults to
+ *  `[]` (every sprite falls back to the flat SPRITE_REGISTRY, unchanged from
+ *  before this module existed) so existing callers that don't pass one keep
+ *  working. `?preview=1` switches into the small, auto-playing, non-
+ *  interactive mode the home page's hero iframe embeds, matching
+ *  spider-fly.html's own dual-purpose file. */
+export function renderAdventureHtml({
+  title = DEFAULT_TITLE,
+  worldPayload = { facts: [], rules: [], opening: "" },
+  spriteTemplates = [],
+} = {}) {
   const pageData = embedJson({
     world: worldPayload,
     previewMaxTicks: PREVIEW_MAX_TICKS,
     tickWaitMs: TICK_WAIT_MS,
+    spriteTemplates,
   });
 
   return `<!doctype html>
@@ -242,6 +279,8 @@ const ADVENTURE = ${pageData};
   const createTicker = ${createTicker.toString()};
   const spriteClassForObject = ${spriteClassForObject.toString()};
   const roomSceneObjects = ${roomSceneObjects.toString()};
+  const spriteAncestryRows = ${spriteAncestryRows.toString()};
+  const factsForSubject = ${factsForSubject.toString()};
   const esc = ${escapeHtml.toString()};
   const el = (id) => document.getElementById(id);
   const spriteRow = el("spriteRow");
@@ -303,11 +342,28 @@ const ADVENTURE = ${pageData};
     chatqEl.focus();
   });
 
+  // ---- sprite resolution — property/instance-aware (sprite-templates.mjs's
+  // resolveSpriteAsset), keyed on the OBJECT'S OWN NAME (via
+  // spriteAncestryRows' synthetic subClassOf edge to its declared class) so
+  // a named object (cabinet, butler) can carry its own data/sprites/*.toml
+  // template while the data-cls attribute still reflects the DECLARED class
+  // (container/furniture/portable/person/room) — the CSS accent-color rules
+  // stay keyed on that declared class unchanged. The player's own "you" row
+  // has no backing fact row, so it resolves directly by its fixed
+  // "adventurer" class with no ancestry/property rows to check.
+  function resolveObjectSprite(rows, s) {
+    if (s.subject === "you") return tmctAdventure.resolveSpriteAsset("adventurer", [], [], ADVENTURE.spriteTemplates, tmctAdventure.SPRITE_REGISTRY);
+    return tmctAdventure.resolveSpriteAsset(
+      s.subject, spriteAncestryRows(rows, s.subject), factsForSubject(rows, s.subject),
+      ADVENTURE.spriteTemplates, tmctAdventure.SPRITE_REGISTRY,
+    );
+  }
+
   function redraw(snap) {
     const objects = roomSceneObjects(snap.rows, snap.state, snap.here);
     const sprites = [{ subject: "you", spriteClass: "adventurer" }, ...objects];
     spriteRow.innerHTML = sprites.map((s) => {
-      const svg = tmctAdventure.resolveSpriteForClass(s.spriteClass, [], tmctAdventure.SPRITE_REGISTRY);
+      const svg = resolveObjectSprite(snap.rows, s);
       return '<div><div class="sprite" data-cls="' + esc(s.spriteClass) + '">' + svg + '</div>'
         + '<div class="sprite-label">' + esc(s.subject) + "</div></div>";
     }).join("");

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

@@ -96,13 +96,18 @@ export function threadCellsForSpiderPlan(agents, geometry) {
 }
 
 /** The self-contained spider-and-fly page. Pure — the same output for the
- *  same `title` every time; every other piece of state this page shows is
- *  computed live in the browser once the sibling bundle loads. `?preview=1`
- *  on the page's own URL switches it into the small, auto-playing,
- *  non-interactive mode the home page's hero iframe embeds (§11) — one file
- *  serves both the hero and the "open full-screen" link, matching how
- *  ledger.html/plan.html are each one file embedded two ways. */
-export function renderSpiderFlyHtml({ title = DEFAULT_TITLE } = {}) {
+ *  same `title`/`spriteTemplates` every time; every other piece of state
+ *  this page shows is computed live in the browser once the sibling bundle
+ *  loads. `spriteTemplates` is the build step's own read of
+ *  data/sprites/*.toml (sprite-template-files.mjs), embedded as page data
+ *  the same reason adventure-viz.mjs's own worldPayload is — the browser
+ *  bundle stays fs-free. Defaults to `[]` (every agent falls back to the
+ *  flat SPRITE_REGISTRY, unchanged from before this module existed).
+ *  `?preview=1` on the page's own URL switches it into the small, auto-
+ *  playing, non-interactive mode the home page's hero iframe embeds (§11) —
+ *  one file serves both the hero and the "open full-screen" link, matching
+ *  how ledger.html/plan.html are each one file embedded two ways. */
+export function renderSpiderFlyHtml({ title = DEFAULT_TITLE, spriteTemplates = [] } = {}) {
   const gridData = embedJson({
     gridSize: GRID_SIZE,
     webCells: webCellIds(),
@@ -114,6 +119,7 @@ export function renderSpiderFlyHtml({ title = DEFAULT_TITLE } = {}) {
     tickWaitMs: TICK_WAIT_MS,
     maxFlyMass: FLY_INITIAL_MASS,
     maxSpiderMass: SPIDER_INITIAL_MASS,
+    spriteTemplates,
   });
 
   return `<!doctype html>
@@ -314,8 +320,14 @@ const SPIDERFLY = ${gridData};
     node = document.createElement("div");
     node.className = "sprite";
     node.dataset.cls = cls;
+    // Property-aware resolution (sprite-templates.mjs's resolveSpriteAsset):
+    // no agent here carries an mgx:hasProperty fact today, so propertyFacts
+    // stays empty and every agent resolves through its plain class template
+    // (or the flat SPRITE_REGISTRY, for a class with none) — the same output
+    // as before this module existed, just wired for the day an agent does
+    // carry one.
     const sprite = window.tmctSpiderFly
-      ? tmctSpiderFly.resolveSpriteForClass(cls, (session && session.taxonomyRows) || [], tmctSpiderFly.SPRITE_REGISTRY)
+      ? tmctSpiderFly.resolveSpriteAsset(cls, (session && session.taxonomyRows) || [], [], SPIDERFLY.spriteTemplates, tmctSpiderFly.SPRITE_REGISTRY)
       : "";
     node.innerHTML = sprite;
     if (!preview) {

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

@@ -38,6 +38,7 @@ import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { foldWorldState, worldDigestRows, roomAffordances } from "../../services/adventure.mjs";
 import { runAdventureAutoplayTick } from "../../services/adventure-autoplay.mjs";
 import { resolveSpriteForClass, SPRITE_REGISTRY } from "../../domain/sprite-map.mjs";
+import { resolveSpriteAsset } from "../../domain/sprite-templates.mjs";
 
 /** A live in-memory adventure this page's ticker AND chat dock can both
  *  drive. Returns `{ memoryDir, autoplayTick, turn, snapshot }`.
@@ -121,5 +122,5 @@ export async function createAdventureSession(worldPayload) {
 // affordances the chat dock's own pills read from — the same posture
 // spider-fly-browser-entry.mjs's own globalThis.tmctSpiderFly re-export takes.
 globalThis.tmctAdventure = {
-  createAdventureSession, resolveSpriteForClass, SPRITE_REGISTRY, worldDigestRows, roomAffordances,
+  createAdventureSession, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset, worldDigestRows, roomAffordances,
 };

package/src/surfaces/web/spider-fly-browser-entry.mjs

@@ -54,6 +54,7 @@ import {
 } from "../../domain/spider-fly-world.mjs";
 import { foldSpiderFlyState, runSpiderFlyTick, startSpiderFlyGame, liveWebs, DEFAULT_VISION_RADIUS } from "../../services/spider-fly.mjs";
 import { resolveSpriteForClass, SPRITE_REGISTRY } from "../../domain/sprite-map.mjs";
+import { resolveSpriteAsset } from "../../domain/sprite-templates.mjs";
 
 /** A live in-memory game the page's ticker and chat dock can both drive.
  *  Returns { memoryDir, sessionId, opening, initial, taxonomyRows, tick,
@@ -149,6 +150,6 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
 // a spider's remaining silk-thread path from its returned direction list, and
 // computing the POV overlay's visible-cell mask, both need them.
 globalThis.tmctSpiderFly = {
-  createSpiderFlySession, normFactTerm, resolveSpriteForClass, SPRITE_REGISTRY,
+  createSpiderFlySession, normFactTerm, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
   cellId, parseCellId, DIRECTION_DELTA, visibleCells, DEFAULT_VISION_RADIUS,
 };