add treetest protocol simulator and ui

treetest/src/app.rs

@@ -0,0 +1,603 @@
+//! Ratatui application shell for the protocol demo.
+
+use std::{io, time::Duration};
+
+use crossterm::{
+    event::{self, Event, KeyCode, KeyEventKind},
+    execute,
+    terminal::{EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode},
+};
+use ratatui::{
+    DefaultTerminal, Frame,
+    layout::{Constraint, Direction, Layout, Rect},
+    style::{Modifier, Style, Stylize},
+    text::{Line, Text},
+    widgets::{Block, Borders, List, ListItem, Paragraph, Wrap},
+};
+
+use crate::{
+    model::{Selection, format_path},
+    scenarios::built_in_scenarios,
+    sim::{RecordedEvent, Simulation},
+};
+
+/// Errors returned by the TUI application.
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    #[error(transparent)]
+    Io(#[from] io::Error),
+    #[error(transparent)]
+    Sim(#[from] crate::sim::SimError),
+}
+
+/// Starts the TUI application.
+pub fn run() -> Result<(), AppError> {
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen)?;
+    let terminal = ratatui::init();
+    let result = App::new()?.run(terminal);
+    ratatui::restore();
+    disable_raw_mode()?;
+    execute!(io::stdout(), LeaveAlternateScreen)?;
+    result
+}
+
+#[derive(Debug)]
+struct App {
+    scenarios: Vec<crate::model::ScenarioDefinition>,
+    scenario_index: usize,
+    simulation: Simulation,
+    selection_index: usize,
+    selections: Vec<Selection>,
+    status: String,
+}
+
+impl App {
+    fn new() -> Result<Self, AppError> {
+        let scenarios = built_in_scenarios();
+        let simulation = Simulation::new(scenarios[0].clone())?;
+        let selections = build_selections(&simulation);
+        let selection_index = selections
+            .iter()
+            .position(|selection| *selection == simulation.initial_selection())
+            .unwrap_or(0);
+        Ok(Self {
+            scenarios,
+            scenario_index: 0,
+            simulation,
+            selection_index,
+            selections,
+            status: "Use arrows to move, Enter to switch scenarios, q to quit.".to_owned(),
+        })
+    }
+
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<(), AppError> {
+        loop {
+            terminal.draw(|frame| self.render(frame))?;
+            if event::poll(Duration::from_millis(100))?
+                && let Event::Key(key) = event::read()?
+                && key.kind == KeyEventKind::Press
+                && !self.handle_key(key.code)?
+            {
+                break;
+            }
+        }
+        Ok(())
+    }
+
+    fn handle_key(&mut self, code: KeyCode) -> Result<bool, AppError> {
+        match code {
+            KeyCode::Char('q') => return Ok(false),
+            KeyCode::Up => {
+                if self.selection_index > 0 {
+                    self.selection_index -= 1;
+                }
+            }
+            KeyCode::Down => {
+                if self.selection_index + 1 < self.selections.len() {
+                    self.selection_index += 1;
+                }
+            }
+            KeyCode::Left => {
+                if self.scenario_index > 0 {
+                    self.load_scenario(self.scenario_index - 1)?;
+                }
+            }
+            KeyCode::Right => {
+                if self.scenario_index + 1 < self.scenarios.len() {
+                    self.load_scenario(self.scenario_index + 1)?;
+                }
+            }
+            KeyCode::Enter => {
+                let next = (self.scenario_index + 1) % self.scenarios.len();
+                self.load_scenario(next)?;
+            }
+            KeyCode::Char('i') => {
+                self.perform_introspection()?;
+            }
+            KeyCode::Char('e') => {
+                self.perform_echo()?;
+            }
+            KeyCode::Char('p') => {
+                self.perform_ping()?;
+            }
+            KeyCode::Char('c') => {
+                self.perform_chunked()?;
+            }
+            KeyCode::Char('h') => {
+                self.perform_chat_call()?;
+            }
+            KeyCode::Char('d') => {
+                self.perform_chat_data()?;
+            }
+            KeyCode::Char('b') => {
+                self.perform_chat_bye()?;
+            }
+            KeyCode::Char('f') => {
+                self.perform_invalid_fault_demo()?;
+            }
+            KeyCode::Char('s') => {
+                let processed = self.simulation.step()?;
+                self.status = if processed {
+                    "Processed one queued frame.".to_owned()
+                } else {
+                    "Network already idle.".to_owned()
+                };
+            }
+            KeyCode::Char('a') => {
+                let steps = self.simulation.drain()?;
+                self.status = format!("Drained {steps} queued frames.");
+            }
+            _ => {}
+        }
+        Ok(true)
+    }
+
+    fn load_scenario(&mut self, index: usize) -> Result<(), AppError> {
+        self.scenario_index = index;
+        self.simulation = Simulation::new(self.scenarios[index].clone())?;
+        self.selections = build_selections(&self.simulation);
+        self.selection_index = self
+            .selections
+            .iter()
+            .position(|selection| *selection == self.simulation.initial_selection())
+            .unwrap_or(0);
+        self.status = format!("Loaded scenario: {}", self.scenarios[index].name);
+        Ok(())
+    }
+
+    fn selected(&self) -> &Selection {
+        &self.selections[self.selection_index]
+    }
+
+    fn perform_introspection(&mut self) -> Result<(), AppError> {
+        match self.selected().clone() {
+            Selection::Node(node_id) => {
+                let result = self.simulation.call_endpoint_introspection(node_id)?;
+                let steps = self.simulation.drain()?;
+                self.status = format!("{} ({steps} steps)", result.label);
+            }
+            Selection::Leaf { node_id, leaf_name } => {
+                let result = self
+                    .simulation
+                    .call_leaf_introspection(node_id, &leaf_name)?;
+                let steps = self.simulation.drain()?;
+                self.status = format!("{} ({steps} steps)", result.label);
+            }
+        }
+        Ok(())
+    }
+
+    fn perform_echo(&mut self) -> Result<(), AppError> {
+        if let Selection::Leaf { node_id, leaf_name } = self.selected().clone() {
+            let result =
+                self.simulation
+                    .call_echo_leaf(node_id, &leaf_name, "demo echo from root")?;
+            let steps = self.simulation.drain()?;
+            self.status = format!("{} ({steps} steps)", result.label);
+        } else {
+            self.status = "Select a leaf first, then press e.".to_owned();
+        }
+        Ok(())
+    }
+
+    fn perform_ping(&mut self) -> Result<(), AppError> {
+        if let Selection::Node(node_id) = self.selected().clone() {
+            if let Some(procedure_id) = self
+                .simulation
+                .node(node_id)
+                .endpoint_procedures
+                .first()
+                .map(|procedure| procedure.procedure_id.clone())
+            {
+                let result = self.simulation.call_endpoint_procedure(
+                    node_id,
+                    &procedure_id,
+                    b"ping".to_vec(),
+                )?;
+                let steps = self.simulation.drain()?;
+                self.status = format!("{} ({steps} steps)", result.label);
+            } else {
+                self.status = "Selected node has no endpoint procedures.".to_owned();
+            }
+        } else {
+            self.status = "Select a node first, then press p.".to_owned();
+        }
+        Ok(())
+    }
+
+    fn perform_chunked(&mut self) -> Result<(), AppError> {
+        if let Selection::Node(node_id) = self.selected().clone() {
+            if let Some(procedure_id) = self
+                .simulation
+                .node(node_id)
+                .endpoint_procedures
+                .iter()
+                .find(|procedure| {
+                    procedure.description.contains("chunk")
+                        || procedure.procedure_id.contains("chunked")
+                })
+                .map(|procedure| procedure.procedure_id.clone())
+            {
+                let result = self.simulation.call_endpoint_procedure(
+                    node_id,
+                    &procedure_id,
+                    b"chunk please".to_vec(),
+                )?;
+                let steps = self.simulation.drain()?;
+                self.status = format!("{} ({steps} steps)", result.label);
+            } else {
+                self.status = "Selected node has no chunked procedure.".to_owned();
+            }
+        } else {
+            self.status = "Select a node first, then press c.".to_owned();
+        }
+        Ok(())
+    }
+
+    fn perform_chat_call(&mut self) -> Result<(), AppError> {
+        if let Selection::Node(node_id) = self.selected().clone() {
+            if let Some(procedure_id) = self
+                .simulation
+                .node(node_id)
+                .endpoint_procedures
+                .iter()
+                .find(|procedure| procedure.procedure_id.contains("chat"))
+                .map(|procedure| procedure.procedure_id.clone())
+            {
+                let result = self.simulation.call_endpoint_procedure(
+                    node_id,
+                    &procedure_id,
+                    b"open chat".to_vec(),
+                )?;
+                let steps = self.simulation.drain()?;
+                self.status = format!("{} ({steps} steps)", result.label);
+            } else {
+                self.status = "Selected node has no chat procedure.".to_owned();
+            }
+        } else {
+            self.status = "Select a node first, then press h.".to_owned();
+        }
+        Ok(())
+    }
+
+    fn perform_chat_data(&mut self) -> Result<(), AppError> {
+        if let Some(hook_id) = self.simulation.hook_ids().last().copied() {
+            let result =
+                self.simulation
+                    .send_root_hook_data(hook_id, "hello from the root", false)?;
+            let steps = self.simulation.drain()?;
+            self.status = format!("{} ({steps} steps)", result.label);
+        } else {
+            self.status = "No known hook yet. Press h to open chat first.".to_owned();
+        }
+        Ok(())
+    }
+
+    fn perform_chat_bye(&mut self) -> Result<(), AppError> {
+        if let Some(hook_id) = self.simulation.hook_ids().last().copied() {
+            let result = self.simulation.send_root_hook_data(hook_id, "bye", true)?;
+            let steps = self.simulation.drain()?;
+            self.status = format!("{} ({steps} steps)", result.label);
+        } else {
+            self.status = "No known hook yet. Press h to open chat first.".to_owned();
+        }
+        Ok(())
+    }
+
+    fn perform_invalid_fault_demo(&mut self) -> Result<(), AppError> {
+        if let Some(hook_id) = self.simulation.hook_ids().last().copied() {
+            let root_id = crate::model::NodeId(0);
+            if self.simulation.tree.nodes.len() > 1 {
+                let attacker = crate::model::NodeId(1);
+                let result = self.simulation.inject_invalid_peer_data(
+                    attacker,
+                    root_id,
+                    hook_id,
+                    "demo.endpoint.v1.chat.session",
+                    "spoofed data",
+                )?;
+                let steps = self.simulation.drain()?;
+                self.status = format!("{} ({steps} steps)", result.label);
+            } else {
+                self.status =
+                    "This scenario has no second node for invalid-peer traffic.".to_owned();
+            }
+        } else {
+            self.status = "Open a hook first before injecting invalid traffic.".to_owned();
+        }
+        Ok(())
+    }
+
+    fn render(&self, frame: &mut Frame<'_>) {
+        let chunks = Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([
+                Constraint::Length(3),
+                Constraint::Min(14),
+                Constraint::Length(8),
+            ])
+            .split(frame.area());
+
+        self.render_header(frame, chunks[0]);
+        self.render_body(frame, chunks[1]);
+        self.render_footer(frame, chunks[2]);
+    }
+
+    fn render_header(&self, frame: &mut Frame<'_>, area: Rect) {
+        let title = format!(
+            "treetest | scenario {} / {}: {}",
+            self.scenario_index + 1,
+            self.scenarios.len(),
+            self.scenarios[self.scenario_index].name
+        );
+        frame.render_widget(
+            Paragraph::new(title).block(Block::default().borders(Borders::ALL).title("Scenario")),
+            area,
+        );
+    }
+
+    fn render_body(&self, frame: &mut Frame<'_>, area: Rect) {
+        let columns = Layout::default()
+            .direction(Direction::Horizontal)
+            .constraints([
+                Constraint::Length(34),
+                Constraint::Percentage(36),
+                Constraint::Percentage(32),
+            ])
+            .split(area);
+
+        let scenario_items = self
+            .scenarios
+            .iter()
+            .enumerate()
+            .map(|(index, scenario)| {
+                let label = if index == self.scenario_index {
+                    format!("> {}", scenario.name)
+                } else {
+                    format!("  {}", scenario.name)
+                };
+                ListItem::new(label)
+            })
+            .collect::<Vec<_>>();
+        frame.render_widget(
+            List::new(scenario_items)
+                .block(Block::default().borders(Borders::ALL).title("Scenarios")),
+            columns[0],
+        );
+
+        let center = Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([Constraint::Percentage(54), Constraint::Percentage(46)])
+            .split(columns[1]);
+        self.render_selection_list(frame, center[0]);
+        self.render_inspector(frame, center[1]);
+
+        let right = Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+            .split(columns[2]);
+        self.render_trace(frame, right[0]);
+        self.render_hooks(frame, right[1]);
+    }
+
+    fn render_selection_list(&self, frame: &mut Frame<'_>, area: Rect) {
+        let items = self
+            .selections
+            .iter()
+            .enumerate()
+            .map(|(index, selection)| {
+                let label = match selection {
+                    Selection::Node(node_id) => {
+                        let node = self.simulation.node(*node_id);
+                        format!(
+                            "{} {}",
+                            if index == self.selection_index {
+                                ">"
+                            } else {
+                                " "
+                            },
+                            node.display_path()
+                        )
+                    }
+                    Selection::Leaf { node_id, leaf_name } => {
+                        format!(
+                            "{} {} :: {}",
+                            if index == self.selection_index {
+                                ">"
+                            } else {
+                                " "
+                            },
+                            self.simulation.node(*node_id).display_path(),
+                            leaf_name
+                        )
+                    }
+                };
+                ListItem::new(label)
+            })
+            .collect::<Vec<_>>();
+        frame.render_widget(
+            List::new(items).block(Block::default().borders(Borders::ALL).title("Tree")),
+            area,
+        );
+    }
+
+    fn render_inspector(&self, frame: &mut Frame<'_>, area: Rect) {
+        let selection = self.selected();
+        let body = match selection {
+            Selection::Node(node_id) => {
+                let node = self.simulation.node(*node_id);
+                let mut lines = vec![
+                    Line::from(node.title.clone()).bold(),
+                    Line::from(node.description.clone()),
+                    Line::from(format!("Path: {}", node.display_path())),
+                    Line::from(format!("Children: {}", node.children.len())),
+                    Line::from(format!("Leaves: {}", node.leaves.len())),
+                    Line::from(format!(
+                        "Endpoint procedures: {}",
+                        node.endpoint_procedures.len()
+                    )),
+                    Line::default(),
+                    Line::from("Endpoint procedures:"),
+                ];
+                lines.extend(
+                    node.endpoint_procedures
+                        .iter()
+                        .map(|procedure| Line::from(format!("- {}", procedure.procedure_id))),
+                );
+                lines.extend(
+                    node.leaves
+                        .iter()
+                        .map(|leaf| Line::from(format!("- leaf {}", leaf.name))),
+                );
+                Text::from(lines)
+            }
+            Selection::Leaf { node_id, leaf_name } => {
+                let node = self.simulation.node(*node_id);
+                let leaf = node
+                    .leaves
+                    .iter()
+                    .find(|leaf| &leaf.name == leaf_name)
+                    .expect("selection should stay valid");
+                Text::from(vec![
+                    Line::from(format!("Leaf {}", leaf.name)).bold(),
+                    Line::from(leaf.description.clone()),
+                    Line::from(format!("Node: {}", node.display_path())),
+                    Line::from(format!("Procedures: {}", leaf.procedures.join(", "))),
+                ])
+            }
+        };
+
+        frame.render_widget(
+            Paragraph::new(body)
+                .block(Block::default().borders(Borders::ALL).title("Inspector"))
+                .wrap(Wrap { trim: true }),
+            area,
+        );
+    }
+
+    fn render_trace(&self, frame: &mut Frame<'_>, area: Rect) {
+        let items = self
+            .simulation
+            .trace
+            .iter()
+            .rev()
+            .take(12)
+            .map(|event| {
+                ListItem::new(format!(
+                    "#{:03} {} | {}",
+                    event.tick, event.node_path, event.summary
+                ))
+            })
+            .collect::<Vec<_>>();
+        frame.render_widget(
+            List::new(items).block(Block::default().borders(Borders::ALL).title("Trace")),
+            area,
+        );
+    }
+
+    fn render_hooks(&self, frame: &mut Frame<'_>, area: Rect) {
+        let items = self
+            .simulation
+            .hooks
+            .values()
+            .map(|hook| {
+                let status = if hook.closed { "closed" } else { "open" };
+                ListItem::new(format!(
+                    "#{} {} -> {} [{}] {}",
+                    hook.hook_id,
+                    format_path(&hook.host_path),
+                    format_path(&hook.peer_path),
+                    status,
+                    hook.last_message,
+                ))
+            })
+            .collect::<Vec<_>>();
+        frame.render_widget(
+            List::new(items).block(Block::default().borders(Borders::ALL).title("Hooks")),
+            area,
+        );
+    }
+
+    fn render_footer(&self, frame: &mut Frame<'_>, area: Rect) {
+        let help = vec![
+            Line::from(self.status.clone()).style(Style::default().add_modifier(Modifier::BOLD)),
+            Line::from(
+                "Keys: arrows move selection/scenario | i introspect | e echo leaf | p ping | c chunked | h open chat | d chat data | b chat bye | f invalid peer | s step | a autoplay | q quit",
+            ),
+            Line::from(format!(
+                "Current selection: {}",
+                self.simulation.selection_summary(self.selected())
+            )),
+            Line::from(match self.simulation.recorded_events.last() {
+                Some(RecordedEvent::Data {
+                    node_path, message, ..
+                }) => {
+                    format!(
+                        "Last local event: Data at {node_path} ({})",
+                        String::from_utf8_lossy(&message.data)
+                    )
+                }
+                Some(RecordedEvent::Fault {
+                    node_path, message, ..
+                }) => {
+                    format!(
+                        "Last local event: Fault at {node_path} (0x{:02X})",
+                        message.fault.0
+                    )
+                }
+                Some(RecordedEvent::Call {
+                    node_path, message, ..
+                }) => {
+                    format!(
+                        "Last local event: Call at {node_path} ({})",
+                        message.procedure_id
+                    )
+                }
+                None => "Last local event: none yet".to_owned(),
+            }),
+        ];
+
+        frame.render_widget(
+            Paragraph::new(Text::from(help))
+                .block(Block::default().borders(Borders::ALL).title("Status"))
+                .wrap(Wrap { trim: true }),
+            area,
+        );
+    }
+}
+
+fn build_selections(simulation: &Simulation) -> Vec<Selection> {
+    let mut selections = Vec::new();
+    for node in &simulation.tree.nodes {
+        selections.push(Selection::Node(node.id));
+        for leaf in &node.leaves {
+            selections.push(Selection::Leaf {
+                node_id: node.id,
+                leaf_name: leaf.name.clone(),
+            });
+        }
+    }
+    selections
+}

