blockworx/choreography/

mod.rs

//! The choreographer's substrate: given a document and one commit, a
//! [`Timeline`] depicting how that change could have been made. The contract
//! is `docs/choreographer-playbook.md` (C1–C8); the load-bearing rule is C3 —
//! a timeline is lossless, and [`Timeline::recovered`] rebuilding a commit
//! whose fold matches the real one is the oracle that keeps a rule from being
//! decorative.
//!
//! A derived layer beside `presentation`: presentation answers "where is the
//! wire now", this module answers "how did it get there", and only this one
//! has a clock — a caller-supplied `dt`, never a wall clock, which is what
//! makes a golden timeline a deterministic artifact. Nothing here is
//! authored, logged, or persisted, and the module draws nothing: it produces
//! [`Frame`]s, and painting one belongs to the UI half.

use core::time::Duration;
use std::sync::Arc;

use ahash::{HashMap, HashSet};

use blockworx_doc::block_model::{
    AreaUpdate, Block, BlockInit, BlockUpdate, Icon, ImageUpdate, Label, LabelUpdate, Pin,
    PinUpdate, RouteLabelUpdate, RouteUpdate, TextUpdate,
};
use blockworx_doc::commit::{Commit, CommitBuilder};
use blockworx_doc::document::{DocIndex, Document, IndexedDocument, TitleBlockUpdate};
use blockworx_doc::geometry::{
    FracVal, GridPoint, GridRect, GridSize, PinSlot, ScreenRect, ScreenSize,
};
use blockworx_doc::id::{
    AreaId, BlockId, EntityRef, ImageId, PinId, RouteId, RouteLabelId, TextId,
};
use blockworx_doc::opcode::{Crud, OpCodes};
use blockworx_doc::values::{LabelSide, PinDir, PinSide, Role};

use crate::edit::naming::{InterfaceLock, LabelVisibility, TagVisibility};
use crate::grid::{GRID_SIZE, pin_slot_row};
use crate::path::Scope;
use crate::presentation::Presentation;
use crate::progress::Progress;
use crate::tools::names::ToolName;

/// How long an entity takes to arrive.
const APPEAR: Duration = Duration::from_millis(600);
/// How long a shape takes to travel.
const MORPH: Duration = Duration::from_millis(500);
/// How much later each level of a delete cascade begins ([`Cascade`]).
const STAGGER: Duration = Duration::from_millis(120);

/// One commit, depicted: concurrent [`Track`]s under one clock, the
/// camera's advisory plan, and the one L1 [`Pantomime`]. The whole of what
/// the UI half plays.
///
/// The pantomime sits beside the tracks rather than among them because it
/// carries no op: [`Timeline::recovered`] rebuilds the commit from the
/// tracks, and a track whose op were optional would weaken C3 from "every
/// op lands in exactly one track" to "most of them do".
pub struct Timeline {
    label: String,
    duration: Duration,
    camera: Option<CameraPlan>,
    tracks: Vec<Track>,
    pantomime: Option<Pantomime>,
}

/// L1: what the *hand* did, as far as the commit's label and the L0
/// subjects can say — the tool a viewer should see ringed, the affordance
/// the gesture took hold of, and where a ghost cursor goes while it
/// happens. Data only; painting a ghost is the UI half's.
///
/// One per timeline, appended by [`synthesize`] and never authored by a
/// rule: a rule sees one op, and a gesture is the whole commit.
pub struct Pantomime {
    /// The tool to ring, where the label's verb and the subject name one.
    /// `None` where no tool performs the verb — the hand still travels,
    /// it simply rings nothing.
    pub tool: Option<ToolName>,
    pub affordance: Affordance,
    /// The ghost cursor's path, as [`TrackValue::Point`] keyframes on the
    /// same clock as the tracks.
    pub cursor: Vec<Keyframe>,
}

/// What a gesture takes hold of, named for the UI half to ring. Derived
/// from the primary subject and the shape of what the commit did to it;
/// never resolved to pixels here (C5).
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Affordance {
    /// Empty canvas: what arrives is drawn where nothing was.
    Canvas,
    /// The subject itself — its footprint, its anchor, or its length.
    Body(EntityRef),
    /// A corner of the subject's footprint: the grip a resize is made by.
    Handle(EntityRef),
    /// The stub on its owner's boundary that a pin is seen and grabbed by
    /// (7·2), rather than the port body drawn one scope in.
    Stub(EntityRef),
    /// One of the subject's written lines.
    Writing(EntityRef),
}

/// Where a played-back commit should look: the scope it happened in and the
/// world region that contains everything it touched. Advisory — never part
/// of the C3 oracle.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct CameraPlan {
    pub scope: Scope,
    pub region: GridRect,
}

/// One op's depiction. The op itself rides along verbatim — that is what
/// makes [`Timeline::recovered`] total, so the oracle guards coverage and
/// order while the keyframes stay free to depict.
pub struct Track {
    pub subject: EntityRef,
    pub kind: TrackKind,
    op: OpCodes,
    pub keys: Vec<Keyframe>,
}

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum TrackKind {
    Appear,
    Vanish,
    Morph,
    Emphasis,
    Overlay,
    Pantomime,
}

impl TrackKind {
    /// How a two-key track approaches its arrival, decided once here so no
    /// two rules can disagree: a depiction that moves eases into what it
    /// lands on, and one that steps has no approach to shape.
    fn arrival(self) -> Easing {
        match self {
            TrackKind::Appear | TrackKind::Vanish | TrackKind::Morph => Easing::EaseOut,
            TrackKind::Emphasis | TrackKind::Overlay | TrackKind::Pantomime => Easing::Linear,
        }
    }
}

/// A moment on a track: when, what value the depiction has reached, and how
/// the approach from the previous key is shaped.
#[derive(Clone, PartialEq, Debug)]
pub struct Keyframe {
    pub at: Duration,
    pub value: TrackValue,
    pub easing: Easing,
}

/// What a keyframe holds. Each variant is a shape the UI half must paint
/// differently: a grid footprint, a bare anchor, the document's one
/// unsnapped (world-pixel) artwork box, a solved wire polyline, and the two
/// authored pairs — a place along a wire and a place along a shape's side —
/// that only the painter can resolve to a point.
///
/// `Settled` is the value-free one: the stand-in of a rule that has not
/// landed yet (the op is carried, so C3 holds, but nothing is depicted —
/// step 7·6 removes the last of those), and the answer of the few landed
/// arms whose subject has no geometry at all.
#[derive(Clone, PartialEq, Debug)]
pub enum TrackValue {
    Rect(GridRect),
    Point(GridPoint),
    Artwork(ScreenRect),
    /// `Arc`: a keyframe is cloned once per played frame, and a polyline
    /// is the one value here that is not two numbers wide.
    Path(Arc<[GridPoint]>),
    Along {
        route: RouteId,
        at: FracVal,
    },
    /// A placed label: the pair its shape holds, for the same reason
    /// [`TrackValue::Along`] is a pair — the projection that resolves an
    /// offset on a side to a point speaks the UI toolkit's geometry, so
    /// the painter resolves it (C5).
    Label {
        slot: LabelSlot,
        side: LabelSide,
        offset: FracVal,
    },
    /// One written string. A keyframe pair is a **crossfade** and holds
    /// both strings, so a rename still says what the register became (C3).
    Text {
        of: Written,
        /// `Arc`: a keyframe is cloned once per played frame.
        text: Arc<str>,
    },
    /// One discrete register's value. A keyframe pair **steps** at its
    /// second key: two enum values have no ground between them for a
    /// depiction to cross, so nothing is drawn in between.
    Flag {
        at: Site,
        state: FlagState,
    },
    Settled,
}

/// Which of a shape's placeable labels a [`TrackValue::Label`] carries: a
/// block has both, an area only its title.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum LabelSlot {
    Title,
    TypeLabel,
}

/// Where a written value shows, as far as the document can say: on a shape
/// it places, at a bare anchor, along a wire, or in the drawing's own
/// title block. The exact spot is the painter's — placing a label needs a
/// text width, and measuring text is the UI toolkit's job (C5) — so this
/// names the place to *look at*, and is what the camera plans from.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Site {
    Shape(GridRect),
    Anchor(GridPoint),
    /// A wire's own registers show wherever its labels do — an arc length
    /// along the polyline, the same seam as [`TrackValue::Along`].
    Wire,
    /// The title block in the sheet's corner, which is chrome pinned to
    /// the viewport rather than anything on the canvas: the document's
    /// own name has no world position at all, so it frames nothing.
    Sheet,
}

impl Site {
    fn bounds(self) -> Option<GridRect> {
        match self {
            Site::Shape(rect) => Some(rect),
            Site::Anchor(at) => Some(spot(at)),
            Site::Wire | Site::Sheet => None,
        }
    }
}

/// Which written line, and where it reads: without the first the painter
/// could not tell which of a block's two strings is being rewritten, and
/// without the second the camera could not frame it.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct Written {
    pub at: Site,
    pub line: TextLine,
}

/// The written lines an entity carries: a shape has two labels, a pin has
/// three lines, a text box and a wire have one each, and the drawing
/// itself has the name its title block states.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum TextLine {
    Label(LabelSlot),
    Pin(PinLine),
    /// A text box, which is nothing but its content.
    Content,
    WireName,
    DocumentName,
}

/// A pin's three written lines: what it is called, what it carries, and
/// where it is on the board.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum PinLine {
    Name,
    Type,
    Tag,
}

impl PinLine {
    fn of(self, pin: &Pin) -> &str {
        match self {
            PinLine::Name => pin.name.as_ref(),
            PinLine::Type => pin.type_name.as_ref(),
            PinLine::Tag => pin.tag.as_ref(),
        }
    }
}

/// A discrete register and the value it holds: a colour role, an interface
/// lock, a signal direction, a tag's visibility, and whether a shape draws
/// one of its two placed labels.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum FlagState {
    Accent(Role),
    Lock(InterfaceLock),
    Direction(PinDir),
    Tag(TagVisibility),
    Label(LabelSlot, LabelVisibility),
}

impl TrackValue {
    /// The grid region this value covers, for the camera's advisory plan.
    fn bounds(&self) -> Option<GridRect> {
        match self {
            TrackValue::Rect(r) => Some(*r),
            TrackValue::Point(p) => Some(spot(*p)),
            TrackValue::Artwork(r) => Some(grid_bounds(*r)),
            TrackValue::Path(points) => points.iter().map(|p| spot(*p)).reduce(union),
            TrackValue::Text { of, .. } => of.at.bounds(),
            TrackValue::Flag { at, .. } => at.bounds(),
            // An arc length along a solved polyline, and an offset along a
            // shape's side: only the painter can place either, so they
            // frame nothing.
            TrackValue::Along { .. } | TrackValue::Label { .. } | TrackValue::Settled => None,
        }
    }
}

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Easing {
    Linear,
    EaseOut,
}

impl Easing {
    fn apply(self, p: Progress) -> Progress {
        let t = f32::from(p);
        match self {
            Easing::Linear => p,
            Easing::EaseOut => Progress::new(1.0 - (1.0 - t) * (1.0 - t)),
        }
    }
}

/// Where playback stands. Advanced by the caller's `dt`; the module never
/// reads a clock (C4).
#[derive(Clone, Copy, Default, PartialEq, Eq, Debug)]
pub struct Playhead {
    pub elapsed: Duration,
}

impl Playhead {
    pub fn advance(&mut self, dt: Duration) {
        self.elapsed = self.elapsed.saturating_add(dt);
    }

