That’s the part most visualEffect write-ups skip. GeometryReader was never the real tax. The real cost is a value that changes every frame landing in state on a view that has a lot of work to do. Whatever API produced the number, once it lands in @State on the wrong view, you’ve signed up for a body evaluation per frame.

Here’s how I moved that parallax to the render layer. I’ll also cover a second effect I built the same way and deleted three weeks later, the one scroll effect in the app that still uses state on purpose, and a Bool that can leave a toggle disabled forever.

Harvester of Sorrow — The Scroll Offset That Rebuilt the Home Screen

In March, VinylCrate’s featured-album card got parallax. The artwork slides down at 30% of scroll speed and stops at 40 points. The image is drawn 1.4 times the card’s height, so there’s extra artwork outside the visible crop for it to slide into.

Here’s how it was wired. CollectionScrollView, the view behind the entire home screen, owned the offset:

@State private var heroScrollOffset: CGFloat = 0

.onScrollGeometryChange(for: CGFloat.self) { $0.contentOffset.y } action: { _, offset in
    heroScrollOffset = offset
}

It passed that value to FeaturedAlbumView through a scrollOffset: parameter, and the card turned it into an offset:

let parallaxOffset = scrollOffset > 0 ? min(scrollOffset * 0.3, 40) : 0

.offset(y: parallaxOffset)

None of those lines are wrong on their own. The problem is how they fit together.

onScrollGeometryChange splits its work into a transform and an action, and the action only runs when the transformed value changes. That works great when the transform turns scrolling into something coarse, like a Bool. This transform handed back contentOffset.y untouched, and during a scroll that value changes every frame. So every frame wrote heroScrollOffset, and every write invalidated the view that owned it.

The view that owned it was the whole collection screen: the LazyVStack with every section of the grid, plus the alphabetical index overlay. All of it was re-evaluated and diffed against the previous tree so one image could move a few points.

I’ve written about keeping body re-evaluations rare and finding the ones you didn’t expect. This one is easy to miss because the code looks modern. In the GeometryReader days you could at least see the cost: a greedy container, sizes fed in by hand, an onChange writing state. With onScrollGeometryChange the code is three lines and tidy, but the structure underneath hasn’t changed. A parent still takes a state write on every frame.

Chasing Light — Parallax at the Render Layer

In May I moved it into visualEffect. The commit message sums it up:

This avoids body rebuilds on every scroll frame; the transform runs at the render layer.

The @State came off CollectionScrollView. The onScrollGeometryChange went with it, and so did the scrollOffset: parameter. Here’s what replaced all three, trimmed of the matched-geometry modifier and design tokens:

private func parallaxBackground(height: CGFloat) -> some View {
    CachedAsyncImage(url: detail.bestImageURL) { image in
        image
            .resizable()
            .aspectRatio(contentMode: .fill)
            .visualEffect { content, geometry in
                let amount = -geometry.frame(in: .scrollView).minY
                let parallax = amount > 0 ? min(amount * 0.3, 40) : 0
                return content.offset(y: parallax)
            }
    } placeholder: {
        Rectangle()
            .fill(AppColors.separator.opacity(0.3))
    }
    .frame(height: height)
    .clipped()
}

Same math, same 30%, same 40-point cap. The difference is where it runs.

Here’s the declaration in the SDK:

nonisolated public func visualEffect(
    _ effect: @escaping @Sendable (EmptyVisualEffect, GeometryProxy) -> some VisualEffect
) -> some View

The first argument is a placeholder for the view you’re modifying. You don’t build views with it. You chain effects off it and return the result. The second is a GeometryProxy for the modified view itself: its size, and its frame in whatever coordinate space you ask for. It’s the same proxy GeometryReader hands you, without a container that takes over your layout.

Apple describes a VisualEffect as changing “the visual appearance of a view without changing its ancestors or descendents,” and that’s the whole contract. Everything you can call on the placeholder is a render-time transform: offset, scale, rotation, opacity, blur, color adjustments, shaders. None of it can resize the view, and nothing around it moves to make room. That’s why it’s safe to compute from geometry. The classic scroll-effect feedback loop goes geometry to state, state to body, body to layout, and layout back to geometry. An effect that can’t change layout can’t trigger another layout pass, so the loop never starts.

There’s no state anywhere in that picture either. FeaturedAlbumView’s body runs, sets up the closure, and stays out of it. SwiftUI re-runs the closure as the image’s geometry changes, and nothing is invalidated or diffed along the way. CollectionScrollView doesn’t know the parallax exists.

Two details make this particular effect work.

There’s hidden image to slide. The artwork is .fill, so it overflows its frame. The 1.4× height gives it room, and .clipped() trims what’s outside. Offsetting the image pulls pixels that were already cropped into view. Without that slack, an offset just opens a gap at the edge. Remember that, because it decides the next effect.

The card measures itself. The old version read the scroll view’s contentOffset, which only matched “how far past the hero” because the hero happened to sit at the top of the content. The new version measures the image’s own frame against the nearest scroll view. amount goes positive once the image’s top edge passes above the scroll view’s top edge, and only then does the offset kick in. The card no longer depends on where it sits.

Thorn Within — The Capture List Reduce Motion Needed

In September I gated that parallax on Reduce Motion. It was the only motion in the app that ignored the setting, and it sat on the first screen people see. Parallax is one of the classic triggers for motion sensitivity, so that was a bad one to miss.

The obvious change doesn’t compile:

.visualEffect { content, geometry in
    let amount = -geometry.frame(in: .scrollView).minY
    let parallax = amount > 0 && !reduceMotion ? min(amount * 0.3, 40) : 0
    return content.offset(y: parallax)
}

Go back to the signature: an @Sendable closure on a nonisolated function. The closure doesn’t run on the main actor, and reduceMotion is an @Environment property on a main-actor view. VinylCrate also builds with SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor, so everything in the module is main-actor unless it says otherwise. The compiler won’t let a Sendable closure reach back into main-actor state.

What ships is a capture list:

.visualEffect { [reduceMotion] content, geometry in
    let amount = -geometry.frame(in: .scrollView).minY
    let parallax = amount > 0 && !reduceMotion ? min(amount * 0.3, 40) : 0
    return content.offset(y: parallax)
}

The capture runs when body builds the closure, and body runs on the main actor, so the copy is legal. After that the closure only ever sees a Bool. Reading the environment value in body also keeps the dependency. When someone flips Reduce Motion, body runs again, builds a new closure, and the new closure captures the new value. You don’t need any observation code for that.

The same rule covers helpers. With default main-actor isolation, a plain helper type or a private func on the view is main-actor isolated too, and the closure can’t call it. Anything the closure reads that isn’t a local or a capture has to be explicitly nonisolated. The parallax math is inline, so it never hit this. The next effect did.

Notice the shape of the Reduce Motion check, too. parallax is either the real number or 0, and .offset(y:) stays in the chain either way. That’s not just style. The closure returns some VisualEffect, an opaque type, so every path has to produce the same concrete chain. This won’t compile:

.visualEffect { [reduceMotion] content, geometry in
    if reduceMotion {
        return content.opacity(1)
    } else {
        return content.offset(y: -geometry.frame(in: .scrollView).minY * 0.3).opacity(1)
    }
}

Branch on values, not modifiers. When an effect should disappear, give it its identity value: offset 0, scale 1, blur 0. The shader effects take an isEnabled: parameter for the same reason.

Slither — Drawing the Record Out of the Sleeve

The same September change also touched the album detail screen. I wanted its hero to respond to scroll too, and parallax was the obvious first idea. It doesn’t work there.

FeaturedAlbumView’s parallax works because the image is .fill inside a fixed-height, clipped frame, so there’s hidden image to slide. The detail hero is .scaledToFit() with no clip. The artwork fills its frame exactly. Offset it and you expose the black background behind it. The only way to create slack would have been to crop the cover, and on a vinyl app the cover art is the whole point. Cropping it wasn’t an option.

So I drew the record out of the sleeve instead. A vinyl disc sat behind the cover in AlbumHeroHeader, and as you scrolled, it slid out to the right and turned:

nonisolated private enum Geometry {
    static let restingReveal: CGFloat = 20
    static let maxReveal: CGFloat = 56
    static let travel: CGFloat = 200
    static let rotationDegrees: Double = 16
    static let discInset: CGFloat = 10
}

VinylDiscView(
    artistName: detail.primaryArtistName,
    trackTitle: detail.title,
    labelColor: VinylLabelColor.forArtist(detail.primaryArtistName)
)
    .padding(Geometry.discInset)
    .visualEffect { [reduceMotion] content, geometry in
        let scrolled = max(0, -geometry.frame(in: .scrollView).minY)
        let progress = reduceMotion ? 0 : min(scrolled / Geometry.travel, 1)
        return content
            .offset(x: Geometry.restingReveal + progress * Geometry.maxReveal)
            .rotationEffect(.degrees(progress * Geometry.rotationDegrees))
    }
    .accessibilityHidden(true)

That nonisolated on the enum is the helper rule from the last section. Without it, under default main-actor isolation, Geometry is main-actor isolated and the closure can’t read its constants.

The disc was attached as a .background(alignment: .center) of the sleeve, not as a ZStack sibling, so the sleeve decided the size and the disc just lived behind it. The math maps the first 200 points of scroll onto a progress from 0 to 1. The disc rests 20 points out so there’s a hint of it at the top, then travels up to 56 more and rotates up to 16 degrees. Reduce Motion pins progress at zero, which leaves the resting reveal and stops all motion. Values again, not modifiers.

Rotation came from scroll offset rather than a TimelineView. A spinning record is the obvious version, and it would mean a timer running on a screen people sit on while they read liner notes. Driving it from scroll meant the disc moved when your thumb moved and not otherwise.

Too Far Gone? — The Effect That Never Read

On September 23 the disc came back out. Here’s the note I left:

On device the disc only ever showed as a sliver at the screen edge. On iPhone
the sleeve fills the width minus a 16pt margin, so the disc's travel went
off-screen and the effect never read.

That’s the whole story. The sleeve is nearly full-width on a phone, so a disc sliding out to the right has nowhere to go but past the edge of the screen. Those constants were first-pass numbers I planned to tune on a real phone. Once I saw it on a real phone, there was nothing worth tuning.

The refactors that came with it stayed. So did the Reduce Motion gate on the home screen. Only the disc left, and leaving was cheap. No state to unwind and no parameters threaded through parents. One closure and one enum came out of one file. visualEffect made the effect cheap to build, and it made it just as cheap to delete.

Mama Said — When Scroll State Is the Right Call

Not everything belongs in visualEffect. The album detail screen has one scroll effect that stays in state, and it should.

The back, favorite, and crate buttons float over the artwork in an .overlay(alignment: .top). As the hero scrolls up under them, a frosted backdrop fades in behind the buttons. It’s a linear ramp over 44 points, clamped between 0 and 0.6. The ceiling is there because .ultraThinMaterial is already SwiftUI’s lightest material, so capping the opacity is the only way to make it lighter.

visualEffect can’t do this, for a structural reason. The closure only knows the geometry of the view it modifies. The chrome sits outside the scroll content, so its own frame never moves when you scroll. Put a visualEffect on it and the closure sees the same rectangle every frame. The thing the fade depends on, the hero’s bottom edge reaching the bar, lives in a different view entirely. This one really does need state.

So the question becomes where the state lives. Not on the screen:

@MainActor
@Observable
final class AlbumDetailChromeModel {

    nonisolated static let maxBarOpacity = 0.6

    private(set) var barOpacity: Double = 0

    private(set) var heroHeight: CGFloat = 0

    nonisolated static func opacity(
        scrollOffset: CGFloat,
        heroHeight: CGFloat,
        barHeight: CGFloat,
        fadeDistance: CGFloat = 44
    ) -> Double {
        guard heroHeight > 0, fadeDistance > 0 else { return 0 }
        let threshold = heroHeight - barHeight
        let progress = (scrollOffset - threshold) / fadeDistance
        return Double(min(max(progress, 0), 1)) * maxBarOpacity
    }

    func updateHeroHeight(_ height: CGFloat) {
        guard height != heroHeight else { return }
        heroHeight = height
    }

    func update(scrollOffset: CGFloat, barHeight: CGFloat) {
        let newValue = Self.opacity(
            scrollOffset: scrollOffset,
            heroHeight: heroHeight,
            barHeight: barHeight
        )
        guard newValue != barOpacity else { return }
        barOpacity = newValue
    }
}

AlbumDetailView owns it, feeds it, and hands it to the chrome. Trimmed to the lines that matter:

@State private var chrome = AlbumDetailChromeModel()

var body: some View {
    ScrollView {
        VStack(spacing: 0) {
            AlbumHeroHeader(detail: detail) { chrome.updateHeroHeight($0) }
        }
    }
    .onScrollGeometryChange(for: CGFloat.self) { $0.contentOffset.y + $0.contentInsets.top } action: { _, offset in
        chrome.update(scrollOffset: offset, barHeight: Spacing.navBarHeight)
    }
    .overlay(alignment: .top) {
        AlbumDetailTopChrome(
            chrome: chrome,
            isFavorite: isFavorite,
            showsDelete: onDelete != nil,
            onBack: { dismiss() },
            onToggleFavorite: { container?.collection.toggleFavorite(detail) },
            onAddToCrate: { showingCrateOptions = true },
            onDelete: { showingDeleteConfirmation = true }
        )
    }
}

Ownership does the important work here. AlbumDetailView.body holds the model but never reads barOpacity. Only AlbumDetailTopChrome reads it, so a change invalidates that one small view and nothing else. That matters because AlbumDetailView is enormous. The SwiftLint header at the top of the file talks about splitting “the 1300-line body.” Putting this value in that view’s @State would recreate the home screen’s problem on the screen that can least afford it.

The clamp does the rest. opacity returns 0 before the threshold and maxBarOpacity past the fade band, so the value only changes inside those 44 points. Outside the band, the onScrollGeometryChange action still runs every frame, but it computes the same number every time, and the guard newValue != barOpacity turns that into no write at all. The guard is extra insurance. As I found in the last Observation post, @Observable’s generated setter already skips notification when an Equatable value comes in equal. I keep it anyway because it makes the intent obvious in the code instead of leaving it to whatever the macro generates.

Adding contentInsets.top to the offset normalizes it so zero means “at rest,” whatever the safe area is doing. The ramp is a nonisolated static func, which makes it pure arithmetic you can unit test without standing up a scroll view. With default main-actor isolation, that keyword has to be spelled out.

One more detail from the chrome is worth stealing:

.background {
    Color.clear
        .background(.ultraThinMaterial)
        .opacity(chrome.barOpacity)
        .ignoresSafeArea(edges: .top)
        .allowsHitTesting(false)
}

Even at zero opacity, that strip swallowed drags in the gaps between the buttons, which made the top of the page unscrollable. Invisible isn’t the same as absent.

Sleepwalk My Life Away — The Bool That Never Changes

The usual advice for scroll state is to quantize it: have the transform return something coarse, like a Bool, so the action fires twice per round trip instead of every frame. That advice is right. It also has a trap, and CRX’s onboarding is written to avoid it.

The disclaimer step won’t enable its accept toggle until you’ve scrolled to the bottom of the legal copy. Here’s the obvious version, the one CRX doesn’t use:

.onScrollGeometryChange(for: Bool.self) { geometry in
    Self.hasReachedBottom(geometry: geometry)
} action: { _, reachedBottom in
    if reachedBottom {
        hasScrolledToBottom = true
    }
}

The action only fires when the transformed value changes. On a phone, the disclaimer is taller than its container, so the Bool starts false, flips to true when you reach the end, and the toggle enables.

Now run it where the content fits without scrolling, like macOS or a large iPad. The Bool is true on the very first layout pass. It never changes after that, so the action never fires and the toggle stays disabled forever. The user did everything right. There was nothing to scroll.

The fix is to stop quantizing in the transform. Observe the whole ScrollGeometry and evaluate the predicate in the action:

.onScrollGeometryChange(for: ScrollGeometry.self) { geometry in
    geometry
} action: { _, geometry in
    if Self.hasReachedBottom(geometry: geometry) {
        hasScrolledToBottom = true
    }
}

static func hasReachedBottom(geometry: ScrollGeometry) -> Bool {
    geometry.contentOffset.y + geometry.containerSize.height
        >= geometry.contentSize.height - 24
}

