pane/

api.rs

//! # Pane
//!
//! A RON-driven retained UI library for wgpu applications.
//!
//! Layouts are defined in `.ron` files and hot-reloaded at runtime. Pane handles
//! all rendering, input, animation, and state — your app just reads actions and
//! drives values.
//!
//! ## Three usage modes
//!
//! | Mode | Use when |
//! |------|----------|
//! | [`run`] | Pane owns the window and event loop entirely |
//! | [`overlay`] / [`PaneOverlay`] | You own wgpu; Pane renders into your frame |
//! | [`headless`] / [`PaneHeadless`] | No GPU — logic, state, and events only (tests, servers) |
//!
//! ## Quick start (overlay)
//!
//! ```ignore
//! let mut ui = pane::overlay("ui/main.ron", &device, &queue, surface_format, None);
//!
//! // in your event loop:
//! ui.handle_event(&window_event, width as f32, height as f32);
//!
//! // in your render pass:
//! for action in ui.draw(&mut encoder, &view, width as f32, height as f32) {
//!     match action {
//!         PaneAction::Custom(id) => println!("button pressed: {id}"),
//!         PaneAction::Slider(id, val) => println!("{id} = {val}"),
//!         _ => {}
//!     }
//! }
//! ```

use std::collections::HashMap;
use std::sync::{Arc, mpsc};
use std::time::Instant;
use winit::event::WindowEvent;

use crate::builder::{StyleMap, build_logic};
use crate::draw::{Pane, Scene, ShaderId};
use crate::input::Input;
use crate::loader::{MenuDef, UiMsg, load_menu, load_menu_soft, spawn_watcher};
use crate::logic::Root;
use crate::styles::StyleRegistry;
use crate::textures::{GifMode, TextureId, TextureRegistry};

// ── Shared Helpers ────────────────────────────────────────────────────────────

/// An event emitted by the UI in response to user interaction.
///
/// Returned as a `Vec<PaneAction>` from [`PaneOverlay::draw`] and [`PaneHeadless::update`]
/// each frame. Process them in a `match` to drive your application logic.
///
/// Widget IDs in the variants correspond to the `id` field set in your `.ron` file.
#[derive(Debug, Clone, PartialEq)]
pub enum PaneAction {
    /// The active root has been switched, either by a button action or a [`PaneOverlay::draw`]
    /// call that processed a `SwitchRoot` message. Contains the name of the new root.
    SwitchRoot(String),

    /// A button with a `Quit` action was pressed, or the window close button was clicked.
    /// In standalone mode this exits immediately; in overlay/headless mode you should
    /// use this to exit your own event loop.
    Quit,

    /// A button with a `Custom(tag)` action was pressed. The `String` is the tag from
    /// the RON definition.
    Custom(String),

    /// A slider's value changed. `f32` is the new value in the slider's `min..=max` range.
    Slider(String, f32),

    /// A text box's content changed (fires on every keystroke). Contains the widget id
    /// and the full current string.
    TextChanged(String, String),

    /// The user pressed Enter in a text box. Contains the widget id and the submitted string.
    TextSubmitted(String, String),

    /// A toggle was flipped. `bool` is the new checked state.
    Toggle(String, bool),

    /// A dropdown selection changed. Contains the widget id, the new selected index,
    /// and the selected option string.
    Dropdown(String, usize, String),

    /// A radio group selection changed. Contains the widget id, the new selected index,
    /// and the selected option string.
    Radio(String, usize, String),
}

// ── WriteValue ────────────────────────────────────────────────────────────────

/// The value to set when calling [`PaneOverlay::write`] or [`PaneHeadless::write`].
///
/// Each variant corresponds to a writable widget type. Passing the wrong variant
/// for a given widget id is a no-op (a warning is printed).
///
/// # Examples
///
/// ```ignore
/// ui.write("volume", WriteValue::Slider(0.8));
/// ui.write("mute",   WriteValue::Toggle(true));
/// ui.write("name",   WriteValue::Text("Player 1".into()));
/// ui.write("lang",   WriteValue::Selected(2));
/// ```
#[derive(Debug, Clone)]
pub enum WriteValue {
    /// Set a `Slider` value. Clamped to the slider's `min..=max` range.
    Slider(f32),
    /// Set a `Toggle` checked state.
    Toggle(bool),
    /// Set a `TextBox` string. Truncated to `max_len` if set.
    Text(String),
    /// Set the selected index of a `Dropdown` or `RadioGroup`. Clamped to the valid range.
    Selected(usize),
}

// ── Private helpers ───────────────────────────────────────────────────────────

/// Register all built-in and user-defined shaders into the renderer's shader table.
///
/// Returns `(name → ShaderId map, id of the built-in "textured" shader)`.
/// The textured shader id is extracted separately because it is used by both the
/// background quad and texture-overlay draw calls.
fn register_shaders(
    renderer: &mut Pane,
    device: &wgpu::Device,
    shader_dirs: &[String],
    tex_reg: &TextureRegistry,
) -> (HashMap<String, ShaderId>, ShaderId) {
    let mut map = HashMap::new();
    for name in crate::shader_reg::BUILTIN_SHADER_NAMES {
        let id = renderer.register_shader(device, &crate::shader_reg::load_shader(name), tex_reg);
        map.insert(name.to_string(), id);
    }
    for dir in shader_dirs {
        for (name, src) in crate::shader_reg::scan_shader_dir(dir) {
            map.insert(name, renderer.register_shader(device, &src, tex_reg));
        }
    }
    let textured_id = *map
        .get("textured")
        .expect("[pane_ui] built-in 'textured' shader missing");
    (map, textured_id)
}

