@aura3d/engine 3.0.0 → 4.0.0

package/dist/rendering/world/water/UnderwaterState.js

@@ -0,0 +1,134 @@
+/**
+ * PRD-10 §8.7 / T4.5 — underwater state + caustics wiring.
+ *
+ * `isUnderwater` asks whether a world-space point sits below a water body's
+ * Gerstner surface at time t — evaluated by the caller's `heightAt` (the
+ * `AuraWaterHandle`, same formula as the vertex shader). The frame pass uses
+ * it to flip the fog request to C-21 absorption and to enable the
+ * `prd10.underwaterDistortion` post pass.
+ *
+ * `registerPrd10Caustics()` lands the `a3d_prd10_caustics` chunk as the C-02
+ * ShaderFeature `prd10.caustics` (hooks `fragment:pars` + `fragment:indirect`, define
+ * `A3D_PRD10_CAUSTICS`) so Path G materials pick up the direct-sun boost
+ * automatically; Path S programs link the chunk explicitly.
+ */
+import { registerShaderFeature } from "../../contracts/program.js";
+import { registerPostPass } from "../../contracts/post.js";
+import { a3d_prd10_caustics } from "./shaders/caustics.js";
+import { Texture } from "../../Texture.js";
+import { Sampler } from "../../Sampler.js";
+import { TextureBinding } from "../../TextureBinding.js";
+/** True when `point` sits under the water surface at `timeSeconds`. */
+export function isUnderwaterPoint(point, heightAt, timeSeconds) {
+    return point[1] < heightAt(point[0], point[2], timeSeconds);
+}
+// -------------------------------------------------------------------------
+// `prd10.underwaterDistortion` — C-13 post pass in `linear-hdr`, 2-tap UV
+// offset (§8.7). Enabled only while the camera is submerged (the frame
+// contributor flips the blackboard key).
+//
+// The fragment follows the §6.12 custom-pass contract
+// (`customPassFragmentSource`): the engine prelude already declares
+// `u_color`, `u_depthLinear`, `u_velocity`, `u_texelSize`, `u_time`, `v_uv`
+// and `outColor`, so the pass declares only `u_distortion` and a `main()`.
+// The first body redeclared `u_time`, sampled an unbound `u_scene` and had no
+// `main()` — it could never compile once enabled. C-13 binds no extra
+// textures, so the two taps use an analytic wave field instead of the water
+// detail-normal atlas (§8.7 deviation, recorded in evidence/prd-10/phase-4.md).
+export const UNDERWATER_KEY = "prd10.water.underwater";
+export const UNDERWATER_DISTORTION_GLSL = /* glsl */ `
+uniform vec2 u_distortion;     // amplitude in UV units (~0.004)
+vec2 a3dUnderwaterWave(vec2 uv, float t) {
+  vec2 o1 = vec2(sin(uv.y * 41.0 + t * 1.7), cos(uv.x * 37.0 - t * 1.3));
+  vec2 o2 = vec2(sin((uv.x + uv.y) * 73.0 - t * 2.3), cos((uv.x - uv.y) * 67.0 + t * 1.9));
+  return (o1 + 0.5 * o2) / 1.5;
+}
+vec4 a3dUnderwaterDistort(vec2 uv) {
+  vec2 duv = uv + a3dUnderwaterWave(uv, u_time) * u_distortion;
+  return texture(u_color, clamp(duv, vec2(0.0), vec2(1.0)));
+}
+void main() {
+  outColor = a3dUnderwaterDistort(v_uv);
+}
+`;
+export const UNDERWATER_DISTORTION_WGSL = /* wgsl */ `
+@group(0) @binding(0) var u_color : texture_2d<f32>;
+@group(0) @binding(1) var u_samp : sampler;
+struct A3dUnderwater { time : f32, pad : f32, distortion : vec2f };
+@group(0) @binding(2) var<uniform> u : A3dUnderwater;
+fn a3dUnderwaterWave(uv : vec2f, t : f32) -> vec2f {
+  let o1 = vec2f(sin(uv.y * 41.0 + t * 1.7), cos(uv.x * 37.0 - t * 1.3));
+  let o2 = vec2f(sin((uv.x + uv.y) * 73.0 - t * 2.3), cos((uv.x - uv.y) * 67.0 + t * 1.9));
+  return (o1 + 0.5 * o2) / 1.5;
+}
+fn a3dUnderwaterDistort(uv : vec2f) -> vec4f {
+  let duv = uv + a3dUnderwaterWave(uv, u.time) * u.distortion;
+  return textureSampleLevel(u_color, u_samp, clamp(duv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+`;
+const REPEAT = new Sampler({ minFilter: "linear", magFilter: "linear", addressU: "repeat", addressV: "repeat" });
+let fallbackAtlas;
+let causticsState = {
+    scale: 2,
+    strength: 0,
+    waterHeight: 0,
+    sunDirection: [0.42, 0.9, 0.18],
+    atlasBinding: undefined
+};
+export function setPrd10CausticsState(state) {
+    causticsState = {
+        scale: state.scale ?? causticsState.scale,
+        strength: state.strength ?? causticsState.strength,
+        waterHeight: state.waterHeight ?? causticsState.waterHeight,
+        sunDirection: state.sunDirection ?? causticsState.sunDirection,
+        atlasBinding: state.atlas ? new TextureBinding({ name: "u_causticAtlas", texture: state.atlas, sampler: REPEAT }) : state.atlas === null ? undefined : causticsState.atlasBinding
+    };
+}
+function causticAtlasBinding() {
+    if (causticsState.atlasBinding)
+        return causticsState.atlasBinding;
+    fallbackAtlas ??= new Texture({ width: 1, height: 1, format: "rgba8", colorSpace: "linear", label: "prd10-caustics-fallback", data: new Uint8Array([0, 0, 0, 255]) });
+    causticsState.atlasBinding = new TextureBinding({ name: "u_causticAtlas", texture: fallbackAtlas, sampler: REPEAT });
+    return causticsState.atlasBinding;
+}
+/** Register `prd10.caustics` + `prd10.underwaterDistortion`; returns unregister. */
+export function registerPrd10UnderwaterFeatures() {
+    const unCaustics = registerShaderFeature({
+        id: "prd10.caustics",
+        owner: "prd10",
+        flag: "A3D_QR_WORLD",
+        select: (input) => input.item.label?.startsWith("prd10.caustics:") ? 1 : undefined,
+        defines: (v) => (v ? { A3D_PRD10_CAUSTICS: 1 } : {}),
+        // #1143 (C-02 pars/call split): declarations at fragment:pars, the boost
+        // call appended at fragment:indirect so the default light loop still runs
+        // (a fragment:lights claim would replace it). `a3d_prd10_caustics` stays
+        // the Path S chunk.
+        chunks: ["a3d_prd10_caustics_pars", "a3d_prd10_caustics_apply"],
+        hooks: ["fragment:pars", "fragment:indirect"],
+        bindUniforms: (_value, _item, set) => {
+            set("u_causticAtlas", causticAtlasBinding());
+            set("u_causticScale", causticsState.scale);
+            set("u_causticStrength", causticsState.strength);
+            set("u_waterHeight", causticsState.waterHeight);
+            set("u_causticSunDir", new Float32Array(causticsState.sunDirection));
+        }
+    });
+    const unDistortion = registerPostPass({
+        id: "prd10.underwaterDistortion",
+        owner: "prd10",
+        flag: "A3D_QR_WORLD",
+        insertAt: "after-depth",
+        space: "linear-hdr",
+        inputs: ["color"],
+        fragment: { glsl: UNDERWATER_DISTORTION_GLSL, wgsl: UNDERWATER_DISTORTION_WGSL },
+        enabled: (frame) => frame.blackboard.get(UNDERWATER_KEY) === true,
+        uniforms: () => ({ u_distortion: [0.004, 0.004] }),
+        gpuOnly: true
+    });
+    return () => {
+        unCaustics();
+        unDistortion();
+    };
+}
+export { a3d_prd10_caustics };
+//# sourceMappingURL=UnderwaterState.js.map

