shuyi_platform/

headless.rs

//! [`HeadlessPlatform`]: a backend with no window, no clock, no heap
//! counter and no memory tags (unless a test hands it them) and no sound
//! card. It plays scripted input and system events, records the frames
//! presented to it, keeps its storage in memory, and stands in for the
//! music player ([`Speaker`]), so a screen that keeps time with the music
//! is tested too.
//!
//! The test Harness runs games on it, through the same
//! [`App::frame`](crate::App::frame) the devices do. It is also the
//! smallest complete backend, for anyone writing one
//! (`docs/platform-backends.md`).

use crate::alloc_prelude::*;
use alloc::collections::{BTreeMap, VecDeque};
use alloc::vec;

#[cfg(feature = "std")]
use shuyi_assets::bundle::Layer;
use shuyi_ui::audio::{MusicCommand, SharedSamples, SoundId};
use shuyi_ui::frame::Rgb;
use shuyi_ui::frame::glyph_buffer::GlyphBuffer;
use shuyi_ui::frame_cap::FrameCap;
use shuyi_ui::perf::{
    HeapCounts, HeapSnapshot, MemoryReading, MemoryScopes, PerfClock, TagClass, TagRow,
};
use shuyi_ui::storage::{MemoryStorage, Storage};
use shuyi_ui::{PlatformFacts, RawInputEvent};

use crate::app::Card;
use crate::audio::{Audio, AudioFrame, SoundRequest};
use crate::platform::{DisplayInfo, Frame, Millis, Platform, Show, SystemEvent};
use crate::session::{FrameRecord, KeyboardFrame, SessionRecord};
use crate::text_input::{TextAnswer, TextAsk, TextInput};

/// A frame as the headless backend keeps it.
#[derive(Debug, Clone, PartialEq)]
pub enum Presented {
    /// The loading card.
    Card(Card),
    /// Why the game couldn't start.
    Errors(String),
    /// The game's console.
    Game {
        /// Its cells and pictures.
        buffer: GlyphBuffer,
        /// The colour behind it.
        background: Rgb,
        /// Whether it asked to fill the screen.
        fullscreen: bool,
    },
}

impl Presented {
    /// The game's console, if this frame shows it.
    pub fn buffer(&self) -> Option<&GlyphBuffer> {
        match self {
            Self::Game { buffer, .. } => Some(buffer),
            Self::Card(_) | Self::Errors(_) => None,
        }
    }

    /// The frame as it was presented, kept: `old`'s buffer is reused when
    /// both show the game.
    fn keep(old: &mut Option<Self>, frame: &Frame<'_>) {
        match (old.as_mut(), frame.show) {
            (
                Some(Self::Game {
                    buffer,
                    background,
                    fullscreen,
                }),
                Show::Game {
                    buffer: new,
                    background: new_background,
                    ..
                },
            ) => {
                if buffer != new {
                    buffer.clone_from(new);
                }
                *background = new_background;
                *fullscreen = frame.fullscreen;
            }
            (
                _,
                Show::Game {
                    buffer, background, ..
                },
            ) => {
                *old = Some(Self::Game {
                    buffer: buffer.clone(),
                    background,
                    fullscreen: frame.fullscreen,
                });
            }
            (_, Show::Card(card)) => *old = Some(Self::Card(card.clone())),
            (_, Show::Errors(errors)) => *old = Some(Self::Errors(errors.to_owned())),
        }
    }
}

/// A sound started with a handle that the [`Speaker`] holds as playing.
/// Only the `Speaker` builds one (ADR-0039).
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct PlayingSound {
    /// Its handle.
    pub id: SoundId,
    /// Its sound cue.
    pub cue: String,
    /// Whether [`SoundRequest::PauseSounds`] paused it.
    pub paused: bool,
}

