sindicate 0.12.0 → 0.15.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 0.15.0 — the world-building release
+
+Everything between the last published version (0.13.0) and here. 0.14.0 was bumped in the
+repo but never published, so its contents ship as part of this release.
+
+### The world, split out of the games (0.14.0's work)
+
+The terrain and stamper machinery both games carried privately now belongs to the engine, and
+each game keeps only its own content:
+
+- `world/geo.js` — the noise/curve toolkit (fbm, ridged, terrace, segDist, smoothstep).
+- `world/railFormation.js` — the rail solver: max-grade Lipschitz envelopes and vertical curves.
+- `world/bridgeSplice.js`, `world/waterLevels.js`, `world/waterMeshes.js` — bridges and water.
+- `world/heightfield.js` — the chunked terrain mesh and its cook (one height lattice, central-
+  difference normals so chunk borders cannot seam, cooked to a single self-writing bin).
+- `world/kit.js` — the kit registries, doors and ladders, `setKitContent`, `buildArea`,
+  `buildTown`, `dressTownCenter`.
+- `world/placement.js` — the cook, samplers, resident kits and occupancy.
+- `world/worldBase.js` — the world facade's engine half, with eight hooks a game fills in.
+- `world/permanentWay.js` — the track-laying machinery.
+
+### The World Designer
+
+- `tools/designer.js` + `tools/devPlugin.js` — a visual editor over the game's real terrain:
+  place, move and remove prefabs, draw road polylines, fly the camera, save to JSON.
+- `tools/designer-mcp.mjs` — an MCP server so a Claude session can drive the designer while
+  you watch it.
+- `world/design.js` — `buildDesign()`, the layout-JSON → live-scene bridge.
+
+### The road system (new)
+
+Junctions are rigid prefab pieces; the roads between them are generated. Both halves, plus the
+earthworks that make the ground agree with them:
+
+- `world/roadKit.js` — reads a pack's measured kit. Lanes are stored by which side of the
+  centre line they sit on, so **left/right-hand drive is a runtime switch**, not baked data.
+  `gradeLevel`/`seatY` sink a multi-level junction until the roads that meet the outside world
+  are at ground level.
+- `world/roadLink.js` — the road between two sockets: a cubic Bezier through both arms'
+  tangents so seams are tangential, cross-sections matching each socket's measured width and
+  paint, and a vertical profile squeezed into the reachable-at-max-grade envelope then relaxed
+  into vertical curves. Connecting is non-negotiable: if two sockets cannot be joined within
+  the requested grade the road still meets both ends and reports `feasible: false`.
+- `world/roadTerrain.js` — pads under junctions, cut/fill corridors under links, both using a
+  batter slope so a road crossing a valley gets an embankment that reaches it. `pickSites` and
+  `pickManySites` put junctions on the flats.
+- `world/roadNetwork.js` — sites in, road system out: a spanning tree plus a few short extra
+  links so the map has loops, and for each site the junction piece and rotation whose arms best
+  face the neighbours it must serve.
+
+### Pack tooling
+
+- `tools/unityMeshToGlb.mjs`, `tools/unityPrefabToAssembly.mjs`, `tools/truthToAssemblies.mjs`,
+  `tools/fbxToGlb.mjs`, `tools/roadKitAnalyze.mjs`, `tools/buildKiwiRoadsPack.mjs` — recovering
+  a Unity road library into an engine pack: meshes, Unity-resolved transforms and materials,
+  per-file FBX import scale, measured sockets and cross-sections.
+- `tools/ExportKiwiRoadMaterials.cs`, `tools/ExportKiwiRoadRefs.cs` — the Unity-side exports.
+
+### Notes
+
+- `world/roadGraph.js` (A\* routing for the map) and the road piece system are different
+  things that share a word.
+- The road modules are new and may still move before 1.0.
+
+## 0.13.0
+
+World splits steps 1–3a; the package catalog and one-click install.

package/docs/plans/kiwi-road-recon.md

