blockworx/presentation/

mod.rs

//! How the document actually appears on the canvas: where wires run
//! (solved route geometry), how big text really is (measured extents),
//! what color pin stubs show (accents propagated from route roles).
//! Everything here is computed *from* the authored document and lives
//! *beside* it — never authored, never undone, never persisted (the
//! editor-swap playbook, step 7; renamed from `derived` 2026-08-19,
//! which said how this is computed rather than what it is for).
//!
//! Owned by the app for the life of a session and threaded through
//! [`Drawing`](crate::widget::drawing::Drawing) like the spatial index,
//! mutably, because the passes that fill it run inside `Drawing` methods.
//! Each part is gated on the document's own stamp, so a commit that landed
//! anywhere — local, foreign, or an undo — re-derives it on the next
//! borrow and nothing has to remember to invalidate it. A live preview is
//! the one writer that does not follow the document: it *supposes*
//! geometry and says so ([`Presentation::routes_supposed`]), which is what
//! takes an abandoned drag's supposition back.

pub mod route;
pub mod store;

pub use route::{Crossing, LocAndDirection, RouteDirection, RouteEdge, RouteGeometry};

use ahash::HashMap;

use blockworx_doc::{
    document::{IndexedDocument, chronological},
    geometry::GridSize,
    id::{PinId, RouteId, TextId},
    rev::DocStamp,
};

use crate::edit::lower::accent_from_role;
use crate::path::Scope;

/// Solved geometry per route. Flat: route ids are document-wide unique,
/// so the scope key the map carried until 2026-08-19 (when a flat map let
/// each materialized scope overwrite the last one's geometry, because
/// legacy ids were minted per block) no longer distinguishes anything.
pub type RouteGeometries = HashMap<RouteId, RouteGeometry>;

#[derive(Default)]
pub struct Presentation {
    pub pin_accents: PinAccents,
    pub text_extents: TextExtents,
    /// A missing entry is a route that has not been materialized —
    /// nothing to draw or hit-test yet.
    pub routes: RouteGeometries,
    /// The document value [`Self::routes`] was materialized from, or `None`
    /// when a preview supposed geometry the document does not hold.
    routes_stamp: Option<DocStamp>,
}

impl Presentation {
    /// Bring the accent propagation up to date with the document behind
    /// `indexed`. Gated on the document's stamp, so the once-per-borrow
    /// call sites stay cheap.
    pub fn refresh_accents(&mut self, indexed: &IndexedDocument<'_>) {
        if self.pin_accents.stamp == Some(indexed.doc.stamp()) {
            return;
        }
        self.pin_accents.recompute(indexed);
    }

    /// Rebuild every scope's wire geometry from the authored waypoints
    /// behind `indexed`. Gated on the document's stamp like
    /// [`Self::refresh_accents`], so a borrow that changed nothing costs a
    /// comparison — and a commit that landed anywhere, local or foreign,
    /// re-derives the wires without anyone asking.
    ///
    /// The stamp is claimed before the pass runs: the materialization builds
    /// its own scoped [`Drawing`](crate::widget::drawing::Drawing)s, whose
    /// constructor calls back in here.
    pub fn refresh_routes(&mut self, indexed: &IndexedDocument<'_>) {
        if self.routes_stamp == Some(indexed.doc.stamp()) {
            return;
        }
        self.routes_stamp = Some(indexed.doc.stamp());
        crate::widget::drawing::materialize_document(indexed, self);
    }

    /// A throwaway presentation for a solve against a document that does not
    /// exist yet: the geometry the editor is showing, held as already
    /// materialized so the pass compares against what the user can see rather
    /// than re-deriving it. Measurement caches start empty — the solve reads
    /// neither.
    pub fn scratch(&self, indexed: &IndexedDocument<'_>) -> Self {
        Self {
            routes: self.routes.clone(),
            routes_stamp: Some(indexed.doc.stamp()),
            ..Self::default()
        }
    }

    /// A preview drew geometry the document does not hold, so the next
    /// borrow must re-derive it. Previews never move the document, hence
    /// never its stamp — this is how an abandoned drag's supposition is
    /// taken back.
    pub fn routes_supposed(&mut self) {
        self.routes_stamp = None;
    }
}

/// Route-role propagation onto pin stubs: a wire's accent colors the pins
/// it lands on. Presentation fresh from the routes — the last route at a
/// scope to touch a pin wins, including a plain (`None`) role — where the
/// document used to store the propagation and let it go stale.
///
/// Keyed by the *scope* the coloring happened in, not the pin's owner: one
/// pin is drawn twice, as its own block's boundary port and as a stub on
/// that block seen from the parent, and each drawing takes the accent of
/// the wires in the scope it is drawn in.
#[derive(Default)]
pub struct PinAccents {
    stamp: Option<DocStamp>,
    accents: HashMap<(Scope, PinId), Option<u8>>,
}

impl PinAccents {
    /// The stub accent of `pin` as drawn in `scope`.
    pub fn pin(&self, scope: Scope, pin: PinId) -> Option<u8> {
        self.accents.get(&(scope, pin)).copied().flatten()
    }

    fn recompute(&mut self, indexed: &IndexedDocument<'_>) {
        self.accents.clear();
        for id in chronological(indexed.doc.routes()) {
            let Some(route) = indexed.doc.route(&id) else {
                continue;
            };
            let accent = accent_from_role(route.role);
            let scope = Scope::from_wire(route.owner);
            for endpoint in [route.from, route.to] {
                self.accents.insert((scope, endpoint), accent);
            }
        }
        self.stamp = Some(indexed.doc.stamp());
    }
}

/// Galley-measured text-box extents, keyed by the text they were
/// measured for: an entry is consulted only while the box still holds
/// that text, so the cache can never serve a stale rect — undo, load,
/// or restore leave it self-invalidated and readers fall back to the
/// character-count estimate until the box is next edited.
#[derive(Default)]
pub struct TextExtents {
    map: HashMap<TextId, (String, GridSize)>,
}

impl TextExtents {
    pub fn set(&mut self, id: TextId, text: String, size: GridSize) {
        self.map.insert(id, (text, size));
    }

    /// The measured extent, if it was measured for exactly `current_text`.
    pub fn valid_for(&self, id: TextId, current_text: &str) -> Option<GridSize> {
        self.map
            .get(&id)
            .filter(|(text, _)| text == current_text)
            .map(|&(_, size)| size)
    }
}

/// The accent lookup for the pins of one shape, resolved by a caller that
/// knows which scope the shape is being drawn in.
#[derive(Clone, Copy)]
pub struct ShapeAccents<'a> {
    scope: Scope,
    accents: &'a PinAccents,
}

impl<'a> ShapeAccents<'a> {
    pub fn new(scope: Scope, accents: &'a PinAccents) -> Self {
        Self { scope, accents }
    }

    pub fn pin(&self, pin: PinId) -> Option<u8> {
        self.accents.pin(self.scope, pin)
    }
}