    pub fn done(self, timeline: &Timeline) -> bool {
        self.elapsed >= timeline.duration
    }
}

/// One playback instant, ready to paint: every track's subject, kind,
/// interpolated value, and progress, plus where the ghost hand is. The UI
/// half's entire input.
pub struct Frame {
    pub tracks: Vec<FrameTrack>,
    pub ghost: Option<Ghost>,
}

/// The [`Pantomime`] at one instant: what to ring, what to name, and where
/// the hand is.
pub struct Ghost {
    pub tool: Option<ToolName>,
    pub affordance: Affordance,
    /// Grid cells, fractional — the hand moves between the positions the
    /// document knows, as every other interpolated value does.
    pub at: [f32; 2],
}

pub struct FrameTrack {
    pub subject: EntityRef,
    pub kind: TrackKind,
    pub value: FrameValue,
    pub progress: Progress,
}

/// An interpolated value: fractional, because animation happens between the
/// grid positions the document knows. `Rect`, `Point` and `Path` are in
/// grid cells; `Artwork` is in world pixels, as the document stores it.
#[derive(Clone, PartialEq, Debug)]
pub enum FrameValue {
    Rect {
        min: [f32; 2],
        max: [f32; 2],
    },
    Point {
        at: [f32; 2],
    },
    Artwork {
        min: [f32; 2],
        max: [f32; 2],
    },
    Path(Vec<[f32; 2]>),
    Along {
        route: RouteId,
        at: f32,
    },
    Label {
        slot: LabelSlot,
        side: LabelSide,
        offset: f32,
    },
    /// A crossfade in progress: both strings, and how far it has run.
    Text {
        of: Written,
        from: Arc<str>,
        to: Arc<str>,
        mix: Progress,
    },
    /// A step: at any instant exactly one discrete value is true.
    Flag {
        at: Site,
        state: FlagState,
    },
    Settled,
}

impl Timeline {
    pub fn duration(&self) -> Duration {
        self.duration
    }

    pub fn label(&self) -> &str {
        &self.label
    }

    pub fn camera(&self) -> Option<CameraPlan> {
        self.camera
    }

    pub fn tracks(&self) -> &[Track] {
        &self.tracks
    }

    pub fn pantomime(&self) -> Option<&Pantomime> {
        self.pantomime.as_ref()
    }

    /// 7·6's whole-inventory probe: the tracks that depict nothing but the
    /// op they carry. A payload op is the one op with nothing to depict by
    /// design — its bytes are invisible, and what the user sees is the
    /// image referencing them (7·2) — so it is the one subject excused.
    #[cfg(test)]
    pub(crate) fn undepicted(&self) -> Vec<&Track> {
        self.tracks
            .iter()
            .filter(|track| !matches!(track.subject, EntityRef::Asset(_)))
            .filter(|track| {
                track
                    .keys
                    .iter()
                    .all(|key| key.value == TrackValue::Settled)
            })
            .collect()
    }

    /// The commit this timeline depicts, rebuilt from its tracks — the C3
    /// oracle's left hand. Op order is track order, which is the commit's
    /// own op order, so the write sequence survives the round trip.
    pub fn recovered(&self) -> Option<Commit> {
        let mut builder = CommitBuilder::new(self.label.clone());
        for track in &self.tracks {
            builder.push(track.op.clone());
        }
        builder.seal()
    }

    /// The playback instant at `t`.
    pub fn at(&self, t: Duration) -> Frame {
        Frame {
            tracks: self.tracks.iter().map(|track| track.at(t)).collect(),
            ghost: self.pantomime.as_ref().map(|mime| mime.at(t)),
        }
    }

    /// The reviewable text form the goldens pin: every fact a reviewer needs
    /// to judge a depiction, and nothing environment-dependent.
    pub fn describe(&self) -> String {
        let mut lines = vec![
            format!("label: {}", self.label),
            format!("duration: {}ms", ms(self.duration)),
        ];
        lines.push(match self.camera {
            None => "camera: none".to_owned(),
            Some(CameraPlan { scope, region }) => {
                let scope = match scope {
                    Scope::Root => "root".to_owned(),
                    Scope::Block(id) => format!("block {id}"),
                };
                format!("camera: {scope} {}", rect(region))
            }
        });
        for track in &self.tracks {
            lines.push(format!("track {} {}", track.subject, kind_name(track.kind)));
            keys(&mut lines, &track.keys);
        }
        match &self.pantomime {
            None => lines.push("pantomime: none".to_owned()),
            Some(mime) => {
                lines.push(format!(
                    "pantomime: tool {}, {}",
                    match mime.tool {
                        None => "none".to_owned(),
                        Some(tool) => format!("{tool:?}"),
                    },
                    affordance_name(mime.affordance),
                ));
                keys(&mut lines, &mime.cursor);
            }
        }
        lines.push(String::new());
        lines.join("\n")
    }
}

fn keys(lines: &mut Vec<String>, keys: &[Keyframe]) {
    for key in keys {
        lines.push(format!(
            "  {}ms {} {}",
            ms(key.at),
            easing_name(key.easing),
            value(&key.value),
        ));
    }
}

fn affordance_name(affordance: Affordance) -> String {
    match affordance {
        Affordance::Canvas => "canvas".to_owned(),
        Affordance::Body(at) => format!("body {at}"),
        Affordance::Handle(at) => format!("handle {at}"),
        Affordance::Stub(at) => format!("stub {at}"),
        Affordance::Writing(at) => format!("writing {at}"),
    }
}

fn ms(d: Duration) -> u128 {
    d.as_millis()
}

fn rect(r: GridRect) -> String {
    format!(
        "[{} {} {}x{}]",
        r.top_left.x, r.top_left.y, r.size.w, r.size.h
    )
}

fn point(p: GridPoint) -> String {
    format!("[{} {}]", p.x, p.y)
}

/// Two decimals: world-pixel geometry is fixed-point, and a golden must
/// not turn on the last bit of an `f32` rendering.
fn artwork(r: ScreenRect) -> String {
    let (x, y) = (f32::from(r.top_left.x), f32::from(r.top_left.y));
    let (w, h) = (f32::from(r.size.w), f32::from(r.size.h));
    format!("[{x:.2} {y:.2} {w:.2}x{h:.2}]")
}

fn value(v: &TrackValue) -> String {
    match v {
        TrackValue::Rect(r) => format!("rect {}", rect(*r)),
        TrackValue::Point(p) => format!("point {}", point(*p)),
        TrackValue::Artwork(r) => format!("artwork {}", artwork(*r)),
        TrackValue::Path(points) => {
            let corners: Vec<String> = points.iter().map(|p| point(*p)).collect();
            format!("path {}", corners.join(" -> "))
        }
        TrackValue::Along { route, at } => {
            format!("along route {route} at {:.2}", f32::from(*at))
        }
        TrackValue::Label { slot, side, offset } => format!(
            "label {} {} at {:.2}",
            slot_name(*slot),
            side_name(*side),
            f32::from(*offset),
        ),
        TrackValue::Text { of, text } => {
            format!("text {} {} {text:?}", site_name(of.at), line_name(of.line))
        }
        TrackValue::Flag { at, state } => {
            format!("flag {} {}", site_name(*at), flag_name(*state))
        }
        TrackValue::Settled => "settled".to_owned(),
    }
}

fn site_name(at: Site) -> String {
    match at {
        Site::Shape(r) => rect(r),
        Site::Anchor(p) => point(p),
        Site::Wire => "wire".to_owned(),
        Site::Sheet => "sheet".to_owned(),
    }
}

fn line_name(line: TextLine) -> &'static str {
    match line {
        TextLine::Label(slot) => slot_name(slot),
        TextLine::Pin(PinLine::Name) => "pin-name",
        TextLine::Pin(PinLine::Type) => "pin-type",
        TextLine::Pin(PinLine::Tag) => "pin-tag",
        TextLine::Content => "content",
        TextLine::WireName => "wire-name",
        TextLine::DocumentName => "document-name",
    }
}

fn flag_name(state: FlagState) -> String {
    match state {
        FlagState::Accent(role) => format!("role {}", role_name(role)),
        FlagState::Lock(InterfaceLock::Locked) => "lock locked".to_owned(),
        FlagState::Lock(InterfaceLock::Unlocked) => "lock unlocked".to_owned(),
        FlagState::Direction(dir) => format!("dir {}", dir_name(dir)),
        FlagState::Tag(TagVisibility::Shown) => "tag shown".to_owned(),
        FlagState::Tag(TagVisibility::Hidden) => "tag hidden".to_owned(),
        FlagState::Label(slot, LabelVisibility::Shown) => {
            format!("{} shown", slot_name(slot))
        }
        FlagState::Label(slot, LabelVisibility::Hidden) => {
            format!("{} hidden", slot_name(slot))
        }
    }
}

fn role_name(role: Role) -> &'static str {
    match role {
        Role::Accent0 => "plain",
        Role::Accent1 => "accent1",
        Role::Accent2 => "accent2",
        Role::Accent3 => "accent3",
        Role::Accent4 => "accent4",
        Role::Accent5 => "accent5",
        Role::Accent6 => "accent6",
        Role::Accent7 => "accent7",
        Role::Accent8 => "accent8",
    }
}

fn dir_name(dir: PinDir) -> &'static str {
    match dir {
        PinDir::Input => "input",
        PinDir::Output => "output",
        PinDir::InOut => "in-out",
    }
}

fn slot_name(slot: LabelSlot) -> &'static str {
    match slot {
        LabelSlot::Title => "title",
        LabelSlot::TypeLabel => "type",
    }
}

fn side_name(side: LabelSide) -> &'static str {
    match side {
        LabelSide::Top => "top",
        LabelSide::Center => "center",
        LabelSide::Bottom => "bottom",
    }
}

fn kind_name(kind: TrackKind) -> &'static str {
    match kind {
        TrackKind::Appear => "appear",
        TrackKind::Vanish => "vanish",
        TrackKind::Morph => "morph",
        TrackKind::Emphasis => "emphasis",
        TrackKind::Overlay => "overlay",
        TrackKind::Pantomime => "pantomime",
    }
}

fn easing_name(e: Easing) -> &'static str {
    match e {
        Easing::Linear => "linear",
        Easing::EaseOut => "ease-out",
    }
}

impl Track {
    fn end(&self) -> Duration {
        ends(&self.keys).1
    }

    /// When this track's depiction begins — read by the stagger's proof.
    #[cfg(test)]
    fn start(&self) -> Duration {
        ends(&self.keys).0
    }

    /// This track's state at `t`.
    fn at(&self, t: Duration) -> FrameTrack {
        let (start, end) = ends(&self.keys);
        FrameTrack {
            subject: self.subject,
            kind: self.kind,
            value: sample(&self.keys, t),
            progress: Progress::through(t.saturating_sub(start), end.saturating_sub(start)),
        }
    }
}

/// The window a key list occupies. A lone key holds the value its window
/// *ends* on, so it runs from the top; only the delete cascade's stagger
/// ([`Cascade`]) moves a start off zero.
fn ends(keys: &[Keyframe]) -> (Duration, Duration) {
    let end = keys.last().map_or(Duration::ZERO, |k| k.at);
    match keys {
        [first, _, ..] => (first.at, end),
        _ => (Duration::ZERO, end),
    }
}

