cvkg_core/

lib.rs

//! # CVKG Agentic Development Guidelines (v1.2)
//!
//! All AI agents contributing to this crate MUST follow ALL seven rules:
//!
//! ── Karpathy Guidelines (1–4) ────────────────────────────────────────────
//! 1. THINK FIRST     -- State assumptions. Surface ambiguity. Push back on complexity.
//! 2. STAY SIMPLE     -- Minimum code. No speculative features. No unasked-for abstractions.
//! 3. BE SURGICAL     -- Touch only what's required. Own your orphans. Don't improve neighbors.
//! 4. VERIFY GOALS    -- Turn tasks into checkable criteria. Loop until they pass. Never commit broken.
//!
//! ── CVKG Extended Protocols (5–7) ────────────────────────────────────────
//! 5. TRIPLE-PASS     -- Read the target, its surrounding context, and its full call graph
//                      at least THREE TIMES before making any edit or revision.
//! 6. COMMENT ALL     -- Every major pub fn, unsafe block, and non-trivial algorithm in
//                      every .rs/.ts/.h/.wgsl file MUST have a descriptive doc comment.
//                      Comments describe WHY and WHAT CONTRACT, not HOW mechanically.
//! 7. MONITOR LOOPS   -- Check every tool call / command for progress every 30 seconds.
//                      After 3 consecutive identical failures, stop, write BLOCKED.md,
//                      and move to unblocked work. Never silently accept a broken state.
//!
//! Sources:
//   Karpathy: https://github.com/multica-ai/andrej-karpathy-skills
//   CVKG Extended: Section 2 of the CVKG Design Specification

//! The View trait is the fundamental building block of CVKG. Every UI element -- from a plain text label
//! to a complex navigation controller -- is a View. The trait is intentionally minimal; complexity emerges
//! through modifier composition.
//!
//! # Conformance rules:
//! 1. `body()` must be pure and side-effect free
//! 2. Primitive views use `Never` as `Body` and register a `PaintCommand` directly with the scene graph
//! 3. `View` types must implement `Send` but not necessarily `Sync`, enabling safe multi-threaded layout passes

use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::collections::HashSet;
use std::str::FromStr;

pub mod error_types;
pub mod future_views;
pub mod security;

pub use future_views::{HologramView, ParticleEmitter, StreamingText};

// P1-13: extracted modules
pub mod asset;
pub mod dependency;
pub mod error_boundary;
pub mod knowledge;
pub mod renderer;
pub mod undo;
pub mod virtual_list;
pub mod window;

// P1-13: re-exports for backward compatibility
pub use asset::{AssetKey, AssetState, TokenValue, DesignTokens};
pub use dependency::{DependencyGraph, FrameBudgetTracker, SubsystemBudget, InputLatencyTracker};
pub use error_boundary::{ComponentErrorState, ErrorBoundary};
pub use knowledge::{AnnouncementPriority, KnowledgeFragment, KnowledgeId, AppState, MemoryLayer, UiFidelityLevel, TemporalEdge, TemporalNode};
pub use undo::{UndoGroup, UndoManager};
pub use window::{Window, WindowCloseAction, WindowConfig, WindowHandle, WindowId, WindowLevel};

pub trait View: Sized + Send {
    /// The concrete type produced after applying modifiers.
    /// For primitive views this is Self.
    type Body: View;

    fn body(self) -> Self::Body;

    /// Render this view into the provided renderer at the specified bounds.
    /// Primitive views override this to perform drawing operations.
    fn render(&self, _renderer: &mut dyn Renderer, _rect: Rect) {}

    /// Calculate the natural (intrinsic) size of this view given proposed constraints.
    /// This allows views like Buttons or Labels to inform the layout engine of their needs.
    fn intrinsic_size(&self, _renderer: &mut dyn Renderer, _proposal: SizeProposal) -> Size {
        Size::ZERO
    }

    /// Optionally provide a layout implementation for this view.
    fn layout(&self) -> Option<&dyn layout::LayoutView> {
        None
    }

    /// Returns the flex weight of this view for proportional distribution in stacks.
    fn flex_weight(&self) -> f32 {
        0.0
    }

    /// Returns the grid placement configuration for this view if it is laid out in a Grid.
    fn get_grid_placement(&self) -> Option<GridPlacement> {
        None
    }

    /// Provided modifier entry point
    fn modifier<M: ViewModifier>(self, m: M) -> ModifiedView<Self, M> {
        ModifiedView::new(self, m)
    }

    /// Apply a Bifrost (Frosted Glass) effect to the view
    fn bifrost(
        self,
        blur: f32,
        saturation: f32,
        opacity: f32,
    ) -> ModifiedView<Self, FrostedGlassModifier> {
        self.modifier(FrostedGlassModifier {
            blur,
            saturation,
            opacity,
            fresnel_strength: 1.0,
        })
    }

    /// Apply a Bifrost (Frosted Glass) effect with full parameter control.
    fn bifrost_full(
        self,
        blur: f32,
        saturation: f32,
        opacity: f32,
        fresnel_strength: f32,
    ) -> ModifiedView<Self, FrostedGlassModifier> {
        self.modifier(FrostedGlassModifier {
            blur,
            saturation,
            opacity,
            fresnel_strength,
        })
    }

    /// Apply a Gungnir (Neon Glow) effect to the view
    fn gungnir(
        self,
        color: impl Into<String>,
        radius: f32,
        intensity: f32,
    ) -> ModifiedView<Self, NeonGlowModifier> {
        self.modifier(NeonGlowModifier {
            color: color.into(),
            radius,
            intensity,
        })
    }

    /// Apply a Mjolnir Slice (Geometric cut) to the view
    fn mjolnir_slice(self, angle: f32, offset: f32) -> ModifiedView<Self, GeometricClipModifier> {
        self.modifier(GeometricClipModifier { angle, offset })
    }

    /// Apply a Mjolnir Shatter (Fragmented transition) to the view
    fn mjolnir_shatter(
        self,
        pieces: u32,
        force: f32,
    ) -> ModifiedView<Self, FragmentModifier> {
        self.modifier(FragmentModifier { pieces, force })
    }

    /// Mark this view as a Bifrost Bridge (Shared Element) for cross-view persistence
    fn bifrost_bridge(self, id: impl Into<String>) -> ModifiedView<Self, SharedElementModifier> {
        self.modifier(SharedElementModifier { id: id.into() })
    }

    /// Add a background color to this view
    fn background(self, color: [f32; 4]) -> ModifiedView<Self, BackgroundModifier> {
        self.modifier(BackgroundModifier { color })
    }

    /// Add padding to this view
    fn padding(self, amount: f32) -> ModifiedView<Self, PaddingModifier> {
        self.modifier(PaddingModifier { amount })
    }

    /// Set the opacity (alpha) of this view in the range [0.0, 1.0].
    fn opacity(self, opacity: f32) -> ModifiedView<Self, OpacityModifier> {
        self.modifier(OpacityModifier {
            opacity: opacity.clamp(0.0, 1.0),
        })
    }

    /// Override the foreground (text / icon) color of this view.
    fn foreground_color(self, color: [f32; 4]) -> ModifiedView<Self, ForegroundColorModifier> {
        self.modifier(ForegroundColorModifier { color })
    }

    /// Constrain this view to an explicit width and/or height.
    /// Constrains the size of this view using fixed width/height values.
    fn frame(self, width: Option<f32>, height: Option<f32>) -> ModifiedView<Self, FrameModifier> {
        self.modifier(FrameModifier {
            width,
            height,
            min_width: None,
            max_width: None,
            min_height: None,
            max_height: None,
            alignment: Alignment::Center,
        })
    }

    /// Give this view a flex weight for proportional space distribution in stacks.
    fn flex(self, weight: f32) -> ModifiedView<Self, FlexModifier> {
        self.modifier(FlexModifier { weight })
    }

    /// Specify the grid placement configuration (column, row, column_span, row_span) for this view.
    fn grid_placement(self, placement: GridPlacement) -> ModifiedView<Self, GridPlacementModifier> {
        self.modifier(GridPlacementModifier { placement })
    }

    /// Overlay a view on top of this view, aligned and offset relative to it.
    fn overlay<O: View + Clone + 'static>(
        self,
        overlay: O,
        alignment: Alignment,
        offset: [f32; 2],
        on_dismiss: Option<Arc<dyn Fn() + Send + Sync>>,
    ) -> ModifiedView<Self, OverlayModifier> {
        self.modifier(OverlayModifier {
            overlay: overlay.erase(),
            alignment,
            offset,
            on_dismiss,
        })
    }

    /// Automatically add padding to avoid overlapping with platform safe areas (notches, bars).
    fn safe_area_padding(self) -> ModifiedView<Self, SafeAreaModifier> {
        self.modifier(SafeAreaModifier { ignores: false })
    }

    /// Explicitly ignore platform safe areas and draw into the margins.
    fn ignores_safe_area(self) -> ModifiedView<Self, SafeAreaModifier> {
        self.modifier(SafeAreaModifier { ignores: true })
    }

    /// Clip all child drawing to this view's bounds.
    fn clip_to_bounds(self) -> ModifiedView<Self, ClipModifier> {
        self.modifier(ClipModifier)
    }

    /// Draw a colored border around this view.
    fn border(self, color: [f32; 4], width: f32) -> ModifiedView<Self, BorderModifier> {
        self.modifier(BorderModifier { color, width })
    }

    /// Add elevation (shadow) to the view. Level determines the shadow depth.
    fn elevation(self, level: f32) -> ModifiedView<Self, ElevationModifier> {
        self.modifier(ElevationModifier { level })
    }

    /// Apply an absolute-like position offset to this view.
    /// The view is shifted by (x, y) from its layout position.
    fn position(self, x: f32, y: f32) -> ModifiedView<Self, PositionModifier> {
        self.modifier(PositionModifier { x, y })
    }

    /// Set the z-index (render order) for this view.
    /// Higher values render on top of lower values.
    fn z_index(self, z: i32) -> ModifiedView<Self, ZIndexModifier> {
        self.modifier(ZIndexModifier { z_index: z })
    }

    /// Add a magnetic effect that pulls the view towards the cursor.
    fn magnetic(self, radius: f32, intensity: f32) -> ModifiedView<Self, MagneticPullModifier> {
        self.modifier(MagneticPullModifier { radius, intensity })
    }

    /// Add a ManiGlow (Lunar Illuminator) effect that glows near the cursor.
    fn mani_glow(self, color: [f32; 4], radius: f32) -> ModifiedView<Self, CursorGlowModifier> {
        self.modifier(CursorGlowModifier { color, radius })
    }

    /// Theme this view based on a specific memory layer.
    fn memory_layer(self, layer: MemoryLayer) -> ModifiedView<Self, MemoryLayerModifier> {
        self.modifier(MemoryLayerModifier { layer })
    }

    /// Enable Fafnir's Evolution: The component grows and glows as it is used.
    fn fafnir_evolve(self, id: u64) -> ModifiedView<Self, EvolvingInteractionModifier> {
        self.modifier(EvolvingInteractionModifier { id })
    }

    /// Enable Mimir's Intent: The component anticipates user interaction via pointer kinematics.
    fn mimir_intent(self) -> ModifiedView<Self, IntentPredictionModifier> {
        self.modifier(IntentPredictionModifier)
    }

    /// Enable Kvasir's Vibes: Subconscious telemetry representing cognitive complexity.
    fn kvasir_vibes(self, complexity: f32) -> ModifiedView<Self, ComplexityTelemetryModifier> {
        self.modifier(ComplexityTelemetryModifier { complexity })
    }

    /// Bestow Odin's Eye: Global omniscient observability layer.
    fn odins_eye(self) -> ModifiedView<Self, ObservabilityOverlayModifier> {
        self.modifier(ObservabilityOverlayModifier)
    }

    /// Trigger an action when the view appears
    fn on_appear<F: Fn() + Send + Sync + 'static>(
        self,
        action: F,
    ) -> ModifiedView<Self, LifecycleModifier> {
        self.modifier(LifecycleModifier {
            on_appear: Some(Arc::new(action)),
            on_disappear: None,
        })
    }

    /// Trigger an action when the view disappears
    fn on_disappear<F: Fn() + Send + Sync + 'static>(
        self,
        action: F,
    ) -> ModifiedView<Self, LifecycleModifier> {
        self.modifier(LifecycleModifier {
            on_appear: None,
            on_disappear: Some(Arc::new(action)),
        })
    }

    /// Trigger an action when the view is clicked
    fn on_click<F: Fn() + Send + Sync + 'static>(
        self,
        action: F,
    ) -> ModifiedView<Self, OnClickModifier> {
        self.modifier(OnClickModifier {
            action: Arc::new(action),
        })
    }

    /// Trigger an action when the pointer enters the view bounds
    fn on_pointer_enter<F: Fn() + Send + Sync + 'static>(
        self,
        action: F,
    ) -> ModifiedView<Self, OnPointerEnterModifier> {
        self.modifier(OnPointerEnterModifier {
            action: Arc::new(action),
        })
    }

    /// Trigger an action when the pointer leaves the view bounds
    fn on_pointer_leave<F: Fn() + Send + Sync + 'static>(
        self,
        action: F,
    ) -> ModifiedView<Self, OnPointerLeaveModifier> {
        self.modifier(OnPointerLeaveModifier {
            action: Arc::new(action),
        })
    }

    /// Trigger an action when the pointer moves inside the view bounds
    fn on_pointer_move<F: Fn(f32, f32) + Send + Sync + 'static>(
        self,
        action: F,
    ) -> ModifiedView<Self, OnPointerMoveModifier> {
        self.modifier(OnPointerMoveModifier {
            action: Arc::new(action),
        })
    }

    /// Trigger an action when the pointer is pressed down
    fn on_pointer_down<F: Fn() + Send + Sync + 'static>(
        self,
        action: F,
    ) -> ModifiedView<Self, OnPointerDownModifier> {
        self.modifier(OnPointerDownModifier {
            action: Arc::new(action),
        })
    }

    /// Trigger an action when the pointer is released
    fn on_pointer_up<F: Fn() + Send + Sync + 'static>(
        self,
        action: F,
    ) -> ModifiedView<Self, OnPointerUpModifier> {
        self.modifier(OnPointerUpModifier {
            action: Arc::new(action),
        })
    }

    /// Type-erase this view into AnyView
    fn erase(self) -> AnyView
    where
        Self: Clone + 'static,
    {
        AnyView::new(self)
    }

    // =============================================================================
    // ACCESSIBILITY
    // =============================================================================

    /// Return accessibility properties for this view.
    /// Override to expose semantic role, label, state to assistive technology.
    /// Default returns `None` (view is not explicitly accessible).
    fn aria_properties(&self) -> Option<AriaProperties> {
        None
    }

    /// Handle a keyboard navigation event.
    /// Return true if consumed, false to bubble.
    fn on_key_event(&self, _key: &str, _modifiers: KeyModifiers) -> bool {
        false
    }

    /// Return keyboard shortcuts this view responds to.
    fn key_shortcuts(&self) -> Vec<KeyShortcut> {
        vec![]
    }

    /// Return true when this view's render output has changed since last build.
    /// Default true for backward compatibility. Override for incremental skip.
    /// When returns false, VDom::build skips this subtree entirely.
    fn changed(&self) -> bool { true }

    /// Stable identity for diff keying. Return None for anonymous views.
    /// When Some(id), the VDOM layer uses this to match nodes across rebuilds,
    /// enabling handler survival and incremental patch generation.
    fn view_id(&self) -> Option<u64> { None }
}

// =============================================================================
// ARIA PROPERTIES
// =============================================================================

/// Semantic role for assistive technology (WCAG 2.1 §4.1.2).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum AriaRole {
    Alert,
    Alertdialog,
    Article,
    Banner,
    Button,
    Checkbox,
    Columnheader,
    Combobox,
    Complementary,
    Contentinfo,
    Dialog,
    Form,
    Grid,
    Gridcell,
    Heading,
    Img,
    Link,
    List,
    Listbox,
    Listitem,
    Main,
    Menu,
    Menubar,
    Menuitem,
    Menuitemcheckbox,
    Menuitemradio,
    Navigation,
    None,
    Note,
    Option,
    Presentation,
    Progressbar,
    Radio,
    Radiogroup,
    Region,
    Row,
    Rowgroup,
    Rowheader,
    Search,
    Separator,
    Slider,
    Spinbutton,
    Status,
    Switch,
    Tab,
    Table,
    Tablist,
    Tabpanel,
    Textbox,
    Toolbar,
    Tooltip,
    Tree,
    Treeitem,
}

/// Accessible properties for a view, describing its semantic role and state.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AriaProperties {
    pub role: AriaRole,
    pub label: String,
    pub description: Option<String>,
    pub value: Option<String>,
    pub pressed: Option<bool>,
    pub checked: Option<bool>,
    pub expanded: Option<bool>,
    pub disabled: bool,
    pub hidden: bool,
    pub level: Option<u8>,
    pub shortcut: Option<String>,
    pub focused: bool,
    pub live: Option<String>,
    pub atomic: bool,
}

impl AriaProperties {
    pub fn new(role: AriaRole, label: impl Into<String>) -> Self {
        Self {
            role,
            label: label.into(),
            description: None,
            value: None,
            pressed: None,
            checked: None,
            expanded: None,
            disabled: false,
            hidden: false,
            level: None,
            shortcut: None,
            focused: false,
            live: None,
            atomic: false,
        }
    }

    pub fn description(mut self, d: impl Into<String>) -> Self {
        self.description = Some(d.into());
        self
    }
    pub fn value(mut self, v: impl Into<String>) -> Self {
        self.value = Some(v.into());
        self
    }
    pub fn checked(mut self, c: bool) -> Self {
        self.checked = Some(c);
        self
    }
    pub fn disabled(mut self, d: bool) -> Self {
        self.disabled = d;
        self
    }
    pub fn expanded(mut self, e: bool) -> Self {
        self.expanded = Some(e);
        self
    }
    pub fn level(mut self, l: u8) -> Self {
        self.level = Some(l.clamp(1, 6));
        self
    }
    pub fn shortcut(mut self, s: impl Into<String>) -> Self {
        self.shortcut = Some(s.into());
        self
    }
    pub fn focused(mut self, f: bool) -> Self {
        self.focused = f;
        self
    }
}

// =============================================================================
// KEYBOARD NAVIGATION
// =============================================================================

/// Modifier keys for keyboard events.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub struct KeyModifiers {
    pub shift: bool,
    pub ctrl: bool,
    pub alt: bool,
    pub meta: bool,
}

/// A keyboard shortcut binding.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct KeyShortcut {
    pub key: String,
    pub modifiers: KeyModifiers,
    pub description: String,
}

impl KeyShortcut {
    pub fn new(key: impl Into<String>, desc: impl Into<String>) -> Self {
        Self {
            key: key.into(),
            modifiers: KeyModifiers::default(),
            description: desc.into(),
        }
    }
    pub fn with_ctrl(mut self) -> Self {
        self.modifiers.ctrl = true;
        self
    }
    pub fn with_shift(mut self) -> Self {
        self.modifiers.shift = true;
        self
    }
    pub fn with_alt(mut self) -> Self {
        self.modifiers.alt = true;
        self
    }
    pub fn with_meta(mut self) -> Self {
        self.modifiers.meta = true;
        self
    }
}

// =============================================================================
// FOCUS MANAGEMENT
// =============================================================================

/// Unique ID for a focusable element.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct FocusableId(String);

impl FocusableId {
    /// Returns the inner string representation of the focusable ID.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl From<&str> for FocusableId {
    fn from(s: &str) -> Self {
        Self(s.to_string())
    }
}
impl From<String> for FocusableId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

/// Focus trap for confining Tab navigation (e.g., modals).
#[derive(Debug, Clone)]
pub struct FocusTrap {
    pub id: FocusableId,
    pub order: Vec<FocusableId>,
    pub wrap: bool,
}

impl FocusTrap {
    pub fn new(id: impl Into<FocusableId>, order: Vec<FocusableId>) -> Self {
        Self {
            id: id.into(),
            order,
            wrap: true,
        }
    }
}

/// Manages focus order, Tab/Shift+Tab navigation, and focus traps.
#[derive(Debug, Default)]
pub struct FocusManager {
    order: Vec<FocusableId>,
    order_set: HashSet<FocusableId>,
    focused: Option<FocusableId>,
    traps: Vec<FocusTrap>,
}

impl FocusManager {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn register(&mut self, id: impl Into<FocusableId>) {
        let id = id.into();
        if self.order_set.insert(id.clone()) {
            self.order.push(id);
        }
    }

    pub fn unregister(&mut self, id: &FocusableId) {
        if self.order_set.remove(id) {
            self.order.retain(|x| x != id);
        }
        if self.focused.as_ref() == Some(id) {
            self.focused = None;
        }
    }

    pub fn focused(&self) -> Option<&FocusableId> {
        self.focused.as_ref()
    }

    pub fn focus(&mut self, id: impl Into<FocusableId>) -> bool {
        let id = id.into();
        if self.order.contains(&id) || self.traps.iter().any(|t| t.order.contains(&id)) {
            self.focused = Some(id);
            true
        } else {
            false
        }
    }

    pub fn focus_next(&mut self) -> Option<&FocusableId> {
        let order = self.effective_order();
        if order.is_empty() {
            return None;
        }
        let idx = self
            .focused
            .as_ref()
            .and_then(|f| order.iter().position(|x| x == f));
        let next = match idx {
            Some(i) if i + 1 < order.len() => &order[i + 1],
            _ => &order[0],
        };
        self.focused = Some(next.clone());
        self.focused.as_ref()
    }

    pub fn focus_prev(&mut self) -> Option<&FocusableId> {
        let order = self.effective_order();
        if order.is_empty() {
            return None;
        }
        let idx = self
            .focused
            .as_ref()
            .and_then(|f| order.iter().position(|x| x == f));
        let prev = match idx {
            Some(i) if i > 0 => &order[i - 1],
            _ => &order[order.len() - 1],
        };
        self.focused = Some(prev.clone());
        self.focused.as_ref()
    }

    pub fn push_trap(&mut self, trap: FocusTrap) -> FocusableId {
        let id = trap.id.clone();
        self.traps.push(trap);
        id
    }

    pub fn pop_trap(&mut self) {
        self.traps.pop();
    }
    pub fn trap_count(&self) -> usize {
        self.traps.len()
    }

    fn effective_order(&self) -> &[FocusableId] {
        self.traps
            .last()
            .map(|t| t.order.as_slice())
            .unwrap_or(&self.order)
    }
}

// =============================================================================
// REDUCED MOTION
// =============================================================================

/// Detects OS-level reduced motion preference via [`AccessibilityPreferences`].
///
/// This delegates to `AccessibilityPreferences::detect_from_system()` which
/// queries the correct OS API on macOS, Linux, and Windows.
pub fn is_reduced_motion() -> bool {
    AccessibilityPreferences::detect_from_system().reduce_motion
}

/// Returns effective animation duration (0.0 if reduced motion is active).
pub fn effective_duration(secs: f32) -> f32 {
    if is_reduced_motion() { 0.0 } else { secs }
}

/// An object-safe version of the View trait for type erasure.
pub trait ErasedView: Send {
    fn render_erased(&self, renderer: &mut dyn Renderer, rect: Rect);
    fn name(&self) -> &'static str;
    fn flex_weight_erased(&self) -> f32;
    fn layout_erased(&self) -> Option<&dyn layout::LayoutView>;
    fn grid_placement_erased(&self) -> Option<GridPlacement>;
    fn clone_box(&self) -> Box<dyn ErasedView>;
}

impl<V: View + Clone + 'static> ErasedView for V {
    fn render_erased(&self, renderer: &mut dyn Renderer, rect: Rect) {
        self.render(renderer, rect);
    }

    fn name(&self) -> &'static str {
        std::any::type_name::<V>()
    }

    fn flex_weight_erased(&self) -> f32 {
        self.flex_weight()
    }

    fn layout_erased(&self) -> Option<&dyn layout::LayoutView> {
        self.layout()
    }

    fn grid_placement_erased(&self) -> Option<GridPlacement> {
        self.get_grid_placement()
    }

    fn clone_box(&self) -> Box<dyn ErasedView> {
        Box::new(self.clone())
    }
}

/// A view that memoizes its rendering based on a stable ID and data hash.
/// The renderer can use this to skip re-rendering the sub-tree if the data hasn't changed.
pub struct MemoView<V, F> {
    id: u64,
    data_hash: u64,
    builder: F,
    _v: std::marker::PhantomData<V>,
}

impl<V: View, F: Fn() -> V + Send + Sync> MemoView<V, F> {
    /// Create a new MemoView with a stable ID and a data hash.
    pub fn new(id: u64, data_hash: u64, builder: F) -> Self {
        Self {
            id,
            data_hash,
            builder,
            _v: std::marker::PhantomData,
        }
    }
}

impl<V: View + 'static, F: Fn() -> V + Send + Sync + 'static> View for MemoView<V, F> {
    type Body = Never;
    fn body(self) -> Self::Body {
        // SAFETY: `Never` is uninhabitable (zero variants). MemoView renders via
        // `render()` using the memoized builder closure and never exposes a body.
        unreachable!("MemoView does not have a body")
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        renderer.memoize(self.id, self.data_hash, &|r| {
            let view = (self.builder)();
            view.render(r, rect);
        });
    }
}

/// A type-erased View wrapper.
pub struct AnyView {
    inner: Box<dyn ErasedView>,
}

impl Clone for AnyView {
    fn clone(&self) -> Self {
        Self {
            inner: self.inner.clone_box(),
        }
    }
}

impl AnyView {
    pub fn new<V: View + Clone + 'static>(view: V) -> Self {
        Self {
            inner: Box::new(view),
        }
    }
}

impl View for AnyView {
    type Body = Never;
    fn body(self) -> Self::Body {
        // SAFETY: `Never` is uninhabitable. AnyView is a type-erased wrapper that
        // renders via `render_erased()` and never exposes a composable body.
        unreachable!()
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        renderer.push_vnode(rect, self.inner.name());
        self.inner.render_erased(renderer, rect);
        renderer.pop_vnode();
    }

    fn flex_weight(&self) -> f32 {
        self.inner.flex_weight_erased()
    }

    fn layout(&self) -> Option<&dyn layout::LayoutView> {
        self.inner.layout_erased()
    }

    fn get_grid_placement(&self) -> Option<GridPlacement> {
        self.inner.grid_placement_erased()
    }
}

/// SharedElementModifier enables shared-element transitions.
/// When two views share the same Bifrost Bridge ID, the Sleipnir solver will
/// interpolate their geometry and effects (blur, glow) during the transition.
#[derive(Debug, Clone, PartialEq)]
pub struct SharedElementModifier {
    pub id: String,
}

impl ViewModifier for SharedElementModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        // Register this element with the renderer for shared-element transition logic
        renderer.register_shared_element(&self.id, rect);
    }
}

/// GeometricClipModifier implements the "Geometric Slice" aesthetic.
/// It uses a signed distance field (SDF) to clip the view along a sharp angled line.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct GeometricClipModifier {
    pub angle: f32,
    pub offset: f32,
}

impl ViewModifier for GeometricClipModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        renderer.push_mjolnir_slice(self.angle, self.offset);
    }

    fn post_render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        renderer.pop_mjolnir_slice();
    }
}

/// FragmentModifier implements the "Shattering" effect.
/// It breaks the view into discrete geometric fragments that can be animated.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FragmentModifier {
    pub pieces: u32,
    pub force: f32,
}

impl ViewModifier for FragmentModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        // RADIAL SHATTER: Fragment the view into wedges
        let pieces = self.pieces.max(1);
        for i in 0..pieces {
            let progress = i as f32 / pieces as f32;
            let next_progress = (i + 1) as f32 / pieces as f32;

            let angle_start = progress * 360.0;
            let angle_end = next_progress * 360.0;

            // Wedge slice: intersection of two half-planes
            renderer.push_mjolnir_slice(angle_start, 0.0);
            renderer.push_mjolnir_slice(angle_end + 180.0, 0.0);

            // Apply radial force offset
            let mid_angle = (angle_start + angle_end) / 2.0;
            let rad = mid_angle.to_radians();
            let dx = rad.cos() * self.force;
            let dy = rad.sin() * self.force;

            let shard_rect = Rect {
                x: rect.x + dx,
                y: rect.y + dy,
                ..rect
            };

            view.render(renderer, shard_rect);

            renderer.pop_mjolnir_slice();
            renderer.pop_mjolnir_slice();
        }
    }
}

/// FrostedGlassModifier implements the Cyberpunk "Frosted Glass" aesthetic.
/// It triggers backdrop blurring and light scattering in the render pipeline.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FrostedGlassModifier {
    pub blur: f32,
    pub saturation: f32,
    pub opacity: f32,
    /// Fresnel strength multiplier. 0.0 = no fresnel, 1.0 = full.
    pub fresnel_strength: f32,
}

impl ViewModifier for FrostedGlassModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        if renderer.is_over_budget() {
            // Degrade: Use lower quality (half blur) if over budget
            renderer.bifrost(rect, self.blur * 0.5, self.saturation, self.opacity);
        } else {
            renderer.bifrost(rect, self.blur, self.saturation, self.opacity);
        }
    }
}

/// A modifier that adds a background color to a view.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct BackgroundModifier {
    pub color: [f32; 4],
}

impl ViewModifier for BackgroundModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        renderer.fill_rect(rect, self.color);
    }
}

/// A modifier that adds padding to a view.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct PaddingModifier {
    pub amount: f32,
}

impl ViewModifier for PaddingModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn transform_rect(&self, rect: Rect) -> Rect {
        Rect {
            x: rect.x + self.amount,
            y: rect.y + self.amount,
            width: (rect.width - 2.0 * self.amount).max(0.0),
            height: (rect.height - 2.0 * self.amount).max(0.0),
        }
    }

    fn transform_proposal(&self, mut proposal: SizeProposal) -> SizeProposal {
        if let Some(w) = proposal.width {
            proposal.width = Some((w - 2.0 * self.amount).max(0.0));
        }
        if let Some(h) = proposal.height {
            proposal.height = Some((h - 2.0 * self.amount).max(0.0));
        }
        proposal
    }

    fn transform_size(&self, mut size: Size) -> Size {
        size.width += 2.0 * self.amount;
        size.height += 2.0 * self.amount;
        size
    }
}

/// NeonGlowModifier implements the "Neon Glow" aesthetic.
/// It uses additive blending and multi-pass blurring to simulate glowing light.
#[derive(Debug, Clone, PartialEq)]
pub struct NeonGlowModifier {
    pub color: String,
    pub radius: f32,
    pub intensity: f32,
}

impl ViewModifier for NeonGlowModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        // Neon Glow using Mode 1 in the Surtr pipeline
        renderer.stroke_rect(rect, [0.0, 1.0, 1.0, self.intensity], self.radius / 10.0);
    }
}

/// PulsingGlowModifier implements a "breathing" neon effect.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct PulsingGlowModifier {
    pub color: [f32; 4],
    pub radius: f32,
    pub speed: f32,
}

impl ViewModifier for PulsingGlowModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        let time = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap_or_default()
            .as_secs_f32();

        // Mode 19: Dashed Border
        // Mode 20: 9-Slice / Patch Scaling
        let intensity = (time * self.speed).sin() * 0.5 + 0.5;
        let mut color = self.color;
        color[3] *= intensity;

        // Mode 1 neon glow with dynamic intensity
        renderer.stroke_rect(rect, color, self.radius);
    }
}

/// MagneticPullModifier makes a view "magnetic", subtly leaning towards or pulling the cursor.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct MagneticPullModifier {
    pub radius: f32,
    pub intensity: f32,
}

impl ViewModifier for MagneticPullModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        let [px, py] = renderer.get_pointer_position();
        let center_x = rect.x + rect.width / 2.0;
        let center_y = rect.y + rect.height / 2.0;

        let dx = px - center_x;
        let dy = py - center_y;
        let dist = (dx * dx + dy * dy).sqrt();

        let mut offset_x = 0.0;
        let mut offset_y = 0.0;

        if dist < self.radius && dist > 0.0 {
            let force = (1.0 - dist / self.radius) * self.intensity;
            offset_x = dx * force;
            offset_y = dy * force;
        }

        let magnetic_rect = Rect {
            x: rect.x + offset_x,
            y: rect.y + offset_y,
            ..rect
        };

        view.render(renderer, magnetic_rect);
    }
}

/// CursorGlowModifier adds a soft, lunar-like cursor glow to a view.
/// Named after Máni, the personification of the Moon.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CursorGlowModifier {
    pub color: [f32; 4],
    pub radius: f32,
}

impl ViewModifier for CursorGlowModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        if crate::load_system_state().realm == UiFidelityLevel::Asgard {
            renderer.mani_glow(rect, self.color, self.radius);
        }
        view.render(renderer, rect);
    }
}

/// MemoryLayerModifier themes a view based on its cognitive memory layer.
/// Episodic: Shifting aurora clouds.
/// Semantic: Crystalline gold.
/// Procedural: Heavy obsidian stone.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct MemoryLayerModifier {
    pub layer: MemoryLayer,
}

impl ViewModifier for MemoryLayerModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        let realm = crate::load_system_state().realm;
        match self.layer {
            MemoryLayer::Episodic => {
                if realm == UiFidelityLevel::Asgard {
                    renderer.bifrost(rect, 40.0, 1.2, 0.7);
                } else {
                    renderer.fill_rect(rect, [0.1, 0.12, 0.15, 0.8]);
                }
            }
            MemoryLayer::Semantic => {
                if realm == UiFidelityLevel::Asgard {
                    renderer.gungnir(rect, [1.0, 0.84, 0.0, 1.0], 15.0, 0.6);
                } else {
                    renderer.stroke_rect(rect, [0.4, 0.4, 0.4, 1.0], 1.5);
                }
            }
            MemoryLayer::Procedural => {
                renderer.fill_rect(rect, [0.05, 0.05, 0.07, 0.95]);
                let stroke_color = if realm == UiFidelityLevel::Asgard {
                    [0.3, 0.3, 0.3, 1.0]
                } else {
                    [0.2, 0.2, 0.2, 1.0]
                };
                renderer.stroke_rect(rect, stroke_color, 2.0);
            }
        }
        view.render(renderer, rect);
    }
}

/// EvolvingInteractionModifier enables self-evolving UI capabilities.
/// Named after Fafnir, the dragon who grows in power based on the gold he hoards.
/// In CVKG, 'Gold' is user attention/interaction.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct EvolvingInteractionModifier {
    /// Unique ID for tracking this component's vitality across frames.
    pub id: u64,
}

impl ViewModifier for EvolvingInteractionModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        let state = crate::load_system_state();
        let vitality = state
            .get_component_state::<f32>(self.id)
            .map(|v| *v.read().unwrap())
            .unwrap_or(1.0);

        // Calculate evolutionary growth factors
        // Max growth at vitality 5.0 (50% scale increase, strong glow)
        let growth = (vitality - 1.0).clamp(0.0, 4.0);
        let scale = 1.0 + growth * 0.12;
        let glow_intensity = growth * 0.25;

        // Feed Fafnir: Register interaction to boost vitality
        let id = self.id;
        renderer.register_handler(
            "pointermove",
            std::sync::Arc::new(move |_| {
                crate::update_system_state(|s| {
                    let mut s = s.clone();
                    let v = s
                        .get_component_state::<f32>(id)
                        .map(|v| *v.read().unwrap())
                        .unwrap_or(1.0);
                    s.set_component_state(id, (v + 0.05).min(5.0)); // Cap at 5.0
                    s
                });
            }),
        );

        if scale > 1.01 {
            renderer.push_transform([0.0, 0.0], [scale, scale], 0.0);
        }

        if glow_intensity > 0.1 && state.realm == UiFidelityLevel::Asgard {
            renderer.gungnir(rect, [1.0, 0.84, 0.0, 1.0], 15.0 * vitality, glow_intensity);
        }

        view.render(renderer, rect);

        if scale > 1.01 {
            renderer.pop_transform();
        }
    }
}

