blockworx/script/

step.rs

//! Declarative instruction-animation scripts. A [`Script`] is a sequence of
//! timed [`Step`]s; playback is the pure [`Script::sample`] — a function of
//! elapsed seconds only, so the whole engine is testable with a fake clock.
//! Cursor positions stay symbolic ([`CueTarget`]) because a glide can span
//! coordinate spaces (toolbar button → canvas); the drawing pass resolves both
//! endpoints to screen space and lerps there.

use std::time::Duration;

use blockworx_doc::{
    block_model::Block,
    document::{IndexedDocument, chronological},
    id::{BlockId, PinId},
};
use egui::Pos2;

use crate::grid::{GRID_SIZE, px};
use crate::progress::Progress;
use crate::schema::lower::SourceIds;
use crate::shape::block::BlockShape;
use crate::shape::pin::{Pin, slot};
use crate::tools::names::ToolName;

/// The world-space position of a grid cell's corner — for authoring canvas
/// targets in the same units the level KDL uses.
pub fn grid_pos(x: i32, y: i32) -> Pos2 {
    egui::pos2(px(x), px(y))
}

/// Linear blend of two camera rects at eased progress `p`.
fn lerp_rect(a: egui::Rect, b: egui::Rect, p: Progress) -> egui::Rect {
    let t = p.get();
    egui::Rect::from_min_max(a.min.lerp(b.min, t), a.max.lerp(b.max, t))
}

/// A cue target on the canvas, in grid cells: `at(8, 6)`. Shipped scripts are
/// authored in level KDL; these constructors serve the tests.
#[cfg(test)]
pub fn at(x: i32, y: i32) -> CueTarget {
    CueTarget::World(grid_pos(x, y))
}

/// A cue target on the toolbar: `tool(NewBlock)`.
#[cfg(test)]
pub fn tool(name: ToolName) -> CueTarget {
    CueTarget::ToolButton(name)
}

/// A cue target at the live position of the block with this title: `block("core")`.
#[cfg(test)]
pub fn block(title: &'static str) -> CueTarget {
    CueTarget::Block(title)
}

/// A cue target on a live block's resize handle: `corner("core", RightBottom)`.
#[cfg(test)]
pub fn corner(title: &'static str, handle: Handle) -> CueTarget {
    CueTarget::Corner(title, handle)
}

/// A drag destination `dx,dy` grid cells from the drag's start.
#[cfg(test)]
pub fn by(dx: i32, dy: i32) -> CueTarget {
    CueTarget::Relative { dx, dy }
}

/// Which resize handle of a block a cue points at.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Handle {
    LeftTop,
    RightTop,
    LeftBottom,
    RightBottom,
}

