masonry_core: introduce VisualLayerPlan and scene-layer paint splits (#1746)

This PR introduces VisualLayerPlan as the paint output of masonry_core and adds the first in-tree scene-layer split mechanism.

The scope is intentionally narrow:

core-only
no host or masonry_winit presentation changes
no ExternalSurface
no Subduction integration
no behavior change in current rendering paths

Current consumers still flatten the plan back into the same rendered output they had before.

What changed

1. Replace `PaintResult` with `VisualLayerPlan`

RenderRoot::redraw() now returns a VisualLayerPlan instead of the old PaintResult / PaintedLayer split.

VisualLayerPlan is now the semantic paint output of Masonry:

painter-ordered visual layers
each layer carries a retained scene plus its transform into window space
current consumers use compatibility helpers to replay/flatten those layers

This changes the representation, but not runtime behavior.

2. Add scene-only paint splits inside a root

This PR adds a small paint-pass seam:

PaintLayerMode
PaintCtx::set_paint_layer_mode(...)

For now it supports:

Inline
IsolatedScene

PaintLayerMode::IsolatedScene records the current widget subtree as its own scene layer in the VisualLayerPlan.

Current hosts still flatten those layers back together, so this does not change final rendering yet. What it changes is that the core paint output can now represent in-tree scene boundaries explicitly, not just top-level LayerStack roots.

Why this is split out first

The goal of this PR is to establish the core paint model before introducing:

external layers
widget-level external surface APIs
host-side realization
Subduction integration

That gives us a cleaner sequence:

core can describe visual layering
core can describe in-tree scene boundaries
later work can add external placeholders
later still, hosts can realize the plan differently

This PR only handles the first two steps.

Compatibility / behavior

There should be no user-visible behavior change.

Xilem

An experimental Rust architecture for reactive UI

Xilem and Masonry provide an experimental high-level architecture for writing GUI apps in Rust.

Masonry is a foundational crate for building natively compiled GUIs in Rust. It provides a retained widget tree and runs event handling and update passes on it.

Xilem is a high-level reactive framework inspired by React, SwiftUI and Elm. It lets users create a lightweight view tree, and changes the rendered app based on changes to the tree. It has a web backend and a Masonry backend.

masonry/ and xilem/ are the respective entry points of these projects for new users. See ARCHITECTURE.md for details about the repository structure.

Xilem and Masonry are built on top of:

winit for window creation.
Vello and wgpu for 2D graphics.
Parley and Fontique for the text stack.
AccessKit for plugging into accessibility APIs.

Note for new users: If you’re not sure what to use between Xilem and Masonry, you probably want Xilem. In general, if you’re trying to make an app with minimum hassle, you probably want Xilem. Xilem is a UI framework, whereas Masonry is a toolkit for building UI frameworks (including Xilem).

Screenshots

*From https://github.com/StefanSalewski/xilem-chess/*

Getting started

After cloning this repository, you can try running the examples, such as the to_do_mvc example shown above:

cargo run --example to_do_mvc

To add Xilem as a dependency to your project, run

cargo add xilem

Prerequisites

Linux and BSD

You need to have installed pkg-config, clang, and the development packages of wayland, libxkbcommon, libxcb, and vulkan-loader. Most distributions have pkg-config installed by default.

To install the remaining packages on Fedora, run:

sudo dnf install clang wayland-devel libxkbcommon-x11-devel libxcb-devel vulkan-loader-devel

To install the remaining packages on Debian or Ubuntu, run:

sudo apt-get install clang libwayland-dev libxkbcommon-x11-dev libvulkan-dev

There’s a Nix flake in docs/ which may be used for developing on NixOS:

[!NOTE]

This flake is provided as a starting point, and we do not routinely validate its correctness. We do not require contributors to ensure that this accurately reflects the build requirements, as we expect most contributors (and indeed many maintainers) will not be using NixOS. If it is out of date, please let us know by opening an issue or PR.

# For all crates within this repo
nix develop ./docs
# For a specific crate
nix develop ./docs#xilem
nix develop ./docs#masonry
nix develop ./docs#xilem_web

Recommended Cargo Config

The Xilem repository includes a lot of projects and examples, most of them pulling a lot of dependencies.

If you contribute to Xilem on Linux or macOS, we recommend using split-debuginfo in your .cargo/config.toml file to reduce the size of the target/ folder:

[profile.dev]
# One debuginfo file per dependency, to reduce file size of tests/examples.
# Note that this value is not supported on Windows.
# See https://doc.rust-lang.org/cargo/reference/profiles.html#split-debuginfo
split-debuginfo="unpacked"

Minimum supported Rust Version (MSRV)

This version of Xilem has been verified to compile with Rust 1.92 and later.

Future versions of Xilem might increase the Rust version requirement. It will not be treated as a breaking change and as such can even happen with small patch releases.

Community

Discussion of Xilem development happens in the Linebender Zulip, specifically the #xilem channel. All public content can be read without logging in.

Contributions are welcome by pull request. The Rust code of conduct applies.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache 2.0 license, shall be licensed as noted in the License section, without any additional terms or conditions.

License

Licensed under the Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0)

Some files used for examples are under different licenses:

The font file (RobotoFlex-Subset.ttf) in xilem/resources/fonts/roboto_flex/ is licensed solely as documented in that folder (and is not licensed under the Apache License, Version 2.0).
The data file (status.csv) in xilem/resources/data/http_cats_status/ is licensed solely as documented in that folder (and is not licensed under the Apache License, Version 2.0).
The data file (emoji.csv) in xilem/resources/data/emoji_names/ is licensed solely as documented in that folder (and is not licensed under the Apache License, Version 2.0).

1. Replace PaintResult with VisualLayerPlan