With the introduction of the Swift-native AttributedString in iOS 15 and macOS 12, it’s become pretty common to convert between the existing NSAttributedString and the new type. Certain first-party frameworks, like SwiftUI and App Intents, require developers to use the new AttributedString. In existing apps, simply moving off of NSAttributedString can be too heavy of a lift, and if you’re using Objective-C at any point in the stack, such a migration simply wouldn’t be feasible. I also would be the last person to shame you for enjoying well-written Objective-C code.

Luckily, we can convert between AttributedString and NSAttributedString with the help of built-in methods. While it is fairly widely known that the bridging is not toll-free, as the types use distinct underlying representations, I haven’t found any comprehensive explorations or official first-party insight into exactly how fast or how slow such conversions are.

If you’ve worked in an established SwiftUI codebase, or if you maintain one of your own, you’ve likely seen code like this:

Text(AttributedString(viewModel.nsAttributedString))

As any experienced SwiftUI developer is likely to know, our views’ body computations should be as lightweight and cheap to execute as possible. AttributeGraph will ultimately decide when and how often to reevaluate the body, and putting accidentally expensive computations that should’ve been precomputed and cached inside a view model – or elsewhere outside the view – is likely one of the more common and easier to fix performance problems in SwiftUI view hierarchies.

Depending on just how expensive these conversions are, performance of our entire app could be at stake! Given the weight of the situation, exactly how concerned should we be when we see the bridging between the two attributed string representations? Are the performance characteristics the same for both directions of the conversion? How does the performance scale with the size of the strings?

Apple’s documentation does not provide a definitive answer. So, I decided to set up some performance tests on macOS 26.2 and try to find out. I’m posting the findings here hoping they could be of use to someone asking themselves similar questions.

String length

In this test, I held the number of attributes per run (4) and run count (32) constant while increasing the length of the string.

This shows that the cost of conversion from NSAttributedString to AttributedString scales strongly with length: 148.3 μs at 256 characters to 2814.2 μs at 131072 characters (about 19.0x). This raises concerns for code like the above Text(AttributedString(viewModel.nsAttributedString)), where the conversion happens on a hot path, especially if you can’t guarantee the string to be sufficiently small.

The other direction stays much flatter with length, rising from 103.6 μs to 143.6 μs over the same range. It seems to generally be a lot cheaper to convert an AttributedString to an NSAttributedString than the other way around.

Number of attributes

The length of the string is not the only axis we may want to test when dealing with attributed strings. I wanted to see what happens if I held both the string length (8,192) and run count (32) constant while increasing attributes per run (1 → 4). This would show the sensitivity to “attribute richness” of the strings.

This shows a close to linear increase for both directions.

A combination

I also wanted to grow the length and attribute richness together to simulate a very frequent real-world scenario. Based on the above results, the hypothesis was that the growth would be dominated by the growth of the length of the string.

The shape of the results is pretty much the same as what we saw when growing the length of the string, leading to very similar conclusions.

What this shows

The initializers of both AttributedString and NSAttributedString accepting the other representation are designed to be syntactically lightweight, but as we can see from this test, are not guaranteed to be. What this tells me is that I shouldn’t treat the work done by these conversion operations as trivial, and should therefore avoid cases where I perform a lot of these conversions on a hot code path like inside a SwiftUI view’s body, especially if I don’t know the length of the input string.

In SwiftUI

My practical recommendation here, solely based on the data above, would be as follows.

• If you’re dealing with very small strings, or strings of a deterministic but short length, it’s probably “fine” to keep converting them inline.
  • It likely doesn’t matter how saturated with attributes the string is.
• If the string we’re working with is based on a user input or is otherwise of a nondeterministic length, convert it once.
  • It is best to store the string as the representation you’re going to present at the View Model (or equivalent) layer. If you’re presenting via SwiftUI Text, store the string as an AttributedString.
  • When the input value affecting the string changes, rebuild it.
  • This way, you’re the one in control of how often the string conversion occurs.

What this doesn’t show

My goal with this little performance test was to see how converting between the two built-in attributed string representations performed on the current version of macOS (26.2). It was not meant to be a comprehensive test, since other platforms, devices, and OS versions may behave differently. Optimizations may be introduced at the framework level in the future. Similarly, the performance could regress, and surely both instances have happened in the past.

I have already written about another gnarly bug around document-based apps in SwiftUI in a previous post. In that post, I found that on visionOS, any DocumentGroup scene would duplicate your view hierarchy, causing pretty funny looking visual overlaying glitches. It was most visible on visionOS due to the amount of UI translucency, but I later realized the bug was also reproducible on iOS.

It is fairly evident that document-based apps have not been a major focus area in the recent SwiftUI evolution and development lifecycle, because today we’re looking at another bug that makes DocumentGroup quite unusable. Turns out, if you have a DocumentGroup scene and you try using the focusedSceneValue API to define self-validating Commands for that scene, it just won’t work on iOS or visionOS, as your focused value will always be nil.

Implementing self-validating menu commands

The SwiftUI focus APIs can be quite helpful for implementing automatically validated key equivalents if your application uses SwiftUI App Lifecycle. I’ll aim to provide a quick introduction and demonstrate the behavior here, so please feel free to skip to the next section if you’re already familiar with these techniques.

Adding some key commands to your iOS app, or menu items to the macOS (and now iPadOS) menu bar, and wanting to automatically enable or disable them based on where the user is focused within your Scene, is a pretty canonical use case for focusedSceneValue. Perhaps you’d also like to know which instance of your Scene any invoked command should go to if your application supports multiple windows.

If you’re not yet familiar with using SwiftUI for building good menu bar experiences on the Mac (and iPad starting with iOS 26), Apple’s own Building and customizing the menu bar with SwiftUI is a good starting point.

If you’re coming from a macOS and particularly AppKit background, FocusedValue and focusedSceneValue will sound very conceptually similar to the Responder Chain.

The simplest example would be implementing key equivalents (or Commands, if you’re willing to forgive my Mac-ism) to operate on a text view that is currently being edited somewhere in your app. Suppose we have a very simple Observable object that stores the contents of our document and the high-level state of the app’s UI, like so:

@Observable
final class DocumentState {
    var text: String = ""
    var selection: TextSelection?
    
    func formatBold() { … }
}

struct ContentView: View {
    @State private var state = DocumentState()

    var body: some View {
        TextEditor(text: $state.text, selection: $state.selection)
            .focusedSceneValue(state)
    }
}

Now, since I have added my Observable object as a focusedSceneValue, I can implement my formatting commands and add them to the scene:

struct EditingCommands: Commands {
    @FocusedValue(DocumentState.self) private var state
    
    var body: some Commands {
        CommandGroup(after: .textEditing) {
            Button("Bold") { state?.formatBold() }
                .disabled(state == nil)
        }
    }
}

@main
struct FocusedSceneValueDocumentApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .commands { EditingCommands() }
    }
}

To see the effects of what we’ve just accomplished, it is probably the easiest to run the app on macOS. You will see that when no instances of our WindowGroup are present (for example, if we close all of the application’s windows), our custom Bold menu item will be disabled in the Edit menu. If we open at least one window, and if at least one of these windows is key, it will become enabled. Moreover, we get the desired effect of SwiftUI knowing which instance of the Scene the command should go to when multiple windows are open. Invoking the Bold menu item in this sample app will always operate on the key window, which is what the user of your app expects.

focusedSceneValue is very powerful for implementing automatic action validation in your app, and its use is likely required if you want to build anything close to a Mac-assed Mac app with SwiftUI App Lifecycle. The above example can be useful for establishing the baseline of how this is supposed to work. And now…

Completely broken if your Scene is a DocumentGroup

The above simply does not work if the following 2 conditions are true:

• Your scene is a DocumentGroup, and
• You’re running on any platform other than macOS.

As far as I can tell, the bug reproduces on all latest versions of iOS (including iPadOS) and visionOS, as well as the Seed versions of iOS 26 and visionOS 26.

To reproduce this issue, it is enough to create a document-based SwiftUI app from the Xcode template and try using the focusedSceneValue API to implement a simple autovalidating command. You’ll notice that in your Commands implementation, the FocusedValue is always simply nil and your body is never invoked again with an updated value, even as you present more instances of the DocumentGroup or close the existing ones.

Workaround

After reporting the bug, I wanted to determine if a conceptually simple and lightweight workaround was possible. Since focusedSceneValue works fine on macOS, I only needed a targeted workaround for UIKit based platforms.

• First, we need some kind of shared state that our Commands implementation can read, since it’s by far the most lightweight way to pass the state across the Scene boundary. It’s not the “Swiftiest,” but felt like an appropriate balance of conciseness and complexity.
• We need a way to track what the active Scene is. We can use the scenePhase Environment key with some added handling for onAppear and onDisappear.
• Finally, we can combine these into a ViewModifier that can be reused across various Scenes, and adopt it in our Commands implementation.

Putting this all together, here is where I landed:

#if canImport(UIKit)

import SwiftUI

extension View {
    func documentGroupSceneFocusBinding<T: AnyObject>(
        _ document: T,
        keyPath: ReferenceWritableKeyPath<ActiveScene, T?>
    ) -> some View {
        ModifiedContent(content: self, modifier: DocumentGroupFocusWorkaround(document: document, keyPath: keyPath))
    }
}

struct DocumentGroupFocusWorkaround<T: AnyObject>: ViewModifier {
    let document: T
    let keyPath: ReferenceWritableKeyPath<ActiveScene, T?>
    
    @Environment(\.scenePhase) private var scenePhase
    
    func body(content: Content) -> some View {
        content
            .onChange(of: scenePhase) { _, newValue in scenePhaseDidChange(to: newValue) }
            .onAppear { scenePhaseDidChange(to: .active) }
            .onDisappear { scenePhaseDidChange(to: .background) }
    }
    
    private func scenePhaseDidChange(to scenePhase: ScenePhase) {
        let isActive = scenePhase == .active
        if isActive {
            ActiveScene.shared[keyPath: keyPath] = document
        } else if ActiveScene.shared[keyPath: keyPath] === document {
            ActiveScene.shared[keyPath: keyPath] = nil
        }
    }
}

@Observable @MainActor
final class ActiveScene {
    static let shared = ActiveScene()
}

#endif

What’s left is to add the fields we care about, like the DocumentState from the example app we’ve defined, to the ActiveScene definition:

