@desklink/host 0.3.1 → 0.4.0

package/docs/PROTOCOL.md

@@ -10,8 +10,7 @@ macOS engine uses the same v3 stdio/WebRTC session path, with native display
 capture, input and clipboard adapters. A Windows build with static libvpx
 (`DESKLINK_VPX_STATIC_DIR`) also serves consumer-fed H.264 encoded sources over
 the shared session path. Native desktop capture, input and clipboard are not
-implemented on Windows, and `session.open` refuses `agent_indicator` with
-`indicator-unavailable`. Without static libvpx, the Windows compile seam
+implemented on Windows; optional agent feedback is unavailable there. Without static libvpx, the Windows compile seam
 reports encoding unavailable and refuses `serve`. The protocol contains no
 application concepts: no accounts, no chat, no machine ids, no pane ids.
 
@@ -96,16 +95,16 @@ dimensions, origin and scale), the current keyboard layout, console state, and
 Screen Recording/Accessibility grant states. A `display` source accepts an
 optional `display_id` from `capture.displays`; an absent ID selects the main
 display. Screen Recording consent is requested by `session.open` when capture
-is needed. Control may request Accessibility consent; if it remains unavailable,
-open fails with `input-unavailable`. TCC permissions attach to the responsible
-launching app (for example Terminal, iTerm, or the Node.js host), not to a
+is needed. Input may request Accessibility consent; if it remains unavailable,
+the session still opens and input actions are refused with `input-unavailable`.
+TCC permissions attach to the responsible launching app (for example Terminal, iTerm, or the Node.js host), not to a
 separate DesklinkHost.app bundle. Enable that app in **System Settings → Privacy
 & Security → Screen & System Audio Recording** and **Accessibility**, then
 reconnect. No TCC state is pre-seeded or bypassed.
 
-macOS clipboard read/write is plain text and requires the session's `clipboard`
-permission. `restore_token` is not supported by this native backend; a new
-session may require fresh consent. The macOS engine requires a VP9-enabled build
+macOS clipboard read/write is plain text and available to paired consumers.
+`restore_token` is not supported by this native backend; a new session may
+require fresh consent. The macOS engine requires a VP9-enabled build
 (`DESKLINK_VPX_STATIC_DIR`) for `serve`.
 
 ## Capabilities
@@ -186,12 +185,17 @@ desktop is visible here rather than silent. `capture.backends` lists what this
 build has, not what this machine can necessarily use.
 
 `input.unavailable_reason` and `input.grant` describe the portal/uinput path:
-without kernel input access a portal session may request `view`, but an open
-requesting `control` is refused. X display capture uses XTest instead and does
-not require that grant. The muxr host and WebSocket bridge report clipboard
-unavailable for an X display, regardless of the engine's Wayland clipboard
-probe. On Linux the engine never asks for privileges on its own; macOS may
-request Screen Recording or Accessibility consent at `session.open`.
+without kernel input access a portal session opens and captures, but input
+messages are refused with `input-unavailable`. X display capture uses XTest
+instead and does not require that grant. The engine probes XTest on that named
+display; if it is unavailable, capture and clipboard still open, and input
+messages are refused with `input-unavailable`. X11 clipboard uses CLIPBOARD on the
+session's named display; the WebSocket bridge reports it independently of the
+engine's ambient Wayland clipboard probe. The engine's Linux `clipboard.read`
+reports the Wayland session environment; `clipboard.write` additionally requires
+`wl-copy`. A portal bridge preserves those flags even when Xwayland is reachable.
+On Linux the engine never asks for
+privileges on its own; macOS may request Screen Recording or Accessibility consent at `session.open`.
 
 `capabilities` is safe to call before any consent has been given and must not
 trigger a capture request.
@@ -203,7 +207,6 @@ trigger a capture request.
   "source": {"kind":"portal"},          // or {"kind":"x11","display":":99"}
                                            // macOS: {"kind":"display","display_id":123}
                                            // or {"kind":"encoded","codec":"h264","width":486,"height":1080}
-  "permissions": ["view","control","clipboard"],
   "max_width": 3840, "max_height": 2160, // encode box (default); never upscales
   "bitrate_kbps": 0,                    // 0 (default): sized to the encoded surface
   "max_fps": 60,
