duo-performance

Keeps an iPhone Duo app smooth when the phone folds and unfolds. One fold changes the app's layout size in several steps (a full-width view went 382 → 466 → 951 → 867 pt on open), and every body that

SKILL.md

GitHub

duo-performance

Make opening and closing iPhone Duo cheap for your app, prove it with numbers, and keep it that way.

Load other skills for the work around it: duo-transitions (the motion itself, the 120 Hz frame budget, CADisplayLink, the hinge stream), duo-layout and duo-continuity (one layout that changes shape, state that survives the fold), duo-pose-matrix (duo-pose, which this skill's script uses), duo-testing (launch switches and sample data).

Labels: measured means we ran it on the iPhone Duo simulator (iOS 27.1) on 6 November 2026; details in references/evidence.md. Unverified means we could not confirm it. Nothing here has run on a real iPhone Duo; references/device-checks.md lists what to check there.

What one fold costs

  • Several resizes, not one. While the window grows from 466 to 951 pt (duo-transitions), a full-width view went through three widths in about 100 ms (measured): 382 → 466 → 951 → 867 pt, as the safe area insets changed. UIKit updates the scene metrics (Window / UpdateSceneMetrics signposts, three in that open), and SwiftUI reruns body for every view that reads the size, lays out again and commits a frame. Closing changed that view's width once, to 382 pt.

  • The budget. Both displays run up to 120 Hz; a frame lasts 8.3 ms (Understanding hitches). While the main thread runs without going back to its run loop, the app can't commit a new frame; only animations already handed to the render server keep moving.

  • What an app pays (measured, Release builds, median of 3 folds):

    App Open: longest stretch / busy Close: longest / busy
    A grid of 3,000 cells, work done once 29 ms / 71 ms 14 ms / 45 ms
    The same, with a sort and a date formatter in body 486 ms / 517 ms 137 ms / 154 ms
    Ledger eval fixture: 2,000 rows, all the mistakes below 2,913 ms / 4,370 ms 1,645 ms / 1,683 ms
    Ledger fixed by hand with the steps below 86 ms / 115 ms 15 ms / 45 ms
  • The first fold after launch costs the most (measured: 71 and 43 ms longest on the fast grid, then 15 to 30 ms; 269 ms on the fixed Ledger, then 86 and 14 ms). Caches, first layouts of the wide variant and first appearances happen then.

  • These are simulator numbers: it runs on the Mac's CPU and draws at 60 Hz (maximumFramesPerSecond = 60, measured in Duology's device facts). Use them to compare and to find causes. They are not device timings.

Rules

  1. Measure before you change anything, and after. Same Mac, same simulator, a Release build, at least 3 cycles.
  2. body only describes views. No sorting, filtering, grouping, summing, formatter creation, date or number formatting of many items, image decoding or I/O in it. Do that once, when the data changes.
  3. Read the size once, high up, and pass down the one value the layout needs (a Boolean, a column count). Not a GeometryReader per row.
  4. Keep identity through the fold: one layout that changes shape (AnyLayout, a custom Layout), never an if that builds the same content twice, never .id(size).
  5. Long content is lazy: List, LazyVStack, LazyVGrid.
  6. Work that follows a fold (new prefetch, a reload for a new column count) waits until the fold settles, and runs off the main thread when it can.
  7. Smoothness is tested on a device. The simulator can't show 120 Hz or count hitches.

Step 1. Measure on the simulator

scripts/duo-fold-cost folds the phone with duo-pose while Instruments records the app's main thread, then reports each fold. The app needs no changes.