/// A play of a sound the game added at run time, as the [`Speaker`] heard
/// it: the samples it played. Only the `Speaker` builds one (ADR-0039).
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct AddedPlay {
    /// The sound cue.
    pub cue: String,
    /// The samples it played.
    pub samples: SharedSamples,
    /// The volume asked for, 0–1: a multiplier on the sound's own, full.
    pub volume: f32,
    /// The handle it was started with, if it was.
    pub id: Option<SoundId>,
}

/// The headless backend's sound device: it records what the last frame
/// played, works out which music "sounds" from the music commands and the
/// clock, and keeps the sounds started with a handle until they stop (one
/// that plays once too: it knows no lengths). Like `shuyi-app`, it mutes
/// rather than pauses: while [`suspended`](Self::suspended) its music
/// clock runs on. It keeps the sounds the game added at run time, and
/// hears every play of them ([`added_plays`](Self::added_plays)). A voice
/// clip sounds from its request until it is stopped or replaced, or until
/// the length a test gave clips has passed
/// ([`set_voice_length`](Self::set_voice_length)).
#[derive(Debug, Clone, Default)]
pub struct Speaker {
    /// Seconds a track takes to load: it sounds that long after its
    /// `Start`.
    load_delay: f64,
    /// Whether no track ever sounds (the music files are missing).
    silent: bool,
    /// The track started last, and when.
    started: Option<(String, Millis)>,
    /// How long every voice clip lasts, in seconds; `None` until it is
    /// stopped.
    voice_length: Option<f64>,
    /// The voice clip asked for last and not stopped, and when.
    voice: Option<(String, Millis)>,
    /// The last frame's sound and voice requests.
    requests: Vec<SoundRequest>,
    /// The last frame's music commands.
    music: Vec<MusicCommand>,
    /// The last frame's volumes: music, sound and voice. Full until told.
    volumes: Option<(f32, f32, f32)>,
    /// Whether everything was stopped (the game quit).
    stopped: bool,
    /// The sounds started with a handle and not stopped, in id order.
    playing: Vec<PlayingSound>,
    /// Whether the system suspended the game ([`Audio::suspend`]).
    suspended: bool,
    /// What a session record says is sounding, while one plays: the
    /// answer to `music_playing` in place of the speaker's own.
    recorded: Option<RecordedMusic>,
    /// The sounds added and not removed, by cue.
    added: BTreeMap<String, SharedSamples>,
    /// Every play of a sound added, in order.
    added_plays: Vec<AddedPlay>,
}

/// What a session record says is sounding.
#[derive(Debug, Clone, Default)]
struct RecordedMusic {
    /// The cue of the track, written only when it changes.
    track: String,
    /// Its position this frame; `None` in silence.
    position: Option<f64>,
    /// The file of the voice clip sounding, written only when it changes;
    /// empty for none.
    voice: String,
}

impl Speaker {
    /// Makes music take `seconds` to load: a track sounds that long after
    /// the game starts it (at once by default). Negative or NaN counts as
    /// 0.
    pub fn set_load_delay(&mut self, seconds: f64) {
        self.load_delay = seconds.max(0.0);
    }

    /// Makes every voice clip last `seconds`: it stops sounding that long
    /// after it was asked for. Until this is called a clip sounds until it
    /// is stopped or replaced. Negative or NaN counts as 0.
    pub fn set_voice_length(&mut self, seconds: f64) {
        self.voice_length = Some(seconds.max(0.0));
    }

    /// Makes no music ever sound, as when the music files are missing.
    pub fn set_silent(&mut self) {
        self.silent = true;
    }

    /// The sound and voice requests of the last frame that played any
    /// audio.
    pub fn requests(&self) -> &[SoundRequest] {
        &self.requests
    }

    /// The music commands of the last frame that played audio.
    pub fn music(&self) -> &[MusicCommand] {
        &self.music
    }

    /// The music, sound and voice volumes the last frame played at, 0–1;
    /// full before any.
    pub fn volumes(&self) -> (f32, f32, f32) {
        self.volumes.unwrap_or((1.0, 1.0, 1.0))
    }

