tessera-ui/tessera

1. This is a Rust monorepo organized around a cross-platform UI framework called Tessera, plus a set of companion crates and tools. The main architectural split is between runtime/rendering, reusable UI components, state/routing, platform integration, and build/CLI tooling.

2. The core runtime lives in tessera-ui. It is the central execution boundary for apps: declarative component functions are turned into a component tree, laid out, converted into a render graph/scene, and then rendered through a GPU-backed renderer. This crate also owns input and session state such as focus, keyboard, IME, cursor, scroll, timing, profiling, and test support.

3. tessera-macros provides the procedural macro entry point used by application code. Its role is to transform user-authored component functions into the form the runtime can execute, so the app author writes declarative UI while the macro bridges that to tessera-ui’s execution model.

4. tessera-components is the reusable widget layer. It contains higher-level primitives such as buttons, text, layout containers, navigation, dialogs, text fields, sliders, scrollables, and glass/material-style controls. It also includes shader-backed rendering pipelines under src/pipelines, so many components are not just layout wrappers but own their own rendering behavior.

5. tessera-foundation is the low-level support layer beneath components. It defines core concepts such as alignment, gestures, shapes, and modifier semantics/layout/interaction. This crate is the shared vocabulary for layout and interaction across the UI stack.

6. The rendering path is split between the generic renderer in tessera-ui and specialized GPU work in tessera-components. tessera-ui provides the main render engine and render passes, while components contribute specialized draw/compute pipelines and WGSL shaders for effects like blur, shadows, image/vector rendering, progress arcs, and custom glass visuals. The architecture is clearly GPU-first and designed for custom visual effects.

7. tessera-shard is a separate application state/navigation subsystem. It provides handle-based state storage, async support, and a router with destinations/controllers/home state. Conceptually, it sits above the UI runtime as an application-level state and navigation layer rather than a rendering layer.

8. tessera-platform encapsulates host-platform features that are not part of the pure UI runtime, such as clipboard and window-related integration. It also contains an Android plugin surface, which makes it the boundary where Tessera reaches into platform-specific native services.

9. tessera-build is the build-time integration crate. It appears to support embedding backend assets and selecting platform backends, including Android-specific backend logic. This is the bridge between Rust source, generated artifacts, and native platform packaging.

10. Mobile support is handled by tessera-mobile and the higher-level cargo-tessera CLI. tessera-mobile contains project/config parsers, target detection, device/emulator management, platform-specific logic for Android and Apple, and template generation for app/platform scaffolding. cargo-tessera exposes user-facing commands like new, build, dev, check, web, android, plugin, and profiling, acting as the workflow front end for the whole workspace.

11. The repository is template-driven for generated apps and platform projects. Under cargo-tessera/templates and tessera-mobile/templates, the repo stores skeletons for basic/blank apps, plugins, Android Studio projects, and Xcode projects. The generated example tree shows the result of this pipeline: a Rust app plus generated Android and web outputs, demonstrating how source code is turned into deployable platform artifacts.

12. The example crate is both a demo and an integration test of the architecture. Its src/pages/* modules show how app code is organized around pages and custom shaders, while the generated gen/ directories show the platform-specific wrappers Tessera produces for web and Android.

13. External technology choices materially shape the architecture: wgpu for rendering, winit for window/event handling, and glyphon for text. On mobile, the repo integrates with Android Gradle/NDK and Apple tooling such as Xcode, simulators/devicectl, and ios-deploy. Those platform toolchains are not incidental; they are part of the deployment boundary of the framework.

14. A useful diagram of this repo should therefore show three main planes: application code and macros at the top; shared UI/runtime/component/state crates in the middle; and platform/build/CLI/template tooling around the edges that generates, packages, and launches platform-specific projects.