kernel/overlay.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 overlay stroke descriptors.
8//!
9//! These are the pure-data shapes that the workbench compositor emits
10//! for host painters to render on top of graph panes — focus rings,
11//! selection borders, dashed drag-preview outlines, lens-glyph badges.
12//! Descriptors flow through the `FrameViewModel.overlays` field in
13//! the host-neutral vocabulary; egui / iced hosts convert the
14//! portable types back to their native painting primitives at the
15//! render boundary.
16//!
17//! Pre-M4 slice 10 (2026-04-22) these types lived in
18//! `shell/desktop/workbench/compositor_adapter.rs` alongside the
19//! egui-specific painter, and the glyph-overlay types were in
20//! `registries/atomic/lens/registry.rs`. Consolidating them here
21//! removes the last data-shape barrier between `FrameViewModel` and
22//! kernel.
23
24use serde::{Deserialize, Serialize};
25
26use crate::geometry::PortableRect;
27use crate::graph::NodeKey;
28use crate::paint::Stroke;
29use crate::pane::TileRenderMode;
30
31/// One overlay stroke pass the host painter renders over a pane.
32///
33/// Fields use portable types throughout (`PortableRect`,
34/// `kernel::paint::Stroke`) so the descriptor flows across the
35/// host boundary without egui leakage. Egui painters convert at the
36/// draw-call boundary via `egui_rect_from_portable` /
37/// `egui_stroke_from_portable` in `compositor_adapter`; iced painters
38/// consume the portable types directly.
39#[derive(Clone)]
40pub struct OverlayStrokePass {
41 pub node_key: NodeKey,
42 pub tile_rect: PortableRect,
43 pub rounding: f32,
44 pub stroke: Stroke,
45 pub glyph_overlays: Vec<GlyphOverlay>,
46 pub style: OverlayAffordanceStyle,
47 pub render_mode: TileRenderMode,
48}
49
50/// Affordance classification — hosts use this to pick the visual
51/// treatment. Pure data with no host-specific payload.
52#[derive(Clone, Copy, Debug, PartialEq, Eq)]
53pub enum OverlayAffordanceStyle {
54 /// Plain rectangular stroke (focus ring, selection border).
55 RectStroke,
56 /// Dashed rectangular stroke (drag-preview target indicator).
57 DashedRectStroke,
58 /// Stroke applied to just the pane chrome area, not the full
59 /// tile rect.
60 AreaStroke,
61 /// Render chrome only — no stroke overlay.
62 ChromeOnly,
63}
64
65/// Lens-registered glyph overlay attached to a pane corner or center.
66///
67/// The glyph itself is identified by a host-resolved string id; the
68/// host supplies the glyph-to-pixel rendering (usually via an icon
69/// font or SVG atlas). Pre-M4 slice 10 (2026-04-22) this lived in
70/// `registries/atomic/lens/registry.rs`; moved here alongside
71/// `OverlayStrokePass` because they travel together through the
72/// view-model.
73#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
74pub struct GlyphOverlay {
75 pub glyph_id: String,
76 pub anchor: GlyphAnchor,
77}
78
79/// Anchor classification for [`GlyphOverlay`]. Hosts position the
80/// glyph based on this: corner or center of the pane rect.
81#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
82pub enum GlyphAnchor {
83 TopLeft,
84 TopRight,
85 BottomLeft,
86 BottomRight,
87 Center,
88}
89
90#[cfg(test)]
91mod tests {
92 use super::*;
93
94 #[test]
95 fn glyph_overlay_serde_round_trip() {
96 // Serialize → deserialize — pins the wire shape across
97 // persistence / network emission boundaries.
98 let original = GlyphOverlay {
99 glyph_id: "warning".to_string(),
100 anchor: GlyphAnchor::TopRight,
101 };
102 let json = serde_json::to_string(&original).unwrap();
103 let decoded: GlyphOverlay = serde_json::from_str(&json).unwrap();
104 assert_eq!(decoded, original);
105 }
106
107 #[test]
108 fn glyph_anchor_serde_uses_variant_names() {
109 // Pin wire shape — persisted sessions mustn't break when the
110 // enum order changes.
111 let cases = [
112 (GlyphAnchor::TopLeft, "\"TopLeft\""),
113 (GlyphAnchor::TopRight, "\"TopRight\""),
114 (GlyphAnchor::BottomLeft, "\"BottomLeft\""),
115 (GlyphAnchor::BottomRight, "\"BottomRight\""),
116 (GlyphAnchor::Center, "\"Center\""),
117 ];
118 for (variant, expected) in cases {
119 assert_eq!(serde_json::to_string(&variant).unwrap(), expected);
120 }
121 }
122
123 #[test]
124 fn overlay_affordance_style_variants_distinct() {
125 assert_ne!(
126 OverlayAffordanceStyle::RectStroke,
127 OverlayAffordanceStyle::DashedRectStroke
128 );
129 assert_ne!(
130 OverlayAffordanceStyle::AreaStroke,
131 OverlayAffordanceStyle::ChromeOnly
132 );
133 }
134}