/// A key list's value at `t`: the bracketing keys interpolated under the
/// later key's easing, clamped to the ends. Shared by the tracks and the
/// ghost cursor, which is a key list like any other.
fn sample(keys: &[Keyframe], t: Duration) -> FrameValue {
    match keys {
        [] => FrameValue::Settled,
        [only] => frame_value(&only.value),
        keys => match keys.iter().position(|k| k.at > t) {
            None => frame_value(&keys[keys.len() - 1].value),
            Some(0) => frame_value(&keys[0].value),
            Some(i) => {
                let (from, to) = (&keys[i - 1], &keys[i]);
                let local =
                    Progress::through(t.saturating_sub(from.at), to.at.saturating_sub(from.at));
                lerp(&from.value, &to.value, to.easing.apply(local))
            }
        },
    }
}

fn cell(v: i32) -> f32 {
    v as f32
}

fn corners(r: GridRect) -> ([f32; 2], [f32; 2]) {
    (
        [cell(r.left()), cell(r.top())],
        [cell(r.right()), cell(r.bottom())],
    )
}

fn px_corners(r: ScreenRect) -> ([f32; 2], [f32; 2]) {
    let min = [f32::from(r.top_left.x), f32::from(r.top_left.y)];
    (
        min,
        [min[0] + f32::from(r.size.w), min[1] + f32::from(r.size.h)],
    )
}

fn frame_value(v: &TrackValue) -> FrameValue {
    match v {
        TrackValue::Settled => FrameValue::Settled,
        TrackValue::Rect(r) => {
            let (min, max) = corners(*r);
            FrameValue::Rect { min, max }
        }
        TrackValue::Point(p) => FrameValue::Point {
            at: [cell(p.x), cell(p.y)],
        },
        TrackValue::Artwork(r) => {
            let (min, max) = px_corners(*r);
            FrameValue::Artwork { min, max }
        }
        TrackValue::Path(points) => {
            FrameValue::Path(points.iter().map(|p| [cell(p.x), cell(p.y)]).collect())
        }
        TrackValue::Along { route, at } => FrameValue::Along {
            route: *route,
            at: f32::from(*at),
        },
        TrackValue::Label { slot, side, offset } => FrameValue::Label {
            slot: *slot,
            side: *side,
            offset: f32::from(*offset),
        },
        // A lone text key is a crossfade that has already run: the string
        // it holds is both ends of it.
        TrackValue::Text { of, text } => FrameValue::Text {
            of: *of,
            from: text.clone(),
            to: text.clone(),
            mix: Progress::one(),
        },
        TrackValue::Flag { at, state } => FrameValue::Flag {
            at: *at,
            state: *state,
        },
    }
}

fn lerp(from: &TrackValue, to: &TrackValue, p: Progress) -> FrameValue {
    let t = f32::from(p);
    let mix = |a: [f32; 2], b: [f32; 2]| [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
    match (frame_value(from), frame_value(to)) {
        (FrameValue::Rect { min: a0, max: a1 }, FrameValue::Rect { min: b0, max: b1 }) => {
            FrameValue::Rect {
                min: mix(a0, b0),
                max: mix(a1, b1),
            }
        }
        (FrameValue::Artwork { min: a0, max: a1 }, FrameValue::Artwork { min: b0, max: b1 }) => {
            FrameValue::Artwork {
                min: mix(a0, b0),
                max: mix(a1, b1),
            }
        }
        (FrameValue::Point { at: a }, FrameValue::Point { at: b }) => {
            FrameValue::Point { at: mix(a, b) }
        }
        (FrameValue::Path(from), FrameValue::Path(to)) => FrameValue::Path(wipe(&from, &to, t)),
        (FrameValue::Along { route: a, at: x }, FrameValue::Along { route: b, at: y })
            if a == b =>
        {
            FrameValue::Along {
                route: a,
                at: x + (y - x) * t,
            }
        }
        // A side change is a step, not a slide: the label lands on its new
        // side and travels the offset along it.
        (
            FrameValue::Label { offset: x, .. },
            FrameValue::Label {
                slot,
                side,
                offset: y,
            },
        ) => FrameValue::Label {
            slot,
            side,
            offset: x + (y - x) * t,
        },
        // A text morph is a crossfade: both strings reach the painter, so
        // what it draws is the one turning into the other.
        (FrameValue::Text { from, .. }, FrameValue::Text { of, to: now, .. }) => FrameValue::Text {
            of,
            from,
            to: now,
            mix: p,
        },
        // A discrete register steps at its arrival: there is nothing
        // between two enum values to draw on the way.
        (FrameValue::Flag { state: was, .. }, FrameValue::Flag { at, state: now }) => {
            FrameValue::Flag {
                at,
                state: if p.is_complete() { now } else { was },
            }
        }
        // A track never mixes value shapes; anything else settles.
        (_, settled) => settled,
    }
}

/// A path keyframe pair is an **arc-length wipe**, never a corner-by-corner
/// mix: what is drawn is always a prefix of one real polyline, so every leg
/// stays orthogonal and no wire is shown in a shape no wire can have. A
/// pair ending on a seed — a one-point list — retracts the path it starts
/// from; every other pair draws the one it ends on. A wire whose corner
/// list is rewritten therefore stages: it is rubbed out and redrawn, which
/// is what its op does to the list, and it needs no answer to the question
/// of which corner of one solve became which corner of the other.
fn wipe(from: &[[f32; 2]], to: &[[f32; 2]], t: f32) -> Vec<[f32; 2]> {
    if to.len() < 2 && from.len() > 1 {
        reveal(from, 1.0 - t)
    } else {
        reveal(to, t)
    }
}

/// The prefix of `points` covering fraction `t` of its arc length, ending
/// part-way along a leg where the fraction falls there.
fn reveal(points: &[[f32; 2]], t: f32) -> Vec<[f32; 2]> {
    if t >= 1.0 {
        return points.to_vec();
    }
    let leg = |a: [f32; 2], b: [f32; 2]| ((b[0] - a[0]).powi(2) + (b[1] - a[1]).powi(2)).sqrt();
    let Some(&start) = points.first() else {
        return Vec::new();
    };
    let mut drawn = vec![start];
    let mut left = points
        .windows(2)
        .map(|pair| leg(pair[0], pair[1]))
        .sum::<f32>()
        * t.max(0.0);
    for pair in points.windows(2) {
        let length = leg(pair[0], pair[1]);
        if length <= left {
            drawn.push(pair[1]);
            left -= length;
            continue;
        }
        if left > 0.0 {
            let f = left / length;
            drawn.push([
                pair[0][0] + (pair[1][0] - pair[0][0]) * f,
                pair[0][1] + (pair[1][1] - pair[0][1]) * f,
            ]);
        }
        break;
    }
    drawn
}

impl Pantomime {
    /// Where the ghost hand is at `t`, and what it is over.
    fn at(&self, t: Duration) -> Ghost {
        Ghost {
            tool: self.tool,
            affordance: self.affordance,
            at: match sample(&self.cursor, t) {
                FrameValue::Point { at } => at,
                // [`cursor`] builds nothing but `Point` keys, and never an
                // empty list.
                _ => [0.0, 0.0],
            },
        }
    }
}

/// L1, appended once per timeline (7·6): the hand behind the commit.
///
/// Two inputs, and the split between them is the contract. The **label**
/// says what the user reached for — this is L1's one sanctioned reading of
/// it (C2), and only its leading verb is read. The **L0 tracks** say what
/// the hand touched and where, so a pantomime never claims geometry the
/// rules did not already derive.
///
/// A label whose verb no *tool* says is not evidence a hand did anything
/// on the canvas: a delete, a paste, a flag from a menu were given from
/// the chrome, and there is no gesture to mime. Those get no pantomime,
/// and neither does a commit that depicts nothing to point at.
fn pantomime(scene: &Scene<'_>, label: &str, tracks: &[Track]) -> Option<Pantomime> {
    let verb = Verb::opening(label)?;
    let depicted = || {
        tracks
            .iter()
            .filter_map(|track| Some((track, track_region(scene, track)?)))
    };
    // The subject the verb answers to, where the commit has one: a wire
    // that stamps its own destination pin writes both, and it is the wire
    // the hand was drawing.
    let (track, region) = depicted()
        .find(|(track, _)| verb.armed(track).is_some())
        .or_else(|| depicted().next())?;
    Some(Pantomime {
        tool: verb.armed(track),
        affordance: affordance(scene, track),
        cursor: cursor(track, region),
    })
}

/// The verb a commit's label opens with, which is the only part of a label
/// L1 reads. The vocabulary is exactly [`ToolName::verb`]'s outputs plus
/// the two verbs the editor says without a tool behind them — the
/// substitute `edit::describe` makes when a gesture names something that
/// had no name, and the arrow keys' nudge. A label that begins with
/// anything else was written by a command, an import, or a restore, and
/// no hand is mimed for it.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Verb {
    Add,
    Create,
    Edit,
    Modify,
    Move,
    Rename,
    Resize,
    Retype,
}

impl Verb {
    fn opening(label: &str) -> Option<Self> {
        let word = label.split_whitespace().next()?.to_ascii_lowercase();
        Some(match word.as_str() {
            "add" => Verb::Add,
            "create" => Verb::Create,
            "edit" => Verb::Edit,
            "modify" => Verb::Modify,
            // The arrow keys are the one hand gesture no tool is armed
            // for, and they do what a drag does.
            "move" | "nudge" => Verb::Move,
            // "Name" is what `edit::describe` says instead of "Rename"
            // when the register it names had nothing in it.
            "rename" | "name" => Verb::Rename,
            "resize" => Verb::Resize,
            "retype" => Verb::Retype,
            _ => return None,
        })
    }

    /// The tool to ring: the one table, total over the verbs a label can
    /// open with crossed with the subjects L0 found. `None` where the two
    /// name no tool — the hand still travels, it simply rings nothing.
    fn armed(self, track: &Track) -> Option<ToolName> {
        use EntityRef as E;
        let artwork = track
            .keys
            .iter()
            .any(|key| matches!(key.value, TrackValue::Artwork(_)));
        Some(match (self, track.subject) {
            // A block's one piece of artwork is its icon.
            (Verb::Add, E::Block(_)) if artwork => ToolName::Icon,
            (Verb::Add, E::Block(_)) => ToolName::NewBlock,
            (Verb::Add, E::Area(_)) => ToolName::NewArea,
            (Verb::Add, E::Pin(_)) => ToolName::AddPort,
            (Verb::Add, E::Image(_)) => ToolName::NewImage,
            (Verb::Add, E::Text(_)) => ToolName::AddText,
            (Verb::Add, E::RouteLabel(_)) => ToolName::AddRouteLabel,
            (Verb::Create, E::Route(_)) => ToolName::Route,
            (Verb::Move, E::Block(_)) => match written_slot(track) {
                Some(LabelSlot::Title) => ToolName::MoveTitle,
                Some(LabelSlot::TypeLabel) => ToolName::MoveBlockType,
                // One tool drags every shape, whatever the toolbar calls
                // it.
                None => ToolName::MoveBlock,
            },
            (Verb::Move, E::Area(_) | E::Text(_) | E::Image(_)) => ToolName::MoveBlock,
            (Verb::Move, E::Pin(_)) => ToolName::MovePin,
            (Verb::Move, E::RouteLabel(_)) => ToolName::MoveLabel,
            (Verb::Resize, E::Block(_) | E::Area(_) | E::Image(_)) => ToolName::ResizeBlock,
            (Verb::Modify, E::Route(_)) => ToolName::EditRoute,
            (Verb::Rename, E::Pin(_)) => ToolName::RenamePin,
            (Verb::Rename, E::Route(_)) => ToolName::RenameRoute,
            (Verb::Rename, E::Block(_) | E::Area(_)) => ToolName::RenameTitle,
            (Verb::Retype, E::Pin(_)) => ToolName::RetypePin,
            (Verb::Retype, E::Block(_)) => ToolName::RenameBlockType,
            (Verb::Edit, E::Text(_)) => ToolName::EditTextBox,
            // A verb the subject does not answer to: the gesture reached
            // the document some other way, and the toolbar shows nothing.
            _ => return None,
        })
    }
}

