blockworx/script/

lowering.rs

//! Lower a [`Script`] into the per-frame synthetic input a human performing
//! it would have produced: hover glides, click/drag events, tool switches,
//! and editor typing, at a fixed timestep so replays are deterministic.
//!
//! Lowering is *streaming*: each step's endpoints resolve against the
//! document as the step begins, because earlier frames may have created or
//! moved the very objects a later step targets (a drag that moves a block
//! must not chase the block it is moving).

use std::time::Duration;

use egui::Pos2;

use crate::canvas::{Event, Press};
use crate::progress::Progress;
use crate::tools::names::ToolName;

use super::step::{Anchoring, ClickCount, CueScope, CueTarget, Script, Step, typed_prefix};

/// The fixed simulation timestep (one frame at 60 Hz).
pub const SIM_DT: Duration = Duration::from_nanos(1_000_000_000 / 60);

/// One frame of synthetic input.
#[derive(Clone, Copy, Debug, Default)]
pub struct SimFrame {
    /// Canvas event, world space — what `compute_interaction` would have
    /// produced from the real pointer.
    pub event: Option<Event>,
    /// The held primary button, world space — the level `compute_interaction`
    /// reports while a click or drag is in progress.
    pub press: Option<Press>,
    /// A toolbar press this frame: arm this tool.
    pub switch_tool: Option<ToolName>,
    /// Text to force into the open in-place editor, plus whether this frame
    /// finishes the entry (Enter on the next frame).
    pub typing: Option<Typing>,
    /// A registry command to dispatch this frame, by its typeable name.
    pub command: Option<&'static str>,
}

#[derive(Clone, Copy, Debug)]
pub struct Typing {
    /// The prefix typed so far (grows frame over frame).
    pub text: &'static str,
    /// This frame completes the entry; the runner presses Enter next frame.
    pub commit: bool,
}

/// A doc-anchored target named an object the document doesn't have — the
/// stage's demo references something its prerequisites didn't create.
// The fields reach error reports through the derived Debug, which dead-code
// analysis deliberately ignores.
#[derive(Debug)]
#[allow(dead_code)]
pub struct UnresolvedTarget {
    pub step: usize,
    pub target: CueTarget,
}

/// Streaming lowerer over one script. Call [`Lowering::next`] with the
/// *current* document each frame until it returns `Ok(None)`.
pub struct Lowering {
    steps: Vec<Step>,
    step: usize,
    /// Frames already emitted for the current step.
    frame: u32,
    /// World endpoints of the current step, resolved when it began.
    span: Option<(Option<Pos2>, Option<Pos2>)>,
    /// Where the cursor rests, in world space (`None` after toolbar targets).
    cursor: Option<Pos2>,
}

impl Lowering {
    pub fn new(script: &Script) -> Self {
        Self {
            steps: script.steps().to_vec(),
            step: 0,
            frame: 0,
            span: None,
            cursor: None,
        }
    }

    /// Which step the frame just handed out came from.
    #[cfg(test)]
    pub fn step(&self) -> usize {
        self.step
    }

    /// The next frame of input, or `Ok(None)` when the script has finished.
    ///
    /// `scope` is read only where the lowerer actually resolves endpoints —
    /// the first frame of a step.
    pub fn next(&mut self, scope: &CueScope<'_>) -> Result<Option<SimFrame>, UnresolvedTarget> {
        loop {
            let Some(step) = self.steps.get(self.step) else {
                return Ok(None);
            };
            let frames = step_frames(step);
            if self.frame >= frames {
                self.finish_step();
                continue;
            }
            let (from, to) = if let Some(span) = self.span {
                span
            } else {
                let span = self.resolve_span(step, scope)?;
                self.span = Some(span);
                span
            };
            // Progress through the step at this frame's *end*, so the final
            // frame lands exactly on the target.
            let p = Progress::new((self.frame + 1) as f32 / frames as f32);
            let frame = self.frame;
            self.frame += 1;
            let lerp = |p: Progress| match (from, to) {
                (Some(a), Some(b)) => Some(a.lerp(b, p.eased().get())),
                (_, b) => b,
            };
            let sim = match step {
                Step::Highlight { .. }
                | Step::Pause { .. }
                | Step::Camera { .. }
                | Step::Instruct { .. }
                | Step::Hold { .. } => SimFrame::default(),
                Step::Command { name } => SimFrame {
                    command: Some(name),
                    ..SimFrame::default()
                },
                Step::MoveTo { .. } | Step::Hover { .. } => SimFrame {
                    event: lerp(p).map(Event::HoverAt),
                    ..SimFrame::default()
                },
                Step::Click { target, count } => lower_click(*target, *count, p, to),
                Step::Drag { .. } => {
                    let (Some(a), Some(b)) = (from, to) else {
                        return Err(self.unresolved(step));
                    };
                    // The glide occupies frames 0..frames-1 and *completes* on
                    // the last Dragging frame, so per-frame deltas sum exactly
                    // to the displacement (movers accumulate deltas and ignore
                    // the stop position). DragStopped is its own final frame.
                    let motion = |f: u32| {
                        let q = Progress::new(f as f32 / (frames - 2) as f32);
                        a.lerp(b, q.eased().get())
                    };
                    // The button releases on the stop frame, exactly as a live
                    // drag reports it.
                    let (event, press) = if frame == 0 {
                        (Event::DragStarted { pos: a }, Some(Press { origin: a }))
                    } else if self.frame == frames {
                        (Event::DragStopped { pos: b }, None)
                    } else {
                        (
                            Event::Dragging {
                                pos: motion(frame),
                                delta: motion(frame) - motion(frame - 1),
                            },
                            Some(Press { origin: a }),
                        )
                    };
                    SimFrame {
                        event: Some(event),
                        press,
                        ..SimFrame::default()
                    }
                }
                Step::Type { text, .. } => SimFrame {
                    typing: Some(Typing {
                        text: typed_prefix(text, p),
                        commit: self.frame == frames,
                    }),
                    ..SimFrame::default()
                },
            };
            return Ok(Some(sim));
        }
    }

