@call-me-sensei/toonlab 0.4.21 → 0.4.23

package/src/water/waterFoamParticles.js

@@ -0,0 +1,196 @@
+import * as THREE from 'three';
+import { MeshBasicNodeMaterial } from 'three/webgpu';
+import { attribute, clamp, dot, length, max, mix, normalWorld, positionWorld, smoothstep, texture, uniform, uv } from 'three/tsl';
+import { getWaterFoamTexture } from './waterFoamTexture.js';
+import { sampleEnvironmentSunShadow } from '../shaders-tsl/chunks/environment-sun-shadow.js';
+import { sampleEnvironmentCloudShadow } from '../sky/cloudShadow.js';
+
+// Small floating foam rafts, each resolving several bubbles. They translate
+// with solved flow but do not stretch into polygons with a texture mapping.
+export class WaterFoamParticles {
+  constructor(dynamics, count=12000) {
+    this.dynamics=dynamics;this.count=count;this.seed=6297;
+    this.points=new Float32Array(count*6); // x,z,age,lifetime,size,rotation
+    this.thickness=new Float32Array(count);
+    for(let i=0;i<count;i++)this.points[i*6+2]=-1;
+    this.alpha=new Float32Array(count);
+    const seeds=new Float32Array(count);
+    for(let i=0;i<count;i++)seeds[i]=this.random()*8;
+    // A rounded cap, not a flat card: its base touches the water and its
+    // crown gives the aerated lip a centimetre-scale silhouette and shading.
+    const geometry=new THREE.PlaneGeometry(1,1,4,4);geometry.rotateX(-Math.PI/2);
+    const position=geometry.attributes.position;
+    for(let i=0;i<position.count;i++) {
+      const r2=4*(position.getX(i)**2+position.getZ(i)**2);
+      position.setY(i,Math.max(0,1-r2)**.7);
+    }
+    geometry.computeVertexNormals();
+    geometry.setAttribute('aFoamAlpha',new THREE.InstancedBufferAttribute(this.alpha,1).setUsage(THREE.DynamicDrawUsage));
+    geometry.setAttribute('aFoamSeed',new THREE.InstancedBufferAttribute(seeds,1));
+    this.color=uniform(new THREE.Color());
+    this.sun=uniform(new THREE.Vector3(0,1,0));
+    const material=new MeshBasicNodeMaterial({transparent:true,depthWrite:false,side:THREE.DoubleSide});
+    const bubble=texture(getWaterFoamTexture()).sample(uv().mul(.25));
+    const seed=attribute('aFoamSeed','float');
+    const shape=texture(getWaterFoamTexture()).sample(uv().mul(.3).add(seed)).b;
+    const radius=shape.mul(.22).add(.22);
+    const disk=smoothstep(radius.sub(.035),radius.add(.015),length(uv().sub(.5))).oneMinus();
+    const visibility=sampleEnvironmentSunShadow(positionWorld).mul(sampleEnvironmentCloudShadow(positionWorld,1));
+    const diffuse=max(dot(normalWorld,this.sun),0).mul(.38).add(.62);
+    material.colorNode=this.color.mul(bubble.r).mul(mix(.6,1,visibility)).mul(diffuse);
+    material.opacityNode=clamp(attribute('aFoamAlpha','float').mul(disk).mul(mix(.15,1,bubble.g)),0,1);
+    this.mesh=new THREE.InstancedMesh(geometry,material,count);
+    this.mesh.name='FloatingSwashFoam';this.mesh.frustumCulled=false;this.mesh.renderOrder=3;
+    this.mesh.userData.waterExclude=true;this.mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+    dynamics.surface.add(this.mesh);
+    this.focus=new THREE.Vector3();this.sample={};this.alive=0;
+    this.frontState=new Float32Array(dynamics.columns*4);
+    this.previousEdges=new Float32Array(dynamics.columns);
+    this.frontReady=false;
+    this.frontTexture=new THREE.DataTexture(this.frontState,dynamics.columns,1,THREE.RGBAFormat,THREE.FloatType);
+    this.frontTexture.minFilter=this.frontTexture.magFilter=THREE.LinearFilter;
+    this.frontTexture.generateMipmaps=false;
+  }
+  random(){this.seed=(Math.imul(this.seed,1664525)+1013904223)>>>0;return (this.seed+.5)/4294967296;}
+  concentration(x,z) {
+    const d=this.dynamics;
+    return d.hydro.sampleArray(d.hydro.foam,(x-d.minX)/d.dx,(z-d.minZ)/d.dz);
+  }
+  edgeAt(x) {
+    const d=this.dynamics;
+    if(d.options.shorelineAxis!=='z')return d.shoreEdgeAt(x);
+    const gx=THREE.MathUtils.clamp((x-d.minX)/d.dx,0,d.columns-1),i=Math.min(d.columns-2,Math.floor(gx));
+    return THREE.MathUtils.lerp(d.shoreContour[i],d.shoreContour[i+1],gx-i);
+  }
+  sampleFront(x,component,previous=false) {
+    const d=this.dynamics,gx=THREE.MathUtils.clamp((x-d.minX)/d.dx,0,d.columns-1),i=Math.min(d.columns-2,Math.floor(gx));
+    const a=previous?this.previousEdges[i]:this.frontState[i*4+component];
+    const b=previous?this.previousEdges[i+1]:this.frontState[(i+1)*4+component];
+    return THREE.MathUtils.lerp(a,b,gx-i);
+  }
+  updateFront(dt) {
+    const d=this.dynamics;
+    if(d.options.shorelineAxis!=='z')return;
+    for(let i=0;i<d.columns;i++) {
+      const x=d.minX+i*d.dx,edge=this.edgeAt(x),j=i*4;
+      const previous=this.frontReady?this.frontState[j]:edge;
+      this.previousEdges[i]=previous;
+      if(dt>0&&this.frontReady) {
+        const speed=THREE.MathUtils.clamp((edge-previous)/dt,-5,5);
+        this.frontState[j+1]=THREE.MathUtils.lerp(this.frontState[j+1],speed,1-Math.exp(-dt/.18));
+      }
+      this.frontState[j]=edge;
+      const concentration=Math.max(this.concentration(x,edge-.025),this.concentration(x,edge-.15),this.concentration(x,edge-.3));
+      // Remember existing aeration through the drain. This is a visual
+      // contact-line reservoir; it neither creates water nor refills a calm
+      // shore. Its contribution fades and is thinner during retreat.
+      this.frontState[j+2]=Math.max(concentration,this.frontState[j+2]*Math.exp(-dt/5));
+      this.frontState[j+3]+=d.sample(x,edge-.2,this.sample).velocityZ*dt;
+    }
+    this.frontReady=true;this.frontTexture.needsUpdate=true;
+    d.surface.material.uniforms.uFoamFrontState.value=this.frontTexture;
+    d.surface.material.uniforms.uUseFoamFrontState.value=1;
+  }
+  retreatAt(x) {return this.frontReady?THREE.MathUtils.smoothstep(-this.sampleFront(x,1),.02,.18):0;}
+  patchAt(x,edge) {
+    // Smooth packet-scale variation, transported with the changing front.
+    // The aeration field still decides whether any foam can exist here.
+    return .5+.5*Math.sin(x*1.31+edge*.27)*Math.sin(x*.47-edge*.19+2.1);
+  }
+  networkAt(x,z) {
+    const {data,width:n}=getWaterFoamTexture().image;
+    const flow=this.frontReady?this.sampleFront(x,3):0;
+    const gx=((x/2.4%1)+1)%1*n,gz=(((z-flow)/2.4%1)+1)%1*n;
+    const ix=Math.floor(gx),iz=Math.floor(gz),tx=gx-ix,tz=gz-iz;
+    const at=(a,b)=>data[((b%n)*n+a%n)*4+3]/255;
+    return (at(ix,iz)*(1-tx)+at(ix+1,iz)*tx)*(1-tz)+(at(ix,iz+1)*(1-tx)+at(ix+1,iz+1)*tx)*tz;
+  }
+  availableFoam(x,z) {
+    const current=this.concentration(x,z),edge=this.edgeAt(x);
+    if(!this.frontReady||edge==null)return current;
+    return Math.max(current,this.sampleFront(x,2)*this.retreatAt(x)*Math.exp(-Math.max(0,edge-z)/.4));
+  }
+  update(dt) {
+    const d=this.dynamics,s=d.surface,settings=s.renderedSettings??s.settings;
+    this.updateFront(dt);
+    if(typeof s.followTarget==='function')s.followTarget(this.focus);
+    const cx=THREE.MathUtils.clamp(this.focus.x,d.minX+12,d.minX+s.width-12);
+    const cz=(this.edgeAt(cx)??0)-1.5;
+    const gain=settings.foamAmount*settings.swashFoamAmount;
+    this.color.value.setRGB(...settings.foamColor,THREE.SRGBColorSpace);
+    this.sun.value.set(...settings.sunDirection).normalize();
+    const matrices=this.mesh.instanceMatrix.array;
+    let budget=dt>0?Math.min(this.count,Math.ceil(dt*18000)):0,alive=0,packetRemaining=0,packetX=cx,packetZ=cz;
+    let packetRim=true,packetPatch=1,packetSpread=.035;
+    for(let i=0;i<this.count;i++) {
+      const j=i*6;
+      let x=this.points[j],z=this.points[j+1],age=this.points[j+2];
+      if(age>=0&&dt>0) {
+        const oldX=x,oldZ=z,oldEdge=this.frontReady?this.sampleFront(x,0,true):null;
+        const flow=d.sample(x,z,this.sample);
+        x+=flow.velocityX*dt;z+=flow.velocityZ*dt;age+=dt;
+        if(oldEdge!=null&&oldEdge-oldZ>=0&&oldEdge-oldZ<.35) {
+          const newEdge=this.edgeAt(x),edgeDelta=newEdge-this.sampleFront(oldX,0,true);
+          // The narrow rim remains with the receding contact line. Foam
+          // farther into the sheet continues to follow the bulk current.
+          if(edgeDelta<0)z=oldZ+edgeDelta;
+        }
+        if(age>this.points[j+3]||Math.abs(x-cx)>13||Math.abs(z-cz)>5)age=-1;
+      }
+      if(age<0&&budget>0&&gain>0) {
+        budget--;
+        if(packetRemaining--<=0){
+          packetRemaining=4+Math.floor(this.random()*9);
+          packetX=cx+(this.random()-.5)*23.6;
+          const front=this.edgeAt(packetX);
+          packetPatch=front==null?1:this.patchAt(packetX,front);
+          packetRim=front==null||this.random()<.42;
+          const drain=1-.5*this.retreatAt(packetX);
+          const width=(.18-.11*packetPatch)*drain;
+          const distance=packetRim ? .018+Math.min(.65,-Math.log(this.random())*width)
+            : .35+this.random()**1.25*(.6+1.65*packetPatch)*drain;
+          packetZ=front==null?cz+(this.random()-.5)*7.6:front-distance;
+          packetSpread=packetRim?.035:.25+.45*packetPatch;
+        }
+        x=packetX+(this.random()-.5)*.24;
+        const localFront=this.edgeAt(x),packetFront=this.edgeAt(packetX);
+        z=packetZ+(localFront!=null&&packetFront!=null?localFront-packetFront:0)+(this.random()-.5)*packetSpread;
+        const column=d.sample(x,z,this.sample),foam=this.availableFoam(x,z),retreat=this.retreatAt(x);
+        const patchDensity=localFront==null?1:(packetRim?.65:.3)+(packetRim?.35:.7)*packetPatch;
+        const network=localFront==null||packetRim?1:.25+.75*this.networkAt(x,z);
+        if(column.wet&&column.depth<.3&&foam>(retreat>.1?.008:.04)&&this.random()<(1-.6*retreat)*patchDensity*network) {
+          age=0;this.points[j+3]=2.5+this.random()*3;
+          const lip=localFront!=null&&localFront-z<.35;
+          this.points[j+4]=lip?.055+(.055+.13*packetPatch)*this.random():.035+this.random()*.1;
+          this.thickness[i]=lip?.006+.025*packetPatch**1.5*(.5+.5*this.random()):.0015+this.random()*.005;
+          this.points[j+5]=lip?this.random()*Math.PI*2:Math.atan2(column.velocityX,column.velocityZ)+(this.random()-.5);
+        }
+      }
+      this.points[j]=x;this.points[j+1]=z;this.points[j+2]=age;
+      if(age<0){this.alpha[i]=0;continue;}
+      const column=d.sample(x,z,this.sample),foam=this.availableFoam(x,z);
+      if(!column.wet||foam<.008){this.points[j+2]=-1;this.alpha[i]=0;continue;}
+      const life=this.points[j+3];
+      const fade=THREE.MathUtils.smoothstep(age,0,.18)*(1-THREE.MathUtils.smoothstep(age,life-.6,life));
+      const edge=(1-THREE.MathUtils.smoothstep(Math.abs(x-cx),10,12))*(1-THREE.MathUtils.smoothstep(Math.abs(z-cz),3,4));
+      this.alpha[i]=fade*edge*(1-.6*this.retreatAt(x))*THREE.MathUtils.clamp(foam*5*gain,0,1);
+      const size=this.points[j+4],angle=this.points[j+5],c=Math.cos(angle),sn=Math.sin(angle),k=i*16;
+      const distance=(this.edgeAt(x)??z)-z,filament=distance>.35;
+      const sx=size*(filament?.45:1),sz=size*(filament?1.8:1);
+      const nx=THREE.MathUtils.clamp(Math.round((x-d.minX)/d.dx),0,d.columns-1);
+      const nz=THREE.MathUtils.clamp(Math.round((z-d.minZ)/d.dz),0,d.rows-1),ni=(nz*d.columns+nx)*3;
+      const gx=-d.normals[ni]/Math.max(d.normals[ni+1],.1),gz=-d.normals[ni+2]/Math.max(d.normals[ni+1],.1);
+      const height=this.thickness[i]*(1-.65*this.retreatAt(x))*(.5+.5*fade);
+      matrices[k]=c*sx;matrices[k+2]=-sn*sx;matrices[k+5]=height;matrices[k+8]=sn*sz;matrices[k+10]=c*sz;
+      matrices[k+1]=(gx*c-gz*sn)*sx;matrices[k+9]=(gx*sn+gz*c)*sz;
+      matrices[k+12]=x-d.x;matrices[k+13]=column.height-d.level+.0015;matrices[k+14]=z-d.z;matrices[k+15]=1;
+      alive++;
+    }
+    this.alive=alive;
+    this.mesh.visible=gain>0;
+    this.mesh.geometry.attributes.aFoamAlpha.needsUpdate=true;this.mesh.instanceMatrix.needsUpdate=true;
+    s.material.uniforms.uFoamParticleRegion.value.set(cx,cz,12,4);
+    s.material.uniforms.uFoamParticleCoverage.value=gain>0?Math.min(1,alive/4500):0;
+  }
+  dispose(){this.dynamics.surface.material.uniforms.uUseFoamFrontState.value=0;this.frontTexture.dispose();this.mesh.removeFromParent();this.mesh.geometry.dispose();this.mesh.material.dispose();}
+}