package/dist/rendering/world/water/UnderwaterState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnderwaterState.js","sourceRoot":"","sources":["../../../../../../packages/rendering/src/world/water/UnderwaterState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,qBAAqB,EAAiC,MAAM,4BAA4B,CAAC;AAClG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAC/B,KAAwC,EACxC,QAAqD,EACrD,WAAmB;IAEnB,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;AAC9D,CAAC;AAED,4EAA4E;AAC5E,0EAA0E;AAC1E,uEAAuE;AACvE,yCAAyC;AACzC,EAAE;AACF,sDAAsD;AACtD,oEAAoE;AACpE,4EAA4E;AAC5E,2EAA2E;AAC3E,8EAA8E;AAC9E,sEAAsE;AACtE,4EAA4E;AAC5E,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAG,wBAAwB,CAAC;AAEvD,MAAM,CAAC,MAAM,0BAA0B,GAAG,UAAU,CAAC;;;;;;;;;;;;;;CAcpD,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,UAAU,CAAC;;;;;;;;;;;;;;CAcpD,CAAC;AAgBF,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;AACjH,IAAI,aAAkC,CAAC;AACvC,IAAI,aAAa,GAA+F;IAC9G,KAAK,EAAE,CAAC;IACR,QAAQ,EAAE,CAAC;IACX,WAAW,EAAE,CAAC;IACd,YAAY,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC;IAC/B,YAAY,EAAE,SAAS;CACxB,CAAC;AAEF,MAAM,UAAU,qBAAqB,CAAC,KAAyB;IAC7D,aAAa,GAAG;QACd,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,aAAa,CAAC,KAAK;QACzC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,aAAa,CAAC,QAAQ;QAClD,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,aAAa,CAAC,WAAW;QAC3D,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,aAAa,CAAC,YAAY;QAC9D,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,YAAY;KAClL,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB;IAC1B,IAAI,aAAa,CAAC,YAAY;QAAE,OAAO,aAAa,CAAC,YAAY,CAAC;IAClE,aAAa,KAAK,IAAI,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,yBAAyB,EAAE,IAAI,EAAE,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IACtK,aAAa,CAAC,YAAY,GAAG,IAAI,cAAc,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACrH,OAAO,aAAa,CAAC,YAAY,CAAC;AACpC,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,+BAA+B;IAC7C,MAAM,UAAU,GAAG,qBAAqB,CAAC;QACvC,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,CAAC,KAA+B,EAAE,EAAE,CAC1C,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;QACjE,OAAO,EAAE,CAAC,CAAC,EAAoD,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtG,yEAAyE;QACzE,0EAA0E;QAC1E,yEAAyE;QACzE,oBAAoB;QACpB,MAAM,EAAE,CAAC,yBAAyB,EAAE,0BAA0B,CAAC;QAC/D,KAAK,EAAE,CAAC,eAAe,EAAE,mBAAmB,CAAC;QAC7C,YAAY,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACnC,GAAG,CAAC,gBAAgB,EAAE,mBAAmB,EAAE,CAAC,CAAC;YAC7C,GAAG,CAAC,gBAAgB,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;YAC3C,GAAG,CAAC,mBAAmB,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;YACjD,GAAG,CAAC,eAAe,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;YAChD,GAAG,CAAC,iBAAiB,EAAE,IAAI,YAAY,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;QACvE,CAAC;KACF,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,gBAAgB,CAAC;QACpC,EAAE,EAAE,4BAA4B;QAChC,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,cAAc;QACpB,QAAQ,EAAE,aAAa;QACvB,KAAK,EAAE,YAAY;QACnB,MAAM,EAAE,CAAC,OAAO,CAAC;QACjB,QAAQ,EAAE,EAAE,IAAI,EAAE,0BAA0B,EAAE,IAAI,EAAE,0BAA0B,EAAE;QAChF,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,IAAI;QACjE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,IAAI;KACd,CAAC,CAAC;IACH,OAAO,GAAG,EAAE;QACV,UAAU,EAAE,CAAC;QACb,YAAY,EAAE,CAAC;IACjB,CAAC,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/rendering/world/water/WaterMaterial.d.ts

