uzor_framework/lib.rs
1//! # uzor-framework — the app engine
2//!
3//! ```text
4//! Role: kernel (+ engines, handle, host shells by module — see module table)
5//! Owns: on-screen state only — windows, layout / dock trees, overlay stacks, focus scopes, pointer
6//! capture, hover / press, keymap bindings, cadence, animation. Nothing else.
7//! Exports: Handle<S>, App / Spec, AppCommand<S>, Intent<S>, VisualSnapshot<S>, InputEnvelope /
8//! InputEvent, WindowCommand, Runtime, hosts behind features `native` / `web`, headless host.
9//! Imports: uzor (widgets, input, docking, tokens), uzor-render-hub (hosts only),
10//! uzor-window-desktop (feature native), uzor-window-web (feature web).
11//! Forbidden: winit / web-sys / render backends inside kernel, engine, types, handle, runtime;
12//! HTTP, MCP, scripting, plugins, persistence, file I/O, business data anywhere;
13//! locks / threads / RefCell outside handle and hosts; pub fields on kernel / engine structs;
14//! a second door into on-screen state (the old layout façade / framework::* paths).
15//!
16//! Module roles: types | engine/* | kernel | handle | runtime (shell) | host/* (shell).
17//! Gate: CICD/uzor/scripts/gate-next.sh --crates uzor-framework (release profile; never
18//! --workspace --all-targets). Bans F1-F10 live in CICD/uzor/scripts/forbidden-deps.toml.
19//! ```
20//!
21//! ## Status
22//!
23//! Briefs F1-F6: the `types` role (the input bus, the command vocabulary,
24//! intents, the visual snapshot, window commands, frame requests, the layout
25//! blob, the [`Spec`] vocabulary trait, engine ops / effects) and seven
26//! engines in the crate-internal `engine` module (windows, cadence +
27//! deadline wheel, animation, input, keymap, overlays, layout with expand
28//! and drag-out). F7: the kernel
29//! (phase pipeline, conduction per design §3.8, routing per §4.3), the
30//! [`App`] contract with the hook contexts, [`Handle`], [`Runtime`] and the
31//! headless host in [`host`]. F8: [`widgets`] convenience functions over the
32//! hook contexts, [`flex`] and [`profiler`]. F9: native host behind feature
33//! `native` (`host::native`). F10: web host behind feature `web`
34//! (`host::web`: listeners, RAF, executor, canvas2d paint). F11: the demo
35//! (`examples/demo`, one `DemoApp`, native and web entries) and the §9.4
36//! goldens. M1: [`view!`] retargets onto [`widgets`] / [`flex`].
37//!
38//! ## Data flow
39//!
40//! Hosts push [`InputEnvelope`]s in; the app sends [`AppCommand`]s in; the
41//! kernel publishes a [`VisualSnapshot`], typed [`Intent`]s, host-bound
42//! [`WindowCommand`]s and [`FrameRequest`]s out. Everything in this crate is
43//! generic over one app-supplied [`Spec`] (panel / overlay / action types).
44
45#![deny(missing_docs)]
46
47#[cfg(feature = "automation")]
48pub mod automation;
49#[cfg(feature = "dev-control")]
50pub mod dev_control;
51pub(crate) mod engine;
52pub mod flex;
53pub mod handle;
54pub mod host;
55mod kernel;
56pub mod platform;
57pub mod profiler;
58mod runtime;
59pub mod types;
60pub mod widgets;
61
62/// `view!` JSX-like DSL — re-exported from `uzor-framework-macros` (brief M1).
63pub use engine::input::Selectables;
64pub use uzor_framework_macros::view;
65
66pub use handle::{
67 App, FrameTime, Handle, HandleError, HookOp, HookOps, InitCx, IntentCx, OverlayCx, PanelCx,
68 VisualView, Waker, Widgets,
69};
70pub use host::HeadlessHost;
71pub use runtime::{Runtime, RuntimeConfig, TickOutput, MAX_SETTLE};
72
73pub use types::anim::{AnimKey, AnimPolicy, ExpandKind};
74
75pub use types::bus::{
76 ClipboardResult, DropInput, DroppedFile, HostCaps, HostEvent, ImeInput, InputEnvelope,
77 InputEvent, KeyInput, KeyState, PointerInput, RenderInfo, TimerWake, TouchInput, WheelDelta,
78 WheelInput, WindowInput,
79};
80pub use types::command::{
81 AppCommand, Binding, CadenceCmd, ChromeKind, ChromeModel, ChromeTab, ClipboardCmd, DockTarget,
82 Domain, DragOutChrome, DragOutPolicy, FocusCmd, KeymapCmd, KeymapScope, LayoutCmd, LayoutHit,
83 LayoutPolicy, OverlayCmd, OverlayPolicy, OverlaySize, SplitDir, SplitterPolicy, ThemeCmd,
84 WindowCmd,
85};
86pub use types::controls::{ControlButton, ControlsPlacement, FloatingControls, WindowControlsStyle, HOST_HAS_WINDOW_CONTROLS};
87pub use types::scroll::{sticky_top, Overscroll, ScrollAlign, ScrollKey, ScrollStyle, ScrollView};
88pub use types::error::FrameworkError;
89pub use types::frame::{FrameRequest, RegionPlan, RegionSpec, TimerOwner, Wake, WindowSurface};
90pub use types::ids::{
91 OrderedSeconds, OverlaySlot, RegionId, Revision, ScopeId, Seconds, Ticket, TimerToken,
92 TrayItemId, WindowId,
93};
94pub use types::intent::{
95 CloseCause, DockIntent, DropIntent, Intent, OverlayIntent, TextIntent, UnhandledInput,
96 WindowIntent,
97};
98pub use types::layout_blob::{LayoutBlob, LayoutCodecError, WindowGeometrySnapshot};
99pub use types::overlay_model::{
100 ContextMenuEntry, ContextMenuModel, DropdownModel, ModalModel, OverlayModel, TooltipModel,
101};
102pub use types::snapshot::{
103 CadenceView, ChromeView, DockView, EdgeSlotView, FloatingView, InputView, LeafView,
104 OverlayView, PanelRef, SeparatorView, VisualSnapshot, WindowView,
105};
106pub use types::spec::{PanelHome, Spec};
107pub use types::window::{
108 Attention, CaptionButtons, ClosePolicy, CursorMode, FullscreenMode, ImePurpose, Point,
109 RenderCmd, SizePx, ThemeHint, WindowCommand, WindowGeometry, WindowSpec,
110};