loam_app/session/

frame.rs

#[cfg(not(target_arch = "wasm32"))]
use std::sync::Arc;

use glam::Vec2;
use web_time::Instant;
use wgpu::{CommandBuffer, CommandEncoder, Texture, TextureFormat, TextureView};
#[cfg(not(target_arch = "wasm32"))]
use winit::window::Window;

use loam_render::device::GpuContext;
use loam_render::present::Presenter;
#[cfg(not(target_arch = "wasm32"))]
use loam_runtime::host::HostConfig;
use loam_runtime::host::HostError;
use loam_runtime::{Eye, Publication, PublishError, Records, Session, Stores};
use loam_time::{frame_trace, FixedTimestep};

use super::app::{CaptureControl, FrameHook, InputHook, Posts, Redraw, SessionApp};
use super::cursor::CursorCapture;
#[cfg(feature = "egui")]
use super::debug_layer::DebugLayer;
use super::input::InputMap;

pub struct Target<'a> {
    pub view: &'a TextureView,
    pub texture: &'a Texture,
    pub format: TextureFormat,
    pub size: (u32, u32),
}

pub(crate) fn failed(error: impl std::fmt::Display) -> HostError {
    HostError::Host(error.to_string())
}

#[derive(Clone, Copy, Default, PartialEq)]
struct Shown {
    content: u64,
    eye: Eye,
    size: (u32, u32),
    background: wgpu::Color,
}

fn redraws(policy: Redraw, drawn: Option<&Shown>, next: &Shown, forced: bool) -> bool {
    policy == Redraw::EveryFrame || forced || drawn != Some(next)
}

struct Inner<A: Stores> {
    session: Session<A>,
    records: Records,
    timestep: Option<FixedTimestep>,
    callbacks: Vec<CommandBuffer>,
    input: InputMap,
    cursor: CursorCapture,
    app: SessionApp<A>,
    posts: Posts,
    no_views_reported: bool,
    shown: Shown,
    drawn: Option<Shown>,
    #[cfg(test)]
    presented: Option<Eye>,
    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    capture: crate::capture::Capture,
}

pub(crate) struct Frame<A: Stores> {
    presenter: Option<Presenter>,
    #[cfg(feature = "egui")]
    layer: Option<DebugLayer>,
    inner: Inner<A>,
    trace: Option<frame_trace::Scope>,
}

impl<A: Stores> Frame<A> {
    pub(crate) fn new(session: Session<A>, app: SessionApp<A>) -> Result<Self, HostError> {
        let sim = session.config();
        sim.check().map_err(failed)?;
        let timestep = sim
            .dt()
            .map(|_| FixedTimestep::new(sim.fixed_hz).with_max_catch_up(sim.max_ticks_per_frame));
        Ok(Self {
            presenter: None,
            #[cfg(feature = "egui")]
            layer: None,
            inner: Inner {
                session,
                records: Records::default(),
                timestep,
                callbacks: Vec::new(),
                input: InputMap::default(),
                cursor: CursorCapture::new(),
                app,
                posts: Posts::default(),
                no_views_reported: false,
                shown: Shown::default(),
                drawn: None,
                #[cfg(test)]
                presented: None,
                #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
                capture: crate::capture::Capture::new(),
            },
            trace: None,
        })
    }

    pub(crate) fn redraw(&self) -> Redraw {
        self.inner.app.redraw
    }

    pub(crate) fn invalidate(&mut self) {
        self.inner.drawn = None;
    }

    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn config(&self) -> &HostConfig {
        &self.inner.app.config
    }

    pub(crate) fn app_mut(&mut self) -> &mut SessionApp<A> {
        &mut self.inner.app
    }

    #[cfg(any(all(target_arch = "wasm32", feature = "measure"), test))]
    pub(crate) fn phase_error(&self) -> Option<loam_runtime::PhaseError> {
        self.inner.session.phase_error()
    }

    #[cfg(any(target_arch = "wasm32", test))]
    pub(crate) fn posts(&self) -> impl Iterator<Item = (&'static str, &[f32])> {
        self.inner.posts.iter()
    }

    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn input_mut(&mut self) -> &mut InputMap {
        &mut self.inner.input
    }

    pub(crate) fn alt(&mut self, index: usize, pressed: bool) {
        self.inner.cursor.alt(index, pressed);
    }

    pub(crate) fn focus(&mut self, focused: bool) {
        self.inner.cursor.focus(focused);
        if !focused {
            self.inner.input.release_all();
        }
    }

    pub(crate) fn cursor_applied(&mut self, locked: bool) {
        self.inner.cursor.applied(locked);
        self.inner.input.set_cursor_locked(locked);
    }

    pub(crate) fn cursor_locked(&self) -> bool {
        self.inner.cursor.locked()
    }

    pub(crate) fn take_cursor_request(&mut self) -> Option<bool> {
        self.inner.cursor.take_request()
    }

    #[cfg(target_arch = "wasm32")]
    pub(crate) fn apply_message(
        &mut self,
        message: &crate::wasm::input_queue::InputMessage,
        consumed: bool,
    ) {
        super::input::apply(
            &mut self.inner.input,
            &self.inner.app.config.bindings,
            message,
            consumed,
        );
    }