/// Where a cue points: a toolbar button (screen space, resolved from the
/// toolbar's stashed button rects), a fixed canvas position (world space), or a
/// spot anchored to the *live* document — by block title or by logical id —
/// which follows the object wherever the demo actually put it.
#[derive(Clone, Copy, PartialEq, Debug)]
pub enum CueTarget {
    ToolButton(ToolName),
    World(Pos2),
    /// Center of the block with this title.
    Block(&'static str),
    /// A corner (resize handle) of the block with this title.
    Corner(&'static str, Handle),
    /// Center of the block with this id (`"b4"`).
    BlockId(&'static str),
    /// A pin's wire anchor, by logical ids (`"b4:p3"`).
    PinAnchor {
        block: &'static str,
        pin: &'static str,
    },
    /// A destination offset from a drag's start, in grid cells (`"+4,-3"` in
    /// the KDL). Only meaningful as a [`Step::Drag`] `to`; it has no world
    /// position of its own.
    Relative {
        dx: i32,
        dy: i32,
    },
}

/// How a [`CueTarget`] gets its position. Every consumer switches on this
/// distinction rather than on the variants, so a new target kind is classified
/// once, here, instead of falling through a wildcard at each site.
#[derive(Clone, Copy, PartialEq, Debug)]
pub enum Anchoring {
    /// Screen space: the toolbar owns the button's rect, so there is no world
    /// position by design (as opposed to one that failed to resolve).
    Toolbar(ToolName),
    /// A world position, resolved against the live document by
    /// [`CueTarget::world`].
    Document,
    /// A displacement from the drag's start, in world units — no position of
    /// its own, so a cursor rides the drag's base instead of gliding.
    FromDragBase(egui::Vec2),
}

/// What a cue target resolves against: the session's live document, and the
/// table naming the entities its level file authored.
///
/// The document alone cannot answer `"b1:p1"` — every lowering mints fresh
/// uuids, so the file's own spellings survive only in
/// [`SourceIds`]. Titles and world
/// positions come off the document, wherever the demo has since put them.
#[derive(Clone, Copy)]
pub struct CueScope<'a> {
    indexed: IndexedDocument<'a>,
    ids: &'a SourceIds,
}

impl<'a> CueScope<'a> {
    pub fn new(indexed: IndexedDocument<'a>, ids: &'a SourceIds) -> Self {
        Self { indexed, ids }
    }

    fn block(&self, id: BlockId) -> Option<&'a Block> {
        let live = self.indexed.doc.block(&id)?;
        live.is_alive().then(|| live.as_ref())
    }

    /// The live block carrying this title. Titles are not unique by
    /// construction, so the oldest wins — the same `chronological` order
    /// the draw and hit passes take.
    fn by_title(&self, title: &str) -> Option<&'a Block> {
        chronological(
            self.indexed
                .doc
                .blocks()
                .filter(|(_, live)| live.is_alive()),
        )
        .into_iter()
        .find_map(|id| self.block(id).filter(|b| b.title.name.as_ref() == title))
    }

    fn by_source_id(&self, id: &str) -> Option<&'a Block> {
        self.block(self.ids.block(id)?)
    }

    fn rect_of(block: &Block) -> egui::Rect {
        crate::edit::lower::px_rect(*block.rect.as_ref())
    }

    /// Where a pin's wire anchors — the same point the block draws its stub
    /// tip at, resolved through the one anchor rule
    /// ([`BlockShape::pin_anchor_at`]).
    fn pin_anchor(&self, owner: BlockId, pin: PinId) -> Option<Pos2> {
        let block = self.block(owner)?;
        let pins: Vec<(PinId, &Pin)> = self
            .indexed
            .index
            .scope(owner)?
            .pins
            .iter()
            .filter_map(|&id| Some((id, self.indexed.doc.pin(&id)?.as_ref())))
            .collect();
        let placed = slot(pins.iter().find(|(id, _)| *id == pin)?.1);
        let shape = BlockShape::new(block, pins, crate::path::structure(&self.indexed, owner));
        Some(shape.pin_anchor_at(shape.rect(), placed.side, placed.offset))
    }
}

/// A lowered document held with the pieces a [`CueScope`] borrows — the
/// fixture the cue, lowering and replay tests resolve targets against.
#[cfg(test)]
pub struct CueFixture {
    doc: blockworx_doc::document::Document,
    index: blockworx_doc::document::DocIndex,
    ids: SourceIds,
}

#[cfg(test)]
impl CueFixture {
    /// What a level's `initial { … }` KDL becomes once the bridge has
    /// lowered it and the session has folded it.
    pub fn lowered(kdl: &str) -> Self {
        let parsed = crate::schema::model::Document::parse_kdl(kdl, "cue-fixture")
            .expect("the fixture parses");
        let lowered = crate::schema::lower::lower(&parsed, "cue-fixture");
        let mut doc = blockworx_doc::document::Document::default();
        for commit in &lowered.commits {
            doc = doc.try_apply(commit).expect("the lowered commit folds");
        }
        Self {
            index: blockworx_doc::document::DocIndex::of(&doc),
            doc,
            ids: lowered.ids,
        }
    }

    /// A document with nothing in it: the cases that resolve no target.
    pub fn empty() -> Self {
        let doc = blockworx_doc::document::Document::default();
        Self {
            index: blockworx_doc::document::DocIndex::of(&doc),
            doc,
            ids: SourceIds::default(),
        }
    }

    pub fn scope(&mut self) -> CueScope<'_> {
        CueScope::new(self.index.view(&self.doc), &self.ids)
    }
}

