blockworx/panels/

nav_tree.rs

//! The Hierarchy segment of the [navigator](crate::shell::navigator). A
//! filter box over a tree view of the whole document: expanding a row
//! reveals its child blocks; selecting a row selects that block on the
//! canvas (navigating the canvas to the block's own level first).
//!
//! The segment keeps the name of what the tree holds. A parts list would be
//! an assembly tree of parts and subassemblies with instance counts; every
//! row here is a block with its own id — blockworx has no instancing, so
//! there is nothing to count and no parts list to browse, and what the tree
//! shows is containment.
//!
//! Three mechanisms make a deep tree workable in a narrow panel:
//!
//! 1. **Focus re-roots.** A branch row carries `»`, and answers a
//!    double-click, by redrawing the tree from that node with a breadcrumb
//!    above it. Indentation resets, so a name's width does not depend on how
//!    deep it really is.
//! 2. **The filter flattens.** While filtering, matches are a flat list with
//!    their ancestor path beneath each, truncated from the *left* so the
//!    immediate parent survives. Ancestors are never rows of their own —
//!    three matches would become fifteen rows of context. The filter reads
//!    the whole document, crossing the focus boundary.
//! 3. **Reveal from canvas.** Selecting geometry opens every ancestor of the
//!    block, moves the cursor onto it and scrolls it into view — dropping a
//!    focus that would otherwise hide it.
//!
//! Leaf counts on closed branches are here; instance counts (`×4`) have
//! nothing to count.
//!
//! Not built: sticky ancestor headers while scrolling deep.

use crate::canvas::convert::IntoEgui as _;
use std::collections::HashSet;

use crate::{
    kernel::NavTree,
    path::Scope,
    theme::{Role, Theme, accent_role},
    tools::tool::Action,
};
use blockworx_doc::id::BlockId;
use blockworx_kernel::nav::{self, Filtered, Index, Row};

/// Horizontal step per tree depth, in pixels.
const INDENT: f32 = 16.0;
/// Width of the chevron/twisty column. Always reserved — even for childless
/// blocks — so leaf labels line up with their expandable siblings.
const GUTTER: f32 = 16.0;
/// Height of one tree row, in pixels.
const ROW_H: f32 = 22.0;
/// Extra height a filtered row takes for the ancestor path under its label.
const PATH_H: f32 = 13.0;
/// The glyph a branch row carries to re-root the tree on itself.
/// Latin-1, so no font this app ships can fail to draw it.
const FOCUS: &str = "\u{bb}";
/// Half-extent of the little expand/collapse triangle.
const TRI: f32 = 4.0;
/// Padding between the gutter and the label.
const LABEL_PAD: f32 = 4.0;
/// The column the row's own dot sits in, between the twisty and the label,
/// and the dot's radius. A directory tree's rows each wear one, and it is
/// where the guide from the parent arrives.
const DOT_COLUMN: f32 = 10.0;
const DOT: f32 = 3.0;

/// A row's disclosure triangle: pointing down (children shown) or right.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Twisty {
    Open,
    Closed,
}

/// What the navigator renders against: the session's tree — every block,
/// the canvas's current path, and the blocks selected on it — and the theme
/// a row's dot gets its colour from, resolved the same way the canvas
/// resolves it, so the tree and the drawing name one thing one colour.
#[derive(Clone, Copy)]
pub struct NavScene<'a> {
    pub tree: &'a NavTree,
    pub theme: &'a Theme,
}

/// The panel's body, drawn into whatever `ui` the workspace gives it: the
/// filter box over the tree. Returns the navigation [`Action`] a click or a
/// keystroke produced.
pub fn body(ui: &mut egui::Ui, scene: NavScene<'_>) -> Option<Action> {
    let ctx = ui.ctx().clone();
    // Substring-matches block labels anywhere in the hierarchy. Stateless
    // here, so it persists in egui's temp data store frame to frame.
    let filter_id = nav_filter_id();
    let mut filter: String = ctx.data_mut(|d| d.get_temp::<String>(filter_id).unwrap_or_default());
    ui.add(
        egui::TextEdit::singleline(&mut filter)
            .id(filter_id)
            .hint_text("Search all blocks\u{2026}")
            .desired_width(f32::INFINITY),
    );
    ctx.data_mut(|d| d.insert_temp(filter_id, filter.clone()));
    ui.separator();
    tree_view(ui, scene, &filter)
}

/// The persistent expand/collapse set and keyboard cursor ids for the tree.
fn tree_ids() -> (egui::Id, egui::Id) {
    (
        egui::Id::new("nav_tree_expanded"),
        egui::Id::new("nav_tree_cursor"),
    )
}

