bevy_director 0.7.0-dev

//! The runtime: who renders, when, and what the camera does about it.
//! One state machine (DirectorState.phase): Idle until asked, Shooting
//! while a sequence owns the frame, Handback while it glides to the live
//! camera, Viewfinder while a human flies. All mutation happens in
//! PostUpdate before transform propagation, so a pose written this frame
//! renders this frame.

use bevy::{
    camera::Exposure,
    core_pipeline::prepass::MotionVectorPrepass,
    post_process::{
        dof::{DepthOfField, DepthOfFieldMode},
        effect_stack::{ChromaticAberration, LensDistortion, Vignette},
        motion_blur::MotionBlur,
    },
    prelude::*,
    render::view::ColorGrading,
};

use crate::{
    eval::{
        ActiveActorCue, ActiveText, CameraPose, CameraSnapshot, CompiledSequence, EvalCtx, bake,
        mix,
    },
    letterbox::LetterboxSettings,
    sequence::{Blend, SequenceAsset},
};

/// The optional dedicated camera. Spawn your own and the director adopts
/// it for every take; without one the director borrows the gameplay
/// camera and drives it in place, so clear color, tonemapping, bloom,
/// and the rest of your post stack are never swapped out from under the
/// frame. The marker rides the borrowed camera for the length of a take.
#[derive(Component, Default)]
pub struct CineCamera;

/// Optional marker naming the gameplay camera to hand off from and back
/// to, for apps with several non-cine cameras. With exactly one active
/// camera the director finds it by itself.
#[derive(Component)]
pub struct HandoffCamera;

/// Playback state for a sequence, on the cine camera entity.
#[derive(Component)]
pub struct SequencePlayer {
    pub sequence: Handle<SequenceAsset>,
    pub playhead: f32,
    pub rate: f32,
    pub playback: Playback,
    pub clock: ClockSource,
    pub loop_mode: LoopMode,
}

impl SequencePlayer {
    pub fn new(sequence: Handle<SequenceAsset>) -> Self {
        Self {
            sequence,
            playhead: 0.0,
            rate: 1.0,
            playback: Playback::Playing,
            clock: ClockSource::default(),
            loop_mode: LoopMode::default(),
        }
    }

    /// Jump the playhead. Seeks never fire markers.
    pub fn seek(&mut self, t: f32) {
        self.playhead = t.max(0.0);
    }
}

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Playback {
    Stopped,
    #[default]
    Playing,
    Paused,
}

/// Which clock advances the playhead. Virtual freezes with the game's
/// pause; Real keeps rolling through it.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum ClockSource {
    #[default]
    Virtual,
    Real,
}

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum LoopMode {
    #[default]
    Once,
    Loop,
    /// Bounce between the ends, flipping the rate.
    PingPong,
}

/// What the director is doing right now. A plain resource: map it onto
/// your own game states however you like.
#[derive(Resource, Default)]
pub struct DirectorState {
    pub phase: DirectorPhase,
    /// The camera on air right now: the take's anchor, or whichever
    /// named [`CineCamera`] the current shot cut to. Titles and the
    /// letterbox follow this one.
    pub camera: Option<Entity>,
    /// Where the take's playback lives — resolved when it started and
    /// never moved by a cut. Equal to `camera` outside a cut.
    pub anchor: Option<Entity>,
    /// The gameplay camera the director took the frame from.
    pub live_camera: Option<Entity>,
}

impl DirectorState {
    /// True while the gameplay camera is the one being driven, rather
    /// than a separate cine camera it handed the frame to.
    pub fn is_borrowing(&self) -> bool {
        self.anchor.is_some() && self.anchor == self.live_camera
    }

    /// The camera carrying the take's playback state. Falls back to
    /// `camera` for apps that drive [`DirectorState`] by hand.
    pub fn take_anchor(&self) -> Option<Entity> {
        self.anchor.or(self.camera)
    }
}

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum DirectorPhase {
    #[default]
    Idle,
    Shooting,
    Handback,
    Viewfinder,
}

/// The text blocks visible this frame, fades resolved, refreshed during
/// [`DirectorSet::Apply`](crate::DirectorSet); empty whenever nothing is
/// on. This is the whole contract for custom caption rendering: read it
/// and draw. The `titles` feature ships a built-in renderer over the
/// same data.
#[derive(Resource, Default, Debug, Clone)]
pub struct ActiveTexts {
    pub blocks: Vec<ActiveText>,
}

/// The actor cues the playhead is inside this frame, weights resolved,
/// refreshed during [`DirectorSet::Apply`](crate::DirectorSet); empty
/// whenever no take runs. This is the whole actor-track contract: the
/// game reads it, matches each cue's `Entity(name)` target against its
/// own entities, and drives its own animation setup — deriving start and
/// stop edges from the stable `(track, cue_index)` pair. There are
/// deliberately no per-cue messages: a level-triggered resource survives
/// seeks, skips, loops, and reverse playback with no cursor bookkeeping.
#[derive(Resource, Default, Debug, Clone)]
pub struct ActiveActorCues {
    pub cues: Vec<ActiveActorCue>,
}

/// Run condition: no directed camera work at all.
pub fn director_idle(state: Res<DirectorState>) -> bool {
    state.phase == DirectorPhase::Idle
}

/// Run condition: a sequence or the viewfinder owns the frame.
pub fn director_active(state: Res<DirectorState>) -> bool {
    state.phase != DirectorPhase::Idle
}

/// Run condition for the game's own camera-driving system: true while the
/// gameplay camera should keep moving. That includes Handback, where the
/// director chases the live camera, so keep your rig running under this.
///
/// This is for games with their own [`CineCamera`]. When the director
/// borrows the gameplay camera there is nothing to chase — it glides
/// back to the pose it took over — so a rig writing that same transform
/// through Handback fights the blend; gate those on [`director_idle`].
pub fn gameplay_camera_free(state: Res<DirectorState>) -> bool {
    matches!(state.phase, DirectorPhase::Idle | DirectorPhase::Handback)
}

// ---------- messages ----------

/// A sequence took the frame. `camera` is the take's anchor, which is
/// stable across cuts; [`SequenceCut`] reports the camera on air.
#[derive(Message, Debug, Clone)]
pub struct SequenceStarted {
    pub camera: Entity,
    pub sequence: AssetId<SequenceAsset>,
}

/// The take cut to a different camera. Stingers, rumble, and anything
/// else that should land on the cut belong here.
#[derive(Message, Debug, Clone)]
pub struct SequenceCut {
    pub from: Entity,
    pub to: Entity,
    /// The shot that owns the playhead after the cut.
    pub shot: usize,
}

/// The playhead crossed a marker while playing forward.
#[derive(Message, Debug, Clone)]
pub struct MarkerReached {
    pub camera: Entity,
    pub name: String,
    pub time: f32,
}

/// The sequence gave the frame back (or is about to glide it back).
#[derive(Message, Debug, Clone)]
pub struct SequenceFinished {
    pub camera: Entity,
    pub reason: FinishReason,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum FinishReason {
    Completed,
    Skipped,
    Stopped,
}

/// Internal control-channel messages, written by DirectorCommands.
#[derive(Message)]
pub(crate) enum DirectorRequest {
    Play {
        handle: Handle<SequenceAsset>,
        options: PlayOptions,
    },
    Skip,
    Stop,
}

/// Tuning for one playback.
#[derive(Clone, Debug)]
pub struct PlayOptions {
    pub rate: f32,
    pub clock: ClockSource,
    pub loop_mode: LoopMode,
    /// Overrides the asset's blend_out when set.
    pub blend_out: Option<Blend>,
    /// Crop the take to this aspect (e.g. 2.39 for scope) with real
    /// letterbox bars; cleared when the take ends.
    pub letterbox: Option<f32>,
}

impl Default for PlayOptions {
    fn default() -> Self {
        Self {
            rate: 1.0,
            clock: ClockSource::default(),
            loop_mode: LoopMode::default(),
            blend_out: None,
            letterbox: None,
        }
    }
}

/// Fire-and-forget control surface on Commands.
pub trait DirectorCommands {
    fn play_sequence(&mut self, handle: Handle<SequenceAsset>);
    fn play_sequence_with(&mut self, handle: Handle<SequenceAsset>, options: PlayOptions);
    /// Jump to the end and take the normal blend_out home.
    fn skip_sequence(&mut self);
    /// Hard stop: instant swap back to the live camera.
    fn stop_sequence(&mut self);
}

impl DirectorCommands for Commands<'_, '_> {
    fn play_sequence(&mut self, handle: Handle<SequenceAsset>) {
        self.play_sequence_with(handle, PlayOptions::default());
    }

    fn play_sequence_with(&mut self, handle: Handle<SequenceAsset>, options: PlayOptions) {
        self.queue(move |world: &mut World| {
            world.write_message(DirectorRequest::Play { handle, options });
        });
    }

    fn skip_sequence(&mut self) {
        self.queue(|world: &mut World| {
            world.write_message(DirectorRequest::Skip);
        });
    }

