duo-continuity
Keeps app state alive when iPhone Duo, Apple's foldable, folds, unfolds, rotates or resizes between the outer display and the inner display. Use when scroll position, video or audio playback, typed te
SKILL.mdplugins/duology/skills/duo-continuity/SKILL.md
GitHubduo-continuity
Apple says your app resizes when someone opens or closes iPhone Duo (Tech Talk 111461). Your content moves to the other display, and the window changes size and usually its horizontal size class. State survives only if it lives above the part of the view tree that the change rebuilds. This skill tells you where to put each kind of state and how to prove it survives.
Load other skills for neighbouring work: duo-layout (size classes, ArrangementView, the even split), duo-navigation (bars, sidebars, sheets), duo-testing (test setup on the Duo simulator).
Labels: measured means we ran it on the iPhone Duo simulator (iOS 27.1). Fold results come from flipping the size class from code, the change a fold makes to your views, because our probes can't fold the simulator themselves; see references/evidence.md. Unverified means we could not confirm it. Everything else comes from Apple's pages, linked inline. Full source list: reference/sources.md.
Apple has no continuity API
Don't look for one. The iOS 27.1 SDK has no fold, pose or posture symbol, and the hinge APIs only report status and angle (API index). Apple states the goal, not a tool. The HIG asks you to keep functionality and the state of elements the same on both displays. Tech Talk 111466 says people open and close the phone often, so the app must stay predictable. Tech Talk 111463 keeps scrolling content in place because moving it breaks continuity. You reach that goal with ordinary SwiftUI and UIKit state tools. (Apple's "Continuity" feature, Handoff between devices, is unrelated.)
What a fold does
| Change | What your app sees |
|---|---|
| Close or open | Content moves between displays. The width changes and the horizontal size class flips: compact outside, regular inside. |
| Partially open | The window stays on the inner display. A division region (the fold) becomes active. |
| Rotate | Width and height swap. The inner display doesn't honour your supported orientations, so don't rely on them. |
| Split View, pinned Picture in Picture | The window gets narrower or shorter. |
| Combinations | Rotate, then close. Close while scrolling. Open while typing. Each step is another resize. |
- Measured on the simulator with Device Hub's pose buttons (v0.2): close, open, partial fold and rotation kept the root view alive, with no relaunch, no new
onAppearand no scene disconnect, and the scene stayedactivewith no.inactive(duo-transitions evidence, duo-scenes evidence). Unverified: a real iPhone Duo, and what the keyboard does when the window changes display. Still save on.background.
Where state gets lost
- Identity changes. An
if/elseorswitchon size class, aViewThatFitsthat picks another child, or an.idtied to layout gives views a new identity. SwiftUI drops their@State, takes keyboard focus away, runsonAppearagain, cancels their.task, and closes sheets attached to them. - Code reloads on resize. A fetch in
onAppear, a UIKit trait handler that rebuilds child view controllers, anonDisappearthat pauses or clears. - A pane leaves the screen. When the phone closes, a split view collapses and the extra column leaves the view tree. State stored only in that column goes with it.
What must survive, and where it lives
| State | Keep it in | Tool |
|---|---|---|
| Scroll position | the model, as an item ID | ScrollPosition + scrollTargetLayout() (iOS 18); scrollPosition(id:anchor:) (iOS 17) |
| Playback | one player owned by a model | AVPlayer, VideoPlayer(player:) |
| Text and selection | the model | TextEditor(text:selection:), TextSelection (iOS 18) |
| Keyboard focus | @FocusState on a view whose identity never changes |
focused(_:equals:) |
| Form input | a draft struct in the model | @Observable, @Bindable |
| Selected item, navigation stack | the model | NavigationSplitView selection, NavigationPath |
| Uploads, downloads | a service object, never a view | a Task the service keeps |
| Sign-in | an app-level session object, secrets in the Keychain | Keychain Services |
| Open sheet or alert | the item in the model, the modifier on a stable view | sheet(item:onDismiss:content:) |
1. Own state above every layout switch
Put screen state in an @Observable model (Observation). Create one per window in the window's root view, which never changes identity, and pass it down with .environment. Section 3 shows that root. Keep @State for values you are happy to lose, such as a press highlight. Data shared by every window (a store, the signed-in user) goes one level up, in the App. The snippets below use this model.
import SwiftUI
import Observation
struct Item: Identifiable, Hashable, Codable, Sendable {
let id: Int
var title: String
}
@MainActor @Observable
final class LibraryModel {
var items: [Item] = []
var selection: Item.ID? // drives the detail column
var path = NavigationPath() // pushed screens in the detail
var scroll = ScrollPosition(idType: Item.ID.self) // where the feed is
var draft = "" // text being typed
var draftSelection: TextSelection? // the selection in that text
var sheetItem: Item? // the open sheet, if any
private var didLoad = false
func loadIfNeeded() async {
guard !didLoad else { return } // a fold never refetches
didLoad = true
items = (1...200).map { Item(id: $0, title: "Item \($0)") } // your fetch here
}
}
2. Keep view identity stable
Don't branch between containers on size class. Pick a layout and keep the same children (AnyLayout changes the layout without destroying the subviews' state).
import SwiftUI
struct CommentsPane: View {
@State private var reply = "" // lost on every fold in the bad version
var body: some View { TextField("Reply", text: $reply) }
}
// Bad: each branch is a different identity, so a fold resets CommentsPane.
struct ArticleScreenBad: View {
@Environment(\.horizontalSizeClass) private var sizeClass
var body: some View {
if sizeClass == .compact {
VStack { Text("Article"); CommentsPane() }
} else {
HStack { Text("Article"); CommentsPane() }
}
}
}
// Good: one identity, two layouts.
struct ArticleScreen: View {
@Environment(\.horizontalSizeClass) private var sizeClass
var body: some View {
let layout = sizeClass == .compact ? AnyLayout(VStackLayout()) : AnyLayout(HStackLayout())
layout {
Text("Article")
CommentsPane()
}
}
}
- Measured: with the
if/else, every flip gave the child a new@State, ranonAppearagain and cancelled its.task. WithAnyLayout, the child appeared once for the whole run. - Use
.id(_:)only for data identity, such as.id(item.id)to reset a detail on purpose. Changing the value resets the view's state (id(_:)). Never.id(sizeClass),.id(proxy.size)or.id(UUID()). - ViewThatFits shows a different child when space changes; keep its children free of state. Never swap
NavigationStackforNavigationSplitViewby size class. The split view collapses to a stack on its own. - For two panes around the fold, use
ArrangementViewor the even split fromduo-layout. Both take each pane once, with no branch. A splitArrangementViewcan hide its secondary view when it can't split (seeduo-layout), so keep that view's state in the model.
3. Selection and navigation stack
Keep the selection and the path in the model. NavigationSplitView collapses to one stack when the phone closes and shows the detail when something is selected (NavigationSplitView). If you switch panes yourself and opening the phone pops a pushed screen, pop it after the unfold animation (references/swiftui.md).
import SwiftUI
struct LibrarySplitView: View {
@Environment(LibraryModel.self) private var model
var body: some View {
@Bindable var model = model
NavigationSplitView {
List(model.items, selection: $model.selection) { item in
Text(item.title)
}
} detail: {
NavigationStack(path: $model.path) {
if let item = model.items.first(where: { $0.id == model.selection }) {
NavigationLink("Related", value: item.id + 1)
.navigationTitle(item.title)
.navigationDestination(for: Item.ID.self) { Text("Item \($0)") }
}
}
}
}
}
struct WindowRoot: View {
@State private var model = LibraryModel() // one per window, lives as long as the window
var body: some View {
LibrarySplitView()
.environment(model)
.task { await model.loadIfNeeded() } // WindowRoot never changes identity
}
}
- Measured: with the size class flipped to compact, the split view collapsed, kept the selection, and brought the sidebar list back at the same scroll offset on expand.
init(preferredCompactColumn:sidebar:detail:)(iOS 17) is a hint for the column shown after the collapse. Keep that binding in the model too. Measured: with an item selected, the collapse hid the sidebar although the binding said.sidebar. Check what you get in Device Hub.- A fold does not need
@SceneStorage. Use it so the window comes back after the system ends the app: save the selection andpath.codablewhen the scene goes to the background (NavigationPath, SceneStorage). Keep it small and never store secrets in it. Code: references/swiftui.md.
4. Scroll position by item ID, never by offset
import SwiftUI
struct FeedView: View {
@Environment(LibraryModel.self) private var model
@Environment(\.horizontalSizeClass) private var sizeClass
var body: some View {
@Bindable var model = model
let count = sizeClass == .compact ? 2 : 4 // even column counts
ScrollView {
LazyVGrid(columns: Array(repeating: GridItem(.flexible()), count: count)) {
ForEach(model.items) { Text($0.title) }
}
.scrollTargetLayout()
}
.scrollPosition($model.scroll, anchor: .top)
}
}
- Apple's ScrollPosition page says SwiftUI tries to keep the view with that ID visible when the scroll view's size changes. A point position gets no such help.
- Measured: item 150 stayed at the top through 4 → 1 → 4 columns; a point position showed rows 31 to 33 instead.
scrollPosition(id:)did not move aList. UseScrollViewReaderfor aList, or aScrollViewwith a lazy stack when you need ID positions. One exception, measured in the gallery: long text that reflows while the system margins arrive late lost its paragraph withScrollPosition; aScrollViewReader.scrollToby the saved ID after the width settles kept it (gallery README).
5. No reloads, and no work tied to a view's life
- Load once, in the model (
loadIfNeeded()), from a view that never changes identity. Or use.task(id:)keyed on the data, such asitem.id, never on layout. - SwiftUI cancels a
.taskwhen its view goes away or changes identity (task). Never start an upload, a download or a payment from.taskoronAppearinside a layout branch. Start it from a button action in a service object. Code: references/swiftui.md. - Never pause, clear or sign out in
onDisappear. A fold can trigger it.
6. Text, focus and selection
import SwiftUI
struct NoteEditor: View {
@Bindable var model: LibraryModel
@FocusState private var isFocused: Bool // lives in this view, so keep its identity stable
@Environment(\.horizontalSizeClass) private var sizeClass
var body: some View {
let layout = sizeClass == .compact ? AnyLayout(VStackLayout()) : AnyLayout(HStackLayout())
layout {
TextEditor(text: $model.draft, selection: $model.draftSelection)
.focused($isFocused)
Text("\(model.draft.count) characters")
}
}
}
- Measured: a field with stable identity kept focus through two size-class flips. The same field inside an
if/elselost it: its@FocusStatebecamenil. - Form drafts work the same way: a struct in the model, fields bound with
$model.form.name(references/swiftui.md).
7. Playback
- Create the
AVPlayeronce, in a model owned by the window root. Views only show it:VideoPlayer(player: playback.player). Measured: a model-ownedAVPlayerkept playing whileVideoPlayerwas torn down and rebuilt on each flip. - Never write
@State private var player = AVPlayer(url:)in a view below a layout switch. A fold starts a new player from zero. - Code for SwiftUI and
AVPlayerViewController: references/swiftui.md, references/uikit.md.
8. Sheets, alerts and sign-in
- Attach
.sheet,.fullScreenCover,.alertand.confirmationDialogto a view that never changes identity, usually the window root. Drive them from the model. Measured: a sheet attached inside anif/elseclosed when the size class flipped, and itsisPresentedbinding stayedtrue. The model and the screen disagreed. The same sheet on the root stayed up. - Keep the session in an app-level object and secrets in the Keychain. Let the root decide between signed-in and signed-out content. Never start sign-in from
onAppearbelow a layout switch; a fold would start it again. Unverified: whether a web sign-in sheet in flight survives a fold. Start it from the root to be safe.
9. UIKit
Keep the same view controllers and views. Change layout in place; don't rebuild. Keep the top item in view when the column count changes.
import UIKit
// Give it a compositional layout that reads the size class; see references/uikit.md.
final class FeedViewController: UICollectionViewController {
private var pendingAnchor: IndexPath?
override func viewDidLoad() {
super.viewDidLoad()
registerForTraitChanges([UITraitHorizontalSizeClass.self]) { (self: Self, _: UITraitCollection) in
self.pendingAnchor = self.pendingAnchor ?? self.collectionView.indexPathsForVisibleItems.min()
}
}
override func viewWillTransition(to size: CGSize, with coordinator: any UIViewControllerTransitionCoordinator) {
pendingAnchor = pendingAnchor ?? collectionView.indexPathsForVisibleItems.min() // before the resize
super.viewWillTransition(to: size, with: coordinator)
}
override func viewDidLayoutSubviews() {
super.viewDidLayoutSubviews()
guard let anchor = pendingAnchor else { return }
pendingAnchor = nil
collectionView.scrollToItem(at: anchor, at: .top, animated: false) // after the new layout
}
}
- Measured: with no restore, a 4 → 2 column change put item 74 at the top instead of item 148. Scrolling inside the trait handler didn't stick; scrolling after the next layout pass kept item 148.
- registerForTraitChanges(_:handler:) replaces
traitCollectionDidChange(_:), deprecated in iOS 17 (Adapting your app when traits change). viewWillTransition(to:with:) runs before the size changes; always callsuper. Unverified: the size-transition path, because the open simulator refused a rotation request from code. - Never call
reloadData()or replace child view controllers in either handler. - Split view, compositional layout, text views, players and state restoration: references/uikit.md.
10. How to test
- By hand in Device Hub. Run on the iPhone Duo simulator. Build up state: scroll halfway, select an item, push a screen, type and select text, start playback, start an upload, open a sheet. Then press Closed, Open and Partially Open under the bezel, rotate, and try the combinations (Interacting with your app in Device Hub). Check every row of the table above after each step.
- Automatic UI test. A debug-only launch switch adds a button that flips the size class at the root and hidden labels that report a state summary. The test records the summary, flips there and back, and compares. Measured: it passed on the closed Duo simulator. Don't rotate in it: measured, setting
XCUIDevice.shared.orientationon the closed Duo did not resize the app (open: unverified). - Real fold and rotation in a UI test. A test can't fold the simulator:
XCUIDevicehas no fold control, andsimctlanddevicectlhave no pose command. So a test, skipped by default, waits while you press the pose buttons and the rotate button in Device Hub, then compares the summary. Steps, matrix and full test code: references/testing.md.
Red flags in review
if sizeClass == .compact { A } else { B }where A and B hold the same stateful views.id(UUID()),.id(sizeClass),.id(geometry.size)or any.idfed by layout.onAppear { load() }or.task { await upload() }below a layout switch;onDisappear { player.pause() }or a form cleared inonDisappear@State private var player = AVPlayer(...)in a leaf viewNavigationStackin one branch andNavigationSplitViewin the other;.sheetor.alertattached inside a size-class branch- UIKit:
traitCollectionDidChange(_:),reloadData()or new child view controllers on a trait change; restoring a savedcontentOffsetafter a layout change
Checklist
- Screen state lives in an
@Observablemodel created once per window in a root view that never changes identity. - Layout switches use
AnyLayout,ArrangementViewor one container. Noif/elsebetween containers, and no.idfed by size, size class or a freshUUID. - Selection and navigation path live in the model; one
NavigationSplitViewhandles open and closed;@SceneStoragerestores them after a relaunch and holds no secrets. - Scroll position is stored as an item ID, not an offset.
- Loading runs once in the model. Uploads, downloads and payments run in a service object, never in
.taskoronAppear. - Draft text, selection and form input live in the model; focused fields keep their identity.
- One
AVPlayer, owned by a model above the layout switch; no pause inonDisappear. - Sheets and alerts attach to the window root and read their item from the model. Sign-in state lives above every window; secrets are in the Keychain.
- UIKit: same view controllers through trait changes; the top item is remembered before the change and restored after the next layout pass.
- Tested in Device Hub (Closed, Open, Partially Open, rotate, Split View, rotate-then-close) with every state in the table; a UI test flips the size class and checks the state summary.