    /// Whether the game stopped all its audio (it quit).
    pub fn stopped(&self) -> bool {
        self.stopped
    }

    /// The sounds started with a handle and not yet stopped, in id order.
    pub fn sounds_playing(&self) -> &[PlayingSound] {
        &self.playing
    }

    /// Whether the audio is held because the system suspended the game.
    pub fn suspended(&self) -> bool {
        self.suspended
    }

    /// The sounds the game added at run time and hasn't removed, by cue.
    pub fn added_sounds(&self) -> &BTreeMap<String, SharedSamples> {
        &self.added
    }

    /// Every play and start of a sound the game added, in order, since the
    /// speaker was made: what each played.
    pub fn added_plays(&self) -> &[AddedPlay] {
        &self.added_plays
    }

    /// Hears a play of `cue`, if it is a sound added.
    fn hear_added(&mut self, cue: &str, volume: f32, id: Option<SoundId>) {
        if let Some(samples) = self.added.get(cue) {
            self.added_plays.push(AddedPlay {
                cue: cue.to_owned(),
                samples: samples.clone(),
                volume,
                id,
            });
        }
    }

    /// One frame of a session record: the track if it changed, its
    /// position, and the voice clip if it changed.
    fn play_recorded(&mut self, frame: &FrameRecord) {
        let recorded = self.recorded.get_or_insert_default();
        if let Some(track) = &frame.track {
            track.clone_into(&mut recorded.track);
        }
        recorded.position = frame.music;
        if let Some(voice) = &frame.voice {
            voice.clone_into(&mut recorded.voice);
        }
    }

    /// Follows one sound request: a start adds a sound playing (or
    /// replaces the one of its id, as a new game's queue counts from 1
    /// again), a stop takes it away.
    fn hear(&mut self, request: &SoundRequest, now: Millis) {
        match request {
            SoundRequest::Voice { clip } => self.voice = Some((clip.clone(), now)),
            SoundRequest::StopVoice => self.voice = None,
            SoundRequest::Sound { cue, volume } => self.hear_added(cue, *volume, None),
            SoundRequest::Start {
                id, cue, volume, ..
            } => {
                self.hear_added(cue, *volume, Some(*id));
                let sound = PlayingSound {
                    id: *id,
                    cue: cue.clone(),
                    paused: false,
                };
                match self.playing.binary_search_by_key(id, |p| p.id) {
                    Ok(at) => self.playing[at] = sound,
                    Err(at) => self.playing.insert(at, sound),
                }
            }
            SoundRequest::Stop { id } => self.playing.retain(|p| p.id != *id),
            SoundRequest::PauseSounds => self.playing.iter_mut().for_each(|p| p.paused = true),
            SoundRequest::ResumeSounds => self.playing.iter_mut().for_each(|p| p.paused = false),
            SoundRequest::Add { cue, samples, .. } => {
                self.added.insert(cue.clone(), samples.clone());
            }
            SoundRequest::Remove { cue } if self.added.remove(cue).is_some() => {
                self.playing.retain(|p| p.cue != *cue);
            }
            _ => {}
        }
    }

    /// Follows one music command: a `Start` starts the count at `now`; a
    /// `Stop` (or a fresh `Load`) of that track ends it.
    fn apply(&mut self, command: &MusicCommand, now: Millis) {
        match command {
            MusicCommand::Start { cue, .. } => self.started = Some((cue.clone(), now)),
            MusicCommand::Stop { cue } | MusicCommand::Load { cue } => {
                if self.started.as_ref().is_some_and(|(c, _)| c == cue) {
                    self.started = None;
                }
            }
            MusicCommand::Gain { .. } => {}
        }
    }
}

