@woosh/meep-engine 3.39.0 → 3.40.0

package/src/shade/renderer/water/shader_water.js

@@ -1,406 +1,490 @@
-import { GPUShaderStage } from "../../descriptor/GPUShaderStage.js";
-import { DepthStencilState } from "../../descriptor/pipeline/render/DepthStencilState.js";
-import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
-import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
-import { SHADING_LIGHT_RESOURCE_GROUP } from "../deferred/SHADING_LIGHT_RESOURCE_GROUP.js";
-import { BRICK4_DATA_STRUCT } from "../global_illumination/brick4/gpu/BRICK4_DATA_STRUCT.js";
-import { chunk_F_dielectric } from "../shader/chunk/brdf/fresnel/chunk_F_dielectric.js";
-import { chunk_direction_view_to_world } from "../shader/chunk/camera/chunk_direction_view_to_world.js";
-import { chunk_direction_world_to_view } from "../shader/chunk/camera/chunk_direction_world_to_view.js";
-import { chunk_ray_at } from "../shader/chunk/geometry/ray/chunk_ray_at.js";
-import { chunk_ffx_sssr_advance_ray } from "../shader/chunk/screen_space/chunk_ffx_sssr_advance_ray.js";
-import { chunk_ffx_sssr_load_depth } from "../shader/chunk/screen_space/chunk_ffx_sssr_load_depth.js";
-import { chunk_ffx_sssr_validate_hit } from "../shader/chunk/screen_space/chunk_ffx_sssr_validate_hit.js";
-import { chunk_project_direction } from "../shader/chunk/screen_space/chunk_project_direction.js";
-import { chunk_screen_space_newton_ray } from "../shader/chunk/screen_space/chunk_screen_space_newton_ray.js";
-import { chunk_texture_sample_bilinear_uv } from "../shader/chunk/texture/sample/chunk_texture_sample_bilinear_uv.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
-import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
-import { f32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
-import { VIEW_UNIFORM_STRUCT } from "../view/VIEW_UNIFORM_STRUCT.js";
-import { chunk_water_gi_brick4, chunk_water_gi_ibl } from "./chunk_water_gi.js";
-import { WATER_BODIES_STRUCT } from "./medium/WATER_BODIES_STRUCT.js";
-import { chunk_water_inscatter } from "./optics/chunk_water_inscatter.js";
-import { chunk_water_receiver_downwelling } from "./optics/chunk_water_receiver_downwelling.js";
-import { chunk_water_optics } from "./optics/chunk_water_optics.js";
-import { WATER_SURFACE_VERTEX_STRUCT } from "./surface/WATER_SURFACE_VERTEX_STRUCT.js";
-import { chunk_water_receiver_radiance, chunk_water_receiver_texel, chunk_water_refraction_confidence,
-    chunk_water_transport, WATER_LEVEL_TOLERANCE_DECLARATION } from './chunk_water_transport.js';
-
-export const WATER_DRAW_STRUCT = WebGPUStruct.from({
-    level: f32, ior: f32, roughness: f32, surface_id: u32,
-    // row of this body in the water bodies table
-    body_index: u32,
-    // how far to integrate the water when no receiver is seen through it: where its clearest channel's
-    // transmittance falls to a thousandth, bounded by the trace distance (water_missing_receiver_path)
-    missing_receiver_path: f32,
-}, "WaterDraw").pack();
-
-export const WATER_TRACE_STRUCT = WebGPUStruct.from({
-    max_distance: f32, distance_tolerance: f32, max_updates: u32, fallback_steps: u32,
-    mode: u32, reflections: u32,
-    // steps of the water body's in-scatter along each refracted view ray
-    inscatter_segments: u32,
-}, "WaterTrace").pack();
-
-function water_resources(finalize = false) {
-    const resources = new ShaderResourceSetDescriptor();
-    const group = resources.createGroup()
-        .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-        .addUniform("water", WATER_DRAW_STRUCT)
-        .addUniform("trace", WATER_TRACE_STRUCT)
-        .addTexture("tDepth")
-        .addTexture("tNormal", "uint")
-        .addTexture("tHZB")
-        .addTexture("tScene")
-        // the surface interface: the producer's vertices
-        .addStorageBuffer("surface_vertices", WebGPUArray.from(WATER_SURFACE_VERTEX_STRUCT), false);
-    if (finalize) {
-        group.addTexture('receiver').addTexture('trace_metadata').addTexture('visibility_distance')
-            .addUniform("water_bodies", WATER_BODIES_STRUCT);
-    }
-    return resources;
-}
-const resources = water_resources();
-
-/** Optics under IBL (and LPV, which has no transparent variant): the lights and the environment. */
-export const WATER_FINALIZE_RESOURCES_IBL = water_resources(true);
-WATER_FINALIZE_RESOURCES_IBL.addGroup(SHADING_LIGHT_RESOURCE_GROUP);
-
-/** Optics under Brick4: the lights, and the light map with the view its sampling jitters by. */
-export const WATER_FINALIZE_RESOURCES_BRICK4 = water_resources(true);
-WATER_FINALIZE_RESOURCES_BRICK4.addGroup(SHADING_LIGHT_RESOURCE_GROUP);
-WATER_FINALIZE_RESOURCES_BRICK4.createGroup()
-    .addStorageBuffer("brick4", BRICK4_DATA_STRUCT, false)
-    .addUniform("view", VIEW_UNIFORM_STRUCT);
-
-const surface_body = CodeChunk.from(/* language=WGSL */ `
-struct WaterVertexOut {
-    // Receivers and optics are separate modules drawing this mesh; optics tests depth 'equal'
-    // against the receivers' depth, and both must cover the same edge pixels. Only @invariant
-    // makes the position bit-identical across programs.
-    @invariant @builtin(position) clip: vec4<f32>,
-    @location(0) world: vec3<f32>,
-    @location(1) normal: vec3<f32>,
-    // slope variance of the waves the surface's mesh does not resolve
-    @location(2) unresolved_variance: f32,
-}
-
-// Pulls the producer's vertex: in an indexed draw the vertex index is the index-buffer entry.
-@vertex
-fn vs_main(@builtin(vertex_index) vi: u32) -> WaterVertexOut {
-    let vertex = surface_vertices[vi];
-    let world = vertex.position.xyz;
-    return WaterVertexOut(camera.view_projection_matrix * vec4<f32>(world, 1.0), world,
-        vertex.normal.xyz, vertex.position.w);
-}
-
-// The interface at one water fragment, in view space. Receivers trace through it and optics
-// shade it, so both passes take it from here.
-struct WaterInterface {
-    origin: vec3<f32>,
-    incident: vec3<f32>,
-    // Faces the camera's side of the interface.
-    normal: vec3<f32>,
-    above: bool,
-    ior: f32,
-    // Screen-space travel bound.
-    limit: f32,
-}
-
-fn water_interface(world: vec3<f32>, surface_normal: vec3<f32>) -> WaterInterface {
-    let origin = (camera.view_matrix * vec4f(world, 1.0)).xyz;
-    let above = camera.view_matrix_inverse[3].y >= world.y;
-    var normal_ws = normalize(surface_normal);
-    if (!above) { normal_ws = -normal_ws; }
-    return WaterInterface(origin, normalize(origin), normalize(direction_world_to_view(normal_ws, camera)), above,
-        max(water.ior, 1.0), min(max(trace.max_distance, 0.1), camera.clip_near_far.y));
-}
-`, [chunk_direction_world_to_view]);
-
-export const chunk_water_screen_ray = CodeChunk.from(/* language=WGSL */ `
-fn water_hzb_mip_size(depth_size: vec2f, hzb_size: vec2f, mip: i32) -> vec2f {
-    if (mip <= 0) { return depth_size; }
-    return max(vec2f(1.0), floor(hzb_size / exp2(f32(mip-1))));
-}
-// Reuse the renderer's FFX cell intersection and depth loads, but walk the actual
-// integer mip grids. Its SSR driver halves floating sizes and assumes power-of-two
-// reductions; Meep's HZB conservatively resamples arbitrary viewport dimensions.
-fn water_hzb_crossing(origin: vec3f, direction: vec3f, budget: u32,
-    valid: ptr<function,bool>, iterations: ptr<function,u32>) -> vec3f {
-    let size = vec2f(textureDimensions(tDepth,0));
-    let pyramid_size = vec2f(textureDimensions(tHZB,0));
-    let last_mip = i32(textureNumLevels(tHZB));
-    let inverse_direction = select(vec3f(F32_MAX), 1.0/direction, abs(direction)>vec3f(1e-12));
-    let floor_offset = select(vec2f(1.0), vec2f(0.0), direction.xy<vec2f(0.0));
-    let uv_offset = select(0.005/size, -0.005/size, direction.xy<vec2f(0.0));
-    var mip = 0;
-    var position = origin;
-    var travel = 0.0;
-    *valid = false;
-    // Water is absent from the opaque depth buffer: skipping the initial pixel
-    // can skip the entire receiver for almost zero projected displacement.
-    for (var i=0u; i<min(budget,128u); i++) {
-        *iterations = i+1u;
-        if (!screen_space_ray_in_bounds(position.xy) || is_background(position.z)) { break; }
-        let resolution = water_hzb_mip_size(size,pyramid_size,mip);
-        let pixel = resolution * position.xy;
-        let depth = ffx_sssr_load_depth(vec2i(pixel),mip);
-        let skipped = ffx_sssr_advance_ray(origin,direction,inverse_direction,pixel,
-            1.0/resolution,floor_offset,uv_offset,depth,&position,&travel);
-        if (!skipped && mip==0) { *valid=true; break; }
-        mip = clamp(mip+select(-1,1,skipped),0,last_mip);
-    }
-    return position;
-}
-// HZB returns a depth-slab crossing, not the intersection of the ray with the
-// receiver's plane. Refine that crossing before using its UV or optical path.
-fn water_exact_receiver(ray: Ray, input: ScreenSpaceRayHit) -> ScreenSpaceRayHit {
-    var hit = input;
-    if (hit.status != 0u) { return hit; }
-    let receiver = screen_space_ray_load_receiver(hit.uv, tDepth, tNormal,
-        camera.projection_matrix_inverse, camera.view_matrix);
-    let travel = plane_ray_raycast(ray.origin, ray.direction, receiver.plane);
-    // Keep the analytic distance rather than the projection of the texel center onto the ray.
-    if (travel > 1e-4 && travel <= ray.tmax) {
-        hit.distance = travel;
-        hit.uv = project_position(ray_at(ray.origin, ray.direction, travel), camera.projection_matrix).xy;
-        // Reprojection can change texel ownership at a silhouette. Validate that lookup
-        // again; the analytic travel above already checked the ray's bounded interval.
-        let checked = screen_space_ray_validate(Ray(ray.origin,ray.direction,1e20),hit.uv,tDepth,tNormal,
-            camera.projection_matrix,camera.projection_matrix_inverse,camera.view_matrix,trace.distance_tolerance);
-        hit.status = checked.status;
-        hit.residual = checked.residual;
-    } else { hit.status = 4u; }
-    return hit;
-}
-fn water_refine_receiver(ray: Ray, seed: vec2f) -> ScreenSpaceRayHit {
-    // The traversal already selected the first depth footprint. Intersect its plane
-    // once and validate ownership; another Newton search could jump past that footprint
-    // to a later root that the traversal has already ruled out.
-    return water_exact_receiver(ray, ScreenSpaceRayHit(seed, 0.0, 1e20, 0u, 0u));
-}
-fn water_hzb_hit(ray: Ray, budget: u32) -> ScreenSpaceRayHit {
-    var miss = ScreenSpaceRayHit(vec2f(0.0), 0.0, 1e20, 0u, 5u);
-    if (budget == 0u || !screen_space_ray_projectable(ray.origin, camera.projection_matrix)
-        || !screen_space_ray_projectable(ray.origin + ray.direction, camera.projection_matrix)) { return miss; }
-    let origin = project_position(ray.origin, camera.projection_matrix);
-    let direction = project_direction(ray.origin, ray.direction, origin, camera.projection_matrix);
-    // Only rays advancing into reverse-Z are supported by this adapter.
-    if (direction.z >= -1e-8 || !screen_space_ray_in_bounds(origin.xy)) { return miss; }
-    var valid = false;
-    var iterations = 0u;
-    let candidate = water_hzb_crossing(origin, direction, budget, &valid, &iterations);
-    if (!valid) { miss.iterations = iterations; return miss; }
-    var hit = water_refine_receiver(ray, candidate.xy);
-    hit.iterations = iterations;
-    return hit;
-}
-`, [chunk_screen_space_newton_ray, chunk_ffx_sssr_advance_ray, chunk_ffx_sssr_load_depth, chunk_project_direction,
-    chunk_ray_at]);
-
-const body = CodeChunk.from(/* language=WGSL */ `
-struct WaterReceiver {
-    @location(0) receiver: vec4<f32>,
-    @location(1) metadata: vec4<f32>,
-    // Receiver UV, bounded path, classified status + Newton updates / 32. Readback is opt-in.
-}
-
-// A screen-space receiver must lie below the surface point the ray entered at: the refracted ray runs
-// downward from it, so any point on the ray is lower, and one that is not is a root off the ray.
-fn water_receiver_submerged(uv: vec2f, surface_y: f32) -> bool {
-    let receiver = water_receiver_texel(tDepth, tNormal, vec2i(uv * vec2f(textureDimensions(tDepth, 0))),
-        camera.projection_matrix_inverse, camera.view_matrix_inverse);
-    return receiver.position.y <= surface_y + WATER_LEVEL_TOLERANCE;
-}
-
-@fragment
-fn fs_main(in: WaterVertexOut) -> WaterReceiver {
-    let coord = vec2<i32>(in.clip.xy);
-    let dimensions = vec2f(textureDimensions(tDepth, 0));
-    let uv = in.clip.xy / dimensions;
-    let scene_depth = textureLoad(tDepth, coord, 0).r;
-    if (scene_depth >= in.clip.z) { discard; }
-    // the opaque scene behind this pixel, and how deep under the surface point it lies: shore water
-    // fades in over its first 10 cm, whatever is under it
-    var behind_vs = vec3f(0.0);
-    var water_depth = 1e20;
-    if (!is_background(scene_depth)) {
-        behind_vs = inv_project_position(vec3f(uv, scene_depth), camera.projection_matrix_inverse);
-        water_depth = in.world.y - (camera.view_matrix_inverse * vec4f(behind_vs, 1.0)).y;
-    }
-    let coverage = smoothstep(0.0, 0.1, water_depth);
-    let surface = water_interface(in.world, in.normal);
-    let above = surface.above;
-    let limit = surface.limit;
-    let direction = refract(surface.incident, surface.normal, 1.0 / surface.ior);
-    let ray = Ray(surface.origin, normalize(direction), limit);
-    var hit = ScreenSpaceRayHit(uv, limit, 1e20, 0u, 8u);
-    var newton_updates = 0u;
-    var newton_failure = 0u;
-    if (above && trace.mode == 0u) {
-        // Mayer et al. §2.2: a root within one pixel of the ray is accepted as is. Like the paper,
-        // this can converge past a thin occluder; traversal is only the fallback for failures.
-        hit = screen_space_newton_ray(ray, uv, tDepth, tNormal, camera.projection_matrix,
-            camera.projection_matrix_inverse, camera.view_matrix, trace.max_updates, trace.distance_tolerance);
-        newton_updates = hit.iterations;
-        newton_failure = hit.status;
-    }
-    // Reject foreground receivers before deciding whether traversal is needed.
-    if (hit.status == 0u && !water_receiver_submerged(hit.uv, in.world.y)) { hit.status = 5u; newton_failure = 5u; }
-    if (above && trace.mode != 2u && hit.status != 0u) {
-        let fallback = water_hzb_hit(ray, trace.fallback_steps);
-        if (fallback.status == 0u && water_receiver_submerged(fallback.uv, in.world.y)) { hit = fallback; hit.status = 6u; }
-    }
-    // Compute the control event for every pixel, independently of Newton/HZB success. With nothing
-    // behind the water on screen, integrate it to where it has taken all but a thousandth.
-    var control_path = min(water.missing_receiver_path, limit);
-    var control_status = select(8u, 9u, !above);
-    if (!is_background(scene_depth)) {
-        if (water_depth >= -WATER_LEVEL_TOLERANCE || !above) {
-            control_path = min(distance(ray.origin, behind_vs), limit);
-            control_status = select(7u, 9u, !above);
-        }
-    }
-    if (trace.mode == 2u || !above || (hit.status != 0u && hit.status != 6u)) {
-        // Never use an unvalidated Newton iterate as a color lookup.
-        hit.uv = uv;
-        // A missing screen receiver is missing visibility, not 300 metres of water.
-        hit.distance = control_path;
-        hit.status = control_status;
-    }
-    var status = hit.status;
-    if (status == 6u) { status = 8u + newton_failure; }
-    else if (status == 7u) { status = 16u + newton_failure; }
-    else if (status == 8u) { status = 24u + newton_failure; }
-    else if (status == 9u) { status = 31u; }
-    return WaterReceiver(vec4f(hit.uv, hit.distance, f32(status) + f32(newton_updates)/32.0),
-        vec4f(control_path, min(hit.residual, 65504.0), coverage, f32(water.surface_id)));
-}
-`, [surface_body, chunk_water_screen_ray, chunk_direction_view_to_world,
-    chunk_water_receiver_texel, WATER_LEVEL_TOLERANCE_DECLARATION]);
-
-const finalize_body = CodeChunk.from(/* language=WGSL */ `
-struct WaterOptics {
-    @location(0) transmission: vec4f,
-    @location(1) radiance: vec4f,
-    @location(2) background: vec4f,
-}
-@fragment
-fn fs_main(in: WaterVertexOut) -> WaterOptics {
-    let coord = vec2i(in.clip.xy);
-    let metadata = textureLoad(trace_metadata, coord, 0);
-    // Equal-depth surfaces must retain the same deterministic owner as receiver selection.
-    if (metadata.w != f32(water.surface_id)) { discard; }
-    let dimensions = vec2f(textureDimensions(tDepth, 0));
-    let uv = in.clip.xy / dimensions;
-    let receiver_data = textureLoad(receiver, coord, 0);
-    let surface = water_interface(in.world, in.normal);
-    let body = water_bodies.bodies[water.body_index];
-    let origin = surface.origin;
-    let above = surface.above;
-    let ior = surface.ior;
-    let limit = surface.limit;
-    let nov = clamp(dot(-surface.incident, surface.normal), 0.0, 1.0);
-    // exact dielectric Fresnel: water is most reflective at grazing angles, where Schlick's is not right
-    let fresnel = F_dielectric(nov, ior);
-    let reflection_direction = reflect(surface.incident, surface.normal);
-    // a reflection that misses on screen falls back to the GI mode, as SSR's resolve does
-    var reflection = water_gi_specular(in.world, direction_view_to_world(surface.normal, camera),
-        direction_view_to_world(-surface.incident, camera), water.roughness);
-    if (trace.reflections != 0u && above) {
-        let reflected = water_hzb_hit(Ray(ray_at(origin, reflection_direction, 0.02), reflection_direction, limit),
-            trace.fallback_steps);
-        if (reflected.status == 0u) {
-            let reflected_point = ray_at(origin, reflection_direction, reflected.distance + 0.02);
-            let projected = project_position(reflected_point, camera.projection_matrix);
-            // Reflection uses the renderer's usual back-face, thickness, self-hit and
-            // vignette validation. Its two-pixel rule must not reject normal-incidence refraction.
-            let confidence = ffx_sssr_validate_hit(vec3f(reflected.uv, projected.z), uv,
-                reflection_direction, dimensions, max(trace.distance_tolerance, 0.02), 0.05);
-            let radiance = water_receiver_radiance(tScene, tDepth, tNormal, reflected.uv,
-                camera.projection_matrix_inverse, camera.view_matrix_inverse, in.world.y, false);
-            reflection = mix(reflection, radiance.rgb,
-                confidence * min(radiance.a * 2.0, 1.0) * smoothstep(0.05, 0.5, reflected.distance)
-                * smoothstep(1.0, 4.0, length((reflected.uv - uv) * dimensions)));
-        }
-    }
-    let original = textureLoad(tScene, coord, 0);
-    let valid = receiver_data.w < 16.0 && above && trace.mode != 2u;
-    var confidence = select(0.0, water_refraction_confidence(receiver_data.xy, uv, dimensions,
-        texture_sample_bilinear_uv(visibility_distance, uv, 0u).r), valid);
-    // Mayer's fade selects one UV, rather than crossfading two images of the same edge.
-    let lookup = water_refraction_lookup(uv, receiver_data.xy, confidence);
-    // The surface height here stands for the one above the displaced receiver: they differ by the
-    // wave height across a few metres, against a tolerance the gather already allows.
-    let gathered = water_receiver_radiance(tScene, tDepth, tNormal, lookup,
-        camera.projection_matrix_inverse, camera.view_matrix_inverse, in.world.y, above);
-    var path = metadata.x;
-    var color = original.rgb;
-    // the receiver seen through the surface: refracted, or the pixel's own when there is none
-    var receiver_coord = coord;
-    if (confidence > 0.0 && gathered.a > 0.0) {
-        path = min(water_receiver_path(tDepth, tNormal, lookup, camera.projection_matrix_inverse,
-            camera.view_matrix, origin), limit);
-        color = gathered.rgb;
-        receiver_coord = vec2i(lookup * dimensions);
-    } else { confidence = 0.0; }
-    // The opaque scene was shaded dry: what reaches the receiver is what survives the water above it
-    // (WATER_OPTICS_PLAN_2026_10_02.md §4.3). Seen from under the surface, the receiver is above it.
-    let receiver_texel = water_receiver_texel(tDepth, tNormal, receiver_coord, camera.projection_matrix_inverse,
-        camera.view_matrix_inverse);
-    if (above && !is_background(receiver_texel.depth)) {
-        let camera_ws = camera.view_matrix_inverse[3].xyz;
-        color *= water_receiver_downwelling(body, receiver_texel.position, receiver_texel.normal,
-            max(in.world.y - receiver_texel.position.y, 0.0), normalize(camera_ws - receiver_texel.position));
-    }
-    // Light in the water body (WATER_OPTICS_PLAN_2026_10_02.md §4.4): the receiver attenuated along
-    // the refracted path, and the sun and sky scattered back up it; both cross the surface by the
-    // n² law. A view from under the surface is outside this model: attenuation only.
-    let extinction = body.extinction.xyz;
-    var transmitted = exp(-extinction * max(path, 0.0));
-    var scattered = vec3f(0.0);
-    if (above) {
-        let exit = water_exit_factor(nov, ior);
-        let direction = normalize(direction_view_to_world(refract(surface.incident, surface.normal, 1.0 / ior), camera));
-        transmitted *= exit;
-        scattered = exit * water_inscatter(body, in.world, direction, max(path, 0.0), trace.inscatter_segments);
-    }
-    let event = water_event(transmitted, fresnel * reflection + scattered);
-    let optical = water_transport(event, original.rgb, color, metadata.z);
-    return WaterOptics(vec4f(optical.transmission, metadata.z), vec4f(optical.radiance, confidence),
-        vec4f(optical.background, original.a));
-}
-`, [surface_body, chunk_water_screen_ray, chunk_F_dielectric,
-    chunk_ffx_sssr_validate_hit, chunk_texture_sample_bilinear_uv,
-    chunk_direction_view_to_world, chunk_ray_at, chunk_water_optics, chunk_water_inscatter,
-    chunk_water_receiver_downwelling, chunk_water_receiver_texel,
-    chunk_water_transport, chunk_water_receiver_radiance, chunk_water_refraction_confidence]);
-
-export const water_shader = ShaderDescriptor.from({ label: "Water / receivers", resources, body });
-/** The optics pass under IBL, and under LPV, which has no transparent variant. */
-export const water_finalize_shader_ibl = ShaderDescriptor.from({ label: 'Water / coherent optics IBL',
-    resources: WATER_FINALIZE_RESOURCES_IBL, body: CodeChunk.from('', [finalize_body, chunk_water_gi_ibl]) });
-/** The optics pass under Brick4. */
-export const water_finalize_shader_brick4 = ShaderDescriptor.from({ label: 'Water / coherent optics Brick4',
-    resources: WATER_FINALIZE_RESOURCES_BRICK4, body: CodeChunk.from('', [finalize_body, chunk_water_gi_brick4]) });
-export const WATER_RESOURCES = resources;
-
-/** Nearest-interface selection writes only water-owned depth and optics, never opaque G-buffer. */
-function water_pipeline(shader, targets, finalize) {
-    const code = shader.source;
-    return RenderPipelineDescriptor.from({
-        label: shader.label,
-        layout: shader.resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-        vertex: { module: { code }, entryPoint: "vs_main" },
-        fragment: { module: { code }, entryPoint: "fs_main", targets: targets.map(format => ({ format })) },
-        depthStencil: DepthStencilState.from({ format: "depth32float", depthWriteEnabled: !finalize, depthCompare: finalize ? 'equal' : 'greater' }),
-        primitive: { topology: "triangle-list", cullMode: "none" },
-    });
-}
-export function create_water_pipeline() { return water_pipeline(water_shader, ['rgba32float', 'rgba32float'], false); }
-export function create_water_finalize_pipeline_ibl() { return water_pipeline(water_finalize_shader_ibl, ['rgba32float', 'rgba16float', 'rgba16float'], true); }
-export function create_water_finalize_pipeline_brick4() { return water_pipeline(water_finalize_shader_brick4, ['rgba32float', 'rgba16float', 'rgba16float'], true); }
+import { GPUShaderStage } from "../../descriptor/GPUShaderStage.js";
+import { DepthStencilState } from "../../descriptor/pipeline/render/DepthStencilState.js";
+import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { SHADING_LIGHT_RESOURCE_GROUP } from "../deferred/SHADING_LIGHT_RESOURCE_GROUP.js";
+import { BRICK4_DATA_STRUCT } from "../global_illumination/brick4/gpu/BRICK4_DATA_STRUCT.js";
+import { chunk_F_dielectric } from "../shader/chunk/brdf/fresnel/chunk_F_dielectric.js";
+import { chunk_direction_view_to_world } from "../shader/chunk/camera/chunk_direction_view_to_world.js";
+import { chunk_direction_world_to_view } from "../shader/chunk/camera/chunk_direction_world_to_view.js";
+import { chunk_ray_at } from "../shader/chunk/geometry/ray/chunk_ray_at.js";
+import { chunk_ffx_sssr_advance_ray } from "../shader/chunk/screen_space/chunk_ffx_sssr_advance_ray.js";
+import { chunk_ffx_sssr_load_depth } from "../shader/chunk/screen_space/chunk_ffx_sssr_load_depth.js";
+import { chunk_ffx_sssr_validate_hit } from "../shader/chunk/screen_space/chunk_ffx_sssr_validate_hit.js";
+import { chunk_project_direction } from "../shader/chunk/screen_space/chunk_project_direction.js";
+import { chunk_screen_space_newton_ray } from "../shader/chunk/screen_space/chunk_screen_space_newton_ray.js";
+import { chunk_texture_sample_bilinear_uv } from "../shader/chunk/texture/sample/chunk_texture_sample_bilinear_uv.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
+import { f32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+import { VIEW_UNIFORM_STRUCT } from "../view/VIEW_UNIFORM_STRUCT.js";
+import { chunk_water_gi_brick4, chunk_water_gi_ibl } from "./chunk_water_gi.js";
+import { WATER_BODIES_TABLE, WATER_WAVES_TABLE } from "./medium/chunk_water_bodies.js";
+import { MESHLET_METADATA_STRUCT } from "../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { COLLECTION_U32_STRUCT_READ } from "../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { chunk_lower_bound_branchless } from "../shader/chunk/math/chunk_lower_bound_branchless.js";
+import { chunk_water_tessellation, WATER_TILE_STRUCT, WATER_TESSELLATION_STRUCT, WATER_TILE_CELLS } from "./surface/chunk_water_tessellation.js";
+import { chunk_read_meshlet_vertex_by_draw_index } from "../shader/chunk/geometry/meshlet/chunk_read_meshlet_vertex_by_draw_index.js";
+import { chunk_scene_database_access } from "../scene/chunk_scene_database_access.js";
+import { chunk_mat3_inverse } from "../shader/chunk/geometry/mat3/chunk_mat3_inverse.js";
+import { NODE3D_GLOBAL_FLAG_MIRRORED } from "../scene/NODE3D_STRUCT.js";
+import { chunk_water_inscatter } from "./optics/chunk_water_inscatter.js";
+import { chunk_water_receiver_downwelling } from "./optics/chunk_water_receiver_downwelling.js";
+import { chunk_water_optics } from "./optics/chunk_water_optics.js";
+import { chunk_water_receiver_radiance, chunk_water_receiver_texel, chunk_water_refraction_confidence,
+    chunk_water_transport, WATER_LEVEL_TOLERANCE_DECLARATION } from './chunk_water_transport.js';
+
+export const WATER_GRID_STRUCT = WebGPUStruct.from({ resolution: u32 }, 'WaterGrid');
+
+export const WATER_TRACE_STRUCT = WebGPUStruct.from({
+    max_distance: f32, distance_tolerance: f32, max_updates: u32, fallback_steps: u32,
+    mode: u32, reflections: u32,
+    // steps of the water body's in-scatter along each refracted view ray
+    inscatter_segments: u32,
+}, "WaterTrace").pack();
+
+function water_resources(finalize = false) {
+    const resources = new ShaderResourceSetDescriptor();
+    const group = resources.createGroup()
+        .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+        .addUniform("trace", WATER_TRACE_STRUCT)
+        .addTexture("tDepth")
+        .addTexture("tNormal", "uint")
+        .addTexture("tHZB")
+        .addTexture("tScene")
+        .addStorageBuffer('scene_database', WebGPUArray.u32)
+        .addStorageBuffer('water_tiles', WebGPUArray.from(WATER_TILE_STRUCT))
+        .addStorageBuffer('water_tile_sums', COLLECTION_U32_STRUCT_READ)
+        .addUniform('tessellation', WATER_TESSELLATION_STRUCT)
+        .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT))
+        .addStorageBuffer('meshlet_data', WebGPUArray.from(f32))
+        .addStorageBuffer('wave_state', WebGPUArray.from(f32))
+        .addUniform('wave_grid', WATER_GRID_STRUCT);
+    if (finalize) {
+        group.addTexture('receiver').addTexture('trace_metadata').addTexture('visibility_distance');
+    }
+    return resources;
+}
+const resources = water_resources();
+
+/** Optics under IBL (and LPV, which has no transparent variant): the lights and the environment. */
+export const WATER_FINALIZE_RESOURCES_IBL = water_resources(true);
+WATER_FINALIZE_RESOURCES_IBL.addGroup(SHADING_LIGHT_RESOURCE_GROUP);
+
+/** Optics under Brick4: the lights, and the light map with the view its sampling jitters by. */
+export const WATER_FINALIZE_RESOURCES_BRICK4 = water_resources(true);
+WATER_FINALIZE_RESOURCES_BRICK4.addGroup(SHADING_LIGHT_RESOURCE_GROUP);
+WATER_FINALIZE_RESOURCES_BRICK4.createGroup()
+    .addStorageBuffer("brick4", BRICK4_DATA_STRUCT, false)
+    .addUniform("view", VIEW_UNIFORM_STRUCT);
+
+const surface_body = CodeChunk.from(/* language=WGSL */ `
+struct WaterVertexOut {
+    // Receivers and optics are separate modules drawing this mesh; optics tests depth 'equal'
+    // against the receivers' depth, and both must cover the same edge pixels. Only @invariant
+    // makes the position bit-identical across programs.
+    @invariant @builtin(position) clip: vec4<f32>,
+    @location(0) world: vec3<f32>,
+    @location(1) normal: vec3<f32>,
+    // slope variance of the waves the surface's mesh does not resolve
+    @location(2) unresolved_variance: f32,
+    @location(3) @interpolate(flat) body_index: u32,
+    @location(4) rest_normal: vec3<f32>,
+}
+
+fn water_wave_height(row: u32, cell: vec2i) -> f32 {
+    let n = i32(wave_grid.resolution);
+    let c = clamp(cell, vec2i(0), vec2i(n - 1));
+    return wave_state[row * u32(n * n) + u32(c.y * n + c.x)];
+}
+
+// One instance per occupied view tile and source triangle. All overlap candidates survive
+// classification; receiver depth selects the nearest displaced interface.
+@vertex
+fn vs_main(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> WaterVertexOut {
+    let row = lower_bound_branchless(&water_tile_sums.elements, ii + 1u, water_tile_sums.count);
+    let definition = water_tiles[row];
+    let body = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, definition.body);
+    let header = meshlet_metadata[definition.meshlet];
+    let node = scene_read_node(&scene_database, body.node);
+    var previous = 0u;
+    if (row > 0u) { previous = water_tile_sums.elements[row - 1u]; }
+    let patch_index = ii - previous;
+    let tile = definition.origin + vec2i(i32(patch_index % definition.size.x), i32(patch_index / definition.size.x));
+    let cell = vi / 18u;
+    let lattice = tile * ${WATER_TILE_CELLS} + vec2i(i32(cell % ${WATER_TILE_CELLS}u), i32(cell / ${WATER_TILE_CELLS}u));
+    let pixel = vec2f(lattice) * definition.pixels;
+    let ndc0 = pixel / tessellation.resolution * vec2f(2,-2) + vec2f(-1,1);
+    // Form both endpoints from their integer lattice coordinate. Adding the pitch to
+    // an already rounded pixel coordinate gives neighbouring cells different edges.
+    let ndc1 = (vec2f(lattice + vec2i(1)) * definition.pixels) / tessellation.resolution * vec2f(2,-2) + vec2f(-1,1);
+    let a = read_meshlet_vertex_by_draw_index(header, definition.triangle * 3u);
+    let b = read_meshlet_vertex_by_draw_index(header, definition.triangle * 3u + 1u);
+    let c = read_meshlet_vertex_by_draw_index(header, definition.triangle * 3u + 2u);
+    let simulated = body.wave != ~0u;
+    let ca = tessellation.view_projection_matrix * (node.global * vec4f(water_reference_position(a.position, definition.anchor, simulated), 1));
+    let cb = tessellation.view_projection_matrix * (node.global * vec4f(water_reference_position(b.position, definition.anchor, simulated), 1));
+    let cc = tessellation.view_projection_matrix * (node.global * vec4f(water_reference_position(c.position, definition.anchor, simulated), 1));
+    let polygon = water_cell_polygon(ca, cb, cc, min(ndc0,ndc1), max(ndc0,ndc1));
+    let fan = (vi % 18u) / 3u;
+    if (polygon.count < fan + 3u) { return WaterVertexOut(vec4f(0,0,0,1),vec3f(0),vec3f(0,1,0),0,definition.body,vec3f(0,1,0)); }
+    let corner = select(vi % 3u, 2u - vi % 3u, (node.global_flags & ${NODE3D_GLOBAL_FLAG_MIRRORED}u) != 0u);
+    var index = 0u;
+    if (corner != 0u) { index = fan + corner; }
+    let barycentric = polygon.points[index];
+    var position = water_corner_position(a.position,b.position,c.position,ca,cb,cc,barycentric,
+        polygon.boundaries[index],min(ndc0,ndc1),max(ndc0,ndc1));
+    var normal = normalize(a.normal * barycentric.x + b.normal * barycentric.y + c.normal * barycentric.z);
+    let rest_normal = normal;
+    var variance = 0.0;
+    if (body.wave != ~0u) {
+        let params = ${WATER_WAVES_TABLE.marshalling_method_read}(&scene_database, body.wave);
+        let spacing = max((params.extent.zw - params.extent.xy) / f32(wave_grid.resolution - 1u), vec2f(1e-20));
+        let grid = clamp((position.xz - params.extent.xy) / spacing, vec2f(0.0), vec2f(f32(wave_grid.resolution - 1u)));
+        let cell = vec2i(grid);
+        let blend = fract(grid);
+        let h00 = water_wave_height(body.wave, cell);
+        let h10 = water_wave_height(body.wave, cell + vec2i(1, 0));
+        let h01 = water_wave_height(body.wave, cell + vec2i(0, 1));
+        let h11 = water_wave_height(body.wave, cell + vec2i(1, 1));
+        position.y += mix(mix(h00, h10, blend.x), mix(h01, h11, blend.x), blend.y);
+        let slope = vec2f(mix(h10 - h00, h11 - h01, blend.y), mix(h01 - h00, h11 - h10, blend.x)) / spacing;
+        normal = normalize(vec3f(normal.x - normal.y * slope.x, normal.y, normal.z - normal.y * slope.y));
+        variance = params.unresolved_variance;
+    }
+    let world = (node.global * vec4f(position, 1.0)).xyz;
+    let linear = mat3x3f(node.global[0].xyz, node.global[1].xyz, node.global[2].xyz);
+    let inverse_transpose = transpose(mat3_inverse(linear));
+    let normal_ws = normalize(inverse_transpose * normal);
+    let rest_normal_ws = normalize(inverse_transpose * rest_normal);
+    return WaterVertexOut(camera.view_projection_matrix * vec4f(world, 1.0), world, normal_ws, variance, definition.body,rest_normal_ws);
+}
+
+// The interface at one water fragment, in view space. Receivers trace through it and optics
+// shade it, so both passes take it from here.
+struct WaterInterface {
+    origin: vec3<f32>,
+    incident: vec3<f32>,
+    // Faces the camera's side of the interface.
+    normal: vec3<f32>,
+    ior: f32,
+    // Screen-space travel bound.
+    limit: f32,
+}
+
+fn water_interface(world: vec3<f32>, surface_normal: vec3<f32>, ior: f32, above: bool) -> WaterInterface {
+    let origin = (camera.view_matrix * vec4f(world, 1.0)).xyz;
+    let view = normalize(camera.view_matrix_inverse[3].xyz - world);
+    let shading = normalize(select(-surface_normal, surface_normal, above));
+    // At a crest the interpolated shading normal can leave the rasterized face's
+    // visible hemisphere. Keep Snell/Fresnel on that face's side, continuously at grazing.
+    let normal_ws = normalize(shading + view * max(1e-4 - dot(shading,view), 0.0));
+    return WaterInterface(origin, normalize(origin), normalize(direction_world_to_view(normal_ws, camera)),
+        max(ior, 1.0), min(max(trace.max_distance, 0.1), camera.clip_near_far.y));
+}
+`, [chunk_direction_world_to_view, WATER_BODIES_TABLE.chunk_read, WATER_WAVES_TABLE.chunk_read,
+    chunk_read_meshlet_vertex_by_draw_index, chunk_scene_database_access, chunk_mat3_inverse,
+    chunk_lower_bound_branchless, chunk_water_tessellation]);
+
+export const chunk_water_screen_ray = CodeChunk.from(/* language=WGSL */ `
+fn water_hzb_mip_size(depth_size: vec2f, hzb_size: vec2f, mip: i32) -> vec2f {
+    if (mip <= 0) { return depth_size; }
+    return max(vec2f(1.0), floor(hzb_size / exp2(f32(mip-1))));
+}
+// Reuse the renderer's FFX cell intersection and depth loads, but walk the actual
+// integer mip grids. Its SSR driver halves floating sizes and assumes power-of-two
+// reductions; Meep's HZB conservatively resamples arbitrary viewport dimensions.
+fn water_hzb_crossing(origin: vec3f, direction: vec3f, budget: u32,
+    valid: ptr<function,bool>, iterations: ptr<function,u32>) -> vec3f {
+    let size = vec2f(textureDimensions(tDepth,0));
+    let pyramid_size = vec2f(textureDimensions(tHZB,0));
+    let last_mip = i32(textureNumLevels(tHZB));
+    let inverse_direction = select(vec3f(F32_MAX), 1.0/direction, abs(direction)>vec3f(1e-12));
+    let floor_offset = select(vec2f(1.0), vec2f(0.0), direction.xy<vec2f(0.0));
+    let uv_offset = select(0.005/size, -0.005/size, direction.xy<vec2f(0.0));
+    var mip = 0;
+    var position = origin;
+    var travel = 0.0;
+    *valid = false;
+    // Water is absent from the opaque depth buffer: skipping the initial pixel
+    // can skip the entire receiver for almost zero projected displacement.
+    for (var i=0u; i<min(budget,128u); i++) {
+        *iterations = i+1u;
+        if (!screen_space_ray_in_bounds(position.xy) || is_background(position.z)) { break; }
+        let resolution = water_hzb_mip_size(size,pyramid_size,mip);
+        let pixel = resolution * position.xy;
+        let depth = ffx_sssr_load_depth(vec2i(pixel),mip);
+        let skipped = ffx_sssr_advance_ray(origin,direction,inverse_direction,pixel,
+            1.0/resolution,floor_offset,uv_offset,depth,&position,&travel);
+        if (!skipped && mip==0) { *valid=true; break; }
+        mip = clamp(mip+select(-1,1,skipped),0,last_mip);
+    }
+    return position;
+}
+// HZB returns a depth-slab crossing, not the intersection of the ray with the
+// receiver's plane. Refine that crossing before using its UV or optical path.
+fn water_exact_receiver(ray: Ray, input: ScreenSpaceRayHit) -> ScreenSpaceRayHit {
+    var hit = input;
+    if (hit.status != 0u) { return hit; }
+    let receiver = screen_space_ray_load_receiver(hit.uv, tDepth, tNormal,
+        camera.projection_matrix_inverse, camera.view_matrix);
+    let travel = plane_ray_raycast(ray.origin, ray.direction, receiver.plane);
+    // Keep the analytic distance rather than the projection of the texel center onto the ray.
+    if (travel > 1e-4 && travel <= ray.tmax) {
+        hit.distance = travel;
+        hit.uv = project_position(ray_at(ray.origin, ray.direction, travel), camera.projection_matrix).xy;
+        // Reprojection can change texel ownership at a silhouette. Validate that lookup
+        // again; the analytic travel above already checked the ray's bounded interval.
+        let checked = screen_space_ray_validate(Ray(ray.origin,ray.direction,1e20),hit.uv,tDepth,tNormal,
+            camera.projection_matrix,camera.projection_matrix_inverse,camera.view_matrix,trace.distance_tolerance);
+        hit.status = checked.status;
+        hit.residual = checked.residual;
+    } else { hit.status = 4u; }
+    return hit;
+}
+fn water_refine_receiver(ray: Ray, seed: vec2f) -> ScreenSpaceRayHit {
+    // The traversal already selected the first depth footprint. Intersect its plane
+    // once and validate ownership; another Newton search could jump past that footprint
+    // to a later root that the traversal has already ruled out.
+    return water_exact_receiver(ray, ScreenSpaceRayHit(seed, 0.0, 1e20, 0u, 0u));
+}
+fn water_hzb_hit(ray: Ray, budget: u32) -> ScreenSpaceRayHit {
+    var miss = ScreenSpaceRayHit(vec2f(0.0), 0.0, 1e20, 0u, 5u);
+    if (budget == 0u || !screen_space_ray_projectable(ray.origin, camera.projection_matrix)
+        || !screen_space_ray_projectable(ray.origin + ray.direction, camera.projection_matrix)) { return miss; }
+    let origin = project_position(ray.origin, camera.projection_matrix);
+    let direction = project_direction(ray.origin, ray.direction, origin, camera.projection_matrix);
+    // Only rays advancing into reverse-Z are supported by this adapter.
+    if (direction.z >= -1e-8 || !screen_space_ray_in_bounds(origin.xy)) { return miss; }
+    var valid = false;
+    var iterations = 0u;
+    let candidate = water_hzb_crossing(origin, direction, budget, &valid, &iterations);
+    if (!valid) { miss.iterations = iterations; return miss; }
+    var hit = water_refine_receiver(ray, candidate.xy);
+    hit.iterations = iterations;
+    return hit;
+}
+`, [chunk_screen_space_newton_ray, chunk_ffx_sssr_advance_ray, chunk_ffx_sssr_load_depth, chunk_project_direction,
+    chunk_ray_at]);
+
+const body = CodeChunk.from(/* language=WGSL */ `
+struct WaterReceiver {
+    @location(0) receiver: vec4<f32>,
+    @location(1) metadata: vec4<f32>,
+    // Receiver UV, bounded path, classified status + Newton updates / 32. Readback is opt-in.
+}
+
+// A screen-space receiver must lie below the surface point the ray entered at: the refracted ray runs
+// downward from it, so any point on the ray is lower, and one that is not is a root off the ray.
+fn water_receiver_submerged(uv: vec2f, surface: vec3f, normal: vec3f) -> bool {
+    let receiver = water_receiver_texel(tDepth, tNormal, vec2i(uv * vec2f(textureDimensions(tDepth, 0))),
+        camera.projection_matrix_inverse, camera.view_matrix_inverse);
+    return dot(receiver.position - surface, normal) <= WATER_LEVEL_TOLERANCE;
+}
+
+@fragment
+fn fs_main(in: WaterVertexOut, @builtin(front_facing) above: bool) -> WaterReceiver {
+    let water = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, in.body_index);
+    let coord = vec2<i32>(in.clip.xy);
+    let dimensions = vec2f(textureDimensions(tDepth, 0));
+    let uv = in.clip.xy / dimensions;
+    let scene_depth = textureLoad(tDepth, coord, 0).r;
+    if (scene_depth >= in.clip.z) { discard; }
+    // the opaque scene behind this pixel, and how deep under the surface point it lies: shore water
+    // fades in over its first 10 cm, whatever is under it
+    var behind_vs = vec3f(0.0);
+    var water_depth = 1e20;
+    if (!is_background(scene_depth)) {
+        behind_vs = inv_project_position(vec3f(uv, scene_depth), camera.projection_matrix_inverse);
+        // Measure shore thickness relative to the authored surface. Wave crests
+        // becoming tangent to the view do not turn deep water into a shore fade.
+        // Both sides retain coverage; back faces use bounded below-interface transport.
+        water_depth = abs(dot(in.world - (camera.view_matrix_inverse * vec4f(behind_vs, 1.0)).xyz, normalize(in.rest_normal)));
+    }
+    let coverage = smoothstep(0.0, 0.1, water_depth);
+    let surface = water_interface(in.world, in.normal, water.ior, above);
+    let interface_normal = direction_view_to_world(surface.normal, camera);
+    let limit = surface.limit;
+    let direction = refract(surface.incident, surface.normal, 1.0 / surface.ior);
+    let ray = Ray(surface.origin, normalize(direction), limit);
+    var hit = ScreenSpaceRayHit(uv, limit, 1e20, 0u, 8u);
+    var newton_updates = 0u;
+    var newton_failure = 0u;
+    if (above && trace.mode == 0u) {
+        // Mayer et al. §2.2: a root within one pixel of the ray is accepted as is. Like the paper,
+        // this can converge past a thin occluder; traversal is only the fallback for failures.
+        hit = screen_space_newton_ray(ray, uv, tDepth, tNormal, camera.projection_matrix,
+            camera.projection_matrix_inverse, camera.view_matrix, trace.max_updates, trace.distance_tolerance);
+        newton_updates = hit.iterations;
+        newton_failure = hit.status;
+    }
+    // Reject foreground receivers before deciding whether traversal is needed.
+    if (hit.status == 0u && !water_receiver_submerged(hit.uv, in.world, interface_normal)) { hit.status = 5u; newton_failure = 5u; }
+    if (above && trace.mode != 2u && hit.status != 0u) {
+        let fallback = water_hzb_hit(ray, trace.fallback_steps);
+        if (fallback.status == 0u && water_receiver_submerged(fallback.uv, in.world, interface_normal)) { hit = fallback; hit.status = 6u; }
+    }
+    // Compute the control event for every pixel, independently of Newton/HZB success. With nothing
+    // behind the water on screen, integrate it to where it has taken all but a thousandth.
+    let clearest = min(min(water.extinction.x, water.extinction.y), water.extinction.z);
+    var control_path = min(log(1000.0) / max(clearest, 1e-30), limit);
+    var control_status = select(8u, 9u, !above);
+    if (!is_background(scene_depth)) {
+        if (water_depth >= -WATER_LEVEL_TOLERANCE || !above) {
+            control_path = min(distance(ray.origin, behind_vs), limit);
+            control_status = select(7u, 9u, !above);
+        }
+    }
+    if (trace.mode == 2u || !above || (hit.status != 0u && hit.status != 6u)) {
+        // Never use an unvalidated Newton iterate as a color lookup.
+        hit.uv = uv;
+        // A missing screen receiver is missing visibility, not 300 metres of water.
+        hit.distance = control_path;
+        hit.status = control_status;
+    }
+    var status = hit.status;
+    if (status == 6u) { status = 8u + newton_failure; }
+    else if (status == 7u) { status = 16u + newton_failure; }
+    else if (status == 8u) { status = 24u + newton_failure; }
+    else if (status == 9u) { status = 31u; }
+    return WaterReceiver(vec4f(hit.uv, hit.distance, f32(status) + f32(newton_updates)/32.0),
+        vec4f(control_path, min(hit.residual, 65504.0), coverage, f32(in.body_index + 1u)));
+}
+`, [surface_body, chunk_water_screen_ray, chunk_direction_view_to_world,
+    chunk_water_receiver_texel, WATER_LEVEL_TOLERANCE_DECLARATION]);
+
+const finalize_body = CodeChunk.from(/* language=WGSL */ `
+struct WaterOptics {
+    @location(0) transmission: vec4f,
+    @location(1) radiance: vec4f,
+    @location(2) background: vec4f,
+}
+@fragment
+fn fs_main(in: WaterVertexOut, @builtin(front_facing) above: bool) -> WaterOptics {
+    let water = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, in.body_index);
+    let coord = vec2i(in.clip.xy);
+    let metadata = textureLoad(trace_metadata, coord, 0);
+    // Equal-depth surfaces must retain the same deterministic owner as receiver selection.
+    if (metadata.w != f32(in.body_index + 1u)) { discard; }
+    let dimensions = vec2f(textureDimensions(tDepth, 0));
+    let uv = in.clip.xy / dimensions;
+    let receiver_data = textureLoad(receiver, coord, 0);
+    let surface = water_interface(in.world, in.normal, water.ior, above);
+    let interface_normal = direction_view_to_world(surface.normal, camera);
+    let body = water;
+    let origin = surface.origin;
+    let ior = surface.ior;
+    let limit = surface.limit;
+    let nov = clamp(dot(-surface.incident, surface.normal), 0.0, 1.0);
+    // exact dielectric Fresnel: water is most reflective at grazing angles, where Schlick's is not right
+    let fresnel = F_dielectric(nov, ior);
+    let reflection_direction = reflect(surface.incident, surface.normal);
+    // a reflection that misses on screen falls back to the GI mode, as SSR's resolve does
+    var reflection = water_gi_specular(in.world, direction_view_to_world(surface.normal, camera),
+        direction_view_to_world(-surface.incident, camera), clamp(sqrt(water.roughness * water.roughness + in.unresolved_variance), 0.0, 1.0));
+    if (trace.reflections != 0u && above) {
+        let reflected = water_hzb_hit(Ray(ray_at(origin, reflection_direction, 0.02), reflection_direction, limit),
+            trace.fallback_steps);
+        if (reflected.status == 0u) {
+            let reflected_point = ray_at(origin, reflection_direction, reflected.distance + 0.02);
+            let projected = project_position(reflected_point, camera.projection_matrix);
+            // Reflection uses the renderer's usual back-face, thickness, self-hit and
+            // vignette validation. Its two-pixel rule must not reject normal-incidence refraction.
+            let confidence = ffx_sssr_validate_hit(vec3f(reflected.uv, projected.z), uv,
+                reflection_direction, dimensions, max(trace.distance_tolerance, 0.02), 0.05);
+            let radiance = water_receiver_radiance(tScene, tDepth, tNormal, reflected.uv,
+                camera.projection_matrix_inverse, camera.view_matrix_inverse, in.world, interface_normal, false);
+            reflection = mix(reflection, radiance.rgb,
+                confidence * min(radiance.a * 2.0, 1.0) * smoothstep(0.05, 0.5, reflected.distance)
+                * smoothstep(1.0, 4.0, length((reflected.uv - uv) * dimensions)));
+        }
+    }
+    let original = textureLoad(tScene, coord, 0);
+    let valid = receiver_data.w < 16.0 && above && trace.mode != 2u;
+    var confidence = select(0.0, water_refraction_confidence(receiver_data.xy, uv, dimensions,
+        texture_sample_bilinear_uv(visibility_distance, uv, 0u).r), valid);
+    // Mayer's fade selects one UV, rather than crossfading two images of the same edge.
+    let lookup = water_refraction_lookup(uv, receiver_data.xy, confidence);
+    // The surface height here stands for the one above the displaced receiver: they differ by the
+    // wave height across a few metres, against a tolerance the gather already allows.
+    let gathered = water_receiver_radiance(tScene, tDepth, tNormal, lookup,
+        camera.projection_matrix_inverse, camera.view_matrix_inverse, in.world, interface_normal, above);
+    var path = metadata.x;
+    var color = original.rgb;
+    // the receiver seen through the surface: refracted, or the pixel's own when there is none
+    var receiver_coord = coord;
+    if (confidence > 0.0 && gathered.a > 0.0) {
+        path = min(water_receiver_path(tDepth, tNormal, lookup, camera.projection_matrix_inverse,
+            camera.view_matrix, origin), limit);
+        color = gathered.rgb;
+        receiver_coord = vec2i(lookup * dimensions);
+    } else { confidence = 0.0; }
+    // The opaque scene was shaded dry: what reaches the receiver is what survives the water above it
+    // (WATER_OPTICS_PLAN_2026_10_02.md §4.3). Seen from under the surface, the receiver is above it.
+    let receiver_texel = water_receiver_texel(tDepth, tNormal, receiver_coord, camera.projection_matrix_inverse,
+        camera.view_matrix_inverse);
+    if (above && !is_background(receiver_texel.depth)) {
+        let camera_ws = camera.view_matrix_inverse[3].xyz;
+        let up = normalize(in.rest_normal);
+        color *= water_receiver_downwelling(body, receiver_texel.position, receiver_texel.normal, up,
+            max(dot(in.world - receiver_texel.position, up), 0.0), normalize(camera_ws - receiver_texel.position));
+    }
+    // Light in the water body (WATER_OPTICS_PLAN_2026_10_02.md §4.4): the receiver attenuated along
+    // the refracted path, and the sun and sky scattered back up it; both cross the surface by the
+    // n² law. A view from under the surface is outside this model: attenuation only.
+    let extinction = body.extinction.xyz;
+    var transmitted = exp(-extinction * max(path, 0.0));
+    var scattered = vec3f(0.0);
+    if (above) {
+        let exit = water_exit_factor(nov, ior);
+        let direction = normalize(direction_view_to_world(refract(surface.incident, surface.normal, 1.0 / ior), camera));
+        transmitted *= exit;
+        scattered = exit * water_inscatter(body, in.world, direction, normalize(in.rest_normal), max(path, 0.0), trace.inscatter_segments);
+    }
+    let event = water_event(transmitted, fresnel * reflection + scattered);
+    let optical = water_transport(event, original.rgb, color, metadata.z);
+    return WaterOptics(vec4f(optical.transmission, metadata.z), vec4f(optical.radiance, confidence),
+        vec4f(optical.background, original.a));
+}
+`, [surface_body, chunk_water_screen_ray, chunk_F_dielectric,
+    chunk_ffx_sssr_validate_hit, chunk_texture_sample_bilinear_uv,
+    chunk_direction_view_to_world, chunk_ray_at, chunk_water_optics, chunk_water_inscatter,
+    chunk_water_receiver_downwelling, chunk_water_receiver_texel,
+    chunk_water_transport, chunk_water_receiver_radiance, chunk_water_refraction_confidence]);
+
+export const water_shader = ShaderDescriptor.from({ label: "Water / receivers", resources, body });
+/** The optics pass under IBL, and under LPV, which has no transparent variant. */
+export const water_finalize_shader_ibl = ShaderDescriptor.from({ label: 'Water / coherent optics IBL',
+    resources: WATER_FINALIZE_RESOURCES_IBL, body: CodeChunk.from('', [finalize_body, chunk_water_gi_ibl]) });
+/** The optics pass under Brick4. */
+export const water_finalize_shader_brick4 = ShaderDescriptor.from({ label: 'Water / coherent optics Brick4',
+    resources: WATER_FINALIZE_RESOURCES_BRICK4, body: CodeChunk.from('', [finalize_body, chunk_water_gi_brick4]) });
+export const WATER_RESOURCES = resources;
+
+/** Nearest-interface selection writes only water-owned depth and optics, never opaque G-buffer. */
+function water_pipeline(shader, targets, finalize) {
+    const code = shader.source;
+    const layout = shader.resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT);
+    // Tile reconstruction spends six storage slots. Lighting spends four in the fragment stage.
+    // Keep their visibility precise so the Brick4 variant fits the guaranteed stage budget.
+    const vertex_only = new Set(['water_tiles', 'water_tile_sums', 'tessellation', 'meshlet_metadata', 'meshlet_data', 'wave_state', 'wave_grid']);
+    shader.resources.groups.forEach((group, gi) => group.resources.forEach((resource, ri) => {
+        layout.bindGroupLayouts[gi].entries[ri].visibility = vertex_only.has(resource.name) ? GPUShaderStage.VERTEX
+            : resource.name === 'camera' || resource.name === 'scene_database' ? GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT
+            : GPUShaderStage.FRAGMENT;
+    }));
+    return RenderPipelineDescriptor.from({
+        label: shader.label,
+        layout,
+        vertex: { module: { code }, entryPoint: "vs_main" },
+        fragment: { module: { code }, entryPoint: "fs_main", targets: targets.map(format => ({ format })) },
+        depthStencil: DepthStencilState.from({ format: "depth32float", depthWriteEnabled: !finalize, depthCompare: finalize ? 'equal' : 'greater' }),
+        primitive: { topology: "triangle-list", cullMode: "none" },
+    });
+}
+export function create_water_pipeline() { return water_pipeline(water_shader, ['rgba32float', 'rgba32float'], false); }
+export function create_water_finalize_pipeline_ibl() { return water_pipeline(water_finalize_shader_ibl, ['rgba32float', 'rgba16float', 'rgba16float'], true); }
+export function create_water_finalize_pipeline_brick4() { return water_pipeline(water_finalize_shader_brick4, ['rgba32float', 'rgba16float', 'rgba16float'], true); }