/// Which block the tree is currently re-rooted on. Panel state,
/// like the filter and the expand set, so it survives a frame without the
/// editor holding a field for it.
fn focus_id() -> egui::Id {
    egui::Id::new("nav_tree_focus")
}

/// Render the document tree and return the navigation [`Action`] it produced.
/// Rows are laid out depth-first from whatever the tree is focused on;
/// branches carry a twisty and a `»`, and every block — leaf or branch — is
/// selectable. A non-empty `filter` flattens the tree to its matches
/// wherever in the document they live.
fn tree_view(ui: &mut egui::Ui, scene: NavScene<'_>, filter: &str) -> Option<Action> {
    let NavScene { tree, theme } = scene;
    let (path, selected) = (&tree.path, tree.selected.as_slice());
    let ctx = ui.ctx().clone();
    let (expanded_id, cursor_id) = tree_ids();
    let mut expanded: HashSet<BlockId> =
        ctx.data_mut(|d| d.get_temp(expanded_id).unwrap_or_default());
    let mut cursor: Option<BlockId> = ctx.data_mut(|d| d.get_temp::<BlockId>(cursor_id));
    let mut focus: Option<BlockId> = ctx.data_mut(|d| d.get_temp::<BlockId>(focus_id()));
    // The tree is keyboard-driven while the pointer is over it. egui focus on a
    // non-interactive sentinel doesn't survive the tool switch a row-click
    // triggers, so hover is the reliable signal for a side panel.
    let tree_rect = ui.max_rect();
    let keyboard_active = ui.rect_contains_pointer(tree_rect);
    let (filtered, active_filter) = Filtered::of(filter);

    // Parent links, and the blocks whose own labels match the search.
    let index = Index::of(tree, active_filter);

    let mut scroll_to_cursor = false;
    // Follow the canvas: when the selection or the active path
    // changes, open the active block's ancestors, move the cursor onto it and
    // scroll it into view, so the tree always reflects where the canvas is.
    // Edge-triggered off a stored signature so it never fights the user's own
    // expand/collapse frame to frame.
    let sig_id = egui::Id::new("nav_tree_reveal_sig");
    let signature = (selected.to_vec(), path.segments().to_vec());
    let changed = ctx
        .data_mut(|d| d.get_temp::<(Vec<BlockId>, Vec<BlockId>)>(sig_id))
        .as_ref()
        != Some(&signature);
    if changed {
        // Open the whole active path so the current diagram's contents show.
        for &seg in path.segments() {
            expanded.insert(seg);
        }
        if let Some(target) = selected
            .first()
            .copied()
            .or_else(|| path.segments().last().copied())
        {
            // A focus the target does not live under would hide the row the
            // canvas just asked for, so revealing gives the focus up.
            if focus.is_some_and(|at| !index.under(at, target)) {
                focus = None;
            }
            index.expand_ancestors(Scope::Root, target, &mut expanded);
            cursor = Some(target);
            scroll_to_cursor = true;
        }
        ctx.data_mut(|d| d.insert_temp(sig_id, signature));
    }

    // The breadcrumb, above the tree and belonging to it: the way back
    // out of a focus, one ancestor at a time. Drawn only while focused —
    // an unfocused tree hangs from the document and has nothing to say.
    if let Some(Refocus(to)) = focus.and_then(|at| breadcrumb(ui, tree, &index, at)) {
        focus = to;
    }

    // The filter reads the whole document: it starts from the tree's real
    // root whatever the panel is focused on.
    let root = match filtered {
        Filtered::Yes => Scope::Root,
        Filtered::No => nav::rooted_at(tree, focus),
    };
    let walk = |expanded: &HashSet<BlockId>| index.rows(tree, expanded, root, filtered);
    let mut rows = walk(&expanded);
    if cursor.is_none_or(|c| !rows.iter().any(|r| r.id == c)) {
        cursor = rows.first().map(|r| r.id);
    }

    let mut navigation = None;
    if keyboard_active {
        navigation = KeyNav {
            rows: &rows,
            index: &index,
            top_id: root,
            expanded: &mut expanded,
            cursor: &mut cursor,
            scroll: &mut scroll_to_cursor,
        }
        .handle_keys(&ctx);
        // Expansion may have changed; re-walk so the render matches.
        rows = walk(&expanded);
    }

    let refocus = egui::ScrollArea::both()
        .auto_shrink([false, false])
        .show(ui, |ui| {
            if rows.is_empty() {
                ui.weak(if filtered == Filtered::Yes {
                    "No matches"
                } else {
                    "No blocks"
                });
                return None;
            }

            let font = egui::TextStyle::Body.resolve(ui.style());
            let small = egui::TextStyle::Small.resolve(ui.style());
            // Lay out with a placeholder color so each row can be painted in its
            // own (selected/normal) color via the galley fallback.
            let ink = egui::Color32::PLACEHOLDER;
            let lay = |ui: &egui::Ui, text: String, font: &egui::FontId| {
                ui.painter().layout_no_wrap(text, font.clone(), ink)
            };
            let galleys: Vec<_> = rows
                .iter()
                .map(|r| lay(ui, r.label.clone(), &font))
                .collect();
            let extras: Vec<_> = rows
                .iter()
                .map(|r| r.leaves.map(|n| lay(ui, n.to_string(), &small)))
                .collect();
            let focus_mark = lay(ui, FOCUS.to_owned(), &font);
            let content_w = |row: &Row, gw: f32| {
                row.depth as f32 * INDENT
                    + GUTTER
                    + DOT_COLUMN
                    + LABEL_PAD
                    + gw
                    + LABEL_PAD
                    + focus_mark.size().x
            };
            let row_w = rows
                .iter()
                .zip(&galleys)
                .map(|(r, g)| content_w(r, g.size().x))
                .fold(ui.available_width(), f32::max);

            let visuals = ui.visuals().clone();
            let guide = visuals.widgets.noninteractive.bg_stroke.color;
            let quiet = visuals.weak_text_color();
            let accent = visuals.selection.stroke.color;
            let mut refocus = None;

            for ((row, galley), extra) in rows.iter().zip(galleys).zip(extras) {
                let height = ROW_H + if row.ancestors.is_some() { PATH_H } else { 0.0 };
                let (rect, resp) =
                    ui.allocate_exact_size(egui::vec2(row_w, height), egui::Sense::click());
                let is_selected = selected.contains(&row.id);
                let is_cursor = cursor == Some(row.id);
                let line = egui::Rect::from_min_size(rect.min, egui::vec2(rect.width(), ROW_H));

                if is_selected {
                    ui.painter()
                        .rect_filled(rect, 4.0, visuals.selection.bg_fill);
                } else if resp.hovered() {
                    ui.painter()
                        .rect_filled(rect, 4.0, visuals.widgets.hovered.bg_fill);
                }

                let p = ui.painter();
                let gutter_x = rect.left() + row.depth as f32 * INDENT;
                let dot_at = egui::pos2(gutter_x + GUTTER + DOT_COLUMN * 0.5, line.center().y);
                let stroke = egui::Stroke::new(1.0, guide);
                // The tree guides the user asked for: *"a small colored dot
                // next to each object, with a connected line going up to the
                // top."* Each ancestor level draws its own trunk down the
                // row, the row's own parent draws an elbow across to the
                // dot, and the trunk of a parent whose last child this is
                // stops at that elbow rather than running on past the
                // family — which is what makes a directory tree readable as
                // one.
                for level in 0..row.depth {
                    let x = rect.left() + level as f32 * INDENT + INDENT * 0.5;
                    let ends_here = level + 1 == row.depth && row.last_child;
                    let bottom = if ends_here {
                        dot_at.y
                    } else {
                        rect.bottom() + LABEL_PAD
                    };
                    p.line_segment(
                        [egui::pos2(x, rect.top() - LABEL_PAD), egui::pos2(x, bottom)],
                        stroke,
                    );
                    if level + 1 == row.depth {
                        p.line_segment(
                            [
                                egui::pos2(x, dot_at.y),
                                egui::pos2(dot_at.x - DOT, dot_at.y),
                            ],
                            stroke,
                        );
                    }
                }
                p.circle_filled(
                    dot_at,
                    DOT,
                    theme
                        .resolve(accent_role(row.accent).unwrap_or(Role::AccentDefault))
                        .egui(),
                );

                if row.has_children {
                    paint_twisty(
                        p,
                        egui::pos2(gutter_x + GUTTER * 0.5, line.center().y),
                        if row.open {
                            Twisty::Open
                        } else {
                            Twisty::Closed
                        },
                        quiet,
                    );
                }

                let label_color = if is_selected {
                    accent
                } else {
                    visuals.text_color()
                };
                let label_x = gutter_x + GUTTER + DOT_COLUMN + LABEL_PAD;
                let label_w = galley.size().x;
                p.galley(
                    egui::pos2(label_x, line.center().y - galley.size().y * 0.5),
                    galley,
                    label_color,
                );
                let mut after = label_x + label_w + LABEL_PAD;
                if let Some(count) = extra {
                    let w = count.size().x;
                    p.galley(
                        egui::pos2(after, line.center().y - count.size().y * 0.5),
                        count,
                        quiet,
                    );
                    after += w + LABEL_PAD;
                }
                // Where this match lives, shortened from the left so
                // the immediate parent — the part that tells them apart —
                // survives the panel's width.
                if let Some(ancestors) = &row.ancestors {
                    let room = rect.right() - label_x;
                    let text = nav::shortened(ancestors, room, |text| {
                        ui.painter()
                            .layout_no_wrap(text.to_owned(), small.clone(), ink)
                            .size()
                            .x
                    });
                    if !text.is_empty() {
                        ui.painter().text(
                            egui::pos2(label_x, line.bottom()),
                            egui::Align2::LEFT_TOP,
                            text,
                            small.clone(),
                            quiet,
                        );
                    }
                }
                // The re-root affordance, on the branch rows that have
                // somewhere to go.
                let mark = egui::Rect::from_min_size(
                    egui::pos2(after, line.top()),
                    egui::vec2(focus_mark.size().x + LABEL_PAD, ROW_H),
                );
                if row.has_children {
                    ui.painter().text(
                        mark.left_center(),
                        egui::Align2::LEFT_CENTER,
                        FOCUS,
                        font.clone(),
                        quiet,
                    );
                }

                if is_cursor && keyboard_active {
                    ui.painter().rect_stroke(
                        rect,
                        4.0,
                        egui::Stroke::new(1.0, accent),
                        egui::StrokeKind::Inside,
                    );
                }

                // A double-click is the other half of the focus
                // affordance, so it outranks the select the same press made.
                if resp.double_clicked() && row.has_children {
                    refocus = Some(Refocus(Some(row.id)));
                } else if resp.clicked() {
                    let chevron = egui::Rect::from_min_size(
                        egui::pos2(gutter_x, line.top()),
                        egui::vec2(GUTTER, ROW_H),
                    );
                    let at = resp.interact_pointer_pos();
                    if row.has_children && at.is_some_and(|pt| chevron.contains(pt)) {
                        toggle(&mut expanded, row.id);
                    } else if row.has_children && at.is_some_and(|pt| mark.contains(pt)) {
                        refocus = Some(Refocus(Some(row.id)));
                    } else {
                        cursor = Some(row.id);
                        let extend = ctx.input(|i| i.modifiers.shift);
                        navigation = Some(Action::NavSelect {
                            block: row.id,
                            extend,
                        });
                    }
                }

                if scroll_to_cursor && is_cursor {
                    resp.scroll_to_me(Some(egui::Align::Center));
                }
            }
            refocus
        })
        .inner;
    if let Some(Refocus(to)) = refocus {
        focus = to;
        // A tree re-rooted somewhere else has no business keeping the old
        // root's cursor, which is no longer one of its rows.
        cursor = to;
    }

    ctx.data_mut(|d| {
        d.insert_temp(expanded_id, expanded);
        if let Some(c) = cursor {
            d.insert_temp(cursor_id, c);
        }
        match focus {
            Some(at) => {
                d.insert_temp(focus_id(), at);
            }
            None => {
                d.remove_temp::<BlockId>(focus_id());
            }
        }
    });
    navigation
}