impl CueTarget {
    pub fn anchoring(self) -> Anchoring {
        match self {
            CueTarget::ToolButton(name) => Anchoring::Toolbar(name),
            CueTarget::Relative { dx, dy } => {
                Anchoring::FromDragBase(egui::vec2(dx as f32, dy as f32) * GRID_SIZE)
            }
            CueTarget::World(_)
            | CueTarget::Block(_)
            | CueTarget::Corner(..)
            | CueTarget::BlockId(_)
            | CueTarget::PinAnchor { .. } => Anchoring::Document,
        }
    }

    /// The world position this target names, resolved against the session's
    /// document. `None` for the targets that have no world position of their
    /// own (see [`CueTarget::anchoring`]) and for document anchors naming an
    /// object that doesn't exist (yet).
    pub fn world(self, scope: &CueScope<'_>) -> Option<Pos2> {
        match self {
            CueTarget::ToolButton(_) | CueTarget::Relative { .. } => None,
            CueTarget::World(p) => Some(p),
            CueTarget::Block(title) => scope.by_title(title).map(|b| CueScope::rect_of(b).center()),
            CueTarget::Corner(title, handle) => scope.by_title(title).map(|b| {
                let r = CueScope::rect_of(b);
                match handle {
                    Handle::LeftTop => r.left_top(),
                    Handle::RightTop => r.right_top(),
                    Handle::LeftBottom => r.left_bottom(),
                    Handle::RightBottom => r.right_bottom(),
                }
            }),
            CueTarget::BlockId(id) => scope
                .by_source_id(id)
                .map(|b| CueScope::rect_of(b).center()),
            CueTarget::PinAnchor { block, pin } => {
                scope.pin_anchor(scope.ids.block(block)?, scope.ids.pin(block, pin)?)
            }
        }
    }
}

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum ClickCount {
    Single,
    Double,
}

impl ClickCount {
    fn presses(self) -> u32 {
        match self {
            ClickCount::Single => 1,
            ClickCount::Double => 2,
        }
    }
}

/// Length of one animated click press (a [`Step::Click`] lasts one press per
/// [`ClickCount`]).
pub const CLICK_PRESS: Duration = Duration::from_millis(450);

/// A key the demo is holding down, drawn beside the mouse badge so a gesture
/// that depends on a modifier (space-drag to pan, shift-drag to extend a
/// selection) reads as more than a plain drag. Purely a cue: scripted input
/// carries no modifiers, so the *effect* is scripted separately (a `camera`
/// glide for a pan).
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum HeldKey {
    Ctrl,
    Shift,
    Alt,
    Space,
}

impl HeldKey {
    /// The key's name, as the badge shows it and a level spells it.
    pub fn label(self) -> &'static str {
        match self {
            HeldKey::Ctrl => "ctrl",
            HeldKey::Shift => "shift",
            HeldKey::Alt => "alt",
            HeldKey::Space => "space",
        }
    }

    pub fn parse(name: &str) -> Option<Self> {
        [HeldKey::Ctrl, HeldKey::Shift, HeldKey::Alt, HeldKey::Space]
            .into_iter()
            .find(|key| key.label() == name)
    }
}

#[derive(Clone, Copy, PartialEq, Debug)]
pub enum Step {
    /// Pulse a ring around the target; the cursor stays where it was.
    Highlight {
        target: CueTarget,
        duration: Duration,
    },
    /// Glide the cursor to the target, button up.
    MoveTo {
        target: CueTarget,
        duration: Duration,
    },
    /// Park the cursor on the target, button up — depicts hovering.
    Hover {
        target: CueTarget,
        duration: Duration,
    },
    /// Flash the button at the target: one press per [`ClickCount`].
    Click {
        target: CueTarget,
        count: ClickCount,
    },
    /// Glide with the button held — depicts a drag.
    Drag {
        from: CueTarget,
        to: CueTarget,
        duration: Duration,
    },
    /// Depict typing into an editor a previous step opened: `text` appears at
    /// the target a character at a time. The cursor stays where it was.
    Type {
        target: CueTarget,
        text: &'static str,
        duration: Duration,
    },
    Pause {
        duration: Duration,
    },
    /// Frame the player's view on this world rect from here on. With a zero
    /// `duration` it cuts; otherwise the view eases from the previous framing
    /// over `duration` (demonstrating pan/zoom), holding the input timeline
    /// while it glides. Input replay ignores it either way.
    Camera {
        rect: egui::Rect,
        duration: Duration,
    },
    /// Show this instruction centered over the player from here on (until the
    /// next `Instruct`). Instantaneous; input replay ignores it.
    Instruct {
        text: &'static str,
    },
    /// Hold a key down (or release it, with `None`) from here on, so the cue
    /// badge shows it. Instantaneous; input replay ignores it.
    Hold {
        key: Option<HeldKey>,
    },
    /// Dispatch the named registry command (see `CommandId::name`) against the
    /// session — an overlay button press or palette pick, by its typeable
    /// spelling. Resolved when the step executes, so availability follows
    /// whatever the demo has selected. Instantaneous.
    Command {
        name: &'static str,
    },
}