/// Which of a shape's two placed labels a track writes or places, where it
/// does either.
fn written_slot(track: &Track) -> Option<LabelSlot> {
    track.keys.iter().find_map(|key| match key.value {
        TrackValue::Label { slot, .. }
        | TrackValue::Text {
            of:
                Written {
                    line: TextLine::Label(slot),
                    ..
                },
            ..
        } => Some(slot),
        _ => None,
    })
}

/// What the gesture took hold of, read off the depiction rather than off
/// the op: a written line is grabbed by its writing, a pin by the stub it
/// is seen on (7·2) unless the op moves its port body, and a travel that
/// changes a footprint's *size* was made by its corner rather than by its
/// middle. An arrival is drawn on bare canvas — except where the pre-image
/// already holds the subject, which is the icon a block gains.
fn affordance(scene: &Scene<'_>, track: &Track) -> Affordance {
    let subject = track.subject;
    let holds = |of: fn(&TrackValue) -> bool| track.keys.iter().any(|key| of(&key.value));
    if holds(|value| {
        matches!(
            value,
            TrackValue::Text { .. } | TrackValue::Along { .. } | TrackValue::Label { .. }
        )
    }) {
        return Affordance::Writing(subject);
    }
    if matches!(subject, EntityRef::Pin(_)) && !holds(|value| matches!(value, TrackValue::Rect(_)))
    {
        return Affordance::Stub(subject);
    }
    match track.kind {
        TrackKind::Appear if !scene.held(subject) => Affordance::Canvas,
        TrackKind::Morph if resizes(track) => Affordance::Handle(subject),
        _ => Affordance::Body(subject),
    }
}

/// Whether a travel changes its subject's extent rather than only its
/// place.
fn resizes(track: &Track) -> bool {
    let extent = |key: &Keyframe| key.value.bounds().map(|r| r.size);
    match (track.keys.first(), track.keys.last()) {
        (Some(first), Some(last)) => extent(first) != extent(last),
        _ => false,
    }
}

/// The ghost cursor's path, decided once per [`TrackKind`] so no rule
/// invents one:
///
/// - what **arrives** is drawn into place — the hand enters at the framed
///   region's edge, puts its pen down on the seed the shape grows out of,
///   and drags to the far corner it ends on;
/// - what **travels** is carried — the hand starts on the pre-image and
///   goes the whole way with it;
/// - what **goes**, and what merely **changes**, is reached for and dwelt
///   on — the hand arrives half way through and stays while the change
///   lands, because there is nothing for it to drag.
fn cursor(track: &Track, region: GridRect) -> Vec<Keyframe> {
    let (start, end) = ends(&track.keys);
    let bounds = |key: &Keyframe| key.value.bounds().unwrap_or(region);
    let (first, last) = match (track.keys.first(), track.keys.last()) {
        (Some(first), Some(last)) => (bounds(first), bounds(last)),
        _ => (region, region),
    };
    let reached = start + end.saturating_sub(start) / 2;
    let hold = |at: GridPoint| {
        vec![
            step(start, entry(region, at)),
            step(reached, at),
            step(end, at),
        ]
    };
    match track.kind {
        TrackKind::Appear => {
            let seed = first.top_left;
            let far = track.keys.last().map_or(region.top_left, |key| {
                landing(&key.value).unwrap_or(GridPoint {
                    x: last.right(),
                    y: last.bottom(),
                })
            });
            vec![
                step(start, entry(region, seed)),
                step(reached, seed),
                step(end, far),
            ]
        }
        TrackKind::Morph => vec![step(start, center(first)), step(end, center(last))],
        TrackKind::Vanish | TrackKind::Emphasis | TrackKind::Overlay => hold(center(first)),
        // A pantomime is the ghost; it is never an L0 track, and the arm
        // is here so the policy stays total over the kinds.
        TrackKind::Pantomime => hold(center(last)),
    }
}

/// Where a hand that drew this value lets go: the far end of a stroke,
/// which is a real point on the wire rather than a corner of the box
/// around it. Every other value is a region, and its far corner is the
/// caller's business.
fn landing(value: &TrackValue) -> Option<GridPoint> {
    match value {
        TrackValue::Path(points) => points.last().copied(),
        _ => None,
    }
}

fn step(at: Duration, to: GridPoint) -> Keyframe {
    Keyframe {
        at,
        value: TrackValue::Point(to),
        easing: Easing::EaseOut,
    }
}

/// Where the hand comes in from: the nearer of the framed region's two
/// vertical edges, at the row it is heading for. A hand already at the
/// edge simply starts there.
fn entry(region: GridRect, toward: GridPoint) -> GridPoint {
    let (left, right) = (region.left(), region.right());
    GridPoint {
        x: if toward.x - left <= right - toward.x {
            left
        } else {
            right
        },
        y: toward.y,
    }
}

/// The whole substrate in one call (C1): pure over the document the commit
/// was written against and the commit itself.
pub fn synthesize(before: &IndexedDocument<'_>, commit: &Commit) -> Timeline {
    let after = before.doc.try_apply(commit).ok();
    let scene = Scene {
        span: span(before, commit),
        paths: Paths::of(before.doc, after.as_ref(), commit),
        indexed: before,
        after,
        commit,
    };
    let cascade = Cascade::of(commit);
    let tracks: Vec<Track> = commit
        .ops()
        .iter()
        .map(|op| delayed(rule(&scene, op), cascade.start(&scene, op)))
        .collect();
    let duration = tracks
        .iter()
        .map(Track::end)
        .max()
        .unwrap_or(Duration::ZERO);
    let camera = camera_plan(&scene, &tracks);
    let pantomime = pantomime(&scene, commit.label(), &tracks);
    Timeline {
        label: commit.label().to_owned(),
        duration,
        camera,
        tracks,
        pantomime,
    }
}

/// What a rule may read (C1): the document the commit was written against,
/// the document it produces, the commit itself, the window their tracks
/// share, and the polylines the router solved on either side of it. A
/// pre-image comes from the first, an arrival from the second — a pin
/// re-slotted on a block the same commit resized lands on the boundary the
/// document will hold, not on the one it had.
///
/// A freshly minted entity exists in neither document nor in its own op
/// alone — a wire that stamps its own destination pin writes both in one
/// commit — so a sibling op is the only pre-image such an entity has.
struct Scene<'a> {
    indexed: &'a IndexedDocument<'a>,
    /// Absent when the fold refuses the commit; the rules then depict
    /// arrivals from the pre-image and say nothing they cannot know.
    after: Option<Document>,
    commit: &'a Commit,
    span: Duration,
    paths: Paths,
}

/// The polylines the router solved for the wires this commit draws,
/// redraws, retracts or brings back, on both sides of it.
///
/// C1 (amended 2026-08-30) admits the router because it is a pure,
/// deterministic function of document state — the same call the drag
/// previews make every frame without mutating anything — and a depiction
/// whose end state is not the geometry the document will show is a
/// depiction of something that did not happen. The seam is
/// [`Presentation::refresh_routes`]: an [`IndexedDocument`] in, solved
/// grid-space edges out, no painter and no UI toolkit between.
struct Paths {
    before: HashMap<RouteId, Arc<[GridPoint]>>,
    after: HashMap<RouteId, Arc<[GridPoint]>>,
}

impl Paths {
    fn of(before: &Document, after: Option<&Document>, commit: &Commit) -> Self {
        // A wire the commit mints or revives has no path in the pre-image
        // to ask for, and one it tombstones has none in the arrival.
        let mut was = Vec::new();
        let mut now = Vec::new();
        for op in commit.ops() {
            match op {
                OpCodes::Route(id, Crud::Create(_) | Crud::Restore) => now.push(*id),
                OpCodes::Route(id, Crud::Update(RouteUpdate::Waypoints(_))) => {
                    was.push(*id);
                    now.push(*id);
                }
                // A delete retracts along the pre-image side. And a write
                // ON a wire that moves no geometry — its name — still
                // needs the polyline, because the camera's fallback frames
                // the wire the writing sits on: identical on both sides,
                // solved on the pre-image side it certainly exists on.
                OpCodes::Route(id, Crud::Delete | Crud::Update(_)) => was.push(*id),
                OpCodes::RouteLabel(id, _) => {
                    if let Some(live) = before.route_label(id) {
                        was.push(*live.as_ref().owner.as_ref());
                    }
                }
                _ => {}
            }
        }
        Self {
            before: solved(before, &was),
            after: after.map(|doc| solved(doc, &now)).unwrap_or_default(),
        }
    }
}

/// The corner list each wanted wire takes in `doc`. A wire the solve
/// leaves unplaced yields nothing and the rule says so.
fn solved(doc: &Document, wanted: &[RouteId]) -> HashMap<RouteId, Arc<[GridPoint]>> {
    if wanted.is_empty() {
        return HashMap::default();
    }
    let mut index = DocIndex::default();
    let mut presentation = Presentation::default();
    presentation.refresh_routes(&index.view(doc));
    wanted
        .iter()
        .filter_map(|id| {
            let geometry = presentation.routes.get(id)?;
            let mut corners = vec![geometry.start_pos];
            corners.extend(geometry.iter_edges().map(|(_, edge)| edge.end));
            (corners.len() > 1).then(|| (*id, Arc::from(corners)))
        })
        .collect()
}

/// Where a pin shows: the point on its owner's boundary that its slot
/// picks. A pin the document root holds has no boundary to sit on (F9)
/// and neither has one whose owner the document cannot place, so its own
/// drawn body is the only place it can be said to sit.
fn slot_anchor(owner: Option<GridRect>, slot: PinSlot, body: GridRect) -> GridPoint {
    let Some(rect) = owner else {
        return center(body);
    };
    GridPoint {
        x: match slot.side {
            PinSide::West => rect.left(),
            PinSide::East => rect.right(),
        },
        y: pin_slot_row(rect.top(), slot.offset),
    }
}

/// The geometry readers ask the document, never the liveness flag: a
/// delete tombstones an entity but retains its values, so `before` can
/// still say where a dead thing stood — which is the footprint a `Vanish`
/// fades from and a `Restore` travels out of (7·5). Only an entity the
/// document never held has nothing to depict.
fn block_icon(doc: &Document, id: BlockId) -> Option<ScreenRect> {
    icon_box(doc.block(&id)?.as_ref().icon.as_ref())
}

fn area_rect(doc: &Document, id: AreaId) -> Option<GridRect> {
    Some(*doc.area(&id)?.as_ref().rect.as_ref())
}

fn text_pos(doc: &Document, id: TextId) -> Option<GridPoint> {
    Some(*doc.text(&id)?.as_ref().pos.as_ref())
}

fn image_rect(doc: &Document, id: ImageId) -> Option<ScreenRect> {
    Some(*doc.image(&id)?.as_ref().rect.as_ref())
}

/// A pin's seat: the block it sits on, the slot it took there, and the
/// port body it draws in that block's interior.
fn pin_seat(doc: &Document, id: PinId) -> Option<(BlockId, PinSlot, GridRect)> {
    let pin = doc.pin(&id)?.as_ref();
    Some((*pin.owner.as_ref(), *pin.slot.as_ref(), *pin.rect.as_ref()))
}

