blockworx/tutorial/

player.rs

//! The walkthrough player (spec §8.3): a floating panel that plays a
//! tutorial's log back as the animation the choreographer synthesizes for it.
//!
//! **It is a panel, not a mode.** The user's own document stays live and
//! editable behind it — there is no `Mode` enum any more and none returns,
//! nothing here reaches the open diagram's log, its undo stack, or its
//! selection, and closing the player leaves the session exactly where it was.
//! Like the toast it is transient, so it is not one of the shell's berths:
//! the frame's three persistent regions stay three. It is placed inside the room the chrome measured, so it lands
//! in a corner of the *canvas* rather than under the navigator.
//!
//! **Chapters are the primary navigation** (§8.3). The transport is
//! play/pause and chapter prev/next; the chapter list is a menu off the
//! title. There is a scrubber, and it is secondary — it says where in the
//! chapter the playhead is and can be dragged, but nothing hangs on it.
//!
//! **What is drawn is the document being changed, plus the change.** The
//! pane is a real canvas — its own view, the ordinary drawing pass over the
//! tutorial's document as it stood before the commit — with the timeline's
//! [`Frame`] laid over it in one guide role.
//! The subjects a track depicts are held back from the document pass, so the
//! wire being drawn and the block being moved are drawn once, by the
//! depiction, rather than twice.

use core::time::Duration;
use std::path::Path;

use blockworx_doc::document::{DocIndex, Document};
use blockworx_doc::id::EntityRef;
use blockworx_doc::rev::Rev;
use egui::{Pos2, Rect, Vec2, pos2, vec2};

use crate::canvas::view::{CanvasChrome, View};
use crate::choreography::{Frame, FrameTrack, FrameValue, TrackKind};
use crate::grid::GRID_SIZE;
use crate::path::{BlockPath, Scope};
use crate::shape::ShapeId;
use crate::shell::glass;
use crate::state::RenderMode;
use crate::theme::{Role, RoleStroke, Style, Theme};
use crate::tutorial::library::{Watched, clock};
use crate::tutorial::reader::Tutorial;
use crate::units::WorldPx;
use crate::widget::drawing::Drawing;

/// How big the panel stands. Two sizes and a toggle between them, which is
/// what §8.3's "floats over the canvas so users can follow along" and "the
/// library browses" together ask for: small enough to work beside, large
/// enough to watch.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum Size {
    #[default]
    Corner,
    Large,
}

impl Size {
    fn extent(self, room: Rect) -> Vec2 {
        let wanted = match self {
            Size::Corner => vec2(400.0, 300.0),
            Size::Large => vec2(760.0, 560.0),
        };
        vec2(
            wanted.x.min(room.width() - 2.0 * glass::MARGIN),
            wanted.y.min(room.height() - 2.0 * glass::MARGIN),
        )
    }

    fn toggled(self) -> Self {
        match self {
            Size::Corner => Size::Large,
            Size::Large => Size::Corner,
        }
    }

    fn hover(self) -> &'static str {
        match self {
            Size::Corner => "Expand",
            Size::Large => "Shrink",
        }
    }
}

/// Whether the playhead is moving.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Running {
    Playing,
    Paused,
    /// The last rev has played out. Nothing advances, and nothing asks for
    /// another frame — a finished player must settle.
    Ended,
}

/// What one player frame reports.
pub struct Played {
    /// The chapter the playhead has reached, for the watched list.
    pub reached: Option<usize>,
    /// Whether the viewer closed it.
    pub closed: bool,
}

