//! Application configuration: CLI arguments, environment variables,
//! and TOML config files, all through one clap arg surface.
//!
//! Layering (by `clap_config`, see `from_merged`):
//!
//! 1. CLI arguments (`--rig-left-position "-0.4,0,0"`)
//! 2. environment variables (`KINECT_VIEW_RIG_LEFT_POSITION=-0.4,0,0`)
//! 3. the TOML config file (`--config-file` / `KINECT_VIEW_CONFIG_FILE`,
//!    keys snake_cased: `rig_left_position = [-0.4, 0.0, 0.0]`)
//! 4. built-in defaults (the development rig: a Kinect-like center
//!    camera and two webcams converged on the synthetic subject)
//!
//! Every setting is configurable in all four ways. The arg surface is
//! flat (clap_config has no nested-group support), so rig fields are
//! named `rig_<side>_<field>`.
//!
//! Rotation can be given three ways, with priority
//! `rotation_quat > rotation_deg > look_at`:
//!
//! * `rotation_quat = [x, y, z, w]` — exact COLMAP camera-to-world
//!   quaternion, e.g. from calibration output,
//! * `rotation_deg = [pitch, yaw, roll]` — human-friendly aviation
//!   angles (see [`rig::CameraPose::from_euler_deg`]),
//! * `look_at = [x, y, z]` — converge the camera on a point (the
//!   default: `[0, 0, 2]`, the subject).

use std::path::PathBuf;

use anyhow::{Context, Result, ensure};
use clap::{CommandFactory, Parser};
use clap_config::ClapConfig;
use glam::{Quat, UVec2, Vec3};
use replay::NoiseParams;
use serde::{Deserialize, Serialize};
use splatgen::{ProxyParams, SplatGenParams};

use rig::{Camera, CameraIntrinsics, CameraPose, Rig};

/// Which source feeds the pipeline. Selected with `--source`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum SourceArg {
    /// The synthetic dataset (dev; the default).
    Synthetic,
    /// A recorded dataset directory (`--recording-path`).
    Recording,
    /// The live rig: Kinect + webcams.
    Kinect,
}

/// The resolved source selection.
#[derive(Debug, Clone, PartialEq)]
pub enum SourceSelection {
    Synthetic,
    Recording(PathBuf),
    Kinect,
}

/// Load the configuration from argv (CLI + environment), merged with
/// the config file named by `--config-file` / `KINECT_VIEW_CONFIG_FILE`,
/// if any.
pub fn load() -> Result<Args> {
    load_from(std::env::args_os())
}

/// Like [`load`], but from an explicit argv (tests).
pub fn load_from<I, T>(argv: I) -> Result<Args>
where
    I: IntoIterator<Item = T>,
    T: Into<std::ffi::OsString> + Clone,
{
    let matches = Args::command().get_matches_from(argv);
    let config_file = matches.get_one::<PathBuf>("config_file").cloned();

    let file_config = match config_file {
        Some(path) if !path.as_os_str().is_empty() => {
            let text = std::fs::read_to_string(&path)
                .with_context(|| format!("reading config file {}", path.display()))?;
            let parsed: ArgsConfig = toml::from_str(&text)
                .with_context(|| format!("parsing config file {}", path.display()))?;
            Some(parsed)
        }
        _ => None,
    };

    Ok(Args::from_merged(matches, file_config))
}

/// The application arguments; also the shape of the config file (see
/// the [module docs](self) for layering).
#[derive(ClapConfig, Parser, Debug, Clone)]
pub struct Args {
    /// Path to a TOML config file. Settings there are overridden by
    /// environment variables and CLI arguments.
    #[clap_config(skip)]
    #[arg(long, env = "KINECT_VIEW_CONFIG_FILE")]
    pub config_file: Option<PathBuf>,

