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

package/README.md

@@ -847,6 +847,29 @@ enabled = false             # local-only counters; never phones home
 [memory]
 retention_versions = 5      # snapshot generations memory/core.mjs keeps on manifest bootstrap
 backend = "sqlite"          # default | memory | sqlite (see "Memory backends" above)
+
+# Game tuning knobs (src/domain/game-config.mjs). Every OTHER game parameter
+# (disk/peg counts, the goal, ...) lives in the game's own taught-English
+# world instead — these are the handful of genuine magic numbers that
+# aren't expressible that way.
+[games.spider-fly]
+spider_initial_mass = 15
+spider_mass_decrement_per_turn = 0.5   # lower = slower to starve
+fly_initial_mass = 10
+fly_mass_decrement_per_turn = 1
+vision_radius = 4                      # Chebyshev radius an agent can see other agents within
+egg_hatch_delay_turns = 3              # turns between a lay and its hatch
+fly_spawn_interval_turns = 3           # a new fly arrives every Nth turn
+eggs_eaten_threshold = 2               # flies eaten since the last egg before the next one lays
+web_duration_turns = 10                # turns a spider-built web stays active
+
+[games.guess-number]
+default_lo = 1           # the range's default lower bound, when the opening line states none
+default_hi = 100         # the range's default upper bound, when the opening line states none
+max_bound = 1000000000   # sanity cap on either bound, however the opening line states it
+
+[planning]
+max_depth = 300  # the "solve it" plan lane's search-depth cap (hanoi, river-crossing, any taught-rule domain)
 ```
 
 ### Try it on an example graph

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.23",
+  "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/adapters/toml-config.mjs

@@ -117,6 +117,14 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   if (src.extensions !== undefined) cfg.extensions = src.extensions;
   if (src.bias !== undefined) cfg.bias = src.bias;
 
+  // Game tuning knobs (src/domain/game-config.mjs): sparse PASS-THROUGH only,
+  // same discipline as [extensions]/[bias] above — the raw `[games.*]`/
+  // `[planning]` tables ride through unmodified (snake_case keys); mapping
+  // them onto the internal camelCase shape and filling in unset keys from
+  // the shipped defaults is resolveGameConfig's job, never this module's.
+  if (src.games !== undefined) cfg.games = src.games;
+  if (src.planning !== undefined) cfg.planning = src.planning;
+
   const idx = src.index || {};
   const index = {};
   if (idx.languages !== undefined) index.languages = idx.languages;

package/src/domain/game-config.mjs

@@ -0,0 +1,90 @@
+// game-config.mjs — the shipped defaults for every game's tuning knobs
+// (spider-fly's mass economy, guess-the-number's default/max bounds, the
+// shared plan lane's search-depth cap) and the pure function that folds a
+// normalized tmct.toml's [games]/[planning] tables over them.
+//
+// Every other game parameter lives in the game's own taught-English world
+// definition (data/games/hanoi-3.txt and friends) and never needs a knob
+// here — only a genuine magic number with no taught-fact home does.
+//
+// Pure: no filesystem access, no module-level mutable state. resolveGameConfig
+// is safe to call once per session and the result handed around freely —
+// several games/tests running in the same process never share or mutate one
+// another's resolved config.
+
+export const DEFAULT_GAME_CONFIG = Object.freeze({
+  spiderFly: Object.freeze({
+    spiderInitialMass: 15,
+    spiderMassDecrementPerTurn: 0.5,
+    flyInitialMass: 10,
+    flyMassDecrementPerTurn: 1,
+    visionRadius: 4,
+    eggHatchDelayTurns: 3,
+    flySpawnIntervalTurns: 3,
+    eggsEatenThreshold: 2,
+    webDurationTurns: 10,
+  }),
+  guessNumber: Object.freeze({
+    defaultLo: 1,
+    defaultHi: 100,
+    maxBound: 1_000_000_000,
+  }),
+  planning: Object.freeze({
+    maxDepth: 300,
+  }),
+});
+
+// snake_case tmct.toml key -> camelCase internal key, one map per table —
+// mirrors how toml-config.mjs's normalizeConfig maps every other section
+// (e.g. [tune]) onto its own internal shape.
+const SPIDER_FLY_KEY_MAP = Object.freeze({
+  spider_initial_mass: "spiderInitialMass",
+  spider_mass_decrement_per_turn: "spiderMassDecrementPerTurn",
+  fly_initial_mass: "flyInitialMass",
+  fly_mass_decrement_per_turn: "flyMassDecrementPerTurn",
+  vision_radius: "visionRadius",
+  egg_hatch_delay_turns: "eggHatchDelayTurns",
+  fly_spawn_interval_turns: "flySpawnIntervalTurns",
+  eggs_eaten_threshold: "eggsEatenThreshold",
+  web_duration_turns: "webDurationTurns",
+});
+
+const GUESS_NUMBER_KEY_MAP = Object.freeze({
+  default_lo: "defaultLo",
+  default_hi: "defaultHi",
+  max_bound: "maxBound",
+});
+
+const PLANNING_KEY_MAP = Object.freeze({
+  max_depth: "maxDepth",
+});
+
+/** `defaults` with every key `keyMap` names overridden by its raw snake_case
+ *  counterpart in `raw`, when actually present — every unset sibling keeps
+ *  the default, so the result is always fully populated. */
+function mergeSection(defaults, raw, keyMap) {
+  const out = { ...defaults };
+  if (!raw || typeof raw !== "object") return out;
+  for (const [tomlKey, camelKey] of Object.entries(keyMap)) {
+    if (raw[tomlKey] !== undefined) out[camelKey] = raw[tomlKey];
+  }
+  return out;
+}
+
+/**
+ * Fold a normalized tmct.toml's `games`/`planning` tables (the raw sparse
+ * pass-through src/adapters/toml-config.mjs's normalizeConfig produces —
+ * snake_case keys, present only when actually set in the file) over
+ * DEFAULT_GAME_CONFIG. `toml` may be null/undefined (no tmct.toml, or one
+ * that failed to load) — every key then falls back to its default. Returns a
+ * fully populated object of the same shape as DEFAULT_GAME_CONFIG; toml value
+ * wins per key when present, default otherwise.
+ */
+export function resolveGameConfig(toml) {
+  const games = toml?.games ?? {};
+  return {
+    spiderFly: mergeSection(DEFAULT_GAME_CONFIG.spiderFly, games["spider-fly"], SPIDER_FLY_KEY_MAP),
+    guessNumber: mergeSection(DEFAULT_GAME_CONFIG.guessNumber, games["guess-number"], GUESS_NUMBER_KEY_MAP),
+    planning: mergeSection(DEFAULT_GAME_CONFIG.planning, toml?.planning, PLANNING_KEY_MAP),
+  };
+}

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

@@ -25,9 +25,12 @@ export const WEB_DURATION_TURNS = 10;
 // FLY_INITIAL_MASS/FLY_MASS_DECREMENT_PER_TURN): a spider starves like a fly
 // does, and gains exactly a fly's remaining mass on an eat. Heavier starting
 // mass than a single fly's worth on purpose — a spider that eats nothing for
-// a while has some runway before starving.
+// a while has some runway before starving. The decrement is half a fly's own
+// (spiders live longer between meals than flies do), and — like every other
+// tunable here — overridable per session via tmct.toml's [games.spider-fly]
+// (src/domain/game-config.mjs).
 export const SPIDER_INITIAL_MASS = 15;
-export const SPIDER_MASS_DECREMENT_PER_TURN = 1;
+export const SPIDER_MASS_DECREMENT_PER_TURN = 0.5;
 
 export const cellId = (x, y) => `cell-${x}-${y}`;
 

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