Documentation for SpaceAtlas

1. Download SpaceAtlas and run the .pkg installer. Follow the on-screen steps to complete the installation.
2. Launch SpaceAtlas. On first startup, a built-in onboarding tutorial will guide you through the basics.
3. The app will run a System Configuration check to verify that required permissions (Accessibility, Input Monitoring) and recommended settings are configured correctly. Use the "Fix It" buttons to resolve any issues automatically.
4. Once setup is complete, SpaceAtlas lives in your menu bar. Click the menu bar icon to access the dropdown with all key actions.

SpaceAtlas checks your system configuration on first launch and helps you fix any issues before you start.

SpaceAtlas runs from your menu bar. Click the icon to open the dropdown, which gives you quick access to:

• Pause / Resume Navigation — toggle SpaceAtlas on or off without quitting the app.
• Toggle Test Mode — use the grid virtually without any actual space switching. Useful for experimenting with layouts.
• Settings — open the full settings window to configure keyboard shortcuts, grid layout, overlays, and more.
• Manage Account — go directly to your online account page to manage licenses and devices.
• Show Tutorial Again — restart the onboarding walkthrough at any time.
• Save / Load / Delete Profile — manage different grid configurations for different workflows.

The menu bar dropdown is your quick-access hub for toggling navigation, switching profiles, and opening settings.

Profiles

Profiles let you save entirely different grid configurations and switch between them. For example, you might have a "Work" profile with your development tools laid out in one arrangement, and a "Home" profile with a different setup.

Use Save New Profile to capture the current setup, Load Profile to switch instantly, and Delete Profile to remove an outdated layout when you no longer need it.

Mapping Types

SpaceAtlas supports six core mapping types when you build spaces, portals, and larger galaxy regions:

• Space — maps directly to a specific macOS space.
• Wormhole — jumps to another position in the current profile.
• Gateway — jumps to a destination in another profile.
• Nexus — routes differently depending on the direction you enter from.
• Last Active Space — resolves dynamically to the most recently active mapped space.
• Previous Space — jumps back to the space you came from.

Last Active Space and Previous Space are especially useful when you want portal behavior that reacts to context instead of a fixed destination.

Quick Jumps

Quick Jumps let you instantly teleport to a specific space from anywhere in the grid using Cmd+1 through Cmd+9. Right-click a space on the grid and select "Assign Quick Jump" to set it up. Quick Jump assignments are shown in the panel on the right.

Bookmarks

Bookmarks give you twelve additional direct-jump slots. Assign frequently used destinations to F1 through F12 so you can jump there without stepping through the grid one move at a time.

Wormholes

A Wormhole is a one-way teleport link between two positions within the same profile. When you navigate into a wormhole, you jump directly to its target space instead of the adjacent grid position. You can also set dynamic targets:

• Last Active Space — the wormhole always takes you back to whichever space you were on most recently.
• Previous Space — the wormhole takes you to the space you came from, like a back button.

Gateways

Gateways work like wormholes, but connect across different profiles. Navigate into a gateway and you'll jump to a space in another profile — useful for linking shared spaces between your Work and Home setups.

Nexus

A Nexus is a directional hub. Each direction you enter from (left, right, up, down) can lead to a different destination — either a space or a gateway. This makes the Nexus a powerful routing point where a single grid position can connect to four different places depending on how you navigate into it.

For more complex direction-aware routing, use the Nexus Wizard. Walkthrough mode guides you through one entry direction at a time, while Summary mode shows the full routing setup together so you can review and edit every path from one screen.

Galaxy

A Galaxy groups multiple contiguous cells into a single unified entity. Any supported mapping type — Space, Wormhole, Gateway, Nexus, Last Active Space, or Previous Space — can become a Galaxy, letting it span a region of the grid rather than a single position.

Moving into a Galaxy is a normal navigation move that lands you on the entry cell. From there, additional moves navigate within the Galaxy or out of it:

• Reverse direction — pressing back the way you came returns you to the cell you entered from.
• Any other direction — SpaceAtlas traces through the Galaxy's cells in that direction and exits at the first cell beyond the boundary.

The entity type determines what happens on entry: a Galaxy-Space switches to that desktop space, a Galaxy-Wormhole or Galaxy-Gateway teleports you immediately, and a Galaxy-Nexus routes based on the direction you entered from — exactly like a regular Nexus.

When you create a Galaxy, you also choose its navigation mode: Edge or Memory. Those modes control how SpaceAtlas resolves movement through the larger region, so pick the one that matches whether you want edge-driven or memory-driven behavior.

To create a Galaxy, right-click any cell and choose Create Galaxy. Click adjacent cells to grow the selection (minimum 2 cells), then right-click or press Enter to finish and choose the entity type.

Click any circle on the grid to assign a space. Right-click for advanced options like wormholes, gateways, nexus, galaxies, and quick jumps.

Each action in the list shows its current shortcut binding. Click the info icon next to any action to see a description of what it does.

• Set a shortcut — click the Keyboard or Gesture button next to an action and press your desired key combination.
• Unbind a shortcut — clear an existing binding to leave an action unbound.
• Reset All to Defaults — restore all shortcuts to the original configuration.
• Disable Keyboard Shortcuts — temporarily turn off all keyboard shortcuts without removing your bindings.
• Touchpad/Mouse Gestures — gesture support is experimental. You can tune sensitivity, but gestures may not work reliably after system wake. If that happens, restart SpaceAtlas.

Useful defaults

