konjure_sdk/

presentation.rs

//! Portable semantic UI documents and per-view presentation routing.
//!
//! This module describes what an assistant or scene wants to present. Platform
//! adapters own pixels, graphics handles, eye textures, input devices, and room
//! tracking implementations. A [`PresentationPlan`] makes every target view
//! explicit so a stereo adapter cannot accidentally present one monoscopic
//! dialog for both eyes.

use alloc::{string::String, vec, vec::Vec};
use core::fmt;
use serde::{Deserialize, Serialize};

use crate::domain::{Transform, wire_u64};

/// Maximum nodes accepted in one portable UI document.
pub const MAX_UI_NODES: usize = 128;
/// Maximum UTF-8 byte length of a UI identifier, action, or resource name.
pub const MAX_UI_ID_BYTES: usize = 128;
/// Maximum UTF-8 byte length of visible UI text or text input value.
pub const MAX_UI_TEXT_BYTES: usize = 4 * 1024;

macro_rules! identifier {
    ($name:ident, $docs:literal) => {
        #[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
        #[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
        #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
        #[serde(transparent)]
        #[doc = $docs]
        pub struct $name(pub String);
    };
}

identifier!(UiDocumentId, "Owned identifier for a semantic UI document.");
identifier!(
    UiNodeId,
    "Owned identifier for a node within a UI document."
);
identifier!(
    UiResourceId,
    "Opaque identifier for an adapter-resolved image resource."
);
identifier!(
    RoomAnchorId,
    "Identifier for a tracked room anchor supplied by an adapter."
);

/// Opaque application action identifier carried by UI events.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(transparent)]
pub struct UiActionId(pub u32);

/// A named target view; it has no platform graphics handle.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ViewIdentity {
    /// The only view on a monoscopic target.
    Mono,
    /// The left view of a stereo target.
    Left,
    /// The right view of a stereo target.
    Right,
}

/// A positive, half-open rectangular region in adapter-defined logical pixels.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Viewport {
    /// Explicit identity of the view rendered into this region.
    pub view: ViewIdentity,
    /// Horizontal origin in logical pixels.
    pub x: i32,
    /// Vertical origin in logical pixels.
    pub y: i32,
    /// Positive width in logical pixels.
    pub width: u32,
    /// Positive height in logical pixels.
    pub height: u32,
}

/// Adapter-declared presentation topology.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[allow(missing_docs)]
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum DeviceTarget {
    /// One explicitly named monoscopic view.
    Mono {
        surface_width: u32,
        surface_height: u32,
        view: Viewport,
    },
    /// Exactly one left and one right view. Their viewports must not overlap.
    Stereo {
        surface_width: u32,
        surface_height: u32,
        left: Viewport,
        right: Viewport,
    },
}

impl DeviceTarget {
    /// Rejects malformed view identities, empty regions, and overlapping stereo regions.
    ///
    /// # Errors
    ///
    /// Returns an error when the topology cannot safely route a document to
    /// its declared view or views.
    pub fn validate(&self) -> Result<(), PresentationError> {
        match self {
            Self::Mono {
                surface_width,
                surface_height,
                view,
            } => {
                if view.view != ViewIdentity::Mono {
                    return Err(PresentationError::InvalidMonoView);
                }
                validate_surface(*surface_width, *surface_height)?;
                validate_viewport(*view, *surface_width, *surface_height)
            }
            Self::Stereo {
                surface_width,
                surface_height,
                left,
                right,
            } => {
                if left.view != ViewIdentity::Left || right.view != ViewIdentity::Right {
                    return Err(PresentationError::InvalidStereoViews);
                }
                validate_surface(*surface_width, *surface_height)?;
                validate_viewport(*left, *surface_width, *surface_height)?;
                validate_viewport(*right, *surface_width, *surface_height)?;
                if viewports_overlap(*left, *right) {
                    return Err(PresentationError::OverlappingStereoViewports);
                }
                Ok(())
            }
        }
    }