impl Scene<'_> {
    /// The document the commit was written against.
    fn before(&self) -> &Document {
        self.indexed.doc
    }

    /// The document the commit produces, or the pre-image where the fold
    /// refused it.
    fn after(&self) -> &Document {
        self.after.as_ref().unwrap_or(self.indexed.doc)
    }

    /// The create this commit mints a block with — the only pre-image a
    /// block the pre-image never held can have, which is the shape a
    /// paste lands in (7·2).
    fn minted(&self, id: BlockId) -> Option<&BlockInit> {
        self.commit.ops().iter().find_map(|op| match op {
            OpCodes::Block(other, Crud::Create(init)) if *other == id => Some(init),
            _ => None,
        })
    }

    /// A block's footprint before the commit, or from the same commit's
    /// create.
    fn block_rect(&self, id: BlockId) -> Option<GridRect> {
        if let Some(live) = self.before().block(&id) {
            return Some(*live.as_ref().rect.as_ref());
        }
        self.minted(id).map(|init| init.rect)
    }

    /// A block's footprint after the commit — where a pin this commit
    /// re-slots on it actually lands.
    fn block_rect_after(&self, id: BlockId) -> Option<GridRect> {
        self.after()
            .block(&id)
            .map(|live| *live.as_ref().rect.as_ref())
            .or_else(|| self.block_rect(id))
    }

    /// Where a pin's written lines and discrete registers read: the slot
    /// anchor on its owner's boundary, which is where the user sees the
    /// pin at all (7·2). Its port body is interior geometry and is not.
    fn pin_site(&self, id: PinId) -> Option<Site> {
        let (owner, slot, body) = pin_seat(self.before(), id)?;
        Some(Site::Anchor(slot_anchor(
            self.block_rect(owner),
            slot,
            body,
        )))
    }

    /// Where the document says an entity stands on one side of the
    /// commit: the footprint a `Vanish` fades from, a `Restore` travels
    /// between, and a re-point is held up at. A pin shows at its slot
    /// anchor and a wire along its solved polyline — the same places the
    /// create family draws them into.
    fn footprint(&self, side: Side, subject: EntityRef) -> TrackValue {
        let doc = side.doc(self);
        let value = match subject {
            EntityRef::Block(id) => side.block_rect(self, id).map(TrackValue::Rect),
            EntityRef::Pin(id) => pin_seat(doc, id).map(|(owner, slot, body)| {
                TrackValue::Point(slot_anchor(side.block_rect(self, owner), slot, body))
            }),
            EntityRef::Route(id) => side.paths(self).get(&id).cloned().map(TrackValue::Path),
            EntityRef::RouteLabel(id) => doc.route_label(&id).map(|live| TrackValue::Along {
                route: *live.as_ref().owner.as_ref(),
                at: *live.as_ref().pos.as_ref(),
            }),
            EntityRef::Text(id) => text_pos(doc, id).map(TrackValue::Point),
            EntityRef::Area(id) => area_rect(doc, id).map(TrackValue::Rect),
            EntityRef::Image(id) => image_rect(doc, id).map(TrackValue::Artwork),
            EntityRef::Document | EntityRef::Asset(_) => None,
        };
        value.unwrap_or(TrackValue::Settled)
    }

    /// Whether the pre-image holds this entity at all. A tombstone counts
    /// — the document still says where it stood — and only the entity the
    /// commit itself mints is absent.
    fn held(&self, subject: EntityRef) -> bool {
        let doc = self.before();
        match subject {
            EntityRef::Block(id) => doc.block(&id).is_some(),
            EntityRef::Pin(id) => doc.pin(&id).is_some(),
            EntityRef::Route(id) => doc.route(&id).is_some(),
            EntityRef::RouteLabel(id) => doc.route_label(&id).is_some(),
            EntityRef::Text(id) => doc.text(&id).is_some(),
            EntityRef::Area(id) => doc.area(&id).is_some(),
            EntityRef::Image(id) => doc.image(&id).is_some(),
            EntityRef::Document | EntityRef::Asset(_) => true,
        }
    }

    /// The block an op's subject sits inside: a shape's owner, a block's
    /// parent, a wire label's wire's owner — read from the pre-image
    /// where the op does not carry it. The document itself and an asset
    /// sit in nothing.
    fn container(&self, op: &OpCodes) -> Option<BlockId> {
        let doc = self.before();
        Some(match op {
            OpCodes::Block(_, Crud::Create(init)) => init.parent,
            OpCodes::Block(id, _) => *doc.block(id)?.as_ref().parent.as_ref(),
            OpCodes::Area(_, Crud::Create(init)) => init.owner,
            OpCodes::Area(id, _) => *doc.area(id)?.as_ref().owner.as_ref(),
            OpCodes::Text(_, Crud::Create(init)) => init.owner,
            OpCodes::Text(id, _) => *doc.text(id)?.as_ref().owner.as_ref(),
            OpCodes::Image(_, Crud::Create(init)) => init.owner,
            OpCodes::Image(id, _) => *doc.image(id)?.as_ref().owner.as_ref(),
            OpCodes::Route(_, Crud::Create(init)) => init.owner,
            OpCodes::Route(id, _) => *doc.route(id)?.as_ref().owner.as_ref(),
            OpCodes::RouteLabel(_, Crud::Create(init)) => {
                *doc.route(&init.owner)?.as_ref().owner.as_ref()
            }
            OpCodes::RouteLabel(id, _) => {
                let route = *doc.route_label(id)?.as_ref().owner.as_ref();
                *doc.route(&route)?.as_ref().owner.as_ref()
            }
            OpCodes::Pin(_, Crud::Create(init)) => init.owner,
            OpCodes::Pin(id, _) => *doc.pin(id)?.as_ref().owner.as_ref(),
            OpCodes::Document(_) | OpCodes::Asset(..) => return None,
        })
    }

    /// The scope an op's subject is drawn in. A pin is the exception: it
    /// is depicted at its slot anchor, which is on its owner's *outside*,
    /// so it belongs to the scope the owner itself is a child of — except
    /// where the op moves the port *body*, which is interior geometry.
    fn scope_of(&self, op: &OpCodes) -> Option<Scope> {
        let inside = self.container(op)?;
        Some(Scope::from_wire(match op {
            OpCodes::Pin(_, Crud::Update(PinUpdate::Rect(_) | PinUpdate::FlipLR(_))) => inside,
            OpCodes::Pin(..) => self.parent_of(inside),
            _ => inside,
        }))
    }

    /// The scope a block is a child of. The root's own parent is the root.
    fn parent_of(&self, block: BlockId) -> BlockId {
        self.before()
            .block(&block)
            .map(|live| *live.as_ref().parent.as_ref())
            .or_else(|| self.minted(block).map(|init| init.parent))
            .unwrap_or(BlockId::NULL)
    }
}

/// Which side of the commit a footprint is read from.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Side {
    Before,
    After,
}

impl Side {
    fn doc<'a>(self, scene: &'a Scene<'_>) -> &'a Document {
        match self {
            Side::Before => scene.before(),
            Side::After => scene.after(),
        }
    }

    fn paths<'a>(self, scene: &'a Scene<'_>) -> &'a HashMap<RouteId, Arc<[GridPoint]>> {
        match self {
            Side::Before => &scene.paths.before,
            Side::After => &scene.paths.after,
        }
    }

    fn block_rect(self, scene: &Scene<'_>, id: BlockId) -> Option<GridRect> {
        match self {
            Side::Before => scene.block_rect(id),
            Side::After => scene.block_rect_after(id),
        }
    }
}

/// The delete family's stagger, as policy rather than per-rule numbers: a
/// tombstone's depiction starts one [`STAGGER`] later for every block of
/// *this commit's own* cascade that contains it, so a subtree fades
/// outside-in and the user sees how far the delete reached. Measuring
/// inside the commit is what keeps a lone deleted text box starting at
/// once, however deep it happens to sit.
struct Cascade {
    doomed: HashSet<BlockId>,
}

impl Cascade {
    fn of(commit: &Commit) -> Self {
        Self {
            doomed: commit
                .ops()
                .iter()
                .filter_map(|op| match op {
                    OpCodes::Block(id, Crud::Delete) => Some(*id),
                    _ => None,
                })
                .collect(),
        }
    }

    fn start(&self, scene: &Scene<'_>, op: &OpCodes) -> Duration {
        if self.doomed.is_empty() {
            return Duration::ZERO;
        }
        let mut rank = 0;
        let mut inside = scene.container(op);
        while let Some(block) = inside {
            rank += u32::from(self.doomed.contains(&block));
            inside = (block != BlockId::NULL).then(|| scene.parent_of(block));
        }
        STAGGER * rank
    }
}

/// The window every track in one commit shares: an arrival takes longer
/// than a travel, and a rider — the block that grew to make room for a new
/// port — moves *with* what it makes room for rather than after it.
fn span(before: &IndexedDocument<'_>, commit: &Commit) -> Duration {
    if commit.ops().iter().any(|op| arrives(before.doc, op)) {
        APPEAR
    } else {
        MORPH
    }
}

/// Whether an op brings something into view: any entity's create, and the
/// icon write that gives a block a picture it did not have — the same
/// write on a block that already has one is the icon riding a move or a
/// resize, which travels rather than arrives.
fn arrives(before: &Document, op: &OpCodes) -> bool {
    fn creates<I, U>(crud: &Crud<I, U>) -> bool {
        matches!(crud, Crud::Create(_))
    }
    match op {
        OpCodes::Block(id, Crud::Update(BlockUpdate::Icon(icon))) => {
            icon_box(icon).is_some() && block_icon(before, *id).is_none()
        }
        OpCodes::Block(_, crud) => creates(crud),
        OpCodes::Pin(_, crud) => creates(crud),
        OpCodes::Route(_, crud) => creates(crud),
        OpCodes::RouteLabel(_, crud) => creates(crud),
        OpCodes::Text(_, crud) => creates(crud),
        OpCodes::Area(_, crud) => creates(crud),
        OpCodes::Image(_, crud) => creates(crud),
        OpCodes::Document(_) | OpCodes::Asset(..) => false,
    }
}

/// The box a block's icon shows in, or `None` for the model's zero icon —
/// which means "no picture", and is the value Delete Icon writes (7·5).
fn icon_box(icon: &Icon) -> Option<ScreenRect> {
    (icon != &Icon::default()).then_some(icon.rect)
}

