blockworx/script/

driver.rs

//! The synthetic-input state machine every scripted driver shares: the
//! pointer, held button and queued editor commit a script's [`SimFrame`]s
//! imply, and the one implementation of *applying* such a frame to an editing
//! state through a painter.
//!
//! The painter is a parameter, which is the whole trick: the headless test
//! harness hands in a throwaway painter and gets the golden-replay tests; the
//! tutorial player hands in its video pane's painter and every `widget()` call
//! *is* a video frame — previews, selection frames, everything the real tools
//! draw.
//!
//! [`SimClock`] is the other half: real time banked into whole sim frames, so
//! a hitch can't fast-forward a demo.

use std::time::Duration;

use egui::Pos2;

use crate::doc::Writability;
use crate::gesture::Gesture;
use blockworx_doc::document::DocIndex;

use crate::canvas::painter::Painter;
use crate::canvas::{Event, Interaction, Press};
use crate::gesture;
use crate::path::BlockPath;
use crate::theme::{Style, Theme};
use crate::tools::commands;
use crate::tools::tool::{Action, Tool, ToolTrait};
use blockworx_doc::repo::Repo;

use super::lowering::{SIM_DT, SimFrame};

/// The editing state a scripted frame acts on: a repo to submit to, the
/// caches beside it, and the armed tool. Separate borrows, so a driver whose
/// repo and tool live in different fields of a larger struct (the app)
/// can hand them over without borrowing itself whole.
pub struct SimTarget<'a> {
    pub repo: &'a mut Repo,
    pub index: &'a mut DocIndex,
    pub path: &'a BlockPath,
    pub presentation: &'a mut crate::presentation::Presentation,
    /// The gesture in progress. The driver opens and closes one per frame,
    /// exactly as the app's canvas pass does.
    pub gesture: &'a mut Gesture,
    pub tool: &'a mut Tool,
}

#[derive(Default)]
pub struct SimDriver {
    /// Enter queued by a committed typing frame, delivered on the next frame
    /// so the editor sees its buffer before the key.
    pending_enter: bool,
    /// Where the script's events last put the pointer (world space) — the
    /// driver's stand-in for a physical pointer, fed to the painter so hover
    /// affordances light up under the demo cursor.
    pointer: Option<Pos2>,
    /// The held button as of the last scripted frame, re-presented by idle
    /// frames so press affordances stay armed between them.
    press: Option<Press>,
    /// Between `DragStarted` and `DragStopped`: idle frames must not
    /// re-present a hover mid-gesture.
    dragging: bool,
}

impl SimDriver {
    /// One synthetic frame through the real tool, exactly as `View::show`
    /// would deliver it: apply a toolbar switch, run `widget()` against
    /// `egui_painter` (in world coordinates — offset zero, zoom one), then
    /// drive the in-place editor the tool may have opened.
    pub fn apply(
        &mut self,
        frame: SimFrame,
        target: SimTarget<'_>,
        theme: &Theme,
        egui_painter: &egui::Painter,
    ) {
        let SimTarget {
            repo,
            index,
            path,
            presentation,
            gesture,
            tool,
        } = target;
        if let Some(name) = frame.switch_tool {
            // Arming a tool authors nothing: the gesture the outgoing tool
            // was in sealed when its frame ended.
            *tool = Tool::from_name(name);
        }
        self.track(frame.event);
        self.press = frame.press;
        let interaction = self.interaction(&frame);
        let mut painter = Painter::headless(egui_painter.clone(), theme.palette().clone());
        // The driver's input is exclusively this frame's `Interaction` plus
        // the synthetic pointer tracked from it: the tools' raw-pointer reads
        // (hover and press-and-hold affordances) must see the demo's pointer,
        // never the user's mouse.
        painter.set_scripted(crate::canvas::painter::ScriptedInput {
            pointer: self.pointer,
        });
        // The frame IS the tool's gesture, exactly as the app's canvas pass
        // is: everything it writes seals into one commit labelled for the
        // tool that made it.
        // A scripted session drives its own scratch repo, which is always
        // writable — there is no container to be locked and no past to view.
        *gesture = gesture::Gesture::open(
            crate::edit::describe::Label::verb(tool.name().verb()),
            Writability::Writable,
        );
        let action = {
            let mut drawing = gesture::drawing(repo, index, path, presentation, gesture);
            let mut style = Style::new(theme, &mut painter);
            crate::tools::tool::frame(tool, &mut drawing, &interaction, &mut style)
        };
        gesture::close(repo, index, path, presentation, gesture);
        // The editor seam: a tool that opened an in-place editor surfaces it
        // here (the on-screen `View` renders a TextEdit from it). Type by
        // writing the shared buffer; commit by queueing Enter.
        if let Some(typing) = frame.typing
            && let Some(edit) = painter.take_edit_text()
        {
            let mut buffer = edit.buffer.borrow_mut();
            buffer.clear();
            buffer.push_str(typing.text);
            if typing.commit {
                self.pending_enter = true;
            }
        }
        // Actions the tools return apply through the same document-scoped
        // dispatcher the app uses; app-level requests (export, pickers,
        // clipboard) are logged and dropped rather than silently diverging.
        if let Some(action) = action
            && let Some(other) = dispatch(
                action,
                SimTarget {
                    repo,
                    index,
                    path,
                    presentation,
                    gesture,
                    tool,
                },
            )
        {
            tracing::warn!(
                "scripted frame ignoring app-level action: {}",
                action_name(&other)
            );
        }
        if let Some(name) = frame.command {
            run_command(
                name,
                SimTarget {
                    repo,
                    index,
                    path,
                    presentation,
                    gesture,
                    tool,
                },
            );
        }
    }