    fn views(&self) -> Vec<Viewport> {
        match self {
            Self::Mono { view, .. } => vec![*view],
            Self::Stereo { left, right, .. } => vec![*left, *right],
        }
    }
}

/// Placement requested by a semantic UI document.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[allow(missing_docs)]
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum UiPlacement {
    /// Place in the adapter's ordinary screen layer.
    Screen,
    /// Place relative to the current head pose; this does not claim room anchoring.
    HeadLocked,
    /// Place relative to an explicitly tracked room anchor.
    World { anchor: RoomAnchorId },
}

/// A room anchor resolved by a presentation adapter before plan construction.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[allow(missing_docs)]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ResolvedRoomAnchor {
    /// Stable identity referenced by a world-placed document.
    pub id: RoomAnchorId,
    /// Current room-space transform supplied by the adapter.
    pub transform: Transform,
}

/// Adapter-owned resolved spatial state needed to construct a presentation plan.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PresentationContext {
    /// Currently resolved room anchors. An empty list explicitly cannot satisfy world placement.
    pub room_anchors: Vec<ResolvedRoomAnchor>,
}

/// One semantic UI document, independent of a device's view or graphics APIs.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[allow(missing_docs)]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct UiDocument {
    /// Stable document identifier.
    pub id: UiDocumentId,
    /// Source and interaction epoch, serialized as a decimal string.
    ///
    /// Increment this when the node structure, declared actions, or interaction
    /// policy changes. It is not a per-value or per-frame tick; adapters validate
    /// input values against the current document state at dispatch time.
    #[serde(with = "wire_u64")]
    #[cfg_attr(feature = "schema", schemars(with = "String"))]
    #[cfg_attr(feature = "typescript", ts(type = "string"))]
    pub revision: u64,
    /// Requested spatial placement; adapters never silently replace it.
    pub placement: UiPlacement,
    /// Whether this document captures platform navigation and draws a scrim.
    ///
    /// Modal documents prevent scene navigation while active. Modeless documents
    /// remain an overlay, so scene controls such as sliders do not hide the scene.
    #[serde(default)]
    pub modal: bool,
    /// Flat, deterministic document order for typed UI nodes.
    pub nodes: Vec<UiNode>,
}

impl UiDocument {
    /// Validates document structure and required adapter capabilities.
    ///
    /// # Errors
    ///
    /// Returns an error for malformed identifiers, bounds, duplicate nodes, or
    /// a world placement requested without room tracking.
    pub fn validate(&self) -> Result<(), PresentationError> {
        validate_identifier(&self.id.0)?;
        if self.nodes.len() > MAX_UI_NODES {
            return Err(PresentationError::TooManyNodes);
        }
        for (index, node) in self.nodes.iter().enumerate() {
            validate_node(node)?;
            if self.nodes[..index].iter().any(|prior| prior.id == node.id) {
                return Err(PresentationError::DuplicateNodeId);
            }
        }
        Ok(())
    }