/// What re-rooting the tree asks for: a block to hang it from, or the
/// document's own root.
#[derive(Clone, Copy)]
struct Refocus(Option<BlockId>);

/// The panel's own breadcrumb, drawn above a focused tree: the
/// document, then every ancestor down to the block the tree hangs from.
/// Clicking a segment re-roots there; the tree's indentation restarts from
/// whatever it lands on. This is the panel's, not the status strip's — that
/// one says where the *canvas* is, which is a different question.
fn breadcrumb(ui: &mut egui::Ui, tree: &NavTree, index: &Index, focus: BlockId) -> Option<Refocus> {
    let mut trail: Vec<BlockId> = index.ancestor_ids(Scope::Root, focus);
    trail.push(focus);
    let mut picked = None;
    ui.horizontal_wrapped(|ui| {
        ui.spacing_mut().item_spacing.x = 2.0;
        if ui.small_button(ROOT_CRUMB).clicked() {
            picked = Some(Refocus(None));
        }
        for (ndx, id) in trail.iter().enumerate() {
            ui.label(egui::RichText::new("/").small().weak());
            let last = ndx + 1 == trail.len();
            let label = egui::RichText::new(nav::label_of(tree, *id)).small();
            if last {
                ui.label(label);
            } else if ui.small_button(label).clicked() {
                picked = Some(Refocus(Some(*id)));
            }
        }
    });
    ui.separator();
    picked
}

