appkit-launch-continuity

AppKit Launch Continuity: Graceful Quit + State Restoration

Overview

A great Mac app quits without pushback and comes back as if it was never quit. People quit apps whenever they want — sometimes the system does it for them, e.g. an overnight reboot for a software update. The app should block quit only when it genuinely needs to, and on relaunch restore exactly where the user left off.

Source: WWDC 2026 Session 289, "Modernize Your AppKit App."

When to Use

• The app blocks a system restart/shutdown because a sheet or modal is up.
• After quit + relaunch the app loses its open windows, selection, or window arrangement.

Part 1 — Graceful termination

When a window is presenting a sheet, it may not be able to close — and if a window can't close, the app can't quit. The relevant property is:

window.preventsApplicationTerminationWhenModal = false

• It defaults to true — for good reason: it protects unsaved data (e.g. a "save this document?" sheet that genuinely needs a response).
• Set it to false for every sheet or modal that does not strictly require user intervention (inspectors, non-blocking dialogs). That lets the app terminate gracefully.

You do not need to inspect the quit reason (kAEQuitReason Apple Events, applicationShouldTerminate: archaeology) to decide whether to block. Set this one property per-modal based on whether the modal is critical.

Part 2 — State restoration (NSWindowRestoration)

Three steps: opt in → encode UI state → decode to restore windows and UI.

Step 1: Opt in (in the window controller)

@MainActor class MainWindowController: NSWindowController, NSWindowDelegate {
    convenience init() {
        let window = NSWindow(/* ... */)
        window.identifier = NSUserInterfaceItemIdentifier(WindowIdentifiers.mainWindow)
        window.setFrameAutosaveName(WindowIdentifiers.mainWindow)
        window.isRestorable = true
        window.restorationClass = WindowRestorationHandler.self
    }
}

• identifier — stable identity for the window.
• setFrameAutosaveName — for common windows (main, preferences); restores to the same space with the same frame. Not needed for document windows.
• isRestorable = true — lets AppKit call encodeRestorableState/restoreState, and auto-restore which window was minimized, frontmost, and full-screen.
• restorationClass — invoked on relaunch to recreate the window.

Step 2: Encode UI state

override func encodeRestorableState(with coder: NSCoder) {
    super.encodeRestorableState(with: coder)   // always call super
    coder.encode(selectedProduct?.identifier.uuid.uuidString,
                 forKey: RestorationKeys.productIdentifier)
}

• Encode UI state only. The goal is to reconstruct the UI, not re-serialize the app — avoid encoding data that lives in your document or database.
• All NSResponders have encodeRestorableState — override it on views too, as needed.
• It's called only when state has been invalidated. Whenever a view-hierarchy change should alter saved state, call invalidateRestorableState():

splitViewController.onProductSelected = { [weak self] product in
    self?.invalidateRestorableState()
}

AppKit then calls encodeRestorableState on everything invalidated, before quit.

Step 3: Restore on relaunch — windows first, then state

Restore windows in the restoration class. This is called for every window being restored:

class WindowRestorationHandler: NSObject, NSWindowRestoration {
    static func restoreWindow(
        withIdentifier identifier: NSUserInterfaceItemIdentifier,
        state: NSCoder,
        completionHandler: @escaping (NSWindow?, Error?) -> Void
    ) {
        if identifier == .mainWindow, let window = appDelegate.mainWindowController?.window {
            completionHandler(window, nil)
        } else if identifier == .imageWindow {
            let controller = ImageWindowController()
            appDelegate.imageWindowControllers.append(controller)
            completionHandler(controller.window, nil)
        } else {
            completionHandler(nil, error)
        }
    }
}

Always call the completion handler — AppKit waits on every restorable window. If creation fails, call it with the error. If you can't call it inside the method, save the handler and call it later, but be absolutely sure to call it.

Then restore the UI for each window with the same coder you encoded into:

override func restoreState(with coder: NSCoder) {
    super.restoreState(with: coder)
    if let productId = coder.decodeObject(
        of: [NSString.self],
        forKey: RestorationKeys.productIdentifier) as? String {
        splitViewController?.selectedProductId = productId
    }
}

Common Mistakes

• Over-engineering termination by inspecting quit reasons / applicationShouldTerminate: instead of setting preventsApplicationTerminationWhenModal = false on non-critical modals.
• Encoding document/database data into restorable state. Encode only what's needed to rebuild the UI.
• Forgetting to call the completion handler in restoreWindow(withIdentifier:state:) — AppKit hangs waiting for it.
• Omitting super in encodeRestorableState/restoreState.
• Never calling invalidateRestorableState() — so encodeRestorableState never fires and nothing is saved.

Recap

Make quit non-blocking for non-critical modals, then save and restore UI state so relaunch feels uninterrupted. See Apple's code sample "Restoring your app's state with AppKit."