    /// Validates an input event against this exact document revision and node role.
    ///
    /// This method checks only the semantic contract. Applying an accepted
    /// action remains an application responsibility.
    ///
    /// # Errors
    ///
    /// Returns an error for stale documents, disabled nodes, mismatched actions,
    /// malformed text, or slider values outside the node's declared range.
    pub fn validate_event(&self, event: &UiEvent) -> Result<ValidatedUiEvent, PresentationError> {
        self.validate()?;
        if event.document != self.id {
            return Err(PresentationError::WrongDocument);
        }
        if event.revision != self.revision {
            return Err(PresentationError::StaleRevision);
        }
        let node = self
            .nodes
            .iter()
            .find(|node| node.id == event.node)
            .ok_or(PresentationError::UnknownNode)?;
        if !node.enabled {
            return Err(PresentationError::DisabledNode);
        }
        match (&node.kind, &event.action) {
            (UiNodeKind::Button { action, .. }, UiEventAction::Activate { action: received })
                if action == received =>
            {
                Ok(ValidatedUiEvent {
                    node: node.id.clone(),
                    action: *received,
                })
            }
            (
                UiNodeKind::Slider {
                    minimum,
                    maximum,
                    step,
                    action,
                    ..
                },
                UiEventAction::SetSlider {
                    action: received,
                    value,
                },
            ) if action == received => {
                if !value.is_finite()
                    || *value < *minimum
                    || *value > *maximum
                    || !slider_step_matches(*value, *minimum, *step)
                {
                    return Err(PresentationError::SliderValueOutOfRange);
                }
                Ok(ValidatedUiEvent {
                    node: node.id.clone(),
                    action: *received,
                })
            }
            (
                UiNodeKind::TextInput {
                    max_bytes, action, ..
                },
                UiEventAction::SetText {
                    action: received,
                    value,
                },
            ) if action == received => {
                if value.len() > *max_bytes as usize {
                    return Err(PresentationError::TextValueTooLong);
                }
                Ok(ValidatedUiEvent {
                    node: node.id.clone(),
                    action: *received,
                })
            }
            (
                UiNodeKind::Toggle { action, .. },
                UiEventAction::SetToggle {
                    action: received, ..
                },
            ) if action == received => Ok(ValidatedUiEvent {
                node: node.id.clone(),
                action: *received,
            }),
            _ => Err(PresentationError::WrongEventForNode),
        }
    }

    /// Returns the next enabled focusable node in document order, wrapping at either end.
    pub fn next_focus(
        &self,
        current: Option<&UiNodeId>,
        direction: UiNavigation,
    ) -> Option<UiNodeId> {
        let focusable: Vec<&UiNode> = self
            .nodes
            .iter()
            .filter(|node| node.enabled && node.kind.focusable())
            .collect();
        if focusable.is_empty() {
            return None;
        }
        let current_index = current.and_then(|id| focusable.iter().position(|node| &node.id == id));
        let next = match (current_index, direction) {
            (Some(index), UiNavigation::Forward) => (index + 1) % focusable.len(),
            (Some(0), UiNavigation::Backward) => focusable.len() - 1,
            (Some(index), UiNavigation::Backward) => index - 1,
            (None, UiNavigation::Forward) => 0,
            (None, UiNavigation::Backward) => focusable.len() - 1,
        };
        Some(focusable[next].id.clone())
    }
}

impl PresentationContext {
    fn resolve(&self, anchor: &RoomAnchorId) -> Result<Transform, PresentationError> {
        let resolved = self
            .room_anchors
            .iter()
            .find(|candidate| candidate.id == *anchor)
            .ok_or(PresentationError::UnresolvedRoomAnchor)?;
        validate_identifier(&resolved.id.0)?;
        validate_transform(resolved.transform)?;
        Ok(resolved.transform)
    }
}

/// A typed node in a flat semantic UI document.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[allow(missing_docs)]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct UiNode {
    /// Identifier unique within the containing document.
    pub id: UiNodeId,
    /// Whether the node accepts focus and input.
    pub enabled: bool,
    /// Typed semantic role and values.
    #[serde(flatten)]
    pub kind: UiNodeKind,
}

/// Semantic role and typed values of a UI node.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[allow(missing_docs)]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum UiNodeKind {
    /// A noninteractive visual grouping surface.
    Panel { label: Option<String> },
    /// Noninteractive visible text.
    Text { text: String },
    /// An activatable command.
    Button { label: String, action: UiActionId },
    /// A bounded scalar input.
    Slider {
        label: String,
        value: f32,
        minimum: f32,
        maximum: f32,
        step: Option<f32>,
        action: UiActionId,
    },
    /// A bounded UTF-8 text input.
    TextInput {
        label: String,
        value: String,
        max_bytes: u16,
        action: UiActionId,
    },
    /// A Boolean input.
    Toggle {
        label: String,
        value: bool,
        action: UiActionId,
    },
    /// An adapter-resolved image with an accessible text alternative.
    ImageResource { resource: UiResourceId, alt: String },
}