The geometry always changes at least once, from its zero initial value to the first real layout, so the action fires on first layout too. If the content already fits, the predicate passes immediately. The 24-point tolerance means nobody has to land on the last pixel.

So here’s the more precise version of the rule. Quantizing is still right, but think about the first layout. A Bool that starts false and only flips when the user scrolls, like a header collapse threshold, is fine. A Bool that can already be true at first layout is the trap.

Better Than You — When scrollTransition Is the Right Tool

Before reaching for geometry at all, ask whether you need it. scrollTransition uses the same VisualEffect machinery and the same @Sendable closure, but it gives you a phase instead of a proxy. Here’s a general illustration, not app code:

AlbumCard(album: album)
    .scrollTransition(.interactive.threshold(.visible(0.6))) { content, phase in
        content
            .opacity(1 - abs(phase.value) * 0.5)
            .scaleEffect(phase.isIdentity ? 1 : 0.95)
    }

phase.value runs from -1 (leaving past the top or leading edge) through 0 (identity) to 1 (leaving past the bottom or trailing edge). The threshold decides what counts as fully visible. Here, a card is at identity once 60% of it is on screen. Swap .interactive for .animated and the transition snaps between phases with an animation instead of tracking the finger.

When the effect is about visibility, scrollTransition is the better tool. Cards that fade as they leave either edge are symmetric, and SwiftUI already knows the answer. That means less code and no coordinate-space decisions.

Reach for visualEffect when the effect is defined in points. VinylCrate’s parallax is 30% of distance scrolled, capped at 40 points, and it only reacts to the top edge. The disc mapped 200 points of travel onto a progress value. Neither is a visibility question. The same goes for anything that needs the view’s own size, or measures against a named container or a specific axis. visualEffect also works anywhere there’s geometry, while scrollTransition only works inside a scrolling container.

Spit Out the Bone — Where visualEffect Bites

Only VisualEffect methods are allowed. On iOS that’s offset (a CGSize or x:y:), opacity, three scaleEffect overloads, rotationEffect, rotation3DEffect, transformEffect (affine or projection), blur, brightness, contrast, saturation, grayscale, hueRotation, blendMode, and the shader effects colorEffect, distortionEffect, and layerEffect. If you’ve seen offset(z:), transform3DEffect, or perspectiveRotationEffect in examples, those are visionOS. Nothing that sizes or lays out content is on the list: no frame, padding, or font. shadow and clipShape aren’t there either. If one of those has to respond to scroll, you’re in state territory, and the chrome model above is the shape I’d use.

Layout never finds out. That’s the point of the API, and it’s also the trap. The parallax image offset 40 points still occupies its original frame. The disc rotated 16 degrees still had the frame it started with. Neighbors don’t make room. If something should push its siblings around, visualEffect is the wrong tool, and no amount of offset math will fake it convincingly.

Don’t assume the tap target followed the pixels. Hit testing is based on layout, and a visual effect is explicitly not layout. I haven’t found Apple documentation that pins down hit testing for visualEffect transforms, so measure it on the OS versions you ship rather than trusting me. Then design so the answer doesn’t matter. Keep big offsets on decorative layers. VinylCrate’s parallax moves artwork inside a clipped card, and the card, which is the button, stays where layout put it. The disc was accessibilityHidden and never interactive.

Pick the coordinate space on purpose. .global is the window, and it breaks first. Sheets, resizable iPad windows, and anything above the scroll view all leak into your “distance from the top.” .scrollView is the innermost containing scroll view, which is what both VinylCrate effects use, and it’s usually right until you nest a horizontal shelf inside a vertical feed. .scrollView(axis: .vertical) resolves to the innermost scroll view on that axis. GeometryProxy.bounds(of:) gives you that container’s bounds in the view’s local space when you need the viewport size as well as your position. For anything else, name the container and measure against it. Named coordinate spaces work the same way here as everywhere else.

Keep the closure to arithmetic. It runs for every visible view as geometry changes. No formatters, no allocations, no lookups, nothing that belongs in a model. Both VinylCrate closures are a handful of multiplications and a min. That’s the budget.

blur isn’t free. It renders offscreen, per view. One blurred hero is fine. A blur on every card in a dense list is the first thing you’ll feel on older hardware. If the frame budget gets tight, opacity and scale usually carry the effect on their own.

Measure it. Turn on the SwiftUI instrument, scroll, and count body updates for the screen’s parent view. Do it before the change and after. That comparison is the whole argument for this API, and it’s more convincing than anything I can write.

Orion — Pixels, Not State

Here’s the rule I’ve landed on. If an effect only moves pixels and can see the geometry it depends on, it belongs in visualEffect or scrollTransition, and it never touches state. If it changes layout, or it lives outside the scroll content it reacts to, it gets state. Clamp or quantize that state before it’s written, check what the first layout hands you, and keep it in the smallest view that reads it.

The scroll API you choose doesn’t decide the cost. Where the number lands does. VinylCrate’s home screen used the newest scroll API there is and still paid for a full collection body on every frame, because the number landed on the wrong view. Now the parallax runs at the render layer, and the home screen’s body never hears about it.

The disc is the other half. The architecture was right: no state, no timer, nothing a parent had to know about. That told me what the effect cost. It didn’t tell me whether anyone could see it. The phone answered that one.

Keep shipping.

That’s me on the left, 17 years old, in the Metal Up Your Ass shirt, next to my good friend Marc. Another good friend, Jamie, took the picture. We’re all still good friends to this day.

A couple of years later I finally saw them live. My first Metallica show was January 15, 1989. Damaged Justice tour, Kiefer UNO Lakefront Arena in New Orleans. I was 19 and sitting in the stands. Honestly, I don’t remember much about it other than having a great time.

That show opened with The Ecstasy of Gold into Blackened. Hold that thought.

I’ve seen Metallica about 15 times since then. This fall they kicked off a residency at the Sphere in Las Vegas called Life Burns Faster, and I went out for the first weekend: Thursday, October 1 and Saturday, October 3. They billed it as a “No Repeat Weekend.” A different setlist each night, with nothing repeated except the Kirk and Rob doodle.

My friend Brian got us tickets through the Legacy fan club presale. We had the First Entry GA Two Day Package, which meant general admission on the floor both nights. Brian is a good Metallica friend I met through Brandon, and Brandon is a longtime friend from when we worked together at Overstock.com. Amy stayed home with the dogs.

I stayed at the Westin, about a three-quarter-mile walk to the Sphere. It was really nice: no casino, no resort fees, and just one block off the Strip.

Metal Militia — The Fan Club Line and the Numbers on Our Hands

The line started around 10am.

If you’ve never done a GA line with the Metallica fan club regulars, here’s how it works. They write your place-in-line number on your hand. It’s not official, but it keeps things civil, and it lets you come and go within reason without losing your spot.

On Thursday, the Tokyo fan club chapter ran the line. On Saturday, Brandon ran it, and he did an amazing job.

I got there at 10 on Thursday and stayed until about noon. Then we went to get food and rest, and came back around 3. That only works because of the numbers. Without them, you’re standing on that patch of ground all day.

By Saturday you’re seeing the same people from Thursday. The ones I remember most were the Ecuador chapter and the Tokyo chapter. They came all the way from Ecuador and Tokyo to stand in that line. The Ecuador guys had picks made special for the trip, and one of them gave me one.

My spot in line, in Sharpie. And the ticket that got us onto the floor both nights.

Where the Wild Things Are — The Metallica Crowd Meets the Oz Crowd

The Sphere also runs The Wizard of Oz show, and there are giant inflatable Wicked Witch legs outside, striped stockings and ruby slippers included. They were right near our line.

The first day, we noticed a very different crowd heading in. Older folks, women, some of them dressed like Dorothy. The Oz show was still running right up until our 5pm entry time, so for a while you had a line full of Metallica fans on one side and Dorothy on the other.

It was a fun contrast.

Motorbreath — Gates, Wristbands, and the Walk to the Rail

Gates opened at 5:00. Everyone got in order by the number on their hand. Not ideal, but orderly. No shoving, no pushing.

From there we walked into another waiting zone, which was a basic single-file cattle line. We waited there until 6:45 for doors. First Entry let about 500 of us in 15 minutes before everyone else. Security, then a floor wristband, then another brisk walk to the floor.

Our floor band. You can still see what’s left of my line number on my hand.

We ended up on the rail near the tip of the stage. Both nights. It was a lot like the two nights I spent in the snake pit at Mile High in Denver last year, which I wrote about in my year-end post.

That’s me in the red circle, on the rail near the tip of the stage.

Before the show, the screen was covered in flags and banners from fan club chapters all over the world. I found the Tokyo chapter’s flag. I never did spot the Ecuador one.

The Call of Ktulu — Night One

Night one opened with Battery, the first time they’d opened a show with it since 2014.

Thursday, October 1: Battery, Creeping Death, Now That We’re Dead, Sad but True, The Shortest Straw, Wherever I May Roam, The Day That Never Comes, …And Justice for All, Kirk and Rob Doodle, Nothing Else Matters, The Call of Ktulu, Lux Æterna, Ride the Lightning, The Memory Remains, Seek & Destroy, Master of Puppets.

The big one for me was …And Justice for All. It hadn’t been played since August 2014, and I loved seeing it. Brandon had been hoping they’d add Justice back since it had been so long, so he got his wish.

From the floor it was hard to take in the full Sphere visuals. For me, this weekend was mostly about seeing the band up close. I did get a couple of shots, though: Lady Justice up on the screen during …And Justice for All, and a giant Ktulu rising over the stage during The Call of Ktulu.

The end of night one. James hands off his guitar and takes it all in.

Hero of the Day — Giving Blood and an Off Day in Vegas

Friday was the off day, so I gave blood at Metallica’s blood drive. I’d signed up ahead of time and had an appointment, so the wait was only about 15 minutes.

You got a T-shirt and a pick, plus cookies, snacks, and water. There were older show posters on the walls, Metallica pinball machines to play, and a drum kit set up for photos. Of course I sat behind it.

After that came the official pop-up store. Another three-hour line.

This is the show poster I was able to get. A demon tearing through the Welcome to Fabulous Las Vegas sign, with both of our dates on it.

We walked around for a while, then I met Brandon and Brian for dinner and we went to see Penn & Teller. It was my first time seeing them. Fun show, and I’d see them again.

We also found KISS World at the Rio. It’s an interesting display. They even had a KISS mini putt-putt.

Left to right: the Ecuador chapter pick (they had them made special for the trip), the pick Rob handed me, and the blood drive pick.

Blackened — Night Two, 37 Years Later

Saturday started with AC/DC’s “It’s a Long Way to the Top” on tape. Then The Ecstasy of Gold. Then Blackened.

Same opening as my first show in New Orleans. In 1989 I was 19 and in the stands. Thirty-seven years later, I was on the rail.

The band hitting the stage on night two, filmed from the rail.

Saturday, October 3: Blackened, Fuel, Leper Messiah, Devil’s Dance, 72 Seasons, King Nothing, Welcome Home (Sanitarium), The Outlaw Torn, Kirk and Rob Doodle, The Unforgiven, Orion, Hardwired, Whiskey in the Jar, For Whom the Bell Tolls, One, Enter Sandman.

Devil’s Dance hadn’t been played since 2008, and it was really good. The Outlaw Torn hadn’t been played since 2019. Both were amazing to see.

Across the two nights, they played ten songs from that 1989 setlist: Blackened, For Whom the Bell Tolls, Welcome Home (Sanitarium), Leper Messiah, Master of Puppets, One, Seek & Destroy, …And Justice for All, Creeping Death, and Battery.

Lars behind the kit on night two.

Devil’s Dance — Life on the Rail

Being on the rail is addicting. You get to interact with the band and be up close and personal.

James walks by, makes eye contact, and nods at you while he’s playing. Lars walks by teasing like he’s about to hand you a drumstick. Kirk comes by and just dumps picks to everyone in the crowd.

It makes all the standing and waiting worth it. At least to this crazy fan.

Then there was Rob. On night two he was walking around the stage throwing picks. He went to throw me one, and it fell short. Rob said “Fuck,” walked over, and handed me the pick.

I thought it was great and funny at the same time.

That’s two for Rob now. He gave me a high five at the Arlington show a few years ago.

After the show we got a group photo under the lit-up Metallica logo. That’s me on the far right, then Brandon, then Brian, plus two others whose names I don’t remember.

Turn the Page — A Cancelled Flight and One More Night

Sunday, my flight got cancelled. I came back from the airport and stayed an extra night, this time at the MGM.

I decided to look at it as one more night in Vegas. I really hadn’t had a nice dinner the whole trip, so I went to Morimoto. Then I crashed.

I made my flight on Monday. I was tired and ready to get home to Amy and the dogs. The flight home went right over the Grand Canyon.

I’m not done with the Sphere yet. I’m going back for the October 29 and October 31 shows for my birthday, and Amy is coming with me. We’ll be in the seats this time. I’m looking forward to a whole new experience of the show, and to finally seeing the visuals. I’ll write that one up too.

In 1989 I was in the stands. This weekend I was on the rail. At the end of the month, I’ll be in the seats with Amy.

I found that out in Workout Wanderer, my HealthKit and MapKit app. It maps your workout routes on iPhone and iPad, paints them as heat maps (heart rate, pace, elevation, cadence, power, and a few more), and lets you compare workouts side by side. Workouts load in two phases. First comes the basic list. Then background enrichment fills in each workout’s route, city name, heart-rate summary, elevation stats, and the detailed series the heat maps draw from.

Three commits landed on September 27, and all three trace back to one struct. The first fixed an == that was too loose, so observers never heard about enrichment. The other two fixed observers that were too broad, so two map cameras reacted to every enrichment write. The bugs point in opposite directions, but they’re the same bug. And I only found the second one because I fixed the first.

Dirty Window — An id-only == on a Two-Phase Model

Here’s WorkoutData before the fix, trimmed:

struct WorkoutData: Identifiable, Equatable {
    let id: UUID
    let workout: HKWorkout

    var cityName: String?
    var routeCoordinates: [CLLocationCoordinate2D] = []
    var heartRateData: (low: Double, avg: Double, high: Double)?
    var routeLocations: [WorkoutLocation] = []
    var detailedHeartRateData: WorkoutHeartRateData?
    var detailedPaceData: WorkoutPaceData?
    // ...detailedElevationData, detailedCadenceData, detailedRunningPowerData,
    // detailedVerticalOscillationData, detailedGAPData, detailedPowerEffortData
    var cachedElevationStatistics: ElevationStatistics?

    static func == (lhs: WorkoutData, rhs: WorkoutData) -> Bool {
        lhs.id == rhs.id
    }
}

Hashable lives in an extension and hashes the same single field:

extension WorkoutData: Hashable {
    func hash(into hasher: inout Hasher) {
        hasher.combine(id)
    }
}

An id-only == is easy to write and easy to defend. Two values with the same id are the same workout, so they’re equal. For a model that never changes after it’s created, that’s close enough. WorkoutData changes after it’s created. That’s the whole point of phase two. A workout with no route and a workout with a full route, a city, and eight heat-map series all compared equal as long as they shared a UUID.

The commit message says what that cost: “SwiftUI observers of workoutsData (and of an enriched selectedWorkout) never saw routes, city names or heat-map data arrive.”

That “never” deserves a footnote, and the footnote is the most interesting part of the whole fix.

The House Jack Built — What @Observable Generates for a Setter

I went and read what the @Observable macro actually generates in the Swift 6.4 toolchain. For a stored property like selectedWorkout, the setter looks like this:

set {
    guard shouldNotifyObservers(_selectedWorkout, newValue) else {
        _selectedWorkout = newValue
        return
    }
    withMutation(keyPath: \.selectedWorkout) {
        _selectedWorkout = newValue
    }
}

shouldNotifyObservers is overloaded. For T: Equatable it returns lhs != rhs. For T: AnyObject it returns lhs !== rhs. For T: Equatable & AnyObject it goes back to lhs != rhs. The unconstrained version returns true.

WorkoutData? is Equatable. So is [WorkoutData], and an array’s == asks each element’s ==. Assign a value that your == calls equal, and Observation takes the early exit. It stores the new value and notifies nobody.

Read that twice, because it’s not the bug you’d guess. The data isn’t lost. It’s sitting in the backing storage. Any view that re-renders later for some unrelated reason reads it and draws it. That’s the kind of bug that looks intermittent, and it’s completely deterministic.