    /// The frame a driver feeds when the script owes nothing this instant —
    /// the player's visible paint pass, the post-script commit flush. It
    /// re-presents the resting pointer as a hover (a physical pointer doesn't
    /// vanish between events), so per-frame hover affordances stay lit.
    pub fn idle_frame(&self) -> SimFrame {
        SimFrame {
            event: (!self.dragging)
                .then_some(self.pointer)
                .flatten()
                .map(Event::HoverAt),
            press: self.press,
            ..SimFrame::default()
        }
    }

    /// [`SimDriver::idle_frame`] as an interaction, for a visible pass that
    /// runs the tool itself (the app's canvas) instead of through
    /// [`SimDriver::apply`].
    pub fn idle_interaction(&mut self) -> Interaction {
        let idle = self.idle_frame();
        self.interaction(&idle)
    }

    pub fn pointer(&self) -> Option<Pos2> {
        self.pointer
    }

    /// A committed typing frame owes an Enter, so the script isn't done until
    /// a later frame has delivered it.
    pub fn enter_pending(&self) -> bool {
        self.pending_enter
    }

    #[cfg(test)]
    pub fn queue_enter(&mut self) {
        self.pending_enter = true;
    }

    fn interaction(&mut self, frame: &SimFrame) -> Interaction {
        Interaction {
            event: frame.event,
            press: frame.press,
            lost_focus: false,
            enter_pressed: std::mem::take(&mut self.pending_enter),
            tab_pressed: false,
            escape_pressed: false,
            delete_pressed: false,
            shift: false,
        }
    }

    /// Track the pointer the script's events imply (see [`SimDriver::idle_frame`]).
    fn track(&mut self, event: Option<Event>) {
        match event {
            Some(
                Event::HoverAt(pos)
                | Event::Clicked { pos }
                | Event::DoubleClicked { pos }
                | Event::Dragging { pos, .. },
            ) => self.pointer = Some(pos),
            Some(Event::DragStarted { pos }) => {
                self.pointer = Some(pos);
                self.dragging = true;
            }
            Some(Event::DragStopped { pos }) => {
                self.pointer = Some(pos);
                self.dragging = false;
            }
            None => {}
        }
    }
}

/// Apply the document-scoped half of `action` inside its own labelled
/// gesture, settling the tool where the arm says. Whatever needs app
/// machinery comes back for the caller to report.
fn dispatch(action: Action, target: SimTarget<'_>) -> Option<Box<Action>> {
    let SimTarget {
        repo,
        index,
        path,
        presentation,
        gesture,
        tool,
    } = target;
    *gesture = gesture::Gesture::open(
        crate::edit::describe::Label::verb(action.label()),
        Writability::Writable,
    );
    let outcome = {
        let mut drawing = gesture::drawing(repo, index, path, presentation, gesture);
        commands::apply_scripted(action, &mut drawing)
    };
    gesture::close(repo, index, path, presentation, gesture);
    match outcome {
        commands::ScriptedApply::Applied(settles_on) => {
            if let Some(next) = settles_on {
                *tool = next;
            }
            None
        }
        commands::ScriptedApply::NeedsApp(other) => Some(other),
    }
}

