sindicate 0.2.0 → 0.4.0

package/docs/api/shatter.md

@@ -0,0 +1,121 @@
+# Shatter
+
+`src/systems/shatter.js` — physics-y debris for smashed props (pots, urns, pre-fractured smashables). When something is smashed, `Shatter` clones the pack's real shard meshes (e.g. `SM_Prop_Vase_Shard_01..04`), flings them out with velocity and spin, drops them under gravity, bounces and settles them on the floor, then fades them out and removes them. It is pure CPU integration over a tiny transient list — no physics engine, no per-shard lights, nothing resident: shard meshes are added to the scene on smash and removed once faded.
+
+Exported from the package barrel (`export * from './systems/shatter.js'` in `src/index.js`).
+
+## Why it's built this way (PERF LAW)
+
+The engine's WebGPU doctrine (see `ENGINE_DESIGN.md`, P2) is: everything resident at boot, never add/remove skinned meshes mid-play, fixed light counts, no pipeline compiles after boot. Shatter is the deliberate, minimal way to have mid-play debris inside that doctrine:
+
+- Shards are plain static mesh clones — never skinned, never lit individually.
+- The "pool" (`this.pieces`) is a tiny, short-lived array; each burst adds a handful of pieces and every piece removes itself after settle + fade. Nothing accumulates.
+- All motion is closed-form CPU integration in `update(dt)` — no physics engine dependency.
+- Cloned shard materials are of types the scene already renders, so bursts reuse existing pipelines. The design doc plans to make this a hard guarantee (shatter materials warm-registered at boot so the first mid-fight burst can never compile a pipeline); today it is discipline by convention — keep shard templates using materials that have already been rendered.
+
+Note the word "pool" here means *bounded transient set*, not object reuse: clones are created per burst and fully disposed after fading.
+
+## Injection
+
+The scene is constructor-injected — the class holds no globals and touches nothing but the `THREE.Scene` you hand it. This file is part of the "verified-clean" migration tier: moved verbatim from the western game because it already imported clean, with the scene as its only external dependency.
+
+## Exports
+
+### `class Shatter`
+
+#### `constructor(scene)`
+
+- `scene` — the `THREE.Scene` shard meshes are added to and removed from.
+
+Creates an empty pool (`this.pieces = []`).
+
+#### `burst(pos, frags, opts = {})`
+
+Spawn one burst of shards. No-op if `frags` is missing or empty.
+
+```js
+burst(pos, frags, { count = 8, floorY = pos.y, spread = 2.4, up = 3.2, scale = 1, dir = null, ry = 0 } = {})
+```
+
+- `pos` — world `THREE.Vector3`, base of the smashed prop.
+- `frags` — array of template `Object3D`s to clone (the shard meshes). Cycled with `i % frags.length` when `count` exceeds the template count.
+- `count` — how many shards to throw (default 8).
+- `floorY` — Y the shards rest on (default `pos.y`). Each piece actually settles at `floorY + 0.04..0.08` (random) so shards stack slightly instead of z-fighting on one plane.
+- `spread` — horizontal fling speed scale (default 2.4).
+- `up` — upward fling speed scale (default 3.2).
+- `scale` — uniform scale multiplier applied to each clone (default 1).
+- `dir` — optional unit `THREE.Vector3`; the blow "carries through": `spread * (0.5..0.9)` of extra velocity along `dir` is added to every shard.
+- `ry` — the prop's yaw in radians. Only meaningful for pivot templates (below).
+
+Two spawn modes, chosen per template:
+
+1. **Pre-fractured smashables** — templates carrying `userData.pivot` (a local-space offset) spawn at their *true position inside the prop* (pivot rotated by `ry`, scaled, offset from `pos`), start in the prop's rest orientation (`rotation.set(0, ry, 0)`), and fly *outward from the prop's centre*, so the prop visibly breaks apart along its fracture planes instead of debris materialising at a point. These chunky shards tumble slower (`spinScale = 0.55`).
+2. **Generic shards** (no pivot) — spawn in a small random cloud around `pos` with fully random orientation and random outward velocity.
+
+Every clone gets **independent material instances** (`material.clone()`, arrays handled) so each shard can fade on its own without affecting the templates or its siblings.
+
+#### `update(dt)`
+
+Advance every piece one frame. Call this once per frame from the game loop. Early-returns when the pool is empty. `dt` is clamped to `0.04` s internally so a hitched frame can't tunnel shards through the floor.
+
+Per-piece lifecycle:
+
+1. **Flying** — gravity (`G = 17`, tuned snappy for low-poly debris), position integration, Euler spin.
+2. **Bounce** — on crossing `floorY`: Y velocity reflected with restitution `REST = 0.34`, horizontal velocity kept at `FRICTION = 0.62` per bounce, spin damped to 45 %.
+3. **Rest** — when a bounce leaves `|vel.y| < 0.7` and horizontal speed² `< 0.4`, the piece rests (spin zeroed).
+4. **Settle hold** — a rested shard lingers `SETTLE_HOLD = 1.4` s.
+5. **Fade** — opacity ramps to 0 over `FADE = 1.1` s (`transparent = true`, `depthWrite = false` forced on its materials).
+6. **Removal** — at opacity 0 the mesh is removed from the scene, its cloned materials disposed, and the piece spliced out (the loop iterates backwards so splicing is safe).
+
+#### `clear()`
+
+Immediately remove every live shard from the scene, dispose their cloned materials, and empty the pool. Call on scene teardown / level change — pieces mid-flight will otherwise stay in the scene forever since only `update` retires them.
+
+## Usage
+
+```js
+import * as THREE from 'three/webgpu';
+import { Shatter } from 'sindicate';
+
+const shatter = new Shatter(scene);
+
+// Loaded once at boot: the pack's real shard meshes.
+const vaseShards = [shard01, shard02, shard03, shard04];
+
+// On smash — e.g. a melee hit lands on a pot:
+function smashPot(pot, hitDir) {
+  shatter.burst(pot.position.clone(), vaseShards, {
+    count: 10,
+    floorY: pot.position.y,   // pot sits on the floor
+    dir: hitDir,              // unit vector — the blow carries through
+    scale: 0.9,
+  });
+  scene.remove(pot);
+}
+
+// Pre-fractured prop: templates carry userData.pivot, so pass the prop's yaw
+// and the shards fly apart along the fracture planes.
+shatter.burst(crate.position.clone(), crate.userData.fragments, {
+  count: crate.userData.fragments.length,
+  ry: crate.rotation.y,
+  dir: hitDir,
+});
+
+// Frame loop:
+shatter.update(dt);
+
+// Level teardown:
+shatter.clear();
+```
+
+## Gotchas
+
+- **Geometry is shared with the templates and must never be disposed.** Only the *materials* are cloned per shard (so each fades independently); the internal `disposeMats` helper frees exactly those clones on removal and deliberately leaves geometry alone. If you ever touch removal code, keep that asymmetry — disposing geometry here would destroy the templates for every future burst.
+- **You must drive `update(dt)` every frame and call `clear()` on teardown.** There is no timer or scene hook; a Shatter that stops being updated leaves its shards frozen in the scene.
+- **`dt` is clamped to 0.04 s** inside `update` — a long hitch slows the debris rather than letting shards tunnel through the floor or fly across the map.
+- **Templates cycle.** `count` larger than `frags.length` reuses templates round-robin (`i % frags.length`); asking for 12 shards from 4 templates is fine and normal.
+- **`userData.pivot` changes everything about a template**: spawn position (true position inside the prop, rotated by `ry`), initial orientation (prop's rest orientation, not random), outward-from-centre velocity, and slower tumble (`spinScale = 0.55`). Generic point-burst behaviour only applies to templates without it.
+- **Fading mutates the cloned materials** (`transparent = true`, `depthWrite = false`). This is safe precisely because they are per-shard clones — another reason not to "optimise" the clone away.
+- **Mid-play adds are the point, but keep them cheap.** The whole design exists to add/remove *only* tiny unskinned meshes mid-play, with materials whose pipelines already exist. Don't extend it to spawn lights, skinned meshes, or novel material types per burst — that breaks the PERF LAW this module was shaped by. (Future engine work warm-registers shatter materials at boot to enforce this; see `ENGINE_DESIGN.md`.)
+- **Settle heights are jittered** (`floorY + 0.04..0.08`) so stacked shards don't z-fight on a single plane — if debris looks like it floats slightly, that offset is intentional.
+- The tuning constants (`G = 17`, `REST = 0.34`, `FRICTION = 0.62`, `SETTLE_HOLD = 1.4`, `FADE = 1.1`) are module-private, not exported — they are tuned as a set for snappy low-poly debris, not meant as per-game knobs.

package/docs/api/utils-decals.md

@@ -0,0 +1,188 @@
+# Core Utils & DecalField
+
+Two small core modules:
+
+- `src/core/utils.js` — shared math/noise helpers and scratch objects used across the engine.
+- `src/core/decalField.js` — `DecalField`, a portable ground/surface decal system (blood splats, scorch marks, sigils, footprints) with a ring-buffer budget.
+
+Both are re-exported from `src/index.js` (e.g. `export { DecalField } from './core/decalField.js'`).
+
+---
+
+## utils.js
+
+Small shared helpers. Imports `three/webgpu` and `ImprovedNoise` from three's addons.
+
+### Exports
+
+#### `noise: ImprovedNoise`
+
+A single shared `ImprovedNoise` instance. `fbm` samples it; you can sample it directly with `noise.noise(x, y, z)`.
+
+#### `mulberry32(seed) → () => number`
+
+Deterministic pseudo-random generator for reproducible world generation. Returns a function that yields floats in `[0, 1)`. The seed is coerced with `seed >>> 0`, so any number is accepted; the same seed always produces the same sequence. Use this — not `Math.random()` — anywhere world-gen output must be reproducible across runs.
+
+```js
+const rng = mulberry32(1234);
+rng(); // same value every run for seed 1234
+```
+
+#### `fbm(x, z, octaves = 4, lacunarity = 2, gain = 0.5, scale = 0.01) → number`
+
+Fractal Brownian motion over the shared `noise` instance, sampled in the XZ plane. Each octave samples `noise.noise(x * freq, z * freq, 7.31 + i * 13.7)` — the third coordinate is a fixed per-octave slice offset, so octaves decorrelate but the field is fully determined by `(x, z)` and the parameters. The result is normalized by the total amplitude (`sum / norm`), so output stays in roughly `[-1, 1]` regardless of octave count.
+
+#### `clamp(v, a, b) → number`
+
+`Math.min(b, Math.max(a, v))`.
+
+#### `lerp(a, b, t) → number`
+
+`a + (b - a) * t`.
+
+#### `smoothstep(a, b, t) → number`
+
+Classic Hermite smoothstep: clamps `(t - a) / (b - a)` to `[0, 1]`, then `x * x * (3 - 2x)`. Note the argument order: edges first, value last.
+
+#### `dist2D(ax, az, bx, bz) → number`
+
+Euclidean distance in the XZ plane via `Math.sqrt(dx*dx + dz*dz)`.
+
+> **Perf note (from the source):** `Math.hypot` is 5–10x slower in V8 — this is THE hot distance helper. Do not "clean it up" to `Math.hypot`; it is called constantly in hot paths.
+
+#### `angleLerp(a, b, t) → number`
+
+Shortest-arc angle interpolation for smooth turning. Wraps the delta into `(-π, π]` before lerping, so turning from `0.1` to `2π - 0.1` goes the short way through 0 instead of spinning almost a full turn.
+
+#### `tmpV1`, `tmpV2`, `tmpV3: THREE.Vector3` · `tmpQ1: THREE.Quaternion`
+
+Shared scratch objects for allocation-free math in per-frame code.
+
+### Usage example
+
+```js
+import { mulberry32, fbm, dist2D, angleLerp, clamp, tmpV1 } from './core/utils.js';
+
+const rng = mulberry32(worldSeed);            // reproducible per seed
+const h = fbm(wx, wz, 5, 2, 0.5, 0.008);      // terrain height sample, ~[-1, 1]
+
+// hot path: chase steering
+const d = dist2D(enemy.x, enemy.z, player.x, player.z);
+if (d < aggroRange) {
+  const want = Math.atan2(player.x - enemy.x, player.z - enemy.z);
+  enemy.heading = angleLerp(enemy.heading, want, clamp(turnRate * dt, 0, 1));
+}
+
+tmpV1.set(enemy.x, 0, enemy.z);               // scratch — do not retain
+```
+
+### Gotchas
+
+- **`dist2D` over `Math.hypot`, always.** The 5–10x V8 penalty is why this helper exists; it is the engine's hot distance function.
+- **`mulberry32` for anything that must be reproducible.** World generation is seeded through it; mixing in `Math.random()` breaks determinism.
+- **`tmpV1/2/3` and `tmpQ1` are shared module-level scratch.** Never store them, return them, or hold them across a call that might also use them — values are clobbered by the next user. Copy out if you need to keep a result.
+- **`fbm` samples a fixed 3D slice** (`7.31 + i * 13.7` per octave); two calls with identical args always match, and octaves don't self-correlate.
+- **`smoothstep(a, b, t)`** takes edges first — not the `(t)`-only GLSL convenience form.
+
+---
+
+## decalField.js
+
+`DecalField` — portable ground/surface decals for the unity-vfx-webgpu format. Lays flat textured quads on the surface they are projected onto, oriented to the surface normal, with fade-in/out over life and a ring-buffer budget. Contains no game-specific code.
+
+**These are simple laid-flat quads, NOT true projected decals** — there is no mesh-conforming UV projection. They are cheap, WebGPU-safe, and enough for a flat-ish ground surface. On sharply curved or stepped geometry a large decal will float or clip.
+
+### `class DecalField`
+
+#### `constructor(scene, { loadTexture, textureBase = '', max = 128 } = {})`
+
+Injection points — the field owns no loader or scene of its own:
+
+- `scene` — a `THREE.Scene` (or any `Object3D` container) that decal meshes are added to / removed from.
+- `loadTexture(nameOrUrl) → Promise<Texture>` — injected texture loader. All texture I/O goes through this.
+- `textureBase` — when set, bare basenames in recipes resolve to `${textureBase}/${name}.png` (normal maps too). When absent, the basename is passed to `loadTexture` unchanged.
+- `max` — ring-buffer budget. When the `(max + 1)`th decal is added, the oldest is evicted (removed from scene, geometry and material disposed).
+
+Public state: `recipes` (name → recipe), `textures` (basename → `THREE.Texture` or `null` on load failure), `items` (active decals, oldest first — the ring buffer).
+
+#### `async load(decalRecipes)`
+
+Stores the recipe table and pre-resolves every texture (and normal map) referenced by any recipe, via the injected `loadTexture`. A failed load warns `[decal] missing tex <name>` and stores `null` — later `add()` calls for that recipe render an untextured tinted quad rather than throwing. Call once at init, before `add()`.
+
+**Recipe schema** (all fields optional):
+
+| Field | Type | Meaning |
+|---|---|---|
+| `tex` | string | Albedo texture basename/URL |
+| `norm` | string | Normal-map basename (preloaded — see gotchas) |
+| `sz` | `[min, max]` | Base size range in metres, sampled uniformly per spawn (default `[1, 1]`) |
+| `aspect` | number | Width = `size * aspect`, height = `size` (default 1, square) |
+| `tint` | `[r, g, b, a]` | Authored color/alpha multiplier (default `[1,1,1,1]`) |
+| `blend` | `'a'` | Additive blending; anything else = normal blending |
+| `rot` | `'rand'` \| degrees | Spin about the surface normal |
+| `yOffset` | number | Lift along the normal in metres (default `0.02`) |
+| `life` | number | Seconds until auto-removal; `0`/absent = persistent |
+| `fade` | `[in, out]` | Fade-in / fade-out durations in seconds |
+
+#### `add(name, { pos, normal = [0, 1, 0], scale = 1, rot, color } = {}) → { decal, remove } | null`
+
+Lays a decal from recipe `name` at world `pos` (accepts `{x,y,z}` or `[x,y,z]`), oriented so its face points along `normal` (an `[x,y,z]` array; degenerate normals fall back to `+Y`). Returns `null` if the recipe doesn't exist.
+
+- `scale` multiplies the authored size.
+- `rot` overrides the recipe's rotation (`'rand'` or degrees).
+- `color` multiplies the authored tint — accepts an `[r,g,b,(a)]` array, a `THREE.Color`, or anything `new THREE.Color(color)` accepts (only arrays can scale alpha).
+
+Internals worth knowing:
+
+- Geometry is a fresh `PlaneGeometry`; three's plane faces `+Z`, so orientation is `setFromUnitVectors(+Z, normal)`, then the spin quaternion is premultiplied about the normal.
+- Material is `MeshBasicMaterial` with `transparent: true`, `depthWrite: false`, `polygonOffset` (`factor/units = -4`), `DoubleSide`, `fog: false`. polygonOffset beats z-fighting against the surface the decal lies on; depthWrite off + transparent makes overlapping splats blend instead of clipping each other.
+- Position is lifted along the normal by `yOffset` (default 0.02 m) as a second z-fighting guard.
+- Opacity spawns at the correct first-frame alpha — `0` when fading in — so decals never pop for one frame at full alpha.
+- After pushing, the ring buffer evicts oldest items past `max` (scene remove + geometry/material dispose).
+
+The returned handle's `remove()` deletes that specific decal early, regardless of its life.
+
+#### `update(dt)`
+
+Advance ages, apply fades, expire dead decals. Iterates backwards so expiry splices are safe. `life > 0` decals are disposed when `age >= life`; fade-in ramps alpha up over `fade[0]`, fade-out ramps down over the last `fade[1]` seconds. Persistent decals (`life` 0/absent) fade in and never fade out. **Must be called every frame** for fades and expiry to happen.
+
+#### `clear()`
+
+Dispose every active decal and empty the buffer (level unload / restart).
+
+### Usage example
+
+```js
+import { DecalField } from 'sindicate';
+
+const decals = new DecalField(scene, {
+  loadTexture: (url) => textureLoader.loadAsync(url),
+  textureBase: 'assets/decals',   // 'blood' -> assets/decals/blood.png
+  max: 96,
+});
+
+await decals.load({
+  blood:  { tex: 'blood',  sz: [0.6, 1.2], rot: 'rand', tint: [0.7, 0.05, 0.05, 0.9], life: 20, fade: [0.1, 4] },
+  scorch: { tex: 'scorch', sz: [1.5, 2.0], rot: 'rand', blend: 'a', life: 0, fade: [0.2, 0] }, // persistent
+});
+
+// on hit:
+const h = decals.add('blood', { pos: hit.point, normal: [hit.normal.x, hit.normal.y, hit.normal.z], scale: 1.3 });
+// h.remove() to delete early
+
+// per frame:
+decals.update(dt);
+```
+
+### Gotchas
+
+- **Not projected decals.** Flat quads oriented to a single normal — intentional: cheap and WebGPU-safe. Don't expect them to wrap stairs, rocks, or walls-meeting-floors.
+- **Ring buffer is the only budget.** Nothing throttles `add()`; spamming it just evicts your oldest decals (including "persistent" ones — persistence only means no lifetime expiry, not eviction immunity). Size `max` for the worst-case burst you care about.
+- **Call `update(dt)` every frame.** Fades and `life` expiry live there; skip it and timed decals never die.
+- **`load()` before `add()`.** `add()` reads `this.textures` synchronously; unresolved textures render as untextured tinted quads (missing textures warn once at load, then silently degrade).
+- **Two z-fighting defenses, keep both.** `polygonOffset(-4, -4)` plus the `yOffset` lift along the normal (default 0.02 m). Removing either brings the flicker back on coplanar ground.
+- **`depthWrite: false` is load-bearing.** Overlapping splats must blend; with depth writes on they clip each other.
+- **First-frame alpha is set at spawn** (`0` when `fadeIn > 0`, else the composed alpha) specifically so decals never pop at full opacity for a frame before the first `update()`.
+- **`norm` maps are preloaded but not currently applied.** `load()` fetches them into `this.textures`, but `add()` builds a `MeshBasicMaterial` with only `map` — the recipe field is plumbed for the format, not yet wired into the material.
+- **Per-decal geometry and material.** Each `add()` allocates a `PlaneGeometry` + `MeshBasicMaterial`; both are disposed on eviction/expiry/`clear()`. If you bypass `remove()`/`clear()` and pull meshes out yourself, you leak GPU resources.
+- **Spawn randomness uses `Math.random()`** (size within `sz`, `'rand'` rotation) — decal placement is not part of the deterministic `mulberry32` world-gen path.

package/docs/api/water.md

@@ -0,0 +1,143 @@
+# Water
+
+`src/world/water.js`, `src/world/waterNoise.js`
+
+Low-poly water with **see-through depth**. The core techniques are ported from Braffolk's fable5-world-demo `WaterMaterial` (same three.js/TSL stack), restyled for the faceted Synty look. The surface refracts the actual rendered scene behind it (`viewportSharedTexture`) with per-channel Beer–Lambert absorption by water-column thickness, and reflects the sky-phase colours (`uSkyCol` / `uHorizonCol` from `weatherUniforms.js`) by fresnel — so riverbeds and wading legs show through the shallows, deep water goes murky, and the water tracks dawn/dusk/night/moor-dread for free. Kept from the house style: the gentle faceted swell, per-vertex `aDepth` (foam + inside-gating), the pond's `rClip` sprawl guard, and dive-under-terrain shoreline geometry.
+
+Both materials are `THREE.MeshBasicNodeMaterial` (TSL node materials, WebGPU renderer) with `transparent: true, depthWrite: true`.
+
+## Exports
+
+### `waterMaterial(options = {}) → THREE.MeshBasicNodeMaterial`
+
+Still water: lakes, ponds, the sea.
+
+```js
+waterMaterial({
+  foam       = 0xeef8f6,  // foam colour
+  shallow    = 0x3f96a8,  // baked-ramp shallow colour (only used when refract: false)
+  deep       = 0x114f78,  // baked-ramp deep colour   (only used when refract: false)
+  maxDepth   = 2.0,       // aDepth at which the baked ramp reaches `deep`
+  foamDepth  = 0.18,      // water depth (m) under which shoreline foam appears
+  rClip      = 21,        // pond radius clip — a number, or 'attribute' (see below)
+  waveHeight = 0.16,      // vertical swell amplitude (local Z)
+  waveLen    = 9,         // swell wavelength (m)
+  waveSpeed  = 0.7,       // swell + foam animation rate
+  refract    = true,      // false = cheap baked shallow→deep ramp, no viewport copy
+})
+```
+
+**Geometry contract.** The mesh is authored in local space with the pond centred at the local origin: `positionLocal.xy` is the water plane (so `positionLocal.xy.length()` is distance from pond centre) and local Z is up — the swell is *added* to the baked local Z. Shore vertices are baked **below** the terrain so the sheet dives under dry ground and the waterline is the natural surface intersection. Required attributes:
+
+| attribute | type  | meaning |
+|-----------|-------|---------|
+| `aDepth`  | float | baked water depth at the vertex; 0 on the dry dive-skirt verts (gates opacity, drives foam and the non-refracting colour ramp) |
+| `aRClip`  | float | per-vertex clip radius — **only** when `rClip: 'attribute'` |
+
+**`rClip` and material sharing.** `rClip` may be a number (one body per material — the sea) or the string `'attribute'`: lakes bake their radius per-vertex (`aRClip`) so **every lake shares one material**. This matters for cost, not just convenience — each distinct refracting material compiles its own `viewportSharedTexture` sampling, and each ViewportTexture node pays its own `copyFramebufferToTexture` per frame. N lakes on one material is **1 framebuffer copy, not N**.
+
+**`refract: false`** replaces the viewport refraction with a baked `shallow → deep` colour ramp keyed on `aDepth / maxDepth`. Used for the sea: too big to pay viewport copies for water you can't see into anyway.
+
+Foam appears wherever the water *ends* — at the shallow waterline (`aDepth → 0`) **and** at the clip radius — both edges wave-jittered.
+
+### `riverMaterial(options = {}) → THREE.MeshBasicNodeMaterial`
+
+Flowing river water: a ribbon mesh (built in `zones.js`) at world Y, `side: THREE.DoubleSide`. Same see-through refraction + sky fresnel as the lakes; a flowmap ripple layer and advected foam make the current read.
+
+```js
+riverMaterial({
+  foam      = 0xeef8f6,
+  shallow   = 0x4494a4,  // baked-ramp colours, only used when refract: false
+  deep      = 0x11557a,
+  maxDepth  = 1.3,
+  foamDepth = 0.2,       // NOTE: currently accepted but unused in the body
+  flowSpeed = 0.5,       // NOTE: currently accepted but unused in the body
+  refract   = true,
+})
+```
+
+Rivers use a denser in-scatter murk than lakes (`vec3(0.22, 0.30, 0.32)` vs `vec3(0.10, 0.16, 0.17)`) — their plain beds give refraction little to show until the riverbed-texturing pass lands, so the murk gives the stream a visible body.
+
+Required attributes:
+
+| attribute | type  | meaning |
+|-----------|-------|---------|
+| `aDepth`  | float | baked water depth; 0 on the dry dive-skirt verts |
+| `aFlow`   | vec2  | per-vertex downstream flow velocity (world XZ) — advects ripples and foam; its length scales ripple amplitude |
+| `aDrop`   | float | baked downstream water-level drop — rapids foam keys on this, so real rapids appear exactly where the stepped monotonic river profile steps down |
+
+### `waterNoiseTexture() → THREE.DataTexture`
+
+`src/world/waterNoise.js`. CPU-baked tileable water noise — braffolk's NoiseBake, boot-time edition (~10 ms). A **cached singleton**: the first call bakes, every later call returns the same texture (also consumed by `grass.js` — do not dispose it per-material).
+
+One 256² RGBA **float** texture, `RepeatWrapping`, linear min/mag filters:
+
+| channel | contents |
+|---------|----------|
+| `r` | fbm (three periodic value-noise octaves, 8/16/32 lattices, weights 0.55/0.3/0.15) |
+| `g` | decorrelated fbm (different seed + offsets) — used for foam patterns |
+| `b`, `a` | d(fbm)/du, d(fbm)/dv — central differences, packed as `gradient * 0.02 + 0.5` |
+
+Because the gradients are pre-derived and packed, a ripple layer costs **one texture fetch** (the shader unpacks with `.zw.sub(0.5).div(0.02 * scale)`). The lattices use a deterministic LCG, so the bake is reproducible.
+
+## The viewport-refraction approach
+
+The internal `refraction(n, murk)` helper (shared by both materials) is where the see-through look comes from:
+
+1. **Sample the scene behind the surface.** `screenUV` is offset by the surface normal's XZ (`n.xz * refrK`) — the ripple/facet-driven refraction wobble. `refrK = clamp(9/dist, 0.04, 1) * 0.05` shrinks the offset with camera distance so far water doesn't shimmer wildly.
+2. **Depth-validate the offset UV.** The refracted sample's view-Z (via `viewportDepthTexture`) is compared against the water fragment's own Z. If the sample landed on geometry **in front of** the water (a wader, a bridge post — `zR > fragZ + 0.02`), the shader falls back to the straight `screenUV`. Without this, foreground geometry smears into the water surface.
+3. **Beer–Lambert absorption.** Water thickness along the view ray = `fragZ − zS` (metres, from the depth texture). Per-channel transmittance `T = exp(−1.3 · thick · σ)` with σ = `(0.55, 0.24, 0.17)` — UK water: red dies first, so depths go cool green-blue and murky by ~2.5 m.
+4. **Turbidity in-scatter.** `uSkyCol · murk` fills in what absorption removes (`col = scene·T + inscat·(1−T)`), so the murk brightens by day and dims at night automatically.
+5. **Vertical column.** `vDepth = thick · max(|viewDirY|, 0.06)` — the *vertical* water column, used for the per-pixel shoreline feather (mm-deep water fades over the bed) and shore foam.
+
+On top of the refracted base: fresnel-weighted sky reflection along the reflected ray, reproducing the sky dome's horizon→sky ramp, darkened ×0.78.
+
+## Flowmap ripples and foam (rivers)
+
+Faithful port of braffolk `WaterMaterial` 132–151 (ripples) and 283–308 (foam):
+
+- **No-sliding-texture flowmap:** two phases half a cycle apart (`ph1`, `ph2 = ph1 + 0.5`), each advecting the noise along `aFlow`, crossfaded by `w2 = |ph1 − 0.5| · 2` so each phase's snap-back is hidden. A small constant velocity `(0.045, 0.03)` is the breeze fallback where `aFlow` ≈ 0.
+- **One fetch per ripple layer:** slope comes straight from the pre-baked gradient channels. Two scales (0.9 and 3.4 tiles) sum into each layer. Ripple amplitude `0.007 + |aFlow| · 0.028` — their tuned value; the ripple normal is added **under** the facet silhouette (`normalize(facetN + (−slope.x, 0, −slope.y))`) so ripples wobble the refraction downstream without breaking the low-poly read.
+- **Foam:** two decorrelated advected noise scales are blended and then **multiplied** into clumpy patches — a single thresholded fbm slides as coherent stripes. The crossfade is variance-renormalised (`÷ sqrt(w2² + (1−w2)²)`) so foam coverage doesn't pulse at blend midpoints. Shore foam keys on the per-pixel water column (`R.vDepth`); rapids foam keys on the baked `aDrop`. Total foam is capped at 0.68.
+- **Opacity body term:** `smoothstep(0.1, 0.7, aDepth) · 0.55` guarantees the channel core always reads as *water*, not damp ground, even where refraction feathers thin.
+
+## Usage
+
+```js
+import * as THREE from 'three/webgpu';
+import { waterMaterial, riverMaterial } from './world/water.js';
+
+// ONE material for every lake — radius baked per-vertex means one
+// framebuffer copy per frame no matter how many lakes are visible.
+const lakeMat = waterMaterial({ rClip: 'attribute' });
+
+// Pond disc authored in local XY (centre at origin, local Z = up),
+// shore ring baked BELOW the terrain so the sheet dives under dry ground.
+geo.setAttribute('aDepth', new THREE.BufferAttribute(depths, 1)); // 0 on the dry skirt
+geo.setAttribute('aRClip', new THREE.BufferAttribute(radii, 1));
+const lake = new THREE.Mesh(geo, lakeMat);
+lake.rotation.x = -Math.PI / 2; // orient local +Z to world up
+scene.add(lake);
+
+// The sea: baked depth ramp, no viewport copy.
+const seaMat = waterMaterial({ refract: false, rClip: 4000 });
+
+// A river ribbon (geometry from zones.js: aDepth + aFlow + aDrop baked in).
+const river = new THREE.Mesh(riverGeo, riverMaterial());
+scene.add(river);
+```
+
+## Gotchas
+
+- **Fresnel uses a hard-flattened normal.** Braffolk's lesson: the reflectance weight must follow the *mean* surface — feed the tilted per-facet normal into `(1−cosθ)^5` and big facet tilts saturate it into a white ice sheet. `fresnel()` flattens X/Z ×0.25 for the mix weight only; the full normal still shapes the reflected sky colour and shimmer, so the facets still sparkle. Related: fresnel is capped ×0.5 so the refracted bed always survives underneath, and river `rippleAmp` is tuned small for the same reason — bigger amplitudes saturate fresnel into the same white sheet.
+- **Refraction UV must stay depth-validated.** A refracted sample landing on geometry in front of the water must fall back to the straight UV, or foreground geometry (a wader, a bridge post) smears into the surface. If you touch `refraction()`, keep the `zR > fragZ + 0.02` guard.
+- **One material = one framebuffer copy.** Every distinct refracting material compiles its own `viewportSharedTexture` sampling and pays its own `copyFramebufferToTexture` per frame. Share materials across bodies via `rClip: 'attribute'` + `aRClip`; never instantiate a refracting material per lake.
+- **Build the expensive nodes once.** In both materials the shared nodes (`R`, `skyShared`, `fresShared`, the facet normal) are constructed *outside* `colorNode`/`opacityNode` and referenced from both — separate calls would duplicate the viewport-texture sampling in the compiled shader. Preserve this structure when editing.
+- **`refract: false` exists for a reason.** The sea is too big to pay viewport copies for water you can't see into — it takes the cheap baked shallow→deep ramp instead.
+- **Sky reflection is darkened ×0.78.** Real water reflects darker than the sky (micro-roughness), and a full-brightness midday sky whites out narrow streams seen at grazing angles.
+- **The whole surface is dimmed by sky brightness** (base + foam, not just the reflection): `lit = clamp(luma(uSkyCol)·0.55, 0.22, 1)`. Without it water glows white at dusk/night; the 0.22 floor keeps it readable in darkness.
+- **Shoreline geometry does the waterline.** Shore verts are baked below the terrain; the swell is *added* to that baked local Z, so the waterline is the natural mesh/terrain intersection — don't "fix" verts that appear underground.
+- **River murk is deliberately denser than lake murk** — the plain riverbeds give refraction little to show until the riverbed-texturing pass lands.
+- **`riverMaterial`'s `foamDepth` and `flowSpeed` options are currently dead** — accepted in the signature but not referenced in the body (foam thresholds and flow timing are hard-coded to braffolk's tuned constants).
+- **Foam must multiply, not threshold.** Two decorrelated advected scales multiplied give clumpy patches; a single thresholded fbm slides past as coherent stripes. Keep the variance-renormalised crossfade or coverage pulses at blend midpoints.
+- **`waterNoiseTexture()` is a shared singleton** (also used by `grass.js`); its gradients are packed as `g·0.02 + 0.5`, so any consumer must unpack with `.sub(0.5).div(0.02 · scale)` — the 0.02 constant appears on both sides of the bake.

