kernel/pane.rs
1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Portable workbench-pane identity + render-mode classification.
5//!
6//! [`PaneId`] is the canonical pane identity used by the pane-hosted
7//! view architecture — distinct from `egui_tiles::TileId` (host layout
8//! identity) and the legacy `u64` persistence key that predated it.
9//!
10//! [`TileRenderMode`] classifies how a pane's viewer produces pixels
11//! — a composited offscreen texture (Servo), an OS-native overlay
12//! window (Wry), direct host rendering, or a placeholder when the
13//! viewer is unresolved. The runtime uses this to drive compositor
14//! routing decisions; hosts read it when selecting a surface backend.
15//!
16//! Both types are fully portable: `PaneId` wraps a UUIDv4, and
17//! `TileRenderMode` is a 4-variant enum with `serde` derives. Pre-M4
18//! slice 8 (2026-04-22) they lived in
19//! `shell/desktop/workbench/pane_model.rs`, alongside larger
20//! shell-coupled types that remain shell-side; the shell module
21//! re-exports these two at their original paths.
22
23use serde::{Deserialize, Serialize};
24
25/// Opaque stable identifier for a workbench pane.
26///
27/// Distinct from `egui_tiles::TileId` (layout tree identity) and the
28/// legacy `u64` persistence key. This is the canonical pane identity
29/// for the pane-hosted view architecture.
30#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
31pub struct PaneId(uuid::Uuid);
32
33impl PaneId {
34 /// Construct a fresh random pane identity (UUIDv4).
35 ///
36 /// Gated to non-WASM targets because `Uuid::new_v4()` pulls in an
37 /// OS randomness source unavailable on `wasm32-unknown-unknown`.
38 /// WASM hosts should obtain the UUID from the host runtime (e.g.
39 /// `crypto.randomUUID()`) and construct via [`PaneId::from_uuid`].
40 #[cfg(not(target_arch = "wasm32"))]
41 pub fn new() -> Self {
42 Self(uuid::Uuid::new_v4())
43 }
44
45 /// Construct a `PaneId` from an existing UUID. Prefer this on
46 /// WASM targets where OS randomness is unavailable.
47 pub fn from_uuid(uuid: uuid::Uuid) -> Self {
48 Self(uuid)
49 }
50
51 /// Borrow the underlying UUID. Useful for serialising or
52 /// rendering; does not expose any mutation point.
53 pub fn as_uuid(&self) -> &uuid::Uuid {
54 &self.0
55 }
56}
57
58#[cfg(not(target_arch = "wasm32"))]
59impl Default for PaneId {
60 fn default() -> Self {
61 Self::new()
62 }
63}
64
65impl std::fmt::Display for PaneId {
66 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
67 write!(f, "pane:{}", self.0)
68 }
69}
70
71/// Node viewer pane render classification.
72///
73/// The runtime's `pane_render_modes` map uses this to decide which
74/// compositor/backend path drives each pane. Hosts render accordingly:
75///
76/// - `CompositedTexture` → read the pane's composited texture and
77/// blit into the layout slot (Servo's standard path).
78/// - `NativeOverlay` → position an OS-native subwindow at the pane's
79/// rect (Wry's path on platforms that prefer native viewports).
80/// - `EmbeddedHost` → draw directly in the active host UI layer (used
81/// for fallback/placeholder viewers that don't need a separate surface).
82/// - `Placeholder` → nothing to render yet; the pane is reserved.
83#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
84pub enum TileRenderMode {
85 /// Viewer renders to a Graphshell-owned composited texture (e.g. Servo).
86 CompositedTexture,
87 /// Viewer uses an OS-native overlay window (e.g. Wry).
88 NativeOverlay,
89 /// Viewer renders directly into the active host UI.
90 #[serde(alias = "EmbeddedEgui")]
91 EmbeddedHost,
92 /// Viewer is unavailable or unresolved for this pane.
93 #[default]
94 Placeholder,
95}
96
97/// Tool pane content variant.
98///
99/// Identifies which tool surface is rendered in a tool pane. New tool
100/// surfaces land as additional variants; the pane model contract stays
101/// stable across additions (serde round-trip remains compatible as
102/// long as variants are added at the tail).
103///
104/// Pre-M4 slice 10 (2026-04-22) this enum lived in
105/// `shell/desktop/workbench/pane_model.rs`. Moved here alongside
106/// [`PaneId`] so `ToolSurfaceReturnTarget::Tool(ToolPaneState)` in
107/// [`crate::routing`] can be fully portable.
108#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
109pub enum ToolPaneState {
110 /// Engine topology, compositor state, and diagnostics inspector.
111 Diagnostics,
112 /// Traversal history timeline and dissolved node archive.
113 HistoryManager,
114 /// Accessibility inspection surface.
115 AccessibilityInspector,
116 /// Legacy file-tree projection surface, now presented as Navigator.
117 FileTree,
118 /// Application and workspace settings.
119 Settings,
120}
121
122impl ToolPaneState {
123 /// The canonical navigator tool surface identity.
124 pub fn navigator_surface() -> Self {
125 Self::FileTree
126 }
127
128 pub fn is_navigator_surface(&self) -> bool {
129 matches!(self, Self::FileTree)
130 }
131
132 pub fn is_file_tree_surface(&self) -> bool {
133 self.is_navigator_surface()
134 }
135
136 /// Human-readable tool title. Chrome surfaces render this directly.
137 pub fn title(&self) -> &'static str {
138 match self {
139 Self::Diagnostics => "Diagnostics",
140 Self::HistoryManager => "History",
141 Self::AccessibilityInspector => "Accessibility",
142 Self::FileTree => "Navigator",
143 Self::Settings => "Settings",
144 }
145 }
146}
147
148// ---------------------------------------------------------------------------
149// Slice 64 — workbench types portable
150// ---------------------------------------------------------------------------
151
152/// Pane chrome / mobility classification. Drives chrome rendering
153/// (full / reduced / chromeless) and tile-tree mobility (whether
154/// the pane participates in normal split moves).
155///
156/// Promoted to kernel in Slice 64 from
157/// `shell/desktop/workbench/pane_model.rs` so the intent vocabulary
158/// (`AppCommand`) can reference it without dragging the workbench
159/// module into portable code.
160#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
161pub enum PanePresentationMode {
162 /// Full tile chrome with normal tile-tree mobility.
163 #[default]
164 Tiled,
165 /// Reduced chrome with position-locked interaction.
166 Docked,
167 /// Chromeless overlay presentation used by ephemeral panes before
168 /// promotion.
169 Floating,
170 /// Content-only presentation; reserved for future use.
171 Fullscreen,
172}
173
174/// Placement context for promoting a floating pane into the tile tree.
175/// Promoted to kernel in Slice 64.
176#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
177pub enum FloatingPaneTargetTileContext {
178 TabGroup,
179 Split,
180 BareGraph,
181}
182
183/// Direction for pane split operations. Promoted to kernel
184/// in Slice 64. (Note: `crates/graph-tree::member::SplitDirection`
185/// and `crates/registrar/register-layout::workbench_surface::SplitDirection`
186/// are separate types in their respective domains; this is the
187/// pane-mutation enum.)
188#[derive(Debug, Clone, Copy, PartialEq, Eq)]
189pub enum SplitDirection {
190 Horizontal,
191 Vertical,
192}
193
194#[cfg(test)]
195mod tests {
196 use super::*;
197
198 #[test]
199 fn pane_id_display_uses_pane_prefix() {
200 let pid = PaneId::from_uuid(uuid::uuid!("00000000-0000-0000-0000-000000000001"));
201 assert_eq!(pid.to_string(), "pane:00000000-0000-0000-0000-000000000001");
202 }
203
204 #[test]
205 fn pane_id_from_uuid_preserves_value() {
206 let uuid = uuid::uuid!("11111111-2222-3333-4444-555555555555");
207 let pid = PaneId::from_uuid(uuid);
208 assert_eq!(pid.as_uuid(), &uuid);
209 }
210
211 #[cfg(not(target_arch = "wasm32"))]
212 #[test]
213 fn pane_id_new_produces_distinct_values() {
214 let a = PaneId::new();
215 let b = PaneId::new();
216 // UUIDv4 collision probability is ~0 for any practical
217 // consecutive calls. Pin the sanity check.
218 assert_ne!(a, b);
219 }
220
221 #[test]
222 fn pane_id_serde_round_trip() {
223 let original = PaneId::from_uuid(uuid::uuid!("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"));
224 let json = serde_json::to_string(&original).unwrap();
225 let decoded: PaneId = serde_json::from_str(&json).unwrap();
226 assert_eq!(decoded, original);
227 }
228
229 #[test]
230 fn tile_render_mode_default_is_placeholder() {
231 // The default matters: a freshly-discovered pane with no
232 // viewer resolution yet should not be treated as composited.
233 // Pin that default stays Placeholder across any enum-reorder.
234 assert_eq!(TileRenderMode::default(), TileRenderMode::Placeholder);
235 }
236
237 #[test]
238 fn tile_render_mode_serde_uses_variant_names() {
239 // The render-mode is persisted in session state via serde; its
240 // discriminants must remain stable or existing persisted
241 // sessions fail to deserialise after an update. Pin the wire
242 // shape for each variant.
243 for (variant, expected) in [
244 (TileRenderMode::CompositedTexture, "\"CompositedTexture\""),
245 (TileRenderMode::NativeOverlay, "\"NativeOverlay\""),
246 (TileRenderMode::EmbeddedHost, "\"EmbeddedHost\""),
247 (TileRenderMode::Placeholder, "\"Placeholder\""),
248 ] {
249 let json = serde_json::to_string(&variant).unwrap();
250 assert_eq!(json, expected);
251 let back: TileRenderMode = serde_json::from_str(&json).unwrap();
252 assert_eq!(back, variant);
253 }
254
255 let legacy: TileRenderMode = serde_json::from_str("\"EmbeddedEgui\"").unwrap();
256 assert_eq!(legacy, TileRenderMode::EmbeddedHost);
257 }
258}