gardesk/ers / 32a4ba8

+# CLAUDE.md

+

+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

+

+## What this is

+

+ers is a macOS window border renderer for the tarmac window manager. It draws colored overlay borders around application windows using private SkyLight framework APIs. macOS Tahoe only.

+

+## Build & Run

+

+```bash

+cargo build              # debug build

+cargo build --release    # release build

+cargo run                # run (borders all windows)

+cargo run -- --list      # list on-screen windows with IDs and bounds

+cargo run -- -w 6.0      # custom border width (default: 4.0)

+cargo run -- <wid>       # border a specific window ID

+```

+

+No tests — verification is visual. Use `RUST_LOG=debug` for tracing output.

+

+## Architecture

+

+Three source files (~1300 lines total):

+

+- **`src/main.rs`** — `BorderMap` struct manages overlay lifecycle. Event loop batches window events with 150ms debounce, then processes creates/destroys/moves/resizes. Focus detection recolors borders (active=white, inactive=gray). Main thread runs CFRunLoop; events dispatch from a background thread via mpsc.

+

+- **`src/skylight.rs`** — FFI bindings for private macOS frameworks: SkyLight (CGS window creation, event registration), CoreGraphics (drawing), CoreFoundation (collections, RunLoop). All types `repr(C)`.

+

+- **`src/events.rs`** — Event enum and SLSRegisterNotifyProc callbacks. Filters out the renderer's own windows to prevent feedback loops. Sends events over mpsc channel.

+

+- **`build.rs`** — Links SkyLight (private framework), CoreGraphics, CoreFoundation.

+

+## Critical macOS Tahoe constraints

+

+These are hard-won discoveries from debugging undocumented APIs:

+

+1. **SLSCopyManagedDisplaySpaces poisons SLSNewWindow** — calling it on ANY connection corrupts window creation on ALL connections. Use `CGWindowListCopyWindowInfo` instead.

+

+2. **Fresh SLS connection per border** — each overlay needs its own `SLSNewConnection`. Required for reliable rendering.

+

+3. **Create windows at final size** — the 1×1-then-reshape pattern breaks on Tahoe. Create at correct position/size immediately.

+

+4. **Draw before setting tags** — CGContext from `SLWindowContextCreate` must be used to draw BEFORE setting window tags/shadow. Re-obtaining context later for redraws uses the border's own connection.

+

+## Dependencies

+

+Only `serde`/`serde_json` (JSON parsing of window info) and `tracing`/`tracing-subscriber` (logging). No external runtime dependencies beyond macOS frameworks.

+    /// Add border (event mode). Uses main_cid — fresh connections create

+    /// invisible windows on Tahoe.