impl UiNodeKind {
    fn focusable(&self) -> bool {
        matches!(
            self,
            Self::Button { .. }
                | Self::Slider { .. }
                | Self::TextInput { .. }
                | Self::Toggle { .. }
        )
    }
}

/// Direction for deterministic focus navigation.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum UiNavigation {
    /// Move toward later nodes in document order.
    Forward,
    /// Move toward earlier nodes in document order.
    Backward,
}

/// Input reported by a platform adapter for a specific document revision.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct UiEvent {
    /// Document that the adapter displayed.
    pub document: UiDocumentId,
    /// Document revision displayed by the adapter, serialized as a decimal string.
    #[serde(with = "wire_u64")]
    #[cfg_attr(feature = "schema", schemars(with = "String"))]
    #[cfg_attr(feature = "typescript", ts(type = "string"))]
    pub revision: u64,
    /// Node receiving the event.
    pub node: UiNodeId,
    /// Typed input and requested semantic action.
    #[serde(flatten)]
    pub action: UiEventAction,
}

/// Typed user input accepted only by a matching node role.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[allow(missing_docs)]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum UiEventAction {
    /// Activate a button's declared action.
    Activate { action: UiActionId },
    /// Set a slider to a bounded scalar value.
    SetSlider { action: UiActionId, value: f32 },
    /// Set a text input value.
    SetText { action: UiActionId, value: String },
    /// Set a toggle value.
    SetToggle { action: UiActionId, value: bool },
}

/// Event proven to target an enabled node in the displayed document revision.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ValidatedUiEvent {
    /// Enabled node that accepted the input.
    pub node: UiNodeId,
    /// Declared application action requested by that node.
    pub action: UiActionId,
}

/// A centrally produced routing instruction for one adapter view.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ViewRoute {
    /// Target view receiving this semantic document.
    pub viewport: Viewport,
    /// Document identifier presented to this view.
    pub document: UiDocumentId,
    /// Exact document revision presented to this view, serialized as a decimal string.
    #[serde(with = "wire_u64")]
    #[cfg_attr(feature = "schema", schemars(with = "String"))]
    #[cfg_attr(feature = "typescript", ts(type = "string"))]
    pub revision: u64,
}

/// Placement ready for a renderer after all required room anchors are resolved.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[allow(missing_docs)]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ResolvedUiPlacement {
    /// Render in the adapter's ordinary screen layer.
    Screen,
    /// Render relative to the current head pose.
    HeadLocked,
    /// Render using this exact adapter-resolved room transform.
    World {
        anchor: RoomAnchorId,
        transform: Transform,
    },
}

/// Validated mapping of one semantic document onto every view of a target.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PresentationPlan {
    /// Resolved placement that every route in this plan must use.
    pub placement: ResolvedUiPlacement,
    /// One route per declared target view.
    pub routes: Vec<ViewRoute>,
}

impl PresentationPlan {
    /// Validates semantic and target contracts then routes the document to every explicit view.
    ///
    /// # Errors
    ///
    /// Returns any document capability or target topology error without selecting
    /// a fallback placement or view.
    pub fn build(
        document: &UiDocument,
        target: &DeviceTarget,
        context: &PresentationContext,
    ) -> Result<Self, PresentationError> {
        document.validate()?;
        target.validate()?;
        let placement = match &document.placement {
            UiPlacement::Screen => ResolvedUiPlacement::Screen,
            UiPlacement::HeadLocked => ResolvedUiPlacement::HeadLocked,
            UiPlacement::World { anchor } => ResolvedUiPlacement::World {
                anchor: anchor.clone(),
                transform: context.resolve(anchor)?,
            },
        };
        Ok(Self {
            placement,
            routes: target
                .views()
                .into_iter()
                .map(|viewport| ViewRoute {
                    viewport,
                    document: document.id.clone(),
                    revision: document.revision,
                })
                .collect(),
        })
    }
}