package/src/water/waterFoamTexture.js

@@ -0,0 +1,57 @@
+import * as THREE from 'three';
+
+let cached;
+// Packed bubble membranes and separated small bubbles. Generated once;
+// this is surface detail, not glowing spray points or a scrolling photograph.
+export function getWaterFoamTexture() {
+  if (cached) return cached;
+  const n=512, cells=32, data=new Uint8Array(n*n*4);
+  const hash=(x,y,salt=0)=>{const v=Math.sin(x*127.1+y*311.7+salt*91.3)*43758.5453;return v-Math.floor(v);};
+  const wrap=v=>(v%cells+cells)%cells;
+  const smooth=(a,b,v)=>{const t=Math.max(0,Math.min(1,(v-a)/(b-a)));return t*t*(3-2*t);};
+  const noise=(x,y)=>{
+    const ix=Math.floor(x),iy=Math.floor(y),tx=smooth(0,1,x-ix),ty=smooth(0,1,y-iy);
+    const h=(a,b)=>hash((a%8+8)%8,(b%8+8)%8,9);
+    return (h(ix,iy)*(1-tx)+h(ix+1,iy)*tx)*(1-ty)+(h(ix,iy+1)*(1-tx)+h(ix+1,iy+1)*tx)*ty;
+  };
+  for(let y=0;y<n;y++)for(let x=0;x<n;x++) {
+    const px=x/n*cells,py=y/n*cells,ix=Math.floor(px),iy=Math.floor(py);
+    let d1=Infinity,d2=Infinity,radius=.4;
+    for(let dy=-1;dy<=1;dy++)for(let dx=-1;dx<=1;dx++) {
+      const sx=ix+dx,sy=iy+dy,hx=wrap(sx),hy=wrap(sy);
+      const ox=sx+.15+.7*hash(hx,hy),oy=sy+.15+.7*hash(hx,hy,1);
+      const d=Math.hypot(px-ox,py-oy);
+      if(d<d1){d2=d1;d1=d;radius=.23+.18*hash(hx,hy,2);}else if(d<d2)d2=d;
+    }
+    const rim=1-smooth(.025,.11,d2-d1);
+    const disk=1-smooth(radius-.04,radius+.025,d1);
+    const i=(y*n+x)*4;
+    data[i]=Math.round(255*(.68+.32*rim));
+    data[i+1]=Math.round(255*disk);
+    data[i+2]=Math.round(255*noise(x/n*8,y/n*8));
+    // A second, coarser cellular field stores only narrow shared borders.
+    // These are the connected foam strands around clear-water pockets.
+    // Two periodic shears curve the cell walls without collapsing their
+    // area. Straight Voronoi bisectors otherwise read as cracked ice.
+    const mx=x/n*6+.20*Math.sin(y/n*Math.PI*6)+.07*Math.sin(y/n*Math.PI*14+1.2);
+    const my=y/n*6+.20*Math.sin(mx/6*Math.PI*6+.8)+.08*Math.sin(mx/6*Math.PI*10);
+    const bx=Math.floor(mx),by=Math.floor(my);
+    let m1=Infinity,m2=Infinity;
+    for(let dy=-1;dy<=1;dy++)for(let dx=-1;dx<=1;dx++) {
+      const sx=bx+dx,sy=by+dy,hx=(sx%6+6)%6,hy=(sy%6+6)%6;
+      const ox=sx+.15+.7*hash(hx,hy,31),oy=sy+.15+.7*hash(hx,hy,37);
+      const distance=Math.hypot(mx-ox,my-oy);
+      if(distance<m1){m2=m1;m1=distance;}else if(distance<m2)m2=distance;
+    }
+    const gap=m2-m1,width=.045+.11*noise(x/n*8,y/n*8);
+    const core=1-smooth(.012,.04,gap);
+    const fringe=(1-smooth(.014,width,gap))*(.45+.55*disk);
+    data[i+3]=Math.round(255*Math.max(core,fringe));
+  }
+  cached=new THREE.DataTexture(data,n,n,THREE.RGBAFormat);
+  cached.name='WaterFoamBubbles';
+  cached.wrapS=cached.wrapT=THREE.RepeatWrapping;
+  cached.minFilter=THREE.LinearMipmapLinearFilter;cached.magFilter=THREE.LinearFilter;
+  cached.generateMipmaps=true;cached.needsUpdate=true;
+  return cached;
+}

