facett_core/

lib.rs

//! **facett-core** — the visual kernel. Render a node/edge **`Scene`** into egui.
//! Source-agnostic: build a `Scene` from anything (Arrow rows, a graph, a DAG),
//! hand it here, get pixels. The CPU painter is the reference; a **wgpu** fast
//! path (GPU viewport-cull + indirect draw, seeded from katana-osm's
//! `osm-viewer`) lands behind this same `draw()` call — consumers don't change.

use egui::{Align2, Color32, FontId, Pos2, Rect, Sense, Stroke, Ui, vec2};

pub mod a11y;
pub mod caps;
pub mod clip;
pub mod clipboard;
pub mod deckfx;
pub mod edges;
pub mod effects;
pub mod focus;
pub mod labels3d;
pub mod harness;
pub mod look;
pub mod nav;
pub mod overlay;
pub mod rabbit;
pub mod scroll_engine;
pub mod testmatrix; // functional-status → nornir test-matrix bridge (feature
                    // `testmatrix`); no-op in release.
pub mod theme;
pub mod trace; // structured IN/OUT/END event stream ($FACETT_TRACE) — the
               // machine-readable data a facet actually rendered.
pub use a11y::{Semantics, node as a11y_node, stable_id};
pub use caps::FacetCaps;
pub use clip::{ArrowColumnRef, ClipKind, ClipPayload, CopySource, PasteTarget};
pub use clipboard::ClipAction;
pub use deckfx::{DeckFx, DeckRaven};
pub use look::{Action, KeyMap, Palette};
pub use nav::{Dir4, Navigable, nearest_in_direction};
pub use rabbit::{Rabbit, RabbitMesh, rabbit_mesh, rabbit_outline};
pub use scroll_engine::SmoothScroll;
pub use theme::{Theme, set_theme, theme};

// The rich look-&-feel `Theme` (the work-order architecture) is re-exported under
// an unambiguous alias so it coexists with the legacy flat palette `Theme` above.
pub use look::Theme as LookTheme;

/// A node: a label + a colour (the *consumer* picks the colour policy — hash by
/// label, by status, …).
#[derive(Clone)]
pub struct Node {
    pub label: String,
    pub color: Color32,
}

/// A directed edge between node indices.
#[derive(Clone, Copy)]
pub struct Edge {
    pub src: usize,
    pub dst: usize,
}

/// A drawable graph: nodes + edges (edges index into `nodes`).
#[derive(Default, Clone)]
pub struct Scene {
    pub nodes: Vec<Node>,
    pub edges: Vec<Edge>,
}

impl Scene {
    pub fn new() -> Self {
        Self::default()
    }
    /// Push a node, returning its index.
    pub fn node(&mut self, label: impl Into<String>, color: Color32) -> usize {
        self.nodes.push(Node { label: label.into(), color });
        self.nodes.len() - 1
    }
    pub fn edge(&mut self, src: usize, dst: usize) {
        self.edges.push(Edge { src, dst });
    }
    pub fn is_empty(&self) -> bool {
        self.nodes.is_empty()
    }
}

/// Node placement strategy.
#[derive(Clone, Copy, PartialEq, Eq, Default)]
pub enum Layout {
    #[default]
    Circular,
    /// Deterministic Fruchterman–Reingold (edges pull, all nodes repel). O(n²)
    /// per iteration — best for small/medium graphs.
    Force,
}

/// Draw a `Scene` into `ui` — the reusable render primitive. Empty scenes show
/// `empty_hint`. Labels render when the node count is small enough to read.
pub fn draw(ui: &mut Ui, scene: &Scene, layout: Layout, empty_hint: &str) {
    let (rect, _) = ui.allocate_exact_size(ui.available_size(), Sense::hover());
    let th = theme(ui);
    let painter = ui.painter_at(rect);
    let n = scene.nodes.len();
    if n == 0 {
        painter.text(rect.center(), Align2::CENTER_CENTER, empty_hint, FontId::proportional(13.0), th.text_dim);
        return;
    }
    let pos = positions(layout, scene, rect);
    for e in &scene.edges {
        if e.src < n && e.dst < n {
            painter.line_segment([pos[e.src], pos[e.dst]], Stroke::new(0.6, th.edge));
        }
    }
    for (i, node) in scene.nodes.iter().enumerate() {
        painter.circle_filled(pos[i], 5.0, node.color);
    }
    if n <= 60 {
        for (i, node) in scene.nodes.iter().enumerate() {
            painter.text(pos[i] + vec2(7.0, 0.0), Align2::LEFT_CENTER, &node.label, FontId::proportional(10.0), th.text);
        }
    }
}

