threejs-spectral-ocean ยท diff
git:20260713.f0e8d5c to git:20260716.2ce13bc
227 added, 1 removed. Audit C to A.
- ../../threejs-spectral-ocean/SKILL.md
+ ---
+ name: threejs-spectral-ocean
+ description: Synthesize broad-band offshore seas with spectral FFT cascades in Three.js WebGPU/TSL. Use for homogeneous directional wind sea or swell, or for offshore forcing of a separate coastal model.
+ ---
+
+ # Spectral Ocean
+
+ Build a dimensioned random sea from directional variance density to one
+ displaced, shaded surface. The spectral domain is a horizontally homogeneous
+ periodic patch with one mean depth and one dispersion relation per cascade.
+
+ ## 1. Gate the representation
+
+ Choose from the required observable, not the desired look:
+
+ | Observable | Owner |
+ | --- | --- |
+ | A few authored modes or exact cheap CPU queries | Parametric waves in `threejs-water-optics` |
+ | Bounded disturbances or explicit walls | Bounded heightfield in `threejs-water-optics` |
+ | Broad stochastic directional sea | This spectral FFT skill |
+ | Depth-varying refraction, diffraction, breaking, run-up, or wet/dry fronts | Coastal branch in `threejs-water-optics`; this skill may supply offshore forcing |
+ | Overturning, entrained air, jets, or three-dimensional vortices | External free-surface solver |
+
+ Select FFT cascades only when the visible wavelength band contains enough
+ independent modes that direct summation is more expensive or visibly
+ repetitive. Record the visible wavelength interval, footprint, tolerated
+ phase/slope error, periodic repeat distance, interaction needs, and measured
+ storage budget.
+
+ **Complete when:** one row owns every required water observable, and every
+ rejected row has a stated validity or cost reason.
+
+ ## 2. Freeze the spectral convention
+
+ Use metres, seconds, radians per metre, and radians per second. Declare:
+
+ - stable horizontal physics frame and water datum;
+ - patch length, resolution, `Delta k`, represented radial band, and guard band
+ for every cascade;
+ - inverse-transform sign, normalization, and centered-index correction;
+ - gravity, mean depth, surface tension, density, and uniform current;
+ - spectrum family, direction convention, seed, and cascade power windows;
+ - one coefficient/state clock and one render-surface owner.
+
+ The required inverse convention is
+
+ ```text
+ f[j] = sum_n F[n] exp(+i 2 pi n dot j / N).
+ ```
+
+ If the implementation uses a normalized inverse, rescale coefficient
+ initialization rather than tuning the sea afterward. Current is a separate
+ water velocity and Doppler term; atmospheric wind never becomes water current.
+
+ For wind sea, record the sampled wind vector, reference height, averaging
+ window and footprint, profile/drag calibration, stability treatment, fetch,
+ forcing duration or wave age, spreading model, and represented source terms.
+ Retarget a statistical state continuously; gusts may affect spray but do not
+ reseed mature waves.
+
+ Load only the reference sections for
+ [environment forcing](references/spectral-cascade-ocean-system.md#environment-forcing),
+ [wavevector and transform convention](references/spectral-cascade-ocean-system.md#wavevector-and-transform-convention),
+ and [dispersion and dimensional spectrum](references/spectral-cascade-ocean-system.md#dispersion-and-dimensional-spectrum)
+ while freezing this contract.
+
+ **Complete when:** every coefficient and clock has unambiguous units, the same
+ transform convention appears in initialization and validation, and replaying
+ one forcing snapshot reproduces the same coefficients and phase.
+
+ ## 3. Build deterministic cascades
+
+ Load the reference sections for
+ [cascade power and deterministic coefficients](references/spectral-cascade-ocean-system.md#cascade-power-and-deterministic-coefficients),
+ [displacement and derivative spectra](references/spectral-cascade-ocean-system.md#displacement-and-derivative-spectra),
+ [packing and inverse FFT](references/spectral-cascade-ocean-system.md#packing-and-inverse-fft),
+ and the [transform gate](references/spectral-cascade-ocean-system.md#transform-gate).
+
+ For directional angular-frequency variance density `S_omega`,
+
+ ```text
+ P(k_x,k_z) = S_omega(omega(k),theta) |d omega/dk| / |k|,
+ [P] = m^4.
+ ```
+
+ Include `Delta k_x Delta k_z` in discrete coefficient variance. Power windows
+ obey `sum_c w_c(k)=1` over the represented band; smooth overlap uses
+ `sqrt(w_c)` on amplitude. Generate normals from
+ `(seed,cascade,index_x,index_z)` so masks and quality changes do not perturb
+ surviving coefficients.
+
+ Evolve a Hermitian height field, construct derivatives in wavevector space,
+ then transform height, horizontal displacement, slopes, and displacement
+ derivatives. Treat DC and self-conjugate Nyquist cells explicitly before any
+ division.
+
+ **Complete when:** directional normalization, power-window sum, target versus
+ realized variance, coefficient determinism, Hermitian partner error, DC, both
+ axis bins, an oblique bin, a conjugate pair, every Nyquist parity case, CPU-DFT
+ error, Parseval error, and post-IFFT imaginary leakage all pass declared
+ gates.
+
+ ## 4. Assemble one exact surface
+
+ Load only [exact displaced geometry](references/spectral-cascade-ocean-system.md#exact-displaced-geometry)
+ for the composite tangent, velocity, sampling, and fold rules.
+
+ Sum all cascade fields before nonlinear geometry. For
+
+ ```text
+ P(q) = (q_x + chi D_x, h, q_z + chi D_z),
+ ```
+
+ derive both parametric tangents from the summed displacement and set the normal
+ to `normalize(cross(P_qz,P_qx))`. Compute the full horizontal Jacobian,
+ including the mixed derivative. A nonpositive determinant is a fold, not a
+ normal-map defect.
+
+ Choose the sign of `chi` with the one-mode criterion: under the positive
+ inverse convention, `h=a cos(kx)` and positive choppiness must produce
+ `X=x-chi a sin(kx)`, compressing the crest.
+
+ Geometry must resolve the represented displacement band. Filter or omit modes
+ that its footprint cannot resolve, and report their height/slope contribution.
+ One mesh/material owns every displayed location.
+
+ **Complete when:** the one-mode travel and displacement signs are correct;
+ analytic tangents and normals match finite differences; combined variance and
+ minimum Jacobian are measured; folds are counted; and position, normal,
+ velocity, foam, and temporal consumers read the same immutable state pair.
+
+ ## 5. Add only represented optional state
+
+ ### Foam
+
+ When foam is enabled, load only the
+ [foam](references/spectral-cascade-ocean-system.md#foam) section.
+
+ Build one source from combined-cascade compression, Jacobian evolution,
+ curvature, or a calibrated breaking proxy, then evolve one bounded history.
+ Declare Lagrangian parameter storage, Eulerian advection, or conservative
+ density transport. Source, transport, reaction, diffusion, and display
+ coverage remain separately inspectable.
+
+ ### Queries
+
+ When CPU queries are enabled, load only the
+ [CPU queries](references/spectral-cascade-ocean-system.md#cpu-queries) section.
+
+ Retain a deterministic coefficient subset on CPU. Expose parameter-coordinate
+ sampling separately from physics-horizontal sampling. Choppy Eulerian queries
+ invert `X(q)=x`; the omitted-mode bound, inversion residual, numeric error, and
+ GPU probe discrepancy stay separate. The frame path performs no synchronous
+ map readback.
+
+ ### Optics
+
+ When `$threejs-water-optics` is installed and available, invoke it for Fresnel,
+ refraction, Beer-Lambert, and receiver-caustic rules. Surface geometry,
+ derivatives, foam, and optics then share one cause and one final output
+ transform. When it is unavailable, report `missing optics owner` and keep
+ optics outside this implementation and its claims.
+
+ **Complete when:** each enabled option has an owner, validity interval,
+ support/filter, reset rule, and failure diagnostic; disabled options allocate
+ no state and make no claim.
+
+ ## 6. Couple a coast only when required
+
+ When the sea feeds a depth-varying or wet/dry owner, load only the
+ [coastal donor](references/spectral-cascade-ocean-system.md#coastal-donor)
+ section and its phase-resolved, phase-averaged, and ownership subsections.
+ Before either solver runs, record the spectral donor, coastal consumer, and
+ forcing, reaction, render-surface, and foam owners; SI units; common physics
+ frame/origin and water datum; clock, sample instant or transfer interval,
+ cadence, and sample phase; band support, filter, and quadrature; validity,
+ staleness, and error; and donor/receiver state and resource versions. Keep
+ atmospheric forcing, mean current, wave transfer, and coastal reaction as
+ separate signals. Reset dependent boundary, query, foam, geometry, and temporal
+ state after a clock discontinuity, rebase, incompatible version,
+ representation change, or ownership change. Invoke `$threejs-choose-skills` if
+ the composed route still lacks one owner per observable.
+
+ Choose exactly one:
+
+ - **Phase resolved:** transfer elevation and depth-integrated discharge with
+ common phase, intrinsic frequency, sample instant, band identity, and error.
+ Prescribe only the incoming characteristic; retain the coastal outgoing one.
+ - **Phase averaged:** transfer dimensioned wave action/energy, intrinsic
+ frequency, group velocity, current, direction, quadrature, and band identity.
+ The receiver separately owns local display phase.
+
+ The FFT remains the offshore donor. It does not gain refraction, diffraction,
+ breaking, run-up, or wet/dry ownership by sampling bathymetry in its material.
+ Coherent donor/receiver copies use one spatial render owner; power windows apply
+ only to independent or orthogonal bands.
+
+ **Complete when:** producer, consumer, interval, sample phase, units, support,
+ filter, validity, staleness, error, state versions, reflection scope, and
+ render/foam ownership are explicit; single-mode normal and oblique tests close
+ phase, elevation, discharge or action, transmitted power, and reflection.
+
+ ## 7. Integrate and verify the GPU path
+
+ Load only [WebGPU and performance](references/spectral-cascade-ocean-system.md#webgpu-and-performance)
+ for backend, resource, dispatch, precision, and lifecycle requirements.
+
+ Initialize `WebGPURenderer` before checking its backend or limits. Use
+ `StorageTexture` data with `NoColorSpace` and explicit precision. A global
+ producer/consumer dependency crosses a dispatch boundary. Select global
+ Stockham or workgroup-resident rows from transform correctness, initialized
+ device limits, occupancy, traffic, and sustained timing.
+
+ Render through one `RenderPipeline` and one output transform. Keep coefficient,
+ resolved-map, foam, query, and presentation generations immutable while a
+ render lease consumes them; resize, seed, spectrum, cadence, representation, or
+ origin changes either migrate compatible state or reset all dependent history.
+
+ Report actual allocations, peak live bytes, dispatches, precision comparison,
+ warm sustained timings, and fixed-camera final/no-foam/no-detail/no-post
+ captures for each named target.
+
+ **Complete when:** the initialized backend and selected limits are recorded;
+ all numerical gates above pass; no frame-critical readback exists; lifecycle
+ rebuild/dispose reaches an allocation plateau; and the final image has one
+ surface owner and one output transform.
+