Onboarding walkthrough
View and the terminalA SwiftTUI frame is not "draw the view." It is a compiler-style pipeline: the value you author is lowered, step by step, through a chain of typed, immutable representations, each one closer to the terminal and able to answer a question the one before it could not. This page follows one small view down that ladder and links each step to its source. New framework developers can use it as an introduction. Renderer developers can use it as a reference.
some View value to styled cells and host bytes; every frame re-derives the chain.swift-tui.HEADLowering is a compiler idea: translate a program from one representation into a lower-level one. Keep the meaning, change the vocabulary, and discard whatever the next consumer does not need. A compiler lowers source to an AST, the AST to an IR, the IR to machine code. SwiftTUI treats your view the same way: the View value is the source program, and the terminal cells are the machine code. The framework's documentation describes this as seven phases scheduled across five stages: two views of one frame, kept separate because they serve different purposes.
Phase products are the values that the engine computes in order: the rungs of the lowering ladder, plus its side products. Each product is an immutable type from SwiftTUICore. The engine derives later products from earlier products. It does not change the earlier products.
resolve → measure → place → semantics → draw → raster → commit
The products define the correctness model. Layout is a function of a resolved tree. Drawing is a function of placement.
Runtime stages are the boundaries across which an interactive session schedules work. SwiftTUIRuntime owns these stages. They provide cancellation points, animation sampling, and an off-actor boundary.
head → animationInjection → latePreferenceReconciliation → fusedFrameTail → commit
fusedFrameTail combines five phase products in one scheduling node. Thus, pure work can leave the main actor.
resolve. animationInjection and latePreferenceReconciliation change the current draft without a new product. fusedFrameTail spans measure→raster. commit covers commit. The two models differ because each model has a different purpose. See isolation.Follow one authored line, Text("Deploy Queue").bold() from the example below, down every representation the framework gives it during a frame. Each rung is a level: it gains the answers the next consumer needs and gives up the vocabulary it no longer needs. The arrows between rungs are the pipeline phases. Two products hang off the ladder rather than sitting on it: the semantic snapshot is a projection and the commit plan is an effect package.
The ladder is the data story; the runtime schedules it. Step through the five runtime stages: head runs the first lowering on the main actor, the fused tail descends the rest, and commit publishes. The left panel highlights the authored lines that the runtime reads. The center panel describes the stage. The right panel shows the available products. Terminal cells do not exist before raster in the fused tail.
Authored input
Runtime stage
Products so far
Each product answers one question about the frame. Five are levels of the lowering ladder; the semantic snapshot and commit plan are its side products. FrameArtifacts contains all seven. Hosts consume committed contracts and do not access the private renderer state.
Defined in SwiftTUICore/Commit/FrameArtifacts.swift.
State writes, input, signals, and deadlines do not call the renderer directly. They record intent. A scheduler combines that intent. The run loop then gets one frame of work at a time. Thus, ten mutations in one tick produce one render operation.
Authored View, Scene, and App values are main-actor APIs, so the first lowering must run on the main actor. Every later lowering is a pure function over an already-derived, immutable product, which is exactly why the fused tail can leave the main actor when the strategy permits. This boundary is the reason for the scheduling model.
The computation of frame products does not display the frame. Commit applies the completed-frame policy. A candidate can take one of four paths. These paths explain why a state change can have no visible result.
Decided in DefaultRenderer+CompletedFrameCandidates.swift.
Commit produces data, not output. RunLoop performs the ladder's final step: it lowers the committed, host-neutral surface into whatever the output mode and surface roles consume. Terminal bytes exist only below this boundary.
Dispatched in RunLoop+Presentation.swift. The host contract is in PresentationSurface.swift.
These excerpts support the walkthrough. Use the tabs to examine the points where data changes shape. The prose refers to the highlighted lines.
You can examine renderer activity without reading the source. If you install a diagnostics sink, the runtime emits a RuntimeFrameSample for each result. A result is a committed frame, a zero-artifact outcome, or an elision.
SwiftTUIProfiling converts these neutral samples into public records and summaries. The runtime does not depend on the profiling product.
Start with your question. This section lists the framework entry points. It also defines the types that this page uses.