sindicate 0.4.0 → 0.6.0

package/src/ui/cartograph.js

@@ -0,0 +1,456 @@
+// THE CHART OF DUSTWATER COUNTY — and the gazetteer of everything on it.
+//
+// THREE THINGS LIVE HERE, and they are deliberately the three things that are PURE:
+//   renderChart()  — the paper. A function of the terrain and nothing else (heightAt +
+//                    roadDistance + ROADS + RIVERS), rendered ONCE into a bitmap.
+//   allPOIs()      — the places. Assembled from the world's OWN tables (TOWN, OUTPOSTS,
+//                    STOPS, SETTLEMENTS), so the map cannot disagree with the county.
+//   allBuildings() — the ROOFS. Every building in the county in world space, from those same
+//                    tables — what the minimap paints its grey blocks from.
+// Everything that MOVES — markers, labels, the player, the waypoint, pan and zoom — lives in
+// worldmap.js and rides on top in screen space. That split is the whole point: the ground does
+// not move, so re-rendering it on a wheel tick is a waste, and an icon that scales with the
+// chart is unreadable at both ends of the zoom.
+//
+// WHY IT LOOKS LIKE PAPER. The first chart was a screenshot-coloured heightmap and it read as a
+// grey-brown smear, because Dustwater IS a smear: a near-flat plain where 900 m of desert differ
+// by two metres. A satellite view of flat ground is a picture of nothing. So this is drawn the
+// way a rider's map would be drawn — ink CONTOURS every four metres (the one thing that makes
+// flat country legible: the lines fan out where it's flat and crowd where it's steep), a lit
+// relief over the top, the roads as ink, the creek in wash, and the whole thing on aged paper.
+// The chart is a pure projection of GAME world data — register it all before the first
+// renderChart/allPOIs call (the game's boot does this from its world module):
+//   setChartWorld({ heightAt, roadDistance, roads, rivers, lakes, worldSize, town, fbm,
+//                   railPaths, outposts, campfires, coachStop, coachStops, buildings })
+let heightAt = () => 0, roadDistance = () => 1e9, fbm = () => 0;
+let ROADS = [], RIVERS = [], LAKES = [], TOWN = null, RAIL_PATHS = [];
+let OUTPOSTS = [], CAMPFIRE_SPOTS = [], COACH_STOP = null, STOPS = [], DUSTWATER = [];
+export let WORLD_SIZE = 4320;
+export function setChartWorld(w = {}) {
+  if (w.heightAt) heightAt = w.heightAt;
+  if (w.roadDistance) roadDistance = w.roadDistance;
+  if (w.fbm) fbm = w.fbm;
+  if (w.roads) ROADS = w.roads;
+  if (w.rivers) RIVERS = w.rivers;
+  if (w.lakes) LAKES = w.lakes;
+  if (w.worldSize) WORLD_SIZE = w.worldSize;
+  if (w.town !== undefined) TOWN = w.town;
+  if (w.railPaths) RAIL_PATHS = w.railPaths;
+  if (w.outposts) OUTPOSTS = w.outposts;
+  if (w.campfires) CAMPFIRE_SPOTS = w.campfires;
+  if (w.coachStop !== undefined) COACH_STOP = w.coachStop;
+  if (w.coachStops) STOPS = w.coachStops;
+  if (w.buildings) DUSTWATER = w.buildings;
+}
+// ...continued registered world data (see setChartWorld): frontier areas, railway
+// areas, the county's population defs, and the shop tables for the gazetteer.
+let AREAS = [], RAILWAY_AREAS = [], COUNTY_DEFS = [];
+let shopIdFor = () => null, SHOPS = {}, isMerchant = () => false;
+export function setChartGazetteer(g = {}) {
+  if (g.areas) AREAS = g.areas;
+  if (g.railwayAreas) RAILWAY_AREAS = g.railwayAreas;
+  if (g.countyDefs) COUNTY_DEFS = g.countyDefs;
+  if (g.shopIdFor) shopIdFor = g.shopIdFor;
+  if (g.shops) SHOPS = g.shops;
+  if (g.isMerchant) isMerchant = g.isMerchant;
+}
+
+// Settlements are registered like the rest of the survey (the old in-game glob import
+// worked only game-side; an engine file cannot glob a game's data directory).
+let SETTLEMENTS = [], SETTLEMENT_AREAS = {};
+export function setChartSettlements(s = {}) {
+  if (s.settlements) SETTLEMENTS = s.settlements;
+  if (s.settlementAreas) SETTLEMENT_AREAS = s.settlementAreas;
+}
+
+const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
+const lerp = (a, b, t) => a + (b - a) * t;
+const smoothstep = (a, b, x) => { const t = clamp((x - a) / (b - a), 0, 1); return t * t * (3 - 2 * t); };
+
+// ————————————————————————————— THE GAZETTEER —————————————————————————————
+// Entry: { id, x, z, name, kind, category, icon, big }
+//   kind     — what the place IS ('town'|'fort'|'mission'|'camp'|'mine'|'stop'|'ranch'|…)
+//   category — the legend's language ('Settlement'|'Outpost'|'Stage'), i.e. how it FILTERS
+//   icon     — a basename in /assets/ui/map/ (white Synty silhouettes; worldmap inks them)
+//   big      — a place you navigate a county by: bigger stamp, bigger label, never suppressed
+//
+// The county's proper names. outposts.js carries these in its comments (the world knows what it
+// built); this is the one place that says them out loud, so a new pin renders with a name instead
+// of the raw id the old map printed.
+const OUTPOST_INFO = {
+  fort:    { name: 'Fort Copperhead',  kind: 'fort',    icon: 'flag' },
+  mexican: { name: 'Mission San Rojo', kind: 'mission', icon: 'cross' },   // a cross, because it is a church
+  native:  { name: 'Red Hawk Camp',    kind: 'camp',    icon: 'fire' },    // a campfire
+  drill:   { name: 'Bonebreak Quarry', kind: 'mine',    icon: 'ore' },     // the diggings
+};
+
+// SHOPS ON THE CHART — derived from the posted merchants (county.js) so the map cannot disagree with
+// who actually stands behind a counter. def.post/.roam are already world-space (toWorld ran at load).
+// MVP points every trade at one 'shop' silhouette; specialise per shop id as the art lands (edit SHOP_ICON).
+const SHOP_ICON = { general: 'shop', gunsmith: 'shop', doctor: 'shop', saloon: 'shop', stable: 'shop' };
+let _shops = null;
+function buildShopSpots() {
+  const out = [];
+  for (const def of COUNTY_DEFS) {
+    if (!isMerchant(def)) continue;
+    const pos = def.post ?? def.roam;
+    if (!pos || !Number.isFinite(pos.x) || !Number.isFinite(pos.z)) continue;
+    const shopId = shopIdFor(def);
+    out.push({ id: `shop:${def.id}`, x: pos.x, z: pos.z, shopId,
+      name: SHOPS[shopId]?.name ?? 'Shop', icon: SHOP_ICON[shopId] ?? 'shop' });
+  }
+  return out;
+}
+export function shopSpots() { return (_shops ??= buildShopSpots()); }
+
+// A settlement's trade decides its stamp. SETTLEMENTS is someone else's table and may land with
+// any shape at all, so every field is read defensively and nothing here is required.
+const settlementIcon = (s) => {
+  const t = `${s.kind ?? ''} ${s.id ?? ''} ${s.name ?? ''}`;
+  if (/mine|dig|claim|quarry/i.test(t)) return 'ore';
+  if (/grave|boot ?hill|cemet/i.test(t)) return 'skull';
+  if (/mission|church|chapel/i.test(t)) return 'cross';
+  if (/camp|fire/i.test(t)) return 'fire';
+  return 'home';                                    // a farm, a ranch, a homestead: a roof is a roof
+};
+
+let _pois = null;
+function buildPOIs() {
+  const out = [
+    { id: 'town', x: TOWN.x, z: TOWN.z, name: 'Dustwater', kind: 'town', category: 'Settlement', icon: 'home', big: true },
+  ];
+  for (const o of OUTPOSTS) {
+    const info = OUTPOST_INFO[o.id] ?? { name: o.id, kind: 'outpost', icon: 'star' };
+    out.push({ id: `outpost:${o.id}`, x: o.x, z: o.z, name: info.name, kind: info.kind, category: 'Outpost', icon: info.icon, big: true });
+  }
+  for (const s of STOPS) {
+    // the depot is Dustwater's own stage office — it sits inside the town's marker, so it is
+    // named for what it is rather than repeating the town's name at half size
+    out.push({ id: `stop:${s.id}`, x: s.x, z: s.z, name: s.inTown ? 'Stage Depot' : `${s.name} Stop`, kind: 'stop', category: 'Stage', icon: 'horse' });
+  }
+  // rest-fires — the same six the game builds (see data/campfires.js); always on the map so a ride
+  // into the wilds can be planned around a place to sleep. The compass/minimap draw them too.
+  CAMPFIRE_SPOTS.forEach((s, i) => {
+    out.push({ id: `camp:${i}`, x: s.x, z: s.z, name: 'Campfire', kind: 'camp', category: 'Camp', icon: 'fire' });
+  });
+  for (const s of SETTLEMENTS ?? []) {
+    if (!Number.isFinite(s?.x) || !Number.isFinite(s?.z)) continue;   // half-authored row: skip, don't crash the map
+    out.push({
+      id: `settle:${s.id ?? s.name}`, x: s.x, z: s.z,
+      name: s.name ?? s.id ?? 'Homestead',
+      kind: s.kind ?? 'ranch', category: 'Settlement',
+      icon: s.mapIcon ?? settlementIcon(s), big: !!s.big,
+    });
+  }
+  // the storefronts — the same posted merchants the compass/minimap draw, so all three agree
+  for (const s of shopSpots()) {
+    out.push({ id: s.id, x: s.x, z: s.z, name: s.name, kind: 'shop', category: 'Shop', icon: s.icon });
+  }
+  return out;
+}
+export function allPOIs() { return (_pois ??= buildPOIs()); }
+export function poiById(id) { return allPOIs().find((p) => p.id === id) ?? null; }
+
+// ————————————————————————————— THE ROOFS —————————————————————————————
+// EVERY BUILDING IN THE COUNTY, in world space: { x, z, ry, collider, name }.
+//
+// The minimap used to paint its grey blocks straight out of town.js's BUILDINGS — which is
+// dustwaterLayout's table and NOTHING else. That was the whole map when Dustwater was the whole
+// county; it is now 48 of the county's 121 buildings, so a rider standing in the middle of
+// Perdition's main street — a second town, eleven buildings — had a minimap with two roads on it
+// and not one roof. Same failure at the fort, the mission, the quarry, every farm and ranch, both
+// line shacks, the burnt claim, the three stage offices and the two railway platforms.
+//
+// The reason they were missing is not a cull: they were never in the list. Dustwater's layout is
+// authored in WORLD coordinates, and every other place in the county is an AREA — a layout authored
+// around its own centre and stamped at a pin (town.js buildArea). So an area's buildings have to go
+// through the SAME transform the stamper uses, or they all pile up on the county's origin:
+//     world = pin + R(pin.ry)·local        heading = b.ry + pin.ry
+// with R three's own Y rotation (x' = x·cos + z·sin, z' = −x·sin + z·cos) — buildArea:517, copied
+// here rather than guessed, because a sign error here puts the barn on the wrong side of the yard.
+//
+// The pins come from the same arrays the WORLD builds from (world.js:69-99): STOPS, OUTPOSTS — which
+// outposts.js has already spread SETTLEMENTS into — and RAILWAY_AREAS, whose pins are computed off
+// the solved rail centreline. One list, two consumers: a building cannot stand in the world and be
+// missing from the map.
+let _blds = null;
+function buildStructures() {
+  const out = DUSTWATER.map((b) => ({ x: b.x, z: b.z, ry: b.ry ?? 0, collider: b.collider ?? 4, name: b.name }));
+  const stamp = (area, at) => {
+    if (!area || !at || !Number.isFinite(at.x) || !Number.isFinite(at.z)) return;
+    const cos = Math.cos(at.ry ?? 0), sin = Math.sin(at.ry ?? 0);
+    for (const b of area.buildings ?? []) {
+      out.push({
+        x: at.x + b.x * cos + b.z * sin,
+        z: at.z - b.x * sin + b.z * cos,
+        ry: (b.ry ?? 0) + (at.ry ?? 0),
+        collider: b.collider ?? 4,
+        name: b.name ?? area.name,
+      });
+    }
+  };
+  for (const stop of STOPS) stamp(COACH_STOP, stop);            // the three stage offices
+  for (const spot of OUTPOSTS) {
+    if (spot.rail) continue;                                    // a pin that is only a pin — see outposts.js
+    stamp(SETTLEMENT_AREAS[spot.area] ?? AREAS.find((a) => a.id === spot.id), spot);
+  }
+  for (const { area, at } of RAILWAY_AREAS) stamp(area, at);    // the station and the loading stage
+  return out;
+}
+export function allBuildings() { return (_blds ??= buildStructures()); }
+
+// ————————————————————————————— THE PAPER —————————————————————————————
+
+// HEIGHT → INK. Not a satellite palette: the range a WATERCOLOURIST would use on a survey of
+// this county — bleached flats, dust, ochre, the red rock the quarry is cut into. Everything is
+// pulled toward the paper so the sheet reads as one document rather than a picture with a border.
+const LAND = [
+  [-8, [186, 169, 133]],   // the washes and the low ground
+  [2, [214, 198, 161]],    // the flats — sun-bleached, almost the paper itself
+  [16, [208, 183, 139]],   // dust
+  [36, [201, 163, 113]],   // rising ground — ochre
+  [64, [180, 130, 90]],    // mesa shoulder
+  [100, [153, 100, 74]],   // red rock
+  [145, [190, 162, 142]],  // bare stone, catching the light
+];
+function tint(h, out) {
+  for (let i = 1; i < LAND.length; i++) {
+    if (h <= LAND[i][0]) {
+      const [h0, c0] = LAND[i - 1], [h1, c1] = LAND[i];
+      const t = (h - h0) / (h1 - h0 || 1);
+      out[0] = lerp(c0[0], c1[0], t); out[1] = lerp(c0[1], c1[1], t); out[2] = lerp(c0[2], c1[2], t);
+      return out;
+    }
+  }
+  const c = LAND[LAND.length - 1][1];
+  out[0] = c[0]; out[1] = c[1]; out[2] = c[2];
+  return out;
+}
+
+// THE PADS. Town, every outpost, and any settlement that brought its own radius stand on
+// FLATTENED ground, and a flattened disc has a hard rim. Hillshade a hard rim and you get a grey
+// coffee-ring round every settlement; contour a hard rim and you get a bullseye. So relief AND
+// contours are suppressed inside them — they are drawn as markers anyway, and nobody needs to see
+// the shape of a slab.
+// Computed at CALL time, never at import: the registered survey lands after this module
+// evaluates (the module-level version crashed on TOWN=null before registration).
+function chartPads() {
+  return [
+    ...(TOWN ? [[TOWN.x, TOWN.z, TOWN.r + 14]] : []),
+    ...OUTPOSTS.map((o) => [o.x, o.z, o.r * 1.2]),
+    ...(SETTLEMENTS ?? []).filter((s) => Number.isFinite(s?.x) && Number.isFinite(s?.r)).map((s) => [s.x, s.z, s.r * 1.2]),
+  ];
+}
+const onAPad = (x, z) => {
+  for (const [px, pz, r] of chartPads()) if ((x - px) ** 2 + (z - pz) ** 2 < r * r) return true;
+  return false;
+};
+
+// CONTOURS. The interval is the whole design decision: at 10 m the plain has no lines at all and
+// the map is blank; at 2 m the mesas turn into a solid black band. 4 m gives the flats one or two
+// lazy lines to a mile and still resolves the terraced buttes in the outer ring. Every 5th is an
+// INDEX contour, drawn heavier, the way a real sheet does it.
+const CONTOUR = 4;
+const INDEX_EVERY = 5;
+
+// Render the chart. `size` is the bitmap's edge in pixels; the county is WORLD_SIZE metres, so at
+// 1600 one pixel is 1.35 m of desert — which still holds together at the map's 8× zoom, where the
+// old 900px sheet went to mush. It is nearly TWICE the sheet for LESS time (~1.2s measured, against
+// the old ~1.7s), because the height field is sampled into an array ONCE and the relief and the
+// contours are then read back out of it; the old one called heightAt five times per pixel to
+// difference its neighbours in place.
+export function renderChart(size = 1600) {
+  const cv = document.createElement('canvas');
+  cv.width = cv.height = size;
+  const ctx = cv.getContext('2d');
+  const M = WORLD_SIZE / size;                 // metres per pixel
+  const half = WORLD_SIZE / 2;
+  const w2p = (v) => (v / WORLD_SIZE + 0.5) * size;
+
+  // 1) THE FIELD, sampled once.
+  const H = new Float32Array(size * size);
+  const PAD = new Uint8Array(size * size);
+  for (let j = 0; j < size; j++) {
+    const z = -half + (j + 0.5) * M;
+    for (let i = 0; i < size; i++) {
+      const x = -half + (i + 0.5) * M;
+      const o = j * size + i;
+      H[o] = heightAt(x, z);
+      PAD[o] = onAPad(x, z) ? 1 : 0;
+    }
+  }
+
+  // 2) THE SHEET.
+  const img = ctx.createImageData(size, size);
+  const px = img.data;
+  const c = [0, 0, 0];
+  for (let j = 0; j < size; j++) {
+    const z = -half + (j + 0.5) * M;
+    for (let i = 0; i < size; i++) {
+      const o = j * size + i;
+      const x = -half + (i + 0.5) * M;
+      const h = H[o];
+      tint(h, c);
+      let r = c[0], g = c[1], b = c[2];
+
+      if (!PAD[o]) {
+        // RELIEF, lit from the NORTH-WEST — as every chart ever drawn is, because the eye reads a
+        // lit slope as raised and a dark one as sunk, and light it from the south-east and every
+        // canyon in the county comes out as a ridge. Sun from NW ⇒ ground is lit where it rises
+        // toward the north-west, i.e. where dh/dx + dh/dz > 0 (north is −Z).
+        const i0 = i > 0 ? o - 1 : o, i1 = i < size - 1 ? o + 1 : o;
+        const j0 = j > 0 ? o - size : o, j1 = j < size - 1 ? o + size : o;
+        const hx = (H[i1] - H[i0]) / (2 * M);
+        const hz = (H[j1] - H[j0]) / (2 * M);
+        // tanh, not a linear ramp: Dustwater's plain slopes by centimetres per metre and its mesas
+        // by whole metres. A linear shade tuned to the mesas leaves the plain dead flat white; one
+        // tuned to the plain clips the mesas to solid black. The knee (×5) gives the flats real
+        // modelling and lets the buttes ride the shoulder instead of blowing out.
+        const s = Math.tanh((hx + hz) * 5);
+        // ASYMMETRIC: the shadow side gets more than the lit side. A symmetric shade on ground this
+        // pale drives every sunlit slope to white paper, and a white blob with white highlights is
+        // the exact "washed-out" chart this replaced — the modelling has to come from the SHADOWS.
+        const k = 1 + s * (s > 0 ? 0.17 : 0.34);
+        r *= k; g *= k; b *= k;
+
+        // CONTOURS. A band edge = a line. Compared against the RIGHT and DOWN neighbours only, so
+        // each line is drawn once and lands on the uphill side, which is what a pen does.
+        const band = Math.floor(h / CONTOUR);
+        if (!PAD[i1] && !PAD[j1] && (band !== Math.floor(H[i1] / CONTOUR) || band !== Math.floor(H[j1] / CONTOUR))) {
+          const index = band % INDEX_EVERY === 0;
+          const t = index ? 0.52 : 0.26;                       // index contours heavier, as on a real sheet
+          r = lerp(r, 92, t); g = lerp(g, 64, t); b = lerp(b, 38, t);
+        }
+      }
+
+      // THE ROADS. Not lines drawn on top — sampled from the same roadDistance the TERRAIN paints
+      // its dirt with, so the chart's road is where the road IS, to the metre. The graded corridor
+      // is ~±10 m, so this is the width you would actually ride on.
+      const rd = roadDistance(x, z);
+      if (rd < 11) {
+        const t = smoothstep(11, 4, rd) * 0.8;
+        r = lerp(r, 176, t); g = lerp(g, 143, t); b = lerp(b, 95, t);      // pale graded dirt
+      }
+
+      // PAPER GRAIN. A deterministic hash, not Math.random: the chart is rebuilt on every boot and
+      // a map whose specks move between sessions reads as noise, not as paper.
+      let hs = (i * 374761393 + j * 668265263) | 0;
+      hs = (hs ^ (hs >>> 13)) * 1274126177;
+      const n = (((hs ^ (hs >>> 16)) >>> 0) / 4294967295 - 0.5) * 13;
+      r += n; g += n; b += n * 0.8;
+
+      const q = o * 4;
+      px[q] = clamp(r, 0, 255);
+      px[q + 1] = clamp(g, 0, 255);
+      px[q + 2] = clamp(b, 0, 255);
+      px[q + 3] = 255;
+    }
+  }
+  ctx.putImageData(img, 0, 0);
+
+  // 3) THE PEN WORK, over the top.
+  ctx.lineJoin = ctx.lineCap = 'round';
+  const K = size / 1200;                                       // every width below is drawn at 1200 and scaled
+
+  // THE GRATICULE — a survey grid every 200 m, faint. It is what tells you, at a glance, that the
+  // county is 2 km across; without it the flats have no scale at all.
+  ctx.strokeStyle = 'rgba(92,70,44,0.13)';
+  ctx.lineWidth = 1 * K;
+  for (let v = -1000; v <= 1000; v += 200) {
+    ctx.beginPath(); ctx.moveTo(w2p(v), 0); ctx.lineTo(w2p(v), size); ctx.stroke();
+    ctx.beginPath(); ctx.moveTo(0, w2p(v)); ctx.lineTo(size, w2p(v)); ctx.stroke();
+  }
+
+  // THE CREEK — the county's only water, away north. Drawn from RIVERS, so it runs in its own
+  // channel: a pale wash for the banks, then the water.
+  for (const R of RIVERS) {
+    const trace = () => {
+      ctx.beginPath();
+      R.pts.forEach((q, i) => (i ? ctx.lineTo(w2p(q.x), w2p(q.z)) : ctx.moveTo(w2p(q.x), w2p(q.z))));
+      ctx.stroke();
+    };
+    ctx.strokeStyle = 'rgba(196,186,150,0.75)'; ctx.lineWidth = Math.max(7, (R.w * 2.4) / M) * K; trace();   // the dry banks
+    ctx.strokeStyle = 'rgba(104,132,132,0.85)'; ctx.lineWidth = Math.max(2.6, R.w / M) * K; trace();         // the water
+  }
+
+  // THE LAKES — the same two inks as the creek: a bank ring, then the water as a filled disc.
+  // LAKES is empty in Dustwater, so this prints nothing today — the chart is simply ready for
+  // the day the table gains a row (drawn before the road ink, like the creek, so roads print
+  // over water edges consistently).
+  // Drawn to the terrain's OWN wavy shoreline, NOT a perfect ctx.arc — a circle on the map when the world's
+  // shore wanders was the "why are the lakes circular" tell. Same fbm field + params + amplitude as the
+  // carve (terrainData rawHeight: d = √ld2 + fbm(x+L.x·7.3, z−L.z·5.1,2,2,.5,.06)·L.r·0.26), so the shore on
+  // the map is the shore you walk up to. (The old rClip disc was ~1.3× the real shore AND perfectly round.)
+  for (const Lk of LAKES) {
+    const N = 72;
+    ctx.beginPath();
+    for (let i = 0; i <= N; i++) {
+      const th = (i / N) * Math.PI * 2, cx = Math.cos(th), cz = Math.sin(th);
+      const sx = Lk.x + cx * Lk.r, sz = Lk.z + cz * Lk.r;                                // a point on the nominal ring
+      const wob = fbm(sx + Lk.x * 7.3, sz - Lk.z * 5.1, 2, 2, 0.5, 0.06) * Lk.r * 0.26;  // the carve's shore wobble
+      const rr = Lk.r - wob;                                                             // shoreline radius at this bearing
+      const px = w2p(Lk.x + cx * rr), pz = w2p(Lk.z + cz * rr);
+      i ? ctx.lineTo(px, pz) : ctx.moveTo(px, pz);
+    }
+    ctx.closePath();
+    ctx.strokeStyle = 'rgba(196,186,150,0.75)'; ctx.lineWidth = Math.max(7, 9.6 / M) * K; ctx.stroke(); // the dry banks
+    ctx.fillStyle = 'rgba(104,132,132,0.85)'; ctx.fill();                                               // the water
+  }
+
+  // THE ROAD CENTRELINES. The dirt is already painted underneath; this is the line the coaches
+  // steer by, and on a chart you want to be able to trace a road with your finger across ground
+  // where the dirt has run thin.
+  ctx.strokeStyle = 'rgba(78,56,32,0.62)';
+  ctx.lineWidth = 1.6 * K;
+  for (const road of ROADS) {
+    ctx.beginPath();
+    road.forEach((q, i) => (i ? ctx.lineTo(w2p(q.x), w2p(q.z)) : ctx.moveTo(w2p(q.x), w2p(q.z))));
+    ctx.stroke();
+  }
+
+  // THE RAILROAD. Drawn the way a railroad is drawn on a survey sheet — a black line with cross
+  // ties hatched across it — because on a chart a rail line must never be mistaken for a road, and
+  // the county has both running the same way for kilometres. Two kilometres of line, a spur to the
+  // quarry, and it was on none of the chart at all: the trains ran across a map that did not know
+  // they existed.
+  for (const [name, path] of Object.entries(RAIL_PATHS ?? {})) {
+    if (!path?.length) continue;
+    ctx.strokeStyle = 'rgba(30,26,22,0.78)';
+    ctx.lineWidth = 2.2 * K;
+    ctx.beginPath();
+    path.forEach((q, i) => (i ? ctx.lineTo(w2p(q.x), w2p(q.z)) : ctx.moveTo(w2p(q.x), w2p(q.z))));
+    ctx.stroke();
+    // the ties: a short tick square to the line, every 40 m of it — enough to read as track, few
+    // enough not to turn a 2 km line into a smear of ink
+    ctx.lineWidth = 1.1 * K;
+    const TIE_EVERY = 20;                       // the survey publishes a point every 2 m
+    const TIE_HALF = 2.6 * K;
+    for (let i = TIE_EVERY; i < path.length - 1; i += TIE_EVERY) {
+      const a = path[i - 1], b = path[i + 1];
+      const dx = w2p(b.x) - w2p(a.x), dz = w2p(b.z) - w2p(a.z);
+      const l = Math.hypot(dx, dz) || 1;
+      const nx = -dz / l, nz = dx / l;           // square to the rails
+      const px = w2p(path[i].x), pz = w2p(path[i].z);
+      ctx.beginPath();
+      ctx.moveTo(px - nx * TIE_HALF, pz - nz * TIE_HALF);
+      ctx.lineTo(px + nx * TIE_HALF, pz + nz * TIE_HALF);
+      ctx.stroke();
+    }
+  }
+
+  // AGE. A warm vignette and a burnt edge — the sheet has been in a saddlebag. Kept mild: the
+  // corners of this map are real country (the mesas), not decoration to be smoked out.
+  const vg = ctx.createRadialGradient(size / 2, size / 2, size * 0.34, size / 2, size / 2, size * 0.74);
+  vg.addColorStop(0, 'rgba(0,0,0,0)');
+  vg.addColorStop(1, 'rgba(74,48,20,0.30)');
+  ctx.fillStyle = vg;
+  ctx.fillRect(0, 0, size, size);
+  ctx.strokeStyle = 'rgba(58,38,16,0.5)';
+  ctx.lineWidth = 10 * K;
+  ctx.strokeRect(5 * K, 5 * K, size - 10 * K, size - 10 * K);   // the sheet's darkened border
+
+  return cv;
+}
+
+// world metres → a fraction across the chart (0..1) — the one conversion every consumer needs
+export const w2f = (v) => v / WORLD_SIZE + 0.5;