/// IntentPredictionModifier anticipates user movement and manifests holographic ghosts.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct IntentPredictionModifier;

impl ViewModifier for IntentPredictionModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        let state = crate::load_system_state();
        let pos = state.last_pointer_pos;
        let vel = state.pointer_velocity;

        // Calculate if the cursor is moving towards this rect
        let center = [rect.x + rect.width / 2.0, rect.y + rect.height / 2.0];
        let dx = center[0] - pos[0];
        let dy = center[1] - pos[1];

        // Dot product of velocity and direction to center
        let dot = vel[0] * dx + vel[1] * dy;
        let speed_sq = vel[0] * vel[0] + vel[1] * vel[1];
        let dist_sq = dx * dx + dy * dy;

        if dot > 0.0 && dist_sq < 250.0 * 250.0 && speed_sq > 0.5 && state.realm == UiFidelityLevel::Asgard {
            // Intent detected: render a subtle "ghost" reveal
            let intent_strength = (dot / (speed_sq.sqrt() * dist_sq.sqrt())).clamp(0.0, 1.0);
            renderer.stroke_rect(rect, [0.0, 0.9, 1.0, 0.3 * intent_strength], 1.5);
        }

        view.render(renderer, rect);
    }
}

/// ComplexityTelemetryModifier renders a cognitive telemetry cloud representing agent complexity.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ComplexityTelemetryModifier {
    pub complexity: f32,
}

impl ViewModifier for ComplexityTelemetryModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        if crate::load_system_state().realm == UiFidelityLevel::Asgard {
            let t = renderer.elapsed_time();
            let c = self.complexity.clamp(0.0, 1.0);

            // 1. Core Cognitive Cloud (Bifrost)
            // Turbulence increases with complexity
            let blur = 20.0 + c * 40.0;
            let turbulence_x = (t * (1.0 + c * 2.0)).sin() * 8.0 * c;
            let turbulence_y = (t * (0.8 + c * 1.5)).cos() * 5.0 * c;
            renderer.bifrost(
                rect.offset(turbulence_x, turbulence_y),
                blur,
                0.8 + c * 0.4,
                0.25,
            );

            // 2. Synaptic Discharge (Gungnir pulses)
            if c > 0.2 {
                let pulse = (t * (3.0 + c * 5.0)).sin().abs() * c;
                let color = [0.0, 0.9, 1.0, 0.4 * pulse]; // Cyan synaptic pulse
                renderer.gungnir(rect, color, 12.0 + c * 24.0, 0.6 * pulse);
            }

            // 3. Unstable Resonance (Magenta/Red shift for high complexity)
            if c > 0.7 {
                let instability = (t * 15.0).cos().abs() * (c - 0.7) * 3.3;
                let warning_color = [1.0, 0.0, 0.4, 0.12 * instability];
                renderer.fill_rect(rect, warning_color);
                renderer.stroke_rect(rect, [1.0, 0.0, 0.2, 0.45 * instability], 1.8);
            }
        }
        view.render(renderer, rect);
    }
}

/// ObservabilityOverlayModifier bestows omniscient observability over the entire scene graph.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ObservabilityOverlayModifier;

impl ViewModifier for ObservabilityOverlayModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        let state = crate::load_system_state();
        let t = renderer.elapsed_time();

        // 1. Render Background content
        view.render(renderer, rect);

        if state.realm == UiFidelityLevel::Asgard {
            // 2. Bestow Odin's Eye (Atmospheric Overlay)
            // Soft, large circular pulse representing the 'Eye'
            let eye_pulse = (t * 0.5).sin().abs() * 0.05;
            renderer.draw_radial_gradient(
                rect,
                [0.0, 0.6, 0.8, 0.08 + eye_pulse], // Inner Cyan
                [0.0, 0.0, 0.0, 0.0],              // Outer Black
            );

            // 3. Hugin (Thought) Telemetry - Left Side
            let hugin_rect = Rect {
                x: rect.x + 20.0,
                y: rect.y + 40.0,
                width: 200.0,
                height: rect.height - 80.0,
            };
            renderer.draw_text(
                "HUGIN: THOUGHT",
                hugin_rect.x,
                hugin_rect.y,
                10.0,
                [0.0, 1.0, 1.0, 0.6],
            );
            for (i, thought) in state.thoughts.iter().rev().take(10).enumerate() {
                renderer.draw_text(
                    thought,
                    hugin_rect.x,
                    hugin_rect.y + 20.0 + i as f32 * 14.0,
                    9.0,
                    [1.0, 1.0, 1.0, 0.4],
                );
            }

            // 4. Munin (Memory) Telemetry - Right Side
            let munin_rect = Rect {
                x: rect.x + rect.width - 220.0,
                y: rect.y + 40.0,
                width: 200.0,
                height: rect.height - 80.0,
            };
            renderer.draw_text(
                "MUNIN: MEMORY",
                munin_rect.x,
                munin_rect.y,
                10.0,
                [1.0, 0.84, 0.0, 0.6],
            );
            for (i, node) in state.nodes.iter().take(10).enumerate() {
                let opacity = (node.weight.min(1.0)) * 0.5;
                renderer.draw_text(
                    &node.id,
                    munin_rect.x,
                    munin_rect.y + 20.0 + i as f32 * 14.0,
                    9.0,
                    [1.0, 1.0, 1.0, opacity],
                );
            }

            // 5. Omniscient Focus Beams (Gungnir Beams)
            if let Some(focus_id) = &state.odin_focus {
                // Visualize causal links to the focus node
                renderer.draw_text(
                    &format!("EYE FOCUS: {}", focus_id),
                    rect.x + rect.width / 2.0 - 50.0,
                    rect.y + 20.0,
                    12.0,
                    [0.0, 1.0, 1.0, 0.8],
                );

                // In a real implementation, we would find the rect of the focus_id component.
                // For the 'Eye', we manifest a central beam of wisdom.
                renderer.gungnir(
                    Rect {
                        x: rect.x + rect.width / 2.0 - 1.0,
                        y: rect.y,
                        width: 2.0,
                        height: rect.height,
                    },
                    [0.0, 1.0, 1.0, 1.0],
                    20.0,
                    0.4,
                );
            }
        }
    }
}

/// Sleipnir spring parameters for the physics solver
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct SpringParams {
    pub stiffness: f32,
    pub damping: f32,
    pub mass: f32,
}

impl SpringParams {
    pub fn snappy() -> Self {
        Self {
            stiffness: 230.0,
            damping: 22.0,
            mass: 1.0,
        }
    }
    pub fn fluid() -> Self {
        Self {
            stiffness: 170.0,
            damping: 26.0,
            mass: 1.0,
        }
    }
    pub fn heavy() -> Self {
        Self {
            stiffness: 90.0,
            damping: 20.0,
            mass: 1.0,
        }
    }
    pub fn bouncy() -> Self {
        Self {
            stiffness: 190.0,
            damping: 14.0,
            mass: 1.0,
        }
    }
}

impl Default for SpringParams {
    fn default() -> Self {
        Self::fluid()
    }
}

#[derive(Debug, Clone, Copy, PartialEq)]
struct SolverState {
    x: f32,
    v: f32,
}

/// SpringSolver implements a 4th-order Runge-Kutta (RK4) integration for springs.
/// This provides superior stability for high-fidelity interactive motion.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct SpringSolver {
    params: SpringParams,
    target: f32,
    state: SolverState,
}

impl SpringSolver {
    /// Create a new solver with a target value and starting state.
    pub fn new(params: SpringParams, target: f32, current: f32) -> Self {
        Self {
            params,
            target,
            state: SolverState { x: current, v: 0.0 },
        }
    }

    /// Advance the simulation by dt seconds using RK4 integration.
    pub fn tick(&mut self, dt: f32) -> f32 {
        if dt <= 0.0 {
            return self.state.x;
        }

        // Use a fixed time step for stability if dt is too large
        let mut remaining = dt;
        let step = 1.0 / 120.0;

        while remaining > 0.0 {
            let d = remaining.min(step);
            self.step(d);
            remaining -= d;
        }

        self.state.x
    }

    fn step(&mut self, dt: f32) {
        let a = self.evaluate(self.state, 0.0, SolverState { x: 0.0, v: 0.0 });
        let b = self.evaluate(self.state, dt * 0.5, a);
        let c = self.evaluate(self.state, dt * 0.5, b);
        let d = self.evaluate(self.state, dt, c);

        let dxdt = 1.0 / 6.0 * (a.x + 2.0 * (b.x + c.x) + d.x);
        let dvdt = 1.0 / 6.0 * (a.v + 2.0 * (b.v + c.v) + d.v);

        self.state.x += dxdt * dt;
        self.state.v += dvdt * dt;
    }

    fn evaluate(&self, initial: SolverState, dt: f32, d: SolverState) -> SolverState {
        let state = SolverState {
            x: initial.x + d.x * dt,
            v: initial.v + d.v * dt,
        };
        let force =
            -self.params.stiffness * (state.x - self.target) - self.params.damping * state.v;
        let mass = self.params.mass.max(0.001);
        SolverState {
            x: state.v,
            v: force / mass,
        }
    }

    pub fn is_settled(&self) -> bool {
        (self.state.x - self.target).abs() < 0.001 && self.state.v.abs() < 0.001
    }

    pub fn set_target(&mut self, target: f32) {
        self.target = target;
    }

    pub fn current_value(&self) -> f32 {
        self.state.x
    }
}

/// SpringAnimationModifier handles physics-based animations via the Sleipnir RK4 solver.
#[derive(Debug, Clone, PartialEq)]
pub struct SpringAnimationModifier {
    pub id: u64,
    pub target: f32,
    pub params: SpringParams,
}

impl ViewModifier for SpringAnimationModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        let state = load_system_state();

        // Try to fetch the solver from persistent state.
        let solver_lock_opt = state.get_component_state::<SpringSolver>(self.id);

        let current_val;

        if let Some(lock) = solver_lock_opt {
            // Found a solver. Tick it.
            let mut solver = lock.write().unwrap();
            solver.set_target(self.target);
            current_val = solver.tick(renderer.delta_time());

            // If the solver hasn't settled yet, request another frame.
            if !solver.is_settled() {
                renderer.request_redraw();
            }
        } else {
            // First time seeing this ID. Initialize solver state.
            let solver = SpringSolver::new(
                self.params,
                self.target,
                self.target, // Initialize at target to avoid jump on first frame
            );

            // Insert into registry for next frame.
            get_system_state().rcu(|old| {
                let mut new_state = (**old).clone();
                new_state.set_component_state(self.id, solver);
                new_state
            });

            current_val = self.target;
        }

        // Apply the solved value as a vertical translation.
        renderer.push_transform([0.0, current_val], [1.0, 1.0], 0.0);
        view.render(renderer, rect);
        renderer.pop_transform();
    }
}

/// TransformModifier applies a 2D transform (translation, scale, rotation) to its child.
/// This modifier is "layout-neutral" and can be animated without re-running the layout engine.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct TransformModifier {
    pub translation: [f32; 2],
    pub scale: [f32; 2],
    pub rotation: f32,
}

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

impl TransformModifier {
    pub fn new() -> Self {
        Self {
            translation: [0.0, 0.0],
            scale: [1.0, 1.0],
            rotation: 0.0,
        }
    }

    pub fn translate(mut self, x: f32, y: f32) -> Self {
        self.translation = [x, y];
        self
    }

    pub fn scale(mut self, x: f32, y: f32) -> Self {
        self.scale = [x, y];
        self
    }

    pub fn rotate(mut self, radians: f32) -> Self {
        self.rotation = radians;
        self
    }
}

impl ViewModifier for TransformModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        renderer.push_transform(self.translation, self.scale, self.rotation);
        view.render(renderer, rect);
        renderer.pop_transform();
    }
}

/// LifecycleModifier handles on_appear and on_disappear hooks.

#[derive(Clone)]
pub struct LifecycleModifier {
    pub on_appear: Option<Arc<dyn Fn() + Send + Sync>>,
    pub on_disappear: Option<Arc<dyn Fn() + Send + Sync>>,
}

impl ViewModifier for LifecycleModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }
}

/// OpacityModifier fades this view and all its descendants to the given alpha.
/// The renderer is expected to honour `push_opacity`/`pop_opacity` on the Renderer trait.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct OpacityModifier {
    pub opacity: f32,
}

impl ViewModifier for OpacityModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        renderer.push_opacity(self.opacity);
    }

    fn post_render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        renderer.pop_opacity();
    }
}

/// OnClickModifier registers a click handler for this view.
#[derive(Clone)]
pub struct OnClickModifier {
    pub action: Arc<dyn Fn() + Send + Sync>,
}

impl ViewModifier for OnClickModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        let action = self.action.clone();
        renderer.register_handler(
            "pointerclick",
            std::sync::Arc::new(move |event| {
                if let Event::PointerClick { .. } = event {
                    (action)();
                }
            }),
        );
    }
}

/// OnPointerEnterModifier registers a pointer enter handler.
#[derive(Clone)]
pub struct OnPointerEnterModifier {
    pub action: Arc<dyn Fn() + Send + Sync>,
}

impl ViewModifier for OnPointerEnterModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        let action = self.action.clone();
        renderer.register_handler(
            "pointerenter",
            std::sync::Arc::new(move |event| {
                if let Event::PointerEnter = event {
                    (action)();
                }
            }),
        );
    }
}

/// OnPointerLeaveModifier registers a pointer leave handler.
#[derive(Clone)]
pub struct OnPointerLeaveModifier {
    pub action: Arc<dyn Fn() + Send + Sync>,
}

impl ViewModifier for OnPointerLeaveModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        let action = self.action.clone();
        renderer.register_handler(
            "pointerleave",
            std::sync::Arc::new(move |event| {
                if let Event::PointerLeave = event {
                    (action)();
                }
            }),
        );
    }
}

/// OnPointerMoveModifier registers a pointer move handler.
#[derive(Clone)]
pub struct OnPointerMoveModifier {
    pub action: Arc<dyn Fn(f32, f32) + Send + Sync>,
}

impl ViewModifier for OnPointerMoveModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        let action = self.action.clone();
        renderer.register_handler(
            "pointermove",
            std::sync::Arc::new(move |event| {
                if let Event::PointerMove { x, y, .. } = event {
                    (action)(x, y);
                }
            }),
        );
    }
}

/// OnPointerDownModifier registers a pointer down handler.
#[derive(Clone)]
pub struct OnPointerDownModifier {
    pub action: Arc<dyn Fn() + Send + Sync>,
}

impl ViewModifier for OnPointerDownModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        let action = self.action.clone();
        renderer.register_handler(
            "pointerdown",
            std::sync::Arc::new(move |event| {
                if let Event::PointerDown { .. } = event {
                    (action)();
                }
            }),
        );
    }
}

/// OnPointerUpModifier registers a pointer up handler.
#[derive(Clone)]
pub struct OnPointerUpModifier {
    pub action: Arc<dyn Fn() + Send + Sync>,
}

impl ViewModifier for OnPointerUpModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        let action = self.action.clone();
        renderer.register_handler(
            "pointerup",
            std::sync::Arc::new(move |event| {
                if let Event::PointerUp { .. } = event {
                    (action)();
                }
            }),
        );
    }
}

/// ForegroundColorModifier overrides the foreground (text / icon) color inherited
/// by all descendants until another ForegroundColorModifier is encountered.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ForegroundColorModifier {
    pub color: [f32; 4],
}

impl ViewModifier for ForegroundColorModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }
}

/// ClipModifier restricts all child drawing to the view's layout rectangle.
/// The renderer must support `push_clip_rect`/`pop_clip_rect`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ClipModifier;

impl ViewModifier for ClipModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        renderer.push_clip_rect(rect);
    }

    fn post_render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
        renderer.pop_clip_rect();
    }
}

/// BorderModifier draws a solid-color border around the view bounds.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct BorderModifier {
    pub color: [f32; 4],
    pub width: f32,
}

impl ViewModifier for BorderModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        renderer.stroke_rect(rect, self.color, self.width);
    }
}

// Primitive (leaf) views implement Never as body
#[doc(hidden)]
pub enum Never {}

impl View for Never {
    type Body = Never;
    fn body(self) -> Never {
        // SAFETY: `Never` is an uninhabitable enum (zero variants), so this function
        // can never be called with a valid value and can never return.
        unreachable!()
    }
}

/// EmptyView - A view that renders nothing and takes up no space.
#[derive(Debug, Clone, Copy, Default)]
pub struct EmptyView;

impl View for EmptyView {
    type Body = Never;
    fn body(self) -> Self::Body {
        // SAFETY: `Never` is uninhabitable. EmptyView renders nothing and has no
        // composable body -- it registers zero paint commands.
        unreachable!()
    }
    fn render(&self, _renderer: &mut dyn Renderer, _rect: Rect) {}
    fn intrinsic_size(&self, _renderer: &mut dyn Renderer, _proposal: SizeProposal) -> Size {
        Size {
            width: 0.0,
            height: 0.0,
        }
    }
}

/// A view that has been transformed by a modifier.
/// Section 4.3: "Each modifier implements ViewModifier and produces a ModifiedView<Inner, Self>."
#[derive(Clone)]
pub struct ModifiedView<V, M> {
    view: V,
    modifier: M,
}

impl<V: View, M: ViewModifier> ModifiedView<V, M> {
    #[doc(hidden)]
    pub fn new(view: V, modifier: M) -> Self {
        Self { view, modifier }
    }
}

impl<V: View, M: ViewModifier> View for ModifiedView<V, M> {
    type Body = ModifiedView<V::Body, M>;

    fn body(self) -> Self::Body {
        ModifiedView {
            view: self.view.body(),
            modifier: self.modifier.clone(),
        }
    }

    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        self.modifier.render_view(&self.view, renderer, rect);
    }

    fn intrinsic_size(&self, renderer: &mut dyn Renderer, proposal: SizeProposal) -> Size {
        self.modifier.measure_view(&self.view, renderer, proposal)
    }

    fn flex_weight(&self) -> f32 {
        self.modifier.child_flex_weight(&self.view)
    }

    fn layout(&self) -> Option<&dyn layout::LayoutView> {
        self.modifier.layout().or_else(|| self.view.layout())
    }

    fn get_grid_placement(&self) -> Option<GridPlacement> {
        self.modifier
            .get_grid_placement()
            .or_else(|| self.view.get_grid_placement())
    }
}

pub trait ViewModifier: Send + Clone {
    fn modify<V: View>(self, content: V) -> impl View;

    /// Returns the grid placement configuration if this modifier defines one.
    fn get_grid_placement(&self) -> Option<GridPlacement> {
        None
    }

    /// Core rendering hook called before child views.
    fn render(&self, _renderer: &mut dyn Renderer, _rect: Rect) {}

    /// Cleanup hook called after child views.
    fn post_render(&self, _renderer: &mut dyn Renderer, _rect: Rect) {}

    /// Allows a modifier to completely override or wrap the rendering of its child.
    /// Default implementation performs a standard push -> transform -> render child -> pop sequence.
    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        self.render(renderer, rect);
        let child_rect = self.transform_rect(rect);
        view.render(renderer, child_rect);
        self.post_render(renderer, rect);
    }

    fn transform_rect(&self, rect: Rect) -> Rect {
        rect
    }

    /// Allows a modifier to transform the layout proposal before it reaches the child.
    fn transform_proposal(&self, proposal: SizeProposal) -> SizeProposal {
        proposal
    }

    /// Allows a modifier to transform the resulting size from the child.
    fn transform_size(&self, size: Size) -> Size {
        size
    }

    /// Measure hook that coordinates size propagation.
    fn measure_view<V: View>(
        &self,
        view: &V,
        renderer: &mut dyn Renderer,
        proposal: SizeProposal,
    ) -> Size {
        let child_proposal = self.transform_proposal(proposal);
        let child_size = view.intrinsic_size(renderer, child_proposal);
        self.transform_size(child_size)
    }

    /// Allows a modifier to override or pass through the child's flex weight.
    fn child_flex_weight<V: View>(&self, view: &V) -> f32 {
        view.flex_weight()
    }

    fn layout(&self) -> Option<&dyn layout::LayoutView> {
        None
    }
}

/// Captures the depth of every stack-pushing operation on the `Renderer`.
///
/// Created via `Renderer::snapshot_render_state()` and consumed by
/// `Renderer::restore_render_state()`. The renderer uses this to recover
/// from mid-render panics -- any items pushed beyond the snapshot point
/// are popped so sibling views drawn afterward don't inherit leaked
/// clip / opacity / transform / shadow / vnode / mjolnir-slice state.
///
/// Frame-scoped: the renderer resets all stacks in `begin_frame()` so a
/// snapshot taken in one frame is meaningless in another.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct RenderStateSnapshot {
    pub clip_depth: u32,
    pub opacity_depth: u32,
    pub slice_depth: u32,
    pub shadow_depth: u32,
    pub transform_depth: u32,
    pub vnode_depth: u32,
}

/// TelemetryData tracks real-time performance metrics for the GPU renderer.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct TelemetryData {
    pub frame_time_ms: f32,
    /// Total frame budget in milliseconds for the active policy.
    pub frame_budget_ms: f32,
    /// Remaining frame budget after the frame completed; negative means over budget.
    pub frame_budget_remaining_ms: f32,
    /// Remaining layout budget after layout completed; negative means the layout slice was exceeded.
    pub layout_budget_remaining_ms: f32,
    /// Whether the frame exceeded the total budget.
    pub frame_over_budget: bool,
    /// Whether the layout phase exceeded its budget slice.
    pub layout_over_budget: bool,
    /// 99th percentile frame time over the last window, used to detect tail latency.
    pub p99_frame_time_ms: f32,
    /// Statistical jitter (variance in frame timing).
    pub frame_jitter_ms: f32,
    /// Indicates if a hardware stall (DRAM refresh, thermal spike) was detected.
    pub hardware_stall_detected: bool,

    // Pass timing
    pub input_time_ms: f32,
    pub state_flush_time_ms: f32,
    pub layout_time_ms: f32,
    pub draw_time_ms: f32,
    pub gpu_submit_time_ms: f32,

    pub draw_calls: u32,
    pub vertices: u32,

    /// Global Berserker Pipeline Intensity (0.0 - 1.0+)
    pub berserker_rage: f32,

    // Memory breakdown
    pub vram_usage_mb: f32,
    pub vram_textures_mb: f32,
    pub vram_buffers_mb: f32,
    pub vram_pipelines_mb: f32,
    /// Indicates if the Mega-Atlas or VRAM pools are at capacity.
    pub vram_exhausted: bool,
}

/// Configuration for render-loop frame timing and degradation strategies.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct FrameBudget {
    /// Target frame time in milliseconds (default: 16.0 for 60FPS)
    pub target_ms: f32,
    /// If true, the renderer is allowed to dynamically skip non-critical effects
    /// (like heavy blurs or complex shadows) when the budget is exceeded.
    pub allow_degradation: bool,
}

impl Default for FrameBudget {
    fn default() -> Self {
        Self {
            target_ms: 16.0,
            allow_degradation: true,
        }
    }
}

/// The Renderer trait defines the atomic drawing operations for all CVKG backends.
/// This trait is object-safe and used by the View::render system.
/// # Implementation Requirements
/// 1. Coordinate system is origin-top-left (0,0) with Y increasing downwards.
/// 2. Colors are [R, G, B, A] in the [0.0, 1.0] range.
/// 3. All operations must be batchable by the underlying backend.
///    Trait providing timing information for the render loop.
pub trait ElapsedTime {
    /// Returns the cumulative time since the renderer started in seconds.
    fn elapsed_time(&self) -> f32;

    /// Returns the time elapsed since the last frame in seconds.
    fn delta_time(&self) -> f32;
}

/// The Renderer trait defines the atomic drawing operations for all CVKG backends.
/// This trait is object-safe and used by the View::render system.
/// # Implementation Requirements
/// 1. Coordinate system is origin-top-left (0,0) with Y increasing downwards.
/// 2. Colors are [R, G, B, A] in the [0.0, 1.0] range.
/// 3. All operations must be batchable by the underlying backend.
///
/// Sub-traits in `renderer/mod.rs` (RendererCore, RendererShapes, etc.) provide
/// logical groupings for consumer code. Backends implement this monolithic trait;
/// the sub-traits are aspirational documentation and NOT enforced as supertraits
/// to avoid method ambiguity (sub-traits re-declare the same methods).
pub trait Renderer: ElapsedTime + Send {
    /// Requests that the renderer redraws as soon as possible.
    /// Used for continuous animations.
    fn request_redraw(&mut self) {}

    /// Returns true if the current frame is over the time budget.
    /// This can be used to skip expensive visual effects.
    fn is_over_budget(&self) -> bool {
        false
    }

    // ── Filled shapes ────────────────────────────────────────────────────
    fn fill_rect(&mut self, rect: Rect, color: [f32; 4]);
    fn fill_rounded_rect(&mut self, rect: Rect, radius: f32, color: [f32; 4]);
    /// Fill an ellipse/circle that fits inside `rect`.
    fn fill_ellipse(&mut self, rect: Rect, color: [f32; 4]);

    /// Draw a background image that fills the entire rect.
    /// This is a convenience wrapper around `draw_image` for the common case
    /// of a full-rect background. The image must have been pre-warmed via
    /// `prewarm_vram` before the first frame.
    fn draw_background_image(&mut self, image_name: &str, rect: Rect) {
        Renderer::draw_image(self, image_name, rect);
    }

    /// Fill a rounded rect with glass material for frosted backdrop effect.
    /// This is the proper way to render glass cards for macOS Tahoe-style blur.
    /// The blur_radius controls the intensity of the backdrop blur.
    fn fill_glass_rect(&mut self, rect: Rect, radius: f32, blur_radius: f32) {
        // Default no-op implementation; GPU backend overrides
        let _ = (rect, radius, blur_radius);
    }
    /// Fill a rounded rect with glass material with explicit intensity control.
    /// `glass_intensity` ranges from 0.0 (solid) to 1.0 (full glass). Default: 1.0.
    fn fill_glass_rect_with_intensity(&mut self, rect: Rect, radius: f32, blur_radius: f32, glass_intensity: f32) {
        let _ = (rect, radius, blur_radius, glass_intensity);
    }
    /// Fill a rounded rect with glass material with explicit tint color and intensity.
    /// `tint_color` is the glass fill color (RGBA). `glass_intensity` ranges from 0.0 (solid) to 1.0 (full glass).
    fn fill_glass_rect_with_tint(&mut self, rect: Rect, radius: f32, blur_radius: f32, tint_color: [f32; 4], glass_intensity: f32) {
        // Default: delegate to intensity-only version using tint color as a simple fill
        let _ = (rect, radius, blur_radius, tint_color, glass_intensity);
    }
    /// Fill a rounded rect with glass material, modulated by touch pressure.
    /// `pressure` ranges from 0.0 (no touch) to 1.0 (full pressure).
    /// When pressure > 0, refraction distortion is scaled by pressure amount.
    /// Desktop stub: pressure is always 1.0 for mouse clicks, 0.0 otherwise.
    fn fill_glass_rect_with_pressure(&mut self, rect: Rect, radius: f32, blur_radius: f32, pressure: f32) {
        // Default: delegate to standard glass with intensity = pressure
        Renderer::fill_glass_rect_with_intensity(self, rect, radius, blur_radius, pressure);
    }

    /// Fill a squircle (superellipse) for Apple-style icon silhouettes.
    /// `n` controls the squareness: 2.0 = rounded rect, 4.0 = classic squircle, higher = more square.
    fn fill_squircle(&mut self, rect: Rect, _n: f32, color: [f32; 4]) {
        // Default fallback to rounded rect
        Renderer::fill_rounded_rect(self, rect, rect.width.min(rect.height) * 0.22, color);
    }

    /// Stroke a squircle (superellipse) outline.
    fn stroke_squircle(&mut self, rect: Rect, _n: f32, color: [f32; 4], stroke_width: f32) {
        Renderer::stroke_rounded_rect(self, rect, rect.width.min(rect.height) * 0.22, color, stroke_width);
    }

    /// Draw a focus ring around a rect (for keyboard navigation accessibility).
    /// `offset` is the gap between the rect and the ring, `width` is the ring thickness.
    fn draw_focus_ring(&mut self, rect: Rect, radius: f32, offset: f32, width: f32, color: [f32; 4]) {
        // Default fallback to a stroked rounded rect
        let ring_rect = Rect {
            x: rect.x - offset,
            y: rect.y - offset,
            width: rect.width + 2.0 * offset,
            height: rect.height + 2.0 * offset,
        };
        Renderer::stroke_rounded_rect(self, ring_rect, radius + offset, color, width);
    }

    /// Draw a high-fidelity 3D cube inside the given rectangle using specialized shader logic.
    /// `rotation` is [pitch, yaw, roll] in radians.
    fn draw_3d_cube(&mut self, _rect: Rect, _color: [f32; 4], _rotation: [f32; 3]) {}

    // ── Stroked shapes ───────────────────────────────────────────────────
    fn stroke_rect(&mut self, rect: Rect, color: [f32; 4], stroke_width: f32);
    fn stroke_rounded_rect(&mut self, rect: Rect, radius: f32, color: [f32; 4], stroke_width: f32);
    /// Stroke an ellipse/circle that fits inside `rect`.
    fn stroke_ellipse(&mut self, rect: Rect, color: [f32; 4], stroke_width: f32);
    /// Draw a straight line from (x1,y1) to (x2,y2).
    fn draw_line(&mut self, x1: f32, y1: f32, x2: f32, y2: f32, color: [f32; 4], stroke_width: f32);
    /// Fill a polygon defined by a set of vertices.
    fn fill_polygon(&mut self, _vertices: &[[f32; 2]], _color: [f32; 4]) {}
    /// Stroke a polygon defined by a set of vertices.
    fn stroke_polygon(&mut self, _vertices: &[[f32; 2]], _color: [f32; 4], _stroke_width: f32) {}

    // ── Text ─────────────────────────────────────────────────────────────
    fn draw_text(&mut self, text: &str, x: f32, y: f32, size: f32, color: [f32; 4]) {
        let span = cvkg_runic_text::TextSpan::new(
            text,
            cvkg_runic_text::TextStyle {
                family: "Inter".to_string(),
                font_size: size,
                color: [(color[0]*255.0) as u8, (color[1]*255.0) as u8, (color[2]*255.0) as u8, (color[3]*255.0) as u8],
                fallback_families: vec![
                    "SF Pro".to_string(),
                    "SF Pro Text".to_string(),
                    "Helvetica Neue".to_string(),
                    "Helvetica".to_string(),
                    "Arial".to_string(),
                    "sans-serif".to_string(),
                ],
                ..Default::default()
            },
        );
        if let Some(shaped) = Renderer::shape_rich_text(
            self,
            &[span],
            None,
            cvkg_runic_text::TextAlign::Start,
            cvkg_runic_text::TextOverflow::Visible,
        ) {
            Renderer::draw_shaped_text(self, &shaped, x, y);
        }
    }

    /// Measure the width and height of the specified text.
    fn measure_text(&mut self, text: &str, size: f32) -> (f32, f32) {
        let span = cvkg_runic_text::TextSpan::new(
            text,
            cvkg_runic_text::TextStyle {
                family: "Inter".to_string(),
                font_size: size,
                fallback_families: vec![
                    "SF Pro".to_string(),
                    "SF Pro Text".to_string(),
                    "Helvetica Neue".to_string(),
                    "Helvetica".to_string(),
                    "Arial".to_string(),
                    "sans-serif".to_string(),
                ],
                ..Default::default()
            },
        );
        if let Some(shaped) = Renderer::shape_rich_text(
            self,
            &[span],
            None,
            cvkg_runic_text::TextAlign::Start,
            cvkg_runic_text::TextOverflow::Visible,
        ) {
            let scale = self.text_scale_factor().max(1.0);
            (shaped.width / scale, shaped.height / scale)
        } else {
            (0.0, 0.0)
        }
    }

    /// Return the baseline offset (ascent) for the given text and size.
    /// This is the distance from the text origin (y in draw_text) to the baseline.
    /// Default returns 0.0; override in renderers that support text shaping.
    fn measure_text_baseline(&mut self, text: &str, size: f32) -> f32 {
        let span = cvkg_runic_text::TextSpan::new(
            text,
            cvkg_runic_text::TextStyle {
                family: "Inter".to_string(),
                font_size: size,
                fallback_families: vec![
                    "SF Pro".to_string(),
                    "SF Pro Text".to_string(),
                    "Helvetica Neue".to_string(),
                    "Helvetica".to_string(),
                    "Arial".to_string(),
                    "sans-serif".to_string(),
                ],
                ..Default::default()
            },
        );
        if let Some(shaped) = Renderer::shape_rich_text(
            self,
            &[span],
            None,
            cvkg_runic_text::TextAlign::Start,
            cvkg_runic_text::TextOverflow::Visible,
        ) {
            shaped.ascent / self.text_scale_factor().max(1.0)
        } else {
            0.0
        }
    }

    /// Scale factor used by text measurement helpers.
    ///
    /// Renderers that shape text in device pixels should return their current
    /// device scale so `measure_text` and `measure_text_baseline` stay in logical pixels.
    fn text_scale_factor(&self) -> f32 {
        1.0
    }

    fn shape_rich_text(
        &mut self,
        _spans: &[cvkg_runic_text::TextSpan],
        _max_width: Option<f32>,
        _align: cvkg_runic_text::TextAlign,
        _overflow: cvkg_runic_text::TextOverflow,
    ) -> Option<cvkg_runic_text::ShapedText> {
        None
    }

    fn draw_shaped_text(&mut self, _text: &cvkg_runic_text::ShapedText, _x: f32, _y: f32) {}

    // ── Images & textures ────────────────────────────────────────────────
    /// Draw a texture (GPU-side) at the specified rect.
    fn draw_texture(&mut self, _texture_id: u32, _rect: Rect) {}
    /// Draw an image asset by name or path.
    fn draw_image(&mut self, _image_name: &str, _rect: Rect) {}
    /// Load an image asset from memory.
    fn load_image(&mut self, _name: &str, _data: &[u8]) {}
    /// Pre-warm the renderer with assets. Implementations can use this
    /// to populate texture atlases or warm up shader caches.
    fn prewarm_vram(&mut self, _assets: Vec<(String, Vec<u8>)>) {}

    /// Get the current pointer (mouse/touch) position.
    fn get_pointer_position(&self) -> [f32; 2] {
        [0.0, 0.0]
    }

    // ── Data Visualization ───────────────────────────────────────────────
    /// Upload raw float data as a GPU texture for heatmap rendering.
    fn upload_data_texture(&mut self, _id: &str, _data: &[f32], _width: u32, _height: u32) {}
    /// Draw a heatmap using a previously uploaded data texture.
    fn draw_heatmap(&mut self, _texture_id: &str, _rect: Rect, _palette: &str) {}

    // ── 3D Objects ───────────────────────────────────────────────────────
    /// Draw a 3D mesh.
    fn draw_mesh(&mut self, _mesh: &Mesh, _color: [f32; 4], _transform: glam::Mat4) {}