/// One op, one track (C6's dispatch). The arms that answer with
/// [`settled`] are the rows whose rules land with their families (7·3–7·6);
/// the exhaustive `OpCodes` match is already total, so a new op *kind* is a
/// compile error today.
fn rule(scene: &Scene<'_>, op: &OpCodes) -> Track {
    let span = scene.span;
    match op {
        // "New Block", "New Area": a drawn footprint grows in.
        OpCodes::Block(id, Crud::Create(init)) => {
            grow_in(EntityRef::Block(*id), init.rect, span, op)
        }
        OpCodes::Area(id, Crud::Create(init)) => grow_in(EntityRef::Area(*id), init.rect, span, op),
        // "New Image": the one geometry the document keeps unsnapped.
        OpCodes::Image(id, Crud::Create(init)) => {
            grow_in_artwork(EntityRef::Image(*id), init.rect, span, op)
        }
        // "New Text Box": a text's extent is measured, never authored, so
        // its anchor is the whole of what the document can say arrived.
        OpCodes::Text(id, Crud::Create(init)) => {
            arrive(EntityRef::Text(*id), TrackValue::Point(init.pos), span, op)
        }
        // "Add Pin", "Add Port": a pin arrives at the slot it took on its
        // owner's boundary — where the user sees it, not where its port
        // body sits in the owner's own interior view.
        OpCodes::Pin(id, Crud::Create(init)) => arrive(
            EntityRef::Pin(*id),
            TrackValue::Point(slot_anchor(
                scene.block_rect_after(init.owner),
                init.slot,
                init.rect,
            )),
            span,
            op,
        ),
        // "New Route (wire)".
        OpCodes::Route(id, Crud::Create(_)) => wire(EntityRef::Route(*id), scene, *id, op),
        // "Add Wire Label": handed over as the pair the document authored,
        // because the projection that would resolve it to a point speaks
        // the UI toolkit's geometry, which this module may not (C5).
        OpCodes::RouteLabel(id, Crud::Create(init)) => arrive(
            EntityRef::RouteLabel(*id),
            TrackValue::Along {
                route: init.owner,
                at: init.pos,
            },
            span,
            op,
        ),
        // "Set Block Icon": the picture arrives inside its block — unless
        // the block already had one, when this is the icon riding a move
        // or a resize. The zero icon is Delete Icon's write (7·5).
        OpCodes::Block(id, Crud::Update(BlockUpdate::Icon(icon))) => {
            match (block_icon(scene.before(), *id), icon_box(icon)) {
                // "Delete Icon": the zero icon is no picture, so the box
                // the block carried fades where it was drawn.
                (Some(from), None) => {
                    vanish(EntityRef::Block(*id), TrackValue::Artwork(from), span, op)
                }
                (None, None) => settled(op),
                (None, Some(to)) => grow_in_artwork(EntityRef::Block(*id), to, span, op),
                (Some(from), Some(to)) => morph(
                    EntityRef::Block(*id),
                    TrackValue::Artwork(from),
                    TrackValue::Artwork(to),
                    span,
                    op,
                ),
            }
        }
        // "Move Shape" (the block arm), "Move Group", "Keyboard Nudge",
        // "Resize Shape", and the growth rider that makes room for a new
        // port — the same travel, over the same window.
        OpCodes::Block(id, Crud::Update(BlockUpdate::Rect(to))) => morph(
            EntityRef::Block(*id),
            TrackValue::Rect(scene.block_rect(*id).unwrap_or(*to)),
            TrackValue::Rect(*to),
            span,
            op,
        ),
        // "Move Shape" and "Move Group" for the shapes that are not
        // blocks, and "Resize Shape" for the two that carry handles.
        OpCodes::Area(id, Crud::Update(AreaUpdate::Rect(to))) => morph(
            EntityRef::Area(*id),
            TrackValue::Rect(area_rect(scene.before(), *id).unwrap_or(*to)),
            TrackValue::Rect(*to),
            span,
            op,
        ),
        OpCodes::Text(id, Crud::Update(TextUpdate::Pos(to))) => morph(
            EntityRef::Text(*id),
            TrackValue::Point(text_pos(scene.before(), *id).unwrap_or(*to)),
            TrackValue::Point(*to),
            span,
            op,
        ),
        OpCodes::Image(id, Crud::Update(ImageUpdate::Rect(to))) => morph(
            EntityRef::Image(*id),
            TrackValue::Artwork(image_rect(scene.before(), *id).unwrap_or(*to)),
            TrackValue::Artwork(*to),
            span,
            op,
        ),
        // A port body travels in its owner's interior, the scope it is
        // drawn in — never on the boundary its slot anchors to.
        OpCodes::Pin(id, Crud::Update(PinUpdate::Rect(to))) => morph(
            EntityRef::Pin(*id),
            TrackValue::Rect(pin_seat(scene.before(), *id).map_or(*to, |(_, _, body)| body)),
            TrackValue::Rect(*to),
            span,
            op,
        ),
        // "Move Pin", "Relocate Pin Group", "Nudge Pins", the slot half of
        // "Flip Shape Pins", "Flip Block Vertical", and the pins a resize
        // carries up.
        OpCodes::Pin(id, Crud::Update(PinUpdate::Slot(to))) => reseated(scene, *id, *to, op),
        // The other half of "Flip Shape Pins": a body told to face the
        // other way keeps every coordinate it had, so it is held up rather
        // than moved. A block flip toggles the flag on every pin precisely
        // *because* the interior must not appear to change.
        OpCodes::Pin(id, Crud::Update(PinUpdate::FlipLR(_))) => held(
            EntityRef::Pin(*id),
            pin_seat(scene.before(), *id)
                .map_or(TrackValue::Settled, |(_, _, body)| TrackValue::Rect(body)),
            span,
            op,
        ),
        // "Edit Route", "Reroute Wire / Block", and the waypoint riders a
        // move owes the wires it drags: one authored list write, one
        // track, along the paths the two lists solve to.
        OpCodes::Route(id, Crud::Update(RouteUpdate::Waypoints(_))) => rewired(scene, *id, op),
        // "Move Wire Label": the label slides along its own wire. Both
        // arc lengths are the document's own — the emitter re-anchors a
        // label onto the geometry the same commit solves — so the pair
        // travels and the painter resolves each end against the wire it
        // is drawing.
        OpCodes::RouteLabel(id, Crud::Update(RouteLabelUpdate::Pos(to))) => {
            slid(scene, *id, *to, op)
        }
        // "Move Title / Type Label", "Rename Title", "Rename Block Type".
        OpCodes::Block(id, Crud::Update(BlockUpdate::Title(update))) => {
            label_write(scene, LabelAt::BlockTitle(*id), update, op)
        }
        OpCodes::Block(id, Crud::Update(BlockUpdate::TypeLabel(update))) => {
            label_write(scene, LabelAt::BlockType(*id), update, op)
        }
        OpCodes::Area(id, Crud::Update(AreaUpdate::Title(update))) => {
            label_write(scene, LabelAt::AreaTitle(*id), update, op)
        }
        // "Rename Pin", "Retype Pin", "Set Pin Tag": a pin's three written
        // lines, crossfading at the anchor the user reads them by. The
        // body a rename widens to fit them is the `Rect` rider above,
        // drawn one scope in.
        OpCodes::Pin(id, Crud::Update(PinUpdate::Name(to))) => {
            pin_line(scene, *id, PinLine::Name, to, op)
        }
        OpCodes::Pin(id, Crud::Update(PinUpdate::TypeName(to))) => {
            pin_line(scene, *id, PinLine::Type, to, op)
        }
        OpCodes::Pin(id, Crud::Update(PinUpdate::Tag(to))) => {
            pin_line(scene, *id, PinLine::Tag, to, op)
        }
        // "Cycle Pin Direction", "Set Pin Direction", "Show/Hide Pin
        // Tags", and the port arm of "Set Accent".
        OpCodes::Pin(id, Crud::Update(PinUpdate::Dir(to))) => pin_flag(
            scene,
            *id,
            |pin| FlagState::Direction(*pin.dir.as_ref()),
            FlagState::Direction(*to),
            op,
        ),
        OpCodes::Pin(id, Crud::Update(PinUpdate::TagHidden(to))) => pin_flag(
            scene,
            *id,
            |pin| FlagState::Tag(TagVisibility::from(*pin.tag_hidden.as_ref())),
            FlagState::Tag(TagVisibility::from(*to)),
            op,
        ),
        OpCodes::Pin(id, Crud::Update(PinUpdate::PortAccent(to))) => pin_flag(
            scene,
            *id,
            |pin| FlagState::Accent(*pin.port_accent.as_ref()),
            FlagState::Accent(*to),
            op,
        ),
        // "Set Accent" and "Lock/Unlock Block": what a shape's footprint
        // is drawn *with*, held up on that footprint.
        OpCodes::Block(id, Crud::Update(BlockUpdate::Role(to))) => block_flag(
            scene,
            *id,
            |block| FlagState::Accent(*block.role.as_ref()),
            FlagState::Accent(*to),
            op,
        ),
        OpCodes::Block(id, Crud::Update(BlockUpdate::Locked(to))) => block_flag(
            scene,
            *id,
            |block| FlagState::Lock(InterfaceLock::from(*block.locked.as_ref())),
            FlagState::Lock(InterfaceLock::from(*to)),
            op,
        ),
        OpCodes::Area(id, Crud::Update(AreaUpdate::Role(to))) => or_settled(
            scene
                .before()
                .area(id)
                .filter(|area| area.is_alive())
                .map(|live| {
                    let area = live.as_ref();
                    stepped(
                        Site::Shape(*area.rect.as_ref()),
                        FlagState::Accent(*area.role.as_ref()),
                        FlagState::Accent(*to),
                        scene.span,
                        op,
                    )
                }),
            op,
        ),
        OpCodes::Text(id, Crud::Update(TextUpdate::Role(to))) => or_settled(
            scene
                .before()
                .text(id)
                .filter(|live| live.is_alive())
                .map(|live| {
                    let box_ = live.as_ref();
                    stepped(
                        Site::Anchor(*box_.pos.as_ref()),
                        FlagState::Accent(*box_.role.as_ref()),
                        FlagState::Accent(*to),
                        scene.span,
                        op,
                    )
                }),
            op,
        ),
        OpCodes::Route(id, Crud::Update(RouteUpdate::Role(to))) => or_settled(
            scene
                .before()
                .route(id)
                .filter(|route| route.is_alive())
                .map(|live| {
                    stepped(
                        Site::Wire,
                        FlagState::Accent(*live.as_ref().role.as_ref()),
                        FlagState::Accent(*to),
                        scene.span,
                        op,
                    )
                }),
            op,
        ),
        // "Rename Route", and the naming half of "Delete Wire Label":
        // clearing the last label's text unnames the wire, which is this
        // same crossfade ending on nothing.
        OpCodes::Route(id, Crud::Update(RouteUpdate::Name(to))) => or_settled(
            scene
                .before()
                .route(id)
                .filter(|route| route.is_alive())
                .map(|live| {
                    let of = Written {
                        at: Site::Wire,
                        line: TextLine::WireName,
                    };
                    crossfade(of, live.as_ref().name.as_ref(), to, scene.span, op)
                }),
            op,
        ),
        // "Edit Text Box".
        OpCodes::Text(id, Crud::Update(TextUpdate::Text(to))) => or_settled(
            scene
                .before()
                .text(id)
                .filter(|live| live.is_alive())
                .map(|live| {
                    let box_ = live.as_ref();
                    let of = Written {
                        at: Site::Anchor(*box_.pos.as_ref()),
                        line: TextLine::Content,
                    };
                    crossfade(of, box_.text.as_ref(), to, scene.span, op)
                }),
            op,
        ),
        // "Delete Text Box (emptied)" and "Delete Text": one op, one arm —
        // a text box is nothing but its content, so it goes the way it was
        // emptied however the gesture reached it (7·4, reconciled 7·5).
        OpCodes::Text(id, Crud::Delete) => emptied(scene, *id, op),
        // "Delete Block" and its cascade, "Delete Port", "Delete Pins",
        // "Delete Area", "Delete Image", "Delete Route", "Delete
        // Selection", and the delete half of "Cut": what a commit
        // tombstones fades out where the pre-image says it stood, one
        // level of the cascade after another ([`Cascade`]).
        OpCodes::Block(_, Crud::Delete)
        | OpCodes::Pin(_, Crud::Delete)
        | OpCodes::Route(_, Crud::Delete)
        | OpCodes::RouteLabel(_, Crud::Delete)
        | OpCodes::Area(_, Crud::Delete)
        | OpCodes::Image(_, Crud::Delete) => vanish(
            op.target(),
            scene.footprint(Side::Before, op.target()),
            span,
            op,
        ),
        // "Paste", in its identity-preserving form: a cut and its first
        // paste are one move, and the restore is the tell. The entity
        // travels out of the tombstone the cut left — `before` still
        // holds where it stood — and lands where this commit re-points
        // it. Never a death and a birth.
        OpCodes::Block(_, Crud::Restore)
        | OpCodes::Pin(_, Crud::Restore)
        | OpCodes::Route(_, Crud::Restore)
        | OpCodes::RouteLabel(_, Crud::Restore)
        | OpCodes::Text(_, Crud::Restore)
        | OpCodes::Area(_, Crud::Restore)
        | OpCodes::Image(_, Crud::Restore) => restored(scene, op),
        // "Wrap Top": the content that was re-parented is held up where it
        // stands, and the title block's repoint holds up its new top. The
        // same reading serves a move's re-point: the restore beside it is
        // the travel, so the handover is held at where it came from.
        OpCodes::Block(_, Crud::Update(BlockUpdate::Parent(_)))
        | OpCodes::Pin(_, Crud::Update(PinUpdate::Owner(_)))
        | OpCodes::Route(_, Crud::Update(RouteUpdate::Owner(_)))
        | OpCodes::Text(_, Crud::Update(TextUpdate::Owner(_)))
        | OpCodes::Area(_, Crud::Update(AreaUpdate::Owner(_)))
        | OpCodes::Image(_, Crud::Update(ImageUpdate::Owner(_))) => held(
            op.target(),
            scene.footprint(Side::Before, op.target()),
            span,
            op,
        ),
        OpCodes::Document(TitleBlockUpdate::Top(id)) => held(
            EntityRef::Document,
            scene
                .block_rect(*id)
                .map_or(TrackValue::Settled, TrackValue::Rect),
            span,
            op,
        ),
        // The drawing's own name crossfades where it is read — the title
        // block in the sheet's corner, which is chrome rather than
        // canvas, so it frames nothing. Written by an import
        // (`schema::lower`) and carried by `edit::restore`.
        OpCodes::Document(TitleBlockUpdate::Name(to)) => crossfade(
            Written {
                at: Site::Sheet,
                line: TextLine::DocumentName,
            },
            scene.before().title_block().name.as_ref(),
            to,
            span,
            op,
        ),
        // A wire label re-homed onto another wire: two wires have no
        // ground between them for a label to slide along, so it is held
        // at the placement it lands on — the reading a label's `Side`
        // step already has (7·3). Written only by `edit::restore`.
        OpCodes::RouteLabel(id, Crud::Update(RouteLabelUpdate::Owner(to))) => held(
            EntityRef::RouteLabel(*id),
            scene
                .before()
                .route_label(id)
                .map_or(TrackValue::Settled, |live| TrackValue::Along {
                    route: *to,
                    at: *live.as_ref().pos.as_ref(),
                }),
            span,
            op,
        ),
        // The picture inside an image box is replaced: the box does not
        // move, so it is held up while what is drawn in it changes.
        // Written by a paste re-stamping a copied image's payload and by
        // `edit::restore`.
        OpCodes::Image(id, Crud::Update(ImageUpdate::Asset(_))) => held(
            EntityRef::Image(*id),
            scene.footprint(Side::After, EntityRef::Image(*id)),
            span,
            op,
        ),
        // The payload rider (`edit::assets`): bytes arriving under their
        // content hash. Nothing of it appears — what the user sees is the
        // image or icon referencing them — so the track carries the op and
        // depicts no geometry. The one op with nothing to depict by
        // design, and the one [`Timeline::undepicted`] excuses.
        OpCodes::Asset(..) => held(op.target(), TrackValue::Settled, span, op),
    }
}

