proposal-activation-requested-event.md

Proposal: Add activation_requested event to river_window_v1

Problem

When a client requests activation via xdg-activation-v1 (e.g., Firefox receiving a URL from another app), River's handleRequestActivate in Server.zig currently discards the event for windows:

.window => |_| {}, // TODO support xdg-activation with a rwm extension protocol

This means the window manager has no way to know a window wants attention, and cannot raise it to become visible.

Proposed Protocol Change

Add an activation_requested event to river_window_v1 (version 4):

<event name="activation_requested" since="4">
  <description summary="the window requested to be activated">
    A client has requested that this window be activated, for example
    via the xdg-activation protocol.

    The window manager may use this to raise the window to the top of
    its stack, focus it, or ignore it.

    This event will be followed by a manage_start event after all other
    new state has been sent by the server.
  </description>
</event>

This event takes no arguments. It follows the same pattern as minimize_requested — a simple notification that the WM can choose to honor or ignore.

Compositor Changes

Window.zig

Add to wm_scheduled:

activation_requested: bool = false,

In manageStart(), after minimize_requested handling:

if (scheduled.activation_requested) {
    if (window_v1.getVersion() >= 4)
        window_v1.sendActivationRequested();
}
scheduled.activation_requested = false;

Server.zig

In handleRequestActivate(), replace the TODO stub:

.window => |window| {
    window.wm_scheduled.activation_requested = true;
    const srv: *Server = @fieldParentPtr("request_activate", listener);
    srv.wm.dirtyWindowing();
},

(Also change the first parameter from _: to listener: to make @fieldParentPtr work.)

build.zig

Bump version: scanner.generate("river_window_manager_v1", 4);

Use Case

User has a split layout: terminal on the left, Firefox (hidden behind another window) on the right. User clicks a URL in the terminal. Firefox receives the URL and calls xdg_activation_v1.activate(). River forwards activation_requested to the WM. The WM raises Firefox to the top of its right stack, making it visible.

Notes

• The event is version-gated (since="4", version check in manageStart), so older WM clients are unaffected.
• The WM has full policy control — it can raise, focus, flash a border, or ignore the event entirely.
• This directly addresses the existing TODO in Server.zig:448.