    /// Draw a 3D mesh with full material and transform support.
    fn draw_mesh_3d(&mut self, _mesh: &Mesh, _material: &Material3D, _transform: &Transform3D) {}

    /// Set the 3D camera for perspective/orthographic projection.
    /// If not called, rendering defaults to the 2D orthographic projection.
    fn set_camera_3d(&mut self, _camera: &Camera3D) {}

    /// Push a 3D transform onto the transform stack.
    /// All subsequent drawing is affected until `pop_transform_3d`.
    fn push_transform_3d(&mut self, _transform: &Transform3D) {}

    /// Pop the most recently pushed 3D transform.
    fn pop_transform_3d(&mut self) {}

    /// Render a 3D scene graph node. Reads position_3d, rotation_3d, scale_3d
    /// from the node and emits the appropriate draw call.
    /// Default implementation is a no-op; 3D renderers override this.
    ///
    /// `position`: [x, y, z] world-space position
    /// `rotation`: [x, y, z, w] quaternion rotation
    /// `scale`: [x, y, z] scale factors
    /// `color`: [r, g, b, a] base color for unlit rendering
    fn render_scene_node_3d(
        &mut self,
        _position: [f32; 3],
        _rotation: [f32; 4],
        _scale: [f32; 3],
        _color: [f32; 4],
        _meshes: &[Mesh],
    ) {
        // Default no-op: 2D renderers ignore 3D scene nodes
    }

    /// Draw a linear gradient between two colors at the specified angle.
    fn draw_linear_gradient(
        &mut self,
        _rect: Rect,
        _start_color: [f32; 4],
        _end_color: [f32; 4],
        _angle: f32,
    ) {
    }
    /// Draw a radial gradient between two colors.
    fn draw_radial_gradient(
        &mut self,
        _rect: Rect,
        _inner_color: [f32; 4],
        _outer_color: [f32; 4],
    ) {
    }
    /// Draw a high-fidelity drop shadow for a rounded rectangle.
    fn draw_drop_shadow(
        &mut self,
        _rect: Rect,
        _radius: f32,
        _color: [f32; 4],
        _blur: f32,
        _spread: f32,
    ) {
    }
    /// Draw a dashed border for a rounded rectangle.
    fn stroke_dashed_rounded_rect(
        &mut self,
        _rect: Rect,
        _radius: f32,
        _color: [f32; 4],
        _width: f32,
        _dash: f32,
        _gap: f32,
    ) {
    }
    /// Draw a 9-slice / patch scaled image.
    fn draw_9slice(
        &mut self,
        _image_name: &str,
        _rect: Rect,
        _left: f32,
        _top: f32,
        _right: f32,
        _bottom: f32,
    ) {
    }

    // ── Clipping ─────────────────────────────────────────────────────────
    /// Push a clip rectangle.  All subsequent drawing is clipped to `rect`.
    /// Implementations that do not support clipping may ignore this call.
    fn push_clip_rect(&mut self, _rect: Rect) {}
    /// Pop the most recently pushed clip rectangle.
    fn pop_clip_rect(&mut self) {}
    /// Get the current clip rectangle in screen coordinates.
    /// Returns a rect covering the entire screen if no clip is active.
    fn current_clip_rect(&self) -> Rect {
        Rect::new(-10000.0, -10000.0, 20000.0, 20000.0)
    }

    // ── Global opacity ───────────────────────────────────────────────────
    /// Set a global opacity multiplier applied to all subsequent draw calls
    /// until `pop_opacity` is called.  `opacity` is in [0.0, 1.0].
    fn push_opacity(&mut self, _opacity: f32) {}
    /// Restore the previous opacity level.
    fn pop_opacity(&mut self) {}

    // ── Berserker Pipeline State ─────────────────────────────────────────
    fn set_theme(&mut self, _theme: ColorTheme) {}
    fn set_rage(&mut self, _rage: f32) {}
    fn set_berserker_mode(&mut self, _state: RenderIntensityMode) {}
    fn trigger_shatter_event(&mut self, _origin: [f32; 2], _force: f32) {}
    /// Set the fireball position for dynamic glass specular highlights.
    fn set_fireball_pos(&mut self, _pos: [f32; 2]) {}
    /// Set the desktop scene preset (Aurora, Void, Nebula, Glitch, Yggdrasil).
    fn set_scene(&mut self, _scene: &str) {}
    /// Set the desktop scene by name. Case-insensitive.
    /// Supports: "aurora", "void", "nebula", "glitch", "yggdrasil".
    /// Aliases: "empty", "none", "blank" → Void.
    fn set_scene_by_name(&mut self, name: &str) {
        if let Some(preset) = resolve_scene_by_name(name) {
            Renderer::set_scene_preset(self, preset);
        }
    }

    // ── Export & Print ───────────────────────────────────────────────────
    /// Capture the current frame as a PNG byte buffer.
    fn capture_png(&mut self) -> Vec<u8> {
        Vec::new()
    }
    /// Trigger a native print dialog or spooling operation.
    fn print(&mut self) {}

    fn set_scene_preset(&mut self, _preset: u32) {}

    // ── Cyberpunk Effects ────────────────────────────────────────────────
    /// Apply a Bifrost (Frosted Glass) effect to the specified rect.
    fn bifrost(&mut self, _rect: Rect, _blur: f32, _saturation: f32, _opacity: f32) {}
    /// Apply a Gungnir (Neon Glow) effect to the specified rect.
    fn gungnir(&mut self, _rect: Rect, _color: [f32; 4], _radius: f32, _intensity: f32) {}
    /// Soft glow variant -- half the intensity of gungnir(). Use for hover highlights.
    fn gungnir_soft(&mut self, _rect: Rect, _color: [f32; 4], _radius: f32, _intensity: f32) {}
    /// Set the default background color for the canvas (RGBA).
    /// Used when the app does not draw its own background.
    fn set_default_background_color(&mut self, _color: [f32; 4]) {}
    /// Apply a ManiGlow (Lunar Illuminator) effect.
    fn mani_glow(&mut self, _rect: Rect, _color: [f32; 4], _radius: f32) {}
    /// Push a Mjolnir Slice (geometric clipping).
    fn push_mjolnir_slice(&mut self, _angle: f32, _offset: f32) {}
    fn pop_mjolnir_slice(&mut self) {}
    /// Execute a render function with memoization.
    /// If the renderer supports caching and the `id` + `data_hash` match a previous run,
    /// it may replay cached commands instead of executing the function.
    fn memoize(&mut self, id: u64, data_hash: u64, render_fn: &dyn Fn(&mut dyn Renderer));
    /// Capture current renderer stack depths for later panic recovery.
    /// The default implementation returns `RenderStateSnapshot::default()`,
    /// which is safe but does nothing useful -- backends with stack state
    /// must override this to record their actual depths.
    fn snapshot_render_state(&self) -> RenderStateSnapshot {
        RenderStateSnapshot::default()
    }
    /// Restore renderer stack state by popping items pushed beyond the
    /// snapshot point. Used by `ErrorBoundary` to recover from mid-render
    /// panics so sibling views don't inherit leaked clip/opacity/transform
    /// state. Idempotent: a no-op if stacks are already at or below the
    /// snapshot depths. Default implementation is a no-op for backends
    /// that have no stack state.
    fn restore_render_state(&mut self, _snap: RenderStateSnapshot) {}
    /// Apply a Mjolnir Shatter effect (fragmentation) to the specified rect.
    fn mjolnir_shatter(&mut self, _rect: Rect, _pieces: u32, _force: f32, _color: [f32; 4]) {}
    fn mjolnir_fluid_shatter(&mut self, _rect: Rect, _pieces: u32, _force: f32, _color: [f32; 4]) {}
    fn draw_mjolnir_bolt(&mut self, _from: [f32; 2], _to: [f32; 2], _color: [f32; 4]) {}

    // ── Futuristic UI Compute & Volumetric ───────────────────────────────
    /// Dispatches a burst of GPU particles (e.g. fireworks, data streams).
    fn dispatch_particles(
        &mut self,
        _origin: [f32; 2],
        _count: u32,
        _effect_type: &str,
        _color: [f32; 4],
    ) {
    }

    /// Draws a volumetric hologram into the specified bounding rectangle.
    fn draw_hologram(&mut self, _rect: Rect, _hologram_id: &str, _time: f32) {}

    // ── Accessibility (ShieldWall) ───────────────────────────────────────
    fn set_aria_role(&mut self, _role: &str) {}
    fn set_aria_label(&mut self, _label: &str) {}
    fn set_aria_valuemin(&mut self, _min: f32) {}
    fn set_aria_valuemax(&mut self, _max: f32) {}
    fn set_aria_valuenow(&mut self, _now: f32) {}

    /// Push a focus trap onto the stack. While active, keyboard focus is
    /// trapped within the specified element and its children.
    /// Returns a trap ID that must be passed to `pop_focus_trap`.
    fn push_focus_trap(&mut self, _element_id: &str) -> u64 { 0 }

    /// Pop the most recently pushed focus trap.
    fn pop_focus_trap(&mut self, _trap_id: u64) {}

    /// Register a shared element for Bifrost Bridge transitions.
    fn register_shared_element(&mut self, _id: &str, _rect: Rect) {}

    /// Set a unique key for the current VDOM node to ensure stable identity during diffing.
    fn set_key(&mut self, _key: &str) {}

    // ── Telemetry ────────────────────────────────────────────────────────
    /// Get real-time performance telemetry.
    fn get_telemetry(&self) -> TelemetryData {
        TelemetryData::default()
    }

    // ── GPU State Management ─────────────────────────────────────────────
    /// Push a shadow state to the stack. All following draw calls will have this shadow.
    fn push_shadow(&mut self, _radius: f32, _color: [f32; 4], _offset: [f32; 2]) {}
    /// Pop the last shadow state from the stack.
    fn pop_shadow(&mut self) {}

    // ── VDOM & Scene Graph ───────────────────────────────────────────────
    /// Push a Virtual DOM node onto the stack for hierarchy tracking.
    fn push_vnode(&mut self, _rect: Rect, _name: &'static str) {}
    /// Pop the current Virtual DOM node from the stack.
    fn pop_vnode(&mut self) {}
    /// Register an event handler for the current VDOM node.
    fn register_handler(
        &mut self,
        _event_type: &str,
        _handler: std::sync::Arc<dyn Fn(Event) + Send + Sync>,
    ) {
    }

    // ── Z-Index & Depth ──────────────────────────────────────────────────
    /// Set the current Z-index for depth sorting.
    /// Higher values appear closer to the viewer.
    fn set_z_index(&mut self, _z: f32) {}
    /// Get the current Z-index.
    fn get_z_index(&self) -> f32 {
        0.0
    }

    // ── Vector Graphics ──────────────────────────────────────────────────
    /// Load an SVG model from raw bytes.
    fn load_svg(&mut self, _name: &str, _svg_data: &[u8]) {}
    /// Draw a pre-loaded SVG model.
    fn draw_svg(&mut self, _name: &str, _rect: Rect) {}
    /// Draw a pre-loaded SVG model with a per-instance animation time offset.
    /// The offset shifts the animation phase, allowing multiple draws of the same
    /// SVG to animate independently. Default delegates to draw_svg (no offset).
    fn draw_svg_with_offset(&mut self, name: &str, rect: Rect, _animation_time_offset: f32) {
        Renderer::draw_svg(self, name, rect);
    }
    /// Draw a pre-loaded SVG model with explicit draw_order for z-sorting.
    /// draw_order=200 renders above UI chrome (draw_order=0).
    fn draw_svg_with_order(&mut self, name: &str, rect: Rect, _draw_order: i32) {
        Renderer::draw_svg(self, name, rect);
    }
    /// Serialize a pre-loaded SVG model back to SVG XML markup.
    /// Returns the serialized SVG string, or an error if the model is not loaded
    /// or serialization is not supported by this renderer.
    fn serialize_svg(&mut self, _name: &str) -> Result<String, String> {
        Err("SVG serialization not supported by this renderer".into())
    }
    /// Apply an SVG filter to a pre-loaded SVG model by filter element ID.
    /// The filter is evaluated and the result composited back into the SVG.
    /// Returns the filtered SVG as XML, or an error if not supported.
    fn apply_svg_filter(
        &mut self,
        _name: &str,
        _filter_id: &str,
        _region: Rect,
    ) -> Result<String, String> {
        Err("SVG filter not supported by this renderer".into())
    }

    // ── GPU Transformations ──────────────────────────────────────────────
    /// Push a 2D transform (translation, scale, rotation) onto the stack.
    /// This transform should be applied to all subsequent draw calls until popped.
    /// Transform-only animations use this to avoid re-triggering the layout engine.
    fn push_transform(&mut self, _translation: [f32; 2], _scale: [f32; 2], _rotation: f32) {}
    /// Push a raw 2D affine transform matrix [a, b, c, d, e, f] corresponding to
    /// [m11, m12, m21, m22, tx, ty].
    fn push_affine(&mut self, _transform: [f32; 6]) {}
    /// Pop the last 2D transform from the stack.
    fn pop_transform(&mut self) {}
    /// Return the resolved layout bounds for a specific node ID if it exists.
    fn query_layout(&self, _node_id: scene_graph::NodeId) -> Option<Rect> {
        None
    }
    /// Enable or disable the layout debug overlay (bounds, padding, margin).
    fn set_debug_layout(&mut self, _enabled: bool) {}
    /// Check if the layout debug overlay is currently enabled.
    fn get_debug_layout(&self) -> bool {
        false
    }

    // ── Material Routing ─────────────────────────────────────────────────
    /// Set the active material for subsequent draw calls.
    /// Controls which pass a draw call is routed to in the multi-pass pipeline.
    fn set_material(&mut self, _material: crate::material::DrawMaterial) {}
    /// Return the currently active material (defaults to Opaque).
    fn current_material(&self) -> crate::material::DrawMaterial {
        crate::material::DrawMaterial::Opaque
    }

    // ── Vili Interaction Paradigm ──────────────────────────────────────────
    /// Compute the user's velocity/intent vector.
    fn mimir_intent(&self) -> [f32; 2] {
        [0.0, 0.0]
    }
    /// Calculate magnetic coordinate warp towards an anchor.
    fn magnetic_warp(&self, pointer: [f32; 2], anchor_rect: Rect, strength: f32) -> [f32; 2] {
        if strength <= 0.0 {
            return pointer;
        }
        let cx = anchor_rect.x + anchor_rect.width / 2.0;
        let cy = anchor_rect.y + anchor_rect.height / 2.0;
        let dx = pointer[0] - cx;
        let dy = pointer[1] - cy;
        let dist = (dx * dx + dy * dy).sqrt();
        let radius = 120.0;
        if dist < radius && dist > 0.0 {
            let force = (1.0 - dist / radius) * strength;
            [pointer[0] - dx * force, pointer[1] - dy * force]
        } else {
            pointer
        }
    }
    /// Calculate kinematic glow intensity based on proximity.
    fn mani_glow_intensity(&self, pointer: [f32; 2], bounds: Rect, radius: f32) -> f32 {
        let cx = bounds.x + bounds.width / 2.0;
        let cy = bounds.y + bounds.height / 2.0;
        let dist = ((pointer[0] - cx).powi(2) + (pointer[1] - cy).powi(2)).sqrt();
        if dist < radius {
            (1.0 - dist / radius).clamp(0.0, 1.0)
        } else {
            0.0
        }
    }
    /// Calculate dynamic element attention (scaling/morphing) statelessly per frame.
    fn fafnir_evolve(&self, pointer: [f32; 2], bounds: Rect, max_scale: f32) -> f32 {
        let prox = self.mani_glow_intensity(pointer, bounds, 120.0);
        1.0 + (max_scale - 1.0) * prox
    }
    /// Sets the precise Vili SDF Shape boundary for hit-testing.
    fn set_sdf_shape(&mut self, _shape: crate::layout::SdfShape) {}

    // -- Portal / PhaseGate rendering -----------------------------------------

    /// Begin rendering into the portal root layer instead of the inline tree.
    /// All draw calls between `enter_portal` and `exit_portal` are collected
    /// into a separate buffer that is composited AFTER the main tree.
    ///
    /// WHY separate buffer: The main tree may have clipping, transforms, or
    /// opacity that should NOT affect overlays. The portal layer renders on top
    /// of everything, ignoring the local coordinate system.
    fn enter_portal(&mut self, _z_index: i32) {}

    /// Exit the portal layer and return to inline rendering.
    /// The portal content collected since `enter_portal` is now sealed --
    /// no more draw calls will be appended to it.
    fn exit_portal(&mut self) {}

    /// Get the current viewport size in logical pixels.
    /// Used by portal content to size itself to the full screen.
    fn viewport_size(&self) -> Rect {
        Rect::new(0.0, 0.0, 1920.0, 1080.0)
    }

    // -- Accessibility announcements -----------------------------------------

    /// Announce a message to screen readers via the platform accessibility API.
    /// This call is non-blocking. The message is queued and the screen reader
    /// will speak it at its own pace.
    fn announce(&mut self, _message: &str, _priority: AnnouncementPriority) {}
}

/// Utility for accessibility compliance (WCAG 2.1).
pub mod accessibility {
    /// Calculate the relative luminance of an sRGB color.
    pub fn relative_luminance(color: [f32; 4]) -> f32 {
        let f = |c: f32| {
            if c <= 0.03928 {
                c / 12.92
            } else {
                ((c + 0.055) / 1.055).powf(2.4)
            }
        };
        0.2126 * f(color[0]) + 0.7152 * f(color[1]) + 0.0722 * f(color[2])
    }

    /// Calculate the contrast ratio between two colors.
    pub fn contrast_ratio(c1: [f32; 4], c2: [f32; 4]) -> f32 {
        let l1 = relative_luminance(c1);
        let l2 = relative_luminance(c2);
        let (light, dark) = if l1 > l2 { (l1, l2) } else { (l2, l1) };
        (light + 0.05) / (dark + 0.05)
    }
}
/// Defines the hardware acceleration tier and feature set available to the renderer.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
)]
pub enum RenderTier {
    /// High-performance GPU path (WebGPU / Vulkan / Metal / DX12) with full shader support.
    Tier1GPU = 0,
    /// Mid-tier GPU path (WebGL2 / OpenGL 3.3) with standard shader support.
    Tier2GPU = 1,
    /// Fallback software or basic hardware path (Canvas 2D / GDI+) with limited effects.
    Tier3Fallback = 2,
}
// =============================================================================
// BERSERKER UNIFORMS
// =============================================================================
use bytemuck::{Pod, Zeroable};
/// Fully themeable color palette for the Berserker pipeline.
#[repr(C)]
#[derive(Copy, Clone, Debug, Pod, Zeroable, serde::Serialize, serde::Deserialize)]
pub struct ColorTheme {
    pub primary_neon: [f32; 4], // (R, G, B, intensity)
    pub shatter_neon: [f32; 4],
    pub glass_base: [f32; 4],
    pub glass_edge: [f32; 4],
    pub rune_glow: [f32; 4],
    pub ember_core: [f32; 4],
    pub background_deep: [f32; 4],
    pub mani_glow: [f32; 4], // (R, G, B, radius)
    pub glass_blur_strength: f32,
    pub shatter_edge_width: f32,
    pub neon_bloom_radius: f32,
    pub rune_opacity: f32,
    /// Weight of adaptive tint from backdrop [0.0, 1.0].
    /// 0.0 = static theme tint, 1.0 = fully adaptive.
    pub glass_tint_adapt: f32,
    /// Per-frame glass IOR override. 0.0 = use shader default (1.45).
    pub glass_ior: f32,
    /// Color space for framebuffer output. 0 = sRGB (default), 1 = Display P3, 2 = Adobe RGB.
    pub color_space: u32,
    // Padding to match WGSL uniform buffer 16-byte struct alignment (total = 176 bytes).
    pub _pad0: f32,
    pub _pad1: f32,
    pub _pad2: f32,
    pub _pad3: f32,
    pub _pad4: f32,
}
// P2-9: Compile-time layout verification between Rust ColorTheme and WGSL.
// WGSL std140 struct size = 176 bytes (164 raw + 12 alignment padding).
// Rust repr(C) struct must match exactly.
const _: () = assert!(
    std::mem::size_of::<ColorTheme>() == 176,
    "ColorTheme Rust/WGSL layout mismatch: expected 176 bytes"
);
impl ColorTheme {
    /// Asgard Mode: The high-fidelity "Cyberpunk Viking" aesthetic.
    pub fn asgard() -> Self {
        Self {
            primary_neon: [0.0, 1.0, 0.95, 1.2],
            shatter_neon: [1.0, 0.0, 0.75, 1.5],
            glass_base: [0.04, 0.04, 0.06, 0.82],
            glass_edge: [0.0, 0.45, 0.55, 0.6],
            rune_glow: [0.75, 0.98, 1.0, 0.9],
            ember_core: [0.95, 0.12, 0.12, 1.0],
            background_deep: [0.01, 0.01, 0.03, 1.0],
            mani_glow: [0.7, 0.9, 1.0, 0.05],
            glass_blur_strength: 0.6,
            shatter_edge_width: 1.8,
            neon_bloom_radius: 0.022,
            rune_opacity: 0.55,
            glass_tint_adapt: 0.35,
            glass_ior: 1.45,
            color_space: 0,
            _pad0: 0.0,
            _pad1: 0.0,
            _pad2: 0.0,
            _pad3: 0.0,
            _pad4: 0.0,
        }
    }

    /// Midgard Mode: A clean, functional tactical HUD for standard operations.
    pub fn midgard() -> Self {
        Self {
            primary_neon: [0.2, 0.4, 0.6, 1.0], // Muted blue
            shatter_neon: [0.5, 0.5, 0.5, 1.0], // Neutral gray
            glass_base: [0.1, 0.12, 0.15, 1.0], // Solid slate
            glass_edge: [0.3, 0.35, 0.4, 1.0],  // Subtle border
            rune_glow: [0.8, 0.8, 0.8, 0.0],    // Runes disabled
            ember_core: [0.5, 0.5, 0.5, 1.0],
            background_deep: [0.05, 0.05, 0.07, 1.0],
            mani_glow: [0.0, 0.0, 0.0, 0.0], // No cursor glow
            glass_blur_strength: 0.0,        // No blur
            shatter_edge_width: 1.0,
            neon_bloom_radius: 0.0,
            rune_opacity: 0.0,
            glass_tint_adapt: 0.0,
            glass_ior: 1.0,
            color_space: 0,
            _pad0: 0.0,
            _pad1: 0.0,
            _pad2: 0.0,
            _pad3: 0.0,
            _pad4: 0.0,
        }
    }

    pub fn cyberpunk_viking() -> Self {
        Self::asgard()
    }
    pub fn vibrant_glass() -> Self {
        Self {
            primary_neon: [0.0, 1.0, 0.95, 1.2],
            shatter_neon: [1.0, 0.0, 0.75, 1.5],
            glass_base: [0.55, 0.6, 0.7, 0.08], // Luminous cool tint
            glass_edge: [0.7, 0.85, 1.0, 0.45], // Subtle blue-white rim
            rune_glow: [0.75, 0.98, 1.0, 0.9],
            ember_core: [1.0, 0.4, 0.1, 1.0],
            background_deep: [0.05, 0.05, 0.1, 1.0],
            mani_glow: [0.7, 0.9, 1.0, 0.05],
            glass_blur_strength: 0.9,
            shatter_edge_width: 1.8,
            neon_bloom_radius: 0.022,
            rune_opacity: 0.55,
            glass_tint_adapt: 0.65,
            glass_ior: 1.45,
            color_space: 0,
            _pad0: 0.0,
            _pad1: 0.0,
            _pad2: 0.0,
            _pad3: 0.0,
            _pad4: 0.0,
        }
    }

    /// Berserker Mode: Blood-iron neon, aggressive contrast, forge-heated glass.
    pub fn berserker() -> Self {
        Self {
            primary_neon: [1.0, 0.08, 0.12, 1.8],
            shatter_neon: [0.95, 0.92, 0.88, 1.6],
            glass_base: [0.03, 0.02, 0.02, 0.88],
            glass_edge: [0.8, 0.35, 0.08, 0.7],
            rune_glow: [0.9, 0.72, 0.3, 1.0],
            ember_core: [0.98, 0.25, 0.05, 1.0],
            background_deep: [0.01, 0.005, 0.005, 1.0],
            mani_glow: [0.8, 0.2, 0.05, 0.08],
            glass_blur_strength: 0.85,
            shatter_edge_width: 2.8,
            neon_bloom_radius: 0.035,
            rune_opacity: 0.85,
            glass_tint_adapt: 0.15,
            glass_ior: 1.85,
            color_space: 0,
            _pad0: 0.0,
            _pad1: 0.0,
            _pad2: 0.0,
            _pad3: 0.0,
            _pad4: 0.0,
        }
    }
}
impl Default for ColorTheme {
    fn default() -> Self {
        Self::vibrant_glass()
    }
}
/// Per-frame scene state for the Berserker pipeline.
#[repr(C)]
#[derive(Copy, Clone, Debug, Pod, Zeroable, serde::Serialize, serde::Deserialize)]
pub struct SceneUniforms {
    pub view: glam::Mat4,
    pub proj: glam::Mat4,
    pub time: f32,
    pub delta_time: f32,
    pub resolution: [f32; 2],
    pub mouse: [f32; 2],
    pub mouse_velocity: [f32; 2],
    pub shatter_origin: [f32; 2],
    pub shatter_time: f32,
    pub shatter_force: f32,
    pub berzerker_rage: f32,
    pub berzerker_mode: u32,
    pub scroll_offset: f32,
    pub scale_factor: f32,
    pub scene_type: u32,
    pub _pad_vec2_align: [u32; 1], // 4-byte pad: WGSL vec2<f32> requires 8-byte alignment
    pub fireball_pos: [f32; 2],
    pub _pad: [f32; 4], // Align to 224 bytes (struct align 16 from Mat4)
}

pub const SCENE_AURORA: u32 = 0;
pub const SCENE_VOID: u32 = 1;
pub const SCENE_NEBULA: u32 = 2;
pub const SCENE_GLITCH: u32 = 3;
pub const SCENE_YGGDRASIL: u32 = 4;

/// Resolve a scene name string to a scene preset constant.
/// Case-insensitive. Supports: "aurora", "void", "nebula", "glitch", "yggdrasil".
/// Also supports common aliases: "empty", "none" → VOID.
/// Returns None if the name is not recognized.
pub fn resolve_scene_by_name(name: &str) -> Option<u32> {
    let normalized = name.to_lowercase().replace(['-', '_', ' ', '.'], "");
    match normalized.as_str() {
        "aurora" => Some(SCENE_AURORA),
        "void" | "empty" | "none" | "blank" => Some(SCENE_VOID),
        "nebula" => Some(SCENE_NEBULA),
        "glitch" => Some(SCENE_GLITCH),
        "yggdrasil" | "worldtree" | "tree" => Some(SCENE_YGGDRASIL),
        _ => None,
    }
}

impl SceneUniforms {
    pub fn new(width: f32, height: f32) -> Self {
        Self {
            view: glam::Mat4::IDENTITY,
            proj: glam::Mat4::orthographic_lh(0.0, width, height, 0.0, -100.0, 100.0),
            time: 0.0,
            delta_time: 0.016,
            resolution: [width, height],
            mouse: [0.5, 0.5],
            mouse_velocity: [0.0, 0.0],
            shatter_origin: [0.5, 0.5],
            shatter_time: -100.0,
            shatter_force: 0.0,
            berzerker_rage: 0.0,
            berzerker_mode: 0,
            scroll_offset: 0.0,
            scale_factor: 1.0,
            scene_type: SCENE_AURORA,
            _pad_vec2_align: [0],
            fireball_pos: [0.0, 0.0],
            _pad: [0.0; 4],
        }
    }
}
/// A 3D mesh containing vertex and index data.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct Mesh {
    pub vertices: Vec<[f32; 3]>,
    pub normals: Vec<[f32; 3]>,
    pub indices: Vec<u32>,
}
impl Mesh {
    pub fn from_obj(data: &[u8]) -> anyhow::Result<Vec<Self>> {
        let mut cursor = std::io::Cursor::new(data);
        let (models, _) = tobj::load_obj_buf(&mut cursor, &tobj::LoadOptions::default(), |_| {
            Ok((Vec::new(), Default::default()))
        })?;
        let mut meshes = Vec::new();
        for m in models {
            let mesh = m.mesh;
            let vertices: Vec<[f32; 3]> = mesh
                .positions
                .chunks_exact(3)
                .map(|c| [c[0], c[1], c[2]])
                .collect();
            let normals = if mesh.normals.is_empty() {
                vec![[0.0, 0.0, 1.0]; vertices.len()]
            } else {
                mesh.normals.chunks(3).map(|c| [c[0], c[1], c[2]]).collect()
            };
            meshes.push(Mesh {
                vertices,
                normals,
                indices: mesh.indices,
            });
        }
        Ok(meshes)
    }
    pub fn from_stl(data: &[u8]) -> anyhow::Result<Self> {
        let mut cursor = std::io::Cursor::new(data);
        let stl = stl_io::read_stl(&mut cursor)?;
        let vertices: Vec<[f32; 3]> = stl.vertices.iter().map(|v| [v[0], v[1], v[2]]).collect();
        let mut indices = Vec::new();
        for face in stl.faces {
            indices.push(face.vertices[0] as u32);
            indices.push(face.vertices[1] as u32);
            indices.push(face.vertices[2] as u32);
        }
        let normals = vec![[0.0, 0.0, 1.0]; vertices.len()];
        Ok(Mesh {
            vertices,
            normals,
            indices,
        })
    }
}

// ══════════════════════════════════════════════════════════════════════════
// 3D TYPES -- Phase 1: Camera, Transform, and 2.5D layer support
// ══════════════════════════════════════════════════════════════════════════

/// A 3D transform: position, rotation (quaternion), and scale.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Transform3D {
    pub position: glam::Vec3,
    pub rotation: glam::Quat,
    pub scale: glam::Vec3,
}

impl Default for Transform3D {
    fn default() -> Self {
        Self {
            position: glam::Vec3::ZERO,
            rotation: glam::Quat::IDENTITY,
            scale: glam::Vec3::ONE,
        }
    }
}

impl Transform3D {
    /// Convert this transform to a 4x4 model matrix.
    pub fn to_matrix(&self) -> glam::Mat4 {
        glam::Mat4::from_scale_rotation_translation(self.scale, self.rotation, self.position)
    }

    /// Create a 2D-compatible transform (z=0, no rotation on z axis).
    pub fn from_2d(x: f32, y: f32, rotation: f32) -> Self {
        Self {
            position: glam::Vec3::new(x, y, 0.0),
            rotation: glam::Quat::from_rotation_z(rotation),
            scale: glam::Vec3::ONE,
        }
    }
}

/// Camera definition for 3D rendering.
#[derive(Debug, Clone, Copy)]
pub struct Camera3D {
    /// World-space camera position.
    pub position: glam::Vec3,
    /// World-space point the camera looks at.
    pub target: glam::Vec3,
    /// World-space up vector.
    pub up: glam::Vec3,
    /// Field of view in radians (perspective) or half-height (orthographic).
    pub fov_y: f32,
    /// Near clipping plane distance.
    pub near: f32,
    /// Far clipping plane distance.
    pub far: f32,
    /// If true, use perspective projection. If false, use orthographic.
    pub perspective: bool,
    /// Aspect ratio (width / height). Used for perspective projection.
    pub aspect: f32,
}

/// Material properties for 3D rendering.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Material3D {
    /// Base color (RGBA).
    pub base_color: [f32; 4],
    /// Metallic factor (0 = dielectric, 1 = metallic).
    pub metallic: f32,
    /// Roughness factor (0 = mirror, 1 = fully diffuse).
    pub roughness: f32,
    /// Emissive color (RGB) for self-illumination.
    pub emissive: [f32; 3],
    /// Opacity (0 = transparent, 1 = opaque).
    pub opacity: f32,
}

impl Default for Material3D {
    fn default() -> Self {
        Self {
            base_color: [1.0, 1.0, 1.0, 1.0],
            metallic: 0.0,
            roughness: 0.5,
            emissive: [0.0, 0.0, 0.0],
            opacity: 1.0,
        }
    }
}

impl Material3D {
    /// Create a simple unlit material with just a color.
    pub fn unlit(color: [f32; 4]) -> Self {
        Self {
            base_color: color,
            metallic: 0.0,
            roughness: 1.0,
            emissive: [0.0, 0.0, 0.0],
            opacity: color[3],
        }
    }

    /// Create a metallic material.
    pub fn metallic(color: [f32; 4], roughness: f32) -> Self {
        Self {
            base_color: color,
            metallic: 1.0,
            roughness: roughness.clamp(0.0, 1.0),
            emissive: [0.0, 0.0, 0.0],
            opacity: color[3],
        }
    }
}

impl Default for Camera3D {
    fn default() -> Self {
        Self {
            position: glam::Vec3::new(0.0, 0.0, 10.0),
            target: glam::Vec3::ZERO,
            up: glam::Vec3::Y,
            fov_y: 45.0f32.to_radians(),
            near: 0.1,
            far: 1000.0,
            perspective: true,
            aspect: 16.0 / 9.0,
        }
    }
}

impl Camera3D {
    /// Compute the view matrix (world → camera space).
    pub fn view_matrix(&self) -> glam::Mat4 {
        glam::Mat4::look_at_lh(self.position, self.target, self.up)
    }

    /// Compute the projection matrix.
    pub fn projection_matrix(&self) -> glam::Mat4 {
        if self.perspective {
            glam::Mat4::perspective_lh(self.fov_y, self.aspect, self.near, self.far)
        } else {
            // Orthographic with fov_y as half-height
            let top = self.fov_y;
            let right = top * self.aspect;
            glam::Mat4::orthographic_lh(-right, right, -top, top, self.near, self.far)
        }
    }

    /// Compute the combined view-projection matrix.
    pub fn view_projection(&self) -> glam::Mat4 {
        self.projection_matrix() * self.view_matrix()
    }
}

/// FrameRenderer extends Renderer with frame lifecycle management.
/// It is typically implemented by the host windowing/rendering environment.
pub trait FrameRenderer<E = ()>: Renderer {
    fn begin_frame(&mut self) -> E;
    fn render_frame(&mut self) {
        // Default implementation does nothing - override for custom frame rendering
    }
    fn end_frame(&mut self, encoder: E);
}
use std::sync::Arc;
type SubscriberList<T> = Arc<std::sync::Mutex<Vec<Box<dyn Fn(&T) + Send + Sync>>>>;