impl Step {
    fn duration(&self) -> Duration {
        match self {
            Step::Highlight { duration, .. }
            | Step::MoveTo { duration, .. }
            | Step::Hover { duration, .. }
            | Step::Drag { duration, .. }
            | Step::Type { duration, .. }
            | Step::Pause { duration }
            | Step::Camera { duration, .. } => *duration,
            Step::Click { count, .. } => CLICK_PRESS * count.presses(),
            Step::Instruct { .. } | Step::Command { .. } | Step::Hold { .. } => Duration::ZERO,
        }
    }

    /// Where the cursor rests once this step completes; `None` leaves it where
    /// the previous steps put it.
    fn end_cursor(&self) -> Option<CueTarget> {
        match self {
            Step::Highlight { .. }
            | Step::Type { .. }
            | Step::Pause { .. }
            | Step::Camera { .. }
            | Step::Instruct { .. }
            | Step::Command { .. }
            | Step::Hold { .. } => None,
            Step::MoveTo { target, .. }
            | Step::Hover { target, .. }
            | Step::Click { target, .. } => Some(*target),
            // A relative drag moved its own base, so the anchor re-resolves
            // to the dragged position.
            Step::Drag { from, to, .. } => Some(match to.anchoring() {
                Anchoring::FromDragBase(_) => *from,
                Anchoring::Toolbar(_) | Anchoring::Document => *to,
            }),
        }
    }
}

/// The fake cursor's position this frame. `Between` keeps both endpoints
/// symbolic so the draw pass can lerp them in screen space.
#[derive(Clone, Copy, PartialEq, Debug)]
pub enum CursorPos {
    At(CueTarget),
    Between {
        from: CueTarget,
        to: CueTarget,
        t: Progress,
    },
}

#[derive(Clone, Copy, PartialEq, Debug)]
pub enum ButtonState {
    Up,
    /// Held through a drag.
    Down,
    /// A click press; `t` runs through the press (drives the flash ring).
    Flash {
        t: Progress,
    },
}

/// Text mid-entry: the prefix of a [`Step::Type`]'s text typed so far, and
/// where the editor receiving it sits.
#[derive(Clone, Copy, PartialEq, Debug)]
pub struct TypingCue {
    pub target: CueTarget,
    pub typed: &'static str,
}

/// One sampled animation frame.
#[derive(Clone, Copy, PartialEq, Debug)]
pub struct CueFrame {
    /// `None` until a step first establishes a cursor position (e.g. during an
    /// opening `Highlight`).
    pub cursor: Option<CursorPos>,
    pub button: ButtonState,
    /// The key held as of this frame (see [`Step::Hold`]).
    pub held: Option<HeldKey>,
    pub highlight: Option<CueTarget>,
    pub typing: Option<TypingCue>,
}

#[derive(Clone)]
pub struct Script {
    steps: Vec<Step>,
}

/// Assembles a [`Script`] one step at a time, so a test's script reads as a
/// sentence instead of a struct literal. Shipped scripts come from level KDL
/// (see `crate::tutorial::level`); the builder survives as the tests' authoring
/// surface.
#[cfg(test)]
#[derive(Default)]
pub struct ScriptBuilder {
    steps: Vec<Step>,
}

