vulkan_ocean.cpp

// Vulkan deferred ocean demo — FFT-displaced water, ray-traced reflections and refraction, LIDAR and radar.

#include "threepp/audio/Audio.hpp"
#include "threepp/audio/WavFile.hpp"
#include "threepp/extras/curves/CatmullRomCurve3.hpp"
#include "threepp/extras/imgui/RendererSettings.hpp"
#include "threepp/extras/terrain/DetailTexture.hpp"
#include "threepp/geometries/PlaneGeometry.hpp"
#include "threepp/helpers/LidarWaveform.hpp"
#include "threepp/helpers/PathTracedLidarSensor.hpp"
#include "threepp/input/KeyListener.hpp"
#include "threepp/lights/AmbientLight.hpp"
#include "threepp/lights/DirectionalLight.hpp"
#include "threepp/geometries/LatheGeometry.hpp"
#include "threepp/geometries/TorusGeometry.hpp"
#include "threepp/loaders/GLTFLoader.hpp"
#include "threepp/loaders/RGBELoader.hpp"
#include "threepp/utils/BufferGeometryUtils.hpp"
#include "threepp/utils/Parallel.hpp"
#include "threepp/materials/MeshPhysicalMaterial.hpp"
#include "threepp/materials/MeshStandardMaterial.hpp"
#include "threepp/math/Box3.hpp"
#include "threepp/math/Matrix3.hpp"
#include "threepp/math/Matrix4.hpp"
#include "threepp/objects/DisplacedMesh.hpp"
#include "threepp/objects/Ocean.hpp"
#include "threepp/renderers/VulkanRenderer.hpp"
#include "threepp/textures/DataTexture.hpp"
#include "threepp/threepp.hpp"

#include "capture_util.hpp"

#include <algorithm>
#include <cmath>
#include <cstdint>
#include <cstdlib>
#include <cstring>
#include <filesystem>
#include <iostream>
#include <memory>
#include <numeric>
#include <random>
#include <unordered_map>
#include <vector>

using namespace threepp;

namespace {

    struct BoatInput : KeyListener {
        bool W = false, A = false, S = false, D = false;
        bool shotRequest = false;// F12: dump the next frame to aaa_caps/ (artifact reports)
        void onKeyPressed(KeyEvent e) override {
            if (e.key == Key::F12) shotRequest = true;
            update(e.key, true);
        }
        void onKeyReleased(KeyEvent e) override { update(e.key, false); }
        void update(Key k, bool down) {
            if (k == Key::W || k == Key::UP)    W = down;
            if (k == Key::S || k == Key::DOWN)  S = down;
            if (k == Key::A || k == Key::LEFT)  A = down;
            if (k == Key::D || k == Key::RIGHT) D = down;
        }
    };

    // 3-DOF maneuvering model (surge/sway/yaw) + wave-driven heave/pitch/roll.
    struct BoatState {
        Vector3 position{0.f, 0.f, 0.f};
        float   yaw          = 0.f;       // heading, radians
        float   yawRate      = 0.f;       // rad/s
        float   forwardSpeed = 0.f;       // surge, m/s
        float   swaySpeed    = 0.f;       // sway, m/s
        float   rudder       = 0.f;       // radians
        float   throttle     = 0.f;       // ∈ [−1, 1]
        bool    aground      = false;
        float   smoothPitch  = 0.f;       // radians, low-passed
        float   smoothRoll   = 0.f;       // radians, low-passed
        float   y            = 0.f;       // heave, metres
        float   vY           = 0.f;       // heave velocity, m/s
    };
    constexpr float kTileSize    = 1000.0f;  // metres
    // FFT res drives wave detail; mesh density is independent (sampled via normalised UVs).
    constexpr uint32_t kFftSize  = 1024;
    constexpr float kPlaneEdge   = kTileSize;
    constexpr uint32_t kOceanRes = kFftSize / 2;  // 512 verts/side ≈ 2 m spacing over 1 km tile

    auto makeSandMaterial() {
        return MeshStandardMaterial::create(MeshStandardMaterial::Params{}.color(Color(0.02,0.02,0.02)).roughness(1.0f));
    }

}// namespace

// Procedural archipelago ring (r 385–495 m): value-noise FBM height field with
// baked albedo + roughness maps. Sub-metre rock relief no longer lives in a
// unique baked normal map — it is carried by the framework's world-XZ-anchored
// tiled detail layer (MaterialWithDetailMap + terrain::makeDetailMaps), which
// the Vulkan deferred G-buffer renders with stochastic tiling, distance fade
// and gated triplanar on steep faces. The vertex grid + analytic normals still
// carry everything ≥ ~0.6 m.
namespace island {

    constexpr float kInnerR = 385.f;// boat waypoints reach ~320 m — keep clear water
    constexpr float kOuterR = 495.f;// stays inside the 1 km ocean/sand tile
    constexpr float kPeakH  = 55.f; // tallest summits (m)
    constexpr float kSkirt  = 7.f;  // rim depth — below the sand floor (-5 m)


    float hashf(int xi, int zi) {
        uint32_t h = static_cast<uint32_t>(xi) * 374761393u + static_cast<uint32_t>(zi) * 668265263u;
        h = (h ^ (h >> 13)) * 1274126177u;
        h ^= h >> 16;
        return static_cast<float>(h) * (1.f / 4294967296.f);
    }

    // Value noise with quintic fade, range [0,1].
    float vnoise(float x, float z) {
        const float fx = std::floor(x), fz = std::floor(z);
        const int xi = static_cast<int>(fx), zi = static_cast<int>(fz);
        float tx = x - fx, tz = z - fz;
        tx = tx * tx * tx * (tx * (tx * 6.f - 15.f) + 10.f);
        tz = tz * tz * tz * (tz * (tz * 6.f - 15.f) + 10.f);
        const float a = hashf(xi, zi), b = hashf(xi + 1, zi);
        const float c = hashf(xi, zi + 1), d = hashf(xi + 1, zi + 1);
        return a + (b - a) * tx + (c - a) * tz + (a - b - c + d) * tx * tz;
    }

    float fbm(float x, float z, int octaves) {
        float sum = 0.f, amp = 0.5f, norm = 0.f;
        for (int o = 0; o < octaves; ++o) {
            sum += amp * vnoise(x, z);
            norm += amp;
            amp *= 0.5f;
            // irrational-ish lacunarity + offset decorrelates the octave lattices
            const float nx = x * 1.93f + 19.7f, nz = z * 2.11f + 7.3f;
            x = nx;
            z = nz;
        }
        return sum / norm;
    }

    float heightAt(float x, float z) {
        const float r = std::sqrt(x * x + z * z);
        // ring coordinate, warped so the coastlines wander instead of circling
        float w = (r - kInnerR) / (kOuterR - kInnerR);
        w += 0.20f * (2.f * fbm(x * 0.011f, z * 0.011f, 2) - 1.f);
        if (w <= 0.f || w >= 1.f) return -kSkirt;
        const float prof = std::pow(std::sin(math::PI * w), 1.5f);

        // mass plan: low-frequency noise on a circle, thresholded — sections
        // below the band stay a submerged sill (the passes between islands)
        const float a = std::atan2(z, x);
        const float m0 = 0.65f * vnoise(7.3f + std::cos(a) * 2.9f, 3.1f + std::sin(a) * 2.9f) +
                         0.35f * vnoise(13.7f + std::cos(a) * 5.3f, 23.9f + std::sin(a) * 5.3f);
        const float m = math::smoothstep(0.27f, 0.60f, m0);

        // ridged FBM (fold-over of signed noise) = sharp rocky crests
        const float ridge = 1.f - std::abs(2.f * fbm(x * 0.035f, z * 0.035f, 4) - 1.f);
        // meso relief: layered creased-slab ridges carried as REAL geometry by
        // the dense vertex grid — λ ≈ 11 m slabs, ≈ 4 m ledges, and sub-metre
        // bumps (≈ 1.8 m and ≈ 0.9 m). Amplitudes are absolute (a ledge is a
        // ledge, independent of the mountain's height) and stay gentler than
        // their own wavelength. Scaled by the mass plan so the submerged passes
        // stay smooth sills; the normal map now carries only the truly
        // sub-vertex scales (≤ ~0.6 m).
        const float slab    = 1.f - std::abs(2.f * fbm(x * 0.09f, z * 0.09f, 3) - 1.f);
        const float slabFn  = 1.f - std::abs(2.f * fbm(x * 0.24f, z * 0.24f, 3) - 1.f);
        const float bump    = fbm(x * 0.55f + 41.f, z * 0.55f + 17.f, 2);
        const float grainHi = fbm(x * 1.15f + 7.f, z * 1.15f + 91.f, 2);
        const float meso = 3.5f * (slab * slab - 0.45f)
                         + 1.8f * (slabFn * slabFn - 0.45f)
                         + 0.7f * (bump - 0.5f)
                         + 0.35f * (grainHi - 0.5f);
        const float crest = (kPeakH * (0.45f + 0.55f * ridge * ridge) + meso) * m;
        // prof=1 mid-ring: passes top out 2 m underwater, islands rise to crest
        return -kSkirt + (crest + kSkirt - 2.f) * prof;
    }

    // Analytic finite-difference normal — seam-consistent (the height field is
    // continuous in angle) and adds sub-vertex shading detail for free. The
    // 0.6 m radius matches the denser ~0.4 m vertex grid so the sub-metre
    // relief shades correctly instead of being averaged away.
    Vector3 normalAt(float x, float z, float eps = 0.6f) {
        const float dhdx = (heightAt(x + eps, z) - heightAt(x - eps, z)) / (2.f * eps);
        const float dhdz = (heightAt(x, z + eps) - heightAt(x, z - eps)) / (2.f * eps);
        Vector3 n(-dhdx, 1.f, -dhdz);
        return n.normalize();
    }

    struct BakedMaps {
        std::shared_ptr<DataTexture> albedo;
        std::shared_ptr<DataTexture> rough;
    };

    // Bake albedo + roughness in polar UV (u = angle, v = radius); rows run in
    // parallel. The normal map is gone — cm-scale rock relief is now the
    // framework detail layer (see build()).
    BakedMaps bakeMaps() {
        const int W = 10240, H = 512;
        std::vector<unsigned char> albPx(static_cast<size_t>(W) * H * 4);
        std::vector<unsigned char> rghPx(static_cast<size_t>(W) * H * 4);
        auto toByte = [](float v) {
            return static_cast<unsigned char>(std::lround(std::clamp(v, 0.f, 1.f) * 255.f));
        };

        std::vector<int> rows(H);
        std::iota(rows.begin(), rows.end(), 0);
        threepp::parallelForEach(rows.begin(), rows.end(), [&](int y) {
            const float r = kInnerR + (kOuterR - kInnerR) * ((y + 0.5f) / H);
            for (int x = 0; x < W; ++x) {
                const float a = 2.f * math::PI * ((x + 0.5f) / W);
                const float ca = std::cos(a), sa = std::sin(a);
                const float wx = ca * r, wz = sa * r;

                const float eps = 2.5f;
                const float h   = heightAt(wx, wz);
                const float hxp = heightAt(wx + eps, wz), hxm = heightAt(wx - eps, wz);
                const float hzp = heightAt(wx, wz + eps), hzm = heightAt(wx, wz - eps);
                const float dhdx = (hxp - hxm) / (2.f * eps);
                const float dhdz = (hzp - hzm) / (2.f * eps);
                const float ny   = 1.f / std::sqrt(1.f + dhdx * dhdx + dhdz * dhdz);
                const float lap  = (hxp + hxm + hzp + hzm - 4.f * h) / (eps * eps);
                // convexity: exposed crests bleach, concave seams collect dirt
                const float crest = std::clamp(-lap * 0.8f, -1.f, 1.f);

                const float tone   = fbm(wx * 0.0045f, wz * 0.0045f, 2); // per-face rock tone, λ ≈ 220 m
                const float mottle = fbm(wx * 0.05f, wz * 0.05f, 3);     // λ ≈ 20 m
                const float grain  = fbm(wx * 0.7f + 5.f, wz * 0.7f + 13.f, 2);// λ ≈ 1.4 m
                const float micro  = fbm(wx * 1.6f + 211.f, wz * 1.6f + 97.f, 2);// λ ≈ 0.6 m
                const float vegL   = fbm(wx * 0.013f + 31.f, wz * 0.013f, 3);  // veg patches, λ ≈ 75 m
                const float vegS   = fbm(wx * 0.11f + 7.f, wz * 0.11f + 3.f, 2);// ragged veg edges, λ ≈ 9 m
                const float warp   = fbm(wx * 0.03f + 71.f, wz * 0.03f + 11.f, 2);

                // two-tone base: pale weathered granite vs darker gneiss,
                // blended at island scale so each face reads as its own mass
                const float t = math::smoothstep(0.35f, 0.65f, tone);
                float cr = 0.26f + 0.20f * t;
                float cg = 0.245f + 0.195f * t;
                float cb = 0.235f + 0.175f * t;
                const float speck = (mottle - 0.5f) * 0.14f + (grain - 0.5f) * 0.09f
                                  + (micro - 0.5f) * 0.05f;
                cr += speck;
                cg += speck;
                cb += speck * 0.9f;
                // wandering sub-horizontal strata bands on steep faces
                const float strata = 1.f + 0.09f * std::sin(h * 0.75f + 6.f * warp) *
                                                 math::smoothstep(0.85f, 0.55f, ny);
                // crest/hollow shading from the Laplacian
                const float cav = 1.f + 0.14f * crest;
                cr *= strata * cav;
                cg *= strata * cav;
                cb *= strata * cav;

                // scree aprons: gentle low benches at the cliff feet collect debris
                const float scree = math::smoothstep(0.60f, 0.78f, ny) * math::smoothstep(1.2f, 2.6f, h) *
                                    (1.f - math::smoothstep(5.f, 13.f, h)) *
                                    math::smoothstep(0.35f, 0.65f, vegS) * 0.55f;
                cr += (0.41f - cr) * scree;
                cg += (0.375f - cg) * scree;
                cb += (0.315f - cb) * scree;

                // heather/shrub on mid slopes, its own patch noise
                const float hePatch = fbm(wx * 0.019f + 57.f, wz * 0.019f + 91.f, 2);
                const float heather = math::smoothstep(0.45f, 0.62f, ny) * math::smoothstep(1.5f, 3.5f, h) *
                                      (1.f - math::smoothstep(22.f, 34.f, h)) *
                                      math::smoothstep(0.45f, 0.62f, hePatch);
                cr += (0.205f + 0.05f * hePatch - cr) * heather;
                cg += (0.17f + 0.05f * hePatch - cg) * heather;
                cb += (0.105f - cb) * heather;

                // grass/moss on flat low benches; hollows accumulate soil, so
                // the Laplacian feeds the patch threshold
                const float gPatch = 0.55f * vegL + 0.30f * vegS +
                                     0.15f * std::clamp(lap * 1.5f, 0.f, 1.f);
                const float grass = math::smoothstep(0.60f, 0.80f, ny) * math::smoothstep(0.8f, 2.6f, h) *
                                    (1.f - math::smoothstep(24.f, 38.f, h)) *
                                    math::smoothstep(0.42f, 0.58f, gPatch);
                cr += (0.13f + 0.07f * vegS - cr) * grass;
                cg += (0.27f + 0.08f * vegL - cg) * grass;
                cb += (0.085f - cb) * grass;

                // pale lichen crusts on exposed high rock
                const float lich = math::smoothstep(8.f, 20.f, h) *
                                   math::smoothstep(0.55f, 0.75f, fbm(wx * 0.15f + 13.f, wz * 0.15f + 29.f, 2)) *
                                   std::clamp(0.5f + 0.5f * crest, 0.f, 1.f) * 0.30f;
                cr += (0.50f - cr) * lich;
                cg += (0.51f - cg) * lich;
                cb += (0.46f - cb) * lich;
                // summits bleach toward bare washed rock
                const float alt = 1.f + 0.08f * math::smoothstep(28.f, 52.f, h);
                cr *= alt;
                cg *= alt;
                cb *= alt;

                // Conifer forest — the signature cover of these slopes. Climbs
                // steep ground (unlike grass) but sheds off sheer cliff faces;
                // a coarse stand field + a ragged canopy-edge noise carve
                // clearings and break the treeline so it never reads as a
                // contour line. Deep blue-green, varied stand to stand.
                const float forestStand = fbm(wx * 0.020f + 13.f, wz * 0.020f + 47.f, 3);// λ ≈ 50 m
                const float forestEdge  = fbm(wx * 0.13f + 61.f, wz * 0.13f + 29.f, 2);  // λ ≈ 8 m
                const float forest = math::smoothstep(0.40f, 0.58f, ny) *
                                     math::smoothstep(1.5f, 4.0f, h) *
                                     (1.f - math::smoothstep(26.f, 36.f, h)) *
                                     math::smoothstep(0.34f, 0.52f, 0.6f * forestStand + 0.4f * forestEdge);
                cr += (0.045f + 0.030f * forestStand - cr) * forest;
                cg += (0.135f + 0.060f * forestStand - cg) * forest;
                cb += (0.050f + 0.020f * forestStand - cb) * forest;

                // Snow — settles on low-angle ground above the snowline and
                // pools in the concave couloirs (lap > 0) well below it, while
                // shedding off anything approaching vertical. Faint cool tint
                // on the ambient-shadowed fields; a patch field keeps the
                // upper edge ragged instead of a hard ring. At this 55 m skerry
                // scale snow reads as summit caps + gully streaks, not full
                // alpine cover — matching a low Norwegian coastal massif.
                const float snowPatch = fbm(wx * 0.05f + 91.f, wz * 0.05f + 5.f, 2);
                const float snowSlope = math::smoothstep(0.42f, 0.72f, ny);
                const float snowfield = math::smoothstep(26.f, 42.f, h);
                const float couloir   = std::clamp(lap * 1.4f, 0.f, 1.f) * math::smoothstep(16.f, 28.f, h);
                float snow = snowSlope * std::clamp(std::max(snowfield, couloir), 0.f, 1.f);
                snow *= 0.6f + 0.4f * math::smoothstep(0.35f, 0.65f, snowPatch);
                cr += (0.92f - cr) * snow;
                cg += (0.94f - cg) * snow;
                cb += (0.98f - cb) * snow;

                // algae film straddling the waterline, then the dark wet band
                const float algae = (1.f - math::smoothstep(0.6f, 1.4f, std::abs(h - 0.3f))) * 0.5f;
                cr += (0.10f - cr) * algae;
                cg += (0.15f - cg) * algae;
                cb += (0.10f - cb) * algae;
                const float wet = (1.f - math::smoothstep(0.4f, 2.2f, h)) * 0.85f;
                cr += (0.095f - cr) * wet;
                cg += (0.095f - cg) * wet;
                cb += (0.09f - cb) * wet;

                // Snowmelt waterfalls — sparse thin ribbons down the steep
                // faces. A slow azimuthal selector picks a few fall-lines and
                // a high-frequency stripe makes each one narrow; both depend
                // only on the angle, so a ribbon runs unbroken down the face
                // as the radius row changes. Gated to steep rock between the
                // splash zone and the snow source above. Bright and slightly
                // blue; the glossy wet sheen is added in the roughness block.
                const float fallRegion = math::smoothstep(0.60f, 0.82f, fbm(a * 2.5f + 11.f, 4.0f, 2));
                const float fallStripe = std::pow(std::max(0.f, std::sin(a * 48.f + 6.f * fbm(a * 9.f, 2.f, 2))), 60.f);
                const float fall = fallRegion * fallStripe *
                                   math::smoothstep(0.30f, 0.55f, 1.f - ny) *
                                   math::smoothstep(4.f, 9.f, h) *
                                   (1.f - math::smoothstep(34.f, 44.f, h));
                cr += (0.82f - cr) * fall;
                cg += (0.86f - cg) * fall;
                cb += (0.92f - cb) * fall;

                // roughness (.g multiplies material roughness): matte dry
                // granite, matte vegetation, matte conifer canopy, water-
                // slicked rock turns glossy, bright soft snow, glossy falls
                float rough = 0.86f + 0.10f * (mottle - 0.5f) - 0.06f * crest;
                rough += (0.95f - rough) * std::max(grass, heather);
                rough += (0.93f - rough) * forest;
                rough += (0.45f - rough) * wet;
                rough += (0.62f - rough) * snow;
                rough += (0.38f - rough) * fall;

                const size_t i = (static_cast<size_t>(y) * W + x) * 4;
                albPx[i + 0] = toByte(cr);
                albPx[i + 1] = toByte(cg);
                albPx[i + 2] = toByte(cb);
                albPx[i + 3] = 255;
                rghPx[i + 0] = 255;
                rghPx[i + 1] = toByte(rough);
                rghPx[i + 2] = 0;
                rghPx[i + 3] = 255;
            }
        });

        auto makeTex = [&](std::vector<unsigned char>&& px, bool srgb) {
            auto tex = DataTexture::create(ImageData{std::move(px)},
                                           static_cast<unsigned>(W), static_cast<unsigned>(H));
            if (srgb) tex->colorSpace = ColorSpace::sRGB;// normal/rough stay raw UNORM
            tex->magFilter = Filter::Linear;
            tex->minFilter = Filter::LinearMipmapLinear;
            tex->generateMipmaps = true;
            tex->needsUpdate();
            return tex;
        };
        return {makeTex(std::move(albPx), true),
                makeTex(std::move(rghPx), false)};
    }

