Ultrawide monitors - back at it now that AI coding agents are much better

[johnstegeman]

I previously asked about this - i.e. the ability to have aerospace work better with ultrawide monitors. I thought - having 3 zones (left/center/right) makes more sense than tiling across huge screens.

In the past, I tried (and failed) with AI coding to make something work. Now that AI coding agents are much better, I decided to give it another crack. Bottom line - I have something working quite well. It is designed for me and my setup, so no promises that it is good for anything else.

What it does:

auto-detects wide screens
sets up 3 zones (left/center/right) with user-configurable ratios (defaults to 33/33/33)
when starting, if a window is in, or mostly in, a zone, puts the window into that zone
floating windows are not bound by zones
user-configurable default layout per zone
move-to-zone and focus-zone commands
probably some other stuff that i cant remember right now

if useful, happy to share (its a fork at the moment)

[johnstegeman]

in case its interesting, here is my design doc

Design: Ultrawide Zone Layout for AeroSpace

Generated by /office-hours
Branch: main
Repo: AeroSpace (fork)
Status: APPROVED
Mode: Builder

Problem Statement

AeroSpace's flat tiling model doesn't work well on ultrawide monitors (21:9+). Windows tile
across the full screen width, becoming uncomfortably wide and hard to navigate. Switching
between a dedicated ultrawide setup and a laptop screen scrambles the layout. There's no
memory of where windows belong per monitor configuration.

Constraints

• Swift 6.2+, macOS 13.0+
• Must stay compatible with AeroSpace's existing tree model (no reimplementation of
  layoutRecursive, TilingContainer, or Workspace from scratch)
• No TOML config required for basic operation (optional overrides OK for power users)
• Must gracefully handle: ultrawide disconnect mid-session, workspace switching, window
  creation/destruction while zones are active

Premises

1. Zones are named TilingContainer children of the workspace root — not separate
   workspaces or fake monitors. Reuses 100% of the existing layout engine.
2. Monitor profile is fingerprinted by [(width, height, originX, originY)] sorted by
   origin (implicitly encodes screen count, dimensions, and arrangement).
   CGDirectDisplayID is not used — it changes across reboots/reconnects.
3. Floating window support is ~80% already present (layoutFloatingWindow in
   layoutRecursive.swift:25). Main work is per-app config rules, not reimplementing
   float logic.
4. (Revised) Zone layout activates automatically at aspect ratio > ~2.1:1. No TOML
   required. Default: equal thirds. Optional [zones] widths = [0.30, 0.40, 0.30]
   in TOML for custom proportions (must sum to 1.0; invalid values fall back to thirds).

Approaches Considered

Approach A: Zones as named TilingContainers (chosen)

• Auto-split workspace root into 3 fixed TilingContainers on ultrawide detection
• Windows assigned to zones; fallback to single container on narrow screens
• Reuses 100% of existing layout engine
• Completeness: 9/10

Approach B: Zones as fake monitors

• Virtually split ultrawide into 3 CGRect regions, treat as separate monitors
• Full workspace isolation per zone; more invasive, touches monitor detection throughout
• Completeness: 8/10 but ~3x the code change surface

Approach C: Config-only workspace pinning

• Use existing forceAssignedMonitor mechanism with virtual rects
• ~50 lines of new code, but awkward naming conventions and poor laptop fallback
• Completeness: 5/10

Recommended Approach2

Approach A — Zones as named TilingContainers.

The existing tree model is already the right abstraction. TilingContainer is a
general-purpose node that can hold windows and sub-containers. Adding named, fixed-weight
zone containers at the workspace root is additive: it doesn't break any existing behavior,
the layout engine already handles recursive layout within containers, and the fallback
(removing the zone split on non-ultrawide monitors) is a matter of collapsing those
containers back to the root.

Tree structure

CRITICAL: Zone containers are children of rootTilingContainer, NOT direct children
of Workspace. WorkspaceEx.swift:17 enforces exactly one TilingContainer child per
Workspace and calls die() otherwise. The correct tree is:

Workspace
└── TilingContainer (rootTilingContainer, .h)   ← enforced by WorkspaceEx.swift
    ├── TilingContainer "left"   (zone, 1/3)
    ├── TilingContainer "center" (zone, 2/5)
    └── TilingContainer "right"  (zone, 1/3)

On non-ultrawide: zones are removed and rootTilingContainer becomes a flat container.

