blockworx_doc/

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};

use crate::values::PinSide;

/// 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("pin slot {0} is outside the document extent ({GRID_LIMIT})")]
    Slot(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 {
    #[serde(default)]
    x: i32,
    #[serde(default)]
    y: i32,
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "RawGridPoint")]
pub struct GridPoint {
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub x: i32,
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    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 {
    #[serde(default)]
    w: u32,
    #[serde(default)]
    h: u32,
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "RawGridSize")]
pub struct GridSize {
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub w: u32,
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    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 })
    }
}

/// A grid-space delta. Deliberately not serializable: deltas never cross
/// the wire — commits carry the absolute values a delta produced.
#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash)]
pub struct GridVec {
    pub dx: i32,
    pub dy: i32,
}

impl GridVec {
    pub const ZERO: GridVec = GridVec { dx: 0, dy: 0 };

    pub const fn new(dx: i32, dy: i32) -> Self {
        Self { dx, dy }
    }
}

impl std::ops::Add<GridVec> for GridPoint {
    type Output = GridPoint;
    fn add(self, rhs: GridVec) -> GridPoint {
        GridPoint {
            x: self.x + rhs.dx,
            y: self.y + rhs.dy,
        }
    }
}

impl std::ops::Sub<GridPoint> for GridPoint {
    type Output = GridVec;
    fn sub(self, rhs: GridPoint) -> GridVec {
        GridVec::new(self.x - rhs.x, self.y - rhs.y)
    }
}

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

/// `contains` is closed on every edge while `intersects` is open on the
/// right and bottom — a point on a shared edge is inside both rects, yet
/// edge-adjacent rects do not overlap. Hit-testing rests on the
/// disagreement, so re-deriving either would move it.
impl GridRect {
    pub fn from_two_pos(a: GridPoint, b: GridPoint) -> Self {
        let min_x = a.x.min(b.x);
        let min_y = a.y.min(b.y);
        Self {
            top_left: GridPoint { x: min_x, y: min_y },
            size: GridSize {
                w: a.x.abs_diff(b.x),
                h: a.y.abs_diff(b.y),
            },
        }
    }

    pub fn max(self) -> GridPoint {
        GridPoint {
            x: self.right(),
            y: self.bottom(),
        }
    }

    pub fn left(self) -> i32 {
        self.top_left.x
    }

    pub fn top(self) -> i32 {
        self.top_left.y
    }

    pub fn right(self) -> i32 {
        self.top_left.x + self.size.w as i32
    }

    pub fn bottom(self) -> i32 {
        self.top_left.y + self.size.h as i32
    }

    pub fn contains(self, p: GridPoint) -> bool {
        p.x >= self.left() && p.x <= self.right() && p.y >= self.top() && p.y <= self.bottom()
    }

    pub fn intersects(self, other: GridRect) -> bool {
        self.left() < other.right()
            && other.left() < self.right()
            && self.top() < other.bottom()
            && other.top() < self.bottom()
    }

    /// The cells two rects share, or `None` where they share none. Open on
    /// the right and the bottom, as [`Self::intersects`] is.
    #[must_use]
    pub fn intersection(self, other: GridRect) -> Option<Self> {
        if !self.intersects(other) {
            return None;
        }
        let left = self.left().max(other.left());
        let top = self.top().max(other.top());
        let right = self.right().min(other.right());
        let bottom = self.bottom().min(other.bottom());
        Some(Self {
            top_left: GridPoint { x: left, y: top },
            size: GridSize {
                w: (right - left).unsigned_abs(),
                h: (bottom - top).unsigned_abs(),
            },
        })
    }

    #[must_use]
    pub fn translate(self, delta: GridVec) -> Self {
        Self {
            top_left: self.top_left + delta,
            size: self.size,
        }
    }
}

#[derive(Deserialize)]
struct RawPinSlot {
    #[serde(default)]
    side: PinSide,
    #[serde(default)]
    offset: u32,
}

/// Where a pin sits on its block-as-child: an edge and a slot index
/// (slots, not cells — the pitch is the editor's concern). Atomic: a
/// slot is one author's intent, and split registers could merge to an
/// edge one write chose and an offset another did.
#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "RawPinSlot")]
pub struct PinSlot {
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub side: PinSide,
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub offset: u32,
}

impl TryFrom<RawPinSlot> for PinSlot {
    type Error = OutOfExtent;
    fn try_from(raw: RawPinSlot) -> Result<Self, Self::Error> {
        if raw.offset > GRID_LIMIT.unsigned_abs() {
            return Err(OutOfExtent::Slot(raw.offset));
        }
        Ok(Self {
            side: raw.side,
            offset: raw.offset,
        })
    }
}

/// 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 {
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub pos: GridPoint,
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    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 {
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub x: FracVal,
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub y: FracVal,
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ScreenSize {
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub w: FracVal,
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    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 {
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub top_left: ScreenPoint,
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub size: ScreenSize,
}

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

    /// Edge-adjacent rects do not intersect (open on the right and
    /// bottom); overlapping ones do.
    #[test]
    fn intersects_is_open_on_the_right() {
        let rect = |x, y, w, h| GridRect {
            top_left: GridPoint { x, y },
            size: GridSize { w, h },
        };
        let a = rect(0, 0, 2, 2);
        assert!(!a.intersects(rect(2, 0, 2, 2)), "touching edges are apart");
        assert!(a.intersects(rect(1, 0, 2, 2)));
        assert!(!a.intersects(rect(0, 2, 2, 2)), "touching edges are apart");
        assert!(a.intersects(rect(0, 1, 2, 2)));
    }

    /// `contains` is closed on every edge — a point on the boundary is
    /// inside — which deliberately disagrees with `intersects` at the
    /// shared edge, which is what hit-testing rests on.
    #[test]
    fn contains_is_closed_on_every_edge() {
        let rect = GridRect {
            top_left: GridPoint { x: 0, y: 0 },
            size: GridSize { w: 2, h: 2 },
        };
        for corner in [
            GridPoint { x: 0, y: 0 },
            GridPoint { x: 2, y: 2 },
            GridPoint { x: 0, y: 2 },
            GridPoint { x: 2, y: 0 },
        ] {
            assert!(rect.contains(corner), "{corner:?} is on the boundary");
        }
        assert!(!rect.contains(GridPoint { x: 3, y: 0 }));
    }

    #[test]
    fn from_two_pos_normalizes_any_corner_pair() {
        let a = GridPoint { x: 5, y: -1 };
        let b = GridPoint { x: 2, y: 3 };
        let expected = GridRect {
            top_left: GridPoint { x: 2, y: -1 },
            size: GridSize { w: 3, h: 4 },
        };
        assert_eq!(GridRect::from_two_pos(a, b), expected);
        assert_eq!(GridRect::from_two_pos(b, a), expected);
        assert_eq!(expected.max(), GridPoint { x: 5, y: 3 });
    }

    #[test]
    fn translation_moves_the_corner_and_keeps_the_size() {
        let rect = GridRect {
            top_left: GridPoint { x: 1, y: 1 },
            size: GridSize { w: 2, h: 3 },
        };
        let moved = rect.translate(GridVec::new(3, -2));
        assert_eq!(moved.top_left, GridPoint { x: 4, y: -1 });
        assert_eq!(moved.size, rect.size);
        assert_eq!(moved.top_left - rect.top_left, GridVec::new(3, -2));
    }

    /// 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);
            }
        }
    }
}