/// Load a texture (or GIF) by path, returning a cached id if the same path was
/// already loaded this session.
///
/// Errors are printed to stderr and return `None` so callers can gracefully skip
/// a missing asset without panicking.
fn load_texture_cached(
    tex_reg: &mut TextureRegistry,
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    tex_cache: &mut HashMap<String, TextureId>,
    path: &str,
    gif_mode: Option<GifMode>,
) -> Option<TextureId> {
    if let Some(&id) = tex_cache.get(path) {
        return Some(id);
    }
    let result = match gif_mode {
        Some(mode) => tex_reg.load_gif(device, queue, path, mode),
        None => tex_reg.load(device, queue, path),
    };
    match result {
        Ok(id) => {
            tex_cache.insert(path.to_string(), id);
            Some(id)
        }
        Err(e) => {
            eprintln!("[pane_ui] texture load error \\'{path}\\': {e}");
            None
        }
    }
}

/// Register shaders, load styles, and build the widget tree from a parsed `MenuDef`.
///
/// Called both at startup and on hot reload. Returns all the pieces that need to
/// be swapped into `Persistent` atomically when the UI rebuilds.
pub(crate) fn init_and_build(
    renderer: &mut Pane,
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    menu: &MenuDef,
    _tx: &mpsc::Sender<UiMsg>,
    tex_reg: &mut TextureRegistry,
) -> (
    StyleRegistry,
    HashMap<String, Root>,
    Option<String>,
    ShaderId,
    Option<crate::styles::StyleId>,
    StyleMap,
) {
    let (shader_map, textured_id) = register_shaders(renderer, device, &menu.shader_dirs, tex_reg);
    let mut tex_cache: HashMap<String, TextureId> = HashMap::new();
    let mut style_registry = StyleRegistry::new();

    let style_map = crate::styles_reg::register_all(
        &mut style_registry,
        &shader_map,
        &menu.style_dirs,
        textured_id,
        &mut |path, gif_mode| {
            load_texture_cached(tex_reg, device, queue, &mut tex_cache, path, gif_mode)
        },
    );

    let default_style = menu.default_style.as_deref().and_then(|name| {
        if let Some(&(id, _)) = style_map.get(name) {
            Some(id)
        } else {
            eprintln!("[pane_ui] default_style '{name}' not found in style map, ignoring");
            None
        }
    });

    let (roots, active_root) = build_logic(menu, &style_map, textured_id, &mut |path, gif_mode| {
        load_texture_cached(tex_reg, device, queue, &mut tex_cache, path, gif_mode)
    });

    (
        style_registry,
        roots,
        active_root,
        textured_id,
        default_style,
        style_map,
    )
}

/// Convert an internal [`UiMsg`] to the public [`PaneAction`] type.
///
/// Navigation messages (`SwitchRoot`, `Reload`, `SwitchTabPage`) are handled
/// upstream before this is called and return `None` here.
pub(crate) fn msg_to_action(msg: UiMsg) -> Option<PaneAction> {
    match msg {
        UiMsg::Quit => Some(PaneAction::Quit),
        UiMsg::Custom(s) => Some(PaneAction::Custom(s)),
        UiMsg::Slider(id, val) => Some(PaneAction::Slider(id, val)),
        UiMsg::TextChanged(id, s) => Some(PaneAction::TextChanged(id, s)),
        UiMsg::TextSubmitted(id, s) => Some(PaneAction::TextSubmitted(id, s)),
        UiMsg::Toggle(tag, checked) => Some(PaneAction::Toggle(tag, checked)),
        UiMsg::Dropdown(tag, idx, val) => Some(PaneAction::Dropdown(tag, idx, val)),
        UiMsg::Radio(tag, idx, val) => Some(PaneAction::Radio(tag, idx, val)),
        _ => None,
    }
}

/// Build an initial [`Persistent`] for standalone mode.
///
/// Called on the first frame tick, once the wgpu device and queue are available.
/// Standalone mode does not store the renderer in `Persistent` (it stays in `Pane`
/// which the draw closure owns), so `renderer` is always `None` here.
///
/// The `rx` field is filled with a dummy channel receiver. Standalone mode drains
/// messages from its own outer `rx` via `drain_messages_standalone` before
/// `run_frame` is called, so `check_messages` inside `run_frame` only ever sees an
/// empty channel. This avoids having to restructure the standalone harness around
/// the same receiver.
fn init_persistent(
    pane: &mut Pane,
    menu: &MenuDef,
    tx: &mpsc::Sender<UiMsg>,
    path_owned: &str,
    bg_path: Option<&String>,
    clear_color: Option<crate::draw::Color>,
) -> crate::threader::Persistent {
    let device = pane
        .device()
        .expect("standalone: device not yet initialized")
        .clone();
    let queue = pane
        .queue()
        .expect("standalone: queue not yet initialized")
        .clone();
    let mut tex_reg = TextureRegistry::new(&device, &queue);
    let (new_styles, new_roots, new_active, textured_id, new_default_style, new_style_map) =
        init_and_build(pane, &device, &queue, menu, tx, &mut tex_reg);
    let background = bg_path.and_then(|p| {
        let result = if p.to_lowercase().ends_with(".gif") {
            tex_reg.load_gif(&device, &queue, p, GifMode::Loop)
        } else {
            tex_reg.load(&device, &queue, p)
        };
        result.ok().map(|id| {
            let (width, height) = tex_reg.dimensions(id);
            crate::threader::BackgroundDef {
                shader: textured_id,
                texture: id,
                width,
                height,
            }
        })
    });
    crate::threader::Persistent {
        roots: new_roots,
        active_root: new_active,
        tab_pages: std::collections::HashMap::new(),
        nav: crate::logic::NavState::default(),
        styles: new_styles,
        style_map: new_style_map,
        default_style: new_default_style,
        tex_reg: Some(tex_reg),
        device: Some(device),
        queue: Some(queue),
        renderer: None,
        background,
        clear_color,
        pending_actions: Vec::new(),
        tx: tx.clone(),
        rx: mpsc::channel().1,
        ron_path: path_owned.to_string(),
        debug: std::env::var("PANE_DEBUG").is_ok(),
        headless_accessible: false,
        osk: crate::keyboard::OskState::default(),
    }
}

