sindicate 0.12.0 → 0.15.0

package/src/world/bridgeSplice.js

@@ -0,0 +1,176 @@
+// THE BRIDGE SPLICER (world splits, step 3) — every road x river crossing becomes a deck.
+// Moved verbatim from the games (their copies were byte-identical except two spacing
+// numbers, parameterized below): find crossings, drop hits an existing deck already
+// carries, dedupe widest-first, then splice the road STRAIGHT across the channel on a
+// perpendicular chord — clear-bank anchors, collinear approach legs, rejoin points walked
+// along the old road, chord mids at chordStep, long legs re-densified under legGate. Runs
+// to a FIXED POINT (a splice can create a new crossing), then pushes any surviving road
+// vertex out of the water to the near bank.
+//
+// MUTATES `roads` IN PLACE — call it before anything snapshots them (chunk indices, road
+// benches, registrations: the same import-order law both counties already live by).
+// Returns the BRIDGE_SPOTS array: { ax, az, bx, bz, x, z, w } chord anchors + centre +
+// local channel half-width; the games' bridge builders and deck holds read it from there.
+//
+// chordStep/legGate: western runs 28/30 (the travellers' ≤30 m route-leg law — see its
+// verify-travellers note); fable runs 36/40 (its minimap's 74 m window). Inserted points
+// are collinear on the chord, so roadDistance, the paint and the terrain are bit-identical
+// under either spacing — only where the walkers get their waypoints changes.
+// Headless by law: no imports at all.
+
+function segInt(a, b, c, d) { // 2D segment intersection → {x,z,t (road param),u (river param)}
+  const rx = b.x - a.x, rz = b.z - a.z, sx = d.x - c.x, sz = d.z - c.z;
+  const denom = rx * sz - rz * sx;
+  if (Math.abs(denom) < 1e-9) return null;
+  const t = ((c.x - a.x) * sz - (c.z - a.z) * sx) / denom;
+  const u = ((c.x - a.x) * rz - (c.z - a.z) * rx) / denom;
+  if (t < 0 || t > 1 || u < 0 || u > 1) return null;
+  return { x: a.x + rx * t, z: a.z + rz * t, t, u };
+}
+
+function walkRoad(road, i, t, dist) { // walk `dist` m along the polyline → {x,z,seg,clamped}
+  let seg = i, tt = t, remaining = Math.abs(dist), clamped = false;
+  const dir = Math.sign(dist) || 1;
+  while (remaining > 0) {
+    const a = road[seg], b = road[seg + 1];
+    if (!a || !b) break;
+    const len = Math.hypot(b.x - a.x, b.z - a.z) || 1e-6;
+    const along = dir > 0 ? (1 - tt) * len : tt * len;
+    if (along >= remaining) { tt += dir * (remaining / len); break; }
+    remaining -= along;
+    seg += dir; tt = dir > 0 ? 0 : 1;
+    if (seg < 0 || seg >= road.length - 1) { seg = Math.max(0, Math.min(road.length - 2, seg)); tt = dir > 0 ? 1 : 0; clamped = true; break; }
+  }
+  const a = road[seg], b = road[seg + 1];
+  return { x: a.x + (b.x - a.x) * tt, z: a.z + (b.z - a.z) * tt, seg, clamped };
+}
+
+export function spliceBridges(roads, rivers, { chordStep = 28, legGate = 30, approach = 14, margin = 5, pushClear = 6 } = {}) {
+  // metres of dry margin OUTSIDE the nearest river channel (negative = inside the water).
+  const riverClearance = (x, z) => {
+    let best = Infinity;
+    for (const R of rivers) {
+      for (let i = 0; i < R.pts.length - 1; i++) {
+        const a = R.pts[i], b = R.pts[i + 1];
+        const dx = b.x - a.x, dz = b.z - a.z;
+        const len2 = dx * dx + dz * dz || 1e-9;
+        let t = ((x - a.x) * dx + (z - a.z) * dz) / len2;
+        t = t < 0 ? 0 : t > 1 ? 1 : t;
+        const d = Math.hypot(x - (a.x + dx * t), z - (a.z + dz * t));
+        const ww = R.ww[i] + (R.ww[Math.min(i + 1, R.ww.length - 1)] - R.ww[i]) * t;
+        best = Math.min(best, d - ww);
+      }
+    }
+    return best;
+  };
+
+  const BRIDGE_SPOTS = [];
+  const deckVerts = new Set();
+  for (let pass = 0; pass < 4; pass++) {
+    const hits = [];
+    roads.forEach((road, ri) => {
+      for (let i = 0; i < road.length - 1; i++)
+        for (const R of rivers)
+          for (let j = 0; j < R.pts.length - 1; j++) {
+            const h = segInt(road[i], road[i + 1], R.pts[j], R.pts[j + 1]);
+            if (h) hits.push({ ...h, ri, i, w: R.ww[j] + (R.ww[Math.min(j + 1, R.ww.length - 1)] - R.ww[j]) * h.u });
+          }
+    });
+    const carried = (h) => BRIDGE_SPOTS.some((s) => {
+      const dx = s.bx - s.ax, dz = s.bz - s.az, l2 = dx * dx + dz * dz || 1e-9;
+      let t = ((h.x - s.ax) * dx + (h.z - s.az) * dz) / l2; t = t < 0 ? 0 : t > 1 ? 1 : t;
+      return Math.hypot(h.x - (s.ax + dx * t), h.z - (s.az + dz * t)) < 8;
+    });
+    hits.sort((a, b) => b.w - a.w);
+    const keep = [];
+    for (const h of hits) if (!carried(h) && !keep.some((k) => Math.hypot(k.x - h.x, k.z - h.z) < Math.max(24, k.w * 1.6))) keep.push(h);
+    if (!keep.length) break; // fixed point — every crossing is bridged
+    keep.sort((a, b) => (b.ri - a.ri) || (b.i - a.i));
+    const splicedFrom = new Map();
+    for (const h of keep) {
+      const road = roads[h.ri];
+      const bound = splicedFrom.get(h.ri) ?? road.length;
+      if (h.i + 1 >= bound) continue;
+      let rv = { x: 1, z: 0 }, bd = Infinity;
+      for (const R of rivers) for (let i = 0; i < R.pts.length - 1; i++) {
+        const a = R.pts[i], b = R.pts[i + 1];
+        const dx = b.x - a.x, dz = b.z - a.z, len2 = dx * dx + dz * dz || 1e-9;
+        let t = ((h.x - a.x) * dx + (h.z - a.z) * dz) / len2; t = t < 0 ? 0 : t > 1 ? 1 : t;
+        const d = Math.hypot(h.x - (a.x + dx * t), h.z - (a.z + dz * t));
+        if (d < bd) { bd = d; const l = Math.hypot(dx, dz) || 1e-9; rv = { x: dx / l, z: dz / l }; }
+      }
+      let px = -rv.z, pz = rv.x;
+      const rd = { x: road[h.i + 1].x - road[h.i].x, z: road[h.i + 1].z - road[h.i].z };
+      if (px * rd.x + pz * rd.z < 0) { px = -px; pz = -pz; }
+      const clearOut = (sgn) => {
+        const cap = h.w + (h.w > 7 ? 80 : 24);
+        let d = h.w + margin;
+        while (d < cap && riverClearance(h.x + sgn * px * d, h.z + sgn * pz * d) < margin) d += 2;
+        return d < cap ? d : h.w + margin;
+      };
+      const dA = clearOut(-1), dB = clearOut(1);
+      const iA = { x: h.x - px * dA, z: h.z - pz * dA }, iB = { x: h.x + px * dB, z: h.z + pz * dB };
+      const aA = { x: iA.x - px * approach, z: iA.z - pz * approach };
+      const aB = { x: iB.x + px * approach, z: iB.z + pz * approach };
+      const rejoin = (sgn, ref) => {
+        const base = (sgn < 0 ? dA : dB) + approach + 12;
+        let P = null;
+        for (let d = base; d <= base + 60; d += 4) {
+          P = walkRoad(road, h.i, h.t, sgn * d);
+          if (P.clamped || ((P.x - ref.x) * px + (P.z - ref.z) * pz) * sgn >= 4) return P;
+        }
+        return P;
+      };
+      const A = rejoin(-1, aA), B = rejoin(1, aB);
+      if (A.clamped && B.clamped) continue;
+      let to = B.clamped ? road.length - 1 : B.seg;
+      const from = A.clamped ? 0 : A.seg + 1;
+      const joinB = to >= bound;
+      if (joinB) to = bound - 1;
+      if (to < from - 1) continue;
+      const start = A.clamped ? iA : aA, end = B.clamped ? iB : aB;
+      const ins = [];
+      if (!A.clamped && Math.hypot(A.x - start.x, A.z - start.z) > 0.01) ins.push({ x: A.x, z: A.z });
+      ins.push(start);
+      const runL = Math.hypot(end.x - start.x, end.z - start.z);
+      for (let d = chordStep; d < runL - 4; d += chordStep) {
+        const mid = { x: start.x + px * d, z: start.z + pz * d };
+        ins.push(mid); deckVerts.add(mid);
+      }
+      ins.push(end);
+      if (!B.clamped && !joinB && Math.hypot(B.x - end.x, B.z - end.z) > 0.01) ins.push({ x: B.x, z: B.z });
+      for (let k = ins.length - 1; k > 0; k--) {
+        const p = ins[k - 1], q = ins[k];
+        const L = Math.hypot(q.x - p.x, q.z - p.z);
+        if (L > legGate) {
+          const n = Math.ceil(L / chordStep), legMids = [];
+          for (let s = 1; s < n; s++) legMids.push({ x: p.x + (q.x - p.x) * s / n, z: p.z + (q.z - p.z) * s / n });
+          ins.splice(k, 0, ...legMids);
+        }
+      }
+      road.splice(from, to - from + 1, ...ins);
+      splicedFrom.set(h.ri, from);
+      deckVerts.add(start); deckVerts.add(end);
+      BRIDGE_SPOTS.push({ ax: iA.x, az: iA.z, bx: iB.x, bz: iB.z, x: (iA.x + iB.x) / 2, z: (iA.z + iB.z) / 2, w: h.w });
+    }
+  }
+  // Final pass: any road vertex still INSIDE a channel is pushed to the near bank.
+  for (const road of roads) for (const v of road) {
+    if (deckVerts.has(v)) continue;
+    let best = Infinity, nx = 0, nz = 0;
+    for (const R of rivers) for (let i = 0; i < R.pts.length - 1; i++) {
+      const a = R.pts[i], b = R.pts[i + 1];
+      const dx = b.x - a.x, dz = b.z - a.z, len2 = dx * dx + dz * dz || 1e-9;
+      let t = ((v.x - a.x) * dx + (v.z - a.z) * dz) / len2; t = t < 0 ? 0 : t > 1 ? 1 : t;
+      const cxp = a.x + dx * t, czp = a.z + dz * t;
+      const d = Math.hypot(v.x - cxp, v.z - czp);
+      const ww = R.ww[i] + (R.ww[Math.min(i + 1, R.ww.length - 1)] - R.ww[i]) * t;
+      if (d - ww < best) { best = d - ww; nx = cxp; nz = czp; }
+    }
+    if (best >= pushClear) continue;
+    const d = Math.hypot(v.x - nx, v.z - nz) || 1e-6;
+    const k = (pushClear - best) / d;
+    v.x += (v.x - nx) * k; v.z += (v.z - nz) * k;
+  }
+  return BRIDGE_SPOTS;
+}