/// A walkthrough, open.
pub struct Player {
    tutorial: Tutorial,
    /// The rev being played, and everything derived from it. Re-derived only
    /// when the step changes — a fold and a synthesis per step, not per
    /// frame.
    step: Step,
    elapsed: Duration,
    running: Running,
    size: Size,
    /// The pane's own camera. A tutorial frames itself from the timeline's
    /// camera plan, and the viewer may pan and zoom inside the pane like any
    /// other canvas.
    view: View,
    presentation: crate::presentation::Presentation,
    index: DocIndex,
    /// What was last said, which stands until something else is said:
    /// narration speaks *over* the step it precedes
    /// (`docs/tutorial-levels.md`), and a note is an empty commit that would
    /// otherwise be gone in one frame.
    caption: String,
    /// The camera the step's timeline planned, waiting for a pane with a
    /// viewport to be measured against.
    owed_fit: Option<Rect>,
    /// Whether the pane has ever been framed. The first step of a converted
    /// container is a note, which plans no camera, so something has to.
    framed: bool,
}

/// One rev's worth of playback, derived once when the step changes.
struct Step {
    at: Rev,
    /// The document the commit is being made to.
    before: Document,
    timeline: crate::choreography::Timeline,
    /// How long this rev holds — the substrate's number
    /// ([`Tutorial::span`]), so the player spends exactly what the library
    /// card advertised.
    span: Duration,
    /// Where the pane looks while it plays, in world pixels.
    region: Option<Rect>,
    path: BlockPath,
}

impl Player {
    /// Open `root` at `at`, or at the beginning.
    ///
    /// # Errors
    /// As [`Tutorial::open`]: there is no container there, or its log cannot
    /// be read.
    pub fn open(
        root: &Path,
        at: Option<Rev>,
    ) -> Result<Self, crate::store::container::ContainerError> {
        let tutorial = Tutorial::open(root)?;
        let first = tutorial.revs().next().unwrap_or(Rev::ZERO.next());
        let mut player = Player {
            step: Step::at(&tutorial, at.unwrap_or(first)),
            tutorial,
            elapsed: Duration::ZERO,
            running: Running::Playing,
            size: Size::default(),
            view: View::new(),
            presentation: crate::presentation::Presentation::default(),
            index: DocIndex::default(),
            caption: String::new(),
            owed_fit: None,
            framed: false,
        };
        player.arrive();
        Ok(player)
    }

    pub fn title(&self) -> &str {
        self.tutorial.name()
    }

    pub fn running(&self) -> Running {
        self.running
    }

    /// The tools this walkthrough is about, as its own log says (D18's tags,
    /// `docs/tutorial-levels.md`). The tool cluster rings them while it
    /// plays, so a viewer can see which button the hand is reaching for.
    pub fn teaches(&self) -> Vec<crate::tools::names::ToolName> {
        self.tutorial.teaches()
    }

    /// Which chapter the playhead stands in.
    pub fn chapter(&self) -> Option<usize> {
        self.tutorial
            .chapters()
            .iter()
            .rposition(|chapter| chapter.at <= self.step.at)
    }

    /// Advance the clock by `dt`, stepping to the next rev whenever this one
    /// has played out. The module never reads a clock (C4): the caller's
    /// frame supplies it, which is what lets a test drive a whole tutorial
    /// deterministically.
    pub fn advance(&mut self, dt: Duration) {
        if self.running != Running::Playing {
            return;
        }
        self.elapsed = self.elapsed.saturating_add(dt);
        // A while, not an if: a step that depicts nothing has zero span, so
        // one long frame may cross several of them.
        while self.running == Running::Playing && self.elapsed >= self.step.span {
            self.elapsed -= self.step.span;
            self.next_rev();
        }
    }

    /// Jump to the chapter `nth`, which is what a chapter pick means
    /// everywhere: the library's rows, the palette's, and the player's own
    /// list and stepper.
    pub fn jump_to_chapter(&mut self, nth: usize) {
        let Some(chapter) = self.tutorial.chapters().get(nth) else {
            return;
        };
        self.seek(chapter.at);
    }

    /// Play or pause. A player that has ended starts again from the top,
    /// which is what pressing play on a finished thing means.
    pub fn toggle_play(&mut self) {
        self.running = match self.running {
            Running::Playing => Running::Paused,
            Running::Paused => Running::Playing,
            Running::Ended => {
                let first = self.tutorial.revs().next().unwrap_or(Rev::ZERO.next());
                self.seek(first);
                Running::Playing
            }
        };
    }