// A test utility keeps its full step vocabulary even when no current test
// exercises every method.
#[cfg(test)]
#[allow(dead_code)]
impl ScriptBuilder {
    #[must_use]
    pub fn highlight(self, target: CueTarget, duration: Duration) -> Self {
        self.step(Step::Highlight { target, duration })
    }

    #[must_use]
    pub fn move_to(self, target: CueTarget, duration: Duration) -> Self {
        self.step(Step::MoveTo { target, duration })
    }

    #[must_use]
    pub fn hover(self, target: CueTarget, duration: Duration) -> Self {
        self.step(Step::Hover { target, duration })
    }

    #[must_use]
    pub fn click(self, target: CueTarget) -> Self {
        self.step(Step::Click {
            target,
            count: ClickCount::Single,
        })
    }

    #[must_use]
    pub fn double_click(self, target: CueTarget) -> Self {
        self.step(Step::Click {
            target,
            count: ClickCount::Double,
        })
    }

    #[must_use]
    pub fn drag(self, from: CueTarget, to: CueTarget, duration: Duration) -> Self {
        self.step(Step::Drag { from, to, duration })
    }

    #[must_use]
    pub fn type_text(self, target: CueTarget, text: &'static str, duration: Duration) -> Self {
        self.step(Step::Type {
            target,
            text,
            duration,
        })
    }

    #[must_use]
    pub fn pause(self, duration: Duration) -> Self {
        self.step(Step::Pause { duration })
    }

    pub fn build(self) -> Script {
        Script::new(self.steps)
    }

    #[must_use]
    fn step(mut self, step: Step) -> Self {
        self.steps.push(step);
        self
    }
}

#[cfg(test)]
impl From<ScriptBuilder> for Script {
    fn from(builder: ScriptBuilder) -> Self {
        builder.build()
    }
}

impl Script {
    #[cfg(test)]
    pub fn builder() -> ScriptBuilder {
        ScriptBuilder::default()
    }

    pub fn new(steps: Vec<Step>) -> Self {
        Self { steps }
    }