    std::shared_ptr<Mesh> build() {
        // 8192 angular × 256 radial (≈0.34/0.43 m spacing); seam column duplicated for clean UVs.
        const int NA = 8192, NR = 256;
        std::vector<float> pos(static_cast<size_t>(NA + 1) * (NR + 1) * 3);
        std::vector<float> nrm(static_cast<size_t>(NA + 1) * (NR + 1) * 3);
        std::vector<float> uv(static_cast<size_t>(NA + 1) * (NR + 1) * 2);
        std::vector<int> rows(NR + 1);
        std::iota(rows.begin(), rows.end(), 0);
        threepp::parallelForEach(rows.begin(), rows.end(), [&](int j) {
            const float r = kInnerR + (kOuterR - kInnerR) * (static_cast<float>(j) / NR);
            for (int i = 0; i <= NA; ++i) {
                const float a = 2.f * math::PI * (static_cast<float>(i) / NA);
                const float x = std::cos(a) * r, z = std::sin(a) * r;
                const Vector3 n = normalAt(x, z);
                const size_t v = static_cast<size_t>(j) * (NA + 1) + i;
                pos[v * 3 + 0] = x;
                pos[v * 3 + 1] = heightAt(x, z);
                pos[v * 3 + 2] = z;
                nrm[v * 3 + 0] = n.x;
                nrm[v * 3 + 1] = n.y;
                nrm[v * 3 + 2] = n.z;
                uv[v * 2 + 0] = static_cast<float>(i) / NA;
                uv[v * 2 + 1] = static_cast<float>(j) / NR;
            }
        });
        std::vector<unsigned int> idx;
        idx.reserve(static_cast<size_t>(NA) * NR * 6);
        for (int j = 0; j < NR; ++j)
            for (int i = 0; i < NA; ++i) {
                const unsigned a0 = j * (NA + 1) + i;// (i, j)
                const unsigned b0 = a0 + 1;          // (i+1, j)
                const unsigned a1 = a0 + (NA + 1);   // (i, j+1)
                const unsigned b1 = a1 + 1;          // (i+1, j+1)
                idx.insert(idx.end(), {a0, b0, b1});
                idx.insert(idx.end(), {a0, b1, a1});
            }

        auto geo = BufferGeometry::create();
        geo->setIndex(idx);
        geo->setAttribute("position", FloatBufferAttribute::create(pos, 3));
        geo->setAttribute("normal", FloatBufferAttribute::create(nrm, 3));
        geo->setAttribute("uv", FloatBufferAttribute::create(uv, 2));
        geo->computeBoundingBox();
        geo->computeBoundingSphere();

        auto mat = MeshStandardMaterial::create(MeshStandardMaterial::Params{}
                                                        .roughness(1.f)// baked map carries the variation
                                                        .metalness(0.f));
        const BakedMaps maps = bakeMaps();
        mat->map          = maps.albedo;
        mat->roughnessMap = maps.rough;

        // Sub-metre granite relief: the framework's world-XZ-anchored tiled
        // detail layer replaces the old unique baked normal map. One shared
        // heightfield feeds a coherent detail albedo + tangent-normal/roughness
        // pair; the Vulkan deferred G-buffer tiles it stochastically, fades it
        // with distance (no far shimmer) and switches to triplanar on the ring's
        // steep faces so cliffs get unstretched grain automatically. Tuned to
        // the old bake's creased-slab + grain granite character: a ~1.7 m repeat
        // carries the slab/ledge scale, normalStrength the craggy relief.
        // Note vs the old bake: this layer is UNIFORM — it lacks the bespoke
        // per-texel canopy/snow damping that softened micro-relief under
        // vegetation and snow. detailNormalScale is trimmed slightly to keep
        // forested/snow patches from reading over-crisp.
        {
            terrain::DetailMapOptions dopt;
            dopt.dim = 256;
            dopt.seed = 1717u;
            dopt.albedoContrast = 0.34f;
            dopt.chroma = 0.05f;
            dopt.normalStrength = 2.4f;// craggier than the terrain default — bare granite
            dopt.roughContrast = 0.5f;
            const terrain::DetailMaps dm = terrain::makeDetailMaps(dopt);
            mat->detailMap          = dm.albedo;
            mat->detailNormalMap    = dm.normalRough;
            mat->detailRepeat       = 0.6f;// one repeat per ≈1.67 m (slab/ledge scale)
            mat->detailStrength     = 0.35f;// gentle albedo breakup; the bake carries the colour
            mat->detailNormalScale  = 0.85f;// trimmed: no per-texel veg/snow damp anymore
            mat->detailRoughStrength = 0.5f;
        }
        auto mesh = Mesh::create(geo, mat);
        mesh->frustumCulled = false;// the ring surrounds the camera — always partly in view
        return mesh;
    }

}// namespace island

// Procedural audio: engine + ocean/wind ambience synthesised to temp WAV, seamlessly looped.
// Seamless loops: periodic terms wrap naturally; a tail crossfade blends filter state at the seam.
namespace {

    struct OnePole {
        float y = 0.f;
        float operator()(float x, float a) {
            y += a * (x - y);
            return y;
        }
    };
    float lpAlpha(float cutoffHz, int sr) {
        return 1.f - std::exp(-2.f * math::PI * cutoffHz / static_cast<float>(sr));
    }

    std::vector<float> normalized(std::vector<float> s, float peak) {
        float m = 0.f;
        for (float x : s) m = std::max(m, std::abs(x));
        if (m > 1e-6f)
            for (float& x : s) x *= peak / m;
        return s;
    }

    // Fold the `extra`-sample overhang back onto the head (linear crossfade).
    // out[0] == s[n] so the n-1 → 0 junction is the continuation of the tail;
    // by i == extra the signal is back on the head verbatim.
    std::vector<float> loopable(const std::vector<float>& s, int n, int extra) {
        std::vector<float> out(s.begin(), s.begin() + n);
        for (int i = 0; i < extra; ++i) {
            const float w = static_cast<float>(i) / static_cast<float>(extra);
            out[i] = s[n + i] * (1.f - w) + s[i] * w;
        }
        return out;
    }


    // Marine diesel at mid RPM, 2 s loop. Firing rate f0 = 27 Hz (54 exact
    // cycles): harmonic stack for the tonal drone, a |sin|³ "chug" envelope
    // gating low-passed exhaust noise, and a faint band-passed mechanical
    // clatter. Played at rate 0.7 (idle) … 1.6 (full ahead) by the updater.
    std::vector<float> synthEngineLoop(int sr = 44100) {
        const float dur = 2.0f;
        const int n     = static_cast<int>(sr * dur);
        const int extra = sr / 4;
        std::mt19937 r(7);
        auto rn = [&] { return std::uniform_real_distribution<float>(-1.f, 1.f)(r); };
        const float f0 = 27.f;
        OnePole lpExhaust, lpClatHi, lpClatLo;
        const float aExhaust = lpAlpha(170.f, sr);
        const float aClatHi  = lpAlpha(1300.f, sr);
        const float aClatLo  = lpAlpha(450.f, sr);
        std::vector<float> s(n + extra);
        for (int i = 0; i < n + extra; ++i) {
            const float t    = static_cast<float>(i) / sr;
            const float chug = std::pow(0.55f + 0.45f * std::abs(std::sin(math::PI * f0 * t)), 3.f);
            float tone = 0.f;
            tone += std::sin(2.f * math::PI * f0 * t) * 0.55f;
            tone += std::sin(2.f * math::PI * 2.f * f0 * t) * 0.30f;
            tone += std::sin(2.f * math::PI * 3.f * f0 * t) * 0.16f;
            tone += std::sin(2.f * math::PI * 4.f * f0 * t) * 0.09f;
            const float w       = rn();
            const float exhaust = lpExhaust(w, aExhaust) * chug * 1.7f;
            const float clatter = (lpClatHi(w, aClatHi) - lpClatLo(w, aClatLo)) * (0.4f + 0.6f * chug) * 0.45f;
            s[i] = tone * (0.7f + 0.3f * chug) + exhaust + clatter;
        }
        return normalized(loopable(s, n, extra), 0.7f);
    }

    // Rolling sea, 8 s loop: deep low-passed noise swelling on three loop-
    // exact LFOs (k/8 Hz), plus a brighter band-passed "wash" that peaks on
    // its own sharper envelope — the crest-breaking hiss over the rumble.
    std::vector<float> synthOceanLoop(int sr = 44100) {
        const float dur = 8.0f;
        const int n     = static_cast<int>(sr * dur);
        const int extra = sr;
        std::mt19937 r(11);
        auto rn = [&] { return std::uniform_real_distribution<float>(-1.f, 1.f)(r); };
        OnePole lpDeep, lpWashHi, lpWashLo;
        const float aDeep   = lpAlpha(240.f, sr);
        const float aWashHi = lpAlpha(1500.f, sr);
        const float aWashLo = lpAlpha(500.f, sr);
        std::vector<float> s(n + extra);
        for (int i = 0; i < n + extra; ++i) {
            const float t = static_cast<float>(i) / sr;
            float swell = 0.6f * std::sin(2.f * math::PI * 0.125f * t)
                        + 0.3f * std::sin(2.f * math::PI * 0.375f * t + 1.7f)
                        + 0.1f * std::sin(2.f * math::PI * 0.625f * t + 4.1f);
            swell = 0.55f + 0.45f * swell;
            const float washEnv = std::pow(0.5f + 0.5f * std::sin(2.f * math::PI * 0.25f * t + 2.6f), 3.f);
            const float w    = rn();
            const float deep = lpDeep(w, aDeep) * swell * 1.0f;
            const float wash = (lpWashHi(w, aWashHi) - lpWashLo(w, aWashLo)) * washEnv * 0.55f;
            s[i] = deep + wash;
        }
        return normalized(loopable(s, n, extra), 0.6f);
    }

    // Wind, 8 s loop. NOT a flat noise band — that reads as TV static. The
    // "whoosh" character comes from (a) a NARROW low band whose cutoff SWEEPS
    // upward with the gust envelope (the rising pitch of a building gust),
    // (b) 12 dB/oct edges — cascaded one-poles; a single pole leaks so much
    // above cutoff that the leak IS the white-noise hiss — and (c) a hard
    // lull↔gust amplitude swing (gust², near-silent lulls) so it reads as
    // weather, not a constant carrier. A faint flutter band rides only the
    // gust peaks (gust⁴). Gust LFOs are loop-exact (k/8 Hz).
    std::vector<float> synthWindLoop(int sr = 44100) {
        const float dur = 8.0f;
        const int n     = static_cast<int>(sr * dur);
        const int extra = sr;
        std::mt19937 r(13);
        auto rn = [&] { return std::uniform_real_distribution<float>(-1.f, 1.f)(r); };
        OnePole hi1, hi2, lo1, lo2, fl1, fl2;
        const float aFlHi = lpAlpha(1000.f, sr);
        const float aFlLo = lpAlpha(450.f, sr);
        std::vector<float> s(n + extra);
        for (int i = 0; i < n + extra; ++i) {
            const float t = static_cast<float>(i) / sr;
            float gust = 0.55f * std::sin(2.f * math::PI * 0.25f * t)
                       + 0.30f * std::sin(2.f * math::PI * 0.5f * t + 1.3f)
                       + 0.15f * std::sin(2.f * math::PI * 0.875f * t + 4.0f);
            gust = std::clamp(0.5f + 0.5f * gust, 0.f, 1.f);
            // Swept band: lulls murmur at ~60–180 Hz, full gusts open to
            // ~140–620 Hz. The per-sample alpha is driven by the loop-exact
            // LFOs, so the sweep itself wraps seamlessly too.
            const float aHi = lpAlpha(180.f + 440.f * gust, sr);
            const float aLo = lpAlpha(60.f + 80.f * gust, sr);
            const float w   = rn();
            const float band    = hi2(hi1(w, aHi), aHi) - lo2(lo1(w, aLo), aLo);
            const float whoosh  = band * (0.10f + 0.90f * gust * gust);
            const float flutter = (fl1(w, aFlHi) - fl2(w, aFlLo)) * gust * gust * gust * gust * 0.18f;
            s[i] = whoosh + flutter;
        }
        return normalized(loopable(s, n, extra), 0.5f);
    }

    // Engine (spatialised at the stern) + ocean/wind ambience loops, with the
    // listener following the camera. Degrades to a no-op when no audio device
    // is available; never constructed in headless --shot capture runs.
    struct OceanSounds {
        std::unique_ptr<AudioListener> listener;
        std::unique_ptr<PositionalAudio> engine;
        std::unique_ptr<Audio> waves, wind;
        bool ok    = false;
        float rpm_ = 0.f;// smoothed RPM proxy ∈ [0,1] — the engine spools, it doesn't snap