    pub fn toggle_size(&mut self) {
        self.size = self.size.toggled();
    }

    pub fn size(&self) -> Size {
        self.size
    }

    /// What is said right now — the note standing at or before the playhead.
    pub fn caption(&self) -> &str {
        &self.caption
    }

    fn seek(&mut self, to: Rev) {
        self.step = Step::at(&self.tutorial, to);
        self.elapsed = Duration::ZERO;
        self.running = Running::Playing;
        self.caption.clear();
        self.arrive();
    }

    /// Move onto the next rev, or end.
    fn next_rev(&mut self) {
        let next = self.step.at.next();
        if self.tutorial.timeline(next).is_none() {
            self.running = Running::Ended;
            self.elapsed = self.step.span;
            return;
        }
        self.step = Step::at(&self.tutorial, next);
        self.arrive();
    }

    /// What arriving at a step does besides fold it: take what is said there
    /// as the caption, and owe the pane the camera the timeline planned.
    ///
    /// Owed rather than applied, because a framing needs a viewport to be
    /// measured against and the pane has none until it has drawn once.
    fn arrive(&mut self) {
        if let Some(note) = self.tutorial.narration(self.step.at) {
            self.caption = note.text.clone();
        }
        self.owed_fit = self.step.region;
    }
}

impl Step {
    fn at(tutorial: &Tutorial, rev: Rev) -> Self {
        let timeline = tutorial.timeline(rev).unwrap_or_else(empty_timeline);
        let before = tutorial.document(rev).unwrap_or_default();
        let plan = timeline.camera();
        Step {
            at: rev,
            span: tutorial.span(rev),
            region: plan.map(|plan| crate::edit::lower::px_rect(plan.region)),
            path: plan.map_or_else(
                || BlockPath::opening(&before),
                |plan| path_of(&before, plan.scope),
            ),
            timeline,
            before,
        }
    }
}

/// The path whose scope is `scope`, for the document `doc`.
fn path_of(doc: &Document, scope: Scope) -> BlockPath {
    match scope {
        Scope::Root => BlockPath::empty(),
        Scope::Block(id) => match BlockPath::to_parent_of(doc, id) {
            Some(mut path) => {
                path.push(id);
                path
            }
            None => BlockPath::opening(doc),
        },
    }
}

/// A timeline for a rev the log does not hold — reached only by a container
/// with no commits at all, which nothing ships.
fn empty_timeline() -> crate::choreography::Timeline {
    crate::choreography::synthesize(
        &DocIndex::default().view(&Document::default()),
        &blockworx_doc::commit::Commit::new(String::new(), Vec::new()),
    )
}

/// Draw the player in a corner of the room the chrome left, and report what
/// the viewer did with it.
pub fn player(
    ctx: &egui::Context,
    player: &mut Player,
    theme: &Theme,
    watched: &Watched,
    room: Rect,
) -> Played {
    // The clock the playback runs on: egui's own smoothed frame time, which
    // is the only place in this module a duration comes from outside.
    let dt = Duration::from_secs_f32(ctx.input(|i| i.stable_dt).clamp(0.0, MAX_STEP));
    player.advance(dt);
    // A paused or ended player owes nothing — which is what lets an idle
    // frame with one on screen still settle. One framing still owed is one
    // more frame, and then it is owed no more.
    if player.running() == Running::Playing || player.owed_fit.is_some() {
        ctx.request_repaint();
    }
    let extent = player.size.extent(room);
    let at = room.right_bottom() - extent - Vec2::splat(glass::MARGIN);
    let mut played = Played {
        reached: player.chapter(),
        closed: false,
    };
    egui::Area::new(id())
        .fixed_pos(at)
        .order(egui::Order::Middle)
        .movable(false)
        .fade_in(false)
        .constrain(false)
        .show(ctx, |ui| {
            ui.set_width(extent.x);
            glass::shell(
                ui,
                glass::Shape::Panel,
                glass::Elevation::Floating,
                glass::Tint::None,
            )
            .show(ui, |ui| {
                glass::type_scale(ui, glass::Shape::Panel);
                played.closed = head(ui, player, watched);
                pane(ui, player, theme, extent);
                caption(ui, player);
                transport(ui, player);
            });
        });
    played
}