@@ -0,0 +1,23 @@
+/**
+ * PRD-10 §8.6 / T4.2 — `WaterMaterial`: the standalone water surface program.
+ * Composes the `a3d_prd10_gerstner` vertex chunk (wave displacement +
+ * `v_crest`), the `a3d_prd10_water` fragment chunk (UDN normals, Fresnel,
+ * depth refraction, Beer-Lambert, foam) and `a3d_prd10_world_light_fallback`
+ * (env specular / sun GGX / shadow stub / linear fog) into `ShaderSources`
+ * that `WaterRuntime` draws in the `transparent` phase.
+ *
+ * `A3D_PRD10_WATER_HAS_SCENE` selects the refraction path: 0 = Low (deep/
+ * shallow mix from the `a_shore` vertex attribute, no scene copy — §8.6 Low),
+ * 1 = scene color + depth copies (foreground-reject refraction + shore foam).
+ * `A3D_PRD10_WATER_PLANAR` binds the planar reflection texture when a
+ * `ReflectionViewPass` captured one this frame.
+ */
+import type { ShaderSources } from "../../RenderDevice.js";
+/** Full §8.6 program. `hasScene`/`planar` bake the feature defines. */
+export declare function waterShaderSources(options: {
+    readonly hasScene: boolean;
+    readonly planar: boolean;
+}): ShaderSources;
+/** Underwater back-face program (§8.7) — drawn when the camera is submerged. */
+export declare function underwaterShaderSources(): ShaderSources;
+//# sourceMappingURL=WaterMaterial.d.ts.map

package/dist/rendering/world/water/WaterMaterial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaterMaterial.d.ts","sourceRoot":"","sources":["../../../../../../packages/rendering/src/world/water/WaterMaterial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AA2E3D,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,aAAa,CASnH;AAwCD,gFAAgF;AAChF,wBAAgB,uBAAuB,IAAI,aAAa,CAOvD"}

package/dist/rendering/world/water/WaterMaterial.js