impl Audio for Speaker {
    fn music_playing(&self, now: Millis) -> Option<(&str, f64)> {
        if let Some(recorded) = &self.recorded {
            return recorded.position.map(|at| (recorded.track.as_str(), at));
        }
        let (cue, at) = self.started.as_ref().filter(|_| !self.silent)?;
        let elapsed = now.since(*at).as_secs_f64() - self.load_delay;
        (elapsed >= 0.0).then_some((cue.as_str(), elapsed))
    }

    fn voice_playing(&self, now: Millis) -> Option<&str> {
        if let Some(recorded) = &self.recorded {
            return Some(recorded.voice.as_str()).filter(|voice| !voice.is_empty());
        }
        let (clip, at) = self.voice.as_ref()?;
        let on = self
            .voice_length
            .is_none_or(|length| now.since(*at).as_secs_f64() < length);
        on.then_some(clip.as_str())
    }

    fn play(&mut self, frame: &AudioFrame<'_>, now: Millis) {
        self.volumes = Some((frame.music_volume, frame.sound_volume, frame.voice_volume));
        self.requests.clear();
        self.requests.extend_from_slice(frame.requests);
        for request in frame.requests {
            self.hear(request, now);
        }
        self.music.clear();
        self.music.extend_from_slice(frame.music);
        for command in frame.music {
            self.apply(command, now);
        }
    }

    fn stop_all(&mut self) {
        self.started = None;
        self.voice = None;
        self.playing.clear();
        self.stopped = true;
    }

    fn suspend(&mut self) {
        self.suspended = true;
    }

    fn resume(&mut self) {
        self.suspended = false;
    }
}

/// A system keyboard that answers from a script: each time it opens it
/// gives the next answer, at the next poll.
#[derive(Debug, Clone, Default)]
pub struct ScriptedKeyboard {
    /// The answers still to give, in order.
    answers: VecDeque<TextAnswer>,
    /// Every ask it was opened with, in order.
    asks: Vec<TextAsk>,
    /// The answer to the ask that is open.
    pending: Option<TextAnswer>,
}

impl ScriptedKeyboard {
    /// A keyboard that answers `answers`, one per opening, then cancels.
    pub fn new(answers: impl IntoIterator<Item = TextAnswer>) -> Self {
        Self {
            answers: answers.into_iter().collect(),
            ..Self::default()
        }
    }

    /// Every ask it was opened with, in order.
    pub fn asks(&self) -> &[TextAsk] {
        &self.asks
    }
}

impl TextInput for ScriptedKeyboard {
    fn open(&mut self, ask: &TextAsk) -> bool {
        if self.pending.is_some() {
            return false;
        }
        self.asks.push(ask.clone());
        self.pending = Some(self.answers.pop_front().unwrap_or(TextAnswer::Cancelled));
        true
    }

    fn poll(&mut self) -> Option<TextAnswer> {
        self.pending.take()
    }
}

/// The system keyboard a session record says was there: its answers and
/// its opens are the frame's. Nothing asks it what to answer.
#[derive(Debug, Clone, Default)]
struct RecordedKeyboard {
    present: bool,
    answer: Option<TextAnswer>,
    opened: Option<bool>,
}

impl RecordedKeyboard {
    /// One frame of a session record, if the keyboard had a part in it.
    fn play(&mut self, frame: Option<&KeyboardFrame>) {
        self.answer = None;
        self.opened = None;
        if let Some(frame) = frame {
            self.present = frame.present.unwrap_or(self.present);
            self.answer.clone_from(&frame.answer);
            self.opened = frame.opened;
        }
    }
}

impl TextInput for RecordedKeyboard {
    fn open(&mut self, _ask: &TextAsk) -> bool {
        self.opened.take().unwrap_or(false)
    }

    fn poll(&mut self) -> Option<TextAnswer> {
        self.answer.take()
    }
}

/// Where a [`HeadlessPlatform`]'s memory readings come from.
#[derive(Debug, Clone, Copy)]
enum Memory {
    /// It reads none.
    None,
    /// Fixed amounts by the frames presented
    /// ([`HeadlessPlatform::with_fake_memory`]).
    Fake,
    /// A real counter's reading.
    Real(fn() -> HeapCounts),
}

