script-kit-window-control

Window management APIs for Script Kit GPUI using macOS Accessibility (AX) APIs.Use when working with: window positioning/tiling, window state persistence, display/monitor detection, window capabilities, resize coalescing, orSpace (virtual desktop) operations. Covers modules: window_control.rs,window_control_enhanced/, window_manager.rs, window_ops.rs, window_resize.rs,window_state.rs.

⭐3stars🔀1forks📁View on GitHub🕐Updated Jan 9, 2026⬇️1downloads

When & Why to Use This Skill

The Script Kit Window Control skill provides a robust set of macOS window management APIs built on Accessibility (AX) services. Designed for GPUI-based applications, it simplifies complex tasks such as window tiling, positioning, and state persistence. It features advanced coordinate system conversion (AX to AppKit), multi-monitor detection, and coalesced operations to ensure jitter-free window resizing and movement, making it an essential tool for developers building high-performance macOS productivity software.

Use Cases

  • Automated Window Layouts: Programmatically tile or snap windows to specific screen regions like halves or quadrants to create optimized developer workspaces.
  • State Persistence & Restoration: Save window positions and dimensions to local storage and restore them accurately upon application restart, even in multi-monitor setups.
  • Coordinate System Synchronization: Seamlessly convert between macOS Accessibility (top-left origin) and AppKit (bottom-left origin) coordinate systems for precise UI element placement.
  • Smooth UI Resizing: Implement dynamic height calculations and deferred window operations to prevent visual jitter during rapid UI updates or view transitions.
  • Virtual Desktop Management: Detect and manage window placement across different macOS Spaces (virtual desktops) and monitors.
namescript-kit-window-control
description|
Use when working withwindow positioning/tiling, window state persistence,
Space (virtual desktop) operations. Covers moduleswindow_control.rs,

Script Kit Window Control

Window management system for Script Kit GPUI, built on macOS Accessibility APIs.

Architecture Overview

window_control.rs          - Core AX-based window operations (list, move, resize, tile)
window_control_enhanced/   - Enhanced types: WindowBounds, capabilities, DisplayInfo, SpaceManager
window_manager.rs          - Thread-safe window registry by role (Main, Notes, AI)
window_ops.rs              - Coalesced window operations via Window::defer
window_resize.rs           - Dynamic height calculation for different view types
window_state.rs            - Window position persistence to ~/.sk/kit/window-state.json

Coordinate Systems

Critical: Two coordinate systems are used internally:

System Origin Y Direction Used By
AX (Accessibility) Top-left of main screen Grows downward window_control.rs, window_control_enhanced/
AppKit (NSScreen) Bottom-left of main screen Grows upward NSScreen.visibleFrame, coordinate conversion

Conversion functions in window_control_enhanced/coords.rs:

  • appkit_to_ax() / ax_to_appkit() - Point conversion
  • nsrect_to_bounds() / bounds_to_nsrect() - Full rect conversion

Quick Reference

Check Accessibility Permission

use crate::window_control::{has_accessibility_permission, request_accessibility_permission};

if !has_accessibility_permission() {
    request_accessibility_permission(); // Opens System Preferences
}

List Windows

use crate::window_control::list_windows;

let windows = list_windows()?;
for w in windows {
    println!("{}: {} - {}", w.id, w.app, w.title);
}

Tile Window (Script Kit's Primary Use Case)

use crate::window_control::{tile_window, TilePosition, get_frontmost_window_of_previous_app};

// Get the window user was working with before invoking Script Kit
if let Some(window) = get_frontmost_window_of_previous_app()? {
    tile_window(window.id, TilePosition::LeftHalf)?;
}

Window Operations

use crate::window_control::{move_window, resize_window, set_window_bounds, Bounds};

move_window(window_id, 100, 200)?;
resize_window(window_id, 800, 600)?;
set_window_bounds(window_id, Bounds::new(100, 200, 800, 600))?;

Coalesced Operations (Prevents Jitter)

use crate::window_ops::{queue_resize, queue_move};

// Multiple calls coalesce - only final value executes
queue_resize(500.0, window, cx);
queue_move(bounds, window, cx);

Window Registry

use crate::window_manager::{register_window, get_main_window, WindowRole};

register_window(WindowRole::Main, ns_window_id);
let main = get_main_window(); // Returns Option<id>

Persistence

use crate::window_state::{save_window_bounds, load_window_bounds, WindowRole, PersistedWindowBounds};

// Save on hide/close
save_window_bounds(WindowRole::Main, PersistedWindowBounds::from_gpui(window_bounds));

// Restore on open
if let Some(bounds) = load_window_bounds(WindowRole::Main) {
    // Use bounds.to_gpui() for WindowOptions
}

Reference Files

For detailed API documentation:

Common Patterns

Script Kit Window Targeting

Script Kit is an LSUIElement (accessory app) that doesn't take menu bar ownership. To act on the window the user was focused on before Script Kit:

// This returns the focused window of the menu bar owner (the previous app)
let target = get_frontmost_window_of_previous_app()?;

Safe Resize During Render Cycle

Never resize directly in render callbacks - use coalescing:

// BAD: Can cause RefCell borrow panic
platform::resize_first_window_to_height(height);

// GOOD: Deferred to end of effect cycle
window_ops::queue_resize(height, window, cx);

Multi-Monitor Window Restoration

use crate::window_state::{get_initial_bounds, is_bounds_visible};
use crate::platform::get_macos_displays;

let displays = get_macos_displays();
let bounds = get_initial_bounds(WindowRole::Main, default_bounds, &displays);
// Automatically clamps to visible display if saved position is offscreen