The footnote gets one level deeper. The macro also generates a _modify accessor, and that’s what in-place mutation goes through: workoutsData[index] = merged. _modify calls the registrar’s willSet and didSet unconditionally. No equality check. Whole-value assignment goes through set and hits the guard: workoutsData = mergingLoadedEnrichment(into: fetchedWorkouts), uiModel.selectedWorkout = finalWorkout.

So some enrichment writes notified and others didn’t, and the difference came down to the shape of the line that did the writing. Two lines that mean the same thing to a reader meant different things to Observation.

onChange(of:) was blind for a simpler reason. It compares old and new with == too. Any .onChange(of: uiModel.selectedWorkout) in the app was, in effect, .onChange(of: uiModel.selectedWorkout?.id) already. Nobody wrote it that way. Nobody had to.

Purify — A Hand-Written == That’s Sufficient, Not Exhaustive

The textbook fix is to delete the hand-written == and let the compiler synthesize one. That wasn’t available here. CLLocationCoordinate2D isn’t Equatable, and a tuple can’t conform to Equatable, so an optional tuple has no == to synthesize with. Even if synthesis worked, it would compare two route arrays element by element on every diff, and workout routes are long.

So the new == is still hand-written. It’s just honest now:

// Route arrays compare by count only: this runs on every SwiftUI onChange diff of workoutsData.
static func == (lhs: WorkoutData, rhs: WorkoutData) -> Bool {
    lhs.id == rhs.id &&
        lhs.routeLocations.count == rhs.routeLocations.count &&
        lhs.routeCoordinates.count == rhs.routeCoordinates.count &&
        lhs.cityName == rhs.cityName &&
        sameHeartRateSummary(lhs.heartRateData, rhs.heartRateData) &&
        lhs.cachedElevationStatistics == rhs.cachedElevationStatistics &&
        lhs.detailedHeartRateData == rhs.detailedHeartRateData &&
        lhs.detailedPaceData == rhs.detailedPaceData &&
        lhs.detailedElevationData == rhs.detailedElevationData &&
        lhs.detailedCadenceData == rhs.detailedCadenceData &&
        lhs.detailedRunningPowerData == rhs.detailedRunningPowerData &&
        lhs.detailedVerticalOscillationData == rhs.detailedVerticalOscillationData &&
        lhs.detailedGAPData == rhs.detailedGAPData &&
        lhs.detailedPowerEffortData == rhs.detailedPowerEffortData
}

private static func sameHeartRateSummary(
    _ lhs: (low: Double, avg: Double, high: Double)?,
    _ rhs: (low: Double, avg: Double, high: Double)?
) -> Bool {
    switch (lhs, rhs) {
    case (nil, nil): true
    case (let lhs?, let rhs?): lhs == rhs
    default: false
    }
}

The goal isn’t an exhaustive ==. It’s a sufficient one. == has to change whenever anything an observer cares about changes. It doesn’t have to prove two values are identical down to the last coordinate.

Route counts work as a change signal because of how routes arrive in this app: whole. A workout has zero points, and then it has all of them. The trade-off is real, though. Count-only is deliberate (the comment says so), and it has a blind spot: if a route were ever replaced by a different one with the same number of points, this == wouldn’t see it. That’s fine for how the app loads data today. If that ever changes, this is the first place I’d look.

The heat-map series cost almost nothing here, because each detailed* type already had its own cheap ==. The heart-rate summary needs the little helper because the stdlib compares tuples of Double just fine, but optional tuples get no == at all.

The Test That Guarded the Bug

A hand-written == over thirteen enrichment fields has an obvious failure mode: someone adds one more and forgets it. So the new test runs once per enrichment field:

@Test("Each enrichment field on its own makes same-id copies unequal", arguments: EnrichedField.allCases)
func equalitySeesEachEnrichmentField(field: EnrichedField) {
    let basic = WorkoutFixtures.makeWorkoutData()

    #expect(basic != field.applied(to: basic))
}

EnrichedField is a CaseIterable enum with one case per enrichment field. applied(to:) returns a copy with only that field set. Add a field to the model and a case to the enum, and the test tells you whether == noticed.

My favorite diff in the commit is smaller. An existing test had been asserting the bug as a feature:

// Should still be equal (equality based on ID only)
#expect(workoutData1 == workoutData2)

It now reads:

// Loaded enrichment makes same-id copies distinguishable
#expect(workoutData1 != workoutData2)

The suite wasn’t failing to catch the bug. It was defending it. A green test only tells you the code does what the test says. It doesn’t tell you the test is saying the right thing.

Confusion — Identity and Equality Answer Different Questions

Making == honest broke every caller that had been using it to ask a different question.

An id-only == quietly carries a second contract. Callers read a == b as “is this the same workout?” and for a long time the answer was right. Once == started meaning “does this look the same?”, every one of those callers changed behavior. The commit lists them.

The iPhone and iPad selection observers start a load when the selection changes. With a strict ==, every enrichment write to the selected copy would look like a new selection, so they’d re-trigger loadWorkoutData, and on iPad they’d also un-minimize the detail panel. The iPhone version shows the pattern:

// before
.onChange(of: uiModel.selectedWorkout) { _, newWorkout in
    handleWorkoutSelectionChange(newWorkout)
}

// after
.onChange(of: uiModel.selectedWorkout?.id) { _, _ in
    handleWorkoutSelectionChange(uiModel.selectedWorkout)
}

The trigger is the id. The payload is read fresh from the model. Those are two separate decisions, and the old code had fused them.

The iPad map-centering observer and WorkoutUIModel’s camera didSet should recenter only when the selection actually changes:

var selectedWorkout: WorkoutData? {
    didSet {
        if selectedWorkout?.id != oldValue?.id {   // was: selectedWorkout != oldValue
            updateCameraForWorkoutSelection()
        }
    }
}

The subtle one was comparison. ComparisonState keeps a Set<WorkoutData>. Hashing is still id-only while == is stricter. That pairing is still legal, because values that compare equal share an id and therefore a hash. But contains finds the right bucket and then asks ==, so it now needs the same value, not the same workout. A copy of a selected workout that picked up its city name afterward wouldn’t register as selected, and couldn’t be deselected. So membership asks about identity explicitly:

func isSelected(_ workout: WorkoutData) -> Bool {
    selectedWorkouts.contains { $0.id == workout.id }
}

private func deselect(_ workout: WorkoutData) {
    guard let selected = selectedWorkouts.first(where: { $0.id == workout.id }) else { return }
    selectedWorkouts.remove(selected)
}

deselect removes the element that’s actually stored, found by id, not the argument it was handed. The test for it is named exactly for the case: “A city-enriched copy of a selected workout is recognised as selected and toggles it off.” It selects a workout, builds the same workout with cityName = "Portland", checks that isSelected sees it, and toggles it off.

Identifiable and id answer “is this the same thing?” == answers “is this still the same?” When one type answers both with the same function, you can’t fix one answer without breaking every caller that wanted the other. When you make == honest, go find everyone who was asking about identity and have them ask .id directly.

Shadows Follow — Triggers That Fire on Every Enrichment Write

With enrichment visible, two cameras started moving too often. That’s the other direction: not a key too small to notice a change, but a key too big to tell noise from intent.

The all-routes camera re-fits the map around every workout. Its update function did that on every call:

func updateWorkouts(_ workouts: [WorkoutData]) {
    allWorkouts = workouts
    if showAllRoutes {
        updateCameraForAllRoutes()
    }
}

The caller is .onChange(of: viewModel?.workoutsData) in MainWorkoutView. Under the id-only ==, that observer never fired on enrichment. Under the honest one, every enrichment merge fires it, so with all routes showing, a city name landing on one workout would re-frame the whole map. The fix asks whether the set of workouts changed, which is the only thing a fit-everything camera cares about:

func updateWorkouts(_ workouts: [WorkoutData]) {
    let membershipChanged = allWorkouts.map(\.id) != workouts.map(\.id)
    allWorkouts = workouts
    if showAllRoutes && membershipChanged {
        updateCameraForAllRoutes()
    }
}

The test sets mapCameraPosition to a sentinel, .userLocation(fallback: .automatic), calls updateWorkouts with enriched copies of the same workouts, and expects the sentinel to still be there. A companion test checks that a real membership change does re-fit. A no-op is only worth something if you’ve also proven the op still happens.

The iPhone camera lives in SimplifiedEnhancedMapCameraModifier, a ViewModifier. Here’s the part that makes this whole post hang together:

.onChange(of: workout) { oldWorkout, newWorkout in
    if oldWorkout?.id != newWorkout?.id {
        camera.resetForNewWorkout()
    }
    updateCamera()
}

Look at what’s already there. The closure checks id before resetting. The code already knew identity mattered. But updateCamera() runs unconditionally, on every change of workout. Before the == fix, that was harmless, and only by accident: the id-only == meant “every change of workout” was really “every change of selection.” The loose == had been hiding the broad trigger. The moment == got honest, every city name, heart-rate summary, and heat-map series became a reason to refocus the camera.

Fixing bug one surfaced bug two.

The camera cares about two things: which workout it’s showing, and whether that workout’s route has arrived. So the key names exactly those:

.onChange(of: focusKey) { oldKey, newKey in
    if oldKey.workoutID != newKey.workoutID {
        camera.resetForNewWorkout()
    }
    updateCamera()
}

private struct FocusKey: Equatable {
    let workoutID: UUID?
    let routePointCount: Int
}

private var focusKey: FocusKey {
    FocusKey(workoutID: workout?.id, routePointCount: workout?.routeCoordinates.count ?? 0)
}

FocusKey is the same trade == made, for the same reason: routes arrive whole, so a count is enough to mean “the route showed up.” But now it’s scoped to one observer instead of baked into the model. The view model already had a smaller version of this pattern, .onChange(of: viewModel.selectedWorkoutRouteCount(for: uiModel.selectedWorkout?.id)), which projects an Int instead of observing a model. FocusKey is that idea with a name and a second field.

All Within My Hands — Key Each Observer on the Effect It Drives

Both bugs are the same bug. The observer’s key didn’t match the effect it drives. In the first, the key was too small, so real changes were ignored. In the second, it was too big, so noise looked like intent.

That splits cleanly into two kinds of observers.

Rendering and Observation need a == that changes whenever anything shown changes. That’s the model’s job. It doesn’t have to be exhaustive, but it has to be sufficient, and with @Observable there’s no second chance: a write that == calls equal never notifies anyone.

Side effects should key on the smallest value that means intent changed. That covers onChange, task(id:), animation(_:value:), camera moves, and loads. Usually it’s an id, a list of ids, or a small named key struct like FocusKey. Usually it’s not a model.

When the camera starts jumping, the tempting fix is to loosen the model’s == until the noise goes away. Don’t. That just recreates bug one. And with Observation it’s worse than it used to be, because the stale data won’t even look stale all the time. It’ll show up on the next unrelated re-render, then refuse to reproduce when you go looking for it. A model’s == has one job, and that job is being true. When one observer needs a narrower view, give that observer its own key.

The End of the Line — A Pre-Ship Checklist

Everything on this list is something these three commits actually touched.

Find every hand-written == in your models:

grep -rn 'static func ==' --include='*.swift' .

For each one, ask whether it changes when anything a view shows changes. An id-only == on a type that gets mutated after creation is bug one, waiting for a whole-value assignment.

Find every .onChange(of:) that observes a whole model. Ask what should actually trigger it. If the answer is “a new selection,” key on the id. If the answer is two things, name them in a key struct.

Find every Set or contains on a type with a custom ==. If a caller means “the same workout,” it has to say .id, because once == is honest, contains won’t say it for you.

Read your tests for assertions that two differently loaded copies of the same thing are equal. Mine had one, with a comment explaining why that was fine.

The == I shipped is still hand-written, still compares routes by count, and still has a blind spot I can name. It tells observers the truth about the data they draw. The cameras only move when the thing they point at changes. I’ll take that trade.

Keep shipping.

Apple announced the iPhone Duo on September 9 — pre-orders October 16, in stores October 23, $1,999 to get in the door, riding on iOS 27.1. The closest I’ve gotten is the Duo simulator that landed with Xcode 27.1 beta on September 18: a 434-point outer display, a 669-point inner one, and no way to fold between them.

VinylCrate 4.1, the next release, supports Apple’s first foldable anyway. The inner display gets the sidebar layout, the grids know where the hinge is, and the camera follows whichever display you’re looking at. Getting there meant ripping out the SwiftUI layout model I taught on this blog six months ago. So that’s where this starts — with me eating a little crow.

Holier Than Thou — Correcting My March Adaptive Layout Post

In March I wrote a post about adaptive SwiftUI layout built around a five-case enum. Trimmed:

enum LayoutEnvironment {
    case iPhonePortrait
    case iPhoneLandscape
    case iPadFullscreen
    case iPadSplitView
    case iPadSlideOver

    var isIPad: Bool {
        switch self {
        case .iPadFullscreen, .iPadSplitView, .iPadSlideOver: return true
        default: return false
        }
    }
}

That post’s closing section was titled “Design for Context, Not Device.” Read the case names again. Every one of them is a device. I told you to stop asking “is this an iPad?” and then handed you an enum whose most important property was isIPad.

A reread turns up worse. .iPadSlideOver is declared, but the initializer in that post never returns it, so nothing ever produced that case. And the checklist at the bottom told you to test Slide Over, “which is narrower than any iPhone,” while the app the post was about was stranding people in Slide Over. More on that in a minute.

And the version I published was the flattering one. The enum actually in the repo skipped the size-class reasoning and went straight to the hardware:

init(horizontalSizeClass: UserInterfaceSizeClass?, verticalSizeClass: UserInterfaceSizeClass?) {
    let isIPad = UIDevice.current.userInterfaceIdiom == .pad

    switch (isIPad, horizontalSizeClass, verticalSizeClass) {
    case (true, .regular, .regular):
        self = .iPadLandscape
    case (true, .compact, .regular):
        // iPad with compact horizontal size class means split view
        self = .iPadSplitView
    case (true, _, _):
        self = .iPadPortrait
    case (false, _, .compact):
        self = .iPhoneLandscape
    default:
        self = .iPhonePortrait
    }
}

The instinct in that post was right. Size classes alone are too coarse, and one branch at the root beats forty scattered through the views. The model was wrong, in both the published version and the shipped one. Each answered “what device is this?” with extra steps, and that question stops having an answer once one device can be two sizes. PR #5 deleted the shipped one. If you built something from the published one, consider this the correction.

The God That Failed — Why userInterfaceIdiom Breaks on the iPhone Duo

Unfolded, the Duo’s inner display is 669 by 951 points and reports regular width and regular height, the same pair a full-screen iPad reports. userInterfaceIdiom is .phone on both displays.

VinylCrate’s old classifier, the init above, asked the idiom first, and its phone branch never looked at the horizontal size class. On the inner display it would have drawn the phone layout: a two-column grid under a bottom tab bar, on a screen as wide as a small iPad, while a fully built NavigationSplitView sat unused in the same file.

Nothing about that fails loudly — no crash, no log line, and every test keyed to device names stays green. It just draws the wrong app.

The idiom was never a good layout signal, even before the Duo. iPad Slide Over reports .pad at roughly 320 points. An iPad app on an Apple silicon Mac reports .pad too. The Duo is just the case you can’t talk your way around.

So the idiom is gone. userInterfaceIdiom, isIPad, and isIPhone don’t appear anywhere in the app target now, and the platform doc says to keep it that way. Every layout question the app asks comes down to three things: the width class, the width of this container, and whether there’s a hinge.

Escape — The iPad Slide Over Dead End

Here’s the gut punch: the Duo forced the rewrite, and the rewrite turned up a bug I’d already shipped.

The old model classified iPad Slide Over as .iPadSplitView, and isIPad sent every iPad case to the sidebar layout. So a pane about 320 points wide rendered a NavigationSplitView, and at compact width a split view collapses to its detail column. In that branch the sidebar was the only way to switch tabs, and there was no tab bar. Anyone who slid VinylCrate over was stuck on whichever tab they had open. The only way out was to close the app.

The fix isn’t a Slide Over special case. Nothing in the new code even mentions Slide Over — a narrow pane is compact, compact gets tabs, done.

It wasn’t free, and the changelog says so. Dragging an album onto a crate used to work in Slide Over; now narrow panes get the phone layout and its tap-to-pick crate sheet. I’d make that trade again every time. Still a trade.