@@ -223,7 +226,7 @@ Result:
  "source":{"kind":"monitor","width":2560,"height":1440,"origin":{"x":0,"y":0}},
  "geometry":{"source":{"width":2560,"height":1440},
              "encoded":{"width":2560,"height":1440},
-             "origin":{"x":0,"y":0}}}
+             "origin":{"x":0,"y":0}},"agentIndicator":false}
 ```
 
 `source` selects the desktop. `portal` (or absent) asks the compositor for a
@@ -234,11 +237,12 @@ main display when omitted); `encoded` carries video the consumer encoded itself.
 The choice is normally the *consumer's* decision, because a client is not in a
 position to know which backend a machine can offer.
 
-`permissions` are the engine's authority for this session. `view` is required
-to open a session. The engine enforces the remaining scopes on every input and
-clipboard action and never infers them from a source, a peer or an SDP.
-`control` without a working input backend is refused at `session.open` with
-`error.code = "input-unavailable"` — the consumer must ask for `view` explicitly instead.
+There are no per-session permissions: whoever holds the channel is paired and
+gets all available view, input and clipboard access. The `permissions` field
+from 0.3 clients is accepted and ignored, including unknown scope names.
+Missing input or clipboard backends fail per action, not at open. The
+`permission` refusal code is reserved for 0.3 peers and is no longer emitted by
+this engine.
 
 `max_fps` defaults to 60 and is bounded to 1–60. It caps the encoded frame
 rate and X11 capture loop; portal capture offers it as the preferred PipeWire
@@ -246,14 +250,29 @@ frame rate, and macOS sets its ScreenCaptureKit stream minimum frame interval.
 A source may still supply fewer frames.
 
 `agent_indicator` is opt-in local feedback for an agent controller; desklink-axi
-sets it for control sessions, never for view-only or human phone control. It
-adds an eased pointer halo, click ripple, and typing pulse. On Wayland it uses
-a click-through layer-shell surface with an edge glow; its bounded area is
+sets it for sessions it drives (except Windows); human phone control omits it. On
+Linux it adds an eased arrow inside a halo that brightens on clicks and keys,
+animating in and out, with light and dark keylines so it reads on any content.
+On Wayland it uses a click-through layer-shell surface with an edge glow, drawn
+at the highest announced output integer scale, capped at 4; its bounded area is
 masked before capture/diff (pixels behind the effect can remain briefly stale).
-On bare X11 it replaces the pointer sprite instead, which the X11 grab excludes:
-there is no edge glow on that path. macOS uses a nonactivating, click-through
-window excluded by the ScreenCaptureKit content filter. Closing the session
-fades and removes the indicator.
+On bare X11 it is an override-redirect, click-through window that follows the
+pointer, so it stays
+visible over windows that set their own cursor and never replaces the cursor.
+Its size follows `Xft.dpi` from 96–384 DPI, defaulting to 1x otherwise;
+the shaped cue reveals outward from the tip and retracts inward, while a
+compositing manager with alpha enables fading instead. The helper announces each
+state before drawing it, and X11 capture restores just
+the pixels the cue covers from the previous frame, so the halo's interior stays
+live; changes under the arrow and ring show once the cue moves away. Click and
+key feedback only recolour the cue, so a still cue never changes what is
+restored. There is no edge glow on that path.
+macOS adds an eased arrow and halo, click ripple, and typing pulse in a
+nonactivating, click-through window excluded by the ScreenCaptureKit content
+filter. Closing the session animates out and removes the indicator.
+Indicator startup is best-effort on every platform; a missing helper or overlay
+backend does not refuse the session. The open result reports `agentIndicator:
+true` only when the helper started.
 
 `local_frames` keeps the latest pre-encode frame and its tile hashes for
 `session.frame` and `session.frame.changed` (see "Latest frame over the local
@@ -514,14 +533,14 @@ an explicit `cursor:"hidden"`. macOS and Windows refuse hidden capture with
 the engine cannot remove pixels the consumer already encoded. Unknown cursor
 options are `malformed`.
 
-`@desklink/host` exposes `openSession({permissions:['view'], cursor:'hidden'})`
+`@desklink/host` exposes `openSession({cursor:'hidden'})`
 and typed `session.cursor` events through `onEvent`/`drainEvents`. The client
 capture request also accepts `cursor`, and AXI accepts `start --cursor hidden`.
 
 ## Point on the host desktop
 
 A local consumer can guide the person without taking control of their pointer
-or keyboard. `session.point` requires `view`, not `control`, and is independent
+or keyboard. `session.point` requires an open session and is independent
 of `agent_indicator`. It draws one blue ring centered at `x,y`, with an optional
 label. A new point replaces the previous one and restarts its timer.
 
@@ -560,7 +579,7 @@ output, no origin is needed. Points map from the selected source to that output.
 An ambiguous or missing selected output returns `indicator-unavailable`.
 Compositors without layer-shell return `point_unsupported` with reason
 `layer_shell_unavailable` (including GNOME Mutter). Consumer-fed encoded sources return `operation`
-because they have no host desktop overlay target. Other refusals are `permission`, `session`,
+because they have no host desktop overlay target. Other refusals are `session`,
 `coordinates`, `malformed`, and `indicator-unavailable` (including unavailable
 X Shape support). Unknown fields are refused. No control-channel or remote
 bridge forwarding is added; the consumer chooses when to request a local cue.
@@ -568,13 +587,13 @@ bridge forwarding is added; the consumer chooses when to request a local cue.
 `@desklink/host` exposes `EngineClient.point(sessionId, {x, y, label?, timeoutMs?})`
 and `EngineClient.point(sessionId, {clear: true})`. `@desklink/axi` exposes
 `desklink-axi point 400,300 --label "Here" --timeout 3000` and
-`desklink-axi point --clear`, including for a session started without `--control`.
+`desklink-axi point --clear`.
 
 ## Input and clipboard: the session's control channel
 
 Input does **not** travel the local protocol. It rides the WebRTC data channel
 the engine creates for the session, which is inside the DTLS/SRTP session that
-was opened for one authorized grant: it inherits that session's identity and dies
+was opened by a paired consumer: it inherits that session's identity and dies
 with it, so a client that kept a socket open cannot keep driving a session that
 was revoked, and the consumer's request path never carries a pointer move.
 
@@ -611,12 +630,12 @@ The engine answers on the same channel, and sends two things unprompted:
 {"kind":"revoked","reason":"…","code":"closed"}  // closed, or a session.revoked code
 ```
 