final class ActiveScene {
    // …
    var documentState: DocumentState?
}

Then, our ContentView can trivially apply the workaround using a single line of code:

var body: some View {
    platformView
#if canImport(UIKit)
        .documentGroupSceneFocusBinding(state, keyPath: \.documentState)
#endif
}

The adoption inside our Commands definition would be trivial, too, not requiring any changes to the body of the implementation:

struct EditingCommands: Commands {
#if canImport(UIKit)
    private var state: DocumentState? {
        ActiveScene.shared.documentState
    }
#else
    @FocusedValue(DocumentState.self) private var state
#endif

    var body: some Commands {
        // …
    }
}

Conclusion

I’ve reported the bug to Apple (tracked as FB20116555), and I’m including both the repro case and the above workaround as sample code available on GitHub. I truly hope both DocumentGroup and Document-Based App lifecycle can get the attention they deserve in the near future, as these issues are quite prohibitive when it comes to attempting to use these APIs in production applications.

SwiftUI undoubtedly has a lot of impressive capabilities and features, but unfortunately transparency is not one of them. Many components are designed and built as black boxes, with developers left attempting to piece together the full picture using the sparse information gathered from the documentation, WWDC videos, and reverse engineering. One of the most unfortunate consequences of that, in my opinion, is the lack of general intuition around possible causes for poor performance. In other words, if something I built in SwiftUI performs horribly, am I hitting one of the framework’s limitations, or am I holding it wrong?

In most cases, poor SwiftUI performance can boil down to accidentally causing unnecessary invalidations. This can be hard to debug, and even harder to develop good intuition about. One of the most easy to reach for tools is perhaps _printChanges(), which can be used to match your expectation of what should be happening in your hierarchy with what is actually happening at runtime.

Unnecessary invalidations can be caused by a variety of different things – and I may explore more of them in a separate post in the near future. For now, I’d like to zoom in on one particular cause that has a lot of misinformation and bad advice on it online: passing closures using the Environment.

The Problem

If you’ve ever looked for SwiftUI advice online or explored some open-source code out there, you’ve probably seen people passing actions through the Environment like so:

import SwiftUI

extension EnvironmentValues {
    @Entry var openSomething: () -> Void = { }
}

struct ContentView: View {
    @State private var isHovered: Bool = false
    
    var body: some View {
        CustomButton()
            .padding()
            .environment(\.openSomething, openSomething)
            .background {
                Color.primary
                    .opacity(isHovered ? 0.2 : 0.05)
            }
            .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
            .onHover {
                isHovered = $0
            }
    }
    
    private func openSomething() {
        print("Open clicked...")
    }
}

struct CustomButton: View {
    @Environment(\.openSomething) var openSomething
    
    var body: some View {
        let _ = Self._printChanges()
        Text("Click to Open")
            .onTapGesture {
                openSomething()
            }
    }
}

Seems like a much nicer alternative to passing closures directly or passing some ViewModel-esque object containing all the actions around, right? Sure, especially if you have a view nested deep inside the hierarchy responding to an action defined somewhere closer to the root. But let’s use the _printChanges I’ve added to CustomButton to match our expectation to the runtime behavior.

Here’s what I’d expect to happen:

• Our print is triggered once during the initial evaluation of the view hierarchy, printing out something like CustomButton: @self changed..
• Toggling isHovered, or any other hypothetical state of the parent view, does not invalidate CustomButton, and therefore does not trigger a print.
• Tapping the button and triggering the action similarly does not cause an invalidation.

Essentially, I’m expecting that the custom button will be only evaluated once, or some very low constant number of times, where the number is not dependent on the number of state changes. This expectation can be important for performance, especially if you imagine a more complex or deeply nested view in the place of CustomButton. Let’s run the app and check what happens in reality:

• ✅ There is an initial evaluation of the body.
• ❌ However, during the initial presentation, the button’s body is churned through multiple times (6 in my case!), claiming my openSomething closure has changed:

CustomButton: @self, @identity, _openSomething changed.
CustomButton: _openSomething changed.
CustomButton: _openSomething changed.
CustomButton: _openSomething changed.
CustomButton: _openSomething changed.
CustomButton: _openSomething changed.

• ❌ Once I hover the button, it invalidates its body and causes a print to happen again, claiming @self, _openSomething changed yet again. If I keep changing state, the button’s body is re-evaluated each time.

This just caused a lot more calls to body for our CustomButton than we expected! And, of course, these changes would’ve propagated further down the view hierarchy. That is, if our button component composed more views, those would be re-evaluated too, increasing the impact on performance. Similarly, if the view that contains the button component had more state that it managed, any changes to that state would also invalidate CustomButton. If we had more instances of CustomButton, those would be invalidated in a similar fashion.

It’s probably obvious why this is a huge performance issue waiting to happen and cause us much headache. If we decide to look into the issue a bit, we can use the hint from our _printChanges exploration to hypothesize that something must be causing SwiftUI to consider our Environment value to have changed, which is probably in turn causing all those redundant invalidations.

Closures do not support equality

In Swift, closures are reference types, but are neither equatable nor reference equatable. This is not some bug in Swift, but is actually very much by design. In the words of Chris Lattner on the Old Developer Forums (preserved thanks to this direct quote on StackOverflow):

This is a feature we intentionally do not want to support. There are a variety of things that will cause pointer equality of functions (in the swift type system sense, which includes several kinds of closures) to fail or change depending on optimization. If "===" were defined on functions, the compiler would not be allowed to merge identical method bodies, share thunks, and perform certain capture optimizations in closures. Further, equality of this sort would be extremely surprising in some generics contexts, where you can get reabstraction thunks that adjust the actual signature of a function to the one the function type expects.

The easiest way to confirm this behavior is declaring a closure and then attempting to reference-compare it to itself, like so:

let closureWithoutArguments: () -> Void = { }
print(closureWithoutArguments == closureWithoutArguments)
print(closureWithoutArguments === closureWithoutArguments)

Neither of the print statements will compile:

Cannot check reference equality of functions; operands here have types '() -> Void' and '() -> Void’.

Note that in previous versions of Swift, reference comparison (===) did compile, but the statement above would’ve returned false at runtime.

Actions in Environment: Exploring Alternatives

So, how do we pass an action down the Environment? Should we simply give up on the flexibility it offers and stick to other alternatives?

Bad: Closures in Environment

At this point, we can see why putting our closure in the Environment directly was such a bad idea. Since the internals of SwiftUI’s Environment implicitly track changes to values and invalidate the views as appropriate, we can hopefully see the problem now. Every time it checks our value, it’s technically different, so the framework must invalidate any views that depend on this value.

Better: Passing Closures Directly

We could revert to a simple action model that you would typically see on views like buttons.

struct ContentView: View {
    @State private var isHovered: Bool = false
    
    var body: some View {
        CustomButton(openSomething: openSomething)
            .padding()
            .background {
                Color.primary
                    .opacity(isHovered ? 0.2 : 0.05)
            }
            .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
            .onHover {
                isHovered = $0
            }
    }
    
    private func openSomething() {
        print("Open clicked...")
    }
}

struct CustomButton: View {
    let openSomething: () -> Void
    
    var body: some View {
        let _ = Self._printChanges()
        Text("Click to Open")
            .onTapGesture {
                openSomething()
            }
    }
}

The behavior here is much more predictable. We get:

• A single CustomButton: @self changed. print on initial evaluation.
• One CustomButton: @self changed. print every time isHovered changes.

The latter is still not ideal, of course. After all, my custom button does not depend on the hover state of its parent view. But in practice, if you’re dealing with a leaf view like a simple button, this can be a good tradeoff to make. The direct passing of the action is much more scoped and much more explicit than passing it through the environment, and the invalidation behavior is certainly more predictable. But, most importantly, it’s so simple!

Of course, one other alternative would be to encapsulate such actions inside some @Observable object that you can hold near the root pass through the Environment, then have your button call some function on it. But, of course, you are sacrificing some flexibility, and it doesn’t work for every use case.

Best: Use a Stable Object

If you’ve seen how SwiftUI’s built-in DismissAction works, you probably know what I’m about to suggest. If not, here’s a brief summary.

Case Study: DismissAction

SwiftUI includes a dismiss action in the Environment that you can use to dismiss things like sheets and popovers.

private struct SheetContents: View {
    @Environment(\.dismiss) private var dismiss


    var body: some View {
        Button("Done") {
            dismiss()
        }
    }
}

You use it like a closure, but it is not actually a closure. If you look at its definition, you will see that it’s a struct that implements a “magic” callAsFunction method.

@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
@MainActor public struct DismissAction {
    public func callAsFunction()
}

callAsFunction is what allows the environment value to be used as if it were a closure or a function. You can read more about methods with special names in Swift on the documentation website.

Implementing Callable Handlers

Let’s do the same for our openSomething closure. The first step is to wrap our action in a callable type and implement callAsFunction:

struct CallableHandler<Input> {
    typealias Handler = (Input) -> Void
    private let handler: Handler
    
    init(_ handler: @escaping Handler) {
        self.handler = handler
    }
    
    func callAsFunction(_ input: Input) {
        handler(input)
    }
}

extension EnvironmentValues {
    @Entry var openSomething: CallableHandler<Void>?
}

Now, let’s use it for our button. I may be tempted to do this in a fairly naive way, initializing the handler “on the fly.”

struct ContentView: View {
    @State private var isHovered: Bool = false
    
    var body: some View {
        CustomButton()
            .environment(\.openSomething, CallableHandler {
                print("Open clicked...")
            })
            .onHover { isHovered = $0 }
    }
}

struct CustomButton: View {
    @Environment(\.openSomething) var openSomething
    
    var body: some View {
        let _ = Self._printChanges()
        Text("Click to Open")
            .onTapGesture {
                openSomething?(())
            }
    }
}

❌ However, this would still cause hovering the parent view to invalidate the button – the same behavior as when passing a closure to it directly. The reason for that is because every time the parent view’s body is evaluated, we will put a new handler in the Environment, which will cause SwiftUI to attempt to diff it with the old one. In this case, SwiftUI will consider the new value to be different.

⚠️ We could, of course, work around this by implementing an explicit Equatable conformance for our CallableHandler. However, a more important piece of intuition about diffing that we can extract from this is:

• Writing newly initialized structs and newly allocated objects to the environment will incur diffing costs, and
• In some cases, the outcome of the diffing may be unexpected.

