konjure_web/

session.rs

use konjure_sdk::{Diagnostic, Frame, Runtime};

/// Invalid browser input, or SDK evaluation failure. Inputs are transactional.
#[derive(Debug, thiserror::Error)]
pub enum BrowserError {
    /// Scene time or browser timestamp was negative or non-finite.
    #[error("{0} must be finite and non-negative")]
    InvalidTime(&'static str),
    /// An active clock moved backwards without a lifecycle transition.
    #[error("browser frame timestamp moved backwards")]
    RegressingTimestamp,
    /// The SDK rejected a sampled scene; accepted session time is retained.
    #[error("{0}")]
    Scene(#[from] Diagnostic),
}

/// Explicit input from DOM controls and browser lifecycle events.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum SessionInput {
    /// Play or pause animation, resetting the browser timestamp baseline.
    Playing(bool),
    /// Seek to a finite, non-negative scene time in seconds.
    Seek(f64),
    /// Combined page visibility and viewport intersection state.
    Visible(bool),
    /// Whether the host's graphics context can accept rendering work.
    ContextAvailable(bool),
    /// Whether an immersive XR session actually owns the animation loop.
    Immersive(bool),
}

/// One host-supplied animation callback timestamp, in browser milliseconds.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct FrameInput {
    /// Monotonic `requestAnimationFrame` timestamp within the active clock epoch.
    pub timestamp_ms: f64,
}

/// A validated presentation time; the host owns graphics submission.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct FrameTiming {
    /// Absolute scene time in seconds after this frame.
    pub time_seconds: f64,
    /// Animation step in seconds, capped at 0.1 to avoid catch-up bursts.
    pub delta_seconds: f64,
    /// False for a lost context or a hidden inline view.
    pub should_render: bool,
}

/// Lifecycle and clock of a browser view, independent of DOM object ownership.
#[derive(Clone, Debug)]
pub struct BrowserSession {
    time_seconds: f64,
    previous_ms: Option<f64>,
    playing: bool,
    visible: bool,
    context_available: bool,
    immersive: bool,
}

impl BrowserSession {
    /// Create an inline, visible view with an available graphics context at time zero.
    pub fn new(playing: bool) -> Self {
        Self {
            time_seconds: 0.0,
            previous_ms: None,
            playing,
            visible: true,
            context_available: true,
            immersive: false,
        }
    }

    /// Apply a lifecycle input; suspension and clock-owner transitions reset the baseline.
    ///
    /// # Errors
    /// A seek to negative or non-finite time is rejected without changing state.
    pub fn apply(&mut self, input: SessionInput) -> Result<(), BrowserError> {
        let changed = match input {
            SessionInput::Playing(value) => {
                self.playing = value;
                true
            }
            SessionInput::Seek(value) => {
                check_time(value, "scene time")?;
                self.time_seconds = value;
                true
            }
            SessionInput::Visible(value) => replace_if_changed(&mut self.visible, value),
            SessionInput::ContextAvailable(value) => {
                replace_if_changed(&mut self.context_available, value)
            }
            SessionInput::Immersive(value) => replace_if_changed(&mut self.immersive, value),
        };
        if changed {
            self.previous_ms = None;
        }
        Ok(())
    }

    /// Whether authored animation is playing, including while temporarily suspended.
    pub fn playing(&self) -> bool {
        self.playing
    }

    /// Current accepted scene time in seconds.
    pub fn time_seconds(&self) -> f64 {
        self.time_seconds
    }

    /// Whether the host may submit a frame in the current lifecycle state.
    pub fn active(&self) -> bool {
        self.context_available && (self.visible || self.immersive)
    }

    /// Validate and advance one frame. The first frame after a transition has zero delta.
    ///
    /// # Errors
    /// Rejects invalid or backwards timestamps, retaining the previous accepted state.
    pub fn frame(&mut self, input: FrameInput) -> Result<FrameTiming, BrowserError> {
        check_time(input.timestamp_ms, "browser timestamp")?;
        let mut delta_seconds = 0.0;
        if self.active() {
            if let Some(previous) = self.previous_ms {
                if input.timestamp_ms < previous {
                    return Err(BrowserError::RegressingTimestamp);
                }
                if self.playing {
                    delta_seconds = ((input.timestamp_ms - previous) / 1000.0).min(0.1);
                }
            }
            let time_seconds = self.time_seconds + delta_seconds;
            check_time(time_seconds, "scene time")?;
            self.time_seconds = time_seconds;
            self.previous_ms = Some(input.timestamp_ms);
        } else {
            self.previous_ms = None;
        }
        Ok(FrameTiming {
            time_seconds: self.time_seconds,
            delta_seconds,
            should_render: self.active(),
        })
    }

    /// Sample an SDK scene using this view's clock, or return `None` while suspended.
    ///
    /// # Errors
    /// Invalid timestamps or rejected SDK frames leave the accepted clock unchanged.
    pub fn sample(
        &mut self,
        runtime: &Runtime,
        input: FrameInput,
    ) -> Result<Option<Frame>, BrowserError> {
        let mut candidate = self.clone();
        let timing = candidate.frame(input)?;
        let frame = timing
            .should_render
            .then(|| runtime.sample(timing.time_seconds))
            .transpose()?;
        *self = candidate;
        Ok(frame)
    }
}

fn check_time(value: f64, label: &'static str) -> Result<(), BrowserError> {
    if !value.is_finite() || value < 0.0 {
        return Err(BrowserError::InvalidTime(label));
    }
    Ok(())
}

fn replace_if_changed(slot: &mut bool, value: bool) -> bool {
    let changed = *slot != value;
    *slot = value;
    changed
}