/// The create family's idiom: what arrives grows out of its own top-left
/// corner, right and down — the direction a hand draws a box (user, 2026-
/// 08-30: "more natural").
fn grow_in(subject: EntityRef, written: GridRect, span: Duration, op: &OpCodes) -> Track {
    let seed = GridRect {
        top_left: written.top_left,
        size: GridSize::default(),
    };
    appearing(
        subject,
        TrackValue::Rect(seed),
        TrackValue::Rect(written),
        span,
        op,
    )
}

/// [`grow_in`] for the document's unsnapped artwork boxes.
fn grow_in_artwork(subject: EntityRef, written: ScreenRect, span: Duration, op: &OpCodes) -> Track {
    let seed = ScreenRect {
        top_left: written.top_left,
        size: ScreenSize::default(),
    };
    appearing(
        subject,
        TrackValue::Artwork(seed),
        TrackValue::Artwork(written),
        span,
        op,
    )
}

/// Inventory row "New Route (wire)": the wire draws itself along the path
/// the router solved for it, from its start anchor outward.
fn wire(subject: EntityRef, scene: &Scene<'_>, id: RouteId, op: &OpCodes) -> Track {
    let Some(path) = scene.paths.after.get(&id) else {
        // A wire the solve leaves unplaced — a suppressed endpoint, a
        // commit the fold refuses — has no path to draw.
        return arrive(subject, TrackValue::Settled, scene.span, op);
    };
    appearing(
        subject,
        TrackValue::Path(Arc::from([path[0]])),
        TrackValue::Path(path.clone()),
        scene.span,
        op,
    )
}

/// The two ends of a two-key track: where the depiction starts, and the
/// value the commit wrote.
struct Ends {
    from: TrackValue,
    to: TrackValue,
}

/// A pair of keys under one kind, the second reached over `span`.
fn between(subject: EntityRef, kind: TrackKind, ends: Ends, span: Duration, op: &OpCodes) -> Track {
    Track {
        subject,
        kind,
        op: op.clone(),
        keys: vec![
            Keyframe {
                at: Duration::ZERO,
                value: ends.from,
                easing: Easing::Linear,
            },
            Keyframe {
                at: span,
                value: ends.to,
                easing: kind.arrival(),
            },
        ],
    }
}

/// An arrival that grows: a seed at the start, the written value at the
/// end of the gesture's window.
fn appearing(
    subject: EntityRef,
    seed: TrackValue,
    written: TrackValue,
    span: Duration,
    op: &OpCodes,
) -> Track {
    between(
        subject,
        TrackKind::Appear,
        Ends {
            from: seed,
            to: written,
        },
        span,
        op,
    )
}

/// An arrival with nothing to grow from — an anchor point, a place along a
/// wire. One key, so the depiction is where it lands and the progress it
/// lands over.
fn arrive(subject: EntityRef, value: TrackValue, span: Duration, op: &OpCodes) -> Track {
    Track {
        subject,
        kind: TrackKind::Appear,
        op: op.clone(),
        keys: vec![Keyframe {
            at: span,
            value,
            easing: Easing::EaseOut,
        }],
    }
}

/// Held up rather than moved or minted: what a gesture changed about an
/// entity that stays where it is.
fn held(subject: EntityRef, value: TrackValue, span: Duration, op: &OpCodes) -> Track {
    Track {
        subject,
        kind: TrackKind::Emphasis,
        op: op.clone(),
        keys: vec![Keyframe {
            at: span,
            value,
            easing: Easing::Linear,
        }],
    }
}

/// The delete family's idiom: what a commit tombstones keeps the
/// footprint the pre-image gave it — the entity is alive there — and
/// fades over the window. A wire is the one exception: it is a stroke
/// rather than a footprint, so it retracts into its own start, which is
/// the 7·3 wipe read the other way round.
fn vanish(subject: EntityRef, footprint: TrackValue, span: Duration, op: &OpCodes) -> Track {
    let gone = match &footprint {
        TrackValue::Path(path) if !path.is_empty() => TrackValue::Path(Arc::from([path[0]])),
        standing => standing.clone(),
    };
    between(
        subject,
        TrackKind::Vanish,
        Ends {
            from: footprint,
            to: gone,
        },
        span,
        op,
    )
}

/// The clipboard's move: an entity comes back out of the tombstone the
/// cut left it in and travels to where this commit re-points it. What the
/// pre-image cannot place at all — a wire whose endpoints were tombstoned
/// with it, so no solve reaches it — starts where it lands.
fn restored(scene: &Scene<'_>, op: &OpCodes) -> Track {
    let subject = op.target();
    let to = scene.footprint(Side::After, subject);
    let from = match scene.footprint(Side::Before, subject) {
        TrackValue::Settled => to.clone(),
        stood => stood,
    };
    morph(subject, from, to, scene.span, op)
}

/// The stagger applied to a finished track, so a rule never has to know
/// what else the commit deleted.
fn delayed(mut track: Track, by: Duration) -> Track {
    if !by.is_zero() {
        for key in &mut track.keys {
            key.at += by;
        }
    }
    track
}

/// The geometry family's idiom: one travel from the pre-image to the value
/// the commit writes, easing into its arrival.
fn morph(
    subject: EntityRef,
    from: TrackValue,
    to: TrackValue,
    span: Duration,
    op: &OpCodes,
) -> Track {
    between(subject, TrackKind::Morph, Ends { from, to }, span, op)
}

/// The naming family's idiom: a crossfade whose keyframes hold both
/// strings, so a rename still says what the register became (C3).
fn crossfade(of: Written, was: &str, now: &str, span: Duration, op: &OpCodes) -> Track {
    morph(op.target(), text(of, was), text(of, now), span, op)
}

fn text(of: Written, value: &str) -> TrackValue {
    TrackValue::Text {
        of,
        text: Arc::from(value),
    }
}

/// The flag family's idiom: a discrete register is held up where it shows
/// and steps to the value the commit wrote at the end key.
fn stepped(at: Site, was: FlagState, now: FlagState, span: Duration, op: &OpCodes) -> Track {
    between(
        op.target(),
        TrackKind::Emphasis,
        Ends {
            from: TrackValue::Flag { at, state: was },
            to: TrackValue::Flag { at, state: now },
        },
        span,
        op,
    )
}

/// The pin rows that rewrite one of its three written lines.
fn pin_line(scene: &Scene<'_>, id: PinId, line: PinLine, now: &str, op: &OpCodes) -> Track {
    let (Some(at), Some(live)) = (scene.pin_site(id), scene.before().pin(&id)) else {
        return settled(op);
    };
    let of = Written {
        at,
        line: TextLine::Pin(line),
    };
    crossfade(of, line.of(live.as_ref()), now, scene.span, op)
}

/// The pin rows that write one of its discrete registers.
fn pin_flag(
    scene: &Scene<'_>,
    id: PinId,
    was: impl Fn(&Pin) -> FlagState,
    now: FlagState,
    op: &OpCodes,
) -> Track {
    let (Some(at), Some(live)) = (scene.pin_site(id), scene.before().pin(&id)) else {
        return settled(op);
    };
    stepped(at, was(live.as_ref()), now, scene.span, op)
}

/// The block rows that write one of its discrete registers.
fn block_flag(
    scene: &Scene<'_>,
    id: BlockId,
    was: impl Fn(&Block) -> FlagState,
    now: FlagState,
    op: &OpCodes,
) -> Track {
    let (Some(rect), Some(live)) = (
        scene.block_rect(id),
        scene.before().block(&id).filter(|b| b.is_alive()),
    ) else {
        return settled(op);
    };
    stepped(Site::Shape(rect), was(live.as_ref()), now, scene.span, op)
}

/// A rule whose subject the pre-image does not hold has nothing to depict
/// but the op it carries.
fn or_settled(track: Option<Track>, op: &OpCodes) -> Track {
    track.unwrap_or_else(|| settled(op))
}