/// The fake memory's reading after `n` frames presented: live bytes
/// 1,048,576 + 16,384 × (*n* mod 30), the peak the most of those so far,
/// and *n* mod 7 allocations.
fn fake_heap(n: u32) -> HeapCounts {
    const BASE: u64 = 1 << 20;
    const STEP: u64 = 16 * 1024;
    let wide = u64::from(n);
    HeapCounts::new(BASE + STEP * (wide % 30), BASE + STEP * wide.min(29), n % 7)
}

/// The fake memory's snapshot after `n` frames presented, its rows adding
/// up to [`fake_heap`]'s live bytes: `image` (an asset kind) 49,152 bytes
/// in 3 blocks, `load` 524,288 in 40, `update` 16,384 × (*n* mod 30) in
/// *n* mod 30, and `other` 475,136 in 12. Each row's peak is the most of
/// its live bytes so far, and its bytes ever allocated its peak; a row
/// with nothing ever allocated (`update` before the first frame) is left
/// out, as a counter leaves it out.
fn fake_snapshot(n: u32) -> HeapSnapshot {
    const STEP: u64 = 16 * 1024;
    let heap = fake_heap(n);
    let row = |class, name: &'static str, live_bytes, live_blocks, peak_bytes| {
        let mut row = TagRow::new(class, name, live_bytes, live_blocks);
        row.allocated_bytes = peak_bytes;
        row.peak_bytes = peak_bytes;
        row
    };
    let fixed = |class, name, bytes, blocks| row(class, name, bytes, blocks, bytes);
    let mut rows = vec![
        fixed(TagClass::Asset, "image", 49_152, 3),
        fixed(TagClass::Phase, "load", 524_288, 40),
        fixed(TagClass::Other, "other", 475_136, 12),
    ];
    if n > 0 {
        let (wide, peak) = (u64::from(n), STEP * u64::from(n.min(29)));
        rows.push(row(
            TagClass::Phase,
            "update",
            STEP * (wide % 30),
            n % 30,
            peak,
        ));
    }
    HeapSnapshot::new(heap.live_bytes, heap.peak_bytes, rows)
}

/// A backend with no devices, for tests and tools.
#[derive(Debug)]
pub struct HeadlessPlatform {
    display: DisplayInfo,
    /// The input of the polls to come, one list per poll.
    input: VecDeque<Vec<RawInputEvent>>,
    /// The system's events for the next poll.
    system: Vec<SystemEvent>,
    /// The storage, until the game takes it.
    storage: Option<Box<dyn Storage>>,
    speaker: Speaker,
    keyboard: Option<ScriptedKeyboard>,
    /// The system keyboard of a session record, while one plays: in place
    /// of `keyboard`.
    recorded_keyboard: Option<RecordedKeyboard>,
    /// Where the game is said to run.
    facts: PlatformFacts,
    /// The clock it gives to measure frames with, if a test set one.
    clock: Option<PerfClock>,
    /// Where its memory readings come from.
    memory: Memory,
    /// How many times `App` asked for the memory.
    memory_calls: u32,
    /// The memory tags it gives, if a test set them.
    scopes: Option<MemoryScopes>,
    /// Where its heap snapshots come from beside the fake memory: a real
    /// counter's.
    snapshots: Option<fn() -> HeapSnapshot>,
    /// How many frames were presented.
    presented: u32,
    /// The last of them.
    last: Option<Presented>,
    /// The frame cap the last of them asked for, and its serial.
    frame_cap: Option<(FrameCap, u32)>,
    /// The reload errors the last of them asked to show.
    reload_errors: Vec<String>,
    /// The files that change at the next ask ([`change_file`](Self::change_file)).
    #[cfg(feature = "std")]
    changes: Vec<(Layer, String, Vec<u8>)>,
    /// How many times `App` asked what changed.
    changed_asks: u32,
    /// What runs on each frame presented, if a tool set it.
    present_hook: Option<Hook>,
}