        void init() {
            try {
                const auto dir = std::filesystem::temp_directory_path() / "threepp_ocean_sounds";
                std::filesystem::create_directories(dir);
                const auto enginePath = dir / "engine_loop.wav";
                const auto wavesPath  = dir / "waves_loop.wav";
                const auto windPath   = dir / "wind_loop.wav";
                audio::writeWav(enginePath, synthEngineLoop());
                audio::writeWav(wavesPath, synthOceanLoop());
                audio::writeWav(windPath, synthWindLoop());

                listener = std::make_unique<AudioListener>();
                // Engine: full volume within ~10 m (the side/deck camera),
                // shallow inverse falloff so the chase cam still hears it and
                // the far buoy cam gets only a faint distant throb.
                engine = std::make_unique<PositionalAudio>(*listener, enginePath);
                engine->setDistanceModel(PositionalAudio::DistanceModel::Inverse);
                engine->setMinDistance(10.f);
                engine->setRolloffFactor(0.5f);
                engine->setLooping(true);
                engine->setVolume(0.f);
                engine->play();
                waves = std::make_unique<Audio>(*listener, wavesPath);
                waves->setLooping(true);
                waves->setVolume(0.f);
                waves->play();
                wind = std::make_unique<Audio>(*listener, windPath);
                wind->setLooping(true);
                wind->setVolume(0.f);
                wind->play();
                ok = true;
            } catch (const std::exception& e) {
                std::cerr << "[audio] disabled: " << e.what() << "\n";
            }
        }

        // sternWorld: engine mount position. thrusting: the telegraph is
        // open — bumps the RPM floor so the engine revs as thrust is
        // applied, before boat speed builds.
        // uw: smoothed submersion ∈ [0,1] — above-surface sound ducks under
        // water (wind almost fully, waves partially, engine least: hull noise
        // carries through the water).
        void update(float dt, const Vector3& sternWorld, float forwardSpeed,
                    bool thrusting, float uw, const PerspectiveCamera& cam,
                    float masterVolume) {
            if (!ok) return;
            listener->setMasterVolume(masterVolume);

            const float speedNorm = std::clamp(std::abs(forwardSpeed) / 8.f, 0.f, 1.f);
            float target = 0.18f + 0.82f * speedNorm;
            if (thrusting) target = std::max(target, 0.45f);
            // Spool up faster than the wind-down coast (turbo lag vs. inertia).
            const float tau = target > rpm_ ? 0.9f : 1.8f;
            rpm_ += (target - rpm_) * (1.f - std::exp(-dt / tau));

            engine->setPlaybackRate((0.7f + 0.9f * rpm_) * (1.f - 0.10f * uw));
            engine->setVolume((0.25f + 0.65f * rpm_) * (1.f - 0.35f * uw));
            engine->position.copy(sternWorld);
            engine->updateMatrixWorld(true);// push the source position to the audio engine

            // Slight speed bump on the ambience = apparent wind over the deck.
            waves->setVolume((0.45f + 0.10f * speedNorm) * (1.f - 0.55f * uw));
            wind->setVolume((0.15f + 0.08f * speedNorm) * (1.f - 0.85f * uw));

            listener->position.copy(cam.position);
            listener->quaternion.copy(cam.quaternion);
            listener->updateMatrixWorld(true);
        }
    };

}// namespace

