refactor: organize host modules and document architecture with UML
Verify Tessera GUI / verify (push) Failing after 2m2s

This commit is contained in:
2026-10-25 21:25:43 +08:00
parent 48fcb96f42
commit 18376793b0
85 changed files with 4450 additions and 3653 deletions
+66
View File
@@ -0,0 +1,66 @@
# Tessera System UI
An internal Rust widget library for Tessera's own management windows and developer
tools. It is independent of Endor's `ui` global, `UiNode`, AST and VM. Guest scripts
cannot construct or control these management widgets. Only geometry, font shaping
and display-list rendering are shared with the page renderer.
## Modules
- `interaction.rs`: stable semantic widget IDs, hit testing, pointer capture,
release-inside activation, drag-out cancellation, keyboard focus traversal,
Enter/Space activation, disabled controls and cursor roles.
- `theme.rs`: neutral/error/success colors, accent presets, readable custom accents
and shared idle/hover/pressed/selected colors.
- `widgets.rs`: button, tab, toggle, text field chrome, borderless inline prompt target, selectable row, color swatch,
splitter and scrollbar thumb. Text is clipped to its widget bounds. Hover, pressed,
selection, keyboard focus and disabled states compose consistently.
- `mod.rs`: public interface used by management surfaces.
## Frame contract
All widget coordinates are logical pixels. Build a `Ui<Action>` from the current
`Theme` and a clone of retained `Interaction`. Actions are host-defined, `Hash`able
values; IDs come from semantic action keys, never screen coordinates or changing
labels. Explicit decoration IDs are scoped by widget kind and region.
```rust,ignore
let mut ui = Ui::new(Theme::new(accent), interaction.clone());
ui.button(bounds, Action::Refresh,
Button::new("Refresh").enabled(can_refresh));
ui.button(tab_bounds, Action::SelectTab(Tab::Sources),
Button::new("Sources").role(Role::Tab).selected(is_sources));
ui.text_field(input_bounds, Action::FocusEditor, editor_focused);
```
Store `ui.targets` with the newly produced layout and render `ui.list` through the
native display-list backend. Reconcile retained interaction against the new targets;
request one more redraw when a target moves, disappears or changes enabled state.
This settles hover under a stationary pointer after a layout change without a timer
or continuous rendering loop. Paint and register splitters after pane content and
toolbars so neither their appearance nor their hit regions are obscured.
Preserve clipping and scale every primitive, including
focus outlines, when converting logical coordinates to physical pixels.
Dispatch pointer movement, press and release to `Interaction`. Press establishes
capture; a button action is returned only when released inside the same enabled
widget. Text fields focus on press, while drag handles perform host-side resizing
or scrolling during capture. Pointer exit clears hover, focus loss cancels all
capture, and disabled targets block click-through to controls behind them.
Tab / Shift-Tab traverse enabled controls; Enter / Space activate a focused button
on key release. The host's editor keeps plain Tab for indentation and Shift-Tab for
leaving the editor. Rows and drag handles are excluded from Tab traversal. Text
editing, clipboard and IME remain host adapters; the widget layer owns their chrome
and focus presentation. `inline_input` registers a text-input target without a
background or focus border; a terminal-style host draws its own caret in the same
scrollable stream as output. `src/shell/clipboard.rs` guarantees UTF-8 for macOS clipboard
subprocesses, independent of Finder's locale.
Tessera's developer tools are the first consumer. Domain actions, HTTP calls,
source navigation and Console execution remain in `developer_tools.rs` and its page modules; none of
those concepts enter this library. The library currently renders synchronously
with immediate state feedback; it is not an Endor component implementation, an
OS accessibility bridge or a separately published Cargo crate.
The built-in start page lives in `ui_bridge/start_page.endor` and uses the ordinary guest Page/Block renderer. System UI no longer paints a welcome overlay. Native window chrome uses the same neutral palette, while each tool Page has its own interaction state.
+204
View File
@@ -0,0 +1,204 @@
use crate::geometry::{Point, Rect};
use std::hash::{Hash, Hasher};
/// Stable across frames, resizing and text changes. Use semantic keys, never row indices.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct WidgetId(u64);
impl WidgetId {
pub fn new(key: impl Hash) -> Self {
let mut hash = std::collections::hash_map::DefaultHasher::new();
key.hash(&mut hash);
Self(hash.finish())
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Axis {
Horizontal,
Vertical,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Role {
Button,
Tab,
Toggle,
TextField,
Row,
Swatch,
Splitter(Axis),
Scrollbar(Axis),
}
impl Role {
fn focusable(self) -> bool {
!matches!(self, Self::Splitter(_) | Self::Scrollbar(_) | Self::Row)
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Cursor {
Default,
Pointer,
Text,
ResizeHorizontal,
ResizeVertical,
Grab,
Disabled,
}
#[derive(Clone, Debug)]
pub struct Target<A> {
pub id: WidgetId,
pub rect: Rect,
pub role: Role,
pub enabled: bool,
pub action: Option<A>,
}
#[derive(Clone, Copy, Debug)]
pub struct VisualState {
pub hovered: bool,
pub pressed: bool,
pub focused: bool,
pub selected: bool,
pub enabled: bool,
}
/// Retained input state for an immediate-mode frame. Actions fire on release inside
/// the same enabled control, so dragging away cancels a click.
#[derive(Clone, Debug, Default)]
pub struct Interaction {
pointer: Option<Point>,
hovered: Option<WidgetId>,
pointer_active: Option<WidgetId>,
key_active: Option<WidgetId>,
focused: Option<WidgetId>,
keyboard_focus: bool,
}
impl Interaction {
pub fn hit<'a, A>(&self, targets: &'a [Target<A>]) -> Option<&'a Target<A>> {
let p = self.pointer?;
targets.iter().rev().find(|t| t.rect.contains(p))
}
pub fn pointer_moved<A>(&mut self, p: Point, targets: &[Target<A>]) {
self.pointer = Some(p);
self.hovered = self.hit(targets).map(|t| t.id);
}
pub fn pointer_left(&mut self) {
self.pointer = None;
self.hovered = None;
}
pub fn press<A: Clone>(&mut self, targets: &[Target<A>]) -> Option<Target<A>> {
self.key_active = None;
self.keyboard_focus = false;
let target = self.hit(targets).filter(|t| t.enabled).cloned();
self.pointer_active = target.as_ref().map(|t| t.id);
self.focused = target.as_ref().filter(|t| t.role.focusable()).map(|t| t.id);
target
}
pub fn release<A: Clone>(&mut self, targets: &[Target<A>]) -> Option<A> {
let active = self.pointer_active.take()?;
self.hit(targets)
.filter(|t| t.enabled && t.id == active && t.role != Role::TextField)
.and_then(|t| t.action.clone())
}
pub fn cancel(&mut self) {
self.pointer_active = None;
self.key_active = None;
}
pub fn blur(&mut self) {
self.cancel();
self.focused = None;
self.keyboard_focus = false;
self.pointer_left();
}
pub fn reconcile<A>(&mut self, targets: &[Target<A>]) -> bool {
let before = (
self.hovered,
self.pointer_active,
self.focused,
self.key_active,
);
let exists = |id| targets.iter().any(|t| t.id == id && t.enabled);
self.focused = self.focused.filter(|id| exists(*id));
self.pointer_active = self.pointer_active.filter(|id| exists(*id));
self.key_active = self.key_active.filter(|id| exists(*id));
self.hovered = self.hit(targets).map(|t| t.id);
before
!= (
self.hovered,
self.pointer_active,
self.focused,
self.key_active,
)
}
pub fn focused<'a, A>(&self, targets: &'a [Target<A>]) -> Option<&'a Target<A>> {
targets
.iter()
.find(|t| Some(t.id) == self.focused && t.enabled)
}
pub fn focus_next<A: Clone>(&mut self, targets: &[Target<A>], back: bool) -> Option<Target<A>> {
self.cancel();
self.keyboard_focus = true;
let candidates = targets
.iter()
.filter(|t| t.enabled && t.role.focusable())
.collect::<Vec<_>>();
if candidates.is_empty() {
self.focused = None;
return None;
}
let current = candidates.iter().position(|t| Some(t.id) == self.focused);
let index = match current {
Some(i) if back => (i + candidates.len() - 1) % candidates.len(),
Some(i) => (i + 1) % candidates.len(),
None if back => candidates.len() - 1,
None => 0,
};
let target = candidates[index];
self.focused = Some(target.id);
Some(target.clone())
}
pub fn key_press<A>(&mut self, targets: &[Target<A>]) {
self.key_active = self
.focused(targets)
.filter(|t| t.role != Role::TextField)
.map(|t| t.id);
}
pub fn key_release<A: Clone>(&mut self, targets: &[Target<A>]) -> Option<A> {
let active = self.key_active.take()?;
self.focused(targets)
.filter(|t| t.id == active)
.and_then(|t| t.action.clone())
}
pub fn visual(&self, id: WidgetId, selected: bool, enabled: bool) -> VisualState {
let hovered = enabled && self.hovered == Some(id);
VisualState {
hovered,
pressed: enabled
&& (self.key_active == Some(id) || (hovered && self.pointer_active == Some(id))),
focused: enabled && self.keyboard_focus && self.focused == Some(id),
selected,
enabled,
}
}
pub fn captured(&self, id: WidgetId) -> bool {
self.pointer_active == Some(id)
}
pub fn cursor<A>(&self, targets: &[Target<A>]) -> Cursor {
let target = self
.pointer_active
.and_then(|id| {
targets.iter().find(|t| {
t.id == id && matches!(t.role, Role::Splitter(_) | Role::Scrollbar(_))
})
})
.or_else(|| self.hit(targets));
match target {
Some(t) if !t.enabled => Cursor::Disabled,
Some(t) => match t.role {
Role::TextField => Cursor::Text,
Role::Splitter(Axis::Horizontal) => Cursor::ResizeHorizontal,
Role::Splitter(Axis::Vertical) => Cursor::ResizeVertical,
Role::Scrollbar(_) => Cursor::Grab,
_ => Cursor::Pointer,
},
None => Cursor::Default,
}
}
}
+7
View File
@@ -0,0 +1,7 @@
//! Tessera's host management widgets. No Endor AST, VM, UiNode or ui_bridge dependency.
//! Shares only low-level drawing, font shaping and geometry with guest content.
mod interaction;
pub mod theme;
mod widgets;
pub use interaction::{Axis, Cursor, Interaction, Role, Target, VisualState, WidgetId};
pub use widgets::{Button, Ui};
+56
View File
@@ -0,0 +1,56 @@
use crate::display_list::Color;
pub const BG: Color = Color::rgb(255, 255, 255);
// A visibly separate chrome layer against the warm, near-white content canvas.
pub const BAR: Color = Color::rgb(230, 233, 237);
pub const BORDER: Color = Color::rgb(226, 226, 226);
pub const TEXT: Color = Color::rgb(35, 42, 53);
pub const MUTED: Color = Color::rgb(103, 114, 130);
pub const ERROR: Color = Color::rgb(175, 42, 49);
pub const OK: Color = Color::rgb(31, 121, 80);
pub const PALETTE: [Color; 6] = [
Color::rgb(22, 113, 213),
Color::rgb(0, 132, 143),
Color::rgb(115, 76, 189),
Color::rgb(180, 68, 115),
Color::rgb(168, 94, 24),
Color::rgb(52, 123, 78),
];
#[derive(Clone, Copy, Debug)]
pub struct Theme {
pub accent: Color,
}
impl Theme {
pub fn new(accent: Color) -> Self {
Self {
accent: readable_accent(accent),
}
}
pub fn soft(self) -> Color {
mix(BG, self.accent, 0.10)
}
pub fn hover(self) -> Color {
mix(BG, self.accent, 0.17)
}
pub fn pressed(self) -> Color {
mix(BG, self.accent, 0.29)
}
}
pub fn mix(a: Color, b: Color, amount: f32) -> Color {
let channel =
|a: u8, b: u8| (a as f32 + (b as f32 - a as f32) * amount.clamp(0.0, 1.0)).round() as u8;
Color::rgb(
channel(a.red, b.red),
channel(a.green, b.green),
channel(a.blue, b.blue),
)
}
pub fn readable_accent(mut c: Color) -> Color {
while (c.red as u32 * 299 + c.green as u32 * 587 + c.blue as u32 * 114) / 1000 > 155 {
c = Color::rgb(
(c.red as f32 * 0.94) as u8,
(c.green as f32 * 0.94) as u8,
(c.blue as f32 * 0.94) as u8,
);
}
c
}
+290
View File
@@ -0,0 +1,290 @@
use super::{
Axis, Interaction, Role, Target, VisualState, WidgetId,
theme::{self, Theme},
};
use crate::{
display_list::{Color, DisplayList, DrawCommand},
geometry::{Point, Rect},
text::{self, TextStyle},
};
use std::hash::Hash;
pub struct Button<'a> {
pub label: &'a str,
pub selected: bool,
pub enabled: bool,
pub role: Role,
}
impl<'a> Button<'a> {
pub fn new(label: &'a str) -> Self {
Self {
label,
selected: false,
enabled: true,
role: Role::Button,
}
}
pub fn selected(mut self, value: bool) -> Self {
self.selected = value;
self
}
pub fn enabled(mut self, value: bool) -> Self {
self.enabled = value;
self
}
pub fn role(mut self, value: Role) -> Self {
self.role = value;
self
}
}
pub struct Ui<A> {
pub list: DisplayList,
pub targets: Vec<Target<A>>,
pub theme: Theme,
interaction: Interaction,
}
impl<A: Hash> Ui<A> {
pub fn new(theme: Theme, interaction: Interaction) -> Self {
Self {
list: DisplayList::default(),
targets: Vec::new(),
theme,
interaction,
}
}
pub fn fill(&mut self, r: Rect, color: Color) {
self.list.push(DrawCommand::FillRoundedRect {
rect: r,
radius: 0.0,
color,
});
}
fn outline(&mut self, r: Rect, color: Color, width: f32) {
self.list.push(DrawCommand::StrokeRoundedRect {
rect: Rect::new(
r.x + width / 2.0,
r.y + width / 2.0,
(r.width - width).max(0.0),
(r.height - width).max(0.0),
),
radius: 3.0,
width,
color,
});
}
pub fn label(&mut self, x: f32, y: f32, value: &str, color: Color, code: bool) {
self.list.push(DrawCommand::Text {
origin: Point::new(x, y),
value: value.into(),
style: if code {
TextStyle::code()
} else {
TextStyle {
font_size: 12.0,
line_height: 18.0,
..TextStyle::ui(1)
}
},
color,
});
}
fn register(
&mut self,
id: WidgetId,
rect: Rect,
role: Role,
action: Option<A>,
selected: bool,
enabled: bool,
) -> VisualState {
let response = self.interaction.visual(id, selected, enabled);
self.targets.push(Target {
id,
rect,
role,
enabled,
action,
});
response
}
fn surface(&mut self, rect: Rect, s: VisualState, base: Option<Color>) {
let color = if !s.enabled {
base
} else if s.pressed {
Some(self.theme.pressed())
} else if s.hovered {
Some(self.theme.hover())
} else if s.selected {
Some(self.theme.soft())
} else {
base
};
if let Some(color) = color {
self.fill(rect, color);
}
if s.focused {
self.outline(rect, self.theme.accent, 1.5);
}
}
pub fn button(&mut self, rect: Rect, action: A, button: Button<'_>) -> VisualState {
let id = WidgetId::new(&action);
let s = self.register(
id,
rect,
button.role,
Some(action),
button.selected,
button.enabled,
);
self.surface(rect, s, None);
self.list.push(DrawCommand::PushClip(rect));
let label = text::fit(
button.label,
(rect.width - 16.0).max(0.0),
TextStyle {
font_size: 12.0,
line_height: 18.0,
..TextStyle::ui(1)
},
);
self.label(
rect.x + 8.0,
rect.y + (rect.height - 18.0) / 2.0,
&label,
if s.enabled {
theme::TEXT
} else {
Color::rgb(151, 160, 172)
},
false,
);
if s.selected && button.role == Role::Tab {
self.fill(
Rect::new(rect.x, rect.y + rect.height - 2.0, rect.width, 2.0),
self.theme.accent,
);
}
self.list.push(DrawCommand::PopClip);
s
}
pub fn text_field(&mut self, rect: Rect, action: A, focused: bool) {
let s = self.register(
WidgetId::new(&action),
rect,
Role::TextField,
Some(action),
false,
true,
);
self.surface(rect, s, Some(theme::BG));
self.outline(
rect,
if focused || s.focused {
self.theme.accent
} else if s.hovered {
theme::MUTED
} else {
theme::BORDER
},
if focused || s.focused { 1.5 } else { 1.0 },
);
}
/// A terminal prompt shares its surface with output; its caret is the focus cue.
pub fn inline_input(&mut self, rect: Rect, action: A) {
self.register(
WidgetId::new(&action),
rect,
Role::TextField,
Some(action),
false,
true,
);
}
pub fn row(&mut self, paint: Rect, hit: Rect, action: A, selected: bool) {
let s = self.register(
WidgetId::new(&action),
hit,
Role::Row,
Some(action),
selected,
true,
);
self.surface(paint, s, None);
}
pub fn swatch(&mut self, rect: Rect, action: A, color: Color, selected: bool) {
let s = self.register(
WidgetId::new(&action),
rect,
Role::Swatch,
Some(action),
selected,
true,
);
self.fill(
rect,
if s.pressed {
theme::mix(color, theme::TEXT, 0.2)
} else {
color
},
);
if s.hovered || s.focused || selected {
self.outline(
Rect::new(
rect.x - 3.0,
rect.y - 3.0,
rect.width + 6.0,
rect.height + 6.0,
),
if s.focused {
self.theme.accent
} else {
theme::TEXT
},
if s.pressed { 3.0 } else { 1.5 },
);
}
if selected {
self.label(rect.x + 10.0, rect.y + 6.0, "✓", theme::BG, false);
}
}
pub fn splitter(&mut self, rect: Rect, id: WidgetId, axis: Axis) {
let hit = Rect::new(
rect.x - 3.0,
rect.y - 3.0,
rect.width + 6.0,
rect.height + 6.0,
);
let mut s = self.register(id, hit, Role::Splitter(axis), None, false, true);
s.pressed |= self.interaction.captured(id);
let color = if s.pressed || s.hovered {
self.theme.accent
} else {
theme::BORDER
};
let line = if s.hovered || s.pressed {
match axis {
Axis::Horizontal => Rect::new(rect.x - 1.0, rect.y, 3.0, rect.height),
Axis::Vertical => Rect::new(rect.x, rect.y - 1.0, rect.width, 3.0),
}
} else {
rect
};
self.fill(line, color);
}
pub fn scrollbar(&mut self, rect: Rect, id: WidgetId, axis: Axis) {
let mut s = self.register(id, rect, Role::Scrollbar(axis), None, false, true);
s.pressed |= self.interaction.captured(id);
self.fill(
rect,
if s.pressed {
self.theme.accent
} else if s.hovered {
theme::mix(theme::MUTED, self.theme.accent, 0.55)
} else {
Color::rgb(161, 173, 190)
},
);
}
}