/// Rejection reason for presentation documents, topology, or input.
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "typescript", derive(ts_rs::TS))]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PresentationError {
    /// An identifier is empty, too long, or contains unsupported characters.
    InvalidIdentifier,
    /// A target has a monoscopic viewport with a non-monoscopic identity.
    InvalidMonoView,
    /// A stereo target does not declare one left and one right viewport.
    InvalidStereoViews,
    /// A target surface or viewport has zero dimensions.
    EmptyViewport,
    /// A viewport extends outside the declared target surface.
    ViewportOutOfBounds,
    /// Stereo viewports occupy overlapping regions.
    OverlappingStereoViewports,
    /// A document exceeds its node bound.
    TooManyNodes,
    /// More than one node uses an identifier.
    DuplicateNodeId,
    /// A world placement's anchor is absent from the resolved adapter context.
    UnresolvedRoomAnchor,
    /// A resolved room anchor has a nonfinite or non-rigid transform.
    InvalidRoomAnchorTransform,
    /// Node text or labels exceed their portable bound.
    TextTooLong,
    /// A slider's values or step are malformed.
    InvalidSlider,
    /// A text input's current value exceeds its declared bound.
    InvalidTextInput,
    /// An event names another document.
    WrongDocument,
    /// An event targets an older or newer document revision.
    StaleRevision,
    /// An event names no node in the document.
    UnknownNode,
    /// An event targets a disabled node.
    DisabledNode,
    /// The event kind or action does not match the node role.
    WrongEventForNode,
    /// A slider event is nonfinite, outside range, or misses its step.
    SliderValueOutOfRange,
    /// A text input event exceeds the node's declared bound.
    TextValueTooLong,
}

impl fmt::Display for PresentationError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(match self {
            Self::InvalidIdentifier => "invalid presentation identifier",
            Self::InvalidMonoView => "monoscopic target must use the mono view identity",
            Self::InvalidStereoViews => {
                "stereo target must use exactly left and right view identities"
            }
            Self::EmptyViewport => "target surface and viewport dimensions must be positive",
            Self::ViewportOutOfBounds => "viewport extends outside the target surface",
            Self::OverlappingStereoViewports => "stereo viewports must not overlap",
            Self::TooManyNodes => "UI document has too many nodes",
            Self::DuplicateNodeId => "UI document has duplicate node identifiers",
            Self::UnresolvedRoomAnchor => "world UI placement requires a resolved room anchor",
            Self::InvalidRoomAnchorTransform => "resolved room anchor transform is invalid",
            Self::TextTooLong => "UI text exceeds the portable bound",
            Self::InvalidSlider => "slider bounds or step are invalid",
            Self::InvalidTextInput => "text input value exceeds its declared bound",
            Self::WrongDocument => "UI event targets another document",
            Self::StaleRevision => "UI event targets a stale document revision",
            Self::UnknownNode => "UI event targets an unknown node",
            Self::DisabledNode => "UI event targets a disabled node",
            Self::WrongEventForNode => "UI event does not match the node role or action",
            Self::SliderValueOutOfRange => "slider event value is invalid",
            Self::TextValueTooLong => "text input event value exceeds its declared bound",
        })
    }
}

#[cfg(feature = "std")]
impl std::error::Error for PresentationError {}

fn validate_identifier(value: &str) -> Result<(), PresentationError> {
    if value.is_empty()
        || value.len() > MAX_UI_ID_BYTES
        || !value
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'/'))
    {
        return Err(PresentationError::InvalidIdentifier);
    }
    Ok(())
}

fn validate_text(value: &str) -> Result<(), PresentationError> {
    if value.len() > MAX_UI_TEXT_BYTES {
        Err(PresentationError::TextTooLong)
    } else {
        Ok(())
    }
}

