# How the OpenLogi Actions Ring Overlay Renders and Provides Cursor-Centered Interaction

> Discover how OpenLogi Actions Ring renders a transparent UI always centered on your cursor. Learn about its edge-aware positioning and click-away dismissal for seamless interaction.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: internals
- Published: 2026-09-05

---

**The OpenLogi Actions Ring is implemented as a lightweight, standalone IPC client binary that renders a transparent GP UI window always centered on the cursor, with edge-aware positioning and click-away dismissal.**

OpenLogi's **Actions Ring** provides a quick-access radial menu for workflow automation. Understanding how this overlay renders and maintains cursor-centered positioning reveals the architecture behind its seamless user experience. This article examines the implementation in the `AprilNEA/OpenLogi` repository, tracing from IPC invocation through GPUI window creation to final dismissal.

## Process Lifecycle and IPC Architecture

The overlay binary (`openlogi-overlay`) operates as a **dedicated subprocess** that communicates with the main agent via inter-process communication.

In [`crates/openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/main.rs), the entry point establishes three critical responsibilities:

- **Singleton enforcement**: Claims the *overlay role* through a system mutex, ensuring only one ring instance runs at a time
- **Tracing initialization**: Sets up structured logging for debugging overlay behavior
- **IPC channel creation**: Spawns bidirectional communication for receiving invocations and sending commands back to the agent

```rust
// From crates/openlogi-overlay/src/main.rs
let Ipc { mut invocations, commands } = spawn_ipc();
cx.spawn(async move {
    while let Some(observed) = invocations.recv().await {
        let invocation = observed.unwrap();
        cx.update(|cx| {
            // Clean up existing windows before showing new ring
            for handle in cx.windows() {
                let _ = handle.update(cx, |_, w, _| w.remove_window());
            }
            let options = ring_window_options(cx);
            cx.open_window(options, |_, cx| {
                cx.new(|_| RingView::new(invocation, commands.clone(), &live_session))
            });
        });
    }
});

```

The IPC protocol uses two core types defined in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs): `ActionRingInvocation` (incoming, containing the actions to display) and `OverlayCommand` (outgoing, including `Activate`, `Hover`, and `Cancel` variants).

## Cursor-Centered Window Positioning

The **`ring_window_options`** function in [`crates/openlogi-overlay/src/ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/ring.rs) implements the core positioning logic that keeps the ring centered on the cursor while respecting display boundaries.

### Step 1: Capture Global Cursor Position

The overlay queries the cursor location through the hook subsystem:

```rust
let cursor = openlogi_hook::cursor_position();  // Global screen coordinates

```

### Step 2: Resolve Display Context

The function determines which display contains the cursor, with platform-specific resolution:

```rust
let native_display = cursor
    .as_ref()
    .and_then(|c| platform::display_containing(c.x, c.y));

```

On macOS, this delegates to `platform::display_containing`; other platforms iterate the GPUI display list.

### Step 3: Compute and Clamp Origin

The desired window origin centers the ring on the cursor, then clamps to visible bounds:

```rust
let origin = display_bounds.map_or(center, |b| clamp_window_origin(center, size, b));

```

The **clamp_window_origin** helper ensures the ring never renders partially off-screen, adjusting the position when the cursor is near display edges.

The resulting `WindowOptions` configure a **borderless, transparent popup**:

```rust
WindowOptions {
    window_bounds: Some(WindowBounds::Windowed(Bounds::new(origin, size))),
    kind: WindowKind::PopUp,
    focus: false,                                  // Non-focusable
    window_background: WindowBackgroundAppearance::Transparent,
    app_id: Some("openlogi-action-ring".to_string()),
    ..Default::default()
}

```

## Rendering the Ring Interface