package/src/water/waterHydrodynamics.js

@@ -0,0 +1,209 @@
+// Conservative finite-volume Saint-Venant solver for finite authored water.
+// Hydrostatic reconstruction + HLL flux (Audusse et al., 2004).
+// h [m], qx/qz [m²/s]; no authored run-up curve or hidden water source.
+const G = 9.81;
+const DRY = 1e-5;
+export class WaterHydrodynamics {
+    constructor({ columns = 96, rows = 96, width = 60, depth = 60, centerX = 0, centerZ = 0, waterLevel = 0, bedHeight = () => -2, boundary = null, friction = 0.018 } = {}) {
+        if (!Number.isInteger(columns) || !Number.isInteger(rows) || columns < 3 || rows < 3 || !Number.isFinite(width) || !Number.isFinite(depth) || width <= 0 || depth <= 0)
+            throw new RangeError('Invalid water grid');
+        Object.assign(this, { columns, rows, width, depth, centerX, centerZ, waterLevel, boundary, friction });
+        this.dx = width / (columns - 1);
+        this.dz = depth / (rows - 1);
+        this.minX = centerX - width / 2;
+        this.minZ = centerZ - depth / 2;
+        this.length = columns * rows;
+        for (const key of ['bed', 'h', 'qx', 'qz', 'dh', 'dqx', 'dqz', 'foam', 'nextFoam', 'dFoamMass', 'moisture']) {
+            this[key] = new Float64Array(this.length);
+        }
+        for (let z = 0; z < rows; z++)
+            for (let x = 0; x < columns; x++) {
+                const i = z * columns + x;
+                this.bed[i] = bedHeight(this.minX + x * this.dx, this.minZ + z * this.dz);
+                if (!Number.isFinite(this.bed[i]))
+                    throw new TypeError('Non-finite water bed');
+                this.h[i] = Math.max(0, waterLevel - this.bed[i]);
+            }
+        this.time = 0;
+        this.boundaryVolume = 0;
+        this.roundoffVolume = 0;
+        this.initialVolume = this.volume();
+        this.steps = 0;
+        this.foamLifetime = 4;
+        this.foamResidueLifetime = 10;
+        this.ghost = { h: 0, qx: 0, qz: 0, bed: 0 };
+    }
+    volume() { return this.h.reduce((a, h) => a + h, 0) * this.dx * this.dz; }
+    diagnostics() {
+        return { time: this.time, steps: this.steps, volume: this.volume(), boundaryVolume: this.boundaryVolume,
+            massError: this.volume() - this.initialVolume - this.boundaryVolume - this.roundoffVolume,
+            roundoffVolume: this.roundoffVolume, minDepth: this.h.reduce((a, h) => Math.min(a, h), Infinity) };
+    }
+    // A momentum impulse moves water without injecting mass. Direction is
+    // radial for a splash; wakes can supply an explicit horizontal direction.
+    impulse(x, z, strength = 0.2, radius = 0.8, direction = null) {
+        const r = Math.max(radius, Math.min(this.dx, this.dz));
+        for (let iz = Math.max(0, Math.floor((z - r * 3 - this.minZ) / this.dz)); iz <= Math.min(this.rows - 1, Math.ceil((z + r * 3 - this.minZ) / this.dz)); iz++) {
+            for (let ix = Math.max(0, Math.floor((x - r * 3 - this.minX) / this.dx)); ix <= Math.min(this.columns - 1, Math.ceil((x + r * 3 - this.minX) / this.dx)); ix++) {
+                const i = iz * this.columns + ix, rx = this.minX + ix * this.dx - x, rz = this.minZ + iz * this.dz - z;
+                const d = Math.hypot(rx, rz), weight = Math.exp(-d * d / (2 * r * r)) * strength;
+                this.qx[i] += this.h[i] * weight * (direction?.[0] ?? rx / Math.max(d, r * 0.1));
+                this.qz[i] += this.h[i] * weight * (direction?.[1] ?? rz / Math.max(d, r * 0.1));
+            }
+        }
+    }
+    face(left, right, axis, dt) {
+        const { h, qx, qz, bed, dh, dqx, dqz } = this;
+        const ghost = this.ghost;
+        const hL = left < 0 ? ghost.h : h[left], hR = right < 0 ? ghost.h : h[right];
+        const bL = left < 0 ? ghost.bed : bed[left], bR = right < 0 ? ghost.bed : bed[right];
+        const uL = hL > DRY ? (left < 0 ? ghost.qx : qx[left]) / hL : 0;
+        const vL = hL > DRY ? (left < 0 ? ghost.qz : qz[left]) / hL : 0;
+        const uR = hR > DRY ? (right < 0 ? ghost.qx : qx[right]) / hR : 0;
+        const vR = hR > DRY ? (right < 0 ? ghost.qz : qz[right]) / hR : 0;
+        const crest = Math.max(bL, bR);
+        const a = Math.max(0, hL + bL - crest), b = Math.max(0, hR + bR - crest);
+        const normalL = axis === 0 ? uL : vL, normalR = axis === 0 ? uR : vR;
+        // Two-sided HLL wave speeds retain an advancing bore more clearly
+        // than a single maximum-speed viscosity in every direction.
+        const cL = Math.sqrt(G*a), cR = Math.sqrt(G*b);
+        const sL = Math.min(0, normalL-cL, normalR-cR, a<=DRY ? normalR-2*cR : Infinity);
+        const sR = Math.max(0, normalL+cL, normalR+cR, b<=DRY ? normalL+2*cL : -Infinity);
+        const width = Math.max(sR-sL, 1e-8);
+        const flux = (fL,fR,delta) => (sR*fL-sL*fR+sL*sR*delta)/width;
+        const mass = flux(a*normalL,b*normalR,b-a);
+        // Transport aeration with the very same water flux. Sampling a
+        // concentration backwards into dry cells diluted the leading swash
+        // foam to zero even while aerated water was entering those cells.
+        const foamFlux = mass * (mass >= 0 ? (left < 0 ? 0 : this.foam[left]) : (right < 0 ? 0 : this.foam[right]));
+        const fx = flux(a*normalL*uL+(axis===0?G*a*a*0.5:0), b*normalR*uR+(axis===0?G*b*b*0.5:0),b*uR-a*uL);
+        const fz = flux(a*normalL*vL+(axis===1?G*a*a*0.5:0), b*normalR*vR+(axis===1?G*b*b*0.5:0),b*vR-a*vL);
+        const scale = dt / (axis === 0 ? this.dx : this.dz);
+        if (left >= 0) {
+            dh[left] -= scale * mass;
+            this.dFoamMass[left] -= scale * foamFlux;
+            dqx[left] -= scale * (fx + (axis === 0 ? G * (hL * hL - a * a) * 0.5 : 0));
+            dqz[left] -= scale * (fz + (axis === 1 ? G * (hL * hL - a * a) * 0.5 : 0));
+        }
+        else
+            this.boundaryVolume += mass * dt * (axis === 0 ? this.dz : this.dx);
+        if (right >= 0) {
+            dh[right] += scale * mass;
+            this.dFoamMass[right] += scale * foamFlux;
+            dqx[right] += scale * (fx + (axis === 0 ? G * (hR * hR - b * b) * 0.5 : 0));
+            dqz[right] += scale * (fz + (axis === 1 ? G * (hR * hR - b * b) * 0.5 : 0));
+        }
+        else
+            this.boundaryVolume -= mass * dt * (axis === 0 ? this.dz : this.dx);
+    }
+    boundaryFace(i, side, axis, low, dt) {
+        const { ghost } = this;
+        ghost.h = this.h[i];
+        ghost.qx = this.qx[i];
+        ghost.qz = this.qz[i];
+        ghost.bed = this.bed[i];
+        const ix = i % this.columns, iz = Math.floor(i / this.columns);
+        const handled = this.boundary?.(side, this.minX + ix * this.dx, this.minZ + iz * this.dz, this.time, ghost);
+        if (!handled) {
+            if (axis === 0)
+                ghost.qx *= -1;
+            else
+                ghost.qz *= -1;
+        }
+        ghost.h = Math.max(0, ghost.h);
+        this.face(low ? -1 : i, low ? i : -1, axis, dt);
+    }
+    advance(duration) {
+        let remaining = Math.max(0, duration);
+        while (remaining > 1e-9) {
+            let rate = 1;
+            for (let i = 0; i < this.length; i++) {
+                const h = this.h[i], c = Math.sqrt(G * h);
+                rate = Math.max(rate, ((h > DRY ? Math.abs(this.qx[i]) / h : 0) + c) / this.dx + ((h > DRY ? Math.abs(this.qz[i]) / h : 0) + c) / this.dz);
+            }
+            // Unsplit 2D CFL; include a conservative cap for external forcing.
+            const dt = Math.min(remaining, 0.32 / rate, 1 / 120);
+            this.step(dt);
+            remaining -= dt;
+        }
+    }
+    step(dt) {
+        this.dh.fill(0);
+        this.dqx.fill(0);
+        this.dqz.fill(0);
+        this.dFoamMass.fill(0);
+        const nx = this.columns, nz = this.rows;
+        for (let z = 0; z < nz; z++) {
+            for (let x = 0; x < nx - 1; x++)
+                this.face(z * nx + x, z * nx + x + 1, 0, dt);
+            this.boundaryFace(z * nx, 'west', 0, true, dt);
+            this.boundaryFace(z * nx + nx - 1, 'east', 0, false, dt);
+        }
+        for (let x = 0; x < nx; x++) {
+            for (let z = 0; z < nz - 1; z++)
+                this.face(z * nx + x, (z + 1) * nx + x, 1, dt);
+            this.boundaryFace(x, 'south', 1, true, dt);
+            this.boundaryFace((nz - 1) * nx + x, 'north', 1, false, dt);
+        }
+        for (let i = 0; i < this.length; i++) {
+            const next = this.h[i] + this.dh[i];
+            const foamMass = this.h[i] * this.foam[i] + this.dFoamMass[i];
+            this.nextFoam[i] = next > DRY ? Math.max(0,Math.min(1,foamMass/next)) : this.foam[i];
+            if (!Number.isFinite(next) || next < -1e-7)
+                throw new Error(`Unstable water depth at ${i}: ${next}`);
+            if (next < 0)
+                this.roundoffVolume -= next * this.dx * this.dz;
+            this.h[i] = Math.max(next, 0);
+            this.qx[i] += this.dqx[i];
+            this.qz[i] += this.dqz[i];
+            if (this.h[i] <= DRY) {
+                this.qx[i] = 0;
+                this.qz[i] = 0;
+            }
+            else {
+                // Semi-implicit Manning bed friction removes energy, never water.
+                const damping = 1 + dt * G * this.friction ** 2 * Math.hypot(this.qx[i], this.qz[i]) / Math.max(this.h[i] ** (7 / 3), 1e-7);
+                this.qx[i] /= damping;
+                this.qz[i] /= damping;
+            }
+        }
+        // Foam is a passive visual tracer advected by the solved velocity.
+        // Only converging, moving shallow water generates new aeration.
+        for (let z = 0; z < nz; z++)
+            for (let x = 0; x < nx; x++) {
+                const i = z * nx + x, h = this.h[i], u = h > DRY ? this.qx[i] / h : 0, v = h > DRY ? this.qz[i] / h : 0;
+                const left = i - (x > 0 ? 1 : 0), right = i + (x < nx - 1 ? 1 : 0), down = i - (z > 0 ? nx : 0), up = i + (z < nz - 1 ? nx : 0);
+                const du = ((this.h[right] > DRY ? this.qx[right] / this.h[right] : 0) - (this.h[left] > DRY ? this.qx[left] / this.h[left] : 0)) / (2 * this.dx);
+                const dv = ((this.h[up] > DRY ? this.qz[up] / this.h[up] : 0) - (this.h[down] > DRY ? this.qz[down] / this.h[down] : 0)) / (2 * this.dz);
+                // Ordinary orbital convergence is not breaking: without a
+                // shallow-flow gate every incoming swell filled with foam.
+                // Aerate rapid, converging bores and wakes, then let their
+                // tracer travel into slower backwash and decay there.
+                const speed = Math.hypot(u, v);
+                const froude = speed / Math.sqrt(G * Math.max(h, 0.025));
+                const breaking = Math.max(0, Math.min(1, (froude - 0.45) / 0.45));
+                const source = Math.max(0, -du - dv - 0.15) * breaking * Math.min(1, speed) * Math.min(1, h / 0.025);
+                const transported = this.nextFoam[i];
+                const lifetime = h > 0.002 ? this.foamLifetime : this.foamResidueLifetime;
+                this.nextFoam[i] = Math.min(1, transported * Math.exp(-dt / Math.max(lifetime, 0.25)) + source * dt * 1.5);
+                this.moisture[i] = h > 0.001 ? 1 : this.moisture[i] * Math.exp(-dt / 16);
+            }
+        [this.foam, this.nextFoam] = [this.nextFoam, this.foam];
+        this.time += dt;
+        this.steps++;
+    }
+    sampleArray(array, x, z) {
+        x = Math.max(0, Math.min(this.columns - 1, x));
+        z = Math.max(0, Math.min(this.rows - 1, z));
+        const ix = Math.min(this.columns - 2, Math.floor(x)), iz = Math.min(this.rows - 2, Math.floor(z)), tx = x - ix, tz = z - iz, i = iz * this.columns + ix;
+        return (array[i] * (1 - tx) + array[i + 1] * tx) * (1 - tz) + (array[i + this.columns] * (1 - tx) + array[i + this.columns + 1] * tx) * tz;
+    }
+    sample(x, z, out = {}) {
+        const gx = (x - this.minX) / this.dx, gz = (z - this.minZ) / this.dz;
+        out.depth = this.sampleArray(this.h, gx, gz);
+        out.height = this.sampleArray(this.bed, gx, gz) + out.depth;
+        out.velocityX = out.depth > DRY ? this.sampleArray(this.qx, gx, gz) / out.depth : 0;
+        out.velocityZ = out.depth > DRY ? this.sampleArray(this.qz, gx, gz) / out.depth : 0;
+        return out;
+    }
+}