package/docs/api/wind-weather-uniforms.md

@@ -0,0 +1,105 @@
+# Wind & Weather Uniforms
+
+Modules: `src/world/wind.js`, `src/world/weatherUniforms.js`
+Both are re-exported from the engine root (`src/index.js`).
+
+Together these two files are the single source of weather truth for the whole scene. `Wind` is a global wind simulation ticked once per frame on the CPU; `weatherUniforms.js` is a set of module-level TSL uniform singletons that carry the current weather/sky state into every shader that opts in. Everything that should lean on the weather reads from here instead of rolling its own — CPU consumers (e.g. tumbleweeds) read `wind.vx/vz` directly, GPU consumers (grass sway, rain slant, water tint, ground wetness) read the shared uniforms.
+
+## Why uniforms decouple build order
+
+The uniforms are **module-level singletons** created at import time. Terrain, grass, water, and the Weather/sky systems may be constructed in any order — some materials are built before the weather system exists, some after — but because every one of them imports the *same* uniform node objects, they all reference identical GPU state no matter who was built first. The writer (Weather, sky, `Wind`) just mutates `.value` each frame and every material that baked the node into its shader graph sees the change. No registration step, no "pass the weather system into the terrain constructor" plumbing, no ordering constraint.
+
+## Exports — `world/wind.js`
+
+### `class Wind`
+
+One slowly-wandering heading plus a gusting strength. Deterministic layered sines drive both the drift and the gusts — smooth, no per-frame RNG jerks, and identical after a reload.
+
+```js
+const wind = new Wind();   // publishes initial state to uWindDir/uWindStr immediately
+wind.update(dt);           // call once per frame; dt in seconds
+```
+
+**`constructor()`** — initializes state and immediately publishes to the shared uniforms (so shaders see sane wind even before the first `update`).
+
+**`update(dt)`** — advances the internal clock, recomputes heading/gust/speed, republishes. Call exactly once per frame.
+
+Instance fields (all readable; treat as read-only outside the class):
+
+| Field | Meaning |
+|---|---|
+| `t` | accumulated sim time (seconds) |
+| `baseAngle` | the PREVAILING heading, fixed at `0.7` rad (~SE-ish); the wind only veers gently around it |
+| `angle` | current heading the wind blows **toward** — radians on the ground plane, `atan2(z, x)` convention. Oscillates `baseAngle ± ~0.47` rad (~±27°) |
+| `base` | mean speed, `1.6` m/s — a light breeze for the CPU consumers, not a gale |
+| `gust` | current gust factor, swells and lulls between ~`0.12` and ~`1.05` |
+| `speed` | current speed, `base * (0.5 + 0.85 * gust)` ≈ 0.96–2.36 m/s |
+| `x`, `z` | unit heading components (`cos(angle)`, `sin(angle)`) |
+| `vx`, `vz` | velocity in m/s (`x * speed`, `z * speed`) — what CPU consumers integrate against |
+
+**`_publish()`** *(private)* — copies `x/z` into `uWindDir` and `gust` into `uWindStr`. Called from the constructor and every `update`; you never call it yourself.
+
+## Exports — `world/weatherUniforms.js`
+
+Every export is a `uniform(...)` node from `three/tsl` (three/webgpu build). Writers mutate `.value` on the CPU; readers compose the node into TSL material graphs.
+
+| Uniform | Initial value | Range / meaning | Written by | Read by |
+|---|---|---|---|---|
+| `uWet` | `0` | 0 dry … 1 soaked — rain darkens the ground | Weather system, **eased** each frame so the ground soaks/dries gradually | `grass.js` (blade colour darkens toward ×0.7 when soaked); terrain ground darkening, puddles, and sheen (per source comments — host-game side) |
+| `uCover` | `0` | 0 bare … 1 snow-covered | Weather system, eased so snow builds/melts gradually | `grass.js` (whitens blade tips toward `vec3(0.95, 0.96, 1.0)`); up-facing terrain whitening (host-game side) |
+| `uDayness` | `1` | 0 night … 1 day | `sky.js` (host-game side) | UNLIT baked-albedo materials (impostors) — dims them so they stop glowing at night |
+| `uSkyCol` | `Color(0x7fb2e5)` | current sky-phase zenith colour | `sky.js` | `water.js` — underwater inscatter tint, sky-reflection gradient, and a luminance clamp so water doesn't glow at dusk/night |
+| `uHorizonCol` | `Color(0xdfe9d8)` | current horizon colour | `sky.js` | `water.js` reflections — water tracks day/dusk/night for free |
+| `uSunDir` | `Vector3(0.3, 0.8, 0.3)` | current key-light direction (sun by day, **moon by night**) | sky/lighting (host-game side) | `grass.js` backlight (`dot(viewDir, uSunDir)^4` rim on blade tips), etc. |
+| `uRain` | `0` | 0 dry … 1 downpour — the rain **falling right now** | Weather system | splash effects (host-game side). See gotcha below — this is deliberately *not* `uWet` |
+| `uRainT` | `0` | seconds, running **while it rains** — the ground's rain clock | Weather system | puddle ripple rings on the ground, so they beat in time with the rain actually falling |
+| `uCloudiness` | `0` | 0 fair … 1 storm deck | `weather.js` — **leads** the rain/snow | sky/cloud rendering, so the sky thickens *before* precipitation and clears after |
+| `uWindDir` | `Vector2(1, 0)` | unit heading the wind blows **toward**, on the ground plane (XZ) | `world/wind.js`, every frame | `grass.js` sway direction + gust-front advection; rain slant (host-game side) |
+| `uWindStr` | `0.4` | 0 calm … ~1 gusting | `world/wind.js`, every frame | `grass.js` gust amplitude; rain slant scaling. CPU consumers (tumbleweeds) read `wind.vx/vz` instead |
+
+In this repository the in-engine importers are `wind.js` (writer), `grass.js`, and `water.js`. The Weather/sky/terrain writers and readers named in the source comments live host-game side (the systems ported onto the engine); the whole point of the singleton design is that they wire up to these exact nodes whenever they're built.
+
+## Usage example
+
+A frame loop driving the wind, a CPU consumer riding it, and a custom TSL material opting into the shared weather:
+
+```js
+import * as THREE from 'three/webgpu';
+import { mix, float } from 'three/tsl';
+import { Wind, uWet, uWindDir, uWindStr } from 'sindicate';
+
+const wind = new Wind(); // uniforms are already valid after this line
+
+// A custom material that darkens when the ground is soaked and shivers with the
+// global gusts — same weather every other material sees, regardless of when
+// this material was built relative to the Weather system.
+const mat = new THREE.MeshStandardNodeMaterial();
+mat.colorNode = baseAlbedo.mul(mix(float(1.0), float(0.7), uWet));
+// ...positionNode can offset along uWindDir scaled by uWindStr for sway...
+
+function tick(dt) {
+  wind.update(dt); // once per frame, before consumers integrate
+
+  // CPU consumer: roll a prop downwind
+  crate.position.x += wind.vx * dt * 0.2;
+  crate.position.z += wind.vz * dt * 0.2;
+
+  // Host-game weather system easing a shared value (shaders pick it up next draw)
+  uWet.value += (stormTargetWet - uWet.value) * Math.min(1, dt * 0.3);
+}
+```
+
+## Gotchas
+
+- **Veer, don't circle (bug history).** `Wind.update` sets the heading *directly* as prevailing ± a bounded oscillation (~±27°). The old code *integrated* sines (`angle += … * dt`); the low-frequency term summed to several radians over time and swept the wind all the way around the compass ("pushed things in a 360, weird"). If you touch the heading math, keep it a bounded function of `t`, never an accumulation.
+- **`uRain` is not `uWet`, and the difference is the whole point.** The ground stays dark and slick for a good while after a storm passes (`uWet` eases down slowly), but the moment the rain stops, drops stop landing (`uRain` drops). Splashes read `uRain`; puddles and sheen read `uWet`. Don't collapse them into one value.
+- **Why `uRainT` exists at all.** The Weather system had a `uTime` of its own, but it was private to the rain particles — the ground could not see it, so the puddle rings could not move. `uRainT` is the shared rain clock: it only advances while it rains, so ground ripples beat in time with the falling rain.
+- **`uCloudiness` leads precipitation.** The weather system raises cloudiness *before* rain/snow starts and clears it after they stop, so the sky thickens ahead of a storm. Preserve that lead if you write your own weather driver.
+- **Wind speed is tuned, not physical.** `base = 1.6` m/s is deliberately a light breeze — at higher values the tumbleweeds "rolled too fast". Retune consumers, not the shared wind, if something moves at the wrong speed.
+- **`angle` is the heading the wind blows TOWARD** (radians on the XZ ground plane, `atan2(z, x)`), and `uWindDir` follows the same convention. Note `uWindDir` is a `Vector2` where `.y` holds world **Z** — grass uses `uWindDir.y` for its Z sway.
+- **`uWindStr` publishes the raw gust factor** (`wind.gust`, 0.12–1.05), not `wind.speed`. Shader consumers scale it themselves; CPU consumers wanting real velocity must use `wind.vx/vz`.
+- **Deterministic on purpose.** The wind is layered sines of `t` with no RNG — smooth (no per-frame jerks) and identical after a reload. Don't add randomness to it.
+- **Tick once, early.** Call `wind.update(dt)` exactly once per frame, before anything integrates against `vx/vz`, or CPU and GPU consumers will see different wind for that frame. The constructor publishes too, so uniforms are never stale-default even before the first update.
+- **Ease the weather uniform writes.** `uWet`/`uCover` are meant to be eased toward targets each frame (soak/dry, build/melt), not snapped — materials render whatever `.value` holds, so a snap is a visible pop.
+- **`uSunDir` is the key light, not literally the sun** — it points at the moon at night. Grass backlight and similar effects rely on it always being the current key light.
+- **Water clamps `uSkyCol` luminance** (floor 0.22) so lit water doesn't go pitch black when the sky colour goes near-black at night, and doesn't glow white at dusk — keep sky colours flowing through `uSkyCol`/`uHorizonCol` rather than baking them into water.

