Skip to main content

kernel/
pane.rs

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