-Refusal codes: `permission`, `session`, `input-replay`, `coordinates`,
-`text-too-large`, `text-unsupported`, `input-unavailable`, `operation`.
+Refusal codes: `session`, `input-replay`, `coordinates`, `text-too-large`,
+`text-unsupported`, `input-unavailable`, `clipboard-unsupported`, `operation`.
 
 `seq` is monotonic per session. A repeat or a lower value is refused with
 `input-replay` and **no side effect**, so a replayed message cannot move the
-pointer twice. Validation, permission and ordering checks all run before any
+pointer twice. Validation and ordering checks all run before any
 physical effect.
 
 The engine holds its own pressed-key/button state. `close`, `release_all`,
@@ -647,8 +666,7 @@ WebRTC, congestion and teardown logic that is already proven on this path.
 it is the only party that knows them (`1..7680` by `1..4320`). Nothing is scaled:
 `geometry.source` and `geometry.encoded` are both that size, the client aims at
 those pixels, and the consumer maps them to its device. `max_width`/
-`max_height`/`bitrate_kbps` are ignored for this source, and `permissions` works
-as it does anywhere else — with one difference: `control` needs no local input
+`max_height`/`bitrate_kbps` are ignored for this source. Input needs no local
 backend, because nothing is applied locally.
 
 `session.open` returns before any offer exists. The offer must name the profile
@@ -719,7 +737,7 @@ pixels, exactly as a client sends them.
 ```
 
 The event carries the control message as it arrived. The engine still validates
-permission, ordering and replay before forwarding, so the client keeps the same
+ordering and replay before forwarding, so the client keeps the same
 `ack`/`rejected` behaviour and a replayed gesture still cannot be delivered
 twice. `ack` means "accepted for this session", not "applied to a desktop" —
 `session.metrics.input_forwarded` counts what was handed on, and `input_applied`
@@ -738,7 +756,7 @@ because packetization is the only stage the engine itself runs.
 
 ## Latest frame over the local protocol
 
-`session.frame` requires `view` permission. It writes the latest pre-encode frame as
+`session.frame` writes the latest pre-encode frame as
 packed BGRX bytes to the caller's path, with optional `[x,y,w,h]` `region`.
 The directory must already exist and be private to the caller; pixels never
 travel through JSON. `seq` advances only when capture changes, `still_ms` is
@@ -775,9 +793,17 @@ instead; both reach the same clipboard:
 {"id":10,"result":{"written":true}}
 ```
 