    // -- rig.left: the left webcam -----------------------------------
    /// Left camera identifier (device name/serial on the physical rig).
    #[arg(long, env = "KINECT_VIEW_RIG_LEFT_ID", default_value = "left")]
    pub rig_left_id: String,
    /// Left camera position, metres: `x,y,z`.
    #[arg(
        long,
        env = "KINECT_VIEW_RIG_LEFT_POSITION",
        default_value = "-0.4,0,0"
    )]
    pub rig_left_position: Position3,
    /// Point the left camera at, metres: `x,y,z` (used when no explicit
    /// rotation is set).
    #[arg(long, env = "KINECT_VIEW_RIG_LEFT_LOOK_AT", default_value = "0,0,2")]
    pub rig_left_look_at: Position3,
    /// Left camera rotation as `pitch,yaw,roll` degrees (overrides
    /// look-at).
    #[arg(long, env = "KINECT_VIEW_RIG_LEFT_ROTATION_DEG")]
    pub rig_left_rotation_deg: Option<RotationEulerDeg>,
    /// Left camera rotation as an `x,y,z,w` quaternion (overrides
    /// rotation-deg and look-at).
    #[arg(long, env = "KINECT_VIEW_RIG_LEFT_ROTATION_QUAT")]
    pub rig_left_rotation_quat: Option<RotationQuat>,
    /// Left camera resolution, pixels: `width,height`.
    #[arg(
        long,
        env = "KINECT_VIEW_RIG_LEFT_RESOLUTION",
        default_value = "640,480"
    )]
    pub rig_left_resolution: Resolution2,
    /// Left camera intrinsics, pixels: `fx,fy,cx,cy` (at its resolution).
    #[arg(
        long,
        env = "KINECT_VIEW_RIG_LEFT_INTRINSICS",
        default_value = "554.256,415.692,320,240"
    )]
    pub rig_left_intrinsics: Intrinsics,

    // -- rig.center: the Kinect depth camera --------------------------
    /// Center camera identifier.
    #[arg(long, env = "KINECT_VIEW_RIG_CENTER_ID", default_value = "kinect")]
    pub rig_center_id: String,
    /// Center camera position, metres: `x,y,z`.
    #[arg(long, env = "KINECT_VIEW_RIG_CENTER_POSITION", default_value = "0,0,0")]
    pub rig_center_position: Position3,
    /// Point the center camera at, metres: `x,y,z`.
    #[arg(long, env = "KINECT_VIEW_RIG_CENTER_LOOK_AT", default_value = "0,0,2")]
    pub rig_center_look_at: Position3,
    /// Center camera rotation as `pitch,yaw,roll` degrees.
    #[arg(long, env = "KINECT_VIEW_RIG_CENTER_ROTATION_DEG")]
    pub rig_center_rotation_deg: Option<RotationEulerDeg>,
    /// Center camera rotation as an `x,y,z,w` quaternion.
    #[arg(long, env = "KINECT_VIEW_RIG_CENTER_ROTATION_QUAT")]
    pub rig_center_rotation_quat: Option<RotationQuat>,
    /// Center camera resolution, pixels: `width,height`.
    #[arg(
        long,
        env = "KINECT_VIEW_RIG_CENTER_RESOLUTION",
        default_value = "256,212"
    )]
    pub rig_center_resolution: Resolution2,
    /// Center camera intrinsics, pixels: `fx,fy,cx,cy`.
    #[arg(
        long,
        env = "KINECT_VIEW_RIG_CENTER_INTRINSICS",
        default_value = "182.803,183.597,128,106"
    )]
    pub rig_center_intrinsics: Intrinsics,

    // -- rig.right: the right webcam ---------------------------------
    /// Right camera identifier (device name/serial on the physical rig).
    #[arg(long, env = "KINECT_VIEW_RIG_RIGHT_ID", default_value = "right")]
    pub rig_right_id: String,
    /// Right camera position, metres: `x,y,z`.
    #[arg(
        long,
        env = "KINECT_VIEW_RIG_RIGHT_POSITION",
        default_value = "0.4,0,0"
    )]
    pub rig_right_position: Position3,
    /// Point the right camera at, metres: `x,y,z`.
    #[arg(long, env = "KINECT_VIEW_RIG_RIGHT_LOOK_AT", default_value = "0,0,2")]
    pub rig_right_look_at: Position3,
    /// Right camera rotation as `pitch,yaw,roll` degrees.
    #[arg(long, env = "KINECT_VIEW_RIG_RIGHT_ROTATION_DEG")]
    pub rig_right_rotation_deg: Option<RotationEulerDeg>,
    /// Right camera rotation as an `x,y,z,w` quaternion.
    #[arg(long, env = "KINECT_VIEW_RIG_RIGHT_ROTATION_QUAT")]
    pub rig_right_rotation_quat: Option<RotationQuat>,
    /// Right camera resolution, pixels: `width,height`.
    #[arg(
        long,
        env = "KINECT_VIEW_RIG_RIGHT_RESOLUTION",
        default_value = "640,480"
    )]
    pub rig_right_resolution: Resolution2,
    /// Right camera intrinsics, pixels: `fx,fy,cx,cy`.
    #[arg(
        long,
        env = "KINECT_VIEW_RIG_RIGHT_INTRINSICS",
        default_value = "554.256,415.692,320,240"
    )]
    pub rig_right_intrinsics: Intrinsics,

    // -- source selection ----------------------------------------------
    /// Which source feeds the pipeline: synthetic, a recording, or the
    /// live Kinect rig.
    #[arg(
        value_enum,
        long,
        env = "KINECT_VIEW_SOURCE",
        default_value = "synthetic"
    )]
    pub source: SourceArg,
    /// The recorded dataset directory (`--source recording`).
    #[arg(long, env = "KINECT_VIEW_RECORDING_PATH")]
    pub recording_path: Option<PathBuf>,

    // -- occlusion proxy -----------------------------------------------
    /// Fill occluded regions from the fitted subject ellipsoid,
    /// recolored from the side cameras.
    #[arg(long, env = "KINECT_VIEW_PROXY_ENABLED", default_value = "true")]
    pub proxy_enabled: bool,
    /// Fitted-ellipsoid radii as a multiple of the subject cluster's
    /// per-axis standard deviation.
    #[arg(long, env = "KINECT_VIEW_PROXY_SIGMA", default_value = "2.0")]
    pub proxy_sigma: f32,
    /// Proxy splats' thickness as a multiple of the regular surfels'.
    #[arg(
        long,
        env = "KINECT_VIEW_PROXY_THICKNESS_MULTIPLE",
        default_value = "3.0"
    )]
    pub proxy_thickness_multiple: f32,
    /// Proxy splat opacity — lower than the surfels' (a lower
    /// confidence weight).
    #[arg(long, env = "KINECT_VIEW_PROXY_OPACITY", default_value = "0.85")]
    pub proxy_opacity: f32,
    /// Subject cluster depth range, metres (the nearest cluster in the
    /// depth map is the subject; the background is further out).
    #[arg(
        long,
        env = "KINECT_VIEW_PROXY_CLUSTER_EXTENT_M",
        default_value = "0.6"
    )]
    pub proxy_cluster_extent_m: f32,

    // -- depth processing (splatgen) -----------------------------------
    /// Bilateral filter radius, pixels (PLAN.md: 3–5).
    #[arg(long, env = "KINECT_VIEW_SPLATGEN_FILTER_RADIUS", default_value = "3")]
    pub splatgen_filter_radius: u32,
    /// Bilateral depth-domain sigma, millimetres.
    #[arg(
        long,
        env = "KINECT_VIEW_SPLATGEN_FILTER_SIGMA_DEPTH_MM",
        default_value = "25.0"
    )]
    pub splatgen_filter_sigma_depth_mm: f32,
    /// Bilateral spatial-domain sigma, pixels.
    #[arg(
        long,
        env = "KINECT_VIEW_SPLATGEN_FILTER_SIGMA_SPACE_PX",
        default_value = "2.0"
    )]
    pub splatgen_filter_sigma_space_px: f32,
    /// Pixels differing from their 3x3 neighbourhood median by more
    /// than this are fliers and dropped, millimetres.
    #[arg(
        long,
        env = "KINECT_VIEW_SPLATGEN_FLIER_THRESHOLD_MM",
        default_value = "250"
    )]
    pub splatgen_flier_threshold_mm: u32,
    /// Background culling: pixels beyond this depth are dropped,
    /// millimetres.
    #[arg(
        long,
        env = "KINECT_VIEW_SPLATGEN_MAX_DEPTH_MM",
        default_value = "4000"
    )]
    pub splatgen_max_depth_mm: u16,
    /// Surfel opacity (PLAN.md: ~0.9–0.99).
    #[arg(long, env = "KINECT_VIEW_SPLATGEN_OPACITY", default_value = "0.95")]
    pub splatgen_opacity: f32,

    // -- synthetic source noise ---------------------------------------
    /// Fraction of valid depth pixels turned into fliers, `[0, 1]`.
    #[arg(
        long,
        env = "KINECT_VIEW_SOURCE_NOISE_FLIER_RATE",
        default_value = "0.005"
    )]
    pub source_noise_flier_rate: f32,
    /// Per-pixel depth jitter, ± millimetres.
    #[arg(long, env = "KINECT_VIEW_SOURCE_NOISE_JITTER_MM", default_value = "4")]
    pub source_noise_jitter_mm: u32,

    // -- scene / source / view ----------------------------------------
    /// Where the synthetic subject sits, metres (the scene is built
    /// around it; the default rig converges on it).
    #[arg(
        long,
        env = "KINECT_VIEW_SCENE_SUBJECT_POSITION",
        default_value = "0,0,2"
    )]
    pub scene_subject_position: Position3,
    /// Playback rate of the frame source, frames per second.
    #[arg(long, env = "KINECT_VIEW_SOURCE_FPS", default_value = "30.0")]
    pub source_fps: f32,
    /// Render background colour, `r,g,b` floats in `[0, 1]`.
    #[arg(long, env = "KINECT_VIEW_BACKGROUND", default_value = "0.10,0.10,0.12")]
    pub background: ColorRgb,
}

