Skip to main content

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}