Desktop Zones Native

Desktop Zones is a lightweight native macOS menu bar app that draws visual glass zones behind Finder desktop icons. Version 0.7 also provides an explicit, default-off Finder integration that can preview Zone membership and arrange icon coordinates inside each Zone. It never moves, renames, deletes, tags, opens, or monitors files.

Download and install (no Terminal required)

For ordinary use, download the latest macOS Apple Silicon DMG from the GitHub Releases page. You do not need Terminal, Xcode, Swift, or any other development environment.

1. Open the downloaded .dmg file.
2. Drag Desktop Zones.app onto the Applications shortcut.
3. In Applications, Control-click Desktop Zones and choose Open the first time. Confirm Open if macOS asks. This one-time step is required because the current public trial is ad-hoc signed and not Apple-notarized.
4. Desktop Zones appears in the menu bar. Finder integration is off by default; enable it only if you want file arrangement, then approve the macOS Finder Automation prompt.

The ZIP asset on the Releases page contains the same prebuilt app and is provided as an alternative. It also requires no development environment.

System requirements

• macOS 13 or later
• Apple Silicon for the downloadable 0.7 build
• One main display for this MVP

Build from source (developers only)

The following section is only for contributors. It requires Apple Command Line Tools with Swift 6, or Xcode.

From the DesktopZones folder:

./scripts/run-tests.sh
./scripts/install-app.sh
open "$HOME/Applications/Desktop Zones.app"

The install script puts the app in ~/Applications. If an older installed build exists, it becomes the single Desktop Zones.previous.app rollback copy. An older rollback is moved to the Trash instead of accumulating searchable duplicates.

Use

The app starts in Locked Mode. Use the Desktop Zones icon in the macOS menu bar:

• Edit Layout — show edit controls and accept Zone input.
• Lock Layout — return below Finder icons and pass all mouse input through.
• Add Zone — add a centered Zone with a small cascade offset.
• Reset Layout — restore the single default Zone on the right.
• Appearance… — adjust transparency, glass presence, and background blur with live preview.
• Refresh Wallpaper — manually reload the current wallpaper after changing it (Cmd-Option-R).
• File Organization (Experimental) — explicitly enable Finder integration, preview current Zone membership, optionally group the same public file types together, arrange icon coordinates, resize Zones while preserving captured members, or undo the last verified arrangement. Stacks must be Off and Finder Sort By must be None.
• Launch at Login — register or unregister Desktop Zones at login. It is off by default. Properly Developer-signed builds use SMAppService.mainApp; the current ad-hoc personal build automatically falls back to a managed per-user LaunchAgent because Service Management cannot identify an app without a signing identity. The menu creates and removes the fallback itself.
• Quit Desktop Zones — save and close the app.

In Edit Mode, drag the body of a Zone to move it, drag the lower-right handle to resize it, or click × to delete it. The minimum size is 160 × 120 points, and at least 40 points remain visible after moving.

Storage

The app automatically writes a versioned JSON document to:

~/Library/Application Support/DesktopZones/layout.json

Writes are debounced during pointer movement and flushed when an operation ends or the app quits. Invalid or unsupported data falls back to the default layout.

To clear the current layout, use Reset Layout. For a complete storage reset, quit the app, move layout.json to the Trash, and reopen the app.

If layout.json is malformed or uses an unsupported version, Desktop Zones first copies the original bytes to a timestamped, uniquely named layout.corrupt-YYYYMMDD-HHMMSS-SSS-XXXXXXXX.json file in the same directory, then creates a default layout. The backup is never silently overwritten.

Appearance

All Zones share one global appearance; settings are intentionally not stored per Zone. Wallpaper Glass is the default renderer, while the AppKit underWindowBackground material remains available as the Native fallback.

Version 0.7 retains the user-approved 0.6.10 frozen visual baseline while adding the isolated Finder organization workflow. File features do not enter the appearance or overlay rendering path.

Open Appearance… from the menu bar to adjust three global values:

• Renderer switches every Zone live between the system Native material and the experimental Wallpaper Glass path.
• Wallpaper Tone is a manual Light Wallpaper / Dark Wallpaper edge profile. It never analyzes the wallpaper automatically. Light uses a subtle neutral contour plus restrained white reflection; Dark uses a brighter continuous white contour and reflection. The choice applies globally, previews live, persists across restarts, and defaults to Dark for upgrades.
• Transparency controls the whole surface film across a linear 0–14% range. 100% removes the film; lower values make the neutral white surface more visible.
• Glass Presence is internally treated as edgePresence: it scales the contour and soft reflection for the manually selected Wallpaper Tone. Version 0.6.10 expands the range by 25%, so the former 100% appearance is preserved at the new 80%, leaving 80%–100% as additional edge-reflection headroom. The reflection uses an edge-distance mask and a gentle top-left-to-bottom-right intensity gradient. Wallpaper saturation and brightness remain unchanged, and there is no shadow or angular/conic border gradient. In Native it controls material participation.
• Background Blur independently controls a nonlinear 0...12 point Gaussian blur and is disabled for Native.

Changes preview immediately on every Zone and persist automatically in macOS preferences. Restore Defaults returns to Wallpaper Glass, 88% transparency, 44% glass presence (the same visual strength as the former 55%), and 30% background blur (about 4 points after nonlinear mapping). Appearance preferences are separate from layout.json, so visual tuning never changes Zone positions or sizes. The former Glass Strength preference migrates to Background Blur on first launch.