/// What runs on each frame a [`HeadlessPlatform`] is presented, in its
/// [`present`](Platform::present): the work a device's backend does there,
/// such as a one-bit display's conversion, so a frame measured headless
/// counts it ([`HeadlessPlatform::set_present_hook`]).
pub type PresentHook = Box<dyn FnMut(&Frame<'_>)>;

/// A [`PresentHook`], which has no `Debug` of its own.
struct Hook(PresentHook);

impl core::fmt::Debug for Hook {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.write_str("PresentHook")
    }
}

impl Default for HeadlessPlatform {
    fn default() -> Self {
        Self::new()
    }
}

impl HeadlessPlatform {
    /// The display headless frames are said to be shown on, unless set.
    pub const DISPLAY: DisplayInfo = DisplayInfo::new(1280, 720);

    /// A backend with an empty memory storage, no input waiting and no
    /// system keyboard.
    pub fn new() -> Self {
        Self {
            display: Self::DISPLAY,
            input: VecDeque::new(),
            system: Vec::new(),
            storage: None,
            speaker: Speaker::default(),
            keyboard: None,
            recorded_keyboard: None,
            facts: PlatformFacts::default(),
            clock: None,
            memory: Memory::None,
            memory_calls: 0,
            scopes: None,
            snapshots: None,
            presented: 0,
            last: None,
            frame_cap: None,
            reload_errors: Vec::new(),
            #[cfg(feature = "std")]
            changes: Vec::new(),
            changed_asks: 0,
            present_hook: None,
        }
    }

    /// A backend ready to play `record` ([`Playback`](crate::session::Playback)):
    /// the display and the facts it recorded, and a memory storage holding
    /// its store (writes stay in memory). Its music and its system keyboard
    /// are the record's from the first [`push_frame`](Self::push_frame).
    pub fn from_session(record: &SessionRecord) -> Self {
        let mut storage = MemoryStorage::new();
        for (key, value) in &record.storage {
            // A key a store refused was never recorded by one.
            let _ = storage.write(key, value);
        }
        Self::new()
            .with_display(record.display)
            .with_facts(record.platform.clone())
            .with_storage(Box::new(storage))
    }

    /// Queues one frame of a session record: its system events, its input,
    /// and what the sound device and the system keyboard answer in it.
    pub fn push_frame(&mut self, frame: &FrameRecord) {
        self.system.extend_from_slice(&frame.system);
        self.push_input(&frame.input);
        self.speaker.play_recorded(frame);
        self.recorded_keyboard
            .get_or_insert_default()
            .play(frame.keyboard.as_ref());
    }

    /// The session record has played: the music and the system keyboard are
    /// this backend's own again.
    pub fn end_session(&mut self) {
        self.speaker.recorded = None;
        self.recorded_keyboard = None;
    }

    /// The same backend on `display`.
    #[must_use]
    pub fn with_display(mut self, display: DisplayInfo) -> Self {
        self.display = display;
        self
    }

    /// The same backend handing the game `storage` (a test's earlier run).
    #[must_use]
    pub fn with_storage(mut self, storage: Box<dyn Storage>) -> Self {
        self.storage = Some(storage);
        self
    }

    /// The same backend saying the game runs where `facts` say (the
    /// `desktop` target's until called): a target's, read from its
    /// profile with [`PlatformFacts::from_profile`].
    #[must_use]
    pub fn with_facts(mut self, facts: PlatformFacts) -> Self {
        self.facts = facts;
        self
    }

    /// The same backend with a system keyboard of its own.
    #[must_use]
    pub fn with_keyboard(mut self, keyboard: ScriptedKeyboard) -> Self {
        self.keyboard = Some(keyboard);
        self
    }