package/src/world/design.js

@@ -0,0 +1,72 @@
+// THE DESIGN STAMPER (designer v3) — renders a World Designer layout (designs/<name>.json,
+// authored in /designer.html by hand or by an MCP-driven session) into the live world.
+// MACHINE-WRITTEN LAYOUTS ARE JSON: { name, prefabs: [{ file, dir, x, y?, z, ry?, s?, tex? }],
+// roads: [[{x,z}, ...], ...] }.
+//
+// Same shape as the kit stamper's prop path: prefabs batch per (file|tex) into ONE
+// InstancedMesh each, on the shared townMaterial pipeline (one material per atlas,
+// lamp-lit). Placement seats on the game's ground through the heightAt option unless the
+// entry pins its own y.
+//
+// COLLISION IS THE BAKE'S BUSINESS: batches are named `scatter:` (solid — the world BVH
+// bake picks them up by name) or `scatterDeco:` (walk-through) via opts.solid. Stamping
+// AFTER world.build's bake gives no collision until the next bake — fine for a dev-flag
+// preview; the production path stamps designs before the bake, exactly like the towns.
+//
+// ROADS: not rendered here. A designer road is a ROUTE, and routes belong to the game's
+// terrain survey (road networks bench the ground, paint the surface and re-cook) — the
+// designer's road polylines feed that pipeline game-side; a painted-on decal would lie
+// about where the carriageway really is.
+import * as THREE from 'three/webgpu';
+import { loadModel } from '../core/assets.js';
+import { flattenToGeometry } from './scatter.js';
+import { townMaterial } from './kit.js';
+
+export async function buildDesign(scene, design, { heightAt = () => 0, solid = true, defaultTex = null } = {}) {
+  const byFile = new Map();   // `${dir}/${file}|${tex}` -> { url, tex, mats: [] }
+  const _p = new THREE.Vector3(), _q = new THREE.Quaternion(), _s = new THREE.Vector3();
+  const _up = new THREE.Vector3(0, 1, 0);
+  for (const e of design.prefabs ?? []) {
+    const bare = e.file.replace(/\.(fbx|glb)$/i, '');
+    const ext = e.ext ?? (/\.glb$/i.test(e.file) ? 'glb' : 'fbx');
+    const url = `${e.dir}/${bare}`;
+    e._url = `${url}.${ext}`;
+    const tex = e.tex ?? defaultTex;
+    const key = `${e._url}|${tex}`;
+    if (!byFile.has(key)) byFile.set(key, { url: e._url, tex, mats: [] });
+    byFile.get(key).mats.push(new THREE.Matrix4().compose(
+      _p.set(e.x, e.y ?? heightAt(e.x, e.z), e.z),
+      _q.setFromAxisAngle(_up, e.ry ?? 0),
+      _s.setScalar(e.s ?? 1),
+    ));
+  }
+  const meshes = [];
+  let count = 0, failed = 0;
+  for (const { url, tex, mats } of byFile.values()) {
+    try {
+      const master = await loadModel(url, tex ? { texture: tex } : {});
+      const flat = flattenToGeometry(master);
+      if (!flat) { failed++; continue; }
+      // textured prefabs ride the shared town pipeline (one material per atlas, lamp-lit);
+      // an untextured one gets a plain slate rather than crashing the whole batch pass
+      const mat = tex ? await townMaterial(tex, url) : new THREE.MeshStandardMaterial({ color: 0x9a938a, roughness: 0.9 });
+      const mesh = new THREE.InstancedMesh(flat.geometry, mat, mats.length);
+      mats.forEach((m, i) => mesh.setMatrixAt(i, m));
+      mesh.instanceMatrix.needsUpdate = true;
+      mesh.castShadow = mats.length < 12;
+      mesh.receiveShadow = true;
+      const file = url.split('/').pop();
+      mesh.name = `${solid ? 'scatter' : 'scatterDeco'}:${file}`;
+      mesh.matrixAutoUpdate = false;
+      mesh.updateMatrix();
+      scene.add(mesh);
+      meshes.push(mesh);
+      count += mats.length;
+    } catch (e) {
+      failed++;
+      console.warn(`[design] prefab batch ${url} failed`, e?.message ?? e);
+    }
+  }
+  console.log(`[design] '${design.name ?? 'unnamed'}': ${count} prefabs in ${meshes.length} batches${failed ? ` (${failed} files failed)` : ''}${design.roads?.length ? ` · ${design.roads.length} road route(s) carried for the survey` : ''}`);
+  return { meshes, count, roads: design.roads ?? [] };
+}