impl Args {
    /// Validate the merged settings and build the typed values the app
    /// runs on.
    pub fn resolve(&self) -> Result<ResolvedConfig> {
        let left = camera_from(
            self.rig_left_id.clone(),
            self.rig_left_position,
            self.rig_left_look_at,
            self.rig_left_rotation_deg,
            self.rig_left_rotation_quat,
            self.rig_left_resolution,
            self.rig_left_intrinsics,
        )?;
        let center = camera_from(
            self.rig_center_id.clone(),
            self.rig_center_position,
            self.rig_center_look_at,
            self.rig_center_rotation_deg,
            self.rig_center_rotation_quat,
            self.rig_center_resolution,
            self.rig_center_intrinsics,
        )?;
        let right = camera_from(
            self.rig_right_id.clone(),
            self.rig_right_position,
            self.rig_right_look_at,
            self.rig_right_rotation_deg,
            self.rig_right_rotation_quat,
            self.rig_right_resolution,
            self.rig_right_intrinsics,
        )?;

        let fps = self.source_fps;
        ensure!(fps > 0.0, "source-fps must be positive, got {fps}");

        let proxy = ProxyParams {
            enabled: self.proxy_enabled,
            sigma: self.proxy_sigma,
            thickness_multiple: self.proxy_thickness_multiple,
            opacity: self.proxy_opacity,
            cluster_extent_m: self.proxy_cluster_extent_m,
        };
        ensure!(
            (0.0..=1.0).contains(&proxy.opacity),
            "proxy-opacity must be in [0, 1], got {}",
            proxy.opacity
        );
        ensure!(proxy.sigma > 0.0, "proxy-sigma must be positive");

        let splatgen = SplatGenParams {
            filter_radius: self.splatgen_filter_radius,
            filter_sigma_depth_mm: self.splatgen_filter_sigma_depth_mm,
            filter_sigma_space_px: self.splatgen_filter_sigma_space_px,
            flier_threshold_mm: self.splatgen_flier_threshold_mm,
            max_depth_mm: self.splatgen_max_depth_mm,
            opacity: self.splatgen_opacity,
            thickness_m: rig::SURFEL_THICKNESS_M,
            proxy,
        };
        ensure!(
            (0.0..=1.0).contains(&splatgen.opacity),
            "splatgen-opacity must be in [0, 1], got {}",
            splatgen.opacity
        );

        let noise = NoiseParams {
            flier_rate: self.source_noise_flier_rate,
            jitter_mm: self.source_noise_jitter_mm,
        };
        ensure!(
            (0.0..=1.0).contains(&noise.flier_rate),
            "source-noise-flier-rate must be in [0, 1], got {}",
            noise.flier_rate
        );

        // Which source feeds the pipeline.
        let source = match self.source {
            SourceArg::Synthetic => SourceSelection::Synthetic,
            SourceArg::Recording => {
                let path = self.recording_path.clone().context(
                    "--source recording needs --recording-path (or \
                     KINECT_VIEW_RECORDING_PATH)",
                )?;
                SourceSelection::Recording(path)
            }
            SourceArg::Kinect => SourceSelection::Kinect,
        };

        Ok(ResolvedConfig {
            rig: Rig {
                left,
                center,
                right,
            },
            subject: self.scene_subject_position.0.into(),
            fps,
            background: self.background.0.into(),
            source,
            splatgen,
            noise,
        })
    }
}