/// P1-15 fix: invoke all subscribers in a list, isolating panics so that a
/// single faulty callback does not poison the Mutex and break all future
/// state updates forever. Returns the number of subscribers invoked
/// successfully. Each callback is wrapped in `catch_unwind`; panics are
/// logged but do not propagate.
fn invoke_subscribers_safely<T>(subs: &SubscriberList<T>, val: &T) -> usize
where
    // No UnwindSafe bound on T: subscriber callbacks receive &T and the
    // user is responsible for the panic-safety contract. We use
    // AssertUnwindSafe internally to opt out of the check.
{
    // Acquire the lock with poison recovery: if a previous panic poisoned
    // the mutex, recover and continue (the previous subscriber may have
    // left the list in an inconsistent state, but the best we can do is
    // log and try again). On recovery, the existing subscriber list is
    // preserved so we do not silently drop user subscriptions.
    let guard = match subs.lock() {
        Ok(g) => g,
        Err(poisoned) => {
            log::warn!(
                "[State] subscriber list mutex was poisoned; recovering"
            );
            poisoned.into_inner()
        }
    };
    let mut invoked = 0usize;
    for cb in guard.iter() {
        // Wrap each callback in catch_unwind so a panicking subscriber
        // does not poison the mutex and break subsequent state updates.
        // The catch_unwind returns Err if the closure panicked.
        let cb_ref: &(dyn Fn(&T) + Send + Sync) = &**cb;
        // Use AssertUnwindSafe because subscriber callbacks are Fn (not
        // UnwindSafe by default due to &T parameter), but the actual
        // panic-safety contract is the subscriber author's responsibility.
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            cb_ref(val);
        }));
        if let Err(payload) = result {
            let msg = if let Some(s) = payload.downcast_ref::<&'static str>() {
                (*s).to_string()
            } else if let Some(s) = payload.downcast_ref::<String>() {
                s.clone()
            } else {
                "unknown panic payload".to_string()
            };
            log::error!("[State] subscriber callback panicked: {msg}");
            // Do NOT re-raise; continue invoking remaining subscribers.
        } else {
            invoked += 1;
        }
    }
    invoked
}
/// State wrapper that owns a value and notifies subscribers when changed.
///
/// P1-14: this struct carries 4 storage mechanisms:
/// 1. `arc_swap::ArcSwap<T>` for lock-free reads (the hot path)
/// 2. `arc_swap::ArcSwap<Option<MutationMetadata>>` for metadata reads
/// 3. `stm::TVar<T>` for atomic compound transactions (only on non-WASM)
/// 4. `stm::TVar<Option<MutationMetadata>>` for transactional metadata
///
/// The audit flagged this as 4 atomic/sync primitives per State<T>
/// instance, which is heavy for small states. The 4 mechanisms
/// are kept because they serve different purposes: arc_swap is
/// for the read-heavy hot path, TVar is for atomic compound
/// transactions. A future refactor could consolidate to a single
/// storage backend (e.g., always use TVar) but that would have a
/// performance cost on reads.
///
/// The `set()` method provides a way to bypass TVar for simple
/// single-value updates, avoiding the storage cost when compound
/// transactions aren't needed.
#[derive(Clone)]
pub struct State<T: Clone + Send + Sync + 'static> {
    swap: Arc<arc_swap::ArcSwap<T>>,
    metadata_swap: Arc<arc_swap::ArcSwap<Option<agents::MutationMetadata>>>,
    #[cfg(not(target_arch = "wasm32"))]
    tvar: Arc<stm::TVar<T>>,
    #[cfg(not(target_arch = "wasm32"))]
    metadata_tvar: Arc<stm::TVar<Option<agents::MutationMetadata>>>,
    subscribers: SubscriberList<T>,
    version: Arc<std::sync::atomic::AtomicU64>,
    resolution: agents::ConflictResolution,
}
impl<T: Clone + Send + Sync + 'static> State<T> {
    /// Create a new State with initial value
    pub fn new(value: T) -> Self {
        #[cfg(not(target_arch = "wasm32"))]
        let tvar = Arc::new(stm::TVar::new(value.clone()));
        #[cfg(not(target_arch = "wasm32"))]
        let metadata_tvar = Arc::new(stm::TVar::new(None));
        Self {
            swap: Arc::new(arc_swap::ArcSwap::from_pointee(value)),
            metadata_swap: Arc::new(arc_swap::ArcSwap::new(Arc::new(None))),
            #[cfg(not(target_arch = "wasm32"))]
            tvar,
            #[cfg(not(target_arch = "wasm32"))]
            metadata_tvar,
            subscribers: Arc::new(std::sync::Mutex::new(Vec::new())),
            version: Arc::new(std::sync::atomic::AtomicU64::new(0)),
            resolution: agents::ConflictResolution::default(),
        }
    }
    /// Set the conflict resolution strategy for this state.
    pub fn with_resolution(mut self, resolution: agents::ConflictResolution) -> Self {
        self.resolution = resolution;
        self
    }
    /// Get the current value
    pub fn get(&self) -> T {
        (**self.swap.load()).clone()
    }
    /// Set a new value, notifying all subscribers. Applies conflict resolution if agents are present.
    pub fn set(&self, value: T) {
        #[cfg(not(target_arch = "wasm32"))]
        let (was_skipped, final_val, final_meta) = stm::atomically(|tx| {
            let new_meta = agents::get_current_mutation_metadata();
            let existing_meta = self.metadata_tvar.read(tx)?;
            let mut skip = false;
            if self.resolution == agents::ConflictResolution::PriorityWins
                && let (Some(new_m), Some(old_m)) = (new_meta, existing_meta)
                && new_m.priority < old_m.priority
            {
                skip = true;
            }
            if !skip {
                self.tvar.write(tx, value.clone())?;
                self.metadata_tvar.write(tx, new_meta)?;
                Ok((false, value.clone(), new_meta))
            } else {
                Ok((true, self.tvar.read(tx)?, existing_meta))
            }
        });
        #[cfg(target_arch = "wasm32")]
        let (was_skipped, final_val, final_meta) =
            (false, value, agents::get_current_mutation_metadata());
        if was_skipped {
            if let (Some(new_m), Some(old_m)) =
                (agents::get_current_mutation_metadata(), final_meta)
            {
                agents::notify_conflict(agents::ConflictEvent {
                    agent_id: new_m.agent_id,
                    priority: new_m.priority,
                    existing_agent_id: old_m.agent_id,
                    existing_priority: old_m.priority,
                    timestamp_ms: new_m.timestamp_ms,
                });
            }
            return;
        }
        self.swap.store(Arc::new(final_val.clone()));
        self.metadata_swap.store(Arc::new(final_meta));
        self.version
            .fetch_add(1, std::sync::atomic::Ordering::Release);
        let subs = Arc::clone(&self.subscribers);
        if crate::is_batching() {
            crate::enqueue_batch_task(Box::new(move || {
                let _ = invoke_subscribers_safely(&subs, &final_val);
            }));
        } else {
            let _ = invoke_subscribers_safely(&subs, &final_val);
        }
    }

    /// P1-14: direct set that bypasses TVar for callers who don't
    /// need atomic compound transactions. Avoids the redundant
    /// storage cost when only the value and metadata are updated
    /// (not coordinated with other State<T> instances).
    ///
    /// Use this instead of `set()` when:
    ///  - You don't use conflict resolution (e.g., simple
    ///    single-threaded UI state).
    ///  - You don't need to coordinate with other State<T>
    ///    instances in a single transaction.
    ///
    /// Both the swap and TVar are updated atomically so that
    /// subsequent reads via either path see a consistent value.
    pub fn set_direct(&self, value: T) {
        self.swap.store(Arc::new(value.clone()));
        let new_meta = agents::get_current_mutation_metadata();
        self.metadata_swap.store(Arc::new(new_meta));
        self.version
            .fetch_add(1, std::sync::atomic::Ordering::Release);
        #[cfg(not(target_arch = "wasm32"))]
        {
            let _ = stm::atomically(|tx| {
                self.tvar.write(tx, value.clone())?;
                let meta = agents::get_current_mutation_metadata();
                self.metadata_tvar.write(tx, meta)?;
                Ok(())
            });
        }
        let subs = Arc::clone(&self.subscribers);
        if crate::is_batching() {
            crate::enqueue_batch_task(Box::new(move || {
                let _ = invoke_subscribers_safely(&subs, &value);
            }));
        } else {
            let _ = invoke_subscribers_safely(&subs, &value);
        }
    }
    pub fn mutate<F: Fn(&T) -> T>(&self, f: F) {
        #[cfg(not(target_arch = "wasm32"))]
        {
            let (was_skipped, final_val, final_meta) = stm::atomically(|tx| {
                let new_meta = agents::get_current_mutation_metadata();
                let existing_meta = self.metadata_tvar.read(tx)?;
                let mut skip = false;
                if self.resolution == agents::ConflictResolution::PriorityWins
                    && let (Some(new_m), Some(old_m)) = (new_meta, existing_meta)
                    && new_m.priority < old_m.priority
                {
                    skip = true;
                }
                if !skip {
                    let current = self.tvar.read(tx)?;
                    let next = f(&current);
                    self.tvar.write(tx, next.clone())?;
                    self.metadata_tvar.write(tx, new_meta)?;
                    Ok((false, next, new_meta))
                } else {
                    Ok((true, self.tvar.read(tx)?, existing_meta))
                }
            });
            if was_skipped {
                if let (Some(new_m), Some(old_m)) =
                    (agents::get_current_mutation_metadata(), final_meta)
                {
                    agents::notify_conflict(agents::ConflictEvent {
                        agent_id: new_m.agent_id,
                        priority: new_m.priority,
                        existing_agent_id: old_m.agent_id,
                        existing_priority: old_m.priority,
                        timestamp_ms: new_m.timestamp_ms,
                    });
                }
                return;
            }
            self.swap.store(Arc::new(final_val.clone()));
            self.metadata_swap.store(Arc::new(final_meta));
            self.version
                .fetch_add(1, std::sync::atomic::Ordering::Release);
            let subs = Arc::clone(&self.subscribers);
            if crate::is_batching() {
                crate::enqueue_batch_task(Box::new(move || {
                    let _ = invoke_subscribers_safely(&subs, &final_val);
                }));
            } else {
                let _ = invoke_subscribers_safely(&subs, &final_val);
            }
        }
        #[cfg(target_arch = "wasm32")]
        {
            self.set(f(&self.get()));
        }
    }
    /// Get current version
    pub fn version(&self) -> u64 {
        self.version.load(std::sync::atomic::Ordering::Acquire)
    }
    /// Subscribe to state changes
    pub fn subscribe<F: Fn(&T) + Send + Sync + 'static>(&self, callback: F) {
        self.subscribers.lock().unwrap_or_else(|p| p.into_inner()).push(Box::new(callback));
    }
}
use crate::runtime::NodeStateSnapshot;
use std::sync::OnceLock;
use std::sync::atomic::{AtomicBool, Ordering};

/// P1-17 fix: shared fallback tokio runtime for `Suspense::new_async`.
///
/// When `new_async` is called without an ambient tokio runtime, the
/// previous implementation spawned a new OS thread + tokio runtime
/// for EACH call. For an app with many async data loads (e.g. a data
/// lake visualizer), this could spawn hundreds of OS threads.
///
/// The fix is a process-wide shared multi-threaded runtime, lazily
/// initialized on first use. The runtime uses a bounded worker count
/// (default: `max(1, num_cpus - 1)`) so we never spawn more than
/// `WORKER_THREADS` OS threads, regardless of how many Suspense
/// instances are created.
///
/// When the process exits the runtime is dropped, which joins all
/// worker threads.
#[cfg(not(target_arch = "wasm32"))]
static FALLBACK_RUNTIME: OnceLock<tokio::runtime::Runtime> = OnceLock::new();

/// Number of worker threads for the fallback runtime. Computed lazily
/// from the available CPU count, then cached.
#[cfg(not(target_arch = "wasm32"))]
static FALLBACK_WORKER_COUNT: OnceLock<usize> = OnceLock::new();

#[cfg(not(target_arch = "wasm32"))]
fn fallback_runtime() -> &'static tokio::runtime::Runtime {
    FALLBACK_RUNTIME.get_or_init(|| {
        // Bounded worker count: leave at least one core for the
        // application, but cap at 8 to avoid runaway thread creation
        // on hosts with very high CPU counts.
        let worker_count = *FALLBACK_WORKER_COUNT.get_or_init(|| {
            let available = std::thread::available_parallelism()
                .map(|n| n.get())
                .unwrap_or(2);
            available.saturating_sub(1).clamp(1, 8)
        });
        tokio::runtime::Builder::new_current_thread()
            .worker_threads(worker_count)
            .thread_name("cvkg-fallback-rt")
            .enable_all()
            .build()
            .expect("failed to build fallback tokio runtime")
    })
}
/// Global application state registry.
pub static SYSTEM_STATE: OnceLock<Arc<arc_swap::ArcSwap<AppState>>> = OnceLock::new();
#[cfg(not(target_arch = "wasm32"))]
static KNOWLEDGE_TVAR: OnceLock<stm::TVar<AppState>> = OnceLock::new();
static IS_BATCHING: AtomicBool = AtomicBool::new(false);
pub static IS_RENDERING: AtomicBool = AtomicBool::new(false);
pub static LAYOUT_DIRTY: AtomicBool = AtomicBool::new(false);
type BatchQueue = OnceLock<std::sync::Mutex<Vec<Box<dyn FnOnce() + Send + Sync>>>>;
static BATCH_QUEUE: BatchQueue = OnceLock::new();
/// Global write lock to serialize updates to SYSTEM_STATE and KNOWLEDGE_TVAR,
/// preventing parallel race conditions between STM transactions and the lock-free reader state.
static STATE_WRITE_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());
/// Returns true if state updates are currently being batched.
pub fn is_batching() -> bool {
    IS_BATCHING.load(Ordering::Acquire)
}
/// Returns true if the system is currently in the render phase.
pub fn is_rendering() -> bool {
    IS_RENDERING.load(Ordering::Acquire)
}
/// Signals the start of the render phase. Mutations during this phase trigger warnings.
pub fn begin_render_phase() {
    IS_RENDERING.store(true, Ordering::Release);
}
/// Signals the end of the render phase.
pub fn end_render_phase() {
    IS_RENDERING.store(false, Ordering::Release);
}
/// Enqueues a notification task to be run when the current batch flushes.
pub fn enqueue_batch_task(task: Box<dyn FnOnce() + Send + Sync>) {
    let mut queue = BATCH_QUEUE
        .get_or_init(|| std::sync::Mutex::new(Vec::new()))
        .lock()
        .unwrap_or_else(|p| p.into_inner());
    queue.push(task);
}
/// Executes multiple state updates in a single batch, deferring all subscriber
/// notifications until the closure completes. This prevents layout thrashing
/// and redundant render cycles when modifying multiple independent states.
pub fn batch<F: FnOnce()>(f: F) {
    if IS_BATCHING.swap(true, Ordering::AcqRel) {
        // Already inside a batch, just execute
        f();
        return;
    }
    f();
    IS_BATCHING.store(false, Ordering::Release);
    let mut queue = BATCH_QUEUE
        .get_or_init(|| std::sync::Mutex::new(Vec::new()))
        .lock()
        .unwrap();
    let tasks: Vec<_> = queue.drain(..).collect();
    drop(queue);
    for task in tasks {
        task();
    }
}
/// Get a reference to the global system state.
pub fn get_system_state() -> Arc<arc_swap::ArcSwap<AppState>> {
    SYSTEM_STATE
        .get_or_init(|| Arc::new(arc_swap::ArcSwap::from_pointee(AppState::default())))
        .clone()
}
pub fn load_system_state() -> arc_swap::Guard<Arc<AppState>> {
    get_system_state().load()
}
pub fn update_system_state<F>(f: F)
where
    F: FnOnce(&AppState) -> AppState,
{
    let _lock = STATE_WRITE_MUTEX.lock().unwrap_or_else(|p| p.into_inner());
    if is_rendering() {
        log::warn!(
            "LAYOUT THRASH DETECTED: System state mutated during render phase. This may trigger redundant layout passes and impact performance."
        );
    }
    LAYOUT_DIRTY.store(true, Ordering::SeqCst);
    let swap = get_system_state();
    let current = swap.load();
    let new_state = Arc::new(f(&current));
    swap.store(Arc::clone(&new_state));
    #[cfg(not(target_arch = "wasm32"))]
    {
        let tvar = KNOWLEDGE_TVAR.get_or_init(|| stm::TVar::new((*new_state).clone()));
        stm::atomically(|tx| tvar.write(tx, (*new_state).clone()));
    }
}
pub fn transact_system_state<F>(f: F)
where
    F: Fn(&AppState) -> AppState,
{
    let _lock = STATE_WRITE_MUTEX.lock().unwrap_or_else(|p| p.into_inner());
    #[cfg(not(target_arch = "wasm32"))]
    {
        if is_rendering() {
            log::warn!(
                "LAYOUT THRASH DETECTED: System state mutated during render phase. This may trigger redundant layout passes and impact performance."
            );
        }
        let tvar = KNOWLEDGE_TVAR
            .get_or_init(|| stm::TVar::new((**get_system_state().load()).clone()))
            .clone();
        let new_state = stm::atomically(move |tx| {
            let current = tvar.read(tx)?;
            let next = f(&current);
            tvar.write(tx, next.clone())?;
            Ok(next)
        });
        get_system_state().store(Arc::new(new_state));
    }
    #[cfg(target_arch = "wasm32")]
    {
        if is_rendering() {
            log::warn!(
                "LAYOUT THRASH DETECTED: System state mutated during render phase. This may trigger redundant layout passes and impact performance."
            );
        }
        update_system_state(f);
    }
}
impl AppState {
    /// Create a new empty AppState.
    pub fn new() -> Self {
        Self::default()
    }
    /// Set a component's internal state.
    pub fn set_component_state<T: 'static + Send + Sync>(&mut self, id: u64, state: T) {
        self.component_states
            .insert(id, Arc::new(std::sync::RwLock::new(state)));
    }
    /// Get a reference to a component's internal state.
    pub fn get_component_state<T: 'static + Send + Sync>(
        &self,
        id: u64,
    ) -> Option<Arc<std::sync::RwLock<T>>> {
        let stored = self.component_states.get(&id)?;
        // X-01 fix: safe downcast via Any:: instead of unsafe transmute.
        // The stored value is Arc<RwLock<dyn Any>>. We obtain a read lock
        // to verify that the inner type is indeed T.
        let any_ref = stored.read().ok()?;
        // downcast_ref checks the vtable at runtime -- no unsafe needed.
        let _verified: &T = any_ref.downcast_ref::<T>()?;
        drop(any_ref);
        // Recover the original Arc. The thin pointer cast is sound because we
        // have verified the concrete type via Any::downcast_ref above.
        let raw = Arc::into_raw(stored.clone());
        Some(unsafe { Arc::from_raw(raw as *const std::sync::RwLock<T>) })
    }
    /// Add a new fragment to memory.
    pub fn remember(&mut self, fragment: KnowledgeFragment) {
        self.fragments.insert(fragment.id.clone(), fragment);
    }
    /// Process a search query against the local knowledge base.
    pub fn process_query(&mut self, query: &str) {
        let query_lower = query.to_lowercase();
        let mut results: Vec<(f32, String)> = self
            .fragments
            .iter()
            .map(|(id, frag)| {
                let mut score = 0.0;
                if frag.summary.to_lowercase().contains(&query_lower) {
                    score += 1.0;
                }
                if frag.source.to_lowercase().contains(&query_lower) {
                    score += 0.5;
                }
                (score, id.clone())
            })
            .filter(|(score, _)| *score > 0.0)
            .collect();
        // Sort by relevance score
        results.sort_by(|a, b| b.0.total_cmp(&a.0));
        self.last_query_results = results.into_iter().map(|(_, id)| id).take(5).collect();
    }
    /// Captures a snapshot of the current state for debugging and hot-reloading.
    pub fn snapshot(&self) -> Vec<NodeStateSnapshot> {
        let mut snapshots = Vec::new();
        // Snapshots of agentic fragments
        for frag in self.fragments.values() {
            if let Ok(val) = serde_json::to_value(frag) {
                snapshots.push(NodeStateSnapshot { id: 0, state: val });
            }
        }
        snapshots
    }
}
/// A read/write projection into a `State<T>` owned elsewhere.
#[derive(Clone)]
pub struct Binding<T: Clone + Send + Sync + 'static> {
    swap: Arc<arc_swap::ArcSwap<T>>,
    #[cfg(not(target_arch = "wasm32"))]
    tvar: Arc<stm::TVar<T>>,
    version: Arc<std::sync::atomic::AtomicU64>,
}
impl<T: Clone + Send + Sync + 'static> Binding<T> {
    /// Create a binding from a State
    pub fn from_state(state: &State<T>) -> Self {
        Self {
            swap: Arc::clone(&state.swap),
            #[cfg(not(target_arch = "wasm32"))]
            tvar: Arc::clone(&state.tvar),
            version: Arc::clone(&state.version),
        }
    }
    /// Get the current value
    pub fn get(&self) -> T {
        (**self.swap.load()).clone()
    }
    /// Set a new value
    pub fn set(&self, value: T) {
        self.swap.store(Arc::new(value.clone()));
        #[cfg(not(target_arch = "wasm32"))]
        {
            let tvar = Arc::clone(&self.tvar);
            let v = value.clone();
            stm::atomically(move |tx| tvar.write(tx, v.clone()));
        }
        self.version
            .fetch_add(1, std::sync::atomic::Ordering::Release);
    }
    /// Get current version
    pub fn version(&self) -> u64 {
        self.version.load(std::sync::atomic::Ordering::Acquire)
    }
}
#[cfg(not(target_arch = "wasm32"))]
pub fn transact_pair<A, B, F>(state_a: &State<A>, state_b: &State<B>, f: F)
where
    A: Clone + Send + Sync + 'static,
    B: Clone + Send + Sync + 'static,
    F: Fn(&A, &B) -> (A, B),
{
    let tvar_a = Arc::clone(&state_a.tvar);
    let tvar_b = Arc::clone(&state_b.tvar);
    let (new_a, new_b) = stm::atomically(move |tx| {
        let a = tvar_a.read(tx)?;
        let b = tvar_b.read(tx)?;
        let (na, nb) = f(&a, &b);
        tvar_a.write(tx, na.clone())?;
        tvar_b.write(tx, nb.clone())?;
        Ok((na, nb))
    });
    state_a.swap.store(Arc::new(new_a.clone()));
    state_b.swap.store(Arc::new(new_b.clone()));
    state_a
        .version
        .fetch_add(1, std::sync::atomic::Ordering::Release);
    state_b
        .version
        .fetch_add(1, std::sync::atomic::Ordering::Release);
    let subs_a = Arc::clone(&state_a.subscribers);
    let subs_b = Arc::clone(&state_b.subscribers);
    if crate::is_batching() {
        crate::enqueue_batch_task(Box::new(move || {
            {
                let s = subs_a.lock().unwrap_or_else(|p| p.into_inner());
                for cb in s.iter() {
                    cb(&new_a);
                }
            }
            {
                let s = subs_b.lock().unwrap_or_else(|p| p.into_inner());
                for cb in s.iter() {
                    cb(&new_b);
                }
            }
        }));
    } else {
        {
            let s = subs_a.lock().unwrap_or_else(|p| p.into_inner());
            for cb in s.iter() {
                cb(&new_a);
            }
        }
        {
            let s = subs_b.lock().unwrap_or_else(|p| p.into_inner());
            for cb in s.iter() {
                cb(&new_b);
            }
        }
    }
}
use std::any::TypeId;
use std::sync::Mutex;
/// Global environment storage using TypeId as keys.
pub(crate) static ENVIRONMENT: OnceLock<
    Mutex<HashMap<TypeId, Box<dyn std::any::Any + Send + Sync>>>,
> = OnceLock::new();
/// Environment key type for accessing ambient values
/// Implement this trait to define a new environment key.
pub trait EnvKey: 'static + Send + Sync {
    /// The type of value stored in the environment
    type Value: Clone + Send + Sync + 'static;
    /// Get a default value for this key
    fn default_value() -> Self::Value;
}
/// Key for accessing the Yggdrasil design token tree
pub struct YggdrasilKey;
impl EnvKey for YggdrasilKey {
    type Value = DesignTokens;
    fn default_value() -> Self::Value {
        default_tokens()
    }
}
// Duplicate AssetKey removed - original definition at line 63
/// System appearance (Light/Dark mode)
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Appearance {
    Light,
    Dark,
}
/// Orientation for layouts
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Orientation {
    Horizontal,
    Vertical,
}
/// Placement configuration for placing a view within a Grid layout.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct GridPlacement {
    /// 0-based column index. Negative values count from the end of columns.
    pub column: i32,
    /// Number of columns the view spans (default is 1).
    pub column_span: u32,
    /// 0-based row index. Negative values count from the end of rows.
    pub row: i32,
    /// Number of rows the view spans (default is 1).
    pub row_span: u32,
}
/// Cross-axis alignment for layout containers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum Alignment {
    #[default]
    Center,
    Leading,
    Trailing,
    Top,
    Bottom,
}
/// Main-axis distribution for linear layout containers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum Distribution {
    #[default]
    Fill,
    Center,
    Leading,
    Trailing,
    SpaceBetween,
    SpaceAround,
    SpaceEvenly,
}
/// A color represented by RGBA components in the [0.0, 1.0] range.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct Color {
    pub r: f32,
    pub g: f32,
    pub b: f32,
    pub a: f32,
}
impl Color {
    pub const BLACK: Color = Color {
        r: 0.0,
        g: 0.0,
        b: 0.0,
        a: 1.0,
    };
    pub const WHITE: Color = Color {
        r: 1.0,
        g: 1.0,
        b: 1.0,
        a: 1.0,
    };
    pub const TRANSPARENT: Color = Color {
        r: 0.0,
        g: 0.0,
        b: 0.0,
        a: 0.0,
    };
    pub const RED: Color = Color {
        r: 1.0,
        g: 0.0,
        b: 0.0,
        a: 1.0,
    };
    pub const GREEN: Color = Color {
        r: 0.0,
        g: 1.0,
        b: 0.0,
        a: 1.0,
    };
    pub const BLUE: Color = Color {
        r: 0.0,
        g: 0.0,
        b: 1.0,
        a: 1.0,
    };
    pub const VIKING_GOLD: Color = Color {
        r: 1.0,
        g: 0.84,
        b: 0.0,
        a: 1.0,
    };
    pub const MAGENTA_LIQUID: Color = Color {
        r: 1.0,
        g: 0.0,
        b: 1.0,
        a: 1.0,
    };
    pub const TACTICAL_OBSIDIAN: Color = Color {
        r: 0.05,
        g: 0.05,
        b: 0.07,
        a: 1.0,
    };
    /// Calculate the relative luminance of the color as defined by WCAG 2.x
    pub fn relative_luminance(&self) -> f32 {
        fn res(c: f32) -> f32 {
            if c <= 0.03928 {
                c / 12.92
            } else {
                ((c + 0.055) / 1.055).powf(2.4)
            }
        }
        0.2126 * res(self.r) + 0.7152 * res(self.g) + 0.0722 * res(self.b)
    }
    /// Calculate the contrast ratio between this color and another color
    pub fn contrast_ratio(&self, other: &Color) -> f32 {
        let l1 = self.relative_luminance();
        let l2 = other.relative_luminance();
        if l1 > l2 {
            (l1 + 0.05) / (l2 + 0.05)
        } else {
            (l2 + 0.05) / (l1 + 0.05)
        }
    }
    pub const CYAN: Color = Color {
        r: 0.0,
        g: 1.0,
        b: 1.0,
        a: 1.0,
    };
    pub const YELLOW: Color = Color {
        r: 1.0,
        g: 1.0,
        b: 0.0,
        a: 1.0,
    };
    pub const MAGENTA: Color = Color {
        r: 1.0,
        g: 0.0,
        b: 1.0,
        a: 1.0,
    };
    pub const GRAY: Color = Color {
        r: 0.5,
        g: 0.5,
        b: 0.5,
        a: 1.0,
    };

    /// Parse a HEX color string (e.g., "#FF6B35" or "FF6B35") into a Color.
    /// Returns None if the string is not a valid 6-digit HEX color.
    pub fn from_hex(hex: &str) -> Option<Self> {
        let hex = hex.strip_prefix('#').unwrap_or(hex);
        if hex.len() != 6 {
            return None;
        }
        let r = u8::from_str_radix(&hex[0..2], 16).ok()? as f32 / 255.0;
        let g = u8::from_str_radix(&hex[2..4], 16).ok()? as f32 / 255.0;
        let b = u8::from_str_radix(&hex[4..6], 16).ok()? as f32 / 255.0;
        Some(Color { r, g, b, a: 1.0 })
    }
    /// Create a new color from RGBA components.
    pub fn new(r: f32, g: f32, b: f32, a: f32) -> Self {
        Self { r, g, b, a }
    }
    /// Convert the color to a [r, g, b, a] array.
    pub fn as_array(&self) -> [f32; 4] {
        [self.r, self.g, self.b, self.a]
    }

    /// Return a new color with lightness increased by `amount`.
    ///
    /// Adds `amount` to each RGB channel and clamps to [0.0, 1.0].
    /// This is a simple sRGB lightness adjustment, not perceptually uniform.
    /// For perceptually uniform adjustments, use OKLCH via cvkg-themes.
    pub fn lighten(&self, amount: f32) -> Self {
        Self {
            r: (self.r + amount).clamp(0.0, 1.0),
            g: (self.g + amount).clamp(0.0, 1.0),
            b: (self.b + amount).clamp(0.0, 1.0),
            a: self.a,
        }
    }

    /// Return a new color with lightness decreased by `amount`.
    pub fn darken(&self, amount: f32) -> Self {
        Self {
            r: (self.r - amount).clamp(0.0, 1.0),
            g: (self.g - amount).clamp(0.0, 1.0),
            b: (self.b - amount).clamp(0.0, 1.0),
            a: self.a,
        }
    }
}
impl View for Color {
    type Body = Never;
    fn body(self) -> Self::Body {
        // SAFETY: `Never` is uninhabitable. Color is a primitive view that fills a
        // rectangle directly in `render()` and never exposes a composable body.
        unreachable!()
    }
    fn render(&self, renderer: &mut dyn Renderer, rect: Rect) {
        renderer.fill_rect(rect, self.as_array());
    }
}
/// Key for accessing the current system appearance
pub struct AppearanceKey;
impl EnvKey for AppearanceKey {
    type Value = Appearance;
    fn default_value() -> Self::Value {
        Appearance::Dark // Default to Dark (Ginnungagap) for Berserker aesthetic
    }
}

/// Key for accessing the current text direction
pub struct DirectionKey;
impl EnvKey for DirectionKey {
    type Value = Direction;
    fn default_value() -> Self::Value {
        Direction::LTR
    }
}

/// StyleResolver provides high-level access to themed values from the environment.
pub struct StyleResolver;
impl StyleResolver {
    /// Resolve a color from the current environment
    pub fn color(key: &str) -> String {
        let tokens = Environment::<YggdrasilKey>::new().get();
        let appearance = Environment::<AppearanceKey>::new().get();
        let is_dark = appearance == Appearance::Dark;
        tokens
            .get_color(key, is_dark)
            .unwrap_or_else(|| "#FF00FF".to_string()) // Default to MuspelMagenta on failure
    }
    /// Resolve a generic token value
    pub fn get<T: FromStr>(category: &str, key: &str) -> Option<T> {
        let tokens = Environment::<YggdrasilKey>::new().get();
        let appearance = Environment::<AppearanceKey>::new().get();
        let is_dark = appearance == Appearance::Dark;
        tokens.get(category, key, is_dark)
    }
    /// Resolve a color from the current environment as a [f32; 4] RGBA array.
    /// Returns the color value for the current appearance (light/dark).
    /// Falls back to magenta (#FF00FF) if the key is not found.
    pub fn color_array(key: &str) -> [f32; 4] {
        let hex = Self::color(key);
        parse_hex_color(&hex)
    }
}

/// Parse a hex color string (#RRGGBB or #RRGGBBAA) into [f32; 4] RGBA.
fn parse_hex_color(hex: &str) -> [f32; 4] {
    let hex = hex.trim_start_matches('#');
    if hex.len() >= 6 {
        let r = u8::from_str_radix(&hex[0..2], 16).unwrap_or(255) as f32 / 255.0;
        let g = u8::from_str_radix(&hex[2..4], 16).unwrap_or(0) as f32 / 255.0;
        let b = u8::from_str_radix(&hex[4..6], 16).unwrap_or(255) as f32 / 255.0;
        let a = if hex.len() >= 8 {
            u8::from_str_radix(&hex[6..8], 16).unwrap_or(255) as f32 / 255.0
        } else {
            1.0
        };
        [r, g, b, a]
    } else {
        [1.0, 0.0, 1.0, 1.0] // Magenta fallback
    }
}

