Skip to main content

day_spec/
lib.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! day-spec: the toolkit specification (DESIGN.md §8).
5//!
6//! Backends depend only on this crate (never on day-core). One backend is linked per binary;
7//! `day-core` is monomorphized over the concrete [`Toolkit`].
8
9use std::any::Any;
10use std::collections::HashMap;
11
12pub use day_geometry::*;
13
14pub mod controls;
15pub use controls::datetime::{DayDate, DayTime};
16
17pub mod applications;
18pub mod capture;
19/// Inline markdown → styled runs (docs/markdown.md). Lives here rather than in day-pieces
20/// because it produces `TextRun`s, and every format codec beside it reads the same model.
21pub mod markdown;
22/// Bundled-resource random-access API + the per-backend `ResourceOpener` hook (§18.3).
23pub mod resource;
24/// Styled text: the document model `label().runs(…)` renders and `day-piece-text-editor` edits,
25/// with the Markdown / HTML / RTF codecs over it (docs/texteditor.md).
26pub mod styled;
27/// Import and export for [`StyledText`]: Markdown, HTML and RTF (docs/texteditor.md).
28pub mod styled_codec;
29pub mod transfer;
30
31pub use resource::{
32    AssetDir, AssetName, FontFamily, ImageName, Resource, ResourceOpener, VectorName,
33    resolve_asset_dir, resolve_image_file, resource, set_resource_opener,
34};
35pub use styled::{
36    ListStyle, ParagraphAlign, ParagraphRun, ParagraphStyle, RunStyle, StyledText, Underline,
37    coalesce_runs, paragraph_bounds, paragraphs_are_valid,
38};
39pub use styled_codec::{
40    DocStyle, html_to_styled, markdown_to_styled, rtf_to_styled, styled_to_html,
41    styled_to_markdown, styled_to_rtf,
42};
43
44/// Bundled custom fonts: name-table parsing, runtime font directory, family → file resolution
45/// (§18.4). Shared by the CLI stagers and the backends' startup registration. Lives in the leaf
46/// `day-fonts` crate (pure std, no `day-geometry`), re-exported here so `day_spec::fonts::…` is
47/// unchanged for the backends while the CLI can depend on `day-fonts` alone.
48pub use day_fonts as fonts;
49
50/// The route inside a deep-link URL (docs/deep-links.md): everything after `scheme://`,
51/// query included (`notes://mail/inbox?hint=x` ⇒ `mail/inbox?hint=x`). A string with no
52/// scheme passes through unchanged (it is already a route). One definition, shared by every
53/// platform's intake and the dayscript `deep_link` step, so a URL maps to the same route
54/// bytes everywhere; percent-decoding stays with the route parser (docs/navigation.md).
55pub fn route_of_url(url: &str) -> String {
56    match url.split_once("://") {
57        Some((_, rest)) => rest.to_string(),
58        None => url.to_string(),
59    }
60}
61
62// ---------------------------------------------------------------------------
63// Identity
64// ---------------------------------------------------------------------------
65
66/// Interned piece-kind key, e.g. `"day.label"` or `"acme.combobox"`.
67pub type PieceKind = &'static str;
68
69/// Declare the built-in piece vocabulary once: the [`Builtin`] enum, its string keys, and the
70/// `kinds::*` constants are all generated from this list, so they can never drift apart.
71///
72/// Adding a variant here is a breaking change for backends: every `Toolkit` must decide how
73/// to realize the new kind, and the exhaustive `match Builtin` in each backend's `realize`
74/// turns that decision into a compile error rather than a runtime placeholder.
75macro_rules! builtin_kinds {
76    ($( $(#[$meta:meta])* $variant:ident = $konst:ident => $key:literal ),+ $(,)?) => {
77        /// Every piece kind Day itself defines (§5.3). Backends match on this exhaustively in
78        /// `realize`; anything outside it is an extension piece resolved through the
79        /// [`Registry`] by its string [`PieceKind`].
80        #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
81        pub enum Builtin {
82            $( $(#[$meta])* $variant, )+
83        }
84
85        impl Builtin {
86            /// This kind's wire key: the same string as the matching `kinds::*` constant.
87            pub const fn key(self) -> PieceKind {
88                match self { $( Builtin::$variant => $key, )+ }
89            }
90
91            /// The built-in this key names, or `None` for an extension piece's kind.
92            pub fn from_key(kind: PieceKind) -> Option<Builtin> {
93                match kind {
94                    $( $key => Some(Builtin::$variant), )+
95                    _ => None,
96                }
97            }
98
99            /// Every built-in, in declaration order (conformance tests iterate it).
100            pub const ALL: &'static [Builtin] = &[ $( Builtin::$variant, )+ ];
101        }
102
103        /// The built-in piece keys as plain strings, for the registry and the `PieceKind` API.
104        pub mod kinds {
105            $( $(#[$meta])* pub const $konst: super::PieceKind = super::Builtin::$variant.key(); )+
106        }
107    };
108}
109
110builtin_kinds! {
111    /// A dumb native panel (the column/row/stack backing).
112    Container = CONTAINER => "day.container",
113    Label = LABEL => "day.label",
114    Button = BUTTON => "day.button",
115    Toggle = TOGGLE => "day.toggle",
116    Slider = SLIDER => "day.slider",
117    TextField = TEXT_FIELD => "day.text_field",
118    /// A native multi-line text editor (docs/textarea.md). Built-in since 2026-07 (previously
119    /// the satellite `day-piece-textarea`).
120    TextArea = TEXT_AREA => "day.text_area",
121    /// A native option picker with menu/segmented/inline stylings (docs/picker.md). Built-in
122    /// since 2026-07 (previously the satellite `day-piece-picker`).
123    Picker = PICKER => "day.picker",
124    Divider = DIVIDER => "day.divider",
125    Scroll = SCROLL => "day.scroll",
126    Image = IMAGE => "day.image",
127    /// Progress indicator: determinate bar (fraction) or indeterminate spinner.
128    Progress = PROGRESS => "day.progress",
129    Canvas = CANVAS => "day.canvas",
130    /// Navigation host (docs/navigation.md): stack on mobile, split panes on desktop.
131    Nav = NAV => "day.nav",
132    /// One destination's native container inside a NAV host.
133    NavPage = NAV_PAGE => "day.nav_page",
134    /// Native navigation item list (docs/navigation.md): NSOutlineView source list /
135    /// GtkListBox navigation-sidebar / QListWidget / UITableView rows with chevrons.
136    NavMenu = NAV_MENU => "day.nav_menu",
137    /// Native recycling list (docs/list.md): NSTableView / UITableView / RecyclerView /
138    /// GtkListView / QListView. Owns scrolling + cell reuse; Day binds row content on demand.
139    List = LIST => "day.list",
140    /// A recycled row's content anchor inside a `LIST`; Day adopts the native cell as its handle.
141    /// Adopted, never realized: `Toolkit::adopt` wraps the native cell, so backends' `realize`
142    /// never sees this kind.
143    ListCell = LIST_CELL => "day.list_cell",
144    /// Native hierarchical tree (docs/tree.md): NSOutlineView / sidebar collection list /
145    /// GtkListView+TreeListModel / WinUI TreeView / ArkTS TreeView. Rows nest, disclose, and
146    /// drag-to-reparent; Day binds row content on demand through `Toolkit::attach_tree`.
147    /// Row cells are adopted (the same `LIST_CELL` anchor path as `List`).
148    Tree = TREE => "day.tree",
149    /// A fullscreen cover (docs/cover.md): a modal surface presented over the whole window,
150    /// edge-to-edge, driven by `CoverPatch::{Present,Dismiss}`. The handle is the cover's
151    /// content container; its frame is native-owned while presented (the backend sizes it to
152    /// the safe area and reports it via `Event::FrameChanged`).
153    Cover = COVER => "day.cover",
154    /// Content beside a trailing inspector pane (docs/inspector.md): the native split whose
155    /// second pane is a show/hidable properties panel. Exactly two `INSPECTOR_PANE` children:
156    /// the content, then the panel (`InspectorPaneProps::panel`). Only realized where
157    /// `Cap::Inspector` answers `Native`; everywhere else the `inspector` piece composes the
158    /// pane from plain containers and this kind never reaches the backend.
159    Inspector = INSPECTOR => "day.inspector",
160    /// One pane's container inside an `INSPECTOR` host: the `NAV_PAGE` of the inspector split.
161    /// Its frame is native-owned (the splitter/dock sizes it), reported via
162    /// `Event::FrameChanged` on this node; Day lays the pane's content out inside it.
163    InspectorPane = INSPECTOR_PANE => "day.inspector_pane",
164    /// Two panes with a divider the user drags (docs/split.md): the toolkit's own splitter,
165    /// side by side or stacked (`SplitProps::axis`), the first pane's share bound to the app
166    /// (`SplitProps::fraction`, reported back as `Event::ValueChanged`). Exactly two
167    /// `SPLIT_PANE` children, first then second. Only realized where `Cap::Split` answers
168    /// `Native`; everywhere else the `split` piece composes the panes and draws the divider
169    /// itself, and this kind never reaches the backend.
170    Split = SPLIT => "day.split",
171    /// One pane's container inside a `SPLIT` host: native-owned frame (the splitter sizes it),
172    /// reported via `Event::FrameChanged` on this node, like an `INSPECTOR_PANE`.
173    SplitPane = SPLIT_PANE => "day.split_pane",
174    /// A list row's standard content (docs/list.md "List items"): a leading icon, a title, an
175    /// optional subtitle and trailing detail, and a check mark, drawn the way the platform
176    /// draws its own list rows: a `UIListContentView` with the cell's default content
177    /// configuration, a Material list item, an `NSTableCellView`'s image and text, a GTK row
178    /// box. Only realized where `Cap::ListItem` answers `Native`; everywhere else the
179    /// `list_item` piece composes the same content and this kind never reaches the backend.
180    ListItem = LIST_ITEM => "day.list_item",
181}
182
183/// Whether a kind is worth asking [`Toolkit::first_baseline`] about (docs/baseline.md).
184///
185/// A blocklist, not an allowlist: the structural and graphic kinds below have no text of their
186/// own, and everything else (including extension pieces like the date/time pickers, whose kinds
187/// day-spec has never heard of) is assumed to be worth asking. An extension piece that turns
188/// out to have no baseline answers `None`, which costs one query; an allowlist would instead
189/// silently leave every extension piece centered, which is the bug this shape avoids.
190pub fn kind_has_baseline(kind: PieceKind) -> bool {
191    !matches!(
192        Builtin::from_key(kind),
193        Some(
194            Builtin::Container
195                | Builtin::Scroll
196                | Builtin::Divider
197                | Builtin::Image
198                | Builtin::Canvas
199                | Builtin::Slider
200                | Builtin::Toggle
201                | Builtin::Progress
202                | Builtin::Nav
203                | Builtin::NavPage
204                | Builtin::NavMenu
205                | Builtin::Split
206                | Builtin::SplitPane
207                | Builtin::List
208                | Builtin::ListCell
209                | Builtin::Cover
210                | Builtin::Inspector
211                | Builtin::InspectorPane
212        )
213    )
214}
215
216/// Placeholder leaves: the one hole in Day's rendering that is invisible to a screenshot.
217///
218/// When a backend has no renderer for a kind it realizes a visible `⟨kind⟩` label rather than
219/// failing. That is the right runtime behavior, but it means a missing renderer looks like a
220/// rendered app: the walkthrough passes, and the gallery's validator (which counts distinct
221/// colors) sees nothing wrong. That is how a stale `skip_on:` survived in the showcase
222/// walkthrough after the renderer it skipped had landed.
223///
224/// So every backend reports here instead of keeping its own warn-once set. The table is process-
225/// wide and append-only, which gives dayscript's `assert_no_placeholders` something to assert on
226/// (`crates/day-script`): a placeholder becomes a test failure instead of a silent gap.
227pub mod placeholder {
228    use super::PieceKind;
229    use std::collections::BTreeSet;
230    use std::sync::{Mutex, OnceLock};
231
232    fn table() -> &'static Mutex<BTreeSet<PieceKind>> {
233        static TABLE: OnceLock<Mutex<BTreeSet<PieceKind>>> = OnceLock::new();
234        TABLE.get_or_init(|| Mutex::new(BTreeSet::new()))
235    }
236
237    /// Record that `toolkit` had no renderer for `kind` and warn, once per kind, however many
238    /// nodes of it are realized. Call from a backend's `realize` fallback arm.
239    pub fn report(kind: PieceKind, toolkit: &str) {
240        let Ok(mut seen) = table().lock() else { return };
241        if seen.insert(kind) {
242            log::warn!(
243                "no renderer for piece kind \"{kind}\" on {toolkit} — is the piece's \
244                 {toolkit} feature enabled? (rendering a placeholder)"
245            );
246        }
247    }
248
249    /// Every kind that has rendered a placeholder in this process, sorted. Empty is the goal.
250    pub fn seen() -> Vec<PieceKind> {
251        table()
252            .lock()
253            .map(|s| s.iter().copied().collect())
254            .unwrap_or_default()
255    }
256}
257
258/// Downcast a realize/update payload to the props/patch type a backend arm expects,
259/// warning (once per kind, via [`placeholder::report`]) instead of panicking on a
260/// mismatch. A mismatch means a piece registered under a builtin key or a day-core
261/// regression; degrade to the placeholder path, never abort: most backend arms run
262/// inside native up-calls, where a panic is a process kill.
263pub fn props_of<'a, T: 'static>(
264    kind: PieceKind,
265    toolkit: &str,
266    any: &'a dyn std::any::Any,
267) -> Option<&'a T> {
268    let p = any.downcast_ref::<T>();
269    if p.is_none() {
270        placeholder::report(kind, toolkit);
271    }
272    p
273}
274
275/// Pointer-keyed per-view side tables with an automatic release sweep.
276///
277/// Backends keep auxiliary per-view state in thread-local maps keyed by the native
278/// handle's address. Historically each map needed its own line in `release()`, a
279/// checklist that drifted repeatedly (missed entries have produced both leaks and
280/// stale-pointer CI segfaults, since a freed address gets recycled). A [`crate::sidetable::SideTable`]
281/// registers itself with a per-thread sweeper list at construction, so a backend's
282/// `release()` calls [`crate::sidetable::sweep`] once and every table, present and future, drops its
283/// entry for that handle, running its teardown hook if one was given.
284pub mod sidetable {
285    use std::cell::RefCell;
286    use std::collections::HashMap;
287    use std::rc::Rc;
288
289    /// One table's "remove this key" hook, registered at construction.
290    type Sweeper = Rc<dyn Fn(usize)>;
291
292    thread_local! {
293        static SWEEPERS: RefCell<Vec<Sweeper>> = const { RefCell::new(Vec::new()) };
294    }
295
296    /// A pointer-keyed map swept automatically by [`crate::sidetable::sweep`]. Construct inside a
297    /// `thread_local!` initializer; the optional teardown hook runs for each removed
298    /// value (release a retained native object, dispose an owned child, …), both on sweep
299    /// and on plain [`SideTable::remove`], so teardown cannot be bypassed by accident.
300    pub struct SideTable<V: 'static> {
301        map: Rc<RefCell<HashMap<usize, V>>>,
302        teardown: Option<Rc<dyn Fn(V)>>,
303    }
304
305    impl<V> Default for SideTable<V> {
306        fn default() -> Self {
307            Self::new()
308        }
309    }
310
311    impl<V> SideTable<V> {
312        pub fn new() -> Self {
313            Self::build(None)
314        }
315
316        /// A table whose values need active teardown when their view goes away.
317        pub fn with_teardown(teardown: impl Fn(V) + 'static) -> Self {
318            Self::build(Some(Rc::new(teardown)))
319        }
320
321        fn build(teardown: Option<Rc<dyn Fn(V)>>) -> Self {
322            let map: Rc<RefCell<HashMap<usize, V>>> = Rc::default();
323            let (m, t) = (map.clone(), teardown.clone());
324            SWEEPERS.with(|s| {
325                s.borrow_mut().push(Rc::new(move |key| {
326                    // Remove under the borrow, tear down outside it: hooks may re-enter
327                    // toolkit code that reads other tables.
328                    let v = m.borrow_mut().remove(&key);
329                    if let (Some(v), Some(t)) = (v, &t) {
330                        t(v);
331                    }
332                }));
333            });
334            SideTable { map, teardown }
335        }
336
337        pub fn insert(&self, key: usize, value: V) -> Option<V> {
338            self.map.borrow_mut().insert(key, value)
339        }
340
341        /// Remove and tear down the entry (returns `None` always when a teardown hook
342        /// exists, because the value is consumed by it; use [`SideTable::take`] to skip it).
343        pub fn remove(&self, key: usize) -> Option<V> {
344            let v = self.map.borrow_mut().remove(&key)?;
345            match &self.teardown {
346                Some(t) => {
347                    t(v);
348                    None
349                }
350                None => Some(v),
351            }
352        }
353
354        /// Remove without running the teardown hook (the caller takes ownership).
355        pub fn take(&self, key: usize) -> Option<V> {
356            self.map.borrow_mut().remove(&key)
357        }
358
359        pub fn contains(&self, key: usize) -> bool {
360            self.map.borrow().contains_key(&key)
361        }
362
363        pub fn get(&self, key: usize) -> Option<V>
364        where
365            V: Clone,
366        {
367            self.map.borrow().get(&key).cloned()
368        }
369
370        /// Run `f` on the value in place (returns `None` if absent).
371        pub fn with<R>(&self, key: usize, f: impl FnOnce(&mut V) -> R) -> Option<R> {
372            self.map.borrow_mut().get_mut(&key).map(f)
373        }
374
375        /// Run `f` over every `(key, value)` (immutable; do not re-enter this table).
376        pub fn for_each(&self, mut f: impl FnMut(usize, &V)) {
377            for (k, v) in self.map.borrow().iter() {
378                f(*k, v);
379            }
380        }
381    }
382
383    /// Remove `key` from every table registered on this thread, running teardowns.
384    /// Call once from a backend's `release()` (and once per auxiliary native object a
385    /// release frees, e.g. an owned content container).
386    pub fn sweep(key: usize) {
387        // Clone the sweeper list first: a teardown may construct a new SideTable
388        // (registering a sweeper) without deadlocking on the borrow.
389        let sweepers: Vec<Sweeper> = SWEEPERS.with(|s| s.borrow().clone());
390        for f in sweepers {
391            f(key);
392        }
393    }
394}
395
396/// Containment for FFI entry points: native callbacks, JNI up-calls, posted-closure
397/// trampolines. A Rust panic unwinding out of an `extern "C"` frame is undefined
398/// behavior (an abort), so every backend trampoline runs its body through
399/// [`ffi_guard::contain`]: a caught panic is reported, the installed recovery hook
400/// restores runtime coherence (day-core installs the reactive runtime's
401/// `recover_from_panic` at boot), and the given default is returned.
402pub mod ffi_guard {
403    use std::sync::OnceLock;
404
405    static RECOVERY: OnceLock<fn()> = OnceLock::new();
406
407    /// Install the post-panic recovery hook (idempotent; first install wins). day-core
408    /// registers `day_reactive::recover_from_panic` here so a contained panic cannot
409    /// leave the reactive observer stack stranded.
410    pub fn set_recovery(f: fn()) {
411        let _ = RECOVERY.set(f);
412    }
413
414    /// Run `f`, containing any panic; on panic, report, run the recovery hook, and
415    /// return `default`.
416    pub fn contain<R>(default: R, f: impl FnOnce() -> R) -> R {
417        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)) {
418            Ok(r) => r,
419            Err(payload) => {
420                let msg = payload
421                    .downcast_ref::<&str>()
422                    .map(|s| s.to_string())
423                    .or_else(|| payload.downcast_ref::<String>().cloned())
424                    .unwrap_or_else(|| "<non-string panic>".into());
425                log::error!("panic contained at an FFI boundary: {msg}");
426                if let Some(recover) = RECOVERY.get() {
427                    recover();
428                }
429                default
430            }
431        }
432    }
433}
434
435/// Realized-node identity as seen by backends (day-core's slotmap key, FFI-encoded).
436#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
437pub struct NodeId(pub u64);
438
439/// Default navigation sidebar width (split presentation) until the pane reports its size.
440/// Semantic container surfaces (see `ContainerProps::role`): each backend maps a role to its
441/// own theme-adaptive material so the fill tracks light/dark mode without app code.
442#[derive(Clone, Copy, Debug, PartialEq, Eq)]
443pub enum SurfaceRole {
444    /// A form `section` card, the platform's grouped-content background: AppKit quaternary
445    /// system fill, libadwaita `.card`, Qt `palette(alternate-base)`, UIKit tertiary system
446    /// fill, Material surface-container, XAML card background brush.
447    SectionCard,
448    /// The window's own background, the surface a page sits on: what an opaque cover paints
449    /// by default, and the card of a composed modal sheet (docs/cover.md "Modal sheet").
450    Window,
451    /// The layer between a composed modal sheet and the page under it, which says the page is
452    /// out of reach until the sheet goes. The container's `background` is the plain dimming a
453    /// backend draws when it has no material of its own; the web frosts the page instead.
454    Scrim,
455}
456
457pub const NAV_SIDEBAR_WIDTH: f64 = 240.0;
458
459/// Drag limits for a navigation host's sidebar pane, around [`NAV_SIDEBAR_WIDTH`]. Shared by the
460/// desktops whose divider the user can drag (docs/navigation.md): AppKit enforces both through
461/// its `NSSplitViewItem`; Qt honors the minimum through the pane's own minimum size and leaves
462/// the maximum to the user.
463pub const NAV_SIDEBAR_MIN_W: f64 = 160.0;
464pub const NAV_SIDEBAR_MAX_W: f64 = 400.0;
465
466/// Default preferred width of a navigation host's content-list pane
467/// (`props::NavProps::list_width`, docs/navigation.md), Mail's message-list proportion.
468pub const NAV_LIST_WIDTH: f64 = 300.0;
469
470/// Drag limits for the content-list pane, around the app's preferred width; the same split of
471/// duties as the sidebar's.
472pub const NAV_LIST_MIN_W: f64 = 220.0;
473pub const NAV_LIST_MAX_W: f64 = 560.0;
474
475/// Reserved id for window-level events (resize, lifecycle): day-core routes it to the root.
476pub const WINDOW_NODE: NodeId = NodeId(u64::MAX);
477
478/// Which nodes handle the non-text keys (docs/menus.md). Keys follow focus (the focused piece
479/// hears them and nobody else), so a backend whose focused view would have to claim a key from
480/// the platform's own dispatch (AppKit's responder chain, the DOM's default action) has to know
481/// whether the app wants it before swallowing it. An unclaimed arrow has to keep traveling, or
482/// a canvas inside a scroll view would silently eat the keys that scroll it.
483///
484/// It lives here, in day-spec, rather than in day-core: `day-toolkit-dom` depends on day-spec alone,
485/// and this is a fact about a node that both sides need.
486pub mod keys {
487    use super::NodeId;
488    use std::cell::RefCell;
489    use std::collections::HashSet;
490
491    thread_local! {
492        static HANDLED: RefCell<HashSet<NodeId>> = RefCell::new(HashSet::new());
493    }
494
495    /// Declare that `node` has a key handler (what `Decorate::on_key` records at build).
496    pub fn mark(node: NodeId) {
497        HANDLED.with(|h| h.borrow_mut().insert(node));
498    }
499
500    /// Whether `node` has one.
501    pub fn handled(node: NodeId) -> bool {
502        HANDLED.with(|h| h.borrow().contains(&node))
503    }
504}
505
506/// Raw foreign native handle for polyglot adoption (§15.3).
507pub type RawHandle = *mut std::ffi::c_void;
508
509// ---------------------------------------------------------------------------
510// Events (§8.3)
511// ---------------------------------------------------------------------------
512
513/// The wire table for backends whose native side reaches Rust through one numeric-kind
514/// trampoline (Android's JNI `nativeOnEvent`, ArkUI's `day_arkui_on_event`). This enum
515/// defines those kind numbers; the Java and C++ sides carry mirrored constants that parity
516/// tests check against these discriminants (so a collision or drift fails `cargo test` on the
517/// host instead of silently mis-decoding events on a device). AppKit/UIKit/GTK/Qt emit `Event`
518/// values directly and never use these numbers; XAML uses per-event callbacks with its own
519/// small local codes.
520///
521/// Payload conventions ride `(num: f64, text: String)` per kind, documented on each variant.
522pub mod bridge {
523    /// One numeric event kind. `as i32` is the wire value.
524    #[repr(i32)]
525    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
526    pub enum BridgeKind {
527        /// Click/press. No payload.
528        Pressed = 0,
529        /// `text` = the field's full new text.
530        TextChanged = 1,
531        /// `num` != 0 ⇒ on.
532        ToggleChanged = 2,
533        /// `num` = the new value.
534        ValueChanged = 3,
535        /// `num` = the selected index.
536        SelectionChanged = 4,
537        /// `num` == 1 ⇒ the native side already popped (predictive back / up arrow).
538        NavBack = 5,
539        /// Nav/tab page size report; `text` = `"w,h"` in px (Rust divides by density).
540        FrameChanged = 6,
541        /// Warm deep link; `text` = the route.
542        Deeplink = 7,
543        /// Modal answered with a button; `num` = the button index.
544        PresentButton = 8,
545        /// Modal answered with text; `text` = the entry.
546        PresentText = 9,
547        /// Modal dismissed.
548        PresentDismissed = 10,
549        /// Gesture; `num` = phase (0 tap, 1 began, 2 changed, 3 ended), `text` = `"x,y,tx,ty"` px.
550        Gesture = 11,
551        /// Piece-defined open channel (`Event::Custom` with an empty tag): the piece reads the
552        /// raw `num`/`text` payload.
553        Custom = 12,
554        /// Menu selection; the event's node id is the chosen action's dispatch id.
555        MenuAction = 13,
556        /// App lifecycle; `num` = the phase code (`day_spec::Lifecycle` order).
557        Lifecycle = 14,
558        /// File-picker answer; `text` = chosen locators joined by the unit separator.
559        PresentFile = 15,
560        /// `num` != 0 ⇒ gained keyboard focus.
561        FocusChanged = 16,
562        /// IME action / Return.
563        Submitted = 17,
564        /// Root size change; `text` = `"w,h"` in px. Routed to `WINDOW_NODE` as a window
565        /// resize (the rail rotation, late inset passes, and the soft keyboard ride).
566        WindowResized = 18,
567        /// Safe-area report from an edge-to-edge backend; `text` =
568        /// `"top,bottom,leading,trailing"` in px (Rust divides by density and feeds
569        /// `day_core::set_safe_area`). Node id ignored; no `Event` is emitted.
570        SafeArea = 19,
571        /// A secondary window closed (docs/windows.md); the node id is the window's root.
572        WindowClosed = 20,
573        /// A secondary window's key/active state changed; `num` != 0 ⇒ focused.
574        WindowFocused = 21,
575        /// `num` = the settled value: the drag ended (see `Event::ValueCommitted`). A backend
576        /// that cannot tell a settled value from a moving one sends only `ValueChanged`.
577        ValueCommitted = 22,
578        /// Inline search on a `.searchable()` navigation surface (docs/search.md): the field's
579        /// new text, against the nav host's node. `num` = 1 ⇒ the text was submitted (Return or
580        /// the keyboard's Search key), decoding to [`crate::Event::SearchSubmitted`].
581        SearchChanged = 23,
582        /// The toolkit's own adaptive nav container changed presentation and is reporting it
583        /// (docs/size-classes.md). `num` = 1.0 for split, 0.0 for stacked.
584        NavPresentation = 24,
585        /// The system switched between light and dark appearance. No payload; node id ignored
586        /// and no `Event` is emitted; Rust calls `day_core::note_appearance_changed`, the same
587        /// thing AppKit's and GTK's own scheme observers do.
588        AppearanceChanged = 25,
589        /// A fullscreen cover's hide transition finished (docs/cover.md); no payload, and the
590        /// node id is the cover's. Decodes to [`crate::Event::CoverHidden`].
591        CoverHidden = 26,
592        /// A styled text run's link was tapped (docs/text-runs.md); `text` = the run's target.
593        /// Decodes to [`crate::Event::LinkActivated`].
594        LinkActivated = 27,
595        /// The platform's own undo affordance fired (⌘Z, a three-finger swipe, the Edit menu
596        /// through a native front); `num` != 0 ⇒ redo.
597        UndoInvoked = 28,
598        /// A toolbar item produced a value (docs/toolbars.md): the node id is the item's
599        /// dispatch action; `text` = `"on"` with `num` != 0 ⇒ a toggle turned on, `"on"` with
600        /// 0 ⇒ off, `"sel"` with `num` = the chosen segment, `"text:<query>"` ⇒ a search
601        /// item's new text, `"submit:<query>"` ⇒ that text submitted. Decodes to
602        /// [`crate::Event::ToolbarChanged`]. A plain toolbar button sends `MenuAction`.
603        ToolbarChanged = 30,
604        /// An activated list row; `num` is its current index.
605        ListActivated = 31,
606        /// External document copied into app storage; `text` = its local locator.
607        DocumentOpened = 32,
608        /// The user's reduce-motion setting flipped (docs/accessibility.md). No payload; node
609        /// id ignored and no `Event` is emitted; Rust calls `day_core::note_motion_changed`, as
610        /// the desktop backends' own observers do.
611        ReduceMotionChanged = 33,
612        /// A non-text key reached the focused node (docs/menus.md); `text` = the day key name
613        /// (`"ArrowLeft"`, `"5"`, …), `num` = the [`crate::KeyEvent`] modifier mask. Decodes to
614        /// [`crate::Event::Key`].
615        Key = 29,
616        /// A window's display state changed (docs/windows.md): `num` = the
617        /// [`crate::WindowState`] code (0 normal, 1 minimized, 2 maximized, 3 fullscreen), against
618        /// the window's root node, or [`crate::WINDOW_NODE`] for the primary. Decodes to
619        /// [`crate::Event::WindowStateChanged`] through [`crate::WindowState::from_code`].
620        WindowStateChanged = 34,
621        /// Native pull-to-refresh request; no payload.
622        RefreshRequested = 35,
623    }
624
625    impl BridgeKind {
626        /// Every variant, for uniqueness/parity tests and exhaustive dispatch.
627        pub const ALL: [BridgeKind; 36] = [
628            BridgeKind::Pressed,
629            BridgeKind::TextChanged,
630            BridgeKind::ToggleChanged,
631            BridgeKind::ValueChanged,
632            BridgeKind::SelectionChanged,
633            BridgeKind::NavBack,
634            BridgeKind::FrameChanged,
635            BridgeKind::Deeplink,
636            BridgeKind::PresentButton,
637            BridgeKind::PresentText,
638            BridgeKind::PresentDismissed,
639            BridgeKind::Gesture,
640            BridgeKind::Custom,
641            BridgeKind::MenuAction,
642            BridgeKind::Lifecycle,
643            BridgeKind::PresentFile,
644            BridgeKind::FocusChanged,
645            BridgeKind::Submitted,
646            BridgeKind::WindowResized,
647            BridgeKind::SafeArea,
648            BridgeKind::WindowClosed,
649            BridgeKind::WindowFocused,
650            BridgeKind::ValueCommitted,
651            BridgeKind::SearchChanged,
652            BridgeKind::NavPresentation,
653            BridgeKind::AppearanceChanged,
654            BridgeKind::CoverHidden,
655            BridgeKind::LinkActivated,
656            BridgeKind::UndoInvoked,
657            BridgeKind::Key,
658            BridgeKind::ToolbarChanged,
659            BridgeKind::ListActivated,
660            BridgeKind::DocumentOpened,
661            BridgeKind::ReduceMotionChanged,
662            BridgeKind::WindowStateChanged,
663            BridgeKind::RefreshRequested,
664        ];
665    }
666
667    #[cfg(test)]
668    mod tests {
669        use super::BridgeKind;
670
671        /// The kind-15 lesson: two meanings on one number decode silently as the first. Every
672        /// discriminant must be unique, and the table must stay dense enough to spot gaps.
673        #[test]
674        fn discriminants_are_unique() {
675            let mut seen = std::collections::BTreeSet::new();
676            for k in BridgeKind::ALL {
677                assert!(
678                    seen.insert(k as i32),
679                    "duplicate bridge kind number {} ({k:?})",
680                    k as i32
681                );
682            }
683            assert_eq!(seen.len(), BridgeKind::ALL.len());
684        }
685
686        /// `ALL` is what the uniqueness check above sees, so a variant left out of it is a variant
687        /// nothing checks, which is how `SearchChanged` and `NavPresentation` sat outside the
688        /// table. The wire numbers are assigned densely from 0, so demanding the set be exactly
689        /// `0..len` catches both a gap and an omission.
690        #[test]
691        fn table_covers_every_wire_number() {
692            let mut nums: Vec<i32> = BridgeKind::ALL.iter().map(|k| *k as i32).collect();
693            nums.sort_unstable();
694            let dense: Vec<i32> = (0..BridgeKind::ALL.len() as i32).collect();
695            assert_eq!(
696                nums, dense,
697                "bridge kinds must be dense from 0 — a missing entry means a variant no test sees"
698            );
699        }
700    }
701}
702
703#[derive(Clone, Debug, PartialEq)]
704pub enum Event {
705    Pressed,
706    TextChanged(String),
707    Submitted,
708    ToggleChanged(bool),
709    ValueChanged(f64),
710    /// A continuous control's value settled: the drag ended (mouse/touch up), or the value moved
711    /// by a discrete action (a keyboard arrow, a click on the track). Always preceded by the
712    /// `ValueChanged` carrying the same value.
713    ///
714    /// The pair exists because one gesture produces two different facts. `ValueChanged` is the
715    /// live one (bindings follow it so the UI tracks the thumb) and it fires continuously, which
716    /// is why nothing durable should key off it: a drag from 1 to 100 and back to 50 emits every
717    /// value in between. `ValueCommitted` fires once, with the value the user chose, and is what
718    /// a recording, a log, or a refetch should use.
719    ///
720    /// A backend that cannot tell the two apart emits only `ValueChanged`; its sliders then do not
721    /// record (docs/coverage-matrix.md).
722    ValueCommitted(f64),
723    SelectionChanged(i64),
724    /// A list row was activated: desktop double-click/Enter, or a touch tap.
725    /// Separate from selection so keyboard browsing need not open or play the row.
726    ListActivated(usize),
727    /// The platform's own undo affordance fired through a native front (⌘Z on the Edit menu,
728    /// a three-finger swipe, shake-to-undo); `redo` distinguishes the pair. Only backends
729    /// with a native undo system emit it; everywhere else the app's own controls call the
730    /// stack directly and this event never exists (docs/model.md).
731    Undo {
732        redo: bool,
733    },
734    /// The platform's own standard edit command fired through its native route (Edit ▸
735    /// Cut/Copy/Paste, ⌘X/⌘C/⌘V, the browser's `copy`/`paste` DOM events) with no text
736    /// widget claiming it first; the app's edit bridge answers (docs/menus.md). Transport
737    /// is the system clipboard (day-part-clipboard), not the event.
738    Edit(EditOp),
739    /// A multi-select list's selection changed: the full set of selected row indices,
740    /// ascending (empty = nothing selected). Emitted instead of `SelectionChanged` where
741    /// `ListProps::multi_select` is honored (docs/list.md).
742    SelectionSet(Vec<i64>),
743    FocusChanged(bool),
744    Tap(Point),
745    /// A link run inside a label was activated; the payload is [`TextRun::link`] verbatim.
746    LinkActivated(String),
747    LongPress(Point),
748    /// A context-menu summon reported by a toolkit that presents no native menu of its own
749    /// (web-dom): the pieces layer shows the composed menu (docs/menus.md). `local` is the
750    /// point in the node's own coordinates (what the app's provider receives); `window` the
751    /// same point in window coordinates (where the composed panel goes). Toolkits that serve
752    /// context menus natively never emit this.
753    ContextMenu {
754        local: Point,
755        window: Point,
756    },
757    /// A drag/pan gesture (docs/shapes.md). `location` is in the node's local coordinates;
758    /// `translation` is the cumulative movement since `Began`.
759    Drag {
760        phase: DragPhase,
761        location: Point,
762        translation: Point,
763    },
764    /// A pinch/magnify gesture over the node (docs/shapes.md): `scale` is cumulative since
765    /// `Began` (1.0 = unchanged), `location` the gesture's centroid in local coordinates,
766    /// the anchor a zoom keeps stationary. Only nodes that enabled
767    /// [`GestureKind::Pinch`] receive it; a backend with no recognizer emits nothing.
768    Pinch {
769        phase: DragPhase,
770        scale: f64,
771        location: Point,
772    },
773    /// A viewport pan over the node (docs/shapes.md): `delta` is the movement since the
774    /// previous event; incremental, not cumulative, because desktop wheels have no gesture
775    /// session to accumulate over (a discrete wheel tick arrives as a lone `Changed`).
776    /// Two-finger touch pans bracket theirs with `Began`/`Ended`. Distinct from
777    /// [`Event::Drag`], the primary pointer's press-drag.
778    Pan {
779        phase: DragPhase,
780        delta: Point,
781        location: Point,
782    },
783    /// The pointer moved over the node, or left it (docs/canvas.md "Interaction"). `location` is
784    /// in the node's local coordinates. Phases follow the drag vocabulary: `Began` on entry,
785    /// `Changed` for each move, `Ended` on exit, where `location` is the last point seen inside,
786    /// so a handler always knows where the pointer went out.
787    ///
788    /// Only nodes that enabled [`GestureKind::Hover`] receive it, and only on a device with a
789    /// pointer at all.
790    Hover {
791        phase: DragPhase,
792        location: Point,
793    },
794    ScrollChanged(Point),
795    /// A canvas node was re-framed by layout; re-record (§11). Nav pane/page containers
796    /// also report their allocated size with this (docs/navigation.md).
797    FrameChanged(Size),
798    /// Native back navigation (iOS back button/swipe, Android system back or toolbar up).
799    /// `already_popped` = the toolkit already performed the pop natively (iOS); the nav
800    /// host then syncs its stack without re-issuing `NavPatch::Popped`.
801    NavBack {
802        already_popped: bool,
803    },
804    /// A nav host's own adaptive container changed presentation, and Day is being told about it
805    /// after the fact (docs/size-classes.md).
806    ///
807    /// The counterpart to [`props::NavPatch::Presentation`], for the toolkits that answer
808    /// `Cap::NavRepresent = Emulated`: `UISplitViewController` collapsing as a Pro Max iPhone
809    /// rotates into portrait, `SlidingPaneLayout` deciding at measure time that two panes no
810    /// longer fit. Day did not ask for it and must not fight it; the pieces layer only
811    /// reconciles what follows, which is the selection rule (a split presentation cannot draw an
812    /// empty detail pane, so expanding with nothing selected picks the first item).
813    ///
814    /// Emitted on the NAV host node, and only when the presentation actually changed.
815    NavPresentationChanged(props::NavPresentation),
816    Key(KeyEvent),
817    Pointer(PointerEvent),
818    WindowResized(Size),
819    /// The platform asks the app to show a route (docs/navigation.md), a runtime deep link:
820    /// on web-dom, the URL hash changing under the app (hand-edited, or browser back/forward);
821    /// on mobile, a warm scheme link (iOS `application:openURL:`, Android `onNewIntent` via
822    /// `BridgeKind::Deeplink`). Emitted on [`WINDOW_NODE`] (day-core answers with `navigate()`
823    /// when the route differs from the current one) or on the active nav host's node (the nav
824    /// piece answers with `navigate()` itself, docs/deep-links.md). Launch-time deep links use
825    /// `DAY_DEEPLINK`/`set_launch_deeplink` instead; this variant is for changes while the
826    /// app runs.
827    RouteRequested(String),
828    /// A native modal answered request `req` (docs/dialogs.md).
829    PresentResult {
830        req: u64,
831        result: present::PresentResult,
832    },
833    /// A decode started by [`Toolkit::decode_image`] finished (docs/images.md).
834    ///
835    /// Keyed by request id like [`Event::PresentResult`], and for the same reason: the answer
836    /// belongs to a waiting caller, not to a tree node. It never crosses a native boundary
837    /// (every backend raises it from its own Rust arm once the platform decoder answers), so it
838    /// has no [`bridge::BridgeKind`], exactly like the completion events dialogs use in-process.
839    ///
840    /// No bitmap id rides here: day-core minted it and handed it to the backend with the bytes,
841    /// so it already knows which image a request answers for. A backend that stored the image
842    /// under that id has nothing more to say than the facts it read.
843    ImageDecoded {
844        req: u64,
845        result: Result<BitmapInfo, ImageError>,
846    },
847    /// An encode started by [`Toolkit::encode_image`] finished (docs/images.md): the encoded
848    /// bytes, or why they could not be produced.
849    ImageEncoded {
850        req: u64,
851        result: Result<Vec<u8>, ImageError>,
852    },
853    /// A canvas drawing started by [`Toolkit::render_bitmap`] finished rendering
854    /// (docs/canvas.md "Exporting"). Keyed by request id like [`Event::ImageDecoded`], and like
855    /// it carries no bitmap id: day-core minted the id and handed it over with the ops, so the
856    /// answer is only the facts of the image the backend stored under it.
857    BitmapRendered {
858        req: u64,
859        result: Result<BitmapInfo, ExportError>,
860    },
861    /// A PDF started by [`Toolkit::render_pdf`] finished (docs/canvas.md "Exporting"): the
862    /// document's bytes, or why they could not be produced.
863    PdfRendered {
864        req: u64,
865        result: Result<Vec<u8>, ExportError>,
866    },
867    /// An open, piece-defined event (§8.2). `tag` names the event for in-process emitters (a static
868    /// literal); it is empty for events that cross a native boundary (JNI/C-ABI), which carry only the
869    /// primitive `num`/`text` payload. A piece's `cx.on` reads whichever fields it needs. This is the
870    /// escape hatch for events the fixed variants above don't cover (a web view's URL, a picked date, …).
871    Custom {
872        tag: &'static str,
873        num: f64,
874        text: String,
875    },
876    /// A menu item (app menu or context menu) with this action id was activated (§ menus). day-core
877    /// routes it to the app closure registered for the id. Standard-role items don't carry an id
878    /// (`role` items are handled natively) so they never emit this.
879    MenuAction(u64),
880    /// A toolbar item produced a value: a search field's text, a toggle's new state
881    /// (docs/toolbars.md). `action` is the item's dispatch id, from the same registry
882    /// [`Event::MenuAction`] uses, and day-core routes it to the closure registered for it.
883    /// A plain toolbar button has no value and emits `MenuAction` instead.
884    ToolbarChanged {
885        action: u64,
886        value: ToolbarValue,
887    },
888    /// A searchable navigation surface's field changed (docs/search.md). Emitted against the nav
889    /// host's node, not through the toolbar's dispatch registry: search belongs to the surface,
890    /// so the field can move between the toolbar and the navigation list without the app
891    /// re-registering anything.
892    SearchChanged(String),
893    /// The user picked a different scope. Carries the index into `SearchProps::scopes`.
894    SearchScopeChanged(usize),
895    /// The user chose one of `SearchProps::suggestions`, by index. The toolkit has already put
896    /// that completion in the field and emitted [`Event::SearchChanged`] for it; this says which
897    /// one, for an app that wants to act on the choice itself.
898    SearchSuggestionChosen(usize),
899    /// The user submitted the inline field's text with its Return or Search key. Emitted
900    /// after the last [`Event::SearchChanged`], with the text as submitted, for a search that
901    /// runs on demand (a server query) rather than narrowing as the text changes.
902    SearchSubmitted(String),
903    /// The app moved through a lifecycle phase (docs/lifecycle.md). Backends emit this from the
904    /// native app/activity delegate; day-core routes it to the app's `on_lifecycle` handlers.
905    Lifecycle(Lifecycle),
906    /// A secondary native window closed (the title-bar close, a platform gesture such as an
907    /// app-switcher swipe or an activity finish, or `Toolkit::close_window`); emitted on the
908    /// window's root node after the platform committed the close. day-core disposes the
909    /// window's subtree on receipt, so native and programmatic closes share one teardown
910    /// path (docs/windows.md). Never emitted for the primary window (its close terminates
911    /// the app).
912    WindowClosed,
913    /// A secondary window's key/active state changed; emitted on the window's root node.
914    /// day-core tracks the focused window with it (dialog parenting, dayscript targeting).
915    WindowFocused(bool),
916    /// A window's display state changed (docs/windows.md): the user minimized, zoomed or took it
917    /// fullscreen, or a [`WindowChange::State`] request landed. Emitted on the window's root node
918    /// (the primary's may arrive on [`WINDOW_NODE`]); day-core feeds the window's `state()`
919    /// signal with it, so the app reads what the platform did rather than what it asked for.
920    WindowStateChanged(WindowState),
921    /// A native list committed a drag-reorder (docs/list.md): row `from` landed at row `to`.
922    /// Emitted on the `LIST` node by the list piece's commit hook: the reorder driver
923    /// rotates its snapshot synchronously inside the platform's drop callback, then reports
924    /// through the event queue so the app's `on_reorder` never runs inside a native animation
925    /// callstack.
926    ListReorder {
927        from: usize,
928        to: usize,
929    },
930    /// A regrouping sidebar committed a drop (`props::NavMenuProps::regroup`, docs/navigation.md
931    /// "Moving rows between sections"), in item indices into the rows as they were before the
932    /// move: row `from` now sits in the section whose first row is item `section` (item 0 for
933    /// rows above the first header), before item `before`, or at that section's end for
934    /// `None`. `before` is never `from`. Emitted on the `NAV_MENU` node by a toolkit whose
935    /// `Cap::NavReorder` is `Native`, deferred through the event queue exactly as
936    /// [`Event::ListReorder`] is; the nav validates it against the app's rules before reporting.
937    NavRegroup {
938        from: usize,
939        section: usize,
940        before: Option<usize>,
941    },
942    /// A native list committed a swipe-delete (docs/list.md): the row at this index is gone.
943    /// Deferred through the event queue exactly as [`Event::ListReorder`] is.
944    ListDelete(usize),
945    /// The native pull-to-refresh control requested an update. The app owns its busy state.
946    RefreshRequested,
947    /// A native list activated a swipe action (docs/list.md): the user pressed button `action`
948    /// (an index into the row's [`ListSwipe::actions_at`] offer for `edge`) on row `index`, or
949    /// swiped clear across for the edge's first action. Emitted on the `LIST` node by the list
950    /// piece's commit hook and deferred through the event queue exactly as
951    /// [`Event::ListReorder`] is, so the app's handler never runs inside a native animation
952    /// callstack.
953    ListSwipe {
954        index: usize,
955        edge: SwipeEdge,
956        action: usize,
957    },
958    /// A fullscreen cover's hide transition finished (docs/cover.md): the content can now be
959    /// disposed. Answers [`props::CoverPatch::Dismiss`]; delivery is a hard guarantee, and
960    /// backends over-report rather than under-report; consumers gate on their own closing
961    /// flag, so duplicates and belated reports are no-ops.
962    CoverHidden,
963    /// The user showed or hid an inspector pane through a native affordance (a dock widget's
964    /// close button, a divider dragged shut) rather than through Day (docs/inspector.md).
965    /// Emitted on the `kinds::INSPECTOR` node, and only when the visibility actually changed;
966    /// the piece writes it back to the bound signal. Applying
967    /// [`props::InspectorPatch::Visible`] must never re-emit it (the from-native echo rule).
968    InspectorChanged(bool),
969    /// The user disclosed or collapsed a tree row through the native affordance (docs/tree.md).
970    /// Emitted on the `kinds::TREE` node; the piece writes it back to the app's expansion
971    /// signal. Applying [`props::TreePatch::Expand`] must never re-emit it (the from-native
972    /// echo rule).
973    TreeExpanded {
974        token: u64,
975        expanded: bool,
976    },
977    /// A native tree committed a drag move (docs/tree.md): `token` now sits under `parent`
978    /// (`None` = the root) at `index` (`None` = dropped onto the parent, an append). Deferred
979    /// through the event queue exactly as [`Event::ListReorder`] is; the app's `on_move`
980    /// writes its own data, whose refresh reloads the tree.
981    TreeMove {
982        token: u64,
983        parent: Option<u64>,
984        index: Option<usize>,
985    },
986    /// A tree's selection changed: the full set of selected row tokens (empty = cleared).
987    /// Token-addressed, since a tree cannot speak row indices: expanding a row renumbers
988    /// everything below it (docs/tree.md).
989    TreeSelection(Vec<u64>),
990}
991
992impl Event {
993    /// Build a text-carrying [`Event::Custom`] (with `num` defaulted to 0), the common case for an
994    /// in-process piece reporting a value back: `emit(node, Event::custom("webview:url", url))`.
995    pub fn custom(tag: &'static str, text: impl Into<String>) -> Event {
996        Event::Custom {
997            tag,
998            num: 0.0,
999            text: text.into(),
1000        }
1001    }
1002}
1003
1004/// An app-lifecycle phase (docs/lifecycle.md). Each backend maps these onto its OS's native app /
1005/// activity delegate. Some phases only exist on some platforms (a mobile app enters the
1006/// background and can be low on memory, a desktop app cannot), so [`Lifecycle::is_universal`]
1007/// marks the ones every backend delivers, and [`Toolkit::supports_lifecycle`] reports per-backend
1008/// truth.
1009///
1010/// Rough native mapping:
1011///
1012/// | phase | AppKit | UIKit | GTK | Qt | Android | XAML |
1013/// |---|---|---|---|---|---|---|
1014/// | `WillLaunch` / `DidLaunch` | `applicationWill/DidFinishLaunching` | same | `startup`/mount | mount | `onCreate` | window create |
1015/// | `DidBecomeActive` | `didBecomeActive` | `didBecomeActive` | `notify::is-active` | `ApplicationActive` | `onResume` | `Activated` |
1016/// | `WillResignActive` | `willResignActive` | `willResignActive` | `notify::is-active` | `ApplicationInactive` | `onPause` | `Deactivated` |
1017/// | `WillEnterForeground` | — | `willEnterForeground` | — | — | `onStart` | — |
1018/// | `DidEnterBackground` | — | `didEnterBackground` | — | — | `onStop` | — |
1019/// | `DidReceiveMemoryWarning` | — | `didReceiveMemoryWarning` | — | — | `onTrimMemory` | — |
1020/// | `WillTerminate` | `willTerminate` | `willTerminate` | `shutdown` | `aboutToQuit` | `onDestroy` | window close |
1021/// | `DidExit` | after `willTerminate` | after `willTerminate` | `run` returned | `exec` returned | after `onDestroy` | loop returned |
1022#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
1023pub enum Lifecycle {
1024    /// Before the window and UI are built: the first thing to run. Set up global state here.
1025    WillLaunch,
1026    /// The UI is mounted and the app is about to start running. Kick off startup work here.
1027    DidLaunch,
1028    /// The app came to the foreground and is the active, focused app receiving input.
1029    DidBecomeActive,
1030    /// The app is about to stop being active (an interruption, app switch, or losing focus).
1031    WillResignActive,
1032    /// The app is about to return to the foreground (mobile). Refresh what background invalidated.
1033    WillEnterForeground,
1034    /// The app left the foreground and is no longer visible (mobile). Persist state, release UI work.
1035    DidEnterBackground,
1036    /// The system is low on memory (mobile). Drop caches and non-essential memory now.
1037    DidReceiveMemoryWarning,
1038    /// The app is about to terminate: the last chance to save. Triggered by the Quit command,
1039    /// the platform's quit shortcut, or the OS reclaiming the app.
1040    WillTerminate,
1041    /// The run loop is over and nothing of the app will run after this: the last phase, after
1042    /// every `WillTerminate` handler. Day logs its exit line ("Clean exit for …") once the
1043    /// handlers have run, so a handler here is the app's last word before it.
1044    DidExit,
1045}
1046
1047impl Lifecycle {
1048    /// Every phase, in delivery order (launch → run → quit). Handy for logging/registration sweeps.
1049    pub const ALL: [Lifecycle; 9] = [
1050        Lifecycle::WillLaunch,
1051        Lifecycle::DidLaunch,
1052        Lifecycle::DidBecomeActive,
1053        Lifecycle::WillResignActive,
1054        Lifecycle::WillEnterForeground,
1055        Lifecycle::DidEnterBackground,
1056        Lifecycle::DidReceiveMemoryWarning,
1057        Lifecycle::WillTerminate,
1058        Lifecycle::DidExit,
1059    ];
1060
1061    /// True for phases every backend delivers (launch, activation, termination). The remaining
1062    /// phases (`WillEnterForeground`, `DidEnterBackground`, `DidReceiveMemoryWarning`) are mobile
1063    /// concepts and are only delivered by the mobile backends. `const` so it composes into a
1064    /// backend's `const fn lifecycle_supported` and thus into compile-time guards.
1065    pub const fn is_universal(self) -> bool {
1066        matches!(
1067            self,
1068            Lifecycle::WillLaunch
1069                | Lifecycle::DidLaunch
1070                | Lifecycle::DidBecomeActive
1071                | Lifecycle::WillResignActive
1072                | Lifecycle::WillTerminate
1073                | Lifecycle::DidExit
1074        )
1075    }
1076
1077    /// A stable, human-readable name (for logs/warnings).
1078    pub const fn name(self) -> &'static str {
1079        match self {
1080            Lifecycle::WillLaunch => "WillLaunch",
1081            Lifecycle::DidLaunch => "DidLaunch",
1082            Lifecycle::DidBecomeActive => "DidBecomeActive",
1083            Lifecycle::WillResignActive => "WillResignActive",
1084            Lifecycle::WillEnterForeground => "WillEnterForeground",
1085            Lifecycle::DidEnterBackground => "DidEnterBackground",
1086            Lifecycle::DidReceiveMemoryWarning => "DidReceiveMemoryWarning",
1087            Lifecycle::WillTerminate => "WillTerminate",
1088            Lifecycle::DidExit => "DidExit",
1089        }
1090    }
1091}
1092
1093/// The phase of a drag gesture (docs/shapes.md).
1094#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1095pub enum DragPhase {
1096    Began,
1097    Changed,
1098    Ended,
1099}
1100
1101/// A gesture a node wants delivered. Backends attach the matching native recognizer when day-core
1102/// calls [`Toolkit::enable_gesture`]; the default is no gesture (recognizers cost, so opt-in).
1103#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
1104pub enum GestureKind {
1105    Tap,
1106    LongPress,
1107    Drag,
1108    /// The pointer moving over the node without pressing (docs/canvas.md "Interaction"), and
1109    /// leaving it. Delivered only where a pointer exists: every desktop, an iPad with a trackpad
1110    /// or pencil, an Android device with a mouse or stylus. A touch-only device reports none,
1111    /// which is the right answer, not a gap, so anything reachable by hover must also be
1112    /// reachable by a tap.
1113    Hover,
1114    /// Pinch/magnify (docs/shapes.md): trackpad magnification, two-finger touch pinch.
1115    Pinch,
1116    /// Viewport pan (docs/shapes.md): trackpad two-finger scroll, two-finger touch pan.
1117    /// Distinct from [`GestureKind::Drag`], the primary pointer's press-drag.
1118    Pan,
1119}
1120
1121// ---------------------------------------------------------------------------
1122// Menus (app menu bar + context menus). The model is a toolkit-neutral tree; each backend renders
1123// it with its native affordance (NSMenu / GMenu+GtkPopoverMenu / QMenu / UIMenu / Android
1124// PopupMenu / XAML MenuFlyout) and its own conventions, so day imposes no menu manager of its own.
1125// ---------------------------------------------------------------------------
1126
1127/// A keyboard shortcut for a menu item. `primary` is the platform's command modifier (⌘ on Apple,
1128/// Ctrl on GTK/Qt/XAML) so one declaration reads correctly everywhere. `key` is a single character
1129/// (`"s"`, `"."`) or a named key (`"Return"`, `"Delete"`, `"Left"`, `"F1"`).
1130#[derive(Clone, Debug, PartialEq, Eq, Default)]
1131pub struct Shortcut {
1132    pub key: String,
1133    /// ⌘ (Apple) / Ctrl (elsewhere). The conventional command modifier.
1134    pub primary: bool,
1135    pub shift: bool,
1136    /// ⌥ / Alt.
1137    pub alt: bool,
1138    /// Literal Control (⌃ on Apple). Rare; prefer `primary` for the command modifier.
1139    pub control: bool,
1140}
1141
1142impl Shortcut {
1143    /// `primary`+`key` (⌘S / Ctrl+S), the common case: `Shortcut::primary("s").shift()`.
1144    pub fn primary(key: impl Into<String>) -> Shortcut {
1145        Shortcut {
1146            key: key.into(),
1147            primary: true,
1148            ..Default::default()
1149        }
1150    }
1151    /// `key` with no modifiers (e.g. `F1`, plain `Delete`).
1152    pub fn plain(key: impl Into<String>) -> Shortcut {
1153        Shortcut {
1154            key: key.into(),
1155            ..Default::default()
1156        }
1157    }
1158    pub fn shift(mut self) -> Shortcut {
1159        self.shift = true;
1160        self
1161    }
1162    pub fn alt(mut self) -> Shortcut {
1163        self.alt = true;
1164        self
1165    }
1166    pub fn control(mut self) -> Shortcut {
1167        self.control = true;
1168        self
1169    }
1170}
1171
1172/// A standard/system command. The backend supplies the native item, a selector on AppKit/UIKit
1173/// (`cut:`/`copy:`/`paste:`…) or a stock action on GTK/Qt/XAML, so it targets the focused
1174/// control, gets the platform's default label + shortcut, and enables/disables itself
1175/// automatically. This is how default items (Edit ▸ Cut/Copy/Paste, the app's Quit/About) are
1176/// accommodated without the app re-implementing them.
1177#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1178pub enum MenuRole {
1179    Cut,
1180    Copy,
1181    Paste,
1182    SelectAll,
1183    Undo,
1184    Redo,
1185    Delete,
1186    /// The app's About command (docs/settings.md). With an About registered through
1187    /// `day::register_about` the item lowers to that dispatch action (a Day-rendered About
1188    /// window, or the toolkit's own About dialog where one exists); without one AppKit shows
1189    /// its stock Info.plist panel and the other desktops show the label alone.
1190    About,
1191    Quit,
1192    Preferences,
1193    Minimize,
1194    CloseWindow,
1195    Fullscreen,
1196    /// File ▸ New Window (docs/windows.md): opens another window through the builder the
1197    /// app registered with `day::register_new_window`. No platform has a native selector
1198    /// for it, so the item lowers to the registered dispatch action (disabled when none).
1199    NewWindow,
1200    /// Check for Updates… (docs/settings.md): placed directly under About in the macOS App
1201    /// menu (the Sparkle convention) and in Help elsewhere. Lowers to the action an updater
1202    /// registered with `day::register_check_for_updates`; absent from the bar when none did.
1203    CheckForUpdates,
1204}
1205
1206/// The keyboard modifiers held at an interaction, queryable ambiently
1207/// ([`Toolkit::modifiers`]): `primary` is the platform's command key (⌘ on Apple platforms,
1208/// Ctrl elsewhere, the same convention [`Shortcut::primary`] uses). Touch-only backends
1209/// answer all-false.
1210#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
1211pub struct Modifiers {
1212    pub shift: bool,
1213    pub primary: bool,
1214    pub alt: bool,
1215}
1216
1217/// A standard edit command a platform route delivered ([`Event::Edit`]).
1218#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1219pub enum EditOp {
1220    Cut,
1221    Copy,
1222    Paste,
1223    SelectAll,
1224}
1225
1226/// What the app's edit bridge can currently do, mirrored into the toolkit
1227/// ([`Toolkit::set_edit_state`]) so native menu validation enables the stock items.
1228/// `can_paste` is the app's half ("a paste handler is installed"); the toolkit combines it
1229/// with its own clipboard-has-text check where one exists.
1230#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
1231pub struct EditState {
1232    pub can_cut: bool,
1233    pub can_copy: bool,
1234    pub can_paste: bool,
1235    pub can_select_all: bool,
1236}
1237
1238/// The undo stack's face, as a native front mirrors it ([`Toolkit::set_undo_state`]): what is
1239/// possible and what the menu titles should say. Labels arrive already localized: a toolkit
1240/// cannot invent translated text, the same rule as every other label in this file.
1241#[derive(Clone, Debug, PartialEq, Default)]
1242pub struct UndoState {
1243    pub can_undo: bool,
1244    pub can_redo: bool,
1245    /// The next undo unit's display label ("Rename"), empty when nothing is undoable. Fronts
1246    /// interpolate it into the platform's own title form ("Undo Rename").
1247    pub undo_label: String,
1248    pub redo_label: String,
1249}
1250
1251/// One entry in a menu (recursive: a `Submenu` nests).
1252#[derive(Clone, Debug, PartialEq)]
1253pub enum MenuItem {
1254    /// A command. `action` (nonzero) dispatches [`Event::MenuAction`] to the app; a `role`-only item
1255    /// uses the native standard command instead (action 0). `label`/`shortcut` override the role's
1256    /// defaults. `icon` is the platform's own glyph beside the title where menus carry one (macOS,
1257    /// Windows, GNOME, KDE, Android); a backend whose menus are text-only ignores it.
1258    ///
1259    /// The `id`/`action` split is [`ToolbarItem`]'s: `id` names the item and `action` is what it
1260    /// runs. They are separate because a label cannot serve as a name (it is localized, and an
1261    /// item that shows its own state changes it), so anything addressing an item from outside
1262    /// (dayscript's `menu: { id: … }`) needs something that does not move.
1263    Action {
1264        /// The app's own name for this item, where it gave one. Stable across locales and across
1265        /// a change of `checked`, and unique within the menu it is installed in.
1266        id: Option<String>,
1267        /// The item's command, as a dispatch id from the same registry [`Event::MenuAction`] uses
1268        /// (0 = no command), so a toolbar button and its menu twin can share one closure.
1269        action: u64,
1270        label: String,
1271        shortcut: Option<Shortcut>,
1272        enabled: bool,
1273        /// On/off state where the item stands for a setting or one of several choices, drawn with
1274        /// the platform's own check mark. `None` is a plain command and reserves no mark; `Some`
1275        /// makes the item checkable and says which way it currently sits.
1276        ///
1277        /// The item still runs its `action` when chosen; a backend never flips this on its own.
1278        /// The app owns the state, and re-installing the menu (`app_menu`, which re-lowers on change) is what moves
1279        /// the mark, so what the menu shows can never disagree with what the app thinks.
1280        checked: Option<bool>,
1281        role: Option<MenuRole>,
1282        icon: Option<Icon>,
1283    },
1284    /// A nested submenu. At the top level of an app menu a `role` claims one of the platform's
1285    /// standard menu-bar slots: the backend then uses this menu instead of its stock one, and
1286    /// places it where the platform expects that menu to sit.
1287    Submenu {
1288        label: String,
1289        items: Vec<MenuItem>,
1290        role: Option<MenuBarRole>,
1291    },
1292    /// A visual separator.
1293    Separator,
1294}
1295
1296/// A standard menu-bar slot (macOS's File/Edit/View/Window/Help, and their counterparts
1297/// elsewhere). A backend that has a house style for the menu bar fills every slot an app did
1298/// not claim with its own stock menu, so an app never has to restate the platform's furniture,
1299/// and can still replace any of it by tagging its own submenu with the matching role.
1300#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1301#[non_exhaustive]
1302pub enum MenuBarRole {
1303    File,
1304    Edit,
1305    View,
1306    /// KDE/Plasma's Settings menu (`Configure <App>`, Configure Shortcuts). No counterpart on
1307    /// macOS, where preferences live in the app menu, or on GNOME/Windows.
1308    Settings,
1309    /// macOS's Window menu. Windows and Linux desktops do not have one.
1310    Window,
1311    Help,
1312}
1313
1314// ---------------------------------------------------------------------------
1315// Window toolbars (docs/toolbars.md)
1316// ---------------------------------------------------------------------------
1317
1318/// A standard icon, named by what it means rather than by how it looks, so each backend can
1319/// draw the platform's own glyph for it: an SF Symbol on macOS, a freedesktop icon name on
1320/// GTK and Qt, a Fluent glyph on Windows. This is the only way an icon looks native on every
1321/// desktop at once; a bundled PNG cannot, because it is one artist's take on all four.
1322///
1323/// The set is kept small: the commands that recur across toolbars. Anything
1324/// app-specific is an [`Icon::Image`].
1325#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
1326#[non_exhaustive]
1327pub enum Symbol {
1328    Add,
1329    Remove,
1330    Delete,
1331    Edit,
1332    New,
1333    Open,
1334    Save,
1335    Print,
1336    Refresh,
1337    Search,
1338    Share,
1339    Settings,
1340    Info,
1341    Star,
1342    Bookmark,
1343    Back,
1344    Forward,
1345    Up,
1346    Down,
1347    Home,
1348    /// Show/hide the sidebar, the leading item of most desktop toolbars.
1349    Sidebar,
1350    Filter,
1351    Sort,
1352    /// An overflow affordance (macOS `ellipsis`, GNOME's hamburger, Fluent `More`).
1353    More,
1354    Play,
1355    Pause,
1356    Stop,
1357    /// A photo capture: a screenshot command, a camera control.
1358    Camera,
1359    /// Source code.
1360    Code,
1361    /// Light appearance (a sun). The three below are the vocabulary of a theme chooser, which
1362    /// every platform draws with the same three ideas.
1363    Light,
1364    /// Dark appearance (a moon).
1365    Dark,
1366    /// Follow the system: the half-filled circle every platform uses for "automatic".
1367    Auto,
1368    ZoomIn,
1369    ZoomOut,
1370    /// Back to actual size: the 100% zoom command between [`Symbol::ZoomIn`] and
1371    /// [`Symbol::ZoomOut`].
1372    ZoomReset,
1373    Undo,
1374    Redo,
1375    Copy,
1376    Cut,
1377    Paste,
1378    Mail,
1379    Folder,
1380    Document,
1381    Check,
1382    Close,
1383    Warning,
1384    /// A rectangle: the shape vocabulary a drawing surface needs (docs/shapes.md), and the
1385    /// glyphs every drawing, diagram and annotation tool puts in the same place.
1386    Rectangle,
1387    /// An ellipse.
1388    Oval,
1389    /// An outlined circle: the read/unread vocabulary (a read row, its dot removed), and the
1390    /// generic ring glyph.
1391    Circle,
1392    /// A filled circle: the unread dot itself.
1393    CircleFilled,
1394    /// A straight line segment.
1395    Line,
1396    /// Combine the selection into a group: the drawing-tool command (two stacked squares).
1397    Group,
1398    /// Dissolve a group back into its members (two separated squares).
1399    Ungroup,
1400    /// Text: a line of type as a drawing element (the drawing-tool "T").
1401    Text,
1402}
1403
1404/// The SF Symbol each standard symbol draws as. The system's own glyphs match the user's
1405/// device: weight, optical size, accent color and all. Shared by both Apple backends
1406/// (toolbars on macOS, menus on both).
1407///
1408/// The match is exhaustive so that a new [`Symbol`] must name its glyph here rather than
1409/// silently drawing nothing on Apple. A name this OS release does not know still resolves to
1410/// no image, and the item falls back to its label.
1411pub fn sf_symbol_name(s: Symbol) -> &'static str {
1412    match s {
1413        Symbol::Add => "plus",
1414        Symbol::Remove => "minus",
1415        Symbol::Delete => "trash",
1416        Symbol::Edit => "pencil",
1417        Symbol::New => "square.and.pencil",
1418        Symbol::Open => "folder",
1419        Symbol::Save => "square.and.arrow.down",
1420        Symbol::Print => "printer",
1421        Symbol::Refresh => "arrow.clockwise",
1422        Symbol::Search => "magnifyingglass",
1423        Symbol::Share => "square.and.arrow.up",
1424        Symbol::Settings => "gearshape",
1425        Symbol::Info => "info.circle",
1426        Symbol::Star => "star",
1427        Symbol::Bookmark => "bookmark",
1428        Symbol::Back => "chevron.backward",
1429        Symbol::Forward => "chevron.forward",
1430        Symbol::Up => "chevron.up",
1431        Symbol::Down => "chevron.down",
1432        Symbol::Home => "house",
1433        Symbol::Sidebar => "sidebar.leading",
1434        Symbol::Filter => "line.3.horizontal.decrease",
1435        Symbol::Sort => "arrow.up.arrow.down",
1436        Symbol::More => "ellipsis",
1437        Symbol::Play => "play.fill",
1438        Symbol::Pause => "pause.fill",
1439        Symbol::Stop => "stop.fill",
1440        Symbol::Camera => "camera",
1441        Symbol::Code => "chevron.left.forwardslash.chevron.right",
1442        Symbol::Light => "sun.max",
1443        Symbol::Dark => "moon",
1444        Symbol::Auto => "circle.lefthalf.filled",
1445        Symbol::ZoomIn => "plus.magnifyingglass",
1446        Symbol::ZoomReset => "1.magnifyingglass",
1447        Symbol::ZoomOut => "minus.magnifyingglass",
1448        Symbol::Undo => "arrow.uturn.backward",
1449        Symbol::Redo => "arrow.uturn.forward",
1450        Symbol::Copy => "doc.on.doc",
1451        Symbol::Cut => "scissors",
1452        Symbol::Paste => "doc.on.clipboard",
1453        Symbol::Mail => "envelope",
1454        Symbol::Folder => "folder",
1455        Symbol::Document => "doc",
1456        Symbol::Check => "checkmark",
1457        Symbol::Close => "xmark",
1458        Symbol::Warning => "exclamationmark.triangle",
1459        Symbol::Rectangle => "rectangle",
1460        Symbol::Oval => "oval",
1461        Symbol::Circle => "circle",
1462        Symbol::CircleFilled => "circle.fill",
1463        Symbol::Line => "line.diagonal",
1464        Symbol::Group => "square.on.square",
1465        Symbol::Ungroup => "square.on.square.dashed",
1466        Symbol::Text => "textformat",
1467    }
1468}
1469
1470/// A button or toolbar item's picture: a standard [`Symbol`] (drawn with the platform's own icon set) or
1471/// a bundled image from `resource/images` for something only this app has.
1472#[derive(Clone, Debug, PartialEq)]
1473pub enum Icon {
1474    Symbol(Symbol),
1475    /// A bundled image name, resolved the same way [`ImageName`] is elsewhere.
1476    Image(String),
1477}
1478
1479/// What a toolbar item is. The variants are the vocabulary every desktop toolbar shares; each
1480/// backend realizes one with its native control, never with a drawn imitation.
1481#[derive(Clone, Debug, PartialEq)]
1482pub enum ToolbarItemKind {
1483    /// A push button running the item's `action`.
1484    Button,
1485    /// A two-state button. `on` seeds it; the user flipping it emits
1486    /// [`ToolbarValue::On`], and the app's own writes arrive as [`ToolbarPatch::On`].
1487    Toggle { on: bool },
1488    /// A button that drops a menu: the same [`MenuItem`] model the menu bar uses, so a
1489    /// toolbar menu and its menu-bar twin are one list of commands.
1490    Menu { items: Vec<MenuItem> },
1491    /// A search field. Edits emit [`ToolbarValue::Text`]; the app's own writes arrive as
1492    /// [`ToolbarPatch::Text`].
1493    ///
1494    /// Day creates this item itself, from a `.searchable()` surface whose placement resolved to
1495    /// the toolbar (docs/search.md); apps declare search on the surface, never here.
1496    Search {
1497        text: String,
1498        placeholder: String,
1499        /// Completions for the current text, drawn by the field's own completion affordance
1500        /// where it has one (`AutoSuggestBox`, `QCompleter`, `<datalist>`). Empty = none.
1501        suggestions: Vec<String>,
1502    },
1503    /// A row of mutually exclusive choices drawn as one control: the native segmented control
1504    /// (`NSSegmentedControl`, a linked GTK/Qt button box, a XAML toggle strip, `.day-segmented`
1505    /// on the web).
1506    ///
1507    /// This is what a set of related toolbar toggles should be when exactly one of them is on at
1508    /// a time: three separate toggles say "three independent switches" to the eye and to a screen
1509    /// reader, and leave the app to keep them exclusive. Choosing a segment emits
1510    /// [`ToolbarValue::Selected`]; the app's own writes arrive as [`ToolbarPatch::Selected`].
1511    Segmented {
1512        /// One entry per segment. A segment with an icon draws it in place of its title where
1513        /// the platform does that, and keeps the title as its accessible name.
1514        segments: Vec<ToolbarSegment>,
1515        selected: usize,
1516    },
1517    /// Static text, for a status or a caption.
1518    Label,
1519    /// A divider between neighbors in the same placement bucket, where the platform draws one
1520    /// (macOS toolbars have no separator, so AppKit renders it as a fixed space,
1521    /// docs/toolbars.md). Grouping is all it does: alignment is [`ToolbarPlacement`]'s job.
1522    Separator,
1523}
1524
1525/// One choice inside a [`ToolbarItemKind::Segmented`] control.
1526#[derive(Clone, Debug, PartialEq)]
1527pub struct ToolbarSegment {
1528    /// The segment's name: its label where the platform shows text, its accessible name always.
1529    pub title: String,
1530    pub icon: Option<Icon>,
1531}
1532
1533/// The reserved id of the sidebar affordance a `nav(Sidebar)` supplies for itself
1534/// (docs/toolbars.md). Backends with a system item for the job (AppKit's
1535/// `NSToolbarToggleSidebarItem`) recognize it by this id and draw theirs instead; dayscript
1536/// recognizes it to drive the toolkit's own duty rather than an app closure.
1537pub const SIDEBAR_TOGGLE_ID: &str = "day::sidebar_toggle";
1538
1539/// The reserved id of a `.searchable()` surface's field (docs/search.md): the `ToolbarItem` a
1540/// desktop bar draws for it, and the name dayscript's `toolbar:` step drives it by wherever the
1541/// platform put it — on the bar, or inline on the navigation surface where the bar holds no
1542/// field, in which case day-core resolves the id to that host instead.
1543pub const SEARCH_ITEM_ID: &str = "day::search";
1544
1545/// One item in a window's toolbar (docs/toolbars.md).
1546#[derive(Clone, Debug, PartialEq)]
1547pub struct ToolbarItem {
1548    /// Stable identity: the native item identifier, the dayscript target, and the key a
1549    /// [`ToolbarPatch`] addresses. Unique within a toolbar.
1550    pub id: String,
1551    pub kind: ToolbarItemKind,
1552    /// The item's name. Shown beside or below the icon where the platform does that, and used
1553    /// verbatim in the overflow and customization menus, so it is never optional, even on a
1554    /// toolbar that only shows icons. It is also the item's accessible name.
1555    pub label: String,
1556    /// Hover help. Defaults to `label` where the platform expects a tooltip and none is given.
1557    pub tooltip: Option<String>,
1558    pub icon: Option<Icon>,
1559    pub enabled: bool,
1560    /// The item's command, as a dispatch id from the same registry [`Event::MenuAction`] uses
1561    /// (0 = no command), so a toolbar button and its menu twin can share one closure.
1562    pub action: u64,
1563    /// This item's role on the chrome carrying it (docs/toolbars.md). It never names a surface:
1564    /// Which chrome an item rides is decided by where the app declared it, so this says only
1565    /// where on that chrome it belongs.
1566    pub placement: ToolbarPlacement,
1567    /// Whether the item draws its title, its icon, or both, where the platform can do more than
1568    /// one. An item folded into an overflow menu shows its title whatever this asks for; a menu
1569    /// row with no words is not a menu row.
1570    pub label_style: LabelStyle,
1571    /// Draw this item in the platform's emphasized style (a tinted/filled bar button, a
1572    /// prominent `NSToolbarItem`). For the one action a chrome is really offering.
1573    pub prominent: bool,
1574    /// Which column of a multi-pane window this item came from (docs/toolbars.md), set by Day
1575    /// from the piece that declared it, never by an app.
1576    ///
1577    /// A desktop toolbar spans every column at once, and a three-pane app expects each column's
1578    /// commands to sit over that column: the sidebar's against the first divider, the list's over
1579    /// the list, the rest over the detail. That is what Mail, Notes and Finder do, and it is only
1580    /// expressible because the declaration site already said which pane the command belongs to.
1581    /// Backends that draw one undivided bar ignore it.
1582    pub column: ToolbarColumn,
1583}
1584
1585/// Which pane of a window's navigation a toolbar item was declared in (docs/toolbars.md).
1586#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
1587pub enum ToolbarColumn {
1588    /// The window itself, over no particular column. Draws with the detail's items, which is
1589    /// where a command that acts on the whole window belongs when the panes are side by side.
1590    #[default]
1591    Window,
1592    /// The sidebar / master column.
1593    Sidebar,
1594    /// The content-list column between the sidebar and the detail.
1595    List,
1596    /// The detail column.
1597    Detail,
1598}
1599
1600/// Where an item sits on the chrome that carries it (docs/toolbars.md).
1601///
1602/// A placement is a role, never a surface. Which toolbar, navigation bar or column an item
1603/// rides follows from the piece that declared it, so an app never spells that out twice.
1604#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
1605pub enum ToolbarPlacement {
1606    /// The natural spot on this chrome: after the leading group on a desktop toolbar, the
1607    /// trailing item group on a navigation bar, an `IF_ROOM` menu action on Android.
1608    #[default]
1609    Automatic,
1610    /// The leading edge: a pane toggle, a control that reveals what is to its left.
1611    Navigation,
1612    /// Centered: a title accessory, a transport, a status readout.
1613    Principal,
1614    /// Trailing, and the last thing a crowded chrome gives up.
1615    Primary,
1616    /// Trailing, and the first thing a crowded chrome folds into its overflow.
1617    Secondary,
1618    /// A bottom bar where the platform has one (iOS `toolbarItems`, an Android bottom app bar);
1619    /// [`ToolbarPlacement::Secondary`] everywhere else.
1620    Bottom,
1621}
1622
1623/// Which halves of an item's label a platform draws, where it can draw more than one.
1624#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
1625pub enum LabelStyle {
1626    /// The platform's own convention for this chrome.
1627    #[default]
1628    Automatic,
1629    /// The icon alone (the title stays as the accessible name and the tooltip).
1630    IconOnly,
1631    /// The title alone, even where an icon was given.
1632    TitleOnly,
1633    /// Both, where the chrome has room for both.
1634    TitleAndIcon,
1635}
1636
1637/// A value a toolbar item produced.
1638#[derive(Clone, Debug, PartialEq)]
1639pub enum ToolbarValue {
1640    /// A search item's full new text.
1641    Text(String),
1642    /// A search item's text, submitted with the field's Return or Search key. Sent after the
1643    /// last [`ToolbarValue::Text`]; it changes no state of its own.
1644    Submit(String),
1645    /// A toggle item's new state.
1646    On(bool),
1647    /// A segmented item's newly chosen index.
1648    Selected(usize),
1649}
1650
1651/// A targeted update to one live toolbar item: the path that keeps a bound signal in sync
1652/// without rebuilding the bar (which would drop the search field's focus mid-keystroke).
1653#[derive(Clone, Debug, PartialEq)]
1654pub enum ToolbarPatch {
1655    /// Focus a search control and select its text without changing its value.
1656    Focus { item: String },
1657    /// Replace a search item's text.
1658    Text { item: String, text: String },
1659    /// Set a toggle item's state.
1660    On { item: String, on: bool },
1661    /// Select a segmented item's index.
1662    Selected { item: String, index: usize },
1663    /// Enable or disable any item.
1664    Enabled { item: String, on: bool },
1665    /// Replace a search item's completions (docs/search.md). Targeted rather than a rebuild,
1666    /// because these change on every keystroke and rebuilding the bar would take the field's
1667    /// focus with it.
1668    Suggestions { item: String, list: Vec<String> },
1669    /// Replace an item's words (a language change): its label, which an icon-only item still
1670    /// carries for the overflow menu and assistive technology, and its tooltip. The item keeps
1671    /// its native widget, its action and its place.
1672    Label {
1673        item: String,
1674        label: String,
1675        tooltip: Option<String>,
1676    },
1677    /// Replace a search item's empty-state prompt (docs/search.md), in the live field.
1678    Placeholder { item: String, text: String },
1679}
1680
1681impl ToolbarPatch {
1682    /// The id of the item this patch addresses.
1683    pub fn item(&self) -> &str {
1684        match self {
1685            ToolbarPatch::Focus { item }
1686            | ToolbarPatch::Text { item, .. }
1687            | ToolbarPatch::On { item, .. }
1688            | ToolbarPatch::Selected { item, .. }
1689            | ToolbarPatch::Enabled { item, .. }
1690            | ToolbarPatch::Suggestions { item, .. }
1691            | ToolbarPatch::Label { item, .. }
1692            | ToolbarPatch::Placeholder { item, .. } => item,
1693        }
1694    }
1695
1696    /// Write this patch's value into `items`, the model of a bar. `false` when no item there
1697    /// takes it (an unknown id, or a kind the value does not apply to).
1698    pub fn apply_to(&self, items: &mut [ToolbarItem]) -> bool {
1699        let Some(it) = items.iter_mut().find(|i| i.id == self.item()) else {
1700            return false;
1701        };
1702        match (self, &mut it.kind) {
1703            (ToolbarPatch::Focus { .. }, ToolbarItemKind::Search { .. }) => (),
1704            (ToolbarPatch::Text { text, .. }, ToolbarItemKind::Search { text: t, .. }) => {
1705                *t = text.clone()
1706            }
1707            (
1708                ToolbarPatch::Suggestions { list, .. },
1709                ToolbarItemKind::Search { suggestions, .. },
1710            ) => *suggestions = list.clone(),
1711            (ToolbarPatch::On { on, .. }, ToolbarItemKind::Toggle { on: o }) => *o = *on,
1712            (
1713                ToolbarPatch::Selected { index, .. },
1714                ToolbarItemKind::Segmented { segments, selected },
1715            ) if *index < segments.len() => *selected = *index,
1716            (ToolbarPatch::Enabled { on, .. }, _) => it.enabled = *on,
1717            (ToolbarPatch::Label { label, tooltip, .. }, _) => {
1718                it.label = label.clone();
1719                it.tooltip = tooltip.clone();
1720            }
1721            (
1722                ToolbarPatch::Placeholder { text, .. },
1723                ToolbarItemKind::Search { placeholder, .. },
1724            ) => *placeholder = text.clone(),
1725            _ => return false,
1726        }
1727        true
1728    }
1729}
1730
1731/// One step of an edit to a window's toolbar (docs/toolbars.md).
1732///
1733/// Day hands a backend its bar as edits, never as a whole new model to rebuild, for the same
1734/// reason the view tree arrives as `insert`/`remove` rather than as a fresh tree: an item the
1735/// edit does not name keeps its native widget, and with it the keyboard focus, the caret, a
1736/// menu that is open. A value (search text, a toggle) never travels as an edit; it is a
1737/// [`ToolbarPatch`] on the live item.
1738///
1739/// An edit lists every [`ToolbarOp::Remove`] first, then every [`ToolbarOp::Insert`] in
1740/// ascending `index`, so applying them in order to the bar's current items (a
1741/// [`ToolbarMirror`] does exactly that) produces the new bar. Items keep their relative order
1742/// across an edit: an item that moves arrives as a remove and an insert, like one whose
1743/// presentation changed.
1744#[derive(Clone, Debug, PartialEq)]
1745pub enum ToolbarOp {
1746    /// The item with this id leaves the bar.
1747    Remove { id: String },
1748    /// `item` joins the bar at `index`, its position once this edit is complete.
1749    Insert { index: usize, item: ToolbarItem },
1750}
1751
1752impl ToolbarOp {
1753    /// Apply this op to `items`, a bar's model in order.
1754    pub fn apply_to(&self, items: &mut Vec<ToolbarItem>) {
1755        match self {
1756            ToolbarOp::Remove { id } => items.retain(|i| i.id != *id),
1757            ToolbarOp::Insert { index, item } => {
1758                items.insert((*index).min(items.len()), item.clone())
1759            }
1760        }
1761    }
1762}
1763
1764/// A backend's copy of one window's toolbar, kept in step with the [`ToolbarOp`]s and
1765/// [`ToolbarPatch`]es that reach it, and the one place a backend works out where a new item
1766/// goes (docs/toolbars.md).
1767///
1768/// Every backend lays its bar out as a few groups (the leading and trailing ends of a header
1769/// bar, the columns of a split window, the primary and overflow commands of a command bar) and
1770/// keeps model order within each. So an inserted item always goes right after
1771/// [`ToolbarMirror::prev_where`] its own group, or first in the group when that is `None`, and
1772/// nothing already on the bar moves.
1773#[derive(Clone, Debug, Default)]
1774pub struct ToolbarMirror {
1775    items: Vec<ToolbarItem>,
1776}
1777
1778impl ToolbarMirror {
1779    /// The bar's items, in model order.
1780    pub fn items(&self) -> &[ToolbarItem] {
1781        &self.items
1782    }
1783
1784    pub fn is_empty(&self) -> bool {
1785        self.items.is_empty()
1786    }
1787
1788    /// The item with this id.
1789    pub fn get(&self, id: &str) -> Option<&ToolbarItem> {
1790        self.items.iter().find(|i| i.id == id)
1791    }
1792
1793    /// The item dispatching `action`: how a backend whose native bar reports only an action
1794    /// id (a menu tap) finds what was tapped.
1795    pub fn by_action(&self, action: u64) -> Option<&ToolbarItem> {
1796        self.items
1797            .iter()
1798            .find(|i| i.action == action && action != 0)
1799    }
1800
1801    /// Take the item with `id` out, returning it.
1802    pub fn remove(&mut self, id: &str) -> Option<ToolbarItem> {
1803        let at = self.items.iter().position(|i| i.id == id)?;
1804        Some(self.items.remove(at))
1805    }
1806
1807    /// Put `item` at `index` (clamped to the end).
1808    pub fn insert(&mut self, index: usize, item: ToolbarItem) {
1809        let at = index.min(self.items.len());
1810        self.items.insert(at, item);
1811    }
1812
1813    /// Apply one op to the model: what a backend that repaints its whole native bar from the
1814    /// model (a menu of actions) does with each.
1815    pub fn apply(&mut self, op: &ToolbarOp) {
1816        op.apply_to(&mut self.items);
1817    }
1818
1819    /// Write a value patch into the model. `false` when no item takes it.
1820    pub fn patch(&mut self, patch: &ToolbarPatch) -> bool {
1821        patch.apply_to(&mut self.items)
1822    }
1823
1824    /// The nearest item before `index` that `same_group` accepts: the native item a new one at
1825    /// `index` goes right after, in that group. `None` = it goes first in the group.
1826    pub fn prev_where(
1827        &self,
1828        index: usize,
1829        same_group: impl Fn(&ToolbarItem) -> bool,
1830    ) -> Option<&ToolbarItem> {
1831        self.items[..index.min(self.items.len())]
1832            .iter()
1833            .rev()
1834            .find(|i| same_group(i))
1835    }
1836}
1837
1838#[derive(Clone, Debug, PartialEq)]
1839pub struct KeyEvent {
1840    /// The key's name, in the web `KeyboardEvent.key` vocabulary every platform can map onto:
1841    /// the four arrows ("ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown") and the ten digits
1842    /// ("0" through "9", from the main row or the numeric keypad) everywhere, plus
1843    /// "Delete" and "Backspace" on backends with no menu bar ([`Cap::AppMenu`] unsupported),
1844    /// where no accelerator can own those keys. A focused piece claims every key the route
1845    /// carries, so offering them on a menu-bar platform would let a canvas swallow the Delete
1846    /// its own Edit menu was about to act on (docs/menus.md). The two delete keys keep the
1847    /// names the platform gives the physical keys (a Mac's ⌫ is "Backspace" and its ⌦ is
1848    /// "Delete"), so a handler that means "remove this" takes both. A digit arrives only while
1849    /// neither [`KeyEvent::PRIMARY`] nor [`KeyEvent::ALT`] (nor a Mac's Control) is held: ⌘1
1850    /// and Ctrl+1 are accelerators, and a canvas claiming them would starve the menu. Most
1851    /// backends name the digit the keypress types, so a layout whose number row needs Shift for
1852    /// digits reports "1" with [`KeyEvent::SHIFT`] set; XAML and ArkUI read the physical key.
1853    /// Backends emit `Event::Key` only while no text widget has focus; a field's own editing
1854    /// keys never surface here.
1855    pub key: String,
1856    /// A [`KeyEvent::SHIFT`]/[`KeyEvent::PRIMARY`]/[`KeyEvent::ALT`] mask.
1857    pub modifiers: u8,
1858}
1859
1860impl KeyEvent {
1861    pub const SHIFT: u8 = 1;
1862    /// The platform's command key: ⌘ on Apple platforms, Ctrl elsewhere (the
1863    /// [`Shortcut::primary`] convention).
1864    pub const PRIMARY: u8 = 2;
1865    pub const ALT: u8 = 4;
1866
1867    /// The ten digit key names, indexed by value.
1868    pub const DIGITS: [&'static str; 10] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"];
1869
1870    /// The key name for a typed character when it is one of the ten digits: what a backend
1871    /// reports for a keypress that types `0`–`9`.
1872    pub fn digit_name(c: char) -> Option<&'static str> {
1873        c.to_digit(10).map(|d| Self::DIGITS[d as usize])
1874    }
1875
1876    /// The value of a digit key, or `None` for every other key.
1877    pub fn digit(&self) -> Option<u8> {
1878        match self.key.as_bytes() {
1879            [d @ b'0'..=b'9'] => Some(d - b'0'),
1880            _ => None,
1881        }
1882    }
1883
1884    pub fn shift(&self) -> bool {
1885        self.modifiers & Self::SHIFT != 0
1886    }
1887    pub fn primary(&self) -> bool {
1888        self.modifiers & Self::PRIMARY != 0
1889    }
1890    pub fn alt(&self) -> bool {
1891        self.modifiers & Self::ALT != 0
1892    }
1893}
1894
1895#[cfg(test)]
1896mod key_event_tests {
1897    use super::KeyEvent;
1898
1899    #[test]
1900    fn digit_names_read_back_as_values() {
1901        for (value, c) in ('0'..='9').enumerate() {
1902            let name = KeyEvent::digit_name(c).expect("an ASCII digit names itself");
1903            let key = KeyEvent {
1904                key: name.to_string(),
1905                modifiers: 0,
1906            };
1907            assert_eq!(key.digit(), Some(value as u8));
1908        }
1909        // Only the ASCII digits: a letter, an Arabic-Indic three, and a named key are not.
1910        assert_eq!(KeyEvent::digit_name('a'), None);
1911        assert_eq!(KeyEvent::digit_name('٣'), None);
1912        let arrow = KeyEvent {
1913            key: "ArrowUp".to_string(),
1914            modifiers: 0,
1915        };
1916        assert_eq!(arrow.digit(), None);
1917    }
1918}
1919
1920#[derive(Clone, Copy, Debug, PartialEq)]
1921pub struct PointerEvent {
1922    pub position: Point,
1923    pub down: bool,
1924}
1925
1926/// The event sink: enqueue-only. It may be invoked re-entrantly from inside any Toolkit method;
1927/// day-core drains queued events at safe points, each as a fresh batch (§3.3).
1928pub type EventSink = Box<dyn Fn(NodeId, Event)>;
1929
1930/// The synchronous row-pull closures for recycling lists (docs/list.md, §10). day-core injects one
1931/// per `LIST` host via [`Toolkit::attach_list`]; a recycling backend stores it and calls it from
1932/// its native data-source (on the UI thread, outside any day-core borrow). Each closure re-enters
1933/// day-core, so, unlike [`EventSink`], these run to completion synchronously (`bind_row` even
1934/// flushes + lays out the row before returning, so the host can measure the cell immediately).
1935#[derive(Clone)]
1936pub struct ListSource {
1937    /// Report the first actually visible row (exclude overscan). Enqueue-only; optional,
1938    /// so hosts without a viewport binding incur no app event work.
1939    pub first_visible: Option<std::rc::Rc<dyn Fn(usize)>>,
1940    /// Current row count.
1941    pub len: std::rc::Rc<dyn Fn() -> usize>,
1942    /// Present on a sectioned list (`ListProps::sections`, docs/list.md "Sections"): whether
1943    /// row `index` is a section header. Every row index the host sees counts headers, and
1944    /// day-core translates to the app's items. A header row is not selectable, activatable or
1945    /// swipeable; the host draws it in its platform's group-header style, sized to its content
1946    /// even in a `Uniform` list, and floats it where the platform does (macOS group rows,
1947    /// UIKit plain-table section headers).
1948    pub is_header: Option<std::rc::Rc<dyn Fn(usize) -> bool>>,
1949    /// Stable identity token for the row at `index` (for native diffing / animation).
1950    pub token_at: std::rc::Rc<dyn Fn(usize) -> u64>,
1951    /// Build (first use of this cell) or rebind (recycled cell) row `index` into the native cell.
1952    pub bind_row: std::rc::Rc<dyn Fn(usize, RawHandle)>,
1953    /// A host that emulates `Cap::ListSections` binds the header it pins over the top of the
1954    /// list with this instead of `bind_row` (docs/list.md "Sections"): the same build or
1955    /// rebind, but the copy carries no element ids, so a dayscript or accessibility lookup of a
1956    /// header finds the header row in the list, never its pinned copy.
1957    pub bind_pinned: std::rc::Rc<dyn Fn(usize, RawHandle)>,
1958    /// The native cell left the viewport; Day may drop per-cell bookkeeping (optional).
1959    pub recycle: std::rc::Rc<dyn Fn(RawHandle)>,
1960    /// The native host is done with this cell for good (a `GtkListItemFactory::teardown`, a
1961    /// `UITableViewCell` deallocating): Day disposes the row it built there, its scope, nodes
1962    /// and element ids. Without this a host that discards cells, as every pool does on a far
1963    /// jump, leaves one dead row behind in day-core per discarded cell. Safe inside a day-core
1964    /// borrow (the work is held for the borrow's end) and for a cell Day never saw.
1965    pub release: std::rc::Rc<dyn Fn(RawHandle)>,
1966    /// Re-lay the row bound to this cell at `width`, called from the cell's own native layout
1967    /// pass, the hook [`TreeSource::layout_cell`] already gives trees. day-core lays a row at the
1968    /// `LIST`'s width first, which is right wherever the cell is the row itself; a backend
1969    /// whose native row wraps the cell in chrome (GtkListView's themed `row` node pads it)
1970    /// corrects it here, so the row fits the cell the platform gave it instead of holding the
1971    /// whole list wider than its frame. Skips quietly when called inside a day-core borrow (a
1972    /// snapshot pass).
1973    pub layout_cell: std::rc::Rc<dyn Fn(RawHandle, f64)>,
1974    /// The height day-core last laid the row bound to this cell at: the row's own height,
1975    /// padding included, as `RowHeight` resolves it. A backend whose cell measures itself
1976    /// (GtkListView's `DayCell`) reports it as the cell's height, so a padded row keeps its
1977    /// bottom padding rather than the height of its last child's frame. `0.0` before the row's
1978    /// first layout, or inside a day-core borrow.
1979    pub cell_height: std::rc::Rc<dyn Fn(RawHandle) -> f64>,
1980    /// Drag-to-reorder closures, present when `ListProps::reorderable` (docs/list.md). `None` on
1981    /// non-reorderable lists; backends must not enable their drag machinery without it.
1982    pub reorder: Option<ListReorder>,
1983    /// Swipe-to-delete closures, present when `ListProps::deletable` (docs/list.md). `None` on
1984    /// non-deletable lists; backends must not offer their delete affordance without it.
1985    pub delete: Option<ListDelete>,
1986    /// Swipe-actions closures, present when `ListProps::swipe_actions` (docs/list.md). `None` on
1987    /// lists that declared none; backends must not install their row-action machinery
1988    /// without it.
1989    pub swipe: Option<ListSwipe>,
1990}
1991
1992/// The synchronous drag-to-reorder half of [`ListSource`] (docs/list.md). Both closures follow
1993/// `bind_row`'s discipline: called on the UI thread from inside native drag callbacks, outside
1994/// any day-core borrow, and they run to completion synchronously.
1995#[derive(Clone)]
1996pub struct ListReorder {
1997    /// May row `from` drop at row `to`? Called from the native validate/hover hook so the
1998    /// affordance (gap, insertion mark, forbidden cursor) reflects the app's answer live.
1999    /// Returns the accepted target index: `to` itself to allow, another index to retarget the
2000    /// drop, or `-1` to deny.
2001    pub can_move: std::rc::Rc<dyn Fn(usize, usize) -> i64>,
2002    /// Commit: row `from` dropped at row `to` (an index `can_move` accepted). Rotates Day's row
2003    /// snapshot before returning (so `len`/`token_at`/`bind_row` reflect the new order while the
2004    /// native move animates) and defers the app's own callback to the next event drain.
2005    pub move_row: std::rc::Rc<dyn Fn(usize, usize)>,
2006}
2007
2008/// The synchronous swipe-to-delete half of [`ListSource`] (docs/list.md), shaped exactly like
2009/// [`ListReorder`]: both closures are called on the UI thread from inside native swipe callbacks,
2010/// outside any day-core borrow, and run to completion synchronously.
2011///
2012/// Each platform spells the gesture its own way (a trailing swipe action on iOS, an
2013/// `ItemTouchHelper` swipe on Android, a `ListItem` swipe action on ArkUI), but all three ask the
2014/// same two questions, so this struct is one pair of closures rather than three shapes.
2015#[derive(Clone)]
2016pub struct ListDelete {
2017    /// May row `index` be deleted? Called before the affordance is offered, so a row the app
2018    /// protects shows no delete action at all rather than one that fails on use.
2019    pub can_delete: std::rc::Rc<dyn Fn(usize) -> bool>,
2020    /// Commit: delete row `index`. Removes it from Day's row snapshot before returning (so
2021    /// `len`/`token_at`/`bind_row` already reflect the shorter list while the native row-removal
2022    /// animates) and defers the app's own callback to the next event drain.
2023    pub delete_row: std::rc::Rc<dyn Fn(usize)>,
2024}
2025
2026/// Which edge of a row a swipe action rides (docs/list.md). Semantic, not geometric:
2027/// `Leading` follows the reading direction (the left edge in LTR, the right in RTL), the
2028/// mapping every platform's swipe API already makes.
2029#[derive(Clone, Copy, Debug, PartialEq, Eq)]
2030pub enum SwipeEdge {
2031    Leading,
2032    Trailing,
2033}
2034
2035/// One offered swipe action (docs/list.md): pure data. The pieces layer keeps the handlers;
2036/// the backend answers a tap through [`ListSwipe::perform`] by index into the offer.
2037#[derive(Clone, Debug, PartialEq)]
2038pub struct ListSwipeAction {
2039    /// The word on the button, already localized (a toolkit cannot translate).
2040    pub label: String,
2041    /// Destructive styling: the platform's red.
2042    pub destructive: bool,
2043    /// Explicit button color; `None` = the platform's default for the style.
2044    pub tint: Option<Color>,
2045    /// A glyph for the button where the platform draws one: above the label on macOS, in
2046    /// place of it on iOS (docs/list.md).
2047    pub symbol: Option<Symbol>,
2048}
2049
2050/// The synchronous swipe-actions half of [`ListSource`] (docs/list.md), the generalized
2051/// sibling of [`ListDelete`]: reveal-as-you-swipe buttons on either row edge. The offer is
2052/// pulled per row at gesture time, so labels follow row state ("Mark Read" on an unread row,
2053/// "Mark Unread" on a read one); the commit defers to the event drain like every closure here.
2054#[derive(Clone)]
2055pub struct ListSwipe {
2056    /// The offer: the actions for row `index` on `edge`, called inside the platform's swipe
2057    /// callback, so keep it pure. Empty = no affordance for that row and edge. The first action
2058    /// is the full-swipe action where the platform activates one at the far edge.
2059    pub actions_at: std::rc::Rc<dyn Fn(usize, SwipeEdge) -> Vec<ListSwipeAction>>,
2060    /// The commit: the user activated action `action` (an index into the offer) on row
2061    /// `index`, `edge`. Unlike a delete this never reshapes the row snapshot; the app's
2062    /// handler is deferred to the next event drain, never run inside the native callback.
2063    pub perform: std::rc::Rc<dyn Fn(usize, SwipeEdge, usize)>,
2064}
2065
2066/// The synchronous row-pull closures for hierarchical trees (docs/tree.md): [`ListSource`]'s
2067/// shape, addressed by token instead of row index, because expanding a row renumbers every
2068/// index below it while tokens hold still. day-core injects one per `TREE` host via
2069/// [`Toolkit::attach_tree`]; the backend answers its native data-source from it. The same
2070/// synchronous discipline as [`ListSource`]: UI thread, outside any day-core borrow;
2071/// `bind_row` flushes and lays the row out before returning.
2072#[derive(Clone)]
2073pub struct TreeSource {
2074    /// How many children `parent` has (`None` = the root level).
2075    pub children_len: std::rc::Rc<dyn Fn(Option<u64>) -> usize>,
2076    /// The i-th child of `parent`: the stable token every backend keys its rows by.
2077    pub child_token: std::rc::Rc<dyn Fn(Option<u64>, usize) -> u64>,
2078    /// Whether this token can hold children at all: what draws (or omits) the disclosure.
2079    pub expandable: std::rc::Rc<dyn Fn(u64) -> bool>,
2080    /// Non-selectable section heading, separate from a navigation destination.
2081    pub section_header: std::rc::Rc<dyn Fn(u64) -> bool>,
2082    /// Current desired expansion, including restoration before the first native reload.
2083    pub expanded: std::rc::Rc<dyn Fn(u64) -> bool>,
2084    /// Build (first use of this cell) or rebind (recycled cell) the row for `token` into the
2085    /// native cell.
2086    pub bind_row: std::rc::Rc<dyn Fn(u64, RawHandle)>,
2087    /// The native cell left the viewport; Day may drop per-cell bookkeeping (optional).
2088    pub recycle: std::rc::Rc<dyn Fn(RawHandle)>,
2089    /// Re-lay the row bound to this cell at `width`, called from the cell's own native
2090    /// layout pass. Trees need this where lists don't: indentation makes every cell's
2091    /// content width per-row, so the host-width layout `bind_row` did is only a first
2092    /// approximation. Skips quietly when called inside a day-core borrow (a snapshot pass).
2093    pub layout_cell: std::rc::Rc<dyn Fn(RawHandle, f64)>,
2094    /// Native bounds for controls whose group headers have a different height from leaves.
2095    /// Overrides the initial row-height estimate and preserves the native height on rebind.
2096    pub layout_cell_size: std::rc::Rc<dyn Fn(RawHandle, Size)>,
2097    /// The height day-core last laid this cell's row at (see [`ListSource::cell_height`]).
2098    pub cell_height: std::rc::Rc<dyn Fn(RawHandle) -> f64>,
2099    /// The row's type-ahead string (docs/tree.md): what native type-select matches against.
2100    pub type_select_text: std::rc::Rc<dyn Fn(u64) -> String>,
2101    /// The row's context menu, built when the menu is summoned (docs/menus.md "Dynamic context
2102    /// menus"), called on the UI thread from the platform's own menu callback, outside any
2103    /// day-core borrow, like every closure here. `None` = rows carry no menu; an empty
2104    /// result suppresses the menu for that row.
2105    pub row_menu: Option<std::rc::Rc<dyn Fn(u64) -> Vec<MenuItem>>>,
2106    /// Drag-to-move closures, present when `TreeProps::movable` (docs/tree.md). `None` on
2107    /// immovable trees; backends must not enable their drag machinery without it.
2108    pub moves: Option<TreeMoves>,
2109}
2110
2111/// The synchronous drag half of [`TreeSource`] (docs/tree.md). Both closures follow
2112/// `bind_row`'s discipline: called on the UI thread from inside native drag callbacks.
2113#[derive(Clone)]
2114pub struct TreeMoves {
2115    /// The live verdict, consulted while the drag is over a target: may `token` land under
2116    /// `parent` at `index`? `index: None` means "dropped onto the parent" (append). Pure, since
2117    /// it runs inside the platform's drag-validate callback.
2118    #[allow(clippy::type_complexity)]
2119    pub can_move: std::rc::Rc<dyn Fn(u64, Option<u64>, Option<usize>) -> MoveVerdict>,
2120    /// Commit an accepted drop. Defers the app's `on_move` through the event queue
2121    /// ([`Event::TreeMove`]); the app's own data write drives the reload.
2122    #[allow(clippy::type_complexity)]
2123    pub move_node: std::rc::Rc<dyn Fn(u64, Option<u64>, Option<usize>)>,
2124}
2125
2126/// A summon-time context-menu provider (docs/menus.md): local-point in, menu out.
2127pub type ContextMenuFn = std::rc::Rc<dyn Fn(Point) -> Vec<MenuItem>>;
2128
2129/// A tree move guard's verdict (docs/tree.md). No `Retarget` yet: the drop vocabulary is
2130/// already positional, so a guard that wants a different target denies and the user drops
2131/// where it is allowed.
2132#[derive(Clone, Copy, Debug, PartialEq, Eq)]
2133pub enum MoveVerdict {
2134    Allow,
2135    Deny,
2136}
2137
2138/// One addressable widget within a composite native backing (docs/tree.md,
2139/// docs/tweaks.md), Qt's name for the concept (`QStyle::SubControl`). A `list`'s or
2140/// `tree`'s node handle is its scroller; `Subcontrol::Content` is the widget inside it.
2141/// Backends resolve an unknown subcontrol to `None`, never to the host.
2142#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
2143pub enum Subcontrol {
2144    /// The node's own handle: what every tweak accessor reached before subcontrols existed.
2145    Host,
2146    /// The content widget inside the scroller (`NSOutlineView`, `NSTableView`, …).
2147    Content,
2148    /// The header view, where the widget has one. Day's lists and trees ship headerless, so
2149    /// this answers `None` until a kind grows a header.
2150    Header,
2151}
2152
2153// ---------------------------------------------------------------------------
2154// Capabilities, animation, a11y
2155// ---------------------------------------------------------------------------
2156
2157/// What to show on the app's icon in the Dock, launcher, home screen, or taskbar (docs/badge.md).
2158///
2159/// Distinct from `NavItem::badge`, which annotates a sidebar row inside the window. This one
2160/// decorates the application itself and is drawn by the shell, not by Day.
2161///
2162/// What each payload needs is asked separately (`Cap::AppBadgeCount`, `AppBadgeText`,
2163/// `AppBadgeDot`) because the platforms differ in what they accept more than in whether they have
2164/// a badge at all: macOS takes arbitrary text, iOS and the web take a number, Android takes nothing.
2165#[derive(Clone, Debug, PartialEq, Eq, Default)]
2166pub enum AppBadge {
2167    /// Clear the badge.
2168    #[default]
2169    None,
2170    /// A count. Zero clears it, matching every platform's own convention.
2171    Count(u32),
2172    /// Short arbitrary text (`"99+"`, `"beta"`). Only macOS renders it; probe `Cap::AppBadgeText`.
2173    Text(String),
2174    /// An indicator with no value.
2175    Dot,
2176}
2177
2178/// How wide a window is, in coarse buckets (docs/size-classes.md).
2179///
2180/// The breakpoints are Android's window size classes, in density-independent points, and they are
2181/// used verbatim on every backend rather than per-platform. One table means one answer: a 700pt
2182/// window is [`WidthClass::Medium`] on a Mac, in a browser, and on a tablet, so an app that lays
2183/// out from the class gets the same layout at the same size everywhere. Apple publishes only two
2184/// buckets (compact/regular); those map onto this table rather than replacing it, with
2185/// [`WidthClass::Compact`] the compact one and everything above it regular.
2186#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Default)]
2187pub enum WidthClass {
2188    /// `< 600dp`: a phone in portrait. One pane at a time.
2189    #[default]
2190    Compact,
2191    /// `600–839dp`: a tablet in portrait, a narrow desktop window.
2192    Medium,
2193    /// `840–1199dp`: a tablet in landscape, a typical desktop window.
2194    Expanded,
2195    /// `1200–1599dp`: a large desktop window.
2196    Large,
2197    /// `≥ 1600dp`: a maximized window on a big display.
2198    ExtraLarge,
2199}
2200
2201/// How tall a window is (docs/size-classes.md). Consulted far less than [`WidthClass`]: it is
2202/// what tells a phone in landscape (wide enough for two panes, too short for a tall list) that
2203/// it should not grow vertical chrome.
2204#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Default)]
2205pub enum HeightClass {
2206    /// `< 480dp`: a phone in landscape.
2207    #[default]
2208    Compact,
2209    /// `480–899dp`: a phone in portrait, a tablet in landscape.
2210    Medium,
2211    /// `≥ 900dp`: a tablet in portrait, most desktop windows.
2212    Expanded,
2213}
2214
2215/// A window's size class (docs/size-classes.md), reported by the backend and read by apps
2216/// through `day::size_class()`.
2217///
2218/// Per-window, not per-app: two windows of one process can sit in different classes at the same
2219/// time (a narrow and a wide window side by side, iPadOS Stage Manager, Android split-screen), and
2220/// an app that keyed off a single global would lay the second window out for the first one's size.
2221#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
2222pub struct SizeClass {
2223    pub width: WidthClass,
2224    pub height: HeightClass,
2225}
2226
2227impl SizeClass {
2228    /// The `Compact`/`Medium` width boundary in dp: the narrowest window where a second
2229    /// pane starts to fit. Backends that hand an adaptive container its pane widths derive
2230    /// them from this (Android's list + minimum-detail widths sum to it), so the platform's
2231    /// measure-time decision and this table agree by construction (docs/size-classes.md).
2232    pub const SPLIT_MIN_WIDTH: f64 = 600.0;
2233
2234    /// Bucket a window's size in points. The one place the breakpoint numbers appear.
2235    pub fn from_size(width: f64, height: f64) -> Self {
2236        SizeClass {
2237            width: match width {
2238                w if w >= 1600.0 => WidthClass::ExtraLarge,
2239                w if w >= 1200.0 => WidthClass::Large,
2240                w if w >= 840.0 => WidthClass::Expanded,
2241                w if w >= Self::SPLIT_MIN_WIDTH => WidthClass::Medium,
2242                _ => WidthClass::Compact,
2243            },
2244            height: match height {
2245                h if h >= 900.0 => HeightClass::Expanded,
2246                h if h >= 480.0 => HeightClass::Medium,
2247                _ => HeightClass::Compact,
2248            },
2249        }
2250    }
2251
2252    /// Whether a two-pane presentation fits. The rule behind an automatic
2253    /// [`props::NavPresentation`]: anything wider than compact gets both panes.
2254    pub fn prefers_split(self) -> bool {
2255        self.width > WidthClass::Compact
2256    }
2257}
2258
2259#[derive(Clone, Copy, PartialEq, Eq, Debug)]
2260pub enum Cap {
2261    /// Standard searchfield control.
2262    SearchField,
2263    /// Standard combobox control.
2264    ComboBox,
2265    /// Standard stepper control.
2266    Stepper,
2267    /// Standard datetime control.
2268    DateTimePicker,
2269    /// Standard colorpicker control.
2270    ColorPicker,
2271    /// Standard pullrefresh control.
2272    PullRefresh,
2273    /// Standard pager control.
2274    Pager,
2275    /// User-driven pull recognition, separate from a refresh indicator.
2276    PullRefreshGesture,
2277
2278    /// Native data-transfer source and destination callbacks.
2279    DragDrop,
2280    /// Transfers between independent native applications (inbound).
2281    DragExternalImport,
2282    /// Transfers to independent native applications, including arbitrary binary MIME data.
2283    DragExternalExport,
2284    /// Lossless ordered items and alternatives between Day applications.
2285    DragMultipleItems,
2286    /// Existing native file references, distinct from promised/generated files.
2287    DragFileReferences,
2288    /// Native result can wait for asynchronous data receipt.
2289    DragDeferredReceipt,
2290    /// Generated files supplied to a destination after dropping.
2291    DragFilePromises,
2292    /// External move acknowledgment safe for source deletion.
2293    DragExternalMove,
2294    ListRecycling,
2295    /// The toolkit fronts the app's undo stack with the platform's own undo system
2296    /// ([`Toolkit::set_undo_state`] + `Event::Undo`): `Native` where one exists
2297    /// (`NSUndoManager` on macOS/iOS, `QUndoStack`), `Unsupported` everywhere else, where
2298    /// Day's menu items and accelerators drive the stack directly and nothing platform-owned
2299    /// needs mirroring (docs/model.md).
2300    UndoBridge,
2301    /// The toolkit routes the platform's standard Cut/Copy/Paste to the app's edit bridge
2302    /// ([`Toolkit::set_edit_state`] + `Event::Edit`): the same menu items, shortcuts, and
2303    /// responder precedence the platform's text editing uses; a focused text widget keeps
2304    /// its own clipboard behavior, everything else reaches the app (docs/menus.md).
2305    /// `Native` where a system route exists (the responder chain, the browser's clipboard
2306    /// events), `Emulated` where Day's own menu items dispatch it, `Unsupported` elsewhere.
2307    EditBridge,
2308    /// The toolkit realizes `ListProps::reorderable` as drag-to-reorder rows: `Native` when the
2309    /// platform's own mechanism drives it (NSTableView drag/drop, UITableView drag delegates,
2310    /// ItemTouchHelper, …), `Emulated` for a pointer-tracked fake (web-dom). `Unsupported` ⇒ the
2311    /// list renders normally but rows cannot be dragged (docs/list.md).
2312    ListReorder,
2313    /// Sidebar destinations can be dragged to reorder (`NavBuilder::reorder_items`) and between
2314    /// sections (`NavBuilder::regroup_items`). `Native` when the toolkit's own sidebar drags them
2315    /// (`NavMenuProps::movable`, and across headers under `NavMenuProps::regroup`); `Emulated`
2316    /// when Day stands a reorderable list in for the sidebar. Independent of `ListReorder`: UIKit
2317    /// supports draggable content lists but retains its native navigation collection for
2318    /// sidebars.
2319    NavReorder,
2320    /// The toolkit realizes `ListProps::deletable` as the platform's delete gesture:
2321    /// `Native` where the platform ships one (UIKit's trailing swipe actions, Android's
2322    /// `ItemTouchHelper`, ArkUI's `ListItem.swipeAction`), `Unsupported` on the desktop toolkits,
2323    /// whose lists have no swipe idiom and where deletion belongs to a menu or a button
2324    /// (docs/list.md).
2325    ListDelete,
2326    /// The toolkit realizes `ListProps::swipe_actions` as edge swipe actions: buttons
2327    /// that reveal as the row tracks the swipe, with the far edge activating the first one
2328    /// (docs/list.md). `Native` where the platform ships the affordance: macos-appkit
2329    /// (`NSTableView` row actions, Mail's own machinery) and ios-uikit
2330    /// (`UISwipeActionsConfiguration`). `Unsupported` everywhere else: the affordance is
2331    /// absent, and the app's command lives in its explicit controls.
2332    ListSwipeActions,
2333    /// The toolkit realizes `ListProps::editing` as the platform's list editing mode: rows
2334    /// show their delete controls and reorder grips while the list is editing (docs/list.md).
2335    /// `Native` on ios-uikit (`UITableView` editing). `Unsupported` everywhere else, where a
2336    /// list has no separate editing mode: its rows already drag, swipe and open menus as they
2337    /// are, and the list renders as if `editing` were off.
2338    ListEditing,
2339    /// The toolkit realizes `kinds::LIST_ITEM` as its own list row content (docs/list.md "List
2340    /// items"): `Native` where the platform has a standard row it draws itself (UIKit's
2341    /// `UIListContentConfiguration`, a Material list item, AppKit's image-and-text table cell,
2342    /// a GTK row box), so the row takes the platform's fonts, icon size, spacing, secondary
2343    /// colors and check mark. `Unsupported` ⇒ the `list_item` piece composes the same content
2344    /// from plain pieces. Apps have no reason to probe this; the piece does.
2345    ListItem,
2346    /// The toolkit realizes `kinds::TREE` as a hierarchical tree view (docs/tree.md):
2347    /// `Native` where a platform tree widget hosts Day-built rows (NSOutlineView, the UIKit
2348    /// sidebar list, GtkListView+TreeListModel, WinUI TreeView, ArkTS TreeView), `Emulated`
2349    /// where Day flattens the tree onto its list machinery, `Unsupported` where neither
2350    /// exists yet. An app gates its tree UI on this answer rather than showing a placeholder.
2351    Tree,
2352    /// The toolkit realizes `TreeProps::movable` as drag-to-reparent/restack rows
2353    /// (docs/tree.md). A strictly smaller set than [`Cap::Tree`]: a backend can render a
2354    /// tree it cannot yet drag within.
2355    TreeMove,
2356    /// Native two-level section headers; general trees may still be composed.
2357    TreeSections,
2358    /// The toolkit answers [`Toolkit::first_baseline`], so rows can align text on its baseline
2359    /// rather than on the middle of its box (docs/baseline.md). `Native` where the platform
2360    /// reports the baseline itself (`NSView.firstBaselineOffsetFromTop`, `View.getBaseline`,
2361    /// `gtk_widget_measure`), `Emulated` where Day derives it from the widget's font metrics,
2362    /// `Unsupported` ⇒ baseline-aligned rows fall back to centering and look exactly as they do
2363    /// today.
2364    BaselineAlignment,
2365    /// The toolkit draws a label's [`TextRun`]s: bold, italic, color or a monospace face within
2366    /// one wrapping paragraph (docs/text-runs.md). `Unsupported` ⇒ the label renders its text
2367    /// uniformly, which reads correctly and loses only the emphasis.
2368    TextRuns,
2369    /// The toolkit makes a run carrying [`TextRun::link`] activatable, emitting
2370    /// [`Event::LinkActivated`]. A strictly smaller set than [`Cap::TextRuns`]: several toolkits
2371    /// draw a link run in link colors but have no way to hit-test it, and one (Android) can do
2372    /// links or selection but not both (docs/text-runs.md).
2373    TextLinks,
2374    Lottie,
2375    NativeSymbols,
2376    /// The toolkit can rasterize its window and hand back the pixels
2377    /// (`Toolkit::snapshot_window`): what the dayscript `screenshot` step captures in-process
2378    /// and what `day::window_image()` offers the app (docs/window-image.md). `Unsupported` where
2379    /// a backend cannot draw itself into a bitmap: web-dom, which would need a rasterizer
2380    /// shipped with it. Probe it before offering a "save a screenshot" affordance, rather than
2381    /// offering one that fails when pressed.
2382    Snapshot,
2383    /// The toolkit can present `nav()` as sidebar+detail split panes, a statement about the
2384    /// toolkit, not about the window it is currently drawing. Whether a given host is split right
2385    /// now follows from its [`SizeClass`]: the pieces layer resolves an automatic
2386    /// [`props::NavPresentation`] against both, and re-resolves on every class change. A backend
2387    /// with no split container answers `Unsupported` and stays stacked at every size.
2388    NavSplit,
2389    /// The toolkit can draw a navigation host's rows as its own chrome: a tab bar
2390    /// ([`props::NavPresentation::Tabs`]) and, where it has one, a rail
2391    /// ([`props::NavPresentation::Rail`]). Like [`Self::NavSplit`] this is a statement about the
2392    /// toolkit, not about the window it is drawing right now.
2393    ///
2394    /// This is what `NavStyle::Automatic` resolves against (docs/navigation.md): a backend
2395    /// answering `Unsupported` gets the sidebar resolver instead (`Split` ↔ `Stack`), which is
2396    /// what every backend did before adaptive navigation existed. So an unimplemented backend
2397    /// degrades to its previous behavior rather than to a hole.
2398    ///
2399    /// `Emulated` means the rows are composed from other widgets rather than drawn by a native
2400    /// tab container (Qt, web-dom). `Native` means a real one (`UITabBarController`, a Material
2401    /// `NavigationBarView`, `NavigationView`).
2402    NavTabs,
2403    /// A narrow window should become a tab bar here, a separate question from [`Self::NavTabs`],
2404    /// which only says the toolkit *can* draw one.
2405    ///
2406    /// The two differ on every desktop. macOS, GNOME, Qt and Windows can all draw a tab bar, and
2407    /// must, because an app is free to pin `NavStyle::Tabs`; but none of them grows one when
2408    /// its window is dragged narrow. A narrow Mail.app hides its sidebar and pushes; it does not
2409    /// sprout a bottom tab bar, and an app that did would look like a port. The phones and the web
2410    /// are the opposite: those are the surfaces whose window size ranges from a phone to a
2411    /// desktop, and a tab bar is what their users expect at the narrow end.
2412    ///
2413    /// So this is a statement about the platform's idiom, not about its widget set:
2414    ///
2415    /// - `Native`/`Emulated`: `NavStyle::Automatic` may resolve to
2416    ///   [`props::NavPresentation::Tabs`] on a compact window (ios-uikit, android-material,
2417    ///   harmony-arkui, web-dom).
2418    /// - `Unsupported`: it may not; a compact window collapses to
2419    ///   [`props::NavPresentation::Stack`] instead, exactly as `NavStyle::Sidebar` has always
2420    ///   done (macos-appkit, linux-gtk, linux-qt, windows-winui).
2421    ///
2422    /// [`props::NavPresentation::Rail`] is not gated by this. A narrow sidebar is an ordinary
2423    /// desktop shape (on Windows it is what `NavigationView` does at that width on its own), so
2424    /// the rail rung stays available everywhere `Cap::NavSplit` is.
2425    NavTabsAdaptive,
2426    /// How a navigation host's presentation follows the window (docs/size-classes.md). All three
2427    /// answers mean something different here, and the difference is who decides:
2428    ///
2429    /// - `Native`: **Day tells the toolkit.** The pieces layer resolves the presentation from
2430    ///   the [`SizeClass`], re-resolves on every change, and sends
2431    ///   [`props::NavPatch::Presentation`]; the toolkit rebuilds its chrome and re-homes the
2432    ///   pages it already has. The desktops and web-dom.
2433    /// - `Emulated`: **the toolkit tells Day.** Its own adaptive container owns the decision
2434    ///   (`UISplitViewController` collapsing as a Pro Max iPhone rotates, `SlidingPaneLayout`
2435    ///   measuring whether both panes fit), so Day must not push a presentation into it: that
2436    ///   would be a second decision racing the platform's own animation. The toolkit
2437    ///   reports what it did with [`Event::NavPresentationChanged`] and Day reconciles.
2438    /// - `Unsupported`: nobody re-presents. The presentation is resolved once, from
2439    ///   [`Cap::NavSplit`] alone, and the window's size never enters into it. A toolkit that
2440    ///   cannot change presentation must not have it decided by something that can, or a window
2441    ///   launched narrow would be stuck stacked with no way back.
2442    NavRepresent,
2443    /// The toolkit places a navigation host's content-list page ([`props::Pane::List`]) in its
2444    /// own pane between the sidebar and the detail, the Mail shape: mailboxes, message list,
2445    /// message (docs/navigation.md). The three answers differ on what happens when the host
2446    /// leaves the split:
2447    ///
2448    /// - `Native`: the pane exists at every presentation. A narrow window collapses the
2449    ///   sidebar but keeps the list beside the detail, exactly as a narrow Mail.app does
2450    ///   (macos-appkit: a `contentList` `NSSplitViewItem`).
2451    /// - `Emulated`: the pane exists while split and merges into the navigation stack when
2452    ///   the host collapses (ios-uikit: `UISplitViewController` triple-column). The pieces
2453    ///   layer then interposes the list between the sidebar root and the detail
2454    ///   ([`props::NavPatch::ListInStack`]) and gates the detail push on the app's
2455    ///   `detail_visible` binding.
2456    /// - `Unsupported`: the backend never sees [`props::Pane::List`] or
2457    ///   [`props::NavProps::list_width`]; the nav piece composes the pane beside (split)
2458    ///   or in place of (stacked) the destination content itself.
2459    NavContentList,
2460    /// The toolkit shows the current destination's title in a native header/bar, so a page
2461    /// needn't repeat it in its own content. `Native` on XAML (the NavigationView header),
2462    /// UIKit (`UINavigationBar`), Android (`MaterialToolbar`), and ArkUI (`NavDestination`
2463    /// title bars). The desktop custom back-headers (AppKit/Qt/web) show a title only in
2464    /// stack mode, so those backends stay `Unsupported` (docs/navigation.md).
2465    NavHeader,
2466    /// The toolkit applies a runtime appearance override (`set_appearance`): native widgets
2467    /// restyle in place and `dark_mode` answers the override. Probe before showing a theme
2468    /// picker; on `Unsupported` backends the call is ignored.
2469    Appearance,
2470    /// The toolkit renders an application menu bar (docs/menus.md), so `app_menu` is visible to
2471    /// the user, and `register_preferences` gets its automatic Settings… item.
2472    ///
2473    /// The question an app asks before deciding where a command lives. Settings is the usual
2474    /// case: on a platform with a menu bar it belongs in the App menu and putting it in the
2475    /// navigation as well is clutter; on one without, the menu is a no-op and a Settings row is
2476    /// the only way in. Distinct from `Cap::Toolbar`: web-dom draws a window toolbar and has no
2477    /// menu bar at all, so keying off the toolbar strands Settings there.
2478    AppMenu,
2479    /// The toolkit can present native alert/confirm/sheet/prompt modals (docs/dialogs.md).
2480    Dialogs,
2481    /// The toolkit can present native open/save file pickers (docs/files.md).
2482    FileDialogs,
2483    /// The toolkit can present a native folder chooser (`PresentSpec::OpenFolder`,
2484    /// docs/files.md). `Native` on the four desktop toolkits (AppKit, GTK, Qt, WinUI); the
2485    /// phone and web backends answer `Unsupported` and resolve the request as `Dismissed`, so
2486    /// an app hides its "Add Folder…" command where this is not `Native`.
2487    FolderDialog,
2488    /// The toolkit runs backend-executed animation for `AnimSpec` intents on
2489    /// `update`/`set_frame`/`set_opacity`/`set_transform` (§8.4). `Unsupported` ⇒ animated calls
2490    /// apply instantly (still correct, just not animated).
2491    Animation,
2492    /// The toolkit presents a `kinds::COVER` node as a native fullscreen modal surface
2493    /// (docs/cover.md). `Unsupported` ⇒ the `cover` piece's content never shows.
2494    Cover,
2495    /// The toolkit presents a `.sheet()` cover as a native modal sheet (AppKit's window sheet,
2496    /// UIKit's page sheet) over the page it covers (docs/cover.md "Modal sheet"). `Unsupported`
2497    /// ⇒ the `cover` piece composes the sheet itself: on a window wider than compact, a card
2498    /// centered over the dimmed page; on a compact one, the full window.
2499    CoverSheet,
2500    /// The toolkit can hide the system status bar while a `status_bar_hidden` subtree is
2501    /// mounted (`Toolkit::set_status_bar_hidden`, docs/cover.md). `Native` on the phone and
2502    /// tablet backends; desktop and web have no status bar, so a setting that offers to hide
2503    /// it should be offered only where this is not `Unsupported`.
2504    StatusBarHidden,
2505    /// The toolkit's `text_area` can be made read-only (`TextAreaProps::editable = false`).
2506    TextEditable,
2507    /// The toolkit's `text_area` selectability can be toggled (`TextAreaProps::selectable`).
2508    /// `Unsupported` where selection is always on (GTK); `Emulated` where the backend
2509    /// collapses native selections itself (XAML, ArkUI).
2510    TextSelectable,
2511    /// The toolkit's `text_area` has built-in spell-check/autocorrect (`TextAreaProps::spellcheck`).
2512    /// `Unsupported` where the toolkit ships none (GTK, Qt, ArkUI).
2513    TextSpellCheck,
2514    /// The toolkit can open additional native OS windows (`Toolkit::open_window`,
2515    /// docs/windows.md). `Native` on the desktop backends and on mobile backends whose
2516    /// platform has a real secondary-window surface (iPad scenes, Android document
2517    /// activities, OHOS multiton abilities). On `Unsupported` backends
2518    /// `day_core::open_window` still works; the content presents as a fullscreen cover in
2519    /// the primary window instead. Probe it to adapt chrome: an `Unsupported` tier has no
2520    /// native title bar or close button, so window content should carry its own close
2521    /// affordance.
2522    MultiWindow,
2523    /// The toolkit can put a count on the app icon (`Toolkit::set_app_badge`, docs/badge.md).
2524    /// `Emulated` where the call is made but the shell may ignore it: desktop Linux, where the
2525    /// Unity launcher protocol is honored by Plasma and Dash-to-Dock but not by stock GNOME.
2526    AppBadgeCount,
2527    /// The toolkit renders `AppBadge::Text` as written. macOS only: `NSDockTile.badgeLabel` is an
2528    /// arbitrary string, while every other platform's badge is a number or nothing.
2529    AppBadgeText,
2530    /// The toolkit can show a valueless indicator (`AppBadge::Dot`).
2531    AppBadgeDot,
2532    /// The toolkit gives a window chrome that persists across pages
2533    /// (`Toolkit::edit_toolbar`, docs/toolbars.md): `Native` on the desktop backends and the
2534    /// phones, `Emulated` on web-dom, `Unsupported` where the only chrome belongs to a page.
2535    ///
2536    /// It no longer decides whether a command can be shown at all: a toolbar item declared on a
2537    /// piece rides that piece's own chrome everywhere. Probe it only for a layout decision that
2538    /// turns on a persistent bar existing.
2539    Toolbar,
2540    /// The window toolbar can hold a search field (docs/search.md): `Native` on the desktop
2541    /// backends, `Emulated` on web-dom. `Unsupported` on the phones, whose bar is a row of actions
2542    /// (an Android app-bar menu, iOS bar buttons, ArkUI title-bar menus): their field goes on the
2543    /// navigation surface instead, so `SearchPlacement::Toolbar` resolves to `Inline` there.
2544    ToolbarSearch,
2545    /// The toolkit realizes `kinds::INSPECTOR` as its own trailing-pane container
2546    /// (docs/inspector.md): an `NSSplitView` inspector pane, a `GtkPaned` with the panel as
2547    /// its end child, a `QDockWidget`, a XAML `SplitView` right pane. `Unsupported` ⇒ the
2548    /// `inspector` piece composes the pane from plain containers instead (same panel, same
2549    /// signal, no native divider), so an unimplemented backend degrades to a drawn pane, not
2550    /// to a hole. Apps normally have no reason to probe this; the piece does.
2551    Inspector,
2552    /// The toolkit realizes `kinds::SPLIT` as its own splitter (docs/split.md): an
2553    /// `NSSplitView`, a `GtkPaned`, a `QSplitter`, each side by side or stacked and with the
2554    /// divider the user drags. `Unsupported` ⇒ the `split` piece composes the two panes and
2555    /// draws and drags the divider itself (the web, the mobile toolkits, XAML), so the piece
2556    /// behaves the same everywhere and only the divider's look is the toolkit's. Apps have no
2557    /// reason to probe this; the piece does.
2558    Split,
2559    /// The toolkit shapes the pointer over a node from the `.cursor()` decorator
2560    /// ([`Toolkit::set_cursor`], docs/cursor.md). `Native` where the platform draws the requested
2561    /// shape from its own set (AppKit, GTK, the DOM, Android's `PointerIcon`), `Emulated` where
2562    /// some shapes map to a nearest neighbor (Qt, XAML) or the platform draws pointer effects
2563    /// rather than shapes (iPadOS), `Unsupported` where nothing changes: a touch-only toolkit,
2564    /// or one whose pointer API Day does not reach yet. Apps ask before offering an affordance
2565    /// that only a cursor reveals, such as a resize handle with no other visual.
2566    Cursor,
2567    /// The toolkit can enumerate the platform's font families with the faces each ships
2568    /// ([`Toolkit::font_families`], docs/fonts.md). `Native` where an OS font database answers
2569    /// (NSFontManager, UIFont, Pango, QFontDatabase, Android's `fonts.xml`,
2570    /// `OH_Drawing_FontMgr`, DirectWrite); `Emulated` where the list is composed rather than
2571    /// read: web-dom answers the CSS generic families plus the bundled `document.fonts`, since
2572    /// a browser exposes no local font list without a permission prompt; `Unsupported` means
2573    /// the list is empty and an app should offer only the default face. Measurement
2574    /// ([`Toolkit::measure_text`]) has no probe: a `None` answer degrades to
2575    /// [`TextMetrics::approximate`]. Probe this before offering a font menu, not before
2576    /// drawing; a [`CanvasFont`] draws everywhere.
2577    FontList,
2578    /// The toolkit reads the user's reduce-motion setting ([`Toolkit::reduce_motion`],
2579    /// docs/accessibility.md) and reports when it changes. `Native` where the platform has the
2580    /// switch and Day reaches it; `Unsupported` where Day reaches none (the app then animates as
2581    /// it would with the setting off, and `DAY_REDUCE_MOTION=1` still forces it on).
2582    ReduceMotion,
2583    /// The toolkit can speak a sentence through the screen reader without moving its focus
2584    /// ([`Toolkit::announce`], docs/accessibility.md): "Saved", "3 results", "Upload failed".
2585    /// `Native` where the platform has an announcement request (`NSAccessibility`'s
2586    /// announcement notification, `UIAccessibility`'s, Android's accessibility event, GTK
2587    /// 4.14's `gtk_accessible_announce`, a WinUI notification event); `Emulated` on the web,
2588    /// where an ARIA live region carries it; `Unsupported` where Day reaches no announcement
2589    /// API yet. An app with a visible status label needs no announcement: screen readers read
2590    /// what changes on screen only when told to, so this is for the change the user cannot
2591    /// otherwise learn about.
2592    Announce,
2593    /// The toolkit can turn encoded image bytes into a native image
2594    /// ([`Toolkit::decode_image`], docs/images.md): what `image(bytes)`, a pasted screenshot and
2595    /// a canvas image all rest on. `Native` wherever the platform decoder takes a buffer;
2596    /// `Unsupported` means only staged asset names draw, so an app should not offer "open an
2597    /// image" at all. Every backend that decodes also answers [`Toolkit::image_info`], so pixel
2598    /// size needs no probe of its own.
2599    ImageDecode,
2600    /// The toolkit can encode a decoded image back to bytes ([`Toolkit::encode_image`]).
2601    /// Which formats it encodes is [`Toolkit::encode_formats`], the same shape as
2602    /// [`Cap::FontList`]/[`Toolkit::font_families`], because "can encode" and "can encode WebP"
2603    /// are different questions and only the second one needs a list.
2604    ImageEncode,
2605    /// The toolkit can read an image's metadata beyond its pixels: EXIF orientation, DPI,
2606    /// capture time ([`Toolkit::image_properties`]). `Native` where a platform metadata reader
2607    /// is already linked (WinRT's `BitmapPropertiesView`, Android's `ExifInterface`);
2608    /// `Unsupported` where reading it would mean shipping a parser or a new framework, which is
2609    /// most places. An app that wants orientation must handle `None`.
2610    ImageProperties,
2611    /// The toolkit can replay a canvas drawing into an offscreen bitmap
2612    /// ([`Toolkit::render_bitmap`], docs/canvas.md "Exporting"): what `Drawing::to_bitmap` and
2613    /// `Drawing::to_png` rest on. `Native` where the toolkit's own canvas painter can target an
2614    /// image surface (a `CGBitmapContext`, a cairo image surface, a `QImage`, an android
2615    /// `Bitmap`, an `OH_Drawing_Bitmap`, a detached `<canvas>`); `Unsupported` where the
2616    /// on-screen canvas has no painter to retarget (WinUI builds XAML shapes instead).
2617    CanvasBitmap,
2618    /// The toolkit can replay canvas drawings into a PDF document ([`Toolkit::render_pdf`],
2619    /// docs/canvas.md "Exporting"), with vector shapes and the platform's own font embedding.
2620    /// `Native` only where the platform ships a PDF writer the canvas painter can draw into
2621    /// (Core Graphics on AppKit and UIKit, cairo on GTK, `QPdfWriter` on Qt, `PdfDocument` on
2622    /// Android); `Unsupported` on ArkUI, the web and WinUI, which have none.
2623    CanvasPdf,
2624    /// The toolkit minimizes, zooms, hides and restores a window on request
2625    /// ([`WindowChange::State`], [`WindowChange::Visible`], docs/windows.md) and reports what the
2626    /// user does through [`Event::WindowStateChanged`]. `Native` on the desktop backends;
2627    /// `Unsupported` on the phones and the web, whose windows the OS sizes.
2628    WindowStates,
2629    /// The toolkit takes a window fullscreen on request and reports when it enters and leaves
2630    /// ([`WindowState::Fullscreen`]). `Native` on the desktops, on Android (system bars hidden
2631    /// through `WindowInsetsController`), on HarmonyOS and on the web (the Fullscreen API, which
2632    /// browsers allow only during a user gesture); `Emulated` on iOS, which hides the status bar
2633    /// and lets the home indicator fade but always keeps the app full-screen anyway.
2634    WindowFullscreen,
2635    /// The toolkit keeps a window out of screenshots, recordings and screen sharing
2636    /// ([`WindowChange::ContentProtected`]). `Native` on macOS (`NSWindowSharingNone`), Windows
2637    /// (`WDA_EXCLUDEFROMCAPTURE`), Android (`FLAG_SECURE`) and HarmonyOS (privacy mode);
2638    /// `Emulated` on iOS, which has no switch for it: Day covers the content while the screen is
2639    /// being recorded or mirrored, but a screenshot still captures it. `Unsupported` on Linux
2640    /// and the web.
2641    ContentProtection,
2642    /// The toolkit honors [`WindowOptions::tabbing`]: macOS window tabs. `Unsupported` everywhere
2643    /// else, where no system window tabs exist.
2644    WindowTabbing,
2645    /// The toolkit shows a Dock menu ([`Toolkit::set_dock_menu`], docs/menus.md): the app's
2646    /// shortcuts and `dock_menu(..)` entries above the system's own items. macOS only.
2647    DockMenu,
2648    /// The toolkit resizes a window and bounds its size on request ([`WindowChange::Frame`]'s
2649    /// size, [`WindowChange::Limits`], [`WindowChange::Resizable`]).
2650    WindowGeometry,
2651    /// The toolkit moves a window to a requested position ([`WindowChange::Frame`]'s origin).
2652    /// `Unsupported` on GTK 4, which removed window positioning, and wherever the compositor owns
2653    /// placement (Wayland).
2654    WindowPosition,
2655    /// The toolkit changes how a window stacks ([`WindowChange::Level`],
2656    /// [`WindowChange::OnAllWorkspaces`], [`WindowChange::SkipTaskbar`]).
2657    WindowLevel,
2658    /// The toolkit gives one window its own light/dark appearance ([`WindowChange::Appearance`]).
2659    /// Where it cannot, the app-wide [`Toolkit::set_appearance`] still applies to every window.
2660    WindowAppearance,
2661    /// The toolkit asks for the user's attention on request ([`WindowChange::RequestAttention`]):
2662    /// a Dock bounce, a flashing taskbar button.
2663    RequestAttention,
2664    /// The toolkit opens a window with no title bar or frame ([`WindowChrome::Frameless`],
2665    /// docs/window-chrome.md). Desktop backends only.
2666    FramelessWindow,
2667    /// The toolkit runs a window's content under its title bar with the window controls kept
2668    /// ([`WindowChrome::Overlay`]) and reports the bar's height as the safe-area top inset.
2669    OverlayTitleBar,
2670    /// The toolkit opens a window whose unpainted pixels show the desktop
2671    /// ([`WindowBackground::Transparent`]).
2672    TransparentWindow,
2673    /// The toolkit puts a translucent system material behind a window
2674    /// ([`WindowBackground::Material`]): macOS's visual-effect materials, Windows 11's Mica and
2675    /// Acrylic. `Emulated` where an approximation stands in.
2676    WindowMaterial,
2677    /// The toolkit lets a piece move its window like a title bar does
2678    /// ([`Toolkit::set_drag_region`], `.window_drag_region()`). `Emulated` on the web, where
2679    /// only an installed app with a window-controls overlay honors it.
2680    DragRegion,
2681    /// The toolkit shows status items ([`Toolkit::set_status_items`], docs/status-item.md): the
2682    /// macOS menu bar, the Windows notification area, a Linux tray. On Linux the answer depends
2683    /// on the desktop: `Native` while a StatusNotifierItem host is running (KDE Plasma, most
2684    /// panels, GNOME with the AppIndicator extension), `Unsupported` without one (stock GNOME),
2685    /// so an app can keep a window instead of vanishing into a tray nobody shows.
2686    StatusItem,
2687    /// The toolkit shows progress on the app's Dock or taskbar icon
2688    /// ([`Toolkit::set_app_progress`]). `Emulated` on Linux, where the Unity launcher protocol is
2689    /// honored by KDE Plasma and Dash to Dock but not by every dock.
2690    AppProgress,
2691    /// The toolkit can hide the app's Dock icon while it runs ([`Toolkit::set_dock_visible`]).
2692    /// macOS only.
2693    DockVisibility,
2694    /// The toolkit lists the displays and their work areas ([`Toolkit::monitors`]). `Emulated`
2695    /// where the one screen the app runs on is reported (a phone, the web).
2696    Monitors,
2697    /// The toolkit shows launcher shortcuts the app sets while it runs
2698    /// ([`Toolkit::set_launcher_shortcuts`]).
2699    DynamicShortcuts,
2700    /// How the toolkit draws a sectioned list's headers (`ListProps::sections`, docs/list.md
2701    /// "Sections"). `Native` where the platform's list has group headers that pin to the top
2702    /// while their section scrolls under them: macos-appkit (`NSTableView` group rows with
2703    /// `floatsGroupRows`) and ios-uikit (plain-style `UITableView` section headers).
2704    /// `Emulated` where the host pins a copy of the current header over the top of the list
2705    /// itself. Headers are unselectable rows on every toolkit, so an app needs this only to
2706    /// describe the difference, never to decide whether to call `.sections`.
2707    ListSections,
2708}
2709
2710impl Cap {
2711    /// Every capability, in declaration order: what a conformance run asks the toolkit about,
2712    /// so the evidence can be held against the declared coverage matrix (docs/testing.md).
2713    pub const ALL: [Cap; 90] = [
2714        Cap::DragDrop,
2715        Cap::DragExternalImport,
2716        Cap::DragExternalExport,
2717        Cap::DragMultipleItems,
2718        Cap::DragFileReferences,
2719        Cap::DragDeferredReceipt,
2720        Cap::DragFilePromises,
2721        Cap::DragExternalMove,
2722        Cap::ListRecycling,
2723        Cap::UndoBridge,
2724        Cap::EditBridge,
2725        Cap::ListReorder,
2726        Cap::NavReorder,
2727        Cap::ListDelete,
2728        Cap::ListSwipeActions,
2729        Cap::Tree,
2730        Cap::TreeMove,
2731        Cap::BaselineAlignment,
2732        Cap::TextRuns,
2733        Cap::TextLinks,
2734        Cap::Lottie,
2735        Cap::NativeSymbols,
2736        Cap::Snapshot,
2737        Cap::NavSplit,
2738        Cap::NavTabs,
2739        Cap::NavTabsAdaptive,
2740        Cap::NavRepresent,
2741        Cap::NavContentList,
2742        Cap::NavHeader,
2743        Cap::Appearance,
2744        Cap::AppMenu,
2745        Cap::Dialogs,
2746        Cap::FileDialogs,
2747        Cap::Animation,
2748        Cap::Cover,
2749        Cap::StatusBarHidden,
2750        Cap::TextEditable,
2751        Cap::TextSelectable,
2752        Cap::TextSpellCheck,
2753        Cap::MultiWindow,
2754        Cap::AppBadgeCount,
2755        Cap::AppBadgeText,
2756        Cap::AppBadgeDot,
2757        Cap::Toolbar,
2758        Cap::ToolbarSearch,
2759        Cap::Inspector,
2760        Cap::Cursor,
2761        Cap::FontList,
2762        Cap::ReduceMotion,
2763        Cap::Announce,
2764        Cap::ImageDecode,
2765        Cap::ImageEncode,
2766        Cap::ImageProperties,
2767        Cap::WindowStates,
2768        Cap::WindowFullscreen,
2769        Cap::ContentProtection,
2770        Cap::WindowTabbing,
2771        Cap::DockMenu,
2772        Cap::WindowGeometry,
2773        Cap::WindowPosition,
2774        Cap::WindowLevel,
2775        Cap::WindowAppearance,
2776        Cap::RequestAttention,
2777        Cap::FramelessWindow,
2778        Cap::OverlayTitleBar,
2779        Cap::TransparentWindow,
2780        Cap::WindowMaterial,
2781        Cap::DragRegion,
2782        Cap::StatusItem,
2783        Cap::AppProgress,
2784        Cap::DockVisibility,
2785        Cap::Monitors,
2786        Cap::DynamicShortcuts,
2787        Cap::Split,
2788        Cap::TreeSections,
2789        Cap::CoverSheet,
2790        Cap::ListEditing,
2791        Cap::ListItem,
2792        Cap::CanvasBitmap,
2793        Cap::CanvasPdf,
2794        Cap::SearchField,
2795        Cap::ComboBox,
2796        Cap::Stepper,
2797        Cap::DateTimePicker,
2798        Cap::ColorPicker,
2799        Cap::PullRefresh,
2800        Cap::Pager,
2801        Cap::PullRefreshGesture,
2802        Cap::FolderDialog,
2803        Cap::ListSections,
2804    ];
2805
2806    /// The capability's place in [`Cap::ALL`]. Exhaustive, so a new variant fails to compile
2807    /// here until it is given one, and the unit test below then holds `ALL` to it.
2808    pub const fn ordinal(self) -> usize {
2809        match self {
2810            Cap::DragDrop => 0,
2811            Cap::DragExternalImport => 1,
2812            Cap::DragExternalExport => 2,
2813            Cap::DragMultipleItems => 3,
2814            Cap::DragFileReferences => 4,
2815            Cap::DragDeferredReceipt => 5,
2816            Cap::DragFilePromises => 6,
2817            Cap::DragExternalMove => 7,
2818            Cap::ListRecycling => 8,
2819            Cap::UndoBridge => 9,
2820            Cap::EditBridge => 10,
2821            Cap::ListReorder => 11,
2822            Cap::NavReorder => 12,
2823            Cap::ListDelete => 13,
2824            Cap::ListSwipeActions => 14,
2825            Cap::Tree => 15,
2826            Cap::TreeMove => 16,
2827            Cap::BaselineAlignment => 17,
2828            Cap::TextRuns => 18,
2829            Cap::TextLinks => 19,
2830            Cap::Lottie => 20,
2831            Cap::NativeSymbols => 21,
2832            Cap::Snapshot => 22,
2833            Cap::NavSplit => 23,
2834            Cap::NavTabs => 24,
2835            Cap::NavTabsAdaptive => 25,
2836            Cap::NavRepresent => 26,
2837            Cap::NavContentList => 27,
2838            Cap::NavHeader => 28,
2839            Cap::Appearance => 29,
2840            Cap::AppMenu => 30,
2841            Cap::Dialogs => 31,
2842            Cap::FileDialogs => 32,
2843            Cap::Animation => 33,
2844            Cap::Cover => 34,
2845            Cap::StatusBarHidden => 35,
2846            Cap::TextEditable => 36,
2847            Cap::TextSelectable => 37,
2848            Cap::TextSpellCheck => 38,
2849            Cap::MultiWindow => 39,
2850            Cap::AppBadgeCount => 40,
2851            Cap::AppBadgeText => 41,
2852            Cap::AppBadgeDot => 42,
2853            Cap::Toolbar => 43,
2854            Cap::ToolbarSearch => 44,
2855            Cap::Inspector => 45,
2856            Cap::Cursor => 46,
2857            Cap::FontList => 47,
2858            Cap::ReduceMotion => 48,
2859            Cap::Announce => 49,
2860            Cap::ImageDecode => 50,
2861            Cap::ImageEncode => 51,
2862            Cap::ImageProperties => 52,
2863            Cap::WindowStates => 53,
2864            Cap::WindowFullscreen => 54,
2865            Cap::ContentProtection => 55,
2866            Cap::WindowTabbing => 56,
2867            Cap::DockMenu => 57,
2868            Cap::WindowGeometry => 58,
2869            Cap::WindowPosition => 59,
2870            Cap::WindowLevel => 60,
2871            Cap::WindowAppearance => 61,
2872            Cap::RequestAttention => 62,
2873            Cap::FramelessWindow => 63,
2874            Cap::OverlayTitleBar => 64,
2875            Cap::TransparentWindow => 65,
2876            Cap::WindowMaterial => 66,
2877            Cap::DragRegion => 67,
2878            Cap::StatusItem => 68,
2879            Cap::AppProgress => 69,
2880            Cap::DockVisibility => 70,
2881            Cap::Monitors => 71,
2882            Cap::DynamicShortcuts => 72,
2883            Cap::Split => 73,
2884            Cap::TreeSections => 74,
2885            Cap::CoverSheet => 75,
2886            Cap::ListEditing => 76,
2887            Cap::ListItem => 77,
2888            Cap::CanvasBitmap => 78,
2889            Cap::CanvasPdf => 79,
2890            Cap::SearchField => 80,
2891            Cap::ComboBox => 81,
2892            Cap::Stepper => 82,
2893            Cap::DateTimePicker => 83,
2894            Cap::ColorPicker => 84,
2895            Cap::PullRefresh => 85,
2896            Cap::Pager => 86,
2897            Cap::PullRefreshGesture => 87,
2898            Cap::FolderDialog => 88,
2899            Cap::ListSections => 89,
2900        }
2901    }
2902}
2903
2904// ---------------------------------------------------------------------------
2905// Raster images (docs/images.md): the currency shared by the `image` piece, the canvas, and
2906// the decode/metadata/encode duties below.
2907// ---------------------------------------------------------------------------
2908
2909/// A decoded image the toolkit holds, addressed by an id day-core mints.
2910///
2911/// Opaque, because what sits behind it is an `NSImage`, a `UIImage`, a `GdkTexture`, a
2912/// `QPixmap`, a `BitmapImage`, an android `Bitmap` or an `ImageBitmap`, and none of those cross
2913/// the boundary. The id is released through [`Toolkit::release_image`] when the app's handle
2914/// drops, so a backend's side table never outlives the app's interest in it.
2915#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
2916pub struct BitmapId(pub u64);
2917
2918/// An encoded image format: what [`BitmapInfo::format`] reports and [`EncodeSpec::format`] asks
2919/// for. Not every backend encodes every one: ask [`Toolkit::encode_formats`] (the
2920/// [`Cap::ImageEncode`] pair of [`Toolkit::font_families`]/[`Cap::FontList`]) rather than
2921/// assuming.
2922#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
2923pub enum ImageFormat {
2924    #[default]
2925    Png,
2926    Jpeg,
2927    Webp,
2928    Gif,
2929    Bmp,
2930    Tiff,
2931    /// HEIF/HEIC, Apple's camera format; decodable on the Apple backends and Android, and
2932    /// encodable almost nowhere.
2933    Heif,
2934    /// Decoded from bytes whose magic numbers [`ImageFormat::sniff`] does not know. A backend may
2935    /// still decode it: the platform decoders read more formats than Day names.
2936    Unknown,
2937}
2938
2939impl ImageFormat {
2940    /// The IANA media type, which is also the string the ArkUI packer, GDI+ and the browser's
2941    /// `toBlob` take. `Unknown` answers `application/octet-stream`.
2942    pub fn mime(self) -> &'static str {
2943        match self {
2944            ImageFormat::Png => "image/png",
2945            ImageFormat::Jpeg => "image/jpeg",
2946            ImageFormat::Webp => "image/webp",
2947            ImageFormat::Gif => "image/gif",
2948            ImageFormat::Bmp => "image/bmp",
2949            ImageFormat::Tiff => "image/tiff",
2950            ImageFormat::Heif => "image/heif",
2951            ImageFormat::Unknown => "application/octet-stream",
2952        }
2953    }
2954
2955    /// The pixel size the encoded bytes declare, read from the container's own header
2956    /// (docs/images.md).
2957    ///
2958    /// Every backend that decodes natively reports its own dimensions; this exists for the one
2959    /// that cannot. The XAML backend's (`windows-winui`) `BitmapImage` learns its size
2960    /// asynchronously, only once the element has been shown, so a synchronous `image_info` there
2961    /// would have nothing to say.
2962    /// Reading the header instead gives the same answer the decoder would, before any decoding.
2963    ///
2964    /// `None` when the header is absent, truncated, or a container this does not parse.
2965    pub fn dimensions(bytes: &[u8]) -> Option<(u32, u32)> {
2966        let be16 = |i: usize| -> Option<u32> {
2967            Some(u32::from(u16::from_be_bytes([
2968                *bytes.get(i)?,
2969                *bytes.get(i + 1)?,
2970            ])))
2971        };
2972        let le16 = |i: usize| -> Option<u32> {
2973            Some(u32::from(u16::from_le_bytes([
2974                *bytes.get(i)?,
2975                *bytes.get(i + 1)?,
2976            ])))
2977        };
2978        let be32 = |i: usize| -> Option<u32> {
2979            Some(u32::from_be_bytes([
2980                *bytes.get(i)?,
2981                *bytes.get(i + 1)?,
2982                *bytes.get(i + 2)?,
2983                *bytes.get(i + 3)?,
2984            ]))
2985        };
2986        let le32 = |i: usize| -> Option<u32> {
2987            Some(u32::from_le_bytes([
2988                *bytes.get(i)?,
2989                *bytes.get(i + 1)?,
2990                *bytes.get(i + 2)?,
2991                *bytes.get(i + 3)?,
2992            ]))
2993        };
2994        match Self::sniff(bytes)? {
2995            // IHDR is always the first chunk: 8-byte signature, 4-byte length, 4-byte type.
2996            ImageFormat::Png => Some((be32(16)?, be32(20)?)),
2997            // The logical screen descriptor follows the 6-byte version stamp, little-endian.
2998            ImageFormat::Gif => Some((le16(6)?, le16(8)?)),
2999            // The DIB header's width/height are signed; a negative height is a top-down bitmap.
3000            ImageFormat::Bmp => Some((
3001                le32(18)?.cast_signed().unsigned_abs(),
3002                le32(22)?.cast_signed().unsigned_abs(),
3003            )),
3004            // Walk the segment chain to the frame header. Every SOF marker carries the size at
3005            // the same offsets; the arithmetic-coded and progressive ones are SOFs too, which is
3006            // why this matches the whole range rather than SOF0 alone. DNL/DHP (0xC4, 0xC8,
3007            // 0xCC) are not frame headers and are skipped like any other segment.
3008            ImageFormat::Jpeg => {
3009                let mut i = 2usize;
3010                // `<=`, not `<`: a frame header that ends the buffer is still a frame header, and
3011                // the size sits in its last four bytes.
3012                while i + 9 <= bytes.len() {
3013                    if bytes[i] != 0xFF {
3014                        i += 1;
3015                        continue;
3016                    }
3017                    let marker = bytes[i + 1];
3018                    // Padding fill bytes and the standalone markers carry no length.
3019                    if marker == 0xFF || (0xD0..=0xD9).contains(&marker) || marker == 0x01 {
3020                        i += 1;
3021                        continue;
3022                    }
3023                    let is_sof = (0xC0..=0xCF).contains(&marker)
3024                        && marker != 0xC4
3025                        && marker != 0xC8
3026                        && marker != 0xCC;
3027                    if is_sof {
3028                        // [marker][len:2][precision:1][height:2][width:2]
3029                        return Some((be16(i + 7)?, be16(i + 5)?));
3030                    }
3031                    i += 2 + be16(i + 2)? as usize;
3032                }
3033                None
3034            }
3035            // RIFF: a 12-byte header, then a chunk id. VP8X states the size minus one in 24-bit
3036            // little-endian; lossy VP8 hides it in the 14 low bits after the start code; lossless
3037            // VP8L packs width-1 and height-1 into 14 bits each across four bytes.
3038            ImageFormat::Webp => match bytes.get(12..16)? {
3039                b"VP8X" => {
3040                    let w = u32::from(*bytes.get(24)?)
3041                        | u32::from(*bytes.get(25)?) << 8
3042                        | u32::from(*bytes.get(26)?) << 16;
3043                    let h = u32::from(*bytes.get(27)?)
3044                        | u32::from(*bytes.get(28)?) << 8
3045                        | u32::from(*bytes.get(29)?) << 16;
3046                    Some((w + 1, h + 1))
3047                }
3048                b"VP8 " => Some((le16(26)? & 0x3FFF, le16(28)? & 0x3FFF)),
3049                b"VP8L" => {
3050                    let bits = le32(21)?;
3051                    Some(((bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1))
3052                }
3053                _ => None,
3054            },
3055            // TIFF's IFD is a pointer chase and HEIF's is a box tree; neither is worth parsing
3056            // here, because every backend that reads them decodes natively and answers for itself.
3057            ImageFormat::Tiff | ImageFormat::Heif | ImageFormat::Unknown => None,
3058        }
3059    }
3060
3061    /// The format `bytes` begins with, by magic number: enough to fill [`BitmapInfo::format`]
3062    /// on every backend, including the ones whose decoder never says what it decoded.
3063    ///
3064    /// Hand-rolled rather than a crate: it is a dozen byte comparisons against fixed prefixes,
3065    /// and the alternative is an image-decoding dependency in the one crate that must stay
3066    /// dependency-free.
3067    pub fn sniff(bytes: &[u8]) -> Option<ImageFormat> {
3068        let starts = |sig: &[u8]| bytes.len() >= sig.len() && &bytes[..sig.len()] == sig;
3069        if starts(&[0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a]) {
3070            return Some(ImageFormat::Png);
3071        }
3072        if starts(&[0xff, 0xd8, 0xff]) {
3073            return Some(ImageFormat::Jpeg);
3074        }
3075        if starts(b"GIF87a") || starts(b"GIF89a") {
3076            return Some(ImageFormat::Gif);
3077        }
3078        if starts(b"BM") {
3079            return Some(ImageFormat::Bmp);
3080        }
3081        if starts(&[0x49, 0x49, 0x2a, 0x00]) || starts(&[0x4d, 0x4d, 0x00, 0x2a]) {
3082            return Some(ImageFormat::Tiff);
3083        }
3084        // RIFF....WEBP and ....ftypheic/heix/mif1 both carry their tag past a 4-byte prefix.
3085        if starts(b"RIFF") && bytes.len() >= 12 && &bytes[8..12] == b"WEBP" {
3086            return Some(ImageFormat::Webp);
3087        }
3088        if bytes.len() >= 12 && &bytes[4..8] == b"ftyp" {
3089            let brand = &bytes[8..12];
3090            if brand == b"heic" || brand == b"heix" || brand == b"mif1" || brand == b"msf1" {
3091                return Some(ImageFormat::Heif);
3092            }
3093        }
3094        None
3095    }
3096}
3097
3098/// What a decoded image is, in the terms every backend can answer
3099/// ([`Toolkit::image_info`], docs/images.md).
3100///
3101/// `pixels` is the image's own pixel size, not the points it draws at: an asset that stages at
3102/// 2× reports twice its point size and a `scale` of 2, so an app sizing a frame divides. Bytes
3103/// carry no density, so a decoded buffer always answers `scale: 1.0`.
3104#[derive(Clone, Copy, Debug, Default, PartialEq)]
3105pub struct BitmapInfo {
3106    pub pixels: Size,
3107    /// Pixels per point (1.0 for decoded bytes; 2 or 3 for a catalog/drawable asset that staged
3108    /// a density variant).
3109    pub scale: f64,
3110    /// The encoded format it came from, where the backend knows or [`ImageFormat::sniff`] said.
3111    pub format: Option<ImageFormat>,
3112    pub has_alpha: bool,
3113}
3114
3115/// What [`Toolkit::encode_image`] should produce (docs/images.md).
3116///
3117/// A struct rather than three positional arguments, per docs/api-style.md: the call site reads
3118/// `EncodeSpec { format: ImageFormat::Jpeg, quality: Some(0.8), ..Default::default() }`.
3119#[derive(Clone, Copy, Debug, PartialEq)]
3120pub struct EncodeSpec {
3121    pub format: ImageFormat,
3122    /// Lossy quality in `0.0..=1.0`. `None` takes the platform's default; a lossless format
3123    /// ignores it.
3124    pub quality: Option<f64>,
3125    /// Scale the longest side down to fit this box first (aspect preserved). `None` encodes at
3126    /// the image's own size.
3127    pub fit: Option<Size>,
3128}
3129
3130impl Default for EncodeSpec {
3131    fn default() -> Self {
3132        EncodeSpec {
3133            format: ImageFormat::Png,
3134            quality: None,
3135            fit: None,
3136        }
3137    }
3138}
3139
3140/// The metadata an image file carries beyond its pixels ([`Toolkit::image_properties`]).
3141///
3142/// Sparse by construction: every field is what the platform's own reader answered, and a
3143/// backend with no metadata reader at all answers `None` to the whole call rather than an empty
3144/// struct. Probe [`Cap::ImageProperties`] before offering an affordance that depends on it.
3145#[derive(Clone, Debug, Default, PartialEq)]
3146pub struct ImageProperties {
3147    /// The EXIF orientation tag (1–8), where one was recorded.
3148    pub orientation: Option<u16>,
3149    /// Pixels per inch, where the file records a resolution.
3150    pub dpi: Option<f64>,
3151    /// The capture timestamp as the file spells it (no parsing: the formats disagree).
3152    pub created: Option<String>,
3153    /// Everything else the platform reader named, in its own vocabulary. Keys are the
3154    /// platform's, so read them defensively.
3155    pub extra: Vec<(String, String)>,
3156}
3157
3158/// Why an image operation could not answer.
3159#[derive(Clone, Copy, Debug, PartialEq, Eq)]
3160pub enum ImageError {
3161    /// The bytes are not an image this platform decodes.
3162    Decode,
3163    /// The image decoded, but this backend cannot encode the format asked for. `encode_formats`
3164    /// says which it can.
3165    Encode,
3166    /// The backend has no path for this at all (probe [`Cap::ImageDecode`] /
3167    /// [`Cap::ImageEncode`]).
3168    Unsupported,
3169    /// The id named no live image: released already, or never decoded.
3170    Gone,
3171}
3172
3173impl std::fmt::Display for ImageError {
3174    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3175        match self {
3176            ImageError::Decode => write!(f, "the bytes are not a decodable image"),
3177            ImageError::Encode => write!(f, "this backend cannot encode that format"),
3178            ImageError::Unsupported => write!(f, "image support is unavailable on this backend"),
3179            ImageError::Gone => write!(f, "the image was released"),
3180        }
3181    }
3182}
3183
3184impl std::error::Error for ImageError {}
3185
3186// ---------------------------------------------------------------------------
3187// Canvas export (docs/canvas.md "Exporting"): a recorded drawing replayed into an offscreen
3188// bitmap or a PDF by the same painter the on-screen canvas uses.
3189// ---------------------------------------------------------------------------
3190
3191/// The largest side, in pixels, a rendered bitmap may have (docs/canvas.md "Exporting").
3192/// day-core answers [`ExportError::TooLarge`] above it before any toolkit allocates.
3193pub const EXPORT_MAX_SIDE: u32 = 16_384;
3194
3195/// The most pixels a rendered bitmap may hold in total: 64 megapixels, 256 MB at four bytes a
3196/// pixel, which is already more than the tightest per-app heap (Android's) comfortably holds.
3197pub const EXPORT_MAX_PIXELS: u64 = 64 * 1024 * 1024;
3198
3199/// The pixel size a drawing of `size` points renders to at `scale` pixels per point: each side
3200/// rounded up, so a drawing never loses its last partial pixel. Shared by day-core's limit
3201/// check and every backend, so the bitmap a backend allocates is the one day-core approved.
3202pub fn export_pixels(size: Size, scale: f64) -> (u32, u32) {
3203    let side = |v: f64| (v * scale).ceil().clamp(0.0, u32::MAX as f64) as u32;
3204    (side(size.width), side(size.height))
3205}
3206
3207/// One page of a PDF [`Toolkit::render_pdf`] writes: the page size in PDF points (1/72 inch,
3208/// the same unit as canvas points) and the ops to replay onto it, origin top-left.
3209#[derive(Clone, Debug, PartialEq)]
3210pub struct PdfPage {
3211    pub size: Size,
3212    pub ops: Vec<DrawOp>,
3213}
3214
3215/// The document information a PDF carries. A backend whose writer has no metadata API (Android's
3216/// `PdfDocument`) ignores it.
3217#[derive(Clone, Debug, Default, PartialEq)]
3218pub struct PdfInfo {
3219    pub title: Option<String>,
3220    pub author: Option<String>,
3221}
3222
3223/// Why a canvas export could not answer (docs/canvas.md "Exporting").
3224#[derive(Clone, Debug, PartialEq)]
3225pub enum ExportError {
3226    /// This toolkit has no path for the export (probe [`Cap::CanvasBitmap`] /
3227    /// [`Cap::CanvasPdf`]).
3228    Unsupported,
3229    /// The bitmap would exceed [`EXPORT_MAX_SIDE`] or [`EXPORT_MAX_PIXELS`]; checked in
3230    /// day-core before the toolkit runs. The size is the one that was refused, in pixels.
3231    TooLarge { width: u32, height: u32 },
3232    /// A zero, negative or non-finite size or scale, or a PDF with no pages.
3233    Invalid,
3234    /// The platform refused (out of memory, a writer error); the text is the platform's.
3235    Failed(String),
3236}
3237
3238impl std::fmt::Display for ExportError {
3239    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3240        match self {
3241            ExportError::Unsupported => write!(f, "this export is unavailable on this backend"),
3242            ExportError::TooLarge { width, height } => {
3243                write!(
3244                    f,
3245                    "a {width} × {height} pixel bitmap is too large to render"
3246                )
3247            }
3248            ExportError::Invalid => write!(f, "the drawing has no size or the PDF has no pages"),
3249            ExportError::Failed(why) => write!(f, "rendering failed: {why}"),
3250        }
3251    }
3252}
3253
3254impl std::error::Error for ExportError {}
3255
3256/// Where a raster image's pixels come from (docs/images.md).
3257///
3258/// One currency for both halves of the same question: `Named` is the staged asset every
3259/// `image(res::images::…)` has always drawn, `Bytes` is an encoded PNG/JPEG the app already
3260/// holds (a download, a file the user picked, a clipboard paste), and `Decoded` names an image
3261/// the toolkit decoded once so several nodes (and the canvas) share it.
3262#[derive(Clone)]
3263pub enum ImageSource {
3264    /// A staged asset name, resolved through the backend's own pipeline (§18.2).
3265    Named(String),
3266    /// Encoded bytes (PNG/JPEG/…) the app owns, decoded by the platform's own decoder. Shared
3267    /// rather than copied: handing over a new buffer is a refcount bump.
3268    Bytes(std::sync::Arc<Vec<u8>>),
3269    /// An image already decoded through [`Toolkit::decode_image`].
3270    Decoded(BitmapId),
3271}
3272
3273impl Default for ImageSource {
3274    fn default() -> Self {
3275        ImageSource::Named(String::new())
3276    }
3277}
3278
3279/// Bytes compare by identity, not content.
3280///
3281/// This is the equality a binding gates on (§4.2), so it runs on every evaluation, and
3282/// comparing two multi-megabyte buffers byte by byte would cost far more than the redundant
3283/// decode it saves. Handing over a distinct buffer holding the same pixels therefore re-decodes,
3284/// which is the same trade `Arc::ptr_eq` makes wherever else Day carries shared buffers.
3285impl PartialEq for ImageSource {
3286    fn eq(&self, other: &Self) -> bool {
3287        match (self, other) {
3288            (ImageSource::Named(a), ImageSource::Named(b)) => a == b,
3289            (ImageSource::Bytes(a), ImageSource::Bytes(b)) => std::sync::Arc::ptr_eq(a, b),
3290            (ImageSource::Decoded(a), ImageSource::Decoded(b)) => a == b,
3291            _ => false,
3292        }
3293    }
3294}
3295
3296/// Logs the buffer's length, never its contents: a `Debug` that dumped a megabyte of pixels
3297/// into a trace line would make the trace useless and slow.
3298impl std::fmt::Debug for ImageSource {
3299    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3300        match self {
3301            ImageSource::Named(n) => f.debug_tuple("Named").field(n).finish(),
3302            ImageSource::Bytes(b) => f.debug_tuple("Bytes").field(&b.len()).finish(),
3303            ImageSource::Decoded(id) => f.debug_tuple("Decoded").field(&id.0).finish(),
3304        }
3305    }
3306}
3307
3308impl From<BitmapId> for ImageSource {
3309    fn from(id: BitmapId) -> Self {
3310        ImageSource::Decoded(id)
3311    }
3312}
3313
3314/// A staged asset name is a source, so `image(res::images::cover)` keeps compiling unchanged.
3315///
3316/// There is no `From<&str>` here, for the same reason [`resource::ImageName`] has none:
3317/// `image("typo")` must stay a compile error rather than a blank view at runtime (resource.rs).
3318/// A path or URL string is not a source either: read the bytes and hand those over.
3319impl From<resource::ImageName> for ImageSource {
3320    fn from(name: resource::ImageName) -> Self {
3321        ImageSource::Named(name.as_str().to_owned())
3322    }
3323}
3324
3325impl From<resource::VectorName> for ImageSource {
3326    fn from(name: resource::VectorName) -> Self {
3327        ImageSource::Named(name.as_str().to_owned())
3328    }
3329}
3330
3331impl From<std::sync::Arc<Vec<u8>>> for ImageSource {
3332    fn from(bytes: std::sync::Arc<Vec<u8>>) -> Self {
3333        ImageSource::Bytes(bytes)
3334    }
3335}
3336
3337/// An owned string is a name, not bytes: the same conversion [`resource::ImageName`] offers for
3338/// a name computed at runtime, and the reason `image(some_string)` keeps compiling. A `&str`
3339/// still converts nowhere, so `image("typo")` stays a compile error (resource.rs).
3340impl From<String> for ImageSource {
3341    fn from(name: String) -> Self {
3342        ImageSource::Named(name)
3343    }
3344}
3345
3346impl From<Vec<u8>> for ImageSource {
3347    fn from(bytes: Vec<u8>) -> Self {
3348        ImageSource::Bytes(std::sync::Arc::new(bytes))
3349    }
3350}
3351
3352#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
3353pub enum Support {
3354    Native,
3355    Emulated,
3356    /// The default: what an unimplemented capability answers everywhere.
3357    #[default]
3358    Unsupported,
3359}
3360
3361/// What a text field collects (`text_field(..).input_purpose(_)`, docs/textfield.md).
3362///
3363/// One word for everything a platform keys off the kind of text: the on-screen keyboard's
3364/// layout, capitalization and correction, and the credential or contact the system offers to
3365/// fill in. A backend applies the parts its toolkit has: a desktop toolkit with no on-screen
3366/// keyboard still takes the autofill and correction half.
3367///
3368/// Purpose is independent of [`InputTraits::secure`]: a numeric PIN is `Number` and secure.
3369#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
3370pub enum InputPurpose {
3371    /// Free text: the default keyboard, with the platform's own capitalization and correction.
3372    #[default]
3373    Text,
3374    /// A person's name: words capitalized, never corrected.
3375    Name,
3376    /// An email address: the `@` keyboard, never capitalized or corrected.
3377    Email,
3378    /// A web address: the URL keyboard, never capitalized or corrected.
3379    Url,
3380    /// A telephone number: the phone pad.
3381    Phone,
3382    /// A whole number: the digit pad.
3383    Number,
3384    /// A number with a fractional part: the digit pad with a decimal separator.
3385    Decimal,
3386    /// An account name: never capitalized or corrected, and offered to the password manager.
3387    Username,
3388    /// An existing password, offered to the password manager for filling.
3389    Password,
3390    /// A password being chosen, so the password manager offers to make and save one.
3391    NewPassword,
3392    /// A code sent by message or mail, which the keyboard offers as it arrives. The keyboard
3393    /// stays the text one, since a code can carry letters.
3394    OneTimeCode,
3395}
3396
3397/// The on-screen keyboard's action key (`text_field(..).submit_label(_)`, docs/textfield.md).
3398///
3399/// The key always fires the field's `on_submit`; this names what it promises. A toolkit with
3400/// no on-screen keyboard ignores it.
3401#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
3402pub enum SubmitLabel {
3403    /// The platform's own key (Return).
3404    #[default]
3405    Return,
3406    Done,
3407    Go,
3408    Next,
3409    Search,
3410    Send,
3411}
3412
3413/// How a text field takes its text (docs/textfield.md): the whole set travels together through
3414/// [`Toolkit::set_input_traits`], so a backend that has to rebuild the widget for one member
3415/// has every other member in hand to dress the replacement.
3416#[derive(Clone, Debug, Default, PartialEq, Eq)]
3417pub struct InputTraits {
3418    /// Hide the characters (a password field).
3419    pub secure: bool,
3420    /// Show and select the text, take no edits.
3421    pub read_only: bool,
3422    pub purpose: InputPurpose,
3423    pub submit_label: SubmitLabel,
3424    /// The most characters (Unicode scalar values) the field takes; `None` is unbounded.
3425    /// day-pieces holds the bound on every backend. A toolkit applies its native limit as well
3426    /// only where that limit counts the same unit (GTK): one that counts UTF-16 units would
3427    /// refuse characters the bound allows.
3428    pub max_length: Option<u32>,
3429}
3430
3431/// The pointer's shape over a piece (the `.cursor()` decorator, docs/cursor.md).
3432///
3433/// The named variants are the CSS cursor vocabulary: the largest set any toolkit accepts as it
3434/// is (GTK and the DOM take the names verbatim), and every other toolkit's set is a subset of it
3435/// or maps onto it. A backend draws its own shape for each name, or the nearest one it has, and
3436/// answers [`Cap::Cursor`] with how faithful that is. [`Cursor::Native`] reaches a shape only one
3437/// toolkit names; the `day::cursor::<toolkit>` modules carry those as constants, gated on that
3438/// toolkit's feature, and every other backend ignores a name it does not know.
3439///
3440/// A cursor applies to the node and its descendants until a descendant sets its own.
3441/// [`Cursor::Default`] hands the shape back to the platform rather than pinning an arrow, so a
3442/// reactive cursor can release what it took.
3443#[derive(Clone, Debug, PartialEq, Eq, Hash, Default)]
3444pub enum Cursor {
3445    /// The platform default (an arrow), and the value that releases a node's cursor.
3446    #[default]
3447    Default,
3448    /// A pointing hand: links and other tap-to-activate content.
3449    Pointer,
3450    /// An I-beam over editable or selectable text.
3451    Text,
3452    /// An I-beam for vertical text.
3453    VerticalText,
3454    Crosshair,
3455    /// Four-way move.
3456    Move,
3457    /// An open hand: content that can be dragged.
3458    Grab,
3459    /// A closed hand: content being dragged.
3460    Grabbing,
3461    NotAllowed,
3462    /// The app is busy and cannot take input.
3463    Wait,
3464    /// The app is busy but still takes input.
3465    Progress,
3466    Help,
3467    ContextMenu,
3468    /// A drop will copy.
3469    Copy,
3470    /// A drop will link.
3471    Alias,
3472    /// A table cell.
3473    Cell,
3474    ZoomIn,
3475    ZoomOut,
3476    /// No pointer at all.
3477    None,
3478    /// Vertical (north–south) resize.
3479    NsResize,
3480    /// Horizontal (east–west) resize.
3481    EwResize,
3482    /// Diagonal resize, north-east to south-west.
3483    NeswResize,
3484    /// Diagonal resize, north-west to south-east.
3485    NwseResize,
3486    ColResize,
3487    RowResize,
3488    /// A toolkit's own named cursor, resolved by that backend's lookup and ignored by every
3489    /// other. Prefer the `day::cursor::<toolkit>` constants, which are gated on the toolkit.
3490    Native(std::borrow::Cow<'static, str>),
3491}
3492
3493impl Cursor {
3494    /// A toolkit-specific cursor by its native name (see [`Cursor::Native`]).
3495    pub const fn native(name: &'static str) -> Self {
3496        Cursor::Native(std::borrow::Cow::Borrowed(name))
3497    }
3498
3499    /// The CSS keyword for a named cursor, which GTK and the DOM take as it is. A native cursor
3500    /// answers its own name, so a backend keyed on CSS names may still recognize it.
3501    pub fn css_name(&self) -> &str {
3502        match self {
3503            Cursor::Default => "default",
3504            Cursor::Pointer => "pointer",
3505            Cursor::Text => "text",
3506            Cursor::VerticalText => "vertical-text",
3507            Cursor::Crosshair => "crosshair",
3508            Cursor::Move => "move",
3509            Cursor::Grab => "grab",
3510            Cursor::Grabbing => "grabbing",
3511            Cursor::NotAllowed => "not-allowed",
3512            Cursor::Wait => "wait",
3513            Cursor::Progress => "progress",
3514            Cursor::Help => "help",
3515            Cursor::ContextMenu => "context-menu",
3516            Cursor::Copy => "copy",
3517            Cursor::Alias => "alias",
3518            Cursor::Cell => "cell",
3519            Cursor::ZoomIn => "zoom-in",
3520            Cursor::ZoomOut => "zoom-out",
3521            Cursor::None => "none",
3522            Cursor::NsResize => "ns-resize",
3523            Cursor::EwResize => "ew-resize",
3524            Cursor::NeswResize => "nesw-resize",
3525            Cursor::NwseResize => "nwse-resize",
3526            Cursor::ColResize => "col-resize",
3527            Cursor::RowResize => "row-resize",
3528            Cursor::Native(name) => name,
3529        }
3530    }
3531
3532    /// Every named cursor, in declaration order, what a gallery or a test walks.
3533    pub const NAMED: [Cursor; 25] = [
3534        Cursor::Default,
3535        Cursor::Pointer,
3536        Cursor::Text,
3537        Cursor::VerticalText,
3538        Cursor::Crosshair,
3539        Cursor::Move,
3540        Cursor::Grab,
3541        Cursor::Grabbing,
3542        Cursor::NotAllowed,
3543        Cursor::Wait,
3544        Cursor::Progress,
3545        Cursor::Help,
3546        Cursor::ContextMenu,
3547        Cursor::Copy,
3548        Cursor::Alias,
3549        Cursor::Cell,
3550        Cursor::ZoomIn,
3551        Cursor::ZoomOut,
3552        Cursor::None,
3553        Cursor::NsResize,
3554        Cursor::EwResize,
3555        Cursor::NeswResize,
3556        Cursor::NwseResize,
3557        Cursor::ColResize,
3558        Cursor::RowResize,
3559    ];
3560}
3561
3562/// A set of screen edges, for the `defers_system_gestures` modifier (docs/cover.md). Mirrors
3563/// SwiftUI's `Edge.Set`: on iOS these map to `UIRectEdge` for
3564/// `preferredScreenEdgesDeferringSystemGestures`; on Android any non-empty set enters
3565/// swipe-to-reveal immersive mode (the closest platform analogue).
3566#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
3567pub struct Edges(pub u8);
3568
3569impl Edges {
3570    pub const NONE: Edges = Edges(0);
3571    pub const TOP: Edges = Edges(1);
3572    pub const BOTTOM: Edges = Edges(2);
3573    pub const LEADING: Edges = Edges(4);
3574    pub const TRAILING: Edges = Edges(8);
3575    pub const ALL: Edges = Edges(15);
3576
3577    pub fn contains(self, other: Edges) -> bool {
3578        self.0 & other.0 == other.0
3579    }
3580    pub fn union(self, other: Edges) -> Edges {
3581        Edges(self.0 | other.0)
3582    }
3583    pub fn is_empty(self) -> bool {
3584        self.0 == 0
3585    }
3586}
3587
3588impl std::ops::BitOr for Edges {
3589    type Output = Edges;
3590    fn bitor(self, rhs: Edges) -> Edges {
3591        self.union(rhs)
3592    }
3593}
3594
3595/// The timing curve of an animation (§8.4). Native backends map each variant onto their own
3596/// easing (`CAMediaTimingFunction`, `QEasingCurve`, ArkUI `ARKUI_CURVE_*`, spring animators); the
3597/// canvas/self-driven path samples it via [`Curve::fraction`]. `Spring` matches SwiftUI's
3598/// `.spring(response:dampingFraction:)`.
3599#[derive(Clone, Copy, Debug, PartialEq)]
3600pub enum Curve {
3601    Linear,
3602    EaseIn,
3603    EaseOut,
3604    EaseInOut,
3605    /// `response` = approximate settling period (seconds); `damping` = damping ratio (1.0 =
3606    /// critically damped, `<1` = bouncy overshoot).
3607    Spring {
3608        response: f64,
3609        damping: f64,
3610    },
3611}
3612
3613impl Curve {
3614    /// Fraction of the transition complete at `elapsed` seconds (0 at start, reaching 1, or
3615    /// overshooting it for an under-damped spring). Easing curves clamp to `duration`; springs
3616    /// evaluate their analytic unit-step response and use `duration` only as a settle cap. Drives
3617    /// the self-driven/canvas path; native backends interpolate on their own compositor instead.
3618    pub fn fraction(self, elapsed: f64, duration: f64) -> f64 {
3619        match self {
3620            Curve::Spring { response, damping } => spring_step(response, damping, elapsed),
3621            _ => {
3622                let t = if duration <= 0.0 {
3623                    1.0
3624                } else {
3625                    (elapsed / duration).clamp(0.0, 1.0)
3626                };
3627                self.ease(t)
3628            }
3629        }
3630    }
3631
3632    /// Eased progress for normalized `t` in `0.0..=1.0` (springs pass through; use [`Self::fraction`]).
3633    #[inline]
3634    pub fn ease(self, t: f64) -> f64 {
3635        match self {
3636            Curve::Linear | Curve::Spring { .. } => t,
3637            Curve::EaseIn => t * t,
3638            Curve::EaseOut => 1.0 - (1.0 - t) * (1.0 - t),
3639            Curve::EaseInOut => t * t * (3.0 - 2.0 * t), // smoothstep
3640        }
3641    }
3642
3643    /// Whether the transition has settled, so the canvas frame clock can stop ticking it.
3644    pub fn is_settled(self, elapsed: f64, duration: f64) -> bool {
3645        match self {
3646            Curve::Spring { response, damping } => {
3647                let cap = response.max(0.0) * 4.0 + 0.2;
3648                if elapsed >= cap {
3649                    return true;
3650                }
3651                (spring_step(response, damping, elapsed) - 1.0).abs() < 0.001
3652                    && elapsed > response * 0.5
3653            }
3654            _ => elapsed >= duration.max(0.0),
3655        }
3656    }
3657}
3658
3659/// Unit-step response of a second-order spring (`response` = period seconds, `damping` = ratio),
3660/// evaluated at `t` seconds. Under-damped rings and overshoots; critically/over-damped eases in.
3661fn spring_step(response: f64, damping: f64, t: f64) -> f64 {
3662    if response <= 0.0 || t <= 0.0 {
3663        return if t <= 0.0 { 0.0 } else { 1.0 };
3664    }
3665    let omega0 = std::f64::consts::TAU / response;
3666    let zeta = damping.max(0.0);
3667    if zeta < 1.0 {
3668        let omega_d = omega0 * (1.0 - zeta * zeta).sqrt();
3669        let e = (-zeta * omega0 * t).exp();
3670        1.0 - e * ((omega_d * t).cos() + (zeta * omega0 / omega_d) * (omega_d * t).sin())
3671    } else {
3672        let e = (-omega0 * t).exp();
3673        1.0 - e * (1.0 + omega0 * t)
3674    }
3675}
3676
3677/// Animation intent (§8.4). Native-widget backends map it onto their own animator (Core Animation,
3678/// `ViewPropertyAnimator`, XAML Composition, `OH_ArkUI_AnimateTo`, …); the canvas/self-driven path
3679/// samples `curve` via [`Curve::fraction`]. Threaded through `Toolkit::update`/`set_frame`/
3680/// `set_opacity`/`set_transform`.
3681#[derive(Clone, Copy, Debug, PartialEq)]
3682pub struct AnimSpec {
3683    pub duration_ms: u32,
3684    pub delay_ms: u32,
3685    pub curve: Curve,
3686    /// Repeat count beyond the first play (`0` = play once); `u32::MAX` = repeat forever.
3687    pub repeat: u32,
3688    pub autoreverse: bool,
3689}
3690
3691impl Default for AnimSpec {
3692    /// The default feel: a smooth spring (SwiftUI's modern default).
3693    fn default() -> Self {
3694        AnimSpec {
3695            duration_ms: 350,
3696            delay_ms: 0,
3697            curve: Curve::Spring {
3698                response: 0.4,
3699                damping: 0.8,
3700            },
3701            repeat: 0,
3702            autoreverse: false,
3703        }
3704    }
3705}
3706
3707impl AnimSpec {
3708    /// A smooth spring: `response` = settling period (s), `damping` = ratio (1.0 = no bounce, `<1`
3709    /// bouncy). `duration_ms` is a nominal cap for backends that need a duration; spring backends
3710    /// use `response`/`damping` directly.
3711    pub fn spring(response: f64, damping: f64) -> Self {
3712        AnimSpec {
3713            // `response` is the animation's duration: every backend maps a spring to a
3714            // fixed-duration overshoot curve over exactly `duration_ms`, so timing is identical
3715            // across toolkits (a physics spring's settle time would vary per platform).
3716            duration_ms: (response * 1000.0).max(50.0) as u32,
3717            delay_ms: 0,
3718            curve: Curve::Spring { response, damping },
3719            repeat: 0,
3720            autoreverse: false,
3721        }
3722    }
3723    pub fn linear(duration_ms: u32) -> Self {
3724        Self::timed(duration_ms, Curve::Linear)
3725    }
3726    pub fn ease_in(duration_ms: u32) -> Self {
3727        Self::timed(duration_ms, Curve::EaseIn)
3728    }
3729    pub fn ease_out(duration_ms: u32) -> Self {
3730        Self::timed(duration_ms, Curve::EaseOut)
3731    }
3732    pub fn ease_in_out(duration_ms: u32) -> Self {
3733        Self::timed(duration_ms, Curve::EaseInOut)
3734    }
3735    fn timed(duration_ms: u32, curve: Curve) -> Self {
3736        AnimSpec {
3737            duration_ms,
3738            delay_ms: 0,
3739            curve,
3740            repeat: 0,
3741            autoreverse: false,
3742        }
3743    }
3744    /// Delay before the animation starts (builder).
3745    pub fn delay(mut self, ms: u32) -> Self {
3746        self.delay_ms = ms;
3747        self
3748    }
3749    /// Repeat `count` extra times (builder); `autoreverse` ping-pongs each cycle.
3750    pub fn repeat(mut self, count: u32, autoreverse: bool) -> Self {
3751        self.repeat = count;
3752        self.autoreverse = autoreverse;
3753        self
3754    }
3755    /// Repeat forever (builder), e.g. a pulsing indicator.
3756    pub fn repeat_forever(mut self, autoreverse: bool) -> Self {
3757        self.repeat = u32::MAX;
3758        self.autoreverse = autoreverse;
3759        self
3760    }
3761    #[inline]
3762    pub fn duration_secs(&self) -> f64 {
3763        self.duration_ms as f64 / 1000.0
3764    }
3765    #[inline]
3766    pub fn delay_secs(&self) -> f64 {
3767        self.delay_ms as f64 / 1000.0
3768    }
3769}
3770
3771#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
3772pub enum Role {
3773    #[default]
3774    None,
3775    Button,
3776    Toggle,
3777    Slider,
3778    TextInput,
3779    Heading(u8),
3780    Image,
3781    Meter,
3782    Group,
3783    /// A hierarchical tree container (docs/tree.md): `role="tree"`, `AXOutline`.
3784    Tree,
3785    /// One row of a tree: `role="treeitem"`, with level/expanded state where the platform
3786    /// carries them (docs/tree.md).
3787    TreeItem,
3788    /// One tab in a strip of peers (`role="tab"`, `AXTabButton`): the composed document
3789    /// strip's title buttons. Pair it with [`A11yProps::selected`] for the current one.
3790    Tab,
3791    /// The strip holding tabs (`role="tablist"`, `AXTabGroup`).
3792    TabList,
3793}
3794
3795impl Role {
3796    /// The a11y role a built-in piece kind reports natively, the audit's *expectation* when the
3797    /// user hasn't set an explicit `.role()`. Native controls already expose these, so Day records
3798    /// them for `a11y_audit` (§14.2) rather than overriding the widget; only canvas/custom pieces
3799    /// need Day to apply a role. Returns `None` for kinds with no inherent control role.
3800    pub fn for_kind(kind: PieceKind) -> Role {
3801        match kind {
3802            kinds::BUTTON => Role::Button,
3803            kinds::TOGGLE => Role::Toggle,
3804            kinds::SLIDER => Role::Slider,
3805            kinds::TEXT_FIELD => Role::TextInput,
3806            kinds::IMAGE => Role::Image,
3807            kinds::PROGRESS => Role::Meter,
3808            kinds::TREE => Role::Tree,
3809            _ => Role::None,
3810        }
3811    }
3812}
3813
3814#[derive(Clone, Debug, Default, PartialEq)]
3815pub struct A11yProps {
3816    pub label: Option<String>,
3817    pub hint: Option<String>,
3818    pub value: Option<String>,
3819    pub role: Role,
3820    pub identifier: Option<String>,
3821    pub hidden: bool,
3822    pub decorative: bool,
3823    /// Whether the element is the selected one among its peers (a tab, a row): the
3824    /// platform's selected state, read aloud as such. `None` leaves the widget's own answer.
3825    pub selected: Option<bool>,
3826}
3827
3828impl A11yProps {
3829    /// Merge another set of annotations onto this one: any field `other` sets (a `Some`, a
3830    /// non-`None` role, or a `true` flag) overrides ours; unset fields are left intact. Lets a
3831    /// node accumulate its `.a11y()`, `.id()`, and piece defaults into one stored result, so
3832    /// each `set_a11y` re-applies the full picture and `a11y_audit` has the complete expectation.
3833    pub fn merge(&mut self, other: &A11yProps) {
3834        if other.label.is_some() {
3835            self.label = other.label.clone();
3836        }
3837        if other.hint.is_some() {
3838            self.hint = other.hint.clone();
3839        }
3840        if other.value.is_some() {
3841            self.value = other.value.clone();
3842        }
3843        if other.role != Role::None {
3844            self.role = other.role;
3845        }
3846        if other.identifier.is_some() {
3847            self.identifier = other.identifier.clone();
3848        }
3849        self.hidden |= other.hidden;
3850        self.decorative |= other.decorative;
3851        if other.selected.is_some() {
3852            self.selected = other.selected;
3853        }
3854    }
3855
3856    /// The role to *expect* for a node of `kind` carrying these annotations: an explicit
3857    /// `.role()` wins, otherwise the kind's native default (`Role::for_kind`).
3858    pub fn resolved_role(&self, kind: PieceKind) -> Role {
3859        if self.role != Role::None {
3860            self.role
3861        } else {
3862            Role::for_kind(kind)
3863        }
3864    }
3865}
3866
3867/// A widget's actual native state, read back from the platform by `Toolkit::read_native`
3868/// (docs/testing.md): what the widget itself shows and reports, independently of Day's tree,
3869/// so `a11y_audit` and `assert_native` (§14.2) can diff it against Day's expectation.
3870///
3871/// Two groups. The accessibility fields (`role`, `label`, `value`, `identifier`) are read
3872/// together and `found` says whether they were: `found = false` means the backend cannot read
3873/// its accessibility tree, and the audit skips the node. Every other field is read on its own,
3874/// and `None` means "not read": the backend cannot read it, or it does not apply to this kind.
3875/// A reader never reports a field it did not take from the widget, so a `None` is a recorded
3876/// gap rather than a pass.
3877#[derive(Clone, Debug, Default, PartialEq)]
3878pub struct NativeSnapshot {
3879    /// The accessibility fields below were read.
3880    pub found: bool,
3881    /// The native role mapped back to Day's `Role` (best-effort).
3882    pub role: Role,
3883    /// The accessibility label the platform reports.
3884    pub label: Option<String>,
3885    /// The accessibility value the platform reports.
3886    pub value: Option<String>,
3887    /// The automation identifier, which Day sets from `.id()`.
3888    pub identifier: Option<String>,
3889    /// The text the widget displays: a label's string, a button's title, a text field's or
3890    /// text area's contents, without markup or mnemonic markers. `None` for a secure field
3891    /// that masks it.
3892    pub text: Option<String>,
3893    /// A slider's or progress indicator's value, in the range Day gave it.
3894    pub number: Option<f64>,
3895    /// A toggle's state, or a button's selected state (`ButtonProps::selected`).
3896    pub checked: Option<bool>,
3897    /// Whether the widget takes input.
3898    pub enabled: Option<bool>,
3899    /// Whether the widget is shown: not hidden itself, nor by an ancestor.
3900    pub visible: Option<bool>,
3901    /// The widget's frame in points, relative to the window's content area, origin top left.
3902    pub frame: Option<Rect>,
3903}
3904
3905// ---------------------------------------------------------------------------
3906// Canvas display list (§11): full op set lands with M8a; the types are v1.
3907// ---------------------------------------------------------------------------
3908
3909#[derive(Clone, Debug, PartialEq)]
3910pub enum Shape {
3911    Rect(Rect),
3912    RoundedRect(Rect, f64),
3913    Ellipse(Rect),
3914    /// Arc within `rect`'s inscribed ellipse; angles in degrees, 0 = +x axis, clockwise.
3915    Arc {
3916        rect: Rect,
3917        start_deg: f64,
3918        sweep_deg: f64,
3919    },
3920    Line(Point, Point),
3921    Polygon(Vec<Point>),
3922    /// An arbitrary path: curves, several contours, and a fill rule (docs/canvas.md).
3923    ///
3924    /// [`Shape::Polygon`] is the straight-line, single-contour special case, kept because it is
3925    /// what most drawing code wants and it encodes far more compactly.
3926    Path(Path),
3927}
3928
3929impl Shape {
3930    /// A rectangle rounded corner by corner (docs/canvas.md "Rounded corners"), as the simplest
3931    /// shape that draws it: a plain [`Shape::Rect`] when every corner is square, a
3932    /// [`Shape::RoundedRect`] (each toolkit's own rounded rectangle) when the corners agree, and a
3933    /// path ([`rounded_rect_segs`]) otherwise. The radii are [fitted](CornerRadii::fitted) first.
3934    ///
3935    /// ```
3936    /// use day_spec::{CornerRadii, Rect, Shape};
3937    ///
3938    /// // A bar standing on its axis: rounded on top, square where it meets the baseline.
3939    /// let bar = Shape::rounded_rect(Rect::new(0.0, 0.0, 20.0, 80.0), CornerRadii::top(6.0));
3940    /// assert!(matches!(bar, Shape::Path(_)));
3941    /// ```
3942    pub fn rounded_rect(rect: Rect, radii: CornerRadii) -> Shape {
3943        let r = radii.fitted(rect.size);
3944        if r.is_zero() || rect.size.width <= 0.0 || rect.size.height <= 0.0 {
3945            Shape::Rect(rect)
3946        } else if r.is_uniform() {
3947            Shape::RoundedRect(rect, r.top_left)
3948        } else {
3949            Shape::Path(Path {
3950                segs: rounded_rect_segs(rect, r),
3951                rule: FillRule::NonZero,
3952            })
3953        }
3954    }
3955
3956    /// The same shape moved by `(dx, dy)`.
3957    ///
3958    /// What a [`Stamp`] means by "the template translated by one point", and the one definition of
3959    /// it: a backend builds each copy of a batch with this rather than reaching for its own
3960    /// platform transform, so every toolkit stamps to the same coordinates.
3961    pub fn translated(&self, dx: f64, dy: f64) -> Shape {
3962        let r = |r: &Rect| {
3963            Rect::new(
3964                r.origin.x + dx,
3965                r.origin.y + dy,
3966                r.size.width,
3967                r.size.height,
3968            )
3969        };
3970        let p = |p: &Point| Point::new(p.x + dx, p.y + dy);
3971        match self {
3972            Shape::Rect(rect) => Shape::Rect(r(rect)),
3973            Shape::RoundedRect(rect, rad) => Shape::RoundedRect(r(rect), *rad),
3974            Shape::Ellipse(rect) => Shape::Ellipse(r(rect)),
3975            Shape::Arc {
3976                rect,
3977                start_deg,
3978                sweep_deg,
3979            } => Shape::Arc {
3980                rect: r(rect),
3981                start_deg: *start_deg,
3982                sweep_deg: *sweep_deg,
3983            },
3984            Shape::Line(a, b) => Shape::Line(p(a), p(b)),
3985            Shape::Polygon(pts) => Shape::Polygon(pts.iter().map(p).collect()),
3986            Shape::Path(path) => Shape::Path(Path {
3987                segs: path
3988                    .segs
3989                    .iter()
3990                    .map(|seg| match seg {
3991                        PathSeg::Move(a) => PathSeg::Move(p(a)),
3992                        PathSeg::Line(a) => PathSeg::Line(p(a)),
3993                        PathSeg::Quad(c, a) => PathSeg::Quad(p(c), p(a)),
3994                        PathSeg::Cubic(c1, c2, a) => PathSeg::Cubic(p(c1), p(c2), p(a)),
3995                        PathSeg::Close => PathSeg::Close,
3996                    })
3997                    .collect(),
3998                rule: path.rule,
3999            }),
4000        }
4001    }
4002
4003    /// The shape's bounding rectangle: the box gradient [`UnitPoint`]s resolve against.
4004    pub fn bounds(&self) -> Rect {
4005        match self {
4006            Shape::Rect(r) | Shape::RoundedRect(r, _) | Shape::Ellipse(r) => *r,
4007            Shape::Arc { rect, .. } => *rect,
4008            Shape::Line(a, b) => points_bounds(&[*a, *b]),
4009            Shape::Polygon(pts) => points_bounds(pts),
4010            Shape::Path(p) => p.bounds(),
4011        }
4012    }
4013}
4014
4015/// One step of a [`Path`]. Points are absolute, in the canvas's coordinate space.
4016#[derive(Clone, Copy, Debug, PartialEq)]
4017pub enum PathSeg {
4018    /// Start a new contour at this point.
4019    Move(Point),
4020    Line(Point),
4021    /// Quadratic bezier: one control point, then the end point.
4022    Quad(Point, Point),
4023    /// Cubic bezier: two control points, then the end point.
4024    Cubic(Point, Point, Point),
4025    /// Close the current contour back to its `Move`.
4026    Close,
4027}
4028
4029/// Which points count as inside when a path's contours overlap (docs/canvas.md).
4030///
4031/// This matters the moment a shape has a hole: the counter of an "o", a washer, a ring chart. It
4032/// is a property of the fill, so stroking ignores it.
4033#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
4034pub enum FillRule {
4035    /// Direction-sensitive: a hole needs its contour wound the opposite way. Every 2-D API's
4036    /// default, and what a font's glyph outlines assume.
4037    #[default]
4038    NonZero,
4039    /// Parity: any contour inside another cuts a hole regardless of winding. What PDF's `f*`
4040    /// operator and SVG's `fill-rule: evenodd` mean.
4041    EvenOdd,
4042}
4043
4044/// An arbitrary 2-D path: any number of contours, straight or curved, with a fill rule.
4045#[derive(Clone, Debug, PartialEq, Default)]
4046pub struct Path {
4047    pub segs: Vec<PathSeg>,
4048    pub rule: FillRule,
4049}
4050
4051impl Path {
4052    /// A conservative bounding box: the hull of every point including control points, which
4053    /// contains the true curve bounds (a bezier stays inside its control hull). Used only to
4054    /// resolve gradient unit points, where being slightly generous costs nothing and computing
4055    /// exact curve extrema would not.
4056    pub fn bounds(&self) -> Rect {
4057        let mut pts: Vec<Point> = Vec::with_capacity(self.segs.len() * 3);
4058        for seg in &self.segs {
4059            match seg {
4060                PathSeg::Move(p) | PathSeg::Line(p) => pts.push(*p),
4061                PathSeg::Quad(c, p) => pts.extend_from_slice(&[*c, *p]),
4062                PathSeg::Cubic(c1, c2, p) => pts.extend_from_slice(&[*c1, *c2, *p]),
4063                PathSeg::Close => {}
4064            }
4065        }
4066        points_bounds(&pts)
4067    }
4068}
4069
4070/// A radius for each corner of a rectangle, clockwise from the top left (docs/canvas.md "Rounded
4071/// corners"). The shape a bar in a chart wants (rounded at its value end, square against its
4072/// axis), a tab (rounded on top), or a card joined to its neighbor.
4073///
4074/// Radii are in points and never negative. [`CornerRadii::fitted`] shrinks them the way CSS
4075/// does when two radii on one side would overlap, which is what a caller animating a radius or
4076/// drawing a short bar needs to not think about.
4077#[derive(Clone, Copy, Debug, PartialEq, Default)]
4078pub struct CornerRadii {
4079    pub top_left: f64,
4080    pub top_right: f64,
4081    pub bottom_right: f64,
4082    pub bottom_left: f64,
4083}
4084
4085impl CornerRadii {
4086    /// The same radius on every corner: what [`Shape::RoundedRect`] draws.
4087    pub fn uniform(r: f64) -> Self {
4088        CornerRadii {
4089            top_left: r,
4090            top_right: r,
4091            bottom_right: r,
4092            bottom_left: r,
4093        }
4094    }
4095    /// Rounded along the top edge, square along the bottom: a bar standing on its axis.
4096    pub fn top(r: f64) -> Self {
4097        CornerRadii {
4098            top_left: r,
4099            top_right: r,
4100            ..Default::default()
4101        }
4102    }
4103    /// Rounded along the bottom edge: a bar hanging below its axis.
4104    pub fn bottom(r: f64) -> Self {
4105        CornerRadii {
4106            bottom_right: r,
4107            bottom_left: r,
4108            ..Default::default()
4109        }
4110    }
4111    /// Rounded along the left edge: a bar growing leftward from its axis.
4112    pub fn left(r: f64) -> Self {
4113        CornerRadii {
4114            top_left: r,
4115            bottom_left: r,
4116            ..Default::default()
4117        }
4118    }
4119    /// Rounded along the right edge: a bar growing rightward from its axis.
4120    pub fn right(r: f64) -> Self {
4121        CornerRadii {
4122            top_right: r,
4123            bottom_right: r,
4124            ..Default::default()
4125        }
4126    }
4127
4128    /// The four radii, clockwise from the top left.
4129    pub fn to_array(self) -> [f64; 4] {
4130        [
4131            self.top_left,
4132            self.top_right,
4133            self.bottom_right,
4134            self.bottom_left,
4135        ]
4136    }
4137
4138    /// Whether every corner is square.
4139    pub fn is_zero(self) -> bool {
4140        self.to_array().iter().all(|r| *r <= 0.0)
4141    }
4142
4143    /// Whether every corner has the same radius, so the rectangle is a [`Shape::RoundedRect`].
4144    pub fn is_uniform(self) -> bool {
4145        let [a, b, c, d] = self.to_array();
4146        a == b && b == c && c == d
4147    }
4148
4149    /// These radii made to fit a `size` rectangle, the rule CSS uses for `border-radius`: a
4150    /// negative or non-finite radius is square, and when the two radii along any side add up to
4151    /// more than that side, every radius is scaled down by the same factor until none overlap.
4152    /// Scaling all four together keeps the corners in proportion, where clamping each one alone
4153    /// would turn a pill into a lopsided shape.
4154    pub fn fitted(self, size: Size) -> Self {
4155        let clean = |r: f64| if r.is_finite() && r > 0.0 { r } else { 0.0 };
4156        let [tl, tr, br, bl] = self.to_array().map(clean);
4157        let (w, h) = (size.width.max(0.0), size.height.max(0.0));
4158        let factor = [(w, tl + tr), (w, bl + br), (h, tl + bl), (h, tr + br)]
4159            .into_iter()
4160            .filter(|(_, sum)| *sum > 0.0)
4161            .map(|(side, sum)| side / sum)
4162            .fold(1.0f64, f64::min);
4163        CornerRadii {
4164            top_left: tl * factor,
4165            top_right: tr * factor,
4166            bottom_right: br * factor,
4167            bottom_left: bl * factor,
4168        }
4169    }
4170}
4171
4172/// The point `angle_deg` round a circle: degrees, `0` = the +x axis, positive clockwise in device
4173/// space (y down), the convention [`Shape::Arc`] and every arc helper here use.
4174pub fn arc_point(center: Point, radius: f64, angle_deg: f64) -> Point {
4175    let a = angle_deg.to_radians();
4176    Point::new(center.x + radius * a.cos(), center.y + radius * a.sin())
4177}
4178
4179/// A circular arc as cubic beziers: `sweep_deg` of a circle of `radius` about `center`, from
4180/// `start_deg` ([`arc_point`]'s convention). The segments start *from* the arc's first point, which
4181/// the caller reaches itself (a move or a line); nothing for a zero or non-finite radius or sweep.
4182///
4183/// The arc is split into quarter turns at most, where a cubic tracks a circle best: the radial
4184/// error peaks at 2.7 × 10⁻⁴ of the radius, a quarter of a pixel on a circle a thousand points
4185/// across (docs/canvas.md "Paths"). The same beziers on every backend mean the same pixels on
4186/// every backend, which an arc op interpreted by nine rasterizers would not.
4187pub fn arc_cubics(center: Point, radius: f64, start_deg: f64, sweep_deg: f64) -> Vec<PathSeg> {
4188    let (start, sweep) = (start_deg.to_radians(), sweep_deg.to_radians());
4189    if !radius.is_finite() || radius <= 0.0 || !sweep.is_finite() || sweep == 0.0 {
4190        return Vec::new();
4191    }
4192    let at = |a: f64| Point::new(center.x + radius * a.cos(), center.y + radius * a.sin());
4193    let steps = (sweep.abs() / std::f64::consts::FRAC_PI_2).ceil() as usize;
4194    let delta = sweep / steps as f64;
4195    // The exact control-handle length for a circular arc of this sweep. Negative for a negative
4196    // sweep, which is what turns the handles around for a counter-clockwise arc.
4197    let k = 4.0 / 3.0 * (delta / 4.0).tan() * radius;
4198    (0..steps)
4199        .map(|i| {
4200            let a = start + delta * i as f64;
4201            let b = a + delta;
4202            let (p0, p1) = (at(a), at(b));
4203            PathSeg::Cubic(
4204                Point::new(p0.x - k * a.sin(), p0.y + k * a.cos()),
4205                Point::new(p1.x + k * b.sin(), p1.y - k * b.cos()),
4206                p1,
4207            )
4208        })
4209        .collect()
4210}
4211
4212/// The closed contour of a rectangle rounded corner by corner, clockwise from the top left, with
4213/// the radii [fitted](CornerRadii::fitted) first. A square corner is a sharp point, not a
4214/// zero-length curve.
4215pub fn rounded_rect_segs(rect: Rect, radii: CornerRadii) -> Vec<PathSeg> {
4216    let r = radii.fitted(rect.size);
4217    let (x0, y0) = (rect.origin.x, rect.origin.y);
4218    let (x1, y1) = (x0 + rect.size.width, y0 + rect.size.height);
4219    // Each corner: the point where its curve starts, then the quarter turn round its center.
4220    let corners = [
4221        (
4222            Point::new(x0 + r.top_left, y0 + r.top_left),
4223            r.top_left,
4224            180.0,
4225        ),
4226        (
4227            Point::new(x1 - r.top_right, y0 + r.top_right),
4228            r.top_right,
4229            270.0,
4230        ),
4231        (
4232            Point::new(x1 - r.bottom_right, y1 - r.bottom_right),
4233            r.bottom_right,
4234            0.0,
4235        ),
4236        (
4237            Point::new(x0 + r.bottom_left, y1 - r.bottom_left),
4238            r.bottom_left,
4239            90.0,
4240        ),
4241    ];
4242    let mut segs = Vec::with_capacity(14);
4243    for (i, (center, radius, start)) in corners.into_iter().enumerate() {
4244        let first = arc_point(center, radius, start);
4245        segs.push(if i == 0 {
4246            PathSeg::Move(first)
4247        } else {
4248            PathSeg::Line(first)
4249        });
4250        segs.extend(arc_cubics(center, radius, start, 90.0));
4251    }
4252    segs.push(PathSeg::Close);
4253    segs
4254}
4255
4256/// How a stroked line ends (docs/canvas.md). Names match PDF's `J`, SVG's `stroke-linecap`, and
4257/// every native 2-D API.
4258#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
4259pub enum LineCap {
4260    #[default]
4261    Butt,
4262    Round,
4263    Square,
4264}
4265
4266/// How two stroked segments meet (docs/canvas.md). Matches PDF's `j` and SVG's
4267/// `stroke-linejoin`.
4268#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
4269pub enum LineJoin {
4270    #[default]
4271    Miter,
4272    Round,
4273    Bevel,
4274}
4275
4276/// Everything about a stroke except its paint.
4277///
4278/// [`StrokeStyle::width`] and `From<f64>` keep the common "just a width" case a single
4279/// argument, so plain `stroke(shape, color, 2.0)` call sites read the same as they always did.
4280#[derive(Clone, Debug, PartialEq)]
4281pub struct StrokeStyle {
4282    pub width: f64,
4283    pub cap: LineCap,
4284    pub join: LineJoin,
4285    /// Ignored unless `join` is [`LineJoin::Miter`]. The 2-D convention: past this ratio of miter
4286    /// length to line width the join falls back to a bevel.
4287    pub miter_limit: f64,
4288    /// On/off run lengths, repeating. Empty means solid.
4289    pub dash: Vec<f64>,
4290    /// How far into the dash pattern the line starts.
4291    pub dash_phase: f64,
4292}
4293
4294impl Default for StrokeStyle {
4295    fn default() -> Self {
4296        // 10.0 is the miter limit PDF, PostScript, SVG and Cairo all default to.
4297        StrokeStyle {
4298            width: 1.0,
4299            cap: LineCap::Butt,
4300            join: LineJoin::Miter,
4301            miter_limit: 10.0,
4302            dash: Vec::new(),
4303            dash_phase: 0.0,
4304        }
4305    }
4306}
4307
4308impl StrokeStyle {
4309    /// A solid stroke of `width`, everything else default.
4310    pub fn width(width: f64) -> Self {
4311        StrokeStyle {
4312            width,
4313            ..Default::default()
4314        }
4315    }
4316    /// A dashed stroke: `dash` is on/off run lengths, repeating.
4317    pub fn dashed(width: f64, dash: Vec<f64>) -> Self {
4318        StrokeStyle {
4319            width,
4320            dash,
4321            ..Default::default()
4322        }
4323    }
4324    /// Rounded ends and joins, the shape a data line usually wants.
4325    pub fn round(width: f64) -> Self {
4326        StrokeStyle {
4327            width,
4328            cap: LineCap::Round,
4329            join: LineJoin::Round,
4330            ..Default::default()
4331        }
4332    }
4333    /// Is this the plain width-only stroke every pre-existing call site asks for? Backends use
4334    /// it to skip setting dash/cap/join state they would only have to set back.
4335    pub fn is_plain(&self) -> bool {
4336        self.cap == LineCap::Butt
4337            && self.join == LineJoin::Miter
4338            && self.dash.is_empty()
4339            && self.miter_limit == 10.0
4340    }
4341}
4342
4343impl From<f64> for StrokeStyle {
4344    fn from(width: f64) -> Self {
4345        StrokeStyle::width(width)
4346    }
4347}
4348
4349fn points_bounds(pts: &[Point]) -> Rect {
4350    let (mut x0, mut y0, mut x1, mut y1) = (f64::MAX, f64::MAX, f64::MIN, f64::MIN);
4351    for p in pts {
4352        x0 = x0.min(p.x);
4353        y0 = y0.min(p.y);
4354        x1 = x1.max(p.x);
4355        y1 = y1.max(p.y);
4356    }
4357    if pts.is_empty() {
4358        return Rect::ZERO;
4359    }
4360    Rect::new(x0, y0, x1 - x0, y1 - y0)
4361}
4362
4363/// A point in the unit space of a shape's bounding box: (0,0) = top-leading, (1,1) =
4364/// bottom-trailing. Gradient geometry is expressed in unit points so one paint value works for
4365/// any shape size (docs/shapes.md §3.2).
4366#[derive(Clone, Copy, Debug, PartialEq)]
4367pub struct UnitPoint {
4368    pub x: f64,
4369    pub y: f64,
4370}
4371
4372impl UnitPoint {
4373    pub const fn new(x: f64, y: f64) -> Self {
4374        UnitPoint { x, y }
4375    }
4376    pub const TOP: UnitPoint = UnitPoint::new(0.5, 0.0);
4377    pub const BOTTOM: UnitPoint = UnitPoint::new(0.5, 1.0);
4378    pub const LEADING: UnitPoint = UnitPoint::new(0.0, 0.5);
4379    pub const TRAILING: UnitPoint = UnitPoint::new(1.0, 0.5);
4380    pub const TOP_LEADING: UnitPoint = UnitPoint::new(0.0, 0.0);
4381    pub const TOP_TRAILING: UnitPoint = UnitPoint::new(1.0, 0.0);
4382    pub const BOTTOM_LEADING: UnitPoint = UnitPoint::new(0.0, 1.0);
4383    pub const BOTTOM_TRAILING: UnitPoint = UnitPoint::new(1.0, 1.0);
4384    pub const CENTER: UnitPoint = UnitPoint::new(0.5, 0.5);
4385
4386    /// Resolve to an absolute point within `rect`.
4387    pub fn resolve(&self, rect: Rect) -> Point {
4388        Point::new(
4389            rect.origin.x + self.x * rect.size.width,
4390            rect.origin.y + self.y * rect.size.height,
4391        )
4392    }
4393}
4394
4395/// A linear gradient (docs/shapes.md §3.2 / §7): color stops along the line from `start` to
4396/// `end`, both in the unit space of the filled shape's bounding box. Stops are
4397/// `(offset 0..=1, color)`, ascending.
4398#[derive(Clone, Debug, PartialEq)]
4399pub struct LinearGradient {
4400    pub start: UnitPoint,
4401    pub end: UnitPoint,
4402    pub stops: Vec<(f64, Color)>,
4403}
4404
4405impl LinearGradient {
4406    pub fn new(start: UnitPoint, end: UnitPoint, stops: Vec<(f64, Color)>) -> Self {
4407        LinearGradient { start, end, stops }
4408    }
4409    /// Top-to-bottom between two colors: the everyday sky/backdrop case.
4410    pub fn vertical(top: Color, bottom: Color) -> Self {
4411        LinearGradient::new(
4412            UnitPoint::TOP,
4413            UnitPoint::BOTTOM,
4414            vec![(0.0, top), (1.0, bottom)],
4415        )
4416    }
4417    /// Leading-to-trailing between two colors.
4418    pub fn horizontal(leading: Color, trailing: Color) -> Self {
4419        LinearGradient::new(
4420            UnitPoint::LEADING,
4421            UnitPoint::TRAILING,
4422            vec![(0.0, leading), (1.0, trailing)],
4423        )
4424    }
4425}
4426
4427/// A radial gradient (docs/shapes.md §3.2 / §7): color stops from `center` outward. Both the
4428/// center and the radius live in the unit space of the filled shape's bounding box, so the
4429/// gradient stretches into an ellipse when the bounds aren't square (the XAML relative-brush
4430/// behavior; the other backends reproduce it with a local matrix on a circular gradient). A
4431/// `radius` of `0.5` from the default center touches the edge midpoints of the bounds.
4432#[derive(Clone, Debug, PartialEq)]
4433pub struct RadialGradient {
4434    pub center: UnitPoint,
4435    pub radius: f64,
4436    pub stops: Vec<(f64, Color)>,
4437}
4438
4439impl RadialGradient {
4440    pub fn new(center: UnitPoint, radius: f64, stops: Vec<(f64, Color)>) -> Self {
4441        RadialGradient {
4442            center,
4443            radius,
4444            stops,
4445        }
4446    }
4447    /// Centered, edge-touching (radius 0.5) between two colors: the everyday glow case.
4448    pub fn centered(inner: Color, outer: Color) -> Self {
4449        RadialGradient::new(UnitPoint::CENTER, 0.5, vec![(0.0, inner), (1.0, outer)])
4450    }
4451}
4452
4453/// The payload of [`DrawOp::Stamp`]: one shape drawn at every position in `at`.
4454///
4455/// A scatter plot is the case this exists for. Drawn as individual ops, fifty thousand points are
4456/// fifty thousand `DrawOp`s, rebuilt, compared and cloned on every frame that re-records, before
4457/// a backend draws anything. As one `Stamp` they are one op and a flat array of coordinates, and
4458/// a backend can put every copy into one path and hand the rasterizer a single fill.
4459///
4460/// Every copy shares the shape, the size and the paint. Varying any of those means more than one
4461/// stamp: group by what varies, which for a chart is usually the series color.
4462#[derive(Clone, Debug, PartialEq)]
4463pub struct Stamp {
4464    /// The template, authored around the origin: each copy is this shape translated by one point.
4465    /// A 6-point dot is `Shape::Ellipse(Rect::new(-3.0, -3.0, 6.0, 6.0))`.
4466    pub shape: Shape,
4467    /// Where the copies go. Order is the drawing order, so later points paint over earlier ones.
4468    pub at: Vec<Point>,
4469    pub paint: Paint,
4470    /// `None` fills each copy; `Some` strokes it with this style.
4471    pub stroke: Option<StrokeStyle>,
4472}
4473
4474/// A fill source: a solid color, or a linear/radial gradient (docs/shapes.md §3.2; angular and
4475/// semantic tokens are later phases). `From<Color>` keeps every existing `fill(shape, color)`
4476/// call site compiling unchanged.
4477#[derive(Clone, Debug, PartialEq)]
4478pub enum Paint {
4479    Solid(Color),
4480    Linear(LinearGradient),
4481    Radial(RadialGradient),
4482}
4483
4484impl From<Color> for Paint {
4485    fn from(c: Color) -> Self {
4486        Paint::Solid(c)
4487    }
4488}
4489
4490impl From<LinearGradient> for Paint {
4491    fn from(g: LinearGradient) -> Self {
4492        Paint::Linear(g)
4493    }
4494}
4495
4496impl From<RadialGradient> for Paint {
4497    fn from(g: RadialGradient) -> Self {
4498        Paint::Radial(g)
4499    }
4500}
4501
4502/// Where `at` sits vertically. `Top`, `Middle` and `Bottom` are edges of the line box (ascent +
4503/// descent at the font's size, the box [`Toolkit::measure_text`] reports); `Baseline` is the
4504/// typographic baseline itself.
4505#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
4506pub enum TextVAlign {
4507    /// `at` is the top of the line box.
4508    #[default]
4509    Top,
4510    /// `at` is the vertical middle of the line box.
4511    Middle,
4512    /// `at` is the baseline itself: what every native 2-D text call takes, and what a run of labels
4513    /// sharing a line should align on rather than their individual boxes.
4514    Baseline,
4515    /// `at` is the bottom of the line box.
4516    Bottom,
4517}
4518
4519/// How canvas text hangs on its `at` point: one placement per axis (docs/canvas.md "Text").
4520///
4521/// Two axes rather than a list of named positions, because that is the shape of the problem and
4522/// of every native API underneath: `NSAttributedString` drawing, Pango extents,
4523/// `QFontMetricsF`, `Paint.Align`, Canvas2D's `textAlign`/`textBaseline`. The alignment is done
4524/// by the backend, which is both cheaper and more accurate than doing it in app code: it already
4525/// has the laid-out metrics, where an app has to ask for them through
4526/// [`Toolkit::measure_text`] first.
4527///
4528/// [`TextAnchor::LEADING`] and [`TextAnchor::CENTERED`] name the two placements that used to be
4529/// this type's only variants.
4530#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
4531pub struct TextAnchor {
4532    /// The horizontal placement: the same three-way leading/center/trailing a wrapped label's
4533    /// lines take ([`props::TextAlign`]), because it is the same question with the same RTL rule.
4534    /// `Trailing` is what an axis label right-aligned against its axis wants, and the reason the
4535    /// horizontal axis is settable at all: emulating it in app code costs a
4536    /// [`Toolkit::measure_text`] call per label, where the backend already holds the width it is
4537    /// about to draw with.
4538    pub h: props::TextAlign,
4539    pub v: TextVAlign,
4540}
4541
4542impl TextAnchor {
4543    /// The top-leading corner of the line box, the default.
4544    pub const LEADING: TextAnchor = TextAnchor {
4545        h: props::TextAlign::Leading,
4546        v: TextVAlign::Top,
4547    };
4548    /// The center of the line box, both ways.
4549    pub const CENTERED: TextAnchor = TextAnchor {
4550        h: props::TextAlign::Center,
4551        v: TextVAlign::Middle,
4552    };
4553    /// The top-trailing corner of the line box.
4554    pub const TRAILING: TextAnchor = TextAnchor {
4555        h: props::TextAlign::Trailing,
4556        v: TextVAlign::Top,
4557    };
4558
4559    /// Where the text's top-leading corner goes, as an offset from `at`, given the line box this
4560    /// text measures to. The single definition of what an anchor means: every backend that draws
4561    /// in Rust calls this, and the C++/Java/JS shims repeat exactly this arithmetic.
4562    ///
4563    /// `height` is the line box (ascent + descent) and `ascent` the baseline's offset from its
4564    /// top, the two numbers [`TextMetrics`] carries.
4565    pub fn offset(self, width: f64, height: f64, ascent: f64) -> (f64, f64) {
4566        let dx = match self.h {
4567            props::TextAlign::Leading => 0.0,
4568            props::TextAlign::Center => -width / 2.0,
4569            props::TextAlign::Trailing => -width,
4570        };
4571        let dy = match self.v {
4572            TextVAlign::Top => 0.0,
4573            TextVAlign::Middle => -height / 2.0,
4574            TextVAlign::Baseline => -ascent,
4575            TextVAlign::Bottom => -height,
4576        };
4577        (dx, dy)
4578    }
4579
4580    /// The anchor as one number, for the numeric op stream the serializing backends share:
4581    /// `h * 4 + v`, so it still occupies the single slot the two-variant enum did.
4582    pub fn pack(self) -> f64 {
4583        (self.h as u8 * 4 + self.v as u8) as f64
4584    }
4585
4586    /// Inverse of [`TextAnchor::pack`]. An unrecognized code answers the default rather than
4587    /// failing: a stream is only ever written by a matching encoder, and a drawing with text in
4588    /// the wrong corner beats one that panics inside a native draw callback.
4589    pub fn unpack(code: f64) -> TextAnchor {
4590        let c = code.round().clamp(0.0, 11.0) as u8;
4591        let h = match c / 4 {
4592            1 => props::TextAlign::Center,
4593            2 => props::TextAlign::Trailing,
4594            _ => props::TextAlign::Leading,
4595        };
4596        let v = match c % 4 {
4597            1 => TextVAlign::Middle,
4598            2 => TextVAlign::Baseline,
4599            3 => TextVAlign::Bottom,
4600            _ => TextVAlign::Top,
4601        };
4602        TextAnchor { h, v }
4603    }
4604}
4605
4606#[derive(Clone, Debug, PartialEq)]
4607pub enum DrawOp {
4608    Fill(Shape, Paint),
4609    /// Stroke `shape`. The paint may be a gradient, and [`StrokeStyle`] carries width, dash, cap
4610    /// and join; `Draw::stroke` builds the plain width-only case.
4611    Stroke(Shape, Paint, StrokeStyle),
4612    /// One line of text. `size` is absolute canvas points (no accessibility scale: canvas
4613    /// text is a label inside a drawing, docs/canvas.md); `font` picks the family, weight and
4614    /// slant, and its default is the platform's own UI face.
4615    Text {
4616        text: String,
4617        at: Point,
4618        size: f64,
4619        color: Color,
4620        anchor: TextAnchor,
4621        font: CanvasFont,
4622    },
4623    /// Draw one shape at many positions, the batched form of [`DrawOp::Fill`]/[`DrawOp::Stroke`]
4624    /// (docs/canvas.md "Stamping").
4625    ///
4626    /// Boxed because the payload is wider than the largest other op, and a bigger `DrawOp` would
4627    /// cost every op in every drawing, the exact thing this variant exists to stop paying.
4628    Stamp(Box<Stamp>),
4629    /// Draw an image into `rect` (docs/images.md).
4630    ///
4631    /// The source is a [`BitmapId`] and never bytes: a canvas re-records on every tracked read,
4632    /// so carrying a buffer here would hand the backend a megabyte to compare, and re-decode, on
4633    /// every frame. The app decodes once with `day::decode_image` and draws the handle.
4634    ///
4635    /// `opacity` multiplies the image's own alpha. A backend that cannot draw a bitmap at all
4636    /// draws nothing rather than a placeholder rectangle, the same way an unknown op is skipped.
4637    Image {
4638        image: BitmapId,
4639        rect: Rect,
4640        opacity: f64,
4641    },
4642    /// Intersect the clip with `shape`; everything drawn afterwards is confined to it.
4643    ///
4644    /// Scoped by [`DrawOp::Save`]/[`DrawOp::Restore`], which is the only way to widen a clip
4645    /// again; every native 2-D context works this way, so there is no "unclip".
4646    Clip(Shape),
4647    /// Push the current transform + clip (§11, shapes). Backends map to save/restore of the
4648    /// native 2-D context; `Concat` multiplies an affine onto the CTM (shape rotate/scale/offset).
4649    Save,
4650    Restore,
4651    Concat(day_geometry::Affine),
4652}
4653
4654// ---------------------------------------------------------------------------
4655// Built-in piece descriptors: full props (realize) + sparse patches (update).
4656// One binding = one attribute = one patch value: sparseness by construction (§8.1).
4657// ---------------------------------------------------------------------------
4658
4659/// A semantic (logical) text style. Each maps to the platform's native text style where the
4660/// toolkit has one: `UIFont`/`NSFont.preferredFont(forTextStyle:)` on Apple (Dynamic Type), the
4661/// `*TextBlockStyle` resources on XAML. A Day app thus matches the OS's own typography and
4662/// inherits its accessibility text scaling with no extra work. Backends without semantic styles
4663/// (GTK/Qt/Android) approximate with sizes that still track the platform's text-scale /
4664/// font-scale accessibility setting.
4665///
4666/// The set mirrors SwiftUI `Font.TextStyle` (largest → smallest).
4667#[derive(Clone, Copy, Debug, PartialEq, Default)]
4668pub enum Font {
4669    LargeTitle,
4670    Title,
4671    Title2,
4672    Title3,
4673    Headline,
4674    Subheadline,
4675    #[default]
4676    Body,
4677    Callout,
4678    Footnote,
4679    Caption,
4680    Caption2,
4681    /// A custom point size. Backends scale it by the platform's accessibility text-scale (iOS via
4682    /// `UIFontMetrics`, Android via `sp`, GTK via text-scaling-factor) so it stays legible.
4683    System(f64),
4684    /// A bundled custom font by **family name**, at a point size (`Font::Custom("Pacifico",
4685    /// 24.0)`). The family must ship in the project's `fonts/` directory; `day build` stages the
4686    /// file into each platform's native font store and the backend registers it at startup
4687    /// (§18.4). The name is the family name baked into the font file (what Font Book /
4688    /// fontconfig report), not the file name. The size scales with the platform accessibility
4689    /// text-scale exactly like [`Font::System`]; weight/italic apply only where the family ships
4690    /// (or the platform synthesizes) such a face. An unknown family falls back to the system font
4691    /// of the same size, with a warning in the log.
4692    Custom(&'static str, f64),
4693}
4694
4695impl Font {
4696    /// A bundled custom font by **typed family**, at a point size, the checked form of
4697    /// [`Font::Custom`]. Pass a generated `res::fonts::…` constant
4698    /// (`Font::custom(res::fonts::pacifico, 24.0)`), which exists only if the family ships in the
4699    /// project's `fonts/` directory, so the font is guaranteed bundled. For a family name known
4700    /// another way, the untyped [`Font::Custom`] variant is the escape hatch.
4701    pub const fn custom(family: FontFamily, size: f64) -> Font {
4702        Font::Custom(family.as_str(), size)
4703    }
4704}
4705
4706/// Font weight, matching `UIFont.Weight` / SwiftUI `Font.Weight` (lightest → heaviest).
4707/// Ordered by heaviness, so backends can e.g. map `>= Semibold` to a synthesized bold face.
4708#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
4709pub enum FontWeight {
4710    UltraLight,
4711    Thin,
4712    Light,
4713    Regular,
4714    Medium,
4715    Semibold,
4716    Bold,
4717    Heavy,
4718    Black,
4719}
4720
4721impl FontWeight {
4722    /// Every rung, lightest first.
4723    pub const ALL: [FontWeight; 9] = [
4724        FontWeight::UltraLight,
4725        FontWeight::Thin,
4726        FontWeight::Light,
4727        FontWeight::Regular,
4728        FontWeight::Medium,
4729        FontWeight::Semibold,
4730        FontWeight::Bold,
4731        FontWeight::Heavy,
4732        FontWeight::Black,
4733    ];
4734
4735    /// The CSS / OpenType numeric weight (100 … 900), the one number every platform font API
4736    /// also speaks (`Typeface.create(base, weight, italic)`, `QFont::Weight`,
4737    /// `DWRITE_FONT_WEIGHT`, `OH_Drawing_FontWeight`), and what the canvas wire carries.
4738    pub const fn css(self) -> u16 {
4739        match self {
4740            FontWeight::UltraLight => 100,
4741            FontWeight::Thin => 200,
4742            FontWeight::Light => 300,
4743            FontWeight::Regular => 400,
4744            FontWeight::Medium => 500,
4745            FontWeight::Semibold => 600,
4746            FontWeight::Bold => 700,
4747            FontWeight::Heavy => 800,
4748            FontWeight::Black => 900,
4749        }
4750    }
4751
4752    /// The nearest rung to a CSS weight (ties round heavier, like CSS font matching); anything
4753    /// outside 100 … 900 clamps.
4754    pub fn from_css(n: u16) -> FontWeight {
4755        let n = n.clamp(100, 900);
4756        let idx = (usize::from(n) + 50) / 100; // 100 → 1 … 900 → 9
4757        FontWeight::ALL[idx.clamp(1, 9) - 1]
4758    }
4759
4760    /// The English face name for a rung ("Semibold"), for platforms whose enumeration names
4761    /// no face (see [`FontFace::synthesized_name`]).
4762    pub const fn name(self) -> &'static str {
4763        match self {
4764            FontWeight::UltraLight => "Ultra Light",
4765            FontWeight::Thin => "Thin",
4766            FontWeight::Light => "Light",
4767            FontWeight::Regular => "Regular",
4768            FontWeight::Medium => "Medium",
4769            FontWeight::Semibold => "Semibold",
4770            FontWeight::Bold => "Bold",
4771            FontWeight::Heavy => "Heavy",
4772            FontWeight::Black => "Black",
4773        }
4774    }
4775}
4776
4777/// One face a font family ships (docs/fonts.md): its display name ("Bold Italic"), weight and
4778/// slant. What [`FontFamilyInfo::faces`] lists and what a font menu's style picker offers.
4779#[derive(Clone, Debug, PartialEq, Eq)]
4780pub struct FontFace {
4781    pub name: String,
4782    pub weight: FontWeight,
4783    pub italic: bool,
4784}
4785
4786impl FontFace {
4787    /// A display name from weight + slant ("Semibold Italic") for platforms whose enumeration
4788    /// API names no face (Android's `fonts.xml`, the CSS generic families).
4789    pub fn synthesized_name(weight: FontWeight, italic: bool) -> String {
4790        if italic {
4791            format!("{} Italic", weight.name())
4792        } else {
4793            weight.name().to_string()
4794        }
4795    }
4796}
4797
4798/// A platform (or bundled) font family and the faces it can draw canvas text in
4799/// ([`Toolkit::font_families`], docs/fonts.md).
4800#[derive(Clone, Debug, PartialEq, Eq)]
4801pub struct FontFamilyInfo {
4802    pub family: String,
4803    pub faces: Vec<FontFace>,
4804}
4805
4806impl FontFamilyInfo {
4807    /// Whether any face is [`FontWeight::Bold`] or heavier.
4808    pub fn has_bold(&self) -> bool {
4809        self.faces.iter().any(|f| f.weight >= FontWeight::Bold)
4810    }
4811    /// Whether any face is italic.
4812    pub fn has_italic(&self) -> bool {
4813        self.faces.iter().any(|f| f.italic)
4814    }
4815    /// The nearest face: an exact slant match preferred, then the smallest weight distance
4816    /// (ties go heavier, like CSS font matching). `None` only when the family lists no faces.
4817    pub fn face_for(&self, weight: FontWeight, italic: bool) -> Option<&FontFace> {
4818        let want = i32::from(weight.css());
4819        self.faces.iter().min_by_key(|f| {
4820            let slant = i32::from(f.italic != italic);
4821            let dist = (i32::from(f.weight.css()) - want).abs();
4822            // Heavier wins a tie: subtracting the bool sorts the heavier face first.
4823            (slant, dist, i32::from(i32::from(f.weight.css()) < want))
4824        })
4825    }
4826}
4827
4828/// Single-line text measurement in canvas points ([`Toolkit::measure_text`], docs/fonts.md).
4829///
4830/// Two boxes, and the difference between them matters. `width`/`height` is the **line box**: the
4831/// typographic slot the text occupies, the same for every string in a face at a size, and what
4832/// [`TextAnchor`] positions. [`ink`](TextMetrics::ink) is the **ink box**: where the glyphs
4833/// put marks. A line of digits leaves the descender space of its line box empty, so the
4834/// two disagree, and which one is wanted depends on the question: laying text out in a column
4835/// wants the line box, and centering it on a rule or keeping it clear of a mark wants the ink.
4836#[derive(Clone, Copy, Debug, PartialEq)]
4837pub struct TextMetrics {
4838    /// The advance width of the whole string.
4839    pub width: f64,
4840    /// The line box: ascent + descent at this size (plus the line gap where the engine reports
4841    /// one), which is the box [`TextAnchor`] positions.
4842    pub height: f64,
4843    /// The baseline's offset from the top of the line box.
4844    pub ascent: f64,
4845    /// The face's cap height at this size: baseline to the top of a capital.
4846    ///
4847    /// A property of the font, not of this string, reported here because it is what optical
4848    /// centering needs and asking for it separately would be a second measurement. Text made of
4849    /// capitals and digits looks centered on a rule when its cap box straddles it, not its line
4850    /// box: the line box reserves descender room that digits never use, so centering by it sits
4851    /// every label a little low. The cap middle is `ascent - cap_height / 2.0` below the line
4852    /// box's top.
4853    pub cap_height: f64,
4854    /// The ink box, the tight bounds of what is drawn, with its origin relative to the line
4855    /// box's top-leading corner, so `ink.origin` is where the marks start inside the slot.
4856    ///
4857    /// Empty (zero-size) for text that draws nothing, a space included. Where a toolkit cannot
4858    /// report ink it answers the whole line box, which is a superset: an overlap test against it
4859    /// can only be too cautious, never wrong.
4860    pub ink: Rect,
4861}
4862
4863impl TextMetrics {
4864    /// The portable guess `day::measure_text` falls back to when a toolkit cannot measure:
4865    /// 0.6 × size per character, 1.2 × size tall, the baseline at 0.9 × size, caps at 0.7 × size.
4866    /// Its ink is the whole line box, the safe direction to be wrong in (see
4867    /// [`ink`](TextMetrics::ink)).
4868    pub fn approximate(text: &str, size: f64) -> TextMetrics {
4869        let (width, height) = (0.6 * size * text.chars().count() as f64, 1.2 * size);
4870        TextMetrics {
4871            width,
4872            height,
4873            ascent: 0.9 * size,
4874            cap_height: 0.7 * size,
4875            ink: Rect::new(0.0, 0.0, width, height),
4876        }
4877    }
4878
4879    /// Read the eight-slot form the serializing backends (qt, xaml, arkui, web) fill across their
4880    /// C ABI: advance, line height, ascent, cap height, then the ink box relative to the line
4881    /// box's top-leading corner. One definition so four shims cannot drift from each other.
4882    pub fn from_slots(out: &[f64; 8]) -> TextMetrics {
4883        TextMetrics {
4884            width: out[0],
4885            height: out[1],
4886            ascent: out[2],
4887            cap_height: out[3],
4888            ink: Rect::new(out[4], out[5], out[6], out[7]),
4889        }
4890    }
4891
4892    /// The line box's top-leading corner, given a baseline-relative measurement, the shape every
4893    /// backend's metrics come in. `ink_*` are relative to the drawing origin on the baseline
4894    /// (`ink_top` negative above it), the convention Skia, Core Text and Qt all report in.
4895    pub fn from_baseline(
4896        width: f64,
4897        ascent: f64,
4898        descent: f64,
4899        cap_height: f64,
4900        ink: Rect,
4901    ) -> TextMetrics {
4902        TextMetrics {
4903            width,
4904            height: ascent + descent,
4905            ascent,
4906            cap_height,
4907            // Baseline-relative to line-box-relative is one shift by the ascent.
4908            ink: Rect::new(
4909                ink.origin.x,
4910                ink.origin.y + ascent,
4911                ink.size.width,
4912                ink.size.height,
4913            ),
4914        }
4915    }
4916}
4917
4918/// What canvas text is drawn with beyond its size (docs/canvas.md "Text"): a family, a weight and
4919/// a slant. The default is the platform's own UI face, regular, upright, which is what every
4920/// backend drew before the field existed, so a default font encodes to nothing on the wire.
4921#[derive(Clone, Debug, PartialEq, Eq, Default)]
4922pub struct CanvasFont {
4923    /// A platform or bundled family name (as [`Toolkit::font_families`] lists it); `None` =
4924    /// the platform's default UI face.
4925    pub family: Option<String>,
4926    /// `None` = Regular.
4927    pub weight: Option<FontWeight>,
4928    pub italic: bool,
4929}
4930
4931impl CanvasFont {
4932    /// The family name to send over the wire, empty for the default.
4933    pub fn family_str(&self) -> &str {
4934        self.family.as_deref().unwrap_or("")
4935    }
4936    /// The CSS weight to send over the wire, 0 for the default.
4937    pub fn css_weight(&self) -> u16 {
4938        self.weight.map(FontWeight::css).unwrap_or(0)
4939    }
4940}
4941
4942/// Field separator inside one family of the shim-side font list ([`parse_font_list`]).
4943pub const FONT_LIST_FIELD: char = '\u{1f}';
4944/// Family separator of the shim-side font list ([`parse_font_list`]).
4945pub const FONT_LIST_FAMILY: char = '\u{1e}';
4946
4947/// Decode the text a non-Rust font enumerator hands back (the Qt, XAML and ArkUI shims, the
4948/// Android bridge, the web shim all produce this one format): families separated by U+001E;
4949/// inside a family, U+001F-separated fields: the family name, then one (name, CSS weight,
4950/// italic `0`/`1`) triple per face. Tolerant: a malformed face or family is skipped, an empty
4951/// face name is synthesized from its weight and slant, and a family with no faces is kept
4952/// with none (the caller decides what a face-less family means).
4953pub fn parse_font_list(s: &str) -> Vec<FontFamilyInfo> {
4954    let mut out = Vec::new();
4955    for fam in s.split(FONT_LIST_FAMILY) {
4956        let mut fields = fam.split(FONT_LIST_FIELD);
4957        let Some(family) = fields.next().map(str::trim).filter(|f| !f.is_empty()) else {
4958            continue;
4959        };
4960        let rest: Vec<&str> = fields.collect();
4961        let mut faces = Vec::new();
4962        for face in rest.chunks(3) {
4963            let [name, weight, italic] = face else {
4964                continue;
4965            };
4966            let Ok(weight) = weight.trim().parse::<u16>() else {
4967                continue;
4968            };
4969            let weight = FontWeight::from_css(weight);
4970            let italic = matches!(italic.trim(), "1" | "true");
4971            let name = name.trim();
4972            let name = if name.is_empty() {
4973                FontFace::synthesized_name(weight, italic)
4974            } else {
4975                name.to_string()
4976            };
4977            if !faces
4978                .iter()
4979                .any(|f: &FontFace| f.weight == weight && f.italic == italic)
4980            {
4981                faces.push(FontFace {
4982                    name,
4983                    weight,
4984                    italic,
4985                });
4986            }
4987        }
4988        out.push(FontFamilyInfo {
4989            family: family.to_string(),
4990            faces,
4991        });
4992    }
4993    out
4994}
4995
4996/// The full font descriptor a label carries: a semantic (or custom) [`Font`] style plus an optional
4997/// weight override, an italic flag, and the tabular-figures request. Backends resolve this to one
4998/// native font.
4999#[derive(Clone, Copy, Debug, PartialEq)]
5000pub struct FontSpec {
5001    pub style: Font,
5002    pub weight: Option<FontWeight>,
5003    pub italic: bool,
5004    /// Ask for tabular (monospaced) figures: every digit takes the same advance, so a number that
5005    /// changes stops changing width.
5006    ///
5007    /// In a proportional system font `1` is narrower than `8`, so a readout beside a slider
5008    /// wobbles as the value changes even when the digit count is fixed. Every platform ships this
5009    /// as a font feature, so Day asks for the platform's own rather than substituting a monospaced
5010    /// family: the text keeps the system face, and only the digits change metrics.
5011    ///
5012    /// Reserving space (`Decorate::reserving`) and tabular figures solve the two halves of the
5013    /// same problem (reservation stops the box resizing, tabular stops the glyphs shifting inside
5014    /// it), and a numeric readout usually wants both.
5015    ///
5016    /// This rides the existing label realize/patch path rather than adding a Toolkit method, so it
5017    /// is not a backend duty and has no duty-matrix row. Every in-tree backend honors it: AppKit
5018    /// and UIKit re-pick the system face (`monospacedDigitSystemFont`), GTK and Qt and ArkUI set
5019    /// the `tnum` OpenType feature, Android `setFontFeatureSettings`, XAML the `Typography`
5020    /// NumeralAlignment property, and web-dom `font-variant-numeric`. A font with no `tnum` table,
5021    /// or an SDK predating the attribute, renders the stock proportional figures.
5022    pub tabular: bool,
5023    /// Ask for the platform's monospaced face at this style's size, what `` `code` `` in a
5024    /// markdown run needs (docs/text-runs.md).
5025    ///
5026    /// A flag rather than a `Font::Monospace(pt)` variant so the run keeps its semantic style:
5027    /// code inside a `Footnote` paragraph must stay footnote-sized and keep tracking the
5028    /// reader's text-size setting, which a fixed point size would throw away.
5029    ///
5030    /// Like [`Self::tabular`], this rides the label realize/patch path and is not a backend duty:
5031    /// every toolkit has a system monospace face (`monospacedSystemFont`, Pango's `monospace`
5032    /// family, `QFontDatabase::FixedFont`, `Typeface.MONOSPACE`, CSS `monospace`).
5033    pub monospace: bool,
5034    /// Multiply the resolved size. `1.0` is the style's own size, `1.6` a heading against a body
5035    /// paragraph, `0.8` a caption inside one.
5036    ///
5037    /// Relative rather than an absolute point size, so that an editor's font-size control can
5038    /// move this while text a person reads for an hour still tracks the platform's
5039    /// accessibility text-scale. `Font::System(pt)` remains the absolute escape hatch, and it
5040    /// is where an imported document's `\fs28` or `font-size: 14px` lands (docs/texteditor.md):
5041    /// faithful to the file, and no longer responsive to the reader, which is the trade that
5042    /// form makes.
5043    ///
5044    /// Three toolkits take it directly (`GtkTextTag::scale`, Android's `RelativeSizeSpan`, CSS
5045    /// `em`); the rest multiply it into the size they already compute.
5046    pub scale: f64,
5047}
5048
5049impl Default for FontSpec {
5050    fn default() -> Self {
5051        FontSpec {
5052            style: Font::Body,
5053            weight: None,
5054            italic: false,
5055            tabular: false,
5056            monospace: false,
5057            scale: 1.0,
5058        }
5059    }
5060}
5061
5062impl From<Font> for FontSpec {
5063    fn from(style: Font) -> Self {
5064        FontSpec {
5065            style,
5066            ..FontSpec::default()
5067        }
5068    }
5069}
5070
5071impl FontSpec {
5072    /// The plain descriptor for a style: no weight override, no italic, scale 1.0.
5073    pub fn new(style: Font) -> Self {
5074        FontSpec::from(style)
5075    }
5076    /// This descriptor at a different relative size (see [`FontSpec::scale`]).
5077    pub fn scaled(mut self, scale: f64) -> Self {
5078        self.scale = scale;
5079        self
5080    }
5081    /// The point size this descriptor resolves to, given the size the platform assigns its
5082    /// semantic style. The one place `scale` is applied, so every backend's font resolver
5083    /// multiplies the same way.
5084    pub fn resolved_points(&self, style_points: f64) -> f64 {
5085        let base = match self.style {
5086            Font::System(pt) | Font::Custom(_, pt) => pt,
5087            _ => style_points,
5088        };
5089        (base * self.scale).max(1.0)
5090    }
5091}
5092
5093/// One styled span of a label's text (docs/text-runs.md).
5094///
5095/// `range` is a byte range into the label's `text`. Bytes, not chars: every backend that takes a
5096/// structured attributed string wants UTF-16 or byte offsets, `str` slicing is byte-based, and a
5097/// char count would have to be converted at every boundary. Ranges must be non-overlapping and
5098/// ascending; a gap between them is unstyled text, drawn with the label's own font.
5099///
5100/// A run says only what differs. `font` is the whole descriptor rather than a delta because a
5101/// bold run inside a Body paragraph is `FontSpec { style: Body, weight: Some(Bold), .. }`. The
5102/// style has to travel with the weight or the run loses its semantic size.
5103#[derive(Clone, Debug, PartialEq)]
5104pub struct TextRun {
5105    pub range: std::ops::Range<usize>,
5106    pub font: FontSpec,
5107    pub color: Option<Color>,
5108    /// A highlight painted behind the glyphs. Every native text editor carries this attribute
5109    /// (docs/texteditor.md), and search hits and review comments are the two things an app is
5110    /// asked for the moment it has styled text at all.
5111    pub background: Option<Color>,
5112    /// A line under the text.
5113    pub underline: Underline,
5114    /// A line through the text. Separate from `FontSpec` because it is a decoration, not a face:
5115    /// no platform expresses it by picking a different font.
5116    pub strikethrough: bool,
5117    /// Makes this run a link to the given target. Rendering it is [`Cap::TextRuns`]; making it
5118    /// activatable is [`Cap::TextLinks`], which is a smaller set (see the docs).
5119    pub link: Option<String>,
5120}
5121
5122impl Default for TextRun {
5123    fn default() -> Self {
5124        TextRun {
5125            range: 0..0,
5126            font: FontSpec::default(),
5127            color: None,
5128            background: None,
5129            underline: Underline::None,
5130            strikethrough: false,
5131            link: None,
5132        }
5133    }
5134}
5135
5136impl TextRun {
5137    /// A run that only changes the font, the common case for emphasis.
5138    pub fn font(range: std::ops::Range<usize>, font: FontSpec) -> Self {
5139        TextRun {
5140            range,
5141            font,
5142            ..TextRun::default()
5143        }
5144    }
5145
5146    /// This run's attributes without its range: what a selection's style is compared against
5147    /// and what an editor's toolbar toggles (docs/texteditor.md).
5148    pub fn style(&self) -> RunStyle {
5149        RunStyle {
5150            font: self.font,
5151            color: self.color,
5152            background: self.background,
5153            underline: self.underline,
5154            strikethrough: self.strikethrough,
5155            link: self.link.clone(),
5156        }
5157    }
5158
5159    /// A run of `style` over `range`.
5160    pub fn styled(range: std::ops::Range<usize>, style: RunStyle) -> Self {
5161        TextRun {
5162            range,
5163            font: style.font,
5164            color: style.color,
5165            background: style.background,
5166            underline: style.underline,
5167            strikethrough: style.strikethrough,
5168            link: style.link,
5169        }
5170    }
5171}
5172
5173/// Serialize a label's text + runs as markup, for the two backends whose text widgets take a
5174/// string in their own dialect rather than a structured attributed string: GTK (Pango markup)
5175/// and Qt (its HTML subset). Shared so the escaping is written and tested once: a translated
5176/// string containing `&` or `<` corrupts the whole label otherwise, and it will be a translated
5177/// string that finds the bug.
5178///
5179/// `dialect` decides the spelling: Pango wants `<span foreground="#rrggbb"
5180/// font_family="monospace">`, Qt wants `<span style="color:#rrggbb">` with `<code>`. Both accept
5181/// `<b>`, `<i>`, `<u>`, `<s>` and `<a href>`, which is why one function can serve them.
5182///
5183/// `base_points` is the size the label itself resolved to. Only a relative-size run
5184/// ([`FontSpec::scale`]) needs it, and only in the Qt dialect: Pango markup takes a percentage
5185/// directly, while Qt's CSS subset understands `pt` and `px` and ignores `%`.
5186pub fn runs_to_markup(
5187    text: &str,
5188    runs: &[TextRun],
5189    dialect: MarkupDialect,
5190    base_points: f64,
5191) -> String {
5192    let mut out = String::with_capacity(text.len() + runs.len() * 24);
5193    let mut at = 0usize;
5194    for r in runs {
5195        // Skip a run whose range does not address this string, without advancing `at`: dropping
5196        // the run loses styling, but advancing past it would drop the rest of the sentence.
5197        // `runs_are_valid` rejects these upstream; this keeps the failure cheap if one slips by.
5198        let Some(styled) = text.get(r.range.clone()) else {
5199            continue;
5200        };
5201        if r.range.start > at
5202            && let Some(plain) = text.get(at..r.range.start)
5203        {
5204            escape_markup_in(plain, &mut out, dialect);
5205        }
5206        open_run(r, dialect, base_points, &mut out);
5207        escape_markup_in(styled, &mut out, dialect);
5208        close_run(r, dialect, &mut out);
5209        at = r.range.end;
5210    }
5211    if let Some(tail) = text.get(at..) {
5212        escape_markup_in(tail, &mut out, dialect);
5213    }
5214    out
5215}
5216
5217impl Symbol {
5218    /// A 24×24 outline path for this symbol, Day's own drawing of it.
5219    ///
5220    /// The platform's icon comes first on every backend that has one (SF Symbols, the freedesktop
5221    /// icon theme, Fluent's glyph font). This is the fallback for when that lookup finds nothing,
5222    /// which is not an edge case: `view-filter-symbolic` exists on a GNOME desktop and nowhere
5223    /// else, so a GTK or Qt app run off that desktop drew a toolbar item with no icon at all.
5224    /// One table here means the same fallback shape everywhere instead of a gap per platform.
5225    ///
5226    /// `None` for a variant with no drawing yet: `Symbol` is `#[non_exhaustive]`, so a new one
5227    /// degrades to a label rather than failing to compile.
5228    pub fn outline_path(self) -> Option<&'static str> {
5229        use Symbol as S;
5230        // The wildcard is unreachable today (every variant is drawn below) and it is here for
5231        // the next one, which should degrade to a label rather than fail to compile.
5232        #[allow(unreachable_patterns)]
5233        Some(match self {
5234            S::Add => "M11 5h2v6h6v2h-6v6h-2v-6H5v-2h6z",
5235            S::Remove => "M5 11h14v2H5z",
5236            S::Delete => "M9 3h6l1 2h4v2H4V5h4zM6 8h12l-1 13H7z",
5237            S::Edit => {
5238                "M3 17.3V21h3.7L17.8 9.9l-3.7-3.7zM20.7 7a1 1 0 0 0 0-1.4l-2.3-2.3a1 1 0 0 0-1.4 0l-1.8 1.8 3.7 3.7z"
5239            }
5240            S::New => "M13 2H6v20h12V7h-5zm2 .5L19.5 7H15z",
5241            S::Open => "M2 5h7l2 2h11v12H2z",
5242            S::Save => "M3 3h13l5 5v13H3zm5 0h7v6H8zm-1 11h10v7H7z",
5243            S::Print => "M7 3h10v4H7zM4 8h16v8h-3v6H7v-6H4z",
5244            S::Refresh => "M12 4V1L8 5l4 4V6a6 6 0 1 1-6 6H4a8 8 0 1 0 8-8z",
5245            S::Search => {
5246                "M10 4a6 6 0 1 0 3.5 10.9l4.8 4.8 1.4-1.4-4.8-4.8A6 6 0 0 0 10 4m0 2a4 4 0 1 1 0 8 4 4 0 0 1 0-8"
5247            }
5248            S::Share => "M12 3l5 5h-3v7h-4V8H7zM5 17h14v4H5z",
5249            // An eight-tooth gear, round about the center (radius 10 at the teeth, 7.6 at the
5250            // roots) with a 3.2 hole: square in its box, so it sits in a row's 24-point icon
5251            // slot at the same size as its neighbors.
5252            S::Settings => {
5253                "M9.9 4.7L10.2 2.2L13.8 2.2L14.1 4.7A7.6 7.6 0 0 1 15.7 5.4L17.7 3.8L20.2 6.3L18.6 8.3A7.6 7.6 0 0 1 19.3 9.9L21.8 10.2L21.8 13.8L19.3 14.1A7.6 7.6 0 0 1 18.6 15.7L20.2 17.7L17.7 20.2L15.7 18.6A7.6 7.6 0 0 1 14.1 19.3L13.8 21.8L10.2 21.8L9.9 19.3A7.6 7.6 0 0 1 8.3 18.6L6.3 20.2L3.8 17.7L5.4 15.7A7.6 7.6 0 0 1 4.7 14.1L2.2 13.8L2.2 10.2L4.7 9.9A7.6 7.6 0 0 1 5.4 8.3L3.8 6.3L6.3 3.8L8.3 5.4A7.6 7.6 0 0 1 9.9 4.7zM12 8.8a3.2 3.2 0 1 0 0 6.4a3.2 3.2 0 1 0 0-6.4z"
5254            }
5255            S::Info => "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20m-1 5h2v2h-2zm0 4h2v6h-2z",
5256            S::Star => {
5257                "M12 2l2.9 6.3 6.9.8-5.1 4.7 1.4 6.8L12 17.3 5.9 20.6l1.4-6.8L2.2 9.1l6.9-.8z"
5258            }
5259            S::Bookmark => "M6 2h12v20l-6-4-6 4z",
5260            S::Back => "M15.4 5.4L14 4l-8 8 8 8 1.4-1.4L8.8 12z",
5261            S::Forward => "M8.6 5.4L10 4l8 8-8 8-1.4-1.4L15.2 12z",
5262            S::Up => "M5.4 15.4L4 14l8-8 8 8-1.4 1.4L12 8.8z",
5263            S::Down => "M5.4 8.6L4 10l8 8 8-8-1.4-1.4L12 15.2z",
5264            S::Home => "M12 3l9 8h-3v10h-5v-6h-2v6H6V11H3z",
5265            S::Sidebar => "M3 4h18v16H3zm2 2v12h4V6zm6 0v12h8V6z",
5266            S::Filter => "M3 5h18l-7 8v6l-4 2v-8z",
5267            S::Sort => "M8 4v12H4l4 4 4-4H10V4zM14 6h7v2h-7zm0 4h5v2h-5zm0 4h3v2h-3z",
5268            S::More => {
5269                "M6 10a2 2 0 1 0 0 4 2 2 0 0 0 0-4m6 0a2 2 0 1 0 0 4 2 2 0 0 0 0-4m6 0a2 2 0 1 0 0 4 2 2 0 0 0 0-4"
5270            }
5271            S::Play => "M8 5l11 7-11 7z",
5272            S::Pause => "M7 5h3v14H7zm7 0h3v14h-3z",
5273            S::Stop => "M6 6h12v12H6z",
5274            S::Camera => {
5275                "M9 3h6l1.5 2H20a2 2 0 0 1 2 2v12H2V7a2 2 0 0 1 2-2h3.5zm3 6a4.5 4.5 0 1 0 0 9 4.5 4.5 0 0 0 0-9m0 1.6a2.9 2.9 0 1 1 0 5.8 2.9 2.9 0 0 1 0-5.8"
5276            }
5277            S::Code => {
5278                "M9.4 16.6L4.8 12l4.6-4.6L8 6l-6 6 6 6zm5.2 0l4.6-4.6L14.6 7.4 16 6l6 6-6 6z"
5279            }
5280            S::Light => {
5281                "M12 7a5 5 0 1 0 0 10 5 5 0 0 0 0-10M11 1h2v3h-2zm0 19h2v3h-2zM1 11h3v2H1zm19 0h3v2h-3zM3.5 4.9l1.4-1.4 2.1 2.1-1.4 1.4zm13.5 13.5l1.4-1.4 2.1 2.1-1.4 1.4zM4.9 20.5l-1.4-1.4 2.1-2.1 1.4 1.4zm13.5-13.5l-1.4-1.4 2.1-2.1 1.4 1.4z"
5282            }
5283            S::Dark => "M12 3a9 9 0 1 0 9 9 7 7 0 0 1-9-9",
5284            // "Automatic": the half-filled circle every platform uses: the left half solid, the
5285            // right half an outline, which `evenodd` below turns into the ring it should be.
5286            S::Auto => "M12 2a10 10 0 0 0 0 20zM12 4a8 8 0 0 1 0 16v-1.6a6.4 6.4 0 0 0 0-12.8z",
5287            S::ZoomIn => {
5288                "M10 4a6 6 0 1 0 3.5 10.9l4.8 4.8 1.4-1.4-4.8-4.8A6 6 0 0 0 10 4M9 7h2v2h2v2h-2v2H9v-2H7V9h2z"
5289            }
5290            S::ZoomOut => {
5291                "M10 4a6 6 0 1 0 3.5 10.9l4.8 4.8 1.4-1.4-4.8-4.8A6 6 0 0 0 10 4M7 9h6v2H7z"
5292            }
5293            // The ZoomIn lens with a numeral 1 in it, "back to actual size".
5294            S::ZoomReset => {
5295                "M10 4a6 6 0 1 0 3.5 10.9l4.8 4.8 1.4-1.4-4.8-4.8A6 6 0 0 0 10 4M12 13h-1.7V9.3l-1.2.8-.9-1.3 2.4-1.8H12z"
5296            }
5297            S::Undo => "M12 5V2L7 7l5 5V9a5 5 0 1 1 0 10H8v2h4a7 7 0 0 0 0-14z",
5298            S::Redo => "M12 5V2l5 5-5 5V9a5 5 0 1 0 0 10h4v2h-4a7 7 0 0 1 0-14z",
5299            S::Copy => "M8 2h10v14H8zM4 6h2v14h12v2H4z",
5300            S::Cut => {
5301                "M9 4l5.5 9.5-1.2 2L7.8 6zM15 4L9.5 13.5l1.2 2L16.2 6zM6 16a3 3 0 1 0 0 6 3 3 0 0 0 0-6m12 0a3 3 0 1 0 0 6 3 3 0 0 0 0-6"
5302            }
5303            S::Paste => "M9 2h6v2h3v18H6V4h3zm0 2v2h6V4z",
5304            S::Mail => "M2 5h20v14H2zm2 3.2V17h16V8.2l-8 5z",
5305            S::Folder => "M2 5h7l2 2h11v12H2z",
5306            S::Document => "M14 2H6v20h12V6zm.5.8L17.2 6H14.5z",
5307            S::Check => "M9 16.2L4.8 12l-1.4 1.4L9 19 21 7l-1.4-1.4z",
5308            S::Close => {
5309                "M19 6.4L17.6 5 12 10.6 6.4 5 5 6.4 10.6 12 5 17.6 6.4 19 12 13.4 17.6 19 19 17.6 13.4 12z"
5310            }
5311            S::Warning => "M12 2l10 19H2zm-1 7h2v6h-2zm0 8h2v2h-2z",
5312            // Shape outlines, stroked as a 2-unit band (an even-odd ring), so they read as
5313            // outlines at any size rather than filled blocks.
5314            S::Rectangle => "M3 5h18v14H3zm2 2v10h14V7z",
5315            S::Oval => {
5316                "M12 5c5 0 9 3.1 9 7s-4 7-9 7-9-3.1-9-7 4-7 9-7zm0 2c-3.9 0-7 2.2-7 5s3.1 5 7 5 7-2.2 7-5-3.1-5-7-5z"
5317            }
5318            // A circular ring (even-odd: outer disc minus inner) and its filled twin.
5319            S::Circle => "M12 4a8 8 0 1 0 0 16 8 8 0 0 0 0-16zm0 2a6 6 0 1 1 0 12 6 6 0 0 1 0-12z",
5320            S::CircleFilled => "M12 4a8 8 0 1 0 0 16 8 8 0 0 0 0-16z",
5321            S::Line => "M4.7 17.9l13.2-13.2 1.4 1.4L6.1 19.3z",
5322            // Group: a solid square stacked on another (the visible L of the back one);
5323            // Ungroup: the same two squares pulled apart.
5324            S::Group => "M8 4h12v12h-4V8H8zM4 8h12v12H4z",
5325            S::Ungroup => "M3 3h8v8H3zM13 13h8v8h-8z",
5326            // `Symbol` is `#[non_exhaustive]`: a variant added upstream draws nothing here rather
5327            // than failing to compile, and its item keeps its label.
5328            _ => return None,
5329        })
5330    }
5331
5332    /// [`Self::outline_path`] wrapped as a standalone SVG document.
5333    pub fn outline_svg(self) -> Option<String> {
5334        self.outline_path().map(|d| {
5335            format!(
5336                "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\">\
5337                 <path fill-rule=\"evenodd\" d=\"{d}\"/></svg>"
5338            )
5339        })
5340    }
5341}
5342
5343/// Which markup dialect [`runs_to_markup`] should emit.
5344#[derive(Clone, Copy, Debug, PartialEq, Eq)]
5345pub enum MarkupDialect {
5346    /// Pango markup (GTK).
5347    Pango,
5348    /// Qt's rich-text HTML subset.
5349    QtHtml,
5350}
5351
5352/// XML-escape a run of plain text into `out`. `&` first, or the escapes escape each other.
5353///
5354/// Newlines are dialect-specific. Pango lays a literal `\n` out as a line break, but Qt's rich
5355/// text is HTML, where any run of whitespace collapses to one space, which silently ran a
5356/// two-paragraph body together into a single block. `<br>` is what says "break here" in HTML, so
5357/// the same string wraps the same way on both.
5358fn escape_markup_in(s: &str, out: &mut String, dialect: MarkupDialect) {
5359    for c in s.chars() {
5360        match c {
5361            '&' => out.push_str("&amp;"),
5362            '<' => out.push_str("&lt;"),
5363            '>' => out.push_str("&gt;"),
5364            '"' => out.push_str("&quot;"),
5365            '\'' => out.push_str("&#39;"),
5366            '\n' if dialect == MarkupDialect::QtHtml => out.push_str("<br>"),
5367            _ => out.push(c),
5368        }
5369    }
5370}
5371
5372/// [`escape_markup_in`] for the URL slot, where a newline cannot appear.
5373fn escape_markup(s: &str, out: &mut String) {
5374    escape_markup_in(s, out, MarkupDialect::Pango);
5375}
5376
5377fn hex(c: Color) -> String {
5378    format!(
5379        "#{:02x}{:02x}{:02x}",
5380        (c.r.clamp(0.0, 1.0) * 255.0) as u8,
5381        (c.g.clamp(0.0, 1.0) * 255.0) as u8,
5382        (c.b.clamp(0.0, 1.0) * 255.0) as u8
5383    )
5384}
5385
5386/// Does this run need a `<span>` in `dialect`, or do the plain tags cover it?
5387fn needs_span(r: &TextRun, dialect: MarkupDialect) -> bool {
5388    let extras = r.color.is_some() || r.background.is_some() || r.font.scale != 1.0;
5389    match dialect {
5390        // Pango expresses the monospace family as a span attribute; Qt cannot (see below).
5391        MarkupDialect::Pango => extras || r.font.monospace,
5392        MarkupDialect::QtHtml => extras,
5393    }
5394}
5395
5396fn open_run(r: &TextRun, dialect: MarkupDialect, base_points: f64, out: &mut String) {
5397    if let Some(url) = r.link.as_deref() {
5398        out.push_str("<a href=\"");
5399        escape_markup(url, out);
5400        out.push_str("\">");
5401    }
5402    // The span carries the attributes that have no tag: colors, relative size, and (on Pango)
5403    // the monospace family. Bold/italic/strike/underline are tags in both dialects, which keeps
5404    // the attribute string short and the escaping trivial.
5405    let color = r.color.map(hex);
5406    let background = r.background.map(hex);
5407    let mono = r.font.monospace;
5408    if needs_span(r, dialect) {
5409        match dialect {
5410            MarkupDialect::Pango => {
5411                out.push_str("<span");
5412                if let Some(c) = &color {
5413                    out.push_str(&format!(" foreground=\"{c}\""));
5414                }
5415                if let Some(c) = &background {
5416                    out.push_str(&format!(" background=\"{c}\""));
5417                }
5418                if mono {
5419                    out.push_str(" font_family=\"monospace\"");
5420                }
5421                if r.font.scale != 1.0 {
5422                    // Absolute, in Pango units (1/1024 pt), not the `font_scale`/`size="N%"`
5423                    // pair: those are Pango 1.50 attributes, and a Pango that does not know an
5424                    // attribute fails the whole markup parse, which renders the label empty
5425                    // rather than merely unscaled. A point size still tracks the desktop's text
5426                    // scaling, since Pango resolves points through the Xft DPI.
5427                    let pts = r.font.resolved_points(base_points);
5428                    out.push_str(&format!(" size=\"{}\"", (pts * 1024.0).round() as i64));
5429                }
5430                out.push('>');
5431            }
5432            MarkupDialect::QtHtml => {
5433                // Color only. Qt's rich text does not resolve the generic `monospace` family
5434                // from a style attribute (it rendered proportional), so the fixed face comes
5435                // from the `<code>` tag below, which Qt maps to its own fixed font.
5436                out.push_str("<span style=\"");
5437                if let Some(c) = &color {
5438                    out.push_str(&format!("color:{c};"));
5439                }
5440                if let Some(c) = &background {
5441                    out.push_str(&format!("background-color:{c};"));
5442                }
5443                if r.font.scale != 1.0 {
5444                    // Points, not a percentage: Qt's rich-text CSS subset understands `pt` and
5445                    // `px` and silently ignores `%`, which is why a scaled run rendered at the
5446                    // base size here while every other backend scaled it.
5447                    let pt = r.font.resolved_points(base_points);
5448                    out.push_str(&format!("font-size:{pt}pt;"));
5449                }
5450                out.push_str("\">");
5451            }
5452        }
5453    }
5454    if dialect == MarkupDialect::QtHtml && mono {
5455        out.push_str("<code>");
5456    }
5457    if r.font.weight.is_some_and(|w| w >= FontWeight::Semibold) {
5458        out.push_str("<b>");
5459    }
5460    if r.font.italic {
5461        out.push_str("<i>");
5462    }
5463    if r.underline.is_on() {
5464        out.push_str("<u>");
5465    }
5466    if r.strikethrough {
5467        out.push_str("<s>");
5468    }
5469}
5470
5471fn close_run(r: &TextRun, dialect: MarkupDialect, out: &mut String) {
5472    if r.strikethrough {
5473        out.push_str("</s>");
5474    }
5475    if r.underline.is_on() {
5476        out.push_str("</u>");
5477    }
5478    if r.font.italic {
5479        out.push_str("</i>");
5480    }
5481    if r.font.weight.is_some_and(|w| w >= FontWeight::Semibold) {
5482        out.push_str("</b>");
5483    }
5484    if dialect == MarkupDialect::QtHtml && r.font.monospace {
5485        out.push_str("</code>");
5486    }
5487    if needs_span(r, dialect) {
5488        out.push_str("</span>");
5489    }
5490    if r.link.is_some() {
5491        out.push_str("</a>");
5492    }
5493}
5494
5495/// Are these runs well formed for `text`: ascending, non-overlapping, inside the string, and on
5496/// character boundaries?
5497///
5498/// Checked once in the pieces layer rather than in eight backends. A backend handed overlapping
5499/// ranges would produce a different wrong answer per platform, and a range splitting a multi-byte
5500/// character would panic on `str` slicing in some and render mojibake in others.
5501pub fn runs_are_valid(text: &str, runs: &[TextRun]) -> Result<(), String> {
5502    let mut prev_end = 0usize;
5503    for (i, r) in runs.iter().enumerate() {
5504        if r.range.start < prev_end {
5505            return Err(format!(
5506                "run {i} starts at {} but the previous run ends at {prev_end} — runs must be \
5507                 ascending and non-overlapping",
5508                r.range.start
5509            ));
5510        }
5511        if r.range.end > text.len() {
5512            return Err(format!(
5513                "run {i} ends at {} but the text is {} bytes",
5514                r.range.end,
5515                text.len()
5516            ));
5517        }
5518        if r.range.start > r.range.end {
5519            return Err(format!("run {i} has an inverted range {:?}", r.range));
5520        }
5521        if !text.is_char_boundary(r.range.start) || !text.is_char_boundary(r.range.end) {
5522            return Err(format!(
5523                "run {i} range {:?} splits a multi-byte character",
5524                r.range
5525            ));
5526        }
5527        prev_end = r.range.end;
5528    }
5529    Ok(())
5530}
5531
5532pub mod props {
5533    use super::*;
5534
5535    #[derive(Clone, Debug, Default, PartialEq)]
5536    pub struct ContainerProps {
5537        pub background: Option<Color>,
5538        pub corner_radius: f64,
5539        pub clips: bool,
5540        /// Semantic, theme-adaptive surface, mapped by each backend to a native material that
5541        /// follows the platform's light/dark appearance automatically (unlike the fixed-RGBA
5542        /// `background`, which it overrides when set).
5543        pub role: Option<super::SurfaceRole>,
5544    }
5545    /// Reactive surface update for a `background(..)` decorator whose color is a signal/closure:
5546    /// the backend re-applies the fill on the container's native backing view. Corner radius and
5547    /// clipping are fixed at realize (the `corner_radius(r)` decorator takes a plain `f64`).
5548    #[derive(Clone, Debug, PartialEq)]
5549    pub enum ContainerPatch {
5550        Background(Option<Color>),
5551    }
5552
5553    /// Realize props for a `scroll` container: which axis it scrolls. Backends create the matching
5554    /// native scroll view (vertical `UIScrollView`/`ScrollView`, horizontal
5555    /// `HorizontalScrollView`, etc.).
5556    #[derive(Clone, Debug, Default, PartialEq)]
5557    pub struct ScrollProps {
5558        pub horizontal: bool,
5559    }
5560
5561    #[derive(Clone, Debug, Default, PartialEq)]
5562    pub struct LabelProps {
5563        pub text: String,
5564        pub font: FontSpec,
5565        pub color: Option<Color>,
5566        /// What the text means, for the color the platform gives it (docs/text.md).
5567        ///
5568        /// Semantic the way [`crate::Font`] is semantic: an app says "this is secondary text"
5569        /// and each platform answers with its own answer: `secondaryLabelColor` on Apple,
5570        /// `?android:textColorSecondary`, GTK's `dim-label`. That is the only way a de-emphasized
5571        /// label stays correct in both appearances, since a literal grey that reads well on white
5572        /// is wrong on black. An explicit [`Self::color`] still wins; a backend that has no such
5573        /// color renders primary, which is legible and correct, just not dimmed.
5574        pub role: TextRole,
5575        pub wraps: bool,
5576        /// Maximum rendered lines; zero is unlimited. Apple and Android plain labels truncate
5577        /// the last line. Other backends may retain their ordinary wrapping behavior.
5578        pub max_lines: u32,
5579        /// How the label's lines sit within its own width. Only observable on a label that
5580        /// wraps or carries explicit newlines: a single line fills its box, so its alignment is
5581        /// the container's business, not the label's.
5582        ///
5583        /// `Leading` is the default and is what running text wants; `Center` is for the short,
5584        /// centered block a welcome screen or an empty state uses. A backend that cannot set
5585        /// it renders leading-aligned, which is legible and correct, just not centered.
5586        pub align: TextAlign,
5587        /// Styled spans within `text` (docs/text-runs.md). Empty is the overwhelmingly common
5588        /// case and means exactly what a label has always meant: one font, one color. A backend
5589        /// that cannot draw runs ignores this and renders `text` uniformly, which is legible and
5590        /// correct, just unstyled.
5591        pub runs: Vec<crate::TextRun>,
5592    }
5593    /// What a label's text means, for the color the platform gives it (`LabelProps::role`).
5594    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
5595    pub enum TextRole {
5596        /// Ordinary text, in the platform's primary label color.
5597        #[default]
5598        Primary,
5599        /// De-emphasized text: a caption, a hint, the "nothing selected" line an empty detail
5600        /// pane shows. Rendered in the platform's secondary label color.
5601        Secondary,
5602    }
5603
5604    /// How a wrapped label's lines sit within its width (`LabelProps::align`).
5605    ///
5606    /// There is no `Justified` variant because no toolkit in Day's set agrees on how to justify
5607    /// the last line, and the ones that can do it at all need a paragraph style the others have
5608    /// no equivalent for.
5609    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
5610    pub enum TextAlign {
5611        /// Left in a left-to-right locale, right in an RTL one (docs/localization.md).
5612        #[default]
5613        Leading,
5614        Center,
5615        Trailing,
5616    }
5617
5618    #[derive(Clone, Debug, PartialEq)]
5619    pub enum LabelPatch {
5620        Text(String),
5621        Color(Option<Color>),
5622        Font(FontSpec),
5623        /// New text and its runs together. One patch, not two: a run's byte range is only
5624        /// meaningful against a particular string, so applying them separately would leave the
5625        /// widget briefly holding ranges that point into the wrong text.
5626        Runs(String, Vec<crate::TextRun>),
5627    }
5628
5629    /// A button's native styling tier. `Automatic` is the toolkit's stock look; `Bordered`
5630    /// asks for a visually contained button where the stock look is borderless (iOS's plain
5631    /// system button reads as a link); `Prominent` asks for the platform's accent-filled /
5632    /// default-action affordance. Toolkits whose stock buttons are already contained treat
5633    /// `Bordered` as `Automatic`.
5634    // `Eq` is gone with the `Tinted` color: `Color` holds floats. `PartialEq` is what the
5635    // props diff uses, and that is unaffected.
5636    #[derive(Clone, Copy, Debug, Default, PartialEq)]
5637    pub enum ButtonStyleSpec {
5638        #[default]
5639        Automatic,
5640        Bordered,
5641        Prominent,
5642        /// A filled button in an app-chosen color, still drawn by the native control: the
5643        /// platform keeps its own pressed, hover, focus and disabled rendering, its button role,
5644        /// and its keyboard activation. The label color is not carried; each backend picks the
5645        /// readable one for the fill (see [`ButtonStyleSpec::on_tint`]), the same call the
5646        /// platform's own tinted buttons make.
5647        ///
5648        /// A backend with no way to recolor its button ignores this and draws its ordinary
5649        /// button. That is the trade: a plain button everywhere beats a colored
5650        /// rectangle that is no longer a button on the platforms that cannot.
5651        Tinted(Color),
5652        /// A button no wider than its title asks for (a one-glyph "−" or "+" in a stepper,
5653        /// a "×" on a chip) on toolkits whose stock button carries a minimum width and wide
5654        /// insets (Material's 88 dp button turns a two-button stepper into 240 dp). The native
5655        /// control stays: only its minimum width and horizontal padding are reduced. A toolkit
5656        /// whose buttons already hug their title (AppKit, UIKit's plain button, Qt) draws its
5657        /// ordinary button.
5658        Compact,
5659        /// Borderless native action button; compact horizontal insets on Material.
5660        Plain,
5661    }
5662
5663    impl ButtonStyleSpec {
5664        /// The label color to draw on a [`ButtonStyleSpec::Tinted`] fill: whichever of black or
5665        /// white contrasts better against it, by WCAG's contrast ratio.
5666        ///
5667        /// Comparing the two ratios rather than thresholding the luminance is the difference
5668        /// between right and nearly right. A mid amber (`#F0A64C`) has a relative luminance of
5669        /// 0.44; under a "brighter than half" test it reads as dark and takes white text, at a
5670        /// hopeless 2.2:1. Its contrast against black is 9.7:1. The two ratios cross at a
5671        /// luminance of 0.179, not 0.5, and everything between those two numbers is a button
5672        /// nobody can read.
5673        pub fn on_tint(fill: Color) -> Color {
5674            // WCAG relative luminance: sRGB channels linearized, then weighted by the eye's
5675            // sensitivity to each.
5676            let lin = |c: f64| {
5677                let c = c.clamp(0.0, 1.0);
5678                if c <= 0.04045 {
5679                    c / 12.92
5680                } else {
5681                    ((c + 0.055) / 1.055).powf(2.4)
5682                }
5683            };
5684            let l = 0.2126 * lin(fill.r) + 0.7152 * lin(fill.g) + 0.0722 * lin(fill.b);
5685            // Contrast ratio is (lighter + 0.05) / (darker + 0.05); white is 1.0, black is 0.0.
5686            let against_white = 1.05 / (l + 0.05);
5687            let against_black = (l + 0.05) / 0.05;
5688            if against_black >= against_white {
5689                Color::BLACK
5690            } else {
5691                Color::WHITE
5692            }
5693        }
5694    }
5695
5696    #[derive(Clone, Debug, Default, PartialEq)]
5697    /// The visible content and accessible title of a button with an icon.
5698    pub struct ButtonContent {
5699        /// Also serves as the accessible name when only the icon is visible.
5700        pub title: String,
5701        pub icon: Option<Icon>,
5702        pub icon_only: bool,
5703    }
5704    #[derive(Clone, Debug, Default, PartialEq)]
5705    pub struct ButtonProps {
5706        pub title: String,
5707        pub icon: Option<Icon>,
5708        pub icon_only: bool,
5709        pub enabled: bool,
5710        pub style: ButtonStyleSpec,
5711        /// The button stands for the current choice among its siblings (a document tab, a
5712        /// view switcher): the platform's own checked or selected rendering, which keeps the
5713        /// button enabled, focusable and activatable, and tells assistive tech it is selected.
5714        /// A click never toggles it natively; only the app's next patch changes it.
5715        pub selected: bool,
5716    }
5717    #[derive(Clone, Debug, PartialEq)]
5718    pub enum ButtonPatch {
5719        Title(String),
5720        /// Update an icon button's label and icon together. Plain buttons still use `Title`.
5721        Content(ButtonContent),
5722        Enabled(bool),
5723        /// The selected state (see [`ButtonProps::selected`]).
5724        Selected(bool),
5725        /// A live style change: what a reactive `.tint(…)` sends, so a button can recolor with
5726        /// app state without being torn down and realized again.
5727        Style(ButtonStyleSpec),
5728    }
5729
5730    #[derive(Clone, Debug, Default, PartialEq)]
5731    pub struct ToggleProps {
5732        pub on: bool,
5733        pub enabled: bool,
5734    }
5735    #[derive(Clone, Debug, PartialEq)]
5736    pub enum TogglePatch {
5737        On(bool),
5738        Enabled(bool),
5739    }
5740
5741    #[derive(Clone, Debug, PartialEq)]
5742    pub struct SliderProps {
5743        pub value: f64,
5744        pub min: f64,
5745        pub max: f64,
5746        pub step: Option<f64>,
5747        pub enabled: bool,
5748    }
5749    impl Default for SliderProps {
5750        fn default() -> Self {
5751            SliderProps {
5752                value: 0.0,
5753                min: 0.0,
5754                max: 1.0,
5755                step: None,
5756                enabled: true,
5757            }
5758        }
5759    }
5760    #[derive(Clone, Debug, PartialEq)]
5761    pub enum SliderPatch {
5762        Value(f64),
5763        Enabled(bool),
5764    }
5765
5766    /// SwiftUI's `pickerStyle` analogue (kinds::PICKER). Each maps to a distinct native
5767    /// control per toolkit (docs/picker.md).
5768    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
5769    pub enum PickerStyle {
5770        /// A dropdown/pop-up menu (NSPopUpButton / GtkDropDown / QComboBox / UIButton+UIMenu / Spinner).
5771        #[default]
5772        Menu,
5773        /// A horizontal segmented control (NSSegmentedControl / UISegmentedControl / linked toggles / …).
5774        Segmented,
5775        /// A vertical radio-button group laid out inline (NSButton radios / GtkCheckButton group / …).
5776        Inline,
5777    }
5778
5779    /// Full picker props (realize). `style` is set once at build; `options`, `selected` and
5780    /// `enabled` patch (via [`PickerPatch`]).
5781    #[derive(Clone, Debug, PartialEq)]
5782    pub struct PickerProps {
5783        /// Decorative boundaries before option indexes (not selectable options). Native menu
5784        /// grouping on AppKit/UIKit; ignored by other backends and non-menu styles.
5785        pub separators_before: Vec<usize>,
5786        pub options: Vec<String>,
5787        pub selected: usize,
5788        pub style: PickerStyle,
5789        /// Whether the picker takes input. Default `true`.
5790        pub enabled: bool,
5791    }
5792    impl Default for PickerProps {
5793        fn default() -> Self {
5794            PickerProps {
5795                separators_before: Vec::new(),
5796                options: Vec::new(),
5797                selected: 0,
5798                style: PickerStyle::default(),
5799                enabled: true,
5800            }
5801        }
5802    }
5803
5804    #[derive(Clone, Debug, PartialEq)]
5805    pub enum PickerPatch {
5806        Selected(usize),
5807        /// New option labels, for a picker whose choices come from data (a document list, a
5808        /// live count). The backend rebuilds its items and keeps the selected index where it
5809        /// still exists, clamping to the last option otherwise; a fresh
5810        /// [`PickerPatch::Selected`] follows whenever the app's own binding disagrees.
5811        Options(Vec<String>),
5812        /// Enable or disable the whole control, every style alike.
5813        Enabled(bool),
5814    }
5815
5816    /// Full text-area props (realize, kinds::TEXT_AREA; docs/textarea.md). `text` seeds the
5817    /// editor; `min_lines`/`max_lines` bound the auto-growing height in text lines
5818    /// (`max_lines == 0` = unbounded). `editable`/`selectable`/`spellcheck` control the native
5819    /// editor attributes (all default `true`); a backend that can't honor one answers
5820    /// `Cap::Text{Editable,Selectable,SpellCheck}` = `Unsupported`. `text` and the three attributes
5821    /// change after build (via [`TextAreaPatch`]); the rest are build-only.
5822    #[derive(Clone, Debug, PartialEq)]
5823    pub struct TextAreaProps {
5824        pub text: String,
5825        pub placeholder: String,
5826        pub min_lines: u32,
5827        pub max_lines: u32,
5828        /// Whether the user can edit the text (`false` = read-only). Default `true`.
5829        pub editable: bool,
5830        /// Whether the text can be selected (and copied). Default `true`.
5831        pub selectable: bool,
5832        /// Whether spell-check / autocorrect highlighting is on. Default `true`.
5833        pub spellcheck: bool,
5834        /// Plain Enter emits `Event::Submitted` instead of inserting a newline (Shift+Enter
5835        /// still inserts one where the platform can distinguish). Chat composers. Default
5836        /// `false`.
5837        pub submit_on_enter: bool,
5838    }
5839
5840    impl Default for TextAreaProps {
5841        fn default() -> Self {
5842            TextAreaProps {
5843                text: String::new(),
5844                placeholder: String::new(),
5845                min_lines: 1,
5846                max_lines: 0,
5847                editable: true,
5848                selectable: true,
5849                spellcheck: true,
5850                submit_on_enter: false,
5851            }
5852        }
5853    }
5854
5855    /// Imperative text-area updates: replace the text (programmatic sync), or flip one of the
5856    /// live attributes.
5857    #[derive(Clone, Debug, PartialEq)]
5858    pub enum TextAreaPatch {
5859        SetText(String),
5860        SetEditable(bool),
5861        SetSelectable(bool),
5862        SetSpellCheck(bool),
5863    }
5864
5865    #[derive(Clone, Debug, Default, PartialEq)]
5866    pub struct TextFieldProps {
5867        pub text: String,
5868        pub placeholder: String,
5869        pub enabled: bool,
5870    }
5871    #[derive(Clone, Debug, PartialEq)]
5872    pub enum TextFieldPatch {
5873        /// Origin-tagged write (§4.4): `from_native` suppresses the echo back into the widget.
5874        Text {
5875            text: String,
5876            from_native: bool,
5877        },
5878        Placeholder(String),
5879        Enabled(bool),
5880    }
5881
5882    /// How an image is scaled to fill its frame (§18.3). Maps to each toolkit's native scaling.
5883    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
5884    pub enum ContentMode {
5885        /// Scale to fit entirely inside the frame, preserving aspect ratio (letterboxed). The
5886        /// default: an image never stretches unless asked. SwiftUI's `.scaledToFit`.
5887        #[default]
5888        Fit,
5889        /// Scale to fill the frame, preserving aspect ratio and cropping the overflow. SwiftUI's
5890        /// `.scaledToFill`.
5891        Fill,
5892        /// Stretch to fill the frame exactly, ignoring aspect ratio.
5893        Stretch,
5894    }
5895
5896    #[derive(Clone, Debug, Default, PartialEq)]
5897    pub struct ImageProps {
5898        /// Which pixels to draw: a staged asset name, encoded bytes, or an already-decoded
5899        /// image ([`ImageSource`], docs/images.md). A name resolves through the backend's own
5900        /// pipeline (§18.2); bytes and decoded ids need [`Cap::ImageDecode`], and a backend
5901        /// without it draws nothing rather than guessing.
5902        pub source: ImageSource,
5903        pub decorative: bool,
5904        /// How the image scales within its frame (default [`ContentMode::Fit`], no stretching).
5905        pub content_mode: ContentMode,
5906        /// Optional width:height ratio the view is constrained to (e.g. `16.0/9.0`). `None` lets the
5907        /// image take its allocated frame.
5908        pub aspect_ratio: Option<f64>,
5909        /// Monochrome tint for a template/vector glyph (docs/vectors.md): backends that can,
5910        /// recolor natively (template rendering on Apple, drawable tint on Android, pixel
5911        /// recolor on GTK); backends that can't yet ignore it and draw the source colors.
5912        /// `None` (the default, and every raster `image(…)`) means "as authored".
5913        pub tint: Option<Color>,
5914        /// A monochrome template glyph (docs/vectors.md "Template"): with no `tint`, it draws
5915        /// in the foreground of the surface it sits on — the theme's label color on the
5916        /// desktops, the cell's tint on UIKit, `currentColor` on the web — and follows a
5917        /// theme switch. What a sidebar row's untinted icon is: a tinted glyph recolors the
5918        /// same way with or without this, and `false` (the default) draws an untinted glyph as
5919        /// authored. [`ImagePatch::Tint`]`(None)` on a template returns to that foreground,
5920        /// not to the authored colors.
5921        pub template: bool,
5922    }
5923
5924    /// A list row's standard content (`kinds::LIST_ITEM`, docs/list.md "List items"). Empty
5925    /// text means the part is absent.
5926    #[derive(Clone, Debug, Default, PartialEq)]
5927    pub struct ListItemProps {
5928        pub title: String,
5929        /// A second line under the title, in the platform's secondary style.
5930        pub subtitle: String,
5931        /// Trailing text (a count, a value), in the platform's secondary style.
5932        pub detail: String,
5933        /// The leading glyph: a symbol or a bundled image.
5934        pub icon: Option<crate::Icon>,
5935        /// The glyph's color; `None` takes the platform's own (template glyphs follow the
5936        /// foreground, the tint color on UIKit).
5937        pub icon_tint: Option<Color>,
5938        /// A trailing check mark: the platform's selected-option mark (UIKit's checkmark
5939        /// accessory, a Material check icon), announced as checked.
5940        pub checked: bool,
5941    }
5942
5943    /// A live change to a realized list item; every part changes in place.
5944    #[derive(Clone, Debug, PartialEq)]
5945    pub enum ListItemPatch {
5946        Title(String),
5947        Subtitle(String),
5948        Detail(String),
5949        Icon(Option<crate::Icon>),
5950        IconTint(Option<Color>),
5951        Checked(bool),
5952    }
5953
5954    /// A live change to a realized image or vector glyph.
5955    ///
5956    /// `content_mode` and the rest still describe which art this is and how it fills its frame,
5957    /// which a rebuild expresses better than a patch. Two things do want to follow a signal: the
5958    /// tint (a glyph that recolors with the selection or the theme should repaint, not be torn
5959    /// down and realized again, docs/vectors.md "Tint") and the source, now that it can be a
5960    /// buffer the app swaps (a download landing, a new photo picked, docs/images.md). Replacing
5961    /// the pixels of a view that is already on screen is what a patch is for; realizing a second
5962    /// view would flash.
5963    #[derive(Clone, Debug, PartialEq)]
5964    pub enum ImagePatch {
5965        /// Recolor the glyph, or `None` to draw the authored colors again.
5966        Tint(Option<Color>),
5967        /// Draw different pixels in the same view. A backend that cannot decode the new source
5968        /// (bytes where [`Cap::ImageDecode`] is `Unsupported`) leaves what it was drawing.
5969        Source(ImageSource),
5970    }
5971
5972    #[derive(Clone, Debug, Default, PartialEq)]
5973    pub struct CanvasProps {
5974        pub ops: Vec<DrawOp>,
5975    }
5976
5977    /// Progress indicator. `value` is the completed fraction in `0.0..=1.0`; `None` means
5978    /// indeterminate (an animated spinner / busy bar, no known extent). Backends map this to
5979    /// their native determinate/indeterminate widgets (docs/progress.md).
5980    #[derive(Clone, Debug, PartialEq)]
5981    pub struct ProgressProps {
5982        pub value: Option<f64>,
5983        /// Whether an indeterminate indicator animates; ignored for a determinate bar.
5984        pub animating: bool,
5985        /// The platform's large indicator size.
5986        pub large: bool,
5987    }
5988    impl Default for ProgressProps {
5989        fn default() -> Self {
5990            Self {
5991                value: None,
5992                animating: true,
5993                large: false,
5994            }
5995        }
5996    }
5997    #[derive(Clone, Debug, PartialEq)]
5998    pub enum ProgressPatch {
5999        Animating(bool),
6000        /// New completed fraction, or `None` to switch to indeterminate.
6001        Value(Option<f64>),
6002    }
6003
6004    /// A rule between neighbors (`divider()`): a hairline across the width it is offered, or,
6005    /// with `vertical`, down the height it is offered (`divider().vertical()`, between a
6006    /// row's panes). A toolkit measures both the same way, as a horizontal rule, because the
6007    /// pieces layer swaps the axes of a vertical one's proposal and answer; realization is
6008    /// where the orientation matters, for the few widgets that draw a horizontal line
6009    /// regardless of their frame.
6010    #[derive(Clone, Debug, Default, PartialEq)]
6011    pub struct DividerProps {
6012        pub vertical: bool,
6013    }
6014
6015    /// How a navigation host lays its panes out (docs/navigation.md).
6016    ///
6017    /// This is the resolved presentation, what the toolkit must draw right now. The app asks for
6018    /// one through `Nav::presentation`, where leaving it unset means "automatic": the pieces
6019    /// layer resolves it from the window's [`SizeClass`] and the toolkit's `Cap::NavSplit`, and
6020    /// re-resolves it whenever the class changes. There is no `Auto` variant here because a
6021    /// backend can only ever draw a concrete one, so the undecided state stays on the app's side
6022    /// of the boundary where it can still be decided.
6023    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
6024    pub enum NavPresentation {
6025        /// Sidebar beside detail, both visible (`NSSplitViewController`, nested `GtkPaned`s,
6026        /// a `NavigationView`). The sidebar pane gets its own container.
6027        Split,
6028        /// One page at a time, back-navigable. The sidebar pane becomes the stack's root.
6029        #[default]
6030        Stack,
6031        /// The rows drawn as a tab bar, one page's content beside it, no back stack: what a
6032        /// phone-shaped window wants from a one-of-N surface (`UITabBarController`, a Material
6033        /// `NavigationBarView`, `NavigationView.PaneDisplayMode = Top`). The `Pane::Sidebar` page
6034        /// is not drawn at all: its rows are the chrome.
6035        Tabs,
6036        /// The rows drawn as a narrow icon strip beside the content, the `Medium`-width answer
6037        /// between [`Self::Tabs`] and [`Self::Split`] (a Material `NavigationRailView`,
6038        /// `PaneDisplayMode = LeftCompact`, an ArkUI vertical `Tabs`).
6039        ///
6040        /// A backend with no rail rounds it to a neighbor of its own choosing rather than
6041        /// failing: UIKit answers `Tabs` (which is what iPadOS does at that width), GTK the same.
6042        /// Rounding is expected and correct; this variant is a request, not a contract.
6043        Rail,
6044    }
6045
6046    impl NavPresentation {
6047        /// `true` for [`NavPresentation::Split`], the shape most backend code wants.
6048        pub fn is_split(self) -> bool {
6049            self == NavPresentation::Split
6050        }
6051
6052        /// `true` when the rows are the chrome rather than a drawn page: [`Self::Tabs`] and
6053        /// [`Self::Rail`]. Both hide the `Pane::Sidebar` page and render its rows themselves, so
6054        /// backend code that only cares about that distinction asks this instead of matching both.
6055        pub fn rows_are_chrome(self) -> bool {
6056            matches!(self, NavPresentation::Tabs | NavPresentation::Rail)
6057        }
6058    }
6059
6060    /// Navigation host (docs/navigation.md).
6061    #[derive(Clone, Debug, Default, PartialEq)]
6062    pub struct NavProps {
6063        /// Document-tab chrome, independent of navigation destinations.
6064        pub documents: Option<DocumentTabsConfig>,
6065        pub title: String,
6066        /// The presentation to draw now; re-presented in place by [`NavPatch::Presentation`].
6067        pub presentation: NavPresentation,
6068        /// The app left the presentation automatic (`NavStyle::Automatic`, or a `Sidebar`
6069        /// nav host with no `.presentation(…)` pin), so it is free to follow the window.
6070        ///
6071        /// Only a toolkit answering `Cap::NavRepresent = Emulated` needs this: its own adaptive
6072        /// container owns the morph, and it must know whether the app asked for one at all before
6073        /// building it. With two presentations that bit could be inferred from a lowered `Split`;
6074        /// with four it cannot, so it is carried explicitly rather than encoded.
6075        ///
6076        /// `Native` re-presenters ignore it (they are told each presentation as it is resolved),
6077        /// and so do toolkits that cannot re-present.
6078        pub adaptive: bool,
6079        /// Draw the platform's own show/hide-sidebar affordance on this host's chrome
6080        /// (docs/toolbars.md). `true` for every `nav(Sidebar)` unless the app opted out:
6081        /// the toolkit owns both the button and the behavior
6082        /// (`NSToolbarToggleSidebarItemIdentifier`, the split view's collapse on GTK,
6083        /// `NavigationView.IsPaneOpen` on XAML), so an app that once declared the item by hand
6084        /// now declares nothing. Hosts with no sidebar ignore it.
6085        pub sidebar_toggle: bool,
6086        /// Search over this navigation surface (`Nav::searchable`, docs/search.md).
6087        /// `None` = the surface is not searchable and no field is rendered anywhere.
6088        pub search: Option<SearchProps>,
6089        /// `Some(width)` = this host has a content-list pane ([`Pane::List`]) at this preferred
6090        /// width in points, between the sidebar and the detail (docs/navigation.md). Read at
6091        /// realize, because a backend that builds a different container for a three-pane host
6092        /// (UIKit's triple-column style is init-only) needs to know before it builds. `None` on
6093        /// every host without one, including all of them on backends answering
6094        /// [`crate::Cap::NavContentList`] `Unsupported`: the pieces layer composes there and
6095        /// the prop is never set.
6096        pub list_width: Option<f64>,
6097        /// Whether that pane is showing for the destination the host opens on
6098        /// (`Nav::content_list_for`). Read at realize, like `list_width`, and for a
6099        /// related reason: a backend whose pane is a real split item can only honor a
6100        /// collapsed state reliably by setting it before the item joins the split. Told
6101        /// afterwards (by `NavPatch::ListVisible`, on a window that has not been displayed
6102        /// yet), AppKit reports the item collapsed and then lays it back out from its holding
6103        /// priorities, and the app opens with a list beside a page that does not own one.
6104        /// `true` on every host whose first destination has a list, and on hosts with no pane
6105        /// at all, where it means nothing.
6106        pub list_visible: bool,
6107    }
6108
6109    /// Switch only tab chrome; resident contents must retain their native identity.
6110    #[derive(Clone, Copy, Debug, PartialEq)]
6111    pub struct DocumentTabsPatch {
6112        pub native: bool,
6113    }
6114
6115    /// Localized document-tab chrome. Native callbacks emit stable route keys.
6116    #[derive(Clone, Debug, Default, PartialEq)]
6117    pub struct DocumentTabsConfig {
6118        pub new_label: String,
6119        pub close_label: String,
6120        pub can_add: bool,
6121    }
6122
6123    /// Where a searchable surface's field should be drawn.
6124    ///
6125    /// A preference, not an instruction: a backend that cannot honor the request falls back to
6126    /// whatever its platform does, exactly as SwiftUI's `searchable(placement:)` does ("depending
6127    /// on the containing view hierarchy and platform, the requested placement may not be able to
6128    /// be fulfilled"). `Automatic` is the one to reach for: it is what lets the field live in the
6129    /// window toolbar on a wide window and move into the navigation list on a narrow one.
6130    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
6131    pub enum SearchPlacement {
6132        /// The platform decides, from the window's size class and its own convention.
6133        #[default]
6134        Automatic,
6135        /// In the window's toolbar (`NSSearchToolbarItem`, an `AdwHeaderBar` entry, a
6136        /// `CommandBar` `AutoSuggestBox`). `Inline` where the toolbar cannot hold a search field
6137        /// (`Cap::ToolbarSearch`).
6138        Toolbar,
6139        /// Attached to the navigation surface itself: above the sidebar list, or in the
6140        /// navigation bar's search drawer on the phones.
6141        Inline,
6142    }
6143
6144    /// Search over a navigation surface (docs/search.md). The query itself stays an app-owned
6145    /// signal; this carries only what the toolkit must draw, so moving the field between
6146    /// placements never moves the state.
6147    #[derive(Clone, Debug, Default, PartialEq)]
6148    pub struct SearchProps {
6149        /// Current text. Two-way: the user typing emits [`Event::SearchChanged`], and the app's
6150        /// own writes arrive as [`SearchPatch::Text`].
6151        pub text: String,
6152        /// Empty-state prompt.
6153        pub prompt: String,
6154        pub placement: SearchPlacement,
6155        /// Opt into native scrolling search/title chrome on mobile. Default false keeps
6156        /// the field pinned. Desktop toolbar search is unchanged.
6157        pub hides_on_scroll: bool,
6158        /// Start the UIKit navigation search drawer collapsed, with a compact toolbar title.
6159        /// Implies scrolling search on UIKit; ignored by other backends. Default false.
6160        pub initially_hidden: bool,
6161        /// Scope titles, empty = no scope bar. One-of-N: a `UISearchBar` scope bar, a Material
6162        /// `ChipGroup` of single-selection filter chips, an ArkUI `SegmentButtonV2`, an
6163        /// `NSSegmentedControl` (docs/search.md has the per-backend table).
6164        pub scopes: Vec<String>,
6165        /// Index into `scopes`; meaningless when `scopes` is empty.
6166        pub scope: usize,
6167        /// Completions offered for the current text. On a navigation surface these complete the
6168        /// field rather than replacing the list: the list is already the result set, so an
6169        /// overlay of results would cover the thing it is filtering.
6170        pub suggestions: Vec<String>,
6171    }
6172
6173    /// A targeted update to a live search field, the path a bound signal writes through, so
6174    /// syncing text never rebuilds (and refocuses) the field mid-word.
6175    #[derive(Clone, Debug, PartialEq)]
6176    pub enum SearchPatch {
6177        Focus,
6178        Text(String),
6179        Scope(usize),
6180        Suggestions(Vec<String>),
6181    }
6182    /// Applied to the nav host after a page child is attached / before it is removed;
6183    /// the toolkit animates its native presentation accordingly.
6184    #[derive(Clone, Debug, PartialEq)]
6185    pub enum NavPatch {
6186        /// The just-attached last page child became the top of the stack. `immersive` marks a
6187        /// page that keeps the floating transparent chrome on backends with an immersive nav
6188        /// mode (day-toolkit-material edge-to-edge today; ignored elsewhere). Unmarked pages get the
6189        /// standard opaque bar.
6190        Pushed { title: String, immersive: bool },
6191        /// The top page is about to be removed; present its predecessor.
6192        Popped,
6193        /// Current top-of-stack title changed.
6194        Title(String),
6195        /// The top page has a back guard (`NavStack::on_back`, docs/navigation.md): while `true`,
6196        /// the toolkit must not auto-pop on a native back gesture/button but route it to
6197        /// Day as `Event::NavBack { already_popped: false }` so the app's guard decides. On
6198        /// backends whose back already routes through Day (AppKit/Qt/XAML/web custom headers)
6199        /// this is a no-op; iOS disables the swipe, Android holds its callback, GTK sets the
6200        /// page `can-pop=false`, ArkUI consumes `onBackPressed`.
6201        GuardTop(bool),
6202        /// Re-present the host: the window's size class crossed a breakpoint, or the app wrote a
6203        /// new `presentation`. The page children do not change: the toolkit rebuilds its
6204        /// chrome and re-homes the pages it already has, each one landing by its
6205        /// [`NavPageProps::pane`]. Rebuilding them instead would drop scroll offsets, field
6206        /// focus, and every native animation in flight, which is why this is a patch and not
6207        /// a rebuild.
6208        ///
6209        /// Backends with no split container ignore it and stay stacked.
6210        Presentation(NavPresentation),
6211        /// Show the resident [`Pane::Detail`] page at this index, counting the host's detail
6212        /// children in attach order. The counterpart to [`Self::Pushed`]/[`Self::Popped`] for the
6213        /// presentations where pages are resident rather than stacked
6214        /// ([`NavPresentation::rows_are_chrome`]): a tab bar switches between pages that all stay
6215        /// alive, so there is nothing to push and nothing to pop.
6216        ///
6217        /// Applied without re-emitting [`crate::Event::SelectionChanged`], per the from-native
6218        /// echo rule: this is the programmatic-sync direction.
6219        ///
6220        /// A backend drawing a stacked presentation never receives it; the pieces layer sends
6221        /// push/pop there instead.
6222        Select(usize),
6223        /// Reorder resident detail pages by their previous indices without rebuilding them.
6224        Reorder(Vec<usize>),
6225        /// Show or collapse the content-list pane ([`Pane::List`]), the per-destination
6226        /// visibility switch (`Nav::content_list_for`, docs/navigation.md): a nav host
6227        /// section that spans the whole detail area (a settings page) collapses the pane, and
6228        /// selecting a list-backed section brings it back. Only sent to hosts whose
6229        /// [`NavProps::list_width`] is set. Applied directly, not through an animator proxy:
6230        /// the screenshot step captures the instant the patch returns (the sidebar-toggle rule).
6231        ListVisible(bool),
6232        /// Stacked presentations on a merged-pane backend ([`crate::Cap::NavContentList`]
6233        /// `Emulated`) only: the resident [`Pane::List`] page joins (`true`) or leaves
6234        /// (`false`) the navigation stack directly above the sidebar root. The pieces layer
6235        /// sends it as the selection gains or loses a list-backed destination; the backend
6236        /// realizes the membership change through its platform's navigation APIs (UIKit:
6237        /// `showColumn(.supplementary)` / a pop to the root; never a manual splice, which
6238        /// destroys the split's collapse bookkeeping). Never sent to `Native` backends (their
6239        /// pane persists through every presentation) nor while split.
6240        ListInStack(bool),
6241    }
6242
6243    /// Which pane of a navigation host a page belongs to (docs/navigation.md).
6244    ///
6245    /// A page's pane is a fact about the model, not about how the host currently draws it: a
6246    /// nav host's list page is [`Pane::Sidebar`] whether the toolkit is showing a sidebar beside
6247    /// a detail or stacking the two. What the presentation decides is where each pane lands:
6248    /// its own splitter pane in [`NavPresentation::Split`], the root of the stack in
6249    /// [`NavPresentation::Stack`]. Keeping the two separate is what lets a host re-present on a
6250    /// size-class change (`NavPatch::Presentation`) by re-homing the pages it already has,
6251    /// instead of tearing the tree down and rebuilding it.
6252    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
6253    pub enum Pane {
6254        /// The list / master pane of a nav host. At most one page per host.
6255        Sidebar,
6256        /// The content-list pane between the sidebar and the detail, Mail's message list
6257        /// (`Nav::content_list`, docs/navigation.md). At most one page per host, and only
6258        /// on hosts whose [`NavProps::list_width`] is set; a backend answering
6259        /// [`crate::Cap::NavContentList`] `Unsupported` never sees one.
6260        List,
6261        /// A destination page. Every page of a `nav_stack` presentation is one of these.
6262        #[default]
6263        Detail,
6264    }
6265
6266    /// One destination's native container.
6267    #[derive(Clone, Debug, Default, PartialEq)]
6268    pub struct NavPageProps {
6269        pub title: String,
6270        pub pane: Pane,
6271    }
6272
6273    /// The largest a modal sheet grows on a desktop, in points: the window less a margin up to
6274    /// this (docs/cover.md "Modal sheet"). AppKit's native sheet and the composed card share it.
6275    pub const SHEET_MAX: crate::Size = crate::Size::new(640.0, 620.0);
6276    /// The largest a [`CoverProps::large`] sheet grows (docs/cover.md "Large sheet").
6277    pub const LARGE_SHEET_MAX: crate::Size = crate::Size::new(1040.0, 880.0);
6278
6279    /// A fullscreen cover's content container (docs/cover.md). Realized detached and hidden;
6280    /// `CoverPatch::Present` shows it over the whole window.
6281    #[derive(Clone, Debug, Default, PartialEq)]
6282    pub struct CoverProps {
6283        /// Prefer a native sheet; toolkits without sheet presentation keep their modal cover.
6284        pub sheet: bool,
6285        /// A half-height sheet rising from the bottom edge, the window content above it
6286        /// staying on show and, where the platform allows, interactive: an inspector over the
6287        /// canvas it describes. Implies `sheet`. The toolkit reports the sheet's own content
6288        /// size through `FrameChanged`, as for any cover (docs/cover.md "Half sheet").
6289        pub half: bool,
6290        /// A large sheet: most of the window, less a margin, for a document or web page that
6291        /// needs the room (docs/cover.md "Large sheet"). Implies `sheet`.
6292        pub large: bool,
6293    }
6294
6295    /// Applied to a `kinds::COVER` node as its bound signal opens and closes it.
6296    #[derive(Clone, Debug, PartialEq)]
6297    pub enum CoverPatch {
6298        /// Present the cover fullscreen (slide up where the platform animates modals).
6299        /// `background` paints the whole surface edge-to-edge (under the status bar / home
6300        /// indicator); the content container is inset to the safe area within it.
6301        /// `dismiss_disabled` = the user must not be able to dismiss it interactively
6302        /// (system back / sheet gestures); programmatic dismissal still works.
6303        Present {
6304            background: Option<Color>,
6305            dismiss_disabled: bool,
6306        },
6307        /// The `interactive_dismiss_disabled` state changed while presented.
6308        DismissDisabled(bool),
6309        /// Dismiss the cover. When the hide transition finishes the backend emits
6310        /// [`crate::Event::CoverHidden`] on the node (trampoline backends send
6311        /// `BridgeKind::CoverHidden`), letting the piece dispose the content only after it
6312        /// left the screen.
6313        Dismiss,
6314    }
6315
6316    /// A `kinds::INSPECTOR` split (docs/inspector.md): content beside a trailing inspector
6317    /// pane. The pane's visibility is Day-owned state (the piece's bound signal), so the
6318    /// props carry the value to draw and [`InspectorPatch::Visible`] keeps it current;
6319    /// a native affordance hiding the pane (a dock close button, a dragged-shut divider)
6320    /// reports back with [`crate::Event::InspectorChanged`].
6321    #[derive(Clone, Debug, PartialEq)]
6322    pub struct InspectorProps {
6323        /// Whether the pane is showing now.
6324        pub visible: bool,
6325        /// The pane's preferred width in points. A backend with a user-draggable divider
6326        /// treats it as the initial width; one without draws it at exactly this.
6327        pub width: f64,
6328        /// Which side of the content the pane sits on. `Trailing` is the classic inspector;
6329        /// `Leading` is a utility pane like a layer panel (docs/tree.md).
6330        pub edge: PaneEdge,
6331    }
6332
6333    /// Which side an inspector pane occupies (docs/inspector.md).
6334    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
6335    pub enum PaneEdge {
6336        #[default]
6337        Trailing,
6338        Leading,
6339    }
6340
6341    /// Applied to a `kinds::INSPECTOR` node as its bound signal changes.
6342    #[derive(Clone, Debug, PartialEq)]
6343    pub enum InspectorPatch {
6344        /// Show or hide the pane (animated where the platform animates panes). The
6345        /// programmatic-sync direction: applying it must not re-emit
6346        /// [`crate::Event::InspectorChanged`], per the from-native echo rule.
6347        Visible(bool),
6348    }
6349
6350    /// One pane of a `kinds::INSPECTOR` split (docs/inspector.md).
6351    #[derive(Clone, Debug, Default, PartialEq)]
6352    pub struct InspectorPaneProps {
6353        /// `true` for the inspector panel itself, `false` for the content pane.
6354        pub panel: bool,
6355    }
6356
6357    /// How a `kinds::SPLIT` lays its two panes (docs/split.md): beside each other, the divider
6358    /// standing, or stacked, the divider lying. Named by where the panes go, since that is
6359    /// what an app's "layout" toggle means; the divider runs the other way.
6360    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
6361    pub enum SplitAxis {
6362        /// The panes side by side (first leading), the divider vertical.
6363        #[default]
6364        Horizontal,
6365        /// The panes stacked (first on top), the divider horizontal.
6366        Vertical,
6367    }
6368
6369    /// A `kinds::SPLIT` (docs/split.md): two panes with a divider the user drags. The first
6370    /// pane's share is Day-owned state (the piece's bound signal): the props carry the value
6371    /// to draw, [`SplitPatch::Fraction`] keeps it current, and a divider the user moved
6372    /// reports back as [`crate::Event::ValueChanged`] with the new share, which applying the
6373    /// patch must never re-emit (the from-native echo rule).
6374    #[derive(Clone, Debug, PartialEq)]
6375    pub struct SplitProps {
6376        pub axis: SplitAxis,
6377        /// The first pane's share of the split's length along `axis`, `0.0..=1.0`.
6378        pub fraction: f64,
6379        /// The least length either pane may be dragged to, in points.
6380        pub min_pane: f64,
6381    }
6382
6383    /// Applied to a `kinds::SPLIT` node as its bound signals change.
6384    #[derive(Clone, Debug, PartialEq)]
6385    pub enum SplitPatch {
6386        /// Turn the split the other way, keeping the share.
6387        Axis(SplitAxis),
6388        /// Move the divider so the first pane takes this share. The programmatic-sync
6389        /// direction: applying it must not re-emit [`crate::Event::ValueChanged`].
6390        Fraction(f64),
6391    }
6392
6393    /// One pane of a `kinds::SPLIT` (docs/split.md).
6394    #[derive(Clone, Debug, Default, PartialEq)]
6395    pub struct SplitPaneProps {
6396        /// `false` for the first pane, `true` for the second.
6397        pub second: bool,
6398    }
6399
6400    /// Native navigation item list. `items` are display titles in route order;
6401    /// `selected` highlights the active route (split presentation; None on mobile roots).
6402    /// `icons` (parallel to `items`, `None` = no icon) are bundled image names resolved by each
6403    /// backend via `resource::resolve_image_file`; a backend that can't decorate its rows just
6404    /// ignores them.
6405    #[derive(Clone, Debug, Default, PartialEq)]
6406    pub struct NavMenuProps {
6407        /// Stable document identities, parallel to items; empty for ordinary navigation.
6408        pub document_keys: Vec<String>,
6409        pub items: Vec<String>,
6410        pub icons: Vec<Option<String>>,
6411        /// A trailing accessory per row: an unread count, a status. Rendered right-aligned and
6412        /// de-emphasized, opposite the label. Parallel to `items`; `None` draws nothing.
6413        pub badges: Vec<Option<String>>,
6414        /// A trailing symbol accessory per row, in the same slot as [`Self::badges`] and drawn
6415        /// after it: a bundled image name resolved the way [`Self::icons`] is. This is what a
6416        /// row-level status glyph rides on (a starred page's star) where `badges` carries only
6417        /// text. Parallel to `items`; `None` draws nothing.
6418        pub badge_icons: Vec<Option<String>>,
6419        /// The tint for [`Self::badge_icons`], parallel to `items`. `None` leaves the glyph at
6420        /// the backend's neutral template tint; a status glyph that means something (a yellow
6421        /// star) names its own color here, exactly as [`Self::tints`] does for the leading icon.
6422        pub badge_tints: Vec<Option<Color>>,
6423        /// A per-row icon tint (docs/vectors.md): the row's glyph recolored to this instead of
6424        /// the backend's neutral template tint. Parallel to `items`; `None` keeps the default.
6425        pub tints: Vec<Option<Color>>,
6426        /// A section header introducing the row at the same index. `Some` opens a new group
6427        /// before that row; `None` continues the current one. Parallel to `items`, so adding a
6428        /// header never shifts the selection indices the rows are addressed by.
6429        pub sections: Vec<Option<String>>,
6430        /// A per-row context menu (docs/menus.md): shown on secondary-click / long-press on
6431        /// that row, the same [`crate::MenuItem`] model as everywhere else: items carry
6432        /// registered action ids, so a chosen entry dispatches [`crate::Event::MenuAction`]
6433        /// exactly like a piece context menu. Parallel to `items`; empty = no menu.
6434        pub menus: Vec<Vec<crate::MenuItem>>,
6435        /// Which rows drag to reorder (docs/navigation.md "Reordering sidebar destinations"),
6436        /// parallel to `items`; empty when the sidebar does not reorder. A row moves only
6437        /// within the run of movable rows around it, which a section header or a fixed row
6438        /// ends. A toolkit whose `Cap::NavReorder` is `Native` drags the rows in its own
6439        /// sidebar and reports a drop as [`crate::Event::ListReorder`] in item indices: `from`
6440        /// is the moved row, `to` the row whose position it takes, in the order before the move.
6441        pub movable: Vec<bool>,
6442        /// The sidebar regroups (docs/navigation.md "Moving rows between sections"): a movable
6443        /// row may also cross section headers, into any section whose rows are all movable. A
6444        /// toolkit whose `Cap::NavReorder` is `Native` offers those drops too and reports every
6445        /// drop as [`crate::Event::NavRegroup`] instead of [`crate::Event::ListReorder`]. `false`
6446        /// keeps [`Self::movable`]'s run rule.
6447        pub regroup: bool,
6448        /// Which movable rows keep the app's sorted order within their own section, parallel to
6449        /// `items`; empty when the sidebar does not regroup. Under [`Self::regroup`], a sorted
6450        /// row drops only into another section: no gap in its own section is offered.
6451        pub sorted: Vec<bool>,
6452        pub selected: Option<usize>,
6453    }
6454    #[derive(Clone, Debug, PartialEq)]
6455    // `Items` carries every row array; a patch travels boxed (`Box<dyn Any>`) and lives for one
6456    // update, so the variants' size difference costs nothing worth an indirection.
6457    #[allow(clippy::large_enum_variant)]
6458    pub enum NavMenuPatch {
6459        /// Active icon overlays by row index: None spins, Some(0..=1) fills a circle.
6460        /// Rows absent from this complete snapshot have no overlay. Does not relayout rows.
6461        /// Currently rendered by AppKit/UIKit; other backends may ignore this decoration.
6462        IconProgress(Vec<(usize, Option<f64>)>),
6463        /// Programmatic highlight sync: toolkits apply without re-emitting
6464        /// SelectionChanged (the TextField from_native echo rule).
6465        Selected(Option<usize>),
6466        /// The item set changed (data-driven `nav().items(signal, …)`): rebuild the rows
6467        /// from these labels/icons, then apply `selected` (docs/navigation.md). Applied without
6468        /// re-emitting SelectionChanged.
6469        ///
6470        /// `rows_changed` is `Some` when the rows themselves are the ones already shown (same
6471        /// keys, sections and row menus) and only these rows' title, icon, tint or badge moved:
6472        /// a count ticking, a language change. A backend updates those rows in place (a tab's
6473        /// badge, a menu item's title) rather than rebuilding, which on most platforms re-lays
6474        /// the bar and replays its selection animation; one that cannot rebuilds as for `None`.
6475        Items {
6476            rows_changed: Option<Box<[usize]>>,
6477            document_keys: Box<[String]>,
6478            items: Vec<String>,
6479            icons: Vec<Option<String>>,
6480            badges: Vec<Option<String>>,
6481            badge_icons: Vec<Option<String>>,
6482            badge_tints: Vec<Option<Color>>,
6483            sections: Vec<Option<String>>,
6484            tints: Vec<Option<Color>>,
6485            menus: Vec<Vec<crate::MenuItem>>,
6486            /// [`NavMenuProps::movable`] for the new rows.
6487            movable: Vec<bool>,
6488            /// [`NavMenuProps::sorted`] for the new rows ([`NavMenuProps::regroup`] holds for
6489            /// the sidebar's life).
6490            sorted: Vec<bool>,
6491            selected: Option<usize>,
6492        },
6493    }
6494
6495    /// How a recycling list sizes its rows (docs/list.md).
6496    #[derive(Clone, Copy, Debug, PartialEq, Default)]
6497    pub enum RowHeight {
6498        /// Every row is this tall, a true layout boundary; the fastest path.
6499        Uniform(f64),
6500        /// Rows self-size from their content (host re-measures on change; slower).
6501        #[default]
6502        Automatic,
6503    }
6504
6505    /// Configure a navigation sidebar's native pull-to-refresh control. Not a synthetic pan:
6506    /// supported toolkits own gesture arbitration and the progress indicator. A false state
6507    /// ends a pull, including a request the application declines. Never emits an event.
6508    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
6509    pub struct RefreshPatch {
6510        pub refreshing: bool,
6511    }
6512
6513    /// Native recycling list (docs/list.md). The host owns scrolling + cell reuse; Day supplies
6514    /// row content on demand through the injected `ListSource` (see `Toolkit::attach_list`).
6515    #[derive(Clone, Debug, Default, PartialEq)]
6516    pub struct ListProps {
6517        /// Whether the app handles row activation. Do not claim activation keys when false.
6518        pub activatable: bool,
6519        pub row_height: RowHeight,
6520        /// Whether the native list reports row selection (`Event::SelectionChanged` with the row).
6521        pub selectable: bool,
6522        /// Whether the native list allows selecting several rows at once. Where honored
6523        /// (docs/list.md has the matrix), every selection change reports the full set via
6524        /// `Event::SelectionSet`; single-selection backends keep reporting
6525        /// `Event::SelectionChanged` and treat this as `selectable`.
6526        pub multi_select: bool,
6527        /// Whether rows can be drag-reordered. The toolkit enables its native drag machinery and
6528        /// drives `ListSource::reorder` (validate via `can_move`, commit via `move_row`);
6529        /// probe `Cap::ListReorder` for per-backend support (docs/list.md).
6530        pub reorderable: bool,
6531        /// Whether rows can be deleted by the platform's own delete gesture: a trailing swipe on
6532        /// iOS and ArkUI, an `ItemTouchHelper` swipe on Android. The toolkit drives
6533        /// `ListSource::delete` (offer via `can_delete`, commit via `delete_row`); probe
6534        /// `Cap::ListDelete` for per-backend support (docs/list.md). Desktop toolkits have no such
6535        /// gesture and answer `Unsupported`; an app that must delete everywhere pairs this with an
6536        /// explicit control (a menu item, a button) rather than relying on the swipe.
6537        pub deletable: bool,
6538        /// The label on that affordance, already localized by the app. A toolkit cannot invent
6539        /// translated text (it has no access to the app's catalog), so the string arrives with
6540        /// the props. Empty means "no text": each backend falls back to its platform's own
6541        /// wordless idiom (a trash glyph), which works in every language.
6542        pub delete_label: String,
6543        /// The rows offer edge swipe actions (docs/list.md) through the injected
6544        /// `ListSource::swipe` (offer via `actions_at`, commit via `perform`); probe
6545        /// [`crate::Cap::ListSwipeActions`] for per-backend support. A backend without the
6546        /// affordance never shows one; an app that must offer the command everywhere
6547        /// pairs the swipe with an explicit control, exactly as `deletable` documents.
6548        pub swipe_actions: bool,
6549        /// Row separators, drawn by the host at the row boundary (docs/list.md), so they
6550        /// align with the native selection and ride the platform's own row animations (a
6551        /// macOS/iOS swipe slides the row content past a stationary separator, exactly as
6552        /// Mail's does). `None` keeps each platform's own default (iOS draws them, the
6553        /// desktops don't); `Some(true)`/`Some(false)` forces. A backend without a separator
6554        /// mechanism ignores a force (the matrix in docs/list.md says which); rows there
6555        /// separate by their pitch alone.
6556        pub separators: Option<bool>,
6557        /// The list starts in the platform's editing mode (docs/list.md): delete controls on
6558        /// the rows `deletable` offers, reorder grips on the rows `reorderable` moves, and a
6559        /// tap that still activates. Later changes arrive as [`ListPatch::Editing`]. Probe
6560        /// [`crate::Cap::ListEditing`]; a backend without an editing mode ignores it.
6561        pub editing: bool,
6562        /// The rows fall into sections, each opened by a header row (docs/list.md
6563        /// "Sections"): `ListSource::is_header` says which rows. Probe
6564        /// [`crate::Cap::ListSections`] for whether headers float natively.
6565        pub sections: bool,
6566    }
6567
6568    /// One row-level result-set change. Indexes are sequential (each delta describes the
6569    /// set as the previous ones left it), so a host applies them one at a time (or falls back
6570    /// to a reload; the source's snapshot already holds the final state either way).
6571    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
6572    pub enum RowDelta {
6573        Insert(usize),
6574        Remove(usize),
6575        Move(usize, usize),
6576    }
6577
6578    /// Immutable-at-realize props of a `kinds::TREE` host (docs/tree.md). Everything that
6579    /// changes after realize flows through [`TreePatch`] or the injected `TreeSource`.
6580    #[derive(Clone, Debug, PartialEq)]
6581    pub struct TreeProps {
6582        /// Two-level sectioned list: root branches are non-selectable headings.
6583        pub section_headers: bool,
6584        pub row_height: RowHeight,
6585        /// Rows highlight and report selection ([`crate::Event::TreeSelection`]).
6586        pub selectable: bool,
6587        /// Several rows may be selected at once; every change reports the full token set.
6588        pub multi_select: bool,
6589        /// Rows drag to a new parent/position through the platform's own mechanism, driving
6590        /// `TreeSource::moves`. Probe [`crate::Cap::TreeMove`] for support.
6591        pub movable: bool,
6592        /// Indentation per depth level, in points. `None` = the platform's default step.
6593        pub indent: Option<f64>,
6594    }
6595
6596    /// Post-realize changes to a `kinds::TREE` host (docs/tree.md). Token-addressed
6597    /// throughout; see [`crate::TreeSource`] for why indices cannot address tree rows.
6598    #[derive(Clone, Debug, PartialEq)]
6599    pub enum TreePatch {
6600        /// The node set changed (count/order/parentage/content): the host re-queries its
6601        /// `TreeSource`. Expansion and selection survive by token (docs/tree.md).
6602        Reload,
6603        /// Programmatically disclose (`true`) or collapse (`false`) one row. Applied without
6604        /// re-emitting [`crate::Event::TreeExpanded`] (the from-native echo rule).
6605        Expand(u64, bool),
6606        /// Programmatic selection sync (tokens; empty = clear), applied without re-emitting
6607        /// [`crate::Event::TreeSelection`].
6608        Selected(Vec<u64>),
6609        /// Scroll this row into view, realizing it if needed. The piece has already expanded
6610        /// the row's ancestors (through the app's expansion signal) before issuing this.
6611        Reveal(u64),
6612    }
6613
6614    #[derive(Clone, Debug, PartialEq)]
6615    pub enum ListPatch {
6616        /// The row set changed (count/order/content): the host re-queries its `ListSource`.
6617        Reload,
6618        /// The row set changed by exactly these deltas: a host that can, animates each row
6619        /// in, out, or across; one that cannot treats this as [`ListPatch::Reload`]. The
6620        /// data source answers with the final state throughout.
6621        Splice(Vec<RowDelta>),
6622        /// An `Automatic`-height row was re-laid at a new height after its first layout (its
6623        /// text changed, a wrapped line appeared, the backend corrected its width): the host
6624        /// gives the row bound to physical cell `cell` (the handle `ListSource::bind_row` got,
6625        /// as `usize`) the new `height`, padding included, the same value
6626        /// `ListSource::cell_height` now answers for it.
6627        ///
6628        /// Sent from inside a day-core layout pass, with the tree borrowed: a host applies it
6629        /// after the pass (posted to its main loop), never by asking the source anything
6630        /// synchronously, which would read a `0.0` height (docs/list.md "Row heights").
6631        RowSizeInvalidated { cell: usize, height: f64 },
6632        /// Imperatively scroll the native list so its last row is fully visible (a chat timeline
6633        /// sticking to the newest message). No-op when the list is empty (docs/list.md).
6634        ScrollToEnd,
6635        /// Imperatively scroll the native list so this row is visible, realizing it if needed
6636        /// (docs/list.md). Clamped to the row count; no-op when the list is empty.
6637        ScrollToRow(usize),
6638        /// Programmatic selection sync (row indices; empty = clear): toolkits apply without
6639        /// re-emitting a selection event, like every other programmatic sync.
6640        Selected(Vec<usize>),
6641        /// Enter (`true`) or leave (`false`) the platform's list editing mode, animated
6642        /// (docs/list.md, [`ListProps::editing`]). Ignored where `Cap::ListEditing` is
6643        /// `Unsupported`.
6644        Editing(bool),
6645    }
6646}
6647
6648// ---------------------------------------------------------------------------
6649// Imperative presentation (docs/dialogs.md)
6650// ---------------------------------------------------------------------------
6651
6652pub mod present {
6653    /// A dialog button's semantic role: styling + default/cancel placement on each toolkit.
6654    #[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
6655    pub enum ButtonRole {
6656        #[default]
6657        Default,
6658        Cancel,
6659        Destructive,
6660    }
6661
6662    #[derive(Clone, Debug, PartialEq)]
6663    pub struct PresentButton {
6664        pub label: String,
6665        pub role: ButtonRole,
6666    }
6667
6668    /// A named group of file extensions for a file dialog (e.g. "Text" → `["txt", "md"]`).
6669    /// An empty `extensions` list means "all files".
6670    #[derive(Clone, Debug, PartialEq, Default)]
6671    pub struct FileFilter {
6672        pub name: String,
6673        pub extensions: Vec<String>,
6674    }
6675
6676    /// What a backend should present for a `req`. Kept toolkit-agnostic; the pieces layer
6677    /// maps a chosen button index back to a typed payload.
6678    #[derive(Clone, Debug, PartialEq)]
6679    pub enum PresentSpec {
6680        /// Alert / confirmation / action sheet: title + optional message + ordered buttons.
6681        /// `sheet` = present from the bottom on mobile (desktop falls back to an alert).
6682        Dialog {
6683            title: String,
6684            message: Option<String>,
6685            buttons: Vec<PresentButton>,
6686            sheet: bool,
6687        },
6688        /// A dialog with a single text field.
6689        Prompt {
6690            title: String,
6691            message: Option<String>,
6692            placeholder: String,
6693            initial: String,
6694            ok: String,
6695            cancel: String,
6696        },
6697        /// Native "open file" picker (docs/files.md). The backend must answer with
6698        /// `PresentResult::Files` whose entries are **readable local paths**: desktop returns
6699        /// the chosen path directly; iOS/Android copy the selection into app storage first, so
6700        /// the pieces layer can read it with `std::fs` regardless of platform. `multiple` lets
6701        /// the user pick several files at once; the answer then carries every chosen path, in
6702        /// the picker's order. A backend that cannot select more than one file still answers
6703        /// with the single pick.
6704        OpenFile {
6705            title: String,
6706            filters: Vec<FileFilter>,
6707            multiple: bool,
6708        },
6709        /// Native "choose folder" picker (docs/files.md). The backend answers with
6710        /// `PresentResult::Files` holding the one chosen directory path, or `Dismissed`. Only
6711        /// backends answering [`Cap::FolderDialog`](crate::Cap::FolderDialog) as `Native` show a
6712        /// chooser; the others resolve the request as `Dismissed` at once, so the await never hangs.
6713        OpenFolder { title: String },
6714        /// Native "save file" picker (docs/files.md). `src_path` is a Day-written temp file
6715        /// holding the bytes to save; iOS/Android deliver it to the chosen destination natively,
6716        /// and the pieces layer best-effort copies it to a chosen local path otherwise.
6717        SaveFile {
6718            title: String,
6719            suggested_name: String,
6720            src_path: String,
6721            filters: Vec<FileFilter>,
6722        },
6723    }
6724
6725    /// The user's answer to a presentation.
6726    #[derive(Clone, Debug, PartialEq)]
6727    pub enum PresentResult {
6728        /// A dialog button at `index` (in spec order) was chosen.
6729        Button(i64),
6730        /// A prompt was confirmed with `text`.
6731        Text(String),
6732        /// One or more file locators chosen from an open/save picker (docs/files.md). Each is a
6733        /// local filesystem path or, on Android save, a `content://` URI.
6734        Files(Vec<String>),
6735        /// Dismissed without choosing (tap-outside / Esc / cancel gesture).
6736        Dismissed,
6737    }
6738
6739    /// The unit-separator that joins string lists across the C ABI (Qt shim / Android JNI), the
6740    /// same encoding the nav menu, combobox, and dialog-button shims use.
6741    pub const UNIT_SEP: char = '\u{1f}';
6742
6743    std::thread_local! {
6744        /// An app-writable scratch directory. Backends whose OS temp dir isn't app-writable
6745        /// (Android → `getCacheDir()`) set this at startup; elsewhere it stays `None` and callers
6746        /// fall back to `std::env::temp_dir()`.
6747        // False positive, and only when checking an android target: the initializer already is
6748        // the `const` block the lint asks for. Android's TLS model makes the macro expand to a
6749        // form clippy reads as lazy, so the suggestion is unfollowable as well as unneeded.
6750        #[allow(clippy::missing_const_for_thread_local)]
6751        static APP_TEMP_DIR: std::cell::RefCell<Option<std::path::PathBuf>> =
6752            const { std::cell::RefCell::new(None) };
6753    }
6754
6755    /// Record an app-writable scratch directory (see [`app_temp_dir`]). Called by a backend at
6756    /// startup when the OS temp dir isn't writable by the app (Android).
6757    pub fn set_app_temp_dir(dir: impl Into<std::path::PathBuf>) {
6758        APP_TEMP_DIR.with(|d| *d.borrow_mut() = Some(dir.into()));
6759    }
6760
6761    /// An app-writable scratch directory: the backend-supplied one, else `std::env::temp_dir()`.
6762    /// Used by the file-save flow (docs/files.md) to stage bytes before the native save picker.
6763    pub fn app_temp_dir() -> std::path::PathBuf {
6764        APP_TEMP_DIR.with(|d| {
6765            d.borrow().clone().unwrap_or_else(|| {
6766                #[cfg(target_arch = "wasm32")]
6767                {
6768                    // A browser has no filesystem and std's `temp_dir()` panics on wasm. A
6769                    // nominal path keeps join/display plumbing alive; actual reads and writes
6770                    // fail with ordinary io errors the file flows already surface.
6771                    std::path::PathBuf::from("/day-tmp")
6772                }
6773                #[cfg(not(target_arch = "wasm32"))]
6774                std::env::temp_dir()
6775            })
6776        })
6777    }
6778
6779    /// The web build's file bytes (wasm32-unknown-unknown only): a browser has no filesystem,
6780    /// so the open/save flows carry bytes through this per-page store instead of `std::fs`:
6781    /// day-toolkit-dom writes a picked file's bytes here and answers with its virtual path; the pieces
6782    /// layer stages save bytes here for the shim to download. Paths are plain strings under
6783    /// `/day-web/`; lifetimes are one picker round-trip (the flows remove what they stage).
6784    #[cfg(all(target_family = "wasm", target_os = "unknown"))]
6785    pub mod web_files {
6786        std::thread_local! {
6787            static FILES: std::cell::RefCell<std::collections::HashMap<String, Vec<u8>>> =
6788                std::cell::RefCell::new(std::collections::HashMap::new());
6789        }
6790
6791        /// Store `bytes` under `path` (replacing any prior content).
6792        pub fn write(path: &str, bytes: Vec<u8>) {
6793            FILES.with(|f| f.borrow_mut().insert(path.to_string(), bytes));
6794        }
6795
6796        /// The bytes at `path`, if present.
6797        pub fn read(path: &str) -> Option<Vec<u8>> {
6798            FILES.with(|f| f.borrow().get(path).cloned())
6799        }
6800
6801        /// Drop `path`'s bytes.
6802        pub fn remove(path: &str) {
6803            FILES.with(|f| {
6804                f.borrow_mut().remove(path);
6805            });
6806        }
6807    }
6808
6809    impl PresentResult {
6810        /// Flat wire tag for the C ABI (Qt shim / Android JNI): 0 dismissed, 1 button, 2 text,
6811        /// 3 files (`text` is the chosen locators joined by the unit separator).
6812        pub fn decode(tag: i32, index: i64, text: String) -> PresentResult {
6813            match tag {
6814                1 => PresentResult::Button(index),
6815                2 => PresentResult::Text(text),
6816                3 => PresentResult::Files(
6817                    text.split(UNIT_SEP)
6818                        .filter(|s| !s.is_empty())
6819                        .map(str::to_string)
6820                        .collect(),
6821                ),
6822                _ => PresentResult::Dismissed,
6823            }
6824        }
6825    }
6826
6827    impl PresentSpec {
6828        /// Backend-facing flattening for the C ABI: `(title, message, button labels, button
6829        /// roles as ints, sheet-or-prompt fields)`. Pure-Rust backends read the enum directly.
6830        pub fn title(&self) -> &str {
6831            match self {
6832                PresentSpec::Dialog { title, .. }
6833                | PresentSpec::Prompt { title, .. }
6834                | PresentSpec::OpenFile { title, .. }
6835                | PresentSpec::OpenFolder { title }
6836                | PresentSpec::SaveFile { title, .. } => title,
6837            }
6838        }
6839        pub fn message(&self) -> Option<&str> {
6840            match self {
6841                PresentSpec::Dialog { message, .. } | PresentSpec::Prompt { message, .. } => {
6842                    message.as_deref()
6843                }
6844                _ => None,
6845            }
6846        }
6847        /// Button labels joined with [`UNIT_SEP`], the encoding the nav menu and combobox
6848        /// shims already use for string lists.
6849        pub fn buttons_joined(&self) -> String {
6850            match self {
6851                PresentSpec::Dialog { buttons, .. } => buttons
6852                    .iter()
6853                    .map(|b| b.label.as_str())
6854                    .collect::<Vec<_>>()
6855                    .join(&UNIT_SEP.to_string()),
6856                PresentSpec::Prompt { ok, cancel, .. } => format!("{ok}{UNIT_SEP}{cancel}"),
6857                _ => String::new(),
6858            }
6859        }
6860        /// Button roles as ints (0 default, 1 cancel, 2 destructive), joined with commas.
6861        pub fn roles_joined(&self) -> String {
6862            let roles: Vec<i32> = match self {
6863                PresentSpec::Dialog { buttons, .. } => {
6864                    buttons.iter().map(|b| b.role as i32).collect()
6865                }
6866                PresentSpec::Prompt { .. } => {
6867                    vec![ButtonRole::Default as i32, ButtonRole::Cancel as i32]
6868                }
6869                _ => vec![],
6870            };
6871            roles
6872                .iter()
6873                .map(|r| r.to_string())
6874                .collect::<Vec<_>>()
6875                .join(",")
6876        }
6877
6878        // --- file-dialog accessors (docs/files.md) ---
6879
6880        /// The file filters, if this is a file dialog.
6881        pub fn filters(&self) -> &[FileFilter] {
6882            match self {
6883                PresentSpec::OpenFile { filters, .. } | PresentSpec::SaveFile { filters, .. } => {
6884                    filters
6885                }
6886                _ => &[],
6887            }
6888        }
6889        /// Whether an open-file dialog lets the user pick several files (`false` for every
6890        /// other spec).
6891        pub fn multiple(&self) -> bool {
6892            matches!(self, PresentSpec::OpenFile { multiple: true, .. })
6893        }
6894        /// The suggested file name for a save dialog (empty otherwise).
6895        pub fn suggested_name(&self) -> &str {
6896            match self {
6897                PresentSpec::SaveFile { suggested_name, .. } => suggested_name,
6898                _ => "",
6899            }
6900        }
6901        /// The Day-written temp source path for a save dialog (empty otherwise).
6902        pub fn src_path(&self) -> &str {
6903            match self {
6904                PresentSpec::SaveFile { src_path, .. } => src_path,
6905                _ => "",
6906            }
6907        }
6908        /// Filters flattened for the C ABI: each filter is `name|ext1,ext2`, joined by
6909        /// [`UNIT_SEP`]. A trailing `|` (no extensions) means "all files". Empty when unfiltered.
6910        pub fn filters_joined(&self) -> String {
6911            self.filters()
6912                .iter()
6913                .map(|f| format!("{}|{}", f.name, f.extensions.join(",")))
6914                .collect::<Vec<_>>()
6915                .join(&UNIT_SEP.to_string())
6916        }
6917    }
6918}
6919
6920// ---------------------------------------------------------------------------
6921// App directories (docs/fs.md "Where files live")
6922// ---------------------------------------------------------------------------
6923
6924/// Where an app keeps its own files: its data, cache and configuration directories, each a
6925/// folder named after the app id in the place its platform sets aside for that kind of file
6926/// (docs/fs.md "Where files live"). Every Day crate that stores files resolves them here, so an
6927/// app's database, documents, caches, settings file and remembered window frames sit together
6928/// and apart from every other app's.
6929///
6930/// These only resolve paths; nothing is created until something is written. Each is `None` where
6931/// the platform has no such directory: the web, or an Android or HarmonyOS process whose host
6932/// passed none.
6933pub mod storage {
6934    use std::path::PathBuf;
6935
6936    /// The app's id, `[app] id` from Day.toml: `DAY_APP_ID` from `day launch`, else the value
6937    /// `day build` baked in, else the executable's name (a test binary or a bare `cargo run`).
6938    /// Made safe as a single folder name.
6939    pub fn app_id() -> String {
6940        std::env::var("DAY_APP_ID")
6941            .ok()
6942            .filter(|id| !id.is_empty())
6943            .or_else(|| {
6944                option_env!("DAY_APP_ID")
6945                    .filter(|id| !id.is_empty())
6946                    .map(str::to_owned)
6947            })
6948            .or_else(|| {
6949                let exe = std::env::current_exe().ok()?;
6950                exe.file_stem()?.to_str().map(str::to_owned)
6951            })
6952            .map(|id| folder_name(&id))
6953            .unwrap_or_else(|| "day-app".to_owned())
6954    }
6955
6956    /// The app's data directory, for what it cannot recreate: databases, documents, downloads
6957    /// the user kept. Application Support on Apple platforms (inside the container when
6958    /// sandboxed), `%LOCALAPPDATA%` on Windows, `$XDG_DATA_HOME` on Linux, the app's files
6959    /// directory on Android and HarmonyOS. `DAY_DATA_DIR` replaces it.
6960    pub fn data_dir() -> Option<PathBuf> {
6961        resolve(Dir::Data, Os::HOST, &app_id(), &env_path)
6962    }
6963
6964    /// [`data_dir`] for the app `app_id` rather than this process's own: a host that keeps a
6965    /// folder per hosted app (a day-lite superapp, a crash reporter's store), or a tool finding
6966    /// where an app it launched writes. On Android and HarmonyOS, where the host's directory is
6967    /// already the one app's, the id changes nothing.
6968    pub fn data_dir_for(app_id: &str) -> Option<PathBuf> {
6969        resolve(Dir::Data, Os::HOST, &folder_name(app_id), &env_path)
6970    }
6971
6972    /// The app's cache directory, for what it can fetch or compute again: the system may clear
6973    /// it, and backups skip it. Caches on Apple platforms, `%LOCALAPPDATA%\<id>\cache` on
6974    /// Windows, `$XDG_CACHE_HOME` on Linux, the app's cache directory on Android and HarmonyOS.
6975    /// `DAY_CACHE_DIR` replaces it; with only `DAY_DATA_DIR` set it is that directory's `cache`.
6976    pub fn cache_dir() -> Option<PathBuf> {
6977        resolve(Dir::Cache, Os::HOST, &app_id(), &env_path)
6978    }
6979
6980    /// The app's configuration directory, for small settings files: Application Support on
6981    /// Apple platforms (whose preferences proper are the user defaults), the roaming
6982    /// `%APPDATA%` on Windows, `$XDG_CONFIG_HOME` on Linux. With `DAY_DATA_DIR` set (as the
6983    /// Android and HarmonyOS hosts do) it is that directory's `config`.
6984    pub fn config_dir() -> Option<PathBuf> {
6985        resolve(Dir::Config, Os::HOST, &app_id(), &env_path)
6986    }
6987
6988    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
6989    enum Dir {
6990        Data,
6991        Cache,
6992        Config,
6993    }
6994
6995    /// The platform families whose conventions differ.
6996    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
6997    enum Os {
6998        /// macOS and iOS: `~/Library`, which is the app's container when sandboxed.
6999        Apple,
7000        Windows,
7001        /// Android and HarmonyOS: the host passes the app's private directories.
7002        Hosted,
7003        /// Linux and the BSDs: the XDG base directories.
7004        Unix,
7005        Web,
7006    }
7007
7008    impl Os {
7009        const HOST: Os = if cfg!(any(target_os = "macos", target_os = "ios")) {
7010            Os::Apple
7011        } else if cfg!(target_os = "windows") {
7012            Os::Windows
7013        } else if cfg!(any(target_os = "android", target_env = "ohos")) {
7014            Os::Hosted
7015        } else if cfg!(target_family = "wasm") {
7016            Os::Web
7017        } else {
7018            Os::Unix
7019        };
7020    }
7021
7022    /// An environment variable naming a directory: set, non-empty and absolute, else ignored.
7023    fn env_path(name: &str) -> Option<PathBuf> {
7024        let path = PathBuf::from(std::env::var_os(name)?);
7025        path.is_absolute().then_some(path)
7026    }
7027
7028    /// One folder name: no separators, no `.`/`..`, nothing a filesystem rejects.
7029    fn folder_name(id: &str) -> String {
7030        let name: String = id
7031            .chars()
7032            .map(|c| match c {
7033                '/' | '\\' | ':' | '*' | '?' | '"' | '<' | '>' | '|' => '_',
7034                c if c.is_control() => '_',
7035                c => c,
7036            })
7037            .collect();
7038        match name.trim() {
7039            "" | "." | ".." => "day-app".to_owned(),
7040            name => name.to_owned(),
7041        }
7042    }
7043
7044    /// The pure resolution, over a platform and an environment, so every platform's rules are
7045    /// testable on any host.
7046    fn resolve(
7047        dir: Dir,
7048        os: Os,
7049        id: &str,
7050        var: &dyn Fn(&str) -> Option<PathBuf>,
7051    ) -> Option<PathBuf> {
7052        // The explicit overrides: a mobile host's own directories, or a test's scratch root.
7053        if dir == Dir::Cache
7054            && let Some(cache) = var("DAY_CACHE_DIR")
7055        {
7056            return Some(cache);
7057        }
7058        if let Some(data) = var("DAY_DATA_DIR") {
7059            return Some(match dir {
7060                Dir::Data => data,
7061                Dir::Cache => data.join("cache"),
7062                Dir::Config => data.join("config"),
7063            });
7064        }
7065        let home = || var("HOME");
7066        match os {
7067            // One expression serves sandboxed and unsandboxed apps: inside the App Sandbox,
7068            // and always on iOS, `HOME` is the container's Data folder, so the same Library
7069            // path lands inside it. Apple asks for a bundle-id folder within Application
7070            // Support and Caches either way. XDG variables are ignored here: a Finder launch
7071            // never sees a shell's, so honoring them would split one app's data across two
7072            // places depending on how it was started.
7073            Os::Apple => {
7074                let library = home()?.join("Library");
7075                let base = match dir {
7076                    Dir::Data | Dir::Config => library.join("Application Support"),
7077                    Dir::Cache => library.join("Caches"),
7078                };
7079                Some(base.join(id))
7080            }
7081            // Local for data and caches: a database or cache roams badly, and a DPAPI-sealed
7082            // file cannot be read on another machine. Roaming for the small settings files.
7083            Os::Windows => {
7084                let profile = |leaf: &str| Some(var("USERPROFILE")?.join("AppData").join(leaf));
7085                let local = || var("LOCALAPPDATA").or_else(|| profile("Local"));
7086                match dir {
7087                    Dir::Data => Some(local()?.join(id)),
7088                    Dir::Cache => Some(local()?.join(id).join("cache")),
7089                    Dir::Config => Some(var("APPDATA").or_else(|| profile("Roaming"))?.join(id)),
7090                }
7091            }
7092            Os::Unix => {
7093                let (xdg, fallback) = match dir {
7094                    Dir::Data => ("XDG_DATA_HOME", ".local/share"),
7095                    Dir::Cache => ("XDG_CACHE_HOME", ".cache"),
7096                    Dir::Config => ("XDG_CONFIG_HOME", ".config"),
7097                };
7098                Some(var(xdg).or_else(|| Some(home()?.join(fallback)))?.join(id))
7099            }
7100            Os::Hosted | Os::Web => None,
7101        }
7102    }
7103
7104    #[cfg(test)]
7105    mod tests {
7106        use super::*;
7107        use std::collections::HashMap;
7108
7109        /// The resolved path as text. `Path::join` uses the host's separator, so on a Windows host
7110        /// another platform's path comes back with `\` between the joined parts; the expectations
7111        /// are that platform's own, so its separators are compared as `/`.
7112        fn at(os: Os, dir: Dir, vars: &[(&str, &str)]) -> Option<String> {
7113            let vars: HashMap<&str, &str> = vars.iter().copied().collect();
7114            let var = |name: &str| vars.get(name).map(PathBuf::from);
7115            resolve(dir, os, "dev.example.notes", &var).map(|p| {
7116                let text = p.display().to_string();
7117                if os == Os::Windows {
7118                    text
7119                } else {
7120                    text.replace('\\', "/")
7121                }
7122            })
7123        }
7124
7125        #[test]
7126        fn apple_uses_library_folders_named_for_the_app() {
7127            let home = [("HOME", "/Users/ada"), ("XDG_DATA_HOME", "/Users/ada/.xdg")];
7128            let support = "/Users/ada/Library/Application Support/dev.example.notes";
7129            assert_eq!(at(Os::Apple, Dir::Data, &home).as_deref(), Some(support));
7130            assert_eq!(at(Os::Apple, Dir::Config, &home).as_deref(), Some(support));
7131            assert_eq!(
7132                at(Os::Apple, Dir::Cache, &home).as_deref(),
7133                Some("/Users/ada/Library/Caches/dev.example.notes")
7134            );
7135            // A sandboxed app's HOME is its container, so its folders land inside it.
7136            let container = [(
7137                "HOME",
7138                "/Users/ada/Library/Containers/dev.example.notes/Data",
7139            )];
7140            assert_eq!(
7141                at(Os::Apple, Dir::Data, &container).as_deref(),
7142                Some(
7143                    "/Users/ada/Library/Containers/dev.example.notes/Data/Library/Application Support/dev.example.notes"
7144                )
7145            );
7146        }
7147
7148        #[test]
7149        fn windows_keeps_data_local_and_settings_roaming() {
7150            let vars = [
7151                ("LOCALAPPDATA", r"C:\Users\ada\AppData\Local"),
7152                ("APPDATA", r"C:\Users\ada\AppData\Roaming"),
7153            ];
7154            let data = at(Os::Windows, Dir::Data, &vars).unwrap_or_default();
7155            assert!(data.starts_with(r"C:\Users\ada\AppData\Local"), "{data}");
7156            assert!(data.ends_with("dev.example.notes"), "{data}");
7157            let cache = at(Os::Windows, Dir::Cache, &vars).unwrap_or_default();
7158            assert!(cache.ends_with("cache"), "{cache}");
7159            let config = at(Os::Windows, Dir::Config, &vars).unwrap_or_default();
7160            assert!(
7161                config.starts_with(r"C:\Users\ada\AppData\Roaming"),
7162                "{config}"
7163            );
7164        }
7165
7166        #[test]
7167        fn unix_follows_xdg_then_home() {
7168            let xdg = [
7169                ("HOME", "/home/ada"),
7170                ("XDG_DATA_HOME", "/data"),
7171                ("XDG_CACHE_HOME", "/cache"),
7172                ("XDG_CONFIG_HOME", "/config"),
7173            ];
7174            assert_eq!(
7175                at(Os::Unix, Dir::Data, &xdg).as_deref(),
7176                Some("/data/dev.example.notes")
7177            );
7178            assert_eq!(
7179                at(Os::Unix, Dir::Cache, &xdg).as_deref(),
7180                Some("/cache/dev.example.notes")
7181            );
7182            assert_eq!(
7183                at(Os::Unix, Dir::Config, &xdg).as_deref(),
7184                Some("/config/dev.example.notes")
7185            );
7186            let home = [("HOME", "/home/ada")];
7187            assert_eq!(
7188                at(Os::Unix, Dir::Data, &home).as_deref(),
7189                Some("/home/ada/.local/share/dev.example.notes")
7190            );
7191            assert_eq!(
7192                at(Os::Unix, Dir::Cache, &home).as_deref(),
7193                Some("/home/ada/.cache/dev.example.notes")
7194            );
7195            assert_eq!(
7196                at(Os::Unix, Dir::Config, &home).as_deref(),
7197                Some("/home/ada/.config/dev.example.notes")
7198            );
7199        }
7200
7201        #[test]
7202        fn hosts_and_tests_override_every_platform() {
7203            let host = [
7204                ("DAY_DATA_DIR", "/data/user/0/dev.example.notes/files"),
7205                ("DAY_CACHE_DIR", "/data/user/0/dev.example.notes/cache"),
7206            ];
7207            for os in [Os::Hosted, Os::Apple, Os::Windows, Os::Unix] {
7208                assert_eq!(
7209                    at(os, Dir::Data, &host).as_deref(),
7210                    Some("/data/user/0/dev.example.notes/files")
7211                );
7212                assert_eq!(
7213                    at(os, Dir::Cache, &host).as_deref(),
7214                    Some("/data/user/0/dev.example.notes/cache")
7215                );
7216            }
7217            let scratch = [("HOME", "/Users/ada"), ("DAY_DATA_DIR", "/tmp/run")];
7218            assert_eq!(
7219                at(Os::Apple, Dir::Cache, &scratch).as_deref(),
7220                Some("/tmp/run/cache")
7221            );
7222            assert_eq!(
7223                at(Os::Apple, Dir::Config, &scratch).as_deref(),
7224                Some("/tmp/run/config")
7225            );
7226            // Without a host directory there is nowhere to put anything.
7227            assert_eq!(at(Os::Hosted, Dir::Data, &[("HOME", "/")]), None);
7228            assert_eq!(at(Os::Web, Dir::Data, &[("HOME", "/")]), None);
7229        }
7230
7231        #[test]
7232        fn app_ids_become_one_folder_name() {
7233            assert_eq!(folder_name("dev.daybrite.news"), "dev.daybrite.news");
7234            assert_eq!(folder_name("a/b\\c:d"), "a_b_c_d");
7235            assert_eq!(folder_name(".."), "day-app");
7236            assert_eq!(folder_name(""), "day-app");
7237        }
7238    }
7239}
7240
7241// ---------------------------------------------------------------------------
7242// The Toolkit trait (§8.1)
7243// ---------------------------------------------------------------------------
7244
7245/// Timing supplied by a native display scheduler. Seconds on a monotonic clock; its epoch
7246/// is platform-specific. `target_timestamp` is absent when the platform cannot predict presentation.
7247#[derive(Clone, Copy, Debug, PartialEq)]
7248pub struct FrameStamp {
7249    pub timestamp: f64,
7250    pub target_timestamp: Option<f64>,
7251}
7252impl FrameStamp {
7253    pub fn new(timestamp: f64) -> Self {
7254        Self {
7255            timestamp,
7256            target_timestamp: None,
7257        }
7258    }
7259}
7260/// A one-shot native frame callback, always delivered asynchronously on the UI thread.
7261pub type FrameCallback = Box<dyn FnOnce(FrameStamp)>;
7262/// Cancels a pending callback and releases its native registration. UI-thread only, idempotent
7263/// in effect, and safe during/after delivery. Dropping without calling is allowed after delivery.
7264pub type CancelFrame = Box<dyn FnOnce()>;
7265
7266/// The margins and minimum height a native list gives each row ([`Toolkit::list_row_metrics`],
7267/// docs/list.md "Row metrics"): a `UITableView` cell's layout margins, a Material list item's
7268/// 16dp sides and 56dp height.
7269#[derive(Clone, Copy, Debug, Default, PartialEq)]
7270pub struct RowMetrics {
7271    /// Space between the row's edges and its content.
7272    pub insets: Insets,
7273    /// The least height a row takes, margins included; content centers vertically in it.
7274    pub min_height: f64,
7275}
7276
7277pub trait Toolkit: Sized + 'static {
7278    // `'static` so a handle clone can cross the object-safe TreeOps boundary boxed as `Any`
7279    // (`node_handle_any`, the tweaks door, docs/tweaks.md).
7280    type Handle: Clone + 'static;
7281
7282    /// Request one frame for the window containing `host`. Never call inline. Each native source
7283    /// must stop after delivery unless requested again; no polling timer. Hidden/unmapped windows
7284    /// may defer delivery until visible. Native callbacks must reach the UI thread before calling
7285    /// Rust. The returned closure cancels safely, including when the window has closed.
7286    /// The mock intentionally stays pending: tests inject a manual scheduler in day-core.
7287    fn request_frame(&mut self, _host: &Self::Handle, _cb: FrameCallback) -> CancelFrame {
7288        Box::new(|| {})
7289    }
7290
7291    fn capability(&self, _cap: Cap) -> Support {
7292        Support::Unsupported
7293    }
7294
7295    // node lifecycle
7296    fn realize(&mut self, kind: PieceKind, props: &dyn Any, id: NodeId) -> Self::Handle;
7297    fn update(
7298        &mut self,
7299        h: &Self::Handle,
7300        kind: PieceKind,
7301        patch: &dyn Any,
7302        anim: Option<&AnimSpec>,
7303    );
7304    /// Called from the turn-boundary release queue; backends may defer destruction further.
7305    fn release(&mut self, h: Self::Handle);
7306    /// Give a satellite piece a chance to drop its own per-view state, immediately before
7307    /// [`release`](Toolkit::release) frees `h` (§15.2).
7308    ///
7309    /// A backend that hosts third-party pieces implements this by looking `kind` up in its renderer
7310    /// registry and calling that piece's `release` hook. Defaulted to nothing: a backend with no
7311    /// registry has nothing to dispatch, and one that has not wired this yet leaves piece
7312    /// teardown unrun rather than failing to build.
7313    fn release_piece(&mut self, _kind: PieceKind, _h: &Self::Handle) {}
7314
7315    // tree
7316    fn insert(&mut self, parent: &Self::Handle, child: &Self::Handle, index: usize);
7317    fn remove(&mut self, parent: &Self::Handle, child: &Self::Handle);
7318    /// Put `child` at index `to` among `parent`'s native children: day's z-order resync, which
7319    /// walks the whole sibling row and asks for every position in turn. A child already at `to`
7320    /// must therefore cost nothing: a backend that re-parents unconditionally pays for the
7321    /// untouched siblings too, and where re-parenting means detach-then-add (no ViewGroup move
7322    /// primitive on Android) the detach resigns the focus of everything inside the subtree,
7323    /// which is how a text field being typed into loses the keyboard (docs/focus.md).
7324    fn move_child(&mut self, parent: &Self::Handle, child: &Self::Handle, to: usize);
7325
7326    // geometry (§7): frames are in the nearest realized native ancestor's space, in points.
7327    fn measure(&mut self, h: &Self::Handle, kind: PieceKind, p: Proposal) -> Size;
7328    /// Distance from the top of the widget's frame to its first text baseline, in points, when
7329    /// the widget is `size` (docs/baseline.md). `None` ⇒ it has no text baseline (an image, a
7330    /// slider, a bare container) and a baseline-aligned row falls back to box alignment for it.
7331    ///
7332    /// This is a measurement, not a layout mode: day places every frame itself (§7.1) and never
7333    /// hands a row to a native baseline-aligning container, so what it needs from the toolkit is
7334    /// where the text sits inside the box. Backends that cannot answer keep the default and rows
7335    /// stay centered, which is what every row did before this existed.
7336    fn first_baseline(&mut self, _h: &Self::Handle, _kind: PieceKind, _size: Size) -> Option<f64> {
7337        None
7338    }
7339    fn set_frame(&mut self, h: &Self::Handle, frame: Rect, anim: Option<&AnimSpec>);
7340
7341    // animatable visual channels (§8.4): cheap per-node opacity + transform that don't relayout.
7342    // Defaulted no-ops so backends adopt them incrementally; `anim = Some` ⇒ animate to the value
7343    // on the toolkit's own compositor, `None` ⇒ set instantly.
7344    fn set_opacity(&mut self, _h: &Self::Handle, _opacity: f64, _anim: Option<&AnimSpec>) {}
7345    fn set_transform(
7346        &mut self,
7347        _h: &Self::Handle,
7348        _t: Transform,
7349        _size: Size,
7350        _anim: Option<&AnimSpec>,
7351    ) {
7352    }
7353
7354    // text selection (docs/text.md): make this node's text user-selectable (copy/drag). Applied
7355    // once from the `.selectable()` modifier (day-pieces) to the widget it wraps (a `label`'s
7356    // native text view, most usefully). Unmanaged: Day sets it here and never patches it, so it
7357    // survives text updates. The default no-op means a backend without a selection affordance
7358    // silently leaves the text unselectable.
7359    //
7360    // Returns `Some(replacement)` when the toolkit had to rebuild the widget as a different
7361    // native class to gain a selection affordance (UIKit: `UILabel` has none, so the label
7362    // becomes a read-only `UITextView`); day-core re-points the node's handle at the
7363    // replacement, so later patches and layout reach the widget that is actually on screen.
7364    // Every property-flip backend returns `None`.
7365    fn set_selectable(&mut self, _h: &Self::Handle, _selectable: bool) -> Option<Self::Handle> {
7366        None
7367    }
7368
7369    // text entry (docs/textfield.md): how a `text_field` takes its text: hidden characters,
7370    // read-only, the keyboard and autofill purpose, the action key, the length bound. Called
7371    // once after `realize` when a field asks for anything but the defaults, and again with the
7372    // whole set whenever a reactive member changes, so the setter is idempotent.
7373    //
7374    // Returns `Some(replacement)` when hiding the characters takes a different native class
7375    // (AppKit: `NSSecureTextField`; WinUI: `PasswordBox`), the same contract as
7376    // `set_selectable`: the backend carries the text, the placeholder and its own event wiring
7377    // over, takes the old widget's place in the native tree, and day-core re-points the node's
7378    // handle. Required, with no default: a backend that left this out would show a password in
7379    // the clear. A member the toolkit has no notion of (an action key on a desktop) is ignored.
7380    fn set_input_traits(&mut self, h: &Self::Handle, traits: &InputTraits) -> Option<Self::Handle>;
7381
7382    // pointer shape (docs/cursor.md): the cursor to show while the pointer is over this node
7383    // and its descendants, from the `.cursor()` modifier. Called again whenever a reactive
7384    // cursor changes, so the setter is idempotent and cheap; `Cursor::Default` releases the
7385    // node. The default no-op is a backend with no pointer API to reach (`Cap::Cursor`
7386    // answers `Unsupported` there).
7387    fn set_cursor(&mut self, _h: &Self::Handle, _cursor: Cursor) {}
7388
7389    /// Show or hide a retained subtree, including its input and accessibility participation.
7390    /// The layout and reactive scope stay alive while hidden.
7391    fn set_presented(&mut self, _h: &Self::Handle, _visible: bool) {}
7392
7393    /// Attach overscroll delivery to a refresh host; the caller owns the mounted scope.
7394    fn attach_refresh(&mut self, _h: &Self::Handle, _host: NodeId) {}
7395
7396    // scroll (§7.6)
7397    fn set_scroll_content(&mut self, _h: &Self::Handle, _content: Size) {}
7398    // The room a classic (non-overlay) scroll bar takes out of a scroll view's content area
7399    // while the content overflows along `vertical`'s axis: its width for a vertical scroll, its
7400    // height for a horizontal one (docs/scroll.md). Day lays overflowing content out that much
7401    // narrower, so it fits beside the bar instead of reaching under it. 0 — the default — is
7402    // every backend whose bars overlay the content (AppKit, GTK, UIKit, Android, XAML, DOM).
7403    fn scroll_bar_inset(&mut self, _h: &Self::Handle, _vertical: bool) -> f64 {
7404        0.0
7405    }
7406    // The margins and minimum height the platform's own list gives a row (docs/list.md "Row
7407    // metrics"), asked of list `h` each time day-core lays a row. Day insets the row's content by
7408    // the margins and keeps it at least that tall, so a row reads at the platform's size without
7409    // the app padding it per platform. Zero — the default — leaves the row to its content.
7410    fn list_row_metrics(&mut self, _h: &Self::Handle) -> RowMetrics {
7411        RowMetrics::default()
7412    }
7413    fn scroll_to(&mut self, _h: &Self::Handle, _target: Rect, _animated: bool) {}
7414    /// Scroll a native navigation menu to its top or bottom without changing selection.
7415    /// The widget owns its content extent. Return false when the handle is unsupported.
7416    fn nav_scroll_to_edge(&mut self, _h: &Self::Handle, _bottom: bool) -> bool {
7417        false
7418    }
7419    fn scroll_offset(&mut self, _h: &Self::Handle) -> Point {
7420        Point::ZERO
7421    }
7422
7423    // events: one trampoline, node-id keyed; enqueue-only contract (§8.3).
7424    fn set_event_sink(&mut self, sink: EventSink);
7425
7426    // gestures (docs/shapes.md): attach a native recognizer for `kind` to `h`, emitting
7427    // `Event::Tap/LongPress/Drag` for `node` (enqueue-only). Default no gesture; a piece opts in
7428    // when it has a handler. Idempotent per (handle, kind).
7429    fn enable_gesture(&mut self, _h: &Self::Handle, _node: NodeId, _kind: GestureKind) {}
7430
7431    // focus (docs/focus.md): move native keyboard focus to (or away from) this control.
7432    // `focused = true` requests focus (on mobile this also raises the soft keyboard for text
7433    // inputs); `false` resigns it (dismissing the keyboard; platforms without a "focus nothing"
7434    // state resign to a focusable root). Backends report the resulting state, user- or
7435    // programmatic, with `Event::FocusChanged(bool)` through the sink; a request that cannot
7436    // be honored (unfocusable, unmounted) produces no event. The default no-op means a
7437    // backend without focus support neither moves nor reports focus.
7438    fn focus(&mut self, _h: &Self::Handle, _node: NodeId, _focused: bool) {}
7439
7440    // focusability (docs/focus.md): opt this container into the platform's focus system, the
7441    // canvas contract generalized (`Decorate::focusable`). A focusable container accepts focus,
7442    // takes it on a press (before the press reaches its gesture recognizers), reports both
7443    // directions with `Event::FocusChanged`, and delivers the non-text keys it hears while
7444    // focused as `Event::Key` for `node` (gated on `keys::handled`, like a canvas). The default
7445    // no-op means the piece renders normally but never joins the focus order: `.focused(…)`
7446    // bindings stay quiet and `.on_key(…)` never fires, the same graceful silence unfocusable
7447    // controls already have. Idempotent; only `true` is ever sent today (a piece opts in at
7448    // build, it does not opt back out).
7449    fn set_focusable(&mut self, _h: &Self::Handle, _node: NodeId, _focusable: bool) {}
7450
7451    // recycling list (docs/list.md, §10): day-core hands the `LIST` host its row-pull `source`
7452    // once, right after realize. A recycling backend stores it and calls it from its native
7453    // data-source; the default no-op means a backend without list support renders nothing.
7454    fn attach_list(&mut self, _host: &Self::Handle, _source: ListSource) {}
7455
7456    // hierarchical tree (docs/tree.md): day-core hands the `TREE` host its token-addressed
7457    // row-pull `source` once, right after realize. A backend with a native tree stores it and
7458    // answers its data-source from it; the default no-op means a backend without tree support
7459    // renders nothing (`Cap::Tree` answers `Unsupported`, and apps gate on that).
7460    fn attach_tree(&mut self, _host: &Self::Handle, _source: TreeSource) {}
7461
7462    // routes (docs/navigation.md): day-core reports the app's current route path here whenever
7463    // it changes ("" = everything at its root), so a backend with a native notion of location
7464    // can mirror it: web-dom writes the URL hash (`#controls`), and browser back/forward or a
7465    // hand-edited hash comes back as `Event::RouteRequested`. Default no-op: most toolkits
7466    // have nowhere to put a route.
7467    fn set_route(&mut self, _route: &str) {}
7468
7469    // undo bridge (docs/model.md): mirror the app's undo stack into the platform's own undo
7470    // objects, so the stock Edit menu retitles and enables itself and the platform's gestures
7471    // land: the native front of one Day-owned history. The state flows down whenever it
7472    // changes; the user's invocation comes back up as `Event::Undo`. Default no-op: a backend
7473    // without a native undo system answers `Cap::UndoBridge` `Unsupported`, and the app's own
7474    // affordances (menu items, buttons, accelerators) drive the stack instead.
7475    fn set_undo_state(&mut self, _state: &UndoState) {}
7476
7477    // edit bridge (docs/menus.md): mirror what the app's standard-edit handlers can do, so
7478    // the platform's own menu validation enables Cut/Copy/Paste exactly as it does for text
7479    // widgets; invocations come back up as `Event::Edit`. Default no-op: a backend without
7480    // a native edit-command route answers `Cap::EditBridge` accordingly.
7481    fn set_edit_state(&mut self, _state: &EditState) {}
7482
7483    // ambient modifiers (docs/menus.md): the keyboard modifiers held right now, for
7484    // interactions whose meaning they change (shift-click multi-select). Pull-based: the
7485    // platforms expose exactly this query (NSEvent.modifierFlags, the shim's tracked mask).
7486    // Touch-only backends keep the all-false default.
7487    fn modifiers(&mut self) -> Modifiers {
7488        Modifiers::default()
7489    }
7490
7491    // Dynamic context menu (docs/menus.md): the menu is built when it is summoned. The provider
7492    // is called synchronously from the platform's own menu callback (UI thread, outside any
7493    // day-core borrow) with the location in the node's local coordinates, and its result is
7494    // shown. The static `set_context_menu` below stays the simple path; this one exists for
7495    // surfaces whose menu depends on what is under the pointer (a canvas selection,
7496    // docs/tree.md). Default no-op: a backend without the affordance shows nothing.
7497    fn set_drag_source(&mut self, _h: &Self::Handle, _source: transfer::Source) {}
7498    fn set_drop_target(&mut self, _h: &Self::Handle, _target: transfer::Target) {}
7499
7500    fn set_context_menu_fn(&mut self, _h: &Self::Handle, _node: NodeId, _f: ContextMenuFn) {}
7501
7502    // menus (§ menus): render `items` with the backend's native menu affordance, firing
7503    // `Event::MenuAction(id)` (enqueue-only) for each id'd item; `role` items use the native standard
7504    // command. Default no-op: a toolkit without a menu bar / context menu shows nothing.
7505    /// The application menu (macOS/Windows/Linux menu bar; the app-bar overflow on Android; the
7506    /// UIMenuBuilder main menu on iPadOS/Catalyst). Replaces any previous app menu.
7507    fn set_app_menu(&mut self, _items: &[MenuItem]) {}
7508    /// A context menu for `h`, shown on secondary-click (desktop) or long-press (mobile). Passing an
7509    /// empty slice removes it.
7510    fn set_context_menu(&mut self, _h: &Self::Handle, _node: NodeId, _items: &[MenuItem]) {}
7511
7512    // toolbars (docs/toolbars.md): a window's native toolbar: NSToolbar, AdwHeaderBar, QToolBar,
7513    // CommandBar. `h` is the window root's handle (the same handle `open_window` returned, or the
7514    // primary root's); the backend walks from it to the window it belongs to. Default no-op: a
7515    // toolkit with no toolbar shows nothing rather than a drawn imitation, and reports
7516    // `Cap::Toolbar` as `Unsupported` so an app can put the command somewhere else.
7517    /// Edit the window's toolbar (docs/toolbars.md): the [`ToolbarOp`]s, removals first, then
7518    /// insertions in ascending position. The bar starts empty, and becomes empty again when every
7519    /// item has been removed, at which point the backend takes it off the window.
7520    ///
7521    /// An item no op names must keep its native widget untouched, which is what keeps a search
7522    /// field focused while the page around it changes. Day sends an edit only when the bar
7523    /// changed, at most once per turn, and an item keeps its [`ToolbarItem::action`] for as long
7524    /// as its window shows an item with that id, so a native item's handler never needs
7525    /// repointing. Keep a [`ToolbarMirror`] and place each new item after
7526    /// [`ToolbarMirror::prev_where`] its group.
7527    ///
7528    /// Returns whether the edit was applied. `false` (the window has no bar to edit yet) makes
7529    /// Day send the whole bar again at the next change rather than assume this one landed.
7530    fn edit_toolbar(&mut self, _h: &Self::Handle, _ops: &[ToolbarOp]) -> bool {
7531        true
7532    }
7533    /// Apply a targeted change to one live toolbar item, the path a bound signal writes through,
7534    /// so syncing a search field does not rebuild the bar. No-op if the item is not present.
7535    fn update_toolbar(&mut self, _h: &Self::Handle, _patch: &ToolbarPatch) {}
7536
7537    // lifecycle (docs/lifecycle.md): does this backend deliver `phase`? The default answers "yes" for
7538    // the universal phases (launch/activation/termination) and "no" for the mobile-only ones. Backends
7539    // that wire up more (the mobile ones) override this; it must agree with the crate's
7540    // `const fn lifecycle_supported`, which drives compile-time guards in `day::require_lifecycle!`.
7541    fn supports_lifecycle(&self, phase: Lifecycle) -> bool {
7542        phase.is_universal()
7543    }
7544
7545    // pillars
7546    /// Apply a node's accessibility annotations (docs/accessibility.md): the label, hint and
7547    /// value the screen reader speaks, an explicit role, whether the node is hidden from
7548    /// assistive technology, and the automation identifier. Called with the node's whole
7549    /// accumulated set each time any of it changes, so every member is written on every call.
7550    /// Only an explicit role is applied: a native control reports its own.
7551    fn set_a11y(&mut self, _h: &Self::Handle, _a11y: &A11yProps) {}
7552    /// Speak `text` through the screen reader without moving its focus (docs/accessibility.md;
7553    /// probe [`Cap::Announce`]). `urgent` interrupts what is being read; otherwise the sentence
7554    /// waits its turn. Nothing happens when no screen reader is running. The default is a
7555    /// backend that reaches no announcement API.
7556    fn announce(&mut self, _text: &str, _urgent: bool) {}
7557    /// Read a widget's native state back from the platform for `a11y_audit` and
7558    /// `assert_native` (§14.2, docs/testing.md) to diff against Day's expectation. Default:
7559    /// nothing read; the audit skips the node and `assert_native` records each field as unread.
7560    fn read_native(&self, _h: &Self::Handle) -> NativeSnapshot {
7561        NativeSnapshot::default()
7562    }
7563    fn replay(&mut self, _h: &Self::Handle, _ops: &[DrawOp], _size: Size) {}
7564
7565    /// Every family this toolkit can draw canvas text in, with the faces each ships
7566    /// (docs/fonts.md; probe [`Cap::FontList`]). Default: none. `day::font_families` calls
7567    /// this once per process and caches the answer: enumeration is slow on every platform
7568    /// (fontconfig, a DirectWrite collection, an XML parse on Android) and the set does not
7569    /// change under a running app.
7570    fn font_families(&mut self) -> Vec<FontFamilyInfo> {
7571        Vec::new()
7572    }
7573
7574    /// Measure one line of canvas text at `size` points in `font`, in the same engine
7575    /// [`Toolkit::replay`] draws [`DrawOp::Text`] with, so a `TextAnchor::LEADING` anchor plus
7576    /// the returned `ascent` lands on the drawn baseline. `None` = cannot measure; the facade
7577    /// then answers [`TextMetrics::approximate`].
7578    fn measure_text(&mut self, _text: &str, _size: f64, _font: &CanvasFont) -> Option<TextMetrics> {
7579        None
7580    }
7581    // --- raster images (docs/images.md) -------------------------------------------------
7582    //
7583    // Request-id shaped rather than blocking, because one backend can never answer
7584    // synchronously: a browser decodes through `createImageBitmap`, which is a promise. Every
7585    // other backend decodes inline and raises the completion before returning, so the shape
7586    // costs them nothing but a line, and the app-facing API can be one thing everywhere
7587    // instead of two (docs/async.md rule 3: a callback and a future, never a runtime).
7588
7589    /// Decode encoded image bytes (PNG/JPEG/…) into a native image, answering `req` with
7590    /// [`Event::ImageDecoded`].
7591    ///
7592    /// The id in that event is minted by the caller (day-core), not the backend: the backend
7593    /// keeps its own side table from that id to whatever it decoded.
7594    ///
7595    /// The default does nothing because a default body cannot reach the event sink
7596    /// (it is installed per backend by [`Toolkit::set_event_sink`], not reachable through this
7597    /// trait), so there is no way for it to answer. day-core asks [`Cap::ImageDecode`] first and
7598    /// resolves the request as [`ImageError::Unsupported`] itself, which is why a backend with
7599    /// no decoder needs no code here at all.
7600    fn decode_image(&mut self, _req: u64, _id: BitmapId, _bytes: &[u8]) {}
7601
7602    /// What a decoded image is: pixel size, scale, format, alpha ([`BitmapInfo`]).
7603    ///
7604    /// Synchronous: every backend that decoded the image already holds these facts. `None` means
7605    /// the id names nothing live.
7606    fn image_info(&mut self, _id: BitmapId) -> Option<BitmapInfo> {
7607        None
7608    }
7609
7610    /// The metadata beyond the pixels: EXIF orientation, DPI, capture time
7611    /// ([`ImageProperties`], probe [`Cap::ImageProperties`]). `None` where the backend has no
7612    /// metadata reader, which is most of them.
7613    fn image_properties(&mut self, _id: BitmapId) -> Option<ImageProperties> {
7614        None
7615    }
7616
7617    /// Encode a decoded image back to bytes per `spec`, answering `req` with
7618    /// [`Event::ImageEncoded`]. A format outside [`Self::encode_formats`] answers
7619    /// [`ImageError::Encode`] rather than silently substituting another one.
7620    ///
7621    /// Defaulted to nothing for the same reason as [`Self::decode_image`]: day-core probes
7622    /// [`Cap::ImageEncode`] and answers `Unsupported` without ever calling this.
7623    fn encode_image(&mut self, _req: u64, _id: BitmapId, _spec: &EncodeSpec) {}
7624
7625    /// Which formats [`Self::encode_image`] can write, the [`Cap::ImageEncode`]
7626    /// counterpart of [`Self::font_families`]/[`Cap::FontList`]. Empty by default.
7627    fn encode_formats(&mut self) -> Vec<ImageFormat> {
7628        Vec::new()
7629    }
7630
7631    /// Drop a decoded image and everything the backend cached for it. Called when the app's
7632    /// last handle to it goes away; an id the backend never saw is a no-op.
7633    fn release_image(&mut self, _id: BitmapId) {}
7634
7635    // --- canvas export (docs/canvas.md "Exporting") --------------------------------------
7636    //
7637    // Request-id shaped like the image duties above, for the same reason: the browser's
7638    // `createImageBitmap` is a promise. Every other backend renders inline and raises the
7639    // completion before returning. day-core validates sizes, enforces the pixel limits and
7640    // probes the caps first, so a backend sees only requests it can attempt.
7641
7642    /// Replay `ops` into a new offscreen bitmap of `size` points at `scale` pixels per point
7643    /// ([`export_pixels`] gives the pixel size), with a transparent background and the
7644    /// canvas's top-left origin. Store it under `id` in the same table [`Self::decode_image`]
7645    /// fills, so `image_info`, `encode_image`, `release_image`, the `image` piece and
7646    /// [`DrawOp::Image`] all take it, then answer `req` with [`Event::BitmapRendered`] (its
7647    /// [`BitmapInfo::scale`] is `scale`).
7648    ///
7649    /// The painter must be the one [`Self::replay`] uses, so text, gradients, clips and stamps
7650    /// match the screen. Defaulted to nothing: day-core probes [`Cap::CanvasBitmap`] and answers
7651    /// [`ExportError::Unsupported`] itself.
7652    fn render_bitmap(
7653        &mut self,
7654        _req: u64,
7655        _id: BitmapId,
7656        _ops: &[DrawOp],
7657        _size: Size,
7658        _scale: f64,
7659    ) {
7660    }
7661
7662    /// Replay each page into one PDF document and answer `req` with [`Event::PdfRendered`].
7663    /// Units are PDF points, top-left origin; shapes and text stay vector, and images embed at
7664    /// their pixel size. `pages` is never empty. Defaulted to nothing: day-core probes
7665    /// [`Cap::CanvasPdf`] first.
7666    fn render_pdf(&mut self, _req: u64, _pages: &[PdfPage], _info: &PdfInfo) {}
7667
7668    fn snapshot_window(&mut self) -> Result<Vec<u8>, String> {
7669        Err("snapshot unsupported".into())
7670    }
7671    /// Where `root`, the primary window's root container, sits in [`Self::snapshot_window`]'s
7672    /// image, in points from its top-left. A reader of the capture (dayscript `sample_pixel`)
7673    /// maps Day's frames into it with this; it matters where the capture spans more than Day's
7674    /// content on more than one side, as Android's edge-to-edge content does (status bar
7675    /// above, navigation bar below).
7676    ///
7677    /// Defaulted to `None`, which the reader takes as "any rows beyond Day's content are
7678    /// above it", true where the only extra area is a title bar.
7679    fn snapshot_origin(&mut self, _root: &Self::Handle) -> Option<Point> {
7680        None
7681    }
7682    /// Establish a fresh screenshot checkpoint after reactive work and native transitions.
7683    /// `revision` is stable across retries and unique to the request; `host` selects a
7684    /// secondary window, or None for the primary. Never block the UI thread waiting for
7685    /// a frame. Pending requests are retried within the dayscript deadline.
7686    ///
7687    /// Ready means the platform render checkpoint completed, not that a vsync callback
7688    /// proves pixels were displayed. OnCapture delegates freshness to snapshot_window.
7689    fn prepare_snapshot(
7690        &mut self,
7691        _host: Option<&Self::Handle>,
7692        _revision: u32,
7693    ) -> Result<capture::Readiness, String> {
7694        // Compatible with external toolkits predating this hook: their synchronous
7695        // snapshot owns freshness, and no external-capture acknowledgment is fabricated.
7696        Ok(capture::Readiness::OnCapture)
7697    }
7698
7699    /// The same capture with the window's own chrome: title bar, toolbar, whatever the platform
7700    /// draws around the content (docs/window-image.md).
7701    ///
7702    /// Defaulted to [`Self::snapshot_window`]: a backend that cannot separate the two
7703    /// (or has no chrome to speak of, a phone) answers with the content shot rather than an
7704    /// error, so an app asking for chrome degrades to "what there was" instead of failing. The
7705    /// dayscript `screenshot` step never calls this, which is what keeps every captured gallery
7706    /// baseline byte-identical to before it existed.
7707    fn snapshot_window_chrome(&mut self) -> Result<Vec<u8>, String> {
7708        self.snapshot_window()
7709    }
7710    /// Show/hide the sidebar pane of the navigation host `host`, which is what the sidebar
7711    /// affordance a `nav(Sidebar)` contributes for itself drives ([`SIDEBAR_TOGGLE_ID`]).
7712    /// `false` when `host` has no pane to toggle (a stack, a tab bar, no sidebar concept at all).
7713    ///
7714    /// Per host, not per process: a second window's button collapses that window's sidebar
7715    /// and not the first's. The item's own action makes the call, and dayscript's `toolbar:`
7716    /// step presses the item like any other, so a walkthrough drives exactly the path a click
7717    /// takes. Defaulted, so a backend with no sidebar needs no code. docs/toolbars.md,
7718    /// docs/navigation.md.
7719    fn toggle_sidebar(&mut self, _host: &Self::Handle) -> bool {
7720        false
7721    }
7722    /// Press the platform's own back affordance (the navigation bar's back button on iOS,
7723    /// the system back on Android) on the innermost navigation host that has something to
7724    /// pop. What `nav_back()` does not do: that is Day's rail, which pops the model and lets the
7725    /// backend follow, while this runs the native path first (the bar's `shouldPop`, the
7726    /// dispatcher's callbacks, the pop itself) and lets the backend report it to Day as a user
7727    /// back, guard and all. dayscript's `nav_back: { native: true }` drives it, so a walkthrough
7728    /// can cover the code that a real tap runs and Day's rail never reaches. `false` when this
7729    /// toolkit has no native back or nothing is popped by it. Defaulted, so a desktop needs no
7730    /// code. docs/navigation.md.
7731    fn native_back(&mut self) -> bool {
7732        false
7733    }
7734    /// Whether the UI has settled, with no native transition (modal present/dismiss, nav push)
7735    /// still animating. The dayscript `screenshot` step polls this before capturing so shots
7736    /// never catch a half-faded dialog or half-pushed page. Backends without async
7737    /// transitions (or without a way to know) report `true`.
7738    fn ui_idle(&mut self) -> bool {
7739        true
7740    }
7741
7742    // imperative presentation (docs/dialogs.md): show a native modal for request `req`;
7743    // the backend answers by enqueuing `Event::PresentResult { req, .. }`. `dismiss` is
7744    // used only when Day resolves programmatically (dayscript) while the modal is still up.
7745    fn present(&mut self, _req: u64, _spec: &present::PresentSpec) {}
7746    fn dismiss(&mut self, _req: u64) {}
7747
7748    /// Open `url` in the platform's default handler: the system browser for `http(s)`, the mail
7749    /// client for `mailto:`, etc. Backs the [`link`](/api/day_pieces/fn.link.html) piece. Fire and
7750    /// forget: there is no result, and an unopenable URL is ignored. The default no-ops so a
7751    /// backend that hasn't wired it up still compiles.
7752    fn open_url(&mut self, _url: &str) {}
7753
7754    /// Whether a native share chooser is available. Does not probe installed share targets.
7755    fn share_support(&self) -> Support {
7756        Support::Unsupported
7757    }
7758    /// Present the system share chooser. True means presentation started, not that sharing
7759    /// completed. Never sends data without the user's choice of a target.
7760    fn share_url(&mut self, _url: &str, _title: &str) -> bool {
7761        false
7762    }
7763
7764    /// Read current OS associations. Unsupported platforms must not fabricate a default.
7765    fn application_handlers(
7766        &mut self,
7767        _query: &applications::HandlerQuery,
7768    ) -> Result<applications::ApplicationHandlers, applications::ApplicationError> {
7769        Err(applications::ApplicationError::Unsupported)
7770    }
7771
7772    /// Open with an opaque application identifier returned by `application_handlers`.
7773    fn open_url_with_application(
7774        &mut self,
7775        _url: &str,
7776        _application: &str,
7777        completion: applications::OpenApplicationCompletion,
7778    ) {
7779        completion(Err(applications::ApplicationError::Unsupported));
7780    }
7781
7782    /// Ask the OS to require a second swipe for its edge gestures on `edges` (docs/cover.md):
7783    /// the union requested by every mounted `defers_system_gestures` modifier, re-sent whenever
7784    /// that set changes (`Edges::NONE` when the last one unmounts). iOS defers the home
7785    /// indicator / notification edges; Android enters swipe-to-reveal immersive mode while
7786    /// non-empty. The default no-ops (desktop has no system edge gestures).
7787    fn defer_system_gestures(&mut self, _edges: Edges) {}
7788
7789    /// Hide (`true`) or show the system status bar (docs/cover.md): whether any mounted
7790    /// `status_bar_hidden` modifier currently asks for it hidden, re-sent whenever that answer
7791    /// may have changed (`false` when the last request unmounts). iOS answers the root and
7792    /// cover view controllers' `prefersStatusBarHidden`; Android and HarmonyOS hide the status
7793    /// bar through their window inset controls. The default no-ops (desktop and web have no
7794    /// status bar); report `Cap::StatusBarHidden` alongside an implementation.
7795    fn set_status_bar_hidden(&mut self, _hidden: bool) {}
7796
7797    /// Whether the platform is rendering in dark appearance right now. Apps painting
7798    /// custom surfaces (opaque overlay panels, scrims) branch on this so their fills track
7799    /// the theme the default text colors already follow; hardcoding either theme's
7800    /// surface produces dark-on-dark or light-on-light text on the other. Queried at
7801    /// build time (a piece rebuilt after a theme change re-queries). The default honors a
7802    /// `DAY_THEME` launch override and otherwise answers light.
7803    fn dark_mode(&mut self) -> bool {
7804        std::env::var("DAY_THEME").ok().as_deref() == Some("dark")
7805    }
7806    /// Whether the user asked the system for less motion (docs/accessibility.md; probe
7807    /// [`Cap::ReduceMotion`]): macOS and iOS "Reduce Motion", Android "Remove animations" (an
7808    /// animator duration scale of zero), GTK's `gtk-enable-animations` off, Windows "Show
7809    /// animations" off, the web's `prefers-reduced-motion`. Read at launch; a backend that
7810    /// watches the setting calls `day_core::note_motion_changed` when it flips. Day then applies
7811    /// every finite animation at its destination and keeps only indeterminate motion. The default
7812    /// is a backend that reads no such setting.
7813    fn reduce_motion(&mut self) -> bool {
7814        false
7815    }
7816
7817    /// App-level appearance override: `Some(true)` forces dark, `Some(false)` forces light,
7818    /// `None` returns to following the system. Backends restyle their native widgets in
7819    /// place and answer the override from [`dark_mode`](Self::dark_mode); app-painted
7820    /// surfaces pick it up on their next rebuild. `Cap::Appearance` reports whether the
7821    /// backend honors this; the default ignores the call.
7822    fn set_appearance(&mut self, _dark: Option<bool>) {}
7823
7824    /// Put `badge` on the app's icon in the Dock / launcher / home screen (docs/badge.md).
7825    ///
7826    /// Fire-and-forget, like `set_appearance`: a payload this toolkit cannot render is ignored, and
7827    /// the app probes `Cap::AppBadge{Count,Text,Dot}` before choosing one. Never substitute: a
7828    /// backend that turned `Text("beta")` into `Count(1)` would put a wrong number on a user's
7829    /// icon, which is worse than showing nothing. The default ignores every call.
7830    fn set_app_badge(&mut self, _badge: &AppBadge) {}
7831
7832    // app lifecycle (mobile; desktop backends no-op)
7833    fn on_suspend(&mut self) {}
7834    fn on_resume(&mut self) {}
7835    fn on_memory_warning(&mut self) {}
7836
7837    // adoption of foreign native handles (polyglot pieces, §15.3)
7838    fn adopt(&mut self, _raw: RawHandle) -> Self::Handle {
7839        unimplemented!("this toolkit does not adopt foreign handles yet")
7840    }
7841
7842    // secondary windows (docs/windows.md)
7843
7844    /// Open a native OS window per `options` + `kind`: create and show the window, wire its
7845    /// events to `id` (`WindowResized` with the content size in points, `WindowClosed` after
7846    /// the native close, `WindowFocused` on key/active changes), and answer with its content
7847    /// container handle, the same contract as the `ready` root container. Backends whose
7848    /// window creation is asynchronous (a scene, an activity, an ability) answer
7849    /// [`WindowOpenReply::Pending`] and complete later through
7850    /// `day_core::finish_window_open(id, raw, size)`, which goes through [`Toolkit::adopt`].
7851    /// The default answers `Unsupported`; day-core then presents the content as a
7852    /// fullscreen cover in the primary window instead.
7853    fn open_window(
7854        &mut self,
7855        _id: NodeId,
7856        _options: &WindowOptions,
7857        _kind: WindowKind,
7858    ) -> WindowOpenReply<Self::Handle> {
7859        WindowOpenReply::Unsupported
7860    }
7861
7862    /// Close the native window whose content container is `host` (a handle `open_window`
7863    /// produced). Asynchronous: the platform confirms with `Event::WindowClosed` on the
7864    /// window's root node, and only then does day-core tear the subtree down. Idempotent; unknown
7865    /// hosts are ignored. Never called with the primary window's container.
7866    fn close_window(&mut self, _host: &Self::Handle) {}
7867
7868    /// End the application: the last window with [`WindowRole::Primary`] has closed
7869    /// (docs/windows.md). day-core decides when, since it owns the window registry and the role
7870    /// each window carries; the backend supplies only the platform's exit:
7871    /// `NSApplication.terminate`, `QCoreApplication::quit`, `GtkApplication.quit`,
7872    /// `PostQuitMessage`. Everything day-core wanted to happen first (secondary windows
7873    /// disposed, `WillTerminate` delivered) already has by the time this is called.
7874    ///
7875    /// The default does nothing, which is right for the backends whose process lifetime is
7876    /// not theirs to end: a browser tab, an Android activity, an iOS scene.
7877    fn quit_app(&mut self) {}
7878
7879    /// Bring the window whose content container is `host` to front and make it key/active:
7880    /// the focus half of open-or-focus singleton windows. Default no-op.
7881    fn focus_window(&mut self, _host: &Self::Handle) {}
7882
7883    /// Retitle the window whose content container is `host`. Default no-op.
7884    fn set_window_title(&mut self, _host: &Self::Handle, _title: &str) {}
7885
7886    /// Resize the window whose content container is `host` to fit `size` of content, and pin it
7887    /// there: what `WindowOptions::size_to_fit` asks for (docs/windows.md).
7888    ///
7889    /// `size` is the content size Day measured, not the window's outer frame: the backend adds
7890    /// its chrome. A settings panel is the case this exists for, and every desktop platform
7891    /// sizes one to its content rather than to a number the app guessed; a fixed height either
7892    /// clips the last row or leaves a band of empty panel under it, and which one you get depends
7893    /// on the user's text size.
7894    ///
7895    /// Default no-op, so a toolkit that cannot resize a live window keeps the size it was
7896    /// opened at, which is what every backend did before this existed.
7897    fn fit_window(&mut self, _host: &Self::Handle, _size: Size) {}
7898
7899    /// Snapshot the window whose content container is `host` (the dayscript `screenshot`
7900    /// step's `window:` target). The default answers the primary snapshot, so backends that
7901    /// never open windows stay correct without changes.
7902    fn snapshot_window_of(&mut self, _host: &Self::Handle) -> Result<Vec<u8>, String> {
7903        self.snapshot_window()
7904    }
7905
7906    /// Apply one property change to the window whose content container is `host`
7907    /// (docs/windows.md "Window properties"). The primary window arrives with its root container,
7908    /// like [`set_window_title`](Self::set_window_title).
7909    ///
7910    /// Fire-and-forget, like [`set_app_badge`](Self::set_app_badge): a change this toolkit cannot
7911    /// make is ignored, and the app probes the matching `Cap` (named on each [`WindowChange`]
7912    /// variant) before relying on it. A change the platform completes later (a fullscreen
7913    /// transition, a zoom animation) reports its outcome through
7914    /// [`Event::WindowStateChanged`], never by assuming the request took. The default ignores
7915    /// every change.
7916    fn apply_window(&mut self, _host: &Self::Handle, _change: &WindowChange) {}
7917
7918    /// True OS window groups, as distinct from native tab widgets.
7919    fn native_window_tabs(&self) -> bool {
7920        false
7921    }
7922    /// Native in-window document/section tab control; OS grouping is reported separately.
7923    fn native_document_tabs(&self) -> bool {
7924        false
7925    }
7926    /// Join/reorder these windows in an OS tab group. Content remains window-owned.
7927    fn group_windows(&mut self, _hosts: &[Self::Handle]) {}
7928    /// Current native order of the group containing this window, including detached groups.
7929    fn window_tab_order(&self, _host: &Self::Handle) -> Vec<NodeId> {
7930        Vec::new()
7931    }
7932
7933    /// Install the app's Dock menu (docs/menus.md "Dock menu"): the items macOS shows above
7934    /// its own when the user right-clicks the app's Dock icon, built from the app's
7935    /// `[[shortcuts]]` and its `dock_menu(..)` entries. Same item model and dispatch as
7936    /// [`set_app_menu`](Self::set_app_menu); an empty slice removes the menu. `Cap::DockMenu`
7937    /// reports support; the default ignores the call.
7938    fn set_dock_menu(&mut self, _items: &[MenuItem]) {}
7939
7940    /// Make the node at `h` move its window when the user drags it, as a title bar does
7941    /// (`.window_drag_region()`, docs/window-chrome.md): the region's own background starts a
7942    /// native window drag (with the platform's snapping and edge tiling), a double click does
7943    /// what the user's title-bar double-click setting says, and controls inside the region keep
7944    /// receiving their own clicks. `false` releases it. `Cap::DragRegion`; the default ignores
7945    /// the call, so on a phone the region is an ordinary view.
7946    fn set_drag_region(&mut self, _h: &Self::Handle, _drag: bool) {}
7947
7948    /// Show these status items, replacing the previous set (docs/status-item.md): add the
7949    /// ones whose `id` is new, update the ones that changed, remove the ones no longer listed.
7950    /// A click on an item runs its `activate` action or opens its menu; menu choices dispatch
7951    /// [`Event::MenuAction`] like the app menu's. `Cap::StatusItem`; the default ignores the
7952    /// call, which is what a phone and the web do.
7953    fn set_status_items(&mut self, _items: &[StatusItemSpec]) {}
7954
7955    /// Show `progress` on the app's Dock or taskbar icon (docs/status-item.md).
7956    /// `Cap::AppProgress`; the default ignores it.
7957    fn set_app_progress(&mut self, _progress: AppProgress) {}
7958
7959    /// Show or hide the app's Dock icon while it runs: a menu-bar app hides it and lives in its
7960    /// status item (macOS activation policy). `Cap::DockVisibility`; the default ignores it.
7961    fn set_dock_visible(&mut self, _visible: bool) {}
7962
7963    /// Keep the process running when its last window closes (docs/windows.md "Keeping the app
7964    /// running"). When `true`, the backend must not end the app on its own as windows close: it
7965    /// reports every close, the first window's included, as `Event::WindowClosed`, and day-core
7966    /// decides whether to call [`quit_app`](Self::quit_app). When `false`, the backend keeps its
7967    /// platform's own rule. A backend whose process lifetime is not its own (a phone, a browser
7968    /// tab) ignores it, which is the default.
7969    fn set_keep_running(&mut self, _keep: bool) {}
7970
7971    /// The displays attached now (docs/windows.md "Monitors"). `Cap::Monitors`; the default
7972    /// answers none, and day-core then describes the primary window's own size as one display.
7973    fn monitors(&self) -> Vec<Monitor> {
7974        Vec::new()
7975    }
7976
7977    /// The outer frame of the window whose content container is `host`, in points on the
7978    /// desktop's coordinate space (top-left origin), or `None` where the platform does not say
7979    /// (a phone, Wayland's positions). Read when the app asks for it and when day-core saves a
7980    /// remembered frame (`WindowOptions::remember_frame`).
7981    fn window_frame(&self, _host: &Self::Handle) -> Option<Rect> {
7982        None
7983    }
7984
7985    /// Replace the launcher shortcuts the app set while running (docs/deep-links.md "Launcher
7986    /// shortcuts"), shown beside the ones Day.toml declares: iOS Home Screen quick actions,
7987    /// Android dynamic shortcuts, the macOS Dock menu. Each opens its route through the deep-link
7988    /// intake. `Cap::DynamicShortcuts`; the default ignores the call.
7989    fn set_launcher_shortcuts(&mut self, _shortcuts: &[LauncherShortcut]) {}
7990}
7991
7992/// What a secondary window is, so backends can apply platform conventions (docs/windows.md).
7993#[derive(Clone, Copy, PartialEq, Eq, Debug)]
7994pub enum WindowKind {
7995    /// A regular document/tool window: resizable, miniaturizable, platform-default tabbing.
7996    Normal,
7997    /// A settings/preferences window: singleton by convention; macOS disallows window
7998    /// tabbing and drops the resize/minimize chrome, mobile presents it modally. Pairs with
7999    /// day-core's key-singleton reopen (`open_window` with a key).
8000    Preferences,
8001    /// The About window (docs/settings.md): the same fixed, centered, untabbed panel chrome
8002    /// as [`Self::Preferences`] (every desktop treats the two alike), presented modally on
8003    /// mobile. Singleton under day-core's `day.about` key.
8004    About,
8005}
8006
8007impl WindowKind {
8008    /// Whether this is a panel (settings or About) rather than a document window: the kinds
8009    /// every desktop draws fixed-size, centered and out of the Window menu, and mobile presents
8010    /// as a cover.
8011    pub fn is_panel(self) -> bool {
8012        !matches!(self, WindowKind::Normal)
8013    }
8014}
8015
8016/// Whether a window keeps the app alive (docs/windows.md close policy).
8017///
8018/// A separate axis from [`WindowKind`], which describes chrome. They correlate (a
8019/// preferences panel is the archetypal window that should not hold an app open), but they are
8020/// not the same question, and conflating them would leave no way to say "an ordinary-looking
8021/// tool window that shouldn't outlive the documents".
8022///
8023/// Note the word "secondary" is overloaded around windows: elsewhere in day it means "a window
8024/// other than the first one opened". Here it means "does not keep the app alive", which is
8025/// about lifetime, not about order of creation.
8026#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
8027pub enum WindowRole {
8028    /// Closing the last one of these ends the app.
8029    #[default]
8030    Primary,
8031    /// Never keeps the app alive: when the last `Primary` closes, the app exits and takes
8032    /// these with it, however many are open.
8033    Secondary,
8034}
8035
8036impl From<WindowKind> for WindowRole {
8037    /// The default pairing: an ordinary window holds the app open, a preferences panel does
8038    /// not. An app that needs a different answer sets the role itself.
8039    fn from(kind: WindowKind) -> WindowRole {
8040        match kind {
8041            WindowKind::Normal => WindowRole::Primary,
8042            WindowKind::Preferences | WindowKind::About => WindowRole::Secondary,
8043        }
8044    }
8045}
8046
8047/// A backend's answer to [`Toolkit::open_window`] (docs/windows.md).
8048pub enum WindowOpenReply<H> {
8049    /// The window exists now; here is its content container (desktop backends).
8050    Open(H),
8051    /// Native creation started but completes asynchronously (a scene, an activity, an
8052    /// ability); the backend will call `day_core::finish_window_open` when the content
8053    /// container exists. day-core parks the window record until then.
8054    Pending,
8055    /// This toolkit cannot open windows (`Cap::MultiWindow` = `Unsupported`); day-core
8056    /// falls back to presenting the content as a fullscreen cover in the primary window.
8057    Unsupported,
8058}
8059
8060/// How a window is shown (docs/windows.md "Window properties"): what the window's `state()`
8061/// signal holds and what [`WindowChange::State`] asks for.
8062#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
8063pub enum WindowState {
8064    /// On screen at its own size: neither minimized, maximized nor fullscreen.
8065    #[default]
8066    Normal,
8067    /// Minimized to the Dock, taskbar or shelf. `Cap::WindowStates`.
8068    Minimized,
8069    /// Zoomed to fill the screen's work area, keeping its chrome. `Cap::WindowStates`.
8070    Maximized,
8071    /// Covering the whole screen with no window chrome; on a phone, the system bars hidden.
8072    /// `Cap::WindowFullscreen`.
8073    Fullscreen,
8074}
8075
8076impl WindowState {
8077    /// The wire code of [`bridge::BridgeKind::WindowStateChanged`].
8078    pub const fn code(self) -> i32 {
8079        match self {
8080            WindowState::Normal => 0,
8081            WindowState::Minimized => 1,
8082            WindowState::Maximized => 2,
8083            WindowState::Fullscreen => 3,
8084        }
8085    }
8086
8087    /// The state a wire code names; an unknown code reads as `Normal`.
8088    pub const fn from_code(code: i32) -> WindowState {
8089        match code {
8090            1 => WindowState::Minimized,
8091            2 => WindowState::Maximized,
8092            3 => WindowState::Fullscreen,
8093            _ => WindowState::Normal,
8094        }
8095    }
8096}
8097
8098/// How a window stacks against other apps' windows ([`WindowChange::Level`], `Cap::WindowLevel`).
8099#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
8100pub enum WindowLevel {
8101    /// Ordinary stacking: the focused app's windows come forward.
8102    #[default]
8103    Normal,
8104    /// Stays above other apps' ordinary windows: a palette, a timer, a video peek.
8105    Floating,
8106}
8107
8108/// How strongly a window asks for the user's attention ([`WindowChange::RequestAttention`]).
8109#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
8110pub enum Attention {
8111    /// Once: one Dock bounce, a taskbar button that flashes a few times.
8112    #[default]
8113    Informational,
8114    /// Until the user switches to the app.
8115    Critical,
8116}
8117
8118/// One change to one window (docs/windows.md "Window properties"), carried by
8119/// [`Toolkit::apply_window`]. Each variant names the `Cap` that reports whether the running
8120/// toolkit makes it.
8121#[derive(Clone, Debug, PartialEq)]
8122pub enum WindowChange {
8123    /// Minimize, zoom, take fullscreen, or return to normal. `Cap::WindowStates` for the
8124    /// first two, `Cap::WindowFullscreen` for fullscreen. The outcome comes back as
8125    /// [`Event::WindowStateChanged`].
8126    State(WindowState),
8127    /// Keep the window's content out of screenshots, recordings and screen sharing.
8128    /// `Cap::ContentProtection`.
8129    ContentProtected(bool),
8130    /// Move and/or resize. `origin` is the outer frame's top-left corner in points on the
8131    /// desktop's coordinate space (top-left origin, `Cap::WindowPosition`); `size` is the size Day
8132    /// lays the content out at, in points, the same size `WindowResized` reports
8133    /// (`Cap::WindowGeometry`): the backend adds its own chrome around it.
8134    Frame {
8135        origin: Option<Point>,
8136        size: Option<Size>,
8137    },
8138    /// The content size the user can resize the window to. `None` lifts that bound.
8139    /// `Cap::WindowGeometry`.
8140    Limits {
8141        min: Option<Size>,
8142        max: Option<Size>,
8143    },
8144    /// Stacking against other apps' windows. `Cap::WindowLevel`.
8145    Level(WindowLevel),
8146    /// Show the window on every virtual desktop / Space. `Cap::WindowLevel`.
8147    OnAllWorkspaces(bool),
8148    /// Leave the window out of the taskbar and the window switcher. `Cap::WindowLevel`.
8149    SkipTaskbar(bool),
8150    /// Whether the user can resize the window. `Cap::WindowGeometry`.
8151    Resizable(bool),
8152    /// Whether the window offers a minimize control. `Cap::WindowStates`.
8153    Minimizable(bool),
8154    /// Whether the window offers a maximize / zoom control. `Cap::WindowStates`.
8155    Maximizable(bool),
8156    /// Whether the window offers a close control. `Cap::WindowStates`.
8157    Closable(bool),
8158    /// Hide the window without closing it, or show it again. `Cap::WindowStates`.
8159    Visible(bool),
8160    /// This window's light/dark override over the app-wide [`Toolkit::set_appearance`].
8161    /// `Cap::WindowAppearance`.
8162    Appearance(Option<bool>),
8163    /// Bounce the Dock icon, flash the taskbar button. `Cap::RequestAttention`.
8164    RequestAttention(Attention),
8165}
8166
8167/// The frame a window wears (docs/window-chrome.md), set once when it opens.
8168#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
8169pub enum WindowChrome {
8170    /// The platform's title bar and frame.
8171    #[default]
8172    Standard,
8173    /// The content runs to the window's top edge, under the title bar, and the platform's own
8174    /// window controls (close, minimize, zoom) stay where they are. For a custom title bar: the
8175    /// backend reports the bar's height as the window's safe-area top inset (`day::safe_area()`),
8176    /// so the app pads its content by it and paints its background under it. Mark the draggable
8177    /// part with `.window_drag_region()`. `Cap::OverlayTitleBar`; where unsupported the window
8178    /// keeps its standard bar.
8179    Overlay,
8180    /// No title bar and no frame: a splash screen, a heads-up panel, a borderless utility. The
8181    /// window still resizes from its edges when resizable; mark the part that moves it with
8182    /// `.window_drag_region()`. `Cap::FramelessWindow`; where unsupported the window keeps its
8183    /// standard frame.
8184    Frameless,
8185}
8186
8187/// What shows behind a window's content (docs/window-chrome.md).
8188#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
8189pub enum WindowBackground {
8190    /// The platform's window background.
8191    #[default]
8192    Opaque,
8193    /// Nothing: pixels the content leaves unpainted show the desktop through the window. For
8194    /// rounded or shaped splash screens and overlays. `Cap::TransparentWindow`.
8195    Transparent,
8196    /// A translucent system material that blurs what is behind the window.
8197    /// `Cap::WindowMaterial`; where unsupported the window stays opaque.
8198    Material(WindowMaterial),
8199}
8200
8201/// The system materials a window background can use ([`WindowBackground::Material`]).
8202#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
8203pub enum WindowMaterial {
8204    /// The main-window material: macOS's window background, Windows 11's Mica.
8205    Window,
8206    /// A sidebar or source list: macOS's sidebar material, Windows 11's Mica Alt (tabbed).
8207    Sidebar,
8208    /// A transient surface (a popover, a menu-like panel, a heads-up display): macOS's popover
8209    /// material, Windows 11's Acrylic.
8210    Transient,
8211}
8212
8213/// Where a window opens ([`WindowOptions::placement`]).
8214#[derive(Clone, Copy, Debug, Default, PartialEq)]
8215pub enum WindowPlacement {
8216    /// The platform's choice: macOS cascades, Windows and Linux let the window manager decide.
8217    #[default]
8218    Automatic,
8219    /// Centered on the screen with the active window.
8220    Centered,
8221    /// The outer frame's top-left corner at this point, in points on the desktop's coordinate
8222    /// space (top-left origin). Falls back to `Automatic` without `Cap::WindowPosition`.
8223    At(Point),
8224}
8225
8226/// A small runtime RGBA image for a status item: charts, meters, or a grid of results.
8227///
8228/// Rows run top to bottom; samples are tightly packed, non-premultiplied sRGB RGBA8.
8229/// `scale` is pixels per logical point (2 for Retina). This owns its bytes, independent of
8230/// any window or decoded-image registry. Currently rendered by AppKit; other backends use
8231/// [`StatusItemSpec::icon`] as a fallback. See docs/status-item.md.
8232#[derive(Clone, PartialEq)]
8233pub struct StatusImage {
8234    width: u32,
8235    height: u32,
8236    scale: f64,
8237    rgba: std::sync::Arc<[u8]>,
8238}
8239
8240impl StatusImage {
8241    /// Validate a runtime image. Rejects empty/mismatched pixels, invalid scales, and images
8242    /// exceeding 16 MiB or 4096 logical points on either axis. No platform allocation occurs.
8243    pub fn rgba(
8244        width: u32,
8245        height: u32,
8246        scale: f64,
8247        pixels: impl Into<std::sync::Arc<[u8]>>,
8248    ) -> Option<Self> {
8249        let rgba = pixels.into();
8250        let expected = (width as usize)
8251            .checked_mul(height as usize)?
8252            .checked_mul(4)?;
8253        if width == 0
8254            || height == 0
8255            || expected > 16 * 1024 * 1024
8256            || rgba.len() != expected
8257            || !scale.is_finite()
8258            || scale <= 0.0
8259            || f64::from(width) / scale > 4096.0
8260            || f64::from(height) / scale > 4096.0
8261        {
8262            return None;
8263        }
8264        Some(Self {
8265            width,
8266            height,
8267            scale,
8268            rgba,
8269        })
8270    }
8271
8272    pub fn width(&self) -> u32 {
8273        self.width
8274    }
8275    pub fn height(&self) -> u32 {
8276        self.height
8277    }
8278    pub fn scale(&self) -> f64 {
8279        self.scale
8280    }
8281    pub fn pixels(&self) -> &[u8] {
8282        &self.rgba
8283    }
8284    pub fn size(&self) -> Size {
8285        Size::new(
8286            f64::from(self.width) / self.scale,
8287            f64::from(self.height) / self.scale,
8288        )
8289    }
8290}
8291
8292impl std::fmt::Debug for StatusImage {
8293    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
8294        f.debug_struct("StatusImage")
8295            .field("width", &self.width)
8296            .field("height", &self.height)
8297            .field("scale", &self.scale)
8298            .field("bytes", &self.rgba.len())
8299            .finish()
8300    }
8301}
8302
8303#[cfg(test)]
8304mod status_image_tests {
8305    use super::*;
8306
8307    #[test]
8308    fn validates_pixel_layout_and_logical_size() {
8309        let image = StatusImage::rgba(120, 36, 2.0, vec![255; 120 * 36 * 4]).unwrap();
8310        assert_eq!(image.size(), Size::new(60.0, 18.0));
8311        assert_eq!(image.clone(), image);
8312        assert!(StatusImage::rgba(0, 1, 1.0, vec![]).is_none());
8313        assert!(StatusImage::rgba(1, 1, 1.0, vec![0; 3]).is_none());
8314        assert!(StatusImage::rgba(u32::MAX, u32::MAX, 1.0, vec![]).is_none());
8315        for scale in [0.0, -1.0, f64::NAN, f64::INFINITY, 0.00001] {
8316            assert!(StatusImage::rgba(1, 1, scale, vec![0; 4]).is_none());
8317        }
8318    }
8319}
8320
8321/// One status item: an icon in the menu bar (macOS), the notification area (Windows) or a
8322/// StatusNotifierItem host's tray (Linux), with a menu (docs/status-item.md).
8323#[derive(Clone, Debug, PartialEq)]
8324pub struct StatusItemSpec {
8325    /// The app's name for the item, stable across updates: what a backend diffs by.
8326    pub id: String,
8327    /// The glyph. `None` shows the title alone (macOS) or the app's icon (elsewhere).
8328    pub icon: Option<Icon>,
8329    /// A runtime image. AppKit prefers this over `icon`, preserving aspect ratio and point
8330    /// size up to 18pt high; other backends ignore it and show `icon`/`title` as before.
8331    pub raster: Option<StatusImage>,
8332    /// Draw the icon as a template: its shape only, in the menu bar's or panel's own color, so
8333    /// it reads in light and dark. Symbols are always templates.
8334    pub template: bool,
8335    /// Text beside the icon where the platform shows one (the macOS menu bar). Empty: icon only.
8336    pub title: String,
8337    /// The hover text.
8338    pub tooltip: String,
8339    /// The menu the item opens. Same model and dispatch as the app menu.
8340    pub menu: Vec<MenuItem>,
8341    /// A dispatch id (the [`Event::MenuAction`] registry) run when the user clicks the item
8342    /// itself, where the platform separates a click from opening the menu (a left click on macOS
8343    /// and Windows, the host's "activate" on Linux). 0: a click opens the menu.
8344    pub activate: u64,
8345}
8346
8347/// One display (docs/windows.md "Monitors"), in points on the desktop's coordinate space:
8348/// top-left origin at the primary display's top-left corner.
8349#[derive(Clone, Debug, PartialEq)]
8350pub struct Monitor {
8351    /// Stable for the display across launches where the platform offers it (a display UUID, a
8352    /// connector name); an index otherwise.
8353    pub id: String,
8354    /// The display's name, for a picker ("Built-in Retina Display", "DELL U2720Q").
8355    pub name: String,
8356    /// The display's whole area.
8357    pub frame: Rect,
8358    /// The part windows should use: the frame minus the menu bar, Dock, taskbar or panels.
8359    pub work_area: Rect,
8360    /// Device pixels per point.
8361    pub scale: f64,
8362    /// The display the desktop's menu bar or primary taskbar is on.
8363    pub primary: bool,
8364}
8365
8366/// A launcher shortcut the app sets while it runs (docs/deep-links.md "Launcher shortcuts"): a
8367/// route to open and the label the launcher shows, already localized.
8368#[derive(Clone, Debug, PartialEq, Eq)]
8369pub struct LauncherShortcut {
8370    /// The route the shortcut opens, through the deep-link intake.
8371    pub route: String,
8372    /// What the launcher shows.
8373    pub label: String,
8374}
8375
8376/// A progress indicator on the app's Dock or taskbar icon ([`Toolkit::set_app_progress`],
8377/// docs/status-item.md).
8378#[derive(Clone, Copy, Debug, Default, PartialEq)]
8379pub enum AppProgress {
8380    /// No indicator.
8381    #[default]
8382    None,
8383    /// Work of unknown length.
8384    Indeterminate,
8385    /// A fraction done, 0.0 to 1.0.
8386    Value(f64),
8387    /// A fraction done, paused. Platforms without a paused state show `Value`.
8388    Paused(f64),
8389    /// A fraction done when the work failed. Platforms without an error state show `Value`.
8390    Error(f64),
8391}
8392
8393/// Whether and how a window joins macOS window tabs ([`WindowOptions::tabbing`],
8394/// `Cap::WindowTabbing`). Other platforms have no system window tabs and ignore it.
8395#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
8396pub enum WindowTabbing {
8397    /// The platform default for the window's kind: an ordinary window tabs with the app's other
8398    /// ordinary windows when the user's "Prefer tabs" setting says so; preferences never tab.
8399    #[default]
8400    Automatic,
8401    /// Tab only with windows of the same group, following the user's setting. The tab bar's
8402    /// "+" opens the builder registered for this group (`register_new_window_for`).
8403    Group(String),
8404    /// Always open as a tab of an existing window of the same group, whatever the setting.
8405    Preferred(String),
8406    /// Never become a tab.
8407    Disallowed,
8408}
8409
8410/// An app's generated locale catalog: `(DEFAULT, CATALOG)`, exactly what `day-build` emits as
8411/// `res::locales::{DEFAULT, CATALOG}` (§18.5). Carried in [`WindowOptions::locales`] so the
8412/// framework can install it at the one moment that is correct.
8413pub type AppLocales = (&'static str, &'static [(&'static str, &'static str)]);
8414
8415#[derive(Clone, Debug)]
8416pub struct WindowOptions {
8417    pub title: String,
8418    pub size: Size,
8419    pub min_size: Option<Size>,
8420    /// Create and mount the window without showing it or activating the app. Supported on
8421    /// AppKit; other backends currently ignore this option. Defaults to false.
8422    ///
8423    /// Menu-bar apps can keep their initial host hidden and open Preferences on demand.
8424    /// The window still exists and can be shown with `WindowHandle::set_visible(true)`;
8425    /// this does not change the app's keep-running policy.
8426    pub start_hidden: bool,
8427    /// Ask the backend to size this window to its content once it has been built and laid out,
8428    /// rather than keeping [`Self::size`] (docs/windows.md). `size` still decides the width and
8429    /// acts as the height ceiling, so a panel with more content than fits the screen scrolls
8430    /// instead of growing past it.
8431    ///
8432    /// What a preferences panel wants on every desktop. Ignored by backends that cannot resize a
8433    /// live window, and by the ones with no windows at all.
8434    pub size_to_fit: bool,
8435    /// The app's display name for the standard application menu / About (macOS). `None` falls back
8436    /// to `title`; set it when `title` carries extra decoration you don't want in `About <name>`
8437    /// (e.g. the showcase's window title is "Day Showcase (AppKit)" but its app name is "Showcase").
8438    pub app_name: Option<String>,
8439    /// The app's locale catalog, installed by `day::launch` (docs/localization.md).
8440    ///
8441    /// The order is why this is the framework's job: the OS's languages reach day-localization from the
8442    /// live backend, and the catalog has to be registered after that hint and before the first
8443    /// localized string is read. An app that installs it itself (before `launch`, where there
8444    /// is no backend yet) registers against an empty hint list and resolves to `DEFAULT`, so a
8445    /// French device opens an English window.
8446    pub locales: Option<AppLocales>,
8447    /// The title, computed once the catalog above is installed: how a window title comes from
8448    /// the catalog rather than a literal. Takes precedence over [`Self::title`], which stays the
8449    /// fallback for the moment before (and for apps with nothing to translate).
8450    ///
8451    /// A plain `fn` rather than a closure: this struct is `Clone`, and the callers are a
8452    /// non-capturing `|| res::str::app_title().format()`, which coerces.
8453    pub title_fn: Option<fn() -> String>,
8454    /// The app's version, for Day's exit line (`Clean exit for <app> v<version> …`,
8455    /// docs/lifecycle.md): `env!("CARGO_PKG_VERSION")` in the app crate, which the scaffold's
8456    /// `window()` sets. `None` falls back to the `DAY_APP_VERSION` the `day` CLI sets on a launch.
8457    pub version: Option<String>,
8458    /// macOS window tabbing for this window (`Cap::WindowTabbing`); ignored elsewhere.
8459    pub tabbing: WindowTabbing,
8460    /// The window's frame: standard, a title bar the content runs under, or none
8461    /// (docs/window-chrome.md). Desktop only; phones and the web ignore it.
8462    pub chrome: WindowChrome,
8463    /// What shows behind the content: the window background, nothing, or a system material.
8464    pub background: WindowBackground,
8465    /// Whether the window casts the platform's drop shadow. A transparent, shaped window often
8466    /// wants none.
8467    pub shadow: bool,
8468    /// Whether the user can resize the window by its edges.
8469    pub resizable: bool,
8470    /// Where the window opens.
8471    pub placement: WindowPlacement,
8472    /// The largest content size the user can resize the window to (`Cap::WindowGeometry`).
8473    pub max_size: Option<Size>,
8474    /// Remember this window's size, position and maximized state under this key, and reopen it
8475    /// that way next launch (docs/windows.md "Remembered frames"). A position that no attached
8476    /// display shows any more is dropped, so a window never reopens off-screen.
8477    pub remember_frame: Option<String>,
8478    /// The logical window this opens (docs/windows.md): `open_window` focuses an already-open
8479    /// window with the same key instead of opening a second (the preferences pattern). `None`
8480    /// always opens a new one.
8481    pub key: Option<String>,
8482    /// The kind of window: a regular one, a preferences panel, an About panel.
8483    pub kind: WindowKind,
8484}
8485
8486impl WindowOptions {
8487    /// The window title. Replaces a [`title_fn`](Self::title_fn) set earlier (the generated
8488    /// `res::window_options()` sets one), so the last title named wins.
8489    pub fn title(mut self, title: impl Into<String>) -> Self {
8490        self.title = title.into();
8491        self.title_fn = None;
8492        self
8493    }
8494    /// The content size the window opens at (desktop; phones fill the screen).
8495    pub fn size(mut self, width: f64, height: f64) -> Self {
8496        self.size = Size::new(width, height);
8497        self
8498    }
8499    /// The smallest content size the user can resize to.
8500    pub fn min_size(mut self, width: f64, height: f64) -> Self {
8501        self.min_size = Some(Size::new(width, height));
8502        self
8503    }
8504    /// The largest content size the user can resize to (`Cap::WindowGeometry`).
8505    pub fn max_size(mut self, width: f64, height: f64) -> Self {
8506        self.max_size = Some(Size::new(width, height));
8507        self
8508    }
8509    /// Create and mount the window without showing it; see [`Self::start_hidden`].
8510    pub fn start_hidden(mut self) -> Self {
8511        self.start_hidden = true;
8512        self
8513    }
8514    /// Size the window to its content once built; see [`Self::size_to_fit`].
8515    pub fn size_to_fit(mut self) -> Self {
8516        self.size_to_fit = true;
8517        self
8518    }
8519    /// The app's display name for the application menu and About; see [`Self::app_name`].
8520    pub fn app_name(mut self, name: impl Into<String>) -> Self {
8521        self.app_name = Some(name.into());
8522        self
8523    }
8524    /// The app's locale catalog, as `res::locales::{DEFAULT, CATALOG}`; see [`Self::locales`].
8525    pub fn locales(
8526        mut self,
8527        default: &'static str,
8528        catalog: &'static [(&'static str, &'static str)],
8529    ) -> Self {
8530        self.locales = Some((default, catalog));
8531        self
8532    }
8533    /// The title, computed once the catalog is installed; see [`Self::title_fn`].
8534    pub fn title_fn(mut self, f: fn() -> String) -> Self {
8535        self.title_fn = Some(f);
8536        self
8537    }
8538    /// The app's version, for Day's exit line; see [`Self::version`].
8539    pub fn version(mut self, version: impl Into<String>) -> Self {
8540        self.version = Some(version.into());
8541        self
8542    }
8543    /// macOS window tabbing for this window; see [`Self::tabbing`].
8544    pub fn tabbing(mut self, tabbing: WindowTabbing) -> Self {
8545        self.tabbing = tabbing;
8546        self
8547    }
8548    /// The window's frame; see [`Self::chrome`].
8549    pub fn chrome(mut self, chrome: WindowChrome) -> Self {
8550        self.chrome = chrome;
8551        self
8552    }
8553    /// What shows behind the content; see [`Self::background`].
8554    pub fn background(mut self, background: WindowBackground) -> Self {
8555        self.background = background;
8556        self
8557    }
8558    /// No drop shadow, for a transparent or shaped window; see [`Self::shadow`].
8559    pub fn no_shadow(mut self) -> Self {
8560        self.shadow = false;
8561        self
8562    }
8563    /// A window the user cannot resize; see [`Self::resizable`].
8564    pub fn fixed_size(mut self) -> Self {
8565        self.resizable = false;
8566        self
8567    }
8568    /// Where the window opens; see [`Self::placement`].
8569    pub fn placement(mut self, placement: WindowPlacement) -> Self {
8570        self.placement = placement;
8571        self
8572    }
8573    /// Remember and restore this window's frame under `key`; see [`Self::remember_frame`].
8574    pub fn remember_frame(mut self, key: impl Into<String>) -> Self {
8575        self.remember_frame = Some(key.into());
8576        self
8577    }
8578    /// The logical window this opens; see [`Self::key`].
8579    pub fn key(mut self, key: impl Into<String>) -> Self {
8580        self.key = Some(key.into());
8581        self
8582    }
8583    /// The kind of window; see [`Self::kind`].
8584    pub fn kind(mut self, kind: WindowKind) -> Self {
8585        self.kind = kind;
8586        self
8587    }
8588}
8589
8590impl Default for WindowOptions {
8591    fn default() -> Self {
8592        WindowOptions {
8593            title: "Day".into(),
8594            size: Size::new(480.0, 640.0),
8595            min_size: None,
8596            start_hidden: false,
8597            size_to_fit: false,
8598            app_name: None,
8599            locales: None,
8600            title_fn: None,
8601            version: None,
8602            tabbing: WindowTabbing::Automatic,
8603            chrome: WindowChrome::Standard,
8604            background: WindowBackground::Opaque,
8605            shadow: true,
8606            resizable: true,
8607            placement: WindowPlacement::Automatic,
8608            max_size: None,
8609            remember_frame: None,
8610            key: None,
8611            kind: WindowKind::Normal,
8612        }
8613    }
8614}
8615
8616/// A platform backend: owns the native main loop and exactly one window in v1 (§8.1).
8617///
8618/// `run` sets up the native app + window, installs the reactive scheduler + main poster,
8619/// then hands `(self, root_container, content_size)` to `ready` (which mounts the tree and
8620/// takes ownership of the backend), and finally runs the native main loop.
8621pub trait Platform: Toolkit {
8622    /// The process-constant target id, e.g. `"macos-appkit"`.
8623    const TARGET: &'static str;
8624    /// The toolkit half of the target, e.g. `"appkit"`.
8625    const TOOLKIT: &'static str;
8626    /// Whether [`Platform::run`] returning means the app is over. True for a backend that
8627    /// drives the native loop itself until the app quits (GTK, Qt, XAML; AppKit's never
8628    /// returns). False where the host owns the loop and `run` hands back at once, with the
8629    /// app still to come (ArkUI's ability, Android's activity, the web page, the mock's test):
8630    /// their `DidExit` is the host's last callback, not the return (docs/lifecycle.md).
8631    const RUN_ENDS_APP: bool = true;
8632
8633    fn run(self, options: WindowOptions, ready: Box<dyn FnOnce(Self, Self::Handle, Size)>);
8634
8635    /// Post a closure onto the native main loop. Callable from any thread; this is the
8636    /// single door the reactive scheduler and `Setter` deliveries ride (§3.3).
8637    fn post(f: Box<dyn FnOnce() + Send>);
8638
8639    /// Post `f` onto the native main loop after (at least) `ms` milliseconds: the timer
8640    /// door behind `day::sleep` (docs/async.md). Every shipped backend overrides it with the
8641    /// loop's own timer (`dispatch_after`, `Handler.postDelayed`, `g_timeout_add`,
8642    /// `QTimer::singleShot`, `SetTimer`, `setTimeout`), so a sleep costs no thread. The
8643    /// default is the fallback for a backend without one: a helper thread that sleeps the
8644    /// whole delay and rides [`Platform::post`] home. It is correct, but a thread per sleep
8645    /// adds up under a ticking loop, so the first use says so once in the log.
8646    fn post_delayed(ms: u32, f: Box<dyn FnOnce() + Send>) {
8647        static SAID: std::sync::Once = std::sync::Once::new();
8648        SAID.call_once(|| {
8649            log::warn!(
8650                "day: {} has no native timer door; `day::sleep` falls back to a helper thread \
8651                 per delay (implement `Platform::post_delayed`)",
8652                Self::TARGET
8653            );
8654        });
8655        std::thread::spawn(move || {
8656            std::thread::sleep(std::time::Duration::from_millis(u64::from(ms)));
8657            Self::post(f);
8658        });
8659    }
8660
8661    /// Ordered OS locale preference list (BCP-47), for fluent-langneg (§12.2).
8662    fn locale_hints(&self) -> Vec<String> {
8663        Vec::new()
8664    }
8665}
8666
8667// ---------------------------------------------------------------------------
8668// Open renderer registry (§8.2)
8669// ---------------------------------------------------------------------------
8670
8671/// The scale a window snapshot is rendered at, when a scripted run states one
8672/// (`DAY_CAPTURE_SCALE=2`, set by `day launch --script` from Day.toml `[screenshots]`).
8673///
8674/// For the backends that render their own snapshot (GTK, Qt): the capture then measures
8675/// window points times this, whatever display the host has, which is what makes a CI capture
8676/// under a 1x xvfb the same 2560x1600 pixels a HiDPI laptop produces. A backend that reads the
8677/// compositor's pixels back (AppKit, XAML) captures at the display's own scale and ignores it.
8678/// `None` when unset or unparseable: capture at the backend's natural scale.
8679pub fn capture_scale() -> Option<f64> {
8680    std::env::var("DAY_CAPTURE_SCALE")
8681        .ok()
8682        .and_then(|v| v.trim().parse::<f64>().ok())
8683        .filter(|s| s.is_finite() && (0.5..=4.0).contains(s))
8684}
8685
8686/// Seconds on a monotonic clock since the first call: the frame timestamp for a backend that
8687/// does not expose a native timestamp (§8.4). The origin is arbitrary. Not for the web
8688/// build, where `Instant` is unavailable and `requestAnimationFrame` stamps the frame itself.
8689pub fn frame_timestamp() -> f64 {
8690    static ORIGIN: std::sync::OnceLock<std::time::Instant> = std::sync::OnceLock::new();
8691    ORIGIN
8692        .get_or_init(std::time::Instant::now)
8693        .elapsed()
8694        .as_secs_f64()
8695}
8696
8697/// The user's language preference from the POSIX environment, newest-first, as BCP-47 tags.
8698///
8699/// `LANGUAGE` is the GNU multi-language list (`fr:en`); `LC_ALL`, `LC_MESSAGES` and `LANG` each
8700/// carry one locale in POSIX form (`fr_FR.UTF-8`), which becomes `fr-FR`. Shared by the backends
8701/// whose platform has no richer API to ask (§12.2, docs/localization.md).
8702pub fn posix_locale_hints() -> Vec<String> {
8703    let mut out: Vec<String> = Vec::new();
8704    let mut push = |tag: &str| {
8705        // "C" and "POSIX" are the absence of a preference, not a language.
8706        let tag = tag.split('.').next().unwrap_or(tag).replace('_', "-");
8707        if tag.is_empty() || tag == "C" || tag == "POSIX" {
8708            return;
8709        }
8710        if !out.contains(&tag) {
8711            out.push(tag);
8712        }
8713    };
8714    if let Ok(list) = std::env::var("LANGUAGE") {
8715        for tag in list.split(':') {
8716            push(tag);
8717        }
8718    }
8719    for key in ["LC_ALL", "LC_MESSAGES", "LANG"] {
8720        if let Ok(v) = std::env::var(key) {
8721            push(&v);
8722        }
8723    }
8724    out
8725}
8726
8727/// Optional custom measure for a third-party piece (§8.2).
8728pub type MeasureFn<B> = fn(&mut B, &<B as Toolkit>::Handle, Proposal) -> Size;
8729
8730/// A third-party piece's per-toolkit implementation. `make` receives the concrete backend
8731/// (public helper surface) and returns a native handle the backend then owns like any built-in.
8732pub struct Renderer<B: Toolkit> {
8733    pub kind: PieceKind,
8734    pub make: fn(&mut B, &dyn Any, NodeId) -> B::Handle,
8735    pub update: fn(&mut B, &B::Handle, &dyn Any),
8736    pub measure: Option<MeasureFn<B>>,
8737    /// Teardown, run from the release queue just before [`Toolkit::release`] frees the handle.
8738    ///
8739    /// A piece that keeps per-view state (a retained delegate, a session map, a native
8740    /// observer) has no other place to drop it: `make`/`update` are the only other hooks, and a
8741    /// disposed node never calls them again. Without this a piece leaks one entry per realized
8742    /// view, and any map keyed by the handle's address can go on to answer for a later view that
8743    /// the allocator hands the same address.
8744    ///
8745    /// `None` for the pieces that own nothing (most of them).
8746    pub release: Option<fn(&mut B, &B::Handle)>,
8747}
8748
8749pub struct Registry<B: Toolkit> {
8750    map: HashMap<PieceKind, Renderer<B>>,
8751}
8752
8753impl<B: Toolkit> Default for Registry<B> {
8754    fn default() -> Self {
8755        Registry {
8756            map: HashMap::new(),
8757        }
8758    }
8759}
8760
8761impl<B: Toolkit> Registry<B> {
8762    pub fn register(&mut self, r: Renderer<B>) {
8763        let kind = r.kind;
8764        if self.map.insert(kind, r).is_some() {
8765            // Two pieces claiming one kind is last-linked-wins in link order, effectively
8766            // nondeterministic. Fail loudly in debug; in release, say so once at boot rather
8767            // than render the wrong widget silently.
8768            debug_assert!(
8769                false,
8770                "duplicate renderer registered for piece kind {kind:?}"
8771            );
8772            log::warn!("duplicate renderer for piece kind {kind:?} — later registration wins");
8773        }
8774    }
8775    pub fn get(&self, kind: PieceKind) -> Option<&Renderer<B>> {
8776        self.map.get(kind)
8777    }
8778    pub fn kinds(&self) -> impl Iterator<Item = PieceKind> + '_ {
8779        self.map.keys().copied()
8780    }
8781}
8782
8783/// The canvas wire op codes (§11, §15.3): slot 0 of every 9-number record in
8784/// [`encode_ops`]'s output. The numeric values are the frozen wire contract: the JNI, C++,
8785/// and JS decoders each hand-write these as constants, so a value here may never be reused
8786/// or renumbered; new ops append. `ALL` drives the density test that keeps this enum and
8787/// the encoder in step.
8788#[derive(Clone, Copy, Debug, PartialEq, Eq)]
8789#[repr(i32)]
8790pub enum OpCode {
8791    /// Fill a rect (a,b=origin, c,d=size).
8792    FillRect = 0,
8793    /// Stroke a rect (g=width).
8794    StrokeRect = 1,
8795    /// Fill a rounded rect (e=radius).
8796    FillRrect = 2,
8797    /// Fill an ellipse in a rect.
8798    FillEllipse = 3,
8799    /// Stroke an ellipse (g=width).
8800    StrokeEllipse = 4,
8801    /// Stroke an arc (e=start°, f=sweep°, g=width). `Fill(Shape::Arc)` also encodes as
8802    /// this with width 0, the known asymmetry; see [`encode_ops`].
8803    StrokeArc = 5,
8804    /// Line a,b → c,d (g=width).
8805    Line = 6,
8806    /// Text at a,b (e=size, f=anchor: 0 leading / 1 centered); the string rides the texts
8807    /// channel.
8808    Text = 7,
8809    /// Save the graphics state.
8810    Save = 8,
8811    /// Restore the graphics state.
8812    Restore = 9,
8813    /// Concat an affine transform (a..f).
8814    Concat = 10,
8815    /// Fill a polygon; points ride the texts channel as "x,y x,y …" (closed automatically).
8816    /// `a` = the [`geometry_key`] of those points, or 0 for none.
8817    FillPolygon = 11,
8818    /// Stroke a polygon (g=width); points and key as [`OpCode::FillPolygon`].
8819    StrokePolygon = 12,
8820    /// Stroke a rounded rect (e=radius, g=width).
8821    StrokeRrect = 13,
8822    /// Set a gradient for the next shape record (f=type: 0 linear with a,b=start / c,d=end
8823    /// unit points; 1 radial with a,b=center unit point, c=unit radius; e=stop count).
8824    /// Stops ride the texts channel as "offset,aarrggbb offset,aarrggbb …". Unit geometry
8825    /// resolves against the shape's bounding box.
8826    SetGradient = 14,
8827    /// Fill a path (f=fill rule: 0 non-zero / 1 even-odd); segments ride the texts channel
8828    /// (see [`encode_path`]). `a` = the [`geometry_key`] of those segments, or 0 for none.
8829    ///
8830    /// The key is a cache handle, not a payload: a decoder that recognizes it may keep the
8831    /// native geometry it built last time and skip re-parsing the segments, but it must still
8832    /// consume the texts entry either way, because that channel is positional and a skipped
8833    /// entry desynchronizes every record after it.
8834    FillPath = 15,
8835    /// Stroke a path (g=width); segments and key as [`OpCode::FillPath`].
8836    StrokePath = 16,
8837    /// Clip to a shape (f=shape kind: 0 rect / 1 rrect(e=radius) / 2 ellipse / 3 path
8838    /// (e=fill rule) / 4 polygon; a..d=geometry; path/polygon payloads ride the texts
8839    /// channel).
8840    ///
8841    /// For the two payload-bearing kinds (3 and 4) there is no geometry in the slots, so `a`
8842    /// carries the [`geometry_key`] instead and b..d stay 0. The other three kinds put real
8843    /// geometry in a..d and have nothing to cache.
8844    Clip = 17,
8845    /// Stroke style for the next stroke record (a=cap, b=join, c=miter limit, d=dash
8846    /// phase, e=dash count; the dash array rides the texts channel).
8847    StrokeStyle = 18,
8848    /// Font for the next text record (a=CSS weight 100 … 900, 0 = default; b=italic 0/1); the
8849    /// family name rides the texts channel, `""` = the platform's default face. Like
8850    /// [`OpCode::SetGradient`] and [`OpCode::StrokeStyle`] it is consumed by the record that
8851    /// follows and then cleared; a default [`CanvasFont`] emits no record at all, so a drawing
8852    /// without fonts encodes exactly as it did before this op existed.
8853    SetFont = 19,
8854    /// The next shape record is a template, drawn once per stamped position rather than once
8855    /// (docs/canvas.md "Stamping"). `a` = how many positions follow. Like [`OpCode::SetGradient`],
8856    /// [`OpCode::StrokeStyle`] and [`OpCode::SetFont`] it is a prefix, consumed by the record it
8857    /// applies to and then cleared.
8858    ///
8859    /// Between this and that template record come `ceil(a / 4)` [`OpCode::StampPoints`] records
8860    /// carrying the coordinates. A drawing with no stamps encodes exactly as it did before.
8861    Stamp = 20,
8862    /// Four stamped positions, filling the record edge to edge: `[op, x0, y0, x1, y1, x2, y2,
8863    /// x3, y3]`, the one record that uses its last slot for geometry instead of a color, because
8864    /// it carries no color of its own. The final record of a run is padded; the count in the
8865    /// [`OpCode::Stamp`] header says how many of the pairs are real.
8866    StampPoints = 21,
8867    /// Draw a decoded image: `a,b` = origin, `c,d` = size, `e` = the [`BitmapId`], `f` = opacity
8868    /// in `0.0..=1.0` (docs/images.md).
8869    ///
8870    /// The id rides the numeric channel because it is a number, and an `f64` carries a `u64` id
8871    /// exactly up to 2^53; ids are minted from 1 per process, so that ceiling is unreachable.
8872    /// Nothing rides the texts channel for this op.
8873    Image = 22,
8874}
8875
8876impl OpCode {
8877    /// Every code, in wire order. The density test iterates this so a new variant that
8878    /// forgets to join fails loudly.
8879    pub const ALL: [OpCode; 23] = [
8880        OpCode::FillRect,
8881        OpCode::StrokeRect,
8882        OpCode::FillRrect,
8883        OpCode::FillEllipse,
8884        OpCode::StrokeEllipse,
8885        OpCode::StrokeArc,
8886        OpCode::Line,
8887        OpCode::Text,
8888        OpCode::Save,
8889        OpCode::Restore,
8890        OpCode::Concat,
8891        OpCode::FillPolygon,
8892        OpCode::StrokePolygon,
8893        OpCode::StrokeRrect,
8894        OpCode::SetGradient,
8895        OpCode::FillPath,
8896        OpCode::StrokePath,
8897        OpCode::Clip,
8898        OpCode::StrokeStyle,
8899        OpCode::SetFont,
8900        OpCode::Stamp,
8901        OpCode::StampPoints,
8902        OpCode::Image,
8903    ];
8904
8905    /// The code back from a wire number (a decoder-side aid and the round-trip test's
8906    /// reference); `None` for anything outside the table.
8907    pub fn from_wire(n: f64) -> Option<OpCode> {
8908        OpCode::ALL.into_iter().find(|c| *c as i32 as f64 == n)
8909    }
8910}
8911
8912/// Flat numeric encoding of a display list for shim/JNI boundaries (§11, §15.3): per op
8913/// 9 numbers [kind, a, b, c, d, e, f, g, rgba-bits]; text payloads ride separately in order.
8914/// The kind slot carries an [`OpCode`]; its doc comments are the per-slot contract.
8915///
8916/// Transports join `texts` with the unit separator U+001F (one entry per text-carrying
8917/// record, in order), so text payloads must not contain U+001F. Known asymmetry:
8918/// `Fill(Shape::Arc)` encodes as [`OpCode::StrokeArc`] with width 0. Filled arcs render
8919/// only on the direct-replay backends (AppKit/UIKit); use a polygon fan if a filled arc
8920/// must be portable.
8921/// Serialize a path for the `texts` side-channel: one space-separated token per segment,
8922/// `M x y` / `L x y` / `Q cx cy x y` / `C c1x c1y c2x c2y x y` / `Z`.
8923///
8924/// Text rather than numbers because that is the channel the encoder already has for
8925/// variable-length payloads, and every decoder (JS, Java, C++) can already split a string. The
8926/// numeric channel is a flat `[f64; 9]`-per-record array with no length prefix, so a path could
8927/// not ride it without changing the record shape for every backend at once.
8928/// A content key for a shape's variable-length geometry: the handle a backend caches decoded
8929/// native geometry under (a `Path2D`, a `QPainterPath`, an `android.graphics.Path`) so an
8930/// unchanged path is rebuilt once instead of re-parsed out of the texts channel every frame.
8931///
8932/// It hashes the geometry, not the op's position or its identity, so that a draw closure that
8933/// rebuilds its `PathBuilder` chain from scratch on every frame (which is what canvas consumers
8934/// do) produces an equal path, hashes the same and hits the same entry. An identity would miss
8935/// every time.
8936///
8937/// Two different paths that collided would draw each other, so the width matters: FNV-1a over the
8938/// IEEE bits, masked to the 53 bits an `f64` wire slot carries exactly. `0.0` is reserved for "no
8939/// key": a decoder seeing it must decode the payload as it always did, which is also what every
8940/// decoder written before this key existed does with the slot.
8941pub fn geometry_key(shape: &Shape) -> f64 {
8942    fn mix(h: &mut u64, v: f64) {
8943        for byte in v.to_bits().to_le_bytes() {
8944            *h ^= u64::from(byte);
8945            *h = h.wrapping_mul(0x0000_0100_0000_01b3);
8946        }
8947    }
8948    fn mix_point(h: &mut u64, p: Point) {
8949        mix(h, p.x);
8950        mix(h, p.y);
8951    }
8952    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
8953    match shape {
8954        Shape::Polygon(pts) => {
8955            // The discriminant joins the hash so a polygon and a path of the same points can
8956            // never share an entry: they decode to different geometry.
8957            mix(&mut h, 11.0);
8958            for p in pts {
8959                mix_point(&mut h, *p);
8960            }
8961        }
8962        Shape::Path(path) => {
8963            mix(&mut h, 15.0);
8964            mix(&mut h, rule_bits(path.rule));
8965            for seg in &path.segs {
8966                match seg {
8967                    PathSeg::Move(a) => {
8968                        mix(&mut h, 0.0);
8969                        mix_point(&mut h, *a);
8970                    }
8971                    PathSeg::Line(a) => {
8972                        mix(&mut h, 1.0);
8973                        mix_point(&mut h, *a);
8974                    }
8975                    PathSeg::Quad(c, a) => {
8976                        mix(&mut h, 2.0);
8977                        mix_point(&mut h, *c);
8978                        mix_point(&mut h, *a);
8979                    }
8980                    PathSeg::Cubic(c1, c2, a) => {
8981                        mix(&mut h, 3.0);
8982                        mix_point(&mut h, *c1);
8983                        mix_point(&mut h, *c2);
8984                        mix_point(&mut h, *a);
8985                    }
8986                    PathSeg::Close => mix(&mut h, 4.0),
8987                }
8988            }
8989        }
8990        // Everything else puts its whole geometry in the record's own slots, so there is nothing
8991        // to parse and nothing worth caching.
8992        _ => return 0.0,
8993    }
8994    let masked = h & ((1u64 << 53) - 1);
8995    // 0 means "no key", so the one hash that lands there borrows its neighbor.
8996    if masked == 0 { 1.0 } else { masked as f64 }
8997}
8998
8999pub fn encode_path(path: &Path) -> String {
9000    let mut out = String::with_capacity(path.segs.len() * 16);
9001    for seg in &path.segs {
9002        if !out.is_empty() {
9003            out.push(' ');
9004        }
9005        match seg {
9006            PathSeg::Move(p) => out.push_str(&format!("M {} {}", p.x, p.y)),
9007            PathSeg::Line(p) => out.push_str(&format!("L {} {}", p.x, p.y)),
9008            PathSeg::Quad(c, p) => out.push_str(&format!("Q {} {} {} {}", c.x, c.y, p.x, p.y)),
9009            PathSeg::Cubic(a, b, p) => out.push_str(&format!(
9010                "C {} {} {} {} {} {}",
9011                a.x, a.y, b.x, b.y, p.x, p.y
9012            )),
9013            PathSeg::Close => out.push('Z'),
9014        }
9015    }
9016    out
9017}
9018
9019/// `FillRule` as a wire number: 0 non-zero, 1 even-odd.
9020fn rule_bits(rule: FillRule) -> f64 {
9021    match rule {
9022        FillRule::NonZero => 0.0,
9023        FillRule::EvenOdd => 1.0,
9024    }
9025}
9026
9027pub fn encode_ops(ops: &[DrawOp]) -> (Vec<f64>, Vec<String>) {
9028    fn color_bits(c: Color) -> f64 {
9029        let r = (c.r.clamp(0.0, 1.0) * 255.0) as u32;
9030        let g = (c.g.clamp(0.0, 1.0) * 255.0) as u32;
9031        let b = (c.b.clamp(0.0, 1.0) * 255.0) as u32;
9032        let a = (c.a.clamp(0.0, 1.0) * 255.0) as u32;
9033        ((a << 24) | (r << 16) | (g << 8) | b) as f64
9034    }
9035    #[allow(clippy::too_many_arguments)]
9036    fn push(
9037        k: OpCode,
9038        a: f64,
9039        b: f64,
9040        c: f64,
9041        d: f64,
9042        e: f64,
9043        f: f64,
9044        g: f64,
9045        col: Color,
9046        nums: &mut Vec<f64>,
9047    ) {
9048        nums.extend_from_slice(&[k as i32 as f64, a, b, c, d, e, f, g, color_bits(col)]);
9049    }
9050    /// The kind-18 prefix a non-plain stroke style emits, applying to the next stroke record,
9051    /// the same "modifier record" rule the gradient and font records follow. A plain style emits
9052    /// nothing, so a drawing without dashes or caps encodes exactly as it always did.
9053    fn stroke_style_record(style: &StrokeStyle, nums: &mut Vec<f64>, texts: &mut Vec<String>) {
9054        if style.is_plain() {
9055            return;
9056        }
9057        push(
9058            OpCode::StrokeStyle,
9059            match style.cap {
9060                LineCap::Butt => 0.0,
9061                LineCap::Round => 1.0,
9062                LineCap::Square => 2.0,
9063            },
9064            match style.join {
9065                LineJoin::Miter => 0.0,
9066                LineJoin::Round => 1.0,
9067                LineJoin::Bevel => 2.0,
9068            },
9069            style.miter_limit,
9070            style.dash_phase,
9071            style.dash.len() as f64,
9072            0.0,
9073            0.0,
9074            Color::CLEAR,
9075            nums,
9076        );
9077        texts.push(
9078            style
9079                .dash
9080                .iter()
9081                .map(|d| d.to_string())
9082                .collect::<Vec<_>>()
9083                .join(" "),
9084        );
9085    }
9086
9087    /// One shape record (the fill/stroke kinds shared by both ops).
9088    fn shape_record(
9089        stroke: bool,
9090        shape: &Shape,
9091        w: f64,
9092        col: Color,
9093        nums: &mut Vec<f64>,
9094        texts: &mut Vec<String>,
9095    ) {
9096        match shape {
9097            Shape::Rect(r) => push(
9098                if stroke {
9099                    OpCode::StrokeRect
9100                } else {
9101                    OpCode::FillRect
9102                },
9103                r.origin.x,
9104                r.origin.y,
9105                r.size.width,
9106                r.size.height,
9107                0.0,
9108                0.0,
9109                w,
9110                col,
9111                nums,
9112            ),
9113            Shape::RoundedRect(r, rad) => push(
9114                if stroke {
9115                    OpCode::StrokeRrect
9116                } else {
9117                    OpCode::FillRrect
9118                },
9119                r.origin.x,
9120                r.origin.y,
9121                r.size.width,
9122                r.size.height,
9123                *rad,
9124                0.0,
9125                w,
9126                col,
9127                nums,
9128            ),
9129            Shape::Ellipse(r) => push(
9130                if stroke {
9131                    OpCode::StrokeEllipse
9132                } else {
9133                    OpCode::FillEllipse
9134                },
9135                r.origin.x,
9136                r.origin.y,
9137                r.size.width,
9138                r.size.height,
9139                0.0,
9140                0.0,
9141                w,
9142                col,
9143                nums,
9144            ),
9145            Shape::Arc {
9146                rect,
9147                start_deg,
9148                sweep_deg,
9149            } => push(
9150                OpCode::StrokeArc,
9151                rect.origin.x,
9152                rect.origin.y,
9153                rect.size.width,
9154                rect.size.height,
9155                *start_deg,
9156                *sweep_deg,
9157                w,
9158                col,
9159                nums,
9160            ),
9161            Shape::Line(p1, p2) => {
9162                push(OpCode::Line, p1.x, p1.y, p2.x, p2.y, 0.0, 0.0, w, col, nums)
9163            }
9164            Shape::Polygon(pts) => {
9165                // Variable-length points ride the texts side-channel ("x,y x,y …"),
9166                // consumed in record order exactly like text payloads.
9167                push(
9168                    if stroke {
9169                        OpCode::StrokePolygon
9170                    } else {
9171                        OpCode::FillPolygon
9172                    },
9173                    geometry_key(shape),
9174                    0.0,
9175                    0.0,
9176                    0.0,
9177                    0.0,
9178                    0.0,
9179                    w,
9180                    col,
9181                    nums,
9182                );
9183                texts.push(
9184                    pts.iter()
9185                        .map(|p| format!("{},{}", p.x, p.y))
9186                        .collect::<Vec<_>>()
9187                        .join(" "),
9188                );
9189            }
9190            Shape::Path(path) => {
9191                // Same side-channel as Polygon, one token per segment (see `encode_path`).
9192                // The fill rule rides slot f; stroking ignores it.
9193                push(
9194                    if stroke {
9195                        OpCode::StrokePath
9196                    } else {
9197                        OpCode::FillPath
9198                    },
9199                    geometry_key(shape),
9200                    0.0,
9201                    0.0,
9202                    0.0,
9203                    0.0,
9204                    rule_bits(path.rule),
9205                    w,
9206                    col,
9207                    nums,
9208                );
9209                texts.push(encode_path(path));
9210            }
9211        }
9212    }
9213    /// A gradient applies to the next shape record, fill or stroke. Geometry per type rides
9214    /// slots a..d and the type discriminant slot f: one record shape, so every decoder keeps a
9215    /// single gradient code path.
9216    fn gradient_record(
9217        geo: [f64; 4],
9218        kind: f64,
9219        stops: &[(f64, Color)],
9220        nums: &mut Vec<f64>,
9221        texts: &mut Vec<String>,
9222    ) {
9223        push(
9224            OpCode::SetGradient,
9225            geo[0],
9226            geo[1],
9227            geo[2],
9228            geo[3],
9229            stops.len() as f64,
9230            kind,
9231            0.0,
9232            Color::CLEAR,
9233            nums,
9234        );
9235        texts.push(
9236            stops
9237                .iter()
9238                .map(|(o, c)| format!("{o},{:08x}", color_bits(*c) as u32))
9239                .collect::<Vec<_>>()
9240                .join(" "),
9241        );
9242    }
9243    let mut nums = Vec::with_capacity(ops.len() * 9);
9244    let mut texts = Vec::new();
9245    for op in ops {
9246        match op {
9247            DrawOp::Fill(shape, paint) => {
9248                // A gradient emits one kind-14 set-gradient record before its shape record;
9249                // the stops ride the texts channel as "offset,aarrggbb offset,aarrggbb …".
9250                // Geometry per type rides slots a..d, the type discriminant slot f: one
9251                // record shape, so every decoder keeps a single gradient code path.
9252                let col = match paint {
9253                    Paint::Solid(c) => *c,
9254                    Paint::Linear(g) => {
9255                        gradient_record(
9256                            [g.start.x, g.start.y, g.end.x, g.end.y],
9257                            0.0,
9258                            &g.stops,
9259                            &mut nums,
9260                            &mut texts,
9261                        );
9262                        // The gradient replaces the shape record's color, but it must be
9263                        // opaque, not clear: Skia-based decoders (Android Paint, OH_Drawing)
9264                        // modulate a shader by the paint alpha, so a clear slot would render
9265                        // the whole gradient invisible.
9266                        Color::WHITE
9267                    }
9268                    Paint::Radial(g) => {
9269                        gradient_record(
9270                            [g.center.x, g.center.y, g.radius, 0.0],
9271                            1.0,
9272                            &g.stops,
9273                            &mut nums,
9274                            &mut texts,
9275                        );
9276                        Color::WHITE
9277                    }
9278                };
9279                shape_record(false, shape, 0.0, col, &mut nums, &mut texts);
9280            }
9281            DrawOp::Stamp(st) => {
9282                // No copies means no drawing. Some native decoders use an empty point
9283                // buffer to mean an ordinary (unstamped) template, so omit the entire op.
9284                if st.at.is_empty() {
9285                    continue;
9286                }
9287                // A prefix record, then the coordinates, then the template shape record: the
9288                // "applies to the next record" rule the gradient, stroke style and font records
9289                // already follow, so a decoder needs no new kind of state, only one more slot in
9290                // the state it keeps. The template goes last because a decoder has to hold the
9291                // points before it can draw with them.
9292                //
9293                // The points are numbers on the numeric channel, not the texts channel a
9294                // polygon's points ride: this op exists for tens of thousands of them, and
9295                // formatting that many floats into a string every frame would cost more than
9296                // the individual ops it replaces.
9297                let col = match &st.paint {
9298                    Paint::Solid(c) => *c,
9299                    Paint::Linear(g) => {
9300                        gradient_record(
9301                            [g.start.x, g.start.y, g.end.x, g.end.y],
9302                            0.0,
9303                            &g.stops,
9304                            &mut nums,
9305                            &mut texts,
9306                        );
9307                        Color::WHITE
9308                    }
9309                    Paint::Radial(g) => {
9310                        gradient_record(
9311                            [g.center.x, g.center.y, g.radius, 0.0],
9312                            1.0,
9313                            &g.stops,
9314                            &mut nums,
9315                            &mut texts,
9316                        );
9317                        Color::WHITE
9318                    }
9319                };
9320                push(
9321                    OpCode::Stamp,
9322                    st.at.len() as f64,
9323                    0.0,
9324                    0.0,
9325                    0.0,
9326                    0.0,
9327                    0.0,
9328                    0.0,
9329                    Color::CLEAR,
9330                    &mut nums,
9331                );
9332                for chunk in st.at.chunks(4) {
9333                    // Written directly rather than through `push`: this is the one record whose
9334                    // last slot is a coordinate rather than a color, which is what lets four
9335                    // points fit with nothing wasted.
9336                    let mut rec = [
9337                        OpCode::StampPoints as i32 as f64,
9338                        0.0,
9339                        0.0,
9340                        0.0,
9341                        0.0,
9342                        0.0,
9343                        0.0,
9344                        0.0,
9345                        0.0,
9346                    ];
9347                    for (i, p) in chunk.iter().enumerate() {
9348                        rec[1 + i * 2] = p.x;
9349                        rec[2 + i * 2] = p.y;
9350                    }
9351                    nums.extend_from_slice(&rec);
9352                }
9353                match &st.stroke {
9354                    None => shape_record(false, &st.shape, 0.0, col, &mut nums, &mut texts),
9355                    Some(style) => {
9356                        stroke_style_record(style, &mut nums, &mut texts);
9357                        shape_record(true, &st.shape, style.width, col, &mut nums, &mut texts);
9358                    }
9359                }
9360            }
9361            DrawOp::Stroke(shape, paint, style) => {
9362                // A styled stroke emits one kind-18 record first, applying to the next stroke
9363                // only, the same "modifier record" shape the gradient uses, so decoders keep
9364                // one rule: consume, apply to the next shape record, reset.
9365                stroke_style_record(style, &mut nums, &mut texts);
9366                let col = match paint {
9367                    Paint::Solid(c) => *c,
9368                    Paint::Linear(g) => {
9369                        gradient_record(
9370                            [g.start.x, g.start.y, g.end.x, g.end.y],
9371                            0.0,
9372                            &g.stops,
9373                            &mut nums,
9374                            &mut texts,
9375                        );
9376                        Color::WHITE
9377                    }
9378                    Paint::Radial(g) => {
9379                        gradient_record(
9380                            [g.center.x, g.center.y, g.radius, 0.0],
9381                            1.0,
9382                            &g.stops,
9383                            &mut nums,
9384                            &mut texts,
9385                        );
9386                        Color::WHITE
9387                    }
9388                };
9389                shape_record(true, shape, style.width, col, &mut nums, &mut texts);
9390            }
9391            DrawOp::Clip(shape) => {
9392                // One record for every clip shape, with the shape kind in slot f and the
9393                // geometry in a..e; a path or polygon puts its points on the texts channel.
9394                // Encoding clips as a variant of `shape_record` instead would need a third
9395                // kind code per shape, which is five more numbers every decoder must learn.
9396                let (kind, geo, extra, payload): (f64, [f64; 4], f64, Option<String>) = match shape
9397                {
9398                    Shape::Rect(r) => (
9399                        0.0,
9400                        [r.origin.x, r.origin.y, r.size.width, r.size.height],
9401                        0.0,
9402                        None,
9403                    ),
9404                    Shape::RoundedRect(r, rad) => (
9405                        1.0,
9406                        [r.origin.x, r.origin.y, r.size.width, r.size.height],
9407                        *rad,
9408                        None,
9409                    ),
9410                    Shape::Ellipse(r) => (
9411                        2.0,
9412                        [r.origin.x, r.origin.y, r.size.width, r.size.height],
9413                        0.0,
9414                        None,
9415                    ),
9416                    // Slot a carries the geometry key for these two sub-kinds only. The other
9417                    // three put real geometry there, which is why the key rides the same slot
9418                    // the payload-bearing kinds leave empty.
9419                    Shape::Path(p) => (
9420                        3.0,
9421                        [geometry_key(shape), 0.0, 0.0, 0.0],
9422                        rule_bits(p.rule),
9423                        Some(encode_path(p)),
9424                    ),
9425                    Shape::Polygon(pts) => (
9426                        4.0,
9427                        [geometry_key(shape), 0.0, 0.0, 0.0],
9428                        0.0,
9429                        Some(
9430                            pts.iter()
9431                                .map(|p| format!("{},{}", p.x, p.y))
9432                                .collect::<Vec<_>>()
9433                                .join(" "),
9434                        ),
9435                    ),
9436                    // A clip to a line or an arc has no interior to clip to. Clipping to an
9437                    // empty region would blank everything after it, so clip to the shape's
9438                    // bounds instead: wrong in the same direction as no clip at all.
9439                    Shape::Line(..) | Shape::Arc { .. } => {
9440                        let r = shape.bounds();
9441                        (
9442                            0.0,
9443                            [r.origin.x, r.origin.y, r.size.width, r.size.height],
9444                            0.0,
9445                            None,
9446                        )
9447                    }
9448                };
9449                push(
9450                    OpCode::Clip,
9451                    geo[0],
9452                    geo[1],
9453                    geo[2],
9454                    geo[3],
9455                    extra,
9456                    kind,
9457                    0.0,
9458                    Color::CLEAR,
9459                    &mut nums,
9460                );
9461                if let Some(s) = payload {
9462                    texts.push(s);
9463                }
9464            }
9465            DrawOp::Text {
9466                text,
9467                at,
9468                size,
9469                color,
9470                anchor,
9471                font,
9472            } => {
9473                if *font != CanvasFont::default() {
9474                    push(
9475                        OpCode::SetFont,
9476                        f64::from(font.css_weight()),
9477                        f64::from(u8::from(font.italic)),
9478                        0.0,
9479                        0.0,
9480                        0.0,
9481                        0.0,
9482                        0.0,
9483                        Color::CLEAR,
9484                        &mut nums,
9485                    );
9486                    texts.push(
9487                        font.family_str()
9488                            .replace([FONT_LIST_FIELD, FONT_LIST_FAMILY], " "),
9489                    );
9490                }
9491                push(
9492                    OpCode::Text,
9493                    at.x,
9494                    at.y,
9495                    0.0,
9496                    0.0,
9497                    *size,
9498                    anchor.pack(),
9499                    0.0,
9500                    *color,
9501                    &mut nums,
9502                );
9503                texts.push(text.clone());
9504            }
9505            DrawOp::Image {
9506                image,
9507                rect,
9508                opacity,
9509            } => push(
9510                OpCode::Image,
9511                rect.origin.x,
9512                rect.origin.y,
9513                rect.size.width,
9514                rect.size.height,
9515                image.0 as f64,
9516                *opacity,
9517                0.0,
9518                Color::CLEAR,
9519                &mut nums,
9520            ),
9521            DrawOp::Save => push(
9522                OpCode::Save,
9523                0.0,
9524                0.0,
9525                0.0,
9526                0.0,
9527                0.0,
9528                0.0,
9529                0.0,
9530                Color::CLEAR,
9531                &mut nums,
9532            ),
9533            DrawOp::Restore => push(
9534                OpCode::Restore,
9535                0.0,
9536                0.0,
9537                0.0,
9538                0.0,
9539                0.0,
9540                0.0,
9541                0.0,
9542                Color::CLEAR,
9543                &mut nums,
9544            ),
9545            DrawOp::Concat(m) => push(
9546                OpCode::Concat,
9547                m.a,
9548                m.b,
9549                m.c,
9550                m.d,
9551                m.tx,
9552                m.ty,
9553                0.0,
9554                Color::CLEAR,
9555                &mut nums,
9556            ),
9557        }
9558    }
9559    (nums, texts)
9560}
9561
9562#[cfg(test)]
9563mod font_list_tests {
9564    use super::*;
9565
9566    #[test]
9567    fn css_weights_round_trip_and_snap_to_the_nearest_rung() {
9568        for w in FontWeight::ALL {
9569            assert_eq!(FontWeight::from_css(w.css()), w);
9570        }
9571        assert_eq!(FontWeight::from_css(0), FontWeight::UltraLight);
9572        assert_eq!(FontWeight::from_css(350), FontWeight::Regular); // ties go heavier
9573        assert_eq!(FontWeight::from_css(649), FontWeight::Semibold);
9574        assert_eq!(FontWeight::from_css(1200), FontWeight::Black);
9575    }
9576
9577    fn sans() -> FontFamilyInfo {
9578        FontFamilyInfo {
9579            family: "Day Sans".into(),
9580            faces: vec![
9581                FontFace {
9582                    name: "Regular".into(),
9583                    weight: FontWeight::Regular,
9584                    italic: false,
9585                },
9586                FontFace {
9587                    name: "Bold".into(),
9588                    weight: FontWeight::Bold,
9589                    italic: false,
9590                },
9591                FontFace {
9592                    name: "Light Italic".into(),
9593                    weight: FontWeight::Light,
9594                    italic: true,
9595                },
9596            ],
9597        }
9598    }
9599
9600    #[test]
9601    fn face_for_prefers_the_slant_then_the_nearest_weight() {
9602        let f = sans();
9603        assert!(f.has_bold() && f.has_italic());
9604        assert_eq!(f.face_for(FontWeight::Bold, false).unwrap().name, "Bold");
9605        assert_eq!(
9606            f.face_for(FontWeight::Semibold, false).unwrap().name,
9607            "Bold"
9608        );
9609        assert_eq!(
9610            f.face_for(FontWeight::Medium, false).unwrap().name,
9611            "Regular"
9612        );
9613        let tie = FontFamilyInfo {
9614            family: "Tie".into(),
9615            faces: vec![
9616                FontFace {
9617                    name: "Light".into(),
9618                    weight: FontWeight::Light,
9619                    italic: false,
9620                },
9621                FontFace {
9622                    name: "Bold".into(),
9623                    weight: FontWeight::Bold,
9624                    italic: false,
9625                },
9626            ],
9627        };
9628        // Medium sits 200 from both; the heavier face wins the tie.
9629        assert_eq!(
9630            tie.face_for(FontWeight::Medium, false).unwrap().name,
9631            "Bold"
9632        );
9633        assert_eq!(
9634            f.face_for(FontWeight::Black, true).unwrap().name,
9635            "Light Italic"
9636        );
9637        let none = FontFamilyInfo {
9638            family: "Empty".into(),
9639            faces: vec![],
9640        };
9641        assert!(none.face_for(FontWeight::Regular, false).is_none());
9642        assert!(!none.has_bold());
9643    }
9644
9645    #[test]
9646    fn the_shim_list_format_decodes_tolerantly() {
9647        let s = "Day Sans\u{1f}Regular\u{1f}400\u{1f}0\u{1f}\u{1f}700\u{1f}1\u{1f}Broken\u{1f}x\u{1f}0\
9648                 \u{1e}\u{1e}Day Mono\u{1f}Regular\u{1f}400\u{1f}0\u{1e}Faceless";
9649        let list = parse_font_list(s);
9650        assert_eq!(list.len(), 3);
9651        assert_eq!(list[0].family, "Day Sans");
9652        assert_eq!(list[0].faces.len(), 2, "the bad weight is skipped");
9653        assert_eq!(list[0].faces[1].name, "Bold Italic"); // synthesized from 700 + italic
9654        assert_eq!(list[1].family, "Day Mono");
9655        assert_eq!(list[2].family, "Faceless");
9656        assert!(list[2].faces.is_empty());
9657    }
9658
9659    #[test]
9660    fn approximate_metrics_scale_with_size_and_length() {
9661        let m = TextMetrics::approximate("abc", 10.0);
9662        assert_eq!((m.width, m.height, m.ascent), (18.0, 12.0, 9.0));
9663        assert_eq!(TextMetrics::approximate("", 10.0).width, 0.0);
9664    }
9665
9666    #[test]
9667    fn a_default_canvas_font_is_the_platform_face() {
9668        let f = CanvasFont::default();
9669        assert_eq!((f.family_str(), f.css_weight(), f.italic), ("", 0, false));
9670    }
9671}
9672
9673#[cfg(test)]
9674mod image_header_tests {
9675    use super::*;
9676
9677    /// A 4×2 PNG: signature, then an IHDR whose width and height are big-endian.
9678    fn png(w: u32, h: u32) -> Vec<u8> {
9679        let mut v = vec![0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a];
9680        v.extend(13u32.to_be_bytes());
9681        v.extend(b"IHDR");
9682        v.extend(w.to_be_bytes());
9683        v.extend(h.to_be_bytes());
9684        v
9685    }
9686
9687    /// A JPEG whose frame header sits behind one other segment, so the walk has to skip it.
9688    fn jpeg(w: u16, h: u16) -> Vec<u8> {
9689        let mut v = vec![0xFF, 0xD8]; // SOI
9690        v.extend([0xFF, 0xE0, 0x00, 0x04, 0x00, 0x00]); // APP0, length 4
9691        v.extend([0xFF, 0xC0, 0x00, 0x11, 0x08]); // SOF0, length 17, precision 8
9692        v.extend(h.to_be_bytes());
9693        v.extend(w.to_be_bytes());
9694        v
9695    }
9696
9697    #[test]
9698    fn a_header_states_the_size_before_anything_decodes() {
9699        assert_eq!(ImageFormat::dimensions(&png(512, 512)), Some((512, 512)));
9700        assert_eq!(ImageFormat::dimensions(&png(1, 65535)), Some((1, 65535)));
9701        // The JPEG walk must step over the APP0 segment to reach the frame header.
9702        assert_eq!(ImageFormat::dimensions(&jpeg(640, 480)), Some((640, 480)));
9703
9704        let mut gif = b"GIF89a".to_vec();
9705        gif.extend(320u16.to_le_bytes());
9706        gif.extend(240u16.to_le_bytes());
9707        assert_eq!(ImageFormat::dimensions(&gif), Some((320, 240)));
9708
9709        // A top-down BMP states its height as a negative number; the size is still positive.
9710        let mut bmp = b"BM".to_vec();
9711        bmp.resize(18, 0);
9712        bmp.extend(64i32.to_le_bytes());
9713        bmp.extend((-32i32).to_le_bytes());
9714        assert_eq!(ImageFormat::dimensions(&bmp), Some((64, 32)));
9715    }
9716
9717    #[test]
9718    fn a_truncated_or_unknown_header_answers_nothing_rather_than_a_guess() {
9719        assert_eq!(ImageFormat::dimensions(&[]), None);
9720        // The signature is there but the IHDR is not.
9721        assert_eq!(ImageFormat::dimensions(&png(8, 8)[..12]), None);
9722        // Not an image at all.
9723        assert_eq!(ImageFormat::dimensions(b"not an image"), None);
9724        // A JPEG that never reaches a frame header must not loop or invent a size.
9725        assert_eq!(
9726            ImageFormat::dimensions(&[0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x04, 0, 0]),
9727            None
9728        );
9729    }
9730}
9731
9732#[cfg(test)]
9733mod encode_ops_tests {
9734    use super::*;
9735
9736    /// The wire codes are a frozen dense table: any gap, duplicate, or variant missing from
9737    /// `ALL` breaks a decoder somewhere, so it must break here first.
9738    #[test]
9739    fn op_codes_are_dense_and_round_trip() {
9740        for (i, code) in OpCode::ALL.into_iter().enumerate() {
9741            assert_eq!(code as i32, i as i32, "{code:?} broke wire density");
9742            assert_eq!(OpCode::from_wire(i as f64), Some(code));
9743        }
9744        assert_eq!(OpCode::from_wire(OpCode::ALL.len() as f64), None);
9745        assert_eq!(OpCode::from_wire(-1.0), None);
9746        assert_eq!(OpCode::from_wire(0.5), None);
9747    }
9748
9749    /// Reference decode of a display list covering every op arm: the record stream must be
9750    /// whole 9-slot records of known codes, and the texts channel must carry exactly one
9751    /// entry per text-carrying record, in order: the contract every shim decoder assumes.
9752    #[test]
9753    fn encode_ops_emits_whole_records_and_matched_text_payloads() {
9754        let r = Rect::new(1.0, 2.0, 3.0, 4.0);
9755        let red = Color::rgb(1.0, 0.0, 0.0);
9756        let ops = vec![
9757            DrawOp::Fill(Shape::Rect(r), Paint::Solid(red)),
9758            DrawOp::Stroke(Shape::Rect(r), Paint::Solid(red), StrokeStyle::round(2.0)),
9759            DrawOp::Fill(Shape::RoundedRect(r, 5.0), Paint::Solid(red)),
9760            DrawOp::Fill(Shape::Ellipse(r), Paint::Solid(red)),
9761            // The documented asymmetry: a filled arc encodes as StrokeArc with width 0.
9762            DrawOp::Fill(
9763                Shape::Arc {
9764                    rect: r,
9765                    start_deg: 0.0,
9766                    sweep_deg: 90.0,
9767                },
9768                Paint::Solid(red),
9769            ),
9770            DrawOp::Stroke(
9771                Shape::Line(Point::new(0.0, 0.0), Point::new(9.0, 9.0)),
9772                Paint::Solid(red),
9773                StrokeStyle::width(1.0),
9774            ),
9775            DrawOp::Fill(
9776                Shape::Polygon(vec![
9777                    Point::new(0.0, 0.0),
9778                    Point::new(4.0, 0.0),
9779                    Point::new(2.0, 3.0),
9780                ]),
9781                Paint::Solid(red),
9782            ),
9783            DrawOp::Fill(
9784                Shape::Path(Path {
9785                    segs: vec![
9786                        PathSeg::Move(Point::new(0.0, 0.0)),
9787                        PathSeg::Line(Point::new(5.0, 5.0)),
9788                        PathSeg::Close,
9789                    ],
9790                    rule: FillRule::EvenOdd,
9791                }),
9792                Paint::Linear(LinearGradient::new(
9793                    UnitPoint::new(0.0, 0.0),
9794                    UnitPoint::new(1.0, 1.0),
9795                    vec![(0.0, red), (1.0, Color::WHITE)],
9796                )),
9797            ),
9798            DrawOp::Clip(Shape::Rect(r)),
9799            DrawOp::Clip(Shape::Polygon(vec![
9800                Point::new(0.0, 0.0),
9801                Point::new(1.0, 0.0),
9802                Point::new(0.0, 1.0),
9803            ])),
9804            DrawOp::Text {
9805                text: "hi".into(),
9806                at: Point::new(7.0, 8.0),
9807                size: 12.0,
9808                color: red,
9809                anchor: TextAnchor::LEADING,
9810                font: CanvasFont::default(),
9811            },
9812            DrawOp::Text {
9813                text: "bold".into(),
9814                at: Point::new(7.0, 8.0),
9815                size: 12.0,
9816                color: red,
9817                anchor: TextAnchor::CENTERED,
9818                font: CanvasFont {
9819                    family: Some("Day Sans".into()),
9820                    weight: Some(FontWeight::Bold),
9821                    italic: true,
9822                },
9823            },
9824            DrawOp::Save,
9825            DrawOp::Concat(Affine::IDENTITY),
9826            DrawOp::Restore,
9827            DrawOp::Image {
9828                image: BitmapId(7),
9829                rect: r,
9830                opacity: 0.5,
9831            },
9832        ];
9833        let (nums, texts) = encode_ops(&ops);
9834        assert_eq!(nums.len() % 9, 0, "partial record on the wire");
9835
9836        let mut expected_texts = 0usize;
9837        let mut decoded = Vec::new();
9838        for rec in nums.chunks(9) {
9839            let code = OpCode::from_wire(rec[0])
9840                .unwrap_or_else(|| panic!("unknown op code {} on the wire", rec[0]));
9841            decoded.push(code);
9842            expected_texts += match code {
9843                OpCode::Text
9844                | OpCode::FillPolygon
9845                | OpCode::StrokePolygon
9846                | OpCode::SetGradient
9847                | OpCode::FillPath
9848                | OpCode::StrokePath
9849                | OpCode::StrokeStyle
9850                | OpCode::SetFont => 1,
9851                // Clip carries a payload only for its path (3) / polygon (4) sub-kinds.
9852                OpCode::Clip => usize::from(rec[6] == 3.0 || rec[6] == 4.0),
9853                _ => 0,
9854            };
9855        }
9856        assert_eq!(
9857            texts.len(),
9858            expected_texts,
9859            "texts channel out of step with the records that consume it"
9860        );
9861        // No payload may carry the transport separator.
9862        assert!(texts.iter().all(|t| !t.contains('\u{1f}')));
9863
9864        let expected = {
9865            use OpCode::*;
9866            vec![
9867                FillRect,
9868                StrokeStyle, // ::round(2.0) is not plain, so the style modifier precedes
9869                StrokeRect,
9870                FillRrect,
9871                FillEllipse,
9872                StrokeArc, // the filled arc's stroke encoding…
9873                Line,
9874                FillPolygon,
9875                SetGradient, // gradient precedes its shape record
9876                FillPath,
9877                Clip,
9878                Clip,
9879                Text,
9880                SetFont, // a non-default font precedes its text record…
9881                Text,
9882                Save,
9883                Concat,
9884                Restore,
9885                Image,
9886            ]
9887        };
9888        assert_eq!(decoded, expected);
9889        // The bitmap id rides the numeric channel intact (an f64 holds a u64 id exactly well
9890        // past any id this process will mint), and nothing of an image reaches the texts channel.
9891        let img = nums
9892            .chunks(9)
9893            .find(|r| r[0] == OpCode::Image as i32 as f64)
9894            .expect("Image record");
9895        assert_eq!(&img[1..7], &[1.0, 2.0, 3.0, 4.0, 7.0, 0.5]);
9896        // …carrying the CSS weight and the slant, with the family on the texts channel.
9897        let font_rec = nums
9898            .chunks(9)
9899            .find(|r| r[0] == OpCode::SetFont as i32 as f64)
9900            .expect("SetFont record");
9901        assert_eq!(&font_rec[1..3], &[700.0, 1.0]);
9902        assert_eq!(texts.iter().filter(|t| *t == "Day Sans").count(), 1);
9903        // …with width 0, per the documented asymmetry.
9904        let arc = nums
9905            .chunks(9)
9906            .find(|r| r[0] == OpCode::StrokeArc as i32 as f64);
9907        assert_eq!(arc.map(|r| r[7]), Some(0.0));
9908        // A gradient-filled shape's color slot is opaque white, never clear (Skia decoders
9909        // modulate the shader by it).
9910        let path_rec = nums
9911            .chunks(9)
9912            .find(|r| r[0] == OpCode::FillPath as i32 as f64);
9913        assert_eq!(
9914            path_rec.map(|r| r[8] as u32),
9915            Some(0xFFFF_FFFF),
9916            "gradient shape record must carry opaque white"
9917        );
9918    }
9919
9920    #[test]
9921    fn variable_length_geometry_carries_a_content_key() {
9922        let path = |x: f64| {
9923            Shape::Path(Path {
9924                segs: vec![
9925                    PathSeg::Move(Point::new(x, 0.0)),
9926                    PathSeg::Cubic(
9927                        Point::new(1.0, 1.0),
9928                        Point::new(2.0, 2.0),
9929                        Point::new(3.0, 3.0),
9930                    ),
9931                    PathSeg::Close,
9932                ],
9933                rule: FillRule::NonZero,
9934            })
9935        };
9936        let poly = Shape::Polygon(vec![
9937            Point::new(0.0, 0.0),
9938            Point::new(1.0, 0.0),
9939            Point::new(0.0, 1.0),
9940        ]);
9941
9942        // Equal geometry keys equal though the two were built separately. The key exists for
9943        // this: a draw closure rebuilds its paths from scratch on every frame.
9944        assert_eq!(geometry_key(&path(0.0)), geometry_key(&path(0.0)));
9945        assert_ne!(geometry_key(&path(0.0)), geometry_key(&path(1.0)));
9946        // The fill rule decides what the path draws, so it belongs to the key.
9947        let even_odd = Shape::Path(Path {
9948            segs: match path(0.0) {
9949                Shape::Path(p) => p.segs,
9950                _ => unreachable!(),
9951            },
9952            rule: FillRule::EvenOdd,
9953        });
9954        assert_ne!(geometry_key(&path(0.0)), geometry_key(&even_odd));
9955        // A polygon and a path decode to different geometry and never share an entry.
9956        assert_ne!(geometry_key(&poly), geometry_key(&path(0.0)));
9957        // Fixed-size shapes keep 0: their geometry rides the record's own slots.
9958        assert_eq!(
9959            geometry_key(&Shape::Rect(Rect::new(0.0, 0.0, 1.0, 1.0))),
9960            0.0
9961        );
9962        // And a key survives an f64 wire slot exactly, which is what the 53-bit mask buys.
9963        let k = geometry_key(&path(0.0));
9964        assert!(
9965            k > 0.0 && k < (1u64 << 53) as f64 && k.fract() == 0.0,
9966            "{k}"
9967        );
9968
9969        // It reaches the wire in slot a, for exactly the ops whose payload rides the texts
9970        // channel, and never displaces geometry that is already there.
9971        let (nums, _) = encode_ops(&[
9972            DrawOp::Fill(path(0.0), Paint::Solid(Color::WHITE)),
9973            DrawOp::Fill(poly.clone(), Paint::Solid(Color::WHITE)),
9974            DrawOp::Clip(path(0.0)),
9975            DrawOp::Clip(Shape::Rect(Rect::new(1.0, 2.0, 3.0, 4.0))),
9976        ]);
9977        let slot_a = |code: OpCode| {
9978            nums.chunks(9)
9979                .find(|r| r[0] == code as i32 as f64)
9980                .unwrap_or_else(|| panic!("no {code:?} record"))[1]
9981        };
9982        assert_eq!(slot_a(OpCode::FillPath), geometry_key(&path(0.0)));
9983        assert_eq!(slot_a(OpCode::FillPolygon), geometry_key(&poly));
9984        let clips: Vec<&[f64]> = nums
9985            .chunks(9)
9986            .filter(|r| r[0] == OpCode::Clip as i32 as f64)
9987            .collect();
9988        assert_eq!(clips[0][1], geometry_key(&path(0.0)), "path clip keys");
9989        assert_eq!(
9990            &clips[1][1..5],
9991            &[1.0, 2.0, 3.0, 4.0],
9992            "a rect clip still puts its geometry in a..d"
9993        );
9994    }
9995}
9996
9997#[cfg(test)]
9998mod markup_tests {
9999    use super::*;
10000
10001    fn bold(range: std::ops::Range<usize>) -> TextRun {
10002        TextRun::font(
10003            range,
10004            FontSpec {
10005                style: Font::Body,
10006                weight: Some(FontWeight::Bold),
10007                ..Default::default()
10008            },
10009        )
10010    }
10011
10012    #[test]
10013    fn plain_text_is_escaped_in_both_dialects() {
10014        // The case a translated string will find: markup metacharacters in the content.
10015        let text = "5 < 6 & \"quoted\" <b>not bold</b>";
10016        for d in [MarkupDialect::Pango, MarkupDialect::QtHtml] {
10017            let m = runs_to_markup(text, &[], d, 16.0);
10018            assert!(!m.contains("<b>"), "content tag survived into markup: {m}");
10019            assert!(m.contains("&lt;b&gt;"), "{m}");
10020            assert!(m.contains("&amp;"), "{m}");
10021            assert!(m.contains("5 &lt; 6"), "{m}");
10022        }
10023    }
10024
10025    #[test]
10026    fn a_styled_run_is_wrapped_and_its_text_escaped() {
10027        let text = "a <b> c";
10028        let m = runs_to_markup(text, &[bold(2..5)], MarkupDialect::Pango, 16.0);
10029        assert_eq!(m, "a <b>&lt;b&gt;</b> c");
10030    }
10031
10032    #[test]
10033    fn color_and_monospace_differ_per_dialect() {
10034        let text = "code";
10035        let run = TextRun {
10036            range: 0..4,
10037            font: FontSpec {
10038                style: Font::Body,
10039                monospace: true,
10040                ..Default::default()
10041            },
10042            color: Some(Color::rgb(1.0, 0.0, 0.0)),
10043            ..TextRun::default()
10044        };
10045        let pango = runs_to_markup(text, std::slice::from_ref(&run), MarkupDialect::Pango, 16.0);
10046        assert!(pango.contains("foreground=\"#ff0000\""), "{pango}");
10047        assert!(pango.contains("font_family=\"monospace\""), "{pango}");
10048        let qt = runs_to_markup(
10049            text,
10050            std::slice::from_ref(&run),
10051            MarkupDialect::QtHtml,
10052            16.0,
10053        );
10054        assert!(qt.contains("color:#ff0000"), "{qt}");
10055        // Qt takes its fixed face from <code>: a `font-family:monospace` style attribute
10056        // renders proportional (observed on Qt 6.11).
10057        assert!(qt.contains("<code>") && qt.contains("</code>"), "{qt}");
10058    }
10059
10060    #[test]
10061    fn the_new_attributes_reach_both_dialects() {
10062        let run = TextRun {
10063            range: 0..2,
10064            font: FontSpec::default().scaled(1.5),
10065            background: Some(Color::rgb(0.0, 1.0, 0.0)),
10066            underline: Underline::Single,
10067            ..TextRun::default()
10068        };
10069        let pango = runs_to_markup("hi", std::slice::from_ref(&run), MarkupDialect::Pango, 16.0);
10070        assert!(pango.contains("background=\"#00ff00\""), "{pango}");
10071        // Pango takes an absolute size in 1/1024 pt (16 pt base × 1.5 = 24 pt), because the
10072        // relative attributes are Pango 1.50's and an unknown attribute empties the whole label.
10073        assert!(pango.contains("size=\"24576\""), "{pango}");
10074        assert!(pango.contains("<u>hi</u>"), "{pango}");
10075        let qt = runs_to_markup(
10076            "hi",
10077            std::slice::from_ref(&run),
10078            MarkupDialect::QtHtml,
10079            16.0,
10080        );
10081        assert!(qt.contains("background-color:#00ff00"), "{qt}");
10082        // Qt takes points: 16 pt base × 1.5 (observed; its CSS subset ignores a percentage).
10083        assert!(qt.contains("font-size:24pt"), "{qt}");
10084        assert!(qt.contains("<u>hi</u>"), "{qt}");
10085    }
10086
10087    #[test]
10088    fn a_link_target_is_escaped_too() {
10089        // A URL carrying `&` between query parameters is ordinary, and unescaped it truncates
10090        // the attribute and swallows the rest of the label.
10091        let text = "docs";
10092        let run = TextRun {
10093            range: 0..4,
10094            link: Some("https://x.dev/?a=1&b=2".into()),
10095            ..TextRun::default()
10096        };
10097        let m = runs_to_markup(text, &[run], MarkupDialect::Pango, 16.0);
10098        assert!(m.contains("a=1&amp;b=2"), "{m}");
10099    }
10100
10101    #[test]
10102    fn tags_nest_and_close_in_reverse() {
10103        let run = TextRun {
10104            range: 0..2,
10105            font: FontSpec {
10106                style: Font::Body,
10107                weight: Some(FontWeight::Bold),
10108                italic: true,
10109                ..Default::default()
10110            },
10111            strikethrough: true,
10112            link: Some("u".into()),
10113            ..TextRun::default()
10114        };
10115        let m = runs_to_markup("hi", &[run], MarkupDialect::Pango, 16.0);
10116        assert_eq!(m, "<a href=\"u\"><b><i><s>hi</s></i></b></a>");
10117    }
10118
10119    #[test]
10120    fn runs_out_of_bounds_are_skipped_not_panicked() {
10121        // `runs_are_valid` rejects these upstream; this is the belt-and-braces path.
10122        let m = runs_to_markup("hi", &[bold(0..99)], MarkupDialect::Pango, 16.0);
10123        assert_eq!(m, "hi");
10124    }
10125
10126    #[test]
10127    fn validation_catches_the_four_ways_runs_go_wrong() {
10128        let text = "héllo";
10129        assert!(runs_are_valid(text, &[bold(0..1)]).is_ok());
10130        // Overlapping.
10131        assert!(runs_are_valid(text, &[bold(0..3), bold(2..4)]).is_err());
10132        // Past the end.
10133        assert!(runs_are_valid(text, &[bold(0..99)]).is_err());
10134        // Inverted. Built from parts, since a literal `3..1` is a clippy error in its own right.
10135        let (hi, lo) = (3, 1);
10136        assert!(runs_are_valid(text, &[bold(hi..lo)]).is_err());
10137        // Splitting the 2-byte `é`.
10138        assert!(runs_are_valid(text, &[bold(0..2)]).is_err());
10139    }
10140}
10141
10142#[cfg(test)]
10143mod route_of_url_tests {
10144    use super::route_of_url;
10145
10146    #[test]
10147    fn strips_the_scheme_and_keeps_route_and_params() {
10148        assert_eq!(
10149            route_of_url("notes://mail/inbox?hint=x"),
10150            "mail/inbox?hint=x"
10151        );
10152        assert_eq!(route_of_url("notes://home"), "home");
10153        // No scheme: already a route, unchanged.
10154        assert_eq!(route_of_url("mail/inbox"), "mail/inbox");
10155        assert_eq!(route_of_url(""), "");
10156        // Percent-encoding passes through; the route parser decodes, not this mapping.
10157        assert_eq!(route_of_url("n://a/b%2Fc?q=1%202"), "a/b%2Fc?q=1%202");
10158    }
10159}
10160
10161#[cfg(test)]
10162mod builtin_kind_tests {
10163    use super::*;
10164
10165    /// Every built-in round-trips through its wire key, and the keys are unique. Guards the
10166    /// `builtin_kinds!` expansion: a copy-paste slip in the table would alias two kinds.
10167    #[test]
10168    fn keys_round_trip_and_are_unique() {
10169        let mut seen = std::collections::HashSet::new();
10170        for &b in Builtin::ALL {
10171            assert_eq!(Builtin::from_key(b.key()), Some(b), "{b:?} key round-trip");
10172            assert!(seen.insert(b.key()), "duplicate key {:?}", b.key());
10173            assert!(
10174                b.key().starts_with("day."),
10175                "built-in {b:?} must use the reserved `day.` prefix"
10176            );
10177        }
10178    }
10179
10180    /// The `kinds::*` constants are the enum's keys, so the two spellings cannot drift.
10181    #[test]
10182    fn kinds_constants_match_the_enum() {
10183        assert_eq!(kinds::LABEL, Builtin::Label.key());
10184        assert_eq!(kinds::LIST_CELL, Builtin::ListCell.key());
10185        assert_eq!(kinds::COVER, Builtin::Cover.key());
10186        assert_eq!(kinds::INSPECTOR, Builtin::Inspector.key());
10187        assert_eq!(kinds::TREE, Builtin::Tree.key());
10188        // 19 after `Tabs`/`TabsPage` retired (the tab bar is a NAV presentation, not a kind),
10189        // +2 for the inspector split and its panes (docs/inspector.md), +1 for the tree
10190        // (docs/tree.md).
10191        assert_eq!(Builtin::ALL.len(), 25);
10192    }
10193
10194    /// An extension piece's kind is not a built-in.
10195    #[test]
10196    fn extension_kinds_are_not_builtin() {
10197        assert_eq!(Builtin::from_key("acme.combobox"), None);
10198        assert_eq!(Builtin::from_key("day.not_a_real_kind"), None);
10199    }
10200}
10201
10202#[cfg(test)]
10203mod locale_tests {
10204    /// POSIX locale strings are not BCP-47 tags, and "C" is not a language; that difference is
10205    /// the job of `posix_locale_hints` (§12.2).
10206    #[test]
10207    fn posix_hints_parse_and_drop_the_c_locale() {
10208        // The parsing is exercised through the same normalization the function applies.
10209        let normalize = |v: &str| v.split('.').next().unwrap_or(v).replace('_', "-");
10210        assert_eq!(normalize("fr_FR.UTF-8"), "fr-FR");
10211        assert_eq!(normalize("en_US"), "en-US");
10212        assert_eq!(normalize("C"), "C");
10213        // A real read never panics whatever this host's environment holds.
10214        let hints = super::posix_locale_hints();
10215        assert!(
10216            hints
10217                .iter()
10218                .all(|h| !h.is_empty() && h != "C" && h != "POSIX")
10219        );
10220    }
10221}
10222
10223#[cfg(test)]
10224mod sidetable_tests {
10225    use super::sidetable::{SideTable, sweep};
10226    use std::cell::Cell;
10227    use std::rc::Rc;
10228
10229    /// The registry exists so that one `sweep(key)` clears every table without any
10230    /// table needing its own line in a backend's `release()`.
10231    #[test]
10232    fn sweep_clears_every_registered_table_and_runs_teardowns() {
10233        let torn = Rc::new(Cell::new(0u32));
10234        let t2 = torn.clone();
10235        let plain: SideTable<&'static str> = SideTable::new();
10236        let hooked: SideTable<u32> = SideTable::with_teardown(move |_| t2.set(t2.get() + 1));
10237
10238        plain.insert(7, "a");
10239        hooked.insert(7, 1);
10240        hooked.insert(8, 2);
10241        sweep(7);
10242        assert!(!plain.contains(7));
10243        assert!(!hooked.contains(7), "swept from every table");
10244        assert!(hooked.contains(8), "other keys untouched");
10245        assert_eq!(torn.get(), 1, "teardown ran for the swept value");
10246
10247        // remove() runs the teardown too; take() bypasses it for ownership transfer.
10248        hooked.remove(8);
10249        assert_eq!(torn.get(), 2);
10250        hooked.insert(9, 3);
10251        assert_eq!(hooked.take(9), Some(3));
10252        assert_eq!(torn.get(), 2, "take() skips the hook");
10253    }
10254
10255    #[test]
10256    fn contain_returns_default_on_panic() {
10257        let ok = super::ffi_guard::contain(0i32, || 5);
10258        assert_eq!(ok, 5);
10259        let prev = std::panic::take_hook();
10260        std::panic::set_hook(Box::new(|_| {}));
10261        let contained = super::ffi_guard::contain(-1i32, || panic!("boom"));
10262        std::panic::set_hook(prev);
10263        assert_eq!(contained, -1, "the panic must not escape the guard");
10264    }
10265}
10266
10267#[cfg(test)]
10268mod cursor_tests {
10269    use super::Cursor;
10270
10271    /// Every named cursor has a distinct CSS keyword, and `NAMED` lists each exactly once: the
10272    /// gallery and every backend's table key on the keyword.
10273    #[test]
10274    fn named_cursors_have_distinct_css_names() {
10275        let mut seen = std::collections::BTreeSet::new();
10276        for c in Cursor::NAMED.iter() {
10277            assert!(
10278                seen.insert(c.css_name().to_string()),
10279                "duplicate: {}",
10280                c.css_name()
10281            );
10282            assert!(!matches!(c, Cursor::Native(_)));
10283        }
10284        assert_eq!(seen.len(), Cursor::NAMED.len());
10285        assert_eq!(Cursor::native("dragCopy").css_name(), "dragCopy");
10286        assert_eq!(Cursor::default(), Cursor::Default);
10287    }
10288}
10289
10290#[cfg(test)]
10291mod text_anchor_tests {
10292    /// The anchor arithmetic every backend repeats. A drawing whose text lands in the wrong
10293    /// corner is a per-backend bug that only a screenshot catches, so the shared definition is
10294    /// pinned here and each shim is written to match it.
10295    #[test]
10296    fn text_anchor_offsets_place_the_line_box() {
10297        use crate::props::TextAlign;
10298        use crate::{TextAnchor, TextVAlign};
10299        // A 40-wide, 20-tall line box whose baseline sits 16 below its top.
10300        let (w, h, asc) = (40.0, 20.0, 16.0);
10301        let at = |ha, va| TextAnchor { h: ha, v: va }.offset(w, h, asc);
10302
10303        // The default is the drawing origin itself, every backend's native "draw here".
10304        assert_eq!(at(TextAlign::Leading, TextVAlign::Top), (0.0, 0.0));
10305        assert_eq!(TextAnchor::default(), TextAnchor::LEADING);
10306        // Horizontal: the box's leading edge, its middle, its trailing edge.
10307        assert_eq!(at(TextAlign::Center, TextVAlign::Top).0, -20.0);
10308        assert_eq!(at(TextAlign::Trailing, TextVAlign::Top).0, -40.0);
10309        // Vertical: top, middle, the baseline itself, bottom.
10310        assert_eq!(at(TextAlign::Leading, TextVAlign::Middle).1, -10.0);
10311        assert_eq!(at(TextAlign::Leading, TextVAlign::Baseline).1, -16.0);
10312        assert_eq!(at(TextAlign::Leading, TextVAlign::Bottom).1, -20.0);
10313        // The two named placements are the ones the two-variant enum used to have.
10314        assert_eq!(TextAnchor::CENTERED.offset(w, h, asc), (-20.0, -10.0));
10315        assert_eq!(TextAnchor::TRAILING.offset(w, h, asc), (-40.0, 0.0));
10316    }
10317
10318    /// The wire code the serializing backends (qt, xaml, arkui, android, web) decode by hand.
10319    #[test]
10320    fn text_anchor_packs_into_one_slot_and_round_trips() {
10321        use crate::props::TextAlign;
10322        use crate::{TextAnchor, TextVAlign};
10323        let mut seen = std::collections::BTreeSet::new();
10324        for h in [TextAlign::Leading, TextAlign::Center, TextAlign::Trailing] {
10325            for v in [
10326                TextVAlign::Top,
10327                TextVAlign::Middle,
10328                TextVAlign::Baseline,
10329                TextVAlign::Bottom,
10330            ] {
10331                let a = TextAnchor { h, v };
10332                let code = a.pack();
10333                assert!(
10334                    (0.0..=11.0).contains(&code),
10335                    "{code} outside the packed range"
10336                );
10337                assert!(seen.insert(code as u64), "two anchors share code {code}");
10338                assert_eq!(TextAnchor::unpack(code), a);
10339            }
10340        }
10341        assert_eq!(seen.len(), 12);
10342        // The shims decode as `h = code / 4`, `v = code % 4` in integer arithmetic.
10343        assert_eq!(TextAnchor::LEADING.pack(), 0.0);
10344        assert_eq!(TextAnchor::CENTERED.pack(), 5.0);
10345        // Junk answers the default rather than failing inside a native draw callback.
10346        assert_eq!(TextAnchor::unpack(-3.0), TextAnchor::LEADING);
10347        assert_eq!(TextAnchor::unpack(99.0), TextAnchor::unpack(11.0));
10348    }
10349
10350    /// The two shapes a backend's own metrics arrive in. Both land on the same contract: the line
10351    /// box's top-leading corner is the origin, and `ink` is relative to it.
10352    #[test]
10353    fn metrics_convert_from_a_backends_own_shape() {
10354        use crate::{Rect, TextMetrics};
10355        // Baseline-relative, y up-negative; Core Text, Skia and Qt all report like this.
10356        let m = TextMetrics::from_baseline(
10357            40.0,
10358            16.0,
10359            4.0,
10360            11.0,
10361            // Ink starting 1 right of the origin, from 11 above the baseline to 2 below it.
10362            Rect::new(1.0, -11.0, 38.0, 13.0),
10363        );
10364        assert_eq!(
10365            (m.width, m.height, m.ascent, m.cap_height),
10366            (40.0, 20.0, 16.0, 11.0)
10367        );
10368        // Shifted down by the ascent: the ink now starts 5 below the line box's top, which is
10369        // where a cap begins in a slot whose baseline is at 16.
10370        assert_eq!(m.ink, Rect::new(1.0, 5.0, 38.0, 13.0));
10371        assert_eq!(m.ascent - m.cap_height, m.ink.origin.y);
10372
10373        // The eight-slot wire form is already line-box-relative and passes straight through.
10374        let w = TextMetrics::from_slots(&[40.0, 20.0, 16.0, 11.0, 1.0, 5.0, 38.0, 13.0]);
10375        assert_eq!(w, m);
10376    }
10377
10378    /// The fallback must be usable, not merely present: a caller frames text with it on a toolkit
10379    /// that cannot measure, and every relation it relies on has to hold.
10380    #[test]
10381    fn the_approximation_is_internally_consistent() {
10382        use crate::TextMetrics;
10383        let m = TextMetrics::approximate("Agy", 20.0);
10384        assert!(m.ascent < m.height, "the baseline sits inside the line box");
10385        assert!(
10386            m.cap_height < m.ascent,
10387            "caps do not reach above the ascent"
10388        );
10389        // The ink box is the whole line box: a superset, so an overlap test using it can only be
10390        // too cautious. Never a claim to be tighter than it knows.
10391        assert_eq!(m.ink.origin.x, 0.0);
10392        assert_eq!(m.ink.origin.y, 0.0);
10393        assert_eq!(m.ink.size.width, m.width);
10394        assert_eq!(m.ink.size.height, m.height);
10395        // Empty text still answers a usable (zero-width, full-height) slot.
10396        let e = TextMetrics::approximate("", 20.0);
10397        assert_eq!(e.width, 0.0);
10398        assert!(e.height > 0.0);
10399    }
10400}
10401
10402#[cfg(test)]
10403mod cap_list_tests {
10404    use super::Cap;
10405
10406    #[test]
10407    fn every_capability_is_listed_once_in_its_place() {
10408        for (i, cap) in Cap::ALL.iter().enumerate() {
10409            assert_eq!(cap.ordinal(), i, "{cap:?} is out of place in Cap::ALL");
10410        }
10411    }
10412}