    #[cfg(target_arch = "wasm32")]
    pub(crate) fn observe_message(&mut self, message: &crate::wasm::input_queue::InputMessage) {
        use crate::wasm::input_queue::InputMessage;

        match message {
            InputMessage::Key {
                code,
                pressed,
                repeat,
                ..
            } if !repeat || !pressed => match code.as_str() {
                "AltLeft" => self.alt(0, *pressed),
                "AltRight" => self.alt(1, *pressed),
                _ => {}
            },
            InputMessage::Focus(focused) => self.focus(*focused),
            InputMessage::PointerLockChanged { locked, released } => {
                self.cursor_applied(*locked);
                if *released {
                    self.inner.cursor.released();
                }
            }
            _ => {}
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn action(&mut self, key: loam_runtime::Key, pressed: bool, consumed: bool) {
        self.inner
            .input
            .host_action(&self.inner.app.config.bindings, key, pressed, consumed);
    }

    #[cfg(feature = "egui")]
    pub(crate) fn layer(&self) -> Option<&DebugLayer> {
        self.layer.as_ref()
    }

    pub(crate) fn reset_clock(&mut self, now: Instant) {
        if let Some(timestep) = self.inner.timestep.as_mut() {
            timestep.reset_clock(now);
        }
        self.inner.app.pacer.reset();
    }

    pub(crate) fn attach(
        &mut self,
        gpu: &GpuContext,
        format: TextureFormat,
        #[cfg(not(target_arch = "wasm32"))] window: Option<Arc<Window>>,
        size: (u32, u32),
        scale: f32,
    ) -> Result<(), HostError> {
        let mut presenter = Presenter::new(format).map_err(failed)?;
        for pass in self.inner.app.passes.drain(..) {
            presenter.register_pass(pass).map_err(failed)?;
        }
        #[cfg(all(not(feature = "egui"), not(target_arch = "wasm32")))]
        let _ = window;
        #[cfg(feature = "egui")]
        if self.inner.app.debug_layer {
            let layer = match self.layer.clone() {
                Some(layer) => layer,
                #[cfg(not(target_arch = "wasm32"))]
                None => match window {
                    Some(window) => DebugLayer::on_window(gpu, format, window, size),
                    None => DebugLayer::offscreen(gpu, format, size, scale),
                },
                #[cfg(target_arch = "wasm32")]
                None => DebugLayer::offscreen(gpu, format, size, scale),
            };
            presenter.register_pass(layer.pass()).map_err(failed)?;
            self.layer = Some(layer);
        }
        presenter.attach(gpu).map_err(failed)?;
        self.presenter = Some(presenter);
        self.resize(size.0, size.1, scale);
        Ok(())
    }

    pub(crate) fn recover(&mut self, gpu: &GpuContext) -> Result<(), HostError> {
        self.invalidate();
        if let Some(presenter) = self.presenter.as_mut() {
            presenter.attach(gpu).map_err(failed)?;
        }
        Ok(())
    }

    pub(crate) fn resize(&mut self, width: u32, height: u32, scale: f32) {
        self.invalidate();
        self.inner.input.resize(width, height, scale);
        #[cfg(feature = "egui")]
        if let Some(layer) = self.layer.as_ref() {
            layer.resize(width, height, scale);
        }
    }

    pub(crate) fn step(
        &mut self,
        gpu: &GpuContext,
        target: &Target<'_>,
        now: Instant,
        finish: impl FnMut(&mut CommandEncoder),
    ) -> Result<(), HostError> {
        if self.update(gpu, target.size, now)? {
            self.draw(gpu, target, now, finish)?;
        }
        Ok(())
    }

    pub(crate) fn update(
        &mut self,
        gpu: &GpuContext,
        size: (u32, u32),
        now: Instant,
    ) -> Result<bool, HostError> {
        self.inner.posts.clear();
        self.end_trace();
        let outcome = self.updated(gpu, size, now);
        if let Err(error) = &outcome {
            tracing::error!("frame failed: {error}");
        }
        outcome
    }

    fn updated(
        &mut self,
        gpu: &GpuContext,
        size: (u32, u32),
        now: Instant,
    ) -> Result<bool, HostError> {
        gpu.device.poll(wgpu::PollType::Poll).map_err(failed)?;
        if let Some(error) = gpu.take_uncaptured_error() {
            return Err(failed(error));
        }
        let Some(presenter) = self.presenter.as_mut() else {
            return Ok(false);
        };
        if size.0 == 0 || size.1 == 0 {
            return Ok(false);
        }
        frame_trace::begin_frame();
        self.trace = Some(frame_trace::scope("frame"));
        let drawn = self.inner.update(
            gpu,
            size,
            now,
            presenter,
            #[cfg(feature = "egui")]
            self.layer.as_ref(),
        );
        if !matches!(drawn, Ok(true)) {
            self.end_trace();
        }
        drawn
    }

    pub(crate) fn draw(
        &mut self,
        gpu: &GpuContext,
        target: &Target<'_>,
        now: Instant,
        finish: impl FnMut(&mut CommandEncoder),
    ) -> Result<(), HostError> {
        let outcome = match self.presenter.as_mut() {
            Some(presenter) => self.inner.draw(
                gpu,
                target,
                now,
                finish,
                presenter,
                #[cfg(feature = "egui")]
                self.layer.as_ref(),
            ),
            None => Ok(()),
        };
        self.end_trace();
        if let Err(error) = &outcome {
            tracing::error!("frame failed: {error}");
        }
        outcome
    }

    fn end_trace(&mut self) {
        if self.trace.is_some() {
            self.trace = None;
            frame_trace::end_frame();
        }
    }
}

impl<A: Stores> Inner<A> {
    fn advance(
        &mut self,
        now: Instant,
        size: (u32, u32),
        #[cfg(feature = "egui")] ui: Option<&loam_egui::egui::Context>,
    ) -> Result<(), HostError> {
        let controls = self.app.console.take_controls();
        if let Some(fps) = controls.target_fps {
            self.app.pacer.set_target_fps(fps);
        }
        if controls.vsync.is_some() {
            self.app.vsync = controls.vsync;
        }
        let Inner {
            session,
            input,
            timestep,
            app,
            ..
        } = self;
        let aspect = input
            .display_aspect()
            .unwrap_or(size.0 as f32 / size.1 as f32);
        session.views_mut().root_mut().eye.aspect = aspect;
        let gathered = input.take();
        let sender = app.commands.sender();
        let was_faulted = session.faulted_phase().is_some();
        if app
            .fault_recovery
            .is_some_and(|action| was_faulted && gathered.pressed(action))
        {
            sender.reset();
        }
        if let Some(hook) = app.input.as_mut() {
            hook(&InputHook {
                session,
                input: &gathered,
                #[cfg(feature = "egui")]
                ui,
                size,
                sender: &sender,
            });
        }
        let result = (|| {
            {
                let _dispatch = frame_trace::scope("dispatch");
                app.boundary(session, gathered)?;
            }
            session.views_mut().root_mut().eye.aspect = aspect;
            if let Some(timestep) = timestep.as_mut() {
                if was_faulted && session.faulted_phase().is_none() {
                    timestep.reset_clock(now);
                }
                let _simulation = frame_trace::scope("simulation");
                for _ in timestep.advance(now) {
                    session.tick()?;
                }
            }
            session.views_mut().root_mut().eye.aspect = aspect;
            Ok(())
        })();
        input.reclaim(session.take_input());
        result
    }

    fn prepare(
        &mut self,
        now: Instant,
        size: (u32, u32),
        #[cfg(feature = "egui")] ui: Option<&loam_egui::egui::Context>,
    ) -> Result<(Publication, Eye), HostError> {
        self.advance(
            now,
            size,
            #[cfg(feature = "egui")]
            ui,
        )?;
        {
            let _publication = frame_trace::scope("publication");
            let alpha = self.timestep.as_ref().map_or(1.0, FixedTimestep::alpha);
            self.records
                .publish_at(&mut self.session, alpha)
                .map_err(|error| match error {
                    PublishError::Borrowed => {
                        HostError::Host("publication buffer is borrowed".into())
                    }
                    PublishError::Phase(error) => HostError::Phase(error),
                })?;
        }
        self.session.views_mut().root_mut().eye.aspect = self
            .input
            .display_aspect()
            .unwrap_or(size.0 as f32 / size.1 as f32);
        let root = self.session.views().root();
        let eye = self
            .session
            .views()
            .get(root)
            .map(|view| view.eye)
            .ok_or_else(|| HostError::Host("the root view is missing".into()))?;
        let records = self
            .records
            .lend()
            .ok_or_else(|| HostError::Host("the publication buffer is unavailable".into()))?;
        if records.views.is_empty() && !self.no_views_reported {
            self.no_views_reported = true;
            tracing::warn!("the session published no views, so nothing is drawn");
            self.app
                .console
                .note("the session published no views, so nothing is drawn".to_string());
        }
        Ok((records, eye))
    }

    fn update(
        &mut self,
        gpu: &GpuContext,
        size: (u32, u32),
        now: Instant,
        presenter: &mut Presenter,
        #[cfg(feature = "egui")] layer: Option<&DebugLayer>,
    ) -> Result<bool, HostError> {
        #[cfg(feature = "egui")]
        let context = layer.map(DebugLayer::begin);
        let faulted_before = self.session.faulted_phase();
        let scene_before = self.session.scene();
        let prepared = self.prepare(
            now,
            size,
            #[cfg(feature = "egui")]
            context.as_ref(),
        );
        let mut requested = false;
        let terminal = match prepared {
            Ok((records, eye)) => {
                {
                    let sender = self.app.commands.sender();
                    let (hook, captures, cursor, background, posts) = (
                        self.app.frame.as_mut(),
                        &mut self.app.captures,
                        &mut self.cursor,
                        &mut self.app.background,
                        &mut self.posts,
                    );
                    if let Some(hook) = hook {
                        hook(&mut FrameHook {
                            session: &self.session,
                            published: &records,
                            alpha: records.alpha,
                            sections: presenter.sections(),
                            #[cfg(feature = "egui")]
                            ui: context.as_ref(),
                            size,
                            sender: &sender,
                            capture: CaptureControl::new(captures),
                            cursor,
                            background,
                            posts,
                            redraw: &mut requested,
                        });
                    }
                }
                let _presentation = frame_trace::scope("presentation");
                #[cfg(test)]
                {
                    self.presented = Some(eye);
                }
                presenter.upload(
                    &gpu.device,
                    &gpu.queue,
                    &eye,
                    Vec2::new(size.0 as f32, size.1 as f32),
                    &records.views,
                );
                self.shown.content = records.content();
                self.shown.eye = eye;
                self.records.release(records);
                None
            }
            Err(error) if self.session.faulted_phase().is_some() => {
                if faulted_before.is_none() || self.session.scene() != scene_before {
                    tracing::error!("session frame failed: {error}");
                    self.cursor.suspend();
                }
                if let Some(timestep) = self.timestep.as_mut() {
                    timestep.reset_clock(now);
                }
                None
            }
            Err(error) => Some(error),
        };
        #[cfg(feature = "egui")]
        if let Some(context) = context.as_ref() {
            loam_egui::ConsoleUi::ui(self.app.console.ui_mut(), context);
        }
        if let Some(driver) = self.app.script.as_mut() {
            driver.advance_console(&mut self.app.console);
        }
        let dispatched = self.app.console.dispatch_pending();
        #[cfg(feature = "egui")]
        if let Some(layer) = layer {
            layer.finish();
        }
        if let Some(error) = terminal {
            return Err(error);
        }
        #[cfg(feature = "egui")]
        let layered = layer.is_some();
        #[cfg(not(feature = "egui"))]
        let layered = false;
        #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
        let capturing = !self.app.captures.is_empty() || self.capture.should_capture(now);
        #[cfg(not(all(feature = "capture", not(target_arch = "wasm32"))))]
        let capturing = false;
        self.shown.size = size;
        self.shown.background = self.app.background;
        let draw = redraws(
            self.app.redraw,
            self.drawn.as_ref(),
            &self.shown,
            requested || dispatched || layered || capturing,
        );
        // Set again only after submit, so a failed acquire keeps the draw pending.
        if draw {
            self.drawn = None;
        }
        Ok(draw)
    }

    fn draw(
        &mut self,
        gpu: &GpuContext,
        target: &Target<'_>,
        now: Instant,
        mut finish: impl FnMut(&mut CommandEncoder),
        presenter: &mut Presenter,
        #[cfg(feature = "egui")] layer: Option<&DebugLayer>,
    ) -> Result<(), HostError> {
        #[cfg(not(all(feature = "capture", not(target_arch = "wasm32"))))]
        let _ = now;
        #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
        let (wants_pre, wants_post) = self.capture_intent(now);
        let mut encoder = gpu
            .device
            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                label: Some("loam-app::session"),
            });
        presenter
            .record_scene(
                &gpu.device,
                &mut encoder,
                target.view,
                target.size,
                self.app.background,
            )
            .map_err(failed)?;
        #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
        let pre = if wants_pre {
            finish(&mut encoder);
            self.record_capture(&gpu.device, &mut encoder, target)
        } else {
            None
        };
        presenter
            .record_overlays(&mut encoder, target.view, target.size)
            .map_err(failed)?;
        finish(&mut encoder);
        #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
        let post = wants_post
            .then(|| self.record_capture(&gpu.device, &mut encoder, target))
            .flatten();
        #[cfg(feature = "egui")]
        if let Some(layer) = layer {
            layer.take_callbacks(&mut self.callbacks);
        }
        gpu.queue
            .submit(self.callbacks.drain(..).chain(Some(encoder.finish())));
        presenter.after_submit();
        crate::trace::record_presentation(presenter.sections(), presenter.uploads());
        #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
        self.consume_capture(&gpu.device, now, pre, post);
        self.drawn = Some(self.shown);
        Ok(())
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    fn capture_intent(&mut self, now: Instant) -> (bool, bool) {
        if !self.app.captures.is_empty() {
            let requests = std::mem::take(&mut self.app.captures);
            for line in self.capture.apply_requests(requests) {
                tracing::info!("{line}");
            }
        }
        if !self.capture.should_capture(now) {
            return (false, false);
        }
        (self.capture.wants_pre(), self.capture.wants_post())
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    fn record_capture(
        &self,
        device: &wgpu::Device,
        encoder: &mut CommandEncoder,
        target: &Target<'_>,
    ) -> Option<crate::capture::TextureReadback> {
        match crate::capture::record_texture_rgba(
            device,
            encoder,
            target.texture,
            target.size.0,
            target.size.1,
            target.format,
        ) {
            Ok(readback) => Some(readback),
            Err(error) => {
                tracing::error!("capture: copy failed: {error:#}");
                None
            }
        }
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    fn consume_capture(
        &mut self,
        device: &wgpu::Device,
        now: Instant,
        pre: Option<crate::capture::TextureReadback>,
        post: Option<crate::capture::TextureReadback>,
    ) {
        for (is_pre, readback) in [(true, pre), (false, post)] {
            let Some(readback) = readback else {
                continue;
            };
            match readback.read(device) {
                Ok(image) => {
                    if let Err(error) = self.capture.consume_frame(
                        is_pre,
                        image.rgba,
                        image.width,
                        image.height,
                        now,
                    ) {
                        tracing::error!("capture: write failed: {error:#}");
                    }
                }
                Err(error) => tracing::error!("capture: readback failed: {error:#}"),
            }
        }
        self.capture.advance_frame(now);
    }
}

#[cfg(test)]
mod tests {
    use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
    use std::sync::{Arc, Mutex};
    use std::time::Duration;

    use glam::Vec3;
    use loam_math::EuclideanR3;
    use loam_render::device::FeatureRequest;
    use loam_render::pass::{FrameFormat, FramePass, FrameTarget, PassStage};
    use loam_runtime::{
        ActionId, Bindings, Command, DomainBuilder, HostConfig, Identity3, Key, LogCapacity,
        Material, Phase, Pose, PreparedGeometry, SimConfig, SpawnBundle, Tick, ViewSpec,
    };
    use wgpu::{
        BackendOptions, Backends, Extent3d, Instance, InstanceDescriptor, NoopBackendOptions,
        TextureDescriptor, TextureDimension, TextureUsages, TextureViewDescriptor,
    };
    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    use wgpu::{
        Color, ColorTargetState, ColorWrites, FragmentState, LoadOp, MultisampleState, Operations,
        PrimitiveState, RenderPassColorAttachment, RenderPassDescriptor, RenderPipeline,
        RenderPipelineDescriptor, ShaderModuleDescriptor, ShaderSource, StoreOp, VertexState,
    };

    use super::*;
    use crate::args::Args;
    use crate::session::CursorPolicy;

    const FORMAT: TextureFormat = TextureFormat::Rgba8UnormSrgb;
    const SIZE: (u32, u32) = (64, 48);
    loam_runtime::stores! {
        #[derive(Default)]
        pub struct Bare {}
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    const CAPTURE_FPS: u16 = 60;

    struct Probe {
        recorded: Arc<AtomicU32>,
        rebuilt: Arc<AtomicU32>,
    }

    impl FramePass for Probe {
        fn name(&self) -> &'static str {
            "probe"
        }

        fn stage(&self) -> PassStage {
            PassStage::Scene
        }

        fn record(
            &mut self,
            _encoder: &mut CommandEncoder,
            _target: &FrameTarget<'_>,
        ) -> anyhow::Result<()> {
            self.recorded.fetch_add(1, Ordering::Relaxed);
            Ok(())
        }

        fn attach(&mut self, _gpu: &GpuContext, _frame: FrameFormat) -> anyhow::Result<()> {
            self.rebuilt.fetch_add(1, Ordering::Relaxed);
            Ok(())
        }
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    struct Paint {
        name: &'static str,
        color: Color,
        overlay: bool,
        pipeline: Option<RenderPipeline>,
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    impl FramePass for Paint {
        fn name(&self) -> &'static str {
            self.name
        }

        fn stage(&self) -> PassStage {
            if self.overlay {
                PassStage::Overlay
            } else {
                PassStage::Scene
            }
        }

        fn record(
            &mut self,
            encoder: &mut CommandEncoder,
            target: &FrameTarget<'_>,
        ) -> anyhow::Result<()> {
            let Some(pipeline) = self.pipeline.as_ref() else {
                anyhow::bail!("paint recorded before attach");
            };
            let mut pass = encoder.begin_render_pass(&RenderPassDescriptor {
                label: Some(self.name),
                color_attachments: &[Some(RenderPassColorAttachment {
                    view: target.color,
                    depth_slice: None,
                    resolve_target: None,
                    ops: Operations {
                        load: LoadOp::Load,
                        store: StoreOp::Store,
                    },
                })],
                depth_stencil_attachment: None,
                timestamp_writes: None,
                occlusion_query_set: None,
            });
            pass.set_pipeline(pipeline);
            pass.draw(0..3, 0..1);
            Ok(())
        }

        fn attach(&mut self, gpu: &GpuContext, frame: FrameFormat) -> anyhow::Result<()> {
            let Color { r, g, b, a } = self.color;
            let source = format!(
                r#"
@vertex
fn vertex(@builtin(vertex_index) index: u32) -> @builtin(position) vec4<f32> {{
    var corners = array<vec2<f32>, 3>(
        vec2<f32>(-1.0, -1.0),
        vec2<f32>(3.0, -1.0),
        vec2<f32>(-1.0, 3.0),
    );
    return vec4<f32>(corners[index], 0.0, 1.0);
}}

@fragment
fn fragment() -> @location(0) vec4<f32> {{
    return vec4<f32>({r:?}, {g:?}, {b:?}, {a:?});
}}
"#
            );
            let shader = gpu.device.create_shader_module(ShaderModuleDescriptor {
                label: Some(self.name),
                source: ShaderSource::Wgsl(source.into()),
            });
            self.pipeline = Some(
                gpu.device
                    .create_render_pipeline(&RenderPipelineDescriptor {
                        label: Some(self.name),
                        layout: None,
                        vertex: VertexState {
                            module: &shader,
                            entry_point: Some("vertex"),
                            compilation_options: Default::default(),
                            buffers: &[],
                        },
                        primitive: PrimitiveState::default(),
                        depth_stencil: None,
                        multisample: MultisampleState::default(),
                        fragment: Some(FragmentState {
                            module: &shader,
                            entry_point: Some("fragment"),
                            compilation_options: Default::default(),
                            targets: &[Some(ColorTargetState {
                                format: frame.color,
                                blend: None,
                                write_mask: ColorWrites::ALL,
                            })],
                        }),
                        multiview: None,
                        cache: None,
                    }),
            );
            Ok(())
        }
    }

    fn noop_gpu() -> GpuContext {
        let instance = Instance::new(&InstanceDescriptor {
            backends: Backends::NOOP,
            backend_options: BackendOptions {
                noop: NoopBackendOptions { enable: true },
                ..Default::default()
            },
            ..Default::default()
        });
        pollster::block_on(GpuContext::new(instance, FeatureRequest::default(), None))
            .expect("the noop backend always yields a context")
    }

    fn offscreen(gpu: &GpuContext) -> Texture {
        gpu.device.create_texture(&TextureDescriptor {
            label: Some("session frame probe"),
            size: Extent3d {
                width: SIZE.0,
                height: SIZE.1,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: TextureDimension::D2,
            format: FORMAT,
            usage: TextureUsages::RENDER_ATTACHMENT | TextureUsages::COPY_SRC,
            view_formats: &[],
        })
    }

    fn bare(app: SessionApp<Bare>) -> Frame<Bare> {
        Frame::new(Session::new(Bare::default(), SimConfig::default()), app)
            .expect("the frame accepted the simulation config")
    }

    fn host<A: Stores>(name: &'static str) -> SessionApp<A> {
        quiet(SessionApp::with_args(
            HostConfig::new(name, Bindings::new()),
            Args::default(),
        ))
    }

    fn quiet<A: Stores>(app: SessionApp<A>) -> SessionApp<A> {
        app.debug_layer(false)
    }

    fn run_one<A: Stores>(frame: &mut Frame<A>, gpu: &GpuContext, texture: &Texture) {
        run_at(frame, gpu, texture, Instant::now());
    }

    fn run_at<A: Stores>(frame: &mut Frame<A>, gpu: &GpuContext, texture: &Texture, now: Instant) {
        let view = texture.create_view(&TextureViewDescriptor::default());
        let target = Target {
            view: &view,
            texture,
            format: FORMAT,
            size: SIZE,
        };
        frame
            .step(gpu, &target, now, |_| {})
            .expect("the frame stepped");
    }

    fn world(moves: bool) -> Session<Bare> {
        let mut session = Session::new(Bare::default(), SimConfig::default());
        let r3 = session
            .register_domain(DomainBuilder::new("r3", EuclideanR3).tracked(LogCapacity::default()));
        let geometry = session.prepare(PreparedGeometry::Lines3 {
            segments: vec![[[0.0; 3], [1.0, 0.0, 0.0]]],
        });
        let material = session.add_material(Material::lines([1.0; 4], 1.0));
        let root = session.views().root();
        let body = session
            .dispatch(|dispatch| {
                let eye = dispatch.spawn(SpawnBundle::new().at(r3, Pose::at(Vec3::Z * 4.0)))?;
                dispatch
                    .domains
                    .typed(r3)?
                    .add_view(ViewSpec::new(root, eye, Identity3))?;
                dispatch.spawn(
                    SpawnBundle::new()
                        .at(r3, Pose::at(Vec3::ZERO))
                        .instance(loam_runtime::Instance::new(geometry, material)),
                )
            })
            .expect("the world spawned");
        session.system(
            Phase::Simulation,
            "drift",
            move |ctx: loam_runtime::Ctx<'_, Bare>| -> Result<(), loam_runtime::DomainError> {
                if moves {
                    let x = (ctx.step.tick.0 + 1) as f32;
                    ctx.domains
                        .typed(r3)?
                        .set_pose(body, Pose::at(Vec3::X * x))?;
                }
                Ok(())
            },
        );
        session
    }

    fn on_change(
        session: Session<Bare>,
        app: SessionApp<Bare>,
        gpu: &GpuContext,
    ) -> (Frame<Bare>, Arc<AtomicU32>) {
        let recorded = Arc::new(AtomicU32::new(0));
        let app = app.redraw(Redraw::OnChange).pass(Box::new(Probe {
            recorded: recorded.clone(),
            rebuilt: Arc::new(AtomicU32::new(0)),
        }));
        let mut frame = Frame::new(session, app).expect("the frame accepted the simulation config");
        frame
            .attach(gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");
        (frame, recorded)
    }

    #[test]
    fn a_still_world_under_on_change_skips_the_draw_after_the_first_frame() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let hooked = Arc::new(AtomicU32::new(0));
        let hooks = hooked.clone();
        let app = host("still").on_frame(move |_| {
            hooks.fetch_add(1, Ordering::Relaxed);
        });
        let (mut frame, recorded) = on_change(world(false), app, &gpu);
        let start = Instant::now();
        for millis in [0, 20, 25] {
            run_at(
                &mut frame,
                &gpu,
                &texture,
                start + Duration::from_millis(millis),
            );
        }
        assert_eq!(recorded.load(Ordering::Relaxed), 1);
        assert_eq!(hooked.load(Ordering::Relaxed), 3);
    }

    #[test]
    fn a_frame_whose_publish_patched_a_moving_body_is_drawn() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let (mut frame, recorded) = on_change(world(true), host("moving"), &gpu);
        let start = Instant::now();
        for millis in [0, 20, 25] {
            run_at(
                &mut frame,
                &gpu,
                &texture,
                start + Duration::from_millis(millis),
            );
        }
        assert_eq!(recorded.load(Ordering::Relaxed), 3);
    }

    #[test]
    fn a_scale_change_redraws_a_frame_whose_content_is_unchanged() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let (mut frame, recorded) = on_change(world(false), host("scale"), &gpu);
        let start = Instant::now();
        run_at(&mut frame, &gpu, &texture, start);
        run_at(
            &mut frame,
            &gpu,
            &texture,
            start + Duration::from_millis(20),
        );
        assert_eq!(recorded.load(Ordering::Relaxed), 1);
        frame.resize(SIZE.0, SIZE.1, 2.0);
        run_at(
            &mut frame,
            &gpu,
            &texture,
            start + Duration::from_millis(25),
        );
        assert_eq!(recorded.load(Ordering::Relaxed), 2);
    }

    #[test]
    fn incompatible_dynamic_shader_reaches_the_host_with_pass_and_cause() {
        let source = r#"
struct Fragment {
    @location(0) color: vec4<f32>,
    @builtin(frag_depth) depth: f32,
}
@group(0) @binding(0) var<storage, read> wrong: array<u32>;
@group(0) @binding(1) var<storage, read> bodies: array<u32>;
@vertex fn vs_fullscreen(@builtin(vertex_index) vertex: u32) -> @builtin(position) vec4<f32> {
    return vec4<f32>(f32(vertex), 0.0, 0.0, 1.0);
}
@fragment fn fs_main() -> @location(0) vec4<f32> {
    return vec4<f32>(0.0);
}
@fragment fn fs_depth() -> Fragment {
    return Fragment(vec4<f32>(0.0), 0.5);
}
"#;
        let gpu = noop_gpu();
        let app =
            host("shader error").pass(Box::new(loam_render::HyperslicePass::new(source.into())));
        let mut frame = bare(app);
        let error = frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect_err("incompatible shader");
        let message = format!("{error:?}");
        assert!(message.contains("pass `hyperslice` failed during attach"));
        assert!(message.contains("WGSL binding 0:0 must use Uniform"));
    }

    #[test]
    fn a_registered_pass_records_again_after_the_device_is_recovered() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let recorded = Arc::new(AtomicU32::new(0));
        let rebuilt = Arc::new(AtomicU32::new(0));
        let app = host("passes").pass(Box::new(Probe {
            recorded: recorded.clone(),
            rebuilt: rebuilt.clone(),
        }));
        let mut frame = bare(app);
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");
        run_one(&mut frame, &gpu, &texture);
        assert_eq!(recorded.load(Ordering::Relaxed), 1);
        assert_eq!(rebuilt.load(Ordering::Relaxed), 1);

        frame.recover(&gpu).expect("recovered");
        run_one(&mut frame, &gpu, &texture);
        assert_eq!(
            rebuilt.load(Ordering::Relaxed),
            2,
            "recovery never rebuilt the application's pass on the new device"
        );
        assert_eq!(
            recorded.load(Ordering::Relaxed),
            2,
            "the recovered presenter no longer records the application's pass"
        );
    }

    #[test]
    fn the_frame_callback_reads_the_sections_the_previous_frame_recorded() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let seen: Arc<Mutex<Vec<&'static str>>> = Arc::new(Mutex::new(Vec::new()));
        let reported = seen.clone();
        let app = host("sections")
            .pass(Box::new(Probe {
                recorded: Arc::new(AtomicU32::new(0)),
                rebuilt: Arc::new(AtomicU32::new(0)),
            }))
            .on_frame(move |hook| {
                let mut names = reported.lock().unwrap_or_else(|error| error.into_inner());
                names.clear();
                names.extend(hook.sections.iter().map(|section| section.name));
            });
        let mut frame = bare(app);
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");

        run_one(&mut frame, &gpu, &texture);
        run_one(&mut frame, &gpu, &texture);

        let names = seen.lock().unwrap_or_else(|error| error.into_inner());
        assert!(
            names.contains(&"probe") && names.contains(&"present-draw"),
            "the callback ran after the presenter cleared its sections: {names:?}"
        );
    }