/// What the breadcrumb calls the document's own root — the tree's home,
/// which is a scope rather than a block and so has no label of its own.
const ROOT_CRUMB: &str = "Diagram";

/// Keyboard tree navigation. Arrow keys move the highlight and Right/Left/Space
/// expand-collapse, mutating the cursor and expand set in place *without* touching
/// the canvas; only Enter commits, returning [`Action::NavSelect`] to select and
/// frame the highlighted block. Keys are consumed so the canvas below does not
/// also act on them.
/// The tree state keyboard navigation reads and writes: the flattened rows and
/// their parent links, plus the cursor/expansion/scroll it mutates in place.
struct KeyNav<'a> {
    rows: &'a [Row],
    index: &'a Index,
    top_id: Scope,
    expanded: &'a mut HashSet<BlockId>,
    cursor: &'a mut Option<BlockId>,
    scroll: &'a mut bool,
}

impl KeyNav<'_> {
    fn handle_keys(&mut self, ctx: &egui::Context) -> Option<Action> {
        use egui::{Key, Modifiers};

        let Self {
            rows,
            index,
            top_id,
            expanded,
            cursor,
            scroll,
        } = self;
        let (rows, index, top_id) = (*rows, *index, *top_id);
        let key = |k: Key| ctx.input_mut(|i| i.consume_key(Modifiers::NONE, k));

        let idx = cursor.and_then(|c| rows.iter().position(|r| r.id == c))?;
        let row = &rows[idx];
        let mut moved_to: Option<BlockId> = None;

        if key(Key::ArrowDown) {
            if idx + 1 < rows.len() {
                moved_to = Some(rows[idx + 1].id);
            }
        } else if key(Key::ArrowUp) {
            if idx > 0 {
                moved_to = Some(rows[idx - 1].id);
            }
        } else if key(Key::Home) {
            moved_to = rows.first().map(|r| r.id);
        } else if key(Key::End) {
            moved_to = rows.last().map(|r| r.id);
        } else if key(Key::ArrowRight) {
            if row.has_children && !row.open {
                expanded.insert(row.id);
            } else if row.has_children && idx + 1 < rows.len() {
                moved_to = Some(rows[idx + 1].id);
            }
        } else if key(Key::ArrowLeft) {
            if row.has_children && row.open {
                expanded.remove(&row.id);
            } else if let Some(p) = index.parent_of(row.id)
                && p != top_id
                && let Scope::Block(next) = p
            {
                moved_to = Some(next);
            }
        } else if key(Key::Space) {
            if row.has_children {
                toggle(expanded, row.id);
            }
        } else if key(Key::Enter) {
            // Commit: select the highlighted block on the canvas and frame it. Arrow
            // keys only move the highlight, so the canvas isn't re-framed on every
            // keystroke.
            return Some(Action::NavSelect {
                block: row.id,
                extend: false,
            });
        }

        if let Some(next) = moved_to {
            **cursor = Some(next);
            **scroll = true;
        }
        None
    }
}

