Skip to main content

kernel/
paint.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 paint primitives — `Color` and `Stroke`.
8//!
9//! These types are the kernel's framework-agnostic color + stroke
10//! vocabulary. Host painters convert to backend-specific types
11//! (egui `Color32`, iced `Color`, vello / wgpu colors) at the draw-
12//! call boundary; portable descriptors flow through `kernel`'s
13//! overlay surface (`OverlayStrokePass`), through `host-contract`
14//! ports, and through `graph-canvas`'s `packet::SceneDrawItem` /
15//! `node_style` / `derive` surfaces — all without coupling the kernel
16//! to a renderer crate.
17//!
18//! **Why these live in kernel, not graph-canvas**: previously
19//! they lived in `graph_canvas::packet`, with kernel importing
20//! them — that made `kernel → graph-canvas` an upward dependency
21//! that blocked the
22//! [cartography layer](../../../../design_docs/mere_docs/research/2026-05-10_cartography_layer_brief.md)
23//! brief's revised §9 step 4 (the `graph-layout` extraction).
24//! Moving these into the kernel and having `graph-canvas` re-export
25//! them reverses the edge to its natural direction (kernel is
26//! foundational; everything else depends on it). The graph-canvas
27//! public API stays stable through the re-export.
28//!
29//! ## Host palettes
30//!
31//! [`Color`] is the f32-channel form used for renderer-style
32//! descriptors. u8 host-palette colours (theme tokens and the like)
33//! are tinct's `Srgb`, which the kernel's former `color::Color32`
34//! merged into on 2026-09-24.
35
36use serde::{Deserialize, Serialize};
37
38/// A color in linear RGBA, 0.0–1.0 per channel.
39///
40/// Framework-agnostic color type. Conversion to/from backend-specific
41/// colors (egui `Color32`, iced `Color`, renderer-specific colors)
42/// happens at the host bridge.
43#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
44pub struct Color {
45    pub r: f32,
46    pub g: f32,
47    pub b: f32,
48    pub a: f32,
49}
50
51impl Color {
52    pub const fn new(r: f32, g: f32, b: f32, a: f32) -> Self {
53        Self { r, g, b, a }
54    }
55
56    pub const WHITE: Self = Self::new(1.0, 1.0, 1.0, 1.0);
57    pub const BLACK: Self = Self::new(0.0, 0.0, 0.0, 1.0);
58    pub const TRANSPARENT: Self = Self::new(0.0, 0.0, 0.0, 0.0);
59}
60
61impl Default for Color {
62    fn default() -> Self {
63        Self::WHITE
64    }
65}
66
67/// Stroke style for lines and shape outlines.
68#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
69pub struct Stroke {
70    pub color: Color,
71    pub width: f32,
72}
73
74#[cfg(test)]
75mod tests {
76    use super::*;
77
78    #[test]
79    fn color_default_is_white() {
80        assert_eq!(Color::default(), Color::WHITE);
81    }
82
83    #[test]
84    fn color_constants_have_expected_channel_values() {
85        assert_eq!(Color::WHITE.r, 1.0);
86        assert_eq!(Color::BLACK.r, 0.0);
87        assert_eq!(Color::TRANSPARENT.a, 0.0);
88    }
89
90    #[test]
91    fn color_serde_round_trip() {
92        let original = Color::new(0.25, 0.5, 0.75, 1.0);
93        let json = serde_json::to_string(&original).unwrap();
94        let decoded: Color = serde_json::from_str(&json).unwrap();
95        assert_eq!(decoded, original);
96    }
97
98    #[test]
99    fn stroke_carries_color_and_width() {
100        let stroke = Stroke {
101            color: Color::BLACK,
102            width: 2.0,
103        };
104        assert_eq!(stroke.color, Color::BLACK);
105        assert_eq!(stroke.width, 2.0);
106    }
107}