@woosh/meep-engine 3.41.0 → 3.42.0

package/src/shade/renderer/water/surface/spectrum/WATER_BAND_STATE.js

@@ -0,0 +1,57 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { atomic_u32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { chunk_water_spectrum } from "./chunk_water_spectrum.js";
+import { WATER_SPECTRUM_BAND_COUNT } from "./WATER_SPECTRUM.js";
+
+/** The bits of every band. */
+export const WATER_SPECTRUM_ALL_BANDS = (1 << WATER_SPECTRUM_BAND_COUNT) - 1;
+
+const fields = (word) => ({
+    /** Bands whose tiles hold the time of the last evaluation. */
+    valid: word,
+    /** Bands the frame's spectrum passes evaluate: asked for and not valid. */
+    todo: word,
+    reserved_a: word,
+    reserved_b: word,
+    /**
+     * Per band, the largest |h| and |(Dx, Dz)| it has shown at any time evaluated on this device (f32 bits).
+     * Never cleared: a band is one fixed realisation, so this is a property of the band.
+     */
+    envelope: WebGPUArray.from(word, 2 * WATER_SPECTRUM_BAND_COUNT),
+});
+
+/**
+ * What the device's band spectrum knows about its bands, persistent across frames
+ * (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3.1). Read with plain loads by the passes that only read it —
+ * the culling pass reads every envelope for every body — and atomically by the passes that write it.
+ */
+export const WATER_BAND_STATE_STRUCT = WebGPUStruct.from(fields(u32), 'WaterBandState');
+
+/** The same state where the passes that write it take it, every word atomic. */
+export const WATER_BAND_STATE_ATOMIC_STRUCT = WebGPUStruct.from(fields(atomic_u32), 'WaterBandStateAtomic');
+
+/**
+ * The bands the frame's visible bodies can draw, ORed in by the culling pass and taken by its finalize: apart from the
+ * band state, so that the culling pass reads that with plain loads.
+ */
+export const WATER_BAND_REQUESTS_STRUCT = WebGPUStruct.from({
+    needed: atomic_u32, reserved_a: u32, reserved_b: u32, reserved_c: u32,
+}, 'WaterBandRequests');
+
+/**
+ * @type {CodeChunk}
+ */
+export const chunk_water_band_state = CodeChunk.from(/* language=WGSL */ `
+// The n-th band set in mask, counting from band 0; WATER_SPECTRUM_BANDS when it has fewer.
+fn water_band_nth(mask: u32, n: u32) -> u32 {
+    var remaining = n;
+    for (var band = 0u; band < WATER_SPECTRUM_BANDS; band++) {
+        if ((mask & (1u << band)) == 0u) { continue; }
+        if (remaining == 0u) { return band; }
+        remaining--;
+    }
+    return WATER_SPECTRUM_BANDS;
+}
+`, [chunk_water_spectrum]);

package/src/shade/renderer/water/surface/spectrum/WATER_SPECTRUM.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Octave bands of the shared ambient-wave basis (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.1).
+ *
+ * Band j holds waves of wavelength λⱼ/2 … 2λⱼ around its node λⱼ = SHORTEST · 2ʲ, on a periodic tile of
+ * 16 node wavelengths. Every water body's ambient waves are a weighted sum of the same bands.
+ */
+export const WATER_SPECTRUM_BAND_COUNT: 18;
+/** Node wavelength of band 0, metres: 7.8 mm, capillary ripples. Band 17 is 1,024 m swell. */
+export const WATER_SPECTRUM_SHORTEST_WAVELENGTH: number;
+/**
+ * Texels per side of a band's tile. Its content sits at mode indices 8 … 32, so the band's shortest waves keep four
+ * texels a wavelength under bilinear sampling.
+ */
+export const WATER_SPECTRUM_TILE_SIZE: 128;
+/** A band's tile period in node wavelengths: the node sits at mode index 16. */
+export const WATER_SPECTRUM_TILE_WAVELENGTHS: 16;
+/**
+ * Angular frequencies are quantized to multiples of 2π / this many seconds, so every wave repeats
+ * after it and the phase can be taken from `time mod LOOP` at full f32 precision (Tessendorf 2001 §3.3).
+ */
+export const WATER_SPECTRUM_LOOP_SECONDS: 1024;
+//# sourceMappingURL=WATER_SPECTRUM.d.ts.map

package/src/shade/renderer/water/surface/spectrum/WATER_SPECTRUM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WATER_SPECTRUM.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/spectrum/WATER_SPECTRUM.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,2CAA4C;AAE5C,8FAA8F;AAC9F,wDAA0D;AAE1D;;;GAGG;AACH,2CAA4C;AAE5C,gFAAgF;AAChF,iDAAkD;AAElD;;;GAGG;AACH,+CAAgD"}

package/src/shade/renderer/water/surface/spectrum/WATER_SPECTRUM.js

@@ -0,0 +1,25 @@
+/**
+ * Octave bands of the shared ambient-wave basis (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.1).
+ *
+ * Band j holds waves of wavelength λⱼ/2 … 2λⱼ around its node λⱼ = SHORTEST · 2ʲ, on a periodic tile of
+ * 16 node wavelengths. Every water body's ambient waves are a weighted sum of the same bands.
+ */
+export const WATER_SPECTRUM_BAND_COUNT = 18;
+
+/** Node wavelength of band 0, metres: 7.8 mm, capillary ripples. Band 17 is 1,024 m swell. */
+export const WATER_SPECTRUM_SHORTEST_WAVELENGTH = 1 / 128;
+
+/**
+ * Texels per side of a band's tile. Its content sits at mode indices 8 … 32, so the band's shortest waves keep four
+ * texels a wavelength under bilinear sampling.
+ */
+export const WATER_SPECTRUM_TILE_SIZE = 128;
+
+/** A band's tile period in node wavelengths: the node sits at mode index 16. */
+export const WATER_SPECTRUM_TILE_WAVELENGTHS = 16;
+
+/**
+ * Angular frequencies are quantized to multiples of 2π / this many seconds, so every wave repeats
+ * after it and the phase can be taken from `time mod LOOP` at full f32 precision (Tessendorf 2001 §3.3).
+ */
+export const WATER_SPECTRUM_LOOP_SECONDS = 1024;

package/src/shade/renderer/water/surface/spectrum/chunk_water_jonswap.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A wind sea's spectrum from its wind and fetch: JONSWAP (Hasselmann et al. 1973) with the fetch relations
+ * as Horvath 2015 restates them, clamped at the fully developed (Pierson–Moskowitz) sea, and turned into a
+ * wavenumber spectrum through the gravity–capillary dispersion relation the band basis uses
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.2).
+ *
+ * Above the peak the saturation k³F(k) is α/2 for gravity waves, so the band weights carry measured
+ * sea-surface slopes without a fitted term.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_jonswap: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_jonswap.d.ts.map