    fn stop_sequence(&mut self) {
        self.queue(|world: &mut World| {
            world.write_message(DirectorRequest::Stop);
        });
    }
}

// ---------- internal components ----------

/// The compiled sequence and the live-camera snapshot it blends from.
#[derive(Component)]
pub(crate) struct Baked {
    pub(crate) compiled: CompiledSequence,
    pub(crate) live: CameraSnapshot,
    /// Marker cursor: starts just below zero so a t=0 marker fires.
    pub(crate) marker_cursor: f32,
    pub(crate) blend_out: Option<Blend>,
    /// The last pose applied: feeds damped looks and seeds the handback.
    pub(crate) last_pose: Option<CameraPose>,
    /// Which lens components the director currently owns on the camera.
    pub(crate) lens_active: LensTouch,
    /// A softened held camera's smoothed world rotation, chased frame to
    /// frame. Cleared on a cut so it never slerps across mounts.
    pub(crate) held_rot: Option<Quat>,
    /// Camera names a cut could not resolve, so the warning is said
    /// once instead of every frame the shot is on screen.
    pub(crate) warned_cameras: Vec<String>,
}

/// Which lens components a take is driving. The director only issues
/// commands for the ones a shot actually uses, and a component the pose
/// just dropped still needs its one frame of removal.
#[derive(Clone, Copy, Default, Debug, PartialEq, Eq)]
pub(crate) struct LensTouch {
    dof: bool,
    exposure: bool,
    vignette: bool,
    distortion: bool,
    aberration: bool,
    motion_blur: bool,
    grading: bool,
}

impl LensTouch {
    pub(crate) fn of(pose: &CameraPose) -> Self {
        Self {
            dof: pose.dof.is_some(),
            exposure: pose.exposure_ev100.is_some(),
            vignette: pose.vignette.is_some(),
            distortion: pose.distortion.is_some(),
            aberration: pose.aberration.is_some(),
            motion_blur: pose.motion_blur.is_some(),
            grading: pose.grading.is_some(),
        }
    }

    pub(crate) fn union(self, other: Self) -> Self {
        Self {
            dof: self.dof || other.dof,
            exposure: self.exposure || other.exposure,
            vignette: self.vignette || other.vignette,
            distortion: self.distortion || other.distortion,
            aberration: self.aberration || other.aberration,
            motion_blur: self.motion_blur || other.motion_blur,
            grading: self.grading || other.grading,
        }
    }
}

/// A play request waiting for its asset to finish loading.
#[derive(Component)]
pub(crate) struct PendingPlay {
    handle: Handle<SequenceAsset>,
    options: PlayOptions,
}

/// The glide home at the end: from a frozen pose toward the live camera,
/// sampled fresh every frame.
#[derive(Component)]
pub(crate) struct HandbackBlend {
    from: CameraPose,
    elapsed: f32,
    blend: Blend,
    clock: ClockSource,
}

/// Everything the director will touch on the take camera, copied off
/// before the first pose lands and put back when the take ends. It lives
/// on the camera rather than in [`DirectorState`] so a mid-take despawn
/// takes the restore data with it instead of leaving it stale.
#[derive(Component)]
pub(crate) struct PreTakeState {
    transform: Transform,
    /// The whole projection, not just the fov: letterboxing writes
    /// `aspect_ratio` too.
    projection: Projection,
    viewport: Option<bevy::camera::Viewport>,
    dof: Option<DepthOfField>,
    exposure: Option<Exposure>,
    vignette: Option<Vignette>,
    distortion: Option<LensDistortion>,
    aberration: Option<ChromaticAberration>,
    motion_blur: Option<MotionBlur>,
    /// MotionBlur requires a MotionVectorPrepass, which bevy inserts for
    /// us but never takes back; the restore has to know whether the
    /// prepass was the game's to begin with.
    had_motion_vector_prepass: bool,
    /// The grade the take composes onto, and puts back untouched.
    grading: Option<ColorGrading>,
    role: TakeRole,
}

/// What a camera is to the take, which decides how much of it is owed
/// back when the take ends.
#[derive(Clone, Copy, PartialEq, Eq)]
pub(crate) enum TakeRole {
    /// The gameplay camera, driven in place: it gets its pose back, and
    /// the [`CineCamera`] marker the director stamped on comes off.
    Borrowed,
    /// A camera the game dedicated to the director. It keeps its last
    /// pose, the way the viewfinder leaves it parked where you flew it.
    Dedicated,
    /// A camera a cut visits. The game placed it and may use it for its
    /// own shots, so the take puts it back where it found it.
    CutTarget,
}

impl PreTakeState {
    /// The grade the camera had before the take, for composing onto.
    /// The previews reach for this; the runtime reads the field.
    #[cfg(feature = "viewfinder")]
    pub(crate) fn grading(&self) -> Option<&ColorGrading> {
        self.grading.as_ref()
    }