    /// One script playing `scripts` back to back — the whole-level demo
    /// derived from the per-stage scripts.
    pub fn concat<'a>(scripts: impl IntoIterator<Item = &'a Script>) -> Script {
        Script::new(
            scripts
                .into_iter()
                .flat_map(|s| s.steps.iter().copied())
                .collect(),
        )
    }

    pub fn steps(&self) -> &[Step] {
        &self.steps
    }

    pub fn total(&self) -> Duration {
        self.steps.iter().map(Step::duration).sum()
    }

    /// The player camera as of `elapsed`: the last [`Step::Camera`] whose
    /// start has been reached — eased from the previous framing while a
    /// glide (non-zero duration) is in progress. Past the end, the final
    /// camera. A glide with no previous camera cuts (there is nothing to
    /// glide from).
    pub fn camera_at(&self, elapsed: Duration) -> Option<egui::Rect> {
        let mut acc = Duration::ZERO;
        let mut current: Option<egui::Rect> = None;
        for step in &self.steps {
            if acc > elapsed {
                break;
            }
            if let Step::Camera { rect, duration } = step {
                current = Some(match current {
                    Some(from) if elapsed < acc + *duration => {
                        let p = Progress::through(elapsed.saturating_sub(acc), *duration).eased();
                        lerp_rect(from, *rect, p)
                    }
                    _ => *rect,
                });
            }
            acc += step.duration();
        }
        current
    }

    /// The centered instruction as of `elapsed`: the last [`Step::Instruct`]
    /// whose start has been reached.
    pub fn instruction_at(&self, elapsed: Duration) -> Option<&'static str> {
        self.applied(elapsed, |step| match step {
            Step::Instruct { text } => Some(*text),
            _ => None,
        })
    }

    /// The last `Some` that `pick` yields over the steps whose start time is
    /// at or before `elapsed` — how the zero-duration state steps (camera,
    /// instruction) persist until superseded.
    fn applied<T>(&self, elapsed: Duration, pick: impl Fn(&Step) -> Option<T>) -> Option<T> {
        let mut acc = Duration::ZERO;
        let mut current = None;
        for step in &self.steps {
            if acc > elapsed {
                break;
            }
            if let Some(value) = pick(step) {
                current = Some(value);
            }
            acc += step.duration();
        }
        current
    }

    /// The frame at `elapsed` into the script, or `None` once the script has
    /// finished — it plays once; replaying is the caller re-anchoring its
    /// start time.
    pub fn sample(&self, elapsed: Duration) -> Option<CueFrame> {
        let mut remaining = elapsed;
        // The resting position accumulated from completed steps.
        let mut cursor: Option<CueTarget> = None;
        let mut held: Option<HeldKey> = None;
        for step in &self.steps {
            // Zero-duration state steps apply as they are passed.
            if let Step::Hold { key } = step {
                held = *key;
            }
            let duration = step.duration();
            if remaining < duration {
                let p = Progress::through(remaining, duration);
                return Some(CueFrame {
                    held,
                    ..Self::frame(step, cursor, p, remaining)
                });
            }
            remaining -= duration;
            if let Some(c) = step.end_cursor() {
                cursor = Some(c);
            }
        }
        None
    }

    /// The frame `into_step` into `step` (progress `p`), with the cursor
    /// previously resting at `prev`.
    fn frame(step: &Step, prev: Option<CueTarget>, p: Progress, into_step: Duration) -> CueFrame {
        let parked = prev.map(CursorPos::At);
        let base = CueFrame {
            cursor: parked,
            button: ButtonState::Up,
            held: None,
            highlight: None,
            typing: None,
        };
        match step {
            Step::Highlight { target, .. } => CueFrame {
                highlight: Some(*target),
                ..base
            },
            // Nothing to depict: a pause, a camera glide (the view itself
            // moves), or the instantaneous instruction/command steps.
            Step::Pause { .. }
            | Step::Camera { .. }
            | Step::Instruct { .. }
            | Step::Command { .. }
            | Step::Hold { .. } => base,
            Step::Hover { target, .. } => CueFrame {
                cursor: Some(CursorPos::At(*target)),
                ..base
            },
            Step::Type { target, text, .. } => CueFrame {
                typing: Some(TypingCue {
                    target: *target,
                    typed: typed_prefix(text, p),
                }),
                ..base
            },
            Step::MoveTo { target, .. } => CueFrame {
                // With no prior position the cursor appears at the target.
                cursor: Some(match prev {
                    Some(from) => CursorPos::Between {
                        from,
                        to: *target,
                        t: p.eased(),
                    },
                    None => CursorPos::At(*target),
                }),
                ..base
            },
            Step::Click { target, .. } => CueFrame {
                cursor: Some(CursorPos::At(*target)),
                button: ButtonState::Flash {
                    t: Progress::new(into_step.div_duration_f32(CLICK_PRESS).fract()),
                },
                ..base
            },
            Step::Drag { from, to, .. } => CueFrame {
                cursor: Some(match to.anchoring() {
                    // A relative destination drags its own base: the doc
                    // anchor follows the session's pointer frame by frame, so
                    // riding the re-resolved anchor IS the drag path (a
                    // symbolic lerp against the moving base would overshoot).
                    Anchoring::FromDragBase(_) => CursorPos::At(*from),
                    Anchoring::Toolbar(_) | Anchoring::Document => CursorPos::Between {
                        from: *from,
                        to: *to,
                        t: p.eased(),
                    },
                }),
                button: ButtonState::Down,
                ..base
            },
        }
    }
}