@@ -0,0 +1,129 @@
+import { a3d_prd10_gerstner } from "./shaders/gerstner.js";
+import { a3d_prd10_water } from "./shaders/water.js";
+import { a3d_prd10_world_light_fallback } from "../shared/shaders/worldLightFallback.js";
+const WATER_VERT_GLSL = /* glsl */ `#version 300 es
+precision highp float;
+// prd10.water — marker for the RenderDevice shader contract.
+in vec3 a_position;       // unit quad grid, xz = metres, y = 0
+in float a_shore;         // baked shore distance (metres) — Low path only
+uniform mat4 u_viewProjection;
+uniform vec3 u_worldOffset;   // grid origin in world space
+uniform float u_waterHeight;  // rest surface Y
+${a3d_prd10_gerstner.glsl}
+out vec3 v_worldPosition;
+out vec2 v_xz;
+out vec3 v_waveNormal;
+out float v_crest;
+out float v_shore;
+void main() {
+  vec3 waveN;
+  vec3 p = a3dGerstner(a_position.xz + u_worldOffset.xz, waveN);
+  v_worldPosition = vec3(p.x, p.y + u_waterHeight, p.z);
+  v_xz = a_position.xz + u_worldOffset.xz;
+  v_waveNormal = waveN;
+  v_crest = a3dGerstnerCrest(v_xz);
+  v_shore = a_shore;
+  gl_Position = u_viewProjection * vec4(v_worldPosition, 1.0);
+}
+`;
+const WATER_FRAG_GLSL = /* glsl */ `#version 300 es
+precision highp float;
+precision highp int;
+// prd10.water — marker for the RenderDevice shader contract.
+in vec3 v_worldPosition;
+in vec2 v_xz;
+in vec3 v_waveNormal;
+in float v_crest;
+in float v_shore;
+out vec4 o_color;
+#ifndef A3D_PRD10_WATER_HAS_SCENE
+#define A3D_PRD10_WATER_HAS_SCENE 0
+#endif
+${a3d_prd10_world_light_fallback.glsl}
+${a3d_prd10_water.glsl}
+void main() {
+  vec3 n = a3dWaterNormal(v_waveNormal, v_xz, u_time);
+  vec3 V = normalize(u_cameraPosition - v_worldPosition);
+  float F = a3dWaterFresnel(n, V);
+  vec2 suv = gl_FragCoord.xy / u_viewport;
+  float waterZ = a3dWaterLinearDepth(gl_FragCoord.z);
+  float thickness;
+  vec3 transmitted;
+#if A3D_PRD10_WATER_HAS_SCENE
+  transmitted = a3dWaterRefracted(suv, waterZ, n, thickness)
+              + u_scatterColor * (1.0 - exp(-u_absorption * thickness)) * a3dSunIrradiance();
+#else
+  // Low path (§8.6): baked shore distance stands in for scene-depth thickness.
+  thickness = max(v_shore, 0.0);
+  vec3 T = exp(-u_absorption * thickness);
+  transmitted = mix(u_shallowColor, u_deepColor, clamp(1.0 - T.g, 0.0, 1.0)) * a3dSkyIrradiance();
+#endif
+  vec3 R = reflect(-V, n);
+  vec3 reflected = u_reflectionMode > 1.5
+    ? a3dWaterPlanarReflection(suv, n)
+    : a3dWorldEnvSpecular(R, 0.03);   // mode 0 env; mode 1 SSR arrives via C-13 (stub = env)
+  vec3 sunSpec = a3dDirectSpecularGGX(n, V, u_sunDirection, 0.06) * u_sunColor * a3dSunShadowAt(v_worldPosition);
+  vec3 color = mix(transmitted, reflected, F) + sunSpec;
+  color = mix(color, vec3(0.9) * a3dSunIrradiance() + a3dSkyIrradiance(), a3dWaterFoam(v_xz, thickness, v_crest));
+  color = a3dApplyFog(color, v_worldPosition);
+  o_color = vec4(color, 1.0);
+}
+`;
+/** Full §8.6 program. `hasScene`/`planar` bake the feature defines. */
+export function waterShaderSources(options) {
+    const defines = `#define A3D_PRD10_WATER_HAS_SCENE ${options.hasScene ? 1 : 0}\n`;
+    return {
+        label: "prd10-water",
+        marker: "prd10.water",
+        vertex: WATER_VERT_GLSL,
+        fragment: defines + WATER_FRAG_GLSL,
+        webgpu: undefined // WGSL twin ships with the Path G variant (chunk-level wgsl exists on a3d_prd10_water)
+    };
+}
+/**
+ * The §8.6 underwater shell program: the surface re-drawn back-face with a
+ * Snell's window (total internal reflection outside the 48.6° cone) and the
+ * depth-graded underwater gradient as background tint.
+ */
+const UNDERWATER_FRAG_GLSL = /* glsl */ `#version 300 es
+precision highp float;
+precision highp int;
+// prd10.water — marker for the RenderDevice shader contract.
+in vec3 v_worldPosition;
+in vec2 v_xz;
+in vec3 v_waveNormal;
+in float v_crest;
+in float v_shore;
+out vec4 o_color;
+${a3d_prd10_world_light_fallback.glsl}
+${a3d_prd10_water.glsl}
+uniform vec3 u_surfaceColor;   // gradient top (#2a8fb0)
+uniform vec3 u_deepGradient;   // gradient bottom (#021018)
+void main() {
+  vec3 n = a3dWaterNormal(v_waveNormal, v_xz, u_time);
+  vec3 V = normalize(v_worldPosition - u_cameraPosition); // view ray upward
+  float cosI = clamp(dot(-V, -n), 0.0, 1.0);
+  // Snell's window: total internal reflection beyond the 48.6° critical cone
+  // (sin²θc = 1/1.33²). Below it the surface refracts the sky gradient.
+  float sinT2 = 1.33 * 1.33 * (1.0 - cosI * cosI);
+  vec3 color;
+  if (sinT2 > 1.0) {
+    // TIR: reflect the underwater background back down
+    color = mix(u_deepGradient, u_surfaceColor, clamp(v_worldPosition.y / u_waterHeight, 0.0, 1.0));
+  } else {
+    color = mix(u_deepGradient, u_surfaceColor, clamp(v_worldPosition.y / max(u_waterHeight, 0.01), 0.0, 1.0))
+          + a3dSunIrradiance() * 0.35 * a3dWaterFresnel(n, -V);
+  }
+  o_color = vec4(a3dApplyFog(color, v_worldPosition), 1.0);
+}
+`;
+/** Underwater back-face program (§8.7) — drawn when the camera is submerged. */
+export function underwaterShaderSources() {
+    return {
+        label: "prd10-water-underwater",
+        marker: "prd10.water",
+        vertex: WATER_VERT_GLSL,
+        fragment: UNDERWATER_FRAG_GLSL
+    };
+}
+//# sourceMappingURL=WaterMaterial.js.map