Wallpaper Glass reads the current main-screen wallpaper URL through the public NSWorkspace.desktopImageURL(for:) API, reproduces the system scaling/cropping, and generates a matching crop for each Zone. Core Image applies only the independent blur while preserving the source wallpaper color space; AppKit then adds a very weak screen-blended film, restrained top reflection, and edge highlights. On pale wallpaper crops, Glass Presence also adds a uniform one-pixel neutral contrast hairline; it does not add a shadow or recolor the wallpaper. The renderer never modifies the wallpaper, captures the screen, or uses private APIs. If the wallpaper cannot be read, the existing snapshot is retained or the Zone falls back to Native on first launch.

The app does not poll or monitor wallpaper changes. After changing a wallpaper, choose Refresh Wallpaper from the menu bar; all existing and future Zones then use the refreshed snapshot. A display-size or backing-scale change is the only automatic reload because the cached image must be rebuilt for the new geometry. Different wallpapers assigned to different Spaces also require a manual refresh after switching Spaces.

Locked Mode uses one desktop-level, click-through window per Zone. This prevents an opaque bitmap from affecting the unused area of a full-screen transparent window. Edit Mode retains the existing full-screen editor and uses the Native renderer while controls are visible; returning to Locked restores Wallpaper Glass.

Three internal presets (clear, standard, and strong) and four material candidates remain available for developer comparison:

DESKTOP_ZONES_GLASS_PRESET=clear \
DESKTOP_ZONES_GLASS_MATERIAL=underWindowBackground \
DESKTOP_ZONES_GLASS_RENDERER=wallpaper \
.build/release/DesktopZones

Supported material values are hudWindow, underWindowBackground, sidebar, and contentBackground. Renderer values accept native or wallpaper (custom remains a compatibility alias). These environment overrides are diagnostic only and temporarily override the saved appearance. The legacy opacity field remains in layout JSON version 1 for compatibility but is not used as a per-Zone visual control.

Architecture

MenuBarManager
      │
AppDelegate ─── lifecycle notifications
      │
OverlayCoordinator
 ┌────┴──────────────────┐
Locked Zone windows    Edit Overlay
Desktop level          Normal level - 1
mouse ignored          mouse accepted
 └────┬──────────────────┘
      │
  shared LayoutStore
      │
versioned layout.json

Only one mode is visible at a time. Locked Mode uses one small Core Graphics desktop-level window per Zone, below Finder desktop icons. Edit Mode uses one full-screen window at the level immediately below normal application windows so Zone controls can receive input without floating over ordinary apps.

Lifecycle behavior

The overlay is hidden when the user session resigns, the screen sleeps, or the Mac sleeps. It is restored and clamped to the current main screen after session activation or wake without rereading wallpaper content. Finder relaunches and Space changes only reassert the desktop layer. Display-parameter changes reload the snapshot only when required for the new screen geometry. Every launch starts Locked.

Only one Desktop Zones process may run in a user session. A second launch detects the existing process through a per-user process lock and exits without creating another menu item, overlay, or writer for layout.json.

Upgrade, rollback, and uninstall

Running ./scripts/install-app.sh builds the new version, asks any running Desktop Zones process to quit even if its bundle was moved, verifies that it stopped, and only then replaces the installed bundle. The previous bundle becomes Desktop Zones.previous.app in ~/Applications; any separately retained frozen backup is not touched. Layouts and appearance preferences are not changed.

To roll back, quit Desktop Zones, move the current ~/Applications/Desktop Zones.app aside, copy Desktop Zones.previous.app or another retained frozen backup to Desktop Zones.app, and open it. Layout format version 1 remains compatible with the current releases.

To uninstall:

1. Turn off Launch at Login from the menu if it is enabled.
2. Choose Quit Desktop Zones.
3. Move ~/Applications/Desktop Zones.app and any unwanted rollback copies to the Trash.
4. Optionally move ~/Library/Application Support/DesktopZones to the Trash to remove layouts and corrupt-file backups.
5. Optionally remove the com.steven.DesktopZones preferences domain to clear appearance settings.

If the App is no longer available but its ad-hoc login fallback was left enabled, remove ~/Library/LaunchAgents/com.steven.DesktopZones.login.plist and log out/in. Normally, turning off Launch at Login removes it automatically.

The app includes a generated .icns application icon. The downloadable trial remains ad-hoc signed; broad public distribution would require Developer ID signing and notarization.

Build-time App bundles are staged under the hidden .build/app-bundle directory so Spotlight does not present them as extra installed copies. The visible build directory is reserved for the final versioned ZIP archive.

Current scope

The 0.7 file workflow uses only public Finder Automation properties for item names, public file types, and desktop position. It changes icon coordinates only after an explicit preview and confirmation. It does not monitor files or use Accessibility, Screen Recording, Full Disk Access, simulated input, or private APIs. Finder does not reliably expose Desktop Stacks and Sort settings through public scripting, so users must manually keep Stacks Off and Sort By set to None.

The current scope remains single-main-display and does not provide automatic background organization, permanent Zone membership, file movement, or a full settings system. Static wallpaper changes use the manual Refresh Wallpaper command; dynamic/video wallpapers cannot be sampled frame by frame.

For daily use, see USER_GUIDE.zh-CN.md. Release changes are recorded in RELEASE_NOTES.md.