brink_runtime/
debug.rs

1//! Read-only debug introspection for the studio State View.
2//!
3//! [`Story::debug_snapshot`](crate::Story::debug_snapshot) produces a
4//! [`DebugSnapshot`] — a name-resolved, structured view of the runtime's
5//! current state (location, globals, call stack, visit counts, pending
6//! choices, rng). Unlike the VM internals, everything here is resolved to
7//! author-facing knot/stitch paths and variable names.
8//!
9//! This is built on demand and is not on any hot path.
10
11use std::collections::HashMap;
12
13use brink_format::{DefinitionId, Value};
14
15use crate::program::Program;
16
17/// A structured, read-only snapshot of the runtime's current state.
18pub struct DebugSnapshot {
19    /// Execution status: `active` / `waiting_for_choice` / `done` / `ended`.
20    pub status: &'static str,
21    /// Nearest named knot/stitch the cursor is currently in, if resolvable.
22    pub current_location: Option<String>,
23    /// Current turn index.
24    pub turn_index: u32,
25    /// Global variables and their current values (display strings).
26    pub globals: Vec<DebugGlobal>,
27    /// Active call frames, innermost (current) first.
28    pub call_stack: Vec<DebugFrame>,
29    /// Per-knot/stitch visit counts, sorted by path.
30    pub visit_counts: Vec<DebugVisit>,
31    /// Choices currently offered to the player.
32    pub pending_choices: Vec<DebugChoice>,
33    /// Story RNG state.
34    pub rng: DebugRng,
35}
36
37/// A global variable and its current value.
38pub struct DebugGlobal {
39    pub name: String,
40    pub value: String,
41}
42
43/// One call frame, resolved to a knot/stitch path.
44pub struct DebugFrame {
45    /// Frame kind: `root` / `function` / `tunnel` / `thread` / `external` / `eval`.
46    pub kind: &'static str,
47    /// Nearest named container for this frame, if resolvable.
48    pub location: Option<String>,
49    /// Number of temporary (local) variables in this frame.
50    pub temps: usize,
51}
52
53/// A visit count for a named knot/stitch.
54pub struct DebugVisit {
55    pub path: String,
56    pub count: u32,
57}
58
59/// A pending choice and the knot it targets.
60pub struct DebugChoice {
61    pub text: String,
62    pub target: Option<String>,
63}
64
65/// Story RNG state.
66pub struct DebugRng {
67    pub seed: i32,
68    pub previous: i32,
69}
70
71/// Resolves container indices / definition ids to author-facing paths and
72/// formats values for display. Holds a one-time reverse map of the program's
73/// `address_by_path` table.
74pub(crate) struct NameResolver<'p> {
75    program: &'p Program,
76    /// `container_idx → shortest knot/stitch path` (offset-0 scope entries).
77    rev: HashMap<u32, String>,
78}
79
80impl<'p> NameResolver<'p> {
81    pub(crate) fn new(program: &'p Program) -> Self {
82        let mut rev: HashMap<u32, String> = HashMap::new();
83        for (path, target) in &program.address_by_path {
84            if target.byte_offset != 0 {
85                continue;
86            }
87            let idx = &target.container_idx;
88            // Deterministic on collision: shortest path, then lexicographically
89            // smallest — independent of HashMap iteration order.
90            let better = match rev.get(idx) {
91                None => true,
92                Some(existing) => {
93                    path.len() < existing.len()
94                        || (path.len() == existing.len() && path.as_str() < existing.as_str())
95                }
96            };
97            if better {
98                rev.insert(*idx, path.clone());
99            }
100        }
101        Self { program, rev }
102    }
103
104    /// The knot/stitch path for a container, if it names a scope.
105    pub(crate) fn container_path(&self, idx: u32) -> Option<&str> {
106        self.rev.get(&idx).map(String::as_str)
107    }
108
109    /// The knot/stitch path a definition id lives in, if resolvable.
110    pub(crate) fn def_path(&self, id: DefinitionId) -> Option<&str> {
111        let (idx, _) = self.program.resolve_target(id)?;
112        self.container_path(idx)
113    }
114
115    /// Format a runtime value for display, resolving names where possible.
116    pub(crate) fn format_value(&self, value: &Value) -> String {
117        match value {
118            Value::Int(i) => i.to_string(),
119            Value::Float(f) => f.to_string(),
120            Value::Bool(b) => b.to_string(),
121            Value::String(s) => format!("\"{s}\""),
122            Value::Null => "null".to_owned(),
123            Value::List(list) => {
124                let members: Vec<&str> = list
125                    .items
126                    .iter()
127                    .filter_map(|id| self.program.list_item_name(*id))
128                    .collect();
129                format!("({})", members.join(", "))
130            }
131            Value::DivertTarget(id) => match self.def_path(*id) {
132                Some(p) => format!("-> {p}"),
133                None => "-> ?".to_owned(),
134            },
135            Value::VariablePointer(id) => match self.program.global_var_name(*id) {
136                Some(n) => format!("ref {n}"),
137                None => "ref ?".to_owned(),
138            },
139            Value::TempPointer { slot, frame_depth } => {
140                format!("temp[{slot}]@{frame_depth}")
141            }
142            Value::FragmentRef(idx) => format!("<fragment {idx}>"),
143        }
144    }
145}
brink_runtime/debug.rs

brink_runtime/
debug.rs