/// Drain the standalone message channel for one frame.
///
/// Handles `Reload` (which needs a live `&mut Pane` unavailable inside
/// `check_messages`), `SwitchRoot`, `SwitchTabPage`, and `Quit` directly.
/// Everything else is forwarded through [`msg_to_action`] into `pending_actions`.
///
/// Must be called before `run_frame` so that `check_messages` sees an empty
/// channel on its drain pass.
fn drain_messages_standalone(
    rx: &mpsc::Receiver<UiMsg>,
    p: &mut crate::threader::Persistent,
    pane: &mut Pane,
    path_owned: &str,
    tx: &mpsc::Sender<UiMsg>,
) {
    while let Ok(msg) = rx.try_recv() {
        match msg {
            UiMsg::SwitchRoot(name) => {
                p.active_root = Some(name.clone());
                p.nav = crate::logic::NavState::default();
                p.pending_actions.push(PaneAction::SwitchRoot(name));
            }
            UiMsg::SwitchTabPage { tab_id, page } => {
                p.tab_pages.insert(tab_id, page);
            }
            UiMsg::Quit => std::process::exit(0),
            UiMsg::Toast {
                message,
                duration,
                x,
                y,
                width,
                height,
            } => {
                push_toast_into(p, message, duration, x, y, width, height);
            }
            UiMsg::Reload => {
                if let Ok(new_menu) = load_menu_soft(path_owned) {
                    let device = p.device.as_ref().unwrap().clone();
                    let queue = p.queue.as_ref().unwrap().clone();
                    let prev_active = p.active_root.clone();
                    let tex_reg = p.tex_reg.as_mut().unwrap();
                    let (
                        new_styles,
                        new_roots,
                        new_active,
                        _textured_id,
                        new_default_style,
                        new_style_map,
                    ) = init_and_build(pane, &device, &queue, &new_menu, tx, tex_reg);
                    p.styles = new_styles;
                    p.style_map = new_style_map;
                    p.active_root = prev_active
                        .filter(|name| new_roots.iter().any(|(k, _)| k == name))
                        .or(new_active);
                    p.roots = new_roots;
                    p.default_style = new_default_style;
                    p.nav = crate::logic::NavState::default();
                    p.clear_color = new_menu.clear_color;
                }
            }
            other => {
                if let Some(a) = msg_to_action(other) {
                    p.pending_actions.push(a);
                }
            }
        }
    }
}

// ── Mode 1: Standalone ────────────────────────────────────────────────────────

/// Run Pane as a standalone application, owning the window and event loop.
///
/// This is the simplest integration — Pane creates the window, runs the loop,
/// and never returns. Use [`overlay`] or [`headless`] if you need to retain
/// control of the event loop or the wgpu device.
///
/// The `.ron` file path is relative to the working directory. Hot reload is
/// enabled automatically if `hot_reload: true` is set in the root definition.
///
/// # Panics
///
/// Panics if the `.ron` file cannot be read or parsed.
pub fn run(path: &str) {
    run_with(path, |_, _| {});
}

// ── StandaloneHandle ──────────────────────────────────────────────────────────

/// A handle passed to the [`run_with`] callback each frame, allowing you to
/// call toast notifications and other runtime APIs from standalone mode.
pub struct StandaloneHandle<'a> {
    persistent: &'a mut crate::threader::Persistent,
}

impl StandaloneHandle<'_> {
    // ── Read / Write ──────────────────────────────────────────────────────────

    /// Returns the item data and its current visual state for any widget by id.
    ///
    /// See [`PaneOverlay::read`] for details.
    #[must_use]
    pub fn read(&self, id: &str) -> Option<(&crate::items::UiItem, crate::widgets::WidgetState)> {
        read_into(self.persistent, id)
    }

    /// Set a widget's value programmatically.
    ///
    /// See [`WriteValue`] for the supported widget types and their matching variants.
    pub fn write(&mut self, id: &str, value: &WriteValue) {
        write_into(self.persistent, id, value);
    }

    // ── Create / Destroy ──────────────────────────────────────────────────────

    /// Add a code-built widget to a named root. Returns `false` if the id is already
    /// in use or the root doesn't exist.
    pub fn create(&mut self, root: &str, builder: impl crate::build::WidgetBuilder) -> bool {
        create_into(self.persistent, root, builder)
    }

    /// Remove a widget by id from any root. Returns `true` if a widget was removed.
    pub fn destroy(&mut self, id: &str) -> bool {
        destroy_into(self.persistent, id)
    }

    /// Create an empty root that can be populated with [`Self::create`].
    pub fn create_root(&mut self, name: impl Into<String>) {
        create_root_into(self.persistent, name);
    }

    /// Resolve a style name to its `StyleId` for use with builders.
    #[must_use]
    pub fn style_id(&self, name: &str) -> Option<crate::styles::StyleId> {
        style_id_in(self.persistent, name)
    }

    /// Returns the name of the current default style, if one is set.
    #[must_use]
    pub fn default_style(&self) -> Option<&str> {
        default_style_in(self.persistent)
    }

    /// Switch the default style by name. Returns `false` if the name is not registered.
    pub fn set_default_style(&mut self, name: &str) -> bool {
        set_default_style_in(self.persistent, name)
    }

    // ── Toast ─────────────────────────────────────────────────────────────────

    /// Spawn a transient toast notification at the given position.
    pub fn push_toast(
        &mut self,
        message: impl Into<String>,
        duration: f32,
        x: f32,
        y: f32,
        width: f32,
        height: f32,
    ) {
        push_toast_into(
            self.persistent,
            message.into(),
            duration,
            x,
            y,
            width,
            height,
        );
    }
}