package/src/shade/renderer/water/surface/spectrum/chunk_water_jonswap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_jonswap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/spectrum/chunk_water_jonswap.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,kCAFU,SAAS,CAmCQ;0BA/CD,uCAAuC"}

package/src/shade/renderer/water/surface/spectrum/chunk_water_jonswap.js

@@ -0,0 +1,48 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_water_spectrum } from "./chunk_water_spectrum.js";
+
+/**
+ * A wind sea's spectrum from its wind and fetch: JONSWAP (Hasselmann et al. 1973) with the fetch relations
+ * as Horvath 2015 restates them, clamped at the fully developed (Pierson–Moskowitz) sea, and turned into a
+ * wavenumber spectrum through the gravity–capillary dispersion relation the band basis uses
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.2).
+ *
+ * Above the peak the saturation k³F(k) is α/2 for gravity waves, so the band weights carry measured
+ * sea-surface slopes without a fitted term.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_jonswap = CodeChunk.from(/* language=WGSL */ `
+struct WaterJonswap {
+    // peak angular frequency, rad/s
+    peak: f32,
+    // Phillips' constant
+    alpha: f32,
+}
+
+// Wind speed U at 10 m (m/s) and fetch F (m). Dimensionless fetch X = gF/U²: the peak and α fall with
+// fetch until the sea is fully developed near X ≈ 2·10⁴ (ω_p = 0.855 g/U, α = 0.0081).
+fn water_jonswap(wind_speed: f32, fetch: f32) -> WaterJonswap {
+    let x = max(WATER_GRAVITY * fetch / max(wind_speed * wind_speed, 1e-12), 1e-6);
+    let peak = max(22.0 * WATER_GRAVITY / max(wind_speed, 1e-6) * pow(x, -1.0 / 3.0), 0.855 * WATER_GRAVITY / max(wind_speed, 1e-6));
+    let alpha = clamp(0.076 * pow(x, -0.22), 0.0081, 0.1);
+    return WaterJonswap(peak, alpha);
+}
+
+// Saturation B(k) = k³ F(k) of the sea at wavenumber k, F(k) = S(ω) dω/dk.
+fn water_jonswap_saturation(sea: WaterJonswap, k: f32) -> f32 {
+    let omega = water_dispersion(k);
+    let ratio = sea.peak / omega;
+    let sigma = select(0.09, 0.07, omega <= sea.peak);
+    let deviation = (omega - sea.peak) / (sigma * sea.peak);
+    let enhancement = pow(3.3, exp(-0.5 * deviation * deviation));
+    let r2 = ratio * ratio;
+    // S(ω) ω⁵ / (α g²): exp(−5/4 (ω_p/ω)⁴) γ^r
+    let shape = exp(-1.25 * r2 * r2) * enhancement;
+    // k³ · α g² ω⁻⁵ · shape · dω/dk with dω/dk = (g + 3τk²) / 2ω, written through q = gk/ω² (1 for
+    // gravity waves, below 1 where surface tension stiffens them) so no power of ω leaves f32
+    let w2 = omega * omega;
+    let q = WATER_GRAVITY * k / w2;
+    return sea.alpha * shape * q * q * k * (WATER_GRAVITY + 3.0 * WATER_SURFACE_TENSION * k * k) / (2.0 * w2);
+}
+`, [chunk_water_spectrum]);

