Find the Compose boundary

Learning goal

Separate the machinery supplied by Compose from the UI policy that a new surface requires.

Start with the split

“Compose” is often used to mean several layers at once. For a new surface, that shortcut hides the most important design decision.

mindmap
  root((Compose ecosystem))
    Compiler
      transforms composable calls
      inserts group calls and source-derived keys
      passes a Composer
    Runtime
      Composer records positional information
      slot table
      remember
      snapshot state
      recomposition
      effects
      tree changes
    Compose UI
      LayoutNode
      measurement
      drawing
      modifiers
      input
      semantics
    Foundation and Material
      Text
      scrolling
      controls
      design system

Atlas UI reuses the first two branches. It replaces the last two.

flowchart LR
    subgraph Reused
      K[Kotlin + Compose Compiler]
      R[Compose Runtime]
    end
    subgraph Atlas[Built by Atlas UI]
      N[Node model]
      A[Applier]
      L[Layout]
      P[Painter]
      I[Input and semantics]
      H[Host]
    end
    subgraph Boundary[Atlas-owned boundary]
      S[Surface contract]
    end
    subgraph Replaceable
      B[Surface adapter]
    end
    K --> R --> A --> N --> L --> P --> S
    B -. implements .-> S
    I --> N
    H --> R

What Runtime provides here

After a host creates a Composition with an Applier and runs a Recomposer, Runtime can:

retain positional information and remembered values;
observe snapshot-state reads made during composition;
schedule invalidated compositions;
rerun invalidated restart scopes and any descendants that cannot be skipped;
record property and structural changes;
apply those changes to a tree through an Applier.

Runtime does not assign visual meaning to the tree. A node could describe a document, a protocol message, a scene, or a UI for a novel device. Slot tables and restart scopes explain the current implementation; they are not stable public API contracts for Atlas to depend on.

The three representations

A visual toolkit has at least three representations. Do not collapse them into one.

flowchart TD
    C[Composition<br/>groups + remembered values] -->|Applier edits| T[Retained node tree<br/>TextNode + GroupNode]
    T -->|layout + paint| F[Surface frame<br/>typed commands]

    C:::runtime
    T:::toolkit
    F:::surface
    classDef runtime fill:#dbeafe,stroke:#2563eb,color:#172554
    classDef toolkit fill:#dcfce7,stroke:#16a34a,color:#052e16
    classDef surface fill:#fef3c7,stroke:#d97706,color:#451a03

Composition: Runtime’s bookkeeping. It is not your visual tree.
Node tree: retained toolkit objects whose identity can survive recomposition.
Frame: an output snapshot submitted to the surface.

Two projects that must not be confused

Project A — Runtime-powered custom toolkit

You define AtlasText, AtlasGroup, layout rules, input, and rendering. Applications gain familiar Compose state and authoring patterns, but use Atlas components.

Project B — Compose UI platform port

You attempt to run existing Compose UI, Foundation, or Material components. That requires a compatible Compose UI node/owner environment plus the services used by those components. An Applier alone is not enough.

This course follows Project A.

One state change

sequenceDiagram
    participant App
    participant Runtime
    participant Applier
    participant Tree
    participant Surface

    participant Host
    participant Renderer
    App->>Runtime: count snapshot state changes
    Runtime->>Runtime: invalidate scope that read count
    Host->>Runtime: drive pending recomposition
    Runtime->>Runtime: recompose scope and record update
    Runtime->>Applier: apply recorded update
    Applier->>Tree: TextNode.text = "Count: 1"
    Host->>Renderer: render committed tree
    Renderer-->>Host: SurfaceFrame
    Host->>Surface: submit frame

Notice what does not happen: the composable does not draw directly, and the entire node tree need not be recreated.

Visual checkpoint

On paper, draw three boxes labeled Composition, Node tree, and Frame. Add one sentence under each explaining who owns it. If any sentence mentions pixels, cells, or windows under Composition, revisit the three-representation diagram.

Review questions

Why can Runtime maintain a tree it does not understand?
Why can’t Atlas UI call Material Text with an AtlasApplier?
Which representation should a deterministic renderer test inspect?

Recap

Keep:    compiler transformation + Runtime state/composition machinery
Build:   nodes + Applier + policies + host
Replace: the final Surface adapter
Avoid:   treating Runtime, Compose UI, and Material as one layer