An auto tiler for macOS
parcel Sources ParcelUI Overlays
35 files

AppearancePalettes.swift
CleanSpaceBackdrop.swift
DividerHandleController.swift
DividerHandleGeometry.swift
DragLayoutBadge.swift
DragLayoutController.swift
DragLayoutGeometry.swift
DragLayoutTargetLayer.swift
OverlayBrightness.swift
OverlayBrightnessRecovery.swift
OverlayController.swift
OverlayFrameClock.swift
OverlayGeometry.swift
OverlayPalette.swift
OverlayPanel.swift
OverlaySnapshot.swift
PrivacyWindows.swift
README.md
ReservedEdgePreview.swift
ReservedEdgePreviewGeometry.swift
ReservedEdgePreviewVisibility.swift
SelectionGripMetrics.swift
StackChipController.swift
StackChips.md
StackChips.swift
StackChipView.swift
StackCloseConfirmation.swift
StackControls.swift
StackDropPreview.swift
StackGripButton.swift
StackGripController.swift
StackGripGeometry.swift
StackGripView.swift
StackText.swift
WindowControlsController.swift
README.md

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.