Skip to main content

unpeel_surface_guest/
lib.rs

1//! Guest-side UI primitives for Surface.
2//!
3//! This is the `no_std` authoring toolkit for sandboxed Unpeel Surface WASM
4//! guests. The full guest/host command and event contract is re-exported, so
5//! a guest needs only `unpeel-surface-guest` in its dependency list.
6//!
7//! Every demo guest used to hand-roll the same machinery: a command buffer
8//! with a clamped push, f32 state in `AtomicU32` bit patterns, dual
9//! dark/light palettes, scroll physics that settle exactly, a composer-backed
10//! text input, sparkles, checkboxes, scrollbars. This crate is that machinery
11//! as reusable, `no_std`, const-constructible primitives, so a new UI guest
12//! is mostly layout and intent.
13//!
14//! Design rules the primitives enforce:
15//!
16//! - **Everything settles.** Animated values snap exactly onto their targets
17//!   ([`anim::settle`], [`scroll::Scroller`]) so a resting scene is
18//!   byte-stable and the host's dirty-frame skip can idle the surface. That
19//!   is also why the focused caret is steady, not blinking.
20//! - **Statics, not allocation.** All state types have `const fn new` and use
21//!   interior atomics, so guests declare them as plain `static`s.
22//! - **The palette is semantic.** Widgets take a [`theme::Palette`]; guests
23//!   flip the whole scheme from one `EVENT_THEME` with
24//!   [`theme::ThemeState::on_event`].
25
26#![no_std]
27
28pub use unpeel_surface_abi::*;
29
30pub mod anim;
31pub mod scene;
32pub mod scroll;
33pub mod text_field;
34pub mod theme;
35pub mod widgets;
36
37pub use anim::{ease_out, settle, with_alpha};
38pub use scene::SceneBuffer;
39pub use scroll::Scroller;
40pub use text_field::TextField;
41pub use theme::{Palette, ThemeState};
42
43use core::sync::atomic::{AtomicU32, Ordering};
44
45/// Estimated Geist advance per glyph per scale unit, for carets and ellipsis
46/// truncation until the ABI grows a measure capability.
47pub const GEIST_ADVANCE: f32 = 6.4;
48
49/// An `f32` stored as bits in an `AtomicU32` — the standard pattern for
50/// mutable guest state in `no_std` statics.
51pub struct F32Cell(AtomicU32);
52
53impl F32Cell {
54    pub const fn new(value: f32) -> Self {
55        Self(AtomicU32::new(value.to_bits()))
56    }
57
58    pub fn get(&self) -> f32 {
59        f32::from_bits(self.0.load(Ordering::Relaxed))
60    }
61
62    pub fn set(&self, value: f32) {
63        self.0.store(value.to_bits(), Ordering::Relaxed);
64    }
65}
66
67/// A screen-space rectangle used for widget geometry and hit tests.
68#[derive(Clone, Copy, Debug, PartialEq)]
69pub struct Rect {
70    pub x: f32,
71    pub y: f32,
72    pub w: f32,
73    pub h: f32,
74}
75
76impl Rect {
77    pub const fn new(x: f32, y: f32, w: f32, h: f32) -> Self {
78        Self { x, y, w, h }
79    }
80
81    pub fn contains(&self, x: f32, y: f32) -> bool {
82        x >= self.x && x <= self.x + self.w && y >= self.y && y <= self.y + self.h
83    }
84}
85
86#[cfg(test)]
87mod tests {
88    use super::*;
89
90    #[test]
91    fn f32_cell_round_trips() {
92        let cell = F32Cell::new(1.5);
93        assert_eq!(cell.get(), 1.5);
94        cell.set(-3.25);
95        assert_eq!(cell.get(), -3.25);
96    }
97
98    #[test]
99    fn rect_contains_is_edge_inclusive() {
100        let rect = Rect::new(10.0, 20.0, 100.0, 40.0);
101        assert!(rect.contains(10.0, 20.0));
102        assert!(rect.contains(110.0, 60.0));
103        assert!(!rect.contains(9.9, 30.0));
104        assert!(!rect.contains(50.0, 60.1));
105    }
106}