/// Like [`run`], but gives you a [`StandaloneHandle`] each frame to call write, toast, etc.
///
/// `on_action` is called once per [`PaneAction`] emitted that frame.
///
/// ```no_run
/// pane::run_with("assets/menu.ron", |ui, action| {
///     if let pane::PaneAction::Custom(ref id) = action {
///         if id == "save" { ui.push_toast("Saved!", 2.0, 0.0, -400.0, 300.0, 60.0); }
///     }
/// });
/// ```
///
/// # Panics
///
/// Panics if the `.ron` file cannot be read or parsed, or if the standalone
/// wgpu device/queue are not yet initialized when the first frame fires.
pub fn run_with<F>(path: &str, mut on_action: F)
where
    F: FnMut(&mut StandaloneHandle, PaneAction) + 'static,
{
    let path_owned = path.to_string();
    let menu = load_menu(&path_owned);

    let (tx, rx) = mpsc::channel::<UiMsg>();
    if menu.hot_reload {
        spawn_watcher(
            path_owned.clone(),
            menu.shader_dirs.clone(),
            menu.style_dirs.clone(),
            tx.clone(),
        );
    }

    let bg_path = menu.background.clone();
    let clear_color = menu.clear_color;
    let mut persistent: Option<crate::threader::Persistent> = None;
    let mut last_time = Instant::now();

    crate::draw::run(
        move |pane: &mut Pane, scene: &mut Scene, input: &mut Input, pw: f32, ph: f32, _dt: f32| {
            // First tick: initialise once the device/queue are available.
            if persistent.is_none() {
                persistent = Some(init_persistent(
                    pane,
                    &menu,
                    &tx,
                    &path_owned,
                    bg_path.as_ref(),
                    clear_color,
                ));
            }

            let p = persistent.as_mut().unwrap();

            // Drain messages (including Reload) before run_frame sees the channel.
            drain_messages_standalone(&rx, p, pane, &path_owned, &tx);

            let mut frame = crate::threader::Frame {
                dt: 0.0,
                last_tick: last_time,
                pw,
                ph,
                input: std::mem::take(input),
                scene: std::mem::take(scene),
            };
            {
                let mut ctx = crate::threader::FrameCtx {
                    persistent: p,
                    frame: &mut frame,
                    standalone_pane: Some(pane),
                };
                crate::order::run_frame(&mut ctx, None, None);
            }
            last_time = frame.last_tick;
            *input = frame.input;
            *scene = frame.scene;

            let actions = std::mem::take(&mut p.pending_actions);
            let cc = p.clear_color;
            let cursor = [
                input.mouse_x,
                input.mouse_y,
                f32::from(u8::from(input.left_pressed)),
            ];
            let mut handle = StandaloneHandle { persistent: p };
            for action in actions {
                on_action(&mut handle, action);
            }

            pane.present_standalone(
                scene,
                pw,
                ph,
                frame.dt,
                cursor,
                cc,
                p.tex_reg.as_mut().unwrap(),
            );
            scene.clear();
        },
    );
}

// ── Mode 2: Overlay ───────────────────────────────────────────────────────────

/// A Pane UI instance that renders into an existing wgpu surface.
///
/// You retain full control of the window, event loop, and wgpu device. Pane
/// composites its output on top of whatever you have already rendered that frame.
///
/// Create with [`overlay`], then call [`handle_event`](PaneOverlay::handle_event)
/// from your winit event loop and [`draw`](PaneOverlay::draw) each frame.
pub struct PaneOverlay {
    persistent: crate::threader::Persistent,
    input: Input,
    scene: Scene,
    last_time: Instant,
    gilrs: Option<gilrs::Gilrs>,
}

/// Create a [`PaneOverlay`] that renders into your existing wgpu surface.
///
/// - `path` — path to the root `.ron` layout file, relative to the working directory.
/// - `device` / `queue` — your wgpu device and queue. Pane stores `Arc` clones of
///   these for hot-reload and per-frame rendering.
/// - `format` — the texture format of your swap chain surface.
/// - `gilrs` — optional pre-constructed gilrs instance for gamepad input.
///
/// # Panics
///
/// Panics if the `.ron` file cannot be read or parsed, or if the built-in `textured`
/// shader is missing from the shader registry.
#[must_use]
pub fn overlay(
    path: &str,
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    format: wgpu::TextureFormat,
    gilrs: Option<gilrs::Gilrs>,
) -> PaneOverlay {
    let menu = load_menu(path);
    let (tx, rx) = mpsc::channel::<UiMsg>();
    let mut renderer = Pane::new(device, queue, format);
    let mut tex_reg = TextureRegistry::new(device, queue);
    let (new_styles, new_roots, new_active, _textured_id, new_default_style, new_style_map) =
        init_and_build(&mut renderer, device, queue, &menu, &tx, &mut tex_reg);

    if menu.hot_reload {
        spawn_watcher(
            path.to_string(),
            menu.shader_dirs.clone(),
            menu.style_dirs.clone(),
            tx.clone(),
        );
    }

    // wgpu Device and Queue are internally ref-counted; clone here is cheap.
    let device_arc = Arc::new(device.clone());
    let queue_arc = Arc::new(queue.clone());

    let persistent = crate::threader::Persistent {
        roots: new_roots,
        active_root: new_active,
        tab_pages: std::collections::HashMap::new(),
        nav: crate::logic::NavState::default(),
        styles: new_styles,
        style_map: new_style_map,
        default_style: new_default_style,
        tex_reg: Some(tex_reg),
        device: Some(device_arc),
        queue: Some(queue_arc),
        renderer: Some(renderer),
        background: None,
        clear_color: None,
        pending_actions: Vec::new(),
        tx,
        rx,
        ron_path: path.to_string(),
        debug: false,
        headless_accessible: false,
        osk: crate::keyboard::OskState::default(),
    };

    PaneOverlay {
        persistent,
        input: Input::new(),
        scene: Scene::new(),
        last_time: Instant::now(),
        gilrs: gilrs.or_else(|| gilrs::Gilrs::new().ok()),
    }
}

