Release Notes Release Notes

# SpaceAtlas v1.1.3 - Release Notes

**Release Date:** March 2026
**Platform:** macOS Sequoia 15.0+ (Apple Silicon only)

---

## Headline: Virtual Spaces

SpaceAtlas no longer requires multiple macOS desktop spaces. All apps now run on a single desktop space, and SpaceAtlas virtualizes space switching by bringing the correct windows to the front. This eliminates Mission Control animations, removes the 16-space limit, and delivers faster, smoother navigation.

---

## New Features

### Virtual Space System
- Complete architectural shift from macOS desktop space switching to virtual spaces
- All apps live on one macOS desktop space; SpaceAtlas manages window visibility
- Apps are brought to the front when entering a space and hidden when leaving
- Supports up to 99 virtual spaces (up from the previous 16 macOS limit)

### Navigation Buffer
- New buffered navigation system for rapid movement through spaces
- First move is instant; subsequent rapid moves pass through without activating apps
- Configurable buffer delay via slider in Advanced Settings
- Prevents unnecessary app activation during fast navigation sequences

### Hide Apps on Leave
- Toggle to automatically hide apps when leaving a virtual space
- Keeps your workspace clean by only showing apps for the current space
- Configurable per-user in Advanced Settings

### Globe Visualization (Alpha)
- Introduced 3D globe view for space layout visualization
- Early preview — expect refinements in future releases

### Dynamic Space Management
- Add or remove spaces dynamically in both Space-Matrix Mapping and Space-App Mapping tabs
- From Base-16 , supporting up to 99 spaces
- No more fixed grid — scale your workspace as needed

---

## Improvements

### Performance
- App launching moved off the main thread to prevent UI blocking
- Window resizing now occurs on space switch with filtering for improved performance
- Fixed lag when switching spaces and opening apps
- Overlay resizing optimized with event filtering

### App-Space Mapping
- App-Space Mapping is now bound to profiles (previously global)
- Each profile maintains its own app-to-space assignments

### Menu Bar
- Improved menu bar UI and layout

---

## Bug Fixes

- Fixed gateway/profile switch bug where Launch App would trigger for all spaces after every profile switch or gateway jump — now only triggers once per session
- Fixed galaxy navigation bug where moving in and out of a galaxy would land on the wrong space
- Fixed galaxy spaces not being treated as valid spaces for app activation
- Fixed galaxy-space resolution in slot index provider
- Fixed resolved space number not being passed through VirtualSpaceManaging for galaxy-space activation
- Fixed last-focused app tracking

---

## Technical Notes

- Virtual space architecture replaces Mission Control-based space switching
- Mission Control keyboard shortcuts are no longer required for basic operation
- The 16-space macOS limit no longer applies — virtual spaces scale to 99
- Navigation buffer prevents app thrashing during rapid directional input
- App visibility managed via NSRunningApplication hide/unhide APIs

# SpaceAtlas v1.1.2 - Release Notes

**Release Date:** March 2026
**Platform:** macOS Sequoia 15.0+ (Apple Silicon only)

---

## What is SpaceAtlas?

SpaceAtlas is a macOS space navigation tool that turns your desktop spaces into a 2D grid you can move through with keyboard shortcuts and trackpad gestures. Arrange your windows across macOS spaces once, then navigate between them using directional movement, bookmarks, quick jumps, and portals - all without disabling SIP or installing third-party window managers.

---

## Core Features

### 2D Matrix Navigation
- Navigate macOS desktop spaces (1-16) using a 2D coordinate grid
- Directional movement with Option + Arrow keys (default)
- Carousel wrapping - moving past an edge wraps to the opposite side
- Configurable matrix bounds per profile

### Quick Jumps & Bookmarks
- **Quick Jumps (Command+1–9):** Jump directly to user-configured coordinates
- **Bookmarks (F1-F12):** Save and load viewport positions with custom names
- **Ping-Pong (Command+0):** Toggle between current and previous position

### Wormhole Portals
- Create portal coordinates that teleport the viewport to a destination
- Same-profile wormholes and cross-profile gateways
- Dynamic destinations: Last Active Space, Previous Space
- Animated vortex effect on the overlay indicating destination

### Nexus Hubs (Direction-Aware Portals)
- Configure different destinations based on entry direction (left, right, above, below)
- Per-direction memory remembers return destinations
- Dedicated Nexus Wizard with step-by-step or summary configuration mode
- Visual diagram showing entry directions

### Galaxies (Multi-Cell Entities)
- Create contiguous multi-cell regions with unified behavior
- Six galaxy types: Space, Wormhole, Gateway, Nexus, Last Active Space, Previous Space
- Two modes: Edge (always enter at border) and Memory (remembers internal position)
- Contiguity validation ensures galaxies form connected shapes

