swift-user-conventions

name	swift-user-conventions
description	User's conventions and patterns for native macOS Swift apps. Use when working on a Swift or macOS app project
allowed-tools	Read,Write,Edit,Bash,Glob,Grep
version	0.1.0
author	ohnotnow <https://github.com/ohnotnow>
license	MIT

Swift / macOS App Conventions

Standards for small native macOS apps — menu-bar utilities, desktop companions, focused tools. These are opinionated defaults, not laws. This skill is young (much younger than its golang sibling): a handful of conventions and a gotcha list earned mostly in one project. When a session teaches a new lesson, add it here rather than leaving it in a transcript.

Project workflow

• XcodeGen: project.yml is the source of truth, the generated .xcodeproj is checked in. Regenerate with xcodegen generate after any structural change, before building.
• Build from the terminal with xcodebuild ... -derivedDataPath build build; run tests with CODE_SIGNING_ALLOWED=NO.
• Swift 6 with SWIFT_STRICT_CONCURRENCY: complete from day one — far cheaper than retrofitting it later.
• Menu-bar / background apps: LSUIElement: true in Info.plist properties.
• When the application is ready for testing - offer to write a simple ./build.sh script rather than making users run some (probably unfamiliar) xcode/swift commands.

Permissions and privacy posture

• App Sandbox and hardened runtime on; entitlements minimal (often just network.client).
• Design around Accessibility, Screen Recording and Automation permissions rather than requesting them. Example: CGWindowListCopyWindowInfo geometry (owner PID/name, bounds, layer, alpha — not window titles) needs no permission at all and works sandboxed.
• Secrets live in Keychain generic-password items only — never in UserDefaults, source, test fixtures or logs.
• If the README documents what's stored in UserDefaults, keep that list truthful when adding features — libraries may write their own defaults (e.g. KeyboardShortcuts stores the recorded shortcut there).
• Ad-hoc signed rebuilds look like new apps to Keychain, so the first access after a rebuild re-prompts. Expected, not a bug.

Dependencies

• Start dependency-free. When a problem is fiddly, permission-sensitive and already well-solved (e.g. global hotkeys plus a shortcut-recorder control), one battle-hardened SPM package beats hand-rolling — sindresorhus/KeyboardShortcuts being the canonical example.
• Pin from: a real release tag, and verify the latest with git ls-remote --tags <url> rather than trusting memory (the model once confidently guessed "2.x"; reality was 1.10.0).
• Expect strict-concurrency friction with pre-Swift-6 libraries. Prefer a narrow local fix — e.g. @MainActor on your own static constant — over a blanket @preconcurrency import.

Testing

• XCTest. Network code is fixture-backed via URLProtocol stubs; Keychain tests use temporary items; the suite never makes live provider calls. Live API checks are separate opt-in scripts under Tools/.
• Guard app bootstrap with an is-running-unit-tests check (Naiku's AppRuntime.isRunningUnitTests) so launching the app as a test host spawns no UI.
• Put the same guard on anything reading live system state (CGWindowList, screen parameters), or the suite inherits whatever happens to be on the developer's desktop.

Verifying beyond a green build

Drive the real app — a compiling binary and passing tests are necessary, not sufficient. Useful sandboxed, permission-light techniques:

• Window census: a five-line Swift script over CGWindowListCopyWindowInfo listing the app's windows by owner name and bounds proves a panel appeared (window titles would need Screen Recording; bounds don't).
• State seeding: write UserDefaults before launch to put the app in the state under test — e.g. KeyboardShortcuts_<name> takes a JSON string {"carbonKeyCode":N,"carbonModifiers":M}. Read the library's source to confirm a storage format; never guess it.
• Synthetic input: osascript -e 'tell application "System Events" to key code ...' (the host terminal needs Accessibility; if it's not granted, degrade gracefully and ask the user to press the key).
• The defaults CLI transparently follows sandboxed apps into their container (~/Library/Containers/<bundle-id>/...).
• Terminal-spawned probe apps are denied activation on modern macOS, so focus-dependent behaviour (key windows, first responders, focus-only visual artefacts) only reproduces in the real app.

Gotchas, earned the hard way

Mostly from Naiku (https://github.com/ohnotnow/naiku), macOS 26 / Xcode 26.1.1. Symptom → fix.

• Borderless NSPanel refuses key status → text fields silently untypable. Subclass and override var canBecomeKey: Bool { true }.
• performClose(nil) on a borderless window is a silent no-op — .closable in the style mask is not enough, AppKit wants an actual close widget — so windowShouldClose delegate logic never fires. Override performClose to run the delegate contract yourself, then close().
• Dark rectangular halo around a transparent/glass window that toggles with focus = the key-window shadow. invalidateShadow() does not fix it; hasShadow = false does. Diagnostic tell: content can't paint outside window bounds and doesn't change with focus — shadows do both.
• NSHostingController's default sizingOptions pin the hosting view to the SwiftUI minimum size, leaving an invisible dead strip inside a larger window. Set sizingOptions = [] and manage window sizing yourself (setContentSize + minSize). One print of window.frame vs window.contentView?.frame settles it.
• macOS 26: withholding .fullScreenAuxiliary does not keep a .canJoinAllSpaces floating panel out of full-screen Spaces — it gatecrashes anyway. The only working fix is active self-suppression: watch Space changes, detect a covering full-screen window via CGWindowList geometry, and orderOut yourself.
• NSWorkspace.activeSpaceDidChangeNotification fires mid-transition — CGWindowList still shows the departing Space's windows at notification time. Treat the notification as a trigger to start converging, not a reliable read point: check immediately, re-check ~0.8s later, and poll slowly while in a suppressed state so recovery never depends on another notification.
• A repeating Timer(target: self) retains its target until invalidated — a poll timer started only in a rare state is easy to miss in tear-down and leaks the controller.
• Global hotkeys: Carbon RegisterEventHotKey (which KeyboardShortcuts wraps) works inside the App Sandbox with no extra permissions. NSEvent.addGlobalMonitorForEvents needs Input Monitoring — avoid it.
• KeyboardShortcuts 1.10 under Swift 6: static KeyboardShortcuts.Name constants trip strict concurrency (Name isn't Sendable); isolate them with @MainActor — both AppKit call sites and SwiftUI body are main-actor anyway.
• A sprite atlas (or any repeatedly drawn image) re-decodes its PNG on every draw — kCGImageSourceShouldCache / ShouldCacheImmediately do not make the decode stick: the CGImage stays backed by the compressed PNG provider and the decoded pixels live in an evictable system cache, so each redraw can trigger a full decode plus colour-match (NSImage.cacheMode = .never guarantees it). Diagnostic tell: CPU tracks the animation frame rate, and /usr/bin/sample shows png_read_filter_row_paeth_neon / CGSImageDataLock under CALayer _display. Fix: at load time, draw the image once into an owned CGContext (sRGB, premultiplied BGRA, byteOrder32Little) and keep context.makeImage() — nothing PNG-backed survives to draw time. Cost is width×height×4 bytes of resident memory.

Out of scope (so far)

• iOS / iPadOS.
• App Store or notarised distribution — no project has shipped a public binary yet; add conventions when the first one does.
• Large document-based AppKit/SwiftUI apps.