    /// The same backend giving `clock` to measure frames with
    /// ([`Platform::clock`]): a fake one ([`PerfClock::fake`]) makes a
    /// test's records the same on every run.
    #[must_use]
    pub fn with_clock(mut self, clock: PerfClock) -> Self {
        self.clock = Some(clock);
        self
    }

    /// Gives `clock` to measure frames with from now on, or none. `App`
    /// asks for it on its first frame only.
    pub fn set_clock(&mut self, clock: Option<PerfClock>) {
        self.clock = clock;
    }

    /// The same backend reading a fake heap ([`Platform::memory`]) that
    /// moves by fixed amounts, so a test's records are the same on every
    /// run: with *n* the frames it has presented, live bytes 1,048,576 +
    /// 16,384 × (*n* mod 30), the peak the most of those so far, and *n*
    /// mod 7 allocations.
    ///
    /// It takes fake heap snapshots too ([`Platform::heap_snapshot`]),
    /// whose rows add up to those live bytes: `Asset`/`image` 49,152 bytes
    /// in 3 blocks; `Phase`/`load` 524,288 in 40; `Phase`/`update` 16,384 ×
    /// (*n* mod 30) in *n* mod 30, left out before the first frame; and
    /// `Other`/`other` 475,136 in 12. Each row's peak is the most of its
    /// live bytes so far, and its bytes ever allocated equal its peak.
    #[must_use]
    pub fn with_fake_memory(mut self) -> Self {
        self.memory = Memory::Fake;
        self
    }

    /// Reads the heap with `memory` from now on (a real counter's
    /// reading), or reads none; the fake memory is dropped either way.
    pub fn set_memory(&mut self, memory: Option<fn() -> HeapCounts>) {
        self.memory = memory.map_or(Memory::None, Memory::Real);
    }

    /// Takes heap snapshots with `snapshot` from now on (a real counter's),
    /// or takes none; the fake memory's snapshots come first.
    pub fn set_heap_snapshots(&mut self, snapshot: Option<fn() -> HeapSnapshot>) {
        self.snapshots = snapshot;
    }

    /// Runs `hook` on each frame presented from now on, after the backend
    /// keeps it, or runs none (`None`).
    pub fn set_present_hook(&mut self, hook: Option<PresentHook>) {
        self.present_hook = hook.map(Hook);
    }

    /// Whether it reads the heap: a fake, or a counter set.
    pub fn has_memory(&self) -> bool {
        !matches!(self.memory, Memory::None)
    }

    /// How many times `App` asked for the memory ([`Platform::memory`]).
    pub fn memory_calls(&self) -> u32 {
        self.memory_calls
    }

    /// The same backend giving `scopes` as its memory tags
    /// ([`Platform::memory_scopes`]): a test's fake ones, which note what
    /// is entered.
    #[must_use]
    pub fn with_scopes(mut self, scopes: MemoryScopes) -> Self {
        self.scopes = Some(scopes);
        self
    }

    /// Gives `scopes` as its memory tags from now on, or none. `App` asks
    /// for them on its first frame only.
    pub fn set_scopes(&mut self, scopes: Option<MemoryScopes>) {
        self.scopes = scopes;
    }

    /// Queues `events` as the input of one poll, after those already
    /// queued.
    pub fn push_input(&mut self, events: &[RawInputEvent]) {
        self.input.push_back(events.to_vec());
    }

    /// Queues `event` for the next poll of the system's events.
    pub fn push_system(&mut self, event: SystemEvent) {
        self.system.push(event);
    }

    /// Queues a change of the file at `path` in `layer` (one handed in at
    /// run time) for the next time `App` asks what changed
    /// ([`Platform::changed_files`]), as a file changing on disk does: then
    /// it has `bytes`, and its path is told.
    #[cfg(feature = "std")]
    pub fn change_file(&mut self, layer: Layer, path: &str, bytes: Vec<u8>) {
        self.changes.push((layer, path.to_owned(), bytes));
    }