/// The title row: what is playing, the chapter list, the size toggle, and
/// the way out.
fn head(ui: &mut egui::Ui, player: &mut Player, watched: &Watched) -> bool {
    let mut closed = false;
    ui.horizontal(|ui| {
        let chapters = player.tutorial.chapters().to_vec();
        let standing = player.chapter();
        // §8.3's primary affordance, as a cascading submenu rather than a
        // dialog (house style): the whole list, always, one press from the
        // title.
        egui::containers::menu::MenuButton::new(
            egui::RichText::new(player.title())
                .color(glass::full_ink(ui.visuals()))
                .strong(),
        )
        .ui(ui, |ui| {
            ui.style_mut().wrap_mode = Some(egui::TextWrapMode::Extend);
            for (nth, chapter) in chapters.iter().enumerate() {
                let here = if Some(nth) == standing {
                    "\u{25b8} "
                } else {
                    ""
                };
                if ui
                    .button(format!(
                        "{here}{}  {}",
                        chapter.title,
                        clock(chapter.duration),
                    ))
                    .clicked()
                {
                    player.jump_to_chapter(nth);
                }
            }
        });
        ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
            if ui.button("\u{2715}").on_hover_text("Close").clicked() {
                closed = true;
            }
            if ui
                .button(match player.size() {
                    Size::Corner => "\u{2921}",
                    Size::Large => "\u{2922}",
                })
                .on_hover_text(player.size().hover())
                .clicked()
            {
                player.toggle_size();
            }
        });
    });
    let _ = watched;
    closed
}

/// The video: the document the commit is being made to, with the commit's
/// depiction over it.
fn pane(ui: &mut egui::Ui, player: &mut Player, theme: &Theme, extent: Vec2) {
    let height = (extent.y - CHROME_HEIGHT).max(MIN_PANE);
    let (rect, _) =
        ui.allocate_exact_size(vec2(ui.available_width(), height), egui::Sense::hover());
    let mut child = ui.new_child(egui::UiBuilder::new().max_rect(rect));
    child.set_clip_rect(rect.intersect(ui.clip_rect()));
    let palette = theme.palette().clone();
    let chrome = CanvasChrome {
        background: palette.resolve(theme.swatch(Role::CanvasBackground)),
        grid: palette.resolve(theme.swatch(Role::GridLine)),
    };
    let frame = player
        .step
        .timeline
        .at(player.elapsed.min(player.step.span));
    let Player {
        step,
        view,
        presentation,
        index,
        owed_fit,
        framed,
        ..
    } = player;
    // The framing the step owed, now that there is a pane to measure it
    // against. Instant, not eased: a step change is a cut, and a camera
    // easing between two of them would still be travelling when the next
    // one arrived.
    if view.viewport().is_positive()
        && let Some(region) = owed_fit.take()
    {
        view.fit_to_rect_instant(region);
    }
    let mut gesture = crate::gesture::Gesture::idle();
    let mut drawing = Drawing::new(
        index.view(&step.before),
        &step.path,
        presentation,
        &mut gesture,
    );
    let mut canvas = view.begin(&mut child, palette, chrome);
    // A rev whose timeline plans no camera — a note, or one of the rows the
    // 7·2/7·3 seams left region-less — has nothing to frame on, so the first
    // one is framed on the scene instead. Measured through the fitting
    // painter and *owed* rather than eased: the pane must be still while a
    // step plays.
    if !*framed {
        let mut scene = None;
        canvas.fit_to(|painter| {
            scene = drawing.content_bounds(&Style::new(theme, painter));
            None
        });
        if let Some(scene) = scene.filter(|rect| rect.is_positive()) {
            *owed_fit = Some(scene);
            *framed = true;
        }
    }
    canvas.paint(|_, painter| {
        let mut style = Style::new(theme, painter);
        drawing.refresh_text_extents(&style);
        // The subjects the timeline is depicting are held back, so a block
        // being moved is drawn once — travelling — rather than twice.
        let depicted: Vec<ShapeId> = frame
            .tracks
            .iter()
            .filter(|track| track.kind != TrackKind::Appear)
            .filter_map(|track| shape_of(track.subject))
            .collect();
        crate::widget::DrawingPasses::new(&drawing)
            .shape_mode(move |id| {
                if depicted.contains(&id) {
                    RenderMode::Hidden
                } else {
                    RenderMode::Normal
                }
            })
            .draw(&mut style);
        depict(&frame, &mut style);
    });
}