fn toggle(set: &mut HashSet<BlockId>, id: BlockId) {
    if !set.remove(&id) {
        set.insert(id);
    }
}

/// Paint the little expand/collapse triangle centered at `c`: pointing down when
/// `open`, right when collapsed.
fn paint_twisty(painter: &egui::Painter, c: egui::Pos2, twisty: Twisty, color: egui::Color32) {
    let pts = if twisty == Twisty::Open {
        vec![
            egui::pos2(c.x - TRI, c.y - TRI * 0.6),
            egui::pos2(c.x + TRI, c.y - TRI * 0.6),
            egui::pos2(c.x, c.y + TRI),
        ]
    } else {
        vec![
            egui::pos2(c.x - TRI * 0.6, c.y - TRI),
            egui::pos2(c.x - TRI * 0.6, c.y + TRI),
            egui::pos2(c.x + TRI, c.y),
        ]
    };
    painter.add(egui::Shape::convex_polygon(pts, color, egui::Stroke::NONE));
}

/// Widget id of the nav dialog's filter box. (The canvas needs no special case
/// for it: any non-canvas widget holding keyboard focus suppresses the canvas
/// key shortcuts — see `compute_interaction`.)
pub(crate) fn nav_filter_id() -> egui::Id {
    egui::Id::new("nav_filter")
}