package/src/world/geo.js

@@ -0,0 +1,53 @@
+// THE GEO TOOLKIT (world splits, step 1) — the terrain-math primitives both games carried
+// as byte-identical private copies: the fbm/ridged noise kit (fixed ImprovedNoise
+// permutation → deterministic, one shared instance is safe), the smoothstep/terrace
+// shapers, and the point-to-segment distance the polyline indices are built on.
+//
+// HEADLESS BY LAW: this module imports ONLY three/addons math — never three/webgpu —
+// because the games' terrainData files (its consumers) run in Node for offline solvers,
+// verify scripts and height-equivalence probes. Keep it that way.
+//
+// EQUIVALENCE CONTRACT: these bodies moved verbatim from western/fable terrainData.js.
+// Any numeric change here changes both counties' ground — prove a refactor with the
+// height-grid probe (441 samples per game) before shipping it.
+import { ImprovedNoise } from 'three/addons/math/ImprovedNoise.js';
+
+const noise = new ImprovedNoise();
+
+export function fbm(x, z, octaves = 4, lacunarity = 2, gain = 0.5, scale = 0.01) {
+  let amp = 1, freq = scale, sum = 0, norm = 0;
+  for (let i = 0; i < octaves; i++) {
+    sum += amp * noise.noise(x * freq, z * freq, 7.31 + i * 13.7);
+    norm += amp; amp *= gain; freq *= lacunarity;
+  }
+  return sum / norm;
+}
+
+export const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
+export const lerp = (a, b, t) => a + (b - a) * t;
+export function smoothstep(a, b, t) { const x = clamp((t - a) / (b - a), 0, 1); return x * x * (3 - 2 * x); }
+
+// ~[0,1]: sharp crests, round valleys — mountain ranges and mesa fields
+export function ridged(x, z, octaves, lac, gain, scale) {
+  let amp = 0.5, freq = scale, sum = 0, norm = 0, prev = 1;
+  for (let i = 0; i < octaves; i++) {
+    let n = 1 - Math.abs(noise.noise(x * freq, z * freq, 41.7 + i * 7.3));
+    n *= n; n *= prev; sum += n * amp; norm += amp; prev = n; amp *= gain; freq *= lac;
+  }
+  return sum / norm;
+}
+
+// quantise to benches with a sharp riser — mesa walls, cliff bands
+export function terrace(h, step, sharp) {
+  const f = h / step, k = Math.floor(f), frac = f - k;
+  return (k + lerp(frac, smoothstep(0.5 - 0.5 * sharp, 0.5 + 0.5 * sharp, frac), sharp)) * step;
+}
+
+// distance from (px,pz) to segment a→b — the primitive under every polyline index
+export function segDist(px, pz, ax, az, bx, bz) {
+  const dx = bx - ax, dz = bz - az;
+  const len2 = dx * dx + dz * dz;
+  let t = len2 ? ((px - ax) * dx + (pz - az) * dz) / len2 : 0;
+  t = clamp(t, 0, 1);
+  return Math.hypot(px - (ax + dx * t), pz - (az + dz * t));
+}