/// The validated, typed configuration the app runs on.
#[derive(Debug, Clone, PartialEq)]
pub struct ResolvedConfig {
    pub rig: Rig,
    /// The synthetic subject position, metres.
    pub subject: Vec3,
    /// Frame source rate, fps.
    pub fps: f32,
    /// Render background colour.
    pub background: Vec3,
    /// Which source feeds the pipeline.
    pub source: SourceSelection,
    /// Depth-processing parameters (`splatgen`).
    pub splatgen: SplatGenParams,
    /// Synthetic sensor noise.
    pub noise: NoiseParams,
}

/// Build one rig camera from its merged args. Rotation priority:
/// quaternion > euler degrees > look-at.
#[allow(clippy::too_many_arguments)]
fn camera_from(
    id: String,
    position: Position3,
    look_at: Position3,
    rotation_deg: Option<RotationEulerDeg>,
    rotation_quat: Option<RotationQuat>,
    resolution: Resolution2,
    intrinsics: Intrinsics,
) -> Result<Camera> {
    let [w, h] = resolution.0;
    ensure!(
        w > 0 && h > 0,
        "{id}: resolution must be positive, got {w}x{h}"
    );
    let [fx, fy, cx, cy] = intrinsics.0;
    ensure!(
        fx.is_finite() && fx > 0.0 && fy.is_finite() && fy > 0.0,
        "{id}: focal lengths must be positive, got fx={fx}, fy={fy}"
    );

    let pose = if let Some(quat) = rotation_quat {
        let rotation = Quat::from_array(quat.0);
        ensure!(
            rotation.length_squared() > 1e-12,
            "{id}: rotation quaternion must be non-zero"
        );
        CameraPose {
            position: position.0.into(),
            rotation: rotation.normalize(),
        }
    } else if let Some(euler) = rotation_deg {
        CameraPose::from_euler_deg(position.0.into(), euler.0[0], euler.0[1], euler.0[2])
    } else {
        CameraPose::looking_at(position.0.into(), look_at.0.into())
    };

    Ok(Camera {
        id,
        pose,
        intrinsics: CameraIntrinsics { fx, fy, cx, cy },
        resolution: UVec2::new(w, h),
    })
}