+        if let Some((cid, wid)) = create_overlay(self.main_cid, target_wid, self.border_width, color) {

+    /// Redraw an existing overlay with a new color (no destroy/recreate).

+    fn redraw(&self, target_wid: u32) {

+        if let Some(overlay) = self.overlays.get(&target_wid) {

+            unsafe {

+                let mut bounds = CGRect::default();

+                if SLSGetWindowBounds(overlay.cid, target_wid, &mut bounds) != kCGErrorSuccess {

+                    return;

+                }

+                let bw = self.border_width;

+                let ow = bounds.size.width + 2.0 * bw;

+                let oh = bounds.size.height + 2.0 * bw;

+

+                let ctx = SLWindowContextCreate(overlay.cid, overlay.wid, ptr::null());

+                if ctx.is_null() { return; }

+

+                let full = CGRect::new(0.0, 0.0, ow, oh);

+                CGContextClearRect(ctx, full);

+

+                let color = self.color_for(target_wid);

+                let stroke_rect = CGRect::new(bw / 2.0, bw / 2.0, ow - bw, oh - bw);

+                let radius = 10.0_f64;

+                let max_r = (stroke_rect.size.width.min(stroke_rect.size.height) / 2.0).max(0.0);

+                let r = radius.min(max_r);

+

+                CGContextSetRGBStrokeColor(ctx, color.0, color.1, color.2, color.3);

+                CGContextSetLineWidth(ctx, bw);

+                let path = CGPathCreateWithRoundedRect(stroke_rect, r, r, ptr::null());

+                if !path.is_null() {

+                    CGContextAddPath(ctx, path);

+                    CGContextStrokePath(ctx);

+                    CGPathRelease(path);

+                }

+

+                CGContextFlush(ctx);

+                SLSFlushWindowContentRegion(overlay.cid, overlay.wid, ptr::null());

+                CGContextRelease(ctx);

+            }

+        }

+    }

+

+    /// Detect focused window and update border colors if focus changed.

+    /// Returns true if focus changed (callers should resubscribe).

+    fn update_focus(&mut self) -> bool {

+        let front = get_front_window(self.own_pid);

+        if front == 0 || front == self.focused_wid { return false; }

+        eprintln!("[focus] {} -> {} (tracked={})", old, front, self.overlays.contains_key(&front));

+        // Recreate overlays with new colors — re-obtaining a CGContext

+        // for an existing window is unreliable on Tahoe

+        true

+/// Get the front (focused) window ID using CGWindowListCopyWindowInfo.

+/// Avoids all SLS display/space queries which poison SLSNewWindow globally.

+fn get_front_window(own_pid: i32) -> u32 {

+        let list = CGWindowListCopyWindowInfo(kCGWindowListOptionOnScreenOnly, kCGNullWindowID);

+        if list.is_null() { return 0; }

+        let count = CFArrayGetCount(list);

+        let wid_key = CFStringCreateWithCString(ptr::null(), b"kCGWindowNumber\0".as_ptr(), kCFStringEncodingUTF8);

+        let pid_key = CFStringCreateWithCString(ptr::null(), b"kCGWindowOwnerPID\0".as_ptr(), kCFStringEncodingUTF8);

+        let layer_key = CFStringCreateWithCString(ptr::null(), b"kCGWindowLayer\0".as_ptr(), kCFStringEncodingUTF8);

+

+        // CGWindowListCopyWindowInfo returns windows in front-to-back order.

+        // First layer-0 window not owned by us is the focused window.

+        let mut front_wid: u32 = 0;

+        for i in 0..count {

+            let dict = CFArrayGetValueAtIndex(list, i);

+            if dict.is_null() { continue; }

+

+            let mut v: CFTypeRef = ptr::null();

+

+            let mut layer: i32 = -1;

+            if CFDictionaryGetValueIfPresent(dict, layer_key as CFTypeRef, &mut v) {

+                CFNumberGetValue(v, kCFNumberSInt32Type, &mut layer as *mut _ as *mut _);

+            }

+            if layer != 0 { continue; }

+

+            let mut pid: i32 = 0;

+            if CFDictionaryGetValueIfPresent(dict, pid_key as CFTypeRef, &mut v) {

+                CFNumberGetValue(v, kCFNumberSInt32Type, &mut pid as *mut _ as *mut _);

+            }

+            if pid == own_pid { continue; }

+

+            let mut wid: u32 = 0;

+            if CFDictionaryGetValueIfPresent(dict, wid_key as CFTypeRef, &mut v) {

+                CFNumberGetValue(v, kCFNumberSInt32Type, &mut wid as *mut _ as *mut _);

+            }

+            if wid != 0 {

+                front_wid = wid;

+                break;

+

+        CFRelease(wid_key as CFTypeRef);

+        CFRelease(pid_key as CFTypeRef);

+        CFRelease(layer_key as CFTypeRef);

+        CFRelease(list);

+        front_wid

+    if borders.update_focus() {

+        borders.subscribe_all();

+    }

+            // Update focus (detects front window, recreates borders if changed)

+            if borders.update_focus() {

+                needs_resubscribe = true;

+            }

+        let rc = SLSGetWindowBounds(cid, target_wid, &mut bounds);

+        if rc != kCGErrorSuccess {

+            eprintln!("[create_overlay] SLSGetWindowBounds failed for wid={target_wid} rc={rc}");

+            eprintln!("[create_overlay] wid={target_wid} too small: {}x{}", bounds.size.width, bounds.size.height);

+        if region.is_null() {

+            eprintln!("[create_overlay] CGSNewRegionWithRect failed for wid={target_wid}");

+            return None;

+        }

+        if wid == 0 {

+            eprintln!("[create_overlay] SLSNewWindow returned 0 for target={target_wid} cid={cid}");

+            return None;

+        }

+

+        eprintln!("[create_overlay] created overlay wid={wid} for target={target_wid} color=({:.2},{:.2},{:.2},{:.2})",

+            color.0, color.1, color.2, color.3);

+            eprintln!("[create_overlay] SLWindowContextCreate returned null for overlay wid={wid}");