/// Dispatch a `command` step: resolve `name` against the frame's command
/// registry — availability follows the repo's selection and lock state,
/// exactly as the palette would offer it — and apply the resolved action.
/// Errors are console reports: an unavailable command leaves the document
/// unchanged, which the golden replay then flags.
fn run_command(name: &str, target: SimTarget<'_>) {
    let SimTarget {
        repo,
        index,
        path,
        presentation,
        gesture,
        tool,
    } = target;
    let action = {
        let history = commands::History {
            can_undo: repo.can_undo(),
            can_redo: repo.can_redo(),
        };
        let drawing = gesture::drawing(repo, index, path, presentation, gesture);
        let current_lock: crate::edit::naming::InterfaceLock = drawing.current_locked().into();
        let mut set = commands::CommandSet::available(&commands::CommandContext {
            tool,
            data: &drawing,
            history,
            current_lock,
            // A scripted session drives a scratch repo, which nothing can
            // hold a lock on, has no container to save into, and never
            // opens the time machine.
            writability: crate::doc::Writability::Writable,
            head: blockworx_doc::rev::Rev::ZERO,
            saving: crate::doc::Saving::Withheld,
            viewing: crate::doc::Viewing::Head,
        });
        set.take_by_name(name)
    };
    let Some(action) = action else {
        tracing::error!("command {name:?} is not available here");
        return;
    };
    if let Some(other) = dispatch(
        action,
        SimTarget {
            repo,
            index,
            path,
            presentation,
            gesture,
            tool,
        },
    ) {
        tracing::error!(
            "command {name:?} needs the app and cannot run in a script: {}",
            action_name(&other)
        );
    }
}

/// Sim frames fed per shown frame at most — enough for 2× speed on a 60 Hz
/// display with headroom, without spiraling after a hitch.
const MAX_FRAMES_PER_SHOW: u32 = 8;

/// Cap on the real time banked per shown frame, so a long stall doesn't
/// fast-forward the demo.
const HITCH_CAP: Duration = Duration::from_millis(100);

/// Playback rate: how much script time one second of real time buys.
#[derive(Clone, Copy, PartialEq, Debug)]
pub struct Speed(f32);

impl Speed {
    pub const HALF: Self = Self(0.5);
    pub const NORMAL: Self = Self(1.0);
    pub const DOUBLE: Self = Self(2.0);
}

impl std::fmt::Display for Speed {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

/// Real time banked into whole sim frames: the fixed-timestep clock every
/// scripted playback runs on.
#[derive(Default)]
pub struct SimClock {
    /// Sim frames fed so far — the cue clock.
    frames: u32,
    /// Real time (× speed) not yet consumed by whole sim frames.
    carry: Duration,
}

impl SimClock {
    /// Bank `dt` real time and return how many sim frames came due, capped so
    /// a hitch can't fast-forward the demo.
    pub fn begin_show(&mut self, dt: Duration, speed: Speed) -> u32 {
        self.carry += dt.min(HITCH_CAP).mul_f32(speed.0);
        // Integer division: a float ratio can round a hair *up* at an exact
        // multiple and claim a frame the carry can't pay for.
        let due = self.carry.as_nanos() / SIM_DT.as_nanos();
        let n = due.min(u128::from(MAX_FRAMES_PER_SHOW)) as u32;
        self.carry -= SIM_DT * n;
        n
    }

    /// One of the banked frames was actually fed.
    pub fn tick(&mut self) {
        self.frames += 1;
    }