// ── Shared helpers (Overlay + Headless) ───────────────────────────────────────

/// Return a mutable reference to the currently active root, if any.
fn active_root_mut(
    persistent: &mut crate::threader::Persistent,
) -> Option<&mut crate::logic::Root> {
    persistent
        .active_root
        .as_deref()
        .and_then(|n| persistent.roots.get_mut(n))
}

/// Apply a [`WriteValue`] to the widget with the given id in the active root.
///
/// Shared by [`PaneOverlay::write`] and [`PaneHeadless::write`].
/// Resolve a style name to its `StyleId`, if registered.
fn style_id_in(
    persistent: &crate::threader::Persistent,
    name: &str,
) -> Option<crate::styles::StyleId> {
    persistent.style_map.get(name).map(|&(id, _)| id)
}

fn default_style_in(persistent: &crate::threader::Persistent) -> Option<&str> {
    let id = persistent.default_style?;
    persistent
        .style_map
        .iter()
        .find(|(_, v)| v.0 == id)
        .map(|(name, _)| name.as_str())
}

fn set_default_style_in(persistent: &mut crate::threader::Persistent, name: &str) -> bool {
    match persistent.style_map.get(name).map(|&(id, _)| id) {
        Some(id) => {
            persistent.default_style = Some(id);
            true
        }
        None => false,
    }
}

/// Add a code-built widget to a named root. Fails if the id already exists or the root is missing.
fn create_into(
    persistent: &mut crate::threader::Persistent,
    root: &str,
    builder: impl crate::build::WidgetBuilder,
) -> bool {
    let (item, state) = builder.build(persistent.default_style);
    let id = item.id().to_string();
    for r in persistent.roots.values() {
        if r.items.iter().any(|(i, _)| i.id() == id) {
            eprintln!("[pane_ui] create: id '{id}' already exists");
            return false;
        }
    }
    let Some(r) = persistent.roots.get_mut(root) else {
        eprintln!("[pane_ui] create: root '{root}' not found");
        return false;
    };
    r.items.push((item, state));
    true
}

/// Remove the first widget matching `id` from any root. Returns true if found.
fn destroy_into(persistent: &mut crate::threader::Persistent, id: &str) -> bool {
    for r in persistent.roots.values_mut() {
        if let Some(idx) = r.items.iter().position(|(item, _)| item.id() == id) {
            r.items.remove(idx);
            if persistent.nav.focused_id.as_deref() == Some(id) {
                persistent.nav = crate::logic::NavState::default();
            }
            return true;
        }
    }
    false
}

/// Create a new empty root. No-op if a root with this name already exists.
fn create_root_into(persistent: &mut crate::threader::Persistent, name: impl Into<String>) {
    let name = name.into();
    persistent
        .roots
        .entry(name)
        .or_insert_with(crate::logic::Root::new);
}

/// Find a widget by id across all roots. Returns the item and a snapshot of its visual state.
fn read_into<'a>(
    persistent: &'a crate::threader::Persistent,
    id: &str,
) -> Option<(&'a crate::items::UiItem, crate::widgets::WidgetState)> {
    for root in persistent.roots.values() {
        for (item, state) in &root.items {
            if item.id() == id {
                return Some((item, state.visual()));
            }
        }
    }
    None
}

fn write_into(persistent: &mut crate::threader::Persistent, id: &str, value: &WriteValue) {
    use crate::items::UiItem;
    use crate::widgets::ItemState;
    for root in persistent.roots.values_mut() {
        for (item, state) in &mut root.items {
            if item.id() != id {
                continue;
            }
            match (item, state, value) {
                (UiItem::Slider(s), ItemState::Slider(st), WriteValue::Slider(v)) => {
                    st.value = v.clamp(s.min, s.max);
                }
                (UiItem::Toggle(_), ItemState::Toggle(st), WriteValue::Toggle(v)) => {
                    st.checked = *v;
                }
                (UiItem::TextBox(tb), ItemState::TextBox(st), WriteValue::Text(v)) => {
                    st.text = tb
                        .max_len
                        .map_or_else(|| v.clone(), |limit| v.chars().take(limit).collect());
                    st.cursor_pos = st.text.chars().count();
                }
                (UiItem::Dropdown(dd), ItemState::Dropdown(st), WriteValue::Selected(i)) => {
                    st.selected = (*i).min(dd.items.len().saturating_sub(1));
                }
                (UiItem::RadioGroup(rg), ItemState::RadioGroup(st), WriteValue::Selected(i)) => {
                    st.selected = (*i).min(rg.items.len().saturating_sub(1));
                }
                _ => {
                    eprintln!("[pane_ui] write('{id}'): value type does not match widget type");
                }
            }
            return;
        }
    }
    eprintln!("[pane_ui] write('{id}'): no widget found");
}