Fixxxer — Column Counts From Measured Width

LayoutEnvironment kept its name. It’s a struct now, trimmed here to the parts that matter:

nonisolated struct LayoutEnvironment: Equatable, Sendable {
    enum WidthClass: Equatable, Sendable {
        case compact
        case regular
    }

    struct Division: Equatable, Sendable {
        let thickness: CGFloat
    }

    let widthClass: WidthClass
    let containerWidth: CGFloat
    let division: Division?

    var usesSidebarNavigation: Bool {
        widthClass == .regular
    }

    static func widthClass(
        horizontal: UserInterfaceSizeClass?,
        vertical: UserInterfaceSizeClass?
    ) -> WidthClass {
        horizontal == .regular && vertical != .compact ? .regular : .compact
    }
}

division is the hinge, and it gets its own section below. widthClass(horizontal:vertical:) is the one place the root reads size classes, and it adds one rule: regular width with compact height gets demoted to compact. A Max iPhone in landscape is wide enough for a sidebar and too short to open one.

It’s easy to overcorrect here, so to be clear: the root navigation decision still comes from size classes. Size classes were never the problem. A size class is the system telling you how much room you have; isIPad is you guessing at the room from the hardware. Only one of those stays right when the hardware folds.

Grids are where the numbers come in. Each grid has a role (the collection, the art wall, the insights summary), and each role has a target tile width and a column range. The column count is a pure function of measured width:

private static func columnCount(
    for width: CGFloat,
    metrics: ResponsiveGridMetrics,
    spacing: CGFloat,
    environment: LayoutEnvironment
) -> Int {
    let range = metrics.columnRange
    guard width.isFinite, width > 0 else { return range.lowerBound }

    let ideal = min((width + spacing) / (metrics.targetTileWidth + spacing), CGFloat(range.upperBound))
    let clamped = max(Int(ideal.rounded()), range.lowerBound)
    guard environment.prefersEvenColumnCount, !clamped.isMultiple(of: 2) else { return clamped }

    if clamped + 1 <= range.upperBound { return clamped + 1 }
    if clamped - 1 >= range.lowerBound { return clamped - 1 }
    return clamped
}

The collection grid aims for 170-point tiles, two to six columns. The art wall aims for 74, four to twelve, with no spacing at all. There’s no device name anywhere in that function. The Duo’s 434-point outer display gets two columns because two 170-point tiles fit in 434 points — nobody had to teach the code what a Duo is. And the same math quietly fixed iPhone landscape: the collection grid used to sit at three columns sideways, and now it fits four or five depending on the phone.

The width a grid measures has to be its own. These grids live in split-view detail panes and inside sheets, which are both much narrower than the window, so ResponsiveGrid measures itself:

struct ResponsiveGrid<Content: View>: View {
    let role: ResponsiveGridRole
    @ViewBuilder var content: () -> Content

    var body: some View {
        LazyVGrid(columns: configuration.gridItems, spacing: configuration.spacing) {
            content()
        }
        .onGeometryChange(for: CGFloat.self) { proxy in
            // Whole points only: this width feeds ~30 views and would otherwise thrash on
            // every sub-pixel step of an interactive resize.
            proxy.size.width.rounded()
        } action: { width in
            measuredWidth = width
        }
    }

    @Environment(\.layoutEnvironment) private var layoutEnvironment
    @State private var measuredWidth: CGFloat?

    private var configuration: ResponsiveGridConfiguration {
        ResponsiveGridConfiguration.resolve(
            role: role,
            width: measuredWidth ?? layoutEnvironment.containerWidth,
            environment: layoutEnvironment
        )
    }
}

That rounding is load-bearing. onGeometryChange fires whenever the value changes, and an interactive resize nudges the width by fractions of a point every frame. Round to whole points and none of that churn reaches the thirty-odd views downstream.

It also has a flaw. Until the first geometry callback, the grid seeds from layoutEnvironment.containerWidth, and that’s the root’s width, not the pane’s.

In the sidebar layout the root measures the whole window while the grid lives in the narrower detail pane, so the first frame can come out one column too many and then snap back. I kept it on purpose. Without the seed, the first frame sits at the column floor. Removing it also means removing the root geometry reader, which is a design change that deserves its own review. For now it’s parked as a documented follow-up. I can live with one frame of wrong.

The root itself is split into two views:

struct AdaptiveRootView: View {
    let container: ViewModelContainer
    let oauthService: OAuthService

    var body: some View {
        AdaptiveRootContent(container: container, oauthService: oauthService)
            .withAdaptiveLayout()
    }
}

// A view cannot read an environment value it sets in the same body — hence the split.
private struct AdaptiveRootContent: View {
    @Environment(\.layoutEnvironment) private var layoutEnvironment

    var body: some View {
        Group {
            if layoutEnvironment.usesSidebarNavigation {
                sidebarLayout
            } else {
                tabBarLayout
            }
        }
        // The system animates the fold itself; a second cross-fade underneath reads as a glitch.
        .transaction(value: layoutEnvironment.usesSidebarNavigation) { $0.animation = nil }
    }
}

The first comment is a SwiftUI rule that bites everybody exactly once: an environment value you set applies to what you wrap, not to the body doing the setting. The second is a judgment call on a transition I’ve reasoned through but never actually watched on hardware. When the phone opens, the system is already animating — cross-fade the tab bar into the sidebar underneath it and you’ve got two animations fighting over one gesture.

Broken, Beat & Scarred — Reading the Hinge From Reserved Regions

The inner display has a hinge down the middle, and it doesn’t show up as a safe-area inset. In iOS 27.1, UIKit describes it as a reserved region: reservedRegions(kind: .division, options:), called on a view. SwiftUI has no equivalent. That’s the half of the Duo API Xcode 27.1 left out of SwiftUI. The hinge is there — you just have to go through UIKit and a representable to reach it.

VinylCrate’s probe is a UIView that ignores touches, placed in the root’s .background by the same modifier that publishes the layout environment:

@available(iOS 27.1, *)
private final class DivisionProbeView: UIView {
    var onChange: ((LayoutEnvironment.Division) -> Void)?

    // Reserved regions have no change notification, so layout is the only hook.
    override func layoutSubviews() {
        super.layoutSubviews()
        // A windowless or empty pass queries nothing, and a hinge must never be retracted.
        guard window != nil, !bounds.isEmpty else { return }

        if let division = currentDivision() {
            publish(division)
        }
    }

    private var published: LayoutEnvironment.Division?

    // `.includeInactive` makes the hinge a property of the device, not the pose: columns cannot reflow mid-fold.
    private func currentDivision() -> LayoutEnvironment.Division? {
        guard let region = reservedRegions(kind: .division, options: .includeInactive).first else {
            return nil
        }
        return ReservedRegionSupport.division(regionFrame: region.frame)
    }

    // Deferred by a hop: this runs inside a UIKit layout pass and the handler writes SwiftUI state.
    private func publish(_ division: LayoutEnvironment.Division) {
        guard published != division else { return }
        published = division
        let handler = onChange
        Task { @MainActor in handler?(division) }
    }
}

There are four decisions packed into that little view.

layoutSubviews, because there’s nothing else to hook. Reserved regions have no notification and no trait. If the region changes, the view lays out, and that’s when you ask.

.includeInactive makes the hinge a property of the device instead of the pose. Without it, the region would come and go as the phone opens and closes, and every grid would reflow while the fold was still moving. With it, the app decides the column count once and it holds while the hardware moves.

A hinge is never retracted. If currentDivision() returns nil, nothing gets published. Once the app knows there’s a hinge, it stays known — same stability argument, other direction.

The publish is deferred through a Task { @MainActor in } hop. This code runs inside a UIKit layout pass, and the handler writes SwiftUI @State. Writing state from inside someone else’s layout pass is how you end up with re-entrant layout.

ReservedRegionSupport.division(regionFrame:) turns the frame into a thickness. It only counts the minor dimension, because the strip’s orientation follows the pose. It rounds to whole points and caps the result at 24, so a malformed region can’t collapse a grid. It also rejects CGRect.infinite, which reports greatestFiniteMagnitude extents that an isFinite check alone won’t catch. This is the app’s only #available(iOS 27.1, *) gate in the layout system, and a custom SwiftLint rule, single_reserved_region_gate, fails the build if reservedRegions( shows up anywhere else.

What the grids do with the hinge is small on purpose. A hinged display gets an even column count, so the hinge never runs down the middle of an album cover. The gutters also get a bonus equal to the hinge’s thickness. In the Duo’s 621-point inner pane, a 12-point hinge brings the collection grid’s spacing to 32. That works out to about 3.2 columns, which rounds to three and then bumps to four.

The art wall opts out of the gutter bonus:

case .artWall:
    // Zero spacing is the point: the wall reads as one continuous surface, not a grid
    // of cards, so the hinge gutter bonus does not apply here.

It still gets the even count — just not the wider gutter.

The Judas Kiss — Testing Widths Instead of Device Names

The old art wall test was ArtWallGridConfigurationTests, and its expected values were a table of device names:

(.iPhonePortrait, 5), (.iPhoneLandscape, 8), (.iPadPortrait, 8), (.iPadLandscape, 10), (.iPadSplitView, 6)

It was green, and it had nothing to say about a device it had never heard of. You can’t add the Duo to that table without first deciding which existing case the Duo “is,” and making that decision was the bug. A test keyed to device names can only confirm that the classifier agrees with itself.

The replacement is a Swift Testing suite, ResponsiveGridConfigurationTests. It keeps a few anchors, because a person should be able to read “this width gets this many columns” and agree. The device names moved into comments, where they describe the width instead of deciding the result:

let anchors = [
    Anchor(width: 361, widthClass: .compact, division: nil, expected: 2), // iPhone 17 Pro portrait
    Anchor(width: 434, widthClass: .compact, division: nil, expected: 2), // Duo outer display
    // Duo inner display, detail pane — hinged, so the odd count rounds up to even
    Anchor(width: 621, widthClass: .regular, division: Self.hinge, expected: 4),
    Anchor(width: 506, widthClass: .regular, division: nil, expected: 3), // iPad 11" portrait pane
    Anchor(width: 890, widthClass: .regular, division: nil, expected: 5) // iPad 13" landscape pane
]

Most of the checking happens in the sweeps. They cover every width from 280 to 1400 points, in both width classes, with and without a hinge, and check properties that have to hold everywhere:

@Test("a hinged display gets an even column count")
func hingedDisplaysGetEvenColumns() {
    for environment in Self.sweep(division: Self.hinge) {
        for role in [ResponsiveGridRole.collection, .artWall] {
            let config = Self.configuration(role, in: environment)
            #expect(config.columns.isMultiple(of: 2), "\(role) at \(environment.containerWidth)pt")
        }
    }
}

The other sweeps check that every role stays inside its column range, that the art wall is denser than the card grid at every width, that art wall tiles never drop below the 44-point tap target, and that the wall keeps zero gutters with or without a hinge. None of them names a device, which is exactly why they’ll still mean something when Apple ships the next weird rectangle.

Degenerate widths get their own test, and its doc comment makes the whole case:

/// `Int(CGFloat.nan)` traps, and a zero-size first layout pass is routine.
@Test("degenerate widths resolve without trapping")
func degenerateWidthsAreSafe() {
    let environment = LayoutEnvironment(widthClass: .regular, containerWidth: 0)

    for role in Self.allRoles {
        for width in [CGFloat(0), -1, -640, .nan, .infinity, -.infinity] {
            let config = ResponsiveGridConfiguration.resolve(role: role, width: width, environment: environment)
            #expect(config.columns == role.metrics.columnRange.lowerBound, "\(role) at width \(width)")
        }
    }
}

That’s why columnCount opens with guard width.isFinite, width > 0. A grid that measures itself sees zero before it sees anything real, and Int(ideal.rounded()) on a NaN crashes the app. Not a weird layout — a crash.

Two smaller suites cover the rest. LayoutEnvironmentTests maps each size-class pair to a root navigation choice, and one of those pairs is (nil, nil), the state where nothing has been published yet. ReservedRegionSupportTests feeds the hinge parser book, tabletop, and near-square poses. It also feeds it empty frames, infinite frames, a negative extent, and a region far too thick to be a hinge, and pins down what each one resolves to.

Room of Mirrors — A Camera That Follows the Display

Layout wasn’t the only place where “the device” turned out to be the wrong unit. On a foldable, “back camera” changes meaning when the phone opens. The lens facing away from you on the outer display isn’t the one facing away from you on the inner display.

Dead Wax Scan reads the etchings in a record’s runout groove with the same on-device OCR pipeline as the sleeve scanner, and it has to keep pointing at the record through a fold. iOS 27.1 adds AVCaptureDeviceDirectionCoordinator for this. You give it the preview’s view, and it reports which cameras face away from the display that view is on:

coordinator = AVCaptureDeviceDirectionCoordinator(
    view: view,
    deviceTypes: CaptureDirection.preferredDeviceTypes,
    changeHandler: { [weak self] map in
        self?.handle(map.backwardFacingDeviceDescriptors.map(CaptureDeviceDescription.init))
    }
)

Two details will bite you. First, deviceDirections is empty until the first callback fires, so nothing can be resolved during setup. Capture starts on a fixed rear camera (dual-wide, then wide-angle) and swaps when a callback names a different one. Second, a swap that can’t complete leaves the previous input in place. replaceInput reports .swapped, .restoredPrevious, or .lostInput, because a fold is exactly when the old input might stop working too. Only .lostInput moves the scanner to .unavailable. A coordinator that isn’t available never means there’s no camera.

My favorite bug of the whole project lived here. The preview view connects to the camera controller through CameraPreviewHost, and attachPreviewView(_:) and detachPreviewView() used to have no-op defaults in a protocol extension. When My Photos got its own in-app camera, its controller inherited those defaults without anyone noticing. It compiled, it ran, and on a real Duo, folding the phone mid-capture would have left that viewfinder pointed at the user. Nobody saw it happen — there was nothing to fold. It surfaced the old-fashioned way, by reading the code.

The fix was deleting the defaults:

@MainActor
protocol CameraPreviewHost: AnyObject {
    var session: AVCaptureSession { get }
    func attachPreviewLayer(_ layer: AVCaptureVideoPreviewLayer)
    // Deliberately undefaulted: a no-op default silently denies a conformer the fold-aware
    // camera swap, which is how My Photos shipped pointing at the user after a fold.
    func attachPreviewView(_ view: UIView)
    func detachPreviewView()
    func previewLayoutDidChange()
    func focus(atDevicePoint point: CGPoint)
}

Now, leaving out either hook is a build error. A default in a protocol extension is a decision made for every future conformer, and a no-op is the quietest decision there is. Both camera screens now share a CaptureSessionRunner that owns the session, interruption handling, and the fold-aware swap, so the next fix only has to land in one place.

The outer display gets a job too. While you scan on the inner display, the outer one shows the side being read, the running etching count, and the last line found. It’s built from CameraCaptureAccessory (27.1) inside sceneAccessory (27.0), and the gate is 27.1 because the accessory is the only content. A 27.0 gate would register an accessory that draws nothing. It also shows no preview frames on purpose: the scan’s guide ring maps to OCR under one preview gravity, and a second preview surface would split that mapping in two.

Dream No More — The Code That Has Never Run

Now the uncomfortable part.

The PR #5 description says it plainly: “All iOS 27.1 paths — reserved regions, direction coordinator, outer-display accessory — have never executed, because no simulator fold control exists.”

The Xcode 27.1 simulator gives you a Duo, but you can’t fold it. So the hinge probe, the direction coordinator, and the outer-display accessory have compiled, passed review, and been reasoned through carefully, and none of them has ever run against a fold. The tests cover everything around them: the thickness parser, the column math, the camera preference order, the swap bookkeeping. Those are the pure parts. The places where the system hands me something are exactly the parts I can’t run.

There’s a reason this post borrowed Through the Never for its title — a chunk of this code lives past the edge of anything I’ve been able to watch run. That’s what “before the device exists” means in practice. I didn’t find an abstraction that makes hardware irrelevant. I have a set of pure functions I trust, wrapped around a few system calls I’ve read the headers for and never seen fire. The repo’s docs have a device QA checklist sitting there, waiting on real hardware.