✅ Given that, a more general and flexible solution would involve making the handler stable and passing it down, like so:

private struct HandlerModifier: ViewModifier {
    @State var handler: CallableHandler<Void>
    
    init(handler: @escaping CallableHandler<Void>.Handler) {
        _handler = .init(wrappedValue: CallableHandler(handler))
    }
    
    func body(content: Content) -> some View {
        content
            .environment(\.openSomething, handler)
    }
}

extension View {
    func openSomethingHandler(_ handler: @escaping () -> Void) -> some View {
        self
            .modifier(HandlerModifier(handler: handler))
    }
}

We can then use the new modifier in our content view:

CustomButton()
    .openSomethingHandler {
        print("Open clicked...")
    }

If we check the behavior now, we will notice that changing the state of the parent view does not cause a body reevaluation of our custom button, which is precisely the effect we desired.

Generalizing

The solution can, of course, be generalized to allow you to pass actions with a variable number of parameters, return types, and environment keys.

For instance, I can make my CallableHandler use parameter packs for its inputs. Further, I can generalize the modifier to be useful for any action.

struct CallableHandler<each Input, Output> {
    typealias Action = ((repeat each Input)) -> Output
    private let action: Action
    
    init(_ action: @escaping Action) {
        self.action = action
    }
    
    func callAsFunction(_ update: repeat each Input) -> Output {
        action((repeat each update))
    }
}

private struct HandlerModifier<each Input, Output>: ViewModifier {
    typealias Key = WritableKeyPath<EnvironmentValues, Handler?>
    typealias Handler = CallableHandler<repeat each Input, Output>
    
    let key: Key
    @State private var handler: Handler
    
    init(key: Key, action: @escaping Handler.Action) {
        self.key = key
        self._handler = .init(wrappedValue: CallableHandler(action))
    }
    
    func body(content: Content) -> some View {
        content
            .environment(key, handler)
    }
}

extension View {
    func environmentHandler<each Input, Output>(
        _ key: WritableKeyPath<EnvironmentValues, CallableHandler<repeat each Input, Output>?>,
        action: @escaping CallableHandler<repeat each Input, Output>.Action
    ) -> some View {
        self
            .modifier(HandlerModifier(key: key, action: action))
    }
}

We could then easily declare new actions as entries, and reuse the same modifier to pass actions down.

extension EnvironmentValues {
    @Entry var openSomething: CallableHandler<Void>?
}

struct ContentView: View {
    @State private var isHovered: Bool = false
    
    var body: some View {
        CustomButton()
            .environmentHandler(\.openSomething) {
                print("Open clicked...")
            }
    }
}

Takeaways

It feels important to reiterate that the above solution is not a silver bullet or a hack that will somehow solve all your performance problems. This solves an extremely targeted problem, and before implementing a similar system in your codebase, it’s important to understand the problem space alongside the available alternatives. And, if a simpler solution works for your particular use case, it’s almost always better to start there!

• If you’re dealing with extremely simple leaf views like Buttons, you’re likely better off simply passing the closure to it directly. It will make your code much clearer, simpler to reason about, and easier to iterate on. Of course, be aware of the tradeoffs you’ve made and reevaluate the decision if the button ever becomes more complex, if you start needing a lot of them, and / or if you start seeing a performance impact.
• If you already keep most of your business logic on some object (e.g., an instance of an Observable type that is the State of the root view of your Scene), and you don’t need any view-specific state to perform the action, adding the action as an instance method on the type and calling it directly can be the lowest overhead solution.

Even if the flexibility of passing the actions through the Environment is indeed what your use case is calling for, it can be incredibly useful to align your expectations of the behavior with what is actually happening at runtime. This can help make SwiftUI internals seem a bit less opaque and develop a more robust intuition that will undoubtedly be of use in the future.

macOS 14 and iOS 17 saw the introduction of the Observation framework and the Observable macro, allowing your SwiftUI views to automatically update in response to underlying data changing. However, that initial implementation contained really limited capabilities for consuming Observable types from outside SwiftUI.

Before macOS 26 and iOS 26

Previously, if I wanted to continuously drive updates to an AppKit or UIKit view in response to Observable changing, I’d have to use withObservationTracking, whose closure would be called on willSet of the underlying value and wasn’t continuous. So, you could end up with hacky methods that kind of worked like:

extension Observation.Observable {
    public func onChange<T>(
        of value: @escaping @autoclosure () -> T,
        execute: @escaping (T) -> Void
    ) {
        withObservationTracking {
            execute(value())
        } onChange: {
            self.onChange(of: value(), execute: execute)
        }
    }
}

You’d then do work on the next turn of the RunLoop or spin up an unstructured Task to get the new value from the updated property. Overall, it’s clear the original Observable wasn’t meant for these use cases!

New in AppKit and UIKit

On macOS 26 and iOS 26, both AppKit and UIKit have built-in support for Observable types, covering a lot of the use cases I’ve personally faced in a mixed UI framework codebase. The UIKit changes are covered in this WWDC video, while the corresponding AppKit changes weren’t explicitly mentioned. I’ll summarize both here and aim to provide some depth for the underlying implementation.

How it works

In update methods on NSViewController and NSView in AppKit, alongside UIViewController and UIView in UIKit, the framework now automatically tracks any Observable you reference, wires up dependencies, and invalidates the right views. This works via a mechanism similar to withObservationTracking, where any property you reference within the apply closure would inform the caller of value changes made to participating properties by way of the onChange closure, except, instead of an explicit apply closure, you are tracking any Observable property you’re referencing within your update methods. This eliminates the recursive call pattern from the hacky onChange handler.

For an example of how this works, consider the following snippet from the UIKit WWDC talk, which will be similar in the AppKit world as well:

@Observable final class UnreadMessagesModel {
    var showStatus: Bool
    var statusText: String
}

final class MessageListViewController: UIViewController {
    var unreadMessagesModel: UnreadMessagesModel

    var statusLabel: UILabel
    
    override func viewWillLayoutSubviews() {
        super.viewWillLayoutSubviews()

        statusLabel.alpha = unreadMessagesModel.showStatus ? 1.0 : 0.0
        statusLabel.text = unreadMessagesModel.statusText
    }
}

Because I reference the Observable properties in my viewWillLayoutSubviews implementation, they are automatically tracked. Any further change to those referenced properties invalidates the view and reruns viewWillLayoutSubviews, keeping the label in sync with the model without extra code or manual didSet hooks.

It's worth noting that this tracking is property-specific – if your UnreadMessagesModel had additional properties like messageCount or lastUpdated, but you didn't reference them in viewWillLayoutSubviews, changes to those properties wouldn't trigger layout updates.

So, which update methods participate in this new tracking behavior? While this Is not explicitly documented at the time of this writing, I’ve compiled a summary here thanks to the magic of reverse engineering.

AppKit

For NSViewController:

• updateViewConstraints
• viewWillLayout
• viewDidLayout

For NSView:

• updateConstraints
• updateLayer
• layout
• draw(_:)

UIKit

For UIViewController:

• updateViewConstraints
• viewWillLayoutSubviews
• viewDidLayoutSubviews
• updateContentUnavailableConfiguration(using:)

For UIView:

• updateConstraints
• layoutSubviews
• draw(_:)

For UITableViewHeaderFooterView, UIButton, UICollectionViewCell, UITableViewCell:

• configurationUpdateHandler

Backwards compatibility

The new Observation tracking behavior in both AppKit and UIKit is enabled by default in macOS 26 and iOS 26.

However, the related changes have actually been present in the source since prior year’s macOS 15 and iOS 18 releases – but were off by default. You can turn them on manually and get the same behavior on both OSes by adding the following keys to your Info.plist:

• For AppKit, add the NSObservationTrackingEnabled key and set its value to YES for compatibility with macOS 15.
• For UIKit, add the UIObservationTrackingEnabled key and set its value to YES for compatibility with iOS 18.

New in Swift 6.2

Swift 6.2 saw an implementation of SE-0475: Transactional Observation of Values, adding a general-purpose way to observe changes to Observable models using an AsyncSequence. This change closes the remaining gap in the ability to consume continuous changes to Observable types in arbitrary contexts not limited by the UI framework use cases.

You can create an Observations instance with a closure that accesses properties it wants to observe – a pattern familiar to Observation consumers. Subsequently, you can access the AsyncSequence directly:

let model = UnreadMessagesModel()

let statusChanges = Observations {
    model.statusText
}

for await statusText in statusChanges {
    print(“Status text is \(statusText).”)
}

The new additions across AppKit, UIKit, and Swift not only close the gaps for general-purpose Observable consumption use cases, but also make interoperability between UI frameworks vastly easier, providing more flexibility for the ways you work with Observable types. This is just one of the few changes to SDKs announced during WWDC25 with the common theme of simplifying interoperability and enhancing flexibility – and I’m here for it.

Admittedly, animation and transition techniques on macOS are not as widely applied or evolved as they may be on iOS-based platforms, and information and advice around them can be scattered and oftentimes outdated. So, let’s fix that and try to outline some best practices, as well as establish some intuition about some of the core tools available to us when working with animations.

CADisplayLink is an unavoidable component in the vast majority of in-process animation techniques. However, so much of the existing usage, both open-source and proprietary, does not consistently and correctly manage CADisplayLinks – at least on macOS.

In-process vs. Out-of-process

Before moving on to the discussion of using CADisplayLink for animations on macOS (and other platforms), it feels important to provide some background on why one might choose to use it in the first place.

Out-of-process animation techniques on both macOS and iOS involve interfacing with the render server. If you’re familiar with Core Animation (or LayerKit, if you prefer), you’ve used CABasicAnimation, CAKeyframeAnimation, or CASpringAnimation. These are all examples of out-of-process animations as they are run outside of your app’s process by committing your changes to your layers’ models and any explicit transactions you commit to the render server. While the animation is running, it does not block your app’s main thread. And, similarly, if your app’s main thread happens to get clogged during one of these animations, you will not experience frame drops within the animation itself. (You may still experience glitches in other areas of the app or when trying to modify or remove the animation.)

Sounds pretty neat, especially for simple use cases like fading a view or moving a button. And it most certainly is. However, one of the biggest limitations of the out-of-process animation techniques, and Core Animation in particular, is that the set of properties that can be animated, as well as the ways in which they can be animated, are both pre-defined and limited. You cannot extend the server’s behavior by e.g. telling it how to animate a custom color matrix on your custom Metal layer. Similarly, you cannot implement a fluid spring that is both interruptible and can preserve its velocity when interrupted using CASpringAnimation alone. These behaviors are implemented outside of your app’s process and should be viewed as immutable.