    #[test]
    fn an_input_command_updates_the_eye_before_publication() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let published: Arc<Mutex<Option<Eye>>> = Arc::new(Mutex::new(None));
        let recorded = published.clone();
        let mut step = 0.0_f32;
        let app = host::<Bare>("camera")
            .on_input(move |hook| {
                step += 1.0;
                let eye = Eye::looking_at([step, 2.0, 3.0], [0.0; 3], [0.0, 1.0, 0.0]);
                hook.sender.app_fn("camera", move |dispatch| {
                    let aspect = dispatch.views.root_mut().eye.aspect;
                    dispatch.views.root_mut().eye = Eye { aspect, ..eye };
                });
            })
            .on_frame(move |hook| {
                let root = hook.session.views().root();
                let eye = hook.session.views().get(root).map(|view| view.eye);
                *recorded.lock().unwrap_or_else(|error| error.into_inner()) = eye;
            });
        let mut frame = bare(app);
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");

        run_one(&mut frame, &gpu, &texture);
        run_one(&mut frame, &gpu, &texture);

        let published = published
            .lock()
            .unwrap_or_else(|error| error.into_inner())
            .expect("the frame hook read the published eye");
        assert_eq!(
            frame.inner.presented,
            Some(published),
            "the presenter did not use the eye committed before publication"
        );
    }

    #[test]
    fn a_post_from_one_frame_is_not_flushed_again_on_the_next() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let mut frames = 0_u32;
        let app = host::<Bare>("posts").on_frame(move |hook| {
            frames += 1;
            if frames == 1 {
                hook.post("rect", &[1.0, 2.0, 3.0, 4.0]);
                hook.post("ready", &[]);
            }
        });
        let mut frame = bare(app);
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");

        run_one(&mut frame, &gpu, &texture);
        let posted: Vec<(&str, Vec<f32>)> = frame
            .posts()
            .map(|(topic, values)| (topic, values.to_vec()))
            .collect();
        assert_eq!(
            posted,
            [("rect", vec![1.0, 2.0, 3.0, 4.0]), ("ready", Vec::new())]
        );

        run_one(&mut frame, &gpu, &texture);
        assert_eq!(frame.posts().count(), 0);
    }

    #[test]
    fn a_publication_with_no_views_is_reported_once_per_frame() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let app = host::<Bare>("no views");
        let mut session = Session::new(Bare::default(), SimConfig::default());
        session.register_domain(DomainBuilder::new("r3", EuclideanR3));
        let mut frame = Frame::new(session, app).expect("the frame accepted the simulation config");
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");
        let start = Instant::now();
        for millis in 0..3 {
            run_at(
                &mut frame,
                &gpu,
                &texture,
                start + Duration::from_millis(millis),
            );
        }

        let lines: Vec<String> = frame
            .app_mut()
            .console_mut()
            .ui()
            .history()
            .iter()
            .map(|line| line.text.clone())
            .collect();
        assert_eq!(
            lines
                .iter()
                .filter(|line| line.contains("published no views"))
                .count(),
            1,
            "the viewless publication was not reported exactly once: {lines:?}"
        );
    }

    #[test]
    fn a_frame_between_ticks_draws_the_body_at_the_elapsed_fraction_of_the_tick() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let mut session = Session::new(Bare::default(), SimConfig::default());
        let r3 = session
            .register_domain(DomainBuilder::new("r3", EuclideanR3).tracked(LogCapacity::default()));
        let geometry = session.prepare(PreparedGeometry::Lines3 {
            segments: vec![[[0.1, 0.0, 0.0], [-0.1, 0.0, 0.0]]],
        });
        let material = session.add_material(Material::flat([1.0; 4]));
        let root = session.views().root();
        let body = session
            .dispatch(|dispatch| {
                let eye = dispatch.spawn(SpawnBundle::new().at(r3, Pose::at(Vec3::Z * 4.0)))?;
                dispatch
                    .domains
                    .typed(r3)?
                    .add_view(ViewSpec::new(root, eye, Identity3))?;
                dispatch.spawn(
                    SpawnBundle::new()
                        .at(r3, Pose::at(Vec3::ZERO))
                        .instance(loam_runtime::Instance::new(geometry, material)),
                )
            })
            .expect("the body spawned");
        session.system(
            Phase::Simulation,
            "move",
            move |ctx: loam_runtime::Ctx<'_, Bare>| {
                if ctx.step.tick == Tick(0) {
                    ctx.domains.typed(r3)?.set_pose(body, Pose::at(Vec3::X))?;
                }
                Ok(())
            },
        );
        let mut frame = Frame::new(session, host("alpha")).expect("the frame accepted the config");
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");
        let start = Instant::now();
        let dt = Duration::from_nanos(1_000_000_000 / u64::from(SimConfig::default().fixed_hz));
        run_at(&mut frame, &gpu, &texture, start);
        run_at(&mut frame, &gpu, &texture, start + dt * 3 / 2);

        let publication = frame.inner.records.lend().expect("the buffer is free");
        let x = publication.views[0].records.instances.rows()[0]
            .pose
            .coordinates[0];
        assert!((x - 0.5).abs() < 1e-3, "the body was drawn at x = {x}");
    }

    #[test]
    fn a_zero_rate_config_pauses_the_frame_and_a_config_without_catch_up_is_refused() {
        let paused =
            loam_runtime::SimConfig::new(0, 2).expect("a zero rate is documented as paused");
        let app = host::<Bare>("paused");
        let session = Session::new(Bare::default(), paused);
        assert!(Frame::new(session, app).is_ok());
        assert!(matches!(
            loam_runtime::SimConfig::new(60, 0),
            Err(loam_runtime::SimConfigError::NoCatchUp)
        ));
    }

    #[test]
    fn a_publication_phase_eye_write_keeps_the_frame_aspect() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let app = host::<Bare>("aspect");
        let mut session = Session::new(Bare::default(), SimConfig::default());
        session.register_domain(DomainBuilder::new("r3", EuclideanR3));
        session.system(
            Phase::Publication,
            "camera",
            |ctx: loam_runtime::Ctx<'_, Bare>| {
                ctx.views.root_mut().eye =
                    Eye::looking_at([0.0, 2.0, 5.0], [0.0; 3], [0.0, 1.0, 0.0]);
                Ok(())
            },
        );
        let mut frame = Frame::new(session, app).expect("the frame accepted the simulation config");
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");
        run_at(&mut frame, &gpu, &texture, Instant::now());

        let root = frame.inner.session.views().root();
        let aspect = frame.inner.session.views().get(root).unwrap().eye.aspect;
        assert!(
            (aspect - SIZE.0 as f32 / SIZE.1 as f32).abs() <= 1e-6,
            "a Publication-phase eye write published aspect {aspect}"
        );
    }

    #[test]
    fn installed_reset_key_recovers_the_fault_and_restores_cursor_capture_once() {
        const RESET: ActionId = ActionId(0);

        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let recorded = Arc::new(AtomicU32::new(0));
        let filled = Arc::new(AtomicU32::new(0));
        let fills = filled.clone();
        let app = quiet(SessionApp::<Bare>::with_args(
            HostConfig::new(
                "fault recovery",
                Bindings::new().key(Key::Letter('r'), RESET),
            ),
            Args::default(),
        ))
        .recover_on_fault(RESET)
        .pass(Box::new(Probe {
            recorded: recorded.clone(),
            rebuilt: Arc::new(AtomicU32::new(0)),
        }))
        .on_frame(move |hook| {
            fills.fetch_add(1, Ordering::Relaxed);
            hook.capture_cursor(true, CursorPolicy::Toggle);
        });
        let mut session = Session::new(Bare::default(), SimConfig::default());
        let r3 = session
            .register_domain(DomainBuilder::new("r3", EuclideanR3).tracked(LogCapacity::default()));
        let root = session.views().root();
        session
            .dispatch(|dispatch| {
                let eye = dispatch.spawn(SpawnBundle::new().at(r3, Pose::at(Vec3::ZERO)))?;
                dispatch
                    .domains
                    .typed(r3)?
                    .add_view(ViewSpec::new(root, eye, Identity3))?;
                Ok::<_, loam_runtime::Rejection>(())
            })
            .expect("view");
        let armed = Arc::new(AtomicBool::new(false));
        let trip = armed.clone();
        session.system(
            Phase::Publication,
            "trip",
            move |_ctx: loam_runtime::Ctx<'_, Bare>| {
                if trip.swap(false, Ordering::Relaxed) {
                    return Err(loam_runtime::DomainError::ChartBoundary);
                }
                Ok(())
            },
        );
        session.system(
            Phase::Dispatch,
            "authored reset",
            |ctx: loam_runtime::Ctx<'_, Bare>| {
                if ctx.input.pressed(RESET) {
                    ctx.commands.submit(Command::Reset);
                }
                Ok(())
            },
        );
        session.set_initial().expect("initial state");
        let epoch = session.scene().epoch();
        let mut frame = Frame::new(session, app).expect("the frame accepted the simulation config");
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");
        let start = Instant::now();
        let expected_sections = ["scene-pass", "triangles", "present-draw", "probe"];

        run_at(&mut frame, &gpu, &texture, start);
        assert_eq!(
            frame
                .presenter
                .as_ref()
                .expect("the presenter attached")
                .sections()
                .iter()
                .map(|section| section.name)
                .collect::<Vec<_>>(),
            expected_sections
        );
        assert_eq!(frame.take_cursor_request(), Some(true));
        frame.cursor_applied(true);
        armed.store(true, Ordering::Relaxed);
        run_at(&mut frame, &gpu, &texture, start + Duration::from_millis(1));
        assert_eq!(
            frame
                .presenter
                .as_ref()
                .expect("the presenter attached")
                .sections()
                .iter()
                .map(|section| section.name)
                .collect::<Vec<_>>(),
            expected_sections
        );
        assert_eq!(
            frame.phase_error().map(|error| error.phase),
            Some(Phase::Publication)
        );
        assert_eq!(filled.load(Ordering::Relaxed), 1);
        assert_eq!(recorded.load(Ordering::Relaxed), 2);
        assert_eq!(frame.take_cursor_request(), Some(false));
        frame.cursor_applied(false);
        for millis in 2_u64..=4 {
            run_at(
                &mut frame,
                &gpu,
                &texture,
                start + Duration::from_millis(millis),
            );
            assert_eq!(
                frame
                    .presenter
                    .as_ref()
                    .expect("the presenter attached")
                    .sections()
                    .iter()
                    .map(|section| section.name)
                    .collect::<Vec<_>>(),
                expected_sections
            );
        }
        assert_eq!(recorded.load(Ordering::Relaxed), 5);

        frame.action(Key::Letter('r'), true, false);
        run_at(&mut frame, &gpu, &texture, start + Duration::from_secs(60));
        assert_eq!(recorded.load(Ordering::Relaxed), 6);
        assert_eq!(filled.load(Ordering::Relaxed), 2);

        assert_eq!(frame.phase_error(), None);
        assert_eq!(frame.inner.session.scene().epoch(), epoch.advance());
        assert_eq!(frame.inner.session.current_tick(), Tick(0));
        assert_eq!(filled.load(Ordering::Relaxed), 2);
        assert_eq!(frame.take_cursor_request(), Some(true));
        run_at(
            &mut frame,
            &gpu,
            &texture,
            start + Duration::from_secs(60) + Duration::from_millis(1),
        );
        assert_eq!(frame.inner.session.scene().epoch(), epoch.advance());
    }

    #[test]
    fn a_scripted_line_reaches_its_verb_on_the_frame_the_script_names() {
        let gpu = noop_gpu();
        let texture = offscreen(&gpu);
        let directory = tempfile::tempdir().expect("temp dir");
        let path = directory.path().join("demo.script");
        std::fs::write(&path, "0 mark first\n2 mark second\n").expect("wrote the script");

        let marked: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
        let recorded = marked.clone();
        let args = Args::from_argv([format!("--script={}", path.display())]);
        let app = quiet(SessionApp::<Bare>::with_args(
            HostConfig::new("script", Bindings::new()),
            args,
        ))
        .command("mark", "record a marker", move |args, _submit, _out| {
            recorded
                .lock()
                .unwrap_or_else(|error| error.into_inner())
                .push(args.join(" "));
            Ok(())
        });
        let mut frame = bare(app);
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");

        let mut after_each = Vec::new();
        for _ in 0..3 {
            run_one(&mut frame, &gpu, &texture);
            after_each.push(
                marked
                    .lock()
                    .unwrap_or_else(|error| error.into_inner())
                    .len(),
            );
        }

        assert_eq!(
            after_each,
            [1, 1, 2],
            "the host drove the script off its own frame index"
        );
        assert_eq!(
            *marked.lock().unwrap_or_else(|error| error.into_inner()),
            ["first", "second"]
        );
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    #[test]
    #[ignore = "requires a working wgpu adapter; run with --include-ignored"]
    fn a_capture_from_the_session_host_writes_the_targets_pixels_gpu_probe() {
        let instance = Instance::default();
        let gpu = pollster::block_on(GpuContext::new(instance, FeatureRequest::default(), None))
            .expect("a wgpu adapter");
        let texture = offscreen(&gpu);
        let directory = tempfile::tempdir().expect("temp dir");
        let app = host("capture")
            .capture(crate::capture::CaptureRequest::OneShot {
                stage: crate::capture::CaptureStage::Post,
                dir: Some(directory.path().to_path_buf()),
                name: Some("session".into()),
            })
            .expect("capture supported");
        let mut frame = bare(app);
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");
        run_one(&mut frame, &gpu, &texture);
        drop(frame);

        let written = directory.path().join("session_post.png");
        let decoded = ::image::open(&written).expect("the capture wrote a png");
        assert_eq!(
            (decoded.width(), decoded.height()),
            SIZE,
            "the capture read a different rectangle than the presenter's target"
        );
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    #[test]
    #[ignore = "requires a working wgpu adapter; run with --include-ignored"]
    fn pre_capture_excludes_the_overlay_that_post_capture_includes_gpu_probe() {
        let instance = Instance::default();
        let gpu = pollster::block_on(GpuContext::new(instance, FeatureRequest::default(), None))
            .expect("a wgpu adapter");
        let texture = offscreen(&gpu);
        let directory = tempfile::tempdir().expect("temp dir");
        let app = host("capture stages")
            .pass(Box::new(Paint {
                name: "red scene",
                color: Color {
                    r: 1.0,
                    g: 0.0,
                    b: 0.0,
                    a: 1.0,
                },
                overlay: false,
                pipeline: None,
            }))
            .pass(Box::new(Paint {
                name: "green overlay",
                color: Color {
                    r: 0.0,
                    g: 1.0,
                    b: 0.0,
                    a: 1.0,
                },
                overlay: true,
                pipeline: None,
            }))
            .capture(crate::capture::CaptureRequest::OneShot {
                stage: crate::capture::CaptureStage::Both,
                dir: Some(directory.path().to_path_buf()),
                name: Some("stages".into()),
            })
            .expect("capture supported");
        let mut frame = bare(app);
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");
        run_one(&mut frame, &gpu, &texture);

        let pre = ::image::open(directory.path().join("stages_pre.png"))
            .expect("the pre capture")
            .to_rgba8();
        let post = ::image::open(directory.path().join("stages_post.png"))
            .expect("the post capture")
            .to_rgba8();
        assert_eq!(pre.get_pixel(0, 0).0, [255, 0, 0, 255]);
        assert_eq!(post.get_pixel(0, 0).0, [0, 255, 0, 255]);
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    #[test]
    #[ignore = "requires a working wgpu adapter; run with --include-ignored"]
    fn a_hook_that_stops_its_capture_finishes_the_file_gpu_probe() {
        let instance = Instance::default();
        let gpu = pollster::block_on(GpuContext::new(instance, FeatureRequest::default(), None))
            .expect("a wgpu adapter");
        let texture = offscreen(&gpu);
        let directory = tempfile::tempdir().expect("temp dir");
        let into = directory.path().to_path_buf();
        let mut frames = 0_u32;
        let app = host::<Bare>("capture").on_frame(move |hook| {
            frames += 1;
            if frames == 1 {
                hook.capture
                    .start(crate::capture::CaptureRequest::StartSequence {
                        format: crate::capture::CaptureFormat::Apng,
                        stage: crate::capture::CaptureStage::Post,
                        dir: Some(into.clone()),
                        name: Some("session".into()),
                        fps: Some(CAPTURE_FPS),
                        scale: None,
                        palette: crate::capture::PaletteMode::default(),
                    })
                    .expect("capture supported");
            }
            if frames == 3 {
                hook.capture.stop().expect("capture supported");
            }
        });
        let mut frame = bare(app);
        frame
            .attach(&gpu, FORMAT, None, SIZE, 1.0)
            .expect("attached");
        for _ in 0..4 {
            run_one(&mut frame, &gpu, &texture);
            std::thread::sleep(Duration::from_millis(1000 / u64::from(CAPTURE_FPS) + 4));
        }
        drop(frame);

        let written = directory.path().join("session.apng");
        let bytes = std::fs::read(&written).expect("the stopped capture finished its file");
        assert_eq!(
            animation_frames(&bytes),
            Some(2),
            "the file holds the frames drawn between the start and the stop"
        );
    }

    #[cfg(all(feature = "capture", not(target_arch = "wasm32")))]
    fn animation_frames(png: &[u8]) -> Option<u32> {
        let mut at = 8;
        while at + 12 <= png.len() {
            let length = u32::from_be_bytes(png[at..at + 4].try_into().ok()?) as usize;
            if &png[at + 4..at + 8] == b"acTL" {
                return Some(u32::from_be_bytes(png[at + 8..at + 12].try_into().ok()?));
            }
            at += 12 + length;
        }
        None
    }
}