I’m comfortable shipping it this way because every 27.1 path fails toward behavior that’s already tested. If no hinge is ever published, there’s no even-column rule and no gutter bonus, and you get the same grids that already work on every iPad. If the direction map stays empty, the camera stays on the lens it started with. If the accessory never becomes available, the outer display doesn’t show it. In each case, the worst outcome is the app I’d have shipped without that code.

That’s the rule I’d hand anyone writing code they can’t run: when the untested path fails, make it fail into the tested one.

Creeping Death — A Checklist Before October 23

You can do all of this today with Xcode 27.1 beta and no hardware.

Find every device question:

grep -rnE 'userInterfaceIdiom|isIPad|isIPhone' --include='*.swift' .

Any hit that feeds a layout decision is a bug on the Duo’s inner display, which reports .phone and is as wide as an iPad. Replace it with a width class, a measured width, or a hinge check.

Put your iPad app in Slide Over and try to change tabs. If your regular-width branch keys off the idiom, a 320-point pane gets a split view that collapses to its detail column, and your only navigation disappears with the sidebar.

Make grids measure their own container with onGeometryChange, rounded to whole points. The window’s width is wrong inside a split-view detail pane, and it’s wrong inside a sheet.

Read the hinge from reservedRegions(kind: .division, options: .includeInactive) behind a single #available(iOS 27.1, *) gate. Do it in a UIViewRepresentable, from layoutSubviews, and publish the result on a deferred hop. Then decide what a hinge means for your grids. An even column count is a good default.

Replace device-named test tables with widths and properties. Keep a few labeled anchors for the humans, sweep everything else, and include NaN and zero.

If your app uses the camera, open a capture flow on the outer display and work out what “back” means once the phone opens. While you’re in there, look for protocol extension defaults on anything the camera depends on.

October 23 is when I find out how much of this I got right. Until then, the app knows more about the Duo than I do — and everything it knows, it learned by measuring.

Keep shipping.

Someone asked what I’d been building, so I pulled up VinylCrate on the App Store — with my region still flipped to Spain from an hour earlier, when I’d been poking at a price tier. The screenshots loaded. Framed, captioned, nicely composed, and every last one of them in English.

The Spanish translation was fine. It had been fine for weeks. What had broken was the screenshot pipeline: it never applied the locale at all, the app quietly fell back to its development region, and the images that came out the other end looked completely correct to anybody who wasn’t reading them.

That’s the failure mode I want to talk about — partly because it’s a nasty one on its own, and partly because it went on to beat me twice more before I was finished, once in a way I’m fairly sure I’d never have caught by looking.

Sad but True — Why a Wrong-Language Screenshot Looks Right

Here’s the thing about a screenshot that renders in the wrong language: it doesn’t look broken. It looks like a screenshot.

Nothing about it trips a check. No crash, no red diff, no missing-asset placeholder, not even a Localizable.strings key leaking through as screenshot.caption.library to give the game away. A wrong-language screenshot is a correct rendering of the wrong thing — every pixel doing its job, nav bar aligned, type fitting the space it was given. The only signal is semantic, which means the only detector is somebody who reads that language, looking at the image at full size, at the exact moment it matters.

Now count them. VinylCrate’s 4.0 set is eight panels, Apple wants a 6.9-inch iPhone set and a 13-inch iPad set, and we ship six languages — en es fr de ja zh-Hans. That’s 8 × 2 × 6 = 96 images, and App Store Connect hands them back to you as a scrollable strip of thumbnails maybe 90 points wide. You’re not reading kanji at 90 points. You’re definitely not telling Spanish from English at 90 points, because at that size both of them are just “some Latin script in roughly the right place.”

The scripts that are obviously different are the ones you’d catch anyway. Japanese, Simplified Chinese — one glance and you know. It’s German and French and Spanish that slip past, because they share an alphabet with your development region and a decent chunk of their proper nouns. The locales most likely to break silently are the ones you’re least equipped to notice, which is a fun property for a bug to have.

So manual review here isn’t just slow, it’s the wrong instrument. Ninety-six images isn’t too many to look at; I’ve reviewed worse. The problem is that “look at it” can’t answer the question. The question is a comparison: is the German panel byte-identical to the English one? If the answer is ever yes, something upstream lied to you.

That’s trivial for a machine and close to impossible for a person, so I stopped reviewing and wrote the check instead. It’s 146 lines of bash, the interesting part is shasum -a 256, and it has since caught two real bugs.

Master of Puppets — Seeding an App That Can’t Drift

A screenshot harness is a determinism problem wearing a UI-testing costume. Everything you’re about to hash has to be a pure function of the inputs, or the hashing is worthless. Two panels that differ because a relative timestamp ticked over are two panels whose hashes tell you nothing.

VinylCrate’s fixture is a ScreenshotSeed enum that builds an in-memory SwiftData container and populates it:

static func makeInMemoryContainer() -> ModelContainer? {
    do {
        let container = try ModelContainer(
            for: SharedModelContainer.schema,
            configurations: [ModelConfiguration(
                schema: SharedModelContainer.schema,
                isStoredInMemoryOnly: true,
                allowsSave: true,
                cloudKitDatabase: .none
            )]
        )
        let context = ModelContext(container)
        try populate(context)
        return container
    } catch {
        logger.error("❌ Screenshot seed container failed: \(error.localizedDescription)")
        assertionFailure("Screenshot seed container failed: \(error)")
        return nil
    }
}

isStoredInMemoryOnly: true and cloudKitDatabase: .none are doing the real work: no store on disk to carry state between runs, and no sync to race with. The seeded library is twelve records (five Metallica, seven Pearl Jam) with fixed prices, fixed favorites, and fixed artwork.

The clock is frozen by construction rather than injected:

static let referenceDate = Date(timeIntervalSince1970: 1_772_500_000)

Every seeded row hangs off that constant. Play events land at referenceDate.addingTimeInterval(-hoursBack * 3600), copy photos at -Double(3 - index) * 3600, the dead wax scan three days back. Anything that renders “2 days ago” renders it the same way every run, because the data is anchored, not the formatter. Photo IDs come from DeterministicUUID.make(namespace:name:) for the same reason.

Two more pieces close the loop. The seed is #if DEBUG-gated so it cannot possibly activate in a release build:

static func isActive(in arguments: [String] = ProcessInfo.processInfo.arguments) -> Bool {
    #if DEBUG
    arguments.contains(launchArgument)
    #else
    false
    #endif
}

And one network call gets stubbed, because Discogs’ /collection/value needs a real OAuth token the seeded launch never obtains and would otherwise 401 into an empty Insights panel:

static let stubCollectionValueTransport: DiscogsClient.Transport = { request in
    guard
        let url = request.url,
        url.path.hasSuffix("/collection/value"),
        let response = HTTPURLResponse(url: url, statusCode: 200, httpVersion: nil, headerFields: nil)
    else {
        return try await URLSession.shared.data(for: request)
    }
    return (stubCollectionValueBody, response)
}

The stubbed figure is deliberately a little above the seed’s $310.45 total invested, so the panel reads as plausible appreciation instead of an arbitrary number. Marketing screenshots have to survive a skeptical reader, not just a hash.

Then there’s the part I did not predict. The launch is --seed-screenshots --disable-tips, and even with an in-memory store and TipKit silenced, one piece of state kept leaking across runs: @AppStorage("importPromptState"). It lives in user defaults, which the in-memory container knows nothing about, and it would present the import sheet on top of a capture in a reused simulator.

The fix is a bigger hammer than I wanted and I’ve made peace with it:

xcrun simctl shutdown "$device" 2>/dev/null || true
xcrun simctl erase "$device"
xcrun simctl boot "$device"
xcrun simctl status_bar "$device" override \
  --time "9:41" --batteryState charged --batteryLevel 100 \
  --cellularBars 4 --wifiBars 3 --dataNetwork wifi

Erase, boot, pin the status bar, twelve times per full run. It costs real minutes and I’d rather spend them than debug a capture that inherited something from the run before it. The status bar override does double duty here. App Store screenshots are supposed to look that way, and a clock left running would change every hash on every run.

Wherever I May Roam — Why -testLanguage Fails and simctl Doesn’t

Now the part that started all of this.

xcodebuild has a -testLanguage flag. It’s right there in the man pages, it’s the obvious tool for the job, and on the Xcode 27 toolchain this project is pinned to (27A5252f), it does not reliably reach the app under test. Read the promise closely: it “overrides the setting for the test action of a scheme in a workspace.” That’s a claim about the scheme’s test action, not about the process your UI test actually launches, and the gap between those two is where six languages go missing. I confirmed it the boring way: ran the capture with -testLanguage ja and got identical English UI out the other end. No warning, no error, exit 0. I haven’t filed feedback on it yet, which I should.

Which is the whole problem in miniature: a flag that silently doesn’t apply, sitting in a pipeline whose output is images nobody reads closely.

What actually works is setting the simulator’s own global domain before the test launches the app:

xcrun simctl spawn "$device" defaults write -g AppleLanguages -array "$lang"
xcrun simctl spawn "$device" defaults write -g AppleLocale -string "$(locale_for "$lang")"

-array "$lang" matters. AppleLanguages is an array; write a bare string into that slot and it isn’t an error, it’s just a value the localization machinery ignores while the bundle quietly resolves to CFBundleDevelopmentRegion. This is the same trap as the old -AppleLanguages es versus -AppleLanguages "(es)" parenthesis gotcha, wearing different clothes.

The language-to-locale mapping is a plain case, and it’s explicit on purpose:

locale_for() {
  case "$1" in
    en) echo "en_US" ;;
    es) echo "es_ES" ;;
    fr) echo "fr_FR" ;;
    de) echo "de_DE" ;;
    ja) echo "ja_JP" ;;
    zh-Hans) echo "zh_Hans_CN" ;;
    *) echo "en_US" ;;
  esac
}

zh-Hans is the structural outlier, the only one using a script subtag, which is why it’s written out by hand rather than derived. A clever "${lang}_$(echo "$lang" | tr '[:lower:]' '[:upper:]')" would produce zh-Hans_ZH-HANS, and you’d find out from a screenshot.

I still pass -testLanguage "$lang" to xcodebuild alongside the defaults write. Belt and suspenders: it costs nothing, and if a future toolchain fixes the flag, the two mechanisms agree rather than fight.

One more trap, and it’s pure paperwork that will waste an afternoon: this project’s build default is iPhone 17 Pro, which is 6.3 inches, which is the wrong size. App Store Connect wants 6.9-inch, 1320 × 2868, and the iPad Pro 13-inch at 2064 × 2752. Apple scales every other size from those two, so the whole matrix is two devices, and both have to be named explicitly:

DEVICES=("iPhone 17 Pro Max" "iPad Pro 13-inch (M5)")

Get that wrong and every image is beautiful, localized, correct, and rejected on upload.

Seek & Destroy — Catching Duplicate Screenshots with shasum

Everything up to here is plumbing. This is the part that actually fixed my problem.

The assertion is one sentence: no two languages may produce a byte-identical panel. Write it down that way and it stops being something a human has to notice and becomes something the script enforces.

assert_language_hashes_distinct() {
  local slug="$1"
  local panel hashfile dup dup_langs lang f
  for panel in "${PANELS[@]}"; do
    hashfile=$(mktemp)
    for lang in "${LANGS[@]}"; do
      f="$OUT/$slug/$lang/panel-$panel.png"
      shasum -a 256 "$f" | awk -v lang="$lang" '{print $1, lang}' >> "$hashfile"
    done
    dup=$(awk '{print $1}' "$hashfile" | sort | uniq -d | head -1)
    if [ -n "$dup" ]; then
      dup_langs=$(awk -v h="$dup" '$1==h {print $2}' "$hashfile" | tr '\n' ' ')
      echo "FAIL $slug panel-$panel: byte-identical across languages: $dup_langs (hash $dup)" >&2
      rm -f "$hashfile"
      exit 1
    fi
    rm -f "$hashfile"
  done
}

That’s a temp file and sort | uniq -d rather than an associative array, because the system bash this script’s shebang resolves to is 3.2.57 and predates declare -A — still what /bin/bash is on macOS, still going to be true next year. Inelegant, but it runs everywhere without me installing anything.

Exact bytes is the right gate here, and the reason matters, because perceptual hashing is the reflexive answer and it’s wrong for this. These images get captured minutes apart, on the same machine, from the same build, with the status bar pinned. There’s no antialiasing drift to absorb, nothing cross-toolchain, no golden image checked in last spring that I’m hoping still matches. In that setting SHA-256 has zero false positives: if two renders are byte-identical they are the same image. A perceptual hash would only buy me a threshold to tune and a new way to be wrong.

So that guard shipped, went green, and was still lying to me.

It compares the same panel number across languages, which makes it structurally blind to a different failure: the wrong screen captured within one language. Which is exactly what was happening. testPanel06MyPhotosGallery was landing on the Dead Wax section instead of the My Photos gallery, producing an image byte-identical to panel-02 — on iPhone, in every language. Every language had the same wrong screen, so the cross-language guard saw six distinct-per-panel hashes and reported success.

The generalization is four lines of different bookkeeping:

assert_panels_pairwise_distinct() {
  local dest="$1"
  local panel hashfile dup dup_panels f
  hashfile=$(mktemp)
  for panel in "${PANELS[@]}"; do
    f="$dest/panel-$panel.png"
    shasum -a 256 "$f" | awk -v panel="$panel" '{print $1, panel}' >> "$hashfile"
  done
  dup=$(awk '{print $1}' "$hashfile" | sort | uniq -d | head -1)
  if [ -n "$dup" ]; then
    dup_panels=$(awk -v h="$dup" '$1==h {print $2}' "$hashfile" | tr '\n' ' ')
    echo "FAIL $dest: panels byte-identical: $dup_panels (hash $dup)" >&2
    rm -f "$hashfile"
    exit 1
  fi
  rm -f "$hashfile"
}

It’s the same primitive rotated ninety degrees. One hashes a panel across languages, the other hashes a language’s panels against each other, and the failures they catch don’t overlap at all. Neither one subsumes the other, which took me an embarrassing minute to be sure of.

When you write a duplicate check, ask what axis it’s blind to. A guard that compares along one dimension of a matrix will sail straight past a bug that varies along the other, and it’ll print ok while it does.

The Thing That Should Not Be — Guards That Test Themselves

A guard that has never fired is a guard you’re trusting on faith. Mine were written to catch a bug that was already fixed, so a normal run proves nothing about them — a for loop with a typo in the path would also sail through without failing. It’s the same discipline as writing a test that fails first, just applied to a shell script instead.

So both guards have a dispatch mode whose entire job is to fail:

if [ "${1:-}" = "--verify-hash-guard" ]; then
  assert_language_hashes_distinct "$2"
  echo "guard did not fire (unexpected)"
  exit 1
fi

if [ "${1:-}" = "--verify-panel-guard" ]; then
  assert_panels_pairwise_distinct "$2"
  echo "guard did not fire (unexpected)"
  exit 1
fi

Follow the control flow there. If the guard fires it prints FAIL and exits 1 from inside the function, so the echo never runs. If the guard doesn’t fire, control falls through to a line that says so and exits 1 anyway. Nothing in either branch can exit 0. You point it at deliberately corrupted input and you get a failure either way — the only question is which message comes back, and that’s the whole design.

Verifying the language guard meant copying an en panel over its ja counterpart, running --verify-hash-guard, checking that the FAIL line named both languages, and putting the file back. The panel guard I got to verify twice: once by duplicating panel-04 over panel-07 in a known-clean capture, and once against the real pre-fix iPhone/en capture that was still sitting on disk, which correctly flagged panels 02 and 06.

That last one was luck, and it’s worth stealing as a habit. The bad output hadn’t been cleaned up yet, so I could test the guard against the actual failure it was written for instead of a synthetic imitation of it. Next time you fix a capture bug, hang onto the broken files until the guard that’s supposed to catch them has been run against them.

Whiplash — XCUITest, .exists, and What .isHittable Fixes

The XCUITest side is five methods, one per panel, and there is nothing clever in any of them. Launch seeded, tap along stable identifiers, assert the thing you came for, attach:

private func launchSeeded() -> XCUIApplication {
    let app = XCUIApplication()
    app.launchArguments += ["--seed-screenshots", "--disable-tips"]
    app.launch()
    return app
}

private func capture(_ app: XCUIApplication, as name: String) {
    let attachment = XCTAttachment(screenshot: app.windows.firstMatch.screenshot())
    attachment.name = name
    attachment.lifetime = .keepAlways
    add(attachment)
}