Needs: Xcode 27.1, the iPhone Duo simulator booted and shown in Device Hub, the app installed, and duo-pose status saying "Ready" (it presses Device Hub's pose buttons through the Accessibility permission; see duo-pose-matrix). It uses an existing simulator and never creates one.

DD=/tmp/myapp-dd; UDID=<the iPhone Duo UDID>
DEVELOPER_DIR=/Applications/Xcode-27.1.app/Contents/Developer xcodebuild -project MyApp.xcodeproj \
  -scheme MyApp -configuration Release -destination "id=$UDID" -derivedDataPath "$DD" build
xcrun simctl install "$UDID" "$DD/Build/Products/Release-iphonesimulator/MyApp.app"
scripts/duo-fold-cost run com.example.myapp --save before.json
Fold (median)           longest     busy   >8.3ms  stalls  hangs
closed -> open           2913 ms  4370 ms        3       3      2   (3 runs)
open -> closed           1645 ms  1683 ms        3       3      1   (3 runs)
Column What it is
longest The longest time the main thread ran without going back to its run loop: the app can't commit a frame before it ends. Watch this one first.
busy The main thread's total running time during the fold.
>8.3ms Stretches longer than one 120 Hz frame.
stalls UIKit's own count of update cycles that stalled (UpdateCycle.Stalls).
hangs What Instruments' Hangs instrument reported (its threshold: 100 ms).
  • Change the poses with --poses open,book,tabletop,closed, the count with --cycles 5, and pass launch arguments after -- (-- -sampleData). Launch the app on the screen you want to measure (duo-testing, launch switches).
  • After a change: scripts/duo-fold-cost run com.example.myapp --compare before.json. It prints what got slower or faster, and exits 1 when a median grew by at least 25 % and 20 ms.
  • --time-profiler adds the Time Profiler instrument and names the code the main thread was in during each fold's longest stretch (measured on the slow grid: closure #1 in slowSorted(_:) 79 %). It keeps the trace for Instruments.

How it works, every column and exit code, and recording a trace by hand: references/measure.md.

Step 2. Find the cause

  1. Run with --time-profiler. Mostly your code in the longest stretch: move that work out of body. Mostly "(system)": SwiftUI and UIKit are laying out or rebuilding too many views (measured on Ledger: 81 to 83 % system, the rest in EntryRow.body). For more, open the trace in Instruments at the fold's time.
  2. See why a view's body runs on a fold: add let _ = Self._printChanges() as its first line for a run, fold, and read the console (WWDC23 Demystify SwiftUI performance). Remove it after.
  3. Mark your own work with an OSSignposter interval: it shows next to the fold in the os_signpost instrument.
  4. Read the list of causes below against your body properties: each fold runs them several times.

On the simulator, Instruments' SwiftUI template doesn't record (measured: "Hitches is not supported on this platform."), the SwiftUI instrument added to a recording gets no data, and XCTHitchMetric returns no values. Use them on a device.

Step 3. Fix

What the trace shows Cause Fix
One long stretch per resize step, in your body Sorting, grouping, summing or formatting in body Do it once in a model when the data changes; body reads finished values
Long stretches in layout, many rows A non-lazy stack of every row List, LazyVStack or LazyVGrid
Rows re-laid out at every step A GeometryReader in each row Read the size once, high up; pass a value
The whole screen rebuilt, scroll and selection lost if wide { … } else { … } building the same views twice, or .id(width) AnyLayout or a custom Layout; no .id tied to the size
The same action runs several times per fold onGeometryChange returning the raw size Return the small value the layout needs: it runs only when that changes
Work right after the fold A reload or prefetch on each resize step .task(id:) on the small value, with a short wait, off the main thread
Images decode again at each size (unverified on Duo) Decoding at the view's current size Decode once, sized for the largest display, off the main thread

Code for each fix, all typechecked: references/fixes.md.

Step 4. Keep it from coming back

  • Keep a saved run per Mac (--save main.json on the main branch) and run --compare main.json before merging work that touches a screen people fold on. Numbers from different Macs don't compare.
  • Put the work you moved out of body in plain functions or a model, and test them on the Mac with XCTClockMetric or a logic test (duo-testing). They are where a regression comes back.
  • Run duo-fold-cost before each release, next to /duo-ship.

Step 5. From real users (iOS 27)

MetricKit can split its daily report by a state the app reports, with the StateReporting framework (MetricManager, StateReporter). State entries carry hang time, hitch time, terminations and signpost intervals (MetricReport). Report the pose, and you get hitches and hangs per pose from real phones.

  • Report closed, open, book or tabletop from the fold geometry, once the pose has held for half a second: one fold passes through several sizes, and Apple warns that reporting faster than "user interaction timescales" can be rate-limited.
  • Mark each fold as an animation interval with mxSignpostAnimationIntervalBegin, so the report counts hitches during folds.
  • Measured on the simulator: the pose transitions show in Instruments (Points of Interest, a State Reporting track), labelled correctly in all four poses. The fold intervals from MetricKit's log handle didn't appear, and no report arrives on the simulator.

The code, which also builds for iOS 26 and does nothing there: references/field.md.

Step 6. On a device

The simulator can't tell you whether folds are smooth at 120 Hz. On an iPhone Duo, profile Open and Close with the Animation Hitches template, run your UI tests with XCTHitchMetric, and watch the Hitches metric in Xcode Organizer. The list, with what we expect and what would change this skill: references/device-checks.md.

Checklist

  • A saved duo-fold-cost run from before the change, and a --compare after it
  • No sorting, grouping, summing, formatter creation or decoding in any body
  • The size read once per screen, as the value the layout needs
  • One layout that changes shape; no if that builds the same content twice; no .id tied to the size
  • Long content in List, LazyVStack or LazyVGrid
  • Follow-up work in .task(id:) after the fold settles, off the main thread
  • Images decoded once, for the largest display
  • Pose reported to MetricKit (iOS 27), fold intervals marked
  • Device checks done, or listed as not done