fn positions(layout: Layout, scene: &Scene, rect: Rect) -> Vec<Pos2> {
    let n = scene.nodes.len();
    let center = rect.center();
    let radius = rect.size().min_elem() * 0.42;
    let circular = |i: usize| {
        let a = std::f32::consts::TAU * (i as f32) / (n as f32);
        vec2(a.cos(), a.sin())
    };
    match layout {
        Layout::Circular => (0..n).map(|i| center + radius * circular(i)).collect(),
        Layout::Force => {
            // Deterministic Fruchterman–Reingold from a circular seed (unit space).
            let mut p: Vec<egui::Vec2> = (0..n).map(circular).collect();
            let k = (1.0 / (n.max(1) as f32).sqrt()).clamp(0.05, 1.0);
            for _ in 0..120 {
                let mut disp = vec![egui::Vec2::ZERO; n];
                for i in 0..n {
                    for j in (i + 1)..n {
                        let d = p[i] - p[j];
                        let dist = d.length().max(1e-3);
                        let f = k * k / dist;
                        let dir = d / dist;
                        disp[i] += dir * f;
                        disp[j] -= dir * f;
                    }
                }
                for e in &scene.edges {
                    if e.src < n && e.dst < n {
                        let d = p[e.src] - p[e.dst];
                        let dist = d.length().max(1e-3);
                        let f = dist * dist / k;
                        let dir = d / dist;
                        disp[e.src] -= dir * f;
                        disp[e.dst] += dir * f;
                    }
                }
                for i in 0..n {
                    let dl = disp[i].length().max(1e-3);
                    p[i] += disp[i] / dl * dl.min(0.04); // capped step (cooling-free, deterministic)
                }
            }
            // Normalise to fit the rect.
            let (mut mn, mut mx) = (egui::vec2(f32::MAX, f32::MAX), egui::vec2(f32::MIN, f32::MIN));
            for v in &p {
                mn.x = mn.x.min(v.x);
                mn.y = mn.y.min(v.y);
                mx.x = mx.x.max(v.x);
                mx.y = mx.y.max(v.y);
            }
            let span = (mx - mn).max(egui::vec2(1e-3, 1e-3));
            p.iter()
                .map(|v| center + egui::vec2(((v.x - mn.x) / span.x - 0.5) * 2.0 * radius, ((v.y - mn.y) / span.y - 0.5) * 2.0 * radius))
                .collect()
        }
    }
}

/// The facett **component contract**. Every facet — graph, map, pipeline, table,
/// the ported nornir viewers — implements this, so consumers (korp, nornir, …)
/// compose them uniformly *and* get headless robot-testing for free.
///
/// The three things a component owes its host:
/// 1. a **title** (tab label / panel heading),
/// 2. how to **draw** itself into egui,
/// 3. its **observable state** as JSON — dumped to `$APP_STATE` for headless
///    assertions. **Rule:** every visible list/status/count goes in `state_json`.
pub trait Facet {
    fn title(&self) -> &str;
    fn ui(&mut self, ui: &mut Ui);
    fn state_json(&self) -> serde_json::Value;

    // --- uniform capability surface (all defaulted; see caps.rs / clipboard.rs) ---

    /// What this facet can do. Override to opt into capabilities.
    fn caps(&self) -> FacetCaps {
        FacetCaps::NONE
    }

    /// Current uniform scale (1.0 = native). Override if `caps().scalable`.
    fn scale(&self) -> f32 {
        1.0
    }
    /// Set the uniform scale; clamp internally. Default no-op (not scalable).
    fn set_scale(&mut self, _scale: f32) {}