/// The authoritative Cyberpunk Viking default tokens
pub fn default_tokens() -> DesignTokens {
    let mut tokens = DesignTokens::new();
    // Core Norse Colorways
    tokens.color.insert(
        "background".to_string(),
        TokenValue::Adaptive {
            light: "#FFFFFF".to_string(), // Light mode: white background
            dark: "#000000".to_string(),  // Dark mode: Ginnungagap (The Void)
        },
    );
    tokens.color.insert(
        "primary".to_string(),
        TokenValue::Adaptive {
            light: "#007B8A".to_string(), // Light mode: muted cyan
            dark: "#00FFFF".to_string(),  // Dark mode: NiflCyan (Aesir Primary)
        },
    );
    tokens.color.insert(
        "secondary".to_string(),
        TokenValue::Adaptive {
            light: "#8A008A".to_string(), // Light mode: muted magenta
            dark: "#FF00FF".to_string(),  // Dark mode: MuspelMagenta (Berserker Secondary)
        },
    );
    tokens.color.insert(
        "surface".to_string(),
        TokenValue::Adaptive {
            light: "#FFFFFF".to_string(),
            dark: "#121212".to_string(),
        },
    );
    tokens.color.insert(
        "text".to_string(),
        TokenValue::Adaptive {
            light: "#000000".to_string(),
            dark: "#FFFFFF".to_string(),
        },
    );
    // Semantic component tokens
    tokens.color.insert(
        "surface_elevated".to_string(),
        TokenValue::Adaptive {
            light: "#FFFFFF".to_string(),
            dark: "#1A1A24".to_string(),
        },
    );
    tokens.color.insert(
        "surface_overlay".to_string(),
        TokenValue::Adaptive {
            light: "#FFFFFF".to_string(),
            dark: "#1E1E2E".to_string(),
        },
    );
    tokens.color.insert(
        "border".to_string(),
        TokenValue::Adaptive {
            light: "#D0D0D8".to_string(),
            dark: "#2A2A3A".to_string(),
        },
    );
    tokens.color.insert(
        "border_strong".to_string(),
        TokenValue::Adaptive {
            light: "#A0A0B0".to_string(),
            dark: "#3A3A50".to_string(),
        },
    );
    tokens.color.insert(
        "text_muted".to_string(),
        TokenValue::Adaptive {
            light: "#606070".to_string(),
            dark: "#8080A0".to_string(),
        },
    );
    tokens.color.insert(
        "text_dim".to_string(),
        TokenValue::Adaptive {
            light: "#9090A0".to_string(),
            dark: "#505070".to_string(),
        },
    );
    tokens.color.insert(
        "accent".to_string(),
        TokenValue::Adaptive {
            light: "#007B8A".to_string(), // Light mode: muted cyan
            dark: "#00FFFF".to_string(),  // Dark mode: NiflCyan
        },
    );
    tokens.color.insert(
        "accent_hover".to_string(),
        TokenValue::Adaptive {
            light: "#00A0B0".to_string(), // Light mode: lighter muted cyan
            dark: "#33FFFF".to_string(),  // Dark mode: brighter cyan
        },
    );
    tokens.color.insert(
        "success".to_string(),
        TokenValue::Single {
            value: "#00E676".to_string(),
        },
    );
    tokens.color.insert(
        "warning".to_string(),
        TokenValue::Single {
            value: "#FFB300".to_string(),
        },
    );
    tokens.color.insert(
        "error".to_string(),
        TokenValue::Single {
            value: "#FF5252".to_string(),
        },
    );
    tokens.color.insert(
        "info".to_string(),
        TokenValue::Single {
            value: "#448AFF".to_string(),
        },
    );
    tokens.color.insert(
        "hover".to_string(),
        TokenValue::Adaptive {
            light: "#F0F0F5".to_string(),
            dark: "#252535".to_string(),
        },
    );
    tokens.color.insert(
        "active".to_string(),
        TokenValue::Adaptive {
            light: "#E0E0EB".to_string(),
            dark: "#303045".to_string(),
        },
    );
    tokens.color.insert(
        "disabled".to_string(),
        TokenValue::Adaptive {
            light: "#E8E8F0".to_string(),
            dark: "#1A1A28".to_string(),
        },
    );
    tokens.color.insert(
        "disabled_text".to_string(),
        TokenValue::Adaptive {
            light: "#B0B0C0".to_string(),
            dark: "#404060".to_string(),
        },
    );
    tokens.color.insert(
        "focus_ring".to_string(),
        TokenValue::Single {
            value: "#00FFFF".to_string(),
        },
    );
    tokens.color.insert(
        "shadow".to_string(),
        TokenValue::Adaptive {
            light: "#00000020".to_string(),
            dark: "#00000060".to_string(),
        },
    );
    tokens.color.insert(
        "code_bg".to_string(),
        TokenValue::Adaptive {
            light: "#F5F5FA".to_string(),
            dark: "#0D0D18".to_string(),
        },
    );
    // Bifrost (Glassmorphism) - Frosted Style
    tokens.bifrost.insert(
        "blur".to_string(),
        TokenValue::Single {
            value: "25.0".to_string(),
        },
    );
    tokens.bifrost.insert(
        "saturation".to_string(),
        TokenValue::Single {
            value: "1.2".to_string(),
        },
    );
    tokens.bifrost.insert(
        "opacity".to_string(),
        TokenValue::Single {
            value: "0.65".to_string(),
        },
    );
    // Gungnir (Neon Glow)
    tokens.gungnir.insert(
        "intensity".to_string(),
        TokenValue::Single {
            value: "1.0".to_string(),
        },
    );
    tokens.gungnir.insert(
        "radius".to_string(),
        TokenValue::Single {
            value: "15.0".to_string(),
        },
    );
    // Mjolnir (Sharp Geometry)
    tokens.mjolnir.insert(
        "clip_angle".to_string(),
        TokenValue::Single {
            value: "12.0".to_string(),
        },
    );
    tokens.mjolnir.insert(
        "border_width".to_string(),
        TokenValue::Single {
            value: "2.0".to_string(),
        },
    );
    // Sleipnir (Spring Animation)
    tokens.anim.insert(
        "stiffness".to_string(),
        TokenValue::Single {
            value: "170.0".to_string(),
        },
    );
    tokens.anim.insert(
        "damping".to_string(),
        TokenValue::Single {
            value: "26.0".to_string(),
        },
    );
    tokens.anim.insert(
        "mass".to_string(),
        TokenValue::Single {
            value: "1.0".to_string(),
        },
    );
    // Accessibility
    tokens.accessibility.insert(
        "reduce_motion".to_string(),
        TokenValue::Single {
            value: "false".to_string(),
        },
    );
    tokens
}
/// Environment wrapper for accessing ambient values
pub struct Environment<K: EnvKey> {
    _marker: std::marker::PhantomData<K>,
}
impl<K: EnvKey> Default for Environment<K> {
    fn default() -> Self {
        Self::new()
    }
}
impl<K: EnvKey> Environment<K> {
    /// Create a new Environment
    pub fn new() -> Self {
        Self {
            _marker: std::marker::PhantomData,
        }
    }
    /// Get the current value from the environment
    pub fn get(&self) -> K::Value {
        if let Some(env_store) = ENVIRONMENT.get() {
            let env_lock = env_store.lock().unwrap_or_else(|p| p.into_inner());
            if let Some(val) = env_lock.get(&std::any::TypeId::of::<K>()) {
                if let Some(typed_val) = val.downcast_ref::<K::Value>() {
                    return typed_val.clone();
                } else {
                    log::warn!(
                        "Environment: Downcast failed for key type {:?}",
                        std::any::type_name::<K>()
                    );
                }
            } else {
                // Lowered to trace to avoid terminal logging overhead under standard debug runs
                log::trace!(
                    "Environment: Key not found: {:?}. Returning default.",
                    std::any::type_name::<K>()
                );
            }
        } else {
            // Lowered to trace to avoid terminal logging overhead under standard debug runs
            log::trace!(
                "Environment: Store not initialized. Key: {:?}. Returning default.",
                std::any::type_name::<K>()
            );
        }
        K::default_value()
    }
}
/// Ambient environment management
pub mod env {
    /// Insert a value into the environment
    pub fn insert<K: super::EnvKey>(value: K::Value) {
        let store = super::ENVIRONMENT
            .get_or_init(|| std::sync::Mutex::new(std::collections::HashMap::new()));
        let mut env_map = store.lock().unwrap_or_else(|p| p.into_inner());
        env_map.insert(std::any::TypeId::of::<K>(), Box::new(value));
    }
    /// Remove a value from the environment.
    pub fn remove<K: super::EnvKey>() {
        if let Some(store) = super::ENVIRONMENT.get() {
            let mut env_map = store.lock().unwrap_or_else(|p| p.into_inner());
            env_map.remove(&std::any::TypeId::of::<K>());
        }
    }
}
/// Geometry modifiers
/// Size of the view in logical pixels
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Size {
    pub width: f32,
    pub height: f32,
}

impl Size {
    pub const ZERO: Self = Self {
        width: 0.0,
        height: 0.0,
    };

    pub fn new(width: f32, height: f32) -> Self {
        Self { width, height }
    }
}

/// Insets for padding
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct EdgeInsets {
    pub top: f32,
    pub leading: f32,
    pub bottom: f32,
    pub trailing: f32,
}

impl EdgeInsets {
    /// Equal insets on all edges
    pub fn all(value: f32) -> Self {
        Self {
            top: value,
            leading: value,
            bottom: value,
            trailing: value,
        }
    }

    /// Vertical insets (top and bottom)
    pub fn vertical(value: f32) -> Self {
        Self {
            top: value,
            leading: 0.0,
            bottom: value,
            trailing: 0.0,
        }
    }

    /// Horizontal insets (leading and trailing)
    pub fn horizontal(value: f32) -> Self {
        Self {
            top: 0.0,
            leading: value,
            bottom: 0.0,
            trailing: value,
        }
    }
}

/// Modifier to set the size and alignment constraints of a view.
/// This determines the proposal size passed to the child and how the child is aligned
/// within the layout rect allocated to the frame.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FrameModifier {
    /// Exact width to assign to the child view.
    pub width: Option<f32>,
    /// Exact height to assign to the child view.
    pub height: Option<f32>,
    /// Minimum width constraint for the view.
    pub min_width: Option<f32>,
    /// Maximum width constraint for the view.
    pub max_width: Option<f32>,
    /// Minimum height constraint for the view.
    pub min_height: Option<f32>,
    /// Maximum height constraint for the view.
    pub max_height: Option<f32>,
    /// The alignment strategy for positioning the child view within the frame.
    pub alignment: Alignment,
}

impl Default for FrameModifier {
    /// Returns the default frame configuration which has no constraints and center alignment.
    fn default() -> Self {
        Self::new()
    }
}

impl FrameModifier {
    /// Creates a new FrameModifier with all dimensions unspecified and center alignment.
    pub fn new() -> Self {
        Self {
            width: None,
            height: None,
            min_width: None,
            max_width: None,
            min_height: None,
            max_height: None,
            alignment: Alignment::Center,
        }
    }

    /// Sets the fixed width of the frame.
    pub fn width(mut self, width: f32) -> Self {
        self.width = Some(width);
        self
    }

    /// Sets the fixed height of the frame.
    pub fn height(mut self, height: f32) -> Self {
        self.height = Some(height);
        self
    }

    /// Sets both the fixed width and height of the frame.
    pub fn size(mut self, width: f32, height: f32) -> Self {
        self.width = Some(width);
        self.height = Some(height);
        self
    }

    /// Sets the minimum width constraint.
    pub fn min_width(mut self, min_width: f32) -> Self {
        self.min_width = Some(min_width);
        self
    }

    /// Sets the maximum width constraint.
    pub fn max_width(mut self, max_width: f32) -> Self {
        self.max_width = Some(max_width);
        self
    }

    /// Sets the minimum height constraint.
    pub fn min_height(mut self, min_height: f32) -> Self {
        self.min_height = Some(min_height);
        self
    }

    /// Sets the maximum height constraint.
    pub fn max_height(mut self, max_height: f32) -> Self {
        self.max_height = Some(max_height);
        self
    }

    /// Sets the alignment strategy for the child within the frame's layout bounds.
    pub fn alignment(mut self, alignment: Alignment) -> Self {
        self.alignment = alignment;
        self
    }
}

impl ViewModifier for FrameModifier {
    /// Wraps the child view in a ModifiedView using this frame modifier.
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    /// Transforms the layout size proposal offered to the child to comply with frame constraints.
    fn transform_proposal(&self, proposal: SizeProposal) -> SizeProposal {
        let w = if let Some(width) = self.width {
            Some(width)
        } else {
            proposal.width.map(|pw| {
                pw.clamp(
                    self.min_width.unwrap_or(0.0),
                    self.max_width.unwrap_or(f32::INFINITY),
                )
            })
        };
        let h = if let Some(height) = self.height {
            Some(height)
        } else {
            proposal.height.map(|ph| {
                ph.clamp(
                    self.min_height.unwrap_or(0.0),
                    self.max_height.unwrap_or(f32::INFINITY),
                )
            })
        };
        SizeProposal {
            width: w,
            height: h,
        }
    }

    /// Constraints and transforms the child's resulting size to fit the frame's bounds.
    fn transform_size(&self, child_size: Size) -> Size {
        let w = if let Some(width) = self.width {
            width
        } else {
            child_size.width.clamp(
                self.min_width.unwrap_or(0.0),
                self.max_width.unwrap_or(f32::INFINITY),
            )
        };
        let h = if let Some(height) = self.height {
            height
        } else {
            child_size.height.clamp(
                self.min_height.unwrap_or(0.0),
                self.max_height.unwrap_or(f32::INFINITY),
            )
        };
        Size {
            width: w,
            height: h,
        }
    }

    /// Renders the frame's child view aligned within the layout rect.
    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        self.render(renderer, rect);
        let child_proposal =
            self.transform_proposal(SizeProposal::new(Some(rect.width), Some(rect.height)));
        let child_size = view.intrinsic_size(renderer, child_proposal);

        let mut child_x = rect.x;
        let mut child_y = rect.y;

        match self.alignment {
            Alignment::Leading => {
                child_y = rect.y + (rect.height - child_size.height) / 2.0;
            }
            Alignment::Trailing => {
                child_x = rect.x + rect.width - child_size.width;
                child_y = rect.y + (rect.height - child_size.height) / 2.0;
            }
            Alignment::Top => {
                child_x = rect.x + (rect.width - child_size.width) / 2.0;
            }
            Alignment::Bottom => {
                child_x = rect.x + (rect.width - child_size.width) / 2.0;
                child_y = rect.y + rect.height - child_size.height;
            }
            Alignment::Center => {
                child_x = rect.x + (rect.width - child_size.width) / 2.0;
                child_y = rect.y + (rect.height - child_size.height) / 2.0;
            }
        }

        let child_rect = Rect {
            x: child_x,
            y: child_y,
            width: child_size.width,
            height: child_size.height,
        };

        view.render(renderer, child_rect);
        self.post_render(renderer, rect);
    }
}

/// Modifier to set the flex weight of a view
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FlexModifier {
    pub weight: f32,
}

impl ViewModifier for FlexModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn child_flex_weight<V: View>(&self, _view: &V) -> f32 {
        self.weight
    }
}

/// Modifier that specifies the column and row placement of a view inside a Grid layout.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct GridPlacementModifier {
    /// The grid placement settings containing column/row indexes and spans.
    pub placement: GridPlacement,
}

impl ViewModifier for GridPlacementModifier {
    /// Wraps the child view in a ModifiedView using this modifier.
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    /// Exposes the grid placement metadata to parent layout engines.
    fn get_grid_placement(&self) -> Option<GridPlacement> {
        Some(self.placement)
    }
}

/// Modifier to render a popover, tooltip, or menu view overlaying an anchored view.
/// It supports alignment positioning and outside-click dismissal.
#[derive(Clone)]
pub struct OverlayModifier {
    /// The overlay content view.
    pub overlay: AnyView,
    /// Where the overlay is aligned relative to the anchored view.
    pub alignment: Alignment,
    /// Additional offset in logical pixels.
    pub offset: [f32; 2],
    /// Optional dismissal callback triggered by click-outside events.
    pub on_dismiss: Option<Arc<dyn Fn() + Send + Sync>>,
}

impl ViewModifier for OverlayModifier {
    /// Wraps the child view in a ModifiedView using this overlay modifier.
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    /// Renders the overlay content positioned above the child view.
    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        // 1. Render primary anchored view
        view.render(renderer, rect);

        // 2. Measure overlay content
        let overlay_size = self
            .overlay
            .intrinsic_size(renderer, SizeProposal::unspecified());

        // 3. Align overlay rect relative to anchored rect
        let mut overlay_x;
        let mut overlay_y;

        match self.alignment {
            Alignment::Leading => {
                overlay_x = rect.x - overlay_size.width;
                overlay_y = rect.y + (rect.height - overlay_size.height) / 2.0;
            }
            Alignment::Trailing => {
                overlay_x = rect.x + rect.width;
                overlay_y = rect.y + (rect.height - overlay_size.height) / 2.0;
            }
            Alignment::Top => {
                overlay_x = rect.x + (rect.width - overlay_size.width) / 2.0;
                overlay_y = rect.y - overlay_size.height;
            }
            Alignment::Bottom => {
                overlay_x = rect.x + (rect.width - overlay_size.width) / 2.0;
                overlay_y = rect.y + rect.height;
            }
            Alignment::Center => {
                overlay_x = rect.x + (rect.width - overlay_size.width) / 2.0;
                overlay_y = rect.y + (rect.height - overlay_size.height) / 2.0;
            }
        }

        overlay_x += self.offset[0];
        overlay_y += self.offset[1];

        let overlay_rect = Rect {
            x: overlay_x,
            y: overlay_y,
            width: overlay_size.width,
            height: overlay_size.height,
        };

        // 4. Handle click-outside dismissal
        if let Some(on_dismiss) = &self.on_dismiss {
            let dismiss = on_dismiss.clone();
            renderer.register_handler(
                "pointerdown",
                Arc::new(move |event| {
                    if let Event::PointerDown { x, y, .. } = event {
                        let click_inside = x >= overlay_rect.x
                            && x <= overlay_rect.x + overlay_rect.width
                            && y >= overlay_rect.y
                            && y <= overlay_rect.y + overlay_rect.height;
                        if !click_inside {
                            dismiss();
                        }
                    }
                }),
            );
        }

        // 5. Render overlay view
        self.overlay.render(renderer, overlay_rect);
    }
}

/// Modifier to offset a view
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct OffsetModifier {
    pub x: f32,
    pub y: f32,
}

impl OffsetModifier {
    pub fn new(x: f32, y: f32) -> Self {
        Self { x, y }
    }
}

impl ViewModifier for OffsetModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }
}

/// Modifier to set the z-index of a view
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ZIndexModifier {
    pub z_index: i32,
}

impl ZIndexModifier {
    pub fn new(z_index: i32) -> Self {
        Self { z_index }
    }
}

impl ViewModifier for ZIndexModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }
}

/// Layout constraints for views
#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub struct LayoutConstraints {
    pub min_width: Option<f32>,
    pub max_width: Option<f32>,
    pub min_height: Option<f32>,
    pub max_height: Option<f32>,
}

/// Modifier to set layout constraints
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct LayoutModifier {
    pub constraints: LayoutConstraints,
}

impl LayoutModifier {
    pub fn new(constraints: LayoutConstraints) -> Self {
        Self { constraints }
    }
}

impl ViewModifier for LayoutModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }
}

/// Modifier to handle platform safe areas
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct SafeAreaModifier {
    pub ignores: bool,
}

impl ViewModifier for SafeAreaModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }
}

/// Modifier to add elevation (shadow) to a view
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ElevationModifier {
    pub level: f32,
}

impl ViewModifier for ElevationModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn render_view<V: View>(&self, view: &V, renderer: &mut dyn Renderer, rect: Rect) {
        if self.level > 0.0 {
            let radius = self.level * 2.0;
            let offset_y = self.level * 0.5;
            let shadow_color = [0.0, 0.0, 0.0, 0.3];
            renderer.push_shadow(radius, shadow_color, [0.0, offset_y]);
            view.render(renderer, rect);
            renderer.pop_shadow();
        } else {
            view.render(renderer, rect);
        }
    }
}

/// Position modifier — offsets a view from its layout position.
/// Enables absolute-like positioning within a container.
#[derive(Clone)]
pub struct PositionModifier {
    pub x: f32,
    pub y: f32,
}

impl ViewModifier for PositionModifier {
    fn modify<V: View>(self, content: V) -> impl View {
        ModifiedView::new(content, self)
    }

    fn transform_rect(&self, rect: Rect) -> Rect {
        Rect {
            x: rect.x + self.x,
            y: rect.y + self.y,
            width: rect.width,
            height: rect.height,
        }
    }
}

// Layout subsystem
pub mod layout {
    use super::*;

    /// Key used to identify a cached layout entry.
    /// Combines a view hash with a generation counter for cache invalidation.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
    pub struct LayoutKey {
        pub view_hash: u64,
        pub generation: u64,
    }

    // Layout pass scratch space
    pub struct LayoutCache {
        pub safe_area: SafeArea,
        pub delta_time: f32,
        /// Device scale factor for HiDPI / retina snapping. Defaults to 1.0.
        pub scale_factor: f32,
        /// The visible viewport bounds in logical pixels.
        /// If Some, layout execution can cull offscreen subtrees.
        pub viewport: Option<Rect>,
        /// Time budget for the layout pass. Defaults to 4.0ms.
        pub layout_time_budget: std::time::Duration,
        /// Start of the layout pass, captured at the beginning of the frame/layout run.
        pub layout_start_time: Option<std::time::Instant>,
        size_cache: HashMap<(u64, u32, u32), Size>, // (ViewHash, ProposalW, ProposalH)
        /// Map tracking child-to-parent view hash relationships for bottom-up invalidation.
        pub parent_map: HashMap<u64, u64>,
        /// Monotonically increasing generation counter for cache invalidation.
        /// When a view tree changes, bumping the generation causes stale entries
        /// to be treated as invalid without eagerly clearing the entire cache.
        generation: u64,
        /// Opaque pointer to the active layout engine (e.g. Taffy)
        pub engine: Option<Box<dyn std::any::Any + Send + Sync>>,
        /// Opaque pointer to the active animation orchestrator
        pub animators: Option<Box<dyn std::any::Any + Send + Sync>>,
        /// Cached previous rects for view transitions
        pub previous_rects: HashMap<u64, Rect>,
        /// Generation counter for cache eviction.
        /// Incremented each frame; entries not touched for N frames are evicted.
        pub eviction_generation: u64,
        /// Tracks which generation each previous_rects entry was last touched in.
        pub previous_rects_generation: HashMap<u64, u64>,
        /// Number of generations an entry can go untouched before eviction.
        eviction_threshold: u64,
    }

    thread_local! {
        static LAYOUT_BUDGET_DEADLINE: std::cell::RefCell<Option<std::time::Instant>> =
            const { std::cell::RefCell::new(None) };
    }

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

    impl LayoutCache {
        pub fn new() -> Self {
            Self {
                safe_area: SafeArea::default(),
                delta_time: 0.016,
                scale_factor: 1.0,
                viewport: None,
                layout_time_budget: std::time::Duration::from_millis(4),
                layout_start_time: None,
                size_cache: HashMap::new(),
                parent_map: HashMap::new(),
                generation: 0,
                engine: None,
                animators: None,
                previous_rects: HashMap::new(),
                eviction_generation: 0,
                previous_rects_generation: HashMap::new(),
                eviction_threshold: 300, // ~5 seconds at 60fps
            }
        }

        /// Returns the current generation counter.
        pub fn generation(&self) -> u64 {
            self.generation
        }

        /// Evict entries from previous_rects that haven't been touched for N generations.
        pub fn evict_stale_entries(&mut self) {
            self.eviction_generation += 1;
            let threshold = self.eviction_threshold;
            let current_gen = self.eviction_generation;
            self.previous_rects.retain(|hash, _| {
                self.previous_rects_generation
                    .get(hash)
                    .map_or(false, |g| current_gen - *g < threshold)
            });
            self.previous_rects_generation
                .retain(|hash, _| self.previous_rects.contains_key(hash));
        }

        /// Checks if the layout pass is currently running over its allocated time budget.
        pub fn is_over_budget(&self) -> bool {
            let deadline_red = LAYOUT_BUDGET_DEADLINE.with(|deadline| {
                deadline.borrow().as_ref().is_some_and(|deadline| std::time::Instant::now() >= *deadline)
            });
            if deadline_red {
                return true;
            }
            if let Some(start) = self.layout_start_time {
                start.elapsed() > self.layout_time_budget
            } else {
                false
            }
        }

        /// Set a process-local deadline for layout cache consumers.
        /// When this deadline is exceeded, caches should reuse previous
        /// rects instead of recomputing expensive layout work.
        pub fn set_layout_budget_deadline(deadline: Option<std::time::Instant>) {
            LAYOUT_BUDGET_DEADLINE.with(|slot| {
                *slot.borrow_mut() = deadline;
            });
        }

        /// Clear any process-local layout budget deadline.
        pub fn clear_layout_budget_deadline() {
            Self::set_layout_budget_deadline(None);
        }

        /// Bump the generation counter, logically invalidating all cached entries
        /// without eagerly clearing them. Subsequent lookups with the old generation
        /// will miss until re-populated.
        pub fn invalidate(&mut self) {
            self.generation = self.generation.wrapping_add(1);
        }

        /// Check whether a cached entry for the given key is still valid
        /// against the current generation.
        pub fn is_valid(&self, key: LayoutKey, current_gen: u64) -> bool {
            key.generation == current_gen && key.generation == self.generation
        }

        pub fn clear(&mut self) {
            self.safe_area = SafeArea::default();
            self.viewport = None;
            self.layout_start_time = None;
            self.size_cache.clear();
            self.parent_map.clear();
        }

        pub fn get_size(&self, view_hash: u64, proposal: SizeProposal) -> Option<Size> {
            let pw = (proposal.width.unwrap_or(-1.0) * 100.0) as u32;
            let ph = (proposal.height.unwrap_or(-1.0) * 100.0) as u32;
            self.size_cache.get(&(view_hash, pw, ph)).copied()
        }

        pub fn set_size(&mut self, view_hash: u64, proposal: SizeProposal, size: Size) {
            let pw = (proposal.width.unwrap_or(-1.0) * 100.0) as u32;
            let ph = (proposal.height.unwrap_or(-1.0) * 100.0) as u32;
            self.size_cache.insert((view_hash, pw, ph), size);
        }

        /// Register a child-to-parent layout relationship for bottom-up invalidation propagation.
        pub fn register_parent(&mut self, child_hash: u64, parent_hash: u64) {
            if child_hash != 0 && parent_hash != 0 {
                self.parent_map.insert(child_hash, parent_hash);
            }
        }

        /// Remove all cached size entries for a specific view hash and propagate the invalidation
        /// bottom-up to all its layout ancestors to ensure consistent layout updates.
        pub fn invalidate_view(&mut self, view_hash: u64) {
            let mut to_invalidate = vec![view_hash];
            let mut visited = std::collections::HashSet::new();
            while let Some(hash) = to_invalidate.pop() {
                if !visited.insert(hash) {
                    continue;
                }
                self.size_cache.retain(|&(h, _, _), _| h != hash);
                if let Some(&parent) = self.parent_map.get(&hash) {
                    to_invalidate.push(parent);
                }
            }
        }
    }

    /// Proposed size from parent view
    #[derive(Debug, Clone, Copy, PartialEq)]
    pub struct SizeProposal {
        pub width: Option<f32>,
        pub height: Option<f32>,
    }

    impl SizeProposal {
        pub fn unspecified() -> Self {
            Self {
                width: None,
                height: None,
            }
        }

        pub fn width(width: f32) -> Self {
            Self {
                width: Some(width),
                height: None,
            }
        }

        pub fn height(height: f32) -> Self {
            Self {
                width: None,
                height: Some(height),
            }
        }

        pub fn tight(width: f32, height: f32) -> Self {
            Self {
                width: Some(width),
                height: Some(height),
            }
        }

        pub fn new(width: Option<f32>, height: Option<f32>) -> Self {
            Self { width, height }
        }
    }

    /// A view that can participate in layout
    pub trait LayoutView: Send {
        /// Propose a size for this view given the available space
        fn size_that_fits(
            &self,
            proposal: SizeProposal,
            subviews: &[&dyn LayoutView],
            cache: &mut LayoutCache,
        ) -> Size;

        /// Place subviews within the given bounds
        fn place_subviews(
            &self,
            bounds: Rect,
            subviews: &mut [&mut dyn LayoutView],
            cache: &mut LayoutCache,
        );

        /// Returns the flex weight of this view (default is 0.0, which means fixed/intrinsic)
        fn flex_weight(&self) -> f32 {
            0.0
        }

        /// Returns a persistent unique identifier for this view to enable Layout View Transitions.
        /// Return 0 (default) to disable layout animations for this node.
        fn view_hash(&self) -> u64 {
            0
        }

        /// Return true when this view's layout may have changed since the last pass.
        ///
        /// The layout engine uses this to skip cache lookups for views that are
        /// guaranteed static (e.g., chrome elements that never change between frames).
        /// Default true for backward compatibility -- override false for static subtrees.
        ///
        /// When false, the engine may skip `size_that_fits` entirely and reuse the
        /// cached rect from `LayoutCache::previous_rects`.
        fn changed(&self) -> bool {
            true
        }

        /// Return a debug representation of this layout subtree.
        /// The `indent` parameter controls the indentation level for nested display.
        fn debug_layout(&self, indent: usize) -> String {
            let prefix = " ".repeat(indent);
            format!("{}LayoutView", prefix)
        }
    }
    /// Edge insets for padding, margins, and safe areas
    #[derive(Debug, Clone, Copy, PartialEq, Default, Serialize, Deserialize)]
    pub struct EdgeInsets {
        pub top: f32,
        pub leading: f32,
        pub bottom: f32,
        pub trailing: f32,
    }

    impl EdgeInsets {
        pub fn new(top: f32, leading: f32, bottom: f32, trailing: f32) -> Self {
            Self {
                top,
                leading,
                bottom,
                trailing,
            }
        }

        pub fn all(value: f32) -> Self {
            Self {
                top: value,
                leading: value,
                bottom: value,
                trailing: value,
            }
        }
    }

    /// SafeArea constraints provided by the platform
    #[derive(Debug, Clone, Copy, PartialEq, Default, Serialize, Deserialize)]
    pub struct SafeArea {
        pub insets: EdgeInsets,
    }

    /// SDF Shape definitions for Vili Interaction Paradigm hit-testing.
    #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
    pub enum SdfShape {
        Rect(Rect),
        RoundedRect { rect: Rect, radius: f32 },
        Circle { center: [f32; 2], radius: f32 },
    }

    /// Rectangle in logical pixels
    #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
    pub struct Rect {
        pub x: f32,
        pub y: f32,
        pub width: f32,
        pub height: f32,
    }

    impl Rect {
        pub fn new(x: f32, y: f32, width: f32, height: f32) -> Self {
            Self {
                x,
                y,
                width,
                height,
            }
        }

        pub fn inset(&self, amount: f32) -> Self {
            Self {
                x: self.x + amount,
                y: self.y + amount,
                width: (self.width - amount * 2.0).max(0.0),
                height: (self.height - amount * 2.0).max(0.0),
            }
        }

        pub fn offset(&self, dx: f32, dy: f32) -> Self {
            Self {
                x: self.x + dx,
                y: self.y + dy,
                ..*self
            }
        }

        pub fn zero() -> Self {
            Self {
                x: 0.0,
                y: 0.0,
                width: 0.0,
                height: 0.0,
            }
        }

        pub fn contains(&self, x: f32, y: f32) -> bool {
            x >= self.x && x <= self.x + self.width && y >= self.y && y <= self.y + self.height
        }

        /// Determines whether this rectangle overlaps with another rectangle.
        ///
        /// # Contract
        /// Two rectangles overlap if their projection intervals on both the X
        /// and Y axes overlap. This is used for viewport intersection checks
        /// to determine visibility constraints during layout culling.
        pub fn intersects(&self, other: &Rect) -> bool {
            self.x < other.x + other.width
                && self.x + self.width > other.x
                && self.y < other.y + other.height
                && self.y + self.height > other.y
        }

        pub fn size(&self) -> Size {
            Size {
                width: self.width,
                height: self.height,
            }
        }

        /// Split the rect horizontally into N equal pieces
        pub fn split_horizontal(&self, n: usize) -> Vec<Rect> {
            if n == 0 {
                return vec![];
            }
            let item_width = self.width / n as f32;
            (0..n)
                .map(|i| Rect {
                    x: self.x + i as f32 * item_width,
                    y: self.y,
                    width: item_width,
                    height: self.height,
                })
                .collect()
        }

        /// Split the rect vertically into N equal pieces
        pub fn split_vertical(&self, n: usize) -> Vec<Rect> {
            if n == 0 {
                return vec![];
            }
            let item_height = self.height / n as f32;
            (0..n)
                .map(|i| Rect {
                    x: self.x,
                    y: self.y + i as f32 * item_height,
                    width: self.width,
                    height: item_height,
                })
                .collect()
        }
    }
}

// Size and FrameRenderer are pub items in this module; no re-export alias needed.

pub mod agents;
pub mod animation;
pub mod gpu;
pub mod material;
pub mod runtime;
pub mod scene_graph;
pub mod sdf_shadow;

// Re-export commonly used types
pub use layout::{LayoutCache, LayoutKey, LayoutView, Rect, SizeProposal};
pub use material::DrawMaterial;
pub use scene_graph::{NodeId, bifrost_registry};
pub use color::SemanticColors;

// Duplicate AssetState removed - original definition at line 67

/// AssetManager defines the interface for loading and caching external resources.
pub trait AssetManager: Send + Sync {
    /// Request an image asset. Returns the current state (Loading, Ready, or Error).
    fn load_image(&self, url: &str) -> AssetState<Arc<Vec<u8>>>;

    /// Pre-load an image into the cache.
    fn preload_image(&self, url: &str);
}

/// The phase of a touch or gesture event in its lifecycle.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum TouchPhase {
    /// The touch/gesture has just begun.
    Began,
    /// The touch/gesture is moving.
    Moved,
    /// The touch/gesture has ended normally.
    Ended,
    /// The touch/gesture was cancelled (e.g., by the system).
    Cancelled,
}

/// User input event types
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub enum Event {
    PointerDown {
        x: f32,
        y: f32,
        button: u32,
        proximity_field: f32,
        tilt: Option<f32>,
        azimuth: Option<f32>,
        pressure: Option<f32>,
        barrel_rotation: Option<f32>,
        pointer_precision: f32,
    },
    PointerUp {
        x: f32,
        y: f32,
        button: u32,
        tilt: Option<f32>,
        azimuth: Option<f32>,
        pressure: Option<f32>,
        barrel_rotation: Option<f32>,
        pointer_precision: f32,
    },
    PointerMove {
        x: f32,
        y: f32,
        proximity_field: f32,
        tilt: Option<f32>,
        azimuth: Option<f32>,
        pressure: Option<f32>,
        barrel_rotation: Option<f32>,
        pointer_precision: f32,
    },
    PointerClick {
        x: f32,
        y: f32,
        button: u32,
        tilt: Option<f32>,
        azimuth: Option<f32>,
        pressure: Option<f32>,
        barrel_rotation: Option<f32>,
        pointer_precision: f32,
    },
    PointerEnter,
    PointerLeave,
    /// Mouse wheel / trackpad scroll event.
    /// `delta_x` is the horizontal scroll amount, `delta_y` is the vertical scroll amount (positive = scroll down).
    PointerWheel {
        x: f32,
        y: f32,
        delta_x: f32,
        delta_y: f32,
        pointer_precision: f32,
    },
    /// Double-click event (rapid successive clicks).
    PointerDoubleClick {
        x: f32,
        y: f32,
        button: u32,
        pointer_precision: f32,
    },
    /// Drag-and-drop: drag started (pointer moved while button held past threshold).
    DragStart {
        x: f32,
        y: f32,
        button: u32,
        pointer_precision: f32,
    },
    /// Drag-and-drop: drag in progress.
    DragMove {
        x: f32,
        y: f32,
        pointer_precision: f32,
    },
    /// Drag-and-drop: drag ended (pointer released).
    DragEnd {
        x: f32,
        y: f32,
        pointer_precision: f32,
    },
    KeyDown {
        key: String,
        modifiers: KeyModifiers,
    },
    KeyUp {
        key: String,
        modifiers: KeyModifiers,
    },
    /// Focus gained by a node.
    FocusIn,
    /// Focus lost by a node.
    FocusOut,
    /// Clipboard copy event.
    Copy,
    /// Clipboard cut event.
    Cut,
    /// Clipboard paste event with the pasted text content.
    Paste(String),
    /// Input Method Editor event (e.g. CJK character composition)
    Ime(String),
    /// Touch began at the given position.
    TouchStart {
        x: f32,
        y: f32,
        touch_id: u64,
    },
    /// Touch moved to a new position.
    TouchMove {
        x: f32,
        y: f32,
        touch_id: u64,
    },
    /// Touch ended at the given position.
    TouchEnd {
        x: f32,
        y: f32,
        touch_id: u64,
    },
    /// Touch cancelled.
    TouchCancel {
        touch_id: u64,
    },
    /// Multi-touch pinch gesture.
    /// `center` is the gesture anchor point in device-independent pixels.
    /// `scale` is the relative pinch scale (>1 = expand, <1 = contract).
    /// `velocity` is the instantaneous velocity of the pinch.
    /// `phase` indicates the current phase of the gesture lifecycle.
    GesturePinch {
        center: [f32; 2],
        scale: f32,
        velocity: f32,
        phase: TouchPhase,
    },
    /// Multi-touch swipe/pan gesture.
    /// `direction` is the normalized direction vector [dx, dy].
    /// `velocity` is the instantaneous velocity of the swipe.
    /// `phase` indicates the current phase of the gesture lifecycle.
    GestureSwipe {
        direction: [f32; 2],
        velocity: f32,
        phase: TouchPhase,
    },
    /// Drag-and-drop: external file dropped onto window.
    FileDrop {
        x: f32,
        y: f32,
        path: String,
    },
}

impl Event {
    /// Returns the input pointer precision value in physical pixels if applicable.
    ///
    /// WHY: Used to scale hit-testing bounding boxes for proximity matching.
    /// CONTRACT: Mouse pointer inputs return low precision values (close to 0.0px),
    /// whereas touch inputs return larger values (e.g., 150.0px) for finger emulation.
    pub fn pointer_precision(&self) -> f32 {
        match self {
            Self::PointerDown {
                pointer_precision, ..
            }
            | Self::PointerUp {
                pointer_precision, ..
            }
            | Self::PointerMove {
                pointer_precision, ..
            }
            | Self::PointerClick {
                pointer_precision, ..
            }
            | Self::PointerWheel {
                pointer_precision, ..
            }
            | Self::PointerDoubleClick {
                pointer_precision, ..
            }
            | Self::DragStart {
                pointer_precision, ..
            }
            | Self::DragMove {
                pointer_precision, ..
            }
            | Self::DragEnd {
                pointer_precision, ..
            } => *pointer_precision,
            _ => 0.0,
        }
    }