These are specifically the cases where you may want to consider an in-process animation technique. Perhaps you want a fluid spring, or a customizable decay function – or you want to interpolate between 2 custom data structures. To accomplish this, you’d implement some of the implicit render server behavior inside your app’s process. You would synchronize on the display’s (or a display’s – more on that later) refresh rate, interpolate between the source and the target value using an interpolation strategy you prefer, and at each update, or tick, of the animation, you would update the value of the animated property.

In-process animation techniques typically rely on being run on the main thread, since they need to modify main thread only properties, like anything on NSView or UIView, or risk runtime warnings and undefined behavior. There are notable exceptions, of course – for instance, if you’re okay with using SPI, you can update CALayer properties from a background thread – but I’ll leave that discussion outside the scope of this post. As anything that is run on the main thread, these animations will be subject to resource contention with UI framework code and your own work that is being done on the main thread. If anything is blocking the main thread and you happen to miss the commit deadline, you will start seeing frame drops. And, now that is on you to handle, since you’re owning the animation stack. How fun!

CADisplayLink

Until macOS 14, CADisplayLink was unavailable on macOS, and the majority of clients implementing in-process animations and transitions used the CVDisplayLink family of APIs. These were in principle the same, having the same goal, which was to allow running callbacks in sync with the display. Some typical code to get started with receiving callbacks you’d see would be something like:

CVDisplayLinkCreateWithActiveCGDisplays(&displayLink)
CVDisplayLinkSetOutputHandler(displayLink!) { (_, _, _, _, _) -> CVReturn in
    animationStep()
    return kCVReturnSuccess
}
CVDisplayLinkStart(displayLink!)

Similarly, for a CADisplayLink with an Objective-C API surface you’d see something like:

let displayLink = CADisplayLink(target: target, selector: selector)
displayLink?.preferredFramesPerSecond = Config.preferredFramesPerSecond
displayLink?.add(to: .main, forMode: .common)
displayLink?.isPaused = false

In the vast majority of use cases I’ve seen, like the ones above, the handling of both CVDisplayLink and CADisplayLink is incomplete and therefore the animation strategies can be fundamentally flawed in certain scenarios. That FPS is hard coded!

In a better, but still very much flawed, scenario, you might see something more sane like using UIScreen.main.maximumFramesPerSecond (with CADisableMinimumFrameDuration Info.plist key) on iOS.

But now, for instance, imagine I’m driving a 60 Hz external display with an iPad Pro or a MacBook Pro. You can imagine much more complicated external display use cases, especially on macOS, and especially when you consider other cases like Screen Mirroring or Sidecar, which demand these updates to happen dynamically even for the same display identities. Neither of the techniques above would correctly handle even the simplest case of switching between displays, let alone some of the more conceptually complicated use cases.

Ultimately, when you want to run an animation that smoothly runs on whatever display may be connected with the maximum possible refresh rate, you have to have the following considerations in mind:

• Multiple displays with varying refresh rates may be connected at any given time.
• The refresh rate of any display can change at any point while a display link is running.
• A window in which something is being animated may be moved to another display, which may have a different refresh rate compared to the original.
• A view in which something is being animated may be reparented and moved to a different window, potentially on a different display, which may, again, have a different refresh rate.
• A view (or a window) you’re animating may leave a display while the animation is running, in which case you should suspend your display link, and resume it when the animated object appears on some display again.

AppKit to the rescue

macOS 14.0 saw the deprecation of CVDisplayLink family of APIs in favor of the new AppKit methods: displayLink(target:selector:) which exist on NSView, NSWindow, and NSScreen instances. These methods vend an opaque CADisplayLink, which you can customize if you wish but don’t have to. You can simply call

displayLink.add(to: .current, forMode: .common)

And start receiving callbacks on the target you’ve specified.

These AppKit-managed display links (backed by an internal _NSDisplayLink class) will handle two very important cases:

• It will track which display your view, window, or screen belongs to, and adjust the refresh rate of the display link accordingly.
• It will automatically suspend itself if the view or window isn’t on a display.

This gives you the complete set of tools you may need in order to handle all of the cases I’ve outlined above, and therefore to achieve animations that run as smoothly as possible on whichever display they may be running on at any given time. Of course, you may still choose to manage your display link directly (though I certainly wouldn’t recommend it if you’re targeting macOS), in which case the conceptual understanding of the variables at play will be incredibly helpful in making sure your implementation handles more than just the single most obvious use case out there.

More to consider

Once you’ve figured out your display link creation and management, it’s time to actually run your animation or transition. While interpolation techniques and ways to handle retargeting or spring physics are intentionally out of scope of this post (or any single post, for that matter) to preserve its focus, there are a few more things one must consider that are direct consequences of the variable refresh rates.

First and foremost, the duration of your frame is not TimeInterval(1 / 60) – and never has been. Once we’ve taken the time to understand display links and moved away from hard coding FPS, we must make similar adjustments to our code elsewhere. Luckily, the CADisplayLink object we’re working with provides 3 helpful properties: timestamp, duration, and targetTimestamp. Understanding the difference between these is crucial to make sure your interpolations are correct and consistent across displays.

• timestamp represents the TimeInterval when the last frame was displayed.
• targetTimestamp is the time when the next frame is scheduled the display. When you get a callback from the display link and need to calculate the interpolation step of your animation, this is what you need to use – not timestamp, since your job within that callback is calculating what to display next.
• duration is the interval between display updates. If you’d like to query it, note that it will only be guaranteed to be valid within the display link callbacks.

In combination with CACurrentMediaTime(), these properties provide the complete information about display updates that may be needed in order to calculate the interpolating values for your animations and transitions.

I was working on porting one of my side project apps from macOS to visionOS, and at some point wanted to test it against the newly released visionOS 2.4. What I found was my app, which I hadn’t touched in any substantial way since the previous release, was very close to unusable. I observed the following symptoms. Images and text seemed overexposed, as if multiple copies had been layered on top of one another. Once I tried scrolling in the main scroll view, that proved to be the case. There was an actual copy of the view hierarchy in its initial state behind the interactive portion of the view.

The result was comical but concerning. Had I done something wrong? Had I accidentally regressed the functionality? (I had never ever done that before, of course!)

It turns out, the same symptoms were reproducible in any document-based app, even the one created from the Xcode template. It reproduced on both the physical device and the simulator running visionOS 2.4. The regression wasn’t mine, it’s Apple’s!

After contemplating whether anyone had bothered to test document-based apps before the public visionOS 2.4 release, and making a few initial hypotheses about what could’ve happened based on my first-hand familiarity with Apple’s engineering processes, I realized that things were not looking good for being able to test my app on my shiny Vision Pro.

Debugging

I made a sample document-based app from the Xcode template, built it, and ran it on a device running visionOS 2.4. So, this wasn’t anything about the app itself; in fact, it seems like any document-based app is suffering the same fate. Multiple copies of my content stacked on top of each other, creating that distinctive “overexposed” look, and scrolling the content produced the same duplication, as if multiple copies of my view hierarchy were stacked on top of one another. I tried removing scrollable content from the equation. The issue still reproduced. I then tried a non-document-based app, and the issue was gone.

With that preliminary investigation out of the way, I needed to understand what was happening under the hood. My initial hypothesis was that root SwiftUI views were being added to the hierarchy multiple times, and were never removed, which produced both the overexposed look (due to plusLighter blending liberally used throughout visionOS) and the duplication effect during scrolling.

To get a better intuition and visibility into what was going on, the next step was to set a breakpoint on init of the root view.

init(document: Binding<MaterialBugDocument>) {
    self._document = document
}

The first 2 times, we were called with the following UIKit symbols in the stack trace:

#49 0x0000000185227bc8 in -[UIPresentationController _sendWillDismiss] ()
#50 0x0000000185227a2c in -[UIPresentationController _sendDismissalsAsNeeded] ()
#51 0x0000000185df8f60 in -[UIDocumentViewControllerLaunchOptions _dismissBrowserViewController] ()
#52 0x0000000185df7e60 in -[UIDocumentViewControllerLaunchOptions _documentCloseStateDidChange] ()
#53 0x00000001855ad6e8 in -[UIDocumentViewController _documentStateChanged:] ()

The third (and final) time, it was something more intuitively expected:

#44 0x00000001860145cc in -[UIView _postMovedFromSuperview:] ()
#45 0x00000001860210c8 in -[UIView(Internal) _addSubview:positioned:relativeTo:] ()
#46 0x00000001d41e0434 in __C.UIDocumentViewController.embedDocumentHostingController(Swift.Optional<__C.UIViewController>) -> () ()
#47 0x00000001d41ea340 in merged SwiftUI.DocumentViewController.documentDidOpen() -> () ()
#48 0x00000001d41df80c in @objc SwiftUI.DocumentViewController.documentDidOpen() -> () ()
#49 0x00000001855aca24 in __62-[UIDocumentViewController openDocumentWithCompletionHandler:]_block_invoke_4 ()

The SwiftUI view being created, of course, doesn’t mean much by itself – a View is a transient object, after all, and is instantiated by SwiftUI machinery many times throughout the lifecycle, driven by graph updates. However, given the symptoms and the above, I suspected that the hosting view the above calls produced was actually added to the view hierarchy each time, and was never removed.

To sanity check myself, I added some basic instrumentation to track view lifecycle events:

.onAppear {
    print("View appeared.")
}
.onDisappear {
    print("View disappeared.")
}

The output was revealing: onAppear was called three times per document, while onDisappear wasn't called at all. So, in addition to providing strong evidence to the initial intuition, this seemed to indicate the SwiftUI view hierarchy wasn't just duplicated – it was triplicated. For every one view I intended to show, the visionOS 2.4 SDK was creating three! How very generous.

Diving Deeper

I wanted to understand what exactly was going on and hopefully fix it – on my own timeline. As the next step, I wrote a quick utility method to print the entire view hierarchy:

func printViewHierarchy(level: Int = 0) {
    let indent = String(repeating: "  ", count: level)
    let className = "\(type(of: self))"
    
    print("\(indent)• \(className): frame=\(frame)")
    
    // Print specific properties for common control types
    if let label = self as? UILabel {
        print("\(indent)  text: \"\(label.text ?? "nil")\"")
    }
    // ... other control-specific info
    
    // Recursively print subviews
    for subview in self.subviews {
        subview.printViewHierarchy(level: level + 1)
    }
}

let scenes = UIApplication.shared.connectedScenes.first as? UIWindowScene
let window = scenes?.windows.first
window?.rootViewController?.view.printViewHierarchy()

Running this on the main window’s root view controller’s view after it had appeared yielded the following output (I took the liberty to truncate it to make it easier to parse):

• UILayoutContainerView: frame=(0.0, 0.0, 1280.0, 720.0), tag=0, accessibilityID=nil
  • UINavigationTransitionView: frame=(0.0, 0.0, 1280.0, 720.0), tag=0, accessibilityID=nil
    • UIViewControllerWrapperView: frame=(0.0, 0.0, 1280.0, 720.0), tag=0, accessibilityID=nil
      • UIView: frame=(0.0, 0.0, 1280.0, 720.0), tag=0, accessibilityID=nil
        • _UIHostingView<ModifiedContent<ModifiedContent<AnyView, DocumentSceneRootBoxModifier>, DocumentBaseModifier>>: frame=(0.0, 0.0, 0.0, 0.0), tag=0, accessibilityID=nil
          <...>
        • _UIHostingView<ModifiedContent<ModifiedContent<AnyView, DocumentSceneRootBoxModifier>, DocumentBaseModifier>>: frame=(0.0, 0.0, 0.0, 0.0), tag=0, accessibilityID=nil
          <...>
        • _UIHostingView<ModifiedContent<ModifiedContent<AnyView, DocumentSceneRootBoxModifier>, DocumentBaseModifier>>: frame=(0.0, 0.0, 0.0, 0.0), tag=0, accessibilityID=nil
          <...>
  • UIKitNavigationBar: frame=(0.0, 0.0, 1280.0, 92.0), tag=0, accessibilityID=nil
    <...>

And here is the smoking gun: three identical sibling instances of _UIHostingView were being created for each document window.

Looking at the hierarchy output, I noticed that these extra views were identical siblings – same class, same parent view, same everything. This gave me an idea for a surgical workaround: scan the view hierarchy for groups of sibling views with the same class name that contains "_UIHostingView", and remove all but the last one of them. If this works, I’ll at least be able to test the application on the new visionOS without it being completely broken.

I crafted a utility extension that does exactly this:

extension UIView {
    /// Removes redundant sibling view instances of the same class
    /// containing the provided substring in their class name,
    /// keeping only one instance per group of sibling views.
    func cleanupRedundantViews(withClassNameContaining classNameSubstring: String) {
        func processViewGroup(_ viewGroup: [UIView]) {
            // Group sibling views by their class name
            var viewsByClassName: [String: [UIView]] = [:]
            
            for view in viewGroup {
                let className = NSStringFromClass(type(of: view))
                if className.contains(classNameSubstring) {
                    viewsByClassName[className, default: []].append(view)
                }
                
                // Recursively process this view's children
                processViewGroup(view.subviews)
            }
            
            // For each group of same-class views, keep only one
            for (_, views) in viewsByClassName where views.count > 1 {
                // Keep the last one, remove the rest
                for view in views.dropLast() {
                    view.removeFromSuperview()
                    print("Removing \(view)...")
                }
            }
        }
        
        // Start with the root view's immediate subviews
        processViewGroup(self.subviews)
    }
}

With this utility in hand, I could now apply it when the view appears:

.onAppear {
    let scenes = UIApplication.shared.connectedScenes.first as? UIWindowScene
    let window = scenes?.windows.first
    
    window?.rootViewController?.view.cleanupRedundantViews(withClassNameContaining: "_UIHostingView")
}

I ran the app again, and... success! The redundant views were removed, leaving only one instance of each view. The SwiftUI views were also cleaned up correctly, and the disappear handler ran as expected. But, most importantly, the app was usable again, with proper rendering and scrolling behavior.

The Aftermath

I've posted the sample project, which includes the bug as well as the aforementioned hacky workaround, here: https://github.com/philptr/SwiftUIDocumentBasedBug. This workaround isn’t perfect. It's a hack that shouldn’t be necessary, and it comes with some limitations. The real fix, of course, needs to be originated by Apple (I have reported it as FB17146267).

Whatever the cause, this is a clear reminder that it’s much easier to regress something you aren’t using yourself. The SwiftUI document-based app architecture is notoriously pretty limited and oftentimes feels underpowered next to their Kit counterparts, NSDocument and UIDocument. Given how forcibly lightweight and thus underpowered this initial architecture is, it is completely unsurprising that none of Apple’s first-party apps on visionOS adopt the SwiftUI document-based architecture. It is therefore even less surprising (though, of course, pretty upsetting) that a bug like this one was not caught in testing passes, during the dogfooding process, or throughout the Seed cycle.

Whatever the present issues may be, I remain excited and hopeful for SwiftUI’s future, which includes the document-based architecture, among many other things. After all, it is perhaps the only light at the end of the tunnel that can save native development on Apple platforms at this point, and the best way for third-party developers like myself to do our part is by providing feedback.

While working on a behavior that required dynamically switching between the nonactivating panel behavior and one that is more similar to the regular window behavior, I discovered a subtle but significant issue in AppKit: changing the NSWindowStyleMaskNonactivatingPanel flag after an NSPanel has been initialized doesn't fully update the window's activation behavior the way the API contract seems to suggest.

This creates a perplexing situation where changing a window's style mask – something the API suggests should be fully supported – results in inconsistent window behavior that can be difficult to diagnose, and is certainly hard to reason about without fully understanding the window behavior on macOS, including WindowServer window tags.

Understanding Nonactivating Panels

The nonactivating panel behavior, which is canonically only valid for subclasses of NSPanel, not NSWindow, allows the window that declares itself as a nonactivating panel to be sent and handle key events without activating the owning application. In other words, you will be able to type into a nonactivating panel and do everything you’d be able to do with a key window in an active application, but the application itself will not become “active.” Among other things, this will cause it to not acquire the menu bar.

The nonactivating panel behavior is useful for utility panels, inspector windows, and other elements that shouldn't disrupt the user's current context. This can be achieved by either overriding _isNonactivatingPanel instance method and returning YES, or setting the NSWindowStyleMaskNonactivatingPanel style mask flag.

A Deeper Dive

Before a key event on macOS is routed to the client process and ultimately lands in NSApplication, it is dequeued from the hardware and is routed by WindowServer. The server ultimately maintains and owns key aspects of the truth about the window positioning, order, which process currently shows the menu bar, and the active application state. Each window, in addition to things like geometry, has a set of tags, which determine its behavior.

When you click on a window, what happens in most cases – unless you perform a nonactivating click by holding Command, for example – is that the application will be made active. That means that it will start receiving key events by default. However, one of the aforementioned window tags, kCGSPreventsActivationTagBit, dictates that performing a canonically activating action on a window that has this tag will not activate the application that owns it.

How does the application get the key events in this state then? When a window is nonactivating,

1. The window will be drawn as key by the application (the process managed by AppKit), but
2. The application will not be considered active and will not own the menu bar. In other words, the previously active application will still be active.

How is it not the case that the application can receive the key events then? While a nonactivating panel is key, the application will “steal key focus” from the true active application, through a process referred to as key focus theft, managed by the CoreProcesses subsystem of the WindowServer (abbreviated as CPS). The client process will make a call to -[NSApplication _stealKeyFocusWithOptions:], which will ultimately funnel down to CPSStealKeyFocusReturningID and IPC over to the server-side code that will alter the focus stack.

Likewise, when it’s time to restore the normal behavior, -[NSApplication _releaseKeyFocus] will be called and will funnel down to CPSReleaseKeyFocusWithID. Note the use of ID in both routines, which helps maintain the correctness of the focus stack.

Reproducing the Bug

I created a minimal reproduction case to demonstrate the issue. The full code is available at https://github.com/philptr/NonactivatingPanelBug.

The sample app has:

• A panel that starts as nonactivating
• A button to toggle the nonactivating state
• A text field for testing keyboard input

When you run this application and:

1. Launch the app (which creates a nonactivating panel),
2. Switch to another application,
3. Click the "Toggle Nonactivating Panel Bit" button to make it a regular window,
4. Click on the panel;

You'll observe the following unexpected behavior:

• The panel's appearance changes correctly (gaining a title bar and close button);
• The panel shows visual indication that it has keyboard focus, i.e. will draw as key;
• BUT typing into the text field won’t work!

The Root Cause

After investigation, I determined that the issue stems from how NSPanel manages window server tags:

1. During initialization, NSPanel calls an internal method -_setPreventsActivation: to set the kCGSPreventsActivationTagBit window tag when the nonactivating style mask bit is present.
2. When you change the style mask later during the lifetime of the panel instance via -setStyleMask:, it doesn't call -_setPreventsActivation: again to update this window tag.

Based on the way things work under the hood that we’ve established above, we can gain pretty good insight into what is actually going on. The bug occurs due to a mismatch:

• The framework thinks the panel is a regular window (because the style mask no longer includes NSWindowStyleMaskNonactivatingPanel).
• The WindowServer still treats it as nonactivating (because the window tag remains set).

Since the panel doesn’t have the NSWindowStyleMaskNonactivatingPanel bit in its style mask anymore, its -_isNonactivatingPanel returns NO, and the application will not steal key focus for it when it is supposed to become key. However, mousing down on the window will also not make the application frontmost, because we’ve never removed the kCGSAvoidsActivationTagBit. As a result, the window will appear key, since that is the behavior managed by AppKit, but will not be receiving key events.

Reverse Engineering the Behavior

Discovering the root cause required investigating how AppKit interacts with the WindowServer. Here's the outline of a process one could use to reverse engineer this or similar behavior:

Symbolic Breakpoints are Your Friends

You could use LLDB to trace method calls when setting the style mask. With the application running:

(lldb) breakpoint set -n "-[NSWindow setStyleMask:]"
(lldb) breakpoint set -n "-[NSWindow _setPreventsActivation:]"

This revealed that -_setPreventsActivation: is called during panel initialization but not when the style mask is changed. In our sample application, this is tested by clicking the button that toggles the nonactivating panel style mask bit.

Inspecting Window Server Tags