    /// Resolve the step's world endpoints as it begins: `from` is where the
    /// cursor rests, `to` the step's target.
    fn resolve_span(
        &self,
        step: &Step,
        scope: &CueScope<'_>,
    ) -> Result<(Option<Pos2>, Option<Pos2>), UnresolvedTarget> {
        let resolve = |target: &CueTarget| -> Result<Option<Pos2>, UnresolvedTarget> {
            match target.anchoring() {
                // Toolbar targets have no world position by design.
                Anchoring::Toolbar(_) => Ok(None),
                Anchoring::Document | Anchoring::FromDragBase(_) => target
                    .world(scope)
                    .map(Some)
                    .ok_or_else(|| self.unresolved(step)),
            }
        };
        Ok(match step {
            Step::Highlight { .. }
            | Step::Pause { .. }
            | Step::Type { .. }
            | Step::Camera { .. }
            | Step::Instruct { .. }
            | Step::Command { .. }
            | Step::Hold { .. } => (self.cursor, self.cursor),
            Step::MoveTo { target, .. }
            | Step::Hover { target, .. }
            | Step::Click { target, .. } => (self.cursor, resolve(target)?),
            Step::Drag { from, to, .. } => {
                let a = resolve(from)?;
                let b = match to.anchoring() {
                    Anchoring::FromDragBase(offset) => a.map(|p| p + offset),
                    Anchoring::Toolbar(_) | Anchoring::Document => resolve(to)?,
                };
                (a, b)
            }
        })
    }

    fn finish_step(&mut self) {
        if let Some((_, to)) = self.span.take()
            && !matches!(
                self.steps[self.step],
                Step::Highlight { .. }
                    | Step::Pause { .. }
                    | Step::Type { .. }
                    | Step::Camera { .. }
                    | Step::Instruct { .. }
                    | Step::Command { .. }
                    | Step::Hold { .. }
            )
        {
            self.cursor = to.or(self.cursor);
        }
        self.step += 1;
        self.frame = 0;
    }

    fn unresolved(&self, step: &Step) -> UnresolvedTarget {
        let target = match step {
            Step::Highlight { target, .. }
            | Step::MoveTo { target, .. }
            | Step::Hover { target, .. }
            | Step::Click { target, .. }
            | Step::Type { target, .. } => *target,
            Step::Drag { from, to, .. } => {
                // Whichever endpoint failed; prefer naming the one that can't
                // be a fixed position.
                if matches!(from, CueTarget::World(_)) {
                    *to
                } else {
                    *from
                }
            }
            // These have no target and resolve unconditionally.
            Step::Pause { .. }
            | Step::Camera { .. }
            | Step::Instruct { .. }
            | Step::Command { .. }
            | Step::Hold { .. } => CueTarget::World(Pos2::ZERO),
        };
        UnresolvedTarget {
            step: self.step,
            target,
        }
    }
}

/// A click flashes for its press duration but acts once, on its final
/// frame: the canvas event or the toolbar switch. The frames before it hold
/// the button down at the target — the release is what egui's click *is* —
/// so press-and-hold affordances see the same sequence a live click makes.
fn lower_click(target: CueTarget, count: ClickCount, p: Progress, world: Option<Pos2>) -> SimFrame {
    if !p.is_complete() {
        return SimFrame {
            press: world.map(|origin| Press { origin }),
            ..SimFrame::default()
        };
    }
    match (target, world) {
        (CueTarget::ToolButton(name), _) => SimFrame {
            switch_tool: Some(name),
            ..SimFrame::default()
        },
        (_, Some(pos)) => SimFrame {
            event: Some(match count {
                ClickCount::Single => Event::Clicked { pos },
                ClickCount::Double => Event::DoubleClicked { pos },
            }),
            ..SimFrame::default()
        },
        (_, None) => SimFrame::default(),
    }
}