treetest/src/lib.rs

@@ -0,0 +1,12 @@
+//! Interactive UnShell protocol demo crate.
+//!
+//! This crate intentionally keeps protocol logic in the root `unshell` crate and
+//! uses that implementation as a consumer would: by building endpoint topologies,
+//! simulating packet transport, and rendering an inspector UI around the results.
+
+pub mod app;
+pub mod model;
+pub mod scenarios;
+pub mod sim;
+
+pub use app::run;

treetest/src/main.rs

@@ -0,0 +1,5 @@
+//! Binary entry point for the protocol demo.
+
+fn main() -> Result<(), treetest::app::AppError> {
+    treetest::run()
+}

treetest/src/model.rs

@@ -0,0 +1,184 @@
+//! Static tree and scenario metadata used by the simulator and UI.
+//!
+//! The protocol runtime already owns routing and hook validation state. This
+//! module adds a second, UI-friendly model so the demo can keep titles,
+//! descriptions, selection ids, and behavior metadata without polluting the core
+//! protocol implementation.
+
+use std::collections::BTreeMap;
+
+/// Stable identifier for a node in a demo tree.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct NodeId(pub usize);
+
+/// Supported demo leaf kinds.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LeafKind {
+    /// Uses the built-in echo leaf behavior from `unshell`.
+    Echo,
+}
+
+/// Static leaf declaration used to build a protocol endpoint and describe it in the UI.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LeafSpec {
+    pub name: String,
+    pub description: String,
+    pub kind: LeafKind,
+    pub procedures: Vec<String>,
+}
+
+/// Demo-only endpoint procedure behaviors.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum EndpointProcedureKind {
+    /// Single response that completes the hook immediately.
+    Ping,
+    /// Multi-packet response used to demonstrate chunking and finalization.
+    ChunkedGreeting,
+    /// Bidirectional hook that remains active until one side sends `bye`.
+    Chat,
+}
+
+/// Static endpoint procedure definition.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct EndpointProcedureSpec {
+    pub procedure_id: String,
+    pub description: String,
+    pub kind: EndpointProcedureKind,
+}
+
+/// Recursive scenario node specification.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NodeSpec {
+    /// Empty for the root endpoint.
+    pub segment: String,
+    pub title: String,
+    pub description: String,
+    pub leaves: Vec<LeafSpec>,
+    pub endpoint_procedures: Vec<EndpointProcedureSpec>,
+    pub children: Vec<NodeSpec>,
+}
+
+/// Concrete node metadata used after scenario construction.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DemoNode {
+    pub id: NodeId,
+    pub parent: Option<NodeId>,
+    pub children: Vec<NodeId>,
+    pub path: Vec<String>,
+    pub title: String,
+    pub description: String,
+    pub leaves: Vec<LeafSpec>,
+    pub endpoint_procedures: Vec<EndpointProcedureSpec>,
+}
+
+impl DemoNode {
+    /// Returns a display path that keeps the root easy to recognize in the UI.
+    pub fn display_path(&self) -> String {
+        format_path(&self.path)
+    }
+}
+
+/// Fully flattened tree metadata used by the simulator and UI.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DemoTree {
+    pub root: NodeId,
+    pub nodes: Vec<DemoNode>,
+    path_index: BTreeMap<Vec<String>, NodeId>,
+}
+
+impl DemoTree {
+    /// Builds a flattened tree from a recursive specification.
+    pub fn from_root(spec: &NodeSpec) -> Self {
+        let mut nodes = Vec::new();
+        let mut path_index = BTreeMap::new();
+        let root = Self::push_node(spec, None, &[], &mut nodes, &mut path_index);
+        Self {
+            root,
+            nodes,
+            path_index,
+        }
+    }
+
+    fn push_node(
+        spec: &NodeSpec,
+        parent: Option<NodeId>,
+        base_path: &[String],
+        nodes: &mut Vec<DemoNode>,
+        path_index: &mut BTreeMap<Vec<String>, NodeId>,
+    ) -> NodeId {
+        let id = NodeId(nodes.len());
+        let path = if spec.segment.is_empty() {
+            base_path.to_vec()
+        } else {
+            let mut next = base_path.to_vec();
+            next.push(spec.segment.clone());
+            next
+        };
+
+        nodes.push(DemoNode {
+            id,
+            parent,
+            children: Vec::new(),
+            path: path.clone(),
+            title: spec.title.clone(),
+            description: spec.description.clone(),
+            leaves: spec.leaves.clone(),
+            endpoint_procedures: spec.endpoint_procedures.clone(),
+        });
+        path_index.insert(path.clone(), id);
+
+        let child_ids = spec
+            .children
+            .iter()
+            .map(|child| Self::push_node(child, Some(id), &path, nodes, path_index))
+            .collect::<Vec<_>>();
+        nodes[id.0].children = child_ids;
+        id
+    }
+
+    /// Returns the node with the given id.
+    pub fn node(&self, id: NodeId) -> &DemoNode {
+        &self.nodes[id.0]
+    }
+
+    /// Resolves an absolute path to a node id.
+    pub fn find_by_path(&self, path: &[String]) -> Option<NodeId> {
+        self.path_index.get(path).copied()
+    }
+}
+
+/// Root-focused interaction target shown in the inspector.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Selection {
+    Node(NodeId),
+    Leaf { node_id: NodeId, leaf_name: String },
+}
+
+impl Selection {
+    /// Returns the owning node of this selection.
+    pub fn node_id(&self) -> NodeId {
+        match self {
+            Self::Node(node_id) => *node_id,
+            Self::Leaf { node_id, .. } => *node_id,
+        }
+    }
+}
+
+/// User-facing scenario definition.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ScenarioDefinition {
+    pub name: String,
+    pub description: String,
+    pub highlights: Vec<String>,
+    pub root: NodeSpec,
+    pub initial_selection: Selection,
+}
+
+/// Formats a path the same way throughout the UI and tests.
+pub fn format_path(path: &[String]) -> String {
+    if path.is_empty() {
+        "/".to_owned()
+    } else {
+        format!("/{}", path.join("/"))
+    }
+}