    /// The current selection as JSON (also folded into `state_json` by
    /// convention). `Null` when nothing/none selectable.
    fn selection_json(&self) -> serde_json::Value {
        serde_json::Value::Null
    }

    /// Clipboard hooks — see clipboard.rs. Defaults: nothing to give/take.
    /// Returns the text to place on the clipboard (None = nothing copyable now).
    fn copy(&mut self) -> Option<String> {
        None
    }
    /// Like `copy`, but also removes the selection. Default delegates to `copy`.
    fn cut(&mut self) -> Option<String> {
        self.copy()
    }
    /// Accept pasted text. Returns true if consumed.
    fn paste(&mut self, _text: &str) -> bool {
        false
    }

    /// Optional downcast handle for hosts that need typed access to a specific
    /// facet living inside a [`FacetDeck`] (e.g. a robot-UI driver clicking an
    /// app-level control that must forward to a concrete component's own API).
    /// Defaulted to `None` so no existing facet has to change; a component opts in
    /// by returning `Some(self)`.
    fn as_any_mut(&mut self) -> Option<&mut dyn std::any::Any> {
        None
    }
}

/// A tabbed set of [`Facet`]s — the reusable multi-component shell. Draws a tab
/// bar + the active facet, and composes **every** facet's `state_json` under its
/// title, so the whole-app introspection contract is free. korp/nornir can build
/// their window from a `FacetDeck` instead of hand-rolling tabs + the state dump.
pub struct FacetDeck {
    facets: Vec<Box<dyn Facet>>,
    active: usize,
    /// Opt-in deck effects (palette override + glow). `Default` = all off, so a
    /// deck that never opts in is unchanged and pays nothing.
    fx: DeckFx,
    /// A raven summoned through the deck, in flight or perched (or `None`).
    raven: Option<DeckRaven>,
}

impl FacetDeck {
    pub fn new(facets: Vec<Box<dyn Facet>>) -> Self {
        Self { facets, active: 0, fx: DeckFx::OFF, raven: None }
    }
    pub fn active(&self) -> usize {
        self.active
    }

    /// The title of the currently-active facet (the deck's `state_json["active"]`),
    /// or `None` if the deck is empty.
    pub fn active_title(&self) -> Option<&str> {
        self.facets.get(self.active).map(|f| f.title())
    }

    /// The titles of every tabbed facet, in tab order — the discoverable surface a
    /// host (or a robot-UI control channel) enumerates to know which tabs exist.
    pub fn titles(&self) -> Vec<&str> {
        self.facets.iter().map(|f| f.title()).collect()
    }

    /// Make the facet titled `title` the active tab — the programmatic (headless,
    /// robot-addressable) equivalent of clicking its tab header. Returns `true` if a
    /// facet with that title exists (and is now active), `false` otherwise. This is
    /// the named boundary a control channel switches tabs through (the deck analogue
    /// of the viz's `Tab::from_name`), so a driver needn't replay a pointer click.
    pub fn set_active_by_title(&mut self, title: &str) -> bool {
        match self.facets.iter().position(|f| f.title() == title) {
            Some(i) => {
                self.active = i;
                true
            }
            None => false,
        }
    }

    /// Typed mutable access to the facet with `title`, downcast to `T` — `None` if
    /// no such facet, or it doesn't opt into [`Facet::as_any_mut`], or the type
    /// mismatches. Lets a host drive a concrete component's own API (e.g. a
    /// robot-UI control forwarding a node selection to a `SystemChart`).
    pub fn facet_mut<T: std::any::Any>(&mut self, title: &str) -> Option<&mut T> {
        self.facets
            .iter_mut()
            .find(|f| f.title() == title)
            .and_then(|f| f.as_any_mut())
            .and_then(|a| a.downcast_mut::<T>())
    }

