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