int main(int argc, char** argv) {

    // --shot <name.png> [--frames N] [--night] [--pt] [--vista] [--close] [--island] [--toggle]
    std::string shotPath;
    int  shotFrames = 240;
    bool startNight = false;
    bool shotVista  = false;
    bool shotClose  = false;// near-surface grazing view — surface-artifact hunting
    bool shotIsland = false;// low close-up of the −X archipelago island (terrain-detail capture)
    int  toggleNightAt = 0;// --toggle: start in day, flip to night mid-run (exercises the runtime toggle path)
    for (int i = 1; i < argc; ++i) {
        if (std::strcmp(argv[i], "--shot") == 0 && i + 1 < argc) shotPath = argv[++i];
        else if (std::strcmp(argv[i], "--frames") == 0 && i + 1 < argc) shotFrames = std::atoi(argv[++i]);
        else if (std::strcmp(argv[i], "--night") == 0) startNight = true;
        else if (std::strcmp(argv[i], "--vista") == 0) shotVista = true;
        else if (std::strcmp(argv[i], "--close") == 0) shotClose = true;
        else if (std::strcmp(argv[i], "--island") == 0) shotIsland = true;
        else if (std::strcmp(argv[i], "--toggle") == 0) toggleNightAt = 60;
    }
    const bool capturing = !shotPath.empty();
    // Shared capture machinery (capture_util.hpp): --cam/--look override the
    // capture framing below with NO rebuild; --profile dumps per-pass timings.
    const capture::Args capArgs = capture::parseArgs(argc, argv);
    int shotFrame = 0;

    Canvas canvas("Vulkan Ocean", {{"vsync", false}, {"size", WindowSize{1600, 900}}});

    auto renderer = VulkanRenderer(canvas);

    renderer.setDenoise(true);
    renderer.setRestirDIEnabled(true);
    renderer.setFireflyClamp(6.0f);

    // Render at lower resolution; TAA upsamples to full swapchain by
    // accumulating jittered low-res samples into the full-res history.
    renderer.setRenderScale(0.9f);
    renderer.toneMapping = ToneMapping::ACESFilmic;
    renderer.toneMappingExposure = 0.7f;

    RGBELoader rgbe;
    auto env = rgbe.load(std::string(DATA_FOLDER) +
                         "/textures/env/autumn_field_puresky_2k.hdr");

    Scene scene;
    if (env) {
        scene.background = env;
        scene.environment = env;
    }

    // Sun-like directional light. The HDR env already contains a sun (the
    // renderer's one-sun policy lets a scene DirectionalLight claim it), so
    // the directional is mostly here to drive crisp RT sun shadows and the
    // volumetric god rays — kept gentle so it doesn't double up with the
    // env's own sun on the surface.
    auto sun = DirectionalLight::create(Color(1.0f, 0.95f, 0.85f), 2.0f);
    sun->position.set(2.f, 1.f, 2.f);
    Object3D sunTarget;
    sunTarget.position.set(0.f, 0.f, 0.f);
    sun->setTarget(sunTarget);
    scene.add(sun);

    // Sand floor sits directly under the ocean tile and matches its extent:
    // making the floor larger leaves a visible sand frame around the water
    // when viewed from above (the open-ocean illusion breaks). At the
    // edges, rays going past the water plane just hit the env sky, which
    // sells "horizon" better than visible beach.
    auto floor = Mesh::create(PlaneGeometry::create(kPlaneEdge, kPlaneEdge),
                              makeSandMaterial());
    floor->rotation.x = -math::PI / 2.f;
    floor->position.y = -5.f;
    scene.add(floor);

    // Enclosing archipelago ring — see namespace island above. Static mesh,
    // one BLAS build; the lighthouse beam grazes its cliffs at night.
    scene.add(island::build());

    Ocean::Options oceanOpts;
    oceanOpts.size       = kTileSize;
    oceanOpts.resolution = kOceanRes;
    oceanOpts.fftSize    = kFftSize;
    // windSpeed scales wave amplitude as V⁴ in Phillips, so it's the dominant
    // lever for "how big is the sea": 20 m/s = gale, 8–10 = Beaufort 4–5 (1–2 m
    // waves, visible chop without overpowering geometry). --close drops to a
    // calm glassy sea — the surface-artifact-hunting state.
    oceanOpts.windSpeed  = shotClose ? 3.5f : 10.0f;
    auto ocean = Ocean::create(oceanOpts);
    scene.add(ocean);

    // ── Lighthouse (scene centre) ───────────────────────────────────────────
    // Procedural Norwegian-coast station: skerry → lathe tower → glazed lantern.
    // Rotating lamp hood gives the emissive area light the same directionality as the SpotLight.
    auto lampMat = MeshStandardMaterial::create(MeshStandardMaterial::Params{}
            .color(Color(1.f, 0.95f, 0.8f)).roughness(0.4f).metalness(0.f));
    lampMat->emissive = Color(1.f, 0.85f, 0.55f);
    lampMat->emissiveIntensity = 0.f;// day: off — night toggle raises it
    std::shared_ptr<Mesh> lensHood;   // rotated with beamAngle in the render loop
    std::shared_ptr<MeshStandardMaterial> hoodMat;// soft lens glow — night toggle drives it
    {
        auto whitePaint = MeshStandardMaterial::create(MeshStandardMaterial::Params{}
                .color(Color(0.92f, 0.90f, 0.86f)).roughness(0.55f).metalness(0.f));
        auto redPaint = MeshStandardMaterial::create(MeshStandardMaterial::Params{}
                .color(Color(0.70f, 0.10f, 0.08f)).roughness(0.5f).metalness(0.f));
        auto ironwork = MeshStandardMaterial::create(MeshStandardMaterial::Params{}
                .color(Color(0.07f, 0.075f, 0.08f)).roughness(0.45f).metalness(0.85f));
        auto concrete = MeshStandardMaterial::create(MeshStandardMaterial::Params{}
                .color(Color(0.55f, 0.54f, 0.52f)).roughness(0.9f).metalness(0.f));

        // Granite skerry: flattened sphere with vertices pushed in/out by the
        // island FBM — same granite character as the surrounding ring. The
        // noise mixes a y-dependent term so the relief isn't vertical ridges.
        auto rockMat = MeshStandardMaterial::create(MeshStandardMaterial::Params{}
                .color(Color(0.14f, 0.135f, 0.13f)).roughness(0.95f).metalness(0.f));
        auto rockGeo = SphereGeometry::create(8.5f, 56, 28);
        {
            auto* p = rockGeo->getAttribute<float>("position");
            for (unsigned i = 0; i < p->count(); ++i) {
                const float x = p->getX(i), y = p->getY(i), z = p->getZ(i);
                // Two scales: a broad mass term shifts whole flanks in/out, a
                // ridged term (fold-over, like the islands') carves crevices
                // and sharp spurs so the skerry reads as fractured granite
                // rather than a sanded dome.
                const float broad = island::fbm(x * 0.16f + 11.f, z * 0.16f + 5.f, 3)
                                  + 0.5f * island::fbm(y * 0.45f + 3.f, (x + z) * 0.22f + 17.f, 2);
                const float ridge = 1.f - std::abs(2.f * island::fbm(x * 0.45f + 31.f, z * 0.45f + 13.f, 3) - 1.f);
                const float k = 1.f + 0.55f * (broad / 1.5f - 0.5f) + 0.30f * (ridge * ridge - 0.45f);
                p->setXYZ(i, x * k, y * 0.5f * k, z * k);
            }
            rockGeo->computeVertexNormals();
            rockGeo->computeBoundingBox();
            rockGeo->computeBoundingSphere();
        }
        auto rock = Mesh::create(rockGeo, rockMat);
        rock->position.set(0.f, -1.8f, 0.f);
        scene.add(rock);

        // Concrete foundation pads — generous height absorbs the skerry's
        // noise variance so the tower and hut always sit on solid footing.
        auto pad = Mesh::create(CylinderGeometry::create(3.4f, 3.7f, 1.2f, 32), concrete);
        pad->position.set(0.f, 2.0f, 0.f);
        scene.add(pad);
        auto hutPad = Mesh::create(CylinderGeometry::create(2.5f, 2.9f, 1.6f, 24), concrete);
        hutPad->position.set(5.6f, 0.6f, 0.f);
        scene.add(hutPad);

        // Tower: lathe profile, base at world y = 2.6 (pad top). Plinth with a
        // chamfer, concave-tapered shaft, corbel flare carrying the gallery.
        constexpr float kTowerBase = 2.6f;
        {
            const std::vector<Vector2> prof = {
                    {0.05f, 0.00f}, {2.85f, 0.00f}, {2.85f, 0.85f}, {2.45f, 1.05f},
                    {2.29f, 3.50f}, {2.04f, 6.50f}, {1.83f, 9.50f},
                    {1.66f, 12.50f}, {1.52f, 15.00f},
                    {1.55f, 15.15f}, {1.95f, 15.75f}, {1.95f, 15.90f}};
            auto tower = Mesh::create(LatheGeometry::create(prof, 48), whitePaint);
            tower->position.y = kTowerBase;
            scene.add(tower);
        }

        // Gallery deck + red watch room below the lantern.
        auto deck = Mesh::create(CylinderGeometry::create(2.8f, 2.8f, 0.22f, 32), redPaint);
        deck->position.set(0.f, 18.6f, 0.f);
        scene.add(deck);
        auto watchRoom = Mesh::create(CylinderGeometry::create(1.8f, 1.8f, 0.95f, 24), redPaint);
        watchRoom->position.set(0.f, 19.18f, 0.f);
        scene.add(watchRoom);

        // Lantern glazing: an open thin-walled transmission cylinder — the
        // lamp shines through real glass. Radius stays inside the 1.7 m
        // offset the render loop pushes the SpotLight origin out to, so the
        // spot never starts inside the pane.
        auto glassMat = MeshPhysicalMaterial::create();
        glassMat->color = Color::white;
        glassMat->roughness = 0.03f;
        glassMat->metalness = 0.f;
        glassMat->transmission = 1.f;
        glassMat->setIor(1.52f);
        glassMat->thickness = 0.02f;
        glassMat->thinWalled = true;
        glassMat->side = Side::Double;
        auto glazing = Mesh::create(
                CylinderGeometry::create(1.45f, 1.45f, 1.4f, 24, 1, true), glassMat);
        glazing->position.set(0.f, 20.3f, 0.f);
        scene.add(glazing);

        // Lantern frame: 8 vertical mullions + top/bottom astragal rings,
        // baked into one static geometry (one BLAS instance).
        {
            std::vector<std::shared_ptr<BufferGeometry>> parts;
            for (int i = 0; i < 8; ++i) {
                const float a = 2.f * math::PI * (static_cast<float>(i) / 8.f);
                auto m = BoxGeometry::create(0.09f, 1.4f, 0.09f);
                m->rotateY(a);
                m->translate(1.45f * std::sin(a), 20.3f, 1.45f * std::cos(a));
                parts.push_back(m);
            }
            for (const float y : {19.62f, 20.98f}) {
                auto ring = TorusGeometry::create(1.45f, 0.06f, 10, 48);
                ring->rotateX(math::PI / 2.f);
                ring->translate(0.f, y, 0.f);
                parts.push_back(ring);
            }
            scene.add(Mesh::create(mergeBufferGeometries(parts), redPaint));
        }

        // Lamp + rotating lens assembly. The "hood" is a partial cylinder with
        // a ~109° window the render loop yaws to track the beam direction —
        // the full lamp blazes through the opening while the shell itself
        // glows softly at night (a Fresnel optic leaks light everywhere, it
        // doesn't black out the lantern), so the beacon reads from any bearing.
        auto lamp = Mesh::create(CylinderGeometry::create(0.5f, 0.5f, 1.0f, 16), lampMat);
        lamp->position.set(0.f, 20.3f, 0.f);
        scene.add(lamp);
        hoodMat = MeshStandardMaterial::create(MeshStandardMaterial::Params{}
                .color(Color(0.30f, 0.27f, 0.22f)).roughness(0.4f).metalness(0.2f));
        hoodMat->emissive = Color(1.f, 0.85f, 0.55f);
        hoodMat->emissiveIntensity = 0.f;// day: off — night toggle raises it
        hoodMat->side = Side::Double;
        lensHood = Mesh::create(
                CylinderGeometry::create(0.8f, 0.8f, 1.25f, 24, 1, true,
                                         0.95f, math::TWO_PI - 1.9f), hoodMat);
        lensHood->position.set(0.f, 20.3f, 0.f);
        scene.add(lensHood);

        // Domed roof + ventilator ball and lightning rod.
        {
            const std::vector<Vector2> domeProf = {
                    {1.92f, 0.00f}, {1.78f, 0.42f}, {1.45f, 0.80f},
                    {0.95f, 1.10f}, {0.42f, 1.32f}, {0.10f, 1.42f}};
            auto dome = Mesh::create(LatheGeometry::create(domeProf, 32), redPaint);
            dome->position.y = 21.0f;
            scene.add(dome);
        }

        // Gallery railing (18 stanchions + two hoop rails) and the roof
        // finial, merged into a single ironwork instance.
        {
            std::vector<std::shared_ptr<BufferGeometry>> parts;
            for (int i = 0; i < 18; ++i) {
                const float a = 2.f * math::PI * (static_cast<float>(i) / 18.f);
                auto post = CylinderGeometry::create(0.035f, 0.035f, 1.0f, 6);
                post->translate(2.62f * std::sin(a), 19.21f, 2.62f * std::cos(a));
                parts.push_back(post);
            }
            for (const float y : {19.40f, 19.70f}) {
                auto rail = TorusGeometry::create(2.62f, 0.045f, 8, 48);
                rail->rotateX(math::PI / 2.f);
                rail->translate(0.f, y, 0.f);
                parts.push_back(rail);
            }
            auto ball = SphereGeometry::create(0.17f, 12, 8);
            ball->translate(0.f, 22.55f, 0.f);
            parts.push_back(ball);
            auto rod = CylinderGeometry::create(0.02f, 0.02f, 0.6f, 6);
            rod->translate(0.f, 22.95f, 0.f);
            parts.push_back(rod);
            scene.add(Mesh::create(mergeBufferGeometries(parts), ironwork));
        }

        // Door at the plinth and three shaft windows, all facing the hut
        // (+X). Window radius follows the shaft taper so each frame sits
        // proud of the wall by ~10 cm.
        {
            auto shaftR = [&](float yWorld) {
                const float yl = yWorld - kTowerBase;
                return 2.45f - 0.95f * (yl - 1.05f) / 13.95f;
            };
            std::vector<std::shared_ptr<BufferGeometry>> parts;
            auto door = BoxGeometry::create(0.3f, 2.0f, 0.95f);
            door->translate(2.45f, 3.6f, 0.f);
            parts.push_back(door);
            for (const float y : {7.0f, 10.5f, 14.0f}) {
                auto win = BoxGeometry::create(0.24f, 0.7f, 0.5f);
                win->translate(shaftR(y), y, 0.f);
                parts.push_back(win);
            }
            auto joinery = MeshStandardMaterial::create(MeshStandardMaterial::Params{}
                    .color(Color(0.05f, 0.10f, 0.08f)).roughness(0.6f).metalness(0.1f));
            scene.add(Mesh::create(mergeBufferGeometries(parts), joinery));
        }

        // Service hut: white walls, red gabled roof (45°-rotated box reads as
        // a gable from any playable distance), on its own pad. Yawed a touch
        // so it doesn't sit axis-aligned with the door/window azimuth.
        const float hutYaw = 0.35f;
        auto hut = Mesh::create(BoxGeometry::create(3.0f, 2.2f, 2.4f), whitePaint);
        hut->position.set(5.6f, 2.5f, 0.f);
        hut->rotation.y = hutYaw;
        scene.add(hut);
        auto hutRoof = Mesh::create(BoxGeometry::create(1.75f, 1.75f, 3.0f), redPaint);
        // Euler XYZ applies Z first: the 45° gable tilt, then the yaw.
        hutRoof->rotation.set(0.f, hutYaw, math::PI / 4.f);
        hutRoof->position.set(5.6f, 3.55f, 0.f);
        scene.add(hutRoof);
    }

    // Rotating beam — narrow long-throw spot, aimed slightly below horizontal
    // so the far end grazes the swells. decay 2 = physical inverse-square; a
    // real lighthouse lamp is O(10⁵–10⁶ cd), which is what it takes to light
    // water hundreds of metres out. Off by day (intensity 0).
    auto beam = SpotLight::create(Color(1.f, 0.92f, 0.72f), 0.f,
                                  /*distance=*/600.f, /*angle=*/math::PI / 40.f,
                                  /*penumbra=*/0.45f, /*decay=*/2.f);
    beam->position.set(0.f, 20.3f, 0.f);
    Object3D beamTarget;
    beamTarget.position.set(300.f, -4.f, 0.f);
    beam->setTarget(beamTarget);
    scene.add(beam);

    // Dim blue moonlight — direction matches the procedural night env's moon
    // disc so shadows and the bright sky spot agree.
    auto moon = DirectionalLight::create(Color(0.65f, 0.75f, 1.0f), 0.f);
    moon->position.set(-0.55f, 0.60f, 0.35f);
    Object3D moonTarget;
    moonTarget.position.set(0.f, 0.f, 0.f);
    moon->setTarget(moonTarget);
    scene.add(moon);

    // Procedural night sky equirect: gradient + horizon glow + moon disc (bright enough for env CDF IS).
    std::shared_ptr<Texture> nightEnv;
    {
        // 2048×1024: one texel ≈ 0.18° ≈ ~4 screen px at this FOV — stars stay
        // point-like. At 512² a texel was ~19 px and bilinear magnification
        // rendered every star as a big square tent.
        const int W = 2048, H = 1024;
        std::vector<float> data(static_cast<size_t>(W) * H * 4, 0.f);
        // sampleEnvLod maps dir.y=+1 → v=1.0 (zenith = last row).
        const Vector3 moonDir = Vector3(-0.55f, 0.60f, 0.35f).normalize();
        for (int y = 0; y < H; ++y) {
            const float v    = (y + 0.5f) / H;
            const float elev = (v - 0.5f) * math::PI;// >0 = above horizon
            for (int x = 0; x < W; ++x) {
                const float u  = (x + 0.5f) / W;
                const float az = (u - 0.5f) * 2.f * math::PI;
                const Vector3 dir(std::cos(elev) * std::cos(az), std::sin(elev),
                                  std::cos(elev) * std::sin(az));
                // Sky gradient: near-black zenith → faint blue horizon band;
                // below the horizon a dark sea-glow so reflections aren't void.
                float r, g, b;
                if (elev >= 0.f) {
                    const float horizon = std::exp(-elev * 4.5f);
                    r = 0.004f + 0.020f * horizon;
                    g = 0.006f + 0.028f * horizon;
                    b = 0.012f + 0.050f * horizon;
                } else {
                    const float fade = std::exp(elev * 6.f);
                    r = 0.003f * fade; g = 0.004f * fade; b = 0.007f * fade;
                }
                // Moon disc (~1.7° radius) + soft glow halo.
                const float cosToMoon = std::clamp(dir.dot(moonDir), -1.f, 1.f);
                const float angTo     = std::acos(cosToMoon);
                if (angTo < 0.03f) {
                    r += 28.f; g += 32.f; b += 40.f;
                } else {
                    const float glow = 0.35f * std::exp(-angTo * angTo * 90.f);
                    r += glow * 0.65f; g += glow * 0.75f; b += glow;
                }
                const size_t i = (static_cast<size_t>(y) * W + x) * 4;
                data[i + 0] = r; data[i + 1] = g; data[i + 2] = b; data[i + 3] = 1.f;
            }
        }
        // Stars via setDeferredStarfield (not baked) — baked stars blur to ~14 px blobs after bilinear+TAA.
        Image img{std::move(data), static_cast<unsigned>(W), static_cast<unsigned>(H), 0};
        nightEnv = Texture::create(img);
        nightEnv->format = Format::RGBA;
        nightEnv->type = Type::Float;
        nightEnv->colorSpace = ColorSpace::Linear;
        nightEnv->mapping = Mapping::EquirectangularReflection;
        nightEnv->needsUpdate();
    }

    // ── Day/night toggle ────────────────────────────────────────────────────
    bool  night       = startNight;
    float beamSpeed   = 0.45f;// rad/s — ~14 s revolution, classic lighthouse cadence
    float beamAngle   = 0.f;
    float hazeDensity = 0.018f;// σ (1/m) for the deferred volumetric beams
    auto applyMode = [&] {
        if (night) {
            scene.background  = nightEnv;
            scene.environment = nightEnv;
            sun->intensity  = 0.f;
            moon->intensity = 0.30f;
            beam->intensity = 150000.f;// inverse-square: bright enough to read at 300 m
            // Lamp is ~6× smaller in area than the pre-optic version — higher
            // intensity keeps the through-window flare reading at distance.
            lampMat->emissiveIntensity = 45.f;
            hoodMat->emissiveIntensity = 8.f;// soft all-round lens glow
            renderer.setDeferredVolumetrics(hazeDensity, 0.6f);
            renderer.setDeferredStarfield(1.0f);
            renderer.toneMappingExposure = 1.15f;
        } else {
            scene.background  = env;
            scene.environment = env;
            sun->intensity  = 2.0f;
            moon->intensity = 0.f;
            beam->intensity = 0.f;
            lampMat->emissiveIntensity = 0.f;
            hoodMat->emissiveIntensity = 0.f;
            renderer.setDeferredVolumetrics(0.f, 0.6f);
            renderer.setDeferredStarfield(0.f);
            renderer.toneMappingExposure = 0.7f;
        }
        // Material PBR values live in a GPU MaterialDesc refreshed on version
        // bump — emissiveIntensity is a plain field, so without this the
        // day↔night toggle leaves the GPU-side lamp at the OLD emissive:
        // no glow, no lamp area light, and (since strongly-emissive housings
        // are what shadow rays skip) the housing blocks the beam entirely.
        lampMat->needsUpdate();
        hoodMat->needsUpdate();
    };
    applyMode();

    constexpr float kBoatLength = 28.0f;
    constexpr float kBoatBeam   = 9.0f;

    // Maneuvering model constants — Nomoto/Norrbin for a 28 m displacement hull (R/V Gunnerus-ish).
    constexpr float kMaxSpeed    = 7.2f;  // m/s ≈ 14 kn
    constexpr float kMaxAccel    = 0.55f; // m/s²
    constexpr float kDragQuad    = kMaxAccel / (kMaxSpeed * kMaxSpeed);
    constexpr float kAsternFrac  = 0.25f; // astern thrust fraction
    constexpr float kRudderMax   = 0.61f; // 35° hard-over
    constexpr float kRudderRate  = 0.30f; // rad/s actuator slew
    constexpr float kTurnGain    = 1.f / (70.f * kRudderMax);// r_ss = gain·flow·δ, ≈2.5 L turning radius
    constexpr float kPropWash    = 2.0f;  // m/s extra rudder flow per unit ahead throttle
    constexpr float kTurnDrag    = 0.5f;  // surge drag ∝ |r|·u in turns
    constexpr float kSwayCouple  = 1.45f; // centripetal sway
    constexpr float kSwayDamp    = 0.8f;  // 1/s lateral damping
    constexpr float kTurnHeel    = 0.08f; // rad outward heel per (m/s · rad/s)
    constexpr float kSpeedTrim   = 0.021f;// rad bow-up trim at full speed
    constexpr float kDraft       = 2.5f;  // m, grounding depth

    GLTFLoader gltfLoader;
    auto boat = loadAsync([&gltfLoader]() -> std::shared_ptr<Group> {
        auto gltf = gltfLoader.load(std::string(DATA_FOLDER) + "/models/gltf/Gunnerus.glb");
        if (!gltf || !gltf->scene) {
            std::cerr << "Failed to load Gunnerus.glb" << std::endl;
            auto fallback = Group::create();
            fallback->add(Mesh::create(BoxGeometry::create(kBoatBeam, 5.f, kBoatLength),
                                       MeshStandardMaterial::create(MeshStandardMaterial::Params{}.color(Color::red))));
            return fallback;
        }

        auto innerAsset = gltf->scene;
        {
            Box3 bbox;
            bbox.setFromObject(*innerAsset);
            Vector3 size; bbox.getSize(size);
            if (size.x > size.z) {
                innerAsset->rotateY(-math::PI / 2.f);
                bbox.setFromObject(*innerAsset);
                bbox.getSize(size);
            }
            innerAsset->rotateY(math::PI);
            const float maxExtent = std::max({size.x, size.y, size.z});
            if (maxExtent > 0.f) {
                const float s = kBoatLength / maxExtent;
                innerAsset->scale.set(s, s, s);
            }
        }

        // Material re-grade. The GLB exports EVERY material with the same
        // metallic-roughness pair (rough 0.71, metal 0.40) — half-metallic
        // everything is exactly the "grey plastic toy" look, and the PBR
        // ocean now exposes it hard. Painted marine steel is a DIELECTRIC
        // with a fairly glossy topcoat; deck paint is matte non-slip; only
        // railings/stairs/exhaust keep a metallic component; glass is
        // near-mirror. Albedo + normal maps stay — only the response
        // changes. Keyed by the GLB's material names (see git history for
        // the dumped inventory).
        struct Grade { float rough, metal; };
        static const std::unordered_map<std::string, Grade> grades = {
                {"HullWhite",            {0.38f, 0.00f}},// painted steel topsides
                {"VesselBlue",           {0.35f, 0.00f}},
                {"BridgeWhite",          {0.42f, 0.00f}},
                {"BridgeWhite.001",      {0.42f, 0.00f}},
                {"BridgeBlue",           {0.40f, 0.00f}},
                {"whitePaint_notBridge", {0.42f, 0.00f}},
                {"VesselBottom",         {0.55f, 0.15f}},// antifouling; bronze props share it
                {"Deck",                 {0.85f, 0.00f}},// matte non-slip paint
                {"Interior",             {0.80f, 0.00f}},
                {"Decals",               {0.55f, 0.00f}},
                {"Glass",                {0.06f, 0.00f}},// near-mirror, mostly sky reflection
                {"VesselGlass",          {0.06f, 0.00f}},
                {"Railing",              {0.45f, 0.35f}},// galvanized/painted metalwork
                {"stairs",               {0.50f, 0.35f}},
                {"Material #315",        {0.50f, 0.35f}},// stairs sibling
                {"Exhaust",              {0.60f, 0.30f}},
                {"VesselSafe",           {0.55f, 0.00f}},// life rings: actual plastic
                {"BridgeSafe",           {0.55f, 0.00f}},
                {"vesselShared",         {0.50f, 0.10f}},
        };
        innerAsset->traverseType<Mesh>([](Mesh& m) {
            auto* mat = m.material()->as<MeshStandardMaterial>();
            if (!mat) return;
            const auto it = grades.find(mat->name);
            // Unknown names: sane dielectric default, far better than the
            // export's uniform half-metal.
            const Grade g = (it != grades.end()) ? it->second : Grade{0.55f, 0.05f};
            mat->roughness = g.rough;
            mat->metalness = g.metal;
        });

        auto group = Group::create();
        group->add(innerAsset);
        return group;
    });
    scene.add(boat);
    BoatState bs;
    BoatInput bi;
    canvas.addKeyListener(bi);

    // ── Auto-pilot waypoints ───────────────────────────────────────────────
    // Closed Catmull-Rom loop the vessel follows when autopilot is on.
    // Five waypoints, one per buoy variant loaded from the GLB below.
    // Points are world-space (x, 0, z); y=0 — boat heave still comes from
    // wave sampling so it rides crests naturally along the path.
    // Centripetal parameterization avoids cusps/loops in non-uniform spacing;
    // closed=true makes the curve wrap so reaching u=1 seamlessly resets to
    // u=0 (continuous tangent at the seam).
    std::vector<Vector3> waypoints = {
            Vector3(-200.f, 0.f, -150.f),
            Vector3( 250.f, 0.f, -200.f),
            Vector3( 320.f, 0.f,  100.f),
            Vector3(   0.f, 0.f,  280.f),
            Vector3(-300.f, 0.f,   50.f),
    };
    CatmullRomCurve3 navCurve(waypoints, /*closed=*/true,
                              CatmullRomCurve3::centripetal, 0.5f);
    const float navCurveLength = navCurve.getLength();

    // ── Buoys at each waypoint ─────────────────────────────────────────────
    // A named group is pulled from the buoy GLB and cloned; its children are
    // the buoy variants, one placed at each waypoint. The clone keeps the
    // GLB's Z-up→Y-up rotation and 0.1 scale on its root, so positioning a
    // child at a world-space waypoint goes through the inverse root matrix
    // (see the GLB-success branch below).
    //
    // Fallback path: if the GLB is missing or doesn't expose ≥5 children,
    // emissive spheres take over. The renderer's emissive NEE picks them up
    // (low intensity so they don't double as light sources).
    auto buoyFallbackMat = MeshStandardMaterial::create(MeshStandardMaterial::Params{}.color(Color(0.95f, 0.25f, 0.1f)).emissive(Color(0.95f, 0.25f, 0.1f)).emissiveIntensity(0.6f).roughness(0.8f));
    auto makeFallbackBuoy = [&] {
        return Mesh::create(SphereGeometry::create(1.0f, 16, 12), buoyFallbackMat);
    };

    std::shared_ptr<Object3D> buoyRoot;
    try {
        auto buoyGltf = gltfLoader.load(std::string(DATA_FOLDER) +
                                        "/models/gltf/ocean_buoy/ocean_buoy_v.2_tao_buoy.glb");
        if (buoyGltf && buoyGltf->scene) {
            auto obj = buoyGltf->scene->getObjectByName("TAO_L.obj.cleaner.materialmerger.gles");
            buoyRoot = obj->clone();

        }
    } catch (const std::exception& e) {
        std::cerr << "Failed to load buoy GLB: " << e.what() << std::endl;
    }

    // Per-buoy state captured across frames for buoyancy. Filled in the
    // GLB-success branch below; the animate loop sees an empty vector if
    // the fallback sphere path took over (and skips buoyancy then).
    struct BuoyState {
        float   worldX = 0.f, worldZ = 0.f;  // fixed waypoint position
        Vector3 baseLocal;                   // anchored "rest" local position
        float   worldYOffset = 0.f;          // current bob (world units)
        float   vY = 0.f;                    // bob velocity (world units / s)
    };
    std::vector<BuoyState> buoyStates;
    Matrix3 buoyInvRotScale;// captures buoyRoot's inverse rotation+scale for
                            // converting world-Y bob deltas back to local.

    if (buoyRoot && buoyRoot->children.size() >= waypoints.size()) {
        // GLB is Z-up at ~10× our scene scale; the rotation + uniform 0.1
        // scale lives on buoyRoot. Because of that parent transform, placing
        // each child at the waypoint requires going through invRootMat —
        // setting child.position directly in local space would put buoys at
        // (0.1·wp) in world coords, and a 15 m underwater spot in Y because
        // the X-axis rotation maps local Z to world Y.
        buoyRoot->position.set(0.f, 0.f, 0.f);
        buoyRoot->rotation.x = -math::PI / 2.f;
        buoyRoot->scale *= 0.1f;
        buoyRoot->updateMatrixWorld(true);
        Matrix4 invRootMat;
        invRootMat.copy(*buoyRoot->matrixWorld).invert();
        buoyInvRotScale.setFromMatrix4(invRootMat);

        // Per-buoy Y anchoring: GLB variants have different origin
        // conventions (one is centred way below its body, hence the
        // hovering buoy in the first screenshot). Computing each child's
        // world bbox and shifting so bbox.min().y sits at a uniform depth
        // below the waterline puts all five buoys at the same visual height.
        constexpr float kBuoyBottomBelowWater = 0.8f;
        buoyStates.resize(waypoints.size());
        for (size_t i = 0; i < waypoints.size(); ++i) {
            auto* child = buoyRoot->children[i];
            // Step 1: put the buoy at (waypoint.x, 0, waypoint.z) in world.
            Vector3 wantWorld(waypoints[i].x, 0.f, waypoints[i].z);
            Vector3 wantLocal = wantWorld;
            wantLocal.applyMatrix4(invRootMat);
            child->position.copy(wantLocal);
            child->updateMatrixWorld(true);

            // Step 2: compute world bbox, derive a vertical shift that
            // anchors the body's bottom at -kBuoyBottomBelowWater (slightly
            // submerged so the float ring intersects the chop naturally).
            Box3 bbox;
            bbox.setFromObject(*child);
            const float deltaWorldY = -kBuoyBottomBelowWater - bbox.min().y;
            Vector3 dLocal(0.f, deltaWorldY, 0.f);
            dLocal.applyMatrix3(buoyInvRotScale);
            child->position.add(dLocal);

            // Snapshot the "rest" local position so the per-frame buoyancy
            // step can offset cleanly without drifting.
            buoyStates[i].worldX = waypoints[i].x;
            buoyStates[i].worldZ = waypoints[i].z;
            buoyStates[i].baseLocal = child->position;
        }
        scene.add(buoyRoot);
    } else {
        if (buoyRoot) {
            std::cerr << "Buoy GLB has " << buoyRoot->children.size()
                      << " children (need " << waypoints.size() << "); using fallback spheres."
                      << std::endl;
        }
        auto buoyGroup = Group::create();
        for (const Vector3& wp : waypoints) {
            auto buoy = makeFallbackBuoy();
            buoy->position.set(wp.x, 1.5f, wp.z);
            buoyGroup->add(buoy);
        }
        scene.add(buoyGroup);
    }

    // Start the vessel at the first waypoint, heading along the initial tangent.
    bool  autoPilot      = true;
    float autoU          = 0.f;   // arc-length parameter in [0, 1)
    float autoCruiseSpeed = 6.f;  // m/s (~12 kn) — moderate cruise
    {
        Vector3 p0, t0;
        navCurve.getPointAt(0.f, p0);
        navCurve.getTangentAt(0.f, t0);
        bs.position.set(p0.x, 0.f, p0.z);
        bs.yaw          = std::atan2(t0.x, t0.z);
        bs.forwardSpeed = autoCruiseSpeed;
        // Steady-state telegraph for the cruise speed, so the demo opens
        // under way instead of spooling the engine up from stop.
        bs.throttle     = std::clamp(kDragQuad * autoCruiseSpeed * autoCruiseSpeed / kMaxAccel, 0.f, 1.f);
    }

    // Far-clip raised so the horizon doesn't get cut at the elevated/distant
    // camera. Initial position is offset from the boat; OrbitControls'
    // target is updated each frame to follow the boat so orbiting always
    // happens around the vessel.
    PerspectiveCamera camera(45.f, canvas.aspect(), 0.1f, 2000.f);
    camera.position.set(40.f, 18.f, 60.f);
    OrbitControls controls{camera, canvas};
    controls.target.set(0.f, 1.f, 0.f);
    controls.update();

    // ── Camera modes ──────────────────────────────────────────────────────
    // C cycles: Free orbit → Side → Chase → Underwater → NearestBuoy.
    // SideFixed/Chase/Underwater/NearestBuoy override camera.position +
    // lookAt each frame; OrbitControls state is left alone so switching
    // back to Free restores whatever orbit angle the user left it at.
    enum class CamMode : int {
        Free        = 0,
        SideFixed   = 1,
        Chase       = 2,
        Underwater  = 3,
        NearestBuoy = 4,
    };
    constexpr int kCamModeCount = 5;
    CamMode camMode = CamMode::Free;
    const char* camModeNames[] = {
            "Free (orbit)", "Side (forward)", "Chase", "Underwater", "Nearest buoy"};

    // Auto-cam: cycles through every CamMode in turn at a fixed cadence.
    // Lets the demo show all viewpoints without the user touching anything.
    // Free is skipped while auto is on so OrbitControls input doesn't fight
    // the timer.
    bool  autoCam        = false;
    float autoCamHold    = 5.0f;  // seconds per camera before switching
    float autoCamElapsed = 0.f;

    KeyAdapter camKey(KeyAdapter::Mode::KEY_PRESSED, [&](KeyEvent ev) {
        if (ev.key == Key::C) {
            camMode = static_cast<CamMode>(
                    (static_cast<int>(camMode) + 1) % kCamModeCount);
            autoCamElapsed = 0.f;  // a manual switch restarts the auto timer
        }
    });
    canvas.addKeyListener(camKey);

    // ── Sound: engine + ocean/wind ambience ─────────────────────────────────
    // Skipped in --shot capture runs (headless iteration shouldn't bleep).
    OceanSounds sounds;
    if (!capturing) sounds.init();
    bool  audioOn  = true;
    float audioVol = 0.3f;

    float waveScale = ocean->params.waveScale;
    float choppiness = ocean->params.choppiness;
    float windSpeed = ocean->params.windSpeed;
    float windTheta = ocean->params.windTheta;

    // Marine cumulus deck over the open sea — drifts on the ocean's wind
    // heading at ~2.5× the surface speed (wind shear aloft).
    bool  cloudsOn   = true;
    float cloudCover = 0.5f;
    auto applyClouds = [&] {
        if (cloudsOn) {
            VulkanRenderer::CloudSettings cl;
            cl.coverage = cloudCover;
            cl.bottomY = 450.f;
            cl.topY = 1100.f;
            cl.wind.set(std::cos(windTheta), 0.f, std::sin(windTheta));
            cl.wind.multiplyScalar(windSpeed * 2.5f);
            renderer.setClouds(cl);
        } else {
            renderer.setClouds(std::nullopt);
        }
    };
    applyClouds();
    float fps = 0.f, fpsAccum = 0.f;
    int   fpsFrames = 0;

    // ── Underwater fog parameters ─────────────────────────────────────────
    // Controlled by ImGui; applied per-frame when the camera is submerged.
    // fogDensity = σ_t (extinction per metre, uniform across channels).
    // fogColor = single-scattering albedo σ_s/σ_t — blue-green for ocean.
    // fogAnisotropy = Henyey-Greenstein g: 0.85 → strong forward scatter
    //   (sun shafts / god rays when looking toward the light).
    float uwFogDensity   = 0.06f;
    float uwFogColor[3]  = {0.10f, 0.55f, 0.65f};
    float uwFogAniso     = 0.85f;
    float uwDepthSmooth  = 0.f;

    // ── Radar state ────────────────────────────────────────────────────────
    // Heading-up scope, 500 m range, 4 s sweep period (15 RPM — realistic
    // small-craft). Per-target intensity is set to 1 when the sweep crosses
    // its bearing, then decays exponentially (3 s time constant ≈ slightly
    // less than one full rotation). Cap intensity by range so distant blips
    // look weaker than nearby ones — closer to a real CRT.
    bool  radarOn          = true;
    float radarRangeM      = 500.f;
    float radarSweepAngle  = 0.f;        // [0, 2π), advances clockwise
    constexpr float kRadarSweepPeriod = 4.f;
    constexpr float kRadarBlipTau     = 3.f;
    constexpr int   kMaxRadarTargets  = 16;
    std::array<float, kMaxRadarTargets> radarBlipIntensity{};

    // ── LIDAR mast: OS0-128 forward hemisphere (bow-mounted, avoids wheelhouse occlusion) ──
    constexpr float kLidarMountHeight  = 11.0f;      // m above waterline — clears wheelhouse + mast roof
    constexpr float kLidarMountForward = 8.0f;       // m forward of boat origin (near the bow)
    constexpr int   kLidarMaxBeams     = 1100000;    // OS0-128 forward × maxReturns 4 × samples 4

    // Forward-only scan (azimuth ∈ [-90°, +90°]). Sensor convention puts
    // azimuth = 0 along the sensor's local -Z (forward), so this carves
    // out the rear half-sphere.
    LidarModel lidarModel = LidarModel::OS0_128();
    lidarModel.azimuthMin = -90.f;
    lidarModel.azimuthMax =  90.f;

    auto lidarSensor = std::make_unique<PathTracedLidarSensor>(lidarModel);
    lidarSensor->params.maxRange = 120.f;            // ~half a buoy spacing
    lidarSensor->params.referenceRange = 30.f;       // calibrate intensity for ocean scale
    lidarSensor->params.laserPower = 2.0f;           // bump so distant buoys still register
    lidarSensor->params.atmosphericExtinction = 0.f;
    lidarSensor->params.detectorThreshold = 0.005f;

    // Dedicated LIDAR water column. Attenuates beams crossing into the
    // ocean regardless of where the camera is, so the seafloor doesn't
    // pop in unattenuated when the eye floats above the waterline.
    // mediumSurfaceY is updated each frame to follow the live wave
    // surface height under the sensor.
    lidarSensor->params.mediumExtinction = 0.30f;
    lidarSensor->params.mediumAlbedo     = 0.85f;
    lidarSensor->params.mediumAnisotropy = 0.85f;
    lidarSensor->params.mediumSurfaceY   = 0.f;
    scene.addRef(*lidarSensor);
    bool lidarEnabled = false;
    bool lidarShowPanel = true;

    // Live stats reflected in the UI panel.
    int   lidarLastReturns = 0;
    float lidarLastScanMs  = 0.f;

    // ── LIDAR point-cloud overlay (Points object, excluded from TLAS) ────────
    auto lidarCloudGeom = BufferGeometry::create();
    lidarCloudGeom->setAttribute("position",
                                  FloatBufferAttribute::create(std::vector<float>(kLidarMaxBeams * 3), 3));
    lidarCloudGeom->setAttribute("color",
                                  FloatBufferAttribute::create(std::vector<float>(kLidarMaxBeams * 3), 3));
    lidarCloudGeom->getAttribute<float>("position")->setUsage(DrawUsage::Dynamic);
    lidarCloudGeom->getAttribute<float>("color")->setUsage(DrawUsage::Dynamic);
    lidarCloudGeom->setDrawRange(0, 0);

    // sizeAttenuation(false): the 3 is PIXELS. The default unit is world
    // space, where a 3-metre point covers the horizon.
    auto lidarCloudMat = PointsMaterial::create(
            PointsMaterial::Params{}.size(3.f).sizeAttenuation(false).vertexColors(true));
    auto lidarCloud = Points::create(lidarCloudGeom, lidarCloudMat);
    lidarCloud->frustumCulled = false;
    scene.add(lidarCloud);

    // ── LIDAR readout panel (screen-space sprite, azimuth × elevation grid) ──
    constexpr unsigned int kLidarPanelW = 720;
    constexpr unsigned int kLidarPanelH = 128;
    constexpr float        kLidarPanelDispW = 360.f;
    constexpr float        kLidarPanelDispH = 64.f;

    auto lidarPanelTex = DataTexture::create(
            ImageData{std::vector<unsigned char>(kLidarPanelW * kLidarPanelH * 4, 0u)},
            kLidarPanelW, kLidarPanelH);
    lidarPanelTex->colorSpace = ColorSpace::sRGB;

    auto lidarPanelMat = SpriteMaterial::create();
    lidarPanelMat->map = lidarPanelTex;
    auto lidarPanel = Sprite::create(lidarPanelMat);
    lidarPanel->scale.set(kLidarPanelDispW, kLidarPanelDispH, 1.f);
    lidarPanel->screenSpace = true;
    lidarPanel->screenAnchor.set(1.f, 1.f);   // viewport top-right
    lidarPanel->center.set(1.f, 1.f);
    lidarPanel->position.set(-10.f, -10.f, 0.f);
    scene.add(lidarPanel);

    std::vector<LidarReturn> lidarReturns;

    // ── Time-of-flight waveform synthesis (Gaussian-pulse convolution of discrete returns) ──
    LidarWaveformParams lidarWavParams;
    lidarWavParams.maxRange   = 120.f;
    lidarWavParams.bins       = 256;
    lidarWavParams.pulseFWHM  = 0.75f;
    lidarWavParams.noiseFloor = 0.f;
    bool  lidarShowWave    = true;
    int   lidarWaveBeamIdx = 0;
    std::vector<float> lidarWaveform;

    // Generic renderer settings (exposure, tone map, render scale, ...) come
    // from the shared collapsed panel at the bottom of the main window.
    RendererSettings settings(renderer);

    ImguiFunctionalContext ui(canvas, renderer, [&] {
        ImGui::SetNextWindowPos({0, 0});
        ImGui::SetNextWindowSize({340, 0});
        ImGui::Begin("Vulkan Deferred - Ocean");
        ImGui::Text("FPS: %.1f", fps);
        ImGui::Separator();
        ImGui::TextWrapped(
            "FFT-displaced surface (multi-cascade Phillips, %u² IFFT, "
            "%.0f m tile). Ray-traced reflections + refraction. "
            "W/S = engine telegraph, A/D = rudder.",
            kFftSize, kTileSize);
        ImGui::Text("Speed: %.1f kn (%.1f m/s)   Heading: %.0f°",
                    bs.forwardSpeed * 1.94384f, bs.forwardSpeed,
                    bs.yaw * math::RAD2DEG);
        ImGui::Text("Telegraph: %+4.0f%%   Rudder: %+5.1f°%s",
                    bs.throttle * 100.f, bs.rudder * math::RAD2DEG,
                    bs.aground ? "   AGROUND!" : "");
        ImGui::Text("Pos: %7.1f, %7.1f", bs.position.x, bs.position.z);
        ImGui::Text("Keys  W:%d  A:%d  S:%d  D:%d   (C = cycle camera)",
                    bi.W ? 1 : 0, bi.A ? 1 : 0, bi.S ? 1 : 0, bi.D ? 1 : 0);
        ImGui::Text("Camera: %s", camModeNames[static_cast<int>(camMode)]);
        if (ImGui::Checkbox("Auto-cam (cycle every N s)", &autoCam))
            autoCamElapsed = 0.f;
        if (autoCam) {
            ImGui::SliderFloat("Hold (s)", &autoCamHold, 1.f, 30.f, "%.1f");
            ImGui::Text("Next in %.1fs", std::max(0.f, autoCamHold - autoCamElapsed));
        }
        ImGui::Separator();

        ImGui::TextUnformatted("Autopilot");
        ImGui::Checkbox("Follow waypoint loop", &autoPilot);
        if (autoPilot) {
            ImGui::SliderFloat("Cruise speed (m/s)", &autoCruiseSpeed, 1.f, kMaxSpeed, "%.1f");
            const int wpCount = static_cast<int>(waypoints.size());
            const int currentWp = std::min(wpCount - 1,
                                           static_cast<int>(autoU * wpCount));
            ImGui::Text("Waypoint %d / %d   (u = %.2f)", currentWp + 1, wpCount, autoU);
        } else {
            ImGui::TextDisabled("W/S engine ahead/astern, A/D rudder.");
        }
        ImGui::Separator();

        if (ImGui::SliderFloat("Wave scale", &waveScale, 0.f, 3.f, "%.2f")) {
            ocean->params.waveScale = waveScale;
        }
        if (ImGui::SliderFloat("Choppiness", &choppiness, 0.f, 1.0f, "%.2f")) {
            ocean->params.choppiness = choppiness;
        }

        ImGui::TextDisabled("Wind changes apply on scene reload.");
        if (ImGui::Checkbox("Clouds", &cloudsOn)) applyClouds();
        if (cloudsOn && ImGui::SliderFloat("Cloud cover", &cloudCover, 0.f, 1.f, "%.2f"))
            applyClouds();
        ImGui::Separator();
        ImGui::TextUnformatted("Night & lighthouse");
        if (ImGui::Checkbox("Night mode", &night)) {
            applyMode();
        }
        if (night) {
            ImGui::SliderFloat("Beam speed (rad/s)", &beamSpeed, 0.f, 2.f, "%.2f");
            if (ImGui::SliderFloat("Haze density (1/m)", &hazeDensity, 0.f, 0.08f, "%.3f")) {
                renderer.setDeferredVolumetrics(hazeDensity, 0.6f);
            }
        }
        ImGui::Separator();
        ImGui::TextUnformatted("Audio");
        if (sounds.ok) {
            ImGui::Checkbox("Enable##audio", &audioOn);
            ImGui::SliderFloat("Volume##audio", &audioVol, 0.f, 1.f, "%.2f");
        } else {
            ImGui::TextDisabled("Audio unavailable.");
        }
        ImGui::Separator();

        ImGui::TextUnformatted("Underwater fog");
        ImGui::SliderFloat("Density (1/m)", &uwFogDensity, 0.01f, 0.20f, "%.3f");
        ImGui::ColorEdit3("Inscatter tint", uwFogColor,
                          ImGuiColorEditFlags_Float | ImGuiColorEditFlags_NoInputs);
        ImGui::SliderFloat("Anisotropy (g)", &uwFogAniso, -0.95f, 0.95f, "%.2f");
        if (uwDepthSmooth > 0.001f) {
            ImGui::Text("Submerged: %.1f%%", uwDepthSmooth * 100.f);
        } else {
            ImGui::TextDisabled("Camera above water.");
        }

        ImGui::Separator();
        if (ImGui::CollapsingHeader("LIDAR mast (OS0-128, path-traced)")) {
            ImGui::Checkbox("Enable LIDAR",    &lidarEnabled);
            ImGui::SameLine();
            ImGui::Checkbox("Range panel",     &lidarShowPanel);
            ImGui::SliderFloat("Max range (m)##lidar",      &lidarSensor->params.maxRange, 10.f, 250.f);
            ImGui::SliderFloat("Reference range (m)##lidar",&lidarSensor->params.referenceRange, 1.f, 80.f);
            ImGui::SliderFloat("Laser power##lidar",        &lidarSensor->params.laserPower, 0.1f, 10.f);
            ImGui::SliderFloat("Atmospheric ext##lidar",    &lidarSensor->params.atmosphericExtinction, 0.f, 0.05f, "%.4f");
            ImGui::SliderFloat("Detector thresh##lidar",    &lidarSensor->params.detectorThreshold, 0.f, 0.02f, "%.4f");
            {
                // Multi-return through the water surface: maxReturns=2 lets the
                // sensor see the seafloor below the wave crests where the
                // surface Fresnel return doesn't fully attenuate the beam.
                int maxRet = static_cast<int>(lidarSensor->params.maxReturns);
                if (ImGui::SliderInt("Max returns##lidar", &maxRet, 1, 4)) {
                    lidarSensor->params.maxReturns = static_cast<uint32_t>(std::max(1, maxRet));
                }
            }
            {
                // Monte Carlo samples per beam: jitters direction within the
                // beam-divergence cone and uses a fresh RNG stream per sample
                // for the fog scatter. >1 averages volumetric noise and shows
                // the beam's true angular footprint.
                int samples = static_cast<int>(lidarSensor->params.samplesPerBeam);
                if (ImGui::SliderInt("Samples / beam##lidar", &samples, 1, 8))
                    lidarSensor->params.samplesPerBeam = static_cast<uint32_t>(std::max(1, samples));
            }
            ImGui::SliderFloat("Beam divergence (mrad)##lidar",
                               &lidarSensor->params.beamDivergenceMrad, 0.f, 10.f, "%.2f");
            ImGui::TextDisabled("Water column (dedicated LIDAR medium)");
            ImGui::SliderFloat("Extinction (1/m)##wat",
                               &lidarSensor->params.mediumExtinction, 0.f, 1.f, "%.3f");
            ImGui::SliderFloat("Albedo##wat",
                               &lidarSensor->params.mediumAlbedo, 0.f, 1.f, "%.2f");
            ImGui::SliderFloat("Anisotropy g##wat",
                               &lidarSensor->params.mediumAnisotropy, -0.95f, 0.95f, "%.2f");
            ImGui::Text("Returns: %d / %u beams   Scan: %.2f ms",
                        lidarLastReturns,
                        lidarSensor->beamCount(),
                        static_cast<double>(lidarLastScanMs));

            ImGui::Separator();
            ImGui::Checkbox("Show ToF waveform", &lidarShowWave);
            if (lidarShowWave) {
                ImGui::SliderFloat("Pulse FWHM (m)##lidar", &lidarWavParams.pulseFWHM, 0.1f, 5.f, "%.2f");
                const int maxBeam = std::max(0, static_cast<int>(lidarSensor->beamCount()) - 1);
                ImGui::SliderInt("Beam##wave", &lidarWaveBeamIdx, 0, maxBeam);
                // Plot the selected beam's analog waveform.
                const size_t bins = lidarWavParams.bins;
                if (!lidarWaveform.empty()) {
                    const size_t off = static_cast<size_t>(lidarWaveBeamIdx) * bins;
                    if (off + bins <= lidarWaveform.size()) {
                        ImGui::PlotLines("Intensity",
                                         &lidarWaveform[off],
                                         static_cast<int>(bins),
                                         0,
                                         nullptr,
                                         0.f, 1.f,
                                         ImVec2(0, 80));
                        ImGui::TextDisabled("X = distance 0 .. %.1f m", static_cast<double>(lidarWavParams.maxRange));
                    }
                }
            }
        }

        ImGui::Separator();
        settings.drawCollapsed();
        ImGui::End();

        // ── Radar HUD ─────────────────────────────────────────────────────
        // Separate floating window, top-right of the viewport. Heading-up
        // CRT-green scope drawn entirely with ImDrawList primitives over a
        // dark phosphor disc. Range slider lives inside the radar window.
        if (radarOn) {
            const ImGuiViewport* vp = ImGui::GetMainViewport();
            const float radarSize = 260.f;
            ImGui::SetNextWindowPos(ImVec2(vp->WorkPos.x + vp->WorkSize.x - radarSize - 16.f,
                                           vp->WorkPos.y + 16.f));
            ImGui::SetNextWindowSize(ImVec2(radarSize, 0.f));
            ImGui::Begin("Radar", &radarOn,
                         ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoCollapse);
            ImDrawList* dl = ImGui::GetWindowDrawList();
            const ImVec2 cursor = ImGui::GetCursorScreenPos();
            const float scopeDim = radarSize - 16.f;
            const ImVec2 center(cursor.x + scopeDim * 0.5f,
                                cursor.y + scopeDim * 0.5f);
            const float R = scopeDim * 0.5f - 4.f;

            // Bearing → scope screen position. Negated sin keeps the radar's
            // left/right in sync with the chase/side camera (this scene uses
            // left-handed-style boatRight so world +X is on the LEFT of any
            // forward-looking view).
            auto scopePos = [&](float angle, float radius) {
                return ImVec2(center.x - std::sin(angle) * radius,
                              center.y - std::cos(angle) * radius);
            };

            // Background disc (dark CRT phosphor)
            dl->AddCircleFilled(center, R, IM_COL32(8, 24, 8, 235), 64);
            // Range rings — 4 concentric, at 25/50/75/100% of range
            for (int k = 1; k <= 4; ++k) {
                const float r = R * static_cast<float>(k) / 4.f;
                dl->AddCircle(center, r, IM_COL32(0, 130, 0, 200), 64, 1.0f);
            }
            // Cross-hairs (vertical = vessel forward; horizontal = abeam)
            dl->AddLine(ImVec2(center.x, center.y - R), ImVec2(center.x, center.y + R),
                        IM_COL32(0, 90, 0, 160), 1.0f);
            dl->AddLine(ImVec2(center.x - R, center.y), ImVec2(center.x + R, center.y),
                        IM_COL32(0, 90, 0, 160), 1.0f);

            // Sweep wedge: 16 segments, each step wide arc, fading toward
            // the trail end. Correct math: segment k spans [sweep - k·step,
            // sweep - (k+1)·step] where step = trailArc / trailSteps. The
            // earlier double-divide bug packed every triangle on top of the
            // leading edge — fixed now.
            constexpr int   trailSteps = 16;
            constexpr float trailArc   = 1.4f;
            constexpr float step       = trailArc / trailSteps;
            for (int k = 0; k < trailSteps; ++k) {
                const float a0 = radarSweepAngle - static_cast<float>(k) * step;
                const float a1 = radarSweepAngle - static_cast<float>(k + 1) * step;
                const int alpha = static_cast<int>(140.f * (1.f - static_cast<float>(k) / trailSteps));
                dl->AddTriangleFilled(center, scopePos(a0, R), scopePos(a1, R),
                                      IM_COL32(40, 220, 40, alpha));
            }
            // Sweep leading edge — bright line
            dl->AddLine(center, scopePos(radarSweepAngle, R),
                        IM_COL32(140, 255, 140, 255), 1.6f);

            // Blips — halo glow + bright core for the CRT look.
            for (size_t i = 0; i < buoyStates.size() && i < kMaxRadarTargets; ++i) {
                const float a = radarBlipIntensity[i];
                if (a <= 0.01f) continue;
                const float dxw = buoyStates[i].worldX - bs.position.x;
                const float dzw = buoyStates[i].worldZ - bs.position.z;
                const float dist = std::sqrt(dxw * dxw + dzw * dzw);
                if (dist > radarRangeM) continue;
                const float bearing = std::atan2(dxw, dzw) - bs.yaw;
                const float r       = (dist / radarRangeM) * R;
                const ImVec2 pos    = scopePos(bearing, r);
                dl->AddCircleFilled(pos, 7.f,
                                    IM_COL32(120, 255, 120, static_cast<int>(90.f * a)), 14);
                dl->AddCircleFilled(pos, 3.5f,
                                    IM_COL32(200, 255, 200, static_cast<int>(255.f * a)), 12);
            }

            // Own-ship marker (triangle pointing forward = up)
            const float ts = 7.f;
            dl->AddTriangleFilled(
                    ImVec2(center.x,             center.y - ts),
                    ImVec2(center.x - ts * 0.6f, center.y + ts * 0.55f),
                    ImVec2(center.x + ts * 0.6f, center.y + ts * 0.55f),
                    IM_COL32(220, 255, 220, 255));

            // Reserve the drawn area + readouts below.
            ImGui::Dummy(ImVec2(scopeDim, scopeDim));
            ImGui::Text("Range: %.0f m   Heading: %.0f°",
                        radarRangeM, bs.yaw * math::RAD2DEG);
            ImGui::SliderFloat("##rng", &radarRangeM, 100.f, 1000.f, "Range %.0f m");
            ImGui::End();
        }
    });

    IOCapture ioCapture;
    ioCapture.preventMouseEvent    = []() -> bool { return ImGui::GetIO().WantCaptureMouse; };
    ioCapture.preventScrollEvent   = []() -> bool { return ImGui::GetIO().WantCaptureMouse; };
    ioCapture.preventKeyboardEvent = []() -> bool { return ImGui::GetIO().WantCaptureKeyboard; };
    canvas.setIOCapture(&ioCapture);

    canvas.onWindowResize([&](const WindowSize& ns) {
        renderer.setSize(ns);
        camera.aspect = canvas.aspect();
        camera.updateProjectionMatrix();
    });

    Clock clock;
    auto lidarIntensityColor = [](float intensity, Color& col) {
        const float t = std::clamp(intensity * 3.f, 0.f, 1.f);
        col.setHSL((1.f - t) * 0.66f, 1.f, 0.5f);
    };

    canvas.animate([&] {
        const float dt = std::min(clock.getDelta(), 0.1f);  // clamp dt — pause / breakpoints shouldn't teleport the boat
        fpsAccum += dt;
        ++fpsFrames;
        if (fpsAccum >= 0.5f) {
            fps = fpsFrames / fpsAccum;
            fpsAccum = 0.f;
            fpsFrames = 0;
        }

        // === Boat steering & propulsion ===
        // Both modes only produce rudder/throttle COMMANDS; the shared
        // actuator + dynamics integration below turns them into motion.
        // The autopilot is a helmsman, not a teleport: it chases a pure-
        // pursuit look-ahead point on the nav curve with a PD heading
        // controller, so the boat heels, drifts and bleeds speed through
        // turns exactly as it does under manual control (and cuts the
        // corners a real helm would).
        float rudderCmd = 0.f, throttleCmd = 0.f;
        if (autoPilot && navCurveLength > 1e-3f) {
            // Advance the pursuit target along the curve until it sits
            // kLookAhead metres from the hull. getPointAt is arc-length
            // parameterised, so stepU advances ~2 m per iteration; the guard
            // bounds the catch-up after a long pause or a manual excursion.
            constexpr float kLookAhead = 40.f;
            Vector3 tgt;
            navCurve.getPointAt(autoU, tgt);
            const float stepU = 2.f / navCurveLength;
            for (int guard = 0; guard < 64; ++guard) {
                const float dx = tgt.x - bs.position.x;
                const float dz = tgt.z - bs.position.z;
                if (dx * dx + dz * dz >= kLookAhead * kLookAhead) break;
                autoU = std::fmod(autoU + stepU, 1.f);
                navCurve.getPointAt(autoU, tgt);
            }
            const float desiredYaw = std::atan2(tgt.x - bs.position.x,
                                                tgt.z - bs.position.z);
            float err = desiredYaw - bs.yaw;
            while (err >  math::PI) err -= 2.f * math::PI;
            while (err < -math::PI) err += 2.f * math::PI;
            // PD: P on heading error, D on yaw rate (counter-rudder — checks
            // the swing early instead of S-curving across the track).
            rudderCmd   = std::clamp(1.0f * err - 2.5f * bs.yawRate,
                                     -kRudderMax, kRudderMax);
            throttleCmd = std::clamp((autoCruiseSpeed - bs.forwardSpeed) * 0.6f,
                                     -0.3f, 1.f);
        } else {
            // Manual: A/D order the rudder hard-over (it slews there at the
            // actuator rate), W/S open the telegraph ahead/astern. Released
            // keys recentre the helm and ring the engine back to stop — the
            // hull then coasts on its own inertia against quadratic drag.
            rudderCmd   = ((bi.A ? 1.f : 0.f) - (bi.D ? 1.f : 0.f)) * kRudderMax;
            throttleCmd = bi.W ? 1.f : (bi.S ? -1.f : 0.f);
        }

        // Actuators. Rudder slews at a fixed rate; the engine spools faster
        // than it winds down (turbo lag vs shaft inertia, mirrors the audio).
        auto slewTo = [dt](float v, float tgt, float rate) {
            const float d = tgt - v;
            const float step = rate * dt;
            return std::abs(d) <= step ? tgt : v + std::copysign(step, d);
        };
        bs.rudder   = slewTo(bs.rudder, rudderCmd, kRudderRate);
        bs.throttle = slewTo(bs.throttle, throttleCmd,
                             throttleCmd > bs.throttle ? 0.5f : 0.35f);

        // Yaw — first-order Nomoto model: the rudder commands a steady-state
        // turn rate ∝ flow over the blade (hull speed + prop wash, so a burst
        // of ahead throttle kick-turns a stationary boat); the hull reaches it
        // with time constant T ≈ L/u.
        const float flow    = bs.forwardSpeed + kPropWash * std::max(bs.throttle, 0.f);
        const float rTarget = kTurnGain * flow * bs.rudder;
        const float Tyaw    = std::clamp(kBoatLength / std::max(std::abs(bs.forwardSpeed), 1.5f), 2.f, 7.f);
        bs.yawRate += (rTarget - bs.yawRate) * std::min(dt / Tyaw, 1.f);
        bs.yaw     += bs.yawRate * dt;

        // Surge: thrust vs quadratic hull drag, plus the extra resistance of
        // a deflected hull in a turn. Sway: centripetal coupling pushes the
        // hull outward through a turn; lateral drag bleeds it off again.
        const float thrust = kMaxAccel * (bs.throttle > 0.f ? bs.throttle
                                                            : kAsternFrac * bs.throttle);
        const float u = bs.forwardSpeed;
        bs.forwardSpeed += (thrust
                            - kDragQuad * u * std::abs(u)
                            - kTurnDrag * std::abs(bs.yawRate) * u) * dt;
        bs.forwardSpeed = std::clamp(bs.forwardSpeed, -4.f, kMaxSpeed + 0.5f);
        bs.swaySpeed += (-kSwayCouple * u * bs.yawRate - kSwayDamp * bs.swaySpeed) * dt;

        // Position: world velocity = heading·u + lateral·v. Convention:
        // yaw=0 → +Z forward, lateral basis (cosY, −sinY).
        float cosY = std::cos(bs.yaw);
        float sinY = std::sin(bs.yaw);
        bs.position.x += (sinY * bs.forwardSpeed + cosY * bs.swaySpeed) * dt;
        bs.position.z += (cosY * bs.forwardSpeed - sinY * bs.swaySpeed) * dt;

        // Grounding: the archipelago sills top out ~2 m below the surface and
        // the shores shoal up — once the island height field rises above keel
        // depth the hull scrubs off its way fast. (The sand floor of the bay
        // sits at −5 m, so open water never triggers this.)
        bs.aground = island::heightAt(bs.position.x, bs.position.z) > -kDraft;
        if (bs.aground) {
            const float g = std::exp(-3.f * dt);
            bs.forwardSpeed *= g;
            bs.swaySpeed    *= g;
            bs.yawRate      *= g;
        }

        // === Hydrodynamics from sampled wave surface ===
        // Sample 5 points: centre + four corners of the bounding rectangle.
        // Heave (Y) follows the centre; pitch comes from fore/aft height
        // diff over hull length; roll from port/starboard diff over beam.
        //
        // Cascade mask 0b011 = swells + mid-frequency only; skip cascade 2
        // (4-8 m chop). A 28 m hull doesn't physically pitch on wavelengths
        // shorter than itself — those waves wash under harmlessly. Reading
        // them at bow and stern gave the boat a "car on rocks" feel.
        // Visuals are unaffected — the GPU still renders all three cascades.
        constexpr uint32_t kBuoyancyMask = 0b011u;
        const float halfL = kBoatLength * 0.5f;
        const float halfB = kBoatBeam   * 0.5f;
        auto sampleH = [&](float dx, float dz) {
            // Local (forward, right) → world via yaw rotation
            const float wx = bs.position.x + sinY * dz + cosY * dx;
            const float wz = bs.position.z + cosY * dz - sinY * dx;
            return ocean->sampleHeight(wx, wz, kBuoyancyMask);
        };
        const float hCentre = sampleH(0.f,    0.f);
        const float hBow    = sampleH(0.f,  +halfL);
        const float hStern  = sampleH(0.f,  -halfL);
        const float hPort   = sampleH(-halfB, 0.f);
        const float hStbd   = sampleH(+halfB, 0.f);
        // Positive pitch = bow up (right-hand rotation around local X).
        // Speed trim added on top: a displacement hull squats stern-down
        // (bow up ~1°) as it approaches hull speed.
        const float trimNorm = bs.forwardSpeed / kMaxSpeed;
        const float pitch = std::atan2(hBow  - hStern, kBoatLength)
                          + kSpeedTrim * trimNorm * std::abs(trimNorm);
        // Positive roll = starboard down (right-hand rotation around local Z,
        // which under +Z forward convention means starboard side dips).
        // Turn heel added on top: a surface ship heels OUTWARD in a turn
        // (centre of gravity above the lateral pressure centre), ∝ the
        // centripetal acceleration u·r. Both inputs are already first-order
        // states, so the heel builds and releases smoothly with the turn.
        const float roll  = std::atan2(hStbd - hPort,  kBoatBeam)
                          - kTurnHeel * bs.forwardSpeed * bs.yawRate;

        // Pitch / roll: temporal low-pass at ~1 Hz so attitude rides the
        // swells but doesn't snap to wave-pumping at hull-traversal rates.
        // alpha = 1 − exp(−2π · cutoff · dt). With cascade 2 masked out
        // the input is already smoother; 1 Hz cutoff (was 3 Hz) is the
        // additional damping that finishes off the rock-terrain feel.
        const float alpha = 1.f - std::exp(-math::TWO_PI * dt);
        bs.smoothPitch += (pitch - bs.smoothPitch) * alpha;
        bs.smoothRoll  += (roll  - bs.smoothRoll)  * alpha;

        // Heave: spring-damped follower instead of a 1:1 height tracker.
        // A real hull's vertical motion is bounded by buoyancy + mass +
        // hydrodynamic drag; tracking the wave surface exactly looked like
        // a yo-yo riding the crests. Tuning: ω ≈ 0.8 Hz natural frequency
        // (k = (2π·f)²), damping ratio ζ ≈ 0.7 (slightly under-damped → one
        // gentle overshoot then settles). Yields a believable "settling on
        // a wave" rhythm where the boat lags the surface a beat.
        const float omega = math::TWO_PI * 0.8f;
        const float k     = omega * omega;
        const float c     = 2.f * 0.7f * omega;
        const float yErr  = hCentre - bs.y;
        const float accel = yErr * k - bs.vY * c;
        bs.vY += accel * dt;
        bs.y  += bs.vY * dt;

        // Apply transforms. Euler order YXZ — yaw first, then pitch about
        // the post-yaw local X, then roll about the post-yaw-pitch local Z;
        // i.e. the standard ship-attitude convention.
        // Pitch is NEGATED: in three.js, positive Euler.x rotation around
        // local +X tilts +Z forward toward −Y (bow DOWN) by right-hand
        // rule. Our `pitch` is positive when bow is on a crest, so we want
        // bow UP — flip the sign here.
        // The +0.5 m bias raises the hull origin above the waterline so
        // the deck reads above the wave surface (Gunnerus's bbox centres
        // around the waterline).
        boat->position.set(bs.position.x, bs.y - 0.2f, bs.position.z);
        boat->rotation.set(-bs.smoothPitch, bs.yaw, bs.smoothRoll, Euler::YXZ);

        // LIDAR mast: tracks the boat with a vertical offset for wheelhouse
        // clearance + a forward offset so the sensor sits near the bow
        // (otherwise the wheelhouse occludes the rear half of the scan and
        // the forward 180° starts blocked by the hull's superstructure).
        // Inherits pitch + yaw so the beam pattern sweeps with the hull;
        // roll is intentionally damped so the range panel stays readable
        // when the boat heels.
        //
        // The +π yaw offset reconciles two competing forward conventions:
        // the boat moves along (sinY, 0, +cosY) at yaw=0, but the
        // LidarModel puts azimuth=0 along sensor-local -Z so its forward
        // is (-sinY, 0, -cosY) before the offset. Rotating by π makes the
        // sensor look in the direction the boat is heading.
        lidarSensor->position.set(bs.position.x + sinY * kLidarMountForward,
                                  bs.y + kLidarMountHeight,
                                  bs.position.z + cosY * kLidarMountForward);
        lidarSensor->rotation.set(-bs.smoothPitch * 0.5f,
                                  bs.yaw + math::PI,
                                  0.f, Euler::YXZ);

        // Track the live wave height under the boat so the LIDAR water
        // column clamp matches the actual sea surface. Beams crossing
        // this Y get water-column extinction; segments above stay in
        // air and pass through unattenuated.
        lidarSensor->params.mediumSurfaceY = ocean->sampleHeight(bs.position.x, bs.position.z);
        lidarCloud->visible = lidarEnabled;
        lidarPanel->visible = lidarEnabled && lidarShowPanel;

        ocean->hullExclusion.centerX    = bs.position.x;
        ocean->hullExclusion.centerZ    = bs.position.z;
        ocean->hullExclusion.halfLength = kBoatLength * 0.5f;
        ocean->hullExclusion.halfBeam   = kBoatBeam * 0.5f;
        ocean->hullExclusion.sinYaw     = sinY;
        ocean->hullExclusion.cosYaw     = cosY;

        // Adaptive vertex density follows the vessel. The 1 km × 512² grid
        // is uniform-natural at ~1.96 m spacing; the cubic warp packs it
        // toward the boat to roughly 0.15 m at the centre while edge
        // spacing only grows to ~2.7 m. Vertex history (foam) is in a
        // world-space texture now, so vertices reflowing per frame is
        // realism-safe — wake trails stay where they were deposited.
        ocean->warp.centerX   = bs.position.x;
        ocean->warp.centerZ   = bs.position.z;
        ocean->warp.halfRange = kPlaneEdge * 0.5f;
        ocean->warp.coefA     = 0.1f;

        // Vessel wake — analytical foam trail + bow bump + Kelvin V-wake
        // injected in water_displace.comp from the same pose plus speed.
        // The Kelvin V-wake additionally uses a historical sample trail
        // so it traces the boat's actual sailed curve through turns,
        // instead of snapping to the current heading every frame. Trail
        // is maintained below: emit at 10 Hz (or every 1 m travelled),
        // drop samples older than 6 s, cap at the renderer's
        // kMaxWakeSamples (64) — that's ~36 m of path at the 6 m/s cruise,
        // enough curved history to bend the V-wake through the boat's turns.
        ocean->wake.forwardSpeed = bs.forwardSpeed;
        {
            constexpr float kEmitInterval     = 0.10f;     // 10 Hz cadence
            constexpr float kEmitDistance     = 1.0f;      // also emit on > 1 m travel
            constexpr float kMaxAge           = 6.0f;      // seconds
            constexpr size_t kMaxSamples      = 64;
            static float emitAccum = 0.f;
            static float lastEmitX = std::numeric_limits<float>::quiet_NaN();
            static float lastEmitZ = std::numeric_limits<float>::quiet_NaN();

            // Age all samples and drop expired ones.
            auto& trail = ocean->wake.trail;
            for (auto& s : trail) s.age += dt;
            trail.erase(std::remove_if(trail.begin(), trail.end(),
                                       [](const DisplacedMesh::WakeSample& s){
                                           return s.age > kMaxAge;
                                       }),
                        trail.end());

            // Emit a new sample on whichever fires first: cadence elapsed
            // OR the boat has travelled > kEmitDistance since the last
            // emission. The distance trigger gives an immediate sample
            // when the boat speeds up from rest (no 100 ms gap of missing
            // wake while emitAccum builds), and the cadence keeps the
            // trail well-sampled during steady-state cruising.
            emitAccum += dt;
            const float spd = std::abs(bs.forwardSpeed);
            const float dxLast = std::isnan(lastEmitX) ? 1e9f : (bs.position.x - lastEmitX);
            const float dzLast = std::isnan(lastEmitZ) ? 1e9f : (bs.position.z - lastEmitZ);
            const float distLast = std::sqrt(dxLast * dxLast + dzLast * dzLast);
            const bool shouldEmit = spd > 0.3f &&
                                    (emitAccum >= kEmitInterval ||
                                     distLast >= kEmitDistance);
            if (shouldEmit) {
                emitAccum = 0.f;
                lastEmitX = bs.position.x;
                lastEmitZ = bs.position.z;
                if (trail.size() >= kMaxSamples) {
                    trail.erase(trail.begin());// drop oldest
                }
                DisplacedMesh::WakeSample s{};
                s.worldX = bs.position.x;
                s.worldZ = bs.position.z;
                s.sinYaw = sinY;
                s.cosYaw = cosY;
                s.speed  = bs.forwardSpeed;
                s.age    = 0.f;
                trail.push_back(s);
            }
        }

        // Hull-contact foam disturbances. Splats gaussian foam blobs along
        // the port + starboard hull perimeter (where the hull pushes water
        // aside at the waterline) and an extra one off the stern for prop
        // wash when the boat is moving. Decays naturally via the existing
        // foam decay (~1.4 s half-life), so a fast-moving boat leaves a
        // visible trail of agitated water in addition to the analytical
        // wake foam. Always-on perimeter base intensity even at zero speed
        // — the hull still displaces water, just less dramatically.
        ocean->clearFoamDisturbances();
        {
            const float L = kBoatLength * 0.5f;
            const float B = kBoatBeam   * 0.5f;
            const float spd = std::abs(bs.forwardSpeed);
            const float speedNorm = std::clamp(spd / 4.0f, 0.0f, 1.0f);
            const float baseI     = 0.4f + 0.55f * speedNorm;
            // Analytical hull plan-form half-width at fraction t ∈ [0,1]
            // along the length (0 = bow, 1 = stern). Bow is sharp (≈0 at
            // tip) so foam pinches to the centreline at the prow rather
            // than sitting on the bbox front corners; stern keeps ~75 %
            // beam (Gunnerus has a roughly transom aft form). Without
            // this taper the perimeter splats below sit on the corners
            // of the 28×9 bounding box and read as a rectangular foam
            // outline that doesn't match the hull silhouette.
            auto hullHalfWidth = [B](float t) -> float {
                const float u = 2.0f * t - 1.0f;          // -1 at bow, +1 at stern
                if (u <= 0.0f) {
                    // Elliptical bow with sharpening exponent < 1 — pinches
                    // tighter toward the tip than a pure ellipse would.
                    const float k = 1.0f - u * u;          // 0 at bow tip, 1 amidships
                    return B * std::pow(k, 0.6f);
                }
                // Stern: stays near full beam, fading slightly toward the transom.
                return B * (1.0f - 0.25f * u * u);
            };
            // 8 points each side, bow → stern. Splats are positioned just
            // outside the tapered hull silhouette (+0.2 m offset) so their
            // gaussian halos paint visible foam on the surrounding ocean
            // rather than on the flat hull-excluded zone below the boat.
            // Spacing ≈ 4 m at midship × radius 1.6 m gives partial overlap
            // along the length so the foam reads as a continuous band.
            constexpr int   kSamples = 8;
            constexpr float kRadius  = 1.6f;
            for (int side = -1; side <= 1; side += 2) {
                for (int i = 0; i < kSamples; ++i) {
                    const float t       = static_cast<float>(i) / static_cast<float>(kSamples - 1);
                    const float localZ  = L - 2.0f * L * t;       // +L (bow) → -L (stern)
                    const float localX  = static_cast<float>(side) * (hullHalfWidth(t) + 0.2f);
                    const float worldX  = bs.position.x + cosY * localX + sinY * localZ;
                    const float worldZ  = bs.position.z - sinY * localX + cosY * localZ;
                    ocean->addFoamDisturbance(worldX, worldZ, kRadius, baseI);
                }
            }
            // Prop wash: larger, brighter splat just behind the stern.
            // Only active when actually moving — a docked boat shouldn't
            // be churning. The +0.5m localZ offset puts it just aft of
            // the hull rectangle so it doesn't fight hull exclusion.
            if (speedNorm > 0.1f) {
                const float localZ  = -L - 1.0f;
                const float worldX  = bs.position.x + sinY * localZ;
                const float worldZ  = bs.position.z + cosY * localZ;
                const float propI   = std::min(0.7f + 0.4f * speedNorm, 1.0f);
                ocean->addFoamDisturbance(worldX, worldZ, 3.0f, propI);
            }
        }

        // ── Buoy buoyancy ──────────────────────────────────────────────────
        // Each buoy spring-damps toward the wave height at its fixed waypoint
        // position. Stiffer than the boat (1.6 Hz natural freq vs 0.8) so the
        // small bodies track chop visibly; under-damped (ζ=0.55) so they get
        // a subtle bob after a crest passes through. Same buoyancy cascade
        // mask as the boat (swells + mid; cascade-2 chop is too fine to push
        // a buoy meaningfully).
        if (!buoyStates.empty() && buoyRoot) {
            constexpr float kBuoyOmega = math::TWO_PI * 1.6f;
            constexpr float kBuoyK     = kBuoyOmega * kBuoyOmega;
            constexpr float kBuoyC     = 2.f * 0.55f * kBuoyOmega;
            for (size_t i = 0; i < buoyStates.size(); ++i) {
                BuoyState& s = buoyStates[i];
                const float h = ocean->sampleHeight(s.worldX, s.worldZ, kBuoyancyMask)
                              + ocean->sampleWakeHeight(s.worldX, s.worldZ);
                const float err = h - s.worldYOffset;
                const float accel = err * kBuoyK - s.vY * kBuoyC;
                s.vY += accel * dt;
                s.worldYOffset += s.vY * dt;
                Vector3 dLocal(0.f, s.worldYOffset, 0.f);
                dLocal.applyMatrix3(buoyInvRotScale);
                auto* child = buoyRoot->children[i];
                child->position.copy(s.baseLocal).add(dLocal);
            }
        }

        // ── Radar sweep + blip update ─────────────────────────────────────
        // Sweep advances clockwise (positive angle from "up" = forward).
        // For each target (buoys only here), compute heading-up bearing and
        // check if the sweep just crossed it this frame. When it crosses,
        // set the blip intensity = range-attenuated strength; otherwise
        // decay toward zero. The ImGui block below renders the scope.
        if (radarOn) {
            const float prevSweep = radarSweepAngle;
            const float twoPi     = math::TWO_PI;
            const float omega     = twoPi / kRadarSweepPeriod;
            radarSweepAngle = std::fmod(radarSweepAngle + omega * dt, twoPi);
            const float decay     = std::exp(-dt / kRadarBlipTau);
            // Helper: does the angle `tgt` ∈ [0, 2π) fall in the swept arc
            // (prev → curr)? Handles wraparound (prev > curr).
            auto inSweep = [&](float prev, float curr, float tgt) {
                if (prev <= curr) return tgt >= prev && tgt <= curr;
                return tgt >= prev || tgt <= curr;
            };
            for (size_t i = 0; i < buoyStates.size() && i < kMaxRadarTargets; ++i) {
                const float dxw = buoyStates[i].worldX - bs.position.x;
                const float dzw = buoyStates[i].worldZ - bs.position.z;
                const float dist = std::sqrt(dxw * dxw + dzw * dzw);
                radarBlipIntensity[i] *= decay;
                if (dist > radarRangeM) continue;
                // Heading-up bearing: world-bearing − yaw, wrapped to [0, 2π).
                float bearing = std::atan2(dxw, dzw) - bs.yaw;
                bearing = std::fmod(bearing, twoPi);
                if (bearing < 0.f) bearing += twoPi;
                if (inSweep(prevSweep, radarSweepAngle, bearing)) {
                    // Range-attenuated echo: 1 close, ~0.3 at the edge.
                    const float r01 = dist / radarRangeM;
                    const float strength = std::clamp(1.f - 0.7f * r01, 0.3f, 1.f);
                    radarBlipIntensity[i] = std::max(radarBlipIntensity[i], strength);
                }
            }
        }

        // ── Auto-cam timer ────────────────────────────────────────────────
        // When enabled, cycle through every camera mode every `autoCamHold`
        // seconds. Skip Free — its position is owned by OrbitControls and
        // re-entering it mid-cycle just shows the user's last orbit. Start
        // the cycle at SideFixed (1) so the first auto switch from Free
        // doesn't snap straight back to Free.
        if (autoCam) {
            autoCamElapsed += dt;
            if (autoCamElapsed >= autoCamHold) {
                autoCamElapsed = 0.f;
                int next = static_cast<int>(camMode) + 1;
                if (next >= kCamModeCount) next = 1;
                if (next == 0) next = 1;
                camMode = static_cast<CamMode>(next);
            }
        }

        // ── Camera pose per mode ──────────────────────────────────────────
        // Boat basis vectors (yaw-only — pitch/roll come from wave tilt but
        // we deliberately ignore them for camera framing so the horizon
        // doesn't wobble in side/chase modes; that's how real-world doc /
        // chase footage is shot too).
        const Vector3 boatFwd{sinY, 0.f, cosY};
        const Vector3 boatRight{cosY, 0.f, -sinY};
        const Vector3 boatPos{bs.position.x, bs.y, bs.position.z};
        switch (camMode) {
            case CamMode::Free: {
                // Existing behavior: orbit target tracks the boat; controls
                // own the position. User drags / scrolls to compose.
                controls.target.set(boatPos.x, boatPos.y, boatPos.z);
                controls.update();
                break;
            }
            case CamMode::SideFixed: {
                // Starboard rail, just above the deck, looking forward.
                // Offset: half-beam + a bit outboard, ~3 m above mean water,
                // 2 m forward of midships so the bow + bow-wave are visible.
                const Vector3 camPos = boatPos
                                      + boatRight * (kBoatBeam * 0.5f + 1.0f)
                                      + Vector3(-2.f, 5.0f, -2.f)
                                      + boatFwd * 2.0f;
                // Look ~50 m ahead along the heading, slightly down so the
                // horizon sits in the upper third (cinematic framing).
                const Vector3 lookAt = boatPos
                                       + boatFwd * 50.0f
                                       + Vector3(0.f, -2.0f, 0.f);
                camera.position.copy(camPos);
                camera.lookAt(lookAt);
                break;
            }
            case CamMode::Chase: {
                // Behind + above, looking at the boat. Tuned so the boat
                // occupies ~⅓ of the vertical frame at this FOV.
                const Vector3 camPos = boatPos
                                      - boatFwd * 32.0f
                                      + Vector3(0.f, 12.0f, 0.f);
                const Vector3 lookAt = boatPos + Vector3(0.f, 2.0f, 0.f);
                camera.position.copy(camPos);
                camera.lookAt(lookAt);
                break;
            }
            case CamMode::Underwater: {
                // Below the surface near the boat, looking forward and
                // slightly up so god rays from the sun are visible and
                // the caustic pattern on the sand floor is in frame.
                const Vector3 camPos = boatPos
                                      - boatFwd * 15.0f
                                      + Vector3(0.f, -3.0f, 0.f);
                const Vector3 lookAt = boatPos
                                      + boatFwd * 20.0f
                                      + Vector3(0.f, -1.0f, 0.f);
                camera.position.copy(camPos);
                camera.lookAt(lookAt);
                break;
            }
            case CamMode::NearestBuoy: {
                // Find the buoy closest to the current boat position and
                // perch the camera right next to it, looking at the boat.
                // As the boat moves through the waypoint loop this naturally
                // hands off from one buoy to the next — the camera tracks
                // whichever marker is currently nearest.
                int   nearest    = -1;
                float nearestSq  = 1e30f;
                for (size_t i = 0; i < buoyStates.size(); ++i) {
                    const float dx = buoyStates[i].worldX - bs.position.x;
                    const float dz = buoyStates[i].worldZ - bs.position.z;
                    const float d2 = dx * dx + dz * dz;
                    if (d2 < nearestSq) {
                        nearestSq = d2;
                        nearest   = static_cast<int>(i);
                    }
                }
                if (nearest >= 0) {
                    const float bx = buoyStates[nearest].worldX;
                    const float bz = buoyStates[nearest].worldZ;
                    // Offset 3 m behind the buoy (toward the boat) and 2.5 m
                    // up so the buoy sits in the foreground with the boat
                    // visible past it. "Behind" = direction from boat to buoy
                    // continued past the buoy by a small amount.
                    const float dxw = bx - bs.position.x;
                    const float dzw = bz - bs.position.z;
                    const float dlen = std::max(std::sqrt(dxw * dxw + dzw * dzw), 1e-3f);
                    const float ux = dxw / dlen, uz = dzw / dlen;
                    const Vector3 camPos(bx + ux * 3.0f,
                                         2.5f,
                                         bz + uz * 3.0f);
                    const Vector3 lookAt(bs.position.x, bs.y + 1.0f, bs.position.z);
                    camera.position.copy(camPos);
                    camera.lookAt(lookAt);
                } else {
                    // No buoys (fallback path took over earlier) — degrade
                    // to a Chase-style framing rather than leaving the camera
                    // stranded at its last pose.
                    const Vector3 camPos = boatPos
                                          - boatFwd * 32.0f
                                          + Vector3(0.f, 12.0f, 0.f);
                    const Vector3 lookAt = boatPos + Vector3(0.f, 2.0f, 0.f);
                    camera.position.copy(camPos);
                    camera.lookAt(lookAt);
                }
                break;
            }
        }

        // ── Lighthouse beam sweep ─────────────────────────────────────────
        if (capturing) {
            // Deterministic capture aim: steeper + into the FRAMED water so
            // the lit pool lands in-shot (~135 m out, centre-right).
            beamAngle = -1.1f;
        } else {
            beamAngle += beamSpeed * dt;
        }
        if (night) {
            if (capturing) {
                beamTarget.position.set(std::cos(beamAngle) * 150.f, -2.f,
                                        std::sin(beamAngle) * 150.f);
            } else {
                beamTarget.position.set(std::cos(beamAngle) * 300.f, -4.f,
                                        std::sin(beamAngle) * 300.f);
            }
            // Spot origin at the lamp glass's OUTER face along the beam — never
            // inside the housing, so no self-geometry can occlude the beam's
            // shadow rays regardless of emissive thresholds.
            const Vector3 lampPos(0.f, 20.3f, 0.f);
            Vector3 beamDir = beamTarget.position;
            beamDir.sub(lampPos).normalize();
            beam->position.copy(lampPos).addScaledVector(beamDir, 1.7f);
        }
        // The lamp hood's window tracks the beam azimuth (cylinder θ=0 is
        // local +Z; the beam dir is (cos A, sin A) in XZ → yaw = π/2 − A), so
        // the lantern's emissive flare points where the spot does. The optic
        // keeps turning by day too, visible inside the glass.
        if (lensHood) lensHood->rotation.y = math::PI / 2.f - beamAngle;

        // ── Underwater fog activation ─────────────────────────────────────
        // Sample the wave height at the camera's XZ position. If the camera
        // is below the surface, enable homogeneous fog (participating media)
        // — this activates the renderer's volumetric-fog in-scatter path
        // (single scattering with an HG phase; setFogAnisotropy drives the
        // asymmetry). A 0.5 m ramp smooths the transition at the waterline.
        {
            const float waveH = ocean->sampleHeight(camera.position.x,
                                                    camera.position.z);
            const float submerge = waveH - camera.position.y;
            const float target = std::clamp(submerge / 0.5f, 0.f, 1.f);
            // Temporal smoothing so the fog doesn't flash when waves wash
            // over the camera near the waterline (~4 Hz cutoff).
            const float fogAlpha = 1.f - std::exp(-math::TWO_PI * 4.f * dt);
            uwDepthSmooth += (target - uwDepthSmooth) * fogAlpha;

            if (uwDepthSmooth > 0.001f) {
                const float d = uwFogDensity * uwDepthSmooth;
                scene.fog = FogExp2(
                        Color(uwFogColor[0], uwFogColor[1], uwFogColor[2]), d);
                renderer.setFogAnisotropy(uwFogAniso);
                renderer.setFogWaterSurfaceY(waveH);
            } else {
                scene.fog = std::nullopt;
                renderer.setFogWaterSurfaceY(1e30f);
            }
        }

        // ── Sound update ──────────────────────────────────────────────────
        // After the camera pose (listener follows it) and the underwater fog
        // (uwDepthSmooth ducks the above-surface ambience). Engine source
        // sits at the stern, just above the waterline by the prop wash.
        {
            const Vector3 sternWorld = boatPos - boatFwd * (kBoatLength * 0.45f) + Vector3(0.f, 1.0f, 0.f);
            // Telegraph state covers both modes now — the autopilot works the
            // same throttle, so the engine note tracks what the prop is doing.
            const bool thrusting = std::abs(bs.throttle) > 0.05f;
            sounds.update(dt, sternWorld, bs.forwardSpeed, thrusting,
                          uwDepthSmooth, camera, audioOn ? audioVol : 0.f);
        }

        if (capturing) {
            if (capArgs.camPos && capArgs.camTarget) {
                // --cam/--look override (capture_util): reframe any capture from
                // the CLI with no rebuild — highest priority over the named shots.
                camera.position.copy(*capArgs.camPos);
                camera.lookAt(*capArgs.camTarget);
            } else if (shotClose) {
                // Near-surface grazing view beside the boat, looking across
                // its wake — the high-foam-coverage region where close-up
                // world-grid surface artifacts (foam texels, normal facets)
                // are magnified to screen-filling size.
                const Vector3 side = Vector3(boatFwd.z, 0.f, -boatFwd.x);
                // Keep the camera MOVING (slow sideways strafe) — temporal
                // history (TAA / reflection accumulation) never converges,
                // matching interactive flying where the tile artifact shows.
                camera.position.copy(boatPos)
                        .addScaledVector(boatFwd, -10.f)
                        .addScaledVector(side, 9.f + 0.04f * static_cast<float>(shotFrame))
                        .add(Vector3(0.f, 2.5f, 0.f));
                Vector3 tgt = boatPos;
                tgt.addScaledVector(boatFwd, -45.f);// far into the wake — near-horizontal grazing
                tgt.y = 0.5f;
                camera.lookAt(tgt);
            } else if (shotVista) {
                // High oblique overview: lighthouse centre, archipelago ring,
                // passes and the far shore all in frame.
                camera.position.set(300.f, 220.f, 520.f);
                camera.lookAt(Vector3(0.f, 0.f, -60.f));
            } else if (shotIsland) {
                // Low, close view across the water at the −X archipelago
                // island — frames the forest / treeline / snow / waterfall
                // banding and the new sub-metre rock relief for detail capture.
                camera.position.set(-200.f, 15.f, 30.f);
                camera.lookAt(Vector3(-460.f, 30.f, 10.f));
            } else if (night) {
                // Night framing: low camera toward the lighthouse + horizon —
                // sky (stars), beam fan, and lit water all in shot.
                camera.position.set(70.f, 7.f, 110.f);
                camera.lookAt(Vector3(0.f, 14.f, 0.f));
            } else {
                // Day framing (≈ the reported-artifact view): boat centre,
                // mostly water in frame, horizon out of shot.
                camera.position.set(10.f, 32.f, 50.f);
                camera.lookAt(Vector3(0.f, 0.f, -20.f));
            }
            camera.updateMatrixWorld();
        }

        renderer.render(scene, camera);

        // --profile (capture_util): per-pass GPU/CPU timings as JSON. Headless
        // this makes perf measurable (e.g. the cost of a geometry/texture bump)
        // instead of eyeballed; interactive, throttle to ~once a second.
        if (capArgs.profile) {
            static int profCount = 0;
            if (capturing || ++profCount % 60 == 0)
                capture::writeFrameTimings(renderer.lastFrameTimings(), capArgs, shotFrame);
        }

        // F12: interactive screenshot → aaa_caps/usershot_N.png. Native-res
        // ground truth for artifact reports — screen captures of the window
        // get rescaled/compressed and hide texel-scale structure.
        if (bi.shotRequest) {
            bi.shotRequest = false;
            static int userShotN = 0;
            const auto path = std::filesystem::path(PROJECT_FOLDER) / "aaa_caps" /
                              ("usershot_" + std::to_string(userShotN++) + ".png");
            try {
                renderer.writeFramebuffer(path);
                std::printf("wrote %s\n", path.string().c_str());
            } catch (const std::exception& e) {
                std::cerr << "[shot] failed: " << e.what() << "\n";
            }
        }

        if (capturing && toggleNightAt > 0 && shotFrame == toggleNightAt) {
            night = true;// runtime day→night flip — the path the UI checkbox takes
            applyMode();
        }
        if (capturing && ++shotFrame >= shotFrames) {
            const auto path = std::filesystem::path(PROJECT_FOLDER) / "aaa_caps" / shotPath;
            renderer.writeFramebuffer(path);// creates parent dirs; throws on failure
            std::printf("wrote %s\n", path.string().c_str());
            std::exit(0);
        }

        // ── LIDAR scan + visualisation update ─────────────────────────────
        // Must follow render() so the TLAS is built; the cloud/panel show
        // last frame's data when re-rendered next frame.
        if (lidarEnabled) {
            const auto t0 = std::chrono::steady_clock::now();
            lidarSensor->scan(renderer, lidarReturns);
            const auto t1 = std::chrono::steady_clock::now();
            lidarLastScanMs = std::chrono::duration<float, std::milli>(t1 - t0).count();

            // Cloud refresh.
            auto* cloudPos = lidarCloudGeom->getAttribute<float>("position");
            auto* cloudCol = lidarCloudGeom->getAttribute<float>("color");
            int vi = 0;
            Color col;
            int validHits = 0;
            for (const auto& r : lidarReturns) {
                if (r.returnNo <= 0) continue;// miss / sub-threshold
                ++validHits;
                if (vi >= cloudPos->count()) break;
                lidarIntensityColor(r.intensity, col);
                cloudPos->setXYZ(vi, r.position.x, r.position.y, r.position.z);
                cloudCol->setXYZ(vi, col.r, col.g, col.b);
                ++vi;
            }
            lidarCloudGeom->setDrawRange(0, vi);
            cloudPos->needsUpdate();
            cloudCol->needsUpdate();
            lidarLastReturns = validHits;

            // Panel refresh — (azimuth × elevation) grid filled in blocks so
            // the linear sprite sampler doesn't blend bright cells with
            // empty rows. The Ouster pattern uses 1028 azimuth × 128
            // elevation, so the panel naturally renders dense even though
            // the source texture is sparse-by-design.
            if (lidarShowPanel) {
                const int numAz = std::max(1, static_cast<int>(std::round(
                                                  (lidarModel.azimuthMax - lidarModel.azimuthMin) /
                                                  lidarModel.azimuthResolution)));
                const int numElev = static_cast<int>(lidarModel.elevationAngles.size());
                const int blockW = std::max(1, static_cast<int>(kLidarPanelW) / numAz);
                const int blockH = std::max(1, static_cast<int>(kLidarPanelH) / numElev);

                auto& panelBytes = lidarPanelTex->image().data<unsigned char>();
                std::fill(panelBytes.begin(), panelBytes.end(), 0u);

                // Panel shows the FIRST sample's FIRST return per beam
                // (real LIDAR sensors' default debug view). Other samples
                // / multi-returns appear in the 3-D cloud where they don't
                // overlap spatially.
                const uint32_t maxRet  = std::max(1u, lidarSensor->params.maxReturns);
                const uint32_t samples = std::max(1u, lidarSensor->params.samplesPerBeam);
                const uint32_t slotsPerBeam = maxRet * samples;
                for (size_t beam = 0; beam < lidarSensor->beamCount(); ++beam) {
                    const size_t b = beam * slotsPerBeam;
                    if (b >= lidarReturns.size()) break;
                    const auto& r = lidarReturns[b];
                    if (r.returnNo <= 0) continue;// miss
                    const int ai = static_cast<int>(beam) / numElev;
                    const int ei = static_cast<int>(beam) % numElev;
                    const int px0 = std::clamp(ai * static_cast<int>(kLidarPanelW) / numAz,
                                                0, static_cast<int>(kLidarPanelW) - 1);
                    const int py0 = std::clamp(ei * static_cast<int>(kLidarPanelH) / numElev,
                                                0, static_cast<int>(kLidarPanelH) - 1);
                    lidarIntensityColor(r.intensity, col);
                    const unsigned char rByte = static_cast<unsigned char>(col.r * 255.f);
                    const unsigned char gByte = static_cast<unsigned char>(col.g * 255.f);
                    const unsigned char bByte = static_cast<unsigned char>(col.b * 255.f);
                    for (int dy = 0; dy < blockH; ++dy) {
                        const int y = std::min(py0 + dy, static_cast<int>(kLidarPanelH) - 1);
                        size_t row = static_cast<size_t>(y) * kLidarPanelW * 4;
                        for (int dx = 0; dx < blockW; ++dx) {
                            const int x = std::min(px0 + dx, static_cast<int>(kLidarPanelW) - 1);
                            const size_t idx = row + static_cast<size_t>(x) * 4;
                            panelBytes[idx + 0] = rByte;
                            panelBytes[idx + 1] = gByte;
                            panelBytes[idx + 2] = bByte;
                            panelBytes[idx + 3] = 255u;
                        }
                    }
                }
                lidarPanelTex->needsUpdate();
            }

            // Synthesize the per-beam analog waveform from the discrete
            // returns. Cheap (<1 ms) for one beam per frame.
            if (lidarShowWave) {
                const uint32_t mr = std::max(1u, lidarSensor->params.maxReturns);
                const uint32_t sp = std::max(1u, lidarSensor->params.samplesPerBeam);
                lidarWavParams.maxRange = lidarSensor->params.maxRange;
                synthesizeLidarWaveform(lidarReturns,
                                        lidarSensor->beamCount(),
                                        static_cast<size_t>(mr) * sp,
                                        lidarWavParams, lidarWaveform);
            }
        } else {
            lidarCloudGeom->setDrawRange(0, 0);
        }

        if (!capturing) ui.render();// capture reads the bare frame (no HUD)
    });

    return 0;
}