@woosh/meep-engine 3.37.0 → 3.39.0

package/src/shade/playground/sh_exponential/sh_exp_playground_shaders.js

@@ -0,0 +1,270 @@
+import { chunk_get_ibl_radiance } from "../../renderer/deferred/indirect/chunk_get_ibl_radiance.js";
+import { chunk_sh_exp_p4q2_base_reflectance } from "../../renderer/shader/chunk/spherical_harmonics/exponential/chunk_sh_exp_p4q2_base_reflectance.js";
+import { SH_EXP_P4Q2_PROBE_STRUCT } from "../../renderer/shader/chunk/spherical_harmonics/exponential/SH_EXP_P4Q2_PROBE_STRUCT.js";
+import { chunk_D_GGX } from "../../renderer/shader/chunk/brdf/chunk_D_GGX.js";
+import { chunk_V_GGX_SmithCorrelated } from "../../renderer/shader/chunk/brdf/chunk_V_GGX_SmithCorrelated.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.js";
+import { f32, u32, vec4f } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../../renderer/texture/SAMPLER_LINEAR_UPSCALE.js";
+
+/**
+ * Rows of the sphere grid, top to bottom.
+ * @type {string[]}
+ */
+export const PLAYGROUND_ROWS = [
+    'reference (quadrature)',
+    'SH exponential, P4 Q2',
+    'engine IBL (split sum)',
+    'SH exponential − reference',
+];
+
+/**
+ * Step through the reference grid's cells: odd, so it visits every cell of a power-of-two grid once
+ * per pass, and large, so any run of consecutive steps is spread over the sphere and a partial sum
+ * is already a fair estimate of the whole.
+ *
+ * @type {number}
+ */
+export const REFERENCE_CELL_STRIDE = 7919;
+
+/**
+ * What both playground kernels read.
+ *
+ * - `right`, `up`, `back`: the orthographic camera's basis; `back` points at the viewer and is every
+ *   pixel's view direction;
+ * - `cell_size`: pixels per sphere cell, `columns` spheres per row, one per roughness;
+ * - `alpha_first_root`, `alpha_root_step`: column `c` is at roughness `first + step * c`, GGX alpha
+ *   its square — the paper's own sweep is 0.3 to 1 in steps of 0.1;
+ * - `slice_start`, `slice_count`: which reference cells this frame adds; `processed` how many will
+ *   have been added after it, of `cell_count`;
+ * - `exposure`, `error_gain`: display only.
+ *
+ * @type {WebGPUStruct}
+ */
+export const PLAYGROUND_VIEW_STRUCT = WebGPUStruct.from({
+    right: vec4f,
+    up: vec4f,
+    back: vec4f,
+    cell_size: u32,
+    columns: u32,
+    slice_start: u32,
+    slice_count: u32,
+    cell_count: u32,
+    processed: u32,
+    alpha_first_root: f32,
+    alpha_root_step: f32,
+    exposure: f32,
+    error_gain: f32,
+}, "SHExpPlaygroundView");
+
+/**
+ * The sphere a pixel of a cell sees: `w` is 1 on the sphere and 0 off it, `xyz` the world normal.
+ */
+const chunk_playground_sphere = CodeChunk.from(
+    //language=WGSL
+    `
+const SPHERE_RADIUS : f32 = 0.92;
+
+fn playground_sphere_normal(local: vec2<u32>) -> vec4<f32> {
+    let p = (vec2<f32>(local) + 0.5) / f32(view.cell_size) * 2.0 - 1.0;
+    // screen y grows downwards
+    let q = vec2<f32>(p.x, -p.y) / SPHERE_RADIUS;
+    let r2 = dot(q, q);
+
+    if (r2 >= 1.0) {
+        return vec4<f32>(0.0);
+    }
+
+    let normal = view.right.xyz * q.x + view.up.xyz * q.y + view.back.xyz * sqrt(1.0 - r2);
+
+    return vec4<f32>(normalize(normal), 1.0);
+}
+
+fn playground_alpha(column: u32) -> f32 {
+    let root = view.alpha_first_root + view.alpha_root_step * f32(column);
+    return root * root;
+}
+`);
+
+const accumulate_resources = new ShaderResourceSetDescriptor();
+
+accumulate_resources.createGroup()
+    .addUniform("view", PLAYGROUND_VIEW_STRUCT)
+    .addStorageBuffer("cells", WebGPUArray.from(vec4f), false)
+    .addStorageBuffer("accumulation", WebGPUArray.from(vec4f), true);
+
+/**
+ * Adds one slice of the reference quadrature to every sphere pixel: `E0` summed over
+ * `slice_count` cells of an octahedral grid made by `shader_sh_exp_environment_cells`, at a finer
+ * resolution than the encoder fits on. Spread over frames, so no invocation loops over the sphere.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_playground_accumulate_reference = ComputeShader.from({
+    label: "SH exponential playground / accumulate reference",
+    resources: accumulate_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(8, 8)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let width = view.columns * view.cell_size;
+
+    if (id.x >= width || id.y >= view.cell_size) {
+        return;
+    }
+
+    let column = id.x / view.cell_size;
+    let local = vec2<u32>(id.x % view.cell_size, id.y);
+    let sphere = playground_sphere_normal(local);
+
+    if (sphere.w == 0.0) {
+        return;
+    }
+
+    let normal = sphere.xyz;
+    let view_direction = view.back.xyz;
+    let NoV = max(dot(normal, view_direction), 1e-4);
+    let alpha = playground_alpha(column);
+    let alpha2 = alpha * alpha;
+
+    var sum = vec3<f32>(0.0);
+
+    // a uniform trip count: the slice is the same for every pixel
+    for (var k = 0u; k < view.slice_count; k++) {
+        let cell = ((view.slice_start + k) * ${REFERENCE_CELL_STRIDE}u) % view.cell_count;
+        let light = cells[2u * cell].xyz;
+        let NoL = dot(normal, light);
+
+        if (NoL > 0.0) {
+            let half_vector = normalize(light + view_direction);
+            let NoH = saturate(dot(normal, half_vector));
+
+            sum += cells[2u * cell + 1u].xyz * (D_GGX(alpha2, NoH * NoH) * V_GGX_SmithCorrelated(alpha, NoL, NoV) * NoL);
+        }
+    }
+
+    let pixel = column * view.cell_size * view.cell_size + local.y * view.cell_size + local.x;
+
+    accumulation[pixel] += vec4<f32>(sum, 0.0);
+}
+`, [
+            chunk_playground_sphere,
+            chunk_D_GGX,
+            chunk_V_GGX_SmithCorrelated,
+        ]),
+});
+
+const view_resources = new ShaderResourceSetDescriptor();
+
+view_resources.createGroup()
+    .addUniform("view", PLAYGROUND_VIEW_STRUCT)
+    .addTexture("tEnvironment")
+    .addTexture("tSplitSum", "float")
+    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
+    .addStorageBuffer("probe", SH_EXP_P4Q2_PROBE_STRUCT, false)
+    .addStorageBuffer("accumulation", WebGPUArray.from(vec4f), false)
+    .addStorageBuffer("values", WebGPUArray.from(vec4f), true)
+    .addStorageTexture("output", "rgba8unorm", "2d", "write-only");
+
+/**
+ * Draws the four rows of {@link PLAYGROUND_ROWS}, and writes the linear values of the first three
+ * into `values` (`[row][column][pixel]`, `w` = 1 on the sphere) for `verify()` to read.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_playground_view = ComputeShader.from({
+    label: "SH exponential playground / view",
+    resources: view_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+const BACKGROUND = vec3<f32>(0.035);
+
+fn tonemap(x: vec3<f32>) -> vec3<f32> {
+    return vec3<f32>(1.0) - exp(-max(x, vec3<f32>(0.0)) * view.exposure);
+}
+
+fn srgb_encode(x: vec3<f32>) -> vec3<f32> {
+    let low = x * 12.92;
+    let high = 1.055 * pow(x, vec3<f32>(1.0 / 2.4)) - 0.055;
+    return select(high, low, x <= vec3<f32>(0.0031308));
+}
+
+fn luminance(x: vec3<f32>) -> f32 {
+    return dot(x, vec3<f32>(0.2126, 0.7152, 0.0722));
+}
+
+@compute @workgroup_size(8, 8)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let width = view.columns * view.cell_size;
+
+    if (id.x >= width || id.y >= 4u * view.cell_size) {
+        return;
+    }
+
+    let column = id.x / view.cell_size;
+    let row = id.y / view.cell_size;
+    let local = vec2<u32>(id.x % view.cell_size, id.y % view.cell_size);
+    let pixel = column * view.cell_size * view.cell_size + local.y * view.cell_size + local.x;
+    let slots = view.columns * view.cell_size * view.cell_size;
+
+    let sphere = playground_sphere_normal(local);
+
+    if (sphere.w == 0.0) {
+        if (row < 3u) {
+            values[row * slots + pixel] = vec4<f32>(0.0);
+        }
+
+        textureStore(output, id.xy, vec4<f32>(srgb_encode(BACKGROUND), 1.0));
+        return;
+    }
+
+    let normal = sphere.xyz;
+    let view_direction = view.back.xyz;
+    let alpha = playground_alpha(column);
+    let roughness = sqrt(alpha);
+
+    // the partial sum so far stands for the whole sphere: the cells it has seen are spread over it
+    let reference = accumulation[pixel].xyz * (f32(view.cell_count) / f32(max(view.processed, 1u)));
+    let sh_exp = sh_exp_p4q2_base_reflectance(probe, view_direction, normal, alpha);
+
+    var value = vec3<f32>(0.0);
+
+    if (row == 0u) {
+        value = reference;
+    } else if (row == 1u) {
+        value = sh_exp;
+    } else if (row == 2u) {
+        // the forward path's specular with Fresnel taken out: prefiltered radiance times the
+        // split sum's F0 scale plus F90 bias, which together are the GGX directional albedo (the engine's
+        // LUT, to within 0.06%; see chunk_sh_exp_split_sum)
+        let NoV = saturate(dot(normal, view_direction));
+        let dfg = textureSampleLevel(tSplitSum, sLinear, vec2<f32>(NoV, roughness), 0.0).rg;
+
+        value = get_ibl_radiance(view_direction, normal, roughness) * (dfg.x + dfg.y);
+    }
+
+    var color: vec3<f32>;
+
+    if (row < 3u) {
+        values[row * slots + pixel] = vec4<f32>(value, 1.0);
+        color = tonemap(value);
+    } else {
+        // red: SH exponential brighter than the reference, blue: darker; on the tonemapped scale
+        let difference = (luminance(tonemap(sh_exp)) - luminance(tonemap(reference))) * view.error_gain;
+        color = vec3<f32>(max(difference, 0.0), 0.0, max(-difference, 0.0));
+    }
+
+    textureStore(output, id.xy, vec4<f32>(srgb_encode(saturate(color)), 1.0));
+}
+`, [
+            chunk_playground_sphere,
+            chunk_sh_exp_p4q2_base_reflectance,
+            chunk_get_ibl_radiance,
+        ]),
+});

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

@@ -0,0 +1,158 @@
+# 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. The surface is a real mesh: a primitive wave simulation on a
+512² grid over the body, driven by the WaterWaves component (wind speed and direction), writes its
+its mesh behind the surface interface the production simulation will replace
+(WATER_OPTICS_PLAN_2026_10_02.md §7.2). Screen reflections can be disabled while retaining the
+fallback to the renderer's indirect lighting (IBL, or Brick4 when it is the active mode).
+The Newton, bounded HZB traversal, and undisplaced control modes all use the same AVBOIT path.
+The Medium select picks one of the water presets (`shade/renderer/medium/water/water_presets.js`):
+what fills the body as absorption and scattering in 1/m. The body's colour is not authored — it is the sun
+and sky scattered back up the refracted view ray, single scattering for now, and In-scatter segments
+sets how many steps that integral takes. Seen from above, light leaving the water crosses the surface
+by Fresnel and the n² law, so the floor reads about half as bright as it would dry.
+
+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 converged Newton 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
+reflection and in-scattered radiance and its RGB transmittance; 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.
+As in the paper, a converged Newton root is final: screen bounds plus the one-pixel and distance
+residuals accept it, with no further visibility proof. Like the paper's method it can converge past
+a thin occluder between the interface and the receiver; that is the accepted cost of a few G-buffer
+reads per pixel. Pixels Newton fails fall back to 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 past the first footprint to a root the traversal has ruled out.
+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. Each Newton lookup reads depth and face normal once: the plane that rejects one lookup
+is the tangent plane for the next update, so N updates read N+1 texels. Fallback steps bound only
+the traversal for failed pixels and screen reflections.
+
+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; disocclusion fades 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,
+converged roots kept without a traversal budget, 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,40 @@
+<!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>Wind m/s<input id="wind" type="range" min="0" max="12" step=".1" value="3"></label>
+<label>Wind direction °<input id="wind_direction" type="range" min="0" max="360" step="1" value="30"></label>
+<label>Roughness<input id="roughness" type="range" min="0" max="1" step=".01" value=".02"></label>
+<label>Medium<select id="medium"><option value="swimming_pool">Swimming pool</option><option value="clear_ocean">Clear ocean</option><option value="tropical_lagoon">Tropical lagoon</option><option value="open_ocean" selected>Open ocean</option><option value="coastal">Coastal</option><option value="green_lake">Green lake</option><option value="turbid_river">Turbid river</option></select></label>
+<label>In-scatter segments<input id="segments" type="range" min="1" max="16" step="1" value="4"></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><label>Warp steps (4 per octave)<input id="warp_steps" type="checkbox" checked></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":""}