/// The [`Frame`] itself: every track at this instant, in the one guide role,
/// plus the ghost hand.
///
/// A value the painter cannot place on its own — an arc length along a wire,
/// an offset along a shape's side, a discrete register — draws nothing here:
/// those are the seams `docs/choreographer-playbook.md` 7·2/7·3 left open,
/// and what the viewer sees instead is the document itself once the commit
/// lands one step later.
fn depict(frame: &Frame, style: &mut Style<'_, impl crate::canvas::Renderer>) {
    for track in &frame.tracks {
        let fade = match track.kind {
            TrackKind::Vanish => 1.0 - f32::from(track.progress),
            TrackKind::Appear => f32::from(track.progress).max(ARRIVING),
            _ => 1.0,
        };
        style.with_opacity(fade, |style| mark(track, style));
    }
    if let Some(ghost) = &frame.ghost {
        let at = cells(ghost.at);
        style.circle(
            at,
            WorldPx::new(HAND),
            Role::WalkthroughGhost,
            RoleStroke::from((MARK_WIDTH, Role::WalkthroughMark)),
        );
    }
}

/// One track's value, drawn.
fn mark(track: &FrameTrack, style: &mut Style<'_, impl crate::canvas::Renderer>) {
    let stroke = RoleStroke::from((MARK_WIDTH, Role::WalkthroughMark));
    match &track.value {
        FrameValue::Rect { min, max } | FrameValue::Artwork { min, max } => {
            let scale = if matches!(track.value, FrameValue::Artwork { .. }) {
                1.0
            } else {
                GRID_SIZE
            };
            style.rect(
                Rect::from_min_max(
                    pos2(min[0] * scale, min[1] * scale),
                    pos2(max[0] * scale, max[1] * scale),
                ),
                WorldPx::ZERO,
                Role::Transparent,
                stroke,
            );
        }
        FrameValue::Point { at } => {
            style.circle(cells(*at), WorldPx::new(DOT), Role::WalkthroughMark, stroke);
        }
        FrameValue::Path(points) if points.len() > 1 => {
            style.line(points.iter().copied().map(cells).collect(), stroke);
        }
        FrameValue::Text { of, to, .. } => {
            if let Some(at) = written_at(of.at) {
                style.text(
                    at,
                    egui::Align2::LEFT_BOTTOM,
                    to.as_ref(),
                    &style.theme().title_font.clone(),
                    Role::WalkthroughMark,
                );
            }
        }
        FrameValue::Path(_)
        | FrameValue::Along { .. }
        | FrameValue::Label { .. }
        | FrameValue::Flag { .. }
        | FrameValue::Settled => {}
    }
}