// ---------------------------------------------------------------------------
// Value types: comma-separated on the CLI, arrays in TOML.

macro_rules! comma_value_type {
    ($(#[$meta:meta])* $name:ident, [$elem:ty; $n:literal]) => {
        $(#[$meta])*
        #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
        pub struct $name(pub [$elem; $n]);

        impl std::str::FromStr for $name {
            type Err = String;

            fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
                let values: std::result::Result<Vec<$elem>, _> = s
                    .split(',')
                    .map(|part| part.trim().parse::<$elem>())
                    .collect();
                let values = values
                    .map_err(|e| format!("invalid {} value in `{s}`: {e}", stringify!($name)))?;
                if values.len() != $n {
                    return Err(format!(
                        "{} expects {} comma-separated values, got {}",
                        stringify!($name),
                        $n,
                        values.len()
                    ));
                }
                Ok(Self(values.try_into().expect("checked length")))
            }
        }

        impl std::fmt::Display for $name {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                let parts: Vec<String> = self.0.iter().map(|v| v.to_string()).collect();
                write!(f, "{}", parts.join(","))
            }
        }
    };
}

comma_value_type!(
    /// A 3D position, metres: `x,y,z`.
    Position3,
    [f32; 3]
);
comma_value_type!(
    /// Aviation-style rotation, degrees: `pitch,yaw,roll`.
    RotationEulerDeg,
    [f32; 3]
);
comma_value_type!(
    /// A quaternion, `x,y,z,w`.
    RotationQuat,
    [f32; 4]
);
comma_value_type!(
    /// Pinhole intrinsics, pixels: `fx,fy,cx,cy`.
    Intrinsics,
    [f32; 4]
);
comma_value_type!(
    /// An image resolution, pixels: `width,height`.
    Resolution2,
    [u32; 2]
);
comma_value_type!(
    /// An RGB colour, floats in `[0, 1]`: `r,g,b`.
    ColorRgb,
    [f32; 3]
);

