duo-scenes
Scenes and windows on iPhone Duo, Apple's foldable. Use when an app opens a second window (openWindow, WindowGroup(for:), activateSceneSession, UISceneSessionActivationRequest, UIWindowScene.Activatio
SKILL.mdplugins/duology/skills/duo-scenes/SKILL.md
GitHubduo-scenes
iPhone Duo is the first iPhone that can show more than one window of the same app. It also runs two apps side by side on the inner display, and it can put a camera app's extra content on the outer display. All of this goes through scenes. This skill tells you how to open windows safely, how to use scene accessories, and how to keep each window's state.
Load other skills for neighbouring work: duo-layout (size classes, half-width layouts in Split View), duo-continuity (state that survives a fold inside one window), duo-navigation (bars on the outer edge in Split View), duo-pose-matrix (set the simulator's pose from a script), duo-testing (UI tests on the simulator).
Labels: measured means we ran it on the iPhone Duo simulator (iOS 27.1) on 18 October 2026, closed and fully open, with no camera; 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.
What changes on iPhone Duo
| Feature | What Apple says | Source |
|---|---|---|
| Several windows of one app | If your app supports several windows on iPad, it does on iPhone Duo too. | Tech Talk 111464 |
| New windows | Only the inner display can create one. Requests on the outer display fail, so handle errors. UIWindowScene.ActivationAction hides itself when a new window isn't possible. |
111464 |
| Split View | Every app takes part. Two apps share the inner display 50/50, each with its bars on its outer edge. A pinned Picture in Picture video can sit on top and resize the app below. | 111464, Tech Talk 111466, HIG |
| Scene accessories | The system can show your extra content on another display. A camera capture accessory uses the outer display while the camera UI runs full screen on the inner display. | 111464, Registering a camera capture accessory |
Rules
- Make every window work on its own. One model per window, one shared store per app.
- Treat "Open in New Window" as an extra. The same content must open inside the current window too.
- Pass an error handler to every UIKit scene request, and fall back to showing the content in place.
- Never assume a new window appears beside the old one. Measured: closed and open, it replaced the visible window.
- Write
UIWindowScene.ActivationAction(title:alternate:_:)with thealternate:label, or an explicitreturn. The short form crashes (section 3). - Register a camera capture accessory on the view that shows your camera. Keep every control in the main UI; the accessory can vanish at any time.
- Save per-window state on
.background. ReadwindowScene.screenwhen you need it; never cache it. - Test what the simulator can't show on a real iPhone Duo: the camera accessory with capture running, and the outer display refusing new windows.
1. Turn on multiple windows
Add the scene manifest key to the app's Info.plist. Apps without it get one window (UIApplicationSupportsMultipleScenes).
<key>UIApplicationSceneManifest</key>
<dict>
<key>UIApplicationSupportsMultipleScenes</key>
<true/>
</dict>
- Check the built app:
plutil -p <App>.app/Info.plist | grep -A2 SceneManifest. - Measured: with the key, UIApplication.shared.supportsMultipleScenes and SwiftUI's
supportsMultipleWindowswere bothtrueon the closed phone. Apple'ssupportsMultipleWindowspage still says only iPadOS and macOS returntrue. Neither value tells you which display you're on. - Split View needs no key. Every app takes part, so every app must lay out at half the inner display. See
duo-layout.
2. Open a window: SwiftUI
Declare a WindowGroup(for:) per kind of content and open it with openWindow(value:). If a window already shows that value, the system brings it forward (OpenWindowAction).
import SwiftUI
import Observation
struct Note: Identifiable, Hashable, Codable, Sendable {
var id = UUID()
var title: String
}
@MainActor @Observable
final class NoteStore { // one per app, shared by every window
var notes = [Note(title: "Groceries"), Note(title: "Trip")]
func note(_ id: Note.ID?) -> Note? { notes.first { $0.id == id } }
}
struct NotesApp: App { // mark it @main in your app
@State private var store = NoteStore()
var body: some Scene {
WindowGroup {
NoteList().environment(store)
}
WindowGroup("Note", for: Note.ID.self) { $id in
NoteDetail(id: id).environment(store)
}
}
}
struct NoteList: View {
@Environment(NoteStore.self) private var store
@Environment(\.openWindow) private var openWindow
@Environment(\.supportsMultipleWindows) private var supportsMultipleWindows
@State private var path: [Note.ID] = [] // each window keeps its own
var body: some View {
NavigationStack(path: $path) {
List(store.notes) { note in
NavigationLink(note.title, value: note.id) // works in every window
.contextMenu {
if supportsMultipleWindows {
Button("Open in New Window", systemImage: "plus.rectangle.on.rectangle") {
openWindow(value: note.id)
}
}
}
}
.navigationDestination(for: Note.ID.self) { NoteDetail(id: $0) }
}
}
}
struct NoteDetail: View {
@Environment(NoteStore.self) private var store
let id: Note.ID?
var body: some View { Text(store.note(id)?.title ?? "Note not found") }
}
openWindowhas no error callback. Where multiple windows aren't supported, SwiftUI ignores the call and logs an error (supportsMultipleWindows).- Measured, closed and open:
openWindow(id:)raised no error. The new window took the whole display (951 × 669 pt when open, not half), and the old one moved to the background, still connected. Split View comes from people dragging a window aside, not from your request. When the app later launched with two saved windows, the system showed a "2 Views Open" pill. That is why rule 2 matters: people may not find the old window again. - Apple says the outer display can't create new windows (111464). Our simulator didn't refuse. Code for both. Unverified: what a real iPhone Duo does here.
3. Open a window: UIKit
Ask with activateSceneSession(for:errorHandler:) and a UISceneSessionActivationRequest (both iOS 17). When it fails with a UISceneError, show the content in the current window.
import UIKit
enum NoteActivity {
static let type = "com.example.notes.open" // list it under NSUserActivityTypes
static func make(noteID: UUID) -> NSUserActivity {
let activity = NSUserActivity(activityType: type)
activity.targetContentIdentifier = noteID.uuidString
activity.userInfo = ["noteID": noteID.uuidString]
return activity
}
}
@MainActor
func openInNewWindow(noteID: UUID, otherwise showHere: @escaping @MainActor @Sendable () -> Void) {
let app = UIApplication.shared
guard app.supportsMultipleScenes else { showHere(); return }
let request = UISceneSessionActivationRequest(userActivity: NoteActivity.make(noteID: noteID))
app.activateSceneSession(for: request) { error in
let code = (error as? UISceneError)?.code // .multipleScenesNotSupported, .requestDenied
print("No new window:", code.map { "\($0)" } ?? "\(error)")
Task { @MainActor in showHere() }
}
}
In menus, use UIWindowScene.ActivationAction; its handler returns a UIWindowScene.ActivationConfiguration. Give it an alternate: action that opens the note in place, and don't list that action again. Apple's header says the alternate replaces the action where multiple windows aren't supported, and runs if the request fails.
import UIKit
@MainActor
func openNoteMenu(noteID: UUID, showHere: @escaping @MainActor () -> Void) -> UIMenu {
let inPlace = UIAction(title: "Open", image: UIImage(systemName: "doc.text")) { _ in showHere() }
let newWindow = UIWindowScene.ActivationAction(title: "Open in New Window", alternate: inPlace) { _ in
UIWindowScene.ActivationConfiguration(userActivity: NoteActivity.make(noteID: noteID))
}
return UIMenu(children: [newWindow]) // shows "Open" where no window can open
}
- Measured: the action showed on the open phone. On the closed phone, with
alternate: nilit was missing, as Apple says, and with an alternate the alternate took its place. The raw requests still succeeded there (section 2), so the action is the more reliable signal. - Measured:
UIWindowScene.ActivationAction(title: "X") { _ in config }compiles with only a warning ("result ... is unused"), because Swift picksUIAction's handler initializer. At runtime it throwsNSInternalInconsistencyException("Initializer is unavailable"). Always writealternate:(evenalternate: nil) orreturn config. - Read the activity when the new scene connects:
connectionOptions.userActivities.first(doc). Code: references/multiple-windows.md.
4. Scene accessories: content on the outer display
A scene accessory is extra content you declare. The system decides if, when and where to show it (sceneAccessory(content:)). Two kinds exist in the iOS 27.1 SDK:
| Accessory | Where it shows | Interactive | Since |
|---|---|---|---|
CameraCaptureAccessory / UISceneAccessory.cameraCapture(sceneConfiguration:) |
The outer display, while your camera UI runs on the inner display | Yes, keep it minimal | iOS 27.1 |
ExternalNonInteractiveAccessory / UISceneAccessory.externalNonInteractive(sceneConfiguration:) |
A connected or AirPlay display. Apple names no other. | No | iOS 27.0 |
The camera capture accessory shows only when all of these hold (111464, Apple's guide): the phone is fully open, your app is in the foreground and full screen on the inner display, a capture session is running (Apple's overview names the rear camera), and the view that registered it is on screen. It goes away when capture stops, the app leaves the foreground, the phone closes, or a deeper view registers its own.
import SwiftUI
import Observation
@MainActor @Observable
final class ShootModel {
var secondsToStart: Int? // countdown the subject sees
var isRecording = false
var showsSubjectView = true // the photographer can turn it off
var subjectViewAvailable = false // only the system sets this
}
@available(iOS 27.1, *)
struct CaptureScreen: View {
@State private var model = ShootModel()
var body: some View {
NavigationStack { // toolbar items show only inside a navigation container
CameraPreview() // your capture UI; it runs the capture session
.sceneAccessory {
CameraCaptureAccessory(isEnabled: $model.showsSubjectView) {
SubjectView(model: model)
}
.onAvailabilityChange { model.subjectViewAvailable = $0 }
}
.toolbar {
if model.subjectViewAvailable {
Toggle("Subject View", systemImage: "person.crop.rectangle", isOn: $model.showsSubjectView)
}
}
}
}
}
struct SubjectView: View { // what the person in front of the camera sees
let model: ShootModel
var body: some View {
if let seconds = model.secondsToStart {
Text("\(seconds)").font(.system(size: 160, weight: .bold))
} else {
Label(model.isRecording ? "Recording" : "Ready", systemImage: "record.circle")
.font(.largeTitle)
}
}
}
struct CameraPreview: View { // stand-in for your preview layer
var body: some View { Color.black.ignoresSafeArea() }
}
- Hand the accessory the same model object. A tap on the outer display then changes what the photographer sees, with no messages in between (Apple's guide).
- Turn it off with
isEnabled, not by removing it. Availability and enabled are separate: the system owns the first, you own the second. It's on by default. - Measured, no capture session (the simulator's known issue): open, availability became
trueand the system made a scene with rolewindowCameraCaptureAccessoryon the outer screen (466 × 678 pt). Closing the phone set it tofalseand discarded that session; reopening made a new scene and new content views. Closed at launch, it stayedfalse. A second window in front made the first window's accessory unavailable. - Deploying below iOS 27.1: wrap the modifier in
if #available(iOS 27.1, *). If the target also builds for Mac Catalyst, wrap it in#if !targetEnvironment(macCatalyst)too: the accessory types don't exist there. Code, the UIKit version, both accessories at once and camera direction per display: references/scene-accessories.md.
5. State per window
Each window is its own scene session, with its own saved state.
- SwiftUI:
@SceneStorageis per window (SceneStorage). Measured: a new window started at 0 while the first window held 7. After a relaunch the system reconnected only the last window used. Activating the other saved session brought back its 7. - UIKit: return an
NSUserActivityfrom stateRestorationActivity(for:) and readsession.stateRestorationActivitywhen the scene connects. - Bring back an existing window with UISceneSessionActivationRequest(session:), not a new request. Otherwise people collect duplicate windows.
- A fold doesn't need restoration: the window stays alive and resizes.
duo-continuitycovers that. - Measured: SwiftUI restores with its own activity type (
com.apple.SwiftUI.stateRestoration). Don't read or replace it. - Measured: application(_:didDiscardSceneSessions:) also reports accessory sessions. Check
session.rolebefore deleting per-window data. - Code for both frameworks, and cleaning up discarded windows: references/restoration-and-lifecycle.md.
6. Scene lifecycle on fold and unfold
Apple says opening and closing work like resizing the app in iPhone Mirroring (Tech Talk 111461). For a scene this means it moves to the other screen and changes size:
| Event | What to expect | Source |
|---|---|---|
| Window moves between displays | windowScene(_:didUpdateEffectiveGeometry:) (iOS 26) always fires, and windowScene.screen changes. Measured: same scene and session, the size class flipped. |
doc, evidence |
| Display link | windowScene.displayLink(target:selector:) (iOS 27) follows the scene to the new display. UIScreen's version is deprecated in iOS 27 (UIScreen.h). |
doc |
| Scene phase during a fold | Measured: scenePhase stayed active through close and open. No inactive, no new onAppear. |
evidence |
| Two windows in Split View, then close | Unverified which one moves to the outer display | Split View needs a drag in Device Hub |
| Any window going to the background (covered by another window, or the whole app) | Measured: inactive, then background, still connected. In 5 of 6 runs, two geometry updates followed within 0.2 s, with no fold. Closed: 466 × 678 to 951 × 669 pt and back, width class unchanged. Open: 951 × 669 to 466 × 678 pt and back, width class regular, compact, regular. |
closed, open |
So:
- Never tear down on
.inactiveor sceneWillResignActive(_:). Save on.background. - Don't treat a geometry update as "the person is looking". Check activationState first. If the scene isn't active, skip the work and catch up in sceneDidBecomeActive(_:).
- SwiftUI: a size-class change alone is not a fold. Act on it only while
scenePhase == .active, check again when the phase returns to.active, and keep one view tree for both widths so@Statesurvives (duo-continuity). Code for both: references/restoration-and-lifecycle.md. - Handle sceneDidDisconnect(_:) at any time. The system may release a background window's scene and keep its session.
- Don't start work from a window's first
onAppearsize. Measured: a new window's first layout reported 466 × 562 pt, then 382 × 644 pt.
UIKit
Scene delegate code for new windows, a close confirmation for windows with unsaved work (closureConfirmation, iOS 27), restoration, geometry updates, the accessory registration and the accessory's own scene delegate: references/multiple-windows.md, references/scene-accessories.md, references/restoration-and-lifecycle.md.
Test it
- Run on the iPhone Duo simulator. Closed: request a new window and check that the content still opens in place when the request fails or covers the old window.
- Open the phone: ask the user to press Open in Device Hub, or, if they want it scripted, run
duo-pose set openfrom duo-pose-matrix. The pose applies to everything on the shared simulator, andduo-poserefuses while UI tests run. Open a second window, then drag your app by its home indicator to each side for Split View (Tech Talk 111461). Close the phone the same way (duo-pose set closed) with two windows open and note which one stays. - Log scene events with the probe pattern in references/evidence.md.
- Screenshots:
xcrun simctl io booted screenshot --display=primary outer.pngand--display=primary-1 inner.png.
What the simulator can't tell you:
| Check | Why | Do instead |
|---|---|---|
| Camera capture accessory conditions | The simulator has no camera, and in the Duo simulator the accessory shows without a capture session (Xcode 27.1 release notes) | Check its layout in the simulator; test availability on a real iPhone Duo with capture running, then stop capture and close the phone |
| Touch on the accessory | It needs the accessory shown for real, with capture running | Real device |
| The outer display refusing new windows | Our simulator didn't refuse | Real device; keep the in-place fallback either way |
Checklist
-
UIApplicationSupportsMultipleScenesis set only if every window works alone; one model per window, one shared store. - Every "Open in New Window" has an in-window way to the same content.
- UIKit requests pass an error handler that falls back to showing the content in place.
-
ActivationActionusesalternate:(or an explicitreturn), never the short trailing-closure form. - Existing windows come back through
UISceneSessionActivationRequest(session:), not duplicates. - The layout works at half the inner display, with bars on either edge (Split View on both sides).
- The camera capture accessory is registered on the camera view, shares the capture model, has a toggle shown only while available, and carries no essential control.
- Accessory code sits behind
#available(iOS 27.1, *), and behind#if !targetEnvironment(macCatalyst)when the target builds for Mac Catalyst. - Per-window state saves on
.background; nothing tears down on.inactive; size and size-class reactions run only while the scene is active, and catch up when it becomes active. - No cached
UIScreen; display links come from the window scene. - Accessory tested on a real iPhone Duo with capture running; inner-display windows tested in Device Hub.