To verify my hypothesis about window server tags, you can forward declare the (private) CGSGetWindowTags routine:

CG_EXTERN CGError CGSGetWindowTags(CGSConnectionID cid, CGWindowID wid, const CGSWindowTagBit tags[2], size_t maxTagSize);

By calling this function before and after changing the style mask, one may be able to confirm that the kCGSPreventsActivationTagBit tag (value 1 << 16) indeed remains set even after removing the nonactivating style mask.

Looking at Disassembly

Finally, to confirm the hypothesis that the bug indeed stems from AppKit simply not calling the relevant method that sets the window tag on the path of changing the style mask during the lifetime of the window, you can use a tool like Hopper to find its callers, which will reveal that the only time the method is called during the lifetime of an NSPanel instance is indeed during the _panelInitCommonCode C helper routine called during the initialization.

Workaround

To work around the issue, we can implement a workaround by manually setting the prevents-activation state after changing the style mask. Please note that this requires calling into NSWindow SPI. The least invasive version of the workaround involves something like the following:

extension NSWindow {
    func updateActivationBehavior() {
        // Access private method via performSelector to update activation state.
        perform(Selector(("_setPreventsActivation:")), 
                with: NSNumber(value: styleMask.contains(.nonactivatingPanel)))
    }
}

Then you may call this method after changing the style mask:

panel.styleMask = newStyleMask
panel.updateActivationBehavior()

Some Implications

The proper fix would be for -setStyleMask: to call -_setPreventsActivation: whenever the nonactivating panel bit changes, ensuring the window tags stay in sync with the style mask.

When working with windows and panels whose behavior needs to change at runtime, be aware that some style mask changes may require additional synchronization with window server state.

The bug has been reported as FB16484811. The full code of the sample application is available at https://github.com/philptr/NonactivatingPanelBug.

Early Macintosh computers have played a huge role not just in personal computing in general, but in core areas like UI design and systems and framework engineering. Apart from these machines just being really, really cool, I have a firm belief that interacting with old technology can serve as inspiration for future innovation in the areas of HCI, frameworks, and systems engineering.

The most accessible way to interact with older Macintosh models is using emulators. Mini vMac, Basilisk II, and SheepShaver all serve a similar purpose: emulating Macintosh computers from different eras.

However, I've always found the process of setting up one of these emulators to be quite cumbersome and not user-friendly. It takes a lot of research and familiarity with software development to get started. In other words, you kind of have to be a bit of a nerd to set one up. If we want more people to discover the joy of vintage computing – and I really do – the process has to become a whole lot more refined and user-friendly. That's why, on and off for a few years, I've been working on a modern macOS emulation environment to make these machines more accessible to an average user.

In this (admittedly more technical) post, I'll walk through one specific aspect of that effort: the techniques for combining multiple Mini vMac emulator variations into a single universal macOS binary with a well-defined public interface.

Background

Mini vMac's architecture relies heavily on C preprocessor directives for conditional compilation. Each Macintosh model variation requires its own set of configuration headers (typically generated by the setup tool) that define hardware capabilities, screen dimensions, ROM specifications, and other model-specific features. This design choice makes sense from an emulation perspective – it allows the maintainer to optimize specifically for each model's characteristics and ensures only the necessary code paths are included.

However, this traditionally means maintaining separate application builds for each model. And, while building a more universal environment for emulating many kinds of Macintosh computers, I'd effectively have to maintain a binary at least for each of the supported models. Let's explore how we can maintain this compilation model while packaging everything into a single, more maintainable application.

The general approach will be the following:

• Automate the generation of the required header files for each of the 7 computers we want to support: 128K, 512Ke, Plus, SE, Classic, SE FDHD, and II.
• Implement the principal class that conforms to the common protocol exposed to both the universal application and each of the frameworks.
• Package each model into a framework bundle, with reused source code.
• Configure the application to dynamically load the correct framework bundle and interface with its principal class to emulate the specific machine known at runtime.

Generating Configuration for Each Model

The first challenge is generating appropriate configuration headers for each model. The general setup process using minivmac for a specific model involves building the setup tool:

gcc -o setup_t ./setup/tool.c

After that, we can use the setup tool to generate the configuration headers for the model. On macOS, that also generates the Xcode project that wraps it into an application.

./setup_t -e xcd -t mcar -sound 1 -drives 20 -sony-sum 1 -sony-tag 1 -sony-dc42 1 -speed z > generate_xcodeproj.sh
bash ./generate_xcodeproj.sh

For the purposes of generating a single application that encapsulates multiple conditionally compiled models, we don't really care about the generated Xcode project, and only want the headers.

Ideally, this process can be automated for each of the models we want to support. So, I have written the setup.sh script that defines the 6 Macintosh models and goes through the process of building the configuration for each one. It then takes only the generated headers and puts them into Configuration folder, removing the other artifacts. What we're left with is 6 directories for each of the Macintosh models, and the unmodified minivmac source.

The script will also include our custom additions for dynamic loading. We'll define a unique principal class name and the display name for each of the frameworks, like so:

// Custom configuration for Macintosh 128K:
#define MMPrincipalClassName Macintosh128KEmulatorVariation
#define MMDisplayName Macintosh 128K

Framework Architecture

Each model variation is compiled as a separate framework. The key is that all frameworks:

1. Share the same Mini vMac source code;
2. Use model-specific configuration headers;
3. Conform to a common protocol.

Here's our base protocol:

@protocol EmulatorVariation <NSObject>

- (instancetype)initWithROMAtPath:(NSString *)path;
- (void)start;
- (BOOL)insertDiskAtPath:(NSString *)path;

@end

We will then define a common implementation file that will be reused across each of the frameworks.

Setting up the .m File

Now let's build the single implementation that we'll reuse across our targets. This is the single case in the entire architecture where we won't use the minivmac source verbatim, instead customizing it and adding a wrapper class.

1. Locate the OSGLUCCO.m implementation file and copy its contents into our MacintoshVariation.m file (the name is arbitrary; feel free to come up with something better).
2. Define the principal class. Note how we'll use the #define key.

#import "EmulatorVariation.h"

NSString *_ROMFilePath;

NS_ASSUME_NONNULL_BEGIN

@interface MMPrincipalClassName : NSObject <EmulatorVariation>

@end

NS_ASSUME_NONNULL_END

Note how we're using MMPrincipalClassName to define the principal class. This will be replaced with the value we defined earlier, resulting in a unique principal class name for each of the generated frameworks. This also allows us to share the same source code, including the .m file, across all of the implementations, without the need to write any target specific code.

1. Implement the wrapper.

@implementation MMPrincipalClassName

- (instancetype)initWithROMAtPath:(NSString *)path {
    if (self = [super init]) {
        _ROMFilePath = path;
    }
    return self;
}

- (void)start {
    ZapOSGLUVars();
    
    if (InitOSGLU()) {
        ProgramMain();
    }
    UnInitOSGLU();
}

- (BOOL)insertDiskAtPath:(NSString *)path {
    return Sony_Insert1(path.stringByStandardizingPath, false);
}

@end

2. Remove the application initialization code.

Since we'll initialize the emulator from an existing NSApplication, we don't need to do that setup again, so simply remove it.

From InitCocoaStuff, we'll remove the following line:

[MyNSApp run];

Xcode Build Settings Setup

Let's outline how to create an individual framework target.

We have already created the EmulatorVariation protocol definition. This will be exposed to both the top-level application and each of the framework targets.

Next, let's create the template Info.plist that will be preprocessed by each of the frameworks. I've called it Variation-Info.plist. This is where we'll make use of our MM-prefixed #defines.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>en</string>
    <key>CFBundleDisplayName</key>
    <string>MMDisplayName</string>
    <key>CFBundleExecutable</key>
    <string>$(EXECUTABLE_NAME)</string>
    <key>CFBundleGetInfoString</key>
    <string>MMDisplayName</string>
    <key>CFBundleIdentifier</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundleName</key>
    <string>$(PRODUCT_NAME)</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
    <key>CFBundleSignature</key>
    <string>????</string>
    <key>CFBundleVersion</key>
    <string>$(CURRENT_PROJECT_VERSION)</string>
    <key>NSPrincipalClass</key>
    <string>MMPrincipalClassName</string>
</dict>
</plist>

Now, let's actually create a framework target, making sure to name it in the same way we named the corresponding Configuration subdirectory, for example "Macintosh 128K." We'll now have to do a few things in the new target's Build Settings.

1. Set up Info.plist preprocessing to replace those template values. Use the newly created header and the target-specific header containing the corresponding #defines for preprocessing. Finally, enable preprocessing.

INFOPLIST_FILE = $(SRCROOT)/Mini vMac/Emulators/Variation-Info.plist
INFOPLIST_PREFIX_HEADER = $(SRCROOT)/Configuration/$(PRODUCT_NAME)/CNFUDALL.h
INFOPLIST_PREPROCESS = YES

2. Disable ARC.

CLANG_ENABLE_OBJC_ARC = NO

3. Limit header search paths to those required for the target.

This is a subtle step: the target will compile without it, but with default search paths, you won't end up using the target-specific headers you want; instead, we'll always pick up whichever ones we find first – in my case, ones in Configuration/Macintosh 128K. So, without this step, we'll accidentally end up with 7 emulators for Macintosh 128K.

The first step here is simple: disable header maps.

Then, we must customize User Header Search Paths.

• "$(SRCROOT)/Configuration/$(PRODUCT_NAME)" will pick up the configuration specific headers we have generated.
• ""$(SRCROOT)/Submodules/minivmac/src" will find the headers from the minivmac source.
• "$(SRCROOT)/Mini vMac" will pick up our protocol definition.

In total, after step 3, we'll have:

USER_HEADER_SEARCH_PATHS = "$(SRCROOT)/Configuration/$(PRODUCT_NAME)" "$(SRCROOT)/Submodules/minivmac/src" "$(SRCROOT)/Mini vMac"
USE_HEADERMAP = NO

Build Phases

Let's setup the build phases for our framework.

1. Make sure to include the 3 CNFUD-prefixed headers from the corresponding configuration subfolder.

2. In Compile Sources, add the required minivmac sources and our .m file that contains the principal class we had defined earlier.

Generating the Rest

To generate the rest of the frameworks, you can simply duplicate the target. You'll need to customize the name, bundle identifier, and redo the Build Phases step, but all of the Build Settings will carry over automatically in the process.

Universal Application Design

