Focus Actions

Navigate and switch focus between windows directionally

Overview

Focus actions enable keyboard-driven navigation between windows based on their spatial relationship. Instead of cycling through windows with Cmd+Tab, you can move focus directionally (up, down, left, right) or through window stacking order.

Defined in the static focus array (line 86):

static var focus: [WindowDirection] { 
    [.focusUp, .focusDown, .focusRight, .focusLeft, 
     .focusNextInStack] 
}

Computed Property

willFocusWindow · Bool

Returns true for all focus actions (line 96)

var willFocusWindow: Bool { 
    WindowDirection.focus.contains(self) 
}

Used to identify actions that change window focus without resizing or moving the focused window.

Directional Focus

Directional focus actions move keyboard focus to the nearest window in the specified direction.

focusLeft

focusLeft · WindowDirection

Moves focus to the nearest window positioned to the left.

Raw Value: "FocusLeft"

URL Scheme: loop://FocusLeft

Behavior:

• Activates the window whose center point is nearest to the left
• Searches within the same screen/Space
• No effect if no window exists to the left
• Does not move or resize any windows

Navigation Direction: .left (line 151)

Visual:

┌────────┐  ┌────────┐  ┌────────┐
│ Window │  │Current │  │        │
│   A    │  │ (You)  │  │        │
└────────┘  └────────┘  └────────┘
    ↑
 Focus moves here

focusRight

focusRight · WindowDirection

Moves focus to the nearest window positioned to the right.

Raw Value: "FocusRight"

URL Scheme: loop://FocusRight

Behavior:

• Activates the window whose center point is nearest to the right
• Searches within the same screen/Space
• No effect if no window exists to the right
• Does not move or resize any windows

Navigation Direction: .right (line 152)

Visual:

┌────────┐  ┌────────┐  ┌────────┐
│        │  │Current │  │ Window │
│        │  │ (You)  │  │   B    │
└────────┘  └────────┘  └────────┘
                            ↑
                     Focus moves here

focusUp

focusUp · WindowDirection

Moves focus to the nearest window positioned above.

Raw Value: "FocusUp"

URL Scheme: loop://FocusUp

Behavior:

• Activates the window whose center point is nearest above
• Searches within the same screen/Space
• No effect if no window exists above
• Does not move or resize any windows

Navigation Direction: .top (line 153)

Visual:

     ┌────────┐
     │ Window │ ← Focus moves here
     │   C    │
     └────────┘
     ┌────────┐
     │Current │
     │ (You)  │
     └────────┘

focusDown

focusDown · WindowDirection

Moves focus to the nearest window positioned below.

Raw Value: "FocusDown"

URL Scheme: loop://FocusDown

Behavior:

• Activates the window whose center point is nearest below
• Searches within the same screen/Space
• No effect if no window exists below
• Does not move or resize any windows

Navigation Direction: .bottom (line 154)

Visual:

     ┌────────┐
     │Current │
     │ (You)  │
     └────────┘
     ┌────────┐
     │ Window │ ← Focus moves here
     │   D    │
     └────────┘

Stack-Based Focus

focusNextInStack

focusNextInStack · WindowDirection

Moves focus to the next window in the stacking order.

Raw Value: "FocusNextInStack"

URL Scheme: loop://FocusNextInStack

Behavior:

• Cycles through windows in z-order (front to back)
• Similar to Cmd+Tab but for visible windows only
• Wraps around to first window after reaching last
• Works within current screen/Space
• Does not move or resize any windows

Stacking Order:

Window 1 (Front) → Window 2 → Window 3 → Window 1 (cycles)

Use Case: Cycle through overlapping windows without spatial reasoning

Navigation Direction Mapping

Focus actions map to NavigationDirection for internal routing (lines 149-157):

var focusDirection: NavigationDirection? {
    switch self {
    case .focusLeft: .left
    case .focusRight: .right
    case .focusUp: .top
    case .focusDown: .bottom
    default: nil
    }
}

This property enables directional window discovery algorithms.

Usage Examples

Vim-Style Navigation

# Navigate windows with directional keys
open "loop://FocusLeft"   # h
open "loop://FocusDown"   # j
open "loop://FocusUp"     # k
open "loop://FocusRight"  # l

Bind to keyboard shortcuts:

• Cmd+Ctrl+H: Focus left
• Cmd+Ctrl+J: Focus down
• Cmd+Ctrl+K: Focus up
• Cmd+Ctrl+L: Focus right

Multi-Window Workflow

# Navigate through a grid of windows
# Layout:
# ┌─────┬─────┬─────┐
# │  1  │  2  │  3  │
# ├─────┼─────┼─────┤
# │  4  │  5  │  6  │
# └─────┴─────┴─────┘

# From window 5 (center):
open "loop://FocusUp"     # → Window 2
open "loop://FocusRight"  # → Window 3
open "loop://FocusDown"   # → Window 6
open "loop://FocusLeft"   # → Window 5

Overlapping Windows

# Cycle through stacked windows on same position
open "loop://FocusNextInStack"  # Next window in stack
open "loop://FocusNextInStack"  # Next window in stack
open "loop://FocusNextInStack"  # Cycles back to first

Combining with Positioning

Focus actions are particularly powerful when combined with window positioning:

# Focus and resize workflow
open "loop://FocusLeft"     # Move focus to left window
open "loop://LeftHalf"      # Resize it to left half

open "loop://FocusRight"    # Move focus to right window
open "loop://RightHalf"     # Resize it to right half

Spatial Navigation Algorithm

Directional focus uses spatial proximity to determine the target window:

1. Calculate center points of all visible windows
2. Filter by direction (e.g., for focusLeft, only windows with center X < current window center X)
3. Compute distances from current window center to candidate window centers
4. Select nearest window based on Euclidean distance
5. Activate the target window

Edge Cases

Multiple windows at same distance

When multiple windows are equidistant, Loop selects based on:

• Z-order (frontmost window preferred)
• Window size (larger windows preferred)

No window in direction

If no window exists in the specified direction:

• Focus remains on current window
• No visual feedback or error
• Can be combined with screen switching for cross-display navigation

Diagonal window positions

For windows positioned diagonally:

• Directional focus uses the primary axis (horizontal or vertical)
• May require two focus actions to reach diagonal windows
• Example: Focus right, then focus up

Radial Menu Behavior

Focus actions don’t have specific directional angles in the radial menu (line 102):

var hasRadialMenuAngle: Bool {
    return !(... || willFocusWindow)
}

They appear as menu options rather than directional triggers.

Keyboard-Driven Workflows

Focus actions enable fully keyboard-driven window management:

Tiling Workflow

1. Focus window with directional navigation
2. Position window with positioning actions
3. Repeat for all windows in layout

Quick Reference Layout

# Set up documentation + code + terminal layout
# Start with browser (docs)
open "loop://LeftTwoThirds"      # Browser: 66% left

# Move to editor (code)
open "loop://FocusRight"
open "loop://TopRightQuarter"   # Editor: top-right 25%

# Move to terminal
open "loop://FocusDown"
open "loop://BottomRightQuarter" # Terminal: bottom-right 25%

Accessibility Benefits

Focus actions provide significant accessibility advantages:

• Keyboard-only navigation: No mouse required
• Spatial reasoning: Intuitive directional movement
• Predictable behavior: Consistent navigation patterns
• Fast context switching: Direct window selection without cycling

Troubleshooting

Focus doesn't move to expected window

• Verify windows are on the same screen/Space
• Check if target window is minimized or hidden
• Ensure target window is actually positioned in the expected direction
• Hidden windows and minimized windows are excluded from focus navigation

focusNextInStack cycles unexpectedly

• Only visible windows are included in stack order
• Minimized and hidden windows are excluded
• Stack order reflects z-order, not window creation order

Focus action has no effect

• No window exists in the specified direction
• Current window is the only visible window
• Target window may be on a different screen (use screen switching first)

Related Actions

Screen Switching

Move focus to windows on other displays

General Actions

Minimize and hide windows

Size Adjustment

Move windows after focusing them

WindowDirection Overview

Complete action reference

Best Practices

Combine with positioning: Use focus actions to select a window, then immediately apply a positioning action. This creates powerful keyboard-driven workflows.

Consistent keybinds: Map focus actions to easily reachable key combinations. Vim-style HJKL or arrow key combinations work well.

Multi-step navigation: For complex layouts, use multiple focus actions in sequence to reach distant windows efficiently.