@lattices/cli 0.3.0 → 0.4.1

package/app/Sources/WindowTiler.swift

@@ -25,6 +25,13 @@ private let _SLSMoveWindow: SLSMoveWindowFunc? = {
     return unsafeBitCast(sym, to: SLSMoveWindowFunc.self)
 }()
 
+private typealias SLSOrderWindowFunc = @convention(c) (Int32, UInt32, Int32, UInt32) -> CGError
+
+private let _SLSOrderWindow: SLSOrderWindowFunc? = {
+    guard let sl = skyLight, let sym = dlsym(sl, "SLSOrderWindow") ?? dlsym(sl, "CGSOrderWindow") else { return nil }
+    return unsafeBitCast(sym, to: SLSOrderWindowFunc.self)
+}()
+
 private let _SLSDisableUpdate: SLSDisableUpdateFunc? = {
     guard let sl = skyLight, let sym = dlsym(sl, "SLSDisableUpdate") else { return nil }
     return unsafeBitCast(sym, to: SLSDisableUpdateFunc.self)
@@ -122,25 +129,75 @@ private class HighlightBorderView: NSView {
     }
 }
 
+// MARK: - Grid Tiling
+
+/// Compute fractional (x, y, w, h) for a cell in a cols×rows grid.
+func tileGrid(cols: Int, rows: Int, col: Int, row: Int) -> (CGFloat, CGFloat, CGFloat, CGFloat) {
+    let w = 1.0 / CGFloat(cols)
+    let h = 1.0 / CGFloat(rows)
+    return (CGFloat(col) * w, CGFloat(row) * h, w, h)
+}
+
+/// Parse a grid string like "grid:3x2:0,0" → fractional (x, y, w, h).
+func parseGridString(_ str: String) -> (CGFloat, CGFloat, CGFloat, CGFloat)? {
+    GridPlacement.parse(str)?.fractions
+}
+
 enum TilePosition: String, CaseIterable, Identifiable {
+    // 1x1
+    case maximize    = "maximize"
+    case center      = "center"
+    // 2x1 (halves, full height)
     case left        = "left"
     case right       = "right"
+    // 1x2 (halves, full width)
     case top         = "top"
     case bottom      = "bottom"
+    // 2x2 (quarters)
     case topLeft     = "top-left"
     case topRight    = "top-right"
     case bottomLeft  = "bottom-left"
     case bottomRight = "bottom-right"
-    case maximize    = "maximize"
-    case center      = "center"
+    // 3x1 (thirds, full height)
     case leftThird   = "left-third"
     case centerThird = "center-third"
     case rightThird  = "right-third"
+    // 3x2 (sixths)
+    case topLeftThird      = "top-left-third"
+    case topCenterThird    = "top-center-third"
+    case topRightThird     = "top-right-third"
+    case bottomLeftThird   = "bottom-left-third"
+    case bottomCenterThird = "bottom-center-third"
+    case bottomRightThird  = "bottom-right-third"
+    // 4x1 (fourths, full height)
+    case firstFourth  = "first-fourth"
+    case secondFourth = "second-fourth"
+    case thirdFourth  = "third-fourth"
+    case lastFourth   = "last-fourth"
+    // 4x2 (eighths)
+    case topFirstFourth    = "top-first-fourth"
+    case topSecondFourth   = "top-second-fourth"
+    case topThirdFourth    = "top-third-fourth"
+    case topLastFourth     = "top-last-fourth"
+    case bottomFirstFourth  = "bottom-first-fourth"
+    case bottomSecondFourth = "bottom-second-fourth"
+    case bottomThirdFourth  = "bottom-third-fourth"
+    case bottomLastFourth   = "bottom-last-fourth"
+    // Horizontal thirds / quarters
+    case topThird    = "top-third"
+    case middleThird = "middle-third"
+    case bottomThird = "bottom-third"
+    case leftQuarter   = "left-quarter"
+    case rightQuarter  = "right-quarter"
+    case topQuarter    = "top-quarter"
+    case bottomQuarter = "bottom-quarter"
 
     var id: String { rawValue }
 
     var label: String {
         switch self {
+        case .maximize:    return "Max"
+        case .center:      return "Center"
         case .left:        return "Left"
         case .right:       return "Right"
         case .top:         return "Top"
@@ -149,11 +206,34 @@ enum TilePosition: String, CaseIterable, Identifiable {
         case .topRight:    return "Top Right"
         case .bottomLeft:  return "Bottom Left"
         case .bottomRight: return "Bottom Right"
-        case .maximize:    return "Max"
-        case .center:      return "Center"
-        case .leftThird:   return "Left Third"
-        case .centerThird: return "Center Third"
-        case .rightThird:  return "Right Third"
+        case .leftThird:   return "Left ⅓"
+        case .centerThird: return "Center ⅓"
+        case .rightThird:  return "Right ⅓"
+        case .topLeftThird:      return "Top Left ⅓"
+        case .topCenterThird:    return "Top Center ⅓"
+        case .topRightThird:     return "Top Right ⅓"
+        case .bottomLeftThird:   return "Bottom Left ⅓"
+        case .bottomCenterThird: return "Bottom Center ⅓"
+        case .bottomRightThird:  return "Bottom Right ⅓"
+        case .firstFourth:  return "1st ¼"
+        case .secondFourth: return "2nd ¼"
+        case .thirdFourth:  return "3rd ¼"
+        case .lastFourth:   return "4th ¼"
+        case .topFirstFourth:    return "Top 1st ¼"
+        case .topSecondFourth:   return "Top 2nd ¼"
+        case .topThirdFourth:    return "Top 3rd ¼"
+        case .topLastFourth:     return "Top 4th ¼"
+        case .bottomFirstFourth:  return "Bottom 1st ¼"
+        case .bottomSecondFourth: return "Bottom 2nd ¼"
+        case .bottomThirdFourth:  return "Bottom 3rd ¼"
+        case .bottomLastFourth:   return "Bottom 4th ¼"
+        case .topThird:    return "Top ⅓"
+        case .middleThird: return "Middle ⅓"
+        case .bottomThird: return "Bottom ⅓"
+        case .leftQuarter:   return "Left ¼"
+        case .rightQuarter:  return "Right ¼"
+        case .topQuarter:    return "Top ¼"
+        case .bottomQuarter: return "Bottom ¼"
         }
     }
 
@@ -172,25 +252,66 @@ enum TilePosition: String, CaseIterable, Identifiable {
         case .leftThird:   return "rectangle.leadingthird.inset.filled"
         case .centerThird: return "rectangle.center.inset.filled"
         case .rightThird:  return "rectangle.trailingthird.inset.filled"
+        case .topThird:    return "rectangle.topthird.inset.filled"
+        case .middleThird: return "rectangle.center.inset.filled"
+        case .bottomThird: return "rectangle.bottomthird.inset.filled"
+        case .leftQuarter: return "rectangle.leadinghalf.inset.filled"
+        case .rightQuarter:return "rectangle.trailinghalf.inset.filled"
+        case .topQuarter:  return "rectangle.tophalf.inset.filled"
+        case .bottomQuarter:return "rectangle.bottomhalf.inset.filled"
+        default:           return "rectangle.split.3x3.fill"
         }
     }
 
     /// Returns (x, y, w, h) as fractions of screen
     var rect: (CGFloat, CGFloat, CGFloat, CGFloat) {
         switch self {
-        case .left:        return (0,     0,   0.5,   1.0)
-        case .right:       return (0.5,   0,   0.5,   1.0)
-        case .top:         return (0,     0,   1.0,   0.5)
-        case .bottom:      return (0,     0.5, 1.0,   0.5)
-        case .topLeft:     return (0,     0,   0.5,   0.5)
-        case .topRight:    return (0.5,   0,   0.5,   0.5)
-        case .bottomLeft:  return (0,     0.5, 0.5,   0.5)
-        case .bottomRight: return (0.5,   0.5, 0.5,   0.5)
+        // 1x1
         case .maximize:    return (0,     0,   1.0,   1.0)
         case .center:      return (0.15,  0.1, 0.7,   0.8)
-        case .leftThird:   return (0,     0,   0.333, 1.0)
-        case .centerThird: return (0.333, 0,   0.334, 1.0)
-        case .rightThird:  return (0.667, 0,   0.333, 1.0)
+        // 2x1
+        case .left:        return tileGrid(cols: 2, rows: 1, col: 0, row: 0)
+        case .right:       return tileGrid(cols: 2, rows: 1, col: 1, row: 0)
+        // 1x2
+        case .top:         return tileGrid(cols: 1, rows: 2, col: 0, row: 0)
+        case .bottom:      return tileGrid(cols: 1, rows: 2, col: 0, row: 1)
+        // 2x2
+        case .topLeft:     return tileGrid(cols: 2, rows: 2, col: 0, row: 0)
+        case .topRight:    return tileGrid(cols: 2, rows: 2, col: 1, row: 0)
+        case .bottomLeft:  return tileGrid(cols: 2, rows: 2, col: 0, row: 1)
+        case .bottomRight: return tileGrid(cols: 2, rows: 2, col: 1, row: 1)
+        // 3x1
+        case .leftThird:   return tileGrid(cols: 3, rows: 1, col: 0, row: 0)
+        case .centerThird: return tileGrid(cols: 3, rows: 1, col: 1, row: 0)
+        case .rightThird:  return tileGrid(cols: 3, rows: 1, col: 2, row: 0)
+        // 3x2
+        case .topLeftThird:      return tileGrid(cols: 3, rows: 2, col: 0, row: 0)
+        case .topCenterThird:    return tileGrid(cols: 3, rows: 2, col: 1, row: 0)
+        case .topRightThird:     return tileGrid(cols: 3, rows: 2, col: 2, row: 0)
+        case .bottomLeftThird:   return tileGrid(cols: 3, rows: 2, col: 0, row: 1)
+        case .bottomCenterThird: return tileGrid(cols: 3, rows: 2, col: 1, row: 1)
+        case .bottomRightThird:  return tileGrid(cols: 3, rows: 2, col: 2, row: 1)
+        // 4x1
+        case .firstFourth:  return tileGrid(cols: 4, rows: 1, col: 0, row: 0)
+        case .secondFourth: return tileGrid(cols: 4, rows: 1, col: 1, row: 0)
+        case .thirdFourth:  return tileGrid(cols: 4, rows: 1, col: 2, row: 0)
+        case .lastFourth:   return tileGrid(cols: 4, rows: 1, col: 3, row: 0)
+        // 4x2
+        case .topFirstFourth:    return tileGrid(cols: 4, rows: 2, col: 0, row: 0)
+        case .topSecondFourth:   return tileGrid(cols: 4, rows: 2, col: 1, row: 0)
+        case .topThirdFourth:    return tileGrid(cols: 4, rows: 2, col: 2, row: 0)
+        case .topLastFourth:     return tileGrid(cols: 4, rows: 2, col: 3, row: 0)
+        case .bottomFirstFourth:  return tileGrid(cols: 4, rows: 2, col: 0, row: 1)
+        case .bottomSecondFourth: return tileGrid(cols: 4, rows: 2, col: 1, row: 1)
+        case .bottomThirdFourth:  return tileGrid(cols: 4, rows: 2, col: 2, row: 1)
+        case .bottomLastFourth:   return tileGrid(cols: 4, rows: 2, col: 3, row: 1)
+        case .topThird:    return tileGrid(cols: 1, rows: 3, col: 0, row: 0)
+        case .middleThird: return tileGrid(cols: 1, rows: 3, col: 0, row: 1)
+        case .bottomThird: return tileGrid(cols: 1, rows: 3, col: 0, row: 2)
+        case .leftQuarter:   return tileGrid(cols: 4, rows: 1, col: 0, row: 0)
+        case .rightQuarter:  return tileGrid(cols: 4, rows: 1, col: 3, row: 0)
+        case .topQuarter:    return tileGrid(cols: 1, rows: 4, col: 0, row: 0)
+        case .bottomQuarter: return tileGrid(cols: 1, rows: 4, col: 0, row: 3)
         }
     }
 }