package/src/world/heightfield.js

@@ -0,0 +1,146 @@
+// THE HEIGHTFIELD BUILDER (world splits, step 4) — the chunked terrain mesh + cook harness
+// both games carried byte-identically around their own paint and material:
+//
+//   · ONE height lattice (every vertex computed exactly once), chunk meshes aligned to it,
+//     normals from lattice CENTRAL DIFFERENCES so chunk borders cannot seam
+//   · THE TERRAIN COOK — the lattice fill is ~1.74M heightAt calls and the paint pass as
+//     many again, all deterministic: cooked to ONE self-writing bin
+//     [u32 hlen][JSON {ver,N} pad4][H f32 N²][sand u8 N²][paint u8 4/vert rgba-as-rgbs]
+//     fetched by NAME (the game bakes its content fingerprints into cookName, so stale
+//     bins 404 and re-cook), recorded back through the dev middleware on a cold boot
+//   · the SAND LATTICE (u8 N²) — the game's paint writes it, other systems (grass blade
+//     fields) query exactly what the ground shows; returned for the game's sandAt()
+//
+// The GAME supplies: heightAt, the cook name + ver, the node material, and makePaint —
+// a factory receiving { hAt, step, N, sandLattice } and returning the per-vertex painter
+// (x, z, h, li, lj, colors, sands, k), the exact signature both counties already use.
+import * as THREE from 'three/webgpu';
+
+export async function buildHeightfield({
+  worldSize, segments, chunkTarget = 360,
+  heightAt, cookName, cookVer,
+  material, makePaint,
+  saveRoute = '/__save-cookbin', cookRoute = '/assets/cook',
+}) {
+  const CHUNKS = Math.max(1, Math.round(worldSize / chunkTarget));
+  if (segments % CHUNKS !== 0) throw new Error(`segments ${segments} not divisible by ${CHUNKS} chunks`);
+  const CSEG = segments / CHUNKS;                  // segments per chunk side
+  const CSIZE = worldSize / CHUNKS;                // metres per chunk side
+  const STEP = worldSize / segments;               // lattice spacing
+  const N = segments + 1;                          // lattice verts per side
+
+  let cook = null;
+  try {
+    const r = await fetch(`${cookRoute}/${cookName}`);
+    if (r.ok) {
+      const buf = await r.arrayBuffer();
+      const hlen = new DataView(buf).getUint32(0, true);
+      const head = JSON.parse(new TextDecoder().decode(new Uint8Array(buf, 4, hlen)));
+      if (head.N === N) {
+        let o = 4 + hlen;
+        cook = { H: new Float32Array(buf.slice(o, o + N * N * 4)) };
+        o += N * N * 4;
+        cook.sand = new Uint8Array(buf.slice(o, o + N * N));
+        o += N * N;
+        cook.paint = new Uint8Array(buf.slice(o));
+        console.log(`[terrain] COOKED lattice+paint from ${cookName} — heightAt/paint compute skipped`);
+      }
+    }
+  } catch (e) { console.warn('[terrain] cook bin missing/unreadable — falling back to the SLOW compute path (first boot after a VER bump is expected; repeated boots are not)', e?.message ?? e); }
+
+  // ---- height lattice: every terrain vertex height, computed once ----
+  const H = cook ? cook.H : new Float32Array(N * N);
+  if (!cook) {
+    for (let j = 0; j < N; j++) {
+      const z = -worldSize / 2 + j * STEP;
+      for (let i = 0; i < N; i++) H[j * N + i] = heightAt(-worldSize / 2 + i * STEP, z);
+    }
+  }
+  const hAt = (i, j) => H[Math.min(N - 1, Math.max(0, j)) * N + Math.min(N - 1, Math.max(0, i))];
+  const sandLattice = cook ? cook.sand : new Uint8Array(N * N);
+  const paintVertex = cook ? null : makePaint({ hAt, step: STEP, N, sandLattice });
+
+  // ---- build the chunk grid ----
+  const group = new THREE.Group();
+  group.name = 'terrain';
+  let chunkIdx = 0, vertsPerChunk = 0;
+  const recChunks = cook ? null : [];
+  for (let cj = 0; cj < CHUNKS; cj++) {
+    for (let ci = 0; ci < CHUNKS; ci++) {
+      const geo = new THREE.PlaneGeometry(CSIZE, CSIZE, CSEG, CSEG);
+      geo.rotateX(-Math.PI / 2);
+      const cx = -worldSize / 2 + (ci + 0.5) * CSIZE;             // chunk centre (mesh position)
+      const cz = -worldSize / 2 + (cj + 0.5) * CSIZE;
+      const pos = geo.attributes.position;
+      const colors = new Float32Array(pos.count * 3);
+      const sands = new Float32Array(pos.count);
+      const normals = geo.attributes.normal;
+      vertsPerChunk = pos.count;
+      for (let k = 0; k < pos.count; k++) {
+        const x = pos.getX(k) + cx, z = pos.getZ(k) + cz;
+        // lattice indices — chunk grids align exactly to the global lattice
+        const li = Math.round((x + worldSize / 2) / STEP);
+        const lj = Math.round((z + worldSize / 2) / STEP);
+        const h = hAt(li, lj);
+        pos.setY(k, h);
+        // normal from lattice central differences — identical on both sides of
+        // a chunk border (computeVertexNormals would seam: edge verts lack
+        // neighbour faces from the adjacent chunk). Cheap H arithmetic — always live.
+        const nx = -(hAt(li + 1, lj) - hAt(li - 1, lj)) / (2 * STEP);
+        const nz = -(hAt(li, lj + 1) - hAt(li, lj - 1)) / (2 * STEP);
+        const inv = 1 / Math.hypot(nx, 1, nz);
+        normals.setXYZ(k, nx * inv, inv, nz * inv);
+        if (cook) {
+          // cooked paint: 4 bytes/vert (r,g,b,sand) in chunk build order
+          const po = (chunkIdx * pos.count + k) * 4;
+          colors[k * 3] = cook.paint[po] / 255;
+          colors[k * 3 + 1] = cook.paint[po + 1] / 255;
+          colors[k * 3 + 2] = cook.paint[po + 2] / 255;
+          sands[k] = cook.paint[po + 3] / 255;
+        } else {
+          paintVertex(x, z, h, li, lj, colors, sands, k);
+        }
+      }
+      geo.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+      geo.setAttribute('aSand', new THREE.BufferAttribute(sands, 1));
+      recChunks?.push({ colors, sands });
+      chunkIdx++;
+      const mesh = new THREE.Mesh(geo, material);
+      mesh.position.set(cx, 0, cz);
+      mesh.receiveShadow = true;
+      mesh.name = `terrain:${ci},${cj}`;
+      group.add(mesh);
+    }
+  }
+  console.log(`[terrain] ${CHUNKS}x${CHUNKS} chunks (${CSIZE}m, ${CSEG}x${CSEG} segs each) — frustum-culled${cook ? ' · cooked' : ''}`);
+
+  // record mode: persist lattice + paint for the next boot (dev middleware writes the file)
+  if (recChunks) {
+    try {
+      let head = JSON.stringify({ ver: cookVer, N });
+      while ((head.length + 4) % 4) head += ' '; // 4-byte-align the Float32 payload
+      const hb = new TextEncoder().encode(head);
+      const paint = new Uint8Array(chunkIdx * vertsPerChunk * 4);
+      recChunks.forEach(({ colors, sands }, cIdx) => {
+        for (let k = 0; k < sands.length; k++) {
+          const po = (cIdx * sands.length + k) * 4;
+          paint[po] = Math.min(255, Math.round(colors[k * 3] * 255));
+          paint[po + 1] = Math.min(255, Math.round(colors[k * 3 + 1] * 255));
+          paint[po + 2] = Math.min(255, Math.round(colors[k * 3 + 2] * 255));
+          paint[po + 3] = Math.min(255, Math.round(sands[k] * 255));
+        }
+      });
+      const out = new Uint8Array(4 + hb.length + H.byteLength + sandLattice.byteLength + paint.byteLength);
+      const dv = new DataView(out.buffer);
+      dv.setUint32(0, hb.length, true);
+      out.set(hb, 4);
+      let o = 4 + hb.length;
+      out.set(new Uint8Array(H.buffer), o); o += H.byteLength;
+      out.set(sandLattice, o); o += sandLattice.byteLength;
+      out.set(paint, o);
+      fetch(`${saveRoute}?name=${cookName}`, { method: 'POST', body: out });
+      console.log(`[terrain] cooked → ${cookName} (${(out.length / 1048576).toFixed(1)}MB)`);
+    } catch (e) { console.warn('[terrain] cook save failed', e); }
+  }
+  return { group, sandLattice, N, step: STEP, cooked: !!cook };
+}