    /// The cue/camera clock: sim frames fed so far, in script time.
    pub fn elapsed(&self) -> Duration {
        SIM_DT * self.frames
    }
}

pub(crate) fn action_name(action: &Action) -> &'static str {
    match action {
        Action::SwitchTool(_) => "SwitchTool",
        Action::Delete(_) => "Delete",
        Action::Copy(_) => "Copy",
        Action::CopyPins(_) => "CopyPins",
        Action::Cut(_) => "Cut",
        Action::CutPins(_) => "CutPins",
        Action::SetPinTags { .. } => "SetPinTags",
        Action::SetShapeTagHidden { .. } => "SetShapeTagHidden",
        Action::FlipShapePins(_) => "FlipShapePins",
        Action::FlipBlockVertical(_) => "FlipBlockVertical",
        Action::SetBlockLocked { .. } => "SetBlockLocked",
        Action::Paste(_) => "Paste",
        Action::ExpandBlock(_) => "ExpandBlock",
        Action::GoToPath(_) => "GoToPath",
        Action::Zoom(_) => "Zoom",
        Action::Camera(_) => "Camera",
        Action::SetRole { .. } => "SetRole",
        Action::SetPinsKind { .. } => "SetPinsKind",
        Action::OpenRolePicker { .. } => "OpenRolePicker",
        Action::OpenPinTypePicker { .. } => "OpenPinTypePicker",
        Action::GoUp => "GoUp",
        Action::NavSelect { .. } => "NavSelect",
        Action::PathBack => "PathBack",
        Action::PathForward => "PathForward",
        Action::Undo => "Undo",
        Action::Redo => "Redo",
        Action::Nudge { .. } => "Nudge",
        Action::ResetView => "ResetView",
        Action::Export { .. } => "Export",
        Action::ExportRev { .. } => "ExportRev",
        Action::Import => "Import",
        Action::Reroute(_) => "Reroute",
        Action::RerouteBlock(_) => "RerouteBlock",
        Action::ViewRev(_) => "ViewRev",
        Action::ViewHead => "ViewHead",
        Action::RestoreRev(_) => "RestoreRev",
        Action::TagRev { .. } => "TagRev",
        Action::OpenTutorial => "OpenTutorial",
        Action::TutorialLoadLevel(_) => "TutorialLoadLevel",
        Action::TutorialExit => "TutorialExit",
        Action::SaveProjection => "SaveProjection",
        // The File flow is app chrome: a script has no dialogs to drive.
        #[cfg(not(target_arch = "wasm32"))]
        Action::NewDocument => "NewDocument",
        #[cfg(not(target_arch = "wasm32"))]
        Action::PickFile(_) => "PickFile",
        #[cfg(not(target_arch = "wasm32"))]
        Action::OpenRecent(_) => "OpenRecent",
        #[cfg(not(target_arch = "wasm32"))]
        Action::RenameDocument(_) => "RenameDocument",
    }
}

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

    #[test]
    fn begin_show_caps_frames_and_conserves_carry() {
        let mut clock = SimClock::default();
        // A whole second owed is clamped to the hitch cap — 6 frames.
        assert_eq!(clock.begin_show(Duration::from_secs(1), Speed::NORMAL), 6);
        assert!(clock.carry < SIM_DT);
        // Banked carry beyond one show's budget is capped and conserved.
        clock.carry = Duration::from_millis(200);
        assert_eq!(
            clock.begin_show(Duration::ZERO, Speed::NORMAL),
            MAX_FRAMES_PER_SHOW
        );
        let banked = Duration::from_millis(200)
            .checked_sub(SIM_DT * MAX_FRAMES_PER_SHOW)
            .unwrap();
        assert_eq!(clock.carry, banked);
        // Half a sim frame owed: nothing due, carry keeps it.
        clock.carry = Duration::ZERO;
        assert_eq!(clock.begin_show(SIM_DT / 2, Speed::NORMAL), 0);
        assert_eq!(clock.carry, SIM_DT / 2);
        // The second half completes exactly one frame.
        assert_eq!(clock.begin_show(SIM_DT / 2, Speed::NORMAL), 1);
        assert!(clock.carry < SIM_DT);
    }

    /// 50 ms of real time is three sim frames at 1×, and the speed scales it
    /// before the hitch cap can bite.
    #[test]
    fn speed_scales_the_banked_time() {
        let show = Duration::from_millis(50);
        let due = |speed| SimClock::default().begin_show(show, speed);
        assert_eq!(due(Speed::NORMAL), 3);
        assert_eq!(due(Speed::HALF), 1);
        assert_eq!(due(Speed::DOUBLE), 6);
    }
}