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}