trycua/cua

cua-driver(macos): per-session overlay windows so each cursor sits z+1 above ITS window

Open

#1,800 opened on Jun 1, 2026

View on GitHub
 (1 comment) (0 reactions) (0 assignees)HTML (1,051 forks)batch import
help wanted

Repository metrics

Stars
 (16,722 stars)
PR merge metrics
 (Avg merge 1d) (166 merged PRs in 30d)

Description

Problem

With multiple concurrent sessions (multi-agent — see #1798), each session has its own agent cursor, but they're all drawn into one shared overlay NSWindow. A single window can occupy only one z-band, so the overlay is pinned just above the last-active cursor's target window (acknowledged in cursor/overlay.rs:556-557: "a single NSWindow can occupy only one z-band, so the last-active cursor's target wins").

Consequence: a cursor that belongs to a background window can render on top of a foreground window — the cursor isn't z-correct relative to its own window.

Desired

Each session's cursor should sit at z(its session's target window) + 1 — visible above its own window, but correctly occluded by windows stacked above it.

Proposal

Replace the single shared overlay window with one borderless, click-through overlay window per session/cursor:

  • create on the session's first cursor command, destroy on session_end / idle-TTL;
  • render that cursor into its own surface (sized to the cursor's bounding region, not the whole screen);
  • orderWindow: NSWindowAbove relativeTo: <that session's target wid> so it tracks its own window's z-band independently (the PinAbove(wid) plumbing + per-session keys already exist).

Single-cursor behavior is unchanged. Isolated to platform-macos/src/cursor/overlay.rs.

Follow-up to #1798 (caller-declared session identity + multi-agent). Windows/Linux have no overlay, so macOS-only.

🤖 Generated with Claude Code

Contributor guide