ers Public

Watch 0 Fork 0 Star 0
markdown · 2691 bytes Raw Blame History

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

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. Use the process main connection — SLSMainConnectionID() for window creation, drawing, ordering, and event registration (current code already does this). Past notes mentioned a "fresh SLSNewConnection per border" requirement; that has not been needed since the current architecture stabilized.

  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.

View source
1 # CLAUDE.md
2
3 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5 ## What this is
6
7 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.
8
9 ## Build & Run
10
11 ```bash
12 cargo build # debug build
13 cargo build --release # release build
14 cargo run # run (borders all windows)
15 cargo run -- --list # list on-screen windows with IDs and bounds
16 cargo run -- -w 6.0 # custom border width (default: 4.0)
17 cargo run -- <wid> # border a specific window ID
18 ```
19
20 No tests — verification is visual. Use `RUST_LOG=debug` for tracing output.
21
22 ## Architecture
23
24 Three source files (~1300 lines total):
25
26 - **`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.
27
28 - **`src/skylight.rs`** — FFI bindings for private macOS frameworks: SkyLight (CGS window creation, event registration), CoreGraphics (drawing), CoreFoundation (collections, RunLoop). All types `repr(C)`.
29
30 - **`src/events.rs`** — Event enum and SLSRegisterNotifyProc callbacks. Filters out the renderer's own windows to prevent feedback loops. Sends events over mpsc channel.
31
32 - **`build.rs`** — Links SkyLight (private framework), CoreGraphics, CoreFoundation.
33
34 ## Critical macOS Tahoe constraints
35
36 These are hard-won discoveries from debugging undocumented APIs:
37
38 1. **SLSCopyManagedDisplaySpaces poisons SLSNewWindow** — calling it on ANY connection corrupts window creation on ALL connections. Use `CGWindowListCopyWindowInfo` instead.
39
40 2. **Use the process main connection** — `SLSMainConnectionID()` for window creation, drawing, ordering, and event registration (current code already does this). Past notes mentioned a "fresh SLSNewConnection per border" requirement; that has not been needed since the current architecture stabilized.
41
42 3. **Create windows at final size** — the 1×1-then-reshape pattern breaks on Tahoe. Create at correct position/size immediately.
43
44 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.
45
46 ## Dependencies
47
48 Only `serde`/`serde_json` (JSON parsing of window info) and `tracing`/`tracing-subscriber` (logging). No external runtime dependencies beyond macOS frameworks.