package/src/shade/renderer/water/surface/spectrum/chunk_water_spectrum.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Exponent s of the directional spreading cos^2s(θ/2) shared by every band. Hasselmann's s is ~10 at a
+ * sea's peak and falls towards 1 far above it; a basis shared by every body cannot follow each body's
+ * peak, so one value between the two is used (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.1).
+ */
+export const WATER_SPECTRUM_SPREADING: 6;
+/**
+ * The band basis of the ambient waves: where each band sits in wavelength, how its waves move, and the
+ * statistics of its unit-saturation spectrum (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4).
+ *
+ * Band j's tile is periodic over `water_band_period(j)` metres. Its waves travel, on average, towards
+ * `water_band_wind_angle(j)` in the tile's own frame: every band is turned by a further golden angle,
+ * so no two bands repeat in step. A sampler turns the tile so that angle points along a body's wind.
+ *
+ * The band's variance spectrum is the saturation spectrum B(k) = k³F(k) = 1 times φⱼ(k)², a hat in
+ * log₂ k over the two octaves around the node, so neighbouring bands' weights sum to one and a body's
+ * spectrum, Σ wⱼ² φⱼ², is its saturation spectrum interpolated linearly in log k between nodes.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_spectrum: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_spectrum.d.ts.map

package/src/shade/renderer/water/surface/spectrum/chunk_water_spectrum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_spectrum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/spectrum/chunk_water_spectrum.js"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,yCAA0C;AAc1C;;;;;;;;;;;;;GAaG;AACH,mCAFU,SAAS,CA8HyB;0BAxKlB,uCAAuC"}

package/src/shade/renderer/water/surface/spectrum/chunk_water_spectrum.js

@@ -0,0 +1,169 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { GOLDEN_ANGLE_DECLARATION } from "../../../shader/chunk/math/GOLDEN_ANGLE_DECLARATION.js";
+import { chunk_pcg3d } from "../../../shader/chunk/random/pcg/chunk_pcg3d.js";
+import {
+    WATER_SPECTRUM_BAND_COUNT,
+    WATER_SPECTRUM_LOOP_SECONDS,
+    WATER_SPECTRUM_SHORTEST_WAVELENGTH,
+    WATER_SPECTRUM_TILE_SIZE,
+    WATER_SPECTRUM_TILE_WAVELENGTHS
+} from "./WATER_SPECTRUM.js";
+
+/**
+ * Exponent s of the directional spreading cos^2s(θ/2) shared by every band. Hasselmann's s is ~10 at a
+ * sea's peak and falls towards 1 far above it; a basis shared by every body cannot follow each body's
+ * peak, so one value between the two is used (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.1).
+ */
+export const WATER_SPECTRUM_SPREADING = 6;
+
+/**
+ * 1 / ∫ cos^2s(θ/2) dθ over a full turn, = (4^s (s!)²) / (2π (2s)!) for integer s.
+ * @param {number} s
+ * @returns {number}
+ */
+function spreading_normalization(s) {
+    let factorial = 1, double_factorial = 1;
+    for (let i = 2; i <= s; i++) { factorial *= i; }
+    for (let i = 2; i <= 2 * s; i++) { double_factorial *= i; }
+    return (4 ** s) * factorial * factorial / (2 * Math.PI * double_factorial);
+}
+
+/**
+ * The band basis of the ambient waves: where each band sits in wavelength, how its waves move, and the
+ * statistics of its unit-saturation spectrum (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4).
+ *
+ * Band j's tile is periodic over `water_band_period(j)` metres. Its waves travel, on average, towards
+ * `water_band_wind_angle(j)` in the tile's own frame: every band is turned by a further golden angle,
+ * so no two bands repeat in step. A sampler turns the tile so that angle points along a body's wind.
+ *
+ * The band's variance spectrum is the saturation spectrum B(k) = k³F(k) = 1 times φⱼ(k)², a hat in
+ * log₂ k over the two octaves around the node, so neighbouring bands' weights sum to one and a body's
+ * spectrum, Σ wⱼ² φⱼ², is its saturation spectrum interpolated linearly in log k between nodes.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_spectrum = CodeChunk.from(/* language=WGSL */ `
+const WATER_SPECTRUM_BANDS: u32 = ${WATER_SPECTRUM_BAND_COUNT}u;
+const WATER_SPECTRUM_TILE: u32 = ${WATER_SPECTRUM_TILE_SIZE}u;
+const WATER_SPECTRUM_SHORTEST: f32 = ${WATER_SPECTRUM_SHORTEST_WAVELENGTH};
+const WATER_SPECTRUM_TILE_WAVELENGTHS: f32 = ${WATER_SPECTRUM_TILE_WAVELENGTHS}.0;
+const WATER_SPECTRUM_LOOP: f32 = ${WATER_SPECTRUM_LOOP_SECONDS}.0;
+const WATER_SPECTRUM_SPREADING: f32 = ${WATER_SPECTRUM_SPREADING}.0;
+const WATER_SPECTRUM_SPREADING_NORMALIZATION: f32 = ${spreading_normalization(WATER_SPECTRUM_SPREADING)};
+const WATER_GRAVITY: f32 = 9.81;
+// surface tension over density, m³/s²
+const WATER_SURFACE_TENSION: f32 = 7.28e-5;
+const WATER_TAU: f32 = 6.28318530717958;
+
+fn water_band_wavelength(band: u32) -> f32 {
+    return WATER_SPECTRUM_SHORTEST * exp2(f32(band));
+}
+
+fn water_band_period(band: u32) -> f32 {
+    return WATER_SPECTRUM_TILE_WAVELENGTHS * water_band_wavelength(band);
+}
+
+fn water_band_wind_angle(band: u32) -> f32 {
+    return f32(band) * GOLDEN_ANGLE;
+}
+
+// Deep-water gravity–capillary angular frequency of wavenumber k (rad/m).
+fn water_dispersion(k: f32) -> f32 {
+    return sqrt(WATER_GRAVITY * k + WATER_SURFACE_TENSION * k * k * k);
+}
+
+// The band's share of a saturation spectrum at wavenumber k: a hat in log₂ k, one at the node,
+// zero an octave either side.
+fn water_band_hat(band: u32, k: f32) -> f32 {
+    let node = WATER_TAU / water_band_wavelength(band);
+    return max(1.0 - abs(log2(k / node)), 0.0);
+}
+
+// Directional spreading about the band's wind, normalized over a full turn.
+fn water_band_spreading(band: u32, direction: vec2<f32>) -> f32 {
+    let wind = water_band_wind_angle(band);
+    let c = clamp(dot(direction, vec2<f32>(cos(wind), sin(wind))), -1.0, 1.0);
+    // cos²(θ/2) = (1 + cos θ) / 2
+    return WATER_SPECTRUM_SPREADING_NORMALIZATION * pow(0.5 * (1.0 + c), WATER_SPECTRUM_SPREADING);
+}
+
+// The mode at tile index (x, z), signed: indices 32..63 are the negative wavenumbers.
+fn water_band_mode(index: vec2<u32>) -> vec2<i32> {
+    return vec2<i32>(index) - select(vec2<i32>(0), vec2<i32>(i32(WATER_SPECTRUM_TILE)), index >= vec2<u32>(WATER_SPECTRUM_TILE / 2u));
+}
+
+// Real amplitude of a mode, for a complex standard normal of E|ξ|² = 2: the square root of the band's
+// directional variance spectrum Ψ(k) = φ² k⁻⁴ D(θ) over the mode's cell, Δk².
+fn water_band_mode_amplitude(band: u32, mode: vec2<i32>) -> f32 {
+    if (all(mode == vec2<i32>(0))) { return 0.0; }
+    let dk = WATER_TAU / water_band_period(band);
+    let k = vec2<f32>(mode) * dk;
+    let magnitude = length(k);
+    let hat = water_band_hat(band, magnitude);
+    if (hat <= 0.0) { return 0.0; }
+    return sqrt(hat * water_band_spreading(band, k / magnitude)) * dk / (magnitude * magnitude);
+}
+
+// A complex standard normal for the mode, E|ξ|² = 2, the same every frame and on every device.
+fn water_band_gaussian(band: u32, mode: vec2<i32>) -> vec2<f32> {
+    let bits = pcg3d(vec3<u32>(band, bitcast<u32>(mode.x), bitcast<u32>(mode.y)));
+    let u1 = (f32(bits.x >> 8u) + 0.5) * (1.0 / 16777216.0);
+    let u2 = f32(bits.y >> 8u) * (1.0 / 16777216.0);
+    let radius = sqrt(-2.0 * log(u1));
+    return radius * vec2<f32>(cos(WATER_TAU * u2), sin(WATER_TAU * u2));
+}
+
+// The mode's phase ωt with ω quantized to whole turns per loop, so the phase can come from the time
+// within the loop, given as a fraction of it.
+fn water_band_mode_phase(k: f32, loop_fraction: f32) -> f32 {
+    let turns = round(water_dispersion(k) * WATER_SPECTRUM_LOOP / WATER_TAU);
+    return WATER_TAU * fract(turns * loop_fraction);
+}
+
+// The height spectrum h̃(k, t) of a mode, Hermitian in k so the field is real:
+// ½ [ξ(k) A(k) e^{−iωt} + conj(ξ(−k) A(−k)) e^{iωt}]. Under the transform's e^{ik·x}, the first term is
+// e^{i(k·x − ωt)}, a wave travelling towards k, so the energy A(k) puts along the wind travels downwind; the
+// second is the partner that makes the field real, and travels downwind too.
+fn water_band_height(band: u32, mode: vec2<i32>, loop_fraction: f32) -> vec2<f32> {
+    let a = water_band_gaussian(band, mode) * water_band_mode_amplitude(band, mode);
+    let b = water_band_gaussian(band, -mode) * water_band_mode_amplitude(band, -mode);
+    let dk = WATER_TAU / water_band_period(band);
+    let phase = water_band_mode_phase(length(vec2<f32>(mode)) * dk, loop_fraction);
+    let rotation = vec2<f32>(cos(phase), -sin(phase));
+    // a · e^{−iφ}
+    let forward = vec2<f32>(a.x * rotation.x - a.y * rotation.y, a.x * rotation.y + a.y * rotation.x);
+    // conj(b) · e^{iφ} = conj(b · e^{−iφ})
+    let backward = vec2<f32>(b.x * rotation.x - b.y * rotation.y, -(b.x * rotation.y + b.y * rotation.x));
+    return 0.5 * (forward + backward);
+}
+
+// A mode's four complex spectra, each two real fields as A + iB so one inverse transform yields both:
+// (h, Dx), (Dz, ∂h/∂x), (∂h/∂z, ∂Dx/∂x), (∂Dz/∂z, ∂Dx/∂z) — height, horizontal displacement and the
+// derivatives a normal and a Jacobian need.
+struct WaterBandFields {
+    a: vec2<f32>,
+    b: vec2<f32>,
+    c: vec2<f32>,
+    d: vec2<f32>,
+}
+
+fn water_band_fields(band: u32, mode: vec2<i32>, loop_fraction: f32) -> WaterBandFields {
+    let h = water_band_height(band, mode, loop_fraction);
+    let k = vec2<f32>(mode) * (WATER_TAU / water_band_period(band));
+    let magnitude = max(length(k), 1e-30);
+    // Horizontal displacement D̃ = i (k/k) h̃: for h = cos(k·x), D = −sin(k·x) k/k, so points slide towards a
+    // crest and away from a trough — a Gerstner wave's pinched crests, and the wave particles' sign.
+    var fields: WaterBandFields;
+    // h̃ + i·D̃x = h̃ (1 − kx/k)
+    fields.a = h * (1.0 - k.x / magnitude);
+    // D̃z + i·(∂h/∂x)~ = h̃ · (−kx + i kz/k)
+    fields.b = vec2<f32>(-k.x * h.x - k.y / magnitude * h.y, -k.x * h.y + k.y / magnitude * h.x);
+    // (∂h/∂z)~ + i·(∂Dx/∂x)~ = h̃ · i (kz − kx²/k)
+    let s = k.y - k.x * k.x / magnitude;
+    fields.c = vec2<f32>(-s * h.y, s * h.x);
+    // (∂Dz/∂z)~ + i·(∂Dx/∂z)~ = h̃ · −(kz²/k + i kx kz/k)
+    let c = -vec2<f32>(k.y * k.y, k.x * k.y) / magnitude;
+    fields.d = vec2<f32>(c.x * h.x - c.y * h.y, c.x * h.y + c.y * h.x);
+    return fields;
+}
+`, [GOLDEN_ANGLE_DECLARATION, chunk_pcg3d]);