    /// The camera's own parked pose, for Held rigs in the previews.
    #[cfg(feature = "viewfinder")]
    pub(crate) fn held_snapshot(&self) -> CameraSnapshot {
        snapshot_of(&self.transform, Some(&self.projection))
    }
}

/// Snapshot the camera state a take is about to overwrite. Borrowing
/// also stamps the [`CineCamera`] marker, which is what lets every
/// `With<CineCamera>` query downstream stay as it was.
pub(crate) fn begin_take(role: TakeRole) -> impl EntityCommand {
    move |mut entity: EntityWorldMut| {
        let borrowed = role == TakeRole::Borrowed;
        let saved = PreTakeState {
            transform: entity.get::<Transform>().copied().unwrap_or_default(),
            projection: entity.get::<Projection>().cloned().unwrap_or_default(),
            viewport: entity.get::<Camera>().and_then(|c| c.viewport.clone()),
            dof: entity.get::<DepthOfField>().cloned(),
            exposure: entity.get::<Exposure>().cloned(),
            vignette: entity.get::<Vignette>().cloned(),
            distortion: entity.get::<LensDistortion>().cloned(),
            aberration: entity.get::<ChromaticAberration>().cloned(),
            motion_blur: entity.get::<MotionBlur>().cloned(),
            had_motion_vector_prepass: entity.contains::<MotionVectorPrepass>(),
            grading: entity.get::<ColorGrading>().cloned(),
            role,
        };
        if borrowed && entity.contains::<ChildOf>() {
            warn!(
                "the gameplay camera is parented; directed poses are world space and will \
                 fight its parent. Spawn a CineCamera entity for this game."
            );
        }
        entity.insert(saved);
        if borrowed {
            entity.insert(CineCamera);
        }
    }
}

/// Put back everything [`begin_take`] saved and strip the playback
/// components. Without a `PreTakeState` (a camera the director never
/// captured, e.g. one an app drives through `DirectorState` by hand)
/// this is just the strip.
fn end_take(mut entity: EntityWorldMut) {
    entity.remove::<(
        SequencePlayer,
        Baked,
        HandbackBlend,
        PendingPlay,
        SkipRequested,
        LetterboxSettings,
    )>();
    let Some(saved) = entity.take::<PreTakeState>() else {
        // Nothing captured: the lens components are still the director's.
        // The motion vector prepass stays — on a camera we never looked
        // at, we cannot tell ours from the game's, and an extra prepass
        // only costs time where a wrong removal breaks its rendering.
        entity.remove::<(
            DepthOfField,
            Exposure,
            Vignette,
            LensDistortion,
            ChromaticAberration,
            MotionBlur,
            ColorGrading,
        )>();
        return;
    };
    if let Some(mut camera) = entity.get_mut::<Camera>() {
        camera.viewport = saved.viewport;
    }
    if let Some(mut projection) = entity.get_mut::<Projection>() {
        *projection = saved.projection;
    }
    restore_component(&mut entity, saved.dof);
    restore_component(&mut entity, saved.exposure);
    restore_component(&mut entity, saved.vignette);
    restore_component(&mut entity, saved.distortion);
    restore_component(&mut entity, saved.aberration);
    restore_component(&mut entity, saved.motion_blur);
    restore_component(&mut entity, saved.grading);
    if !saved.had_motion_vector_prepass {
        entity.remove::<MotionVectorPrepass>();
    }
    if saved.role != TakeRole::Dedicated {
        entity.insert(saved.transform);
    }
    if saved.role == TakeRole::Borrowed {
        entity.remove::<CineCamera>();
    }
}

/// Put a captured component back, or take ours off when the camera had
/// none of its own.
fn restore_component<C: Component>(entity: &mut EntityWorldMut, saved: Option<C>) {
    match saved {
        Some(component) => {
            entity.insert(component);
        }
        None => {
            entity.remove::<C>();
        }
    }
}

// ---------- systems ----------

pub(crate) fn snapshot_of(
    transform: &Transform,
    projection: Option<&Projection>,
) -> CameraSnapshot {
    let fov_y = match projection {
        Some(Projection::Perspective(p)) => p.fov,
        _ => 45f32.to_radians(),
    };
    CameraSnapshot {
        position: transform.translation,
        rotation: transform.rotation,
        fov_y,
    }
}

/// Find the gameplay camera to hand off from: prefer HandoffCamera, else
/// the unique active non-cine 3D camera.
fn resolve_live_camera(
    cameras: &Query<(Entity, &Camera, Has<HandoffCamera>), (With<Camera3d>, Without<CineCamera>)>,
) -> Option<Entity> {
    if let Some((e, ..)) = cameras.iter().find(|(_, _, marked)| *marked) {
        return Some(e);
    }
    let mut actives = cameras.iter().filter(|(_, cam, _)| cam.is_active);
    let first = actives.next().map(|(e, ..)| e);
    if actives.next().is_some() {
        warn!("several active cameras and no HandoffCamera marker; picking one arbitrarily");
    }
    first
}

/// Spawn a cine camera from nothing. Only reached when the app has no
/// camera at all to borrow and none marked CineCamera, so it is bare
/// bones by definition. The active flag rides the bundle because a
/// same-frame get_mut cannot see an entity whose commands have not
/// flushed yet.
fn spawn_fallback_cine_camera(commands: &mut Commands, active: bool) -> Entity {
    commands
        .spawn((
            Name::new("cine camera"),
            CineCamera,
            Camera3d::default(),
            Camera {
                is_active: active,
                ..Default::default()
            },
            Projection::default(),
            Transform::default(),
        ))
        .id()
}

/// Drain control requests. Play resolves cameras, bakes (or parks a
/// PendingPlay until the asset arrives), snapshots the live pose, and
/// swaps is_active in this one place so the two flags never disagree.
#[allow(clippy::too_many_arguments)] // the control hub touches everything
pub(crate) fn handle_requests(
    mut commands: Commands,
    mut requests: MessageReader<DirectorRequest>,
    mut state: ResMut<DirectorState>,
    assets: Res<Assets<SequenceAsset>>,
    // p0 reads cameras to pick the live one; p1 writes is_active. A
    // ParamSet because they overlap on Camera.
    mut cameras: ParamSet<(
        Query<(Entity, &Camera, Has<HandoffCamera>), (With<Camera3d>, Without<CineCamera>)>,
        Query<&mut Camera>,
    )>,
    cine_cameras: Query<(Entity, Option<&Name>), With<CineCamera>>,
    pending: Query<(Entity, &PendingPlay)>,
    mut players: Query<(&mut SequencePlayer, Option<&Baked>)>,
    transforms: Query<(&Transform, Option<&Projection>)>,
    mut started: MessageWriter<SequenceStarted>,
    mut finished: MessageWriter<SequenceFinished>,
) {
    // Retry a parked play once its asset shows up.
    let retry: Option<(Handle<SequenceAsset>, PlayOptions, Entity)> = pending
        .iter()
        .next()
        .filter(|(_, p)| assets.contains(&p.handle))
        .map(|(e, p)| (p.handle.clone(), p.options.clone(), e));
    let mut plays: Vec<(Handle<SequenceAsset>, PlayOptions)> = Vec::new();
    if let Some((handle, options, entity)) = retry {
        commands.entity(entity).remove::<PendingPlay>();
        plays.push((handle, options));
    }

    for request in requests.read() {
        match request {
            DirectorRequest::Play { handle, options } => {
                plays.push((handle.clone(), options.clone()));
            }
            DirectorRequest::Skip => {
                if state.phase == DirectorPhase::Shooting
                    && let Some(camera) = state.take_anchor()
                    && let Ok((mut player, baked)) = players.get_mut(camera)
                    && let Some(baked) = baked
                {
                    // Jump to the end; the tick system routes the finish.
                    player.playhead = baked.compiled.duration();
                    player.playback = Playback::Playing;
                    player.loop_mode = LoopMode::Once;
                    finished.write(SequenceFinished {
                        camera,
                        reason: FinishReason::Skipped,
                    });
                    commands.entity(camera).insert(SkipRequested);
                }
            }
            DirectorRequest::Stop => {
                if state.phase == DirectorPhase::Shooting || state.phase == DirectorPhase::Handback
                {
                    if let Some(camera) = state.take_anchor() {
                        finished.write(SequenceFinished {
                            camera,
                            reason: FinishReason::Stopped,
                        });
                    }
                    let mut writable = cameras.p1();
                    restore_live(&mut commands, &mut state, &mut writable);
                }
            }
        }
    }

    for (handle, options) in plays {
        if state.phase != DirectorPhase::Idle {
            warn!(
                "play_sequence ignored: the director is already {:?}",
                state.phase
            );
            continue;
        }
        let live_entity = resolve_live_camera(&cameras.p0());

        let Some(asset) = assets.get(&handle) else {
            // Not loaded yet: park the request wherever the take will
            // land, without claiming the camera. The retry re-resolves.
            let holder = cine_cameras
                .iter()
                .next()
                .map(|(e, _)| e)
                .or(live_entity)
                .unwrap_or_else(|| spawn_fallback_cine_camera(&mut commands, false));
            commands.entity(holder).insert(PendingPlay {
                handle: handle.clone(),
                options,
            });
            continue;
        };
        let compiled = match bake(asset) {
            Ok(compiled) => compiled,
            Err(err) => {
                error!("sequence '{}' failed to bake: {err}", asset.name);
                continue;
            }
        };

        // A cine camera the sequence cuts to is a destination, not the
        // take's own camera; anything else is a dedicated camera to
        // adopt. With none to adopt the gameplay camera is driven where
        // it stands, so its render settings never leave the frame. A
        // fresh fallback spawns already active because the swap below
        // can only reach cameras that exist.
        let existing = cine_cameras
            .iter()
            .find(|(_, name)| name.is_none_or(|name| !compiled.cuts_to(name.as_str())))
            .map(|(e, _)| e);
        let borrowed = existing.is_none() && live_entity.is_some();
        let cine = existing
            .or(live_entity)
            .unwrap_or_else(|| spawn_fallback_cine_camera(&mut commands, true));

        let live = live_entity
            .and_then(|e| transforms.get(e).ok())
            .map(|(t, p)| snapshot_of(t, p))
            .unwrap_or(CameraSnapshot {
                position: Vec3::ZERO,
                rotation: Quat::IDENTITY,
                fov_y: 45f32.to_radians(),
            });

        let blend_out = options.blend_out.or(compiled.blend_out());
        let mut cine_commands = commands.entity(cine);
        cine_commands.queue(begin_take(if borrowed {
            TakeRole::Borrowed
        } else {
            TakeRole::Dedicated
        }));
        cine_commands.insert((
            SequencePlayer {
                sequence: handle.clone(),
                playhead: 0.0,
                rate: options.rate,
                playback: Playback::Playing,
                clock: options.clock,
                loop_mode: options.loop_mode,
            },
            Baked {
                compiled,
                live,
                marker_cursor: -f32::EPSILON,
                blend_out,
                last_pose: None,
                lens_active: LensTouch::default(),
                held_rot: None,
                warned_cameras: Vec::new(),
            },
        ));
        if let Some(aspect) = options.letterbox {
            cine_commands.insert(LetterboxSettings { aspect });
        }

        // The swap: exactly one camera active, flipped together. A
        // borrowed camera is already the one on air.
        if !borrowed {
            let mut writable = cameras.p1();
            if let Some(live_entity) = live_entity
                && let Ok(mut cam) = writable.get_mut(live_entity)
            {
                cam.is_active = false;
            }
            if let Ok(mut cam) = writable.get_mut(cine) {
                cam.is_active = true;
            }
        }

        state.phase = DirectorPhase::Shooting;
        state.camera = Some(cine);
        state.anchor = Some(cine);
        state.live_camera = live_entity;
        started.write(SequenceStarted {
            camera: cine,
            sequence: handle.id(),
        });
    }
}

/// Skip was requested this frame; suppresses the Completed message when
/// the tick routes the finish.
#[derive(Component)]
pub(crate) struct SkipRequested;

/// Hot reload: rebake when the asset file changes under a live player.
pub(crate) fn rebake_on_asset_change(
    mut events: MessageReader<AssetEvent<SequenceAsset>>,
    assets: Res<Assets<SequenceAsset>>,
    mut players: Query<(&mut SequencePlayer, &mut Baked)>,
) {
    for event in events.read() {
        let AssetEvent::Modified { id } = event else {
            continue;
        };
        for (mut player, mut baked) in &mut players {
            if player.sequence.id() != *id {
                continue;
            }
            let Some(asset) = assets.get(*id) else {
                continue;
            };
            match bake(asset) {
                Ok(compiled) => {
                    player.playhead = player.playhead.min(compiled.duration());
                    baked.compiled = compiled;
                    info!("sequence '{}' rebaked from disk", asset.name);
                }
                Err(err) => error!("sequence '{}' failed to rebake: {err}", asset.name),
            }
        }
    }
}

/// If the cine camera (or its player) vanished mid-flight, put the live
/// camera back on air. This is what keeps a quit-to-title mid-cutscene
/// from black-screening the menu.
pub(crate) fn guard_orphans(
    mut commands: Commands,
    mut state: ResMut<DirectorState>,
    players: Query<&SequencePlayer>,
    mut cameras: Query<&mut Camera>,
    mut finished: MessageWriter<SequenceFinished>,
) {
    if state.phase == DirectorPhase::Idle {
        return;
    }
    // A cut target vanishing is survivable — the cut falls back to the
    // anchor — but losing the anchor loses the take.
    let camera_gone = if state.phase == DirectorPhase::Viewfinder {
        state.camera.is_none_or(|e| cameras.get(e).is_err())
    } else {
        state.take_anchor().is_none_or(|e| players.get(e).is_err())
    };
    if !camera_gone {
        return;
    }
    if let Some(camera) = state.take_anchor() {
        finished.write(SequenceFinished {
            camera,
            reason: FinishReason::Stopped,
        });
    }
    restore_live(&mut commands, &mut state, &mut cameras);
}

/// Back to Idle: the camera the take borrowed or was handed goes back to
/// what it was, playback components gone. Safe against despawned
/// entities on either side.
pub(crate) fn restore_live(
    commands: &mut Commands,
    state: &mut DirectorState,
    cameras: &mut Query<&mut Camera>,
) {
    // Only ever dark a cine camera in favour of a live one; otherwise a
    // take that had the only camera in the scene ends in black. A cut
    // may have left the borrowed anchor dark, so it is relit here too.
    if let Some(live) = state.live_camera {
        if let Ok(mut cam) = cameras.get_mut(live) {
            cam.is_active = true;
        }
        for cine in [state.camera, state.anchor].into_iter().flatten() {
            if cine != live
                && let Ok(mut cam) = cameras.get_mut(cine)
            {
                cam.is_active = false;
            }
        }
    }
    // Every camera the take touched carries its own PreTakeState, cut
    // targets included, and the query only yields the ones still alive.
    // The anchor joins them even without one, so a hand-driven
    // DirectorState still gets its playback components stripped.
    let anchor = state.take_anchor();
    commands.queue(move |world: &mut World| {
        let mut captured: Vec<Entity> = world
            .query_filtered::<Entity, With<PreTakeState>>()
            .iter(world)
            .collect();
        if let Some(anchor) = anchor
            && !captured.contains(&anchor)
        {
            captured.push(anchor);
        }
        for camera in captured {
            if let Ok(entity) = world.get_entity_mut(camera) {
                end_take(entity);
            }
        }
    });
    state.phase = DirectorPhase::Idle;
    state.camera = None;
    state.anchor = None;
    state.live_camera = None;
}

/// Advance playheads, fire markers, and route the end of the sequence
/// into a handback (or an instant swap when there is no blend_out).
pub(crate) fn tick_players(
    mut commands: Commands,
    mut state: ResMut<DirectorState>,
    virtual_time: Res<Time<Virtual>>,
    real_time: Res<Time<Real>>,
    mut players: Query<(Entity, &mut SequencePlayer, &mut Baked, Has<SkipRequested>)>,
    mut cameras: Query<&mut Camera>,
    mut markers: MessageWriter<MarkerReached>,
    mut finished: MessageWriter<SequenceFinished>,
) {
    if state.phase != DirectorPhase::Shooting {
        return;
    }
    let Some(camera) = state.take_anchor() else {
        return;
    };
    let Ok((entity, mut player, mut baked, skipping)) = players.get_mut(camera) else {
        return;
    };
    if player.playback != Playback::Playing {
        return;
    }
    // A take that ends while cut away has nothing to glide: the named
    // camera is not the one the game is getting back.
    let cut_away = state.camera != Some(camera);

    let dt = match player.clock {
        ClockSource::Virtual => virtual_time.delta_secs(),
        ClockSource::Real => real_time.delta_secs(),
    } * player.rate;
    player.playhead += dt;

    let duration = baked.compiled.duration();
    let cursor = baked.marker_cursor;

    if !skipping {
        let fire = |m: &crate::sequence::Marker, markers: &mut MessageWriter<MarkerReached>| {
            markers.write(MarkerReached {
                camera: entity,
                name: m.name.clone(),
                time: m.time,
            });
        };
        if dt >= 0.0 {
            for marker in baked.compiled.markers_between(cursor, player.playhead) {
                fire(marker, &mut markers);
            }
        } else {
            for marker in baked
                .compiled
                .markers_between_backward(player.playhead, cursor)
            {
                fire(marker, &mut markers);
            }
        }
    }
    baked.marker_cursor = player.playhead;

    let over = dt >= 0.0 && player.playhead >= duration;
    let under = dt < 0.0 && player.playhead <= 0.0;
    if !over && !under {
        return;
    }

    match player.loop_mode {
        LoopMode::Loop => {
            let wrapped = if over {
                // Tail markers fired above; fire the head range too.
                let wrapped = (player.playhead - duration).max(0.0);
                if !skipping {
                    for marker in baked.compiled.markers_between(-f32::EPSILON, wrapped) {
                        markers.write(MarkerReached {
                            camera: entity,
                            name: marker.name.clone(),
                            time: marker.time,
                        });
                    }
                }
                wrapped
            } else {
                (player.playhead + duration).clamp(0.0, duration)
            };
            player.playhead = wrapped;
            baked.marker_cursor = wrapped;
        }
        LoopMode::PingPong => {
            player.rate = -player.rate;
            player.playhead = if over {
                (2.0 * duration - player.playhead).clamp(0.0, duration)
            } else {
                (-player.playhead).clamp(0.0, duration)
            };
            baked.marker_cursor = player.playhead;
        }
        LoopMode::Once => {
            player.playhead = if over { duration } else { 0.0 };
            player.playback = Playback::Stopped;
            if !skipping {
                finished.write(SequenceFinished {
                    camera: entity,
                    reason: FinishReason::Completed,
                });
            }
            match baked.blend_out {
                Some(blend) if blend.secs > 0.0 && !cut_away => {
                    // Start the glide from the last pose actually shown.
                    let from = baked.last_pose.unwrap_or_else(|| {
                        baked
                            .compiled
                            .pose_at(player.playhead, &EvalCtx::still(&baked.live))
                    });
                    commands.entity(entity).insert(HandbackBlend {
                        from,
                        elapsed: 0.0,
                        blend,
                        clock: player.clock,
                    });
                    state.phase = DirectorPhase::Handback;
                }
                _ => restore_live(&mut commands, &mut state, &mut cameras),
            }
        }
    }
}

/// Put the shot's named camera on air. Runs before the pose lands, so
/// the cut, the frame it shows, and the letterbox crop all agree.
///
/// The take's playback never moves: only which camera renders does.
/// Cutting to a camera the world does not have holds the anchor rather
/// than cutting to black.
#[allow(clippy::too_many_arguments)] // a cut touches every camera-shaped thing
pub(crate) fn execute_cuts(
    mut commands: Commands,
    mut state: ResMut<DirectorState>,
    mut players: Query<(&SequencePlayer, &mut Baked)>,
    named: Query<(Entity, &Name), With<CineCamera>>,
    mut cameras: Query<&mut Camera>,
    letterbox: Query<&LetterboxSettings>,
    captured: Query<(), With<PreTakeState>>,
    mut cuts: MessageWriter<SequenceCut>,
) {
    if state.phase != DirectorPhase::Shooting {
        return;
    }
    let (Some(anchor), Some(current)) = (state.take_anchor(), state.camera) else {
        return;
    };
    let Ok((player, mut baked)) = players.get_mut(anchor) else {
        return;
    };

    let playhead = player.playhead;
    let wanted = baked.compiled.camera_at(playhead).map(str::to_owned);
    let mut target = match &wanted {
        None => anchor,
        Some(name) => match named.iter().find(|(_, n)| n.as_str() == name.as_str()) {
            Some((entity, _)) => entity,
            None => {
                if !baked.warned_cameras.iter().any(|seen| seen == name) {
                    baked.warned_cameras.push(name.clone());
                    warn!(
                        "shot at {playhead:.2}s cuts to CineCamera '{name}', which no entity \
                         carries; staying on the take's camera"
                    );
                }
                anchor
            }
        },
    };
    // A cut target that despawned mid-shot must not take the frame down
    // with it.
    if target != anchor && cameras.get(target).is_err() {
        target = anchor;
    }
    if target == current {
        return;
    }

    // A camera the take has not used yet keeps its own settings: capture
    // them before the pose and lens land on it.
    if !captured.contains(target) {
        commands
            .entity(target)
            .queue(begin_take(TakeRole::CutTarget));
    }
    if let Ok(mut cam) = cameras.get_mut(current) {
        cam.is_active = false;
    }
    if let Ok(mut cam) = cameras.get_mut(target) {
        cam.is_active = true;
    }
    // The crop belongs to the frame, so it follows the cut.
    if let Ok(settings) = letterbox.get(current) {
        commands.entity(current).remove::<LetterboxSettings>();
        commands.entity(target).insert(*settings);
    }
    // Damped looks and softened mounts reseed instead of chasing the
    // other camera's rotation.
    baked.last_pose = None;
    baked.held_rot = None;
    cuts.write(SequenceCut {
        from: current,
        to: target,
        shot: baked.compiled.shot_index(playhead),
    });
    state.camera = Some(target);
}

/// Write the evaluated pose onto the cine camera: transform, fov, and
/// the lens components (depth of field, exposure) when the shot asks.
/// During handback, chase the live camera's fresh pose (the game's rig
/// runs and we glide to it).
/// Soften a held camera's mount: chase the mount's world rotation with
/// an exponential decay instead of inheriting every jolt, then hand the
/// result back in the camera's local space, which is what gets written.
/// Position stays welded — a gimbal keeps its mount point, and a
/// first-order position filter would trail the mount at any steady speed.
fn soften_mount(
    baked: &mut Baked,
    pose: &mut CameraPose,
    playhead: f32,
    dt: f32,
    mount: Option<Quat>,
) {
    let (Some(decay), Some(mount)) = (baked.compiled.held_damping_at(playhead), mount) else {
        // Welded, or nothing to be mounted on.
        baked.held_rot = None;
        return;
    };
    let target = mount * pose.rotation;
    let mut smoothed = baked.held_rot.unwrap_or(target);
    if dt > 0.0 {
        smoothed.smooth_nudge(&target, decay, dt);
    } else {
        smoothed = target;
    }
    baked.held_rot = Some(smoothed);
    pose.rotation = mount.inverse() * smoothed;
}

#[allow(clippy::too_many_arguments)] // the frame's one write-out
pub(crate) fn apply_pose(
    mut commands: Commands,
    mut state: ResMut<DirectorState>,
    virtual_time: Res<Time<Virtual>>,
    real_time: Res<Time<Real>>,
    // The pose lands on whichever camera is on air; the playback state
    // driving it stays put on the anchor across cuts. Disjoint
    // components, so the two may name the same entity.
    mut driven: Query<(&mut Transform, &mut Projection, Option<&PreTakeState>), With<CineCamera>>,
    mut playback: Query<(
        Option<(&SequencePlayer, &mut Baked)>,
        Option<&mut HandbackBlend>,
    )>,
    live: Query<(&Transform, Option<&Projection>), Without<CineCamera>>,
    names: Query<(&Name, &GlobalTransform)>,
    parents: Query<&ChildOf>,
    globals: Query<&GlobalTransform>,
    mut cameras: Query<&mut Camera>,
) {
    let Some(camera) = state.camera else {
        return;
    };
    let Some(anchor) = state.take_anchor() else {
        return;
    };
    let (borrowed, pre_take_pose, base_grading) = match driven.get(camera) {
        Ok((_, _, pre_take)) => (
            pre_take.is_some_and(|p| p.role == TakeRole::Borrowed),
            pre_take.map(|p| snapshot_of(&p.transform, Some(&p.projection))),
            pre_take.and_then(|p| p.grading.clone()),
        ),
        Err(_) => return,
    };
    let Ok((playing, handback)) = playback.get_mut(anchor) else {
        return;
    };
    // Name positions are last frame's globals: fine for aim targets.
    let resolve = |wanted: &str| {
        names
            .iter()
            .find(|(name, _)| name.as_str() == wanted)
            .map(|(_, gt)| gt.translation())
    };

    let (pose, lens_flags) = match state.phase {
        DirectorPhase::Shooting => {
            let Some((player, mut baked)) = playing else {
                return;
            };
            let dt = match player.clock {
                ClockSource::Virtual => virtual_time.delta_secs(),
                ClockSource::Real => real_time.delta_secs(),
            };
            let ctx = EvalCtx {
                live: &baked.live,
                dt,
                prev_rot: baked.last_pose.map(|p| p.rotation),
                resolve_entity: &resolve,
                // The on-air camera's parked pose: Held shots ride it.
                held: pre_take_pose,
            };
            let mut pose = baked.compiled.pose_at(player.playhead, &ctx);
            baked.last_pose = Some(pose);
            // The mount's world rotation is last frame's — propagation
            // runs after us — which is a frame of lag inside a filter
            // built to lag.
            let mount = parents
                .get(camera)
                .ok()
                .and_then(|child_of| globals.get(child_of.parent()).ok())
                .map(|global| global.rotation());
            soften_mount(&mut baked, &mut pose, player.playhead, dt, mount);
            let touch = LensTouch::of(&pose);
            // What the shot wants plus what it just dropped: the union
            // is the one frame a removal needs.
            let flags = Some(touch.union(baked.lens_active));
            baked.lens_active = touch;
            (pose, flags)
        }
        DirectorPhase::Handback => {
            let Some(mut handback) = handback else {
                return;
            };
            handback.elapsed += match handback.clock {
                ClockSource::Virtual => virtual_time.delta_secs(),
                ClockSource::Real => real_time.delta_secs(),
            };
            // Borrowing, there is no second camera to chase: glide back
            // to the pose the take took over, which is also what the
            // restore writes, so the last blended frame is the landing.
            let target = if borrowed {
                pre_take_pose
            } else {
                state
                    .live_camera
                    .and_then(|e| live.get(e).ok())
                    .map(|(t, p)| snapshot_of(t, p))
            }
            .unwrap_or(CameraSnapshot {
                position: handback.from.position,
                rotation: handback.from.rotation,
                fov_y: handback.from.fov_y,
            });
            let target = CameraPose::from_snapshot(&target);
            let w = handback
                .blend
                .ease
                .sample_clamped((handback.elapsed / handback.blend.secs).clamp(0.0, 1.0));
            let pose = mix(&handback.from, &target, w);
            if handback.elapsed >= handback.blend.secs {
                restore_live(&mut commands, &mut state, &mut cameras);
            }
            (pose, None)
        }
        _ => return,
    };

    let Ok((mut transform, mut projection, _)) = driven.get_mut(camera) else {
        return;
    };
    transform.translation = pose.position;
    transform.rotation = pose.rotation;
    if let Projection::Perspective(perspective) = &mut *projection {
        perspective.fov = pose.fov_y;
    }

    if let Some(touch) = lens_flags {
        apply_lens_components(&mut commands, camera, &pose, touch, base_grading.as_ref());
    }
}

/// Put the pose's lens components on the camera, taking off the ones it
/// no longer asks for. Only the flagged components are touched, so a
/// shot with no lens work issues no commands at all.
///
/// Grading composes: the shot's offsets ride on top of `base_grading`,
/// the grade the camera had before the take, so a game's own look is
/// still there underneath a graded shot.
pub(crate) fn apply_lens_components(
    commands: &mut Commands,
    camera: Entity,
    pose: &CameraPose,
    touch: LensTouch,
    base_grading: Option<&ColorGrading>,
) {
    if touch.dof {
        match pose.dof {
            Some(d) => {
                commands.entity(camera).insert(DepthOfField {
                    mode: if d.bokeh {
                        DepthOfFieldMode::Bokeh
                    } else {
                        DepthOfFieldMode::Gaussian
                    },
                    focal_distance: d.focal_distance,
                    aperture_f_stops: d.aperture_f_stops,
                    sensor_height: d.sensor_height,
                    ..Default::default()
                });
            }
            None => {
                commands.entity(camera).remove::<DepthOfField>();
            }
        }
    }
    if touch.exposure {
        match pose.exposure_ev100 {
            Some(ev100) => {
                commands.entity(camera).insert(Exposure { ev100 });
            }
            None => {
                commands.entity(camera).remove::<Exposure>();
            }
        }
    }
    if touch.vignette {
        match pose.vignette {
            Some(intensity) => {
                commands.entity(camera).insert(Vignette {
                    intensity,
                    ..Default::default()
                });
            }
            None => {
                commands.entity(camera).remove::<Vignette>();
            }
        }
    }
    if touch.distortion {
        match pose.distortion {
            Some(intensity) => {
                commands.entity(camera).insert(LensDistortion {
                    intensity,
                    ..Default::default()
                });
            }
            None => {
                commands.entity(camera).remove::<LensDistortion>();
            }
        }
    }
    if touch.aberration {
        match pose.aberration {
            Some(intensity) => {
                commands.entity(camera).insert(ChromaticAberration {
                    intensity,
                    ..Default::default()
                });
            }
            None => {
                commands.entity(camera).remove::<ChromaticAberration>();
            }
        }
    }
    if touch.motion_blur {
        match pose.motion_blur {
            Some(spec) => {
                commands.entity(camera).insert(MotionBlur {
                    shutter_angle: spec.shutter_angle,
                    samples: spec.samples,
                });
            }
            // The prepass MotionBlur required stays until the take ends,
            // where the restore knows whose it was.
            None => {
                commands.entity(camera).remove::<MotionBlur>();
            }
        }
    }
    if touch.grading {
        match pose.grading {
            Some(grade) => {
                let mut grading = base_grading.cloned().unwrap_or_default();
                grading.global.exposure += grade.exposure;
                grading.global.temperature += grade.temperature;
                grading.global.tint += grade.tint;
                grading.global.post_saturation *= grade.saturation;
                commands.entity(camera).insert(grading);
            }
            // Mid-take the game's own grade goes back on; a camera that
            // never had one renders with bevy's default either way.
            None => match base_grading {
                Some(saved) => {
                    commands.entity(camera).insert(saved.clone());
                }
                None => {
                    commands.entity(camera).remove::<ColorGrading>();
                }
            },
        }
    }
}

/// Refresh [`ActiveTexts`] from the playing take. Level-triggered off
/// the playhead, so seeks, loops, and reverse playback just work. The
/// viewfinder phase is deliberately left alone: the editor's session
/// writer owns the resource there.
pub(crate) fn update_active_texts(
    state: Res<DirectorState>,
    players: Query<(&SequencePlayer, &Baked)>,
    mut active: ResMut<ActiveTexts>,
) {
    match state.phase {
        DirectorPhase::Shooting => {
            let playing = state
                .take_anchor()
                .and_then(|camera| players.get(camera).ok());
            match playing {
                Some((player, baked)) => {
                    // Don't dirty the resource while it stays empty.
                    if baked.compiled.texts().is_empty() && active.blocks.is_empty() {
                        return;
                    }
                    let blocks = &mut active.blocks;
                    baked.compiled.active_texts_into(player.playhead, blocks);
                }
                None => {
                    if !active.blocks.is_empty() {
                        active.blocks.clear();
                    }
                }
            }
        }
        DirectorPhase::Viewfinder => {}
        _ => {
            if !active.blocks.is_empty() {
                active.blocks.clear();
            }
        }
    }
}

/// Refresh [`ActiveActorCues`] from the playing take: the actor twin of
/// [`update_active_texts`], with the same rules — level-triggered off
/// the playhead, cleared outside Shooting (a skip empties it the same
/// frame the finish routes), and left alone during Viewfinder where the
/// editor's session writer owns it.
pub(crate) fn update_active_actor_cues(
    state: Res<DirectorState>,
    players: Query<(&SequencePlayer, &Baked)>,
    mut active: ResMut<ActiveActorCues>,
) {
    match state.phase {
        DirectorPhase::Shooting => {
            let playing = state
                .take_anchor()
                .and_then(|camera| players.get(camera).ok());
            match playing {
                Some((player, baked)) => {
                    // Don't dirty the resource while it stays empty.
                    if baked.compiled.actors().is_empty() && active.cues.is_empty() {
                        return;
                    }
                    let cues = &mut active.cues;
                    baked.compiled.active_actor_cues_into(player.playhead, cues);
                }
                None => {
                    if !active.cues.is_empty() {
                        active.cues.clear();
                    }
                }
            }
        }
        DirectorPhase::Viewfinder => {}
        _ => {
            if !active.cues.is_empty() {
                active.cues.clear();
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::DirectorPlugin;
    use crate::sequence::*;
    use bevy::app::App;
    use bevy::asset::AssetPlugin;
    use bevy::time::TimeUpdateStrategy;
    use std::time::Duration;

    fn test_sequence(blend_out: Option<Blend>) -> SequenceAsset {
        SequenceAsset {
            name: "test".into(),
            shots: vec![Shot {
                start: 0.0,
                duration: 0.1,
                blend_in: None,
                rig: Rig::Keys {
                    keys: vec![Key {
                        time: 0.0,
                        pos: Vec3::new(5.0, 0.0, 0.0),
                        rot: Some(Quat::IDENTITY),
                        ease: EaseFunction::Linear,
                    }],
                    interp: KeyInterp::Eased,
                },
                look: Look::Free,
                lens: Lens::default(),
                shake: None,
                camera: None,
            }],
            markers: vec![Marker {
                time: 0.05,
                name: "beat".into(),
            }],
            texts: vec![],
            actors: vec![],
            blend_out,
        }
    }

    /// One gameplay camera and nothing else: the director borrows it.
    fn test_app() -> (App, Entity, Handle<SequenceAsset>) {
        let mut app = App::new();
        app.add_plugins((MinimalPlugins, AssetPlugin::default(), DirectorPlugin));
        app.insert_resource(TimeUpdateStrategy::ManualDuration(Duration::from_millis(
            16,
        )));
        let live = app
            .world_mut()
            .spawn((
                Camera3d::default(),
                Camera::default(),
                Projection::default(),
                Transform::from_xyz(0.0, 9.0, 0.0),
            ))
            .id();
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(test_sequence(None));
        (app, live, handle)
    }

    /// A game that brought its own cine camera: the director adopts it
    /// and swaps the frame over.
    fn test_app_dedicated() -> (App, Entity, Entity, Handle<SequenceAsset>) {
        let (mut app, live, handle) = test_app();
        let cine = app
            .world_mut()
            .spawn((
                CineCamera,
                Camera3d::default(),
                Camera {
                    is_active: false,
                    ..Default::default()
                },
                Projection::default(),
                Transform::default(),
            ))
            .id();
        (app, live, cine, handle)
    }

    fn phase(app: &App) -> DirectorPhase {
        app.world().resource::<DirectorState>().phase
    }

    fn is_active(app: &mut App, e: Entity) -> bool {
        app.world().get::<Camera>(e).unwrap().is_active
    }

    #[test]
    fn play_swaps_is_active_and_finishes() {
        let (mut app, live, cine, handle) = test_app_dedicated();
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        assert_eq!(phase(&app), DirectorPhase::Shooting);
        assert!(!is_active(&mut app, live));
        assert_eq!(app.world().resource::<DirectorState>().camera, Some(cine));
        assert!(is_active(&mut app, cine));
        // 0.1 s sequence at 16 ms steps: done well within 20 frames.
        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert!(is_active(&mut app, live));
        assert!(!is_active(&mut app, cine));
        // The pose landed on the cine camera while it was shooting.
        let t = app.world().get::<Transform>(cine).unwrap();
        assert_eq!(t.translation.x, 5.0);
    }

    #[test]
    fn borrow_drives_the_gameplay_camera_and_puts_it_back() {
        let (mut app, live, handle) = test_app();
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        // No second camera: the game's own is the one being directed.
        let state = app.world().resource::<DirectorState>();
        assert!(state.is_borrowing());
        assert_eq!(state.camera, Some(live));
        assert_eq!(
            app.world_mut()
                .query::<&Camera3d>()
                .iter(app.world())
                .count(),
            1
        );
        // It never goes dark, and it is driven where it stands.
        assert!(is_active(&mut app, live));
        assert_eq!(
            app.world().get::<Transform>(live).unwrap().translation.x,
            5.0
        );

        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert!(is_active(&mut app, live));
        // Pose handed back, marker and bookkeeping gone.
        assert_eq!(
            app.world().get::<Transform>(live).unwrap().translation,
            Vec3::new(0.0, 9.0, 0.0)
        );
        assert!(app.world().get::<CineCamera>(live).is_none());
        assert!(app.world().get::<PreTakeState>(live).is_none());
    }

    #[test]
    fn borrowed_handback_lands_on_the_pose_it_took_over() {
        let (mut app, live, _) = test_app();
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(test_sequence(Some(Blend {
                secs: 0.05,
                ease: EaseFunction::Linear,
            })));
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        for _ in 0..40 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert_eq!(
            app.world().get::<Transform>(live).unwrap().translation,
            Vec3::new(0.0, 9.0, 0.0)
        );
    }

    #[test]
    fn borrow_restores_the_viewport_and_lens_the_game_owned() {
        let (mut app, live, handle) = test_app();
        let viewport = bevy::camera::Viewport {
            physical_position: UVec2::new(4, 8),
            physical_size: UVec2::new(320, 240),
            ..Default::default()
        };
        app.world_mut().entity_mut(live).insert((
            Camera {
                viewport: Some(viewport.clone()),
                ..Default::default()
            },
            Exposure { ev100: 7.0 },
        ));
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions {
                letterbox: Some(2.39),
                ..Default::default()
            },
        });
        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        let camera = app.world().get::<Camera>(live).unwrap();
        assert_eq!(
            camera.viewport.as_ref().map(|v| v.physical_size),
            Some(viewport.physical_size)
        );
        assert_eq!(
            app.world().get::<Exposure>(live).map(|e| e.ev100),
            Some(7.0)
        );
    }

    #[test]
    fn adopted_cine_camera_keeps_its_own_lens() {
        let (mut app, _, cine, handle) = test_app_dedicated();
        app.world_mut()
            .entity_mut(cine)
            .insert(Exposure { ev100: 3.5 });
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert_eq!(
            app.world().get::<Exposure>(cine).map(|e| e.ev100),
            Some(3.5)
        );
    }

    #[test]
    fn borrowed_camera_despawning_mid_take_just_goes_idle() {
        let (mut app, live, handle) = test_app();
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        app.world_mut().entity_mut(live).despawn();
        app.update();
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert_eq!(app.world().resource::<DirectorState>().camera, None);
    }

    #[cfg(feature = "titles")]
    #[test]
    fn director_plugin_installs_the_text_overlay() {
        let (app, ..) = test_app();
        assert!(app.is_plugin_added::<crate::titles::TitlesPlugin>());
    }

    /// A take that uses every filmic track, so the apply and restore
    /// paths are exercised end to end.
    fn filmic_sequence() -> SequenceAsset {
        let mut sequence = test_sequence(None);
        let lens = &mut sequence.shots[0].lens;
        lens.vignette = Some(ScalarTrack::constant(0.6));
        lens.distortion = Some(ScalarTrack::constant(0.15));
        lens.aberration = Some(ScalarTrack::constant(0.04));
        lens.motion_blur = Some(crate::sequence::MotionBlurSpec {
            shutter_angle: 0.5,
            samples: 2,
        });
        sequence
    }

    #[test]
    fn filmic_components_ride_the_take_and_leave_with_it() {
        let (mut app, live, _) = test_app();
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(filmic_sequence());
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        assert_eq!(
            app.world().get::<Vignette>(live).map(|v| v.intensity),
            Some(0.6)
        );
        assert_eq!(
            app.world().get::<LensDistortion>(live).map(|d| d.intensity),
            Some(0.15)
        );
        assert_eq!(
            app.world()
                .get::<ChromaticAberration>(live)
                .map(|a| a.intensity),
            Some(0.04)
        );
        assert_eq!(
            app.world().get::<MotionBlur>(live).map(|m| m.samples),
            Some(2)
        );
        // MotionBlur requires the prepass, so inserting it brought one in.
        assert!(app.world().get::<MotionVectorPrepass>(live).is_some());

        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert!(app.world().get::<Vignette>(live).is_none());
        assert!(app.world().get::<LensDistortion>(live).is_none());
        assert!(app.world().get::<ChromaticAberration>(live).is_none());
        assert!(app.world().get::<MotionBlur>(live).is_none());
        // The prepass was ours, so it goes too.
        assert!(app.world().get::<MotionVectorPrepass>(live).is_none());
    }

    #[test]
    fn motion_blur_leaves_the_games_own_prepass_alone() {
        let (mut app, live, _) = test_app();
        app.world_mut().entity_mut(live).insert(MotionVectorPrepass);
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(filmic_sequence());
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert!(app.world().get::<MotionVectorPrepass>(live).is_some());
    }

    #[test]
    fn grading_composes_over_the_games_grade_and_hands_it_back() {
        let (mut app, live, _) = test_app();
        let mut base = ColorGrading::default();
        base.global.exposure = 1.0;
        base.global.post_saturation = 0.8;
        app.world_mut().entity_mut(live).insert(base);
        let mut sequence = test_sequence(None);
        sequence.shots[0].lens.grading = Some(crate::sequence::GradeTrack {
            exposure: Some(ScalarTrack::constant(2.0)),
            saturation: Some(ScalarTrack::constant(0.5)),
            ..Default::default()
        });
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(sequence);
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        let live_grade = app.world().get::<ColorGrading>(live).unwrap();
        // Offsets add, saturation multiplies: the game's look survives.
        assert_eq!(live_grade.global.exposure, 3.0);
        assert!((live_grade.global.post_saturation - 0.4).abs() < 1e-6);

        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        let restored = app.world().get::<ColorGrading>(live).unwrap();
        assert_eq!(restored.global.exposure, 1.0);
        assert_eq!(restored.global.post_saturation, 0.8);
    }

    /// Two shots: the first on the take's own camera, the second cutting
    /// to a named one.
    fn cut_sequence(name: &str) -> SequenceAsset {
        let mut sequence = test_sequence(None);
        sequence.shots[0].duration = 0.05;
        let mut second = sequence.shots[0].clone();
        second.start = 0.05;
        second.camera = Some(name.to_string());
        if let Rig::Keys { keys, .. } = &mut second.rig {
            keys[0].pos = Vec3::new(-7.0, 0.0, 0.0);
        }
        sequence.shots.push(second);
        sequence.markers.clear();
        sequence
    }

    fn spawn_named_cine(app: &mut App, name: &str) -> Entity {
        app.world_mut()
            .spawn((
                Name::new(name.to_string()),
                CineCamera,
                Camera3d::default(),
                Camera {
                    is_active: false,
                    ..Default::default()
                },
                Projection::default(),
                Transform::from_xyz(0.0, 1.0, 0.0),
            ))
            .id()
    }

    #[test]
    fn a_cut_moves_the_frame_the_letterbox_and_reports_itself() {
        let (mut app, live, _) = test_app();
        let crane = spawn_named_cine(&mut app, "crane");
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(cut_sequence("crane"));
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions {
                letterbox: Some(2.39),
                ..Default::default()
            },
        });
        app.update();
        // Shot one is on the borrowed gameplay camera.
        assert_eq!(app.world().resource::<DirectorState>().camera, Some(live));

        // Run into shot two.
        for _ in 0..4 {
            app.update();
        }
        let state = app.world().resource::<DirectorState>();
        assert_eq!(state.camera, Some(crane));
        // The anchor keeps the playback while the crane takes the frame.
        assert_eq!(state.anchor, Some(live));
        assert!(is_active(&mut app, crane));
        assert!(!is_active(&mut app, live));
        assert!(app.world().get::<LetterboxSettings>(crane).is_some());
        assert!(app.world().get::<LetterboxSettings>(live).is_none());
        assert!(app.world().get::<SequencePlayer>(live).is_some());
        assert_eq!(
            app.world().get::<Transform>(crane).unwrap().translation.x,
            -7.0
        );

        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        // Both cameras come back: the game's on air, the crane where it
        // was parked, neither carrying take state.
        assert!(is_active(&mut app, live));
        assert!(!is_active(&mut app, crane));
        assert!(app.world().get::<PreTakeState>(live).is_none());
        assert!(app.world().get::<PreTakeState>(crane).is_none());
        assert!(app.world().get::<CineCamera>(live).is_none());
        assert_eq!(
            app.world().get::<Transform>(crane).unwrap().translation,
            Vec3::new(0.0, 1.0, 0.0)
        );
        assert_eq!(
            app.world().get::<Transform>(live).unwrap().translation,
            Vec3::new(0.0, 9.0, 0.0)
        );
    }