@@ -0,0 +1,97 @@
+# Kiwi Road System — Recon & Re-Implementation Brief (for Sindicate/three.js)
+
+> Recon of /Users/nick/Desktop/Kiwi (Unity). Kiwi runs TWO parallel road systems:
+> **A) City grid roads** — Manhattan grid of cardinal segments built from prefab junction
+> pieces + ONE repeated 2.5m straight prefab, a procedural "curved road" mesh overlay, and
+> EasyRoads3D-style terrain benching. **B) Inter-city roads** — procedural spline-extruded
+> meshes (motorway/dual carriageway/country) + generated-then-saved interchange prefabs
+> (roundabouts, overpass, dumbbell). For Sindicate, A's prefab+socket+junction logic and
+> the benching are the model; B is math to mine, not to copy.
+
+## 1. Piece taxonomy + sockets
+- Junction prefabs (TerrainGeneratorWindow_CityJunctions.cs:25-31): Junction_4Way/T/LCorner
+  (City_Simpligon + Countryside variants). City straight: RoadSegment_Simpligon (2.5m).
+- Synty source pieces referenced (POLYGON City/Town kit): Road_01/02/03, Straight_01/02/03,
+  Corner_01/02, Corner_End_03, Road_Crossing_01, Road_Flyover_01(+_Support), Road_Bare_01,
+  Road_Lines_01, Road_YellowLines_02; props Barrier_01, HighwayGuardrail, signs.
+- Interchanges are GENERATED then saved as prefabs (InterCityRoadWindow.cs:48-52, 964-1188).
+- **Kiwi has NO true smallest-cut piece set** — one straight + junction prefabs + curved
+  overlay. Turn/ramp/grade PIECES are net-new design for Sindicate.
+- Sockets, simple form (RoadConnectorPoints.cs:46-177): child anchors named Connector_*;
+  road runs along local +Z; Connector_A at minZ (back), Connector_B at maxZ (front), at
+  road-surface height (mesh maxY), x=0. Junctions: Connector_{N,S,E,W} at ±JUNCTION_RADIUS.
+- Rich form — ADOPT THIS (Runtime/Roads/JunctionConnectionPoints.cs:15-50):
+  ConnectionPoint { armId "N"/"S"/"E"/"W"/...; local position (road-width centre at arm
+  end); outward direction; RoadType {CountryRoad, SideRoad, DualCarriageway, Motorway};
+  laneCount; speedLimit }.
+
+## 2. Network data model
+- ONE constant drives everything (ManhattanGridGenerator.cs:48-65): BLOCK_SIZE=50m →
+  ROAD_PIECE_LENGTH=2.5m, JUNCTION_SIZE=20m, junction spacing 0.4–1.2×block; gates
+  WATER_LEVEL=5m, MAX_SLOPE=22.5°.
+- Serialized graph (CityData.cs): CityData { junctions[], roadSegments[], blocks[],
+  rawRoads[], seed }; JunctionData { id, position(incl terrain Y), JunctionType
+  {DeadEnd,Straight,TJunction,Crossroads,Complex}, connectedRoadIds, rotationY,
+  flattenRadius }; RoadSegmentData { start/endJunctionId, width, roadType, length,
+  heightDifference, splineWaypoints }. JSON-exported (_Cities.cs:2554).
+- Runtime graph (RoadNetworkBuilder.cs): RoadNode merged within 1m; type classified purely
+  by CONNECTION COUNT (:184-208).
+
+## 3. Placement math
+- Grid gen (ManhattanGridGenerator.Generate :412-667): population flood-fill (cells =
+  pop/200), per-cell water/slope reject, per-edge span validity sampled every ~5m,
+  dead-end → perpendicular ray → nearest road → T connector (:791-888), merge verticals,
+  largest-connected-component BFS filter (:673-778).
+- Turns: the grid is CARDINAL-ONLY (±5°); curvature comes from the procedural curved-mesh
+  overlay along a straight→quadratic-bézier→straight "blue spline" (SampleModifiedSpline,
+  _Cities.cs:1640-1682) — because Kiwi lacks turn pieces.
+- Piece fitting: numPieces = floor(dist/pieceLength), walk by pieceLength, orient by
+  LookRotation(direction), Y from terrain +0.1 (_Cities.cs:1559-1637).
+- SplinePlacer.cs VARIABLE-SIZE mode (:123-253): grow a piece until tangent deviation
+  exceeds angleDeviance (3°), then CUT and scale the piece to the chord — the template for
+  turn-aware smallest-cut placement.
+- Weld trick TO AVOID: clone each piece mesh, flatten back edge, SnapVerticesToTargets to
+  the junction's edge verts (_Cities.cs:1863-2062) — incompatible with InstancedMesh.
+- Grades: cities are BENCHED (junction at avg terrain height in its box, :248-285; steep
+  segments REJECTED not ramped). Only inter-city splines carry true 3D elevation.
+
+## 4. Terrain stamping
+- FlattenTerrainUnderCurvedRoads (…_CityTerrainFlattening.cs:35-352): ROAD_BED_OFFSET=1m,
+  INDENT_WIDTH=2m, SURROUNDING_WIDTH=3m. Extract road footprint POLYGONS (vert rings →
+  left/right edge lists with per-ring heights, :357-457) + junction polygons (72 angular
+  sectors +1m, :462-535); 50m spatial grid; per heightmap pixel: inside → per-edge
+  INTERPOLATED roadHeight − offset (grade preserved), indent → edge height − offset, skirt
+  → smoothstep back to terrain. Cut AND fill; region-partial writes; pixel-error 2.
+- TerrainStamp.cs: R-channel heightmap stamps with blend modes (cliffs/mesas, not roads).
+
+## 5. Junction resolution (_CityJunctions.cs:36-404)
+- Tally cardinal connections (±5°): 4 → 4-way rot 0°; 3 → T rotated so the MISSING arm
+  faces north (:257-260); 2 opposite → two back-to-back straight pieces (first keeps the
+  junction's load-bearing name); 2 perpendicular → L-corner rotated by present dirs
+  (:289-293); 1 → dead-end straight; 0 → marker. Junction mesh bottom seated at avg
+  terrain height. Names "City_X_Junction_Y" are parsed by road placement (load-bearing).
+
+## 6. Editor UX
+- TerrainGeneratorWindow (partial class over ~15 files): Preview Cities → Generate per
+  city: ExportCityDataToJson → PlaceJunctionsAndFlattenTerrain → ClearGrassInCity →
+  PlaceRoadsAndFlattenTerrain → RoadSplineEditor blue-lines → CurvedRoadMeshGenerator →
+  FlattenTerrainUnderCurvedRoads → diagnostics. InterCityRoadWindow: tabbed per road type,
+  straight/spline gen, per-type + batch prefab saving.
+
+## 7. Copy vs avoid for Sindicate
+COPY: centralized config; cardinal grid pipeline (flood-fill, gating, dead-end→T,
+largest-component); the RICH socket model (armId+pos+dir+roadType+laneCount) with socket
+transforms precomputed per prefab type; floor(dist/len) fitting + SplinePlacer
+angle-deviance cutting; junction resolution by connection count + 90° rotation; EasyRoads
+benching (indent+skirt, cut+fill, per-edge interpolated heights); CityData-style JSON.
+AVOID: per-instance mesh cloning/vert snapping (author pieces so sockets meet EXACTLY on a
+shared grid instead); three overlapping road systems (pick prefab pieces, add REAL
+turn/ramp pieces); bench-only grades (Sindicate wants ramps — and already owns better
+grade math: the rail formation solver); /tmp logging in loops; per-piece MeshColliders;
+RoadPieceData prefab hacks.
+
+Key files: ManhattanGridGenerator.cs, CityData.cs, RoadConnectorPoints.cs,
+JunctionConnectionPoints.cs, TerrainGeneratorWindow_{Cities,CityJunctions,
+CityTerrainFlattening,InterJunctionRoads}.cs, CurvedRoadMeshGenerator.cs,
+RoadNetworkBuilder.cs, SplinePlacer.cs, PROCEDURAL_MAP_GENERATOR_PLAN.md (Phase 8 §4729,
+postmortems §8336-8420).

package/docs/plans/road-system.md

@@ -0,0 +1,142 @@
+# SINDICATE PREFAB ROADS — design for Nick's review (NO CODE UNTIL SIGNED OFF)
+
+> Nick: "roads using prefabs too where we cut the smallest bit of them to allow drawing
+> them in in single instances etc and allow turns and uphill downhill with them etc."
+> Foundation: docs/plans/kiwi-road-recon.md (what Kiwi proved + what it never solved).
+
+## The one-system rule (Kiwi's lesson #1)
+
+Kiwi grew three overlapping road systems because its grid had no real turn pieces.
+Sindicate builds ONE: a PIECE GRAPH — typed prefab pieces joined socket-to-socket,
+rendered as InstancedMesh batches (one per piece type), never editing geometry per
+instance. Pieces are AUTHORED to mate exactly; welding-by-vertex-snap is banned.
+
+## 1. The piece library (per road kit, registered like setKitContent)
+
+A game registers a ROAD KIT — content, not engine:
+```js
+setRoadKit({
+  dir, atlas,
+  pieces: {
+    straight: [{ file, len }],            // several lengths; shortest = the CUT quantum
+    corner:   [{ file, radius, angle }],  // 90° (and 45° where the pack has one)
+    tee: { file }, cross: { file },
+    ramp: [{ file, len, rise }],          // grade variants (see §4)
+    endcap: { file },
+  },
+  width, surfaceY,                        // measured off the meshes once
+  props: { barrier, lamp, sign... },      // optional dressing hooks
+})
+```
+- GTA game: POLYGON_City kit (Kiwi's own source pieces — Road_01/Straight_01/Corner_01/
+  Road_Crossing_01/Flyover_01 family).
+- Fable: no modern roads in Fantasy Kingdom — its "roads" stay the painted/benched
+  terrain lanes we have (the survey), optionally dressed with the pack's cobble/path
+  floor pieces later. The piece system is for kits that HAVE road prefabs.
+- Western: stays on painted dirt roads (correct for 1880).
+
+Sockets are NOT hand-authored: at kit registration the engine measures each piece
+(bounds; road along local +Z; back socket at minZ, front at maxZ, surface at maxY —
+Kiwi's convention) and builds { armId, pos, dir, laneCount } tables per type.
+
+## 2. The network model (designer-facing)
+
+The DESIGNER draws what Kiwi called blue lines: polylines + junction nodes, per road
+type. The layout JSON stores INTENT, the solver output stores RESULT:
+```js
+roadsV2: {
+  nodes: [{ id, x, z }],                       // junction/endpoint nodes
+  links: [{ a, b, type, via: [{x,z}...] }],    // optional via = curve hints
+}
+// solved (cached in the cook, not hand-edited):
+// pieces: [{ type, file, x, y, z, ry, pitch, sz }...] + junction placements
+```
+
+## 3. The solver (engine — the new module, world/roadGraph.js)
+
+1. NODE RESOLUTION (Kiwi §5, copy): count links per node → cross/tee/corner/straight-
+   through/endcap piece + 90°-stepped rotation (T's missing arm rule verbatim).
+2. LINK FITTING: between the two junction sockets, walk the (optionally curved) path
+   with the SplinePlacer law: grow the current straight until tangent deviation > A°
+   (tunable, Kiwi used 3°), cut, place the LONGEST library straight that fits, repeat;
+   remainder < shortest straight → stretch the last piece via sz (the permanentWay
+   adaptive-panel trick — same batch, z-scale in the matrix). Corners consume their
+   authored arc; curve hints (via points) become corner+straight sequences.
+3. GRADES (Sindicate's advantage — Kiwi never solved this): the link's vertical profile
+   comes from solveFormation (rail solver: max-grade Lipschitz envelopes + vertical
+   curves), pieces pitch via makeChordMatrix (yaw→pitch→z-scale — sleepers stay level,
+   Kiwi had nothing like it). Ramp pieces are selected when |grade| exceeds what a
+   pitched straight reads well at; junction pads are LEVEL (yards law).
+4. OUTPUT: per-type matrix lists → panelBatch (scatterDeco road surface — walk-over law)
+   + collision stays the benched terrain; junction pieces placed like castings.
+
+## 4. Terrain: the road benches the ground (Kiwi §4 + our survey)
+
+The solved centreline + width feeds the SAME machinery our rails use: applyRail-style
+corridor blend to the piece profile (bed = surfaceY − offset), Kiwi's indent+skirt
+(2m flat, 3m smoothstep) as the cross-section, cut AND fill, into heightAt → the
+heightfield/zones cooks re-fingerprint (roadsV2 hash joins the cook names). The ground
+is the road, the pieces dress it — the lesson the railway already proved.
+
+## 5. Designer UX (v4)
+
+- ROAD MODE v2: click nodes/links instead of raw polylines; type picker; live solver
+  preview (pieces appear as you draw, junction pieces swap as links connect).
+- MCP: designer_road_node / designer_road_link / designer_road_solve.
+- Layout JSON carries roadsV2; buildDesign stamps solved pieces; graduation to a game
+  feeds the centrelines into setRoadNetwork for the benching + cook.
+
+## 6. Build order (after sign-off)
+
+1. roadGraph.js solver core (nodes→junction resolution, link fitting, chord matrices) —
+   provable headless (piece counts + junction types on synthetic networks).
+2. POLYGON_City import + road-kit registration + a test design stamped in a scratch
+   scene (this is also the GTA game's first world artifact).
+3. Benching integration (roadsV2 → survey corridor → cook re-fingerprint).
+4. Designer road mode v2 + MCP verbs.
+
+## Open questions for Nick
+- OK that fable/western keep terrain-painted roads (piece roads = City pack era)?
+- Corner radii: lock to the pack's authored radius only (simplest), or also synthesize
+  gentle curves from short straights at deviance-cut angles (Kiwi's overlay did this —
+  more flexible, more math)?
+- Junction sprawl: POLYGON_City has flyovers/supports — v1 scope flat junctions only,
+  flyovers later?
+
+## 7. Direct salvage from Kiwi (Nick: "there are bits you could take out to reuse ofc")
+
+**Algorithms — port near-verbatim (C# → JS is mechanical):**
+- SplinePlacer.cs variable-size loop (:123-253) → the link-fitting cutter in roadGraph.js.
+- ManhattanGridGenerator flood-fill + water/slope gating + dead-end→ray→T + largest-
+  component filter → the AUTO-CITY-GRID generator (a designer "generate district" verb —
+  the GTA game's city blocks for free).
+- _CityJunctions junction-count→piece+rotation table (incl. the missing-arm-north rule).
+- _CityTerrainFlattening footprint-polygon bench (rings→edge lists, indent+skirt,
+  per-edge interpolated heights) → the survey corridor cross-section.
+- SampleModifiedSpline straight→bézier→straight blend → curve hints between nodes.
+- JunctionConnectionPoints data model (armId/pos/dir/roadType/laneCount/speedLimit).
+
+**Assets — the tuned meshes themselves (need ONE Unity export pass):**
+- Junction_{4Way,T,LCorner}_City_Simpligon + RoadSegment_Simpligon are Nick's own
+  tuned pieces, stored as Unity .asset meshes (Road/Markings/Sidewalk sub-meshes per
+  junction — the sub-mesh split is EXACTLY our flattenToGeometry split convention).
+- The generated interchange prefabs (SimpleRoundabout_01, OverpassRoundabout, Dumbbell
+  variants in Prefabs/Roads/) are real saved meshes — a whole interchange library.
+- ASK NICK: open Kiwi in Unity once and export these to FBX (adapt the existing
+  Editor/ExportMyAssets.cs, or the FBX Exporter package) → we import them as a
+  "KiwiRoads" pack through the pack importer and the road kit is instantly armed with
+  proven pieces + interchanges. ~10 minutes of Unity time buys the whole piece library.
+
+**Data:** BLOCK_SIZE-derived constant table; RoadType/laneCount/speedLimit enums.
+
+## 8. The rest of AIGenerateMap (Nick: "and the other bits too ofc")
+
+Beyond roads, the Kiwi world-builder code to mine (all plain C#, no Unity needed):
+- ManhattanGridGenerator + CityData → designer "generate district" verb (city blocks).
+- TerrainStamp (blend-mode heightmap stamps) + VoronoiNoise + FalloffGenerator → port
+  into engine geo.js (Voronoi + stamps are real gaps; fbm family already ours).
+- Terrain/Vegetation/GrassDecorator (+Configs) → config-shape inspiration for our
+  placement/flora systems (machinery stays ours).
+- TerrainTextureApplicator + colormaps → heightfield paint reference.
+- InterCityRoadWindow spline/interchange generation → mined per-need for the solver.
+- NewMapConfig/GeneratedTerrainData assets → GTA-game map parameter reference.

package/docs/plans/three-cities.md

@@ -0,0 +1,43 @@
+# THE THREE CITIES RUN — Nick's founding request for the World Designer
+
+> "come up with a huge map with 3 cities 6 towns and road networks between them all
+> using the prefabs from the packs"
+
+## The pipeline (all pieces SHIPPED as of 0.14)
+
+1. **Author** — an MCP-driven Claude session drives `/designer.html` on fable (5317)
+   through the `aldenvale-designer` tools (place/move/road/camera/save) while the human
+   watches; or write the JSON directly (it is the same artifact). Layouts save to
+   `fable/designs/<name>.json`.
+2. **Preview** — boot `?autostart&design=<name>`: engine `buildDesign()` stamps the
+   layout live (visual-only, post-BVH).
+3. **Integrate** — stamp the accepted designs in `world.build()` BEFORE the BVH bake
+   (collision + grass occupancy for free), and feed the design `roads` polylines into
+   the terrain survey (`setRoadNetwork`) so the ground benches under them → re-cook.
+
+## Authoring facts
+
+- Palette: POLYGON_Fantasy_Kingdom, 2,186 models. The `SM_Bld_Preset_*_Optimized`
+  composites are WHOLE dressed buildings — cities assemble from these, not wall pieces.
+  Atlas: `PolygonFantasyKingdom_Texture_01_A.png` (every entry carries `tex`).
+- Layout entry: `{ file, dir, x, z, ry, y?, s?, tex }`; omit `y` to seat on terrain.
+- World: 4320 m square, Aldenvale relief is real — site cities on the flats
+  (designer viewport shows the relief; check `heightAt` spread before committing a site).
+- Existing settlements to respect (never overlap): Oakhollow (0,14 r~90), the castle
+  (1120,800), Bracklow, VILLAGES/CAMPS lists, Ironkeep (DWARF), Ravenspire (-1400,-1200).
+- Compass: north = −z. Roads: polylines in `roads`, ≥12 m from any building
+  (the farm-rect law), gentle bends (the survey benches them).
+
+## Suggested sites (from the relief + the existing map)
+
+- City A: the plain SE of Oakhollow (~500, 400) — river-adjacent, flat.
+- City B: the western meadows (~-900, 300).
+- City C: the north coast road (~300, -1100).
+- Six towns strung on the road net between them + the existing villages as waypoints.
+- Budget: city ≈ 40-70 presets + walls/props; town ≈ 12-20. Total ≈ 350 placements —
+  trivial for the stamper (49k placements cook in seconds).
+
+## Definition of done
+
+Every city/town saved as its own design file (composable), one master road list,
+preview screenshots of each site, Nick signs the look before integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.12.0",
+  "version": "0.15.0",
   "description": "Sindicate — open-world game engine for three.js WebGPU. Streaming worlds, characters, mounts & vehicles, missions, crowds.",
   "type": "module",
   "main": "src/index.js",
@@ -29,11 +29,19 @@
     "src",
     "tools",
     "docs",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
     "three": "^0.184.0",
     "three-mesh-bvh": "^0.9.10"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "bin": {
+    "sindicate": "tools/sindicate-cli.mjs"
+  },
+  "devDependencies": {
+    "three": "^0.184.0",
+    "three-mesh-bvh": "^0.9.10"
+  }
 }

package/src/core/assets.js

@@ -498,6 +498,21 @@ export async function instantiate(url, opts) {
 // CONTRACT: these materials are shared game-wide — never mutate one on an instance;
 // clone first (see player.applyMoralityLook).
 const atlasMatCache = new Map();
+
+// NodeMaterial.clone() (three r184 WebGPU) silently DROPS the texture and node slots —
+// a private tint clone (player morality, enemy variants, shatter shards) came back
+// bare white. Clone through THIS and the slots ride along.
+export function cloneMat(m) {
+  const c = m.clone();
+  for (const k of ['map', 'normalMap', 'roughnessMap', 'metalnessMap', 'aoMap', 'emissiveMap', 'alphaMap', 'bumpMap']) {
+    if (m[k] && !c[k]) c[k] = m[k];
+  }
+  for (const k of ['colorNode', 'emissiveNode', 'roughnessNode', 'positionNode', 'opacityNode', 'normalNode']) {
+    if (m[k] && !c[k]) c[k] = m[k];
+  }
+  return c;
+}
+
 export function applyAtlas(root, tex, { emissive = null } = {}) {
   root.traverse((o) => {
     if (!o.isMesh) return;

package/src/systems/missions.js

@@ -37,7 +37,7 @@ async function captureThumb(game) {
   try {
     const { renderer, scene, camera } = game;
     if (!renderer?.readRenderTargetPixelsAsync || !scene || !camera) return null;
-    const w = 256, h = 144;
+    const w = 640, h = 360;   // pane-sized: 256px thumbs blown up to the detail pane read as mush
     const rt = (captureThumb._rt ||= new THREE.RenderTarget(w, h));
     renderer.setRenderTarget(rt);
     renderer.render(scene, camera);
@@ -51,7 +51,7 @@ async function captureThumb(game) {
     const ctx = c.getContext('2d'), img = ctx.createImageData(w, h);
     img.data.set(buf);   // top-left origin — no flip (per map.js)
     ctx.putImageData(img, 0, 0);
-    return c.toDataURL('image/jpeg', 0.62);
+    return c.toDataURL('image/jpeg', 0.7);
   } catch (e) { console.warn('[save] thumbnail failed', e?.message ?? e); return null; }
 }
 

package/src/systems/shatter.js

@@ -3,6 +3,7 @@
 // bounce + settle on the floor, then fade them away. Pure CPU integration on a tiny pool — no engine,
 // no per-shard lights, nothing resident (the meshes are added on smash and removed when faded).
 import * as THREE from 'three/webgpu';
+import { cloneMat } from '../core/assets.js';
 
 const G = 17;              // gravity (m/s²-ish, tuned for snappy low-poly debris)
 const REST = 0.34;         // floor bounce restitution
@@ -26,7 +27,7 @@ export class Shatter {
       const tmpl = frags[i % frags.length];
       const m = tmpl.clone(true);
       // independent material instances so each shard fades on its own
-      m.traverse((o) => { if (o.material) o.material = Array.isArray(o.material) ? o.material.map((x) => x.clone()) : o.material.clone(); });
+      m.traverse((o) => { if (o.material) o.material = Array.isArray(o.material) ? o.material.map((x) => cloneMat(x)) : cloneMat(o.material); });
       m.scale.multiplyScalar(scale);
       const pivot = tmpl.userData?.pivot;
       let vel;

package/src/ui/dialogue.js

@@ -42,6 +42,7 @@ let nodeHook = null;
 export function setDialogueOptionHandler(fn) { optionHandler = fn; }
 export function setDialogueNodeHook(fn) { nodeHook = fn; }
 import { padMode, buttonCanvas } from './menuHints.js';
+import { THEME } from './theme.js';
 
 // ── the two-shot, in numbers ────────────────────────────────────────────────────────────────────
 // The lens stands in FRONT of the NPC (he has already turned to face the player, so his front faces
@@ -499,7 +500,7 @@ export class Dialogue {
       #dlg .dlg-byekey { display:inline-flex; align-items:center; vertical-align:middle; margin-right:9px; }
       #dlg .dlg-byekey.kbd { width:18px; height:18px; justify-content:center; line-height:17px; font-size:12px;
         font-weight:700; color:#f4e3b0; border:1px solid #8a6a3a; border-radius:4px; background:rgba(40,28,14,0.92); }
-    `;
+    ` + (THEME.dialogueCss || '');
     document.head.appendChild(css);
   }
 }

package/src/ui/pauseMenu.js

@@ -6,6 +6,7 @@
 import { getQualityName, setQualityName, PRESETS } from '../core/quality.js';
 import { renderHints, refreshHints, padMode } from './menuHints.js';
 import { showSaveLoad } from './saveLoadScreen.js';
+import { THEME } from './theme.js';
 
 // PAUSE CONTENT is GAME data (setPauseContent in engineSetup):
 //   extraItems(game, {resume,close}) → [{label, action}] — game pages (CHARACTER/JOURNAL…)
@@ -17,10 +18,10 @@ import { showSaveLoad } from './saveLoadScreen.js';
 let PAUSE = { saves: null, extraItems: null, settingsRows: null, onQualityChange: null };
 export function setPauseContent(c = {}) { PAUSE = { ...PAUSE, ...c }; }
 
-const GOLD = '#e8c87a';
-const TXT = '#ecdfc2';
-const MUT = '#b6a577';
-const FONT = "Copperplate,'Copperplate Gothic Bold','Palatino','Book Antiqua',Georgia,serif";
+const GOLD = THEME.gold;
+const TXT = THEME.text;
+const MUT = THEME.mut;
+const FONT = THEME.font;
 const clamp = (v, a, b) => Math.max(a, Math.min(b, v));
 const CORNER_SVG = `<svg viewBox="0 0 44 44" width="30" height="30" fill="none" stroke="${GOLD}" stroke-linecap="round"><path d="M3 24 V3 H24" stroke-width="2"/><path d="M9 19 V9 H19" stroke-width="1" opacity="0.6"/><path d="M3 3 h9 l-9 9 z" fill="${GOLD}" stroke="none"/></svg>`;
 const DIVIDER_SVG = `<svg viewBox="0 0 220 14" width="200" height="12" fill="none" stroke="${GOLD}" stroke-width="1.4" stroke-linecap="round"><line x1="8" y1="7" x2="94" y2="7"/><line x1="126" y1="7" x2="212" y2="7"/><circle cx="8" cy="7" r="1.6" fill="${GOLD}"/><circle cx="212" cy="7" r="1.6" fill="${GOLD}"/><path d="M110 1 l7 6 l-7 6 l-7 -6 z" fill="${GOLD}"/></svg>`;
@@ -32,11 +33,15 @@ function el(tag, css, text) {
   return e;
 }
 function framedPanel(w = 420) {
-  const p = el('div', `position:relative;width:${w}px;max-width:90vw;padding:28px 36px 24px;color:${TXT};border:1px solid rgba(232,200,122,0.55);border-radius:3px;`
-    + 'background:linear-gradient(157deg,#241b11 0%,#160f09 58%,#0d0805 100%);box-shadow:0 26px 74px rgba(0,0,0,0.86);');
-  p.appendChild(el('div', 'position:absolute;inset:6px;border:1px solid rgba(232,200,122,0.26);border-radius:2px;pointer-events:none;'));
-  const c = (pos, rot) => { const d = el('div', `position:absolute;${pos}width:30px;height:30px;pointer-events:none;transform:rotate(${rot}deg);`); d.innerHTML = CORNER_SVG; p.appendChild(d); };
-  c('left:3px;top:3px;', 0); c('right:3px;top:3px;', 90); c('right:3px;bottom:3px;', 180); c('left:3px;bottom:3px;', 270);
+  const ground = THEME.panelCss
+    ?? `color:${TXT};border:1px solid rgba(232,200,122,0.55);border-radius:3px;`
+    + 'background:linear-gradient(157deg,#241b11 0%,#160f09 58%,#0d0805 100%);box-shadow:0 26px 74px rgba(0,0,0,0.86);';
+  const p = el('div', `position:relative;width:${w}px;max-width:90vw;padding:28px 36px 24px;${ground}`);
+  if (THEME.filigree) {
+    p.appendChild(el('div', 'position:absolute;inset:6px;border:1px solid rgba(232,200,122,0.26);border-radius:2px;pointer-events:none;'));
+    const c = (pos, rot) => { const d = el('div', `position:absolute;${pos}width:30px;height:30px;pointer-events:none;transform:rotate(${rot}deg);`); d.innerHTML = CORNER_SVG; p.appendChild(d); };
+    c('left:3px;top:3px;', 0); c('right:3px;top:3px;', 90); c('right:3px;bottom:3px;', 180); c('left:3px;bottom:3px;', 270);
+  }
   return p;
 }
 
@@ -55,8 +60,10 @@ export function showPauseMenu(game, opts = {}) {
   const close = () => { if (closed) return; closed = true; cancelAnimationFrame(raf); window.removeEventListener('keydown', onKey); root.remove(); };
   const resume = () => { close(); opts.onResume?.(); };
 
-  const hl = (b, on) => { b.style.background = on ? GOLD : 'rgba(232,200,122,0.06)'; b.style.color = on ? '#1a1207' : TXT; b.style.borderColor = on ? GOLD : 'rgba(232,200,122,0.45)'; };
-  const BTN = `padding:9px 20px;border:1px solid rgba(232,200,122,0.45);border-radius:5px;cursor:pointer;font-family:inherit;letter-spacing:2px;font-size:15px;background:rgba(232,200,122,0.06);color:${TXT};transition:background .12s,color .12s;`;
+  const ACT = THEME.btnActive ?? { bg: GOLD, color: '#1a1207', border: GOLD };
+  const OFF = THEME.btnCss ? { bg: '', color: '', border: '' } : { bg: 'rgba(232,200,122,0.06)', color: TXT, border: 'rgba(232,200,122,0.45)' };
+  const hl = (b, on) => { b.style.background = on ? ACT.bg : OFF.bg; b.style.color = on ? ACT.color : OFF.color; b.style.borderColor = on ? ACT.border : OFF.border; };
+  const BTN = THEME.btnCss ?? `padding:9px 20px;border:1px solid rgba(232,200,122,0.45);border-radius:5px;cursor:pointer;font-family:inherit;letter-spacing:2px;font-size:15px;background:rgba(232,200,122,0.06);color:${TXT};transition:background .12s,color .12s;`;
   const rowWrap = () => el('div', 'display:flex;align-items:center;gap:14px;margin:12px 0;padding:5px 6px;border-radius:5px;');
   const rowLabel = (t) => el('div', `width:110px;text-align:right;color:${MUT};font-size:14px;letter-spacing:1px;text-transform:uppercase;`, t);
 

package/src/ui/saveLoadScreen.js

@@ -7,12 +7,13 @@
 // opts: { mode:'load'|'save', slots:[…ids], list:()=>saves, onLoad(slot), onSave(slot,name),
 //         onDelete(slot), onClose() }. Returns { close }.
 import { renderHints, refreshHints, padMode } from './menuHints.js';
+import { THEME } from './theme.js';
 
 const UI = '/assets/ui/menu';
-const GOLD = '#e8c87a';
-const TXT = '#ecdfc2';
-const MUT = '#b6a577';
-const FONT = "Copperplate,'Copperplate Gothic Bold','Palatino','Book Antiqua',Georgia,serif";
+const GOLD = THEME.gold;
+const TXT = THEME.text;
+const MUT = THEME.mut;
+const FONT = THEME.font;
 
 function el(tag, css, text) {
   const e = document.createElement(tag);
@@ -27,7 +28,7 @@ export function showSaveLoad(opts = {}) {
   const save = opts.mode === 'save';
   const slotIds = opts.slots || ['1', '2', '3', '4', '5', '6'];
 
-  const root = el('div', `position:fixed;inset:0;z-index:130;display:flex;flex-direction:column;font-family:${FONT};background:#0a0705;`);
+  const root = el('div', `position:fixed;inset:0;z-index:130;display:flex;flex-direction:column;font-family:${FONT};background:${THEME.screenBg};`);
   root.appendChild(el('div', `position:absolute;inset:0;background:#000 url(${UI}/title_bg.jpg) center/cover;opacity:0.08;`));
   root.appendChild(el('div', 'position:absolute;inset:0;background:linear-gradient(180deg,rgba(10,7,5,0.86),rgba(10,7,5,0.96));'));
   const head = el('div', 'position:relative;padding:44px 60px 16px;border-bottom:1px solid rgba(232,200,122,0.22);flex:none;');
@@ -49,9 +50,12 @@ export function showSaveLoad(opts = {}) {
 
   const showDetail = (rec) => {
     if (!rec) { detail.innerHTML = `<div style="flex:1;display:flex;align-items:center;justify-content:center;color:${MUT};letter-spacing:2px">${save ? 'NEW SAVE' : 'EMPTY'}</div>`; return; }
-    const img = rec.thumb ? `<img src="${rec.thumb}" style="width:100%;height:100%;object-fit:cover">`
-      : `<div style="flex:1;display:flex;align-items:center;justify-content:center;color:${MUT};font-size:12px;letter-spacing:3px">NO PREVIEW</div>`;
-    detail.innerHTML = `<div style="flex:1;min-height:190px;background:linear-gradient(135deg,#1a130b,#0d0906);display:flex;overflow:hidden">${img}</div>`
+    const img = rec.thumb ? `<img src="${rec.thumb}" style="width:100%;height:100%;object-fit:cover;display:block">`
+      : `<div style="width:100%;height:100%;display:flex;align-items:center;justify-content:center;color:${MUT};font-size:12px;letter-spacing:3px">NO PREVIEW</div>`;
+    // a FRAMED 16:9 plate, not a full-pane stretch — a small thumb blown to the pane reads as mush
+    detail.innerHTML = `<div style="padding:22px 24px 0"><div style="aspect-ratio:16/9;max-height:340px;margin:0 auto;`
+      + `background:linear-gradient(135deg,#1a130b,#0d0906);border:1px solid rgba(232,200,122,0.28);border-radius:3px;`
+      + `box-shadow:0 10px 30px rgba(0,0,0,0.5), inset 0 0 40px rgba(0,0,0,0.35);overflow:hidden">${img}</div></div>`
       + `<div style="padding:20px 24px"><div style="color:${GOLD};font-size:22px;letter-spacing:2px;font-weight:700">${rec.name || rec.title || opts.defaultTitle || 'Saved game'}</div>`
       + `<div style="color:${MUT};font-size:13px;margin-top:8px;line-height:1.9">${rec.auto ? 'Autosave · ' : ''}${fmtDate(rec.savedAt)}<br>Played ${fmtTime(rec.playtime)} &nbsp;·&nbsp; ${opts.moneyLabel ?? 'Purse $'}${rec.money ?? 0}${rec.objective ? '<br>' + rec.objective : ''}</div></div>`;
   };
@@ -59,7 +63,7 @@ export function showSaveLoad(opts = {}) {
   const rebuild = () => {
     const saves = opts.list ? opts.list() : [];
     const bySlot = {}; saves.forEach((s) => { bySlot[String(s.slot)] = s; });
-    const ids = save ? slotIds : ['auto', ...slotIds].filter((id) => bySlot[id]);   // load: only filled; save: all manual slots
+    const ids = save ? slotIds : [...new Set(['auto', ...slotIds])].filter((id) => bySlot[id]);   // load: only filled (auto deduped — a game may list it in its own slots); save: all manual slots
     listEl.innerHTML = ''; items = [];
     if (!ids.length) { listEl.appendChild(el('div', `color:${MUT};opacity:0.8;padding:12px;`, 'No saved games yet.')); showDetail(null); return; }
     ids.forEach((id) => {

package/src/ui/theme.js

@@ -0,0 +1,34 @@
+// THE UI THEME — the rule, codified after the fable title-menu incident: the ENGINE owns
+// the FUNCTIONALITY of a screen; the GAME owns its LOOK. Every value here is declarative
+// (a game ships them as src/game/uiTheme.json and registers it in engineSetup with
+// setUiTheme(theme)), so a re-dress never touches engine code.
+//
+// The defaults are the neutral dark leather-and-gold dress the engine screens shipped with
+// (Dustwater's palette — western's own uiTheme.json restates it explicitly). The engine UI
+// modules are lazily imported AFTER engineSetup runs, so module-load reads of THEME see the
+// game's registration.
+//
+//   font        — the screens' font stack
+//   gold/text/mut — accent, body text, muted labels
+//   panelCss    — the framed panel's ground (popup confirms, the pause panel). Replaces the
+//                 default gradient+border block; the engine still positions and sizes it.
+//   filigree    — draw the gold corner flourishes + inner rule on panels (default true; a
+//                 parchment skin usually wants them off)
+//   btnCss      — the standard button plate (settings rows, confirms, save-slot actions)
+//   btnActive   — { bg, color, border } for the highlighted/selected state
+//   screenBg    — full-screen browser background (save/load screen ground)
+//   dialogueCss — appended after the dialogue panel's own CSS; override any #dlg selector
+export const THEME = {
+  font: "Copperplate,'Copperplate Gothic Bold','Palatino','Book Antiqua',Georgia,serif",
+  gold: '#e8c87a',
+  text: '#ecdfc2',
+  mut: '#b6a577',
+  panelCss: null,       // null = the engine's dark leather gradient
+  filigree: true,
+  btnCss: null,         // null = the engine's gold-outline plate
+  btnActive: null,      // null = { bg: gold, color: '#1a1207', border: gold }
+  screenBg: '#0a0705',
+  dialogueCss: '',
+};
+
+export function setUiTheme(t = {}) { Object.assign(THEME, t); }