package/dist/rendering/world/water/WaterMaterial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaterMaterial.js","sourceRoot":"","sources":["../../../../../../packages/rendering/src/world/water/WaterMaterial.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AAEzF,MAAM,eAAe,GAAG,UAAU,CAAC;;;;;;;;EAQjC,kBAAkB,CAAC,IAAI;;;;;;;;;;;;;;;;CAgBxB,CAAC;AAEF,MAAM,eAAe,GAAG,UAAU,CAAC;;;;;;;;;;;;;EAajC,8BAA8B,CAAC,IAAI;EACnC,eAAe,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BrB,CAAC;AAEF,uEAAuE;AACvE,MAAM,UAAU,kBAAkB,CAAC,OAAiE;IAClG,MAAM,OAAO,GAAG,qCAAqC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,OAAO;QACL,KAAK,EAAE,aAAa;QACpB,MAAM,EAAE,aAAa;QACrB,MAAM,EAAE,eAAe;QACvB,QAAQ,EAAE,OAAO,GAAG,eAAe;QACnC,MAAM,EAAE,SAAS,CAAC,uFAAuF;KAC1G,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,UAAU,CAAC;;;;;;;;;;EAUtC,8BAA8B,CAAC,IAAI;EACnC,eAAe,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;CAoBrB,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,KAAK,EAAE,wBAAwB;QAC/B,MAAM,EAAE,aAAa;QACrB,MAAM,EAAE,eAAe;QACvB,QAAQ,EAAE,oBAAoB;KAC/B,CAAC;AACJ,CAAC"}