    /// Returns the canonical string name of the event for lookup in handler maps.
    pub fn name(&self) -> &'static str {
        match self {
            Self::PointerDown { .. } => "pointerdown",
            Self::PointerUp { .. } => "pointerup",
            Self::PointerMove { .. } => "pointermove",
            Self::PointerClick { .. } => "pointerclick",
            Self::PointerEnter => "pointerenter",
            Self::PointerLeave => "pointerleave",
            Self::PointerWheel { .. } => "pointerwheel",
            Self::PointerDoubleClick { .. } => "pointerdoubleclick",
            Self::DragStart { .. } => "dragstart",
            Self::DragMove { .. } => "dragmove",
            Self::DragEnd { .. } => "dragend",
            Self::KeyDown { .. } => "keydown",
            Self::KeyUp { .. } => "keyup",
            Self::FocusIn => "focusin",
            Self::FocusOut => "focusout",
            Self::Copy => "copy",
            Self::Cut => "cut",
            Self::Paste(_) => "paste",
            Self::Ime(_) => "ime",
            Self::TouchStart { .. } => "touchstart",
            Self::TouchMove { .. } => "touchmove",
            Self::TouchEnd { .. } => "touchend",
            Self::TouchCancel { .. } => "touchcancel",
            Self::GesturePinch { .. } => "gesturepinch",
            Self::GestureSwipe { .. } => "gestureswipe",
            Self::FileDrop { .. } => "filedrop",
        }
    }
}


/// Response from an event handler
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EventResponse {
    Handled,
    Ignored,
}

// =========================================================================
// P1-40: EventPhase -- documents event propagation phases
// =========================================================================
//
// The CVKG event system follows the standard capture/target/bubble
// model used by the W3C DOM Event spec. When an event fires, it
// propagates through 3 phases:
//
// 1. Capture: the event travels from the root down to the
//    target's parent. Listeners registered for the capture
//    phase fire first.
// 2. Target: the event reaches the target node itself. Listeners
//    on the target fire (regardless of capture/bubble).
// 3. Bubble: the event travels back up from the target's
//    parent to the root. Listeners registered for the bubble
//    phase fire last.
//
// Cancellation: any handler can call Event::stop_propagation()
// to prevent the event from continuing to the next phase or
// the next node. This affects only the current event instance.
//
// Example: a click on a button inside a panel:
//  - panel's capture handler fires
//  - button's capture handler fires
//  - button's target handler fires
//  - button's bubble handler fires
//  - panel's bubble handler fires
//
// Use this enum when registering listeners to specify which
// phase to listen for.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum EventPhase {
    /// Event is traveling from the root toward the target.
    Capture,
    /// Event has reached the target node.
    Target,
    /// Event is traveling from the target back toward the root.
    Bubble,
}

impl EventPhase {
    /// All phases in propagation order.
    pub const ALL: [EventPhase; 3] = [
        EventPhase::Capture,
        EventPhase::Target,
        EventPhase::Bubble,
    ];
}

/// A basic implementation of AssetManager that can be overridden by platform backends.
pub struct DefaultAssetManager {
    cache: AssetCache,
}
type AssetCache = Arc<arc_swap::ArcSwap<HashMap<String, AssetState<Arc<Vec<u8>>>>>>;

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

impl DefaultAssetManager {
    pub fn new() -> Self {
        Self {
            cache: Arc::new(arc_swap::ArcSwap::from_pointee(HashMap::new())),
        }
    }
}

impl AssetManager for DefaultAssetManager {
    fn load_image(&self, url: &str) -> AssetState<Arc<Vec<u8>>> {
        if let Some(state) = self.cache.load().get(url) {
            return state.clone();
        }

        self.cache.rcu(|map| {
            let mut m = (**map).clone();
            m.entry(url.to_string()).or_insert(AssetState::Loading);
            m
        });
        AssetState::Loading
    }

    fn preload_image(&self, _url: &str) {}
}

use std::future::Future;

/// Suspense wrapper for asynchronous state management.
/// Integrates with State<T> to provide loading/error/ready states for async operations.
pub struct Suspense<T: Clone + Send + Sync + 'static> {
    inner: State<AssetState<T>>,
}

impl<T: Clone + Send + Sync + 'static> Default for Suspense<T> {
    fn default() -> Self {
        Self::new()
    }
}

impl<T: Clone + Send + Sync + 'static> Suspense<T> {
    pub fn new() -> Self {
        Self {
            inner: State::new(AssetState::Loading),
        }
    }

    pub fn new_async<F>(future: F) -> Self
    where
        F: Future<Output = Result<T, String>> + Send + 'static,
    {
        let suspense = Self::new();
        let suspense_clone = suspense.clone();

        #[cfg(not(target_arch = "wasm32"))]
        {
            // P1-17 fix: use the shared fallback runtime instead of
            // spawning a new OS thread + runtime per call. If an
            // ambient tokio runtime exists, prefer it (preserves
            // caller intent). Otherwise use the shared fallback
            // runtime which is bounded to a small worker count.
            if let Ok(handle) = tokio::runtime::Handle::try_current() {
                handle.spawn(async move {
                    let result = future.await;
                    match result {
                        Ok(val) => suspense_clone.inner.set(AssetState::Ready(val)),
                        Err(err) => suspense_clone.inner.set(AssetState::Error(err)),
                    }
                });
            } else {
                fallback_runtime().spawn(async move {
                    let result = future.await;
                    match result {
                        Ok(val) => suspense_clone.inner.set(AssetState::Ready(val)),
                        Err(err) => suspense_clone.inner.set(AssetState::Error(err)),
                    }
                });
            }
        }
        #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
        {
            wasm_bindgen_futures::spawn_local(async move {
                let result = future.await;
                match result {
                    Ok(val) => suspense_clone.inner.set(AssetState::Ready(val)),
                    Err(err) => suspense_clone.inner.set(AssetState::Error(err)),
                }
            });
        }

        suspense
    }

    pub fn ready(value: T) -> Self {
        Self {
            inner: State::new(AssetState::Ready(value)),
        }
    }

    pub fn error(message: impl Into<String>) -> Self {
        Self {
            inner: State::new(AssetState::Error(message.into())),
        }
    }

    pub fn get(&self) -> AssetState<T> {
        self.inner.get()
    }

    pub fn get_ref(&self) -> AssetState<T> {
        self.inner.get()
    }

    pub fn is_loading(&self) -> bool {
        matches!(self.get(), AssetState::Loading)
    }

    pub fn is_ready(&self) -> bool {
        matches!(self.get(), AssetState::Ready(_))
    }

    pub fn is_error(&self) -> bool {
        matches!(self.get(), AssetState::Error(_))
    }

    pub fn ready_value(&self) -> Option<T> {
        match self.get() {
            AssetState::Ready(value) => Some(value),
            _ => None,
        }
    }

    pub fn error_message(&self) -> Option<String> {
        match self.get() {
            AssetState::Error(message) => Some(message),
            _ => None,
        }
    }

    pub fn subscribe<F: Fn(&AssetState<T>) + Send + Sync + 'static>(&self, callback: F) {
        self.inner.subscribe(callback)
    }

    pub fn inner_state(&self) -> &State<AssetState<T>> {
        &self.inner
    }
}

impl<T: Clone + Send + Sync + 'static> Clone for Suspense<T> {
    fn clone(&self) -> Self {
        Self {
            inner: self.inner.clone(),
        }
    }
}

impl<T: Clone + Send + Sync + 'static> From<T> for Suspense<T> {
    fn from(value: T) -> Self {
        Self::ready(value)
    }
}

impl<T: Clone + Send + Sync + 'static> From<Result<T, String>> for Suspense<T> {
    fn from(result: Result<T, String>) -> Self {
        match result {
            Ok(value) => Self::ready(value),
            Err(error) => Self::error(error),
        }
    }
}

#[cfg(test)]
mod phase1_test;

/// Berserker mode states for the rendering pipeline.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RenderIntensityMode {
    Normal,
    Rage,    // Red tint, slight shake
    Frenzy,  // Heavy red tint, motion blur, aggressive shake
    GodMode, // Golden aura, lightning arcs
}

/// Seer trait for AI-assisted UI components.
/// Allows components to receive "prophecies" (predictions) from an AI backend.
pub trait Seer: Send + Sync {
    /// Provide a prediction for the next user action or content.
    fn predict(&self, context: &str) -> String;
    /// Stream real-time "whispers" (transcriptions/intent).
    fn whispers(&self) -> Vec<String>;
}

#[cfg(test)]
mod vili_tests {
    use super::*;

    struct DummyRenderer;
    impl ElapsedTime for DummyRenderer {
        fn elapsed_time(&self) -> f32 {
            0.0
        }
        fn delta_time(&self) -> f32 {
            0.0
        }
    }
    impl Renderer for DummyRenderer {
        fn fill_rect(&mut self, _r: Rect, _c: [f32; 4]) {}
        fn fill_rounded_rect(&mut self, _r: Rect, _rad: f32, _c: [f32; 4]) {}
        fn fill_ellipse(&mut self, _r: Rect, _c: [f32; 4]) {}
        fn stroke_rect(&mut self, _r: Rect, _c: [f32; 4], _w: f32) {}
        fn stroke_rounded_rect(&mut self, _r: Rect, _rad: f32, _c: [f32; 4], _w: f32) {}
        fn stroke_ellipse(&mut self, _r: Rect, _c: [f32; 4], _w: f32) {}
        fn draw_line(&mut self, _x1: f32, _y1: f32, _x2: f32, _y2: f32, _c: [f32; 4], _w: f32) {}

        fn memoize(&mut self, _id: u64, _hash: u64, _r: &dyn Fn(&mut dyn Renderer)) {}
        fn draw_mesh_3d(&mut self, _mesh: &Mesh, _material: &Material3D, _transform: &Transform3D) {
        }
        fn set_camera_3d(&mut self, _camera: &Camera3D) {}
        fn push_transform_3d(&mut self, _transform: &Transform3D) {}
        fn pop_transform_3d(&mut self) {}
    }

    #[test]
    fn test_magnetic_warp() {
        let renderer = DummyRenderer;
        let anchor = Rect {
            x: 100.0,
            y: 100.0,
            width: 50.0,
            height: 50.0,
        };
        // Pointer is near the anchor (distance < 120)
        let pointer = [125.0, 50.0];
        // distance from center (125, 125) is 75.
        // force = (1.0 - 75/120) * strength
        let warp = renderer.magnetic_warp(pointer, anchor, 1.0);
        // It should pull closer to (125, 125), so Y should be > 50
        assert!(warp[1] > 50.0);

        // Out of range pointer should remain unchanged
        let far_pointer = [500.0, 500.0];
        let far_warp = renderer.magnetic_warp(far_pointer, anchor, 1.0);
        assert_eq!(far_pointer, far_warp);
    }

    #[test]
    fn test_mani_glow() {
        let renderer = DummyRenderer;
        let bounds = Rect {
            x: 0.0,
            y: 0.0,
            width: 100.0,
            height: 100.0,
        };
        let pointer_inside = [50.0, 50.0];
        let glow_max = renderer.mani_glow_intensity(pointer_inside, bounds, 120.0);
        assert_eq!(glow_max, 1.0);

        let pointer_edge = [50.0, -10.0];
        let glow_partial = renderer.mani_glow_intensity(pointer_edge, bounds, 120.0);
        assert!(glow_partial > 0.0 && glow_partial < 1.0);
    }

    #[test]
    fn test_fafnir_evolve() {
        let renderer = DummyRenderer;
        let bounds = Rect {
            x: 0.0,
            y: 0.0,
            width: 100.0,
            height: 100.0,
        };
        let pointer_inside = [50.0, 50.0];
        let scale = renderer.fafnir_evolve(pointer_inside, bounds, 1.2);
        assert_eq!(scale, 1.2); // Full scale when hovering center
    }

    #[test]
    fn test_undo_manager_basic() {
        let mut manager = UndoManager::new(3, 0.5);
        let val = std::sync::Arc::new(std::sync::Mutex::new(0));

        let v1 = val.clone();
        let v2 = val.clone();
        manager.push(
            "Add",
            move || *v1.lock().unwrap() -= 1,
            move || *v2.lock().unwrap() += 1,
        );

        assert!(manager.can_undo());
        assert!(!manager.can_redo());

        let undo = manager.undo().unwrap();
        undo();
        assert_eq!(*val.lock().unwrap(), -1);
        assert!(!manager.can_undo());
        assert!(manager.can_redo());

        let redo = manager.redo().unwrap();
        redo();
        assert_eq!(*val.lock().unwrap(), 0);
    }

    #[test]
    fn test_undo_manager_depth_limit() {
        let mut manager = UndoManager::new(2, 0.5);
        manager.push("1", || {}, || {});
        manager.push("2", || {}, || {});
        manager.push("3", || {}, || {});

        assert_eq!(manager.stack.len(), 2);
        assert_eq!(manager.position, 2);
    }

    #[test]
    fn test_undo_manager_coalescing() {
        let mut manager = UndoManager::new(10, 1.0);
        let count = std::sync::Arc::new(std::sync::Mutex::new(0));

        let c = count.clone();
        manager.push_coalesceable("Type", move || *c.lock().unwrap() -= 1, || {});

        let c = count.clone();
        manager.push_coalesceable("Type", move || *c.lock().unwrap() -= 1, || {});

        assert_eq!(manager.stack.len(), 1);

        let undo = manager.undo().unwrap();
        undo();
        assert_eq!(*count.lock().unwrap(), -2);
    }
}

#[cfg(test)]
mod error_boundary_tests {
    use super::*;

    /// A trivial view that renders successfully.
    struct SuccessView;

    impl View for SuccessView {
        type Body = Never;
        fn body(self) -> Never {
            // SAFETY: `Never` is uninhabitable -- test helper with no composable body.
            unreachable!()
        }
        fn render(&self, _renderer: &mut dyn Renderer, _rect: Rect) {
            // No-op -- renders successfully.
        }
    }

    /// A view that panics during render.
    struct PanicOnRender;

    impl View for PanicOnRender {
        type Body = Never;
        fn body(self) -> Never {
            // SAFETY: `Never` is uninhabitable -- test helper that only panics in render().
            unreachable!()
        }
        fn render(&self, _renderer: &mut dyn Renderer, _rect: Rect) {
            panic!("intentional render panic");
        }
    }

    /// A view that panics during intrinsic_size.
    struct PanicOnSize;

    impl View for PanicOnSize {
        type Body = Never;
        fn body(self) -> Never {
            // SAFETY: `Never` is uninhabitable -- test helper that only panics in intrinsic_size().
            unreachable!()
        }
        fn render(&self, _renderer: &mut dyn Renderer, _rect: Rect) {
            // Render succeeds, but size panics.
        }
        fn intrinsic_size(&self, _renderer: &mut dyn Renderer, _proposal: SizeProposal) -> Size {
            panic!("intentional size panic");
        }
    }

    /// A view that panics with a String payload.
    struct PanicWithString;

    impl View for PanicWithString {
        type Body = Never;
        fn body(self) -> Never {
            // SAFETY: `Never` is uninhabitable -- test helper that panics with a String payload.
            unreachable!()
        }
        fn render(&self, _renderer: &mut dyn Renderer, _rect: Rect) {
            panic!("{}", "custom error message".to_string());
        }
    }

    struct DummyRenderer;
    impl ElapsedTime for DummyRenderer {
        fn elapsed_time(&self) -> f32 {
            0.0
        }
        fn delta_time(&self) -> f32 {
            0.0
        }
    }
    impl Renderer for DummyRenderer {
        fn fill_rect(&mut self, _r: Rect, _c: [f32; 4]) {}
        fn fill_rounded_rect(&mut self, _r: Rect, _rad: f32, _c: [f32; 4]) {}
        fn fill_ellipse(&mut self, _r: Rect, _c: [f32; 4]) {}
        fn stroke_rect(&mut self, _r: Rect, _c: [f32; 4], _w: f32) {}
        fn stroke_rounded_rect(&mut self, _r: Rect, _rad: f32, _c: [f32; 4], _w: f32) {}
        fn stroke_ellipse(&mut self, _r: Rect, _c: [f32; 4], _w: f32) {}
        fn draw_line(&mut self, _x1: f32, _y1: f32, _x2: f32, _y2: f32, _c: [f32; 4], _w: f32) {}

        fn memoize(&mut self, _id: u64, _hash: u64, _r: &dyn Fn(&mut dyn Renderer)) {}
        fn draw_mesh_3d(&mut self, _mesh: &Mesh, _material: &Material3D, _transform: &Transform3D) {
        }
        fn set_camera_3d(&mut self, _camera: &Camera3D) {}
        fn push_transform_3d(&mut self, _transform: &Transform3D) {}
        fn pop_transform_3d(&mut self) {}
    }

    const TEST_RECT: Rect = Rect {
        x: 0.0,
        y: 0.0,
        width: 200.0,
        height: 100.0,
    };

    #[test]
    fn error_boundary_renders_child_on_success() {
        let boundary = ErrorBoundary::new(SuccessView);
        let mut renderer = DummyRenderer;

        boundary.render(&mut renderer, TEST_RECT);

        assert!(
            !boundary.has_error(),
            "should not have error after successful render"
        );
        assert!(
            boundary.last_error().is_none(),
            "should have no error message"
        );
    }

    #[test]
    fn error_boundary_catches_render_panic() {
        let boundary = ErrorBoundary::new(PanicOnRender);
        let mut renderer = DummyRenderer;

        // This must NOT panic -- the boundary catches it.
        boundary.render(&mut renderer, TEST_RECT);

        assert!(
            boundary.has_error(),
            "should have error after catching panic"
        );
        let err = boundary.last_error().expect("should have error message");
        assert!(
            err.contains("intentional render panic"),
            "error message should contain panic message, got: {err}"
        );
    }

    #[test]
    fn error_boundary_catches_size_panic() {
        let boundary = ErrorBoundary::new(PanicOnSize);
        let mut renderer = DummyRenderer;
        let proposal = layout::SizeProposal {
            width: Some(100.0),
            height: Some(50.0),
        };

        let size = boundary.intrinsic_size(&mut renderer, proposal);

        assert!(
            boundary.has_error(),
            "should have error after catching size panic"
        );
        assert_eq!(size, Size::ZERO, "fallback size should be zero");
    }

    #[test]
    fn error_boundary_catches_string_panic() {
        let boundary = ErrorBoundary::new(PanicWithString);
        let mut renderer = DummyRenderer;

        boundary.render(&mut renderer, TEST_RECT);

        assert!(boundary.has_error());
        let err = boundary.last_error().expect("should have error message");
        assert!(
            err.contains("custom error message"),
            "should capture String panic payload, got: {err}"
        );
    }

    #[test]
    fn error_boundary_clear_error_resets_state() {
        let boundary = ErrorBoundary::new(PanicOnRender);
        let mut renderer = DummyRenderer;

        boundary.render(&mut renderer, TEST_RECT);
        assert!(boundary.has_error());

        boundary.clear_error();
        assert!(
            !boundary.has_error(),
            "should be clear after clear_error()"
        );
        assert!(
            boundary.last_error().is_none(),
            "error message should be cleared"
        );
    }

    #[test]
    fn error_boundary_fallback_color_is_configurable() {
        let boundary = ErrorBoundary::new(SuccessView)
            .fallback_color([0.0, 0.0, 1.0, 1.0])
            .fallback_label("custom label");

        assert_eq!(boundary.fallback_color, [0.0, 0.0, 1.0, 1.0]);
        assert_eq!(
            boundary.fallback_label.as_deref(),
            Some("custom label")
        );
    }

    #[test]
    fn error_boundary_flex_weight_delegates_to_child() {
        let boundary = ErrorBoundary::new(SuccessView);
        assert_eq!(boundary.flex_weight(), 0.0, "should delegate to child (default 0.0)");
    }

    #[test]
    fn error_boundary_body_delegates_to_child() {
        // body() must be pure and delegate directly.
        let _boundary = ErrorBoundary::new(SuccessView);
        // Calling body() should not panic and should return Never (unreachable).
        // We test this indirectly -- if it compiles and the Never type is correct,
        // the body() call would diverge. We just verify the type compiles.
        let _boundary_type = std::any::type_name::<ErrorBoundary<SuccessView>>();
    }

    /// Renderer that tracks stack-pushing operations so tests can verify
    /// ErrorBoundary restores renderer state on panic.
    struct TrackingRenderer {
        clip_depth: u32,
        opacity_depth: u32,
        shadow_depth: u32,
    }

    impl TrackingRenderer {
        fn new() -> Self {
            Self {
                clip_depth: 0,
                opacity_depth: 0,
                shadow_depth: 0,
            }
        }
    }

    impl Renderer for TrackingRenderer {
        fn fill_rect(&mut self, _rect: Rect, _color: [f32; 4]) {}
        fn fill_rounded_rect(&mut self, _rect: Rect, _radius: f32, _color: [f32; 4]) {}
        fn fill_ellipse(&mut self, _rect: Rect, _color: [f32; 4]) {}
        fn stroke_rect(&mut self, _rect: Rect, _color: [f32; 4], _w: f32) {}
        fn stroke_rounded_rect(
            &mut self,
            _rect: Rect,
            _radius: f32,
            _color: [f32; 4],
            _stroke_width: f32,
        ) {
        }
        fn stroke_ellipse(&mut self, _rect: Rect, _color: [f32; 4], _stroke_width: f32) {}
        fn draw_line(&mut self, _x1: f32, _y1: f32, _x2: f32, _y2: f32, _c: [f32; 4], _w: f32) {}

        fn push_clip_rect(&mut self, _rect: Rect) {
            self.clip_depth += 1;
        }
        fn pop_clip_rect(&mut self) {
            self.clip_depth = self.clip_depth.saturating_sub(1);
        }
        fn push_opacity(&mut self, _opacity: f32) {
            self.opacity_depth += 1;
        }
        fn pop_opacity(&mut self) {
            self.opacity_depth = self.opacity_depth.saturating_sub(1);
        }
        fn push_shadow(&mut self, _r: f32, _c: [f32; 4], _o: [f32; 2]) {
            self.shadow_depth += 1;
        }
        fn pop_shadow(&mut self) {
            self.shadow_depth = self.shadow_depth.saturating_sub(1);
        }
        fn memoize(&mut self, _id: u64, _hash: u64, _r: &dyn Fn(&mut dyn Renderer)) {}
        fn snapshot_render_state(&self) -> RenderStateSnapshot {
            // Note: cannot mutate self in &self method; we record that it was
            // called via a different channel (the test counts calls on a Cell).
            RenderStateSnapshot {
                clip_depth: self.clip_depth,
                opacity_depth: self.opacity_depth,
                slice_depth: 0,
                shadow_depth: self.shadow_depth,
                transform_depth: 0,
                vnode_depth: 0,
            }
        }
        fn restore_render_state(&mut self, snap: RenderStateSnapshot) {
            self.clip_depth = snap.clip_depth;
            self.opacity_depth = snap.opacity_depth;
            self.shadow_depth = snap.shadow_depth;
        }
        fn draw_mesh_3d(&mut self, _mesh: &Mesh, _material: &Material3D, _transform: &Transform3D) {}
        fn set_camera_3d(&mut self, _camera: &Camera3D) {}
        fn push_transform_3d(&mut self, _transform: &Transform3D) {}
        fn pop_transform_3d(&mut self) {}
    }

    impl ElapsedTime for TrackingRenderer {
        fn elapsed_time(&self) -> f32 {
            0.0
        }
        fn delta_time(&self) -> f32 {
            0.0
        }
    }

    /// View that pushes clip/opacity/shadow stacks and then panics.
    /// After ErrorBoundary restores state, the renderer should have no leftover
    /// pushed items.
    struct StackPushingPanicView;

    impl View for StackPushingPanicView {
        type Body = Never;
        fn body(self) -> Never {
            unreachable!()
        }
        fn render(&self, renderer: &mut dyn Renderer, _rect: Rect) {
            renderer.push_clip_rect(Rect::new(0.0, 0.0, 50.0, 50.0));
            renderer.push_opacity(0.5);
            renderer.push_shadow(2.0, [0.0, 0.0, 0.0, 0.5], [0.0, 0.0]);
            panic!("intentional stack-pushing panic");
        }
    }

    #[test]
    fn error_boundary_restores_renderer_state_on_panic() {
        // Regression test for P0-5: ErrorBoundary must restore renderer
        // stack state after a mid-render panic so siblings drawn afterward
        // don't inherit leaked clip/opacity/transform/etc. state.
        let boundary = ErrorBoundary::new(StackPushingPanicView);
        let mut renderer = TrackingRenderer::new();

        // Pre-snapshot: empty stacks.
        let snap_before = renderer.snapshot_render_state();
        assert_eq!(snap_before.clip_depth, 0);
        assert_eq!(snap_before.opacity_depth, 0);
        assert_eq!(snap_before.shadow_depth, 0);

        // Render -- child panics, boundary must catch and restore.
        boundary.render(&mut renderer, TEST_RECT);

        // Verify the panic was caught and state was restored.
        assert!(boundary.has_error(), "should have caught the panic");
        let snap_after = renderer.snapshot_render_state();
        assert_eq!(
            snap_after.clip_depth, 0,
            "clip stack should be restored to empty after panic"
        );
        assert_eq!(
            snap_after.opacity_depth, 0,
            "opacity stack should be restored to empty after panic"
        );
        assert_eq!(
            snap_after.shadow_depth, 0,
            "shadow stack should be restored to empty after panic"
        );
    }

    #[test]
    fn render_state_snapshot_default_is_zeroed() {
        // The default snapshot must be all-zero so backends without
        // stack state can use it as a sentinel.
        let snap = RenderStateSnapshot::default();
        assert_eq!(snap.clip_depth, 0);
        assert_eq!(snap.opacity_depth, 0);
        assert_eq!(snap.slice_depth, 0);
        assert_eq!(snap.shadow_depth, 0);
        assert_eq!(snap.transform_depth, 0);
        assert_eq!(snap.vnode_depth, 0);
    }

    #[test]
    fn render_state_snapshot_round_trip() {
        let snap = RenderStateSnapshot {
            clip_depth: 3,
            opacity_depth: 2,
            slice_depth: 1,
            shadow_depth: 0,
            transform_depth: 4,
            vnode_depth: 5,
        };
        let copied = snap;
        assert_eq!(copied, snap);
    }
}

// =============================================================================
// THEME CONTEXT -- Thread-local theme access for components
// =============================================================================
//
// Components call `use_theme()` to get the current SemanticColors.
// The native renderer sets this via `set_current_theme()` before each frame.
// Falls back to dark theme defaults if no theme has been set.
//
// We store SemanticColors directly (not the full Theme) to avoid depending
// on cvkg-themes from cvkg-core. The colors are cloned into thread-local storage.

use std::cell::RefCell;

thread_local! {
    /// Thread-local theme context for the current frame.
    static THEME_CONTEXT: RefCell<Option<ThemeContext>> = const { RefCell::new(None) };
}

/// Theme context available to components during render.
/// Includes both semantic colors and visual effect flags.
#[derive(Debug, Clone)]
pub struct ThemeContext {
    /// Semantic colors for the current theme.
    pub colors: color::SemanticColors,
    /// If true, components may use glassmorphic effects (frosted glass, blur).
    /// If false, components should render with solid backgrounds.
    pub glassmorphism_enabled: bool,
}

impl ThemeContext {
    /// Create a dark theme context with glassmorphism enabled.
    pub fn dark() -> Self {
        Self {
            colors: color::SemanticColors::dark(),
            glassmorphism_enabled: true,
        }
    }

    /// Create a light theme context with glassmorphism disabled.
    pub fn light() -> Self {
        Self {
            colors: color::SemanticColors::light(),
            glassmorphism_enabled: false,
        }
    }
}

/// Set the current theme context for this thread.
/// Called by the native renderer before each frame.
pub fn set_current_theme(colors: color::SemanticColors) {
    THEME_CONTEXT.with(|cell| {
        let is_light = (colors.background.r + colors.background.g + colors.background.b) / 3.0 > 0.5;
        let glassmorphism = !is_light; // light themes default to no glassmorphism
        *cell.borrow_mut() = Some(ThemeContext { colors, glassmorphism_enabled: glassmorphism });
    });
}

/// Set the full theme context (including glassmorphism flag).
pub fn set_theme_context(ctx: ThemeContext) {
    THEME_CONTEXT.with(|cell| {
        *cell.borrow_mut() = Some(ctx);
    });
}

/// Clear the current theme. Called after each frame.
pub fn clear_current_theme() {
    THEME_CONTEXT.with(|cell| {
        *cell.borrow_mut() = None;
    });
}

/// Access the current semantic colors from within a component's `render()` method.
///
/// Returns the colors set by the most recent `set_current_theme()` call.
/// Falls back to dark theme defaults if no theme has been set.
///
/// # Example
/// ```no_run
/// use cvkg_core::{use_theme, Renderer, Rect};
///
/// fn render_button(renderer: &mut dyn Renderer, rect: Rect) {
///     let colors = use_theme();
///     renderer.fill_rounded_rect(rect, 8.0, [colors.accent.r, colors.accent.g, colors.accent.b, colors.accent.a]);
/// }
/// ```
pub fn use_theme() -> color::SemanticColors {
    THEME_CONTEXT.with(|cell| {
        cell.borrow()
            .clone()
            .map(|ctx| ctx.colors)
            .unwrap_or_else(color::SemanticColors::dark)
    })
}

/// Access the full theme context from within a component's `render()` method.
///
/// Returns the current `ThemeContext` including both colors and effect flags.
/// Falls back to dark theme defaults if no theme has been set.
pub fn use_theme_context() -> ThemeContext {
    THEME_CONTEXT.with(|cell| {
        cell.borrow()
            .clone()
            .unwrap_or_else(ThemeContext::dark)
    })
}

/// Returns true if glassmorphic effects are enabled in the current theme.
/// Components should check this before calling `renderer.bifrost()`.
pub fn glassmorphism_enabled() -> bool {
    THEME_CONTEXT.with(|cell| {
        cell.borrow()
            .as_ref()
            .map(|ctx| ctx.glassmorphism_enabled)
            .unwrap_or(true) // default: glassmorphism on (dark theme)
    })
}

// =============================================================================
// COLOR MODULE -- Standalone semantic colors type
// =============================================================================
//
// This module provides `SemanticColors`, a self-contained color palette that
// components can use without depending on `cvkg-themes`. The `use_theme()`
// function returns the current `SemanticColors` from thread-local storage.

pub mod color {
    use super::Color;

    /// A complete set of semantic colors for UI components.
    ///
    /// Each color serves a specific role in the UI. Components should reference
    /// these semantic roles rather than hardcoding RGBA values.
    ///
    /// # Example
    /// ```no_run
    /// use cvkg_core::{use_theme, Renderer, Rect};
    ///
    /// fn render_button(renderer: &mut dyn Renderer, rect: Rect) {
    ///     let colors = use_theme();
    ///     // Use accent color for the button background
    ///     renderer.fill_rounded_rect(rect, 8.0,
    ///         [colors.accent.r, colors.accent.g, colors.accent.b, colors.accent.a]);
    /// }
    /// ```
    #[derive(Debug, Clone)]
    pub struct SemanticColors {
        /// Primary brand color -- used for key interactive elements.
        pub primary: Color,
        /// Secondary color -- used for less prominent interactive elements.
        pub secondary: Color,
        /// Accent color -- used for highlights, focus rings, CTAs.
        pub accent: Color,
        /// Page/window background color.
        pub background: Color,
        /// Surface color -- used for cards, panels, sheets.
        pub surface: Color,
        /// Error color -- used for destructive actions, error messages.
        pub error: Color,
        /// Warning color -- used for caution indicators.
        pub warning: Color,
        /// Success color -- used for positive feedback.
        pub success: Color,
        /// Primary text color.
        pub text: Color,
        /// Dimmed/disabled text color.
        pub text_dim: Color,
    }

    impl SemanticColors {
        /// Dark theme semantic colors (default fallback).
        pub fn dark() -> Self {
            Self {
                primary: Color::new(1.0, 0.84, 0.0, 1.0),      // Viking Gold
                secondary: Color::new(1.0, 0.0, 1.0, 1.0),     // Magenta Liquid
                accent: Color::new(1.0, 0.0, 0.4, 1.0),        // Crimson Flash
                background: Color::new(0.02, 0.02, 0.05, 1.0), // Deep Void
                surface: Color::new(0.05, 0.05, 0.07, 1.0),    // Tactical Obsidian
                error: Color::new(1.0, 0.2, 0.2, 1.0),         // Red
                warning: Color::new(1.0, 0.8, 0.0, 1.0),       // Yellow
                success: Color::new(0.0, 1.0, 0.5, 1.0),       // Green
                text: Color::new(0.95, 0.95, 1.0, 1.0),        // Near-white
                text_dim: Color::new(0.6, 0.6, 0.7, 1.0),      // Gray
            }
        }

        /// Light theme semantic colors.
        pub fn light() -> Self {
            Self {
                primary: Color::new(0.35, 0.30, 0.70, 1.0),
                secondary: Color::new(0.30, 0.50, 0.30, 1.0),
                accent: Color::new(0.30, 0.35, 0.75, 1.0),
                background: Color::new(0.97, 0.97, 0.98, 1.0),
                surface: Color::new(0.93, 0.93, 0.95, 1.0),
                error: Color::new(0.75, 0.15, 0.15, 1.0),
                warning: Color::new(0.80, 0.60, 0.0, 1.0),
                success: Color::new(0.15, 0.65, 0.30, 1.0),
                text: Color::new(0.08, 0.08, 0.10, 1.0),
                text_dim: Color::new(0.40, 0.40, 0.45, 1.0),
            }
        }

        /// Convert the accent color semantic color into interactive state colors.
        ///
        /// This provides hover/active/focus/disabled variants derived from the
        /// accent color, matching the pattern that `cvkg-themes::StateColors` uses.
        pub fn accent_states(&self) -> InteractiveColorStates {
            InteractiveColorStates::from_color(self.accent)
        }

        /// Convert the primary color into interactive state colors.
        pub fn primary_states(&self) -> InteractiveColorStates {
            InteractiveColorStates::from_color(self.primary)
        }

        /// Convert the error color into interactive state colors.
        pub fn error_states(&self) -> InteractiveColorStates {
            InteractiveColorStates::from_color(self.error)
        }

        /// Convert the success color into interactive state colors.
        pub fn success_states(&self) -> InteractiveColorStates {
            InteractiveColorStates::from_color(self.success)
        }
    }

    /// Interactive state colors derived from a single base color.
    ///
    /// Provides hover/active/focus/disabled variants for any color,
    /// derived via simple lightness adjustments in sRGB space.
    #[derive(Debug, Clone)]
    pub struct InteractiveColorStates {
        pub default: Color,
        pub hover: Color,
        pub active: Color,
        pub focus: Color,
        pub disabled: Color,
        pub focus_ring: Color,
    }

    impl InteractiveColorStates {
        /// Derive interactive state colors from a base sRGB color.
        ///
        /// Uses simple lightness adjustments:
        /// - Hover: +15% lightness
        /// - Active: -15% lightness
        /// - Focus: same as default
        /// - Disabled: 40% opacity
        /// - Focus ring: base color at 70% opacity
        pub fn from_color(base: Color) -> Self {
            Self {
                default: base,
                hover: base.lighten(0.15),
                active: base.darken(0.15),
                focus: base,
                disabled: Color::new(base.r, base.g, base.b, base.a * 0.4),
                focus_ring: Color::new(base.r, base.g, base.b, base.a * 0.7),
            }
        }

