1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
//! # burin
//!
//! A retained-mode Rust GUI framework built on the
//! [auralis](https://github.com/chh-itt/auralis) reactive signal kernel.
//!
//! ## Quick start
//!
//! ```no_run
//! use burin::core::{Compositor, Widget};
//! use burin::widgets::display::Text;
//! use auralis_signal::Signal;
//!
//! fn hello() -> impl Widget {
//! Compositor::new(|_scope| {
//! let _greeting = Signal::new("Hello, world!".to_string());
//! Text::new("Hello, world!")
//! })
//! }
//! ```
//!
//! ## Architecture at a glance
//!
//! ```text
//! Signal change → dirty flag (O(1) register)
//! → process_dirty_set (O(k) ancestor walk)
//! → 4-path incremental taffy layout
//! → scene/subtree cache check
//! → paint only dirty subtrees
//! → GPU command submission
//! ```
//!
//! ## Modules
//!
//! | Module | Content |
//! |--------|---------|
//! | [`core`] | Widget trait, Element (12 on-demand sub-structs), ElementArena, Compositor, Prop, Context types, signal bridge |
//! | [`style`] | Color, Rect, Size, Dimension, Point, Padding, Margin, Styled trait, geometry |
//! | [`widgets`] | Built-in widget library (~50 widgets: layout, display, input, overlay, composite, decoration) |
//! | [`event`] | Event system (hit testing, gesture, focus, keyboard, action bindings, propagation) |
//! | [`layout`] | Layout system (incremental taffy bridge, dirty propagation, grid layout) |
//! | [`render`] | Renderer abstraction, Painter API, wgpu GPU backend, tiny-skia CPU backend, text shaping |
//! | [`platform`] | Window (winit event loop), accessibility (accesskit), portal system, clipboard, drag-drop, IME |
//! | [`theme`] | Theme system, Material 3 design tokens, light/dark auto-detection |
//! | [`animation`] | Animation driver, easing curves, property transitions, enter/exit animations |
//! | [`ecs`] | Thread-local tracking sets for O(k) operations (theme/drag/scroll/a11y) |
//! | [`testing`] | TestHarness — headless full-frame simulation without window/GPU |
//! | [`debug`] | Debug utilities |
//! | `i18n` | Internationalization (Fluent) |
//! | [`resource`] | Embedded assets (fonts, icons) |
//!
//! ## Features
//!
//! - **`backend-wgpu`** (default) — GPU rendering via wgpu + glyphon
//! - **`backend-tiny-skia`** — CPU rasterization via tiny-skia + softbuffer + swash
//! - **`system-theme`** (default) — Auto-detect system light/dark preference
//! - **`clipboard`** (default) — Clipboard access via arboard
//! - **`i18n`** — Internationalization via Fluent
//! - **`devtools`** — Devtools via auralis-devtools + profiling
//! - **`hot-reload`** — Hot reload via notify
//! - **`rayon`** — Parallel processing
//! - **`ext-image`** — Image loading (png, jpeg)
//! - **`ext-jiff`** — Date/time support
//! - See `Cargo.toml` for the full list.
//!
//! ## Design principles
//!
//! 1. **Signal is state.** No extra state management abstraction. Reading a `Signal`
//! subscribes; writing notifies. There is no virtual DOM, no diff, no reconciliation.
//! 2. **Composition over macros.** No template language, DSL, or proc macros. UI is pure
//! Rust function calls. IDE completions, refactoring, and go-to-definition work
//! without configuration.
//! 3. **O(k) rendering.** Only elements that changed are processed. Dirty flags propagate
//! only up the ancestor chain, short-circuited at containment boundaries. Paint
//! re-records only dirty subtrees; clean subtrees replay from cache.
//! 4. **`forbid(unsafe_code)`** everywhere except platform boundaries.
//! 5. **Retained mode.** Each widget mounts into a persistent `Element`. Signal changes
//! update in-place; the tree is never rebuilt.
//! 6. **Accessibility is mandatory.** AccessKit integration built-in, not bolted on.
/// Debug-only version-generation trace macro.
/// In debug builds, emits `eprintln!` only when `AURALIS_VGEN=1` is set in
/// the environment (checked once, cached). Always a no-op in release builds.
///
/// Rationale (audit 2026-07-16, F2): unconditional `eprintln!` in the signal
/// and paint hot paths polluted benchmark numbers (`bench` profile inherits
/// `dev`, so `debug_assertions` is on) and spammed stderr in dev runs.
/// Golden snapshot assertion. Renders the harness's most recent frame and
/// compares it against `<CARGO_MANIFEST_DIR>/tests/snapshots/<name>.png`.
/// Bless with `AURALIS_UPDATE_SNAPSHOTS=1`.
///
/// ```ignore
/// h.run_frame();
/// assert_snapshot!(h, "button_primary");
/// assert_snapshot!(h, "button_primary", SnapshotOptions::default().ignore_antialiasing(true));
/// ```
pub use UiError;
/// Re-exports for convenient `use burin::prelude::*;`
// ── Cross-thread convenience re-exports ──