-Refused with `error.code = "clipboard"` when the session lacks `clipboard`, or
-when the desktop's clipboard has no text. A read is bounded by
-`capabilities.clipboard.maxBytes`; when the desktop's text is longer, `truncated`
+Refused with `error.code = "clipboard"` when the desktop has no text or a
+clipboard operation fails. Encoded sources have no desktop clipboard; their
+control channel answers with an empty clipboard reply and an explanatory error.
+X11 uses a fresh connection to the session's selected display for each operation.
+Writes verify CLIPBOARD ownership before succeeding and serve TARGETS,
+UTF8_STRING and TEXT; reads request UTF8_STRING. Writes are limited to 256 KiB
+and the server's single request limit; the text lives until another client takes ownership, the engine
+exits, or the display dies. Reads wait at most 2.5 seconds for the owner.
+INCR transfers are refused explicitly as unsupported, not reported as success;
+STRING, PRIMARY and persistence after engine exit are not implemented.
+A read is bounded by `capabilities.clipboard.maxBytes`; when the desktop's text is longer, `truncated`
 is true and the text is cut on a character boundary, so the returned text is
 still valid.
 
@@ -853,8 +879,9 @@ anything to show.
 
 ## What the engine deliberately does not do
 
-- It does not decide *who* the user is. It trusts the consumer's local
-  permission decision and enforces the resulting scope; there is no second
+- It does not decide *who* the user is. Whoever holds stdio (or an authenticated
+  bridge socket) is paired; pairing, identity and revocation are the consumer's.
+  Revocation must end both live sessions and future access. There is no second
   account, token or pairing ceremony. For consumer integration, see the
   [BYOKit guidance](../../../README.md#why-desklink-exists).
 - It does not open ports, register a service, install udev rules, join groups or

package/engine/Cargo.lock

@@ -536,7 +536,7 @@ checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 
 [[package]]
 name = "desklink-host"
-version = "0.3.1"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "ashpd",

package/engine/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "desklink-host"
-version = "0.3.1"
+version = "0.4.0"
 edition = "2021"
 rust-version = "1.97.1"
 license = "Apache-2.0"

package/engine/build.rs

@@ -38,6 +38,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     println!("cargo:rerun-if-changed=native/mac_stream.mm");
     println!("cargo:rerun-if-changed=native/agent_overlay_mac.m");
     println!("cargo:rerun-if-changed=native/agent_overlay_x11.c");
+    println!("cargo:rerun-if-changed=native/agent_indicator.h");
     println!("cargo:rerun-if-changed=native/agent_overlay_wayland.c");
     println!("cargo:rerun-if-changed=Info.plist");
     println!("cargo:rerun-if-changed=vendor/inputtino/src/uinput/include/inputtino/keyboard.hpp");

package/engine/native/agent_indicator.h

@@ -0,0 +1,57 @@
+// Shared Linux agent cue, in logical pixels. The arrow follows the Mac outline;
+// light and dark keylines keep it visible on both bright and dark desktops.
+#ifndef DESKLINK_AGENT_INDICATOR_H
+#define DESKLINK_AGENT_INDICATOR_H
+#include <math.h>
+#include <stdint.h>
+
+static double indicator_segment(double x, double y, double ax, double ay, double bx, double by) {
+    double dx=bx-ax, dy=by-ay;
+    double t=fmax(0,fmin(1,((x-ax)*dx+(y-ay)*dy)/(dx*dx+dy*dy)));
+    return hypot(x-ax-t*dx,y-ay-t*dy);
+}
+static uint32_t indicator_over(uint32_t dst, double coverage, unsigned rgb) {
+    unsigned a=(unsigned)(255*fmax(0,fmin(1,coverage))), inverse=255-a;
+    unsigned da=dst>>24, r=(dst>>16)&255, g=(dst>>8)&255, b=dst&255;
+    return ((a+da*inverse/255)<<24) |
+        ((((rgb>>16)&255)*a/255+r*inverse/255)<<16) |
+        ((((rgb>>8)&255)*a/255+g*inverse/255)<<8) |
+        ((rgb&255)*a/255+b*inverse/255);
+}
+// Recolour without changing coverage, so feedback on a still cue never
+// changes which pixels capture has to restore.
+static uint32_t indicator_tint(uint32_t c, double amount, unsigned rgb) {
+    double keep=1-fmax(0,fmin(1,amount)), a=(c>>24)/255.0;
+    return (c&0xff000000) |
+        ((unsigned)(((c>>16)&255)*keep+((rgb>>16)&255)*a*(1-keep))<<16) |
+        ((unsigned)(((c>>8)&255)*keep+((rgb>>8)&255)*a*(1-keep))<<8) |
+        (unsigned)((c&255)*keep+(rgb&255)*a*(1-keep));
+}
+static uint32_t indicator_pixel(double x, double y, double opacity, double click, double typed) {
+    double radius=hypot(x,y);
+    uint32_t color=0;
+    // 62 logical px halo: a blue band, wide white keyline and dark rim, so the
+    // ring keeps >=2px of contrast after a 2:1 downscale. Inside the band only
+    // the arrow is opaque, so capture can keep the click area live.
+    color=indicator_over(color,fmax(0,fmin(1,2.5-fabs(radius-28.5)))*opacity,0x123047);
+    color=indicator_over(color,fmax(0,fmin(1,2.5-fabs(radius-24)))*opacity,0xffffff);
+    color=indicator_over(color,fmax(0,fmin(1,1.5-fabs(radius-20)))*0.95*opacity,0x2999ff);
+    static const double arrow[][2]={{0,0},{2,24},{8,18},{15,31},{21,28},{14,15},{24,14}};
+    double distance=1000; int inside=0;
+    for(int i=0,j=6;i<7;j=i++) {
+        double ax=arrow[j][0],ay=arrow[j][1],bx=arrow[i][0],by=arrow[i][1];
+        distance=fmin(distance,indicator_segment(x,y,ax,ay,bx,by));
+        if((ay>y)!=(by>y) && x<(bx-ax)*(y-ay)/(by-ay)+ax)inside=!inside;
+    }
+    double signed_distance=inside?-distance:distance;
+    color=indicator_over(color,fmax(0,fmin(1,3-signed_distance))*opacity,0x123047);
+    color=indicator_over(color,fmax(0,fmin(1,2-signed_distance))*opacity,0xffffff);
+    color=indicator_over(color,fmax(0,fmin(1,-signed_distance))*opacity,0x2999ff);
+    // A click sweeps a bright wave out through the cue; a key flashes it.
+    if(click>=0 && click<1)
+        color=indicator_tint(color,fmax(0,1-fabs(radius-(4+32*click))/5)*0.9*(1-click),0x9fdcff);
+    if(typed>=0 && typed<1)
+        color=indicator_tint(color,0.6*(1-typed),0xc8ecff);
+    return color;
+}
+#endif

package/engine/native/agent_overlay_wayland.c

@@ -1,5 +1,5 @@
 // Minimal wlroots layer-shell surface: transparent, unfocusable and input-empty.
-// Only the portal path uses it; X11 uses a cursor sprite instead.
+// Portal capture masking is implemented by capture.rs::IndicatorMask.
 // Protocol interface names/signatures from wlr-layer-shell-unstable-v1:
 // Copyright (c) 2017 Drew DeVault. Permission is hereby granted to use, copy,
 // modify and distribute this protocol for any purpose without fee, provided
@@ -14,6 +14,7 @@
 #include <unistd.h>
 #include <fcntl.h>
 #include <math.h>
+#include "agent_indicator.h"
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -63,7 +64,13 @@ static const struct wl_interface xdg_manager_interface={"zxdg_output_manager_v1"
 static const struct wl_message output_requests[]={{"destroy","",NULL}};
 static const struct wl_message output_events[]={{"logical_position","ii",NULL},{"logical_size","ii",NULL},{"done","",NULL},{"name","2s",NULL},{"description","2s",NULL}};
 static const struct wl_interface xdg_output_interface={"zxdg_output_v1",2,1,output_requests,5,output_events};
-struct Output { struct wl_output *handle; struct wl_proxy *logical; int x,y,w,h,valid; };
+struct Output { struct wl_output *handle; struct wl_proxy *logical; int x,y,w,h,valid,scale; };
+static void output_geometry(void *data,struct wl_output *p,int32_t x,int32_t y,int32_t pw,int32_t ph,int32_t sub,const char *make,const char *model,int32_t transform)
+    {(void)data;(void)p;(void)x;(void)y;(void)pw;(void)ph;(void)sub;(void)make;(void)model;(void)transform;}
+static void output_mode(void *data,struct wl_output *p,uint32_t flags,int32_t w,int32_t h,int32_t refresh){(void)data;(void)p;(void)flags;(void)w;(void)h;(void)refresh;}
+static void output_done(void *data,struct wl_output *p){(void)data;(void)p;}
+static void output_scale(void *data,struct wl_output *p,int32_t scale){(void)p;((struct Output *)data)->scale=scale;}
+static const struct wl_output_listener output_listener={.geometry=output_geometry,.mode=output_mode,.done=output_done,.scale=output_scale};
 static void logical_position(void *data, struct wl_proxy *p,int32_t x,int32_t y){(void)p;struct Output *o=data;o->x=x;o->y=y;o->valid=1;}
 static void logical_size(void *data,struct wl_proxy *p,int32_t w,int32_t h){(void)p;struct Output *o=data;o->w=w;o->h=h;}
 static void logical_done(void *data,struct wl_proxy *p){(void)data;(void)p;}
@@ -89,14 +96,16 @@ struct Overlay {
     struct Output outputs[32]; int output_count;
     struct wl_surface *surface;
     struct Buffer buffers[2];
-    int width, height, source_w, source_h, configured, closed;
+    int width, height, scale, source_w, source_h, configured, closed;
 };
 static double now(void) { struct timespec t; clock_gettime(CLOCK_MONOTONIC,&t); return t.tv_sec+t.tv_nsec/1e9; }
 static void registry_global(void *data, struct wl_registry *registry, uint32_t name, const char *interface, uint32_t version) {
     struct Overlay *o=data;
     if (!strcmp(interface,"wl_output") && o->output_count<32) {
         struct Output *out=&o->outputs[o->output_count++];
-        out->handle=wl_registry_bind(registry,name,&wl_output_interface,1);
+        out->handle=wl_registry_bind(registry,name,&wl_output_interface,version<2?version:2);
+        out->scale=1;
+        wl_output_add_listener(out->handle,&output_listener,out);
     }
     if (!strcmp(interface,"zxdg_output_manager_v1")) o->output_manager=wl_registry_bind(registry,name,&xdg_manager_interface,version<2?version:2);
     if (!strcmp(interface,"wl_compositor")) o->compositor=wl_registry_bind(registry,name,&wl_compositor_interface,version<4?version:4);
@@ -119,13 +128,14 @@ static void buffer_release(void *data, struct wl_buffer *buffer) { (void)buffer;
 static const struct wl_buffer_listener buffer_listener={buffer_release};
 
 static int create_buffer(struct Overlay *o, struct Buffer *b) {
-    b->length=(size_t)o->width*o->height*4;
+    int w=o->width*o->scale,h=o->height*o->scale;
+    b->length=(size_t)w*h*4;
     int fd=memfd_create("desklink-agent-overlay",MFD_CLOEXEC);
     if (fd<0 || ftruncate(fd,b->length)) { if(fd>=0)close(fd); return -1; }
     b->pixels=mmap(NULL,b->length,PROT_READ|PROT_WRITE,MAP_SHARED,fd,0);
     if (b->pixels==MAP_FAILED) {close(fd);return -1;}
     struct wl_shm_pool *pool=wl_shm_create_pool(o->shm,fd,(int)b->length);
-    b->handle=wl_shm_pool_create_buffer(pool,0,o->width,o->height,o->width*4,WL_SHM_FORMAT_ARGB8888);
+    b->handle=wl_shm_pool_create_buffer(pool,0,w,h,w*4,WL_SHM_FORMAT_ARGB8888);
     wl_shm_pool_destroy(pool); close(fd);
     wl_buffer_add_listener(b->handle,&buffer_listener,b);
     return 0;
@@ -134,12 +144,15 @@ static void blend(uint32_t *pixel, unsigned alpha, unsigned rgb) {
     // premultiplied ARGB8888: the compositor blends this over the desktop.
     *pixel=(alpha<<24)|(((rgb>>16)&255)*alpha/255<<16)|(((rgb>>8)&255)*alpha/255<<8)|((rgb&255)*alpha/255);
 }
-static void draw(struct Overlay *o, struct Buffer *b, double x, double y, double click, double typed, double ending, int positioned) {
-    double t=now(), opacity=ending?fmax(0,1-(t-ending)/0.6):1;
+static void draw(struct Overlay *o, struct Buffer *b, double x, double y, double click, double typed, double ending, double started, double cue_started) {
+    double t=now(), opacity=ending?fmax(0,1-(t-ending)/0.6):fmin(1,(t-started)/0.18);
+    // The cue fades in from its first position, not from the session's start.
+    double cue=ending?opacity:fmin(1,(t-cue_started)/0.18);
     memset(b->pixels,0,b->length);
-    int w=o->width,h=o->height;
-    for (int edge=0;edge<7;edge++) {
-        unsigned alpha=(unsigned)((7-edge)*1.8*opacity);
+    // Draw in buffer pixels; the cue itself is specified in logical pixels.
+    int s=o->scale,w=o->width*s,h=o->height*s;x*=s;y*=s;
+    for (int edge=0;edge<7*s;edge++) {
+        unsigned alpha=(unsigned)((7-(double)edge/s)*1.8*opacity);
         for(int px=edge;px<w-edge;px++) {
             blend(&b->pixels[(size_t)edge*w+px],alpha,0x4c9ed0);
             blend(&b->pixels[(size_t)(h-1-edge)*w+px],alpha,0x4c9ed0);
@@ -149,16 +162,17 @@ static void draw(struct Overlay *o, struct Buffer *b, double x, double y, double
             blend(&b->pixels[(size_t)py*w+w-1-edge],alpha,0x4c9ed0);
         }
     }
-    int left=fmax(0,x-55),right=fmin(w,x+55),top=fmax(0,y-55),bottom=fmin(h,y+55);
-    if(positioned)for(int py=top;py<bottom;py++)for(int px=left;px<right;px++) {
-        double distance=hypot(px-x,py-y);
-        double ring=fmax(0,1-fabs(distance-13)/5)*0.18;
-        ring+=fmax(0,1-fabs(distance-23)/7)*0.06;
-        if(click && t-click<0.55)ring+=fmax(0,1-fabs(distance-(12+37*(t-click)/0.55))/3)*0.42*(1-(t-click)/0.55);
-        if(typed && t-typed<0.4)
-            ring+=fmax(0,1-fabs(distance-(8+15*(t-typed)/0.4))/3)*0.22*(1-(t-typed)/0.4);
-        unsigned alpha=(unsigned)(fmin(1,ring*opacity)*255);
-        if(alpha)blend(&b->pixels[(size_t)py*w+px],alpha,0x4c9ed0);
+    int left=fmax(0,x-40*s),right=fmin(w,x+40*s),top=fmax(0,y-40*s),bottom=fmin(h,y+40*s);
+    if(cue_started)for(int py=top;py<bottom;py++)for(int px=left;px<right;px++) {
+        // Capture keeps the pointer's own pixels live (IndicatorMask), so the
+        // tip stays clear; the real cursor sits there anyway.
+        if(hypot((px-x)/s,(py-y)/s)<6)continue;
+        uint32_t src=indicator_pixel((px-x)/s,(py-y)/s,cue,
+            click?(t-click)/0.55:-1,typed?(t-typed)/0.4:-1), *dst=&b->pixels[(size_t)py*w+px];
+        // Premultiplied source-over, keeping the edge glow under the cue.
+        unsigned inverse=255-(src>>24);
+        if(src)*dst=src+((((*dst>>24)&255)*inverse/255)<<24)+((((*dst>>16)&255)*inverse/255)<<16)
+            +((((*dst>>8)&255)*inverse/255)<<8)+((*dst&255)*inverse/255);
     }
 }
 
@@ -202,7 +216,7 @@ static void draw_point(struct Overlay *o,struct Buffer *b,double x,double y,cons
 
 static int overlay_main(int source_w,int source_h,int point_mode,int origin_known,int origin_x,int origin_y) {
 
-    struct Overlay o={.source_w=source_w,.source_h=source_h};
+    struct Overlay o={.source_w=source_w,.source_h=source_h,.scale=1};
     o.display=wl_display_connect(NULL);
     if(!o.display)return 2;
     struct wl_registry *registry=wl_display_get_registry(o.display);
@@ -228,6 +242,11 @@ static int overlay_main(int source_w,int source_h,int point_mode,int origin_know
         if(!selected && o.output_count==1 && (!origin_known || !o.output_manager))selected=o.outputs[0].handle;
         if(!selected){puts("selected_output_unavailable");fflush(stdout);wl_display_disconnect(o.display);return 2;}
     }
+    if(!point_mode && wl_proxy_get_version((struct wl_proxy *)o.compositor)>=3) {
+        // Render the cue at the densest output's integer scale so it stays crisp on HiDPI.
+        if(wl_display_roundtrip(o.display)<0)return 2;
+        for(int i=0;i<o.output_count;i++)if(o.outputs[i].scale>o.scale)o.scale=o.outputs[i].scale<4?o.outputs[i].scale:4;
+    }
     FT_Library library=NULL;FT_Face font=point_mode?point_font(&library):NULL;
     if(point_mode&&!font){wl_display_disconnect(o.display);return 2;}
     o.surface=wl_compositor_create_surface(o.compositor);
@@ -244,13 +263,14 @@ static int overlay_main(int source_w,int source_h,int point_mode,int origin_know
         wl_surface_set_input_region(o.surface,empty);
         wl_region_destroy(empty);
     }
+    if(o.scale>1)wl_surface_set_buffer_scale(o.surface,o.scale);
     wl_surface_commit(o.surface);
     while(!o.configured&&!o.closed&&wl_display_dispatch(o.display)>=0) {}
     if(o.closed||o.width<=0||o.height<=0){wl_display_disconnect(o.display);return 2;}
     if(create_buffer(&o,&o.buffers[0])||create_buffer(&o,&o.buffers[1])){wl_display_disconnect(o.display);return 2;}
     int flags=fcntl(STDIN_FILENO,F_GETFL);fcntl(STDIN_FILENO,F_SETFL,flags|O_NONBLOCK);
     puts("READY");fflush(stdout);
-    double tx=0,ty=0,x=0,y=0,click=0,typed=0,ending=0;
+    double tx=0,ty=0,x=0,y=0,click=0,typed=0,ending=0,started=0,cue_started=0;
     int active=0,positioned=0;
     double deadline=0;char label[97]={0};int dirty=0,visible=0;
     char pending[512];size_t used=0;
@@ -277,8 +297,9 @@ static int overlay_main(int source_w,int source_h,int point_mode,int origin_know
                     else if(kind=='M'||kind=='C'||kind=='T'||kind=='A') {
                         if(px>=0&&py>=0) {
                             if(desklink_wayland_geometry(o.source_w,o.source_h,o.width,o.height,px,py,&tx,&ty)
-                                && !positioned){x=tx;y=ty;positioned=1;}
+                                && !positioned){x=tx;y=ty;positioned=1;cue_started=now();}
                         }
+                        if(!active)started=now();
                         active=1;
                         if(kind=='C')click=now();
                         if(kind=='T')typed=now();
@@ -292,11 +313,11 @@ static int overlay_main(int source_w,int source_h,int point_mode,int origin_know
         if(!point_mode){x+=(tx-x)*0.24;y+=(ty-y)*0.24;}
         for(int i=0;i<2;i++)if(!o.buffers[i].busy) {
             if(point_mode)draw_point(&o,&o.buffers[i],x,y,label,font,visible);
-            else draw(&o,&o.buffers[i],x,y,click,typed,ending,positioned);
+            else draw(&o,&o.buffers[i],x,y,click,typed,ending,started,cue_started);
             dirty=0;
             o.buffers[i].busy=1;
             wl_surface_attach(o.surface,o.buffers[i].handle,0,0);
-            wl_surface_damage_buffer(o.surface,0,0,o.width,o.height);
+            wl_surface_damage_buffer(o.surface,0,0,o.width*o.scale,o.height*o.scale);
             wl_surface_commit(o.surface);
             break;
         }