treetest/src/scenarios.rs

@@ -0,0 +1,310 @@
+//! Demo scenarios ranging from simple introspection to multi-hop hooks.
+
+use crate::model::{
+    EndpointProcedureKind, EndpointProcedureSpec, LeafKind, LeafSpec, NodeId, NodeSpec,
+    ScenarioDefinition, Selection,
+};
+
+const PROC_PING: &str = "demo.endpoint.v1.control.ping";
+const PROC_CHUNKED: &str = "demo.endpoint.v1.stream.chunked_greeting";
+const PROC_CHAT: &str = "demo.endpoint.v1.chat.session";
+const PROC_ECHO: &str = "demo.leaf.v1.echo.invoke";
+
+/// Returns all built-in demo scenarios.
+pub fn built_in_scenarios() -> Vec<ScenarioDefinition> {
+    vec![
+        local_introspection(),
+        echo_leaf(),
+        branch_routing(),
+        bidirectional_chat(),
+        fault_showcase(),
+        complex_tree(),
+    ]
+}
+
+fn local_introspection() -> ScenarioDefinition {
+    ScenarioDefinition {
+        name: "Local Introspection".to_owned(),
+        description:
+            "Inspect the root and its immediate child using the required empty procedure id."
+                .to_owned(),
+        highlights: vec![
+            "Blank procedure calls map to protocol introspection.".to_owned(),
+            "Leaf introspection uses the same hook path as endpoint introspection.".to_owned(),
+        ],
+        root: NodeSpec {
+            segment: String::new(),
+            title: "Root".to_owned(),
+            description: "The operator-controlled root endpoint.".to_owned(),
+            leaves: Vec::new(),
+            endpoint_procedures: vec![EndpointProcedureSpec {
+                procedure_id: PROC_PING.to_owned(),
+                description: "Single-packet endpoint response for baseline testing.".to_owned(),
+                kind: EndpointProcedureKind::Ping,
+            }],
+            children: vec![NodeSpec {
+                segment: "alpha".to_owned(),
+                title: "Alpha".to_owned(),
+                description: "A minimal child endpoint with one echo leaf.".to_owned(),
+                leaves: vec![LeafSpec {
+                    name: "echo".to_owned(),
+                    description: "Echoes bytes back through the declared hook.".to_owned(),
+                    kind: LeafKind::Echo,
+                    procedures: vec![PROC_ECHO.to_owned()],
+                }],
+                endpoint_procedures: Vec::new(),
+                children: Vec::new(),
+            }],
+        },
+        initial_selection: Selection::Node(NodeId(0)),
+    }
+}
+
+fn echo_leaf() -> ScenarioDefinition {
+    ScenarioDefinition {
+        name: "Echo Leaf".to_owned(),
+        description: "Call a concrete leaf and watch the hook finish normally.".to_owned(),
+        highlights: vec![
+            "The leaf uses the built-in `Echo` behavior from the core runtime.".to_owned(),
+            "The final response sets `end_hook = true`.".to_owned(),
+        ],
+        root: NodeSpec {
+            segment: String::new(),
+            title: "Root".to_owned(),
+            description: "The operator origin for all demo calls.".to_owned(),
+            leaves: Vec::new(),
+            endpoint_procedures: Vec::new(),
+            children: vec![NodeSpec {
+                segment: "services".to_owned(),
+                title: "Services".to_owned(),
+                description: "Hosts protocol-visible demo leaves.".to_owned(),
+                leaves: vec![LeafSpec {
+                    name: "echo".to_owned(),
+                    description: "Simple echo leaf.".to_owned(),
+                    kind: LeafKind::Echo,
+                    procedures: vec![PROC_ECHO.to_owned()],
+                }],
+                endpoint_procedures: vec![EndpointProcedureSpec {
+                    procedure_id: PROC_CHUNKED.to_owned(),
+                    description: "Three response packets with a clear final chunk.".to_owned(),
+                    kind: EndpointProcedureKind::ChunkedGreeting,
+                }],
+                children: Vec::new(),
+            }],
+        },
+        initial_selection: Selection::Leaf {
+            node_id: NodeId(1),
+            leaf_name: "echo".to_owned(),
+        },
+    }
+}
+
+fn branch_routing() -> ScenarioDefinition {
+    ScenarioDefinition {
+        name: "Branch Routing".to_owned(),
+        description: "Demonstrates longest-prefix routing across sibling branches.".to_owned(),
+        highlights: vec![
+            "Packets descend through the most specific child path.".to_owned(),
+            "Responses route back upward and then down into the hook host subtree.".to_owned(),
+        ],
+        root: NodeSpec {
+            segment: String::new(),
+            title: "Root".to_owned(),
+            description: "The routing apex.".to_owned(),
+            leaves: Vec::new(),
+            endpoint_procedures: Vec::new(),
+            children: vec![
+                NodeSpec {
+                    segment: "alpha".to_owned(),
+                    title: "Alpha".to_owned(),
+                    description: "Intermediate branch.".to_owned(),
+                    leaves: Vec::new(),
+                    endpoint_procedures: Vec::new(),
+                    children: vec![NodeSpec {
+                        segment: "beta".to_owned(),
+                        title: "Beta".to_owned(),
+                        description: "Nested endpoint for longest-prefix routing.".to_owned(),
+                        leaves: vec![LeafSpec {
+                            name: "echo".to_owned(),
+                            description: "Nested echo leaf.".to_owned(),
+                            kind: LeafKind::Echo,
+                            procedures: vec![PROC_ECHO.to_owned()],
+                        }],
+                        endpoint_procedures: vec![EndpointProcedureSpec {
+                            procedure_id: PROC_PING.to_owned(),
+                            description: "Checks routed endpoint procedures.".to_owned(),
+                            kind: EndpointProcedureKind::Ping,
+                        }],
+                        children: Vec::new(),
+                    }],
+                },
+                NodeSpec {
+                    segment: "gamma".to_owned(),
+                    title: "Gamma".to_owned(),
+                    description: "Sibling endpoint used to make the route tree non-trivial."
+                        .to_owned(),
+                    leaves: vec![LeafSpec {
+                        name: "echo".to_owned(),
+                        description: "Sibling echo leaf.".to_owned(),
+                        kind: LeafKind::Echo,
+                        procedures: vec![PROC_ECHO.to_owned()],
+                    }],
+                    endpoint_procedures: Vec::new(),
+                    children: Vec::new(),
+                },
+            ],
+        },
+        initial_selection: Selection::Node(NodeId(2)),
+    }
+}
+
+fn bidirectional_chat() -> ScenarioDefinition {
+    ScenarioDefinition {
+        name: "Bidirectional Chat".to_owned(),
+        description: "Keeps a hook active so the root can continue sending `Data` packets.".to_owned(),
+        highlights: vec![
+            "After activation, either side may send hook data first.".to_owned(),
+            "The chat handler exists outside the core runtime so the demo can show application-level behavior without changing the protocol.".to_owned(),
+        ],
+        root: NodeSpec {
+            segment: String::new(),
+            title: "Root".to_owned(),
+            description: "The operator-controlled hook host.".to_owned(),
+            leaves: Vec::new(),
+            endpoint_procedures: Vec::new(),
+            children: vec![NodeSpec {
+                segment: "chat".to_owned(),
+                title: "Chat Host".to_owned(),
+                description: "Endpoint with a long-lived hook-backed chat procedure.".to_owned(),
+                leaves: Vec::new(),
+                endpoint_procedures: vec![EndpointProcedureSpec {
+                    procedure_id: PROC_CHAT.to_owned(),
+                    description: "Bidirectional hook that replies until it sees `bye`.".to_owned(),
+                    kind: EndpointProcedureKind::Chat,
+                }],
+                children: Vec::new(),
+            }],
+        },
+        initial_selection: Selection::Node(NodeId(1)),
+    }
+}
+
+fn fault_showcase() -> ScenarioDefinition {
+    ScenarioDefinition {
+        name: "Fault Showcase".to_owned(),
+        description: "Use valid and invalid calls to trigger protocol-level faults.".to_owned(),
+        highlights: vec![
+            "Unknown leaf and unknown procedure faults are attributed to the declared hook."
+                .to_owned(),
+            "Packets with an invalid hook peer are rejected and faulted locally.".to_owned(),
+        ],
+        root: NodeSpec {
+            segment: String::new(),
+            title: "Root".to_owned(),
+            description: "Runs fault-focused experiments.".to_owned(),
+            leaves: Vec::new(),
+            endpoint_procedures: Vec::new(),
+            children: vec![NodeSpec {
+                segment: "faults".to_owned(),
+                title: "Fault Lab".to_owned(),
+                description: "One endpoint with one known leaf and one known procedure.".to_owned(),
+                leaves: vec![LeafSpec {
+                    name: "echo".to_owned(),
+                    description: "Valid leaf used to contrast unknown-leaf failures.".to_owned(),
+                    kind: LeafKind::Echo,
+                    procedures: vec![PROC_ECHO.to_owned()],
+                }],
+                endpoint_procedures: vec![EndpointProcedureSpec {
+                    procedure_id: PROC_PING.to_owned(),
+                    description: "Known procedure for contrast against unknown procedures."
+                        .to_owned(),
+                    kind: EndpointProcedureKind::Ping,
+                }],
+                children: Vec::new(),
+            }],
+        },
+        initial_selection: Selection::Node(NodeId(1)),
+    }
+}
+
+fn complex_tree() -> ScenarioDefinition {
+    ScenarioDefinition {
+        name: "Complex Tree".to_owned(),
+        description: "A larger topology that combines leaf calls, endpoint procedures, and nested routing.".to_owned(),
+        highlights: vec![
+            "Use this as a sandbox after learning the smaller scenarios.".to_owned(),
+            "The tree contains both leaf and endpoint interactions so the UI inspector stays interesting.".to_owned(),
+        ],
+        root: NodeSpec {
+            segment: String::new(),
+            title: "Root".to_owned(),
+            description: "Primary operator endpoint.".to_owned(),
+            leaves: Vec::new(),
+            endpoint_procedures: vec![EndpointProcedureSpec {
+                procedure_id: PROC_PING.to_owned(),
+                description: "Root-local endpoint procedure for comparison with remote calls.".to_owned(),
+                kind: EndpointProcedureKind::Ping,
+            }],
+            children: vec![
+                NodeSpec {
+                    segment: "alpha".to_owned(),
+                    title: "Alpha".to_owned(),
+                    description: "Left branch.".to_owned(),
+                    leaves: vec![LeafSpec {
+                        name: "echo".to_owned(),
+                        description: "Echo leaf on alpha.".to_owned(),
+                        kind: LeafKind::Echo,
+                        procedures: vec![PROC_ECHO.to_owned()],
+                    }],
+                    endpoint_procedures: vec![EndpointProcedureSpec {
+                        procedure_id: PROC_CHUNKED.to_owned(),
+                        description: "Chunked endpoint response.".to_owned(),
+                        kind: EndpointProcedureKind::ChunkedGreeting,
+                    }],
+                    children: vec![NodeSpec {
+                        segment: "deep".to_owned(),
+                        title: "Alpha Deep".to_owned(),
+                        description: "Nested node for multi-hop traffic.".to_owned(),
+                        leaves: vec![LeafSpec {
+                            name: "echo".to_owned(),
+                            description: "Deep nested echo leaf.".to_owned(),
+                            kind: LeafKind::Echo,
+                            procedures: vec![PROC_ECHO.to_owned()],
+                        }],
+                        endpoint_procedures: Vec::new(),
+                        children: Vec::new(),
+                    }],
+                },
+                NodeSpec {
+                    segment: "beta".to_owned(),
+                    title: "Beta".to_owned(),
+                    description: "Right branch.".to_owned(),
+                    leaves: Vec::new(),
+                    endpoint_procedures: vec![EndpointProcedureSpec {
+                        procedure_id: PROC_CHAT.to_owned(),
+                        description: "Long-lived chat procedure.".to_owned(),
+                        kind: EndpointProcedureKind::Chat,
+                    }],
+                    children: vec![NodeSpec {
+                        segment: "gamma".to_owned(),
+                        title: "Gamma".to_owned(),
+                        description: "Nested branch with its own ping procedure.".to_owned(),
+                        leaves: vec![LeafSpec {
+                            name: "echo".to_owned(),
+                            description: "Gamma echo leaf.".to_owned(),
+                            kind: LeafKind::Echo,
+                            procedures: vec![PROC_ECHO.to_owned()],
+                        }],
+                        endpoint_procedures: vec![EndpointProcedureSpec {
+                            procedure_id: PROC_PING.to_owned(),
+                            description: "Nested ping procedure.".to_owned(),
+                            kind: EndpointProcedureKind::Ping,
+                        }],
+                        children: Vec::new(),
+                    }],
+                },
+            ],
+        },
+        initial_selection: Selection::Node(NodeId(0)),
+    }
+}

