blockworx/doc_ng/

geometry.rs

//! Geometry value types for the document model.
//!
//! No floats anywhere: coordinates are integers (`GridPoint`) or fixed-point
//! (`FracVal`), so every value has exactly one encoding and the bytes the
//! change hash covers are deterministic.

use serde::{Deserialize, Serialize};

/// The document extent, in grid cells: two of them sum far inside `i32`,
/// so no rect accessor can overflow a value a decoder accepted. Enforced
/// at the decode boundary, where "bounded by the document extent" stops
/// being true because the payload came from a stranger. Refused, never
/// clamped — clamping relocates geometry instead of reporting a bad
/// payload. Authoring must respect it too, or it writes commits it cannot
/// read back.
pub const GRID_LIMIT: i32 = 1 << 20;

#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum OutOfExtent {
    #[error("coordinate {0} is outside the document extent (±{GRID_LIMIT})")]
    Coordinate(i32),
    #[error("extent {0} exceeds the document extent ({GRID_LIMIT})")]
    Size(u32),
    #[error("fixed-point value {0} is outside the screen range (±{limit})", limit = FracVal::LIMIT)]
    Frac(i64),
}

/// Mirrors [`GridPoint`] so `try_from` has an unchecked type to decode
/// into first — serde's price for a validating decode.
#[derive(Deserialize)]
struct RawGridPoint {
    x: i32,
    y: i32,
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "RawGridPoint")]
pub struct GridPoint {
    pub x: i32,
    pub y: i32,
}

impl TryFrom<RawGridPoint> for GridPoint {
    type Error = OutOfExtent;
    fn try_from(raw: RawGridPoint) -> Result<Self, Self::Error> {
        for coordinate in [raw.x, raw.y] {
            if !(-GRID_LIMIT..=GRID_LIMIT).contains(&coordinate) {
                return Err(OutOfExtent::Coordinate(coordinate));
            }
        }
        Ok(Self { x: raw.x, y: raw.y })
    }
}

#[derive(Deserialize)]
struct RawGridSize {
    w: u32,
    h: u32,
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "RawGridSize")]
pub struct GridSize {
    pub w: u32,
    pub h: u32,
}

impl TryFrom<RawGridSize> for GridSize {
    type Error = OutOfExtent;
    fn try_from(raw: RawGridSize) -> Result<Self, Self::Error> {
        for extent in [raw.w, raw.h] {
            if extent > GRID_LIMIT.unsigned_abs() {
                return Err(OutOfExtent::Size(extent));
            }
        }
        Ok(Self { w: raw.w, h: raw.h })
    }
}

/// Atomic wherever it appears — one register holds the whole rect.
#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct GridRect {
    pub top_left: GridPoint,
    pub size: GridSize,
}

/// The lock rides inside the atomic waypoints value: a polyline with its
/// locks is one author's coherent intent.
#[derive(Clone, Copy, PartialEq, Eq, Default, Debug, Serialize, Deserialize)]
pub struct Waypoint {
    pub pos: GridPoint,
    pub locked: bool,
}

/// An `f32` quantized to units of 2⁻²⁴ (truncated toward zero), stored as
/// `i64`. NOTE: `f32 -> FracVal` on NaN saturates to 0 (Rust `as` cast).
/// Reject NaN at command construction (`debug_assert`) rather than relying on
/// saturation.
#[derive(
    Default, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
)]
#[serde(try_from = "i64")]
pub struct FracVal(i64);

impl FracVal {
    /// ±2²⁴ in screen coordinates; sums of two stay exact in `i64`. Same
    /// refuse-don't-clamp rule as [`GRID_LIMIT`].
    pub const LIMIT: i64 = 1 << 48;
}

impl TryFrom<i64> for FracVal {
    type Error = OutOfExtent;
    fn try_from(raw: i64) -> Result<Self, Self::Error> {
        if (-Self::LIMIT..=Self::LIMIT).contains(&raw) {
            Ok(Self(raw))
        } else {
            Err(OutOfExtent::Frac(raw))
        }
    }
}

impl From<f32> for FracVal {
    fn from(val: f32) -> FracVal {
        debug_assert!(!val.is_nan(), "NaN must not enter the document");
        Self((val as f64 * 2.0f64.powi(24)) as i64)
    }
}
impl From<FracVal> for f32 {
    fn from(val: FracVal) -> f32 {
        ((val.0 as f64) / 2.0f64.powi(24)) as f32
    }
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ScreenPoint {
    pub x: FracVal,
    pub y: FracVal,
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ScreenSize {
    pub w: FracVal,
    pub h: FracVal,
}

/// Atomic (same reasoning as `GridRect`). Default = empty rect (meaningful zero).
#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq, Default)]
pub struct ScreenRect {
    pub top_left: ScreenPoint,
    pub size: ScreenSize,
}

#[cfg(test)]
mod tests {
    use super::*;
    use proptest::prelude::*;

    /// One value, one encoding: the two float zeros collapse to one
    /// `FracVal`, so the sign of a zero can never reach a change hash.
    #[test]
    fn both_float_zeros_quantize_identically() {
        assert_eq!(FracVal::from(0.0f32), FracVal::from(-0.0f32));
    }

    #[test]
    #[should_panic(expected = "NaN must not enter the document")]
    fn nan_is_refused_at_the_boundary() {
        let _ = FracVal::from(f32::NAN);
    }

    /// Any f32 of magnitude ≥ 0.5 is an exact multiple of 2⁻²⁴, so typical
    /// document values (pixel offsets, arc lengths) survive bit-exactly.
    #[test]
    fn representable_values_round_trip_exactly() {
        for v in [0.0f32, 1.0, -1.0, 0.5, -3.25, 1024.75, 65_536.125] {
            assert_eq!(f32::from(FracVal::from(v)), v);
        }
    }

    proptest! {
        #[test]
        fn quantization_error_is_within_one_step(v in -1.0e6f32..1.0e6) {
            let back = f32::from(FracVal::from(v));
            prop_assert!((f64::from(back) - f64::from(v)).abs() <= 2.0f64.powi(-24));
        }

        /// Truncation is monotone, so `FracVal`'s derived order agrees with
        /// f32 order (values within one step may collapse to equal).
        #[test]
        fn ordering_is_preserved(a in -1.0e6f32..1.0e6, b in -1.0e6f32..1.0e6) {
            let (fa, fb) = (FracVal::from(a), FracVal::from(b));
            if a <= b {
                prop_assert!(fa <= fb);
            } else {
                prop_assert!(fa >= fb);
            }
        }
    }
}