Mac Fold Documentation

Overview & Requirements

Mac Fold bridges physical MacBook hardware kinematics with native macOS graphics pipelines. When you tilt or close your MacBook display lid, the desktop visually folds, curls, defocuses, or shutters in exact synchrony with the physical hinge angle.

Installation & Gatekeeper

Because Mac Fold is an independent open-source project without a paid commercial enterprise signing subscription, distributed DMG builds are ad-hoc signed and not notarized by Apple. Follow this simple one-time onboarding procedure:

1. Download Mac-Fold.dmg from the official repository.
2. Double-click the DMG and drag Mac Fold.app into your /Applications folder.
3. Launch Mac Fold from Applications. macOS will display an alert stating: "Mac Fold cannot be opened because Apple cannot check it for malicious software". Click OK or Cancel.
4. Open macOS System Settings → Privacy & Security, scroll down to the Security section, and click Open Anyway next to Mac Fold.
5. Confirm by clicking Open in the system confirmation prompt.

Screen Recording Permission

Mac Fold uses Apple's native ScreenCaptureKit framework to capture current desktop frames and pass them to Metal fragment shaders.

When you click Enable Mac Fold for the first time, macOS will ask you to allow Screen Recording in System Settings → Privacy & Security → Screen Recording.

If permission appears enabled after a rebuild or update but capture does not start, reset the system registration with Terminal:

tccutil reset ScreenCapture local.lidflow.MacFold

Hotkeys & Controls

Mac Fold is designed to stay unobtrusive in your menu bar while providing rapid hotkey access:

• ⌃ ⌥ ⌘ F — Toggle or pause Mac Fold anywhere system-wide.
• Esc — Instant escape pause when an effect is active.
• Replay Button — Test and preview effects immediately, even without granting Screen Recording permission!

Lid Sensor Architecture (IOKit HID)

Mac Fold discovers and reads Apple's integrated hinge sensor through the low-level IOKit.hid subsystem:

let manager = IOHIDManagerCreate(kCFAllocatorDefault, 0)
IOHIDManagerSetDeviceMatching(manager, [
    kIOHIDDeviceUsagePageKey: 0x20, // Sensor Page
    kIOHIDDeviceUsageKey: 0x8A      // Angle Sensor Usage
] as CFDictionary)

The reader runs on a dedicated background dispatch queue (local.lidflow.sensor, QoS: userInteractive) scheduled with a 30Hz timer (every 33.3ms with 2ms leeway). This guarantees that lid reading never induces frame drops or hitches on the main user interface thread.

Metal 3.0 Rendering & Shaders

Effects are processed through compiled Metal 3.0 fragment shaders. Performance measurements on Apple Silicon (M4 MacBook Pro) confirm shader times at the 95th percentile between 1.94 ms and 2.30 ms for full Retina resolutions (up to 3024 × 1964).

• ProMotion 120Hz: Displays render up to 120 FPS when plugged into power.
• Power-Aware Throttling: Refresh rates scale down gracefully on battery or under thermal constraints.
• Settled Previews Pause: When the lid is stationary, Metal rendering completely halts (0% GPU utilization).
• Reusable Blur Pyramid: Mip-mapped Gaussian blur passes are cached and reused across frames, preventing redundant texture allocations.

Stillness Intelligence

A common challenge with lid-based effects is wanting to pause lid movement to type or read comfortably at a non-standard angle.

Mac Fold solves this via LidStillness.swift: if the lid angle remains stationary within a 0.5° tolerance for your selected duration (1 to 5 seconds, default 2 seconds), the active effect fades out and returns full desktop clarity. As soon as you move the lid again, Mac Fold resumes following.

Ghost Perspective Compensation

Introduced in version 0.1.12, the Ghost effect creates the optical illusion that the desktop is a physical painting anchored to a stationary resting plane in space behind the tilting laptop lid.

The shader intersects a stationary viewer's visual ray through the tilted panel with the resting plane. The Perspective slider controls viewing distance between 1.6× and 2.6× screen heights. Counter-rotation tracks faster than optical softening to maintain an authentic physical illusion.

Building from Source

To compile Mac Fold yourself, use Xcode 16 or newer with Swift 6 on macOS 13+:

# Clone repository
git clone https://github.com/dalchandrana/MacFold.git
cd MacFold

# Build release bundle
./build.sh

# Launch compiled application
open "build/Mac Fold.app"

Render Checks & Verification

Mac Fold includes an offline GPU render verification suite that checks pixel identity, opacity, blur pyramids, and timing without needing a physical lid:

swift test
swift build
.build/debug/MacFold --render-check validation

Add the --animation flag to export generated frame sequences for all six closing and reopening effects.

In-App Auto Updater

Mac Fold includes a transparent, user-initiated auto-updater (AppUpdater.swift):

• Contacts GitHub Releases over secure HTTPS only when you click Check for Updates...
• Validates downloads against official Mac-Fold-SHA256SUMS.txt hashes before unpacking.
• Executes an atomic replacement into /Applications without requiring administrator privileges or compromising Gatekeeper.
• Preserves user preferences and provides an immediate recovery dialog to restore previous releases if needed.

Frequently Asked Questions

Does Mac Fold animate external monitors?

No. External displays remain unaffected. Mac Fold detects and animates only the primary built-in Liquid Retina display that corresponds to the physical lid sensor.

Why does Mac Fold need Screen Recording permissions?

macOS requires Screen Recording permissions for any application that reads the desktop surface via ScreenCaptureKit. Mac Fold passes these pixels exclusively to your local GPU Metal shaders and discards them immediately.

Who created Mac Fold?

Mac Fold was conceived, designed, engineered, and authored solely by Dalchand Rana (@dalchandrana).