treetest/src/sim.rs

@@ -0,0 +1,842 @@
+//! Crossbeam-backed protocol simulation.
+//!
+//! The simulator never opens real sockets. Each endpoint gets a mailbox, and
+//! forwarded frames are pushed into the next hop's queue. That makes routing and
+//! hook behavior deterministic enough for tests while still feeling like traffic.
+
+use std::collections::{BTreeMap, VecDeque};
+
+use crossbeam_channel::{Receiver, Sender, TryRecvError, unbounded};
+use thiserror::Error;
+use unshell::protocol::tree::{
+    ChildRoute, ConnectionState, Endpoint, Ingress, LeafBehavior, LocalEvent, ProtocolEndpoint,
+};
+use unshell::protocol::{
+    CallMessage, DataMessage, FaultMessage, FrameBytes, PacketHeader, PacketType, decode_frame,
+};
+
+use crate::model::{
+    DemoTree, EndpointProcedureKind, EndpointProcedureSpec, LeafKind, NodeId, ScenarioDefinition,
+    Selection, format_path,
+};
+
+/// User-facing outcome of a root-originated action.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ActionResult {
+    pub label: String,
+    pub hook_id: Option<u64>,
+}
+
+/// Snapshot of a hook interaction observed by the demo.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HookSnapshot {
+    pub hook_id: u64,
+    pub host_path: Vec<String>,
+    pub peer_path: Vec<String>,
+    pub procedure_id: String,
+    pub closed: bool,
+    pub last_message: String,
+}
+
+/// Trace entry shown in the UI and asserted in tests.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TraceEvent {
+    pub tick: u64,
+    pub node_path: String,
+    pub summary: String,
+}
+
+/// Summary of one local protocol event.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RecordedEvent {
+    Data {
+        node_path: String,
+        header: PacketHeader,
+        message: DataMessage,
+    },
+    Fault {
+        node_path: String,
+        header: PacketHeader,
+        message: FaultMessage,
+    },
+    Call {
+        node_path: String,
+        header: PacketHeader,
+        message: CallMessage,
+    },
+}
+
+#[derive(Debug)]
+struct SimNode {
+    parent: Option<NodeId>,
+    children: Vec<NodeId>,
+    endpoint: ProtocolEndpoint,
+    tx: Sender<Envelope>,
+    rx: Receiver<Envelope>,
+}
+
+#[derive(Debug, Clone)]
+struct Envelope {
+    ingress: Ingress,
+    frame: FrameBytes,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct ChatSession {
+    node_id: NodeId,
+    hook_id: u64,
+    host_path: Vec<String>,
+    procedure_id: String,
+}
+
+/// Errors raised by the demo simulator.
+#[derive(Debug, Error)]
+pub enum SimError {
+    #[error("node {0} was not found")]
+    UnknownNode(String),
+    #[error("leaf {leaf_name} was not found on {node_path}")]
+    UnknownLeaf {
+        node_path: String,
+        leaf_name: String,
+    },
+    #[error("procedure {procedure_id} was not found on {node_path}")]
+    UnknownProcedure {
+        node_path: String,
+        procedure_id: String,
+    },
+    #[error("hook {0} was not found")]
+    UnknownHook(u64),
+    #[error("protocol runtime error: {0}")]
+    Protocol(String),
+}
+
+/// Fully built simulation for one scenario.
+#[derive(Debug)]
+pub struct Simulation {
+    pub scenario: ScenarioDefinition,
+    pub tree: DemoTree,
+    nodes: Vec<SimNode>,
+    root_id: NodeId,
+    next_tick: u64,
+    pub trace: VecDeque<TraceEvent>,
+    pub recorded_events: Vec<RecordedEvent>,
+    pub hooks: BTreeMap<u64, HookSnapshot>,
+    chat_sessions: BTreeMap<u64, ChatSession>,
+}
+
+impl Simulation {
+    /// Creates a fresh simulation from a scenario definition.
+    pub fn new(scenario: ScenarioDefinition) -> Result<Self, SimError> {
+        let tree = DemoTree::from_root(&scenario.root);
+        let mut nodes = Vec::with_capacity(tree.nodes.len());
+
+        for demo_node in &tree.nodes {
+            let (tx, rx) = unbounded();
+            let children = demo_node
+                .children
+                .iter()
+                .map(|child_id| ChildRoute {
+                    path: tree.node(*child_id).path.clone(),
+                    state: ConnectionState::Registered,
+                })
+                .collect::<Vec<_>>();
+            let leaves = demo_node
+                .leaves
+                .iter()
+                .map(|leaf| unshell::protocol::tree::LeafSpec {
+                    name: leaf.name.clone(),
+                    procedures: leaf.procedures.clone(),
+                    behavior: match leaf.kind {
+                        LeafKind::Echo => LeafBehavior::Echo,
+                    },
+                })
+                .collect::<Vec<_>>();
+            let parent_path = demo_node
+                .parent
+                .map(|parent_id| tree.node(parent_id).path.clone());
+
+            let mut endpoint =
+                ProtocolEndpoint::new(demo_node.path.clone(), parent_path, children, leaves);
+            for procedure in &demo_node.endpoint_procedures {
+                endpoint
+                    .add_endpoint_procedure(procedure.procedure_id.clone())
+                    .map_err(|error| SimError::Protocol(error.to_string()))?;
+            }
+
+            nodes.push(SimNode {
+                parent: demo_node.parent,
+                children: demo_node.children.clone(),
+                endpoint,
+                tx,
+                rx,
+            });
+        }
+
+        Ok(Self {
+            scenario,
+            tree,
+            nodes,
+            root_id: NodeId(0),
+            next_tick: 1,
+            trace: VecDeque::new(),
+            recorded_events: Vec::new(),
+            hooks: BTreeMap::new(),
+            chat_sessions: BTreeMap::new(),
+        })
+    }
+
+    /// Returns the scenario's initial selection.
+    pub fn initial_selection(&self) -> Selection {
+        self.scenario.initial_selection.clone()
+    }
+
+    /// Returns a node by id.
+    pub fn node(&self, id: NodeId) -> &crate::model::DemoNode {
+        self.tree.node(id)
+    }
+
+    /// Builds and routes an endpoint introspection call from the root.
+    pub fn call_endpoint_introspection(
+        &mut self,
+        node_id: NodeId,
+    ) -> Result<ActionResult, SimError> {
+        let path = self.tree.node(node_id).path.clone();
+        self.dispatch_root_call(path.clone(), None, "", Vec::new())?;
+        Ok(ActionResult {
+            label: format!("Inspect endpoint {}", format_path(&path)),
+            hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
+        })
+    }
+
+    /// Builds and routes a leaf introspection call from the root.
+    pub fn call_leaf_introspection(
+        &mut self,
+        node_id: NodeId,
+        leaf_name: &str,
+    ) -> Result<ActionResult, SimError> {
+        let node_path = self.tree.node(node_id).path.clone();
+        let node_display = self.tree.node(node_id).display_path();
+        self.require_leaf(node_id, leaf_name)?;
+        self.dispatch_root_call(node_path, Some(leaf_name.to_owned()), "", Vec::new())?;
+        Ok(ActionResult {
+            label: format!("Inspect leaf {} on {}", leaf_name, node_display),
+            hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
+        })
+    }
+
+    /// Calls a leaf echo procedure using the selected payload.
+    pub fn call_echo_leaf(
+        &mut self,
+        node_id: NodeId,
+        leaf_name: &str,
+        text: &str,
+    ) -> Result<ActionResult, SimError> {
+        let node_path = self.tree.node(node_id).path.clone();
+        let node_display = self.tree.node(node_id).display_path();
+        let leaf = self.require_leaf(node_id, leaf_name)?;
+        let procedure_id =
+            leaf.procedures
+                .first()
+                .cloned()
+                .ok_or_else(|| SimError::UnknownProcedure {
+                    node_path: node_display.clone(),
+                    procedure_id: "<missing>".to_owned(),
+                })?;
+        self.dispatch_root_call(
+            node_path,
+            Some(leaf_name.to_owned()),
+            &procedure_id,
+            text.as_bytes().to_vec(),
+        )?;
+        Ok(ActionResult {
+            label: format!("Echo via {leaf_name} on {}", node_display),
+            hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
+        })
+    }
+
+    /// Calls an endpoint-level procedure.
+    pub fn call_endpoint_procedure(
+        &mut self,
+        node_id: NodeId,
+        procedure_id: &str,
+        data: Vec<u8>,
+    ) -> Result<ActionResult, SimError> {
+        let node_path = self.tree.node(node_id).path.clone();
+        let node_display = self.tree.node(node_id).display_path();
+        self.require_endpoint_procedure(node_id, procedure_id)?;
+        self.dispatch_root_call(node_path, None, procedure_id, data)?;
+        Ok(ActionResult {
+            label: format!("Call {procedure_id} on {}", node_display),
+            hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
+        })
+    }
+
+    /// Sends a raw call without demo-side validation so tests can exercise
+    /// remote `UnknownLeaf` and `UnknownProcedure` fault behavior.
+    pub fn call_unchecked(
+        &mut self,
+        node_id: NodeId,
+        dst_leaf: Option<&str>,
+        procedure_id: &str,
+        data: Vec<u8>,
+    ) -> Result<ActionResult, SimError> {
+        let node_path = self.tree.node(node_id).path.clone();
+        let node_display = self.tree.node(node_id).display_path();
+        self.dispatch_root_call(node_path, dst_leaf.map(str::to_owned), procedure_id, data)?;
+        Ok(ActionResult {
+            label: format!(
+                "Call {} on {}{}",
+                if procedure_id.is_empty() {
+                    "<introspection>"
+                } else {
+                    procedure_id
+                },
+                node_display,
+                dst_leaf
+                    .map(|leaf_name| format!(" leaf {leaf_name}"))
+                    .unwrap_or_default()
+            ),
+            hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
+        })
+    }
+
+    /// Sends more hook data from the root side.
+    pub fn send_root_hook_data(
+        &mut self,
+        hook_id: u64,
+        text: &str,
+        end_hook: bool,
+    ) -> Result<ActionResult, SimError> {
+        let snapshot = self
+            .hooks
+            .get(&hook_id)
+            .cloned()
+            .ok_or(SimError::UnknownHook(hook_id))?;
+        let frame = self.nodes[self.root_id.0]
+            .endpoint
+            .make_data(
+                snapshot.peer_path.clone(),
+                hook_id,
+                snapshot.procedure_id.clone(),
+                text.as_bytes().to_vec(),
+                end_hook,
+            )
+            .map_err(|error| SimError::Protocol(error.to_string()))?;
+        self.record_trace(
+            self.root_id,
+            format!("root queued hook data for hook #{hook_id}: {text}"),
+        );
+        self.process_local_frame(self.root_id, frame)?;
+        Ok(ActionResult {
+            label: format!("Send hook data #{hook_id}"),
+            hook_id: Some(hook_id),
+        })
+    }
+
+    /// Injects intentionally invalid traffic to demonstrate `InvalidHookPeer`.
+    pub fn inject_invalid_peer_data(
+        &mut self,
+        from_node_id: NodeId,
+        to_node_id: NodeId,
+        hook_id: u64,
+        procedure_id: &str,
+        text: &str,
+    ) -> Result<ActionResult, SimError> {
+        let from_path = self.tree.node(from_node_id).path.clone();
+        let to_path = self.tree.node(to_node_id).path.clone();
+        let header = PacketHeader {
+            packet_type: PacketType::Data,
+            src_path: from_path.clone(),
+            dst_path: to_path.clone(),
+            dst_leaf: None,
+            hook_id: Some(hook_id),
+        };
+        let message = DataMessage {
+            procedure_id: procedure_id.to_owned(),
+            data: text.as_bytes().to_vec(),
+            end_hook: false,
+        };
+        let frame = unshell::protocol::encode_packet(&header, &message)
+            .map_err(|error| SimError::Protocol(error.to_string()))?;
+
+        self.record_trace(
+            from_node_id,
+            format!(
+                "injected invalid peer data toward {} for hook #{hook_id}",
+                format_path(&to_path)
+            ),
+        );
+        self.process_local_frame(from_node_id, frame)?;
+        Ok(ActionResult {
+            label: format!("Inject invalid peer data for hook #{hook_id}"),
+            hook_id: Some(hook_id),
+        })
+    }
+
+    /// Processes one queued frame if available.
+    pub fn step(&mut self) -> Result<bool, SimError> {
+        for node_id in 0..self.nodes.len() {
+            match self.nodes[node_id].rx.try_recv() {
+                Ok(envelope) => {
+                    self.record_trace(
+                        NodeId(node_id),
+                        format!("received frame via {:?}", envelope.ingress),
+                    );
+                    let outcome = self.nodes[node_id]
+                        .endpoint
+                        .receive(&envelope.ingress, envelope.frame)
+                        .map_err(|error| SimError::Protocol(error.to_string()))?;
+                    self.process_outcome(NodeId(node_id), outcome)?;
+                    return Ok(true);
+                }
+                Err(TryRecvError::Disconnected) => {
+                    return Err(SimError::Protocol("mailbox disconnected".to_owned()));
+                }
+                Err(TryRecvError::Empty) => {}
+            }
+        }
+        Ok(false)
+    }
+
+    /// Runs frames until the network becomes idle.
+    pub fn drain(&mut self) -> Result<usize, SimError> {
+        let mut steps = 0;
+        while self.step()? {
+            steps += 1;
+        }
+        Ok(steps)
+    }
+
+    fn dispatch_root_call(
+        &mut self,
+        dst_path: Vec<String>,
+        dst_leaf: Option<String>,
+        procedure_id: &str,
+        data: Vec<u8>,
+    ) -> Result<(), SimError> {
+        let hook_id = self.nodes[self.root_id.0].endpoint.allocate_hook_id();
+        let frame = self.nodes[self.root_id.0]
+            .endpoint
+            .make_call(
+                dst_path.clone(),
+                dst_leaf.clone(),
+                procedure_id.to_owned(),
+                Some(hook_id),
+                data,
+            )
+            .map_err(|error| SimError::Protocol(error.to_string()))?;
+        self.hooks.insert(
+            hook_id,
+            HookSnapshot {
+                hook_id,
+                host_path: Vec::new(),
+                peer_path: dst_path.clone(),
+                procedure_id: procedure_id.to_owned(),
+                closed: false,
+                last_message: format!("created for {}", format_path(&dst_path)),
+            },
+        );
+        self.record_trace(
+            self.root_id,
+            format!(
+                "root queued Call {} toward {}{}",
+                if procedure_id.is_empty() {
+                    "<introspection>"
+                } else {
+                    procedure_id
+                },
+                format_path(&dst_path),
+                dst_leaf
+                    .as_ref()
+                    .map(|leaf| format!(" leaf {leaf}"))
+                    .unwrap_or_default()
+            ),
+        );
+        self.process_local_frame(self.root_id, frame)
+    }
+
+    fn process_local_frame(&mut self, node_id: NodeId, frame: FrameBytes) -> Result<(), SimError> {
+        let outcome = self.nodes[node_id.0]
+            .endpoint
+            .receive(&Ingress::Local, frame)
+            .map_err(|error| SimError::Protocol(error.to_string()))?;
+        self.process_outcome(node_id, outcome)
+    }
+
+    fn process_outcome(
+        &mut self,
+        node_id: NodeId,
+        outcome: unshell::protocol::tree::EndpointOutcome,
+    ) -> Result<(), SimError> {
+        if outcome.dropped {
+            self.record_trace(node_id, "packet dropped".to_owned());
+        }
+
+        for (route, frame) in outcome.forwards {
+            match route {
+                unshell::protocol::tree::RouteDecision::Child(index) => {
+                    let child_id = self.nodes[node_id.0]
+                        .children
+                        .get(index)
+                        .copied()
+                        .ok_or_else(|| {
+                            SimError::Protocol(format!("missing child index {index}"))
+                        })?;
+                    self.record_trace(
+                        node_id,
+                        format!(
+                            "forwarded frame to child {}",
+                            self.node(child_id).display_path()
+                        ),
+                    );
+                    self.nodes[child_id.0]
+                        .tx
+                        .send(Envelope {
+                            ingress: Ingress::Parent,
+                            frame,
+                        })
+                        .map_err(|error| SimError::Protocol(error.to_string()))?;
+                }
+                unshell::protocol::tree::RouteDecision::Parent => {
+                    let parent_id = self.nodes[node_id.0]
+                        .parent
+                        .ok_or_else(|| SimError::Protocol("missing parent route".to_owned()))?;
+                    let child_path = self.node(node_id).path.clone();
+                    self.record_trace(
+                        node_id,
+                        format!(
+                            "forwarded frame to parent {}",
+                            self.node(parent_id).display_path()
+                        ),
+                    );
+                    self.nodes[parent_id.0]
+                        .tx
+                        .send(Envelope {
+                            ingress: Ingress::Child(child_path),
+                            frame,
+                        })
+                        .map_err(|error| SimError::Protocol(error.to_string()))?;
+                }
+                unshell::protocol::tree::RouteDecision::Local => {
+                    return Err(SimError::Protocol(
+                        "local route leaked into forward list".to_owned(),
+                    ));
+                }
+                unshell::protocol::tree::RouteDecision::Drop => {
+                    self.record_trace(node_id, "route decision dropped frame".to_owned());
+                }
+            }
+        }
+
+        for event in outcome.events {
+            self.handle_local_event(node_id, event)?;
+        }
+
+        Ok(())
+    }
+
+    fn handle_local_event(&mut self, node_id: NodeId, event: LocalEvent) -> Result<(), SimError> {
+        let node_path = self.node(node_id).display_path();
+        match event {
+            LocalEvent::Data { header, message } => {
+                let text = String::from_utf8_lossy(&message.data).to_string();
+                self.record_trace(
+                    node_id,
+                    format!(
+                        "local Data on hook #{}: {text}",
+                        header.hook_id.unwrap_or(0)
+                    ),
+                );
+                if let Some(hook_id) = header.hook_id {
+                    if let Some(snapshot) = self.hooks.get_mut(&hook_id) {
+                        snapshot.last_message = if text.is_empty() {
+                            format!("binary payload ({} bytes)", message.data.len())
+                        } else {
+                            text.clone()
+                        };
+                        if message.end_hook {
+                            snapshot.closed = true;
+                        }
+                    }
+                }
+
+                if let Some(session) = self
+                    .chat_sessions
+                    .get(&header.hook_id.unwrap_or(0))
+                    .cloned()
+                    .filter(|session| session.node_id == node_id)
+                {
+                    // Rationale: chat responses are implemented here instead of in the
+                    // core endpoint so the protocol crate stays generic. The simulator
+                    // acts as the application layer sitting above validated hook traffic.
+                    let reply = if text.eq_ignore_ascii_case("bye") {
+                        Some(("chat session closed".to_owned(), true))
+                    } else if !text.is_empty() {
+                        Some((format!("chat ack: {}", text.to_uppercase()), false))
+                    } else {
+                        None
+                    };
+
+                    if let Some((reply, end_hook)) = reply {
+                        let frame = self.nodes[session.node_id.0]
+                            .endpoint
+                            .make_data(
+                                session.host_path.clone(),
+                                session.hook_id,
+                                session.procedure_id.clone(),
+                                reply.clone().into_bytes(),
+                                end_hook,
+                            )
+                            .map_err(|error| SimError::Protocol(error.to_string()))?;
+                        self.record_trace(session.node_id, format!("chat handler sent: {reply}"));
+                        self.process_local_frame(session.node_id, frame)?;
+                        if end_hook {
+                            self.chat_sessions.remove(&session.hook_id);
+                        }
+                    }
+                }
+
+                self.recorded_events.push(RecordedEvent::Data {
+                    node_path,
+                    header,
+                    message,
+                });
+            }
+            LocalEvent::Fault { header, message } => {
+                self.record_trace(
+                    node_id,
+                    format!(
+                        "local Fault on hook #{}: 0x{:02X}",
+                        header.hook_id.unwrap_or(0),
+                        message.fault.0
+                    ),
+                );
+                if let Some(hook_id) = header.hook_id {
+                    if let Some(snapshot) = self.hooks.get_mut(&hook_id) {
+                        snapshot.closed = true;
+                        snapshot.last_message = format!("fault 0x{:02X}", message.fault.0);
+                    }
+                    self.chat_sessions.remove(&hook_id);
+                }
+                self.recorded_events.push(RecordedEvent::Fault {
+                    node_path,
+                    header,
+                    message,
+                });
+            }
+            LocalEvent::Call { header, message } => {
+                self.record_trace(
+                    node_id,
+                    format!(
+                        "local Call {} on {}",
+                        message.procedure_id,
+                        header
+                            .dst_leaf
+                            .as_ref()
+                            .map(|leaf| format!("leaf {leaf}"))
+                            .unwrap_or_else(|| "endpoint".to_owned())
+                    ),
+                );
+                self.handle_application_call(node_id, &header, &message)?;
+                self.recorded_events.push(RecordedEvent::Call {
+                    node_path,
+                    header,
+                    message,
+                });
+            }
+        }
+        Ok(())
+    }
+
+    fn handle_application_call(
+        &mut self,
+        node_id: NodeId,
+        _header: &PacketHeader,
+        message: &CallMessage,
+    ) -> Result<(), SimError> {
+        let Some(hook) = &message.response_hook else {
+            return Ok(());
+        };
+
+        let procedure = self
+            .lookup_endpoint_procedure(node_id, &message.procedure_id)?
+            .clone();
+        match procedure.kind {
+            EndpointProcedureKind::Ping => {
+                let reply = format!("pong from {}", self.node(node_id).display_path());
+                let frame = self.nodes[node_id.0]
+                    .endpoint
+                    .make_data(
+                        hook.return_path.clone(),
+                        hook.hook_id,
+                        procedure.procedure_id.clone(),
+                        reply.clone().into_bytes(),
+                        true,
+                    )
+                    .map_err(|error| SimError::Protocol(error.to_string()))?;
+                self.record_trace(node_id, format!("endpoint sent ping reply: {reply}"));
+                self.process_local_frame(node_id, frame)?;
+            }
+            EndpointProcedureKind::ChunkedGreeting => {
+                for (index, text) in [
+                    "chunk 1: hello from the endpoint",
+                    "chunk 2: routing stayed path-based",
+                    "chunk 3: hook complete",
+                ]
+                .iter()
+                .enumerate()
+                {
+                    let frame = self.nodes[node_id.0]
+                        .endpoint
+                        .make_data(
+                            hook.return_path.clone(),
+                            hook.hook_id,
+                            procedure.procedure_id.clone(),
+                            text.as_bytes().to_vec(),
+                            index == 2,
+                        )
+                        .map_err(|error| SimError::Protocol(error.to_string()))?;
+                    self.record_trace(node_id, format!("endpoint sent chunk {}", index + 1));
+                    self.process_local_frame(node_id, frame)?;
+                }
+            }
+            EndpointProcedureKind::Chat => {
+                self.chat_sessions.insert(
+                    hook.hook_id,
+                    ChatSession {
+                        node_id,
+                        hook_id: hook.hook_id,
+                        host_path: hook.return_path.clone(),
+                        procedure_id: procedure.procedure_id.clone(),
+                    },
+                );
+                let frame = self.nodes[node_id.0]
+                    .endpoint
+                    .make_data(
+                        hook.return_path.clone(),
+                        hook.hook_id,
+                        procedure.procedure_id.clone(),
+                        b"chat ready".to_vec(),
+                        false,
+                    )
+                    .map_err(|error| SimError::Protocol(error.to_string()))?;
+                self.record_trace(node_id, "chat handler opened session".to_owned());
+                self.process_local_frame(node_id, frame)?;
+            }
+        }
+        Ok(())
+    }
+
+    fn lookup_endpoint_procedure(
+        &self,
+        node_id: NodeId,
+        procedure_id: &str,
+    ) -> Result<&EndpointProcedureSpec, SimError> {
+        self.node(node_id)
+            .endpoint_procedures
+            .iter()
+            .find(|procedure| procedure.procedure_id == procedure_id)
+            .ok_or_else(|| SimError::UnknownProcedure {
+                node_path: self.node(node_id).display_path(),
+                procedure_id: procedure_id.to_owned(),
+            })
+    }
+
+    fn require_leaf(
+        &self,
+        node_id: NodeId,
+        leaf_name: &str,
+    ) -> Result<&crate::model::LeafSpec, SimError> {
+        self.node(node_id)
+            .leaves
+            .iter()
+            .find(|leaf| leaf.name == leaf_name)
+            .ok_or_else(|| SimError::UnknownLeaf {
+                node_path: self.node(node_id).display_path(),
+                leaf_name: leaf_name.to_owned(),
+            })
+    }
+
+    fn require_endpoint_procedure(
+        &self,
+        node_id: NodeId,
+        procedure_id: &str,
+    ) -> Result<(), SimError> {
+        self.lookup_endpoint_procedure(node_id, procedure_id)
+            .map(|_| ())
+    }
+
+    fn record_trace(&mut self, node_id: NodeId, summary: String) {
+        let node_path = self.node(node_id).display_path();
+        self.trace.push_back(TraceEvent {
+            tick: self.next_tick,
+            node_path,
+            summary,
+        });
+        self.next_tick += 1;
+        while self.trace.len() > 200 {
+            self.trace.pop_front();
+        }
+    }
+
+    /// Returns a compact description of a frame for debugging.
+    pub fn describe_frame(frame: &[u8]) -> String {
+        match decode_frame(frame) {
+            Ok(parsed) => {
+                let header = parsed.header();
+                format!(
+                    "{:?} {} -> {} hook {:?}",
+                    header.packet_type,
+                    format_path(&header.src_path),
+                    format_path(&header.dst_path),
+                    header.hook_id,
+                )
+            }
+            Err(error) => format!("<invalid frame: {error}>"),
+        }
+    }
+
+    /// Returns the latest fault observed at the root, if any.
+    pub fn latest_root_fault(&self) -> Option<&FaultMessage> {
+        self.recorded_events
+            .iter()
+            .rev()
+            .find_map(|event| match event {
+                RecordedEvent::Fault {
+                    node_path, message, ..
+                } if node_path == "/" => Some(message),
+                _ => None,
+            })
+    }
+
+    /// Returns the latest root data message as utf-8 for tests and status text.
+    pub fn latest_root_data_text(&self) -> Option<String> {
+        self.recorded_events
+            .iter()
+            .rev()
+            .find_map(|event| match event {
+                RecordedEvent::Data {
+                    node_path, message, ..
+                } if node_path == "/" => Some(String::from_utf8_lossy(&message.data).to_string()),
+                _ => None,
+            })
+    }
+
+    /// Returns all hook ids known to the demo in ascending order.
+    pub fn hook_ids(&self) -> Vec<u64> {
+        self.hooks.keys().copied().collect()
+    }
+
+    /// Builds a human-readable description of the current selection.
+    pub fn selection_summary(&self, selection: &Selection) -> String {
+        match selection {
+            Selection::Node(node_id) => {
+                let node = self.node(*node_id);
+                format!("{}: {}", node.display_path(), node.title)
+            }
+            Selection::Leaf { node_id, leaf_name } => {
+                format!("{} leaf {}", self.node(*node_id).display_path(), leaf_name)
+            }
+        }
+    }
+}