Every tap is on an accessibility identifier, never a localized string. Obvious in hindsight; not obvious the first time you write app.buttons["Settings"].tap() and watch it pass in exactly one of six runs.

Three things cost me real time.

.exists does not imply visible. This was half the panel-06 bug. SwiftUI keeps off-screen views resident in a plain VStack inside a ScrollView, so a section scrolled well past the top still reports exists == true. The assertion passed while the camera was pointed somewhere else entirely. Assert .isHittable when what you mean is “on screen and photographable.”

An accessibility identifier on a container can leak, and override. CopyPhotosSection had .accessibilityIdentifier("copyPhotos.section") on its outer VStack. Because that stack contains interactive buttons, SwiftUI doesn’t collapse it into a single accessibility element; the identifier landed on five separate descendants instead, and (confirmed by direct device inspection) silently overrode a descendant’s own explicit identifier. app.descendants(...)["copyPhotos.section"] resolved unpredictably. The fix was to take the identifier off the container and put one on an unambiguous leaf, the “My Photos” Text.

swipeUp() is a blunt instrument. It drags nearly a full screen height per call, which is fine for a target deep in the page and terrible for a short section near the top: overshoot it and further swipeUp()s can never recover, because they only scroll the same direction. Hence a small-increment variant:

private func smallScrollUntilHittable(_ element: XCUIElement, in scrollView: XCUIElement, maxAttempts: Int = 20) {
    var attempts = 0
    while !element.isHittable, attempts < maxAttempts {
        let start = scrollView.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.7))
        let end = scrollView.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.55))
        start.press(forDuration: 0.05, thenDragTo: end)
        attempts += 1
    }
}

There’s one more, and it’s the async-rendering trap that every screenshot suite eventually hits. The Insights panel’s container exists the moment its ScrollView renders — before the .task that resolves Market Value has returned. Capturing on the container alone races the fetch and grabs the pre-resolution dash. Wait for the resolved content instead of the container that holds it:

let marketValueResolved = app.descendants(matching: .any)
    .matching(NSPredicate(format: "label BEGINSWITH 'Market Value: $'"))
    .firstMatch
XCTAssertTrue(marketValueResolved.waitForExistence(timeout: Self.longTimeout), "Market Value never resolved")

And the interruption monitor matches English button labels only, in a suite that runs in six languages. That’s deliberate, not an oversight: no permission prompt is expected under --seed-screenshots, so the monitor is a backstop against a genuinely unexpected system alert. A miss means the test hangs and fails, which is what would happen without the monitor anyway.

Nothing Else Matters — Why Not fastlane snapshot

Fair question. snapshot has done this job for a decade, it’s well understood, and frameit handles the device frames. If you’re already on fastlane, keep it.

I didn’t reach for it here for one reason: snapshot captures, it doesn’t verify. Point it at a broken locale configuration and it’ll cheerfully produce ninety-six images, sixteen of them in the wrong language, and hand you a tidy HTML index of your bug. That’s not a knock on the tool — capture is the job it signed up for, and it does it well. But capture was never my problem. Two xcodebuild invocations and a for loop capture fine. My problem was that nothing anywhere in the pipeline ever asked whether the thing that happened was the thing I’d asked for.

The second reason is smaller and more personal. snapshot wants SnapshotHelper.swift vendored into your UI test target and drives locale through its own launch-argument convention. That’s another layer between me and AppleLanguages — and given that a locale mechanism silently not applying is what caused all of this, I wanted that line in my own file, where I could read it and test it.

The valuable part here isn’t the harness. It’s the two guards, and they’re portable: they read PNGs off disk and don’t care what produced them. Run assert_language_hashes_distinct and assert_panels_pairwise_distinct after fastlane snapshot and you get the assertion layer without touching anything else you’ve built.

Fade to Black — What It Actually Cost

One day. The commit log is honest about the shape of it. The first entry is [WIP] capture harness — unverified, no test run completed, and the two that matter most are [FIX] Fail loudly on a repeat of the silent English-panel bug and [FIX] Capture the real My Photos gallery in panel-06, catch cross-panel duplicates.

Neither of those is a translation bug. Both are plumbing bugs — a string, or in the second case an entire screen, that never made it from the source to the pixel. That’s the real category here, and it’s the awkward kind: invisible to eyes, trivial to machines.

It isn’t finished. Three of the eight panels can’t be captured by a simulator at all: the dead wax viewfinder needs a live camera over a real run-out groove, the Home Screen widget isn’t reachable from XCUITest, and CarPlay needs its own simulator. Those are captured by hand and fed to the same compositor (swift Tools/ShotComposer/compose.swift), which doesn’t care about provenance, only that it gets a raw PNG and a caption and emits something opaque, alpha-free, and exactly 1320 × 2868 or 2064 × 2752.

And the captions are still English-only, sitting in a captions.json next to the composer rather than in the app’s String Catalog. That’s the same bug class as the one I opened with, one layer up, waiting: a caption file no translator has ever been shown, in a pipeline that would happily composite English text over a Japanese screenshot and report success. Moving them into Localizable.xcstrings, where extraction is a build-time guarantee and translators already work, is the next thing, and it’ll want a guard of its own. Identical output across locales is a defect until proven otherwise.

The general shape of it: when you build a pipeline that asks some process to do something, make it prove what it did. My original harness sent a locale into a black box and photographed whatever came out, and it would have kept doing that indefinitely. What fixed it wasn’t a better flag — it was shasum -a 256 run twice along two different axes, plus a mode whose only job is to point those guards at known-bad input and fail if they stay quiet.

Ninety-six images, six languages, and not one of them requires me to read Japanese.

There’s exactly one door into VinylCrate’s Insights area — an unlabeled chart icon in the Home toolbar. Behind it sits the collector’s dashboard: what your collection is worth, your top genres, your most-spun records. Analytics said people weren’t walking through it. The sessions that found Insights stayed there, so the feature wasn’t weak. The door was invisible.

That’s the job TipKit exists for, and almost everything written about it stops at the demo popover. Add a tip, watch it appear, ship the screenshot. What nobody writes about is what happens when TipKit meets a real app: a first-run flow that fights your popovers for the screen, a 1,300-line detail view where two tips want the same scroll position, a once-per-process configure call that quietly dictates how your debug tooling has to work, and the question of whether any of this is testable at all.

Nothing Else Matters

VinylCrate ships five tips. Not fifteen. The restraint is the point, so before any mechanics, here’s the full roster:

• Insights — “Explore Your Collector’s Dashboard.” The unlabeled toolbar icon that started all of this: the sole entry into an entire feature area.
• AI Crate Builder — “Build a Crate with AI.” A sparkles button that takes a mood — “late-night thrash,” say — and assembles a crate from records you actually own.
• Copy Photos — “Photograph Your Copy.” Covers, inners, and each disc of the physical copy on your shelf, not the Discogs stock art.
• Dead Wax — “Identify Your Exact Pressing.” Scan the runout etchings and match the pressing you own — the difference between a copy of Ride the Lightning and your copy.
• Sleeve Scan — “No Barcode? Scan the Sleeve.” Point the camera at the cover and on-device AI identifies the record.

Notice what’s not on the list: anything with a visible banner or a labeled control. VinylCrate has plenty of features behind buttons that say what they do, and none of them get a tip, because a tip on a labeled button is chrome explaining chrome. TipKit gives you one display slot per day by default — we’ll get to that — and every tip you attach to something self-explanatory spends that budget teaching nothing.

The heuristic that produced this list: tip the features users would love but will never find. Skip the ones the UI already explains. If the tip is describing the button next to it, delete the tip.

One anchoring note for anyone reading along in the repo: the Insights anchor is the toolbar button in CollectionView — the live Home tab — in Views/ContentView.swift.

Sad But True

TipKit gives you two primitives for eligibility, and the framework’s docs treat them as interchangeable knobs. They’re not.

@Parameter is for state the app can recompute at any moment. Collection size. Whether the user owns physical copies. Whether Apple Intelligence is available on this device. Whether onboarding finished. The test is simple: if you deleted the value and could rebuild it from scratch on the next launch, it’s a parameter.

Tips.Event is for history — the thing state can’t honestly represent. “The user has viewed album detail three times” isn’t derivable from your SwiftData store or your services. You can’t recompute a count of past moments; you had to be counting when they happened.

VinylCrate’s shared parameters live on InsightsTip:

nonisolated struct InsightsTip: Tip {

    @Parameter static var onboardingComplete: Bool = false
    @Parameter static var collectionAlbumCount: Int = 0
    @Parameter static var ownsCopies: Bool = false
    @Parameter static var isAIAvailable: Bool = false

    var rules: [Rule] {
        #Rule(Self.$onboardingComplete) { $0 == true }
        #Rule(Self.$collectionAlbumCount) { $0 >= 10 }
    }

    var options: [Option] { [Tips.MaxDisplayCount(3)] }

}

Those type annotations look redundant, but they’re not optional: the @Parameter macro won’t expand without an explicit type on the property.

The events are the entire other half of the model, and this is the whole file:

nonisolated enum TipEvents {
    static let albumDetailViewed = Tips.Event(id: "albumDetailViewed")
    static let scannerOpened = Tips.Event(id: "scannerOpened")
}

Rules compose both. DeadWaxTip is the clearest example — two facts about the present and one fact about the past:

var rules: [Rule] {
    #Rule(InsightsTip.$onboardingComplete) { $0 == true }
    #Rule(InsightsTip.$ownsCopies) { $0 == true }
    #Rule(TipEvents.albumDetailViewed) { $0.donations.count >= 5 }
}

Those cross-type references are deliberate. InsightsTip owns the parameter statics; every other tip reads them via #Rule(InsightsTip.$onboardingComplete). One writer, many readers — the same instinct as single-owner state in SwiftUI. The alternative is four tips each declaring their own onboardingComplete parameter and four call sites that have to stay in sync forever.

And nothing in the view layer ever pokes a parameter directly. The facts flow one way: SwiftData, @AppStorage, and services feed TipFacts.compute, which feeds the statics. RootView computes an Equatable signature of everything the tips care about, and a .task(id:) fires only when the signature actually changes:

private struct TipFactsSignature: Equatable {
    let albumCount: Int
    let ownsCopies: Bool
    let aiAvailable: Bool
    let hasPromptedForDiscogs: Bool
    let isAuthenticated: Bool
    let importPromptStateRawValue: Int
}

private var tipFactsSignature: TipFactsSignature {
    TipFactsSignature(
        albumCount: container.collection.collection.count,
        ownsCopies: ownsAtLeastOneCopy,
        aiAvailable: container.aiService.isAvailable,
        hasPromptedForDiscogs: hasPromptedForDiscogs,
        isAuthenticated: oauthService.isAuthenticated,
        importPromptStateRawValue: importPromptState
    )
}

.task(id: tipFactsSignature) {
    let signature = tipFactsSignature
    TipsCoordinator.refreshFacts(
        albumCount: signature.albumCount,
        ownsCopies: signature.ownsCopies,
        aiAvailable: signature.aiAvailable,
        hasPromptedForDiscogs: signature.hasPromptedForDiscogs,
        isAuthenticated: signature.isAuthenticated,
        importPromptState: ImportPromptState(rawValue: signature.importPromptStateRawValue) ?? .neverPrompted
    )
}

The coordinator is the single place where facts become parameters:

static func refreshFacts(
    albumCount: Int,
    ownsCopies: Bool,
    aiAvailable: Bool,
    hasPromptedForDiscogs: Bool,
    isAuthenticated: Bool,
    importPromptState: ImportPromptState
) {
    guard !TipsBootstrap.isHostedTestRun else { return }

    let facts = TipFacts.compute(
        albumCount: albumCount,
        ownsCopies: ownsCopies,
        aiAvailable: aiAvailable,
        hasPromptedForDiscogs: hasPromptedForDiscogs,
        isAuthenticated: isAuthenticated,
        importPromptState: importPromptState
    )

    InsightsTip.onboardingComplete = facts.onboardingComplete
    InsightsTip.collectionAlbumCount = facts.albumCount
    InsightsTip.ownsCopies = facts.ownsCopies
    InsightsTip.isAIAvailable = facts.aiAvailable
}

The practical upshot: no view anywhere in the app writes a tip parameter, and when a tip misbehaves there’s exactly one function to put a breakpoint in.

The Wait

VinylCrate’s first run is already busy. A “Connect to Discogs?” prompt appears half a second after launch. Saying yes opens a login sheet. Authenticating offers a collection-import sheet. That’s three pieces of launch UI stacked on a brand-new user — and a tip popover cheerfully rendering on top of that stack is the helpful app shouting over itself.

The fix is the gate you’ve already seen on every rule in the last section: #Rule(InsightsTip.$onboardingComplete), on every tip, no exceptions. The interesting part is what “onboarding complete” actually means, and I got it wrong on the first pass. My first gate was basically “import completed” — which permanently silences every tip for users who decline Discogs. They never see the import flow, so it never completes, so the gate never opens. Everyone who tapped “Not Now” would go tipless forever, and no bug report would ever tell you why.

Here’s the gate that shipped:

nonisolated struct TipFacts {

    let albumCount: Int
    let ownsCopies: Bool
    let aiAvailable: Bool
    let onboardingComplete: Bool

    static func compute(
        albumCount: Int,
        ownsCopies: Bool,
        aiAvailable: Bool,
        hasPromptedForDiscogs: Bool,
        isAuthenticated: Bool,
        importPromptState: ImportPromptState
    )
        -> TipFacts {
        TipFacts(
            albumCount: albumCount,
            ownsCopies: ownsCopies,
            aiAvailable: aiAvailable,
            onboardingComplete: hasPromptedForDiscogs && (!isAuthenticated || importPromptState == .completed)
        )
    }

}

Walk the truth table. Not prompted yet: gate closed, the Discogs alert may still be coming. Prompted and not authenticated: gate open — the user declined, or dismissed the login sheet, and no further launch UI can appear, so tips are safe regardless of import state. Prompted and authenticated but import not completed: gate closed, because the import sheet is either up or still possible. Prompted, authenticated, import completed: open.

The lesson generalizes past Discogs. The gate isn’t “did onboarding finish” — it’s “can any launch UI still appear.” Those are different questions, and the second one has to account for the people who say no.

One

Copy Photos and Dead Wax both live in the album-detail scroll, and for an owned release their rules overlap almost entirely. Without intervention, a user who’s browsed five albums gets both inline tips at once — two stacked cards teaching two things, which reads as clutter and teaches neither.

TipKit’s answer is TipGroup, and it costs two lines in the view:

@State private var ownedCopyTips = TipGroup(.ordered) { CopyPhotosTip(); DeadWaxTip() }

if isInCollection {
    TipView(ownedCopyTips.currentTip)
        .vinylTipStyle()
        .padding(.horizontal)
        .padding(.bottom)
}

One slot, .ordered, Copy Photos first. Whichever eligible tip the group surfaces renders in the single TipView; the other waits its turn.

The part I didn’t plan is my favorite part. The two tips have different donation thresholds — Copy Photos fires at three detail views, Dead Wax at five:

#Rule(TipEvents.albumDetailViewed) { $0.donations.count >= 3 }

#Rule(TipEvents.albumDetailViewed) { $0.donations.count >= 5 }

Combined with the ordered group and the daily display budget, the thresholds naturally stagger the two tips across separate visits: photograph your copy this week, identify your pressing the next. Sequenced teaching, and I never built a sequencing engine. The rules composed one on their own.

Worth noticing in that snippet: the slot only exists when isInCollection is true. Rules decide whether a tip is eligible; view-level conditionals decide where it can physically appear. They stack, and you want both — no rule expresses “this release is in the collection being rendered right now,” so the view carries that half.

Fuel

The default display frequency is .daily — one tip, per day, across the whole app — and the default is right. It’s the single best guardrail TipKit gives you against becoming the app that nags. VinylCrate keeps it.

Except for one tip, and the exception has to earn itself. The Sleeve Scan tip anchors inside the scanner sheet — a surface that exists for seconds at a time. Under a daily budget, the odds that the app’s one tip-of-the-day happens to win its slot during the brief window the scanner is open are close to zero. I would have shipped a tip nobody ever sees.

var rules: [Rule] {
    #Rule(InsightsTip.$onboardingComplete) { $0 == true }
    #Rule(InsightsTip.$isAIAvailable) { $0 == true }
    #Rule(TipEvents.scannerOpened) { $0.donations.count >= 2 }
}