The application will need to include all of the individual frameworks, ideally without loading them. Ideally, we can go to the Build Phases tab and:

1. Add a new Copy Files phase.
2. Change the Destination to Frameworks.
3. Add all of the frameworks.

This will copy the frameworks into the Private Frameworks folder in our application's bundle.

Next, we will dynamically load the appropriate framework based on launch arguments. We use Swift's ArgumentParser for clean argument handling. In a more sophisticated implementation, this may be determined automatically by verifying the checksum of the supplied ROM file, and / or allow for a GUI based configuration by the user at runtime.

struct AppArguments: ParsableCommand {
    @Option(name: .customLong("emulator", withSingleDash: true))
    var emulatorName: String
    
    @Option(name: .customLong("rom", withSingleDash: true))
    var romPath: String
    
    @Option(name: .customLong("disks", withSingleDash: true))
    var disks: [String]
}

The application delegate handles framework loading and emulator initialization:

@NSApplicationMain
final class AppDelegate: NSObject, NSApplicationDelegate {
    func applicationDidFinishLaunching(_ aNotification: Notification) {
        let arguments = AppArguments.parseOrExit()
        
        // Dynamic framework loading code...
    }
}

Framework Loading and Initialization

The framework loading process is particularly interesting:

1. We locate the framework in the application bundle.
2. Load it dynamically.
3. Access the principal class (our emulator variation).
4. Initialize the emulator with the provided ROM.

guard let frameworksURL = Bundle.main.privateFrameworksURL,
      let urls = Bundle.urls(forResourcesWithExtension: nil, subdirectory: nil, in: frameworksURL) else {
    fatalError("Could not find the private frameworks URL for the main bundle.")
}

let bundles = urls
    .filter { $0.deletingPathExtension().lastPathComponent == arguments.emulatorName }
    .compactMap { Bundle(url: $0) }

guard let bundle = bundles.first else {
    fatalError("Could not load an emulator bundle for name '\(arguments.emulatorName)'.")
}

try! bundle.loadAndReturnError()

Of course, for any production code, we should handle the above errors more gracefully!

Building and Running

To test our implementation, I'll use Xcode's Scheme editor to pass the app arguments and emulate the Macintosh 128K with System 1.0 on board.

I've called the project minivmac-universal, and made all code available on GitHub. I intend to use this technique to continue building my universal user-friendly vintage Macintosh environment, and will hopefully share more progress and details soon.

In its current version, the environment maintains various emulators (like Mini vMac, Basilisk II, and SheepShaver) as embedded executables, which are managed using NSTask. Upon launch, each uses injected code to host its windows in the parent process using some SPI (private API) tricks that I will not share. This technique will allow me to run all of the emulators in-process instead, which will simplify event handling and layer hosting, and allow for better code reuse and faster iteration on user-facing features.

Further Reading

If you're not very familiar with vintage Mac emulation, I highly recommend reading A Guide to Legacy Mac Emulators.

In addition, when working with Mini vMac, it can be useful to familiarize yourself with the Control Mode and Options for Developers.

Finally, the minivmac source is always a fascinating read.

Swift 6 language mode promises compile-time stricter concurrency checking, aimed at preventing and eliminating data races, runtime memory corruption, as well as other common but hard to debug issues. While adopting the new language mode can be a bit of a challenge for larger or less modular projects, Swift 6 is an obvious choice for new targets.

However, it is worth noting that Swift 6 language mode also includes new runtime checks and can make some of the existing checks more aggressive. Many of them become preemptive assertions rather than silent failures. Surprisingly, this can lead to hard to reproduce occasional runtime crashes in production when interacting with common first-party modules like SwiftUI and AppKit.

SwiftUI Runtime Crashes

Incorrect threading that violates the concurrency declarations of these frameworks may therefore cause runtime crashes in your applications. One such example is the new SwiftUI onGeometryChange modifier, which I wrote about in some detail as part of an earlier post.

Here is an excerpt of a stack trace of one of these crashes captured by an analytics platform:

Thread 3 Crashed::  Dispatch queue: com.apple.SwiftUI.DisplayLink
0   libdispatch.dylib                      0x190b379c0 _dispatch_assert_queue_fail + 120
1   libdispatch.dylib                      0x190b37948 dispatch_assert_queue + 196
2   libswift_Concurrency.dylib             0x2712f2e08 swift_task_isCurrentExecutorImpl(swift::SerialExecutorRef) + 284
3   SomeApp                            0x102262edc 0x102260000 + 11996
4   SwiftUI                                0x1bffd8748 _GeometryActionModifier.value(geometry:) + 28
5   SwiftUI                                0x1bffdc268 partial apply for closure #1 in GeometryActionBinder.updateValue() + 52
6   SwiftUICore                            0x2303feae0 partial apply for closure #1 in _withObservation<A>(do:) + 48
7   SwiftUICore                            0x2303fd214 closure #1 in _withObservation<A>(do:)partial apply + 16
8   SwiftUICore                            0x23046d5ec withUnsafeMutablePointer<A, B, C>(to:_:) + 160
9   SwiftUICore                            0x2303fc664 StatefulRule.withObservation<A>(do:) + 872
10  SwiftUICore                            0x2303fc264 StatefulRule.withObservation<A>(do:) + 72

The onGeometryChange modifier contains a closure that is implicitly non-Sendable. This means the closure is expected to execute on the main thread. However, in some cases SwiftUI ends up calling it on a non-main thread, or, in this case, com.apple.SwiftUI.DisplayLink.

The tricky part in diagnosing an issue like this is that it may not be reproducible on demand and may depend on the device, platform, and the larger context, such as the load of the system. It's entirely possible to go through all stages of testing and end up shipping this runtime crash to production.

You might also think you can fix this issue by immediately dispatching to the main thread, using either DispatchQueue or a MainActor annotated Task:

contentView
    .onGeometryChange(for: CGSize.self, of: \.size) { value in
        DispatchQueue.main.async {
            // Do some work here.
        }
    } 

However, this will still cause the assertion to trigger, as the check happens on the closure executed by SwiftUI, not the one inside the async block you provided.

This situation happens when the imported module has not adopted strict concurrency yet and / or has not annotated its API with correct sendability expectations. In this case, the closure is likely expected to be Sendable but is not correctly marked as such, which leads the runtime to assume it is implicitly not Sendable.

The exact case is outlined in the official Swift 6 Migration Guide.

The sendability of a closure affects how the compiler infers isolation for its body. A callback closure that actually does cross isolation boundaries but is missing a Sendable annotation violates a critical invariant of the concurrency system.

The fix, until the imported module annotates the API it vends, is to manually annotated the closure you provide with @Sendable, like so:

contentView
    .onGeometryChange(for: CGSize.self, of: \.size) { @Sendable value in // This is now sendable!
        // Do some work or dispatch to main queue.
    } 

Adding this annotation will have the effect of leading the compiler to assume the closure's body is nonisolated, which may lead to some new compile-time errors. So, depending on the use case, you might have to also dispatch to the main thread after all. But, this is much better than randomly crashing at runtime in production, isn't it?

Actor Isolation and AppKit

But, SwiftUI users aren't the only victims of this nasty behavior. Even if you are using a battle tested framework like AppKit, you are not exempt. Let's look at a crash of the same nature, but this time without SwiftUI involvement:

* thread #5, queue = 'com.apple.root.default-qos', stop reason = EXC_BREAKPOINT (code=1, subcode=0x1004f8a5c)
  * frame #0: 0x00000001004f8a5c libdispatch.dylib`_dispatch_assert_queue_fail + 120
    frame #1: 0x00000001004f89e4 libdispatch.dylib`dispatch_assert_queue + 196
    frame #2: 0x0000000275bd293c libswift_Concurrency.dylib`swift_task_isCurrentExecutorImpl(swift::SerialExecutorRef) + 280
    frame #3: 0x0000000275b78588 libswift_Concurrency.dylib`Swift._checkExpectedExecutor(_filenameStart: Builtin.RawPointer, _filenameLength: Builtin.Word, _filenameIsASCII: Builtin.Int1, _line: Builtin.Word, _executor: Builtin.Executor) -> () + 60
    frame #4: 0x0000000108922788 MyApp.debug.dylib`@objc static FileDocument.autosavesInPlace.getter at <compiler-generated>:0
    frame #5: 0x00000001a2f7d780 AppKit`-[NSDocument(NSDocument_Versioning) _preserveContentsIfNecessaryAfterWriting:toURL:forSaveOperation:version:error:] + 92
    frame #6: 0x00000001a2fe6d1c AppKit`__85-[NSDocument(NSDocumentSaving) _saveToURL:ofType:forSaveOperation:completionHandler:]_block_invoke_2.398 + 116

In this case, as the Swift Forums user reports, there is no closure involved. Instead, there is an NSDocument subclass annotated with MainActor. When a type is annotated MainActor, its members are expected to execute on the main actor, unless annotated as nonisolated, which voids the inherited isolation. AppKit, as a largely Objective-C framework, is not aware of these tricks. In many cases, it assumes your subclass is a normal Objective-C class, all assertions in which are either triggered by you, the client, or AppKit's internals. Therefore, it reserves the right to manage concurrency as it sees fit, invoking the members of your subclass from whatever thread necessary.

In this case, the issue may be much easier to debug, however, since the thread on which AppKit invokes the members of your subclass is much more likely to be deterministic than in the case of the AttributeGraph driven SwiftUI. Once you hit the issue, the answer would then be to annotate the problematic member with nonisolated, optionally filing a Radar with Apple requesting them to fix the Swift overlay, and moving on.

Conclusion

When you hit a runtime crash in the Swift 6 language mode, you may get lucky and hit it during the debugging process, or receive it as an angry crash report from your users. In either case, you will be much better prepared to diagnose and fix the problem if you are familiar with the Swift concurrency system and, perhaps more importantly in this context, the migration guide.

When I first wrote PZCircularControl in 2019, SwiftUI was still in its early days. The framework has matured significantly since then, introducing new features that enable interactions that were previously only achievable by dropping down to the Kits. Recently, I revisited the codebase and decided that a complete refactor of both the API surface and the implementation was overdue.

Original API

The original implementation had several issues that made it less than suitable for modern SwiftUI.

For example, the original API contract required three generic type parameters for styling (InnerBackgroundType, OuterBackgroundType, TintType), which limited composition – the cornerstone of all SwiftUI API design. We also used a PZCircularControlParams class to configure the control. While the configuration object pattern is common in AppKit and UIKit, it doesn't take advantage of SwiftUI's declarative nature.