/// Where a written value shows, as far as the document can say. A wire's own
/// registers and the sheet's title block have no world position at all, so
/// they are not drawn over the canvas (the 7·4 seam).
fn written_at(site: crate::choreography::Site) -> Option<Pos2> {
    match site {
        crate::choreography::Site::Shape(rect) => {
            Some(crate::edit::lower::px_rect(rect).left_top())
        }
        crate::choreography::Site::Anchor(at) => Some(crate::edit::lower::px_point(at)),
        crate::choreography::Site::Wire | crate::choreography::Site::Sheet => None,
    }
}

/// A frame value's fractional grid cells, in world pixels.
fn cells(at: [f32; 2]) -> Pos2 {
    pos2(at[0] * GRID_SIZE, at[1] * GRID_SIZE)
}

/// The shape a track's subject is, where it is one the document render draws.
/// A pin is left alone: it is drawn on its owner's boundary, and hiding the
/// owner to hide a pin would take the whole block off the pane.
fn shape_of(subject: EntityRef) -> Option<ShapeId> {
    match subject {
        EntityRef::Block(id) => Some(ShapeId::Rect(id)),
        EntityRef::Text(id) => Some(ShapeId::Text(id)),
        EntityRef::Area(id) => Some(ShapeId::Area(id)),
        EntityRef::Image(id) => Some(ShapeId::Image(id)),
        EntityRef::Document
        | EntityRef::Pin(_)
        | EntityRef::Route(_)
        | EntityRef::RouteLabel(_)
        | EntityRef::Asset(_) => None,
    }
}

/// What is being said, under the pane.
fn caption(ui: &mut egui::Ui, player: &Player) {
    ui.add_space(CAPTION_AIR);
    ui.label(
        egui::RichText::new(if player.caption().is_empty() {
            " "
        } else {
            player.caption()
        })
        .color(glass::full_ink(ui.visuals())),
    );
}

/// Play/pause, chapter prev/next, and the secondary scrubber.
fn transport(ui: &mut egui::Ui, player: &mut Player) {
    ui.horizontal(|ui| {
        if ui
            .button(match player.running() {
                Running::Playing => "\u{23f8}",
                Running::Paused | Running::Ended => "\u{25b6}",
            })
            .on_hover_text("Play or pause")
            .clicked()
        {
            player.toggle_play();
        }
        let standing = player.chapter();
        let last = player.tutorial.chapters().len().saturating_sub(1);
        if ui
            .add_enabled(
                standing.is_some_and(|nth| nth > 0),
                egui::Button::new("\u{23ee}"),
            )
            .on_hover_text("Previous chapter")
            .clicked()
            && let Some(nth) = standing
        {
            player.jump_to_chapter(nth - 1);
        }
        if ui
            .add_enabled(
                standing.is_some_and(|nth| nth < last),
                egui::Button::new("\u{23ed}"),
            )
            .on_hover_text("Next chapter")
            .clicked()
            && let Some(nth) = standing
        {
            player.jump_to_chapter(nth + 1);
        }
        if let Some(nth) = standing
            && let Some(chapter) = player.tutorial.chapters().get(nth)
        {
            ui.label(
                egui::RichText::new(format!("{}  {}", chapter.title, clock(chapter.duration)))
                    .small()
                    .weak(),
            );
        }
    });
}

fn id() -> egui::Id {
    egui::Id::new("tutorial_player")
}

/// How much of a stalled frame the clock will believe. A tab that was in the
/// background for a minute must not skip a whole tutorial on the frame it
/// comes back.
const MAX_STEP: f32 = 0.25;

/// How much of itself an arriving depiction keeps at the instant it begins,
/// so a shape growing out of its own corner is visible before it has any
/// size to speak of.
const ARRIVING: f32 = 0.25;

/// The room the head, the caption and the transport take out of the panel's
/// height, leaving the rest to the pane.
const CHROME_HEIGHT: f32 = 118.0;
const MIN_PANE: f32 = 120.0;
const CAPTION_AIR: f32 = 4.0;

