sindicate 0.1.0

package/src/world/bvhWorker.js

@@ -0,0 +1,85 @@
+// Off-main-thread per-tile collision BVH builder.
+//
+// The tile streamer used to bake + merge + build a MeshBVH synchronously in
+// World.update() — ~30–80ms PER TILE, which is the constant town/exploration
+// stutter (the `world` phase in the freeze log). That work is pure geometry math
+// (no DOM, no renderer), so it runs here in a Web Worker instead.
+//
+// Protocol: main thread posts { id, parts } where each part is
+//   { positions:Float32Array, index:Uint16/32Array|null, matrices:Float32Array(count*16), count }
+// (positions/index are the source collider geometry; matrices are the WORLD
+// transforms of every instance). We bake every instance into one big position
+// buffer, build a MeshBVH, serialize it, and post { id, ok, serialized, position }
+// back with everything transferred (zero-copy). The main thread deserializes into
+// a real MeshBVH that still answers .shapecast()/.raycastFirst() — identical
+// collision, just built off the hot path. See collision.js buildBVHAsync.
+//
+// IMPORTANT: plain 'three' here, NOT 'three/webgpu' — the webgpu entry pulls in
+// renderer/DOM code that has no `document`/`window` in a worker. three-mesh-bvh is
+// pure math and worker-safe.
+import { BufferGeometry, BufferAttribute, Matrix4 } from 'three';
+import { MeshBVH } from 'three-mesh-bvh';
+
+const _m = new Matrix4();
+
+// Bake every instance of every part into ONE non-indexed, position-only buffer
+// (mirrors collision.js buildBVH), then build a BVH over it. Inlined matrix×point
+// math + a single preallocated array — no per-instance geometry allocations.
+function buildFromParts(parts) {
+  const bases = [];
+  let totalFloats = 0;
+  for (const p of parts) {
+    if (!p.positions || !p.count) continue;
+    let pos = p.positions;
+    if (p.index) {
+      const idx = p.index;
+      const out = new Float32Array(idx.length * 3);
+      for (let k = 0; k < idx.length; k++) {
+        const v = idx[k] * 3;
+        out[k * 3] = pos[v]; out[k * 3 + 1] = pos[v + 1]; out[k * 3 + 2] = pos[v + 2];
+      }
+      pos = out; // expanded to non-indexed
+    }
+    bases.push({ pos, count: p.count, matrices: p.matrices });
+    totalFloats += pos.length * p.count;
+  }
+  if (!totalFloats) return null;
+
+  const merged = new Float32Array(totalFloats);
+  let off = 0;
+  for (const b of bases) {
+    const pos = b.pos, vn = pos.length / 3;
+    for (let i = 0; i < b.count; i++) {
+      _m.fromArray(b.matrices, i * 16);
+      const e = _m.elements;
+      const e0 = e[0], e1 = e[1], e2 = e[2], e4 = e[4], e5 = e[5], e6 = e[6],
+        e8 = e[8], e9 = e[9], e10 = e[10], e12 = e[12], e13 = e[13], e14 = e[14];
+      for (let v = 0; v < vn; v++) {
+        const x = pos[v * 3], y = pos[v * 3 + 1], z = pos[v * 3 + 2];
+        merged[off++] = e0 * x + e4 * y + e8 * z + e12;
+        merged[off++] = e1 * x + e5 * y + e9 * z + e13;
+        merged[off++] = e2 * x + e6 * y + e10 * z + e14;
+      }
+    }
+  }
+
+  const geom = new BufferGeometry();
+  geom.setAttribute('position', new BufferAttribute(merged, 3));
+  const bvh = new MeshBVH(geom); // creates a sequential index internally
+  return { bvh, position: merged };
+}
+
+self.onmessage = (e) => {
+  const { id, parts } = e.data;
+  try {
+    const res = buildFromParts(parts);
+    if (!res) { self.postMessage({ id, ok: false, empty: true }); return; }
+    const serialized = MeshBVH.serialize(res.bvh, { cloneBuffers: false });
+    const transfer = [res.position.buffer, ...serialized.roots];
+    if (serialized.index) transfer.push(serialized.index.buffer);
+    if (serialized.indirectBuffer) transfer.push(serialized.indirectBuffer.buffer);
+    self.postMessage({ id, ok: true, serialized, position: res.position }, transfer);
+  } catch (err) {
+    self.postMessage({ id, ok: false, error: String(err && err.message || err) });
+  }
+};

package/src/world/collision.js