The **`RingView`** struct in [`crates/openlogi-overlay/src/ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/ring.rs) implements the GPUI `Render` trait to draw the radial interface.

### Slot Layout and Geometry

Eight action slots are positioned using polar coordinates calculated from `ActionRingSlot::placement`:

```rust
// Each slot rendered by slot_element with position from ring geometry
fn slot_element(
    slot: ActionRingSlot,
    commands: OverlayCommandSender,
    live_session: &LiveOverlaySession,
) -> impl gpui::IntoElement {
    // Position calculation from slot.placement
}

```

Slots display **SVG icons** from [`crates/openlogi-ui/src/action_icons.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ui/src/action_icons.rs) and respond to:

- **Hover**: Background color change + `Hover` command sent to agent
- **Click**: `Activate` command sent + window closed

### Central Cancel Button

A cancel control occupies the ring's center, triggering the `Cancel` command when clicked:

```rust
// Center "×" button implementation
div()
    .child(Icon::new(IconName::X))
    .on_click(|_, _, cx| {
        commands.send(OverlayCommand::Cancel);
        cx.remove_window();
    })

```

The visual styling draws from `openlogi_ui::color` constants, using dark panel backgrounds with accent highlights.

## Click-Away Dismissal Implementation

To dismiss the ring when clicking outside its bounds, the overlay implements **global input monitoring** on macOS:

```rust
// In crates/openlogi-overlay/src/platform.rs
pub fn watch_clicks_outside<F>(callback: F) -> impl Drop
where
    F: Fn() + 'static,
{
    // NSEvent monitor for mouse-down outside window
}

```

This monitor invokes a closure that sends `Cancel` and removes the window. Non-macOS platforms rely on in-window dismissal paths: center-click cancel, slot activation, or timeout expiration.

## Platform-Specific Window Policies

The **macOS-specific** [`crates/openlogi-overlay/src/platform.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/platform.rs) ensures the transparent overlay integrates cleanly with the desktop environment:

- **Non-activating**: Window never appears in Dock or Command-Tab switcher
- **Shadow removal**: Native window shadow disabled for true transparency
- **Click-through transparency**: Mouse events pass through transparent regions appropriately

These policies prevent the ephemeral overlay from disrupting normal window management.

## Summary

- The Actions Ring is a **dedicated IPC client binary** (`openlogi-overlay`) that receives session data from the agent
- **Cursor-centered positioning** combines global cursor query with display-aware edge clamping in `ring_window_options`
- **Transparent GPUI window** uses `WindowKind::PopUp` with `Transparent` background for seamless overlay
- **Radial rendering** via `RingView` positions eight slots using geometric placement and handles hover/activate/cancel interactions
- **Click-away dismissal** on macOS uses global mouse-down monitoring; other platforms use in-window controls
- **Platform integration** ensures the overlay remains invisible to window management while capturing intended input

## Frequently Asked Questions

### How does the Actions Ring stay centered when the cursor is near screen edges?

The `clamp_window_origin` helper in [`crates/openlogi-overlay/src/ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/ring.rs) adjusts the window origin when the centered position would place part of the ring off-screen. It takes the desired center point, ring size, and display bounds, then returns a shifted origin that keeps the entire ring visible. This ensures the interface remains fully interactive regardless of cursor position.

### What happens if the user tries to open multiple Action Rings simultaneously?

The overlay enforces singleton behavior through a system mutex claimed at startup in [`main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/main.rs). Only one `openlogi-overlay` process can run at a time, preventing duplicate rings. The agent coordinates with this singleton; if a new invocation arrives while a ring is visible, the existing window is closed before the new one opens.

### Why does the overlay use a separate binary instead of rendering within the main agent?

Separation provides **isolation and responsiveness**. The overlay's minimal footprint reduces impact on agent performance, while the IPC boundary allows privilege separation—the agent runs with broader system access while the overlay handles untrusted display input. This architecture also enables future platform-specific overlay optimizations without agent modifications.

### How are action icons loaded and rendered in the ring slots?

Icons are **SVG assets** defined in [`crates/openlogi-ui/src/action_icons.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ui/src/action_icons.rs), exposed through the `IconName` enum and `Icon` component. The `slot_element` function in [`ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/ring.rs) instantiates these as GPUI elements with hover-state styling, positioning each according to its angular slot placement in the radial layout.