package/src/shade/renderer/water/surface/spectrum/shader_water_spectrum.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Rows and columns of a band's modes that can hold content: mode indices −32 … 31 on either axis.
+ */
+export const WATER_SPECTRUM_CONTENT: 64;
+/** vec4s in the working buffer: bands × content rows × columns × two (four complex fields a texel). */
+export const WATER_SPECTRUM_ROW_VALUE_COUNT: number;
+/** Workgroups of the row pass a band: one a content row. */
+export const WATER_SPECTRUM_ROW_GROUPS_PER_BAND: 64;
+/** Workgroups of the column pass a band: one a column. */
+export const WATER_SPECTRUM_COLUMN_GROUPS_PER_BAND: 128;
+/**
+ * Each content row of every band in `band_state.todo` at the frame's time, transformed along x. The modes come from hashed Gaussians, so
+ * the tiles need no state and are the same on every device and every frame.
+ */
+export const shader_water_spectrum_rows: ComputeShader;
+/**
+ * Each column of every band in `band_state.todo` transformed along z, packed into the two band textures, and each
+ * band's largest |h| and |(Dx, Dz)| raised into its envelope (f32 bits, atomic max, never cleared): the largest the
+ * band has shown at any time evaluated. Bilinear sampling cannot leave the texel range, so a body's weighted sum of
+ * the envelopes bounds its displacement at every time evaluated.
+ *
+ * displacement = (Dx, h, Dz, ∂Dx/∂z), derivatives = (∂h/∂x, ∂h/∂z, ∂Dx/∂x, ∂Dz/∂z).
+ */
+export const shader_water_spectrum_columns: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_water_spectrum.d.ts.map