Workspace
└── TilingContainer (rootTilingContainer)
    ├── Window: Terminal
    └── Window: Browser

Implementation plan

Phase 1: Zone engine (core, start here)

1. Add isUltrawide to Monitor in Sources/AppBundle/model/MonitorEx.swift:

   extension Monitor {
       var isUltrawide: Bool { visibleRect.width / visibleRect.height > 2.1 }
   }

2. Add isZoneContainer: Bool = false to TilingContainer in TilingContainer.swift.
   Modify unbindEmptyAndAutoFlatten() in normalizeContainers.swift:

   • Skip removal of empty containers where isZoneContainer == true (line 27 guard)
   • Skip single-child flattening where isZoneContainer == true (line 12 guard)
     This allows empty zone containers to persist between window moves.

3. Add zoneContainers to Workspace:

   // in Workspace class body
   var zoneContainers: [String: TilingContainer] = [:]  // "left", "center", "right"

4. Add ensureZoneContainers() to Workspace, called from rearrangeWorkspacesOnMonitors()
   by iterating screenPointToVisibleWorkspace.values — NOT from layoutWorkspace().
   Monitor-change is the right trigger.

   • If workspaceMonitor.isUltrawide AND zoneContainers is empty:
     a. Force rootTilingContainer.changeOrientation(.h) (zones must be side-by-side
     regardless of defaultRootContainerOrientation in user config).
     b. Create 3 TilingContainer children on rootTilingContainer with configurable weights.
     Default: equal thirds. Optional TOML override:

     [zones]
     widths = [0.30, 0.40, 0.30]  # proportions, must sum to 1.0

     Parsed via ZonesConfig struct in Config.swift. Falls back to [1/3, 1/3, 1/3]
     if absent or invalid. Initial hWeight for each zone = monitorWidth * proportion.
     c. Set isZoneContainer = true on each created container.
     d. Store references in zoneContainers["left"], ["center"], ["right"].
   • If NOT ultrawide AND zoneContainers is non-empty:
     flatten: re-parent each zone container's windows to rootTilingContainer in order
     (left first, then center, then right), remove zone containers from the tree, clear
     zoneContainers. The flatten order governs the resulting tiling layout on laptop.
   • After rearrangeWorkspacesOnMonitors(), iterate:

     for workspace in screenPointToVisibleWorkspace.values {
         workspace.ensureZoneContainers()
     }

5. Modify MacWindow.swift:233 fallback in unbindAndGetBindingDataForNewTilingWindow:
   When no MRU window exists and zones are active, route to center zone instead of root:

   } else {
       let parent = workspace.zoneContainers["center"] ?? workspace.rootTilingContainer
       return BindingData(parent: parent, adaptiveWeight: WEIGHT_AUTO, index: INDEX_BIND_LAST)
   }

6. Modify FlattenWorkspaceTreeCommand.swift: after re-parenting windows, clear
   workspace.zoneContainers = [:]. This prevents stale zone references after flatten.

7. Add Config.ZonesConfig struct and wire it into Config:

   // Config.swift
   struct ZonesConfig {
       var widths: [Double] = [1.0/3, 1.0/3, 1.0/3]
   }
   // In Config struct:
   var zones: ZonesConfig = ZonesConfig()

   Add [zones] section parsing in parseConfig.swift.

8. Add move-node-to-zone left|center|right command in Sources/AppBundle/command/impl/MoveNodeToZoneCommand.swift.
   Follow the MoveNodeToWorkspaceCommand pattern. Behavior: re-parent focused window into
   the named zone container. Focus follows the window. If zoneContainers is empty: no-op
   with stderr: move-node-to-zone: zones not active on this workspace.
   If invalid zone name: stderr: move-node-to-zone: unknown zone "foo" (valid: left, center, right).

   Also add focus-zone left|center|right command in Sources/AppBundle/command/impl/FocusZoneCommand.swift.
   Behavior: sets workspace.focusedZone (new String? property on Workspace) to the named zone.
   This controls which zone gets the next new window (overrides MRU for one placement, then reverts to MRU).
   If zoneContainers is empty: no-op with stderr: focus-zone: zones not active on this workspace.
   Updates menu bar active zone indicator without moving any windows.
   Follow the FlattenWorkspaceTreeCommand pattern. Behavior: re-parent focused window into
   the named zone container. Focus follows the window. If zoneContainers is empty: no-op
   with a stderr message.