/// Frames a step occupies at [`SIM_DT`] (at least one; a drag needs start,
/// one full-displacement `Dragging`, and stop — at least three).
fn step_frames(step: &Step) -> u32 {
    let duration = match step {
        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, .. } => match count {
            ClickCount::Single => super::step::CLICK_PRESS,
            ClickCount::Double => super::step::CLICK_PRESS * 2,
        },
        // Instantaneous steps; the one-frame floor below keeps the replay
        // loop uniform.
        Step::Instruct { .. } | Step::Command { .. } | Step::Hold { .. } => Duration::ZERO,
    };
    let floor = if matches!(step, Step::Drag { .. }) {
        3
    } else {
        1
    };
    ((duration.div_duration_f32(SIM_DT)).round() as u32).max(floor)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::script::step::{CueFixture, Script, at, grid_pos, tool};
    use crate::tools::names::ToolName;

    fn drain(script: &Script) -> Vec<SimFrame> {
        // A document with no blocks: lowering only reads it to resolve
        // targets, and these cases resolve none.
        let mut fixture = CueFixture::empty();
        let scope = fixture.scope();
        let mut lowering = Lowering::new(script);
        let mut frames = Vec::new();
        while let Some(f) = lowering.next(&scope).unwrap() {
            frames.push(f);
        }
        frames
    }

    #[test]
    fn drag_lowers_to_start_move_stop_with_exact_deltas() {
        let script = Script::builder()
            .drag(at(0, 0), at(8, 0), Duration::from_millis(500))
            .build();
        let frames = drain(&script);
        assert_eq!(frames.len(), 30);
        assert_eq!(
            frames[0].event,
            Some(Event::DragStarted {
                pos: grid_pos(0, 0)
            })
        );
        assert_eq!(
            frames.last().unwrap().event,
            Some(Event::DragStopped {
                pos: grid_pos(8, 0)
            })
        );
        // Movers accumulate Dragging deltas and ignore the stop position, so
        // the deltas must sum to exactly the displacement.
        let sum = frames
            .iter()
            .filter_map(|f| match f.event {
                Some(Event::Dragging { delta, .. }) => Some(delta),
                _ => None,
            })
            .fold(egui::Vec2::ZERO, |acc, d| acc + d);
        let expected = grid_pos(8, 0) - grid_pos(0, 0);
        assert!((sum.x - expected.x).abs() < 1e-3, "{sum:?}");
        assert!(sum.y.abs() < 1e-6);
    }

    #[test]
    fn relative_drag_lands_at_the_offset_from_its_start() {
        let script = Script::builder()
            .drag(
                at(2, 3),
                crate::script::step::by(4, -3),
                Duration::from_millis(500),
            )
            .build();
        let frames = drain(&script);
        assert_eq!(
            frames[0].event,
            Some(Event::DragStarted {
                pos: grid_pos(2, 3)
            })
        );
        assert_eq!(
            frames.last().unwrap().event,
            Some(Event::DragStopped {
                pos: grid_pos(6, 0)
            })
        );
    }

    #[test]
    fn toolbar_click_lowers_to_a_tool_switch() {
        let script = Script::builder()
            .highlight(tool(ToolName::Route), Duration::from_millis(100))
            .click(tool(ToolName::Route))
            .build();
        let frames = drain(&script);
        let switches: Vec<_> = frames.iter().filter_map(|f| f.switch_tool).collect();
        assert_eq!(switches, vec![ToolName::Route]);
        assert!(frames.iter().all(|f| f.event.is_none()));
    }

    #[test]
    fn click_after_move_lands_on_the_target() {
        let script = Script::builder()
            .move_to(at(4, 4), Duration::from_millis(200))
            .click(at(4, 4))
            .build();
        let frames = drain(&script);
        let clicks: Vec<_> = frames
            .iter()
            .filter_map(|f| match f.event {
                Some(Event::Clicked { pos }) => Some(pos),
                _ => None,
            })
            .collect();
        assert_eq!(clicks, vec![grid_pos(4, 4)]);
        // Hover frames precede the click and end on the target.
        assert!(matches!(frames[0].event, Some(Event::HoverAt(_))));
    }

    #[test]
    fn typing_grows_and_commits_on_the_final_frame() {
        let script = Script::builder()
            .type_text(at(0, 0), "CPU", Duration::from_millis(200))
            .build();
        let frames = drain(&script);
        let last = frames.last().unwrap().typing.unwrap();
        assert_eq!(last.text, "CPU");
        assert!(last.commit);
        assert!(
            frames
                .iter()
                .rev()
                .skip(1)
                .all(|f| !f.typing.unwrap().commit)
        );
    }

    #[test]
    fn unresolved_block_target_reports_the_step() {
        let script = Script::builder()
            .move_to(
                crate::script::step::block("ghost"),
                Duration::from_millis(200),
            )
            .build();
        let mut fixture = CueFixture::empty();
        let err = Lowering::new(&script).next(&fixture.scope()).unwrap_err();
        assert_eq!(err.step, 0);
    }
}