/// Insert a transient toast widget into the active root's item list.
///
/// Shared by [`PaneOverlay::push_toast`], [`PaneHeadless::push_toast`], and
/// [`StandaloneHandle::push_toast`].
pub(crate) fn push_toast_into(
    persistent: &mut crate::threader::Persistent,
    message: String,
    duration: f32,
    x: f32,
    y: f32,
    width: f32,
    height: f32,
) {
    if let Some(name) = persistent.active_root.as_deref()
        && let Some(root) = persistent.roots.get_mut(name)
    {
        // Use item count as id suffix so two toasts on the same root get distinct ids.
        let id = format!("__toast_{}", root.items.len());
        root.items.push((
            crate::items::UiItem::Toast(crate::items::Toast {
                id,
                x,
                y,
                width,
                height,
                message,
                duration,
                shape: persistent.default_style,
            }),
            crate::widgets::ItemState::Toast(crate::widgets::ToastState::new(duration)),
        ));
    }
}

/// Delegate for the `actor_move_to` method shared across all three API types.
fn actor_move_to_into(
    persistent: &mut crate::threader::Persistent,
    id: &str,
    x: f32,
    y: f32,
    speed: f32,
) {
    if let Some(r) = active_root_mut(persistent) {
        crate::query::actor_move_to_in(&mut r.items, id, x, y, speed);
    }
}

/// Delegate for the `actor_follow_cursor` method shared across all three API types.
fn actor_follow_cursor_into(
    persistent: &mut crate::threader::Persistent,
    id: &str,
    speed: f32,
    trail: f32,
) {
    if let Some(r) = active_root_mut(persistent) {
        crate::query::actor_follow_cursor_in(&mut r.items, id, speed, trail);
    }
}

/// Delegate for the `actor_reset` method shared across all three API types.
fn actor_reset_into(persistent: &mut crate::threader::Persistent, id: &str) {
    if let Some(r) = active_root_mut(persistent) {
        crate::query::actor_reset_in(&mut r.items, id);
    }
}

/// Delegate for the `actor_set_pos` method shared across all three API types.
fn actor_set_pos_into(persistent: &mut crate::threader::Persistent, id: &str, x: f32, y: f32) {
    if let Some(r) = active_root_mut(persistent) {
        crate::query::actor_set_pos_in(&mut r.items, id, x, y);
    }
}

impl PaneOverlay {
    /// Forward a winit [`WindowEvent`] to Pane's input handler.
    pub fn handle_event(&mut self, event: &WindowEvent, pw: f32, ph: f32) {
        self.input.handle_event(event, pw, ph);
    }

    /// Forward a gilrs gamepad event manually.
    ///
    /// Use this if you own the gilrs instance yourself — pass `None` for `gilrs` in
    /// [`overlay`] first to prevent Pane from also polling it internally.
    pub fn handle_gamepad_event(&mut self, event: gilrs::Event) {
        self.input.handle_gamepad_event(event);
    }

    /// Stop Pane from polling gilrs internally.
    pub fn disable_auto_gamepad(&mut self) {
        self.gilrs = None;
    }

    /// Tick and render the UI into an existing render pass.
    ///
    /// Call once per frame, after your own render commands and before presenting.
    /// Returns all [`PaneAction`]s emitted since the last call.
    ///
    /// - `encoder` — your active command encoder for the current frame.
    /// - `view` — the texture view to render into (typically your swap chain image).
    /// - `pw` / `ph` — window dimensions in logical pixels.
    pub fn draw(
        &mut self,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        pw: f32,
        ph: f32,
    ) -> Vec<PaneAction> {
        // Feed external gilrs events before run_frame polls the owned one.
        if let Some(gilrs) = self.gilrs.as_mut() {
            while let Some(ev) = gilrs.next_event() {
                self.input.handle_gamepad_event(ev);
            }
        }

        self.persistent.pending_actions.clear();

        let mut frame = crate::threader::Frame {
            dt: 0.0,
            last_tick: self.last_time,
            pw,
            ph,
            input: std::mem::take(&mut self.input),
            scene: std::mem::take(&mut self.scene),
        };
        {
            let mut ctx = crate::threader::FrameCtx {
                persistent: &mut self.persistent,
                frame: &mut frame,
                standalone_pane: None,
            };
            crate::order::run_frame(&mut ctx, Some(encoder), Some(view));
        }
        self.last_time = frame.last_tick;
        self.input = frame.input;
        self.scene = frame.scene;

        std::mem::take(&mut self.persistent.pending_actions)
    }

    // ── Read ──────────────────────────────────────────────────────────────────

    /// Returns the item data and its current visual state for any widget by id.
    ///
    /// Pattern-match on `UiItem` to access widget-specific fields:
    /// ```ignore
    /// if let Some((UiItem::Button(b), vis)) = ui.read("my_button") {
    ///     println!("disabled={} hovered={}", b.disabled, vis.hovered);
    /// }
    /// if let Some((UiItem::Slider(s), vis)) = ui.read("volume") {
    ///     println!("value={} grabbed={}", s.value, vis.grabbed);
    /// }
    /// ```
    pub fn read(&self, id: &str) -> Option<(&crate::items::UiItem, crate::widgets::WidgetState)> {
        read_into(&self.persistent, id)
    }

    // ── Write / Set ───────────────────────────────────────────────────────────

    /// Set a widget's value programmatically.
    ///
    /// See [`WriteValue`] for the supported widget types and their matching variants.
    /// Mismatched types and unknown ids are logged and ignored.
    pub fn write(&mut self, id: &str, value: &WriteValue) {
        write_into(&mut self.persistent, id, value);
    }

    // ── Create / Destroy ──────────────────────────────────────────────────────

    /// Add a code-built widget to a named root. Returns `false` if the id is already
    /// in use or the root doesn't exist.
    pub fn create(&mut self, root: &str, builder: impl crate::build::WidgetBuilder) -> bool {
        create_into(&mut self.persistent, root, builder)
    }

    /// Remove a widget by id from any root. Returns `true` if a widget was removed.
    pub fn destroy(&mut self, id: &str) -> bool {
        destroy_into(&mut self.persistent, id)
    }