package/docs/contracts/render.md

@@ -0,0 +1,32 @@
+# Contract: render & scene
+
+**Status:** draft (step 3 — extraction from western main.js in progress).
+
+## The facet
+
+- `engine.render.scene` — attach/detach root for game objects (systems stop touching a raw `game.scene`).
+- `engine.render.camera` — read access. Writing the camera happens ONLY in the camera-overrides phase (time-feel contract §7); anything else is an ordering bug by definition.
+- `engine.render.frustum` — the per-frame culling frustum, built ONCE per unpaused frame after camera-overrides. **May be null; null means "don't cull".** Consumers must treat null as visible — the engine nulls it deliberately when a stale frustum would mis-cull (e.g. a hand-ticked NPC during a paused dialogue whose two-shot faces away from last frame's camera).
+- `engine.render.project(v3, out2)` — world→screen for HUD nameplates/markers (UI never does its own matrix math).
+- `engine.render.post` — the PostProcessing instance; `post.gradeAmount` is the game's one live dial (renderer API doc).
+
+## The single render path
+
+`renderFrame()` is the ONE call that puts pixels on screen — shared by the boot warm-up and the loop tick. Never add a second render call: every code path that renders must pay the same pipeline state, or the first frame through the "other" path compiles pipelines mid-play.
+
+## Exposure write-gating
+
+`renderer.toneMappingExposure` (and any renderer-level uniform-adjacent state) is written **only when the value actually changes**. Redundant writes are not free on WebGPU — the gate lives engine-side so games can "set" exposure every frame safely.
+
+## Warm-up phases (PERF LAW, mechanical)
+
+Boot runs, behind the loading screen, in order:
+1. `warmTextures()` — GPU pre-upload of every cached texture (kills ~75ms first-sight upload hitches).
+2. `warmRenderHidden()` / `warmUpFX()` — force-visible + `compileAsync` every hidden, culled, or count-0 pipeline (pooled VFX, UI-triggered materials) so NO pipeline compiles after boot.
+3. The 360° settle sweep — the camera sweeps a full turn rendering via `renderFrame()`, initializing per-object GPU state along every bearing.
+
+A dev-mode watchdog flags any pipeline compile after warm-up completes, with a stack — that's a spawned-uncached asset or a lazily-built material, and it WILL become a multi-second WebGPU freeze on a player's machine.
+
+## Freeze profiler
+
+The engine stamps phase timings each frame into a ring buffer; a frame over budget dumps the per-phase breakdown (and, with the dev plugin, sinks JSONL to disk). Games get it for free — it exists because "the game hitched once on my machine" is otherwise undebuggable.