class Engine

Maintains `scene_state` for a frame. Every frame, `snapshot`, `links`, and

`link_topology_generation` are moved into `scene_state`; `links` is `std::nullopt` when the

cached links are still current. When `needs_full_rebuild` is true, the global transform state

is rebuilt; otherwise it is reused (debug builds use `FindStaleSceneStateInput()` to verify

that it's safe to reuse).

Returns a description of the first input of the cached global transform state in

`scene_state` that differs in the new frame's `snapshot`, `links`, or `root_transform`, or

`std::nullopt` if reusing that state for the new frame is valid.

This is the only runtime check that reuse is correct. A mutator that forgets its change

signal leaves the cached state stale, which in production shows up as stale rendering, hit

testing, and layout, with no error. `PrepareSceneState()` runs it only in debug builds,

because it scans every session's transform inputs; it is a function so that tests can

exercise it in every build type. When the transform stage gains an input, compare it here.

Orchestrates the generation and submission of a frame to the `DisplayCompositor`.

This updates scene topology and link watchers, culls invisible content, and

handles first-frame startup logic to avoid driving the display before content

is ready.

When `display` is null because no FlatlandDisplay exists, clears `scene_state_` and skips the

frame so that `LinkSystem::UpdateLinkWatchers()` (and any direct `GenerateViewTreeSnapshot()`

call in tests; in production `App` emits an empty ViewTree snapshot directly when there is no

display) observes an empty scene instead of the last rendered one.

Dispatches updated layout information (coordinate transforms, view dimensions,

device pixel ratio, etc.) to layout observers and link watchers based on the

current frame's scene state.

CRITICAL: This must be called *after* the new ViewTree snapshot has been fully

updated and published (e.g. in `UpdateSnapshot()`). This ensures layout observers

do not query or receive layout updates against a stale ViewTree snapshot.

Snapshots the current Flatland content tree from the cached `scene_state_` prepared during

`RenderScheduledFrame()`. `root_transform` is set from the root transform of the display

returned from `FlatlandManager::GetPrimaryFlatlandDisplayForRendering`, and is checked

against the root of `scene_state_`'s global topology when non-empty.

Returns all renderables reachable from the display's root transform.