    /// Replace the facet whose `title` matches with `facet` (the box's own title is
    /// what the deck enumerates afterwards). Returns `true` if a facet was replaced.
    /// Used by hosts that **reload** a tab's data in place — e.g. the OSM region
    /// picker rebuilds the `OSM 2D` / `OSM 3D` views from a freshly clipped region
    /// and swaps them in, keeping the same tab slots (and the active selection).
    pub fn replace_facet(&mut self, title: &str, facet: Box<dyn Facet>) -> bool {
        if let Some(slot) = self.facets.iter_mut().find(|f| f.title() == title) {
            *slot = facet;
            true
        } else {
            false
        }
    }

    // ── opt-in effects + theming (see deckfx.rs) ─────────────────────────────

    /// Enable deck effects up front (builder form of [`fx_mut`](Self::fx_mut)).
    pub fn with_fx(mut self, fx: DeckFx) -> Self {
        self.fx = fx;
        self
    }
    /// The current deck-effects config (read-only).
    pub fn fx(&self) -> &DeckFx {
        &self.fx
    }
    /// Mutate the deck-effects config (toggle glow, pin a palette, …).
    pub fn fx_mut(&mut self) -> &mut DeckFx {
        &mut self.fx
    }
    /// Override the deck theme with palette index `i` (wraps); enables the
    /// override. Convenience over `fx_mut().set_palette(i)`.
    pub fn set_palette(&mut self, i: usize) {
        self.fx.set_palette(i);
    }
    /// Advance to the next palette in [`Theme::ALL`] (wrapping); returns the new
    /// index. Convenience over `fx_mut().cycle_palette()`.
    pub fn cycle_palette(&mut self) -> usize {
        self.fx.cycle_palette()
    }

    /// **Summon the raven** to perch on `target` — any rect a facet/host hands us
    /// (a table row, a node, a header). Replaces any raven already in flight. The
    /// body is tinted from the deck's current palette (or the host theme). Logs an
    /// activity trail entry. Drive/paint happens automatically inside
    /// [`ui`](Self::ui).
    pub fn send_raven(&mut self, target: Rect) {
        let theme = self.effective_theme();
        self.raven = Some(DeckRaven::new(target, &theme));
        harness::trail(
            harness::Kind::Render,
            format!("raven launched → perch ({:.0},{:.0})", target.center().x, target.top()),
        );
    }
    /// True while a raven is present (flying or perched).
    pub fn has_raven(&self) -> bool {
        self.raven.is_some()
    }
    /// True once the summoned raven has landed (false if none).
    pub fn raven_perched(&self) -> bool {
        self.raven.as_ref().map(|r| r.is_perched()).unwrap_or(false)
    }
    /// Dismiss any raven.
    pub fn clear_raven(&mut self) {
        self.raven = None;
    }

    /// The theme the deck paints with: the fx palette override if set, else
    /// [`Theme::default`] (the host's own `set_theme` still applies its visuals;
    /// this is just the colour source for deck-owned effects/picker).
    fn effective_theme(&self) -> Theme {
        self.fx.theme().unwrap_or_default()
    }

    /// Draw a one-line **palette picker** — a switcher over [`Theme::ALL`] the
    /// host can place anywhere (toolbar, menu). Selecting a palette pins the fx
    /// override; `ui()` then applies it each frame. Returns the chosen index if it
    /// changed this frame.
    ///
    /// The override stays **off until the user actually clicks** a palette: merely
    /// drawing the picker must not pin index 0, otherwise a host that drives its
    /// own theme (e.g. the rich [`crate::look::Theme`]) would be silently clobbered
    /// every frame by the legacy `set_theme` in [`ui`](Self::ui) — size still
    /// changing (spacing) but colour frozen on `Theme::ALL[0]`. So we only pin when
    /// the selection genuinely changed this frame.
    pub fn palette_picker(&mut self, ui: &mut Ui) -> Option<usize> {
        let mut sel = self.fx.palette().unwrap_or(0);
        let before = sel;
        ui.horizontal_wrapped(|ui| {
            ui.label("Palette:");
            for (i, ctor) in Theme::ALL.iter().enumerate() {
                ui.selectable_value(&mut sel, i, ctor().name);
            }
        });
        if sel != before {
            self.fx.set_palette(sel);
        }
        (sel != before).then_some(sel)
    }