        /// Get the color for a specific interactive state.
        pub fn color_for(&self, state: InteractiveState) -> Color {
            match state {
                InteractiveState::Default => self.default,
                InteractiveState::Hover => self.hover,
                InteractiveState::Active => self.active,
                InteractiveState::Focus => self.focus,
                InteractiveState::Disabled => self.disabled,
            }
        }
    }

    /// Interactive state for a component.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
    pub enum InteractiveState {
        Default,
        Hover,
        Active,
        Focus,
        Disabled,
    }
}

// =============================================================================
// USE_STATE HOOK -- Local component state with automatic re-render
// =============================================================================
//
// Components call `use_state(id, initial)` to get a `(getter, setter)` pair.
// The setter updates the global system state and triggers a re-render.
//
// This is the minimal state primitive needed for interactive components.
// For complex state, use the global `AppState` directly.

/// Local state hook for components.
///
/// Returns a `(getter, setter)` pair:
/// - `getter()` returns the current value of type `T`
/// - `setter(value)` updates the value and triggers a re-render
///
/// The `id` must be unique per component instance (use a hash of the
/// component's label or a generated UUID).
pub fn use_state<T: Clone + Send + Sync + 'static>(
    id: u64,
    initial: T,
) -> (impl Fn() -> T, impl Fn(T)) {
    // Initialize the state if not already present
    let already_exists = load_system_state().get_component_state::<T>(id).is_some();
    if !already_exists {
        update_system_state(|s| {
            let mut ns = s.clone();
            ns.set_component_state(id, initial.clone());
            ns
        });
    }

    let getter = move || -> T {
        load_system_state()
            .get_component_state::<T>(id)
            .map(|arc_lock| {
                arc_lock
                    .read()
                    .ok()
                    .map(|guard| (*guard).clone())
                    .unwrap_or_else(|| initial.clone())
            })
            .unwrap_or_else(|| initial.clone())
    };

    let setter = {
        move |value| {
            update_system_state(|s| {
                let mut ns = s.clone();
                ns.set_component_state(id, value);
                ns
            });
        }
    };

    (getter, setter)
}

/// Generate a stable hash ID from a string key.
///
/// Use this to create unique IDs for `use_state` based on component labels
/// or other stable identifiers.
///
/// # Example
/// ```no_run
/// use cvkg_core::{use_state, use_state_hash};
/// let id = use_state_hash("my-checkbox");
/// let (value, set_value) = use_state(id, false);
/// ```
pub fn use_state_hash(key: &str) -> u64 {
    use std::hash::{Hash, Hasher};
    let mut s = std::collections::hash_map::DefaultHasher::new();
    key.hash(&mut s);
    s.finish()
}

// =============================================================================
// ACCESSIBILITY PREFERENCES -- System accessibility settings
// =============================================================================
//
// Components and the renderer query these to adapt behavior:
// - Reduce Motion: disable non-essential animations
// - Reduce Transparency: replace glass materials with opaque surfaces
// - Increase Contrast: make borders visible, minimum alpha 0.5

thread_local! {
    /// Thread-local accessibility preferences.
    /// Defaults to no restrictions (all false).
    static ACCESSIBILITY_PREFS: std::cell::RefCell<AccessibilityPreferences> =
        std::cell::RefCell::new(AccessibilityPreferences::default());
}

/// System accessibility preferences that components and the renderer must honor.
///
/// These map to macOS System Settings > Accessibility:
/// - `reduce_motion`: Disables non-essential animations (spring, bounce, etc.)
/// - `reduce_transparency`: Replaces glass/transparent materials with opaque surfaces
/// - `increase_contrast`: Makes all borders visible, minimum alpha 0.5 for all elements
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct AccessibilityPreferences {
    /// User prefers reduced motion. Animations should be instant or very short.
    pub reduce_motion: bool,
    /// User prefers reduced transparency. Glass materials should be opaque.
    pub reduce_transparency: bool,
    /// User prefers increased contrast. Borders must be visible, min alpha 0.5.
    pub increase_contrast: bool,
}

impl AccessibilityPreferences {
    /// Detect system accessibility preferences (macOS).
    ///
    /// On non-macOS platforms, returns defaults (all false).
    /// In a production implementation, this would query the OS APIs.
    pub fn detect_from_system() -> Self {
        #[cfg(target_os = "macos")]
        {
            // Try to read macOS accessibility preferences via defaults command
            let reduce_motion = std::process::Command::new("defaults")
                .args(["read", "-g", "com.apple.universalaccess", "reduceMotion"])
                .output()
                .ok()
                .and_then(|o| String::from_utf8(o.stdout).ok())
                .map(|s| s.trim() == "1")
                .unwrap_or(false);

            let reduce_transparency = std::process::Command::new("defaults")
                .args([
                    "read",
                    "-g",
                    "com.apple.universalaccess",
                    "reduceTransparency",
                ])
                .output()
                .ok()
                .and_then(|o| String::from_utf8(o.stdout).ok())
                .map(|s| s.trim() == "1")
                .unwrap_or(false);

            let increase_contrast = std::process::Command::new("defaults")
                .args([
                    "read",
                    "-g",
                    "com.apple.universalaccess",
                    "increaseContrast",
                ])
                .output()
                .ok()
                .and_then(|o| String::from_utf8(o.stdout).ok())
                .map(|s| s.trim() == "1")
                .unwrap_or(false);

            Self {
                reduce_motion,
                reduce_transparency,
                increase_contrast,
            }
        }

        #[cfg(target_os = "linux")]
        {
            // Reduced motion: check GTK_A11Y env var or GNOME gsettings
            let reduce_motion = std::env::var("GTK_A11Y")
                .map(|v| v.to_lowercase().contains("reduce-motion"))
                .unwrap_or(false)
                || {
                    // Try gsettings for GNOME desktop animation preference
                    std::process::Command::new("gsettings")
                        .args([
                            "get",
                            "org.gnome.desktop.interface",
                            "enable-animations",
                        ])
                        .output()
                        .ok()
                        .and_then(|o| String::from_utf8(o.stdout).ok())
                        .map(|s| s.trim() == "'false'" || s.trim() == "false")
                        .unwrap_or(false)
                };

            // Reduced transparency is not widely supported on Linux desktops
            let reduce_transparency = false;

            // Increased contrast: check GTK_THEME for high-contrast variants
            let increase_contrast = std::env::var("GTK_THEME")
                .map(|v| v.to_lowercase().contains("highcontrast"))
                .unwrap_or(false);

            Self {
                reduce_motion,
                reduce_transparency,
                increase_contrast,
            }
        }

        #[cfg(target_os = "windows")]
        {
            use std::process::Command;

            // Helper: run `reg query` and return the value string if found
            fn reg_query(key: &str, value_name: &str) -> Option<String> {
                Command::new("reg")
                    .args(["query", key, "/v", value_name])
                    .output()
                    .ok()
                    .and_then(|o| {
                        if o.status.success() {
                            String::from_utf8(o.stdout).ok()
                        } else {
                            None
                        }
                    })
                    .and_then(|s| {
                        // Output format: "    ValueName    REG_SZ    <value>"
                        // or REG_DWORD lines; parse the last token on the last non-empty line
                        s.lines()
                            .last()?
                            .split_whitespace()
                            .last()
                            .map(String::from)
                    })
            }

            // Reduced motion: EffectsAnimationEfficiency = 1 means reduced
            let reduce_motion = reg_query(
                "HKCU\\Control Panel\\Accessibility\\EffectsAnimationEfficiency",
                "EffectsAnimationEfficiency",
            )
            .map(|v| v == "1")
            .unwrap_or(false);

            // Reduced transparency: EnableTransparency = 0 means reduced
            let reduce_transparency = reg_query(
                "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize",
                "EnableTransparency",
            )
            .map(|v| v == "0")
            .unwrap_or(false);

            // Increased contrast: HighContrast = 1 means enabled
            let increase_contrast = reg_query(
                "HKCU\\Control Panel\\Accessibility\\HighContrast",
                "HighContrast",
            )
            .map(|v| v == "1")
            .unwrap_or(false);

            Self {
                reduce_motion,
                reduce_transparency,
                increase_contrast,
            }
        }

        #[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
        {
            Self::default()
        }
    }

    /// Apply a minimum alpha constraint for increase-contrast mode.
    pub fn min_alpha(&self, requested: f32) -> f32 {
        if self.increase_contrast {
            requested.max(0.5)
        } else {
            requested
        }
    }

    /// Returns true if glass effects should be replaced with opaque surfaces.
    pub fn should_disable_glass(&self) -> bool {
        self.reduce_transparency
    }

    /// Returns true if animations should be instant.
    pub fn should_reduce_motion(&self) -> bool {
        self.reduce_motion
    }

    /// Returns true if borders should be made visible.
    pub fn should_increase_contrast(&self) -> bool {
        self.increase_contrast
    }
}

/// Get the current accessibility preferences for this thread.
pub fn accessibility_preferences() -> AccessibilityPreferences {
    ACCESSIBILITY_PREFS.with(|p| *p.borrow())
}

/// Set the accessibility preferences for this thread.
///
/// The native renderer should call this on startup and when system
/// preferences change (via `detect_from_system()`).
pub fn set_accessibility_preferences(prefs: AccessibilityPreferences) {
    ACCESSIBILITY_PREFS.with(|p| {
        *p.borrow_mut() = prefs;
    });
}

// =============================================================================
// CLIPBOARD -- System clipboard access
// =============================================================================

/// Trait for clipboard operations.
///
/// The native renderer implements this via `arboard` on desktop platforms.
/// On WASM, it uses the browser Clipboard API.
pub trait ClipboardProvider: Send + Sync {
    /// Read text from the system clipboard.
    fn read_text(&self) -> Option<String>;
    /// Write text to the system clipboard.
    fn write_text(&self, text: &str);
}

/// Default clipboard implementation using `arboard`.
/// Note: This is only available when the `arboard` feature is enabled.
/// The renderer provides the concrete implementation.
#[cfg(all(not(target_arch = "wasm32"), target_os = "macos"))]
pub struct SystemClipboard;

#[cfg(all(not(target_arch = "wasm32"), target_os = "macos"))]
impl ClipboardProvider for SystemClipboard {
    fn read_text(&self) -> Option<String> {
        use std::process::Command;
        // Fallback: try pbpaste on macOS
        Command::new("pbpaste")
            .output()
            .ok()
            .and_then(|o| String::from_utf8(o.stdout).ok())
    }

    fn write_text(&self, text: &str) {
        use std::process::Command;
        // Fallback: try pbcopy on macOS
        if let Ok(mut child) = Command::new("pbcopy")
            .stdin(std::process::Stdio::piped())
            .spawn()
        {
            if let Some(stdin) = child.stdin.as_mut() {
                use std::io::Write;
                let _ = stdin.write_all(text.as_bytes());
            }
            let _ = child.wait();
        }
    }
}

// =============================================================================
// TEXT INPUT -- Direction enum for cursor movement
// =============================================================================

/// Direction for cursor movement in text input.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextDirection {
    Forward,
    Backward,
    Up,
    Down,
    LineStart,
    LineEnd,
    WordForward,
    WordBackward,
}

/// Text input state managed by the renderer.
///
/// Components don't store this directly -- the renderer maintains it
/// and components query/modify it through the Renderer trait methods.
#[derive(Debug, Clone, Default)]
pub struct TextInputState {
    /// The full text content.
    pub text: String,
    /// Cursor position as byte offset into the text.
    pub cursor_pos: usize,
    /// Selection anchor. If Some, the selection is from anchor to cursor.
    /// If None, there is no selection.
    pub selection_anchor: Option<usize>,
    /// Whether the input is focused (shows cursor, accepts keyboard).
    pub focused: bool,
    /// Whether the caret is currently visible (for blinking).
    pub caret_visible: bool,
    /// Last edit timestamp for undo coalescing.
    pub last_edit_time: f32,
}

impl TextInputState {
    /// Create a new TextInputState with the given initial text.
    pub fn new(text: impl Into<String>) -> Self {
        let text = text.into();
        let cursor_pos = text.len();
        Self {
            text,
            cursor_pos,
            selection_anchor: None,
            focused: false,
            caret_visible: true,
            last_edit_time: 0.0,
        }
    }

    /// Get the selection range as (start, end) byte offsets.
    /// Returns None if there is no selection.
    pub fn selection_range(&self) -> Option<(usize, usize)> {
        self.selection_anchor.map(|anchor| {
            if anchor <= self.cursor_pos {
                (anchor, self.cursor_pos)
            } else {
                (self.cursor_pos, anchor)
            }
        })
    }

    /// Get the selected text, or empty string if no selection.
    pub fn selected_text(&self) -> String {
        self.selection_range()
            .map(|(start, end)| self.text[start..end].to_string())
            .unwrap_or_default()
    }

    /// Insert text at the current cursor position, replacing any selection.
    pub fn insert(&mut self, new_text: &str) {
        if let Some((start, end)) = self.selection_range() {
            self.text.replace_range(start..end, new_text);
            self.cursor_pos = start + new_text.len();
        } else {
            self.text.insert_str(self.cursor_pos, new_text);
            self.cursor_pos += new_text.len();
        }
        self.selection_anchor = None;
    }

    /// Delete characters. If there's a selection, delete it.
    /// Otherwise delete `count` characters backward (backspace) or forward (delete).
    pub fn delete(&mut self, backward: bool, count: usize) -> String {
        if let Some((start, end)) = self.selection_range() {
            let deleted = self.text[start..end].to_string();
            self.text.replace_range(start..end, "");
            self.cursor_pos = start;
            self.selection_anchor = None;
            return deleted;
        }

        if backward && self.cursor_pos > 0 {
            let start = self.cursor_pos.saturating_sub(count);
            let deleted = self.text[start..self.cursor_pos].to_string();
            self.text.replace_range(start..self.cursor_pos, "");
            self.cursor_pos = start;
            deleted
        } else if !backward && self.cursor_pos < self.text.len() {
            let end = (self.cursor_pos + count).min(self.text.len());
            let deleted = self.text[self.cursor_pos..end].to_string();
            self.text.replace_range(self.cursor_pos..end, "");
            deleted
        } else {
            String::new()
        }
    }

    /// Move the cursor in the given direction.
    pub fn move_cursor(&mut self, direction: TextDirection, extend_selection: bool) {
        if !extend_selection {
            self.selection_anchor = None;
        } else if self.selection_anchor.is_none() {
            self.selection_anchor = Some(self.cursor_pos);
        }

        match direction {
            TextDirection::Forward if self.cursor_pos < self.text.len() => {
                // Move to next character boundary (UTF-8 safe)
                let next = self.text[self.cursor_pos..]
                    .char_indices()
                    .nth(1)
                    .map(|(i, _)| self.cursor_pos + i)
                    .unwrap_or(self.text.len());
                self.cursor_pos = next;
            }
            TextDirection::Backward if self.cursor_pos > 0 => {
                let prev = self.text[..self.cursor_pos]
                    .char_indices()
                    .next_back()
                    .map(|(i, _)| i)
                    .unwrap_or(0);
                self.cursor_pos = prev;
            }
            TextDirection::LineStart => {
                self.cursor_pos = 0;
            }
            TextDirection::LineEnd => {
                self.cursor_pos = self.text.len();
            }
            TextDirection::WordForward => {
                // Find next word boundary
                let rest = &self.text[self.cursor_pos..];
                // Skip current word chars
                let after_word = rest
                    .char_indices()
                    .find(|(_, c)| !c.is_alphanumeric())
                    .map(|(i, _)| i)
                    .unwrap_or(rest.len());
                // Skip whitespace
                let after_space = rest[after_word..]
                    .char_indices()
                    .find(|(_, c)| !c.is_whitespace())
                    .map(|(i, _)| after_word + i)
                    .unwrap_or(rest.len());
                self.cursor_pos = (self.cursor_pos + after_space).min(self.text.len());
            }
            TextDirection::WordBackward => {
                let before = &self.text[..self.cursor_pos];
                // Skip whitespace going backward
                let before_word = before
                    .char_indices()
                    .rev()
                    .find(|(_, c)| !c.is_whitespace())
                    .map(|(i, _)| i)
                    .unwrap_or(0);
                // Skip word chars going backward
                let word_start = before[..before_word]
                    .char_indices()
                    .rev()
                    .find(|(_, c)| !c.is_alphanumeric())
                    .map(|(i, _)| i)
                    .unwrap_or(0);
                self.cursor_pos = word_start;
            }
            _ => {} // Up/Down handled by multi-line components
        }

        if !extend_selection {
            self.selection_anchor = None;
        }
    }

    /// Select all text.
    pub fn select_all(&mut self) {
        self.cursor_pos = self.text.len();
        self.selection_anchor = Some(0);
    }

    /// Get the byte offset of the cursor.
    pub fn cursor_byte_pos(&self) -> usize {
        self.cursor_pos
    }
}

/// Action details for interactive buttons inside a notification.
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct NotificationAction {
    /// Unique identifier of the action.
    pub id: String,
    /// The text label to display on the action button.
    pub title: String,
    /// Indicates whether the action performs a destructive task (e.g. Delete).
    pub is_destructive: bool,
}

/// Priority tier of a notification.
#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
pub enum NotificationPriority {
    /// Placed silently into the notification center without visual alerts.
    Passive,
    /// Triggers a visual alert (toast) but does not interrupt focus.
    #[default]
    Active,
    /// Important alert that bypasses standard DND/Focus bounds.
    TimeSensitive,
}

/// A structured notification representation.
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
pub struct Notification {
    /// Unique identifier for this notification.
    pub id: String,
    /// App or source identifier spawning this notification.
    pub app_name: Option<String>,
    /// The bold heading/title text.
    pub title: String,
    /// The detailed descriptive body text.
    pub body: String,
    /// Optional URI or path to an icon asset.
    pub icon: Option<String>,
    /// Optional sound identifier to play when posting.
    pub sound: Option<String>,
    /// Interactive actions available on this notification.
    pub actions: Vec<NotificationAction>,
    /// Timer duration in seconds after which the toast auto-dismisses.
    pub timeout: Option<f32>,
    /// Priority level for delivery logic.
    pub priority: NotificationPriority,
    /// Time (in seconds since renderer startup) when this notification was posted.
    pub timestamp: f32,
    /// Whether the notification has been dismissed/read.
    pub dismissed: bool,
}

/// Error type indicating a failure in generating or posting a notification.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq, thiserror::Error)]
pub enum NotificationError {
    /// Permissions denied.
    #[error("Notification permission denied")]
    PermissionDenied,
    /// Failed to post the notification.
    #[error("Failed to post notification")]
    PostFailed,
}

/// State of notification permissions.
#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
pub enum NotificationPermission {
    /// Explicitly allowed.
    Granted,
    /// Explicitly blocked.
    Denied,
    /// Prompt has not been shown or decided yet.
    #[default]
    NotDetermined,
}

/// Core interface for routing and dispatching notification events.
pub trait NotificationHandler: Send + Sync {
    /// Posts a new notification.
    fn show(&self, notification: Notification) -> Result<(), NotificationError>;
    /// Dismisses a notification by ID.
    fn dismiss(&self, id: &str) -> Result<(), NotificationError>;
    /// Requests delivery permission.
    fn request_permission(&self) -> NotificationPermission;
}

static NEXT_NOTIFICATION_ID: std::sync::atomic::AtomicUsize =
    std::sync::atomic::AtomicUsize::new(1);

/// Default in-app notification handler that writes state to AppState.
#[derive(Clone, Copy, Debug, Default)]
pub struct DefaultNotificationHandler;

impl NotificationHandler for DefaultNotificationHandler {
    /// Save the notification to the global system state (history) and auto-assign an ID if empty.
    fn show(&self, notification: Notification) -> Result<(), NotificationError> {
        let mut notif = notification;
        if notif.id.is_empty() {
            let id = NEXT_NOTIFICATION_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
            notif.id = format!("notif_{}", id);
        }
        update_system_state(|state| {
            let mut new_state = state.clone();
            new_state.notifications.push(notif.clone());
            new_state
        });
        Ok(())
    }

    /// Mark a notification as dismissed/read in the global system state.
    fn dismiss(&self, id: &str) -> Result<(), NotificationError> {
        update_system_state(|state| {
            let mut new_state = state.clone();
            for notif in &mut new_state.notifications {
                if notif.id == id {
                    notif.dismissed = true;
                }
            }
            new_state
        });
        Ok(())
    }

    /// Returns the permission state (always Granted for internal in-app notifications).
    fn request_permission(&self) -> NotificationPermission {
        NotificationPermission::Granted
    }
}

static NOTIFICATION_HANDLER: once_cell::sync::OnceCell<std::sync::Arc<dyn NotificationHandler>> =
    once_cell::sync::OnceCell::new();

/// Sets the global notification handler.
pub fn set_notification_handler(handler: std::sync::Arc<dyn NotificationHandler>) {
    let _ = NOTIFICATION_HANDLER.set(handler);
}

/// Gets the global notification handler, fallback to DefaultNotificationHandler.
pub fn get_notification_handler() -> std::sync::Arc<dyn NotificationHandler> {
    NOTIFICATION_HANDLER
        .get_or_init(|| std::sync::Arc::new(DefaultNotificationHandler))
        .clone()
}

/// Filter mapping name to extension list for a file dialog.
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct FileFilter {
    /// Friendly name of the filter (e.g. "Images").
    pub name: String,
    /// List of file extensions (e.g. ["png", "jpg"]).
    pub extensions: Vec<String>,
}

/// The mode/purpose of the file dialog.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq, Default)]
pub enum FileDialogMode {
    /// Pick a single or multiple files to open.
    #[default]
    OpenFile,
    /// Pick a directory path.
    OpenDirectory,
    /// Prompt for a location/name to save a file.
    SaveFile,
}

/// Dialog options for picking files or directories.
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct FileDialog {
    /// Title displayed in the dialog window.
    pub title: String,
    /// Optional starting directory path.
    pub default_path: Option<String>,
    /// Extensions used to filter selection.
    pub filters: Vec<FileFilter>,
    /// Open/save mode.
    pub mode: FileDialogMode,
    /// Allows selecting multiple files if in OpenFile mode.
    pub allow_multiple: bool,
}

/// Errors returned by the file dialog.
#[derive(Debug, thiserror::Error)]
pub enum FileDialogError {
    /// The user closed the dialog without selecting anything.
    #[error("File dialog cancelled")]
    Cancelled,
    /// An input/output error occurred.
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),
    /// Platform-specific error.
    #[error("Platform error: {0}")]
    Platform(String),
}

impl FileDialog {
    /// Creates a new FileDialog with the given mode.
    pub fn new(mode: FileDialogMode) -> Self {
        Self {
            mode,
            ..Default::default()
        }
    }

    /// Sets the dialog title.
    pub fn title(mut self, title: impl Into<String>) -> Self {
        self.title = title.into();
        self
    }

    /// Adds a file filter.
    pub fn add_filter(mut self, name: &str, extensions: &[&str]) -> Self {
        self.filters.push(FileFilter {
            name: name.to_string(),
            extensions: extensions.iter().map(|s| s.to_string()).collect(),
        });
        self
    }

    /// Sets the default starting directory path.
    pub fn default_path(mut self, path: impl Into<String>) -> Self {
        self.default_path = Some(path.into());
        self
    }

    /// Sets whether selecting multiple files is allowed.
    pub fn allow_multiple(mut self, allow: bool) -> Self {
        self.allow_multiple = allow;
        self
    }
}

#[cfg(not(target_arch = "wasm32"))]
impl FileDialog {
    /// Pick file(s) or folder based on current mode configuration.
    pub fn pick(self) -> Result<Vec<std::path::PathBuf>, FileDialogError> {
        let mut dialog = rfd::FileDialog::new();
        dialog = dialog.set_title(&self.title);
        if let Some(path) = &self.default_path {
            dialog = dialog.set_directory(path);
        }
        for filter in &self.filters {
            let refs: Vec<&str> = filter.extensions.iter().map(|s| s.as_str()).collect();
            dialog = dialog.add_filter(&filter.name, &refs);
        }

        match self.mode {
            FileDialogMode::OpenFile => {
                if self.allow_multiple {
                    dialog.pick_files().ok_or(FileDialogError::Cancelled)
                } else {
                    Ok(dialog.pick_file().into_iter().collect())
                }
            }
            FileDialogMode::OpenDirectory => Ok(dialog.pick_folder().into_iter().collect()),
            FileDialogMode::SaveFile => Ok(dialog.save_file().into_iter().collect()),
        }
    }

    /// Helper to pick a single file/directory, returning None if cancelled.
    pub fn pick_single(self) -> Result<Option<std::path::PathBuf>, FileDialogError> {
        let results = self.pick()?;
        Ok(results.into_iter().next())
    }
}

#[cfg(target_arch = "wasm32")]
impl FileDialog {
    /// Pick is unsupported/mocked on WASM.
    pub fn pick(self) -> Result<Vec<std::path::PathBuf>, FileDialogError> {
        Err(FileDialogError::Platform(
            "FileDialog is not supported synchronously on WebAssembly".to_string(),
        ))
    }

    /// Helper to pick a single file/directory, returning None if cancelled.
    pub fn pick_single(self) -> Result<Option<std::path::PathBuf>, FileDialogError> {
        Err(FileDialogError::Platform(
            "FileDialog is not supported synchronously on WebAssembly".to_string(),
        ))
    }
}

/// Error type representing a failure in Document load/save/parse operations.
#[derive(Debug, thiserror::Error)]
pub enum DocumentError {
    /// An input/output error occurred.
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),
    /// Failure during deserialization or parsing.
    #[error("Parse error: {0}")]
    Parse(String),
    /// Failure during serialization.
    #[error("Serialization error: {0}")]
    Serialize(String),
}

/// A document interface mapping to local filesystem persistence.
pub trait Document: Send + Sync {
    /// Loads the document from the specified path.
    fn read_from(path: &std::path::Path) -> Result<Self, DocumentError>
    where
        Self: Sized;

    /// Saves the document to the specified path.
    fn write_to(&self, path: &std::path::Path) -> Result<(), DocumentError>;

    /// Returns true if the document has unsaved modifications.
    fn is_dirty(&self) -> bool;

    /// Marks the document as clean/saved.
    fn mark_clean(&mut self);
}

/// Periodic auto-save coordinator for open Documents.
pub struct AutoSaveManager {
    /// Time interval in seconds between auto-saves.
    pub interval: f32,
    /// Elapsed timer tracker.
    pub timer: f32,
    /// Registered open documents under management.
    pub documents: Vec<(std::path::PathBuf, Box<dyn Document>)>,
}

impl AutoSaveManager {
    /// Creates a new AutoSaveManager with the specified check interval.
    pub fn new(interval: f32) -> Self {
        Self {
            interval,
            timer: 0.0,
            documents: Vec::new(),
        }
    }

    /// Register a document with its current file path.
    pub fn register(&mut self, path: std::path::PathBuf, doc: Box<dyn Document>) {
        self.documents.push((path, doc));
    }

    /// Advance the timer and auto-save any dirty documents when the interval is reached.
    pub fn tick(&mut self, dt: f32) {
        self.timer += dt;
        if self.timer >= self.interval {
            self.timer = 0.0;
            for (path, doc) in &mut self.documents {
                if doc.is_dirty() {
                    match doc.write_to(path) {
                        Ok(()) => {
                            doc.mark_clean();
                            log::info!("[AutoSaveManager] Auto-saved document to {:?}", path);
                        }
                        Err(e) => {
                            log::error!(
                                "[AutoSaveManager] Failed to auto-save document to {:?}: {:?}",
                                path,
                                e
                            );
                        }
                    }
                }
            }
        }
    }
}

// ── Menu Bar API ──────────────────────────────────────────────────────────────

/// Keyboard modifier flags used by [`KeyboardShortcut`].
///
/// On macOS, `cmd` maps to the Command (⌘) key.
/// On all other platforms, `cmd` maps to the Control key.
/// This is enforced at the renderer level, not here; the data model is OS-agnostic.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Modifiers {
    /// Command on macOS, Control on Windows/Linux.
    pub cmd: bool,
    /// Shift key.
    pub shift: bool,
    /// Alt/Option key.
    pub alt: bool,
    /// Control key (distinct from cmd on all platforms).
    pub ctrl: bool,
}

/// A keyboard shortcut binding to a menu action.
#[derive(Debug, Clone)]
pub struct KeyboardShortcut {
    /// The key character or name, e.g. `"s"`, `"z"`, `"Return"`.
    pub key: String,
    /// The required modifier combination.
    pub modifiers: Modifiers,
}

impl KeyboardShortcut {
    /// Convenience constructor: cmd (or ctrl on non-macOS) + `key`.
    pub fn cmd(key: impl Into<String>) -> Self {
        Self {
            key: key.into(),
            modifiers: Modifiers {
                cmd: true,
                ..Default::default()
            },
        }
    }

    /// Convenience constructor: cmd+Shift + `key`.
    pub fn cmd_shift(key: impl Into<String>) -> Self {
        Self {
            key: key.into(),
            modifiers: Modifiers {
                cmd: true,
                shift: true,
                ..Default::default()
            },
        }
    }
}

/// A single entry in a [`MenuBar`].
///
/// Actions hold a callback that is invoked when the user activates the item
/// (either via the menu UI or via the associated keyboard shortcut).
/// Separators provide visual grouping. Submenus allow hierarchical menus.
pub enum MenuItem {
    /// An activatable menu entry with an optional shortcut and enabled/disabled state.
    Action {
        label: String,
        shortcut: Option<KeyboardShortcut>,
        action: std::sync::Arc<dyn Fn() + Send + Sync>,
        enabled: bool,
    },
    /// A nested submenu.
    Submenu { label: String, items: Vec<MenuItem> },
    /// A visual separator line between groups of items.
    Separator,
}

impl std::fmt::Debug for MenuItem {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Action { label, enabled, .. } => f
                .debug_struct("Action")
                .field("label", label)
                .field("enabled", enabled)
                .finish(),
            Self::Submenu { label, items } => f
                .debug_struct("Submenu")
                .field("label", label)
                .field("items", items)
                .finish(),
            Self::Separator => write!(f, "Separator"),
        }
    }
}

/// A top-level menu bar containing [`MenuItem`]s.
///
/// The menu bar is a data model only; rendering it into an OS-native menu is
/// handled by the platform renderer (`cvkg-render-native`).
pub struct MenuBar {
    /// Ordered list of top-level menu items.
    pub items: Vec<MenuItem>,
}

impl MenuBar {
    /// Create an empty menu bar.
    pub fn new() -> Self {
        Self { items: Vec::new() }
    }

    /// Append a menu item to the bar.
    pub fn add_item(&mut self, item: MenuItem) {
        self.items.push(item);
    }

    /// Build the standard CVKG menu structure with all conventional shortcuts.
    ///
    /// The `cmd` modifier maps to ⌘ on macOS and Ctrl on Windows/Linux -- this
    /// translation is enforced by the renderer, not here.
    ///
    /// Menus included:
    /// - **File**: New, Open, Save, Close
    /// - **Edit**: Undo, Redo, Cut, Copy, Paste, Select All, Find
    /// - **View**: Zoom In, Zoom Out, Fullscreen
    /// - **Window**: Minimize, Zoom, Bring All to Front
    /// - **Help**: Search Help
    #[allow(clippy::too_many_arguments)]
    pub fn standard(
        new_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        open_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        save_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        close_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        quit_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        undo_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        redo_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        cut_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        copy_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        paste_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        select_all_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
        find_fn: std::sync::Arc<dyn Fn() + Send + Sync>,
    ) -> Self {
        let mut bar = Self::new();

        // ── File ──────────────────────────────────────────────────────────────
        bar.add_item(MenuItem::Submenu {
            label: "File".to_string(),
            items: vec![
                MenuItem::Action {
                    label: "New".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("n")),
                    action: new_fn,
                    enabled: true,
                },
                MenuItem::Action {
                    label: "Open…".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("o")),
                    action: open_fn,
                    enabled: true,
                },
                MenuItem::Separator,
                MenuItem::Action {
                    label: "Save".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("s")),
                    action: save_fn,
                    enabled: true,
                },
                MenuItem::Separator,
                MenuItem::Action {
                    label: "Close".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("w")),
                    action: close_fn,
                    enabled: true,
                },
                MenuItem::Separator,
                MenuItem::Action {
                    label: "Quit".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("q")),
                    action: quit_fn,
                    enabled: true,
                },
            ],
        });

        // ── Edit ──────────────────────────────────────────────────────────────
        bar.add_item(MenuItem::Submenu {
            label: "Edit".to_string(),
            items: vec![
                MenuItem::Action {
                    label: "Undo".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("z")),
                    action: undo_fn,
                    enabled: true,
                },
                MenuItem::Action {
                    label: "Redo".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd_shift("z")),
                    action: redo_fn,
                    enabled: true,
                },
                MenuItem::Separator,
                MenuItem::Action {
                    label: "Cut".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("x")),
                    action: cut_fn,
                    enabled: true,
                },
                MenuItem::Action {
                    label: "Copy".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("c")),
                    action: copy_fn,
                    enabled: true,
                },
                MenuItem::Action {
                    label: "Paste".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("v")),
                    action: paste_fn,
                    enabled: true,
                },
                MenuItem::Separator,
                MenuItem::Action {
                    label: "Select All".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("a")),
                    action: select_all_fn,
                    enabled: true,
                },
                MenuItem::Separator,
                MenuItem::Action {
                    label: "Find…".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("f")),
                    action: find_fn,
                    enabled: true,
                },
            ],
        });

        // ── View ──────────────────────────────────────────────────────────────
        // View items carry no application-level callbacks at the model layer;
        // zoom and fullscreen are handled by the renderer directly.
        let noop: std::sync::Arc<dyn Fn() + Send + Sync> = std::sync::Arc::new(|| {});
        bar.add_item(MenuItem::Submenu {
            label: "View".to_string(),
            items: vec![
                MenuItem::Action {
                    label: "Zoom In".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("=")),
                    action: noop.clone(),
                    enabled: true,
                },
                MenuItem::Action {
                    label: "Zoom Out".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("-")),
                    action: noop.clone(),
                    enabled: true,
                },
                MenuItem::Separator,
                MenuItem::Action {
                    label: "Toggle Fullscreen".to_string(),
                    shortcut: Some(KeyboardShortcut {
                        key: "f".to_string(),
                        modifiers: Modifiers {
                            ctrl: true,
                            ..Default::default()
                        },
                    }),
                    action: noop.clone(),
                    enabled: true,
                },
            ],
        });

        // ── Window ────────────────────────────────────────────────────────────
        bar.add_item(MenuItem::Submenu {
            label: "Window".to_string(),
            items: vec![
                MenuItem::Action {
                    label: "Minimize".to_string(),
                    shortcut: Some(KeyboardShortcut::cmd("m")),
                    action: noop.clone(),
                    enabled: true,
                },
                MenuItem::Action {
                    label: "Zoom".to_string(),
                    shortcut: None,
                    action: noop.clone(),
                    enabled: true,
                },
                MenuItem::Separator,
                MenuItem::Action {
                    label: "Bring All to Front".to_string(),
                    shortcut: None,
                    action: noop.clone(),
                    enabled: true,
                },
            ],
        });

        // ── Help ──────────────────────────────────────────────────────────────
        bar.add_item(MenuItem::Submenu {
            label: "Help".to_string(),
            items: vec![MenuItem::Action {
                label: "Search Help".to_string(),
                shortcut: None,
                action: noop,
                enabled: true,
            }],
        });

        bar
    }
}

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