var options: [Option] { [Tips.IgnoresDisplayFrequency(true), Tips.MaxDisplayCount(2)] }

IgnoresDisplayFrequency(true) — but look at what surrounds it. The rules already make the tip rare: Apple Intelligence has to be available, and this has to be at least the second scanner session. And MaxDisplayCount(2) backstops the bypass at two lifetime displays no matter what.

That’s the rubric, not a loophole: bypass the frequency budget only when the anchor surface is transient, the rules already make the tip rare, and a max display count caps the damage. All three, or don’t.

Seek & Destroy

invalidate(reason: .actionPerformed) is what keeps a tip from turning into a nag. The rule I hold: invalidation belongs at every code path that performs the taught action, not just wherever the tip happens to render — users get to the action however they get to it.

The Sleeve Scan tip teaches “switch to sleeve mode and capture.” Two paths perform that, and both invalidate:

.onChange(of: mode) { _, newMode in
    // Toggling modes cancels any in-flight capture and clears stale progress/error/complete state.
    cancelCapture()
    sleeveScan?.reset()
    if newMode == .sleeve {
        sleeveScanTip.invalidate(reason: .actionPerformed)
    }
}

private func startCapture(_ service: SleeveScanService) {
    sleeveScanTip.invalidate(reason: .actionPerformed)
    captureTask?.cancel()
    captureTask = Task { await captureSleeve(service) }
}

The scanner also donates its event from the same view, guarded the same way everything TipKit-adjacent is guarded (more on that guard in the testing section):

.task {
    guard !TipsBootstrap.isHostedTestRun else { return }
    await TipEvents.scannerOpened.donate()
}

Album detail is the interesting one. Copy Photos and Dead Wax are performed inside child section views that expose no tap callback to the parent — and I wasn’t going to thread closures through four layers for a tip. But every action in VinylCrate routes through the coordinator, which means the navigation state already knows when the user does the thing. So the parent observes the active sheet:

.task(id: detail.id) {
    await checkRemoteOwnershipIfNeeded()
    guard !TipsBootstrap.isHostedTestRun else { return }
    await TipEvents.albumDetailViewed.donate()
}
.onChange(of: coordinator?.activeSheet) { _, newValue in
    switch newValue {
    case .copyPhotoCapture(let releaseID, _, _, _)? where releaseID == detail.id:
        CopyPhotosTip().invalidate(reason: .actionPerformed)
    case .deadWaxScan(let releaseID, _, _, _)? where releaseID == detail.id:
        DeadWaxTip().invalidate(reason: .actionPerformed)
    default:
        break
    }
}

The coordinator was built for navigation, not for tips — the sheet routes doubling as “user did the thing” signals is a freebie I’ll happily take. And note the releaseID == detail.id guard — invalidation precision includes which instance. A photo capture launched from some other album’s detail view shouldn’t invalidate the tip this view is showing.

Even the Insights button follows the rule, in the simplest possible form: the tap that opens the dashboard invalidates the tip in the same closure.

Jump in the Fire

Tips.configure looks like housekeeping. It’s actually a strict ordering problem with three links: testing and reset overrides must run before configure, configure must run before the first TipView or .popoverTip evaluates — and the Insights anchor sits on the first screen the app renders. Chain those together and “before the first body” means App.init. Not .task, not onAppear. The last line of VinylCrate’s App.init is TipsBootstrap.configureAtLaunch(), and the comment above it in the app file says exactly why: it cannot defer.

Here’s the bootstrap, essentially whole, because every line is a decision:

nonisolated enum TipsPreferences {
    static let pendingResetKey = "vinylcrate.tips.pendingReset"
    static let debugShowAllKey = "vinylcrate.tips.debugShowAll"
    static let debugHideAllKey = "vinylcrate.tips.debugHideAll"
}

@MainActor
enum TipsBootstrap {

    static var isHostedTestRun: Bool {
        ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
    }

    static func configureAtLaunch() {
        if isHostedTestRun {
            return
        }

        let defaults = UserDefaults.standard

        if defaults.bool(forKey: TipsPreferences.pendingResetKey) {
            try? Tips.resetDatastore()
            defaults.removeObject(forKey: TipsPreferences.pendingResetKey)
        }

        #if DEBUG
        let arguments = ProcessInfo.processInfo.arguments
        if arguments.contains("--disable-tips") {
            Tips.hideAllTipsForTesting()
        }
        if arguments.contains("--show-all-tips") {
            Tips.showAllTipsForTesting()
        }
        #endif

        #if DEBUG
        if defaults.bool(forKey: TipsPreferences.debugShowAllKey) {
            Tips.showAllTipsForTesting()
            defaults.removeObject(forKey: TipsPreferences.debugShowAllKey)
        }
        if defaults.bool(forKey: TipsPreferences.debugHideAllKey) {
            Tips.hideAllTipsForTesting()
            defaults.removeObject(forKey: TipsPreferences.debugHideAllKey)
        }
        #endif

        try? Tips.configure([.displayFrequency(.daily), .datastoreLocation(.applicationDefault)])
    }

}

Top to bottom: stand down entirely if a test suite is hosting the app. Consume a staged datastore reset. Honor DEBUG launch arguments. Consume staged debug overrides. Then — and only then — configure.

Don’t skim past .displayFrequency(.daily) as boilerplate. That’s a product decision encoded in one argument: one tip per day is the app’s entire teaching budget. Every eligibility rule in this post competes for that single daily slot, and that scarcity is what keeps five tips from feeling like fifteen.

The Day That Never Comes

Tips.configure runs once per process. Call it again and the call is ignored. There’s no reconfigure, no teardown, no “just for this screen.” Which means every piece of QA tooling that wants to change TipKit’s world has to work across launches, not within one.

That’s why the debug panel stages instead of acts. Each button writes a UserDefaults key; TipsBootstrap consumes and clears it at the top of the next launch — you saw the consumption side above. Here’s the staging side:

Button {
    UserDefaults.standard.set(true, forKey: TipsPreferences.debugShowAllKey)
} label: {
    debugTipsRowLabel(icon: "eye", title: "Show All Tips (next launch)")
}

Button {
    UserDefaults.standard.set(true, forKey: TipsPreferences.debugHideAllKey)
} label: {
    debugTipsRowLabel(icon: "eye.slash", title: "Hide All Tips (next launch)")
}

Button {
    UserDefaults.standard.set(true, forKey: TipsPreferences.pendingResetKey)
} label: {
    debugTipsRowLabel(icon: "arrow.triangle.2.circlepath", title: "Reset Tips Datastore (next launch)")
}

“Takes effect on next launch” reads like a limitation you’d apologize for. It isn’t — it’s the only honest contract the API allows, so the UI says it out loud instead of pretending. The panel’s footnote spells out the whole deal for whoever’s QA-ing: staged actions take effect on next launch, and while Show All is active every tip stays visible and dismissals don’t stick until you relaunch again.

The launch arguments cover the automated side of the same coin. --show-all-tips gives visual QA every tip at once without grinding out eligibility by hand; --disable-tips means UI tests never race a popover for a tap target.

One action on the panel is immediate, and the distinction matters:

static func showTipsAgain() async {
    await InsightsTip().resetEligibility()
    await AICrateBuilderTip().resetEligibility()
    await CopyPhotosTip().resetEligibility()
    await DeadWaxTip().resetEligibility()
    await SleeveScanTip().resetEligibility()
}

Per-tip resetEligibility() is safe, immediate, and non-destructive — it re-arms the tips without touching donation history. That’s the shape you’d ship to real users as a “Show Tips Again” row in Settings. The full datastore reset is the destructive one, which is exactly why it’s DEBUG-only and staged behind a relaunch.

King Nothing

A short one, but it’s the section the post is named for: TipKit’s datastore is keyed by things you probably think of as freely renameable. Eligibility state, display counts, and dismissals persist under your tip type names. Donation history persists under your event string IDs.

static let albumDetailViewed = Tips.Event(id: "albumDetailViewed")

That string is forever. Rename DeadWaxTip to PressingTip in a refactor, or “clean up” that event ID, and every user’s state for it is orphaned on their next update. Dismissed tips come back. Donation counts reset to zero. The user who explicitly closed a tip six months ago gets it again, and nothing in your diff looked dangerous.

Freeze tip type names and event IDs the way you freeze API surface and SwiftData schema names. A refactor that “just renames” one of these is a data migration you didn’t write — the memory remains, but only if you don’t rename what it’s filed under.

Frantic

“How do you even test TipKit?” is the question that made me want to write this post, because the answer is two layers, and each catches what the other can’t.

Layer one: the gate logic is a pure struct. TipFacts doesn’t import TipKit — it’s a function from app state to booleans, which means the onboarding gate gets a parameterized truth table, including the declined-Discogs edge case that motivated it. The shipping test covers all twelve combinations; here it is trimmed to the six that tell the story:

@Test(
    "onboarding-gate truth table",
    arguments: [
        (hasPrompted: false, isAuthenticated: false, state: ImportPromptState.neverPrompted, expected: false),
        (hasPrompted: true, isAuthenticated: false, state: ImportPromptState.neverPrompted, expected: true),
        (hasPrompted: true, isAuthenticated: false, state: ImportPromptState.completed, expected: true),
        (hasPrompted: true, isAuthenticated: true, state: ImportPromptState.neverPrompted, expected: false),
        (hasPrompted: true, isAuthenticated: true, state: ImportPromptState.skippedOnce, expected: false),
        (hasPrompted: true, isAuthenticated: true, state: ImportPromptState.completed, expected: true)
    ]
)
func onboardingGate(
    hasPrompted: Bool,
    isAuthenticated: Bool,
    state: ImportPromptState,
    expected: Bool
) {
    let facts = TipFacts.compute(
        albumCount: 0,
        ownsCopies: false,
        aiAvailable: false,
        hasPromptedForDiscogs: hasPrompted,
        isAuthenticated: isAuthenticated,
        importPromptState: state
    )

    #expect(facts.onboardingComplete == expected)
}

Rows two and three are the ones that matter: prompted, never authenticated, and the gate opens anyway. That’s the never-connected-Discogs user, pinned so no future “simplification” of the gate expression silences their tips again.

Layer two tests the rules against a real TipKit engine — because a truth table can’t tell you whether #Rule macros, donation counting, and parameter propagation actually compose. The suite is .serialized and @MainActor, and it configures TipKit exactly once per process, into a throwaway datastore, with .immediate frequency so display budgets don’t interfere with eligibility assertions:

// Tips.configure(_:) is once-per-process and later calls are ignored, so
// every TipKit-touching test in this suite must share the same temp
// datastore + `.immediate` display frequency, configured exactly once here.
private static let configureOnce: Void = {
    let datastoreURL = FileManager.default.temporaryDirectory
        .appendingPathComponent("TipRulesTests-\(UUID().uuidString)", isDirectory: true)
    try? FileManager.default.createDirectory(at: datastoreURL, withIntermediateDirectories: true)
    try? Tips.configure([.datastoreLocation(.url(datastoreURL)), .displayFrequency(.immediate)])
}()

Then each test flips parameters, donates events, and asserts shouldDisplay flips at the exact threshold — two donations no, three yes:

@Test
func copyPhotosTipFlipsAtThreeAlbumDetailViews() async {
    InsightsTip.onboardingComplete = true
    InsightsTip.ownsCopies = true
    try? await TipEvents.albumDetailViewed.deleteDonations()

    await TipEvents.albumDetailViewed.donate()
    await TipEvents.albumDetailViewed.donate()
    #expect(await settled { !CopyPhotosTip().shouldDisplay })

    await TipEvents.albumDetailViewed.donate()
    #expect(await settled { CopyPhotosTip().shouldDisplay })
}

That settled helper is the hard-won part. The first shouldDisplay read in a process pays a one-time TipKit engine warm-up that no fixed delay reliably outlasts — I know because I tried the fixed delays first. Poll against a deadline instead; never guess a magic sleep:

// The very first `shouldDisplay` read in the process pays a one-time
// TipKit engine warm-up cost that a fixed delay can't reliably outlast;
// every read after that settles near-instantly. Poll instead of guessing
// a magic sleep duration. Timeout is generous because `TipFactsTests`
// (a separate, non-.serialized @Suite) can run concurrently with this
// suite under xcodebuild's default parallel testing and starve the
// TipKit engine's background settle — observed empirically, matches the
// project's documented `-parallel-testing-enabled NO` flake mitigation.
private func settled(timeout: Duration = .seconds(10), _ condition: () -> Bool) async -> Bool {
    let deadline = ContinuousClock.now + timeout
    while ContinuousClock.now < deadline {
        if condition() { return true }
        try? await Task.sleep(for: .milliseconds(50))
    }
    return condition()
}

The last piece is the one that makes layer two possible at all. These tests run hosted inside the real app, and the real app configures TipKit and donates events at launch. Two configurers, one datastore, nondeterministic tests. So the host stands down whenever a suite is running:

static var isHostedTestRun: Bool {
    ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
}

You’ve already seen it honored three times — configureAtLaunch returns early, refreshFacts guards, and every donation site in the views guards. When the suite runs, the app process is TipKit-silent, and the tests own the engine outright.

Of Wolf and Man

I assumed popover tips were sealed system chrome — style the inline TipViews, live with the stock popover. Turns out tipBackground and tipCornerRadius compose with both, so one five-line extension carries the design system to every tip in the app:

extension View {
    func vinylTipStyle() -> some View {
        self
            .tipBackground(AppColors.cardBackground)
            .tipCornerRadius(CornerRadius.medium)
    }
}

Design tokens — AppColors.cardBackground, CornerRadius.medium — at exactly one call site. You saw it on the inline TipView in album detail; here it is on the popover anchor — same modifier, and also the simplest invalidate-at-the-action example in the app:

Button {
    insightsTip.invalidate(reason: .actionPerformed)
    coordinator?.presentSheet(.insights)
} label: {
    Image(systemName: "chart.bar.xaxis")
}
.popoverTip(insightsTip)
.vinylTipStyle()

One Swift 6 note that will save you a confusing diagnostic. VinylCrate builds with default MainActor isolation, and Tip is nonisolated and Sendable in the SDK — so a tip struct that silently infers @MainActor breaks the conformance. Every tip declares itself out of the inference:

// Tip is nonisolated+Sendable in the SDK; default MainActor isolation would break the conformance
nonisolated struct DeadWaxTip: Tip {

TipEvents and TipFacts carry the same keyword for the same reason — they’re touched from nonisolated rule evaluation, not from your UI.

And one sentence on copy, because tips are UI text that renders far from anything a translator can see: every title and message in these files is Text("…", comment:), auto-extracted into the String Catalog, and that comment is the only context a translator gets for a string like “No Barcode? Scan the Sleeve.” Write the comment accordingly.

Fade to Black

What five tips in a shipping app taught me:

1. Tip the features users won’t find. Skip what the UI already explains. The daily display budget is all the teaching you get — don’t spend it narrating labeled buttons.
2. @Parameter is recomputable state. Tips.Event is history. If you could rebuild it from scratch at launch, it’s a parameter. If you had to have been counting, it’s an event.
3. Gate every tip behind “no launch UI can still be in flight.” Model the user who opts out, not just the one who completes onboarding — the naive gate silences tips for exactly the users who declined something.
4. Tips.configure ordering makes it an App.init concern, and once-per-process makes debug tooling staged. Overrides before configure, configure before the first anchor renders, and QA actions that honestly say “next launch.”
5. Type names and event IDs are persistence. Freeze them like API. A rename is a data migration you didn’t write.
6. And test both layers: the gate logic as a pure truth table, the rules against a real temp-directory datastore — and poll for the engine to settle instead of guessing at sleeps.

The tips have been live for a while now. Each one shows up a handful of times, gets invalidated the moment the user does the thing, and is gone — MaxDisplayCount guarantees it. That’s the odd success criterion for this entire feature: it works by disappearing. Nobody will ever compliment the Copy Photos tip. But the Insights door isn’t invisible anymore — people are walking through it who never would have found it — and not one of them remembers being taught.

That was the first of four bugs I fixed in a single day in the sleeve scanner in VinylCrate, my vinyl-collection app. Four different symptoms, four different fixes, one root cause: I was treating Vision’s output as a string when it’s actually a map.

Vision doesn’t give you a document. It gives you a bag of observations — strings pinned to normalized bounding boxes, in whatever order the recognizer felt like emitting them. Reading order isn’t in there. Word boundaries aren’t in there. Layout isn’t in there. You have coordinates, and everything you think of as “the text” is something you compute from those coordinates. Skip that step and your parser works on your three test photos and fails on the first sleeve that came out of a different pressing plant.

Here’s the setup, the four bugs, and — because every one of these survived my manual testing — the fixture that now pins each one down.

What Vision Actually Hands You

The modern Swift Vision API makes the request itself almost boring. RecognizeTextRequest is a value type, perform is async, and the whole thing is clean with strict concurrency:

import Vision

struct TextBox: Equatable, Sendable {
    var string: String
    var box: CGRect
}

func recognizeText(in imageData: Data) async throws -> [TextBox] {
    var request = RecognizeTextRequest()
    request.recognitionLevel = .accurate
    request.usesLanguageCorrection = false

    let observations = try await request.perform(on: imageData)
    return observations.compactMap { observation in
        guard let candidate = observation.topCandidates(1).first else { return nil }
        return TextBox(string: candidate.string, box: observation.boundingBox.cgRect)
    }
}

Two decisions in there matter. Language correction is off because — as the comment in VinylCrate’s shipping recognizer puts it — catalog codes aren’t words. 60439-1 isn’t in anyone’s dictionary, a matrix etching is exactly the kind of string a language model “helpfully” rewrites into English, and band names and track titles are worse: half of them are stylized past anything a dictionary expects. And I immediately flatten each observation into a TextBox — a string and a rect, nothing else. Every helper downstream is a pure function over [TextBox]. That’s not an aesthetic choice. It’s what makes the fixtures possible: I can pin every geometric decision with an array literal instead of a photo shoot. (Keeping the rect earns its keep elsewhere too — the dead-wax scanner uses the same geometry to exclude the label region from live scans.)

What comes back from perform is where the trouble starts. An array of observations that looks ordered, reads ordered in the debugger for simple images, and is not ordered.

Bug 1: The Array Is Not the Sleeve

The symptom. A back cover with the classic two-column tracklist — titles down the left, runtimes down the right — came out as BATTERY, MASTER OF PUPPETS, 5:10, 8:38. My parser, walking the array looking for the first duration “after” each title, gave both tracks the same runtime — and decided an eight-and-a-half-minute track ran 5:10.

The wrong assumption. That the observation array is in reading order. It roughly tracks the image top-to-bottom for simple layouts, which is exactly the kind of roughly that survives every demo and dies in production. The moment a sleeve has columns, offset side-one/side-two blocks, or a title set on a diagonal, the recognizer interleaves regions freely. Nothing in the API contract says otherwise. I had just never read the contract.

The fix. Reading order is a spatial property, so compute it spatially. Cluster observations into lines by vertical midpoint — with a tolerance, because two boxes on the same printed line never share an exact midY — then sort lines top-to-bottom and members left-to-right:

func clusterLines(_ boxes: [TextBox]) -> [[TextBox]] {
    guard !boxes.isEmpty else { return [] }
    let sorted = boxes.sorted { $0.box.midY < $1.box.midY }
    let medianHeight = sorted.map(\.box.height).sorted()[sorted.count / 2]
    let tolerance = medianHeight * 0.6

    var lines: [[TextBox]] = []
    var current = [sorted[0]]

    for box in sorted.dropFirst() {
        let lineMidY = current.map(\.box.midY).reduce(0, +) / CGFloat(current.count)
        if abs(box.box.midY - lineMidY) <= tolerance {
            current.append(box)
        } else {
            lines.append(current)
            current = [box]
        }
    }
    lines.append(current)

    return lines.map { $0.sorted { $0.box.minX < $1.box.minX } }
}

The tolerance is relative to the median box height, not a magic constant in normalized units, so it holds up whether the sleeve fills the frame or sits in a corner of the photo.

The fixture. Four boxes, deliberately fed in the interleaved order Vision actually produced. No image required — the geometry is the fixture:

@Test func twoColumnTracklistReadsRowByRow() {
    let boxes = [
        TextBox(string: "BATTERY",           box: CGRect(x: 0.05, y: 0.10, width: 0.20, height: 0.04)),
        TextBox(string: "MASTER OF PUPPETS", box: CGRect(x: 0.05, y: 0.18, width: 0.40, height: 0.04)),
        TextBox(string: "5:10",              box: CGRect(x: 0.55, y: 0.10, width: 0.08, height: 0.04)),
        TextBox(string: "8:38",              box: CGRect(x: 0.55, y: 0.18, width: 0.08, height: 0.04)),
    ]
    let lines = clusterLines(boxes).map(joinLine)
    #expect(lines == ["BATTERY 5:10", "MASTER OF PUPPETS 8:38"])
}

If anyone — including me, six months from now — “simplifies” the clustering back into an array walk, this test fails with a message that explains the whole bug.

Bug 2: Y Grows Up

The symptom. The first version of clusterLines shipped with a different sort, and the output read like the sleeve had been fed through the scanner bottom-up. Barcode and ℗ line first, album title last. Perfectly ordered. Perfectly backwards.

The wrong assumption. That origin.y means what UIKit has trained me to think it means. Vision’s normalized coordinate space puts the origin at the bottom-left, y increasing upward — image-processing convention, not screen convention. Sorting by minY ascending walks the sleeve from the bottom. Worse, any box math you do in the wrong space is quietly broken: “is this box above that one” flips meaning, and vertical-overlap checks compare the wrong edges.

The fix. Convert once, at the boundary, and let everything downstream live in top-left space. If you’re projecting into image pixels anyway, the API will do it for you — boundingBox.toImageCoordinates(imageSize, origin: .upperLeft). For normalized-space work, the flip is one line:

func topLeftRect(_ visionRect: CGRect) -> CGRect {
    CGRect(x: visionRect.minX,
           y: 1 - visionRect.maxY,
           width: visionRect.width,
           height: visionRect.height)
}

recognizeText now applies this before anything else sees a rect. One conversion, one place. The alternative — sprinkling 1 - y through the codebase wherever things look upside down — is how you end up with code that flips twice and looks correct in exactly one screen orientation.

The fixture. Two boxes in raw Vision space: the album title near the top of the sleeve (high y, in Vision’s terms) and the ℗ line near the bottom. The test pins the relationship, not the arithmetic:

@Test func visionSpaceFlipsToReadingOrder() {
    let albumTitle    = CGRect(x: 0.05, y: 0.85, width: 0.40, height: 0.05)
    let copyrightLine = CGRect(x: 0.05, y: 0.05, width: 0.30, height: 0.04)
    #expect(topLeftRect(albumTitle).midY < topLeftRect(copyrightLine).midY)
}

It looks almost too small to bother with. It has already caught one refactor where a well-meaning cleanup removed the “redundant” flip.

Bug 3: Word Boundaries Are Load-Bearing

The symptom. MASTEROFPUPPETS. Also, on a different sleeve, METALLI CA — the same code, failing in the opposite direction.

The wrong assumption. That joining strings is a string problem. My first pass used joined() — words fused. The obvious “fix” was joined(separator: " ") — and now words that Vision had split mid-word across two observations grew a space in the middle. There is no string-level answer here, because whether two observations deserve a space between them isn’t a property of the strings. It’s a property of the gap between their boxes.

The fix. Measure the gap and compare it to the local character width. If the horizontal distance between two boxes is a meaningful fraction of an average character in those boxes, it’s a word boundary. If it’s a sliver, it’s the same word:

func joinLine(_ line: [TextBox]) -> String {
    guard var result = line.first?.string else { return "" }
    for (previous, next) in zip(line, line.dropFirst()) {
        let gap = next.box.minX - previous.box.maxX
        let averageCharWidth = (previous.box.width + next.box.width)
            / CGFloat(previous.string.count + next.string.count)
        result += gap > averageCharWidth * 0.35 ? " " + next.string : next.string
    }
    return result
}

The 0.35 came from measuring real sleeves, and I’ll be honest: it’s a heuristic, and heuristics over photographs of forty-year-old ring-worn cardboard have losing days. But it’s a heuristic about geometry, which means it degrades gracefully — where joined(separator: " ") was a coin flip dressed up as a decision.

The fixture. Both directions, in one test, because this bug fails both ways and a fix for one direction can silently reintroduce the other:

@Test func wordBoundariesComeFromGeometryNotLuck() {
    let title = [
        TextBox(string: "RIDE",      box: CGRect(x: 0.05, y: 0.40, width: 0.10, height: 0.04)),
        TextBox(string: "THE",       box: CGRect(x: 0.17, y: 0.40, width: 0.08, height: 0.04)),
        TextBox(string: "LIGHTNING", box: CGRect(x: 0.27, y: 0.40, width: 0.22, height: 0.04)),
    ]
    #expect(joinLine(title) == "RIDE THE LIGHTNING")

    let splitWord = [
        TextBox(string: "METALLI", box: CGRect(x: 0.050, y: 0.10, width: 0.21, height: 0.05)),
        TextBox(string: "CA",      box: CGRect(x: 0.266, y: 0.10, width: 0.06, height: 0.05)),
    ]
    #expect(joinLine(splitWord) == "METALLICA")
}

The rects in splitWord are lifted straight from the failing sleeve’s debug output. That’s the move worth stealing: when a real image breaks you, don’t just fix the code — harvest the coordinates into a fixture before you lose the photo.

Bug 4: Proximity Beats Order

The symptom. One track’s runtime came back as 60439-1 — the catalog number. The parser found the track title, then took “the next observation” as its duration. In array order, the next observation was whatever the recognizer emitted next — which, per bug 1, could be anything on the sleeve, including the catalog block.

The wrong assumption. The subtlest one, because it felt fixed. I had line clustering. I had geometric joining. And then, for title–duration association, I reached for array order one more time — firstIndex(of:) plus one. The title and its runtime sit on the same printed line, but on a two-column tracklist they can arrive dozens of positions apart in the array, with half the sleeve between them.

The fix. The value for a label is the nearest observation to its right on the same baseline — a geometric query, not an index:

func verticalOverlap(_ a: CGRect, _ b: CGRect) -> CGFloat {
    let overlap = min(a.maxY, b.maxY) - max(a.minY, b.minY)
    return overlap / min(a.height, b.height)
}

func value(for label: String, in boxes: [TextBox]) -> TextBox? {
    guard let anchor = boxes.first(where: {
        $0.string.localizedCaseInsensitiveContains(label)
    }) else { return nil }

    return boxes
        .filter {
            $0.box.minX > anchor.box.maxX
                && verticalOverlap($0.box, anchor.box) > 0.5
        }
        .min {
            ($0.box.minX - anchor.box.maxX) < ($1.box.minX - anchor.box.maxX)
        }
}

Requiring 50% vertical overlap — rather than a midY distance — handles boxes of different heights sharing a baseline, which happens constantly when a track title set in one weight sits next to a runtime set in another. And min by horizontal distance means a barcode two columns over never wins against the duration printed on the same line.

The fixture. The array order is the trap, so the fixture bakes the trap in — the catalog number sits between the title and its runtime, exactly where the old code would grab it:

@Test func nearestOnBaselineBeatsNextInArray() {
    let boxes = [
        TextBox(string: "ORION",   box: CGRect(x: 0.05, y: 0.60, width: 0.10, height: 0.04)),
        TextBox(string: "60439-1", box: CGRect(x: 0.30, y: 0.72, width: 0.14, height: 0.04)),
        TextBox(string: "8:12",    box: CGRect(x: 0.55, y: 0.60, width: 0.08, height: 0.04)),
    ]
    #expect(value(for: "ORION", in: boxes)?.string == "8:12")
}

The catalog number even passes the “is it to the right of the anchor” check. It dies on the vertical-overlap filter — it’s on a different line, and no amount of array adjacency changes that.

One Fixture That Is a Photo

Pure-geometry fixtures carry most of the weight, but they all share one blind spot: they trust my mental model of what Vision emits. So the suite ends with a fixture that is an image — a sleeve pulled off my own shelf, back cover photographed flat, checked into the test bundle, and run through the real request:

I wrote the obvious assertions first: the joined lines should contain MASTER OF PUPPETS 8:38, and value(for: "ORION") should hand back 8:12, because that’s what’s printed on the sleeve.

The photo failed both immediately — and the failure is the most instructive thing in this post. The runtimes on this pressing are set in type small enough that Vision doesn’t emit them as observations at all. It fuses a garbled fragment into the title’s own box: ORION •1, one observation, one rect. There is no duration box anywhere in the output. value(for: "ORION") isn’t wrong — it’s nil, because the thing I was querying for doesn’t exist in the map. Tiny type claimed other casualties too: CUFF BURTON.

So the test pins what the pipeline actually guarantees on this photograph — rows pair across the column gutter, reading order runs top-down, the nearest-on-baseline query finds the true row partner, and the missing duration stays honestly missing:

@Test func realSleevePhotoSurvivesTheWholePipeline() async throws {
    let url = try #require(
        Bundle.module.url(forResource: "sleeve-back-two-column", withExtension: "heic")
    )
    let boxes = try await recognizeText(in: Data(contentsOf: url))
    let lines = clusterLines(boxes).map(joinLine)

    let puppetsRow = try #require(lines.first { $0.contains("MASTER OF PUPPETS") })
    #expect(puppetsRow.contains("LEPER MESSIAH"))

    let batteryIndex = try #require(lines.firstIndex { $0.contains("BATTERY") })
    let creditsIndex = try #require(lines.firstIndex { $0.contains("PRODUCED BY") })
    #expect(batteryIndex < creditsIndex)

    let rowPartner = value(for: "THE THING THAT SHOULD NOT BE", in: boxes)
    #expect(rowPartner?.string.hasPrefix("ORION") == true)

    #expect(value(for: "ORION", in: boxes) == nil)
}

That last #expect is the one I’d defend in review. It documents a real property of real input — on this sleeve, at this type size, durations are not recoverable as separate fields — and it will fail loudly the day a Vision update starts splitting them, which is exactly when I’d want to revisit the parser.

This test is slower than the others and slightly at the mercy of the recognizer’s mood across OS releases. It’s also the only one that would have caught all four bugs at once, because it exercises the actual contract: observations in whatever order, in Vision’s coordinate space, split — or fused — wherever the recognizer chose. The array-literal fixtures explain which assumption broke. The photo proves the assumptions cover reality, and when the two disagree, the photo wins the argument.

The Map Is the Territory You Get

Four bugs, and every one of them was the same bug wearing a different jacket: I kept treating a spatial data structure as a sequential one. The array order lied. The coordinate origin lied. The whitespace never existed. The “next” element was a stranger from another column.

OCR output is a map, not a string. Reading order is something you compute from y. Word boundaries are something you compute from gaps. Field association is something you compute from proximity — because on a printed page, proximity beats order every single time.

And every geometric assumption you make deserves a fixture, because these bugs have a signature failure mode: they work on your three test photos. The sleeve that breaks you will come from a pressing plant you’ve never seen, with a layout you didn’t imagine, and the only question is whether the coordinates it exposes end up in your test suite or in your support inbox.

Mine go in the test suite now. Harvest the rects, pin the behavior, keep the photo.

That’s the dangerous part. A tool that crashes gets fixed. A tool that prints ** BUILD SUCCEEDED ** while doing something subtly different from what you asked gets trusted — right up until a release build ships without your fix in it, or your CI pipeline spends six months green-lighting tests against binaries that were never rebuilt.

I’ve hit every one of these in real pipelines. Some on personal projects like VinylCrate, some on airline-scale CI where a lie in the build log costs a lot more than an afternoon. This is the field guide I wish someone had handed me. Four traps: the lying command, what’s actually happening under the hood, and the invocation that tells the truth.

Trap 1: “BUILD SUCCEEDED” That Never Built Your App

Here’s the command that lied to me first, years ago, and still lies to people every day:

cd VinylCrate
xcodebuild build

** BUILD SUCCEEDED **. Exit code 0. CI goes green. And your app target may never have compiled.

When you give xcodebuild no -scheme and no -target, it doesn’t guess your intent. It builds the first target listed in the project file, with the default configuration. Target order is a property of the .xcodeproj itself (same for every user, and largely an accident of history). If someone once dragged a shared framework or a helper tool to the top of the target list, that’s what you just built. Your app, your tests, your script phases — untouched. BUILD SUCCEEDED is technically true. It’s just not about the thing you care about.