#[cfg(test)]
mod tests {
    use super::*;
    use glam::vec3;
    use replay::synth::dev_rig;
    use std::collections::BTreeMap;
    use std::sync::Mutex;

    /// clap reads the whole environment when building matches, and the
    /// env test mutates it, so all config tests serialize on this lock.
    static TEST_LOCK: Mutex<()> = Mutex::new(());

    fn merged(argv: &[&str], file: Option<&str>) -> Args {
        let matches = Args::command().get_matches_from(argv.iter().copied());
        let file_config = file.map(|text| {
            let parsed: ArgsConfig = toml::from_str(text).expect("test config parses");
            parsed
        });
        Args::from_merged(matches, file_config)
    }

    #[test]
    fn defaults_match_the_dev_rig() {
        let _guard = TEST_LOCK.lock().unwrap();
        let args = merged(&["app"], None).resolve().expect("defaults resolve");
        let dev = dev_rig();

        // Poses are exact: both go through looking_at with the same
        // positions and target.
        assert_eq!(args.rig.left.pose, dev.left.pose);
        assert_eq!(args.rig.center.pose, dev.center.pose);
        assert_eq!(args.rig.right.pose, dev.right.pose);
        assert_eq!(args.rig.left.id, "left");
        assert_eq!(args.rig.center.id, "kinect");
        assert_eq!(args.rig.right.id, "right");
        assert_eq!(args.rig.left.resolution, dev.left.resolution);
        assert_eq!(args.rig.center.resolution, dev.center.resolution);
        assert_eq!(args.rig.right.resolution, dev.right.resolution);
        // Intrinsics are decimal-rounded defaults; the dev rig computes
        // them from focal ratios.
        for (got, want) in [
            (args.rig.left.intrinsics, dev.left.intrinsics),
            (args.rig.center.intrinsics, dev.center.intrinsics),
            (args.rig.right.intrinsics, dev.right.intrinsics),
        ] {
            assert!((got.fx - want.fx).abs() < 1e-2);
            assert!((got.fy - want.fy).abs() < 1e-2);
            assert_eq!((got.cx, got.cy), (want.cx, want.cy));
        }
        assert_eq!(args.subject, vec3(0.0, 0.0, 2.0));
        assert_eq!(args.fps, 30.0);
        assert_eq!(args.background, vec3(0.10, 0.10, 0.12));
        assert_eq!(args.splatgen, SplatGenParams::default());
        assert_eq!(args.noise, NoiseParams::default());
        assert_eq!(args.source, SourceSelection::Synthetic);
    }