@@ -272,6 +393,10 @@ enum WindowTiler {
     /// Convert fractional rect to AppleScript bounds {left, top, right, bottom}
     /// AppleScript uses top-left origin; NSScreen uses bottom-left origin
     private static func appleScriptBounds(for position: TilePosition, screen: NSScreen? = nil) -> (Int, Int, Int, Int) {
+        appleScriptBounds(for: position.rect, screen: screen)
+    }
+
+    private static func appleScriptBounds(for fractions: (CGFloat, CGFloat, CGFloat, CGFloat), screen: NSScreen? = nil) -> (Int, Int, Int, Int) {
         let targetScreen = screen ?? NSScreen.main
         guard let targetScreen else { return (0, 0, 960, 540) }
         let full = targetScreen.frame
@@ -282,7 +407,7 @@ enum WindowTiler {
         let visW = Int(visible.width)
         let visH = Int(visible.height)
 
-        let (fx, fy, fw, fh) = position.rect
+        let (fx, fy, fw, fh) = fractions
         let x1 = visLeft + Int(CGFloat(visW) * fx)
         let y1 = visTop + Int(CGFloat(visH) * fy)
         let x2 = x1 + Int(CGFloat(visW) * fw)
@@ -290,13 +415,23 @@ enum WindowTiler {
         return (x1, y1, x2, y2)
     }
 
+    /// Get the main screen's frame (safe to call from main thread only).
+    static func mainScreenFrame() -> CGRect {
+        return NSScreen.main?.frame ?? NSScreen.screens.first?.frame ?? CGRect(x: 0, y: 0, width: 1920, height: 1080)
+    }
+
     /// Compute AX-coordinate frame for a tile position on a given screen
     static func tileFrame(for position: TilePosition, on screen: NSScreen) -> CGRect {
+        tileFrame(fractions: position.rect, on: screen)
+    }
+
+    /// Compute AX-coordinate frame for arbitrary fractional placement on a given screen.
+    static func tileFrame(fractions: (CGFloat, CGFloat, CGFloat, CGFloat), on screen: NSScreen) -> CGRect {
         let visible = screen.visibleFrame
         guard let primary = NSScreen.screens.first else { return .zero }
         let primaryH = primary.frame.height
         let axTop = primaryH - visible.maxY
-        let (fx, fy, fw, fh) = position.rect
+        let (fx, fy, fw, fh) = fractions
         return CGRect(
             x: visible.origin.x + visible.width * fx,
             y: axTop + visible.height * fy,
@@ -305,6 +440,10 @@ enum WindowTiler {
         )
     }
 
+    static func tileFrame(for placement: PlacementSpec, on screen: NSScreen) -> CGRect {
+        tileFrame(fractions: placement.fractions, on: screen)
+    }
+
     /// Compute AX-coordinate frame for a tile position within a raw display CGRect (CG/AX coords)
     static func tileFrame(for position: TilePosition, inDisplay displayRect: CGRect) -> CGRect {
         let (fx, fy, fw, fh) = position.rect
@@ -330,12 +469,16 @@ enum WindowTiler {
     /// Tile a specific terminal window on a given screen.
     /// Fast path: DesktopModel → AX. Fallback: AX search → AppleScript last resort.
     static func tile(session: String, terminal: Terminal, to position: TilePosition, on screen: NSScreen) {
+        tile(session: session, terminal: terminal, to: .tile(position), on: screen)
+    }
+
+    static func tile(session: String, terminal: Terminal, to placement: PlacementSpec, on screen: NSScreen) {
         let diag = DiagnosticLog.shared
-        let t = diag.startTimed("tile: \(session) → \(position.rawValue)")
+        let t = diag.startTimed("tile: \(session) → \(placement.wireValue)")
 
         // Fast path: use DesktopModel cache → single AX move
         if let entry = DesktopModel.shared.windowForSession(session) {
-            let frame = tileFrame(for: position, on: screen)
+            let frame = tileFrame(for: placement, on: screen)
             batchMoveAndRaiseWindows([(wid: entry.wid, pid: entry.pid, frame: frame)])
             diag.success("tile fast path (DesktopModel): \(session)")
             diag.finish(t)
@@ -345,7 +488,7 @@ enum WindowTiler {
         // AX fallback: search terminal windows by title tag
         let tag = Terminal.windowTag(for: session)
         if let (pid, axWindow) = findWindowViaAX(terminal: terminal, tag: tag) {
-            let targetFrame = tileFrame(for: position, on: screen)
+            let targetFrame = tileFrame(for: placement, on: screen)
             var newPos = CGPoint(x: targetFrame.origin.x, y: targetFrame.origin.y)
             var newSize = CGSize(width: targetFrame.width, height: targetFrame.height)
             let win = axWindow
@@ -370,7 +513,7 @@ enum WindowTiler {
 
         // AppleScript last resort (slow, single-monitor)
         diag.warn("tile AppleScript last resort: \(session)")
-        let bounds = appleScriptBounds(for: position, screen: screen)
+        let bounds = appleScriptBounds(for: placement.fractions, screen: screen)
         switch terminal {
         case .terminal:
             tileAppleScript(app: "Terminal", tag: tag, bounds: bounds)
@@ -385,8 +528,12 @@ enum WindowTiler {
     /// Tile a specific terminal window (found by lattices session tag) to a position.
     /// Uses the same fast path strategy as tile(session:terminal:to:on:) with main screen.
     static func tile(session: String, terminal: Terminal, to position: TilePosition) {
+        tile(session: session, terminal: terminal, to: .tile(position))
+    }
+
+    static func tile(session: String, terminal: Terminal, to placement: PlacementSpec) {
         let screen = NSScreen.main ?? NSScreen.screens[0]
-        tile(session: session, terminal: terminal, to: position, on: screen)
+        tile(session: session, terminal: terminal, to: placement, on: screen)
     }
 
     /// Tile the frontmost window (works for any terminal)
@@ -537,7 +684,8 @@ enum WindowTiler {
     }
 
     /// Attempt CGS-based window move. Returns nil if APIs are unavailable.
-    private static func moveViaCGS(wid: UInt32, fromSpaces: [Int], toSpace: Int) -> MoveResult? {
+    /// Move a window between spaces via CGS private APIs. Internal — used by present() and moveWindowToSpace().
+    internal static func moveViaCGS(wid: UInt32, fromSpaces: [Int], toSpace: Int) -> MoveResult? {
         let diag = DiagnosticLog.shared
         guard let mainConn = CGS.mainConnectionID,
               let addToSpaces = CGS.addWindowsToSpaces,
@@ -997,53 +1145,59 @@ enum WindowTiler {
         DispatchQueue.main.async { WindowHighlight.shared.flash(frame: frame) }
     }
 
-    /// Tile any window by its CG window ID to a position using AX API
-    static func tileWindowById(wid: UInt32, pid: Int32, to position: TilePosition) {
-        let diag = DiagnosticLog.shared
-        diag.info("tileWindowById: wid=\(wid) pid=\(pid) pos=\(position.rawValue)")
-
-        // Find the screen the window is on
-        guard let windowFrame = cgWindowFrame(wid: wid) else {
-            diag.warn("tileWindowById: no frame for wid=\(wid)")
-            return
+    /// Tile any window by its CG window ID to a position.
+    /// Delegates to `batchMoveAndRaiseWindows` which is the battle-tested path:
+    /// uses `_AXUIElementGetWindow` for direct wid→AX mapping, disables enhanced UI,
+    /// freezes screen rendering, and verifies+retries drifted windows.
+    /// Tile a window using raw fractional coordinates.
+    static func tileWindowById(wid: UInt32, pid: Int32, fractions: (CGFloat, CGFloat, CGFloat, CGFloat), on targetScreen: NSScreen? = nil) {
+        let screen = targetScreen ?? NSScreen.main ?? NSScreen.screens[0]
+        let frame = tileFrame(fractions: fractions, on: screen)
+        DiagnosticLog.shared.info("tileWindowById: wid=\(wid) fractions=\(fractions) frame=(\(Int(frame.origin.x)),\(Int(frame.origin.y))) \(Int(frame.width))x\(Int(frame.height))")
+        if let app = NSRunningApplication(processIdentifier: pid) { app.activate() }
+        let moves = [(wid: wid, pid: pid, frame: frame)]
+        batchMoveAndRaiseWindows(moves)
+        let drifted = verifyMoves(moves)
+        if !drifted.isEmpty {
+            usleep(100_000)
+            batchMoveAndRaiseWindows(drifted.map { (wid: $0.wid, pid: $0.pid, frame: $0.frame) })
         }
-        let screen = NSScreen.screens.first(where: {
-            $0.frame.contains(NSPoint(x: windowFrame.midX, y: windowFrame.midY))
-        }) ?? NSScreen.main ?? NSScreen.screens[0]
+    }
 
-        let visible = screen.visibleFrame
-        let (fx, fy, fw, fh) = position.rect
+    static func tileWindowById(wid: UInt32, pid: Int32, to position: TilePosition, on targetScreen: NSScreen? = nil) {
+        tileWindowById(wid: wid, pid: pid, to: .tile(position), on: targetScreen)
+    }
 
-        // Calculate target in NS coordinates (bottom-left origin)
-        let targetX = visible.origin.x + visible.width * fx
-        let targetY = visible.origin.y + visible.height * (1.0 - fy - fh)
-        let targetW = visible.width * fw
-        let targetH = visible.height * fh
+    static func tileWindowById(wid: UInt32, pid: Int32, to placement: PlacementSpec, on targetScreen: NSScreen? = nil) {
+        let diag = DiagnosticLog.shared
+        let screen = targetScreen ?? NSScreen.main ?? NSScreen.screens[0]
+        let frame = tileFrame(for: placement, on: screen)
 
-        // Convert NS bottom-left → AX top-left origin
-        guard let primaryScreen = NSScreen.screens.first else { return }
-        let primaryHeight = primaryScreen.frame.height
-        let axX = targetX
-        let axY = primaryHeight - targetY - targetH
+        diag.info("tileWindowById: wid=\(wid) pid=\(pid) pos=\(placement.wireValue) screen=\(screen.localizedName) frame=(\(Int(frame.origin.x)),\(Int(frame.origin.y))) \(Int(frame.width))x\(Int(frame.height))")
 
-        // Find the AX window matching this CG wid by frame comparison
-        guard let axWindow = findAXWindowByFrame(wid: wid, pid: pid) else {
-            diag.warn("tileWindowById: couldn't match AX window for wid=\(wid)")
-            return
+        // Focus the app so windows on other Spaces come to the current one
+        if let app = NSRunningApplication(processIdentifier: pid) {
+            app.activate()
         }
 
-        // Set position and size via AX
-        var newPos = CGPoint(x: axX, y: axY)
-        var newSize = CGSize(width: targetW, height: targetH)
+        let moves = [(wid: wid, pid: pid, frame: frame)]
+        batchMoveAndRaiseWindows(moves)
 
-        if let posValue = AXValueCreate(.cgPoint, &newPos) {
-            AXUIElementSetAttributeValue(axWindow, kAXPositionAttribute as CFString, posValue)
-        }
-        if let sizeValue = AXValueCreate(.cgSize, &newSize) {
-            AXUIElementSetAttributeValue(axWindow, kAXSizeAttribute as CFString, sizeValue)
+        // Verify and retry once if needed
+        let drifted = verifyMoves(moves)
+        if !drifted.isEmpty {
+            diag.info("tileWindowById: wid=\(wid) drifted, retrying...")
+            usleep(100_000)
+            batchMoveAndRaiseWindows(drifted)
+            let stillDrifted = verifyMoves(drifted)
+            if stillDrifted.isEmpty {
+                diag.success("tileWindowById: wid=\(wid) retry succeeded")
+            } else {
+                diag.warn("tileWindowById: wid=\(wid) still drifted after retry")
+            }
+        } else {
+            diag.success("tileWindowById: tiled wid=\(wid) to \(placement.wireValue)")
         }
-
-        diag.success("tileWindowById: tiled wid=\(wid) to \(position.rawValue)")
     }
 
     /// Distribute windows in a smart grid layout (delegates to batch operation)
@@ -1074,7 +1228,7 @@ enum WindowTiler {
     }
 
     /// Get NSRect (bottom-left origin) for a known CG window ID
-    private static func cgWindowFrame(wid: UInt32) -> NSRect? {
+    static func cgWindowFrame(wid: UInt32) -> NSRect? {
         guard let windowList = CGWindowListCopyWindowInfo([.optionAll, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] else { return nil }
         for info in windowList {
             if let num = info[kCGWindowNumber as String] as? UInt32, num == wid,
@@ -1128,6 +1282,7 @@ enum WindowTiler {
                 }
             }
         }
+        DesktopModel.shared.markInteraction(wids: windows.map(\.wid))
         diag.success("raiseWindowsAndReactivate: raised \(windows.count) windows")
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
             NSApp.activate(ignoringOtherApps: true)
@@ -1166,6 +1321,7 @@ enum WindowTiler {
         } else {
             doRaise()
         }
+        DesktopModel.shared.markInteraction(wid: wid)
     }
 
     // MARK: - Batch Window Operations
@@ -1288,24 +1444,93 @@ enum WindowTiler {
     }
 
     /// Raise and focus a single window by its CGWindowID.
-    static func focusWindow(wid: UInt32, pid: Int32) {
-        let appRef = AXUIElementCreateApplication(pid)
-        var windowsRef: CFTypeRef?
-        guard AXUIElementCopyAttributeValue(appRef, kAXWindowsAttribute as CFString, &windowsRef) == .success,
-              let axWindows = windowsRef as? [AXUIElement] else { return }
+    @discardableResult
+    static func focusWindow(wid: UInt32, pid: Int32) -> Bool {
+        return present(wid: wid, pid: pid)
+    }
 
-        for axWin in axWindows {
-            var windowId: CGWindowID = 0
-            if _AXUIElementGetWindow(axWin, &windowId) == .success, windowId == wid {
-                AXUIElementPerformAction(axWin, kAXRaiseAction as CFString)
-                AXUIElementSetAttributeValue(axWin, kAXMainAttribute as CFString, kCFBooleanTrue)
-                break
+    // MARK: - Present
+
+    /// Present a window: move it to the current space, bring it to front, optionally position it.
+    /// This is the single entry point for "show me this window right now."
+    @discardableResult
+    static func present(wid: UInt32, pid: Int32, frame: CGRect? = nil) -> Bool {
+        let diag = DiagnosticLog.shared
+
+        // 1. Move to current space if needed
+        let windowSpaces = getSpacesForWindow(wid)
+        let currentSpace = getCurrentSpace()
+        if currentSpace != 0, !windowSpaces.isEmpty, !windowSpaces.contains(currentSpace) {
+            diag.info("present: wid \(wid) on space \(windowSpaces), moving to current space \(currentSpace)")
+            _ = moveViaCGS(wid: wid, fromSpaces: windowSpaces, toSpace: currentSpace)
+        }
+
+        // 2. Position if requested
+        if let frame = frame {
+            if let mainConn = _SLSMainConnectionID, let moveWindow = _SLSMoveWindow {
+                let cid = mainConn()
+                var origin = CGPoint(x: frame.origin.x, y: frame.origin.y)
+                moveWindow(cid, wid, &origin)
+            }
+            // Resize via AX
+            let appRef = AXUIElementCreateApplication(pid)
+            var windowsRef: CFTypeRef?
+            if AXUIElementCopyAttributeValue(appRef, kAXWindowsAttribute as CFString, &windowsRef) == .success,
+               let axWindows = windowsRef as? [AXUIElement] {
+                for axWin in axWindows {
+                    var windowId: CGWindowID = 0
+                    if _AXUIElementGetWindow(axWin, &windowId) == .success, windowId == wid {
+                        var size = CGSize(width: frame.width, height: frame.height)
+                        let sizeValue = AXValueCreate(.cgSize, &size)!
+                        AXUIElementSetAttributeValue(axWin, kAXSizeAttribute as CFString, sizeValue)
+                        break
+                    }
+                }
             }
         }
 
+        // 3. Activate the app first (this may bring the wrong window forward)
         if let app = NSRunningApplication(processIdentifier: pid) {
             app.activate()
         }
+
+        // 4. Then order OUR window to front — after activate so we get the last word
+        if let mainConn = _SLSMainConnectionID, let orderWindow = _SLSOrderWindow {
+            let cid = mainConn()
+            let err = orderWindow(cid, wid, 1, 0)
+            if err != .success {
+                diag.warn("present: SLSOrderWindow failed for wid \(wid): \(err)")
+            }
+        }
+
+        // 5. Set as main window via AX
+        let appRef = AXUIElementCreateApplication(pid)
+        var windowsRef: CFTypeRef?
+        if AXUIElementCopyAttributeValue(appRef, kAXWindowsAttribute as CFString, &windowsRef) == .success,
+           let axWindows = windowsRef as? [AXUIElement] {
+            for axWin in axWindows {
+                var windowId: CGWindowID = 0
+                if _AXUIElementGetWindow(axWin, &windowId) == .success, windowId == wid {
+                    AXUIElementSetAttributeValue(axWin, kAXMainAttribute as CFString, kCFBooleanTrue)
+                    AXUIElementPerformAction(axWin, kAXRaiseAction as CFString)
+                    break
+                }
+            }
+        }
+
+        // 6. Re-raise after delays to defeat focus stealing from the caller.
+        // Two passes: early catch (200ms) and late catch (600ms) for slower responses.
+        for delay in [0.2, 0.6] {
+            DispatchQueue.main.asyncAfter(deadline: .now() + delay) {
+                if let mainConn = _SLSMainConnectionID, let orderWindow = _SLSOrderWindow {
+                    let cid = mainConn()
+                    orderWindow(cid, wid, 1, 0)
+                }
+            }
+        }
+
+        DesktopModel.shared.markInteraction(wid: wid)
+        return true
     }
 
     /// Move AND raise windows in a single CG+AX pass (avoids duplicate lookups).
@@ -1383,6 +1608,7 @@ enum WindowTiler {
 
         // Unfreeze screen rendering
         if let cid { _ = _SLSReenableUpdate?(cid) }
+        DesktopModel.shared.markInteraction(wids: moves.map(\.wid))
         diag.success("batchMoveAndRaiseWindows: processed \(processed)/\(moves.count) windows")
     }
 
@@ -1418,33 +1644,48 @@ enum WindowTiler {
         }
     }
 
-    /// Compute grid slot rects in AX coordinates (top-left origin) for N windows
-    static func computeGridSlots(count: Int, screen: NSScreen) -> [CGRect] {
+    /// Compute grid slot rects in AX coordinates (top-left origin) for N windows.
+    /// If `region` is provided (fractional x, y, w, h), slots are constrained to that sub-area of the screen.
+    static func computeGridSlots(count: Int, screen: NSScreen, region: (CGFloat, CGFloat, CGFloat, CGFloat)? = nil) -> [CGRect] {
         guard count > 0 else { return [] }
         let visible = screen.visibleFrame
         guard let primaryScreen = NSScreen.screens.first else { return [] }
         let primaryHeight = primaryScreen.frame.height
 
-        // AX Y of visible top edge
-        let axTop = primaryHeight - visible.maxY
+        // Compute the target area — full visible frame or a fractional sub-region
+        let targetArea: CGRect
+        if let (rx, ry, rw, rh) = region {
+            targetArea = CGRect(
+                x: visible.origin.x + visible.width * rx,
+                y: visible.origin.y + visible.height * (1.0 - ry - rh),  // NSRect is bottom-left origin
+                width: visible.width * rw,
+                height: visible.height * rh
+            )
+        } else {
+            targetArea = visible
+        }
+
+        // AX Y of target area's top edge
+        let axTop = primaryHeight - targetArea.maxY
         let shape = gridShape(for: count)
         let rowCount = shape.count
-        let rowH = visible.height / CGFloat(rowCount)
+        let rowH = targetArea.height / CGFloat(rowCount)
 
         var slots: [CGRect] = []
         for (row, cols) in shape.enumerated() {
-            let colW = visible.width / CGFloat(cols)
+            let colW = targetArea.width / CGFloat(cols)
             let axY = axTop + CGFloat(row) * rowH
             for col in 0..<cols {
-                let x = visible.origin.x + CGFloat(col) * colW
+                let x = targetArea.origin.x + CGFloat(col) * colW
                 slots.append(CGRect(x: x, y: axY, width: colW, height: rowH))
             }
         }
         return slots
     }
 
-    /// Raise multiple windows and arrange in smart grid — single CG query, single AX query per process
-    static func batchRaiseAndDistribute(windows: [(wid: UInt32, pid: Int32)]) {
+    /// Raise multiple windows and arrange in smart grid — single CG query, single AX query per process.
+    /// If `region` is provided (fractional x, y, w, h), the grid is constrained to that sub-area.
+    static func batchRaiseAndDistribute(windows: [(wid: UInt32, pid: Int32)], region: (CGFloat, CGFloat, CGFloat, CGFloat)? = nil) {
         guard !windows.isEmpty else { return }
         let diag = DiagnosticLog.shared
 
@@ -1466,10 +1707,11 @@ enum WindowTiler {
         diag.info("Grid layout: \(windows.count) windows → [\(desc)]")
         diag.info("  Screen: \(screen.localizedName) \(Int(screenFrame.width))x\(Int(screenFrame.height))")
         diag.info("  Visible: origin=(\(Int(visible.origin.x)),\(Int(visible.origin.y))) size=\(Int(visible.width))x\(Int(visible.height))")
+        if let region { diag.info("  Region: x=\(region.0) y=\(region.1) w=\(region.2) h=\(region.3)") }
         diag.info("  Primary height: \(Int(primaryHeight))")
 
         // Pre-compute all target slots
-        let slots = computeGridSlots(count: windows.count, screen: screen)
+        let slots = computeGridSlots(count: windows.count, screen: screen, region: region)
         guard slots.count == windows.count else {
             diag.warn("  Slot count mismatch: \(slots.count) slots for \(windows.count) windows")
             return
@@ -1593,6 +1835,7 @@ enum WindowTiler {
         if !failed.isEmpty {
             diag.warn("batchRaiseAndDistribute: failed wids=\(failed)")
         }
+        DesktopModel.shared.markInteraction(wids: windows.map(\.wid))
         diag.success("batchRaiseAndDistribute: moved \(moved)/\(windows.count) [\(desc) grid]")
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) {
             NSApp.activate(ignoringOtherApps: true)
@@ -1670,6 +1913,10 @@ enum WindowTiler {
     /// Tile the frontmost window of any app to a position using AX API.
     /// Works for any application (Finder, Chrome, etc.), not just terminals.
     static func tileFrontmostViaAX(to position: TilePosition) {
+        tileFrontmostViaAX(to: .tile(position))
+    }
+
+    static func tileFrontmostViaAX(to placement: PlacementSpec) {
         guard let frontApp = NSWorkspace.shared.frontmostApplication,
               frontApp.bundleIdentifier != "com.arach.lattices" else { return }
 
@@ -1680,7 +1927,7 @@ enum WindowTiler {
         let win = axWindow as! AXUIElement
 
         let screen = screenForAXWindow(win)
-        let target = tileFrame(for: position, on: screen)
+        let target = tileFrame(for: placement, on: screen)
 
         // Disable enhanced UI on the APP element (not window) — breaks macOS tile lock
         AXUIElementSetAttributeValue(appRef, "AXEnhancedUserInterface" as CFString, false as CFTypeRef)
@@ -1736,6 +1983,20 @@ enum WindowTiler {
             ?? NSScreen.screens[0]
     }
 
+    static func screenForWindowFrame(_ frame: WindowFrame) -> NSScreen {
+        guard let primaryScreen = NSScreen.screens.first else {
+            return NSScreen.main ?? NSScreen.screens[0]
+        }
+
+        let centerX = frame.x + frame.w / 2
+        let centerY = frame.y + frame.h / 2
+        let nsCenterY = primaryScreen.frame.height - centerY
+
+        return NSScreen.screens.first(where: {
+            $0.frame.contains(NSPoint(x: centerX, y: nsCenterY))
+        }) ?? NSScreen.main ?? primaryScreen
+    }
+
     // MARK: - Private
 
     private static func tileAppleScript(app: String, tag: String, bounds: (Int, Int, Int, Int)) {