    /// The capabilities of the currently-active facet (or `NONE` if empty).
    pub fn active_caps(&self) -> FacetCaps {
        self.facets.get(self.active).map(|f| f.caps()).unwrap_or(FacetCaps::NONE)
    }

    /// The active facet's current scale (1.0 if none / not scalable).
    fn active_scale(&self) -> f32 {
        self.facets.get(self.active).map(|f| f.scale()).unwrap_or(1.0)
    }

    /// Multiply the active facet's scale by `k`, clamped to a sane range.
    fn scale_active(&mut self, k: f32) {
        if let Some(f) = self.facets.get_mut(self.active) {
            let s = (f.scale() * k).clamp(0.25, 4.0);
            f.set_scale(s);
        }
    }

    /// Reset the active facet's scale to native.
    fn reset_scale(&mut self) {
        if let Some(f) = self.facets.get_mut(self.active) {
            f.set_scale(1.0);
        }
    }

    /// Draw the tab bar + capability toolbar + the active facet, and route
    /// capability-gated shortcuts (Ctrl-+/-/0 for scale; Ctrl-C/X/V for clipboard).
    pub fn ui(&mut self, ui: &mut Ui) {
        // Opt-in palette override: apply the chosen Theme::ALL palette + its
        // egui Visuals each frame so the whole deck (and every facet that reads
        // `theme(ui)`) follows. No override → the host's own theme stays.
        if let Some(theme) = self.fx.theme() {
            set_theme(ui.ctx(), theme);
        }

        let titles: Vec<String> = self.facets.iter().map(|f| f.title().to_string()).collect();
        // Wrap the tab bar: with many facets a single non-wrapping row overflows
        // the panel width and the trailing tabs become unreachable (off-screen,
        // unclickable for a robot driver / pointer). Wrapping keeps every tab
        // visible + clickable no matter how many facets the deck holds.
        ui.horizontal_wrapped(|ui| {
            for (i, t) in titles.iter().enumerate() {
                ui.selectable_value(&mut self.active, i, t);
            }
        });

        let caps = self.active_caps();

        // Capability-driven toolbar: only show controls the active facet honors.
        if caps.scalable {
            ui.horizontal(|ui| {
                if ui.button("−").on_hover_text("Zoom out (Ctrl-−)").clicked() {
                    self.scale_active(1.0 / 1.1);
                }
                ui.label(format!("{:.0}%", self.active_scale() * 100.0));
                if ui.button("+").on_hover_text("Zoom in (Ctrl-+)").clicked() {
                    self.scale_active(1.1);
                }
                if ui.button("Reset").on_hover_text("Reset zoom (Ctrl-0)").clicked() {
                    self.reset_scale();
                }
            });
        }

        // Capability-gated scale shortcuts. egui has no semantic event for these,
        // so we hand-detect the key combos (clipboard uses semantic events below).
        if caps.scalable {
            let (cmd, plus, minus, zero) = ui.input(|i| {
                (
                    i.modifiers.command,
                    i.key_pressed(egui::Key::Plus) || i.key_pressed(egui::Key::Equals),
                    i.key_pressed(egui::Key::Minus),
                    i.key_pressed(egui::Key::Num0),
                )
            });
            if cmd {
                if plus {
                    self.scale_active(1.1);
                }
                if minus {
                    self.scale_active(1.0 / 1.1);
                }
                if zero {
                    self.reset_scale();
                }
            }
        }

        // Clipboard routing: drain semantic events and dispatch to the active
        // facet, gated by its caps. A focused TextEdit already consumed its own.
        self.route_clipboard(ui.ctx());

        ui.separator();
        // Render the active facet, capturing the rect it occupied so the deck can
        // bloom it (opt-in glow) without the facet knowing.
        let content = ui.scope(|ui| {
            if let Some(f) = self.facets.get_mut(self.active) {
                f.ui(ui);
            }
        });
        let content_rect = content.response.rect;

        // Opt-in glow on the active facet's content rect, pulsing.
        if self.fx.glow && content_rect.is_positive() {
            let theme = self.effective_theme();
            let time = ui.input(|i| i.time);
            let painter = ui.painter_at(content_rect);
            deckfx::paint_active_glow(&painter, content_rect.shrink(2.0), &theme, &self.fx, time);
            ui.ctx().request_repaint(); // keep the pulse animating
        }

        // Drive + paint a summoned raven on a foreground layer above everything.
        self.drive_raven(ui.ctx());
    }