package/dist/rendering/world/water/shaders/caustics.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `a3d_prd10_caustics` — PRD-10 §8.7 underwater caustics chunk.
+ * On Path G the C-02 `ShaderFeature` `prd10.caustics` uses the split
+ * `a3d_prd10_caustics_pars` / `_apply` chunks below (define
+ * `A3D_PRD10_CAUSTICS`, #1143); on Path S this chunk is linked into
+ * the lane's own terrain/kit programs. Multiplies the direct sun term by the
+ * 16-frame caustic atlas projected along the sun direction.
+ */
+import type { ShaderChunk } from "../../../contracts/program.js";
+export declare const a3d_prd10_caustics: ShaderChunk;
+export declare const a3d_prd10_caustics_pars: ShaderChunk;
+export declare const a3d_prd10_caustics_apply: ShaderChunk;
+//# sourceMappingURL=caustics.d.ts.map

package/dist/rendering/world/water/shaders/caustics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caustics.d.ts","sourceRoot":"","sources":["../../../../../../../packages/rendering/src/world/water/shaders/caustics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAoEjE,eAAO,MAAM,kBAAkB,EAAE,WAMhC,CAAC;AAuBF,eAAO,MAAM,uBAAuB,EAAE,WAMrC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,WAMtC,CAAC"}

package/dist/rendering/world/water/shaders/caustics.js

@@ -0,0 +1,103 @@
+const CAUSTICS_UNIFORMS_GLSL = /* glsl */ `
+uniform sampler2D u_causticAtlas;   // 4x4 grid of 16 frames
+uniform float u_causticScale;       // world metres per atlas tile
+uniform float u_causticStrength;
+uniform float u_waterHeight;
+`;
+/** Sampling + boost helpers, shared by the Path S chunk and the Path G pars chunk. */
+const CAUSTICS_FUNCTIONS_GLSL = /* glsl */ `
+// Sample the crossfaded caustic value at atlas-local uv in [0,1].
+float a3dCausticSample(vec2 atlasUv, float t) {
+  float frame = mod(floor(t * 12.0), 16.0);
+  float next = mod(frame + 1.0, 16.0);
+  vec2 cell0 = vec2(mod(frame, 4.0), floor(frame / 4.0));
+  vec2 cell1 = vec2(mod(next, 4.0), floor(next / 4.0));
+  float c0 = texture(u_causticAtlas, (cell0 + atlasUv) / 4.0).r;
+  float c1 = texture(u_causticAtlas, (cell1 + atlasUv) / 4.0).r;
+  return mix(c0, c1, fract(t * 12.0));
+}
+
+// Direct-sun multiplier for a submerged fragment: project along the sun dir
+// to the water plane, sample the atlas, attenuate by depth.
+float a3dCausticsBoost(vec3 worldPos, vec3 sunDir, float t) {
+  float h = u_waterHeight;
+  if (worldPos.y >= h) return 1.0;
+  vec2 cuv = (worldPos.xz - sunDir.xz * (h - worldPos.y) / max(sunDir.y, 0.05)) / u_causticScale;
+  float c = a3dCausticSample(fract(cuv), t);
+  float depth = h - worldPos.y;
+  return 1.0 + u_causticStrength * c * exp(-depth * 0.15);
+}
+`;
+const glsl = /* glsl */ `${CAUSTICS_UNIFORMS_GLSL}uniform float u_time;
+${CAUSTICS_FUNCTIONS_GLSL}`;
+const wgsl = /* wgsl */ `
+@group(0) @binding(0) var u_causticAtlas : texture_2d<f32>;
+@group(0) @binding(1) var u_samp : sampler;
+struct A3dCaustics {
+  scale : f32,
+  strength : f32,
+  time : f32,
+  waterHeight : f32,
+};
+@group(0) @binding(2) var<uniform> u_caustics : A3dCaustics;
+
+fn a3dCausticSample(atlasUv : vec2f, t : f32) -> f32 {
+  let frame = floor(t * 12.0) % 16.0;
+  let next = (frame + 1.0) % 16.0;
+  let cell0 = vec2f(frame % 4.0, floor(frame / 4.0));
+  let cell1 = vec2f(next % 4.0, floor(next / 4.0));
+  let c0 = textureSample(u_causticAtlas, u_samp, (cell0 + atlasUv) / 4.0).r;
+  let c1 = textureSample(u_causticAtlas, u_samp, (cell1 + atlasUv) / 4.0).r;
+  return mix(c0, c1, fract(t * 12.0));
+}
+
+fn a3dCausticsBoost(worldPos : vec3f, sunDir : vec3f, t : f32) -> f32 {
+  let h = u_caustics.waterHeight;
+  if (worldPos.y >= h) { return 1.0; }
+  let cuv = (worldPos.xz - sunDir.xz * (h - worldPos.y) / max(sunDir.y, 0.05)) / u_caustics.scale;
+  let c = a3dCausticSample(fract(cuv), t);
+  let depth = h - worldPos.y;
+  return 1.0 + u_caustics.strength * c * exp(-depth * 0.15);
+}
+`;
+export const a3d_prd10_caustics = {
+    name: "a3d_prd10_caustics",
+    owner: "prd10",
+    stage: "fragment",
+    glsl,
+    wgsl
+};
+/**
+ * #1143 — generated-program (C-02, Path G) split of the caustics chunk.
+ * `a3d_prd10_caustics_pars` is the global-scope declaration chunk at
+ * `fragment:pars` (no `u_time`: the call reads frame time from the AuraFrame
+ * block, `u_resolutionFarTime.w`, so it cannot collide with another feature's
+ * `u_time`). `a3d_prd10_caustics_apply` is the statements-only call chunk at
+ * `fragment:indirect`, which the generator appends after the default indirect
+ * body, so the default light loop still runs and the boost scales its direct
+ * accumulators. `u_causticSunDir` points toward the sun.
+ */
+const parsGlsl = /* glsl */ `${CAUSTICS_UNIFORMS_GLSL}uniform vec3 u_causticSunDir;
+${CAUSTICS_FUNCTIONS_GLSL}`;
+const applyGlsl = /* glsl */ `
+#ifdef A3D_PRD10_CAUSTICS
+  float a3dCausticBoost = a3dCausticsBoost(v_worldPosition, normalize(u_causticSunDir), u_resolutionFarTime.w);
+  directDiffuse *= a3dCausticBoost;
+  directSpecular *= a3dCausticBoost;
+#endif
+`;
+export const a3d_prd10_caustics_pars = {
+    name: "a3d_prd10_caustics_pars",
+    owner: "prd10",
+    stage: "fragment",
+    glsl: parsGlsl,
+    wgsl
+};
+export const a3d_prd10_caustics_apply = {
+    name: "a3d_prd10_caustics_apply",
+    owner: "prd10",
+    stage: "fragment",
+    glsl: applyGlsl,
+    requires: ["a3d_prd10_caustics_pars"]
+};
+//# sourceMappingURL=caustics.js.map

package/dist/rendering/world/water/shaders/caustics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caustics.js","sourceRoot":"","sources":["../../../../../../../packages/rendering/src/world/water/shaders/caustics.ts"],"names":[],"mappings":"AAUA,MAAM,sBAAsB,GAAG,UAAU,CAAC;;;;;CAKzC,CAAC;AAEF,sFAAsF;AACtF,MAAM,uBAAuB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;CAsB1C,CAAC;AAEF,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,sBAAsB;EAC/C,uBAAuB,EAAE,CAAC;AAE5B,MAAM,IAAI,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BvB,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAgB;IAC7C,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,UAAU;IACjB,IAAI;IACJ,IAAI;CACL,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,sBAAsB;EACnD,uBAAuB,EAAE,CAAC;AAE5B,MAAM,SAAS,GAAG,UAAU,CAAC;;;;;;CAM5B,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAgB;IAClD,IAAI,EAAE,yBAAyB;IAC/B,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,QAAQ;IACd,IAAI;CACL,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAgB;IACnD,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,SAAS;IACf,QAAQ,EAAE,CAAC,yBAAyB,CAAC;CACtC,CAAC"}

package/dist/rendering/world/water/shaders/gerstner.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `a3d_prd10_gerstner` — PRD-10 §8.6 Gerstner wave vertex chunk.
+ * `GerstnerWaves.ts` holds the same constants and formula on the CPU (wave
+ * steepness sum clamped to <= 1 there to prevent loops). The Jacobian proxy
+ * `1 - Σ steepness·sin(f)` reaches the fragment as `v_crest` for crest foam.
+ */
+import type { ShaderChunk } from "../../../contracts/program.js";
+export declare const a3d_prd10_gerstner: ShaderChunk;
+//# sourceMappingURL=gerstner.d.ts.map

package/dist/rendering/world/water/shaders/gerstner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gerstner.d.ts","sourceRoot":"","sources":["../../../../../../../packages/rendering/src/world/water/shaders/gerstner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAgGjE,eAAO,MAAM,kBAAkB,EAAE,WAMhC,CAAC"}

package/dist/rendering/world/water/shaders/gerstner.js

@@ -0,0 +1,100 @@
+const glsl = /* glsl */ `
+uniform vec4 u_waves[8];      // dir.x, dir.y, steepness, wavelength
+uniform vec4 u_waveSpeed[8];  // x: speed multiplier (vec4: the device rejects 8-float arrays)
+uniform float u_waveCount;     // float: the device has no int uniform upload (#491)
+uniform float u_time;
+
+// Displaced surface point + analytic normal via tangent/binormal accumulation.
+vec3 a3dGerstner(vec2 xz, out vec3 normal) {
+  vec3 p = vec3(xz.x, 0.0, xz.y);
+  vec3 tangent = vec3(1.0, 0.0, 0.0), binormal = vec3(0.0, 0.0, 1.0);
+  for (int i = 0; i < 8; i++) {
+    if (float(i) >= u_waveCount) break;
+    vec2 d = u_waves[i].xy;
+    float k = 6.2831853 / u_waves[i].w;
+    float c = sqrt(9.81 / k) * u_waveSpeed[i].x;
+    float f = k * (dot(d, xz) - c * u_time);
+    float a = u_waves[i].z / k;
+    p.x += d.x * a * cos(f);
+    p.y += a * sin(f);
+    p.z += d.y * a * cos(f);
+    tangent  += vec3(-d.x * d.x * u_waves[i].z * sin(f),  d.x * u_waves[i].z * cos(f), -d.x * d.y * u_waves[i].z * sin(f));
+    binormal += vec3(-d.x * d.y * u_waves[i].z * sin(f),  d.y * u_waves[i].z * cos(f), -d.y * d.y * u_waves[i].z * sin(f));
+  }
+  normal = normalize(cross(binormal, tangent));
+  return p;
+}
+
+// Jacobian proxy for crest foam: 1 - Σ steepness·sin(f) over active waves.
+float a3dGerstnerCrest(vec2 xz) {
+  float j = 0.0;
+  for (int i = 0; i < 8; i++) {
+    if (float(i) >= u_waveCount) break;
+    vec2 d = u_waves[i].xy;
+    float k = 6.2831853 / u_waves[i].w;
+    float c = sqrt(9.81 / k) * u_waveSpeed[i].x;
+    float f = k * (dot(d, xz) - c * u_time);
+    j += u_waves[i].z * sin(f);
+  }
+  return 1.0 - j;
+}
+`;
+const wgsl = /* wgsl */ `
+struct A3dWaves {
+  waves : array<vec4f, 8>,   // dir.x, dir.y, steepness, wavelength
+  speed : array<f32, 8>,
+  count : i32,
+  time : f32,
+  pad0 : f32,
+  pad1 : f32,
+};
+@group(0) @binding(0) var<uniform> u_waves : A3dWaves;
+
+struct A3dGerstnerResult {
+  position : vec3f,
+  normal : vec3f,
+};
+
+fn a3dGerstner(xz : vec2f) -> A3dGerstnerResult {
+  var p = vec3f(xz.x, 0.0, xz.y);
+  var tangent = vec3f(1.0, 0.0, 0.0);
+  var binormal = vec3f(0.0, 0.0, 1.0);
+  for (var i = 0; i < 8; i = i + 1) {
+    if (i >= u_waves.count) { break; }
+    let d = u_waves.waves[i].xy;
+    let k = 6.2831853 / u_waves.waves[i].w;
+    let c = sqrt(9.81 / k) * u_waves.speed[i];
+    let f = k * (dot(d, xz) - c * u_waves.time);
+    let a = u_waves.waves[i].z / k;
+    p = vec3f(p.x + d.x * a * cos(f), p.y + a * sin(f), p.z + d.y * a * cos(f));
+    let s = u_waves.waves[i].z;
+    tangent = tangent + vec3f(-d.x * d.x * s * sin(f), d.x * s * cos(f), -d.x * d.y * s * sin(f));
+    binormal = binormal + vec3f(-d.x * d.y * s * sin(f), d.y * s * cos(f), -d.y * d.y * s * sin(f));
+  }
+  var r : A3dGerstnerResult;
+  r.position = p;
+  r.normal = normalize(cross(binormal, tangent));
+  return r;
+}
+
+fn a3dGerstnerCrest(xz : vec2f) -> f32 {
+  var j = 0.0;
+  for (var i = 0; i < 8; i = i + 1) {
+    if (i >= u_waves.count) { break; }
+    let d = u_waves.waves[i].xy;
+    let k = 6.2831853 / u_waves.waves[i].w;
+    let c = sqrt(9.81 / k) * u_waves.speed[i];
+    let f = k * (dot(d, xz) - c * u_waves.time);
+    j = j + u_waves.waves[i].z * sin(f);
+  }
+  return 1.0 - j;
+}
+`;
+export const a3d_prd10_gerstner = {
+    name: "a3d_prd10_gerstner",
+    owner: "prd10",
+    stage: "vertex",
+    glsl,
+    wgsl
+};
+//# sourceMappingURL=gerstner.js.map

package/dist/rendering/world/water/shaders/gerstner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gerstner.js","sourceRoot":"","sources":["../../../../../../../packages/rendering/src/world/water/shaders/gerstner.ts"],"names":[],"mappings":"AAQA,MAAM,IAAI,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCvB,CAAC;AAEF,MAAM,IAAI,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDvB,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAgB;IAC7C,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,QAAQ;IACf,IAAI;IACJ,IAAI;CACL,CAAC"}

package/dist/rendering/world/water/shaders/water.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `a3d_prd10_water` — PRD-10 §8.6 water fragment chunk: dual-scroll normal
+ * detail, Schlick Fresnel (IOR 1.33), scene-depth refraction with foreground
+ * rejection, Beer-Lambert absorption, shore + crest foam.
+ * IBL specular, sun GGX specular, shadow factor and fog come from shared C-09 /
+ * C-11 / C-13 / C-21 chunks at link time (`a3dWorldEnvSpecular`,
+ * `a3dDirectSpecularGGX`, `a3dSunShadowAt`, `a3dApplyFog`, `a3dSunIrradiance`,
+ * `a3dSkyIrradiance`); Path S binds `a3d_prd10_world_light_fallback`.
+ */
+import type { ShaderChunk } from "../../../contracts/program.js";
+export declare const a3d_prd10_water: ShaderChunk;
+//# sourceMappingURL=water.d.ts.map

package/dist/rendering/world/water/shaders/water.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"water.d.ts","sourceRoot":"","sources":["../../../../../../../packages/rendering/src/world/water/shaders/water.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AA4GjE,eAAO,MAAM,eAAe,EAAE,WAM7B,CAAC"}