Skip to main content

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}