Overlays #
The app's overlay controllers turn engine state into focus borders, drop hints, and stack chips. Panels stay out of managed-window discovery. Decorations do not activate the app or take focus; interactive controls expose native accessibility actions.
Use ParcelAnimation for motion and keep static feedback useful when animation is disabled. Reduce Transparency and Increase Contrast affect appearance, not whether the reader can use a control.
Experimental dimming stays unavailable until the native bridge proves the effect with readback and can persist a recovery marker. Clear that marker only after restoration succeeds. A successful native return value is not proof.
OverlaySnapshot.privacyWorkspaces carries each active display/Space's modes and
last managed focus. OverlayPrivacyWorkspace has no global privacy flag.
Cutouts use actual AX notifications and write readbacks through
observePrivacyFrame; window-list refreshes cannot overwrite a newer frame.
Without a verifier, No peek uses its overlay without a dimming warning.
Snapshots and readbacks dirty displays; each display link commits its latest border, clip, and privacy regions at most once per refresh, then pauses. Managed borders use the last confirmed frame without a second animation clock. Window visibility reads have one in flight and one trailing request; geometry-only snapshots do not start a scan. Display discovery runs at startup and screen changes.
OverlayPaletteSource.shared resolves semantic roles inside the panel's effective
appearance and versions changes. setResolver installs a named palette without
changing renderers or window layout. A nil cleanSpaceBackdrop role keeps the
workspace's configured backdrop. Appearance, accent, and accessibility changes
invalidate the palette; retained highlight geometry is untouched by color changes.
The overlay.render interval and overlay.border.lag event support live profiling.
Run PARCEL_OVERLAY_BENCH=1 swift test -c release --no-parallel --filter RenderingBenchmarks
for local thread-instruction and wall-time measurements. The ten-window glide e2e
scenario checks final borders against FixtureApp readbacks without screen capture.
Rendering measurements #
Release medians on Mac15,10, macOS 15.7.7, Swift 6.2.4. Instructions come from
thread_selfcounts; wall time is sensitive to host load. The starting checkout
already reused highlight layers and deferred closed-menu rebuilding.
| Workload | Instructions before → after | µs before → after |
|---|---|---|
| Highlight, 10 unchanged | 166,533 → 63,691 | 30.68 → 19.03 |
| Highlight, 10 moved | 403,105 → 265,817 | 34.46 → 39.93 |
| Consume, 50 windows | 547,799 → 253,519 | 55.17 → 15.74 |
| Privacy, 8 unchanged cutouts | 306,493 → 3,488 | 16.11 → 0.35 |
| Privacy, 8 moved cutouts | 309,720 → 380,488 | 20.69 → 24.32 |
| Theme, 10 windows | 857,693 → 717,854 | 79.60 → 53.34 |
| Menu icon, cold 36 px raster | 360,468 → 327,482 | 131.62 → 23.55 |
| Menu icon, cached raster extraction | 348,939 → 62,163 | 35.85 → 3.80 |
| Chips, unchanged | 729,430 → 40,792 | 369.99 → 2.49 |
A cached icon lookup without AppKit bitmap extraction takes 5,691 instructions / 0.30 µs. Unchanged highlights allocate zero app-owned layers. A burst of 120 visibility requests starts only two reads; 120 geometry-only snapshots add none. Closed menus rebuild zero times across 120 snapshots, both before and after. Moved privacy regions spend 23% more CPU instructions to remove full-display masks and constrain blur coverage; their update remains below the 200 µs budget.
Live compositor/drop-frame and border-lag measurements remain unverified: the harness refused to control an already-running Parcel, which was left untouched. The live test skips cleanly without opt-in. No screen capture or SIP-dependent calls were added.
Model tests cover presentation decisions. FixtureApp e2e tests cover real focus, window tracking, input, Space/display scoping, and cleanup. See stack chips for the interactive tile control.