/// Forget what was typed in the filter box: it is a transient
/// search, not a persistent view, so dismissing the navigator clears it.
pub fn clear_filter(ctx: &egui::Context) {
    ctx.data_mut(|d| d.remove::<String>(nav_filter_id()));
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::kernel::{NavTree, chrome::block_label};
    use crate::path::BlockPath;
    use blockworx_doc::document::IndexedDocument;

    /// The navigator's tree over `scene`, the way the session builds it.
    fn tree_of(scene: &mut Scene) -> NavTree {
        NavTree::of(&scene.indexed(), BlockPath::empty(), Vec::new())
    }
    use crate::widget::test_fixtures::{self as fx, Scene};
    use blockworx_doc::{fixtures::block_id, id::BlockId};
    use blockworx_geom::{Rect, pos2, vec2};

    fn square(n: u32, name: &str) -> Vec<blockworx_doc::opcode::OpCodes> {
        vec![
            fx::block_in(
                n,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(60.0, 60.0)),
            ),
            fx::titled(n, name),
        ]
    }

    fn nested(n: u32, parent: u32, name: &str) -> Vec<blockworx_doc::opcode::OpCodes> {
        vec![
            fx::block_in(
                n,
                Scope::Block(block_id(parent)),
                Rect::from_min_max(pos2(0.0, 0.0), pos2(60.0, 60.0)),
            ),
            fx::titled(n, name),
        ]
    }

    #[test]
    fn block_name_falls_back_to_the_id_when_unnamed() {
        let id = block_id(1);
        let mut scene = Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(60.0, 60.0)),
            ),
            fx::titled(1, ""),
        ]);
        let indexed = scene.indexed();
        assert_eq!(block_label(&indexed, id), id.to_string());
    }

    /// The panel body must not hammer the repaint clock while idle.
    #[test]
    fn an_open_navigator_settles() {
        let mut scene = Scene::new(
            ["alu", "mux", "regs"]
                .iter()
                .enumerate()
                .flat_map(|(i, name)| {
                    let x = i as f32 * 100.0;
                    vec![
                        fx::block_in(
                            i as u32 + 1,
                            Scope::Root,
                            Rect::from_min_max(pos2(x, 0.0), pos2(x + 80.0, 80.0)),
                        ),
                        fx::titled(i as u32 + 1, name),
                    ]
                })
                .collect(),
        );
        let tree = tree_of(&mut scene);
        let settle = crate::canvas::settle::probe(30, |ui| {
            let _ = body(
                ui,
                NavScene {
                    theme: &Theme::from_embedded(),
                    tree: &tree,
                },
            );
        });
        crate::canvas::settle::assert_settles(&settle, 4);
    }

    /// The tree answers a click on a row by selecting that block — driven
    /// through the body's own layout, so a row that moved or stopped taking
    /// clicks fails here.
    #[test]
    fn a_row_click_selects_its_block() {
        let mut scene = Scene::new(square(1, "alu"));
        let tree = tree_of(&mut scene);
        let screen = Rect::from_min_size(pos2(0.0, 0.0), vec2(320.0, 400.0));
        let mut chrome = crate::panels::painted::Chrome::new(screen);
        let mut fired = None;
        let frame = |ui: &mut egui::Ui| {
            body(
                ui,
                NavScene {
                    theme: &Theme::from_embedded(),
                    tree: &tree,
                },
            )
        };
        chrome.settle(|ui| {
            let _ = frame(ui);
        });
        let row = chrome.rect("alu").expect("the tree drew its one row");
        chrome.click_at(row.center(), |ui| {
            if let Some(action) = frame(ui) {
                fired = Some(action);
            }
        });
        assert!(
            matches!(fired, Some(Action::NavSelect { block, .. }) if block == block_id(1)),
            "a click on the row did not select its block",
        );
    }

    #[test]
    fn block_name_joins_name_and_type_skipping_empties() {
        let id = block_id(1);
        let mut scene = Scene::new(
            square(1, "Adder")
                .into_iter()
                .chain([fx::typed(1, "ALU")])
                .collect(),
        );
        let indexed = scene.indexed();
        let label = block_label(&indexed, id);
        assert_eq!(label, "Adder/ALU");
    }

    #[test]
    fn block_name_omits_empty_type_segment() {
        let mut scene = Scene::new(square(1, "Adder"));
        let indexed = scene.indexed();
        assert_eq!(block_label(&indexed, block_id(1)), "Adder");
    }

    /// The panel driven through real frames, with the canvas's selection
    /// under the test's control — so the three tree mechanisms are proved
    /// by what the panel actually painted, not by what `Walk` returned.
    struct Tree<'a> {
        chrome: crate::panels::painted::Chrome,
        canvas: Canvas<'a>,
    }

    struct Canvas<'a> {
        document: &'a IndexedDocument<'a>,
        path: BlockPath,
        selected: Vec<BlockId>,
        fired: Option<Action>,
    }

    impl Canvas<'_> {
        fn frame(&mut self, ui: &mut egui::Ui) {
            let tree = NavTree::of(self.document, self.path.clone(), self.selected.clone());
            let fired = body(
                ui,
                NavScene {
                    theme: &Theme::from_embedded(),
                    tree: &tree,
                },
            );
            if fired.is_some() {
                self.fired = fired;
            }
        }
    }

    impl<'a> Tree<'a> {
        fn over(document: &'a IndexedDocument<'a>) -> Self {
            let mut tree = Tree {
                chrome: crate::panels::painted::Chrome::new(Rect::from_min_size(
                    pos2(0.0, 0.0),
                    vec2(320.0, 500.0),
                )),
                canvas: Canvas {
                    document,
                    path: BlockPath::empty(),
                    selected: Vec::new(),
                    fired: None,
                },
            };
            tree.settle();
            tree
        }

        fn settle(&mut self) {
            let Self { chrome, canvas } = self;
            chrome.settle(|ui| canvas.frame(ui));
        }

        fn click_on(&mut self, text: &str) {
            let Self { chrome, canvas } = self;
            chrome.click_on(text, |ui| canvas.frame(ui));
        }

        fn double_click_on(&mut self, text: &str) {
            let at = self
                .chrome
                .rect(text)
                .unwrap_or_else(|| panic!("nothing painted reads {text:?}"))
                .center();
            let Self { chrome, canvas } = self;
            chrome.double_click_at(at, |ui| canvas.frame(ui));
        }

        fn type_into_the_filter(&mut self, text: &str) {
            self.click_on(FILTER_HINT);
            let Self { chrome, canvas } = self;
            chrome.type_text(text, |ui| canvas.frame(ui));
        }

        /// What selecting `block` on the canvas puts through the panel.
        fn select_on_the_canvas(&mut self, block: BlockId) {
            self.canvas.selected = vec![block];
            self.settle();
        }

        fn shows(&self, text: &str) -> bool {
            self.chrome.shows(text)
        }
    }

    const FILTER_HINT: &str = "Search all blocks\u{2026}";

    /// Platform > Services > Auth, with Marketing off to one side: three
    /// levels and a sibling subtree to prove a re-rooting left behind.
    fn deep() -> Vec<blockworx_doc::opcode::OpCodes> {
        square(1, "Platform")
            .into_iter()
            .chain(nested(2, 1, "Services"))
            .chain(nested(3, 2, "Auth"))
            .chain(square(4, "Marketing"))
            .collect()
    }

    /// Re-rooting through a real frame: the `»` on a branch row re-roots the
    /// tree there, the panel's own breadcrumb appears above it, and the way
    /// back is a click on that breadcrumb.
    #[test]
    fn the_focus_affordance_re_roots_the_tree_and_the_breadcrumb_undoes_it() {
        let mut scene = Scene::new(deep());
        let indexed = scene.indexed();
        let mut tree = Tree::over(&indexed);
        assert!(
            tree.shows("Platform") && tree.shows("Marketing"),
            "precondition: both root blocks are rows",
        );
        assert!(
            !tree.shows(ROOT_CRUMB),
            "an unfocused tree has no breadcrumb"
        );
        assert_eq!(
            tree.chrome.rects(FOCUS).len(),
            1,
            "only the branch row offers to re-root",
        );

        tree.click_on(FOCUS);
        assert!(tree.shows(ROOT_CRUMB), "the breadcrumb did not appear");
        assert!(
            tree.shows("Services"),
            "the focused block's child is not a row"
        );
        assert!(
            !tree.shows("Marketing"),
            "a block outside the focus is still a row: {:?}",
            tree.chrome.texts(),
        );

        tree.click_on(ROOT_CRUMB);
        assert!(
            tree.shows("Marketing") && !tree.shows(ROOT_CRUMB),
            "the breadcrumb's root did not put the whole document back",
        );
    }

    /// The other half of the focus affordance: a double-click on a branch
    /// row re-roots on it too.
    #[test]
    fn a_double_click_re_roots_the_tree() {
        let mut scene = Scene::new(deep());
        let indexed = scene.indexed();
        let mut tree = Tree::over(&indexed);
        tree.double_click_on("Platform");
        assert!(tree.shows(ROOT_CRUMB), "the double-click did not focus");
        assert!(
            tree.shows("Services") && !tree.shows("Marketing"),
            "the tree did not re-root on the block double-clicked: {:?}",
            tree.chrome.texts(),
        );
    }

    /// The filter through a real frame: it flattens the tree to the
    /// matches, each carrying its ancestor path — and the ancestors
    /// themselves are not rows.
    #[test]
    fn the_filter_flattens_to_matches_carrying_their_path() {
        let mut scene = Scene::new(deep());
        let indexed = scene.indexed();
        let mut tree = Tree::over(&indexed);
        tree.type_into_the_filter("auth");
        assert!(
            tree.shows("Auth"),
            "the match is not a row: {:?}",
            tree.chrome.texts()
        );
        assert!(
            tree.shows("Platform/Services"),
            "the match does not say where it lives: {:?}",
            tree.chrome.texts(),
        );
        for ancestor in ["Platform", "Services"] {
            assert!(
                !tree.shows(ancestor),
                "{ancestor:?} is drawn as a row of its own, not as a path",
            );
        }
    }

    /// The filter's other half: it reads the whole document, so a match
    /// outside the focused subtree is still found.
    #[test]
    fn the_filter_crosses_the_focus_boundary() {
        let mut scene = Scene::new(deep());
        let indexed = scene.indexed();
        let mut tree = Tree::over(&indexed);
        tree.click_on(FOCUS);
        assert!(
            tree.shows(ROOT_CRUMB) && !tree.shows("Marketing"),
            "precondition: the tree is focused and Marketing is outside it",
        );
        tree.type_into_the_filter("market");
        assert!(
            tree.shows("Marketing"),
            "the filter stopped at the focus boundary: {:?}",
            tree.chrome.texts(),
        );
    }

    /// Reveal through a real frame: selecting geometry on the canvas opens
    /// the block's ancestors and puts its row on screen, giving up a focus
    /// that would have hidden it.
    #[test]
    fn selecting_on_the_canvas_reveals_the_block_in_the_tree() {
        let mut scene = Scene::new(deep());
        let indexed = scene.indexed();
        let mut tree = Tree::over(&indexed);
        tree.click_on(FOCUS);
        assert!(
            tree.shows(ROOT_CRUMB) && !tree.shows("Marketing"),
            "precondition: the tree is focused away from Marketing",
        );

        tree.select_on_the_canvas(block_id(4));
        assert!(
            tree.shows("Marketing"),
            "the canvas selection was never revealed: {:?}",
            tree.chrome.texts(),
        );
        assert!(
            !tree.shows(ROOT_CRUMB),
            "a focus that could not show the selection survived it",
        );

        tree.select_on_the_canvas(block_id(3));
        assert!(
            tree.shows("Auth"),
            "a deep block's ancestors were not opened: {:?}",
            tree.chrome.texts(),
        );
    }

    /// One predicate, three consumers: the blocks the canvas draws a second,
    /// inset border on, the blocks the navigator hangs a disclosure triangle
    /// on, and the blocks the PDF cuts a page for are one set. They agree by
    /// construction — all three call [`structure`] — and this fails the day one
    /// of them grows a spelling of its own.
    #[test]
    fn the_canvas_the_navigator_and_the_pdf_agree_on_what_opens_a_scope() {
        use blockworx_editor::shape::ShapeRef;
        use std::collections::BTreeSet;

        let mut scene = Scene::new(fx::nested_scopes());
        let live: Vec<BlockId> = {
            let indexed = scene.indexed();
            indexed.doc.blocks().map(|(id, _)| id).collect()
        };
        let nested: BTreeSet<BlockId> = live
            .iter()
            .copied()
            .filter(|&id| crate::path::structure(&scene.indexed(), id).opens_a_scope())
            .collect();
        assert!(
            !nested.is_empty() && nested.len() < live.len(),
            "precondition: the fixture must hold both kinds of block, got {nested:?} of {live:?}",
        );

        // The canvas: every scope in turn, since a level only ever draws its
        // own children.
        let doc = scene.doc.clone();
        let mut double_bordered: BTreeSet<BlockId> = BTreeSet::new();
        for scope in std::iter::once(BlockPath::empty()).chain(live.iter().map(|&id| {
            let mut path = BlockPath::to_parent_of(&doc, id).expect("a live block has a path");
            path.push(id);
            path
        })) {
            scene.path = scope;
            let drawing = scene.drawing();
            for (id, shape) in drawing.blocks_layer() {
                let ShapeRef::Block(block) = shape else {
                    continue;
                };
                if block.structure.opens_a_scope() {
                    double_bordered.insert(id.block().expect("a block layer holds blocks"));
                }
            }
        }

        let indexed = scene.indexed();
        let pages: BTreeSet<BlockId> = blockworx_export::pdf::page_scopes(&indexed)
            .into_iter()
            .filter_map(|scope| scope.block())
            .collect();
        let branches: BTreeSet<BlockId> =
            nav::branch_rows(&NavTree::of(&indexed, BlockPath::empty(), Vec::new()))
                .into_iter()
                .collect();

        assert_eq!(double_bordered, nested, "the canvas draws a different set");
        assert_eq!(pages, nested, "the PDF pages a different set");
        // The navigator hangs its tree *from* the top block, which is the PDF's
        // first page and the canvas's outermost double border but never a row
        // of its own — the one, principled difference.
        let root = crate::path::tree_root(&indexed)
            .block()
            .expect("the fixture designates a top");
        assert_eq!(
            branches,
            nested
                .iter()
                .copied()
                .filter(|&id| id != root)
                .collect::<BTreeSet<_>>(),
            "the navigator branches on a different set",
        );
    }
}