fn validate_node(node: &UiNode) -> Result<(), PresentationError> {
    validate_identifier(&node.id.0)?;
    match &node.kind {
        UiNodeKind::Panel { label } => {
            if let Some(label) = label {
                validate_text(label)?;
            }
        }
        UiNodeKind::Text { text } => validate_text(text)?,
        UiNodeKind::Button { label, .. } => {
            validate_text(label)?;
        }
        UiNodeKind::Slider {
            label,
            value,
            minimum,
            maximum,
            step,
            ..
        } => {
            validate_text(label)?;
            if !value.is_finite()
                || !minimum.is_finite()
                || !maximum.is_finite()
                || minimum > maximum
                || value < minimum
                || value > maximum
                || step.is_some_and(|step| !step.is_finite() || step <= 0.0)
                || !slider_step_matches(*value, *minimum, *step)
            {
                return Err(PresentationError::InvalidSlider);
            }
        }
        UiNodeKind::TextInput {
            label,
            value,
            max_bytes,
            ..
        } => {
            validate_text(label)?;
            if *max_bytes == 0 || value.len() > *max_bytes as usize {
                return Err(PresentationError::InvalidTextInput);
            }
        }
        UiNodeKind::Toggle { label, .. } => {
            validate_text(label)?;
        }
        UiNodeKind::ImageResource { resource, alt } => {
            validate_identifier(&resource.0)?;
            validate_text(alt)?;
        }
    }
    Ok(())
}

fn validate_surface(width: u32, height: u32) -> Result<(), PresentationError> {
    if width == 0 || height == 0 {
        Err(PresentationError::EmptyViewport)
    } else {
        Ok(())
    }
}

fn validate_viewport(
    viewport: Viewport,
    surface_width: u32,
    surface_height: u32,
) -> Result<(), PresentationError> {
    if viewport.width == 0 || viewport.height == 0 {
        return Err(PresentationError::EmptyViewport);
    }
    let x_end = i64::from(viewport.x) + i64::from(viewport.width);
    let y_end = i64::from(viewport.y) + i64::from(viewport.height);
    if viewport.x < 0
        || viewport.y < 0
        || x_end > i64::from(surface_width)
        || y_end > i64::from(surface_height)
    {
        return Err(PresentationError::ViewportOutOfBounds);
    }
    Ok(())
}

fn viewports_overlap(left: Viewport, right: Viewport) -> bool {
    let left_x_end = i64::from(left.x) + i64::from(left.width);
    let left_y_end = i64::from(left.y) + i64::from(left.height);
    let right_x_end = i64::from(right.x) + i64::from(right.width);
    let right_y_end = i64::from(right.y) + i64::from(right.height);
    i64::from(left.x) < right_x_end
        && i64::from(right.x) < left_x_end
        && i64::from(left.y) < right_y_end
        && i64::from(right.y) < left_y_end
}

fn slider_step_matches(value: f32, minimum: f32, step: Option<f32>) -> bool {
    match step {
        None => true,
        Some(step) => {
            let steps = (value - minimum) / step;
            (steps - libm::roundf(steps)).abs() <= 1e-4
        }
    }
}

fn validate_transform(transform: Transform) -> Result<(), PresentationError> {
    let translation = transform.translation;
    let rotation = transform.rotation;
    let scale = transform.scale;
    if !translation.x.is_finite()
        || !translation.y.is_finite()
        || !translation.z.is_finite()
        || !rotation.x.is_finite()
        || !rotation.y.is_finite()
        || !rotation.z.is_finite()
        || !rotation.w.is_finite()
        || !scale.x.is_finite()
        || !scale.y.is_finite()
        || !scale.z.is_finite()
        || scale.x <= 0.0
        || scale.y <= 0.0
        || scale.z <= 0.0
    {
        return Err(PresentationError::InvalidRoomAnchorTransform);
    }
    let length_squared = rotation.x * rotation.x
        + rotation.y * rotation.y
        + rotation.z * rotation.z
        + rotation.w * rotation.w;
    if (length_squared - 1.0).abs() > 1e-9 {
        return Err(PresentationError::InvalidRoomAnchorTransform);
    }
    Ok(())
}