@@ -0,0 +1,174 @@
+// Unified mesh collision (Phase 1: buildings) built on three-mesh-bvh.
+//
+// We bake the position-only geometry of static colliders into ONE merged
+// BufferGeometry (world transforms applied) and build a BVH over it. The player
+// capsule is then swept against that BVH each frame (see world.moveCapsule),
+// which makes stairs/walls/slopes "just work" as real triangles — no per-object
+// 2D colliders or heightfield hacks. The merged mesh is never rendered.
+//
+// three-mesh-bvh is geometry/math only (no renderer calls), so it is fine under
+// the three/webgpu renderer; we feed it plain BufferGeometry data.
+import * as THREE from 'three/webgpu';
+import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';
+import { MeshBVH } from 'three-mesh-bvh';
+
+// Merge every mesh under `objs` (world matrices baked, position attribute only)
+// and return a MeshBVH over the result — or null if there's no geometry.
+// objs: Object3Ds (regular + instanced meshes) baked at their current matrices.
+// instanceGroups: { geometry, matrices(Float32Array), count } baked from explicit
+// LOD0 geometry + full instance set (used for distance-LOD scatters like rocks,
+// so collision uses LOD0 — never the far LOD — across all instances).
+export function buildBVH(objs = [], instanceGroups = []) {
+  const geos = [];
+  const world = new THREE.Matrix4();
+  const inst = new THREE.Matrix4();
+  const addAt = (base, worldMat) => {
+    if (!base?.attributes?.position) return;
+    let g = base.clone();
+    for (const name of Object.keys(g.attributes)) {
+      if (name !== 'position') g.deleteAttribute(name);
+    }
+    g.applyMatrix4(worldMat);
+    if (g.index) g = g.toNonIndexed(); // normalize so merge doesn't mismatch
+    geos.push(g);
+  };
+  for (const o of objs) {
+    if (!o) continue;
+    o.updateMatrixWorld(true);
+    o.traverse((m) => {
+      if (!m.isMesh || !m.geometry?.attributes?.position) return;
+      // MOVING PARTS OPT OUT. The BVH is baked once and frozen, so anything that later moves
+      // would still be collided at the pose it had at boot — the door would swing open in front
+      // of you while its shut-pose triangles still stood in the doorway. The county's door leaves
+      // ride a BatchedMesh at the scene root, which this walk never reaches, so the flag is belt
+      // and braces; doors collide via the switchable slab in world.collide() (town.js doorsAt).
+      if (m.userData?.noBVH) return;
+      if (m.isInstancedMesh) {
+        for (let i = 0; i < m.count; i++) {
+          m.getMatrixAt(i, inst);
+          world.multiplyMatrices(m.matrixWorld, inst);
+          addAt(m.geometry, world);
+        }
+      } else {
+        addAt(m.geometry, m.matrixWorld);
+      }
+    });
+  }
+  for (const grp of instanceGroups) {
+    for (let i = 0; i < grp.count; i++) {
+      world.fromArray(grp.matrices, i * 16);
+      addAt(grp.geometry, world);
+    }
+  }
+  if (!geos.length) return null;
+  const merged = BufferGeometryUtils.mergeGeometries(geos, false);
+  if (!merged) return null;
+  return new MeshBVH(merged);
+}
+
+// ---- off-main-thread variant (see bvhWorker.js) -------------------------------
+// Same result as buildBVH(), but the bake+merge+BVH (the ~30–80ms cost) runs in a
+// Web Worker. Used for streamed tiles so collision never blocks the frame. The
+// returned MeshBVH supports .shapecast()/.raycastFirst() identically.
+let _worker = null, _workerBroken = false;
+const _jobs = new Map();
+let _nextJob = 1;
+
+function _getWorker() {
+  if (_worker || _workerBroken) return _worker;
+  try {
+    _worker = new Worker(new URL('./bvhWorker.js', import.meta.url), { type: 'module' });
+    _worker.onmessage = (e) => {
+      const job = _jobs.get(e.data.id);
+      if (!job) return;
+      _jobs.delete(e.data.id);
+      if (!e.data.ok) { job.resolve(null); return; }
+      try {
+        const geom = new THREE.BufferGeometry();
+        geom.setAttribute('position', new THREE.BufferAttribute(e.data.position, 3));
+        const bvh = MeshBVH.deserialize(e.data.serialized, geom, { setIndex: true, indirect: Boolean(e.data.serialized.indirectBuffer) });
+        job.resolve(bvh);
+      } catch (err) { console.warn('[bvh] deserialize failed', err); job.resolve(null); }
+    };
+    _worker.onerror = (err) => {
+      console.warn('[bvh] worker error — falling back to sync builds', err?.message || err);
+      _workerBroken = true;
+      for (const job of _jobs.values()) job.resolve(null); // let callers fall back
+      _jobs.clear();
+    };
+  } catch (e) {
+    console.warn('[bvh] worker unavailable — sync builds', e);
+    _workerBroken = true;
+  }
+  return _worker;
+}
+
+// Gather serializable collider data WITHOUT mutating/neutering the live geometry:
+// copy each source position/index, and the WORLD matrix of every instance.
+function extractParts(objs, instanceGroups) {
+  const parts = [];
+  const inst = new THREE.Matrix4(), world = new THREE.Matrix4();
+  const copyPos = (g) => { const a = g.attributes.position.array; return new Float32Array(a); };
+  const copyIdx = (g) => (g.index ? new (g.index.array.constructor)(g.index.array) : null);
+  for (const o of objs) {
+    if (!o) continue;
+    o.updateMatrixWorld(true);
+    o.traverse((m) => {
+      if (!m.isMesh || !m.geometry?.attributes?.position) return;
+      // MOVING PARTS OPT OUT. The BVH is baked once and frozen, so anything that later moves
+      // would still be collided at the pose it had at boot — the door would swing open in front
+      // of you while its shut-pose triangles still stood in the doorway. The county's door leaves
+      // ride a BatchedMesh at the scene root, which this walk never reaches, so the flag is belt
+      // and braces; doors collide via the switchable slab in world.collide() (town.js doorsAt).
+      if (m.userData?.noBVH) return;
+      if (m.isInstancedMesh) {
+        if (!m.count) return;
+        const mats = new Float32Array(m.count * 16);
+        for (let i = 0; i < m.count; i++) { m.getMatrixAt(i, inst); world.multiplyMatrices(m.matrixWorld, inst); world.toArray(mats, i * 16); }
+        parts.push({ positions: copyPos(m.geometry), index: copyIdx(m.geometry), matrices: mats, count: m.count });
+      } else {
+        const mats = new Float32Array(16); m.matrixWorld.toArray(mats, 0);
+        parts.push({ positions: copyPos(m.geometry), index: copyIdx(m.geometry), matrices: mats, count: 1 });
+      }
+    });
+  }
+  for (const grp of instanceGroups) {
+    if (!grp?.geometry?.attributes?.position || !grp.count) continue;
+    const mats = new Float32Array(grp.matrices.subarray(0, grp.count * 16));
+    parts.push({ positions: copyPos(grp.geometry), index: copyIdx(grp.geometry), matrices: mats, count: grp.count });
+  }
+  return parts;
+}
+
+export async function buildBVHAsync(objs = [], instanceGroups = []) {
+  if (_workerBroken) return buildBVH(objs, instanceGroups);
+  const w = _getWorker();
+  if (!w) return buildBVH(objs, instanceGroups);
+  const parts = extractParts(objs, instanceGroups);
+  if (!parts.length) return null;
+  try {
+    const bvh = await new Promise((resolve) => {
+      const id = _nextJob++;
+      _jobs.set(id, { resolve });
+      const transfer = [];
+      for (const p of parts) { transfer.push(p.positions.buffer, p.matrices.buffer); if (p.index) transfer.push(p.index.buffer); }
+      w.postMessage({ id, parts }, transfer);
+    });
+    // worker died mid-job (resolved null via onerror) → rebuild synchronously so the tile still collides
+    if (bvh === null && _workerBroken) return buildBVH(objs, instanceGroups);
+    return bvh;
+  } catch (e) {
+    _workerBroken = true;
+    return buildBVH(objs, instanceGroups);
+  }
+}
+
+// Optional dev visualization: a wireframe mesh of the merged collision geometry,
+// so the collider can be eyeballed without trusting the renderer's BVH helper.
+export function colliderWireframe(bvh) {
+  if (!bvh) return null;
+  const mat = new THREE.MeshBasicMaterial({ color: 0x00ff88, wireframe: true, transparent: true, opacity: 0.4, depthTest: false });
+  const mesh = new THREE.Mesh(bvh.geometry, mat);
+  mesh.renderOrder = 999;
+  return mesh;
+}

