feat: report on-screen cursor position in producer contract

Append cursor_seq/cursor_visible/cursor_pos to the producer block
(host-RO ABI; offsets 168/172/176, existing layout unchanged). Position
is reported every pump tick, independent of draw_cursor, so a consumer
can overlay its own cursor even when the producer does not composite it.

x and y pack into one 8-aligned 64-bit field (single atomic store, no
tear); cursor_seq bumps last to gate a consistent read. Adds the
vgpu_publish_cursor() engine setter and a lightweight cursor_sample_pos()
(position/visibility only, no shape extract) called from the pump.

include/vgpu_stream.h

@@ -69,6 +69,18 @@ typedef struct {
     uint32_t    supported_formats;       /* bitmask (1u<<VGPU_FMT_*) */
     uint32_t    ctrl_ack;                /* echo of control.ctrl_gen (even) applied */
     uint32_t    full_frame_ack;          /* echo of control.full_frame_req honored */
+    /* --- cursor reporting (host-RO; position is sensor data, independent
+     *     of control.draw_cursor / cursor compositing) --- */
+    uint32_t    cursor_seq;              /* @168: monotonic; bumps each cursor publish.
+                                            Host reads it last (acquire) to gate a
+                                            consistent {cursor_pos,cursor_visible}; lets the
+                                            host tell "cursor idle" from "producer stopped
+                                            reporting". */
+    uint32_t    cursor_visible;          /* @172: 1=cursor shown (CURSOR_SHOWING), 0=hidden */
+    uint64_t    cursor_pos;              /* @176: packed screen position, 8-aligned single
+                                            atomic MOV. low 32 bits = x, high 32 = y, each a
+                                            signed int32 (two's-complement; multi-monitor →
+                                            negatives). Pair never tears (one 64-bit store). */
 } vgpu_producer_t;
 static_assert(alignof(vgpu_producer_t) == 64, "producer align");
 static_assert(sizeof(vgpu_producer_t) <= VGPU_PAGE, "producer fits page 0");
@@ -86,6 +98,9 @@ static_assert(offsetof(vgpu_producer_t, applied_fps)       == 152, "producer.app
 static_assert(offsetof(vgpu_producer_t, supported_formats) == 156, "producer.supported_formats");
 static_assert(offsetof(vgpu_producer_t, ctrl_ack)          == 160, "producer.ctrl_ack");
 static_assert(offsetof(vgpu_producer_t, full_frame_ack)    == 164, "producer.full_frame_ack");
+static_assert(offsetof(vgpu_producer_t, cursor_seq)        == 168, "producer.cursor_seq");
+static_assert(offsetof(vgpu_producer_t, cursor_visible)    == 172, "producer.cursor_visible");
+static_assert(offsetof(vgpu_producer_t, cursor_pos)        == 176, "producer.cursor_pos");
 
 /* ===== Control block (host-RW), own page, generation-guarded ===== */
 typedef struct {

src/stream/include/stream.h

@@ -53,4 +53,11 @@ void vgpu_bump_run_epoch(const vgpu_region_view* rv);
 void vgpu_tick_heartbeat(const vgpu_region_view* rv);
 void vgpu_publish_full_frame_ack(const vgpu_region_view* rv, uint32_t req);
 
+/* Publish the on-screen cursor position (host-RO). Position is sensor data and is
+ * reported independent of control.draw_cursor (host may draw its own overlay even when the
+ * producer does not composite the cursor). x,y are screen coords (signed; multi-monitor may
+ * be negative); visible!=0 when the cursor is shown. Packs x|y into one 8-aligned 64-bit
+ * field (single atomic store) and bumps cursor_seq last. */
+void vgpu_publish_cursor(const vgpu_region_view* rv, int32_t x, int32_t y, uint32_t visible);
+
 #endif /* VGPU_STREAM_ENGINE_H */

src/stream/publish.c

@@ -116,3 +116,14 @@ void vgpu_tick_heartbeat(const vgpu_region_view* rv) {
 void vgpu_publish_full_frame_ack(const vgpu_region_view* rv, uint32_t req) {
     vgpu_store_release32(&rv->producer->full_frame_ack, req);
 }
+
+void vgpu_publish_cursor(const vgpu_region_view* rv, int32_t x, int32_t y, uint32_t visible) {
+    vgpu_producer_t* p = rv->producer;
+    /* pack: low 32 = x, high 32 = y (signed → two's-complement bits) */
+    uint64_t packed = ((uint64_t)(uint32_t)y << 32) | (uint64_t)(uint32_t)x;
+    /* 64-bit aligned single MOV is atomic on x86_64; barrier orders it (heartbeat pattern) */
+    p->cursor_pos = packed;
+    vgpu_store_release32(&p->cursor_visible, visible);
+    /* publish seq last: its release-store gates the pos/visible writes above for the host */
+    vgpu_store_release32(&p->cursor_seq, p->cursor_seq + 1u);
+}

src/stream/win32/cursor.c

@@ -105,6 +105,15 @@ int cursor_sample(vgpu_ctx* ctx) {
     return changed;
 }
 
+void cursor_sample_pos(vgpu_ctx* ctx) {
+    vgpu_cursor_t* cur = &ctx->cursor;
+    CURSORINFO ci; ci.cbSize = sizeof ci;
+    if (!GetCursorInfo(&ci)) { cur->visible = 0; return; }
+    cur->visible = (ci.flags & CURSOR_SHOWING) != 0;
+    cur->x = ci.ptScreenPos.x;
+    cur->y = ci.ptScreenPos.y;
+}
+
 void cursor_draw(vgpu_ctx* ctx, uint8_t* dst, uint32_t W, uint32_t H) {
     vgpu_cursor_t* cur = &ctx->cursor;
     if (!cur->visible || cur->gw == 0) return;

src/stream/win32/cursor.h

@@ -10,6 +10,10 @@
  * Returns 1 if anything changed since last sample, else 0. */
 int  cursor_sample(vgpu_ctx* ctx);
 
+/* Sample only cursor position/visibility (no shape extract). Updates
+ * ctx->cursor.{visible,x,y}. Cheap (one GetCursorInfo); safe to call every pump tick. */
+void cursor_sample_pos(vgpu_ctx* ctx);
+
 /* Alpha/AND-XOR compose the sampled cursor onto a tight BGRA frame. */
 void cursor_draw(vgpu_ctx* ctx, uint8_t* bgra, uint32_t width, uint32_t height);
 

src/stream/win32/present.c

@@ -100,6 +100,12 @@ void vgpu_present_run(vgpu_ctx* ctx) {
             last_beat = nowt;
         }
 
+        /* --- cursor position: sensor data, reported every tick independent of
+         *     draw_cursor / compositing (host may overlay it itself) --- */
+        cursor_sample_pos(ctx);
+        vgpu_publish_cursor(rv, (int32_t)ctx->cursor.x, (int32_t)ctx->cursor.y,
+                            (uint32_t)(ctx->cursor.visible != 0));
+
         /* --- reconcile control (gen-seqlock -> apply -> ack) --- */
         vgpu_control_view cv;
         uint32_t desired = prev_state;