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
47pub(crate) mod engine;
48pub mod flex;
49pub mod handle;
50pub mod host;
51mod kernel;
52pub mod profiler;
53mod runtime;
54pub mod types;
55pub mod widgets;
56
57/// `view!` JSX-like DSL — re-exported from `uzor-framework-macros` (brief M1).
58pub use uzor_framework_macros::view;
59
60pub use handle::{
61 App, FrameTime, Handle, HandleError, HookOp, HookOps, InitCx, IntentCx, OverlayCx, PanelCx,
62 VisualView, Waker, Widgets,
63};
64pub use host::HeadlessHost;
65pub use runtime::{Runtime, RuntimeConfig, TickOutput, MAX_SETTLE};
66
67pub use types::anim::{AnimKey, AnimPolicy, ExpandKind};
68
69pub use types::bus::{
70 ClipboardResult, DropInput, DroppedFile, HostCaps, HostEvent, ImeInput, InputEnvelope,
71 InputEvent, KeyInput, KeyState, PointerInput, RenderInfo, TimerWake, TouchInput, WheelDelta,
72 WheelInput, WindowInput,
73};
74pub use types::command::{
75 AppCommand, Binding, CadenceCmd, ChromeKind, ChromeModel, ChromeTab, ClipboardCmd, DockTarget,
76 Domain, DragOutChrome, DragOutPolicy, FocusCmd, KeymapCmd, KeymapScope, LayoutCmd, LayoutHit,
77 LayoutPolicy, OverlayCmd, OverlayPolicy, OverlaySize, SplitDir, SplitterPolicy, ThemeCmd,
78 WindowCmd,
79};
80pub use types::error::FrameworkError;
81pub use types::frame::{FrameRequest, RegionPlan, RegionSpec, TimerOwner, Wake, WindowSurface};
82pub use types::ids::{
83 OrderedSeconds, OverlaySlot, RegionId, Revision, ScopeId, Seconds, Ticket, TimerToken,
84 TrayItemId, WindowId,
85};
86pub use types::intent::{
87 CloseCause, DockIntent, DropIntent, Intent, OverlayIntent, TextIntent, UnhandledInput,
88 WindowIntent,
89};
90pub use types::layout_blob::{LayoutBlob, LayoutCodecError, WindowGeometrySnapshot};
91pub use types::overlay_model::{
92 ContextMenuEntry, ContextMenuModel, DropdownModel, ModalModel, OverlayModel, TooltipModel,
93};
94pub use types::snapshot::{
95 CadenceView, ChromeView, DockView, EdgeSlotView, FloatingView, InputView, LeafView,
96 OverlayView, PanelRef, SeparatorView, VisualSnapshot, WindowView,
97};
98pub use types::spec::{PanelHome, Spec};
99pub use types::window::{
100 Attention, ClosePolicy, CursorMode, FullscreenMode, ImePurpose, Point, RenderCmd, SizePx,
101 ThemeHint, WindowCommand, WindowGeometry, WindowSpec,
102};