Skip to main content

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}