    /// Advance + paint the summoned raven (if any) on a foreground layer. Pins its
    /// launch time on the first frame and keeps repainting while it flies.
    fn drive_raven(&mut self, ctx: &egui::Context) {
        let Some(raven) = self.raven.as_mut() else { return };
        raven.sprite.update(ctx);
        let painter =
            ctx.layer_painter(egui::LayerId::new(egui::Order::Foreground, egui::Id::new("facett_deck_raven")));
        raven.sprite.paint(&painter);
    }

    /// Route this frame's clipboard events to the active facet, gated by caps.
    /// The single OS-touching write (`clipboard::put`) lives here.
    fn route_clipboard(&mut self, ctx: &egui::Context) {
        let caps = self.active_caps();
        if !(caps.copyable || caps.cuttable || caps.pasteable) {
            return;
        }
        for action in clipboard::poll(ctx) {
            let Some(f) = self.facets.get_mut(self.active) else { continue };
            match action {
                ClipAction::Copy if caps.copyable => {
                    if let Some(t) = f.copy() {
                        clipboard::put(ctx, t);
                    }
                }
                ClipAction::Cut if caps.cuttable => {
                    if let Some(t) = f.cut() {
                        clipboard::put(ctx, t);
                    }
                }
                ClipAction::Paste(s) if caps.pasteable => {
                    f.paste(&s);
                }
                // Capability not declared → ignore (event may belong to a focused
                // sub-widget egui already handled).
                _ => {}
            }
        }
    }

    /// The whole-app observable state: the active facet + each facet's
    /// `state_json`, plus an **additive** sibling `caps` map (title → caps JSON)
    /// so the existing flat `facets[title]` shape is unchanged for consumers.
    pub fn state_json(&self) -> serde_json::Value {
        let mut facets = serde_json::Map::new();
        let mut caps = serde_json::Map::new();
        for f in &self.facets {
            facets.insert(f.title().to_string(), f.state_json());
            caps.insert(f.title().to_string(), f.caps().to_json());
        }
        serde_json::json!({
            "active": self.facets.get(self.active).map(|f| f.title()),
            "facets": facets,
            "caps": caps,
        })
    }
}