package/src/shade/renderer/water/surface/spectrum/shader_water_spectrum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_water_spectrum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/spectrum/shader_water_spectrum.js"],"names":[],"mappings":"AA6BA;;GAEG;AACH,wCAAyC;AAEzC,uGAAuG;AACvG,oDAAgI;AAEhI,4DAA4D;AAC5D,oDAAyE;AAEzE,0DAA0D;AAC1D,wDAA8E;AAO9E;;;GAGG;AACH,uDA8BsH;AAqEtH;;;;;;;GAOG;AACH,0DAC0B;8BA/JI,kCAAkC"}

package/src/shade/renderer/water/surface/spectrum/shader_water_spectrum.js

@@ -0,0 +1,161 @@
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_fft128x4_inverse_workgroup } from "../../../shader/chunk/math/fft/chunk_fft128x4_inverse_workgroup.js";
+import { chunk_water_spectrum } from "./chunk_water_spectrum.js";
+import { WATER_SPECTRUM_BAND_COUNT, WATER_SPECTRUM_TILE_SIZE } from "./WATER_SPECTRUM.js";
+import { chunk_water_band_state, WATER_BAND_STATE_ATOMIC_STRUCT, WATER_BAND_STATE_STRUCT } from "./WATER_BAND_STATE.js";
+
+/*
+ Two passes animate the bands the frame asked for (the band state's `todo` mask), dispatched indirectly with a
+ band's worth of workgroups for each, each one workgroup a line of all four of a band's complex fields (`water_band_fields`),
+ transformed together in 4 KiB of workgroup memory (`chunk_fft128x4_inverse_workgroup`):
+
+ - rows: a band's modes only reach index ±32 (its hat ends at twice its node, index 16), so only 64 of the 128 rows can
+   hold content. One workgroup a content row makes the row's modes and transforms them along x;
+ - columns: one workgroup a column of every band reads the content rows, zero elsewhere, transforms along z and packs
+   the texels into the band textures, with each band's extrema.
+
+ Between them a working buffer holds the four fields of one texel in one 32-byte cell, a memory sector, so the rows
+ write whole rows and the columns read whole sectors. Measured on an RTX 4090 against separate modes, row, column and
+ pack passes, each invocation running a 128-point line in private memory: it reproduces them to the f16 bit and takes
+ ~21 µs a frame instead of ~147 (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §8). A subgroup-shuffle variant of the
+ transform, with no barriers, measured no faster on the columns and 35% slower on the rows.
+*/
+
+/**
+ * Rows and columns of a band's modes that can hold content: mode indices −32 … 31 on either axis.
+ */
+export const WATER_SPECTRUM_CONTENT = 64;
+
+/** vec4s in the working buffer: bands × content rows × columns × two (four complex fields a texel). */
+export const WATER_SPECTRUM_ROW_VALUE_COUNT = WATER_SPECTRUM_BAND_COUNT * WATER_SPECTRUM_CONTENT * WATER_SPECTRUM_TILE_SIZE * 2;
+
+/** Workgroups of the row pass a band: one a content row. */
+export const WATER_SPECTRUM_ROW_GROUPS_PER_BAND = WATER_SPECTRUM_CONTENT;
+
+/** Workgroups of the column pass a band: one a column. */
+export const WATER_SPECTRUM_COLUMN_GROUPS_PER_BAND = WATER_SPECTRUM_TILE_SIZE;
+
+const rows_resources = new ShaderResourceSetDescriptor();
+rows_resources.setImmediate('loop_fraction', f32);
+rows_resources.createGroup().addStorageBuffer('rows', WebGPUArray.from(vec4f), true)
+    .addStorageBuffer('band_state', WATER_BAND_STATE_STRUCT);
+
+/**
+ * Each content row of every band in `band_state.todo` at the frame's time, transformed along x. The modes come from hashed Gaussians, so
+ * the tiles need no state and are the same on every device and every frame.
+ */
+export const shader_water_spectrum_rows = ComputeShader.from({ label: 'Water / spectrum rows', resources: rows_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+const WATER_SPECTRUM_CONTENT: u32 = ${WATER_SPECTRUM_CONTENT}u;
+
+@compute @workgroup_size(256)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let index = folded_workgroup_index(group);
+    let band = water_band_nth(band_state.todo, index / WATER_SPECTRUM_CONTENT);
+    if (band >= WATER_SPECTRUM_BANDS) { return; }
+    let row = band * WATER_SPECTRUM_CONTENT + index % WATER_SPECTRUM_CONTENT;
+    let mode_z = i32(row % WATER_SPECTRUM_CONTENT) - i32(WATER_SPECTRUM_CONTENT / 2u);
+    if (lane < WATER_SPECTRUM_TILE) {
+        var fields: WaterBandFields;
+        // x modes −32 … 31: the first and last quarter of the line
+        if (lane < WATER_SPECTRUM_CONTENT / 2u || lane >= WATER_SPECTRUM_TILE - WATER_SPECTRUM_CONTENT / 2u) {
+            fields = water_band_fields(band, vec2<i32>(water_band_mode(vec2<u32>(lane, 0u)).x, mode_z), loop_fraction);
+        }
+        let at = reverseBits(lane) >> 25u;
+        fft128x4_lines[at] = fields.a;
+        fft128x4_lines[128u + at] = fields.b;
+        fft128x4_lines[256u + at] = fields.c;
+        fft128x4_lines[384u + at] = fields.d;
+    }
+    fft128x4_inverse(lane);
+    if (lane < WATER_SPECTRUM_TILE) {
+        let cell = (row * WATER_SPECTRUM_TILE + lane) * 2u;
+        rows[cell] = vec4<f32>(fft128x4_lines[lane], fft128x4_lines[128u + lane]);
+        rows[cell + 1u] = vec4<f32>(fft128x4_lines[256u + lane], fft128x4_lines[384u + lane]);
+    }
+}
+`, [chunk_water_spectrum, chunk_fft128x4_inverse_workgroup, chunk_folded_workgroup_index, chunk_water_band_state]) });
+
+const columns_resources = new ShaderResourceSetDescriptor();
+columns_resources.createGroup()
+    .addStorageBuffer('rows', WebGPUArray.from(vec4f))
+    .addStorageTexture('displacement', 'rgba16float', '2d-array', 'write-only')
+    .addStorageTexture('derivatives', 'rgba16float', '2d-array', 'write-only')
+    .addStorageBuffer('band_state', WATER_BAND_STATE_ATOMIC_STRUCT, true);
+
+const columns_body = CodeChunk.from(/* language=WGSL */ `
+const WATER_SPECTRUM_CONTENT: u32 = ${WATER_SPECTRUM_CONTENT}u;
+
+// the column's largest |h| and |(Dx, Dz)|, gathered here first so a band's bound takes one atomic a column
+var<workgroup> water_column_peaks: array<atomic<u32>, 2>;
+// the frame's bands, read once: an atomic load is not uniform, a workgroup-uniform load of it is
+var<workgroup> water_column_todo: u32;
+
+@compute @workgroup_size(256)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let index = folded_workgroup_index(group);
+    if (lane == 0u) { water_column_todo = atomicLoad(&band_state.todo); }
+    let band = water_band_nth(workgroupUniformLoad(&water_column_todo), index / WATER_SPECTRUM_TILE);
+    if (band >= WATER_SPECTRUM_BANDS) { return; }
+    let x = index % WATER_SPECTRUM_TILE;
+    let rim = WATER_SPECTRUM_CONTENT / 2u;
+    if (lane < 2u) { atomicStore(&water_column_peaks[lane], 0u); }
+    if (lane < WATER_SPECTRUM_TILE) {
+        // z modes −32 … 31 are the content rows 0 … 63; the rest of the column is zero
+        var first = vec4<f32>(0.0);
+        var second = vec4<f32>(0.0);
+        if (lane < rim || lane >= WATER_SPECTRUM_TILE - rim) {
+            let row = select(lane + rim, lane - (WATER_SPECTRUM_TILE - rim), lane >= WATER_SPECTRUM_TILE - rim);
+            let cell = ((band * WATER_SPECTRUM_CONTENT + row) * WATER_SPECTRUM_TILE + x) * 2u;
+            first = rows[cell];
+            second = rows[cell + 1u];
+        }
+        let at = reverseBits(lane) >> 25u;
+        fft128x4_lines[at] = first.xy;
+        fft128x4_lines[128u + at] = first.zw;
+        fft128x4_lines[256u + at] = second.xy;
+        fft128x4_lines[384u + at] = second.zw;
+    }
+    fft128x4_inverse(lane);
+    var height = 0.0;
+    var horizontal = 0.0;
+    if (lane < WATER_SPECTRUM_TILE) {
+        let a = fft128x4_lines[lane];
+        let b = fft128x4_lines[128u + lane];
+        let c = fft128x4_lines[256u + lane];
+        let d = fft128x4_lines[384u + lane];
+        let coordinate = vec2<u32>(x, lane);
+        textureStore(displacement, coordinate, band, vec4<f32>(a.y, a.x, b.x, d.y));
+        textureStore(derivatives, coordinate, band, vec4<f32>(b.y, c.x, c.y, d.x));
+        height = abs(a.x);
+        horizontal = length(vec2<f32>(a.y, b.x));
+    }
+    // non-negative floats order as their bits do; subgroup operations stay in uniform control flow
+    let group_height = subgroupMax(height);
+    let group_horizontal = subgroupMax(horizontal);
+    if (subgroupElect()) {
+        atomicMax(&water_column_peaks[0], bitcast<u32>(group_height));
+        atomicMax(&water_column_peaks[1], bitcast<u32>(group_horizontal));
+    }
+    workgroupBarrier();
+    if (lane < 2u) { atomicMax(&band_state.envelope[2u * band + lane], atomicLoad(&water_column_peaks[lane])); }
+}
+`, [chunk_water_spectrum, chunk_fft128x4_inverse_workgroup, chunk_folded_workgroup_index, chunk_water_band_state]);
+columns_body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * Each column of every band in `band_state.todo` transformed along z, packed into the two band textures, and each
+ * band's largest |h| and |(Dx, Dz)| raised into its envelope (f32 bits, atomic max, never cleared): the largest the
+ * band has shown at any time evaluated. Bilinear sampling cannot leave the texel range, so a body's weighted sum of
+ * the envelopes bounds its displacement at every time evaluated.
+ *
+ * displacement = (Dx, h, Dz, ∂Dx/∂z), derivatives = (∂h/∂x, ∂h/∂z, ∂Dx/∂x, ∂Dz/∂z).
+ */
+export const shader_water_spectrum_columns = ComputeShader.from({ label: 'Water / spectrum columns', resources: columns_resources,
+    body: columns_body });

package/src/shade/wgsl/emulator/WGSLJavaScriptCompiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WGSLJavaScriptCompiler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLJavaScriptCompiler.js"],"names":[],"mappings":"AAkmBA;IAEI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,oBAFa,MAAM,CAMlB;CACJ;;UA9nBa,WAAW,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS;WAC/G,MAAM;WACN,MAAM;WACN,MAAM;WACN,MAAM;aACN,MAAM;cACN,QAAQ;YACR,MAAM"}
+{"version":3,"file":"WGSLJavaScriptCompiler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLJavaScriptCompiler.js"],"names":[],"mappings":"AAsmBA;IAEI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,oBAFa,MAAM,CAMlB;CACJ;;UAloBa,WAAW,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS;WAC/G,MAAM;WACN,MAAM;WACN,MAAM;WACN,MAAM;aACN,MAAM;cACN,QAAQ;YACR,MAAM"}

package/src/shade/wgsl/emulator/WGSLJavaScriptCompiler.js

@@ -302,6 +302,8 @@ function classifyType(ident, args, template_list_node) {
         // template arg 0 is the element type (sub-template), arg 1 is the count
         let element = T_UNKNOWN;
         let count = -1;
+        // a count named by a module constant is read from that constant when a value is made
+        let count_name = null;
         if (template_list_node !== null) {
             const comma_list = namedChildByType(template_list_node, 'template_arg_comma_list');
             if (comma_list !== null) {
@@ -312,12 +314,14 @@ function classifyType(ident, args, template_list_node) {
                     element = parseTypeSpecifier(inner_expr);
                 }
                 if (arg_nodes.length > 1) {
-                    const c = parseInt(arg_nodes[1].text.trim());
+                    const text = arg_nodes[1].text.trim();
+                    const c = parseInt(text);
                     if (!isNaN(c)) count = c;
+                    else if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(text)) count_name = text;
                 }
             }
         }
-        return { kind: 'array', element, count };
+        return count_name === null ? { kind: 'array', element, count } : { kind: 'array', element, count, count_name };
     }
     if (ident === 'atomic') {
         const inner = args.length > 0 ? args[0] : 'i32';
@@ -843,14 +847,16 @@ function defaultValueForType(type) {
         case 'mat':
             return `new Float32Array(${type.cols * type.rows})`;
         case 'array': {
-            if (type.count > 0) {
+            const length = type.count > 0 ? String(type.count)
+                : type.count_name !== undefined ? `Number(${identToJs(type.count_name)})` : null;
+            if (length !== null) {
                 if (type.element.kind === 'primitive') {
                     const ctor = arrayCtorForScalar(type.element.name);
-                    return `new ${ctor}(${type.count})`;
+                    return `new ${ctor}(${length})`;
                 }
                 // For non-primitive elements (vec / mat / struct / nested array) build the
                 // array eagerly so `out[i]` is a fresh, mutable element rather than `undefined`.
-                return `Array.from({ length: ${type.count} }, () => ${defaultValueForType(type.element)})`;
+                return `Array.from({ length: ${length} }, () => ${defaultValueForType(type.element)})`;
             }
             return '[]';
         }
@@ -2727,7 +2733,13 @@ function compileCallPhraseTyped(c, node) {
 
     // 6) array / array<T, N> constructor.
     if (callee_name === 'array') {
-        return { code: `[${stored_args.join(', ')}]`, type: T_UNKNOWN };
+        // The element type is what makes a member or swizzle on an element read compile; without
+        // a template, it is the first argument's, as WGSL infers it.
+        let type = parseTypeSpecifier(ident_node);
+        if ((type.kind !== 'array' || type.element === T_UNKNOWN) && arg_results.length > 0 && !isAbstractType(arg_results[0].type)) {
+            type = { kind: 'array', element: arg_results[0].type, count: arg_results.length };
+        }
+        return { code: `[${stored_args.join(', ')}]`, type };
     }
 
     // 7) Struct constructor.

package/src/shade/wgsl/emulator/WGSLLanguageCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":";IA8+CA;;;;;;;;;;;;;;OAcG;IACH,+DAmDC"}
+{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":";IAs/CA;;;;;;;;;;;;;;OAcG;IACH,+DAmDC"}