@woosh/meep-engine 3.36.0 → 3.38.0

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -11,6 +11,7 @@ import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
 import { System } from "../../ecs/System.js";
 import { t64_announce_change } from "../../ecs/transform/t64_announce_change.js";
+import { TRANSFORM64_EVENT_PLACED } from "../../ecs/transform/TRANSFORM64_EVENT_PLACED.js";
 import { Transform64 } from "../../ecs/transform/Transform64.js";
 import { Interpolated } from "../../interpolation/Interpolated.js";
 import { body_id_index, BodyStorage } from "../body/BodyStorage.js";
@@ -1168,15 +1169,40 @@ export class PhysicsSystem extends System {
         assert.isNumber(rotation[2], 'rotation[2]');
         assert.isNumber(rotation[3], 'rotation[3]');
 
-        const idx = body_id_index(rigidBody._bodyId);
+        const body_id = rigidBody._bodyId;
+        if (!this.storage.is_valid(body_id)) return;
+
+        const idx = body_id_index(body_id);
         const transform = this.__transforms[idx];
-        if (transform === undefined) {
+        if (transform === undefined || this.__bodies[idx] !== rigidBody) {
             return;
         }
 
         transform.setTranslation(position[0], position[1], position[2]);
         transform.setRotation(rotation[0], rotation[1], rotation[2], rotation[3]);
 
+        const dataset = this.entityManager?.dataset;
+        const entity = this.storage.entity_at(idx);
+        if (dataset !== null && dataset !== undefined) {
+            // Snap interpolation before publishing the pose. Compose attached
+            // worlds before re-homing any of the body's collider leaves below.
+            const interpolated = dataset.getComponent(entity, Interpolated);
+            if (interpolated !== undefined && interpolated !== null) {
+                interpolated.snap = true;
+            }
+            transform.updateMatrix();
+            t64_announce_change(dataset, entity);
+
+            // Listeners can destroy/relink this body and immediately reuse its
+            // slot or entity id. Neither its replacement's leaves nor its
+            // placement listeners belong to this call. Check the generation
+            // as well as the references: a listener can relink the same objects.
+            if (rigidBody._bodyId !== body_id || !this.storage.is_valid(body_id)
+                || this.__bodies[idx] !== rigidBody || this.__transforms[idx] !== transform) {
+                return;
+            }
+        }
+
         if (rigidBody.kind !== BodyKind.Dynamic) {
             // Static AND Kinematic: the body itself never sleeps and __wake_body is a no-op for it,
             // so teleporting a support must instead wake what rested on it (old pose) and what it
@@ -1203,20 +1229,10 @@ export class PhysicsSystem extends System {
             this.__wake_body(rigidBody);
         }
 
-        // Flag a snap on the body's Interpolated component, if any: the
-        // InterpolationSystem keeps this pose rather than putting back what a render
-        // blend displaced, and rewrites the body's recent interpolation records with
-        // it, so the blend resumes from here instead of sliding across the jump.
-        const em = this.entityManager;
-        if (em !== null && em !== undefined) {
-            const dataset = em.dataset;
-            if (dataset !== null && dataset !== undefined) {
-                const entity = this.storage.entity_at(idx);
-                const interpolated = dataset.getComponent(entity, Interpolated);
-                if (interpolated !== undefined && interpolated !== null) {
-                    interpolated.snap = true;
-                }
-            }
+        if (dataset !== null && dataset !== undefined) {
+            // Motion consumers reset history at this pose; subsequent ordinary
+            // movement is still a sweep. Attachments forward the placement.
+            dataset.sendEvent(entity, TRANSFORM64_EVENT_PLACED);
         }
     }
 

package/src/shade/playground/water_refraction/README.md

@@ -0,0 +1,149 @@
+# Water refraction / AVBOIT playground
+
+Run `npm run dev --workspace @woosh/meep-engine` from the repository root and open
+`http://localhost:5173/src/shade/playground/water_refraction/index.html`.
+The page needs the renderer's usual WebGPU features, including subgroups and immediate data.
+It generates its fixtures and sprites locally; no external scene download is required.
+
+This uses `EntityManager`, the production `WaterSystem`, `ShadedGeometrySystem`, `LightSystem`,
+and `GPUParticleEmitterSystem`. The ribbon uses `DynamicMeshAVBOITChannel`. The terrain component
+holds the real CPU height field; a normal opaque meshlet floor visualizes the same field.
+Terrain tile streaming is deliberately outside this fixture. Water records through the production
+shared occupancy, warp, extinction volume, integral, four accumulators and single AVBOIT resolve.
+There is no playground water renderer or color overlay.
+
+## Controls and review
+
+Drag to orbit, right-drag to pan, wheel to zoom. Camera input is confined to the viewport.
+Pause freezes waves, particles and fixture motion; the camera remains interactive. Reset also replaces
+the particle components through the ECS lifecycle to start fresh emitter populations. Step advances
+one 1/60-second engine tick. Presets cover the shore, normal incidence, grazing views, thin posts,
+screen edges, the emergent-object/shoreline discontinuity view, and the deliberately unsupported
+below-interface view. The grazing camera stays over the submerged floor.
+
+Water fields edit the actual component. Optical normals are independent of the legacy shoreline
+wave modulation. Screen reflections can be disabled while retaining the environment fallback.
+The Newton, bounded HZB traversal, and undisplaced control modes all use the same AVBOIT path.
+An IOR of 1, zero RGB extinction and zero optical normal strength should leave opaque transport
+unchanged. Increase extinction to see independent color attenuation and the body-color source.
+
+Move the card, alpha/additive particles and ribbon above/below the interface using Layer height.
+The box and five thin posts exercise opaque occlusion and discontinuities. Swap channel order
+checks registration independence. Overlap water verifies deterministic nearest-interface selection;
+it does **not** enable transport through multiple interfaces. Replace terrain exercises height-field
+replacement. Restart device exercises retained facade registration and new GPU resource ownership.
+
+Water enabled off elides all water preparation/contribution passes. MBOIT suppresses water and
+the other AVBOIT side channels. There is no legacy-overlay fallback. TAA can be enabled for moving
+wave/object checks. NSS uses the renderer's existing weight requirement and falls back to TAA
+when weights have not been installed; this standalone page does not supply NSS weights.
+
+Inspection modes display prepared coverage, receiver UV, bounded path, classification/update count,
+surface radiance, residual, RGB throughput, shared front throughput, water's normalization term,
+and the confidence used to select the refraction lookup.
+They replace presentation **after** shared resolve and temporal processing, so diagnostics show
+the current frame's measurements without TAA history. Internal-resolution measurements are
+displayed with nearest sampling at the output resolution.
+Shift-click requests one pixel from four prepared textures on the next frame; normal frames perform
+no readback. Arrays are `receiver=[u,v,path,status+updates/32]`,
+`transmission=[Tr,Tg,Tb,coverage]`, `radiance=[Wr,Wg,Wb,residual]`.
+The separate `confidence` field is the final weight after rejecting unsupported lookups; the
+confidence display reads this same weight rather than recomputing an approximation.
+Status 0 is a Newton-assisted, visibility-checked hit; codes 8–13 are validated HZB hits, 16–21 undisplaced opaque fallbacks,
+24–29 bounded sky fallbacks, and 31 the below-interface control. The low three bits preserve the
+Newton miss reason: 0 none/not attempted, 1 bounds/clip, 2 sky, 3 parallel/invalid, 4 ray interval,
+5 exhausted budget/residual. The probe decodes these names and the update count. Residual is capped
+at 65504 for half-float storage. The status display uses green/cyan/purple/orange/pink for those
+five final classes; red increases with update count.
+
+Compile check compiles all ten production water modules on the active device. Rendering exercises
+their real pipelines and bind groups; the first validation error stops rendering and remains visible
+in the status panel and console. Restart device resumes after correcting the error. Profile / T
+uses the existing GPU profiler and exports `.sgpt`. Compare water on/off at a fixed paused camera,
+resolution and transparency population; include preparation, background transport and all AVBOIT
+passes, rather than quoting just the Newton loop. The recording includes trace budgets and temporal
+mode in its note. A device without timestamp-query records structure without timings.
+
+Copy state writes versioned JSON into the text area and attempts clipboard copying. Apply state
+restores camera, displayed controls, water/fixture clock, terrain offset and channel order.
+GPU particle populations and temporal histories are not serialized: reload/reset them and warm up
+equally for image/performance comparisons. Probe values describe the captured frame; camera changes
+require a fresh probe.
+
+## Integration boundaries and adversarial checks
+
+Opaque receiver transport uses the immutable pre-transparency HDR scene. Water contributes only its
+surface source and RGB extinction; shared resolve applies the transported opaque background once.
+Rear transparent surfaces/particles are attenuated at their original screen positions. Their radiance
+is not sampled through the bent ray. Missing/off-screen receivers get bounded, explicit fallbacks.
+Missing receivers use the local terrain column to estimate water thickness; the trace budget is only
+an upper bound. Final shading fades the receiver UV toward the control UV around emergent silhouettes,
+shoreline visibility gaps and screen edges, then performs one geometry-aware color lookup. It derives
+water thickness from that lookup's local receiver plane and builds its complete optical event. It
+does not crossfade two displaced images. Three quarter-resolution passes form a conservative
+geometry/sky boundary mask and bounded Euclidean distance field. Isolated trace failures never seed
+that field, which would amplify them into large moving blotches. The raw receiver/residual displays
+still show classified misses; Refraction confidence shows the displacement fade actually used by
+the final image. Screen reflections also fade near the ray origin and frame
+edges to avoid self-hit speckles, reusing the existing SSR back-face/thickness/vignette validation.
+Displaced Newton roots also require first-intersection evidence from a water adapter using the
+existing FFX cell intersection/depth-loading chunks. The adapter traverses the HZB's actual integer
+mip dimensions, including odd viewport sizes; it does not assume a floating halving of the source
+grid. It starts in the source pixel, since water is absent from opaque depth. HZB slab crossings
+are intersected once with the selected receiver plane and validated again before shading. A second
+Newton search here could jump to a farther root and falsely certify it as the first hit. Analytic ray distance sets the visibility
+interval instead of the biased texel-center projection. An exhausted traversal uses the control
+event. Color filtering accepts only taps on the validated
+receiver's local plane, with geometric-normal and interface-side checks. Receiver selection retains
+full-precision UV/path/control-path data. Final shading reads the same selected interface and
+deterministic surface owner before shared occupancy/extinction/draw consume its optical result.
+AVBOIT still supplies the sole transparency resolve.
+Underwater transport, two-interface transport, transparent receivers and caustics remain the plan's
+follow-on stage, rather than being implied by the below-interface/overlap controls.
+
+The tangent-plane update follows the paper's Appendix A, but geometry reconstruction differs:
+Newton reads the unfiltered depth and geometric face normal at mip zero, rather than the paper's
+distance-dependent mip filtering for local smoothness. The conservative HZB is a visibility
+traversal, not that filtered reconstruction. Nearest face planes avoid mixing foreground and
+background geometry at silhouettes; the tradeoff is weaker convergence on curved or undersampled
+surfaces. Bounded fallback and classified misses remain necessary. Neither the paper's convergence
+statistics nor its timing results apply directly to this implementation.
+
+Acceptance reconstructs the receiver at its subpixel UV on the sampled face plane before measuring
+ray proximity. Using the texel-center position instead can reject exact planar intersections at
+grazing angles and introduce striped hit/control transitions. This is independent of adaptive mip
+filtering. First-hit traversal still has a finite budget: inspect trace status when increasing the
+fallback steps, since an exhausted visibility check deliberately selects the control event.
+
+The main risks to check on target hardware are moving-wave temporal ghosts (water keeps the opaque
+depth/motion contract), coarse 8×8 volume attenuation near thin/partial edges, tangent-plane hits at
+depth discontinuities, and first activation of AVBOIT in otherwise opaque scenes. No paper performance
+claim is adopted; visibility checks and geometry-aware filtering add work to water rendering.
+Water transient targets cost approximately 68 bytes per internal pixel before allocator lifetime
+reuse, plus up to 0.375 bytes per pixel for the three quarter-resolution visibility fields:
+32 bytes for receiver/trace metadata, 4 for interface depth, and 32 for final optics/background. The tiny-loss
+throughput target is float32 and is read through unfilterable loads, so float32-filterable is unnecessary.
+
+The checker fixture uses 64 texels per square, preserving its world-space pattern while keeping
+the opaque input sharp. Compare water disabled before attributing source-image filtering to water.
+
+Numerical regressions execute production receiver/final-shading entries against analytic optical
+transport, and water's volume splat through shared integration at full, partial and odd-edge coverage.
+They also cover the actual shared WGSL contribution/resolve, count conservation,
+normal-incidence acceptance, analytic plane/sphere intersections, invalid rays, bounded fallback thickness,
+geometry-only visibility seeds, single-lookup transport, subpixel receiver thickness,
+grazing visibility intervals, odd-dimension traversal crossings, receiver ownership at silhouettes,
+first-receiver selection, source/receiver frame-edge fades and old/new serialization.
+Software-device orchestration verifies water precedes shared warp/integration/resolve without adding
+another one. Visual checks are complementary: inspect TAA/fog, mixed sources, below-interface fallback,
+overlap, no-water/MBOIT suppression, terrain replacement and device restart on a real GPU.
+The CPU emulator stores one mip and cannot propagate scalar pointer outputs back to callers;
+its traversal regression checks the returned crossing. Full mip-chain hit classification needs
+the real GPU; the CPU test does not claim to prove that contract.
+
+Blast radius: water lifecycle/shaders/data plus AVBOIT preparation/background plumbing and its
+tiny-loss resolve guard; existing particle, mesh and ribbon APIs remain intact.
+
+Reference: Mayer, Assarsson and Sintorn, *Ultrafast Screen-Space Refractions and Caustics via Newton's
+Method*, JCGT 15(1), 2026, [paper](https://jcgt.org/published/0015/01/03/paper-lowres.pdf).
+See [the integration plan](../../../../WATER_MAYER2026_INTEGRATION_PLAN.md) for the transport contract.

package/src/shade/playground/water_refraction/index.html

@@ -0,0 +1,42 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Water · Mayer refraction / AVBOIT</title>
+<style>
+:root{color-scheme:dark;font:14px/1.45 system-ui,sans-serif;color:#d6e4ea;background:#10161b}*{box-sizing:border-box}
+body{margin:0;display:grid;grid-template-columns:minmax(0,1fr) 330px;grid-template-rows:minmax(0,1fr);height:100vh;overflow:hidden}
+#viewport{min-width:0;min-height:0;overflow:hidden;position:relative;outline:none}#viewport canvas{width:100%;height:100%}
+aside{padding:22px;overflow:auto;border-left:1px solid #2d3a42;background:#151e25}h1{font-size:21px;margin:0 0 6px}h2{font-size:13px;color:#8cb9bf;text-transform:uppercase;letter-spacing:.07em;margin:23px 0 9px}
+p{margin:8px 0;color:#9faeb9;font-size:12px}label{display:flex;align-items:center;justify-content:space-between;gap:8px;margin:8px 0}
+input[type=range]{width:135px}input[type=number]{width:84px}input,select,button,textarea{font:inherit;background:#202d36;border:1px solid #3c505e;border-radius:5px;color:#e2edf0;padding:5px}select{max-width:180px}button{cursor:pointer}button:hover{background:#304753}button:disabled{opacity:.4;cursor:default}.row{display:flex;gap:6px;flex-wrap:wrap}textarea{width:100%;height:92px;font:11px/1.4 monospace;resize:vertical}pre{white-space:pre-wrap;overflow-wrap:anywhere;font:11px/1.5 monospace;color:#8bd3d5;background:#0c151b;padding:10px;border-radius:5px}#status{border-left:3px solid #70b8b5;padding:10px;font-size:12px;background:#1d2c32}#badge{position:absolute;top:18px;left:18px;pointer-events:none;background:#13242cd9;padding:9px 13px;border-radius:5px;color:#c7eff0;font-size:12px}a{color:#8dd3db}@media(max-width:760px){body{grid-template-columns:minmax(0,1fr) 275px}aside{padding:14px}input[type=range]{width:95px}}
+</style></head>
+<body tabindex="0"><div id="viewport" tabindex="0"><div id="badge">Drag to orbit · wheel to zoom · Shift-click to inspect a pixel</div></div>
+<aside><h1>Water / refraction</h1><p>Mayer 2026 · production ECS + shared AVBOIT</p><div id="status">Starting renderer…</div>
+<h2>View</h2><label>Preset<select id="preset"><option value="shore">Shore</option><option value="normal">Normal incidence</option><option value="grazing">Grazing / horizon</option><option value="posts">Thin posts</option><option value="edge">Screen edge</option><option value="discontinuities">Objects / shoreline</option><option value="underwater">Below interface</option></select></label>
+<div class="row"><button id="pause">Pause</button><button id="step">Step</button><button id="reset">Reset</button></div>
+<h2>Water</h2><label>Enabled<input id="enabled" type="checkbox" checked></label>
+<label>Level<input id="level" type="range" min="-1.5" max="2" step=".05" value="0"></label>
+<label>IOR<input id="ior" type="range" min="1" max="1.6" step=".01" value="1.33"></label>
+<label>Optical normal<input id="normal" type="range" min="0" max=".5" step=".01" value=".08"></label>
+<label>Normal scale<input id="scale" type="range" min=".2" max="8" step=".1" value="3"></label>
+<label>Roughness<input id="roughness" type="range" min="0" max="1" step=".01" value=".08"></label>
+<label>Extinction R<input id="extinction_r" type="number" min="0" max="2" step=".01" value=".12"></label>
+<label>Extinction G<input id="extinction_g" type="number" min="0" max="2" step=".01" value=".035"></label>
+<label>Extinction B<input id="extinction_b" type="number" min="0" max="2" step=".01" value=".02"></label>
+<label>Body color<input id="color" type="color" value="#004d80"></label><label>Shore color<input id="shore_color" type="color" value="#95cad9"></label>
+<label>Screen reflections<input id="reflection" type="checkbox" checked></label>
+<h2>Mixed transparency</h2><label>Layer height<input id="layer_height" type="range" min="-2" max="3" step=".05" value="0"></label>
+<label>Card opacity<input id="opacity" type="range" min=".02" max=".98" step=".02" value=".5"></label>
+<label>Alpha + additive particles<input id="particles" type="checkbox" checked></label>
+<label>Ribbon<input id="ribbon" type="checkbox" checked></label><label>Move submerged object<input id="animate" type="checkbox"></label>
+<label>Overlap water<input id="overlap" type="checkbox"></label><div class="row"><button id="order">Swap channel order</button><button id="terrain">Replace terrain</button><button id="restart">Restart device</button></div>
+<h2>Tracing / frame</h2><label>Trace<select id="mode"><option value="0">Newton + fallback</option><option value="1">Bounded traversal</option><option value="2">Undisplaced control</option></select></label>
+<label>Newton updates<input id="iterations" type="number" min="0" max="16" value="4"></label><label>Fallback steps<input id="fallback" type="number" min="0" max="128" value="48"></label>
+<label>Temporal<select id="temporal"><option value="off">Off</option><option value="taa">TAA</option><option value="nss">NSS (requires weights)</option></select></label>
+<label>Internal scale<select id="resolution"><option value="1">1×</option><option value=".75">0.75×</option><option value=".5">0.5×</option></select></label>
+<label>Opaque SSR<input id="ssr" type="checkbox"></label><label>Atmospheric fog<input id="fog" type="checkbox"></label>
+<label>Transparency<select id="transparency"><option value="avboit">AVBOIT</option><option value="mboit">MBOIT (water unavailable)</option></select></label>
+<h2>Inspect</h2><label>Display<select id="debug"><option value="0">Final composite</option><option value="1">Coverage</option><option value="2">Receiver UV</option><option value="3">Water path</option><option value="4">Trace status / updates</option><option value="5">Surface radiance</option><option value="6">Residual</option><option value="7">RGB throughput</option><option value="8">Shared front throughput</option><option value="9">Water normalization</option><option value="10">Refraction confidence</option></select></label>
+<div class="row"><button id="compile">Compile check</button><button id="profile">Profile (T)</button></div><pre id="probe">Shift-click water to read a pixel.</pre>
+<h2>Reproduce a view</h2><div class="row"><button id="copy">Copy state</button><button id="apply">Apply state</button></div><textarea id="state" aria-label="Saved camera and settings"></textarea>
+<p>Rear transparent radiance is attenuated on its original screen path. Initial optics select one water interface; underwater transport and caustics are follow-on work. <a href="./README.md">Review guide</a></p>
+</aside><script type="module" src="./main.js"></script></body></html>

package/src/shade/playground/water_refraction/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/water_refraction/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/water_refraction/main.js"],"names":[],"mappings":""}

package/src/shade/playground/water_refraction/main.js

@@ -0,0 +1,201 @@
+import ConcurrentExecutor from "../../../core/process/executor/ConcurrentExecutor.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import { AssetManager } from "../../../engine/asset/AssetManager.js";
+import { GameAssetType } from "../../../engine/asset/GameAssetType.js";
+import { ImageRGBADataLoader } from "../../../engine/asset/loaders/image/ImageRGBADataLoader.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { EntityManager } from "../../../engine/ecs/EntityManager.js";
+import { Entity } from "../../../engine/ecs/Entity.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { Light } from "../../../engine/graphics/ecs/light/Light.js";
+import { GPUParticleEmitterSystem } from "../../../engine/graphics3/GPUParticleEmitterSystem.js";
+import { GraphicsEngine } from "../../../engine/graphics3/GraphicsEngine.js";
+import { LightSystem } from "../../../engine/graphics3/LightSystem.js";
+import { ShadedGeometrySystem } from "../../../engine/graphics3/ShadedGeometrySystem.js";
+import { WaterSystem } from "../../../engine/graphics3/WaterSystem.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { DynamicMeshAVBOITChannel } from "../../renderer/dynamic/DynamicMeshAVBOITChannel.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { ShadeTransparencyMode } from "../../renderer/ShadeTransparencyMode.js";
+import { ShadeUpscalerType } from "../../renderer/ShadeUpscalerType.js";
+import { ParticipatingMediaVolume } from "../../renderer/volumetrics/ParticipatingMediaVolume.js";
+import { water_shader, water_finalize_shader } from "../../renderer/water/shader_water.js";
+import * as water_shaders from "../../renderer/water/shader_water_avboit.js";
+import { install_profile_hotkey } from "../profile_hotkey.js";
+import { build_world } from "./world.js";
+
+const element = id => document.getElementById(id);
+const presets = {
+    shore: [[22,9,28],[16,0,15]], normal: [[12,17,12.01],[12,0,12]],
+    grazing: [[21,0.6,17],[12,0,12]], posts: [[8,3,20],[10,-0.5,14]],
+    edge: [[22,5,18],[23,0,11]], underwater: [[19,-0.8,18],[12,-1,12]],
+    discontinuities: [[18.946,7.002,6.28],[15.4,2.439,10.562]],
+};
+const input_ids = ["preset","enabled","level","ior","normal","scale","roughness","extinction_r","extinction_g",
+    "extinction_b","color","shore_color","reflection","layer_height","opacity","particles","ribbon","animate",
+    "overlap","mode","iterations","fallback","temporal","resolution","ssr","fog","transparency","debug"];
+const initial_inputs = Object.fromEntries(input_ids.map(id => [id,element(id).type === "checkbox" ? element(id).checked : element(id).value]));
+const number = id => Number(element(id).value);
+const checked = id => element(id).checked;
+const color = (target, hex) => target.setRGB(...[1,3,5].map(i => parseInt(hex.slice(i,i+2),16)/255));
+
+async function main() {
+    const viewport = element("viewport"), graphics = new GraphicsEngine(), scene = new Scene();
+    viewport.appendChild(graphics.viewport.el);
+    const assets = new AssetManager({context:{},executor:new ConcurrentExecutor()});
+    await assets.registerLoader(GameAssetType.Image,new ImageRGBADataLoader()); assets.startup();
+    const dataset = new EntityComponentDataset(), entities = new EntityManager();
+    const water_system = new WaterSystem(graphics);
+    entities.addSystem(new ShadedGeometrySystem(graphics,scene)); entities.addSystem(new LightSystem(graphics,scene));
+    entities.addSystem(new GPUParticleEmitterSystem(graphics,scene,assets)); entities.addSystem(water_system);
+    entities.attachDataset(dataset);
+    await new Promise((resolve,reject) => entities.startup(resolve,reject));
+    const world = await build_world(dataset), channel = new DynamicMeshAVBOITChannel(world.batch);
+    graphics.add_transparency_channel(channel);
+    const sun = new Light(); sun.intensity.set(2.2);
+    const sun_pose = new Transform64(), rotation = new Quaternion();
+    rotation.fromUnitVectors(Vector3.forward,new Vector3(-0.3,-1,0.2).normalize());
+    sun_pose.setRotation(rotation.x,rotation.y,rotation.z,rotation.w);sun_pose.updateMatrix();
+    const sun_entity = new Entity().add(sun).add(sun_pose);sun_entity.build(dataset);
+    const camera = graphics.camera.camera, controller = new OrbitalCameraController(camera,viewport);
+    camera.near=0.1;camera.far=300;camera.fov=Math.PI/3;
+    const look = key => controller.look(new Vector3(...presets[key][0]),new Vector3(...presets[key][1]));
+    look("shore");
+    let ready=false,paused=false,step=false,time=0,profile=null,stop_loop=null,swapped=false,terrain_offset=0,revision=0;
+    const fog = new ParticipatingMediaVolume();fog.target_extinction=0.015;
+    fog.transform.setScale(80,40,80);fog.transform.setTranslation(16,0,16);fog.transform.updateMatrix();
+    let fog_added=false;
+    const report = message => {element("status").textContent=message;};
+    graphics.on.contextFailed.add(error => report(error.message));
+    graphics.on.contextLost.add(error => {ready=false;report(`GPU device lost · ${error.message} · use Restart device`);});
+    function configure() {
+        revision++;
+        const w=world.water,s=water_system.settings,r=graphics.renderer;
+        w.level.set(number("level"));w.ior.set(number("ior"));w.opticalNormalStrength.set(number("normal"));
+        w.opticalNormalScale.set(number("scale"));w.reflectionRoughness.set(number("roughness"));
+        w.extinction.set(number("extinction_r"),number("extinction_g"),number("extinction_b"));
+        color(w.color,element("color").value);color(w.shoreColor,element("shore_color").value);
+        Object.assign(s,{enabled:checked("enabled"),mode:number("mode"),max_updates:number("iterations"),
+            fallback_steps:number("fallback"),reflections:checked("reflection")?1:0,debug_view:number("debug")});
+        world.card.component.material.diffuse_color.a=number("opacity");
+        world.effects.forEach(effect=>effect.emitting=checked("particles"));world.ribbon.visible=checked("ribbon");
+        world.overlap(checked("overlap"));
+        if(checked("fog")&&!fog_added){scene.volumetrics.add(fog);fog_added=true;}
+        if(!checked("fog")&&fog_added){scene.volumetrics.remove(fog);fog_added=false;}
+        if(r!==null&&r!==undefined){
+            r.transparency_mode=element("transparency").value==="avboit"?ShadeTransparencyMode.AVBOIT:ShadeTransparencyMode.MBOIT;
+            r.feature_taa_enabled=element("temporal").value!=="off";
+            r.upscale_type=element("temporal").value==="nss"?ShadeUpscalerType.NSS:ShadeUpscalerType.TAA;
+            r.feature_ssr_enabled=checked("ssr");r.pixel_ratio=number("resolution");
+            r.feature_automatic_exposure_enabled=false;r.exposure_compensation=0;
+            r.feature_bloom_enabled=false;r.feature_ssao_enabled=false;
+        }
+        element("probe").textContent="Settings changed — Shift-click to inspect a fresh pixel.";
+        if(element("transparency").value!=="avboit")report("MBOIT · water, particles and ribbons are unavailable");
+        else if(!s.enabled)report("Water disabled · shared transparency remains active");
+        else if(element("preset").value==="underwater")report("Below interface · bounded tint control; underwater transport is unsupported");
+        else report("Ready · one water interface · shared AVBOIT");
+    }
+    async function start_device() {
+        ready=false;profile?.dispose();await graphics.start();configure();
+        const renderer=graphics.renderer;
+        profile=install_profile_hotkey({renderer,name:"water_refraction",status:element("status"),target:viewport,
+            settings:()=>[element("mode").selectedOptions[0].textContent,`${number("iterations")} updates`,`${number("fallback")} fallback`,element("temporal").value]});
+        let validation_failed=false;
+        renderer.graphics.device.addEventListener("uncapturederror",event=>{
+            if(validation_failed)return;
+            validation_failed=true;ready=false;report(event.error.message);console.error(event.error.message);
+        });
+        ready=true;report("Ready · one water interface · shared AVBOIT");
+    }
+    function state() {
+        const t=camera.transform;
+        return {version:1,inputs:Object.fromEntries(input_ids.map(id=>[id,element(id).type==="checkbox"?checked(id):element(id).value])),
+            camera:{position:[t.translation_x,t.translation_y,t.translation_z],target:[controller.target.x,controller.target.y,controller.target.z]},
+            time,paused,terrain_offset,swapped};
+    }
+    function apply_state(value) {
+        if(value.version!==1)throw new Error("Unsupported state version");
+        for(const id of input_ids){const el=element(id),v=value.inputs?.[id];if(v===undefined)continue;
+            if(el.type==="checkbox")el.checked=!!v;
+            else if(el.type==="range"||el.type==="number"){
+                const n=Number(v);if(!Number.isFinite(n))throw new Error(`Invalid ${id}`);
+                el.value=Math.max(Number(el.min),Math.min(Number(el.max),n));
+            }else if(el.tagName==="SELECT"){
+                if(![...el.options].some(o=>o.value===String(v)))throw new Error(`Invalid ${id}`);el.value=v;
+            }else if(/^#[0-9a-f]{6}$/i.test(v))el.value=v;
+        }
+        const vector=v=>{if(!Array.isArray(v)||v.length!==3||!v.every(Number.isFinite))throw new Error("Invalid camera");return new Vector3(...v);};
+        controller.look(vector(value.camera.position),vector(value.camera.target));
+        if(!Number.isFinite(value.time)||value.time<0)throw new Error("Invalid time");
+        time=value.time;water_system.time=time;paused=!!value.paused;
+        terrain_offset=Number(value.terrain_offset)||0;world.replace_terrain(terrain_offset);
+        if(!!value.swapped!==swapped)swap_order();
+        configure();element("pause").textContent=paused?"Resume":"Pause";
+    }
+    function swap_order() {
+        graphics.remove_transparency_channel(channel);graphics.remove_transparency_channel(water_system.transparency_channel);
+        swapped=!swapped;
+        (swapped?[channel,water_system.transparency_channel]:[water_system.transparency_channel,channel]).forEach(c=>graphics.add_transparency_channel(c));
+    }
+    input_ids.forEach(id=>element(id).addEventListener("input",configure));
+    element("preset").addEventListener("change",()=>{look(element("preset").value);configure();});
+    element("pause").onclick=()=>{paused=!paused;element("pause").textContent=paused?"Resume":"Pause";};
+    element("step").onclick=()=>{paused=true;step=true;element("pause").textContent="Resume";};
+    element("reset").onclick=()=>{world.reset_particles();apply_state({version:1,inputs:initial_inputs,
+        camera:{position:presets.shore[0],target:presets.shore[1]},time:0,paused:false,terrain_offset:0,swapped:false});};
+    element("order").onclick=swap_order;
+    element("terrain").onclick=()=>{terrain_offset=terrain_offset===0?-0.25:0;world.replace_terrain(terrain_offset);};
+    element("restart").onclick=async()=>{try{ready=false;graphics.stop();await start_device();}catch(error){report(error.message);}};
+    element("profile").onclick=()=>profile?.toggle().catch(error=>report(error.message));
+    element("copy").onclick=async()=>{const json=JSON.stringify(state(),null,2);element("state").value=json;
+        try{await navigator.clipboard.writeText(json);}catch{/* Text remains available for manual copying. */}};
+    element("apply").onclick=()=>{try{apply_state(JSON.parse(element("state").value));}catch(error){report(error.message);}};
+    element("compile").onclick=async()=>{
+        if(!ready)return;
+        const device=graphics.renderer.graphics.device,errors=[];
+        for(const shader of [water_shader,water_finalize_shader,...Object.values(water_shaders).map(s=>s.descriptor)]){
+            if(typeof shader?.source!=="string")continue;
+            const module=device.createShaderModule({code:shader.source});const info=await module.getCompilationInfo();
+            errors.push(...info.messages.filter(m=>m.type==="error").map(m=>`${m.lineNum}: ${m.message}`));
+        }
+        report(errors.length?errors.join("\n"):"Water shader modules compiled successfully.");
+    };
+    let probe_pending=false;
+    viewport.addEventListener("click",async event=>{
+        if(!event.shiftKey||!ready||probe_pending)return;
+        if(!checked("enabled")||element("transparency").value!=="avboit"){element("probe").textContent="Enable AVBOIT water before inspecting.";return;}
+        const rect=viewport.getBoundingClientRect();probe_pending=true;
+        const probe_revision=revision,probe_camera=JSON.stringify(state().camera);
+        try{const result=await water_system.request_probe([(event.clientX-rect.left)/rect.width,(event.clientY-rect.top)/rect.height]);
+            const packed=result.receiver[3],code=Math.floor(packed);
+            const classification=result.transmission[3]<=0?"no water coverage":code===31?"below-interface control":
+                ["Newton-assisted hit","HZB hit","undisplaced fallback","bounded sky"][Math.floor(code/8)]??"invalid";
+            const reason=["none / not attempted","bounds / clip","sky","parallel / invalid","ray interval","budget / residual"][code%8];
+            element("probe").textContent=JSON.stringify({...result,
+                stale:revision!==probe_revision||JSON.stringify(state().camera)!==probe_camera,
+                classification,newton_reason:code===31?"unsupported view":reason,
+                newton_updates:Math.round((packed-code)*32)},null,2);
+        }catch(error){element("probe").textContent=error.message;}finally{probe_pending=false;}
+    });
+    Object.assign(globalThis,{graphics,scene,dataset,entities,world,water_system,camera,controller,
+        water_playground:{state,apply_state,get ready(){return ready;}}});
+    await start_device();
+    function frame(raw_dt) {
+        if(!ready)return;
+        const dt=step?1/60:paused?0:Math.min(raw_dt,0.05);step=false;time+=dt;
+        graphics.viewport.size.set(Math.max(1,viewport.clientWidth),Math.max(1,viewport.clientHeight));
+        controller.update();world.update(time,{layer_height:number("layer_height"),animate:checked("animate")});
+        entities.update(dt);graphics.render(dt);
+    }
+    stop_loop=create_frame_loop(frame,60);
+    globalThis.water_playground.frame=frame;
+    window.addEventListener("pagehide",()=>{
+        ready=false;stop_loop?.();profile?.dispose();world.dispose();dataset.removeEntity(sun_entity.id);
+        channel.release(world.ribbon.geometry);graphics.remove_transparency_channel(channel);
+        entities.shutdown(()=>{},console.error);controller.pointer.stop();controller.keyboard.stop();graphics.stop();
+    },{once:true});
+}
+main().catch(error=>{console.error(error);element("status").textContent=error.message;});

package/src/shade/playground/water_refraction/world.d.ts

@@ -0,0 +1,37 @@
+/** All visible static content uses ordinary ECS meshlets; water owns no demo-specific pass. */
+export function build_world(dataset: any): Promise<{
+    terrain: Terrain;
+    water: Water;
+    water_entity: any;
+    card: {
+        transform: Transform64;
+        component: ShadedGeometry;
+        entity: any;
+    };
+    submerged: {
+        transform: Transform64;
+        component: ShadedGeometry;
+        entity: any;
+    };
+    batch: DynamicMeshBatch;
+    ribbon: DynamicMesh;
+    effects: ParticleEffect[];
+    entities: any[];
+    reset_particles(): void;
+    update(time: any, { layer_height, animate }?: {
+        layer_height?: number;
+        animate?: boolean;
+    }): void;
+    replace_terrain(offset?: number): void;
+    overlap(enabled: any): void;
+    dispose(): void;
+}>;
+export function height_at(x: any, z: any, offset?: number): number;
+import Terrain from "../../../engine/ecs/terrain/ecs/Terrain.js";
+import Water from "../../../engine/graphics/ecs/water/Water.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { DynamicMeshBatch } from "../../renderer/scene/DynamicMeshBatch.js";
+import { DynamicMesh } from "../../renderer/scene/DynamicMesh.js";
+import { ParticleEffect } from "../../../engine/graphics/ecs/particles/ParticleEffect.js";
+//# sourceMappingURL=world.d.ts.map

package/src/shade/playground/water_refraction/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/water_refraction/world.js"],"names":[],"mappings":"AA0DA,+FAA+F;AAC/F;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EC;AA5GM,mEAAsE;oBAxBzD,4CAA4C;kBAI9C,6CAA6C;4BAHnC,8CAA8C;+BAE3C,wDAAwD;iCActD,0CAA0C;4BAD/C,qCAAqC;+BAXlC,0DAA0D"}