• Bookmarks — F1 through F12 jump to bookmarked spaces.
• Ping-Pong Navigation — ⌘0 toggles between your current and previous space.
• App Cycling — ⌘⌥← and ⌘⌥→ cycle through apps.

Click the info icon next to any action to learn what it does. Use the Keyboard and Gesture buttons to set or change bindings.

Choose between two modes (Manual Assignment is the default):

• Manual Assignment — you choose exactly which apps belong to each space using the Add App button. Best for a fixed, repeatable workflow.
• Auto Detection — SpaceAtlas learns which apps belong to each space by watching what you use.
  How Auto Detection works

  When Auto Detection is active, SpaceAtlas observes which app is focused on each space and builds a mapping over time:

  • Auto Detection commits an observation only after you stay on a space long enough for the dwell threshold to pass (default: 10 seconds).
  • Quick visits are ignored, which helps prevent noisy mappings when you are just passing through.
  • A reconciliation pass periodically removes apps that are no longer visible on the space, keeping the mapping clean. The interval is configurable in Settings when Auto Detection is selected (default: 10 seconds).
  • Only the focused (frontmost) app is tracked — apps that are visible but never activated may not be added automatically.

  The result is a mapping that reflects how you actually use your spaces, without any manual setup.

Launching apps

Toggle Enable app launch on startup/space visit to have SpaceAtlas automatically open the assigned apps whenever you visit a space or start the app.

If this option is disabled, you can still launch the apps assigned to the current space on demand using a keyboard shortcut (default: ⌥L), which can be configured in the Keyboard Shortcuts tab.

Select a space on the left, then add or remove apps on the right. Use Manual Assignment for full control over your layout.

Display

• Display Mode — choose Constant to keep the overlay visible at all times, or Fade Out to have it appear only when navigating and disappear after a set number of seconds.
• Position — place the overlay in any of the nine screen positions (corners, edges, or center).
• Size — adjust how large the overlay appears on screen.
• Transparency — control how see-through the overlay is so it doesn't get in the way of your content.

Content

• Show full 20x20 grid — display the entire grid or only the mapped spaces.
• Show space images — display thumbnail images for each space in the overlay.
• Show space numbers — display the space number on each cell.
• Show space notes — display the notes you've added to each space in the Space-Matrix Mapping.

Highlight and Style

• Highlight Style — choose how the currently active space is highlighted (e.g. Border).
• Highlight Color — pick a color for the active space indicator.

Navigation Mode

• Carousel (Skip Unmapped) — wraps around the grid and skips over unmapped cells to the next mapped destination.
• Move Through Unmapped — continues through empty cells until you reach the next mapped destination in that direction.
• Hit Wall (Stop at Unmapped) — stops when the next position is unmapped, treating that gap like a wall.

The Overlay tab gives you full control over how the grid mini-map looks and behaves.

Import / Export

The Import / Export tab lets you save your setup before experimenting or moving to another Mac. You can export everything or only selected areas of your configuration, then import those settings later.

• Selective export — back up only the parts you need instead of the entire configuration.
• Conflict handling — choose how imported settings interact with your current setup when names or destinations overlap.
• Auto-backup — create a safety copy before applying an import that may overwrite existing settings.

Logging

The Logging tab is a full diagnostics area, not just a support footnote. Use it when you need more visibility into what SpaceAtlas is doing.

• Log level — choose how much detail SpaceAtlas records.
• Retention — decide how long log files are kept.
• File management — open the log folder quickly and remove older files when you no longer need them.

Advanced

The Advanced tab exposes the timing and behavior controls behind features like navigation, auto detection, and switching latency.

• Timing configuration — adjust thresholds and intervals for features that react over time.
• Cooldowns — fine-tune how quickly repeated actions can trigger.
• Instant switching — control the behavior of faster space-switching flows.

Signing in

1. Open Settings and go to the Account tab.
2. Enter your email address and click Send Code. A 6-digit verification code will be sent to your inbox.
3. Enter the code and click Verify Login to complete sign-in.

Authorization Status

Once signed in, the Account tab shows your current authorization status including your trial or license status, the signed-in email, and the app version you are running.

Account actions

• Send Code — sends a 6-digit verification code to your email.
• Verify Login — confirms your identity using the code you received.
• Refresh Status — re-checks your license and trial status with the server.
• Manage Account — opens your account page on the SpaceAtlas Labs website where you can view purchases, manage devices, and renew your license.
• Logout — signs you out of SpaceAtlas on this device.
• Deactivate Device — removes this device from your license, freeing up a seat for another machine.

The Account tab is your central place for signing in, checking your license status, and managing your device activations.

Session

Shows your current session details including your Device ID and when your access and refresh tokens expire. Click Refresh Session to extend your session if needed.

Licenses

Each license shows its status, seat usage, activation and expiration dates, and your last payment amount. Key details at a glance:

• Seats — how many devices are activated out of your total allowed (e.g. 1 / 6).
• Activated / Expires — when your license was activated and when it expires.
• Devices — lists each activated device by name, with its Device ID, last seen date, OS version, and app version. Click Remove to deactivate a device and free up a seat.

Updates and Downloads

• Owned Version — the version included with your original purchase.
• Latest Eligible — the newest version your license entitles you to. Click the Download button to get it.
• Update Status — shows whether your updates subscription is active.
• Renew Updates — extend your update eligibility at a discounted rate when renewing before expiration.

Your account page is the central place to manage devices, download updates, and renew your license.