    #[test]
    fn file_overrides_defaults() {
        let _guard = TEST_LOCK.lock().unwrap();
        let args = merged(
            &["app"],
            Some(
                "rig_left_position = [1.0, 0.0, 0.0]\nsource_fps = 12.5\n\
                 splatgen_max_depth_mm = 2500\nsource_noise_jitter_mm = 0\n",
            ),
        )
        .resolve()
        .expect("resolves");
        assert_eq!(args.rig.left.pose.position, vec3(1.0, 0.0, 0.0));
        assert_eq!(args.fps, 12.5);
        // Depth-processing and noise settings flow through too.
        assert_eq!(args.splatgen.max_depth_mm, 2500);
        assert_eq!(args.noise.jitter_mm, 0);
        // Everything else keeps its default.
        assert_eq!(args.rig.right.pose.position, vec3(0.4, 0.0, 0.0));
    }

    #[test]
    fn cli_beats_file_beats_defaults() {
        let _guard = TEST_LOCK.lock().unwrap();
        let args = merged(
            &["app", "--rig-right-position", "1,2,3"],
            Some("rig_right_position = [9.0, 9.0, 9.0]\nrig_left_position = [8.0, 0.0, 0.0]\n"),
        )
        .resolve()
        .expect("resolves");
        // CLI wins over the file…
        assert_eq!(args.rig.right.pose.position, vec3(1.0, 2.0, 3.0));
        // …the file wins over defaults…
        assert_eq!(args.rig.left.pose.position, vec3(8.0, 0.0, 0.0));
        // …and untouched fields keep their defaults.
        assert_eq!(args.rig.center.pose.position, vec3(0.0, 0.0, 0.0));
    }

    #[test]
    fn env_beats_file_and_cli_beats_env() {
        let _guard = TEST_LOCK.lock().unwrap();
        // Environment mutation races between tests and is unsafe in
        // edition 2024, so both layers are exercised in one test, in
        // order, with a variable nothing else touches.
        let var = "KINECT_VIEW_RIG_CENTER_POSITION";
        unsafe { std::env::set_var(var, "5,0,0") };
        let args = merged(&["app"], Some("rig_center_position = [8.0, 8.0, 8.0]\n"))
            .resolve()
            .expect("resolves");
        assert_eq!(args.rig.center.pose.position, vec3(5.0, 0.0, 0.0));

        let args = merged(
            &["app", "--rig-center-position", "7,0,0"],
            Some("rig_center_position = [8.0, 8.0, 8.0]\n"),
        )
        .resolve()
        .expect("resolves");
        assert_eq!(args.rig.center.pose.position, vec3(7.0, 0.0, 0.0));
        unsafe { std::env::remove_var(var) };
    }

    #[test]
    fn rotation_priority_quat_over_euler_over_look_at() {
        let _guard = TEST_LOCK.lock().unwrap();
        let args = merged(
            &["app"],
            Some(concat!(
                "rig_left_rotation_quat = [0.0, 0.0, 0.0, 1.0]\n",
                "rig_left_rotation_deg = [0.0, 90.0, 0.0]\n",
            )),
        )
        .resolve()
        .expect("resolves");
        // Identity quaternion: looking straight down +Z (not at the
        // default look-at target).
        assert!((args.rig.left.pose.rotation * Vec3::Z - Vec3::Z).length() < 1e-6);

        // Without the quaternion, euler wins over look-at.
        let args = merged(&["app"], Some("rig_left_rotation_deg = [0.0, 90.0, 0.0]\n"))
            .resolve()
            .expect("resolves");
        assert!((args.rig.left.pose.rotation * Vec3::Z - Vec3::X).length() < 1e-4);

        // And with neither, look-at applies.
        let args = merged(&["app"], None).resolve().expect("resolves");
        let forward = args.rig.left.pose.rotation * Vec3::Z;
        let to_subject = (vec3(0.0, 0.0, 2.0) - args.rig.left.pose.position).normalize();
        assert!(forward.dot(to_subject) > 0.999);
    }

