Visual: add real Water motion, foam, and atmospheric fog

[ael-dev3]

Summary

This draft adds the renderer-only Water presentation layer requested by PR 5. It starts from protected main at 582441671f7ad41158ef7117d28985608d3fa96a and ends at a68fa1b58ee894ee5796d831a6a90ac2d79ff57a.

A separate PR-4 head was not present in the remote refs when this work started. The branch therefore uses the reviewed Water v1/revision-v1 foundation on protected main; it does not copy an unreviewed candidate branch. The canonical Water rows, topology, layout/revision digests, activation state, and authority paths are unchanged.

What was wrong

The previous layer used duplicated center-plus-six-corner hexes, filled river hexes, fixed regime colors, upward normals, and fragment-only sine glimmer. Its fog path blended only 62% toward the horizon, so full-fog cells were not guaranteed to become identical to the fog background. A translucent skirt hid the edge mechanically, and Water time was driven only by local elapsed scheduler time.

What changed

• Added deterministic connected ocean/lake geometry with shared world-space boundary vertices and quality-specific static subdivision (High 3, Balanced 2, Reduced 1).
• Converted the 12 canonical ordered river paths into flow-aligned ribbons with source/mouth caps, bounded 0.50–0.72 world-unit width, accumulation variation, flow attributes, and bounded terrain-contact clearance. Canonical cell keys remain the selection identity.
• Added bounded world-space ocean wave components (8/5/0 by quality), small flow-aligned river motion, shader-side displacement, and analytic normals from the same displacement function.
• Added procedural depth absorption, restrained Fresnel, sun glitter, shore foam, crest foam, river-edge/rapid foam, and mouth/source accents. No texture or reflection target was added.
• Added exact full-fog replacement at canonical full-fog cells and a single opaque outer curtain spanning the reviewed vertical bounds. Full-fog ray hits remain non-interactive.
• Added a pure shared phase resolver anchored to the persisted environment boundary, environment epoch, validated body seed/preset, and synchronized server time when available. First synchronization converges clients to the same target; later large corrections ease by at most 0.18 seconds per sample. Reduced motion freezes deterministically. No raw Date authority or per-frame database write.
• Reused the existing demand-driven ambience scheduler. Water requests cadence through the existing scheduler; it does not add a RAF loop.
• Preserved PR-4-style triangle-to-cell mapping, foreground selection arbitration, selected-cell outline, and static/scene fallback behavior.
• Exposed the already-persisted realm_environment_v1.updatedAt through the validated client projection. No schema, generated binding, topology, seed, or revision activation change is included.

Budgets and measured assertions

Quality	Triangle ceiling	Draw ceiling	Wave components	Water cadence
High	220,000	5	8	up to 30 fps
Balanced	105,000	5	5	22 fps
Reduced	35,000	4	0	static

The focused geometry tests assert all quality ceilings, finite flow attributes, connected/subdivided surfaces, continuous 12-ribbon coverage (800 ribbon triangles for the 400 active river cells), full-fog attributes, disposal, and triangle-to-cell selection mapping.

Fog/boundary proof

proveRealmWaterBoundaryCoverage is a pure QA helper that requires the two-cell hidden buffer, a maximum legal wave displacement of 0.35, and curtain bounds covering the projected vertical range. The shader sets the final Water lighting input to the fog horizon when the canonical fog factor is 1. Full-fog selection is rejected before interaction dispatch.

Validation

Passed:

• focused Water/phase/navigation/scene/connection suite: 89 tests;
• tsc --noEmit -p tsconfig.app.json;
• tsc -b --force;
• Vite production build;
• runtime asset, production-dist exclusion, and committed SpacetimeDB binding verification;
• git diff --check.

The full repository suite ran with 1,731 passing tests. Twenty unrelated subprocess/browser-boundary assertions failed because this sandbox denies loopback listen for the existing tsx and local browser probes (EPERM); none are in the changed Water path. The rendered WebGL harness was also run and failed closed for the same loopback/browser boundary, so no screenshots or clips are attached from this environment. Please rerun the repository browser matrix on a host with local Chrome and loopback permissions, including 1920x1080, 1280x720, tablet, 390x844, reduced quality, reduced motion, fog-depth sectors, river source/mouth, and selection cases.

Non-goals

No SpacetimeDB publication, Water reseed, revision activation, schema expansion, topology change, passability/movement/resource/worker/combat rule, lake restoration for the active revision, boats, swimming, fishing, bridges/fords, currents, flooding, weather, naval combat, WebGPU/FFT migration, copied external shader/art, Pages deploy, tag, release, or merge.

Residual risks

• The live scene currently receives the persisted environment boundary; a synchronized server-time estimate can be supplied by the host when that clock is available. Without it, Water advances from the validated server boundary using monotonic scene time.
• Browser/WebGL screenshot and mobile acceptance remain to be rerun outside this sandbox because the local harness cannot open its loopback/Chrome boundary here.
• Three.js shader chunks are guarded by explicit markers and fail closed to the existing Water-unavailable path if the reviewed contract drifts.

[ael-dev3]

Superseded by #95. The released water presentation is retained; the unused proof helper and standalone design prose were intentionally omitted.