9. Add ensureZoneContainers() call after config reload in ReloadConfigCommand (or
   wherever config reload triggers workspace refresh). After normalizeContainers() runs
   post-reload, iterate visible workspaces and re-establish zones:

   for workspace in screenPointToVisibleWorkspace.values {
       workspace.ensureZoneContainers()
   }

Phase 2: Layout memory per monitor profile

6. Add MonitorProfile: a Codable struct wrapping [(width: CGFloat, height: CGFloat, originX: CGFloat, originY: CGFloat)]
   sorted by originX then originY. Used as a String key (via JSON encoding) in the
   memory dictionary.

7. Add ZoneMemory: persists [windowKey: zoneName] per MonitorProfile.
   Window key is bundleID + "-" + stableHash(windowTitle) where possible.
   Important: Swift's String.hash is randomized per process launch — do not use it.
   Use FNV-1a or store raw title truncated to 64 chars.
   Known limitation: Window titles change (browsers, terminals, editors). On reconnect,
   title-changed windows silently fall back to center zone. For Phase 2, this is accepted.
   Fall back to bundleID-only for single-window apps where multi-instance isn't a concern.
   Revisit in a future phase if the miss rate is annoying in practice.
   Windows not found in memory: silently skipped. Corrupt/missing JSON: silently reset.
   Write to ~/Library/Application Support/AeroSpace/zone-memory.json.

8. On rearrangeWorkspacesOnMonitors(), after ensureZoneContainers() runs and zones
   exist: look up each open window by its identity key in ZoneMemory for the current
   MonitorProfile, then call moveToZone(_:) to place it in the remembered zone.
   Call site: end of rearrangeWorkspacesOnMonitors() in Workspace.swift.

Phase 3: Float rules (note — mostly already works)

Float support via on-window-detected + layout floating already works in the codebase
(layoutFloatingWindow in layoutRecursive.swift:25). Test with Raycast and 1Password
before shipping Phase 1. No new code expected; document the config pattern.

Key files to touch

File	Change
Sources/AppBundle/model/MonitorEx.swift	Add Monitor.isUltrawide
Sources/AppBundle/tree/TilingContainer.swift	Add var isZoneContainer: Bool = false
Sources/AppBundle/tree/normalizeContainers.swift	Guard isZoneContainer in unbindEmptyAndAutoFlatten()
Sources/AppBundle/tree/Workspace.swift	Add zoneContainers, ensureZoneContainers(), call in rearrangeWorkspacesOnMonitors()
Sources/AppBundle/tree/WorkspaceEx.swift	Add moveToZone(_:) helper
Sources/AppBundle/tree/MacWindow.swift	Intercept fallback at line 233
Sources/AppBundle/command/impl/FlattenWorkspaceTreeCommand.swift	Clear zoneContainers + isZoneContainer flags after flatten
Sources/AppBundle/command/impl/ReloadConfigCommand.swift (or refresh)	Call ensureZoneContainers() after reload
Sources/AppBundle/config/Config.swift	Add ZonesConfig struct + zones field
Sources/AppBundle/config/parseConfig.swift	Add [zones] section parsing
Sources/AppBundle/command/impl/MoveNodeToZoneCommand.swift (new)	move-node-to-zone left|center|right command
Sources/Common/cmdArgs/impl/MoveNodeToZoneCmdArgs.swift (new)	Command args for move-node-to-zone
Sources/AppBundle/command/impl/FocusZoneCommand.swift (new)	focus-zone left|center|right command
Sources/Common/cmdArgs/impl/FocusZoneCmdArgs.swift (new)	Command args for focus-zone
Sources/AppBundle/ZoneMemory.swift (new)	MonitorProfile + ZoneMemory persistence (Phase 2)
Sources/AppBundleTests/ZoneEngineTests.swift (new)	Unit tests: isUltrawide, ensureZoneContainers, normalization, fallback
Sources/AppBundleTests/ZoneMemoryTests.swift (new)	Unit tests: ZoneMemory, MonitorProfile, FNV-1a
Sources/AppBundleTests/command/FlattenWorkspaceTreeCommandTest.swift	Regression: zones + flatten

Open Questions

• Should zone weights be adjustable at runtime (drag-resize between zones)?
  If so, those weights need to persist across workspace switches. Deferred.