package/src/water/waterMaterial.js

@@ -229,6 +229,7 @@ export function createWaterMaterial(options = {}) {
     detailOctaves: qualityDefines.WATER_DETAIL_OCTAVES,
     foamOctaves: qualityDefines.WATER_FOAM_OCTAVES,
     shoaling: Boolean(options.shoaling),
+    dynamics: Boolean(options.dynamics),
   });
   return applyWaterSettingsToMaterial(
     material,

package/src/water/waterRenderExtension.js

@@ -0,0 +1,107 @@
+import * as THREE from 'three';
+
+// Visual continuation around a finite coastal solve. Boundary vertices are
+// shared exactly; incoming wave phases continue offshore as a heightfield.
+// This adds distant context, not extra simulated volume or interactive cells.
+export class WaterRenderExtension {
+  constructor(dynamics, extent) {
+    this.dynamics = dynamics;
+    const d = dynamics;
+    const axis = (center, width, count) => {
+      const low = center - width / 2, high = center + width / 2;
+      const inner = Array.from({length:count},(_,i)=>low+i*width/(count-1));
+      const distances = [1, 3, 7, 15, 31, 63, 127, extent / 2];
+      return [...distances.map(v=>low-v).reverse(), ...inner, ...distances.map(v=>high+v)];
+    };
+    this.xs = axis(d.x, d.surface.width, d.columns);
+    this.zs = axis(d.z, d.surface.depth, d.rows);
+    const nx=this.xs.length, nz=this.zs.length;
+    const positions=[], indices=[];
+    for(const z of this.zs)for(const x of this.xs) positions.push(x-d.x,0,z-d.z);
+    for(let z=0;z<nz-1;z++)for(let x=0;x<nx-1;x++) {
+      // Omit every face already covered by the physical grid.
+      if(x>=8&&x<8+d.columns-1&&z>=8&&z<8+d.rows-1) continue;
+      const a=z*nx+x,b=a+1,c=a+nx,e=c+1;
+      indices.push(a,c,b,b,c,e);
+    }
+    this.geometry = new THREE.BufferGeometry();
+    this.geometry.setAttribute('position',new THREE.Float32BufferAttribute(positions,3));
+    this.geometry.setIndex(indices);
+    this.geometry.computeVertexNormals();
+    this.states = new Float32Array(nx*nz*4);
+    this.normals = new Float32Array(nx*nz*3);
+    this.wetDistances = new Float32Array(nx*nz);
+    this.geometry.setAttribute('aWaterState',new THREE.BufferAttribute(this.states,4).setUsage(THREE.DynamicDrawUsage));
+    this.geometry.setAttribute('aWaterNormal',new THREE.BufferAttribute(this.normals,3).setUsage(THREE.DynamicDrawUsage));
+    this.geometry.setAttribute('aWaterWetDistance',new THREE.BufferAttribute(this.wetDistances,1).setUsage(THREE.DynamicDrawUsage));
+    this.mesh = new THREE.Mesh(this.geometry,d.surface.material);
+    this.mesh.name = 'WaterLabCoastalContinuation';
+    this.mesh.frustumCulled = false;
+    this.mesh.userData.waterExclude = true;
+    d.surface.add(this.mesh);
+    this.sample = {};
+  }
+  incoming(x,z,stepX=0,stepZ=0) {
+    const d=this.dynamics;
+    let h=0;
+    for(const w of d.incidentWaves ?? []) {
+      const frequency=w.waveNumber*(Math.abs(w.dirX)*stepX+Math.abs(w.dirZ)*stepZ);
+      const resolved=1-THREE.MathUtils.smoothstep(frequency,Math.PI*.45,Math.PI*.95);
+      h+=resolved*w.amplitude*Math.sin(w.waveNumber*(w.dirX*x+w.dirZ*z)-w.omega*d.time+w.phase);
+    }
+    return h;
+  }
+  update() {
+    const d=this.dynamics,nx=this.xs.length,nz=this.zs.length;
+    this.mesh.material=d.surface.material;
+    for(let z=0;z<nz;z++)for(let x=0;x<nx;x++) {
+      const wx=this.xs[x],wz=this.zs[z],i=z*nx+x;
+      const cx=THREE.MathUtils.clamp((wx-d.minX)/d.dx,0,d.columns-1),ix=Math.min(d.columns-2,Math.floor(cx));
+      this.wetDistances[i]=THREE.MathUtils.lerp(d.shoreContour[ix],d.shoreContour[ix+1],cx-ix)-wz;
+      if(x>=8&&x<8+d.columns&&z>=8&&z<8+d.rows) {
+        const source=((z-8)*d.columns+x-8)*4;
+        this.states.set(d.state.subarray(source,source+4),i*4);
+        continue;
+      }
+      const bx=THREE.MathUtils.clamp(wx,d.minX,d.minX+d.surface.width);
+      const bz=THREE.MathUtils.clamp(wz,d.minZ,d.minZ+d.surface.depth);
+      const distance=Math.hypot(wx-bx,wz-bz);
+      const boundary=d.sample(bx,bz,this.sample);
+      const bed=d.bed(wx,wz), restDepth=Math.max(0,d.level-bed);
+      const stepX=(this.xs[Math.min(nx-1,x+1)]-this.xs[Math.max(0,x-1)])/2;
+      const stepZ=(this.zs[Math.min(nz-1,z+1)]-this.zs[Math.max(0,z-1)])/2;
+      const incoming=this.incoming(wx,wz,stepX,stepZ);
+      // Match the solved boundary exactly, then smoothly remove its local
+      // correction as incoming waves extend into the distant context.
+      const correction=(boundary.height-d.level-this.incoming(bx,bz))*Math.exp(-((distance/18)**2));
+      const allowance=0.35*restDepth;
+      const farHeight=d.level+(allowance>1e-5?allowance*Math.tanh((incoming+correction)/allowance):0);
+      // Continue the measured shore profile alongshore. Fading it to a
+      // rest-depth wave offshore formula on dry sand cut the run-up off at
+      // the two side boundaries. Only deep context tends to that formula.
+      const blend=THREE.MathUtils.smoothstep(distance,0,8)*THREE.MathUtils.smoothstep(restDepth,.5,2.5);
+      const height=THREE.MathUtils.lerp(boundary.height,farHeight,blend);
+      this.states[i*4]=Math.max(bed,height);
+      this.states[i*4+1]=Math.max(0,height-bed);
+      this.states[i*4+2]=boundary.velocityX;
+      this.states[i*4+3]=boundary.velocityZ;
+    }
+    for(let z=0;z<nz;z++)for(let x=0;x<nx;x++) {
+      const i=z*nx+x, left=Math.max(0,x-1),right=Math.min(nx-1,x+1),down=Math.max(0,z-1),up=Math.min(nz-1,z+1);
+      const gx=(this.states[(z*nx+right)*4]-this.states[(z*nx+left)*4])/(this.xs[right]-this.xs[left]);
+      const gz=(this.states[(up*nx+x)*4]-this.states[(down*nx+x)*4])/(this.zs[up]-this.zs[down]);
+      const inv=1/Math.hypot(gx,1,gz);
+      this.normals[i*3]=-gx*inv;this.normals[i*3+1]=inv;this.normals[i*3+2]=-gz*inv;
+      // At the seam also match the original displayed normal, so there is
+      // no abrupt reflection line despite different outer tessellation.
+      if(x>=8&&x<8+d.columns&&z>=8&&z<8+d.rows) {
+        const source=((z-8)*d.columns+x-8)*3;
+        this.normals.set(d.normals.subarray(source,source+3),i*3);
+      }
+    }
+    this.geometry.attributes.aWaterState.needsUpdate=true;
+    this.geometry.attributes.aWaterNormal.needsUpdate=true;
+    this.geometry.attributes.aWaterWetDistance.needsUpdate=true;
+  }
+  dispose() {this.mesh.removeFromParent();this.geometry.dispose();}
+}

package/src/water/waterScenePasses.js

@@ -408,7 +408,14 @@ export class WaterScenePasses {
     this.ensureGrabTarget(renderer);
     this.scratch.waterWorldPosition.setFromMatrixPosition(waterMesh.matrixWorld);
     camera.getWorldPosition(this.scratch.cameraPosition);
-    const cameraBelow = this.scratch.cameraPosition.y < this.scratch.waterWorldPosition.y;
+    const cameraBelowUniform = waterMesh.material?.uniforms?.uCameraBelow;
+    // Standalone meshes using WaterScenePasses may not run WaterSurface's
+    // column update; retain their original rest-plane fallback.
+    const hasSurfaceColumn = typeof waterMesh.getHeightAt === 'function'
+      && typeof waterMesh.containsPoint === 'function';
+    const cameraBelow = hasSurfaceColumn && cameraBelowUniform
+      ? cameraBelowUniform.value > 0.5
+      : this.scratch.cameraPosition.y < this.scratch.waterWorldPosition.y;
     // Above water the grab sees the submerged scene. Below water it becomes a
     // same-pose transmission camera clipped to the air side of the surface,
     // so clouds and above-water objects are genuinely visible through it.
@@ -459,13 +466,13 @@ export class WaterScenePasses {
     }
   }
 
-  applyWaterClipPlane(renderer, camera, waterY) {
+  applyWaterClipPlane(renderer, camera, waterY, side = 1) {
     // Oblique near-plane clipping (Lengyel), matching THREE.Reflector's
     // coordinate-system-aware construction. The positive side of this plane
     // is the air volume, even when the virtual camera itself is underwater.
     const { plane, clipPlane, q } = this.scratch;
-    plane.normal.set(0, 1, 0);
-    plane.constant = -waterY;
+    plane.normal.set(0, side, 0);
+    plane.constant = -waterY * side;
     plane.applyMatrix4(camera.matrixWorldInverse);
     clipPlane.set(plane.normal.x, plane.normal.y, plane.normal.z, plane.constant);
 
@@ -508,7 +515,8 @@ export class WaterScenePasses {
   updateReflectionCamera(renderer, camera, waterY) {
     const { cameraPosition, cameraDirection, target } = this.scratch;
     camera.getWorldPosition(cameraPosition);
-    if (cameraPosition.y <= waterY + 1e-4) return false;
+    if (Math.abs(cameraPosition.y - waterY) < 1e-4) return false;
+    const reflectionSide = cameraPosition.y < waterY ? -1 : 1;
 
     camera.getWorldDirection(cameraDirection);
     target.copy(cameraPosition).add(cameraDirection);
@@ -528,7 +536,7 @@ export class WaterScenePasses {
     reflectionCamera.updateMatrixWorld();
     reflectionCamera.matrixWorldInverse.copy(reflectionCamera.matrixWorld).invert();
 
-    this.applyWaterClipPlane(renderer, reflectionCamera, waterY);
+    this.applyWaterClipPlane(renderer, reflectionCamera, waterY, reflectionSide);
 
     this.reflectionMatrix
       .copy(BIAS_MATRIX)