    /// Create an empty root that can be populated with [`Self::create`].
    pub fn create_root(&mut self, name: impl Into<String>) {
        create_root_into(&mut self.persistent, name);
    }

    /// Resolve a style name to its `StyleId` for use with builders.
    #[must_use]
    pub fn style_id(&self, name: &str) -> Option<crate::styles::StyleId> {
        style_id_in(&self.persistent, name)
    }

    /// Returns the name of the current default style, if one is set.
    #[must_use]
    pub fn default_style(&self) -> Option<&str> {
        default_style_in(&self.persistent)
    }

    /// Switch the default style by name. Returns `false` if the name is not registered.
    pub fn set_default_style(&mut self, name: &str) -> bool {
        set_default_style_in(&mut self.persistent, name)
    }

    /// Enable or disable debug message logging. When on, every internal `UiMsg` is printed to stdout.
    pub const fn set_debug(&mut self, on: bool) {
        self.persistent.debug = on;
    }

    // ── Toast ─────────────────────────────────────────────────────────────────

    /// Spawn a transient toast notification at the given position.
    pub fn push_toast(
        &mut self,
        message: impl Into<String>,
        duration: f32,
        x: f32,
        y: f32,
        width: f32,
        height: f32,
    ) {
        push_toast_into(
            &mut self.persistent,
            message.into(),
            duration,
            x,
            y,
            width,
            height,
        );
    }

    // ── Actor API ─────────────────────────────────────────────────────────────

    /// Programmatically send an actor to a fixed position, overriding its RON behaviours.
    pub fn actor_move_to(&mut self, id: &str, x: f32, y: f32, speed: f32) {
        actor_move_to_into(&mut self.persistent, id, x, y, speed);
    }

    /// Programmatically make an actor follow the cursor, overriding its RON behaviours.
    pub fn actor_follow_cursor(&mut self, id: &str, speed: f32, trail: f32) {
        actor_follow_cursor_into(&mut self.persistent, id, speed, trail);
    }

    /// Clear any programmatic override on an actor, returning it to its RON behaviours.
    pub fn actor_reset(&mut self, id: &str) {
        actor_reset_into(&mut self.persistent, id);
    }

    /// Teleport an actor to a position instantly, without lerping.
    pub fn actor_set_pos(&mut self, id: &str, x: f32, y: f32) {
        actor_set_pos_into(&mut self.persistent, id, x, y);
    }
}

// ── Mode 3: Headless ─────────────────────────────────────────────────────────

/// A Pane UI instance with no GPU or window — logic, state, and actions only.
///
/// Useful for automated testing, server-side UI state machines, or any context
/// where rendering is not needed. All widget state is maintained and actions are
/// emitted normally; draw calls are discarded.
///
/// Create with [`headless`], then call [`update`](PaneHeadless::update) each tick.
pub struct PaneHeadless {
    persistent: crate::threader::Persistent,
    input: Input,
    scene: Scene,
}

/// Create a [`PaneHeadless`] instance — no GPU required.
///
/// Loads the layout from `path` and initialises all widget state. Styles and textures
/// are stubbed out; only widget logic runs.
///
/// Set `headless_accessible: true` in your root definition to enable [`PaneHeadless::press`].
///
/// # Panics
///
/// Panics if the `.ron` file cannot be read or parsed.
#[must_use]
pub fn headless(path: &str) -> PaneHeadless {
    let menu = load_menu(path);
    let (tx, rx) = mpsc::channel::<UiMsg>();
    let dummy_shader = ShaderId::new(0);

    // Build a dummy StyleMap — headless mode has no GPU so styles are stubs.
    let style_map: StyleMap = crate::styles_reg::BUILTIN_STYLE_NAMES
        .iter()
        .enumerate()
        .map(|(i, name)| {
            (
                name.to_string(),
                (crate::styles::StyleId::new(i), dummy_shader),
            )
        })
        .collect();

    let (roots, active_root) = build_logic(&menu, &style_map, dummy_shader, &mut |_, _| None);

    let default_style = menu
        .default_style
        .as_deref()
        .and_then(|name| style_map.get(name).map(|&(id, _)| id));

    let persistent = crate::threader::Persistent {
        roots,
        active_root,
        tab_pages: std::collections::HashMap::new(),
        nav: crate::logic::NavState::default(),
        styles: StyleRegistry::new(),
        style_map,
        default_style,
        tex_reg: None,
        device: None,
        queue: None,
        renderer: None,
        background: None,
        clear_color: None,
        pending_actions: Vec::new(),
        tx,
        rx,
        ron_path: path.to_string(),
        debug: false,
        headless_accessible: menu.headless_accessible,
        osk: crate::keyboard::OskState::default(),
    };

    PaneHeadless {
        persistent,
        input: Input::new(),
        scene: Scene::new(),
    }
}

impl PaneHeadless {
    /// Advance the UI by `dt` seconds and return any actions emitted this tick.
    ///
    /// Call at a fixed or variable rate. `dt` is in seconds; typical values are
    /// `1.0 / 60.0` for a 60 Hz simulation tick.
    pub fn update(&mut self, dt: f32) -> Vec<PaneAction> {
        self.persistent.pending_actions.clear();

        // Override last_tick so tick_dt produces exactly the requested dt.
        let last_tick = std::time::Instant::now()
            .checked_sub(std::time::Duration::from_secs_f32(dt))
            .unwrap_or_else(std::time::Instant::now);

        let mut frame = crate::threader::Frame {
            dt: 0.0,
            last_tick,
            pw: 0.0,
            ph: 0.0,
            input: std::mem::take(&mut self.input),
            scene: std::mem::take(&mut self.scene),
        };
        {
            let mut ctx = crate::threader::FrameCtx {
                persistent: &mut self.persistent,
                frame: &mut frame,
                standalone_pane: None,
            };
            crate::order::run_frame(&mut ctx, None, None);
        }
        self.input = frame.input;
        self.scene = frame.scene;

        std::mem::take(&mut self.persistent.pending_actions)
    }