/// A stable, bright-ish colour from a string (FNV-1a). Handy default node colour.
pub fn hash_color(s: &str) -> Color32 {
    let mut h: u32 = 2166136261;
    for b in s.bytes() {
        h = (h ^ b as u32).wrapping_mul(16777619);
    }
    Color32::from_rgb((h & 0xFF) as u8 | 0x60, ((h >> 8) & 0xFF) as u8 | 0x60, ((h >> 16) & 0xFF) as u8 | 0x60)
}

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

    #[test]
    fn scene_builds() {
        let mut s = Scene::new();
        let a = s.node("Person", hash_color("Person"));
        let b = s.node("Company", hash_color("Company"));
        s.edge(a, b);
        assert_eq!(s.nodes.len(), 2);
        assert_eq!(s.edges.len(), 1);
        assert!(!s.is_empty());
    }

    #[test]
    fn force_layout_produces_finite_bounded_positions() {
        let mut scene = Scene::new();
        for i in 0..12 { scene.node(format!("n{i}"), hash_color("n")); }
        for i in 0..12 { scene.edge(i, (i + 1) % 12); }
        let rect = egui::Rect::from_min_size(egui::pos2(0.0, 0.0), egui::vec2(400.0, 400.0));
        let pos = positions(Layout::Force, &scene, rect);
        assert_eq!(pos.len(), 12);
        for p in &pos {
            assert!(p.x.is_finite() && p.y.is_finite(), "finite");
            assert!(rect.expand(50.0).contains(*p), "roughly within the rect");
        }
    }

    #[test]
    fn hash_color_is_stable() {
        assert_eq!(hash_color("Person"), hash_color("Person"));
        assert_ne!(hash_color("Person"), hash_color("Company"));
    }

    /// A minimal facet for deck tests.
    struct Stub(&'static str);
    impl Facet for Stub {
        fn title(&self) -> &str {
            self.0
        }
        fn ui(&mut self, ui: &mut Ui) {
            ui.label(self.0);
        }
        fn state_json(&self) -> serde_json::Value {
            serde_json::json!({ "t": self.0 })
        }
    }

    #[test]
    fn deck_fx_is_off_by_default() {
        let deck = FacetDeck::new(vec![Box::new(Stub("a"))]);
        assert_eq!(*deck.fx(), DeckFx::OFF, "no effects until the host opts in");
        assert!(!deck.has_raven());
        assert!(!deck.fx().glow);
        assert!(deck.fx().palette().is_none());
    }

    #[test]
    fn deck_cycle_palette_walks_theme_all() {
        let mut deck = FacetDeck::new(vec![Box::new(Stub("a"))]);
        let first = deck.cycle_palette();
        assert_eq!(first, 0);
        assert_eq!(deck.fx().theme().map(|t| t.name), Some(Theme::ALL[0]().name));
        // walks forward and wraps
        for _ in 1..Theme::ALL.len() {
            deck.cycle_palette();
        }
        assert_eq!(deck.cycle_palette(), 0, "wraps back to the first palette");
    }

    #[test]
    fn deck_send_raven_launches_and_perches_after_a_full_flight() {
        use crate::effects::RAVEN_FLIGHT_SECS;
        let mut deck = FacetDeck::new(vec![Box::new(Stub("rows"))]);
        assert!(!deck.has_raven());
        let target = egui::Rect::from_min_size(egui::pos2(120.0, 80.0), egui::vec2(200.0, 28.0));
        deck.send_raven(target);
        assert!(deck.has_raven(), "raven summoned");
        assert!(!deck.raven_perched(), "not perched at launch");

        // Drive the sprite headlessly past the flight duration → it perches.
        if let Some(r) = deck.raven.as_mut() {
            r.sprite.advance(RAVEN_FLIGHT_SECS + 0.1);
        }
        assert!(deck.raven_perched(), "perched after the flight duration");

        deck.clear_raven();
        assert!(!deck.has_raven());
    }

    /// REGRESSION (inject-assert): merely *drawing* the palette picker without a
    /// user click must NOT pin a palette override. The bug: the picker auto-pinned
    /// index 0 on the first passive frame, turning the legacy `set_theme` override
    /// permanently on and clobbering a host's own theme (the rich `look::Theme`)
    /// every frame. We render one frame with no interaction and assert the override
    /// is still `None` (host theme wins).
    #[test]
    fn palette_picker_does_not_pin_without_a_user_click() {
        let mut deck = FacetDeck::new(vec![Box::new(Stub("a"))]);
        assert!(deck.fx().palette().is_none(), "starts with no override");
        let ctx = egui::Context::default();
        let mut chosen = Some(7usize);
        let _ = ctx.run(egui::RawInput::default(), |ctx| {
            egui::CentralPanel::default().show(ctx, |ui| {
                // No synthetic click is fed → the picker is drawn but not used.
                chosen = deck.palette_picker(ui);
            });
        });
        assert_eq!(chosen, None, "drawing the picker reports no selection without a click");
        assert!(
            deck.fx().palette().is_none(),
            "drawing the picker must not pin index 0 — that would clobber the host's own theme each frame"
        );
    }

    #[test]
    fn deck_palette_override_applies_theme_in_a_ui_pass() {
        let mut deck = FacetDeck::new(vec![Box::new(Stub("a"))]);
        deck.set_palette(1); // sci-fi
        let ctx = egui::Context::default();
        let mut seen = "";
        let _ = ctx.run(egui::RawInput::default(), |ctx| {
            egui::CentralPanel::default().show(ctx, |ui| {
                deck.ui(ui);
                seen = theme(ui).name;
            });
        });
        assert_eq!(seen, Theme::ALL[1]().name, "deck applied its palette override");
    }
}