/// The characters of `text` entered by progress `p` through a [`Step::Type`].
/// Shared with the lowering pass, which types the same prefixes into the
/// captured editor buffer.
pub(super) fn typed_prefix(text: &'static str, p: Progress) -> &'static str {
    let entered = (p.get() * text.chars().count() as f32).ceil() as usize;
    let end = text
        .char_indices()
        .nth(entered)
        .map_or(text.len(), |(i, _)| i);
    &text[..end]
}

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

    fn demo() -> Script {
        Script::new(vec![
            Step::Highlight {
                target: CueTarget::ToolButton(ToolName::NewBlock),
                duration: Duration::from_secs(1),
            },
            Step::Click {
                target: CueTarget::ToolButton(ToolName::NewBlock),
                count: ClickCount::Double,
            },
            Step::Drag {
                from: CueTarget::World(grid_pos(0, 0)),
                to: CueTarget::World(grid_pos(8, 0)),
                duration: Duration::from_secs(2),
            },
            Step::Pause {
                duration: Duration::from_millis(500),
            },
        ])
    }

    #[test]
    fn camera_glides_between_framings() {
        let a = egui::Rect::from_min_max(grid_pos(0, 0), grid_pos(10, 10));
        let b = egui::Rect::from_min_max(grid_pos(20, 0), grid_pos(40, 20));
        let script = Script::new(vec![
            Step::Camera {
                rect: a,
                duration: Duration::ZERO,
            },
            Step::Camera {
                rect: b,
                duration: Duration::from_secs(2),
            },
        ]);
        assert_eq!(script.camera_at(Duration::ZERO), Some(a));
        // Halfway through the glide the eased curve is exactly midway.
        let mid = script.camera_at(Duration::from_secs(1)).unwrap();
        assert_eq!(mid.min, a.min.lerp(b.min, 0.5));
        assert_eq!(mid.max, a.max.lerp(b.max, 0.5));
        assert_eq!(script.camera_at(Duration::from_secs(2)), Some(b));
        assert_eq!(script.camera_at(Duration::from_secs(10)), Some(b));
        // The glide holds the input timeline for its duration.
        assert_eq!(script.total(), Duration::from_secs(2));
    }

    #[test]
    fn a_leading_glide_cuts_to_its_target() {
        let b = egui::Rect::from_min_max(grid_pos(20, 0), grid_pos(40, 20));
        let script = Script::new(vec![Step::Camera {
            rect: b,
            duration: Duration::from_secs(2),
        }]);
        assert_eq!(script.camera_at(Duration::ZERO), Some(b));
        assert_eq!(script.camera_at(Duration::from_secs(1)), Some(b));
    }

    /// A held key persists across the steps that follow it, until released —
    /// the badge shows "+ ctrl" for the whole gesture, not one step of it.
    #[test]
    fn a_held_key_persists_until_released() {
        let script = Script::new(vec![
            Step::Pause {
                duration: Duration::from_secs(1),
            },
            Step::Hold {
                key: Some(HeldKey::Space),
            },
            Step::Drag {
                from: at(0, 0),
                to: at(4, 0),
                duration: Duration::from_secs(2),
            },
            Step::Hold { key: None },
            Step::Pause {
                duration: Duration::from_secs(1),
            },
        ]);
        let held = |secs| script.sample(Duration::from_secs(secs)).unwrap().held;
        assert_eq!(held(0), None, "before the hold");
        assert_eq!(held(2), Some(HeldKey::Space), "mid-drag");
        assert_eq!(held(3), None, "after the release");
    }

    #[test]
    fn totals_sum_step_durations() {
        // 1 s highlight + 2 click presses + 2 s drag + 0.5 s pause.
        let expected = Duration::from_millis(3500) + CLICK_PRESS * 2;
        assert_eq!(demo().total(), expected);
    }

    #[test]
    fn highlight_has_no_cursor_until_one_is_established() {
        let frame = demo().sample(Duration::from_millis(500)).unwrap();
        assert_eq!(frame.cursor, None);
        assert_eq!(
            frame.highlight,
            Some(CueTarget::ToolButton(ToolName::NewBlock))
        );
        assert_eq!(frame.button, ButtonState::Up);
    }

    #[test]
    fn double_click_flashes_twice() {
        let script = demo();
        // First press: just after the highlight ends.
        let just_in = Duration::from_secs(1) + Duration::from_millis(100);
        let first = script.sample(just_in).unwrap();
        // Second press: one press-length later.
        let second = script.sample(just_in + CLICK_PRESS).unwrap();
        for frame in [first, second] {
            assert!(matches!(frame.button, ButtonState::Flash { .. }));
            assert_eq!(
                frame.cursor,
                Some(CursorPos::At(CueTarget::ToolButton(ToolName::NewBlock)))
            );
        }
        // The flash phase restarts for the second press.
        let ButtonState::Flash { t: t1 } = first.button else {
            unreachable!()
        };
        let ButtonState::Flash { t: t2 } = second.button else {
            unreachable!()
        };
        assert!((t1.get() - t2.get()).abs() < 1e-3, "{t1:?} vs {t2:?}");
    }

    #[test]
    fn drag_interpolates_between_endpoints_with_button_down() {
        let script = demo();
        let drag_start = Duration::from_secs(1) + CLICK_PRESS * 2;
        let frame = script.sample(drag_start + Duration::from_secs(1)).unwrap();
        assert_eq!(frame.button, ButtonState::Down);
        let Some(CursorPos::Between { t, .. }) = frame.cursor else {
            panic!("expected a lerping cursor, got {:?}", frame.cursor);
        };
        // Halfway through the eased glide.
        assert!((t.get() - 0.5).abs() < 1e-3, "{t:?}");
    }

    #[test]
    fn pause_keeps_the_cursor_where_the_drag_left_it() {
        let script = demo();
        let pause_at = script
            .total()
            .checked_sub(Duration::from_millis(250))
            .unwrap();
        let frame = script.sample(pause_at).unwrap();
        assert_eq!(
            frame.cursor,
            Some(CursorPos::At(CueTarget::World(grid_pos(8, 0))))
        );
    }

    /// Doc-anchored targets resolve against the *lowered* document: by
    /// title off its registers, and by the file's own ids through the
    /// bridge's table (the uuids it minted leave nothing else to key on).
    #[test]
    fn doc_anchored_targets_follow_the_lowered_block() {
        let mut fixture = CueFixture::lowered(
            r#"
top "b0"

block "b0" x=0 y=0 w=28 h=20 {
    title "sheet"
    children "b1"
}

block "b1" x=4 y=4 w=8 h=7 {
    title "core"
    pin "p1" "in" loc="w1" dir="input"
}
"#,
        );
        let doc = &fixture.scope();
        assert_eq!(
            block("core").world(doc),
            Some(grid_pos(8, 7).lerp(grid_pos(8, 8), 0.5))
        );
        assert_eq!(
            corner("core", Handle::RightBottom).world(doc),
            Some(grid_pos(12, 11))
        );
        assert_eq!(
            CueTarget::BlockId("b1").world(doc),
            block("core").world(doc),
            "the file's own id names the same block its title does",
        );
        // The wire anchor is the pin's tip: one cell outside the west edge,
        // `pin_offset_y` down from the block's top.
        assert_eq!(
            CueTarget::PinAnchor {
                block: "b1",
                pin: "p1"
            }
            .world(doc),
            Some(egui::pos2(
                px(4) - GRID_SIZE,
                crate::grid::pin_offset_y(px(4), 1)
            )),
        );
        assert_eq!(block("missing").world(doc), None);
        assert_eq!(CueTarget::BlockId("b9").world(doc), None);
        assert_eq!(tool(ToolName::NewBlock).world(doc), None);
        assert_eq!(at(3, 5).world(doc), Some(grid_pos(3, 5)));
    }

    #[test]
    fn typing_reveals_characters_and_leaves_the_cursor_parked() {
        let script = Script::new(vec![
            Step::MoveTo {
                target: CueTarget::World(grid_pos(4, 0)),
                duration: Duration::from_secs(1),
            },
            Step::Type {
                target: CueTarget::World(grid_pos(0, 0)),
                text: "CPU",
                duration: Duration::from_secs(3),
            },
        ]);
        let at = |millis: u64| {
            script
                .sample(Duration::from_secs(1) + Duration::from_millis(millis))
                .unwrap()
        };
        assert_eq!(at(500).typing.unwrap().typed, "C");
        assert_eq!(at(1500).typing.unwrap().typed, "CP");
        assert_eq!(at(2900).typing.unwrap().typed, "CPU");
        assert_eq!(
            at(1500).cursor,
            Some(CursorPos::At(CueTarget::World(grid_pos(4, 0))))
        );
    }

    #[test]
    fn a_finished_script_yields_no_frame() {
        let script = demo();
        assert!(
            script
                .sample(script.total() + Duration::from_millis(10))
                .is_none()
        );
    }
}