package/src/world/grass.js

@@ -0,0 +1,347 @@
+// Streaming grass — Option A: lightweight procedural blades (≈6 triangles each,
+// vertex-colour gradient) as instanced chunks with GPU wind in a TSL node material.
+// A small ring of tiles is generated on demand around the player and disposed when
+// far, so only a few thousand blades exist/render. Blades also flatten under nearby
+// entities (player + NPCs/enemies) and slowly spring back — a timestamped trail of
+// recent positions drives the recovery, all evaluated on the GPU.
+import * as THREE from 'three/webgpu';
+import {
+  Fn, positionLocal, instanceIndex, time, sin, vec3, vec2, hash, float, mix,
+  positionWorld, cameraPosition, smoothstep, oneMinus, attribute, uniform, uniformArray,
+  Loop, If, step, max, sqrt, length, texture, normalize, dot, normalLocal, transformNormalToView,
+} from 'three/tsl';
+import { uWet, uCover, uSunDir, uWindDir, uWindStr } from './weatherUniforms.js';
+import { waterNoiseTexture } from './waterNoise.js';
+import { mulberry32 } from '../core/utils.js';
+
+// Trample trail split so other entities can't evict the player's path: slots
+// 0..TRAIL_P-1 are a dedicated player trail (≈3s of recovery), the rest hold the
+// current positions of nearby NPCs/enemies.
+const TRAIL_P = 20;
+const TRAIL_E = 8;
+const TRAIL = TRAIL_P + TRAIL_E;
+const TRAMPLE_R = 0.9;  // metres a sample flattens around it
+const PLAYER_GATE = 36; // only blades within this of the player run the trample loop
+
+// A CLUMP of blades per instance (braffolk: clumps read denser than single blades at the
+// same triangle budget). Each blade: 3 paired levels + a POINTED single-vertex tip, a 2×
+// stronger built-in bend, and "rounded cross-section" normals (left/right verts rotated
+// ±38° around the blade's up axis) so the two sides of a blade light differently.
+function makeClumpGeometry() {
+  const BLADES = 4, baseHalf = 0.05;
+  const pos = [], nrm = [], col = [], idx = [];
+  const base = new THREE.Color(0x3d5f24), tip = new THREE.Color(0x8ab551), c = new THREE.Color();
+  const rng = mulberry32(9182736);
+  let v = 0;
+  for (let b = 0; b < BLADES; b++) {
+    const yaw = rng() * 6.2832;
+    const cy = Math.cos(yaw), sy = Math.sin(yaw);
+    const ox = (rng() - 0.5) * 0.22, oz = (rng() - 0.5) * 0.22;   // radial offset in the clump
+    const hgt = 0.75 + rng() * 0.5;                               // per-blade height
+    const leanX = (rng() - 0.5) * 0.16, leanZ = (rng() - 0.5) * 0.16;
+    const put = (lx, y, lz, nx, nz, t) => {
+      // rotate blade-local → clump-local, add offset + lean
+      const wx = lx * cy - lz * sy + ox + leanX * y;
+      const wz = lx * sy + lz * cy + oz + leanZ * y;
+      pos.push(wx, y * hgt, wz);
+      const wnx = nx * cy - nz * sy, wnz = nx * sy + nz * cy;
+      nrm.push(wnx * 0.75, 1.05, wnz * 0.75);                      // mostly UP (≈45°) — noon sun must still light the sward
+      c.copy(base).lerp(tip, t);
+      col.push(c.r, c.g, c.b);
+    };
+    const N38 = Math.sin(0.66), NC = Math.cos(0.66);               // ±38° rounded cross-section
+    for (let i = 0; i <= 2; i++) {
+      const y = i / 3;
+      const hw = baseHalf * (1 - y * 0.7);
+      const zb = 0.28 * y * y;                                     // 2× the old bend
+      put(-hw, y, zb, -N38, NC, y);
+      put(hw, y, zb, N38, NC, y);
+    }
+    put(0, 1, 0.28, 0, 1, 1);                                      // pointed tip
+    const B = v;
+    for (let i = 0; i < 2; i++) { const a = B + i * 2; idx.push(a, a + 1, a + 3, a, a + 3, a + 2); }
+    idx.push(B + 4, B + 5, B + 6);                                 // tip triangle
+    v += 7;
+  }
+  const g = new THREE.BufferGeometry();
+  g.setAttribute('position', new THREE.Float32BufferAttribute(pos, 3));
+  g.setAttribute('normal', new THREE.Float32BufferAttribute(nrm, 3));
+  g.setAttribute('color', new THREE.Float32BufferAttribute(col, 3));
+  g.setIndex(idx);
+  g.computeBoundingSphere();
+  return g;
+}
+
+export class GrassField {
+  constructor(scene, opts) {
+    this.scene = scene;
+    this.accept = opts.accept;
+    this.heightAt = opts.heightAt;
+    this.tile = opts.tile ?? 16;
+    this.spacing = opts.spacing ?? 0.135;
+    this.jitter = opts.jitter ?? 0.11;
+    this.sMin = opts.sMin ?? 0.22;
+    this.sMax = opts.sMax ?? 0.40;
+    this.showR = opts.showR ?? 60;
+    this.hideR = opts.hideR ?? 72;
+    this.maxBuildsPerUpdate = 1;   // >1 stacks multi-ms tile builds into one frame — visible gallop hitches
+
+    // trample trail (world x, z, timestamp) — old/unwritten slots sit far in the past
+    this._ring = Array.from({ length: TRAIL }, () => new THREE.Vector3(0, 0, -1000));
+    this.uTrail = uniformArray(this._ring, 'vec3');
+    this.uNow = uniform(0);
+    this.uPlayer = uniform(new THREE.Vector3());
+    this._pHead = 0; this._eHead = 0; this._now = 0; this._sampleT = 0;
+
+    this.geo = makeClumpGeometry();
+    this.mat = this._makeMaterial();
+    this.tiles = new Map();
+
+    // RESIDENT mesh pool: grass tiles never create meshes at runtime. r184 WebGPU pays
+    // ~3 pipeline-cache entries per new InstancedMesh OBJECT, and adding a mesh to the
+    // scene re-records the render bundle — per-tile mesh churn while moving was most of
+    // the remaining travel freezes (geo:+3 / render 45-60ms records) after the scatter
+    // residents landed. A fixed pool of capacity-sized meshes is built here at boot
+    // (their pipelines compile in the boot warm); a streamed-in tile checks one out and
+    // rewrites its instance buffers, a streamed-out tile returns it (visible=false pool
+    // slots skip the render-list walk). Per-tile bounding spheres keep frustum culling.
+    this.tileCap = Math.ceil((this.tile / this.spacing + 2) ** 2);   // worst-case clumps in one tile
+    // tiles live while their centre is within hideR of the player → pool bound + margin
+    this.poolN = Math.ceil(Math.PI * this.hideR * this.hideR / (this.tile * this.tile)) + 12;
+    this._pool = [];
+    for (let i = 0; i < this.poolN; i++) this._pool.push(this._makePoolMesh());
+  }
+
+  _makePoolMesh() {
+    const geo = this.geo.clone();
+    geo.setAttribute('aBase', new THREE.InstancedBufferAttribute(new Float32Array(this.tileCap * 2), 2));
+    geo.setAttribute('aTNorm', new THREE.InstancedBufferAttribute(new Float32Array(this.tileCap * 3), 3));
+    const im = new THREE.InstancedMesh(geo, this.mat, this.tileCap); // instanceMatrix born zero-filled (warm-flash safe)
+    im.count = 0;
+    im.visible = false;
+    im.castShadow = false; im.receiveShadow = true;
+    im.name = 'scatter:grass';                    // 'grass' is in the BVH EXCLUDE regex — never collides
+    im.frustumCulled = true;
+    im.boundingSphere = new THREE.Sphere();       // set per checkout to the tile's bounds
+    im.matrixAutoUpdate = false; im.updateMatrix();
+    this.scene.add(im);
+    return im;
+  }
+
+  _makeMaterial() {
+    const mat = new THREE.MeshStandardNodeMaterial({ vertexColors: true, roughness: 1, metalness: 0 });
+    mat.side = THREE.DoubleSide;
+    const aBase = attribute('aBase', 'vec2'); // this blade's world x,z
+    const noiseTex = waterNoiseTexture();
+
+    // wind — travelling gust fronts (braffolk): a tileable noise field advected downwind,
+    // squared so lulls rest and fronts SWEEP across whole meadows; a small per-blade sine
+    // jiggle keeps neighbours desynchronised inside a front. One vertex texture fetch.
+    const phase = hash(instanceIndex).mul(6.2832);
+    const bend = positionLocal.y.mul(positionLocal.y);
+    // fronts advect DOWNWIND on the shared global wind (world/wind.js), and the blades lean the way it
+    // blows — strength = the local gust front × the global wind strength, so a calm hour barely stirs and
+    // a gust sweeps the whole meadow over. (Was a fixed vec2(4.2,3.4) front + a fixed +X/+Z lean.)
+    const gust = texture(noiseTex, aBase.sub(uWindDir.mul(5.4).mul(time)).mul(1 / 42)).r;
+    const gustStr = gust.mul(gust).mul(0.5).add(0.04).mul(uWindStr.mul(1.3).add(0.28));
+    const jig = sin(time.mul(2.4).add(phase)).mul(0.05).add(sin(time.mul(3.9).add(phase.mul(1.7))).mul(0.028));
+    const lean = float(0.95).mul(gustStr);
+    const swayX = uWindDir.x.mul(lean).add(jig).mul(bend);
+    const swayZ = uWindDir.y.mul(lean).add(jig.mul(0.7)).mul(bend);
+
+    // trample — only evaluated for blades near the player (cost bounded). Each trail
+    // sample flattens nearby blades; flatten holds ~1s then eases out by ~3s. Loop/If
+    // require a Fn() stack context, so the whole position calc lives inside one.
+    const uTrail = this.uTrail, uNow = this.uNow, uPlayer = this.uPlayer;
+    mat.positionNode = Fn(() => {
+      // strongest trample influence on this blade (0 upright .. 1 fully flattened),
+      // plus the unit direction of that strongest sample (so the tip droops the right way)
+      const flat = float(0).toVar();
+      const dir = vec2(0, 0).toVar();
+      const playerD = length(aBase.sub(vec2(uPlayer.x, uPlayer.z)));
+      If(playerD.lessThan(float(PLAYER_GATE)), () => {
+        Loop(TRAIL, ({ i }) => {
+          const s = uTrail.element(i);
+          const age = uNow.sub(s.z);
+          const dx = aBase.x.sub(s.x), dz = aBase.y.sub(s.y);
+          const d = max(sqrt(dx.mul(dx).add(dz.mul(dz))), float(0.001));
+          const ageGate = step(float(0), age).mul(oneMinus(step(float(3), age)));
+          const distGate = oneMinus(smoothstep(float(TRAMPLE_R * 0.6), float(TRAMPLE_R), d));
+          const recover = oneMinus(smoothstep(float(1), float(3), age)); // 1 hold → 0 risen
+          const f = ageGate.mul(distGate).mul(recover);
+          const stronger = step(flat, f); // 1 when this sample beats the best so far
+          dir.assign(dir.mul(oneMinus(stronger)).add(vec2(dx, dz).div(d).mul(stronger))); // adopt its unit dir
+          flat.assign(max(flat, f));
+        });
+      });
+      const flatten = flat.clamp(0, 1);
+      const droop = flatten.mul(bend);                 // bend the upper blade, planted base
+      const newY = positionLocal.y.mul(oneMinus(flatten.mul(0.85)));  // shorten toward the ground
+      // tip droops outward by ~its own height (bounded — no summed push) so it lies over
+      const px = dir.x.mul(droop).mul(0.7);
+      const pz = dir.y.mul(droop).mul(0.7);
+      const w = oneMinus(flatten); // trampled blades stop swaying
+      const sx = swayX.mul(w), sz = swayZ.mul(w);
+      // cantilever: a bent blade gets SHORTER, not longer — dip the tip by the lean²
+      const dip = sx.mul(sx).add(sz.mul(sz)).mul(0.3);
+      return vec3(positionLocal.x.add(sx).add(px), newY.sub(dip), positionLocal.z.add(sz).add(pz));
+    })();
+
+    const camDist = positionWorld.sub(cameraPosition).length();
+
+    // far blades light like the hillside they grow on: blend the blade's rounded normal
+    // toward the baked TERRAIN normal with distance (braffolk) — kills far-field sparkle
+    // and makes meadows follow the sun across slopes. Instance matrices are composed in
+    // world space (mesh at origin), so instance-transformed normalLocal IS world space.
+    const aTN = attribute('aTNorm', 'vec3');
+    const nBlend = smoothstep(float(7), float(26), camDist).mul(0.6).add(0.3);
+    mat.normalNode = transformNormalToView(normalize(mix(normalLocal, aTN, nBlend)));
+
+    // colour: dryness patches + root AO + light-through-the-blade, then weather on top
+    mat.colorNode = Fn(() => {
+      // broad noise patches drift meadows green → straw gold (braffolk's patch dryness)
+      const dry = smoothstep(float(0.48), float(0.8), texture(noiseTex, aBase.mul(1 / 52)).g).mul(0.65);
+      const graded = attribute('color', 'vec3');
+      const dried = mix(graded, graded.mul(vec3(1.45, 1.2, 0.5)), dry);
+      // roots sit in each other's shadow — cheap AO keeps dense clumps from reading flat
+      const ao = positionLocal.y.mul(0.35).add(0.72).clamp(0.72, 1);
+      // sun/moon shining THROUGH blades when looking toward the light (translucency)
+      const vDir = normalize(positionWorld.sub(cameraPosition));
+      const back = dot(vDir, uSunDir).clamp(0, 1).pow(4).mul(positionLocal.y).mul(0.4);
+      const lit = dried.mul(ao).add(vec3(0.5, 0.55, 0.2).mul(back));
+      const c = lit.mul(mix(float(1.0), float(0.7), uWet));
+      const tip = smoothstep(float(0.1), float(0.55), positionLocal.y);
+      return mix(c, vec3(0.95, 0.96, 1.0), uCover.mul(tip));
+    })();
+
+    // dissolve toward the render edge (fragment stage — no circular dependency)
+    mat.opacityNode = oneMinus(smoothstep(float(this.showR - 14), float(this.showR - 3), camDist));
+    mat.alphaHash = true;
+    return mat;
+  }
+
+  // Feed recent entity positions each frame; sampled into the trail at intervals so
+  // it spans a few seconds (drives the spring-back). Pass player first.
+  tickTrample(dt, sources) {
+    this._now += dt;
+    this.uNow.value = this._now;
+    if (sources.length) this.uPlayer.value.set(sources[0].x, 0, sources[0].z);
+    this._sampleT -= dt;
+    if (this._sampleT > 0) return;
+    this._sampleT = 0.15;
+    // player → dedicated trail slots (0..TRAIL_P-1) so it isn't evicted by others
+    if (sources.length) {
+      this._ring[this._pHead % TRAIL_P].set(sources[0].x, sources[0].z, this._now);
+      this._pHead++;
+    }
+    // nearby NPCs/enemies → the entity slots (TRAIL_P..TRAIL-1)
+    for (let i = 1; i < sources.length; i++) {
+      this._ring[TRAIL_P + (this._eHead % TRAIL_E)].set(sources[i].x, sources[i].z, this._now);
+      this._eHead++;
+    }
+  }
+
+  update(px, pz) {
+    const T = this.tile, hide2 = this.hideR * this.hideR, show2 = this.showR * this.showR;
+    for (const [k, t] of this.tiles) {
+      const dx = t.cx - px, dz = t.cz - pz;
+      if (dx * dx + dz * dz > hide2) {
+        // return the mesh to the pool — no scene.remove (render-bundle re-record), no dispose
+        if (t.mesh) { t.mesh.visible = false; t.mesh.count = 0; this._pool.push(t.mesh); }
+        this.tiles.delete(k);
+      }
+    }
+    const ctx = Math.round(px / T), ctz = Math.round(pz / T), span = Math.ceil(this.showR / T) + 1;
+    let budget = this.maxBuildsPerUpdate;
+    for (let i = -span; i <= span && budget > 0; i++) {
+      for (let j = -span; j <= span && budget > 0; j++) {
+        const tx = ctx + i, tz = ctz + j, cx = tx * T, cz = tz * T;
+        const dx = cx - px, dz = cz - pz;
+        if (dx * dx + dz * dz > show2) continue;
+        const key = tx * 100003 + tz;
+        if (this.tiles.has(key)) continue;
+        this._buildTile(tx, tz, cx, cz, key);
+        budget--;
+      }
+    }
+  }
+
+  _buildTile(tx, tz, cx, cz, key) {
+    const rng = mulberry32(((tx * 73856093) ^ (tz * 19349663)) >>> 0);
+    const half = this.tile / 2;
+    // Coarse height grid + bilinear interp: heightAt (fbm + pads + road scan) per blade
+    // was ~14k full samples per tile — the gallop-streaming hitch. 17×17 real samples
+    // cover the tile; cells whose corners disagree by >0.35 m (river banks, cliff
+    // benches) fall back to exact heightAt so blades never float on rough ground.
+    const HG = 16, gstep = this.tile / HG, gx0 = cx - half, gz0 = cz - half;
+    const hg = new Float32Array((HG + 1) * (HG + 1));
+    for (let gi = 0; gi <= HG; gi++) {
+      for (let gj = 0; gj <= HG; gj++) hg[gi * (HG + 1) + gj] = this.heightAt(gx0 + gi * gstep, gz0 + gj * gstep);
+    }
+    const hAt = (x, z) => {
+      let fx = (x - gx0) / gstep, fz = (z - gz0) / gstep;
+      fx = fx < 0 ? 0 : fx > HG ? HG : fx; fz = fz < 0 ? 0 : fz > HG ? HG : fz;
+      const i0 = Math.min(HG - 1, fx | 0), j0 = Math.min(HG - 1, fz | 0);
+      const tx2 = fx - i0, tz2 = fz - j0, r0 = i0 * (HG + 1) + j0;
+      const h00 = hg[r0], h01 = hg[r0 + 1], h10 = hg[r0 + HG + 1], h11 = hg[r0 + HG + 2];
+      const steep = Math.max(h00, h01, h10, h11) - Math.min(h00, h01, h10, h11) > 0.35;
+      if (steep) return this.heightAt(x, z);
+      return (h00 * (1 - tx2) + h10 * tx2) * (1 - tz2) + (h01 * (1 - tx2) + h11 * tx2) * tz2;
+    };
+    // per-grid-node terrain normals from the height grid (finite differences — no extra
+    // heightAt calls); each clump takes its nearest node's normal for the far-lighting blend
+    const tn = new Float32Array((HG + 1) * (HG + 1) * 3);
+    for (let gi = 0; gi <= HG; gi++) {
+      for (let gj = 0; gj <= HG; gj++) {
+        const iA = Math.max(0, gi - 1), iB = Math.min(HG, gi + 1);
+        const jA = Math.max(0, gj - 1), jB = Math.min(HG, gj + 1);
+        const dx = (hg[iB * (HG + 1) + gj] - hg[iA * (HG + 1) + gj]) / ((iB - iA) * gstep);
+        const dz = (hg[gi * (HG + 1) + jB] - hg[gi * (HG + 1) + jA]) / ((jB - jA) * gstep);
+        const o = (gi * (HG + 1) + gj) * 3, inl = 1 / Math.hypot(dx, 1, dz);
+        tn[o] = -dx * inl; tn[o + 1] = inl; tn[o + 2] = -dz * inl;
+      }
+    }
+    // flat number array (x,y,z,ry,s,nx,ny,nz per clump) — an object per blade was megabytes
+    // of short-lived GC churn per tile, felt as periodic pauses while streaming at speed
+    const data = [];
+    let yMin = Infinity, yMax = -Infinity;
+    for (let x = cx - half; x < cx + half; x += this.spacing) {
+      for (let z = cz - half; z < cz + half; z += this.spacing) {
+        const jx = x + (rng() - 0.5) * this.jitter, jz = z + (rng() - 0.5) * this.jitter;
+        const ry = rng() * 6.2832, s = this.sMin + rng() * (this.sMax - this.sMin);
+        if (!this.accept(jx, jz)) continue;
+        const gi = Math.max(0, Math.min(HG, Math.round((jx - gx0) / gstep)));
+        const gj = Math.max(0, Math.min(HG, Math.round((jz - gz0) / gstep)));
+        const ni = (gi * (HG + 1) + gj) * 3;
+        const y = hAt(jx, jz) - 0.02;
+        if (y < yMin) yMin = y; if (y > yMax) yMax = y;
+        data.push(jx, y, jz, ry, s, tn[ni], tn[ni + 1], tn[ni + 2]);
+      }
+    }
+    let n = data.length / 8;
+    if (!n) { this.tiles.set(key, { mesh: null, cx, cz }); return; }
+    // check a RESIDENT mesh out of the pool and rewrite its buffers — never create one here.
+    // Pool dry (transient burst) → leave the tile unbuilt; update() naturally retries it.
+    const im = this._pool.pop();
+    if (!im) return;
+    if (n > this.tileCap) { console.error(`[grass] tile overflow (${n} > cap ${this.tileCap}) — clumps dropped`); n = this.tileCap; }
+    const baseA = im.geometry.getAttribute('aBase'), tnAt = im.geometry.getAttribute('aTNorm');
+    const m4 = new THREE.Matrix4(), q = new THREE.Quaternion(), up = new THREE.Vector3(0, 1, 0), p = new THREE.Vector3(), sc = new THREE.Vector3();
+    for (let i = 0; i < n; i++) {
+      const o = i * 8;
+      baseA.array[i * 2] = data[o]; baseA.array[i * 2 + 1] = data[o + 2];
+      tnAt.array[i * 3] = data[o + 5]; tnAt.array[i * 3 + 1] = data[o + 6]; tnAt.array[i * 3 + 2] = data[o + 7];
+      q.setFromAxisAngle(up, data[o + 3]);
+      m4.compose(p.set(data[o], data[o + 1], data[o + 2]), q, sc.set(data[o + 4], data[o + 4], data[o + 4]));
+      im.setMatrixAt(i, m4);
+    }
+    im.count = n;
+    im.instanceMatrix.needsUpdate = true;
+    baseA.needsUpdate = true; tnAt.needsUpdate = true;
+    // conservative tile sphere: half-diagonal + terrain span + blade height/sway headroom
+    im.boundingSphere.center.set(cx, (yMin + yMax) / 2, cz);
+    im.boundingSphere.radius = Math.hypot(half * 1.42, (yMax - yMin) / 2 + 1.5);
+    im.visible = true;
+    this.tiles.set(key, { mesh: im, cx, cz });
+  }
+}