Document the different graphs & hierarchies in play along with their lifecycles

[vmanot]

SwiftUI is a complex beast. Going through the codebase as well as other articles by people who've tried to understand how it concretely works, I recognize the following distinct graphs and hierarchies conceptually:

• The attribute graph (OGGraph and OGSubgraph, subgraphs can own subgraphs and attributes)
• ViewGraph

Some questions that I don't have a good answer to despite going over the codebase a dozen times:

• How do ViewInputs and ViewOutputs relate to AttributeGraph? I see sifting through a lot of indirection that they're creating Attributes in many places, I'm assuming the initialization/mutation of these attributes are tracked by some AttributeGraph-owned closure that they are being executed within.
• What is the lifecycle of a ViewGraph?
• Does ViewGraph maintain its hierarchy solely through PreferenceBridge?
• DisplayList?
• What other hierarchies are known to you?

[Kyle-Ye]

Part of the info has already outdated. I'm planning to realign the part to iOS 18 recently.

Keep tuned.

[Kyle-Ye]

DisplayList

SwiftUI will construct DisplayList in UIHostingView/ViewGraph and many other places. And will eventually kick off a render process via RendererHost (Diff & delta time & addSubview/insertLayer).

See more detail on #136.

[Kyle-Ye]

How do ViewInputs and ViewOutputs relate to AttributeGraph? I see sifting through a lot of indirection that they're creating Attributes in many places, I'm assuming the initialization/mutation of these attributes are tracked by some AttributeGraph-owned closure that they are being executed within.

ViewInputs/ViewOutputs and AttributeGraph Relationship

ViewInputs and ViewOutputs are indeed closely tied to the AttributeGraph system:

// From ViewInputs.swift
package struct _ViewInputs {
    package var customInputs: PropertyList
    package var options: _ViewOptions
    package var traits: _ViewTraitKeys
    // ... other properties that create Attributes
}

The relationship works through:

Attribute Creation Context: ViewInputs/ViewOutputs operations are executed within an AttributeGraph context where attribute mutations are tracked
Rule Execution: When views are being built/updated, the graph system captures attribute dependencies and changes
Indirection Pattern: The indirection you've noticed is the dependency tracking mechanism - each attribute read/write is recorded by the graph's rule system

What is the lifecycle of a ViewGraph?

ViewGraph Lifecycle

The ViewGraph lifecycle appears to follow this pattern:

// ViewGraph maintains view hierarchy state
class ViewGraph {
    // Root view creation
    static func makeRootView() -> ViewGraph
    
    // Update cycle
    func update(with inputs: _ViewInputs) -> _ViewOutputs
    
    // Invalidation and reconstruction
    func invalidate()
}

Lifecycle stages:

Creation: Root ViewGraph created for view hierarchy
Population: Views added through _makeView calls
Update: Attribute changes trigger graph updates
Invalidation: When dependencies change, affected subgraphs are marked for rebuild
Reconstruction: Dirty portions of the graph are rebuilt

Does ViewGraph maintain its hierarchy solely through PreferenceBridge?

ViewGraph Hierarchy Maintenance

ViewGraph hierarchy is maintained through multiple mechanisms, not just PreferenceBridge:

PreferenceBridge: Handles preference propagation up the hierarchy
ViewList: Manages collections of child views
Trait Propagation: Environment and other traits flow down
Subgraph Ownership: Parent graphs own child subgraphs

// Multiple hierarchy maintenance mechanisms
struct ViewGraph {
    var subgraphs: [ViewGraph]  // Child view graphs
    var preferences: PreferenceBridge  // Upward data flow
    var environment: EnvironmentValues  // Downward data flow
}

DisplayList?

DisplayList

The DisplayList represents the final rendered output hierarchy:

// DisplayList is the render tree
struct DisplayList {
    var items: [DisplayItem]  // Actual drawing commands
    var bounds: CGRect
    var transform: CGAffineTransform
}

This is separate from ViewGraph - it's the compiled output after layout and rendering decisions are made.

What other hierarchies are known to you?

Layout Hierarchy, Gesture Hierarchy, Animation Hierarchy, Accessibility Hierarchy and so on.