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}