• Empty zone behavior (DECIDED): Empty zones keep reserved space. The zone column holds its configured width even with no windows. This is the contract with the user: zones are always present, always the same width. Collapse behavior is not implemented. This is enforced by the isZoneContainer guard in unbindEmptyAndAutoFlatten() (already in the plan).
• windowTitle.hash is fragile for apps with dynamic titles (browser tabs, editors).
  Accept this limitation for the initial release; revisit if it proves annoying in practice.

Success Criteria

• Connect ultrawide: workspace root automatically shows 3 equal zones, no config
• Open a window: lands in focused zone; if no zone is focused, lands in center zone
• move-node-to-zone right hotkey moves the focused window to the right zone
• Disconnect ultrawide: windows from all zones flatten into workspace root in order
  (left zone children first, then center, then right); layout is a normal tiling layout
• Reconnect ultrawide: windows restore to their last-known zones by bundleID+titleHash;
  windows not found in memory are silently left in their current position
• Float rule for Raycast: floats above zones without disrupting zone tiling
  (validated via existing on-window-detected + layout floating — no new code)
• Test plan: unit test isUltrawide threshold; unit test ensureZoneContainers
  (both directions: split and flatten); integration test new-window placement on ultrawide;
  manual test monitor reconnect with and without zone memory populated

Distribution Plan

This is a personal fork. No distribution needed. Build with ./build-debug.sh,
run with ./run-debug.sh.

Test Plan

File: Sources/AppBundleTests/ZoneEngineTests.swift

• testIsUltrawide_threshold: 2560x1080 → true; 2560x1440 → false; 2560x1080 - 1px → false
• testEnsureZoneContainers_split: ultrawide workspace → 3 containers in rootTilingContainer, correct weights, isZoneContainer = true
• testEnsureZoneContainers_noOp: already has zones → no-op (same container refs)
• testEnsureZoneContainers_flatten: zones present, non-ultrawide → windows re-parented in order, zoneContainers empty
• testEnsureZoneContainers_flattenNoOp: no zones, non-ultrawide → no-op
• testEnsureZoneContainers_orientation: vertical config → rootTilingContainer still forced to .h
• testNormalizationSurvivesEmptyZone: create zones, remove all windows from left zone, call normalizeContainers → left zone still exists
• testNormalizationSurvivesSingleWindow: create zones, left zone has 1 window → normalizeContainers does NOT flatten it up
• testConfigReloadRestoresZones: create zones, reload config, verify zones restored
• testNewWindow_fallbackToCenter: zones active, no MRU window → window lands in center zone
• testNewWindow_followsMruZone: zones active, MRU in left zone → new window also in left zone
• testMoveToZone_basic: focused window moves to named zone, focus follows
• testMoveToZone_noZones: non-ultrawide workspace → no-op + stderr output

File: Sources/AppBundleTests/command/FlattenWorkspaceTreeCommandTest.swift (modification)

• testFlattenClearsZoneContainers [REGRESSION]: set up zones, run Flatten, assert zoneContainers.isEmpty, assert zones don't reappear on next ensureZoneContainers() call

File: Sources/AppBundleTests/ZoneMemoryTests.swift

• testMonitorProfile_fingerprint: same layout → same key; different layout → different key
• testZoneMemory_persistAndRestore: persist window→zone, reload from disk, verify mapping
• testZoneMemory_corruptJson: write garbage JSON → silently resets to empty
• testStableHash_acrossInvocations: same title string → same hash every time (not Swift .hash)

Next Steps

1. Add isZoneContainer: Bool to TilingContainer; update normalizeContainers.swift; write testNormalizationSurvivesEmptyZone + testNormalizationSurvivesSingleWindow tests first (TDD)
2. Add Monitor.isUltrawide + testIsUltrawide_threshold test
3. Add zoneContainers dict + ensureZoneContainers() to Workspace; write split/flatten/orientation/configReload tests
4. Wire ensureZoneContainers() into rearrangeWorkspacesOnMonitors() iteration + ReloadConfigCommand
5. Modify MacWindow.swift:233 fallback; write testNewWindow_fallbackToCenter test
6. Modify FlattenWorkspaceTreeCommand; write testFlattenClearsZoneContainers regression test
7. Add ZonesConfig to Config.swift + parse [zones] in parseConfig.swift
8. Add MoveToZoneCommand + args; write move tests; bind a hotkey
9. Test manually with ultrawide: split, placement, empty zone survival, disconnect, reconnect
10. Verify float rules with Raycast/1Password via existing on-window-detected
11. Build ZoneMemory + MonitorProfile (Phase 2); write ZoneMemory tests