Despite the name, the control was also initially designed to serve display purposes only, and was not directly interactive or editable by the user, unless the developer chose to extend it. With the refactor, there was an opportunity to change this and offer a built-in capability for the user to interactively edit the value.

Redesigning the API

The new API prioritizes ergonomics and SwiftUI idioms while maintaining and oftentimes improving flexibility.

You can declare a simple read-only version of the control in a single trivial line of code.

// A simple example of the display-only version of the control.
CircularControl(progress: 0.4)

But you can now also declare the control to be editable, and allow the users to drag the knob on the control to change its value live. This works on iOS, macOS – and now also visionOS.

// A more advanced example of the editable circular control. 
CircularControl(
    progress: $value,
    strokeWidth: 15,
    style: .init(
        track: Color.secondary.opacity(0.2),
        progress: LinearGradient(colors: [.blue, .purple])
    )
) {
    CustomLabel()
}

CircularControl is now generic over the shape styles its contents, as well as the label, which lets us shed the wrapping types and rely more heavily on Swift's type system and type inference.

public struct CircularControlStyle<Track: ShapeStyle, Progress: ShapeStyle, Knob: ShapeStyle> {
    let track: Track
    let progress: Progress
    let knob: Knob
}

The label can be customized just like the content of any other view via ViewBuilder. Editing capabilities are built-in, along with the native support for Binding-based configuration.

Interactive Control

The most interesting technical challenge was likely implementing the interactive control, the behavior of dragging along the circular path, and handling the various edge cases of how the user might interact with the knob across the various supported platforms.

Interaction Model

The interactive version of the new control has a knob that travels between the start and the end points. The user can drag it along the circular track. The developer may also customize whether the knob will wrap around the track when dragged beyond either the start or the end point.

The circular control's interactive behavior relies on two key mathematical concepts:

Converting touches or clicks to angles

When the user touches the control, we need to convert their touch point into an angle. This is done by:

• Finding the relative position from the center point using atan2
• Converting the angle into a 0-1 progress value, where 1 corresponds to 2π, the maximum value.
• Adjusting for SwiftUI's coordinate system where 0° is at the top of the control and increases clockwise.

Converting back from progress to knob position is the reverse process:

let angle = Double.pi * 2 * progress - Double.pi / 2
let position = CGPoint(
    x: cos(angle) * radius,
    y: sin(angle) * radius
)

Handling the wraparound behavior

Since a circle wraps around at 2π, we need special handling when users drag across the start / end point. We detect this by comparing the change in angle – if it's too large in magnitude, we know the user has crossed the boundary. For example, when the user drags the control's knob in the increasing direction and crosses the end point, the computed angle delta will be negative and close to 1 in magnitude, despite the positive direction of travel.

Modern SwiftUI

The new @Entry macro, introduced at WWDC 2024, has greatly reduced the boilerplate of declaring new EnvironmentValues.

extension EnvironmentValues {
    @Entry public var circularControlAllowsWrapping: Bool = false
    @Entry public var circularControlKnobScale: CGFloat = 1.4
}

The complete implementation is available on GitHub.

NSDrawer is undoubtedly one of the more creative and iconic use cases for so-called "child windows" on macOS. Despite that, drawers have been deprecated in macOS 10.13 and seemingly forgotten since then. You can hardly find any use of drawers in any macOS applications these days. Visiting the NSDrawer page on the modern Developer Documentation website shows a big and scary deprecation warning:

Drawers are deprecated and should not be used in modern macOS apps.

Funny enough, the class is implicitly marked @MainActor.

Now, I'm by no means advocating going against the modern HIG and encouraging widespread adoption of drawers in the year 2025, but I'm a firm believer that the history of our tools, frameworks, and software is well worth studying and drawing inspiration from.

What are Drawers?

NSDrawer is conceptually an auxiliary window that is attached to a visible window and moves with it. Drawers can be resized but can never get larger than their parent. A window may have multiple drawers associated with it and open at the same time.

Drawers can be open, closed, toggled, or in the process of opening or closing. When closed, they’re invisible. Drawers open on a specific edge of their parent, or a preferred edge if not specified. By default, drawers have a delightful animation for opening and closing, in which they appear from underneath and collapse into their parent window.

You can still find examples of drawers in some older OS X applications. UI Browser is the first example that comes to mind. It uses a drawer as an inspector for viewing individual attributes of a selected Accessibility element.

To me, this use of drawers doesn't really feel out of place – even on macOS Sequoia. In a modern application, you would've probably used an inspector panel, which would imply a more compact amount of horizontal space, or a vertical Split View. The drawer here does feel somewhat unusual, simply because it's not something you see across the system anymore, but it's honestly quite welcome and makes me feel in a certain Mac nerd type of way when using UI Browser.

Drawers on macOS Sequoia

As a developer in the Golden Age of drawers, you would use an AppKit class called NSDrawer to create, present, and manipulate drawers. The API surface was fairly straightforward and very similar to that of an NSWindow, albeit simplified. Method names like open, toggle, and close are self explanatory and could get you started quickly.

If you are skeptical that NSDrawer is indeed simply a window under the hood, you may convince yourself by using any tool available to you to inspect the application's window list. You will find that there is a one-to-one mapping between the conceptual representation of the NSDrawer and its window, which has the NSDrawerWindow type. The latter class is, of course, a framework implementation detail.

@interface NSDrawerWindow : NSWindow {
    NSDrawer * _drawer;
    NSWindow * _drawerParentWindow;
}

In the best traditions of AppKit's bincompat, the entirety of the API surface still works. You can still use drawers and compile code that uses them from all those years ago. Now, why wouldn't I want to play with them?

To have some fun with drawers, I went digging in the depths of the best resource known to an old school Apple developer, the Documentation Archive. I found a sample project aptly named DrawerMadness, originally published in May 2009 (more than 15 years ago!) and last updated in June 2012. Excited for some drawer madness, I proceeded to download it, open it in my Xcode 16.2 on macOS 15.2 and press Command-R. It built and ran on the first try, reminding me of one of the many reasons I love Objective-C.

Remember NSDrawers? This is them now. Feel old yet?

The sample app demonstrates the ability to open, close, and toggle multiple drawers along different edges of the window. Dragging the window while drawers are visible clearly still utilizes server-side dragging, and leads to a smooth dragging experience. Like any child windows, the drawers become part of the parent window's movement group. The window's behavior doesn't regress in any way due to the use of drawers.

Child Windows

There are, of course, many reasons why one should avoid using deprecated APIs in production code, but I believe drawers can serve as inspiration for more creative uses of the movement group mechanics of NSWindows. After all, you would be able to replicate the majority of the characteristic behaviors of NSDrawerWindow at home by using the following methods.

First, you'd set up a drawer as a borderless auxiliary NSWindow, then call addChildWindow with the parent window as the receiver to present the drawer.

parentWindow.addChildWindow(drawerWindow, ordered: .below)

Now, you've gotten the behavior of the window moving with the parent window whenever it is dragged or moved programmatically without doing any additional work. What's even better is that you didn't have to opt out of server-side dragging to accomplish that. Your child window will also seamlessly participate in system behaviors like Window Tiling (try Globe-Control-Right Arrow).

We can even implement a simple tear-off behavior by recognizing a drag originating in the drawer, transforming its styleMask and collectionBehavior to be a more standard window, and call removeChildWindow to detach the drawer from the movement group. Of course, once you're done, don't forget to order the window out and make sure it's properly deallocated. It's that simple.

We could further experiment with implementing fun animations for our custom drawers, allowing them to slide from underneath the parent window and perhaps even pop on the tear-off gesture. Perhaps that could be a fun exploration for another post?

A couple of months ago I took a trip to Fortuna, CA – a roughly 5 hour drive from my home in San Jose – to pick up a Macintosh Quadra 700 for my modest albeit growing collection of vintage hardware.

From what I gathered, the person selling the machine finds and repairs them for fun, mostly obtaining the devices, various accessories and software from estate sales. He seemed far more knowledgeable about the hardware than I was (I’m a software guy, okay?), and we had a very interesting conversation.

As part of my general motivation and interest in old Apple stuff, I mentioned having worked on AppKit at Apple alongside some ex-NeXT folks. I ended up leaving with the Quadra and a somewhat worn down envelope addressed to a former Oracle employee with a NeXT Computer, Inc. logo and return address on it. I was admittedly more excited about the latter.

Inside the envelope, I found a memo from NeXT Computer, Inc. dated June 6, 1991.

Alongside it, there were mint condition booklets with the company’s software and hardware offerings from the time. A time capsule from a unique moment in time for computing.

The booklets were all printed on surprisingly high quality dense paper. At the end of one of the booklets, it read:

This booklet was produced using NeXT computers. Text was written with Write Now 2.0. Page composition was done with FrameMaker 2.0. Proofs were printed using a NeXT 400 dpi Laser Printer. All text and image files were transfered directly from a NeXT optical disk to film using NeXT computers and an electronic output device.

The complete contents of the package included stuff I hadn’t seen posted anywhere else online. In total, the envelope included the following materials:

• A memo from NeXT;
• A table of all of the company’s offerings and a price list with discounts;
• NeXT Software and Peripherals Spring 1991
• NeXTdimension, NeXTstation & NeXTcube
• “Why does the world need a new computer?”

The Software and Peripherals booklet contained concise summaries of the company’s offerings at the time, with about a paragraph written about each one. The iconography in there was great!

It was fascinating to see the NeXTdimension, NeXTstation & NeXTcube brochure, as it was by far the most technical. Multiple tables outlined the specifications and features of each, alongside a few notable peripherals. Notably, each of the devices got a hero page with a cool graphic, and a summary table containing not just a list of features, but a concise explanation of the benefits of each.

“Why does the world need a new computer?” was undoubtedly the star of the show. A 15-page booklet, according to Steve himself, was aimed at changing “the way we work in the 90s.” This was somewhat of a pitch deck, focusing on the bigger picture of the what, the how, and the why. A few notable mentions of really cool software made it in, too.

The captures you see above depict the scans I performed using my iPhone 14 Pro camera. While the results were not bad, I am committed to scanning these materials professionally, and posting them here and in online archives. In the meantime, please feel free to email or contact me and I will be happy to send you any of the scans.