package/src/ui/deathScreen.js

@@ -0,0 +1,130 @@
+// DEATH SCREEN — laid out like the Synty "Fantasy Menus" reference Nick keeps showing, in our western
+// palette. The frozen game scene stays visible washed RED; a FULL-WIDTH banner band crosses the middle
+// (soft red, edges fading out); the generated longhorn-skull emblem sits FAINT and CENTRED BEHIND the
+// text; "YOU DIED" is silver-metallic in the band; a gold chevron divider under it; then the choices as
+// a small, tight, CENTRED list of icon+label rows — press the shown pad button (PS ✕/□/○, Xbox A/X/B)
+// or click. ui.deathOpen pauses the world + freezes the player.
+import { padMode, buttonCanvas } from './menuHints.js';
+
+const FONT = "Copperplate,'Copperplate Gothic Bold','Palatino','Book Antiqua',Georgia,serif";
+const UI = '/assets/ui/death';
+const KEYNAME = { cross: '↵', square: 'R', circle: 'Esc' };
+const keyCss = 'display:inline-flex;align-items:center;justify-content:center;min-width:30px;height:24px;padding:0 7px;border-radius:5px;background:#efe6da;color:#241a10;font-weight:700;font-size:12px;flex:none;box-sizing:border-box;';
+// gold rule broken by two downward chevrons near the centre (the kit's divider)
+const DIVIDER_SVG = `<svg width="430" height="20" viewBox="0 0 430 20" fill="none" stroke="#c9a84e" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
+  <line x1="6" y1="9" x2="188" y2="9"/><path d="M196 4 L205 13 L214 4"/><path d="M216 4 L225 13 L234 4"/><line x1="242" y1="9" x2="424" y2="9"/>
+  <circle cx="6" cy="9" r="1.5" fill="#c9a84e"/><circle cx="424" cy="9" r="1.5" fill="#c9a84e"/></svg>`;
+
+function el(tag, css, text) {
+  const e = document.createElement(tag);
+  if (css) e.style.cssText = css;
+  if (text != null) e.textContent = text;
+  return e;
+}
+
+// button-prompt badge for face button `btn`: generated PS/Xbox icon when a pad is up, else a key pill.
+function paintBadge(holder, btn, mode) {
+  holder.textContent = '';
+  if (mode === 'ps' || mode === 'xbox') holder.appendChild(buttonCanvas(btn, mode, 22));
+  else holder.appendChild(el('span', keyCss, KEYNAME[btn]));
+}
+
+export function showDeathScreen(opts = {}) {
+  const root = el('div', 'position:fixed;inset:0;z-index:200;overflow:hidden;'
+    + `font-family:${FONT};`
+    // SOLID dark letterbox bars top & bottom (hide the HUD), scene showing through washed-red in the middle
+    + 'background:linear-gradient(180deg, #0a0302 0%, #0a0302 13%, rgba(96,13,10,0.5) 30%, rgba(96,13,10,0.5) 70%, #0a0302 87%, #0a0302 100%);');
+  document.body.appendChild(root);
+
+  // full-width banner band across the middle, soft red with edges fading out
+  const band = el('div', 'position:absolute;left:0;right:0;top:50%;transform:translateY(-50%);height:44vh;display:flex;flex-direction:column;align-items:center;justify-content:center;'
+    + 'background:linear-gradient(180deg, rgba(122,18,14,0) 0%, rgba(122,18,14,0.4) 18%, rgba(122,18,14,0.5) 50%, rgba(122,18,14,0.4) 82%, rgba(122,18,14,0) 100%);'
+    + 'border-top:1px solid rgba(210,80,60,0.14);border-bottom:1px solid rgba(210,80,60,0.14);');
+  root.appendChild(band);
+
+  // the emblem — CENTRED, FAINT, BEHIND the text; reddened so it reads as part of the band. Its black
+  // is keyed out at runtime (the art is on black) so it doesn't sit in a box.
+  const emblem = el('canvas', 'position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);width:min(820px,90vw);z-index:1;pointer-events:none;'
+    + 'opacity:0.5;filter:brightness(0.72) sepia(0.7) saturate(3) hue-rotate(-24deg);');
+  { const img = new Image();
+    img.onload = () => {
+      emblem.width = img.naturalWidth; emblem.height = img.naturalHeight;
+      const ctx = emblem.getContext('2d'); ctx.drawImage(img, 0, 0);
+      try {
+        const d = ctx.getImageData(0, 0, emblem.width, emblem.height), px = d.data;
+        for (let i = 0; i < px.length; i += 4) { const m = Math.max(px[i], px[i + 1], px[i + 2]); if (m < 30) px[i + 3] = 0; else if (m < 82) px[i + 3] = Math.round((m - 30) / 52 * 255); }
+        ctx.putImageData(d, 0, 0);
+      } catch (e) { /* tainted — leave as drawn */ }
+    };
+    img.onerror = () => { emblem.style.display = 'none'; };
+    img.src = `${UI}/banner.png`;
+  }
+  band.appendChild(emblem);
+
+  // content over the emblem
+  const content = el('div', 'position:relative;z-index:2;display:flex;flex-direction:column;align-items:center;');
+  band.appendChild(content);
+
+  content.appendChild(el('div',
+    'color:#ddd7cc;font-size:min(8vw,76px);letter-spacing:min(1.4vw,10px);font-weight:700;line-height:1;'
+    + 'text-shadow:0 1px 0 rgba(255,255,255,0.28),0 2px 0 #5a1712,0 3px 3px rgba(0,0,0,0.6),0 0 30px rgba(0,0,0,0.45);', 'YOU DIED'));
+  const dv = el('div', 'margin:14px 0 15px;line-height:0;'); dv.innerHTML = DIVIDER_SVG; content.appendChild(dv);
+
+  // options — small, tight, centred: [icon] label
+  const menu = el('div', 'display:flex;flex-direction:column;align-items:center;gap:4px;');
+  content.appendChild(menu);
+
+  const rows = [];
+  const addRow = (label, btn, fn) => {
+    const row = el('button', 'display:flex;align-items:center;gap:11px;padding:5px 16px;border:none;background:none;border-radius:6px;cursor:pointer;'
+      + 'color:#e6dcc4;font-family:inherit;font-size:15px;letter-spacing:2px;font-weight:600;transition:color .12s,background .12s;');
+    const badge = el('span', 'display:inline-flex;align-items:center;'); row.appendChild(badge);
+    row.appendChild(el('span', '', label));
+    const on = () => { row.style.color = '#fff8ec'; row.style.background = 'rgba(150,26,20,0.35)'; };
+    const off = () => { row.style.color = '#e6dcc4'; row.style.background = 'none'; };
+    off();
+    row.onclick = () => act(fn);
+    row.addEventListener('mouseenter', on); row.addEventListener('mouseleave', off);
+    menu.appendChild(row);
+    rows.push({ btn, fn, el: row, badge });
+  };
+  if (opts.hasSave) addRow('LOAD LAST SAVE', 'cross', opts.onLoad);
+  addRow('WAKE AT THE WELL', opts.hasSave ? 'square' : 'cross', opts.onRevive);
+  addRow('QUIT TO TITLE', 'circle', opts.onQuit);
+
+  let raf = 0, closed = false, first = true, prev = {}, lastMode = false;
+  const close = () => { if (closed) return; closed = true; cancelAnimationFrame(raf); window.removeEventListener('keydown', onKey); root.remove(); };
+  const act = (fn) => { close(); fn?.(); };
+  const fire = (btn) => { const r = rows.find((x) => x.btn === btn); if (r) act(r.fn); };
+  const repaintBadges = () => { const m = padMode(); rows.forEach((r) => paintBadge(r.badge, r.btn, m)); return m; };
+  lastMode = repaintBadges();
+
+  const onKey = (e) => {
+    switch (e.code) {
+      case 'Enter': case 'Space': case 'NumpadEnter': fire(rows.some((r) => r.btn === 'cross') ? 'cross' : rows[0].btn); e.preventDefault(); break;
+      case 'KeyR': fire('square'); break;
+      case 'Escape': case 'Backspace': fire('circle'); break;
+      default: return;
+    }
+  };
+  window.addEventListener('keydown', onKey);
+
+  const poll = () => {
+    if (closed) return;
+    const m = padMode();
+    if (m !== lastMode) lastMode = repaintBadges();
+    const pads = navigator.getGamepads ? navigator.getGamepads() : null;
+    let gp = null; if (pads) for (const p of pads) if (p && p.connected) { gp = p; break; }
+    if (gp) {
+      const b = (i) => !!gp.buttons[i]?.pressed;
+      const st = { cross: b(0), circle: b(1), square: b(2) };
+      const edge = (k) => st[k] && !prev[k];
+      if (first) first = false;   // adopt held state — the Cross that was firing when you died mustn't confirm
+      else { if (edge('cross')) fire('cross'); if (edge('square')) fire('square'); if (edge('circle')) fire('circle'); }
+      prev = st;
+    }
+    raf = requestAnimationFrame(poll);
+  };
+  raf = requestAnimationFrame(poll);
+  return { close };
+}