    /// How many times `App` asked what changed
    /// ([`Platform::changed_files`]).
    pub fn changed_asks(&self) -> u32 {
        self.changed_asks
    }

    /// The hot reload errors the last frame presented asked to show
    /// ([`Frame::reload_errors`]).
    pub fn reload_errors(&self) -> &[String] {
        &self.reload_errors
    }

    /// How many frames were presented.
    pub fn presented(&self) -> u32 {
        self.presented
    }

    /// The last frame presented.
    pub fn last_frame(&self) -> Option<&Presented> {
        self.last.as_ref()
    }

    /// The frame cap the last frame presented asked for, and its serial:
    /// the headless backend doesn't pace, and reports nothing.
    pub fn frame_cap(&self) -> Option<(FrameCap, u32)> {
        self.frame_cap
    }

    /// The sound device.
    pub fn speaker(&self) -> &Speaker {
        &self.speaker
    }

    /// The sound device, to set how the music loads.
    pub fn speaker_mut(&mut self) -> &mut Speaker {
        &mut self.speaker
    }

    /// The system keyboard, if it has one.
    pub fn keyboard(&self) -> Option<&ScriptedKeyboard> {
        self.keyboard.as_ref()
    }
}

impl Platform for HeadlessPlatform {
    fn display(&self) -> DisplayInfo {
        self.display
    }

    fn present(&mut self, frame: &Frame<'_>) {
        self.presented += 1;
        self.frame_cap = Some((frame.frame_cap, frame.frame_cap_serial));
        self.reload_errors.clear();
        self.reload_errors.extend_from_slice(frame.reload_errors);
        Presented::keep(&mut self.last, frame);
        if let Some(Hook(hook)) = &mut self.present_hook {
            hook(frame);
        }
    }

    fn poll_input(&mut self, out: &mut Vec<RawInputEvent>) {
        if let Some(events) = self.input.pop_front() {
            out.extend(events);
        }
    }

    fn system_events(&mut self, out: &mut Vec<SystemEvent>) {
        out.append(&mut self.system);
    }

    fn storage(&mut self) -> Box<dyn Storage> {
        self.storage
            .take()
            .unwrap_or_else(|| Box::new(MemoryStorage::new()))
    }

    fn audio(&mut self) -> &mut dyn Audio {
        &mut self.speaker
    }

    fn text_input(&mut self) -> Option<&mut dyn TextInput> {
        if let Some(recorded) = &mut self.recorded_keyboard {
            return recorded.present.then_some(recorded as &mut dyn TextInput);
        }
        self.keyboard.as_mut().map(|k| k as &mut dyn TextInput)
    }

    fn facts(&self) -> PlatformFacts {
        self.facts.clone()
    }

    fn clock(&self) -> Option<PerfClock> {
        self.clock
    }

    fn memory_scopes(&self) -> Option<MemoryScopes> {
        self.scopes
    }

    fn memory(&mut self) -> Option<MemoryReading> {
        self.memory_calls = self.memory_calls.saturating_add(1);
        let heap = match self.memory {
            Memory::None => return None,
            Memory::Fake => fake_heap(self.presented),
            Memory::Real(read) => read(),
        };
        Some(MemoryReading::new(heap))
    }

    fn heap_snapshot(&mut self) -> Option<HeapSnapshot> {
        match self.memory {
            Memory::Fake => Some(fake_snapshot(self.presented)),
            Memory::None | Memory::Real(_) => self.snapshots.map(|snapshot| snapshot()),
        }
    }

    #[cfg(feature = "std")]
    fn changed_files(&mut self, out: &mut Vec<String>) {
        self.changed_asks = self.changed_asks.saturating_add(1);
        for (layer, path, bytes) in self.changes.drain(..) {
            if layer.replace(&path, bytes) {
                out.push(path);
            }
        }
    }
}

#[cfg(test)]
mod tests;