---

## Profiles & Configuration

### Profile Management
- Create multiple workspace profiles for different setups
- Auto-load last-used profile on startup
- Duplicate profile name validation
- Import/Export profiles as JSON bundles

### Per-Profile Settings
- Space mapping: coordinate-to-desktop-space assignments
- Space customization: colors (Material Design palette), notes (up to 30 chars), custom images
- Quick jump assignments, bookmarks, wormholes, nexus hubs, and galaxies
- Monitor layout configuration for multi-display setups

---

## Input & Controls

### Keyboard Shortcuts
- Fully customizable via Settings window with recording UI
- Human-readable display with modifier symbols
- All navigation, bookmark, and mode actions are rebindable

### Trackpad Gestures
- 3-finger swipe gestures for directional navigation
- Configurable horizontal and vertical sensitivity
- Minimum swipe threshold detection
- Can be used alongside or instead of keyboard shortcuts

---

## Space-App Mapping

### Intelligent App-to-Space Mapping
- **Auto-Detection Mode:** Learns which apps you use in each space over time
- **Manual Assignment Mode:** Explicitly assign apps to specific spaces
- **Launch Policies:** Never, On Login, or On First Visit (per app)
- Slot system groups similar app combinations into reusable workspace configurations
- Auto-merge for similar slots (85%+ similarity, 3+ confirmations)
- Auto-cleanup removes empty inferred slots after 30 days
- 90-day history retention
- Note: app launching is best-effort - macOS controls final window placement

---

## Overlay & Visualization

### Overlay Window
- Real-time grid visualization of the current space layout
- Viewport highlight showing current position
- Space colors, numbers, notes, and images displayed on cells
- Wormhole/gateway indicators with animated vortex effects
- Nexus direction indicators with multiple art styles (pinwheel, square loop)
- Galaxy visualization
- Configurable: position, size (1-300%), transparency, fade-out mode

### Menu Bar
- Status icon shows current viewport position or grid miniature
- Dropdown with profile name, pause toggle, test mode, settings, and help
- Dark mode support

---

## Settings

### Settings Window Tabs
1. **Account** : Authorization status, trial days remaining, license info, update checks
2. **Space Mapping** : 2D grid editor with right-click context menus for all entity types
3. **Keyboard Shortcuts** : Rebind all actions with recording UI and hover help
4. **Space-App Mapping** : Mode selection, slot management, launch policy configuration
5. **Overlay** : Display mode, position, size, transparency, grid display options, art styles
6. **Advanced** : Timing configuration, log level, gesture sensitivity, instant switching
7. **Import/Export** : Selective export/import of profiles, shortcuts, and settings with conflict handling

---

## Onboarding

### First-Run Experience
- Welcome window introducing SpaceAtlas
- System checks: accessibility permissions, Mission Control shortcuts, display settings
- Interactive step-by-step tutorial with visual highlights and arrow indicators
- Profile creation wizard
- Resumable - restart tutorial anytime from the menu

---

## Licensing & Updates

### Trial & Licensing
- 40-day free trial on first launch
- Email-based license activation with magic code authentication
- Offline grace period for network interruptions

### In-App Updates
- Automatic background update detection (24-hour throttle)
- Semantic versioning comparison
- Download button for signed builds
- Manual refresh available in Account settings

---

## Import & Export

- Export complete settings bundles or selective components (profiles, shortcuts, overlay, advanced, app mapping)
- Import with conflict handling: overwrite, rename, or skip duplicates
- Automatic backup before import
- Bundle versioning for format compatibility

---

## Logging & Diagnostics

- Configurable log levels (Debug, Info, Warning, Error)
- Persistent log files in `~/Library/Logs/SpaceAtlas/`
- Configurable log retention period
- Emoji-based status indicators for quick scanning

---

## System Requirements

- macOS Sequoia 15.0 or later
- Apple Silicon Mac (M1 or later)
- Accessibility permissions (for global keyboard shortcuts)
- Mission Control keyboard shortcuts enabled ("Switch to Desktop 1-16" in System Settings)
- "Displays have separate Spaces" should be OFF for multi-monitor setups
- No SIP disable required - fully SIP-safe

---

## Technical Notes

- SIP-safe architecture: uses CGS private APIs and Mission Control symbolic hotkeys
- No dependency on yabai, Hammerspoon, or any third-party window manager
- Supports up to 16 desktop spaces (macOS keyboard shortcut limit)
- State persistence: auto-saves every 30 seconds and on quit
- Data stored in `~/Library/Application Support/SpaceAtlas/`
- Migrates automatically from legacy MacSpaceManager data on first launch