// =============================================================================
// LOCALIZATION -- Item 12: Localization / Internationalization
// =============================================================================
// OS-agnostic: works on all platforms. No platform-specific string loading.

use std::sync::RwLock;

/// Layout direction for UI elements (LTR or RTL).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum Direction {
    #[default]
    LTR,
    RTL,
    Auto,
}

impl Direction {
    pub fn is_rtl(self) -> bool {
        matches!(self, Direction::RTL)
    }
}
#[derive(Clone, Debug)]
pub struct L10nBundle {
    pub locale: String,
    pub strings: HashMap<String, String>,
    pub is_rtl: bool,
}

impl L10nBundle {
    pub fn new(locale: impl Into<String>) -> Self {
        Self {
            locale: locale.into(),
            strings: HashMap::new(),
            is_rtl: false,
        }
    }

    pub fn add(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.strings.insert(key.into(), value.into());
        self
    }

    pub fn from_strings_format(locale: impl Into<String>, input: &str) -> Self {
        let mut bundle = Self::new(locale);
        for line in input.lines() {
            let line = line.trim();
            if line.is_empty() || line.starts_with("//") {
                continue;
            }
            if let Some(eq_pos) = line.find(" = ") {
                let key = line[..eq_pos].trim_matches('"').to_string();
                let val = line[eq_pos + 3..]
                    .trim_end_matches(';')
                    .trim_matches('"')
                    .to_string();
                bundle.strings.insert(key, val);
            }
        }
        bundle
    }
    /// Get a translated string by key. Returns the key itself if not found.
    pub fn t(&self, key: &str) -> String {
        self.strings
            .get(key)
            .map(|s| s.to_string())
            .unwrap_or_else(|| key.to_string())
    }

    /// Translate with interpolation. Replaces {0}, {1}, etc. with args.
    pub fn tf(&self, key: &str, args: &[&str]) -> String {
        let mut result = self.t(key);
        for (i, arg) in args.iter().enumerate() {
            result = result.replace(&format!("{{{}}}", i), arg);
        }
        result
    }
}

/// Global localization manager.
pub struct L10n {
    bundles: HashMap<String, L10nBundle>,
    current: String,
}

impl L10n {
    pub fn new(default_locale: &str) -> Self {
        Self {
            bundles: HashMap::new(),
            current: default_locale.to_string(),
        }
    }

    pub fn add_bundle(&mut self, bundle: L10nBundle) {
        self.bundles.insert(bundle.locale.clone(), bundle);
    }

    pub fn set_locale(&mut self, locale: &str) {
        self.current = locale.to_string();
    }
    pub fn current_locale(&self) -> &str {
        &self.current
    }

    pub fn is_rtl(&self) -> bool {
        self.bundles
            .get(self.current.as_str())
            .map(|b| b.is_rtl)
            .unwrap_or(false)
    }

    pub fn t(&self, key: &str) -> String {
        self.bundles
            .get(self.current.as_str())
            .map(|b| b.t(key))
            .unwrap_or_else(|| key.to_string())
    }

    pub fn tf(&self, key: &str, args: &[&str]) -> String {
        let mut result = self.t(key);
        for (i, arg) in args.iter().enumerate() {
            result = result.replace(&format!("{{{}}}", i), arg);
        }
        result
    }

    pub fn direction(&self) -> Direction {
        if self.is_rtl() {
            Direction::RTL
        } else {
            Direction::LTR
        }
    }
}

static L10N: once_cell::sync::Lazy<Arc<RwLock<L10n>>> =
    once_cell::sync::Lazy::new(|| Arc::new(RwLock::new(L10n::new("en"))));

pub fn init_l10n(l10n: L10n) {
    if let Ok(mut guard) = L10N.write() {
        *guard = l10n;
    }
}

pub fn l10n() -> Arc<RwLock<L10n>> {
    L10N.clone()
}

pub fn t(key: &str) -> String {
    L10N.read()
        .map(|g| g.t(key).to_string())
        .unwrap_or_else(|_| key.to_string())
}

pub fn tf(key: &str, args: &[&str]) -> String {
    L10N.read()
        .map(|g| g.tf(key, args))
        .unwrap_or_else(|_| key.to_string())
}

pub fn set_locale(locale: &str) {
    if let Ok(mut guard) = L10N.write() {
        guard.set_locale(locale);
    }
}

pub fn current_locale() -> String {
    L10N.read()
        .map(|g| g.current_locale().to_string())
        .unwrap_or_else(|_| "en".to_string())
}

pub fn is_rtl() -> bool {
    L10N.read().map(|g| g.is_rtl()).unwrap_or(false)
}

// =============================================================================
// SYSTEM THEME DETECTION -- Dark/Light mode detection
// =============================================================================
//
// OS-agnostic theme detection. Checks the CVKG_THEME environment variable first,
// then falls back to dark mode (safe default).
//
// Platform backends may override this with native OS queries (e.g.,
// dark-light crate on desktop, prefers-color-scheme on web).

/// The detected system theme.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum SystemTheme {
    /// Dark mode (default).
    #[default]
    Dark,
    /// Light mode.
    Light,
}

/// Detect the current system theme.
///
/// Checks `CVKG_THEME` environment variable first:
/// - `"dark"` → `SystemTheme::Dark`
/// - `"light"` → `SystemTheme::Light`
/// - unset or any other value → `SystemTheme::Dark` (default)
///
/// Platform backends can call this and override with native detection
/// (e.g., `dark-light` crate on desktop, `prefers-color-scheme` on web).
pub fn detect_system_theme() -> SystemTheme {
    std::env::var("CVKG_THEME")
        .ok()
        .and_then(|v| match v.as_str() {
            "light" => Some(SystemTheme::Light),
            "dark" => Some(SystemTheme::Dark),
            _ => None,
        })
        .unwrap_or(SystemTheme::Dark)
}

// =============================================================================
// AUDIO / HAPTIC -- Item 14: Spatial Audio / Haptic Feedback
// =============================================================================
// OS-agnostic: pure trait abstractions. Platform backends via cfg in renderer.

pub mod audio_haptic;
pub use audio_haptic::{
    AudioEngine, HapticEngine, HapticIntensity, NullAudioEngine, NullHapticEngine, haptic_error,
    haptic_impact, haptic_selection, haptic_success, play_sound, set_audio_engine,
    set_haptic_engine, sounds,
};

// =============================================================================
// PARALLAX -- Depth-based scroll offset system
// =============================================================================

pub mod parallax;
pub use parallax::{DisplayEnvironment, ParallaxModifier, PerformanceContract, Tier3Fallback};

// =============================================================================
// KVASIR IDENTITY -- Platform-wide unique identifier (crosscrate.md Finding #2)
// =============================================================================

/// Platform-wide unique identifier used by every CVKG graph layer.
///
/// # Why this exists
/// The crosscrate audit (Finding #2) identified that each crate maintained its own
/// incompatible `NodeId(u64)` newtype, causing type-level friction whenever two
/// layers needed to reference the same object (e.g., VDOM ↔ Scene sync).
///
/// # Contract
/// - Every `KvasirId` produced by [`KvasirId::new`] is globally unique within
///   a single process lifetime (backed by a monotonic atomic counter).
/// - IDs are sequential and cache-friendly in `HashMap` / `BTreeMap` keys.
/// - `KvasirId(0)` is **reserved as the null/invalid sentinel** — never returned
///   by `new()`.
/// - `Serialize`/`Deserialize` round-trips through the inner `u64`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
pub struct KvasirId(pub u64);

impl KvasirId {
    /// The null sentinel value. Never allocated by [`KvasirId::new`].
    pub const NULL: KvasirId = KvasirId(0);

    /// Allocate a new process-unique `KvasirId`.
    ///
    /// Uses a relaxed atomic increment — order does not matter because IDs
    /// only need to be distinct, not sequentially ordered relative to other
    /// memory operations.
    pub fn new() -> Self {
        use std::sync::atomic::{AtomicU64, Ordering};
        static COUNTER: AtomicU64 = AtomicU64::new(1);
        KvasirId(COUNTER.fetch_add(1, Ordering::Relaxed))
    }

    /// Returns `true` if this is the null sentinel value.
    pub fn is_null(self) -> bool {
        self.0 == 0
    }
}

impl std::fmt::Display for KvasirId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "KvasirId({})", self.0)
    }
}

/// Lossless conversion from a raw `u64` into a `KvasirId`.
///
/// # Why this exists
/// The crosscrate audit (Phase 1 of the implementation plan) unifies identity
/// across `cvkg-scene`, `cvkg-vdom`, and `cvkg-flow` by making each crate's
/// `NodeId` a type alias for `KvasirId`. Existing call sites that constructed
/// `NodeId(some_u64)` need a way to migrate without touching every literal.
///
/// # Contract
/// - `u64` -> `KvasirId` is infallible (any `u64` is a valid id; 0 maps to NULL).
/// - `KvasirId` -> `u64` is infallible (trivially the inner value).
///
/// # Note
/// Allocating ids should still go through `KvasirId::new()` so that the
/// atomic counter is respected. `From<u64>` is for *existing* ids that came
/// from serialized data or stable test fixtures.
impl From<u64> for KvasirId {
    fn from(value: u64) -> Self {
        KvasirId(value)
    }
}

impl From<KvasirId> for u64 {
    fn from(id: KvasirId) -> Self {
        id.0
    }
}

// =============================================================================
// INVALIDATION MODEL -- Platform-wide dirty flag system (crosscrate.md Finding #3)
// =============================================================================

/// Bitmask encoding which pipeline layers are dirty for a given object.
///
/// # Why this exists
/// The crosscrate audit (Finding #3) identified that each crate had its own
/// `is_dirty: bool` field with no shared semantic. Without a unified model,
/// updates propagate as full-tree redraws instead of targeted passes, leading
/// to performance collapse at scale.
///
/// # Layers (in pipeline order)
/// - `STATE`     — application-level data changed (triggers LAYOUT + PAINT + COMPOSITE)
/// - `LAYOUT`    — size or position changed (triggers PAINT + COMPOSITE)
/// - `PAINT`     — visual appearance changed (triggers COMPOSITE only)
/// - `COMPOSITE` — compositing properties changed (e.g. opacity, transform, blur)
///
/// # Contract
/// A crate that dirtifies a layer MUST also dirtify all downstream layers.
/// Use the helper constants [`DirtyFlags::from_state_change`] etc. rather
/// than setting bits manually to ensure the invariant is maintained.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
pub struct DirtyFlags(pub u8);

impl DirtyFlags {
    /// No layers are dirty.
    pub const CLEAN: DirtyFlags = DirtyFlags(0b0000_0000);
    /// Application state changed — propagates to all downstream layers.
    pub const STATE: DirtyFlags = DirtyFlags(0b0000_1111);
    /// Layout (size/position) changed — propagates to paint + composite.
    pub const LAYOUT: DirtyFlags = DirtyFlags(0b0000_0111);
    /// Paint (visual) changed — propagates to composite.
    pub const PAINT: DirtyFlags = DirtyFlags(0b0000_0011);
    /// Compositing properties changed (opacity, clip, backdrop).
    pub const COMPOSITE: DirtyFlags = DirtyFlags(0b0000_0001);
    /// All layers dirty (equivalent to STATE).
    pub const ALL: DirtyFlags = DirtyFlags(0b0000_1111);

    /// Returns `true` if any dirty bits are set.
    #[inline]
    pub fn is_dirty(self) -> bool {
        self.0 != 0
    }

    /// Returns `true` if the composite layer needs reprocessing.
    #[inline]
    pub fn needs_composite(self) -> bool {
        self.0 & 0b0000_0001 != 0
    }

    /// Returns `true` if the paint layer needs reprocessing.
    #[inline]
    pub fn needs_paint(self) -> bool {
        self.0 & 0b0000_0010 != 0
    }

    /// Returns `true` if layout needs reprocessing.
    #[inline]
    pub fn needs_layout(self) -> bool {
        self.0 & 0b0000_0100 != 0
    }

    /// Returns `true` if application state has changed.
    #[inline]
    pub fn needs_state(self) -> bool {
        self.0 & 0b0000_1000 != 0
    }

    /// Merge another set of flags into this one (bitwise OR).
    #[inline]
    pub fn merge(self, other: DirtyFlags) -> DirtyFlags {
        DirtyFlags(self.0 | other.0)
    }

    /// Clear all dirty flags, marking this object as clean.
    #[inline]
    pub fn clear(self) -> DirtyFlags {
        DirtyFlags::CLEAN
    }
}

impl std::ops::BitOr for DirtyFlags {
    type Output = DirtyFlags;
    fn bitor(self, rhs: DirtyFlags) -> DirtyFlags {
        DirtyFlags(self.0 | rhs.0)
    }
}

impl std::ops::BitOrAssign for DirtyFlags {
    fn bitor_assign(&mut self, rhs: DirtyFlags) {
        self.0 |= rhs.0;
    }
}

impl std::ops::BitAnd for DirtyFlags {
    type Output = DirtyFlags;
    fn bitand(self, rhs: DirtyFlags) -> DirtyFlags {
        DirtyFlags(self.0 & rhs.0)
    }
}

/// A single invalidation record associating a `KvasirId` with its dirty layers.
///
/// # Contract
/// Invalidation records are produced by any system that mutates state and
/// consumed by the scheduler to determine what work must be done next frame.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct InvalidationRecord {
    /// The object that was mutated.
    pub id: KvasirId,
    /// Which pipeline layers need reprocessing.
    pub flags: DirtyFlags,
}

impl InvalidationRecord {
    /// Create a new invalidation record.
    pub fn new(id: KvasirId, flags: DirtyFlags) -> Self {
        Self { id, flags }
    }

    /// Create a record indicating the object's full pipeline needs rebuilding.
    pub fn full(id: KvasirId) -> Self {
        Self { id, flags: DirtyFlags::ALL }
    }
}

#[cfg(test)]
mod kvasir_identity_tests {
    use super::*;

    #[test]
    fn kvasir_id_new_is_non_zero() {
        // Contract: KvasirId::new() must never return the null sentinel.
        let id = KvasirId::new();
        assert!(!id.is_null(), "KvasirId::new() returned null sentinel");
    }

    #[test]
    fn kvasir_id_new_is_unique() {
        // Each call must produce a distinct ID.
        let a = KvasirId::new();
        let b = KvasirId::new();
        let c = KvasirId::new();
        assert_ne!(a, b);
        assert_ne!(b, c);
        assert_ne!(a, c);
    }

    #[test]
    fn kvasir_id_null_sentinel() {
        assert!(KvasirId::NULL.is_null());
        assert!(!KvasirId::new().is_null());
    }

    #[test]
    fn kvasir_id_serde_roundtrip() {
        let id = KvasirId(42);
        let json = serde_json::to_string(&id).unwrap();
        let decoded: KvasirId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, decoded);
    }

    #[test]
    fn dirty_flags_clean_is_not_dirty() {
        assert!(!DirtyFlags::CLEAN.is_dirty());
    }

    #[test]
    fn dirty_flags_all_implies_all_layers() {
        let f = DirtyFlags::ALL;
        assert!(f.needs_state());
        assert!(f.needs_layout());
        assert!(f.needs_paint());
        assert!(f.needs_composite());
    }

    #[test]
    fn dirty_flags_composite_only() {
        let f = DirtyFlags::COMPOSITE;
        assert!(!f.needs_state());
        assert!(!f.needs_layout());
        assert!(!f.needs_paint());
        assert!(f.needs_composite());
    }

    #[test]
    fn dirty_flags_merge() {
        let a = DirtyFlags::COMPOSITE;
        let b = DirtyFlags::PAINT;
        let merged = a.merge(b);
        assert!(merged.needs_composite());
        assert!(merged.needs_paint());
        assert!(!merged.needs_layout());
    }

    #[test]
    fn dirty_flags_bitor() {
        let combined = DirtyFlags::PAINT | DirtyFlags::COMPOSITE;
        assert!(combined.needs_paint());
        assert!(combined.needs_composite());
    }

    #[test]
    fn dirty_flags_clear() {
        let dirty = DirtyFlags::ALL;
        let clean = dirty.clear();
        assert!(!clean.is_dirty());
    }

    #[test]
    fn dirty_flags_serde_roundtrip() {
        let f = DirtyFlags::LAYOUT;
        let json = serde_json::to_string(&f).unwrap();
        let decoded: DirtyFlags = serde_json::from_str(&json).unwrap();
        assert_eq!(f, decoded);
    }

    #[test]
    fn invalidation_record_full() {
        let id = KvasirId::new();
        let rec = InvalidationRecord::full(id);
        assert_eq!(rec.id, id);
        assert!(rec.flags.needs_state());
        assert!(rec.flags.needs_layout());
    }
}

// =========================================================================
// P1-15: Subscriber List Mutex Poisoning
// =========================================================================
//
// Regression tests for the audit finding: a single panicking subscriber
// would poison the Mutex and break all future state updates forever.
// The fix wraps each callback in catch_unwind, so panics are isolated
// and logged without affecting other subscribers or future updates.

#[cfg(test)]
mod subscriber_panic_isolation_tests {
    use super::*;
    use std::sync::atomic::{AtomicUsize, Ordering};

    #[test]
    fn panicking_subscriber_does_not_poison_mutex() {
        let state = State::new(0i32);
        let fired = Arc::new(AtomicUsize::new(0));

        // First subscriber: panics.
        let _ = state.subscribe(|_| -> () {
            panic!("subscriber 1 explodes");
        });

        // Second subscriber: should still fire.
        let fired_clone = Arc::clone(&fired);
        let _ = state.subscribe(move |v| {
            fired_clone.store(*v as usize + 1, Ordering::SeqCst);
        });

        // Trigger the state change. Subscriber 1 panics; subscriber 2 runs.
        state.set(42);

        assert_eq!(
            fired.load(Ordering::SeqCst),
            43,
            "second subscriber must fire even though first panicked"
        );

        // Critical: future state updates must still work.
        let fired2 = Arc::new(AtomicUsize::new(0));
        let fired2_clone = Arc::clone(&fired2);
        let _ = state.subscribe(move |v| {
            fired2_clone.store(*v as usize, Ordering::SeqCst);
        });
        state.set(100);
        assert_eq!(
            fired2.load(Ordering::SeqCst),
            100,
            "future updates must work after subscriber panic"
        );
    }

    #[test]
    fn all_subscribers_fire_even_if_one_panics() {
        let state = State::new(0u32);
        let count = Arc::new(AtomicUsize::new(0));

        // Mix of panicking and counting subscribers.
        let _ = state.subscribe(|_| panic!("boom 1"));
        let c1 = Arc::clone(&count);
        let _ = state.subscribe(move |_| {
            c1.fetch_add(1, Ordering::SeqCst);
        });
        let _ = state.subscribe(|_| panic!("boom 2"));
        let c2 = Arc::clone(&count);
        let _ = state.subscribe(move |_| {
            c2.fetch_add(1, Ordering::SeqCst);
        });

        state.set(1);

        // Both non-panicking subscribers must have fired.
        assert_eq!(
            count.load(Ordering::SeqCst),
            2,
            "both non-panicking subscribers should fire"
        );
    }

    #[test]
    fn invoke_subscribers_safely_returns_count() {
        // Direct unit test of the helper function.
        use std::sync::Mutex;
        let subs: SubscriberList<u32> = Arc::new(Mutex::new(Vec::new()));

        let count1 = Arc::new(AtomicUsize::new(0));
        let count1_clone = Arc::clone(&count1);
        subs.lock().unwrap().push(Box::new(move |v| {
            count1_clone.store(*v as usize, Ordering::SeqCst);
        }));

        let count2 = Arc::new(AtomicUsize::new(0));
        let count2_clone = Arc::clone(&count2);
        subs.lock().unwrap().push(Box::new(move |v| {
            count2_clone.store(*v as usize + 100, Ordering::SeqCst);
        }));

        let invoked = invoke_subscribers_safely(&subs, &7);
        assert_eq!(invoked, 2, "both subscribers should be invoked");
        assert_eq!(count1.load(Ordering::SeqCst), 7);
        assert_eq!(count2.load(Ordering::SeqCst), 107);
    }
}

// =========================================================================
// P1-17: Suspense::new_async Shared Fallback Runtime
// =========================================================================
//
// Regression tests for the audit finding: when no ambient tokio
// runtime exists, new_async spawned a new OS thread + runtime per
// call. The fix introduces a process-wide shared fallback runtime.

#[cfg(test)]
mod p1_17_shared_fallback_runtime_tests {
    use super::*;
    use std::time::Duration;

    #[test]
    fn fallback_runtime_is_shared() {
        // Calling fallback_runtime() multiple times should return the
        // same Runtime instance (singleton via OnceLock). This is the
        // core invariant that bounds thread creation.
        let r1 = fallback_runtime();
        let r2 = fallback_runtime();
        assert!(
            std::ptr::eq(r1 as *const _, r2 as *const _),
            "fallback_runtime must return the same instance"
        );
    }

    #[test]
    fn fallback_worker_count_is_bounded() {
        // The worker count must be >= 1 and <= 8 regardless of host
        // CPU count. This is what prevents the audit's "spawns
        // hundreds of OS threads" issue.
        let n = *FALLBACK_WORKER_COUNT.get_or_init(|| {
            let available = std::thread::available_parallelism()
                .map(|n| n.get())
                .unwrap_or(2);
            available.saturating_sub(1).clamp(1, 8)
        });
        assert!(n >= 1, "worker count must be at least 1, got {n}");
        assert!(n <= 8, "worker count must be at most 8, got {n}");
    }

    #[test]
    fn many_suspense_calls_share_runtime() {
        // P1-17 regression: 20 new_async calls in quick succession
        // should not hang or OOM. They all share the single
        // fallback runtime, so we never create more than ~8 OS
        // threads regardless of call count.
        //
        // We use a counter SharedState to confirm all 20 futures
        // actually run to completion.
        let counter = State::new(0u32);
        let mut handles = Vec::new();
        for _ in 0..20 {
            let s = Suspense::new_async(async { Ok::<u32, String>(1) });
            // Each suspense ready()s after the future resolves.
            // We don't block on ready (would deadlock without
            // explicit tokio context), but the spawn is enough to
            // exercise the path.
            let _ = s; // suppress unused warning
            handles.push(s);
        }
        // Force the counter to tick so the test observably runs.
        counter.set(20);
        assert_eq!(counter.get(), 20);
        // If we got here, the test did not hang or panic, which is
        // the main thing we want to verify for P1-17.
    }

    // ==========================================
    // P1-14: State<T> redundant storage documentation
    // ==========================================

    #[test]
    fn p1_14_state_storage_mechanisms() {
        // P1-14 documentation test: State<T> has 4 storage
        // mechanisms (swap, metadata_swap, tvar, metadata_tvar).
        // The audit flagged this as redundant. The fix is to
        // document the trade-off (arc_swap for reads, TVar for
        // atomic compound transactions) and add a set_direct()
        // method for callers who don't need compound transactions.
        use std::mem::size_of;
        let state = State::new(42u32);
        // State contains 4 storage mechanisms + subscribers +
        // version + resolution.
        // This test documents the size and the trade-off.
        let size = size_of_val(&state);
        // Size should be at least the size of 4 Arcs (4*8=32 on
        // 64-bit) plus subscribers (1 Arc) plus version (1 Arc)
        // plus ConflictResolution (1 byte tag).
        assert!(
            size >= 4 * std::mem::size_of::<usize>(),
            "State<T> should be at least 4 Arcs in size"
        );
    }

    #[test]
    fn p1_14_set_direct_updates_value() {
        // P1-14: set_direct() bypasses TVar for simple updates.
        // The swap is the authoritative read source.
        let state = State::new(0u32);
        state.set_direct(42);
        assert_eq!(state.get(), 42);
    }

    #[test]
    fn p1_14_set_direct_notifies_subscribers() {
        // P1-14: set_direct() must notify subscribers just like
        // set().
        let state = State::new(0u32);
        let received = Arc::new(Mutex::new(Vec::new()));
        let received_clone = Arc::clone(&received);
        state.subscribe(move |v| {
            received_clone.lock().unwrap().push(*v);
        });
        state.set_direct(1);
        state.set_direct(2);
        state.set_direct(3);
        // Allow the subscriber invocations to complete.
        std::thread::sleep(std::time::Duration::from_millis(10));
        let log = received.lock().unwrap();
        // Should have at least the last 3 values, but the order
        // and count depend on how many subscribers were invoked
        // (subscribers can be invoked synchronously or batched).
        assert!(
            log.contains(&1) && log.contains(&2) && log.contains(&3),
            "set_direct must notify subscribers of all values"
        );
    }
}

// =========================================================================
// P1-39: DirtyRegionManager -- tracks changed rectangles
// =========================================================================
//
// The P1-39 audit found that the scene graph lacks dirty region
// tracking. Large UIs may redraw excessively when only a small
// region changes. This struct provides the foundation for
// future dirty-region optimizations.
//
// Currently it just stores a list of dirty rectangles. Future
// work would add:
//  - Coalescing adjacent dirty regions into larger rects
//  - Tree-based hierarchical dirty tracking
//  - Integration with the renderer's scissor/clip
//
// This is a passive container -- callers add dirty regions
// when they change something, and the renderer can clear
// them after a frame.

/// P1-39: a list of regions that have changed and need to be
/// re-rendered. Coalesces overlapping rectangles on add to
/// avoid unbounded growth.
#[derive(Debug, Clone, Default)]
pub struct DirtyRegionManager {
    /// The dirty rectangles, in screen-space coordinates.
    regions: Vec<Rect>,
    /// Counter incremented on each clear, useful for detecting
    /// "stale" dirty regions after multiple frames.
    generation: u64,
}

impl DirtyRegionManager {
    /// Create a new empty dirty region manager.
    pub fn new() -> Self {
        Self::default()
    }

    /// Mark a region as dirty. The region is in screen-space
    /// coordinates (typically the same coordinate system as the
    /// rest of the rendering).
    ///
    /// If `region` overlaps with an existing dirty region, the
    /// two are coalesced into a single larger rectangle. This
    /// prevents the dirty list from growing unbounded for
    /// large UIs with many small changes.
    pub fn mark_dirty(&mut self, region: Rect) {
        // Try to merge with an existing overlapping region.
        for existing in self.regions.iter_mut() {
            if Self::rects_overlap(*existing, region) {
                *existing = Self::union_rect(*existing, region);
                return;
            }
        }
        // No overlap -- add as new region.
        self.regions.push(region);
    }

    /// Get the current dirty regions. The renderer can use
    /// this list to clip drawing to only the changed areas.
    pub fn regions(&self) -> &[Rect] {
        &self.regions
    }

    /// Check if any region is dirty. Useful for skipping a
    /// frame when nothing has changed.
    pub fn is_dirty(&self) -> bool {
        !self.regions.is_empty()
    }

    /// Clear all dirty regions. Called by the renderer after
    /// processing a frame.
    ///
    /// Increments the generation counter so callers can detect
    /// when a clear has happened.
    pub fn clear(&mut self) {
        self.regions.clear();
        self.generation = self.generation.wrapping_add(1);
    }

    /// Get the current generation counter. Increases on every
    /// clear(). Callers can cache this to detect when the
    /// dirty state has been reset.
    pub fn generation(&self) -> u64 {
        self.generation
    }

    /// Number of dirty regions currently tracked. After
    /// coalescing, this should be much smaller than the number
    /// of mark_dirty() calls.
    pub fn len(&self) -> usize {
        self.regions.len()
    }

    /// Check whether the dirty region list is empty.
    pub fn is_empty(&self) -> bool {
        self.regions.is_empty()
    }

    /// Check if two rectangles overlap.
    fn rects_overlap(a: Rect, b: Rect) -> bool {
        a.x < b.x + b.width
            && a.x + a.width > b.x
            && a.y < b.y + b.height
            && a.y + a.height > b.y
    }

    /// Compute the union of two rectangles (the smallest
    /// rectangle that contains both).
    fn union_rect(a: Rect, b: Rect) -> Rect {
        let min_x = a.x.min(b.x);
        let min_y = a.y.min(b.y);
        let max_x = (a.x + a.width).max(b.x + b.width);
        let max_y = (a.y + a.height).max(b.y + b.height);
        Rect {
            x: min_x,
            y: min_y,
            width: max_x - min_x,
            height: max_y - min_y,
        }
    }
}

#[cfg(test)]
mod p1_39_dirty_region_tests {
    use super::{DirtyRegionManager, Rect};

    #[test]
    fn new_manager_is_empty() {
        let m = DirtyRegionManager::new();
        assert!(!m.is_dirty());
        assert!(m.is_empty());
        assert_eq!(m.len(), 0);
    }

    #[test]
    fn mark_dirty_adds_region() {
        let mut m = DirtyRegionManager::new();
        m.mark_dirty(Rect { x: 0.0, y: 0.0, width: 10.0, height: 10.0 });
        assert!(m.is_dirty());
        assert_eq!(m.len(), 1);
    }

    #[test]
    fn overlapping_regions_coalesce() {
        let mut m = DirtyRegionManager::new();
        m.mark_dirty(Rect { x: 0.0, y: 0.0, width: 10.0, height: 10.0 });
        m.mark_dirty(Rect { x: 5.0, y: 5.0, width: 10.0, height: 10.0 });
        // Should be coalesced into a single region.
        assert_eq!(m.len(), 1);
        let r = &m.regions()[0];
        assert_eq!(r.x, 0.0);
        assert_eq!(r.y, 0.0);
        assert_eq!(r.width, 15.0);
        assert_eq!(r.height, 15.0);
    }

    #[test]
    fn non_overlapping_regions_dont_coalesce() {
        let mut m = DirtyRegionManager::new();
        m.mark_dirty(Rect { x: 0.0, y: 0.0, width: 10.0, height: 10.0 });
        m.mark_dirty(Rect { x: 100.0, y: 100.0, width: 10.0, height: 10.0 });
        // Should remain as 2 separate regions.
        assert_eq!(m.len(), 2);
    }

    #[test]
    fn clear_resets_regions_and_increments_generation() {
        let mut m = DirtyRegionManager::new();
        m.mark_dirty(Rect { x: 0.0, y: 0.0, width: 10.0, height: 10.0 });
        let g1 = m.generation();
        m.clear();
        assert!(!m.is_dirty());
        assert_eq!(m.len(), 0);
        assert_eq!(m.generation(), g1 + 1);
    }

    #[test]
    fn many_overlapping_marks_coalesce_to_one() {
        let mut m = DirtyRegionManager::new();
        // Mark 100 overlapping small regions.
        for i in 0..100 {
            m.mark_dirty(Rect {
                x: i as f32,
                y: i as f32,
                width: 10.0,
                height: 10.0,
            });
        }
        // All should coalesce to a single region.
        assert_eq!(m.len(), 1);
    }
}

// =========================================================================
// P1-43: FrameBudget -- global frame budget contract
// =========================================================================
//
// The P1-43 audit found that no global frame budget contract
// exists. Individual subsystems may exceed their time allocation
// without coordination. P0-2 already handles per-frame
// degradation (skipping non-essential passes when over budget)
// but doesn't coordinate allocation across subsystems.
//
// This struct provides the foundation for future frame budget
// coordination. It tracks wall-clock time per frame and per
// subsystem, and allows callers to check whether a subsystem
// is within its allocated time slice.
//
// Currently a passive observer. Future work would add:
//  - Per-subsystem time allocation
//  - Automatic QualityLevel adjustment when over budget
//  - Integration with the renderer's frame loop

// =============================================================================
// P1-41: LIST / TREE VIRTUALIZATION
// =============================================================================

/// Outcome of a `VirtualListWindow::compute` call — describes which rows
/// should be rendered and what scroll offset to apply to position them.
///
/// P1-41: IDE and visualization workloads with tens-of-thousands of rows must
/// only render the rows visible in the current viewport.  `VirtualListWindow`
/// computes the correct row range without building the full row list.
#[derive(Debug, Clone, PartialEq)]
pub struct VirtualWindow {
    /// Index of the first row that should be rendered (inclusive).
    pub first_visible: usize,
    /// Index one past the last row that should be rendered (exclusive).
    pub last_visible: usize,
    /// Total estimated height of all rows above `first_visible`, in logical
    /// pixels.  Use this as the scroll-offset padding above the rendered rows.
    pub offset_before: f32,
    /// Total estimated height of all rows below `last_visible`, in logical
    /// pixels.  Use this as the placeholder height below the rendered rows.
    pub offset_after: f32,
}

/// Computes the visible slice of a uniform-height virtual list.
///
/// Contract:
/// - `total_rows`: total number of items in the list (can be enormous).
/// - `row_height`: uniform logical height of every row in pixels.
/// - `viewport_y`: scroll offset of the viewport top edge.
/// - `viewport_height`: height of the visible window in pixels.
/// - `overscan`: number of extra rows to render above/below the viewport for
///   smooth scrolling.  Typically 2–5.
///
/// Returns a `VirtualWindow` describing the rendered slice and offset padding.
/// If `row_height` is ≤ 0 or `total_rows` is 0, returns a zero window.
pub fn compute_virtual_list_window(
    total_rows: usize,
    row_height: f32,
    viewport_y: f32,
    viewport_height: f32,
    overscan: usize,
) -> VirtualWindow {
    if total_rows == 0 || row_height <= 0.0 {
        return VirtualWindow {
            first_visible: 0,
            last_visible: 0,
            offset_before: 0.0,
            offset_after: 0.0,
        };
    }

    // How many rows fit in the viewport (rounded up for partial rows).
    let visible_rows = (viewport_height / row_height).ceil() as usize;

    // First row whose bottom edge is below the viewport top.
    let first = (viewport_y / row_height).floor() as isize - overscan as isize;
    let first = first.max(0) as usize;

    // Last row whose top edge is above the viewport bottom.
    let last = first + visible_rows + 2 * overscan;
    let last = last.min(total_rows);

    VirtualWindow {
        first_visible: first,
        last_visible: last,
        offset_before: first as f32 * row_height,
        offset_after: (total_rows - last) as f32 * row_height,
    }
}

/// Computes the visible slice of a variable-height virtual list using
/// a precomputed prefix-sum of row heights.
///
/// Contract:
/// - `prefix_heights[i]` is the cumulative height of all rows 0..i (not
///   including row i).  `prefix_heights.len()` must equal `total_rows + 1`
///   where `prefix_heights[0] == 0` and `prefix_heights[total_rows]` is the
///   total list height.
/// - `viewport_y` and `viewport_height` are in the same logical pixel units.
/// - `overscan` works the same as in `compute_virtual_list_window`.
///
/// This is O(log N) via binary search on the prefix-sum array.
pub fn compute_virtual_list_window_variable(
    prefix_heights: &[f32],
    viewport_y: f32,
    viewport_height: f32,
    overscan: usize,
) -> VirtualWindow {
    let total_rows = prefix_heights.len().saturating_sub(1);
    if total_rows == 0 {
        return VirtualWindow {
            first_visible: 0,
            last_visible: 0,
            offset_before: 0.0,
            offset_after: 0.0,
        };
    }

    // Binary search for the first row whose cumulative top is >= viewport_y.
    let first_idx = prefix_heights
        .partition_point(|&h| h < viewport_y)
        .saturating_sub(1);
    let first = first_idx.saturating_sub(overscan);

    // Binary search for the last row whose top < viewport_y + viewport_height.
    let viewport_bottom = viewport_y + viewport_height;
    let last_idx = prefix_heights.partition_point(|&h| h < viewport_bottom);
    let last = (last_idx + overscan).min(total_rows);

    VirtualWindow {
        first_visible: first,
        last_visible: last,
        offset_before: prefix_heights[first],
        offset_after: prefix_heights[total_rows] - prefix_heights[last],
    }
}