    #[test]
    fn a_cut_to_a_camera_nobody_has_stays_on_the_take() {
        let (mut app, live, _) = test_app();
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(cut_sequence("nobody"));
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        for _ in 0..5 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Shooting);
        assert_eq!(app.world().resource::<DirectorState>().camera, Some(live));
        assert!(is_active(&mut app, live));
    }

    #[test]
    fn losing_a_cut_target_falls_back_instead_of_ending_the_take() {
        let (mut app, live, _) = test_app();
        let crane = spawn_named_cine(&mut app, "crane");
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(cut_sequence("crane"));
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        for _ in 0..5 {
            app.update();
        }
        assert_eq!(app.world().resource::<DirectorState>().camera, Some(crane));
        app.world_mut().entity_mut(crane).despawn();
        app.update();
        // The anchor still has the playback, so the take survives.
        assert_eq!(phase(&app), DirectorPhase::Shooting);
        assert_eq!(app.world().resource::<DirectorState>().camera, Some(live));
        assert!(is_active(&mut app, live));
    }

    /// A damped mount lags the bike's lean instead of inheriting it, then
    /// settles onto it once the bike holds still. Needs real propagation:
    /// the smoothing reads the mount's GlobalTransform.
    #[test]
    fn a_damped_mount_lags_its_parents_lean_and_settles() {
        let (mut app, _live, _) = test_app();
        app.add_plugins(bevy::transform::TransformPlugin);
        let bike = app.world_mut().spawn(Transform::default()).id();
        let mirror = app
            .world_mut()
            .spawn((
                Name::new("mirror"),
                CineCamera,
                Camera3d::default(),
                Camera {
                    is_active: false,
                    ..Default::default()
                },
                Projection::default(),
                Transform::default(),
                ChildOf(bike),
            ))
            .id();

        let mut sequence = test_sequence(None);
        sequence.shots[0].duration = 0.05;
        let mut held = Shot::held(0.05, 2.0).mount_damping(6.0);
        held.camera = Some("mirror".into());
        sequence.shots.push(held);
        sequence.markers.clear();
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(sequence);
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        // 16 ms a frame: several to reach the held shot and seed it.
        for _ in 0..6 {
            app.update();
        }
        assert_eq!(app.world().resource::<DirectorState>().camera, Some(mirror));

        // Bank the bike hard, then hold it there.
        let lean = Quat::from_rotation_z(0.6);
        app.world_mut().get_mut::<Transform>(bike).unwrap().rotation = lean;
        app.update();
        app.update();
        let local = app.world().get::<Transform>(mirror).unwrap().rotation;
        // Welded would leave the local rotation at identity; a softened
        // mount counter-rotates to hold the frame back.
        assert!(
            local.angle_between(Quat::IDENTITY) > 0.05,
            "the mount never softened: {local:?}"
        );
        assert!(
            (lean * local).angle_between(lean) < 0.6,
            "the camera outran its own mount"
        );

        // Held steady, the smoothing converges and the counter-rotation
        // decays back to nothing.
        for _ in 0..80 {
            app.update();
        }
        let settled = app.world().get::<Transform>(mirror).unwrap().rotation;
        assert!(
            settled.angle_between(Quat::IDENTITY) < 0.02,
            "the mount never settled: {settled:?}"
        );
    }

    #[test]
    fn a_cut_to_a_parented_held_camera_rides_its_mount() {
        let (mut app, _live, _) = test_app();
        let bike = app
            .world_mut()
            .spawn(Transform::from_xyz(0.0, 0.0, 0.0))
            .id();
        let mount = Vec3::new(0.4, 1.0, 0.1);
        let mirror = app
            .world_mut()
            .spawn((
                Name::new("mirror"),
                CineCamera,
                Camera3d::default(),
                Camera {
                    is_active: false,
                    ..Default::default()
                },
                Projection::Perspective(PerspectiveProjection {
                    fov: 1.2,
                    ..Default::default()
                }),
                Transform::from_translation(mount),
                ChildOf(bike),
            ))
            .id();

        let mut sequence = test_sequence(None);
        sequence.shots[0].duration = 0.05;
        let mut second = Shot::held(0.05, 0.2);
        second.camera = Some("mirror".into());
        sequence.shots.push(second);
        sequence.markers.clear();
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(sequence);
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        for _ in 0..5 {
            app.update();
            // The bike rides on regardless of the director.
            app.world_mut()
                .get_mut::<Transform>(bike)
                .unwrap()
                .translation
                .x += 1.0;
        }
        assert_eq!(app.world().resource::<DirectorState>().camera, Some(mirror));
        // The held shot writes the mirror's own parked LOCAL pose back:
        // the mount offset, untouched, while the parent carries it.
        assert_eq!(
            app.world().get::<Transform>(mirror).unwrap().translation,
            mount
        );
        // And the mirror's own fov, not the authored default 45 degrees.
        let Projection::Perspective(p) = app.world().get::<Projection>(mirror).unwrap() else {
            panic!("perspective expected");
        };
        assert_eq!(p.fov, 1.2);

        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert!(app.world().get::<PreTakeState>(mirror).is_none());
        assert_eq!(
            app.world().get::<Transform>(mirror).unwrap().translation,
            mount
        );
    }

    #[test]
    fn a_take_that_ends_cut_away_skips_the_handback() {
        let (mut app, _, _) = test_app();
        spawn_named_cine(&mut app, "crane");
        let mut sequence = cut_sequence("crane");
        sequence.blend_out = Some(Blend {
            secs: 0.2,
            ease: EaseFunction::Linear,
        });
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(sequence);
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        let mut saw_handback = false;
        for _ in 0..40 {
            app.update();
            if phase(&app) == DirectorPhase::Handback {
                saw_handback = true;
            }
        }
        // Gliding a camera the game is not getting back means nothing.
        assert!(!saw_handback);
        assert_eq!(phase(&app), DirectorPhase::Idle);
    }

    #[test]
    fn blend_out_routes_through_handback() {
        let (mut app, live, _) = test_app();
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(test_sequence(Some(Blend {
                secs: 0.05,
                ease: EaseFunction::Linear,
            })));
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        let mut saw_handback = false;
        for _ in 0..40 {
            app.update();
            if phase(&app) == DirectorPhase::Handback {
                saw_handback = true;
            }
        }
        assert!(saw_handback);
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert!(is_active(&mut app, live));
    }

    #[test]
    fn orphan_guard_restores_live_camera() {
        let (mut app, live, cine, handle) = test_app_dedicated();
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        app.world_mut().entity_mut(cine).despawn();
        app.update();
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert!(is_active(&mut app, live));
    }

    #[test]
    fn pause_of_virtual_clock_freezes_playhead() {
        let (mut app, _, handle) = test_app();
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        app.world_mut().resource_mut::<Time<Virtual>>().pause();
        for _ in 0..10 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Shooting);
        let cine = app.world().resource::<DirectorState>().camera.unwrap();
        let head = app.world().get::<SequencePlayer>(cine).unwrap().playhead;
        // One 16 ms step landed before the pause; nothing after.
        assert!(head <= 0.017, "playhead crept to {head}");
    }

    #[derive(Resource, Default)]
    struct MarkerHits(usize);

    fn count_markers(mut hits: ResMut<MarkerHits>, mut reader: MessageReader<MarkerReached>) {
        hits.0 += reader.read().count();
    }

    #[test]
    fn marker_fires_exactly_once() {
        let (mut app, _, handle) = test_app();
        app.init_resource::<MarkerHits>();
        app.add_systems(Update, count_markers);
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        for _ in 0..30 {
            app.update();
        }
        assert_eq!(app.world().resource::<MarkerHits>().0, 1);
    }

    #[test]
    fn active_texts_fill_while_shooting_and_clear_after() {
        let (mut app, _, _) = test_app();
        let mut sequence = test_sequence(None);
        sequence.texts = vec![TextBlock::at(0.0, 0.1, "caption")];
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(sequence);
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        assert_eq!(phase(&app), DirectorPhase::Shooting);
        let active = app.world().resource::<ActiveTexts>();
        assert_eq!(active.blocks.len(), 1);
        assert_eq!(active.blocks[0].block.text, "caption");
        assert_eq!(active.blocks[0].alpha, 1.0);
        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert!(app.world().resource::<ActiveTexts>().blocks.is_empty());
    }

    #[test]
    fn active_actor_cues_fill_while_shooting_and_clear_after() {
        let (mut app, _, _) = test_app();
        let mut sequence = test_sequence(None);
        sequence.actors =
            vec![ActorTrack::entity("player").cue(ActorCue::at(0.0, 0.1, "cutscene.sleeping"))];
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(sequence);
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        assert_eq!(phase(&app), DirectorPhase::Shooting);
        let active = app.world().resource::<ActiveActorCues>();
        assert_eq!(active.cues.len(), 1);
        assert_eq!(active.cues[0].cue.anim, "cutscene.sleeping");
        assert!(matches!(
            &active.cues[0].target,
            crate::sequence::TargetRef::Entity(name) if name == "player"
        ));
        let first_local = active.cues[0].local_time;
        app.update();
        let advanced = app.world().resource::<ActiveActorCues>().cues[0].local_time;
        assert!(advanced > first_local, "local_time never advanced");
        for _ in 0..20 {
            app.update();
        }
        assert_eq!(phase(&app), DirectorPhase::Idle);
        assert!(app.world().resource::<ActiveActorCues>().cues.is_empty());
    }

    #[test]
    fn skip_clears_actor_cues_immediately() {
        let (mut app, _, _) = test_app();
        let mut sequence = test_sequence(None);
        // Long take: without the skip it would still be mid-cue.
        sequence.shots[0].duration = 10.0;
        sequence.actors = vec![ActorTrack::entity("player").cue(ActorCue::at(0.0, 10.0, "sleep"))];
        let handle = app
            .world_mut()
            .resource_mut::<Assets<SequenceAsset>>()
            .add(sequence);
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        assert!(!app.world().resource::<ActiveActorCues>().cues.is_empty());
        app.world_mut().write_message(DirectorRequest::Skip);
        app.update();
        assert!(app.world().resource::<ActiveActorCues>().cues.is_empty());
    }

    #[test]
    fn pingpong_bounces_between_the_ends() {
        let (mut app, _, handle) = test_app();
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions {
                loop_mode: LoopMode::PingPong,
                ..Default::default()
            },
        });
        app.update();
        let cine = app.world().resource::<DirectorState>().camera.unwrap();
        let mut flipped = false;
        for _ in 0..40 {
            app.update();
            let player = app.world().get::<SequencePlayer>(cine).unwrap();
            assert!((-0.001..=0.101).contains(&player.playhead));
            flipped |= player.rate < 0.0;
        }
        assert!(flipped, "the rate never reflected");
        assert_eq!(phase(&app), DirectorPhase::Shooting);
    }

    #[test]
    fn backward_markers_fire_on_the_mirror_rule() {
        let (mut app, _, handle) = test_app();
        app.init_resource::<MarkerHits>();
        app.add_systems(Update, count_markers);
        app.world_mut().write_message(DirectorRequest::Play {
            handle,
            options: PlayOptions::default(),
        });
        app.update();
        let cine = app.world().resource::<DirectorState>().camera.unwrap();
        {
            let mut entity = app.world_mut().entity_mut(cine);
            let duration = entity.get::<Baked>().unwrap().compiled.duration();
            entity.get_mut::<Baked>().unwrap().marker_cursor = duration;
            let mut player = entity.get_mut::<SequencePlayer>().unwrap();
            player.playhead = duration;
            player.rate = -1.0;
        }
        for _ in 0..30 {
            app.update();
        }
        assert_eq!(app.world().resource::<MarkerHits>().0, 1);
        assert_eq!(phase(&app), DirectorPhase::Idle);
    }
}