    #[test]
    fn invalid_values_are_rejected() {
        let _guard = TEST_LOCK.lock().unwrap();
        // Comma parsing.
        assert!("1,2".parse::<Position3>().is_err());
        assert!("a,b,c".parse::<Position3>().is_err());
        assert!("1,2,3".parse::<Position3>().is_ok());
        assert!("640, 480".parse::<Resolution2>().is_ok()); // spaces ok

        // Zero quaternion.
        let err = merged(
            &["app"],
            Some("rig_left_rotation_quat = [0.0, 0.0, 0.0, 0.0]\n"),
        )
        .resolve()
        .expect_err("zero quaternion");
        assert!(err.to_string().contains("non-zero"));

        // Bad resolution.
        let err = merged(&["app", "--rig-left-resolution", "0,480"], None)
            .resolve()
            .expect_err("zero resolution");
        assert!(err.to_string().contains("resolution"));

        // Bad fps.
        let err = merged(&["app", "--source-fps", "0"], None)
            .resolve()
            .expect_err("zero fps");
        assert!(err.to_string().contains("fps"));

        // Missing config file.
        let err = load_from(["app", "--config-file", "/nonexistent/kinect-view.toml"])
            .expect_err("missing file");
        assert!(err.to_string().contains("reading config file"));

        // Malformed config file.
        let err = load_from(["app", "--config-file", "Cargo.toml"])
            .map(|_| ()) // Cargo.toml is TOML, but not this shape.
            .err();
        // Any outcome here is fine as long as it doesn't panic; the
        // error (if any) should mention the config file.
        if let Some(err) = err {
            assert!(err.to_string().contains("config file"));
        }
    }

    #[test]
    fn source_selection_is_configurable() {
        let _guard = TEST_LOCK.lock().unwrap();
        // Default: synthetic.
        let args = merged(&["app"], None).resolve().expect("resolves");
        assert_eq!(args.source, SourceSelection::Synthetic);

        // From a file.
        let args = merged(
            &["app"],
            Some("source = \"recording\"\nrecording_path = \"/tmp/some-rec\"\n"),
        )
        .resolve()
        .expect("resolves");
        assert_eq!(
            args.source,
            SourceSelection::Recording(PathBuf::from("/tmp/some-rec"))
        );

        // From the CLI.
        let args = merged(&["app", "--source", "kinect"], None)
            .resolve()
            .expect("resolves");
        assert_eq!(args.source, SourceSelection::Kinect);

        // Recording without a path is a configuration error.
        let err = merged(&["app", "--source", "recording"], None)
            .resolve()
            .expect_err("missing recording path");
        assert!(err.to_string().contains("recording-path"));

        // Proxy settings flow through.
        let args = merged(
            &["app"],
            Some("proxy_opacity = 0.7\nproxy_cluster_extent_m = 0.9\n"),
        )
        .resolve()
        .expect("resolves");
        assert_eq!(args.splatgen.proxy.opacity, 0.7);
        assert_eq!(args.splatgen.proxy.cluster_extent_m, 0.9);
    }

    #[test]
    fn value_types_round_trip_as_strings_and_toml() {
        let _guard = TEST_LOCK.lock().unwrap();
        let pos: Position3 = "-0.4,0,1".parse().expect("parses");
        assert_eq!(pos.0, [-0.4, 0.0, 1.0]);
        // In a TOML document the value is an array.
        let text = toml::to_string(&BTreeMap::from([("v".to_string(), pos)])).expect("serializes");
        assert!(text.contains("v = [-0.4,"), "unexpected TOML: {text}");
        let back: BTreeMap<String, Position3> = toml::from_str(&text).expect("deserializes");
        assert_eq!(back["v"], pos);
        // And the CLI form round-trips through Display/FromStr.
        let printed = pos.to_string();
        assert_eq!(printed.parse::<Position3>().unwrap(), pos);
    }
}