/// Inventory row "Delete Text Box (emptied)": a text box is nothing but
/// its content, so it goes the way it was emptied — that content fading
/// out at the anchor it stood on. The op is a plain delete, and 7·5's
/// "Delete Text" is the same act reached by pressing a key instead of
/// clearing the buffer, so the two rows share this arm.
fn emptied(scene: &Scene<'_>, id: TextId, op: &OpCodes) -> Track {
    let Some(live) = scene.before().text(&id).filter(|t| t.is_alive()) else {
        return settled(op);
    };
    let of = Written {
        at: Site::Anchor(*live.as_ref().pos.as_ref()),
        line: TextLine::Content,
    };
    between(
        EntityRef::Text(id),
        TrackKind::Vanish,
        Ends {
            from: text(of, live.as_ref().text.as_ref()),
            to: text(of, ""),
        },
        scene.span,
        op,
    )
}

/// The pin rows that write a slot: the pin travels between the two points
/// its old and new slots pick on its owner's boundary — the boundary the
/// document will hold, which a resize in the same commit may have moved.
/// A flip is this travel and nothing more: the ops swap sides, so the pins
/// cross, and no mirror is drawn that the commit does not state.
fn reseated(scene: &Scene<'_>, id: PinId, to: PinSlot, op: &OpCodes) -> Track {
    let Some((owner, was, body)) = pin_seat(scene.before(), id) else {
        return settled(op);
    };
    let landed = pin_seat(scene.after(), id).map_or(body, |(_, _, body)| body);
    morph(
        EntityRef::Pin(id),
        TrackValue::Point(slot_anchor(scene.block_rect(owner), was, body)),
        TrackValue::Point(slot_anchor(scene.block_rect_after(owner), to, landed)),
        scene.span,
        op,
    )
}

/// The rows that rewrite a wire's corner list: the wire is rubbed out
/// along the path its old list solved to and drawn again along the new
/// one ([`wipe`]), because that is what the write does to the list.
/// A list the solver answers the same way on both sides moved nothing, and
/// is held up instead.
fn rewired(scene: &Scene<'_>, id: RouteId, op: &OpCodes) -> Track {
    let subject = EntityRef::Route(id);
    let (Some(was), Some(now)) = (scene.paths.before.get(&id), scene.paths.after.get(&id)) else {
        return held(subject, TrackValue::Settled, scene.span, op);
    };
    if was == now {
        return held(subject, TrackValue::Path(now.clone()), scene.span, op);
    }
    Track {
        subject,
        kind: TrackKind::Morph,
        op: op.clone(),
        keys: vec![
            Keyframe {
                at: Duration::ZERO,
                value: TrackValue::Path(was.clone()),
                easing: Easing::Linear,
            },
            Keyframe {
                at: scene.span / 2,
                value: TrackValue::Path(Arc::from([was[0]])),
                easing: Easing::Linear,
            },
            Keyframe {
                at: scene.span,
                value: TrackValue::Path(now.clone()),
                easing: Easing::EaseOut,
            },
        ],
    }
}

/// Inventory row "Move Wire Label": the label slides along its wire.
fn slid(scene: &Scene<'_>, id: RouteLabelId, to: FracVal, op: &OpCodes) -> Track {
    let Some(live) = scene.before().route_label(&id).filter(|l| l.is_alive()) else {
        return settled(op);
    };
    let route = *live.as_ref().owner.as_ref();
    let from = *live.as_ref().pos.as_ref();
    morph(
        EntityRef::RouteLabel(id),
        TrackValue::Along { route, at: from },
        TrackValue::Along { route, at: to },
        scene.span,
        op,
    )
}

/// Which placed label an op moves, and how to read it out of a document.
#[derive(Clone, Copy)]
enum LabelAt {
    BlockTitle(BlockId),
    BlockType(BlockId),
    AreaTitle(AreaId),
}

impl LabelAt {
    fn subject(self) -> EntityRef {
        match self {
            LabelAt::BlockTitle(id) | LabelAt::BlockType(id) => EntityRef::Block(id),
            LabelAt::AreaTitle(id) => EntityRef::Area(id),
        }
    }

    fn slot(self) -> LabelSlot {
        match self {
            LabelAt::BlockTitle(_) | LabelAt::AreaTitle(_) => LabelSlot::Title,
            LabelAt::BlockType(_) => LabelSlot::TypeLabel,
        }
    }

    fn label(self, doc: &Document) -> Option<&Label> {
        Some(match self {
            LabelAt::BlockTitle(id) => &doc.block(&id).filter(|b| b.is_alive())?.as_ref().title,
            LabelAt::BlockType(id) => &doc.block(&id).filter(|b| b.is_alive())?.as_ref().type_label,
            LabelAt::AreaTitle(id) => &doc.area(&id).filter(|a| a.is_alive())?.as_ref().title,
        })
    }

    /// The footprint the label is drawn on — the whole of what the
    /// document can say about where its text appears, since resolving a
    /// side and an offset to a point needs a measured text width.
    fn site(self, doc: &Document) -> Option<Site> {
        match self {
            LabelAt::BlockTitle(id) | LabelAt::BlockType(id) => doc
                .block(&id)
                .filter(|b| b.is_alive())
                .map(|live| *live.as_ref().rect.as_ref()),
            LabelAt::AreaTitle(id) => area_rect(doc, id),
        }
        .map(Site::Shape)
    }
}

/// Inventory rows "Move Title / Type Label", "Rename Title" and "Rename
/// Block Type": the registers of a shape's placed label.
///
/// The offset travels along the side the label ends on; a side change is a
/// step and is *held*, because two edges of a shape have no ground between
/// them for a label to cross. A rename is the family crossfade, on the
/// footprint that carries the label.
fn label_write(scene: &Scene<'_>, at: LabelAt, update: &LabelUpdate, op: &OpCodes) -> Track {
    let Some(label) = at.label(scene.before()) else {
        return settled(op);
    };
    let placed = |label: &Label| TrackValue::Label {
        slot: at.slot(),
        side: *label.side.as_ref(),
        offset: *label.offset.as_ref(),
    };
    let from = placed(label);
    let to = at.label(scene.after()).map_or_else(|| from.clone(), placed);
    match update {
        LabelUpdate::Offset(_) => morph(at.subject(), from, to, scene.span, op),
        LabelUpdate::Side(_) => held(at.subject(), to, scene.span, op),
        LabelUpdate::Name(now) => or_settled(
            at.site(scene.before()).map(|site| {
                let of = Written {
                    at: site,
                    line: TextLine::Label(at.slot()),
                };
                crossfade(of, label.name.as_ref(), now, scene.span, op)
            }),
            op,
        ),
        // A label that stops being drawn is a flag like any other, so it
        // steps on the footprint that carries it. No *gesture* writes it:
        // the register reaches a commit only through an authored document
        // that hid a label and the restore that carries such a document
        // back, which is the emitter this arm is proven through.
        LabelUpdate::Hidden(now) => or_settled(
            at.site(scene.before()).map(|site| {
                stepped(
                    site,
                    FlagState::Label(at.slot(), LabelVisibility::from(*label.hidden.as_ref())),
                    FlagState::Label(at.slot(), LabelVisibility::from(*now)),
                    scene.span,
                    op,
                )
            }),
            op,
        ),
    }
}

/// Nothing to depict: the op carried, no geometry. Most consumers are rows
/// 7·4–7·6 still owe a rule; the rest are ops whose subject the pre-image
/// does not hold, which have no travel anyone can name.
fn settled(op: &OpCodes) -> Track {
    Track {
        subject: op.target(),
        kind: TrackKind::Emphasis,
        op: op.clone(),
        keys: vec![Keyframe {
            at: Duration::ZERO,
            value: TrackValue::Settled,
            easing: Easing::Linear,
        }],
    }
}

/// The zero-size region at a point — what a bare anchor contributes to the
/// camera's plan.
fn spot(at: GridPoint) -> GridRect {
    GridRect {
        top_left: at,
        size: GridSize::default(),
    }
}

fn center(r: GridRect) -> GridPoint {
    GridPoint {
        x: r.top_left.x + (r.size.w / 2) as i32,
        y: r.top_left.y + (r.size.h / 2) as i32,
    }
}

/// The whole cells an unsnapped artwork box covers — the camera plans in
/// grid space, and artwork is the one geometry stored in world pixels.
fn grid_bounds(r: ScreenRect) -> GridRect {
    let (min, max) = px_corners(r);
    let cells = |v: f32, up: bool| {
        let scaled = v / GRID_SIZE;
        if up { scaled.ceil() } else { scaled.floor() }
    };
    let (left, top) = (cells(min[0], false), cells(min[1], false));
    let (right, bottom) = (cells(max[0], true), cells(max[1], true));
    GridRect {
        top_left: GridPoint {
            x: left as i32,
            y: top as i32,
        },
        size: GridSize {
            w: (right - left) as u32,
            h: (bottom - top) as u32,
        },
    }
}

/// The union of everything the tracks depict, in the scope the first
/// depicted subject lives in. Advisory (never in the oracle), and absent
/// when nothing depicts a region yet.
///
/// A region is measured in the scope it frames: a scope is a coordinate
/// space of its own, so a track drawn in another one — the port body whose
/// pin re-slots on the boundary a level up — is left out of the union.
/// Ops with no scope at all (the document's own, an asset's) are in it,
/// since they depict their subject wherever the rest of the commit is.
fn camera_plan(scene: &Scene<'_>, tracks: &[Track]) -> Option<CameraPlan> {
    let scope = tracks
        .iter()
        .find_map(|track| scene.scope_of(&track.op))
        .unwrap_or(Scope::Root);
    let region = tracks
        .iter()
        .filter(|track| scene.scope_of(&track.op).is_none_or(|owner| owner == scope))
        .filter_map(|track| track_region(scene, track))
        .reduce(union)?;
    Some(CameraPlan { scope, region })
}

/// The grid region one track depicts in: what its keys cover, or — where
/// they cover nothing the camera can frame — the [`fallback_region`] its
/// subject stands in. The camera unions these, and the pantomime picks
/// the first of them as the thing the hand went for.
fn track_region(scene: &Scene<'_>, track: &Track) -> Option<GridRect> {
    track
        .keys
        .iter()
        .filter_map(|key| key.value.bounds())
        .reduce(union)
        .or_else(|| fallback_region(scene, track.subject))
}

/// The advisory region for a track whose keys depict no bounds of their
/// own — a crossfade at a label, a travel along a wire: the subject's own
/// footprint, chasing a wire label onto its route's solved polyline. This
/// is why no row needs the measured-text anchor projections the headless
/// gate refuses — the camera frames the thing whose writing moved, which
/// is what a viewer wants framed anyway.
fn fallback_region(scene: &Scene<'_>, subject: EntityRef) -> Option<GridRect> {
    let resolve = |side| match scene.footprint(side, subject) {
        TrackValue::Along { route, .. } => scene.footprint(side, EntityRef::Route(route)).bounds(),
        value => value.bounds(),
    };
    resolve(Side::Before).or_else(|| resolve(Side::After))
}

fn union(a: GridRect, b: GridRect) -> GridRect {
    let x0 = a.top_left.x.min(b.top_left.x);
    let y0 = a.top_left.y.min(b.top_left.y);
    let x1 = a.right().max(b.right());
    let y1 = a.bottom().max(b.bottom());
    GridRect {
        top_left: GridPoint { x: x0, y: y0 },
        size: GridSize {
            w: (x1 - x0) as u32,
            h: (y1 - y0) as u32,
        },
    }
}

#[cfg(test)]
pub(crate) mod tests;