    /// Simulate pressing a button by id.
    ///
    /// Only works if `headless_accessible: true` is set in the root definition.
    /// Fires the button's action as if the user clicked it.
    pub fn press(&mut self, id: &str) {
        if !self.persistent.headless_accessible {
            eprintln!("[pane_ui] press('{id}') ignored — headless_accessible is false");
            return;
        }
        let tx = self.persistent.tx.clone();
        let debug = self.persistent.debug;
        let Some(name) = self.persistent.active_root.clone() else {
            eprintln!("[pane_ui] press('{id}'): no active root");
            return;
        };
        if let Some(root) = self.persistent.roots.get_mut(&name) {
            let found = root.items.iter_mut().any(|(item, state)| {
                use crate::items::UiItem;
                use crate::widgets::ItemState;
                if let (UiItem::Toggle(t), ItemState::Toggle(s)) = (&*item, state)
                    && t.id == id
                {
                    {
                        s.checked = !s.checked;
                        match &t.action {
                            crate::loader::ToggleAction::Custom(tag) => {
                                let _ =
                                    tx.send(crate::loader::UiMsg::Toggle(tag.clone(), s.checked));
                            }
                            crate::loader::ToggleAction::Print => {
                                println!("{}: {}", t.id, s.checked);
                            }
                        }
                        return true;
                    }
                }
                crate::logic::press_in_item(&tx, item, id, debug)
            });
            if !found {
                eprintln!("[pane_ui] press('{id}'): no button found");
            }
        }
    }

    /// Returns the name of the currently active root, or `None` if none has been set.
    pub fn active_root(&self) -> Option<&str> {
        self.persistent.active_root.as_deref()
    }

    // ── Read ──────────────────────────────────────────────────────────────────

    /// Returns the item data and its current visual state for any widget by id.
    ///
    /// Same as [`PaneOverlay::read`] — pattern-match on `UiItem` to get widget fields.
    pub fn read(&self, id: &str) -> Option<(&crate::items::UiItem, crate::widgets::WidgetState)> {
        read_into(&self.persistent, id)
    }

    // ── Write / Set ───────────────────────────────────────────────────────────

    /// Set a widget's value programmatically.
    ///
    /// See [`WriteValue`] for the supported widget types and their matching variants.
    /// Mismatched types and unknown ids are logged and ignored.
    pub fn write(&mut self, id: &str, value: &WriteValue) {
        write_into(&mut self.persistent, id, value);
    }

    // ── Create / Destroy ──────────────────────────────────────────────────────

    /// Add a code-built widget to a named root. Returns `false` if the id is already
    /// in use or the root doesn't exist.
    pub fn create(&mut self, root: &str, builder: impl crate::build::WidgetBuilder) -> bool {
        create_into(&mut self.persistent, root, builder)
    }

    /// Remove a widget by id from any root. Returns `true` if a widget was removed.
    pub fn destroy(&mut self, id: &str) -> bool {
        destroy_into(&mut self.persistent, id)
    }

    /// Create an empty root that can be populated with [`Self::create`].
    pub fn create_root(&mut self, name: impl Into<String>) {
        create_root_into(&mut self.persistent, name);
    }

    /// Resolve a style name to its `StyleId` for use with builders.
    #[must_use]
    pub fn style_id(&self, name: &str) -> Option<crate::styles::StyleId> {
        style_id_in(&self.persistent, name)
    }

    /// Returns the name of the current default style, if one is set.
    #[must_use]
    pub fn default_style(&self) -> Option<&str> {
        default_style_in(&self.persistent)
    }

    /// Switch the default style by name. Returns `false` if the name is not registered.
    pub fn set_default_style(&mut self, name: &str) -> bool {
        set_default_style_in(&mut self.persistent, name)
    }

    /// Enable or disable debug message logging (no-op in headless mode, but
    /// kept for API symmetry with [`PaneOverlay::set_debug`]).
    pub const fn set_debug(&mut self, on: bool) {
        self.persistent.debug = on;
    }

    // ── Toast ─────────────────────────────────────────────────────────────────

    /// Spawn a transient toast notification.
    ///
    /// In headless mode toasts are tracked but not rendered.
    pub fn push_toast(
        &mut self,
        message: impl Into<String>,
        duration: f32,
        x: f32,
        y: f32,
        width: f32,
        height: f32,
    ) {
        push_toast_into(
            &mut self.persistent,
            message.into(),
            duration,
            x,
            y,
            width,
            height,
        );
    }

    // ── Actor API ─────────────────────────────────────────────────────────────

    /// Programmatically send an actor to a fixed position, overriding its RON behaviours.
    pub fn actor_move_to(&mut self, id: &str, x: f32, y: f32, speed: f32) {
        actor_move_to_into(&mut self.persistent, id, x, y, speed);
    }

    /// Programmatically make an actor follow the cursor, overriding its RON behaviours.
    pub fn actor_follow_cursor(&mut self, id: &str, speed: f32, trail: f32) {
        actor_follow_cursor_into(&mut self.persistent, id, speed, trail);
    }

    /// Clear any programmatic override on an actor, returning it to its RON behaviours.
    pub fn actor_reset(&mut self, id: &str) {
        actor_reset_into(&mut self.persistent, id);
    }

    /// Teleport an actor to a position instantly, without lerping.
    pub fn actor_set_pos(&mut self, id: &str, x: f32, y: f32) {
        actor_set_pos_into(&mut self.persistent, id, x, y);
    }
}