Design Decisions (from /plan-design-review)

Zone Visual Identity (Pass 1 — decided)

Zones are structurally invisible in the window layout (no special borders or gaps vs. normal tiling). Visual feedback comes from the menu bar zone indicator, shown only when ultrawide is active.

Menu bar zone indicator spec:

• Add a new TrayItem type .zone in TrayItem.swift
• Separator : after the workspace items (same pattern as mode indicator in MenuBarLabel.swift)
• Three zone items rendered as squares: left, center, right
• Active zone (focused window's parent zone container) = filled square (same as active workspace style in MenuBarLabel.swift:149)
• Inactive zones = bordered square (same as inactive workspace style in MenuBarLabel.swift:160)
• When ultrawide is NOT active: zone items absent (no separator, no squares)
• Only shown in squares, i3, i3Ordered display styles (not monospacedText/systemText)

Files to add to Phase 1 (Key files table):

File	Change
Sources/AppBundle/ui/TrayMenuModel.swift	Add activeZone: String? property (nil when zones inactive)
Sources/AppBundle/ui/MenuBarLabel.swift	Render zone squares after workspace items when activeZone != nil
Sources/AppBundle/ui/TrayItem.swift	Add .zone TrayItem type

Update TrayMenuModel when:

• ensureZoneContainers() activates/deactivates zones
• move-node-to-zone command runs
• Focus changes to a window in a different zone

Hotkey Bindings (Pass 3 — decided)

Personal config bindings for move-node-to-zone (Gallium layout):

# In aerospace.toml, add to [mode.main.binding]:
alt-shift-h = 'move-node-to-zone left'    # ⚠ conflicts with default 'move left'
alt-shift-a = 'move-node-to-zone center'  # ⚠ conflicts with default 'move-node-to-workspace A'
alt-shift-e = 'move-node-to-zone right'   # ⚠ conflicts with default 'move-node-to-workspace E'
# focus-zone (switch active zone without moving a window):
alt-ctrl-h = 'focus-zone left'
alt-ctrl-a = 'focus-zone center'
alt-ctrl-e = 'focus-zone right'

Note: All three conflict with docs/config-examples/default-config.toml. Resolve against your personal ~/.config/aerospace/aerospace.toml during setup. If you've already remapped or dropped those default bindings, these are clear.

Interaction States (Pass 2 — decided)

Follows AeroSpace command conventions: silent on success, stderr on failure.

Event	User Experience
Ultrawide connects, zones activate	Windows rearrange into 3 columns, menu bar shows zone squares. Silent.
Ultrawide disconnects, zones flatten	Windows flatten to root container. Zone squares disappear from menu bar. Silent.
move-node-to-zone left|center|right (success)	Window moves to named zone. Focus follows. Menu bar updates active zone. Silent.
move-node-to-zone when zones not active	stderr: move-node-to-zone: zones not active on this workspace
move-node-to-zone foo (invalid zone name)	stderr: move-node-to-zone: unknown zone "foo" (valid: left, center, right)
Config reload while zones active	Zones re-established silently after normalizeContainers() runs.
New window, zones active, no MRU	Window lands in center zone. Silent.
New window, zones active, MRU in left	Window lands in left zone (follows MRU). Silent.
Empty zone	Zone container persists (reserved space visible in layout). Silent. No special indicator beyond menu bar zone square still present.

GSTACK REVIEW REPORT

Review	Trigger	Why	Runs	Status	Findings
CEO Review	/plan-ceo-review	Scope & strategy	0	—	—
Codex Review	/codex review	Independent 2nd opinion	0	—	—
Eng Review	/plan-eng-review	Architecture & tests (required)	1	CLEAR (PLAN)	8 issues, 1 critical gap (zone GC loss, deferred)
Design Review	/plan-design-review	UI/UX gaps	1	CLEAR (FULL)	score: 4/10 → 9/10, 6 decisions
DX Review	/plan-devex-review	Developer experience gaps	0	—	—

OUTSIDE VOICE (Claude subagent): Found normalizeContainers() conflict — zones destroyed when empty. Fixed via isZoneContainer flag on TilingContainer.

VERDICT: ENG + DESIGN CLEARED — ready to implement.