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}