/// World-pixel weights for the depiction: a stroke a little heavier than a
/// block outline, a dot at a bare anchor, and the ghost hand.
const MARK_WIDTH: f32 = 2.0;
const DOT: f32 = 4.0;
const HAND: f32 = 7.0;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::shell::tests::screen;
    use crate::tools::painted::Chrome;
    use crate::tutorial::library::Library;

    /// A player over a shipped walkthrough, driven through real egui frames
    /// with a clock the test supplies (C4).
    struct Watching {
        chrome: Chrome,
        player: Player,
        theme: Theme,
        watched: Watched,
        closed: bool,
        reached: Vec<usize>,
    }

    impl Watching {
        fn of(id: &str) -> Self {
            let library = Library::shipped();
            let lesson = library
                .lessons()
                .iter()
                .find(|lesson| lesson.title == id)
                .unwrap_or_else(|| panic!("{id} is not in the library"));
            let mut watching = Watching {
                chrome: Chrome::new(screen()),
                player: Player::open(&lesson.root, None).expect("the walkthrough opens"),
                theme: Theme::default(),
                watched: Watched::default(),
                closed: false,
                reached: Vec::new(),
            };
            watching.frame();
            watching
        }

        /// One drawn frame, with no time passing — so a test's clock is the
        /// only clock.
        fn frame(&mut self) {
            let Watching {
                chrome,
                player,
                theme,
                watched,
                closed,
                reached,
            } = self;
            chrome.settle(|ui| {
                let played = super::player(ui.ctx(), player, theme, watched, screen());
                *closed |= played.closed;
                if let Some(nth) = played.reached
                    && reached.last() != Some(&nth)
                {
                    reached.push(nth);
                }
            });
        }

        /// `millis` of playback, in frames of `STEP` — a real clock's
        /// granularity, so nothing depends on one long jump.
        fn watch(&mut self, millis: u64) {
            const STEP: u64 = 40;
            for _ in 0..millis.div_ceil(STEP) {
                self.player.advance(Duration::from_millis(STEP));
                self.frame();
            }
        }
    }

    /// The exit criterion: every shipped walkthrough plays start to finish
    /// through the real player, drawn into real frames — the playhead
    /// crosses every rev, every chapter is stood in, and it ends.
    #[test]
    fn every_shipped_walkthrough_plays_to_the_end() {
        for id in ["first-block", "first-route", "resize-move"] {
            let mut watching = Watching::of(id);
            let whole: Duration = watching
                .player
                .tutorial
                .revs()
                .fold(Duration::ZERO, |sum, rev| {
                    sum + watching.player.tutorial.span(rev)
                });
            assert!(!whole.is_zero(), "precondition: {id} has something to play");
            let chapters = watching.player.tutorial.chapters().len();
            watching.watch(whole.as_millis() as u64 + 200);
            assert_eq!(
                watching.player.running(),
                Running::Ended,
                "{id} never reached its end",
            );
            assert_eq!(
                watching.reached,
                (0..chapters).collect::<Vec<_>>(),
                "{id} did not stand in every chapter in order",
            );
        }
    }

    /// Narration reaches the screen at the rev it was written at, and stands
    /// there: a note is an empty commit, so a caption that died with its own
    /// step would never be read.
    #[test]
    fn what_is_said_at_a_rev_reaches_the_screen_and_stands() {
        let mut watching = Watching::of("first-block");
        let said = watching.player.caption().to_owned();
        assert!(
            said.contains("Your first block"),
            "the opening chapter is not said: {said:?}",
        );
        assert!(
            watching.chrome.says(&said),
            "the caption is not painted: {:?}",
            watching.chrome.texts(),
        );

        watching.watch(3_000);
        let later = watching.player.caption().to_owned();
        assert_ne!(later, said, "the caption never moved on");
        assert!(!later.is_empty(), "the player fell silent");
        assert!(
            watching.chrome.says(&later),
            "the later caption is not painted: {:?}",
            watching.chrome.texts(),
        );
    }

    /// The depiction reaches a painter: a timeline sampled part way through
    /// its own window draws marks, in the guide role and nowhere else.
    ///
    /// Through a real [`Renderer`](crate::canvas::Renderer) backend — the SVG
    /// one, which is text and can be read — rather than through the on-screen
    /// painter, whose output a test can only count.
    #[test]
    fn a_timeline_in_flight_is_drawn_in_the_guide_role() {
        let watching = Watching::of("first-block");
        let theme = Theme::default();
        let ink = theme.resolve(Role::WalkthroughMark);
        let drawn = watching
            .player
            .tutorial
            .revs()
            .filter_map(|rev| watching.player.tutorial.timeline(rev))
            .filter(|timeline| !timeline.duration().is_zero())
            .map(|timeline| {
                let frame = timeline.at(timeline.duration() / 2);
                assert!(
                    !frame.tracks.is_empty(),
                    "precondition: a depicted commit has tracks",
                );
                let mut svg = crate::canvas::SvgRenderer::new(
                    theme.palette().clone(),
                    crate::preferences::FontChoice::Basic,
                );
                {
                    let mut style = Style::new(&theme, &mut svg);
                    super::depict(&frame, &mut style);
                }
                svg.finish().0
            })
            .collect::<Vec<_>>();
        assert!(!drawn.is_empty(), "precondition: something is depicted");
        let wanted = format!("#{:02x}{:02x}{:02x}", ink.r(), ink.g(), ink.b());
        assert!(
            drawn.iter().any(|svg| svg.contains(&wanted)),
            "no depiction reached the painter in the guide role {wanted}",
        );
    }

    /// §8.3's primary affordance: a chapter jump moves the playhead there,
    /// forwards or back.
    #[test]
    fn a_chapter_jump_moves_the_playhead_to_it() {
        let mut watching = Watching::of("first-route");
        let chapters = watching.player.tutorial.chapters().to_vec();
        assert!(
            chapters.len() > 2,
            "precondition: there are chapters to jump between",
        );
        watching.player.jump_to_chapter(2);
        watching.frame();
        assert_eq!(watching.player.chapter(), Some(2));
        assert_eq!(watching.player.step.at, chapters[2].at);

        watching.player.jump_to_chapter(0);
        watching.frame();
        assert_eq!(
            watching.player.chapter(),
            Some(0),
            "a jump backwards did not take",
        );
    }

    /// The player is a panel, not a mode: nothing it does reaches a
    /// document, and a paused one costs no frames.
    #[test]
    fn a_paused_player_settles() {
        let library = Library::shipped();
        let lesson = &library.lessons()[0];
        let mut player = Player::open(&lesson.root, None).expect("the walkthrough opens");
        player.toggle_play();
        assert_eq!(player.running(), Running::Paused);
        let theme = Theme::default();
        let watched = Watched::default();
        let settle = crate::tools::settle::probe(60, |ui| {
            super::player(ui.ctx(), &mut player, &theme, &watched, screen());
        });
        crate::tools::settle::assert_settles(&settle, 50);
    }

    /// The expand toggle, both ways, and that the panel really changes size
    /// with it.
    #[test]
    fn the_expand_toggle_changes_the_panel_between_two_sizes() {
        let room = screen();
        let corner = Size::Corner.extent(room);
        let large = Size::Large.extent(room);
        assert!(
            large.x > corner.x && large.y > corner.y,
            "the two sizes are the same size: {corner:?} and {large:?}",
        );

        let mut watching = Watching::of("first-block");
        assert_eq!(watching.player.size(), Size::Corner);
        let at = watching
            .chrome
            .rect("\u{2921}")
            .expect("the expand toggle never drew")
            .center();
        let Watching {
            chrome,
            player,
            theme,
            watched,
            ..
        } = &mut watching;
        chrome.click_at(at, |ui| {
            super::player(ui.ctx(), player, theme, watched, screen());
        });
        assert_eq!(player.size(), Size::Large, "the toggle did not expand it");
        player.toggle_size();
        assert_eq!(player.size(), Size::Corner);
    }
}