0.4.0: pointer injection (POST/GET /pointer) 346ca3ee83f4

## 0.4.0

- `POST /pointer?x=&y=[&buttons=]` (absolute) or `?dx=&dy=[&buttons=]` (relative)

  — inject a pointer move/click through the platform's native mouse path.

  `buttons` is a bitmask (bit0=primary, bit1=secondary); omit for a pure move.

  Backend callback: `set_pointer`.

- `GET /pointer` — read back the current pointer `{x, y, buttons}`, so a test can

  tell "input never arrived" from "wrong output drawn". Backend callback:

  `get_pointer`.

- First consumer: the Neo6502 fork (drives the firmware mouse), unblocking the

  pointer floor of the `rstar-api` RWM/RGM toolkit.

| `POST /pointer?x=&y=&buttons=` | inject a pointer move/click | 0.4 |

| `GET /pointer` | read back pointer position + buttons | 0.4 |

Current contract: **0.4.0**. Minors are purely additive (a missing capability

/* Four callbacks satisfy 0.1; add inject_key/reset for 0.2,

   write_mem/capture_audio for 0.3, set_pointer/get_pointer for 0.4.

   A NULL callback 501s its endpoint. */

    .set_pointer     = x16_set_pointer,      /* 0.4 */

    .get_pointer     = x16_get_pointer,      /* 0.4 */

Contract **0.4.0**, implemented across **four** emulators. The shared server and

the conformance suite (18 tests) are complete; the three 0.4 pointer tests are

exercised by the Neo6502 fork (the first 0.4 consumer) and skip on servers still

at 0.3. Reference implementation: the Commander X16 fork (`x16-emulator`), which

vendors `core/` as a git submodule; the NEC PC-FX fork (Mednafen) does the same,

and the FAB Agon emulator conforms directly in Rust.

**Contract version: 0.4.0** (semver; clients assert on the MAJOR). 0.4 adds

pointer injection (`POST /pointer`, `GET /pointer`); 0.3 added memory write

(`POST /mem`) and an audio drain (`GET /audio`); 0.2 added input injection

(`POST /key`, `POST /reset`). Every minor is purely additive, so older clients

keep working and servers advertise the highest level whose callbacks are all

present via `/status.contract`.

  "contract": "0.4.0",

### `POST /pointer?x=<n>&y=<n> | ?dx=<n>&dy=<n>  [&buttons=<mask>]`  *(0.4)*

Inject a pointer (mouse) move and/or click through the platform's native pointer

path — the mouse analogue of `/key`. Query params (no body):

- `x`, `y` — **absolute** pointer position, in the platform's pointer coordinate

  space (framebuffer pixels; appendix). Provide both.

- `dx`, `dy` — **relative** motion applied to the current position; either may be

  omitted (treated as 0). `x`/`y` and `dx`/`dy` are alternatives; provide one

  pair. Absolute is preferred for tests ("put the cursor on the button" beats

  dead-reckoning).

- `buttons` — OPTIONAL bitmask, **bit0 = primary, bit1 = secondary**. Omitted →

  the button state is left unchanged (a pure move). Provide `buttons=0` to

  release. Hold a button across `/step` frames (re-assert it each move) so a

  program that samples the pointer per frame sees the press.

- Response: `{ "injected": true }`. No pointer on the platform → 400.

Device-level, not driver-state: the injection MUST exercise the same path a real

mouse takes (e.g. the KERNAL/VERA mouse on the X16, the firmware mouse on the

Neo6502), so what the program reads is what a physical mouse would produce.

Determinism: inject under `/pause`, then `/step` — the move lands at the frame

boundary, so screenshot-diffing a hovered/clicked UI is reproducible.

### `GET /pointer`  *(0.4)*

Read back the current pointer state. Response:

```json

{ "x": 42, "y": 24, "buttons": 1 }

```

- `x`, `y` — current position in the same coordinate space as `POST /pointer`.

- `buttons` — the current button bitmask (same bit assignment).

- Lets a test distinguish "the input never reached the platform" from "it

  arrived but the program drew the wrong thing". No pointer on the platform → 400.

- Pointer: `/pointer` maps to the KERNAL/VERA mouse — absolute/relative position

  and buttons fed through the same path the host mouse uses, so `MOUSE_GET`

  (and VERA sprite 0) see it. Coordinates are screen pixels. (Backend

  callbacks not yet wired — until then the X16 fork advertises 0.3.0 and

  `/pointer` returns 501.)

- Pointer: `/pointer` drives the firmware mouse — absolute → `MSESetPosition`,

  relative → `MSEOffsetPosition`, buttons → `MSEUpdateButtonState`; `GET /pointer`

  reads `MSEGetState`. Coordinates are firmware graphics pixels (the same space a

  program reads). Buttons: bit0 = left, bit1 = right (the firmware's native

  masks), matching the contract's primary/secondary. The emulator enables the

  mouse at reset, so injection works from boot.

  `inject_key`/`reset` for 0.2, `write_mem`/`capture_audio` for 0.3, and

  `set_pointer`/`get_pointer` for 0.4 — a NULL callback makes its endpoint return

  501 and lowers the advertised contract), wire three loop hooks, call

  `retro_control_start(port, &backend)`; the socket loop, HTTP parsing, PPM/JSON

  encoding and pause/step control come for free. The Commander X16 fork does

  this.

../SPEC.md (0.4.x). Depends only on the stdlib; Pillow is optional and only

    def pointer(self, x: int | None = None, y: int | None = None,

                dx: int | None = None, dy: int | None = None,

                buttons: int | None = None) -> None:

        """Inject a pointer move/click (contract 0.4). Give absolute (x, y) or

        relative (dx, dy). `buttons` is a bitmask (bit0=primary, bit1=secondary);

        omit it for a pure move (leaves the button state unchanged). Hold buttons

        across step() frames for a program that samples the pointer each frame."""

        parts = []

        if x is not None and y is not None:

            parts.append(f"x={x}")

            parts.append(f"y={y}")

        elif dx is not None or dy is not None:

            parts.append(f"dx={dx if dx is not None else 0}")

            parts.append(f"dy={dy if dy is not None else 0}")

        else:

            raise EmuControlError("pointer() needs x= and y=, or dx=/dy=")

        if buttons is not None:

            parts.append(f"buttons={buttons}")

        self._post("/pointer?" + "&".join(parts))

    def pointer_get(self) -> dict:

        """GET /pointer — the current pointer as {x, y, buttons} (contract 0.4).

        `buttons` uses the same bitmask as pointer()."""

        body, _ = self._get("/pointer")

        return json.loads(body)

# -- contract 0.4: pointer injection (skipped on < 0.4 servers) --------------

def test_pointer_injection(emu):

    """/pointer accepts absolute (x,y) and relative (dx,dy) with an optional

    buttons= bitmask, and rejects a request with neither. The pointer's *effect*

    is platform-specific and tested per-port; here we assert the contract

    surface only."""

    if _contract_minor(emu) < 4:

        pytest.skip("contract < 0.4 (no pointer injection)")

    emu.pointer(x=10, y=20)                 # absolute move, buttons unchanged

    emu.pointer(x=10, y=20, buttons=1)      # primary button down

    emu.pointer(x=10, y=20, buttons=0)      # buttons released

    emu.pointer(dx=4, dy=-2)                # relative move

    code, _ = _raw(emu, "POST", "/pointer")  # neither x/y nor dx/dy

    assert code == 400

def test_pointer_readback(emu):

    """GET /pointer reports {x, y, buttons} as ints (contract 0.4). Values are

    platform-specific; we assert only shape."""

    if _contract_minor(emu) < 4:

        pytest.skip("contract < 0.4")

    emu.pause()

    try:

        emu.pointer(x=42, y=24, buttons=0)

        emu.step(1)

        p = emu.pointer_get()

        assert {"x", "y", "buttons"} <= p.keys()

        assert all(isinstance(p[k], int) for k in ("x", "y", "buttons"))

    finally:

        emu.resume()

def test_pointer_get_is_get(emu):

    if _contract_minor(emu) < 4:

        pytest.skip("contract < 0.4")

    # GET /pointer is the readback path (200); POST is the inject path.

    code, _ = _raw(emu, "GET", "/pointer")

    assert code == 200

#include <limits.h>

               REQ_WRITE, REQ_AUDIO, REQ_PTR_SET, REQ_PTR_GET } req_t;

static int      g_ptr_absolute;  /* 1 => (x,y) absolute; 0 => relative deltas */

static int32_t  g_ptr_x, g_ptr_y;

static int      g_ptr_buttons;   /* button bitmask, or -1 = leave unchanged */

    case REQ_PTR_SET: {

        const char *json;

        if (!g_be->set_pointer) {

            json = "{\"error\":\"not implemented\"}"; g_resp_status = 501;

        } else if (g_be->set_pointer(g_ptr_absolute, g_ptr_x, g_ptr_y, g_ptr_buttons)) {

            json = "{\"injected\":true}"; g_resp_status = 200;

        } else {

            json = "{\"error\":\"no pointer\"}"; g_resp_status = 400;

        }

        size_t l = strlen(json);

        uint8_t *b = (uint8_t *)malloc(l + 1);

        if (b) memcpy(b, json, l + 1);

        g_resp_body = b; g_resp_len = b ? l : 0;

        g_resp_ctype = "application/json";

        break;

    }

    case REQ_PTR_GET: {

        char *b;

        if (!g_be->get_pointer) {

            const char *json = "{\"error\":\"not implemented\"}";

            size_t l = strlen(json); b = (char *)malloc(l + 1);

            if (b) memcpy(b, json, l + 1);

            g_resp_len = b ? l : 0; g_resp_status = 501;

        } else {

            int32_t x = 0, y = 0; int buttons = 0;

            int ok = g_be->get_pointer(&x, &y, &buttons);

            b = (char *)malloc(96);

            if (!b) { g_resp_len = 0; g_resp_status = 500; }

            else if (ok) {

                g_resp_len = (size_t)snprintf(b, 96,

                    "{\"x\":%ld,\"y\":%ld,\"buttons\":%d}",

                    (long)x, (long)y, buttons);

                g_resp_status = 200;

            } else {

                g_resp_len = (size_t)snprintf(b, 96, "{\"error\":\"no pointer\"}");

                g_resp_status = 400;

            }

        }

        g_resp_body = (uint8_t *)b;

        g_resp_ctype = "application/json";

        break;

    }

        (g_be->inject_key && g_be->write_mem && g_be->capture_audio &&

         g_be->set_pointer && g_be->get_pointer) ? "0.4.0" :

        return;

    }

    if (!strcmp(target, "/pointer")) {

        if (is_post) {                        /* 0.4: move/click the pointer */

            long x  = query_long(query, "x",  LONG_MIN);

            long y  = query_long(query, "y",  LONG_MIN);

            long dx = query_long(query, "dx", LONG_MIN);

            long dy = query_long(query, "dy", LONG_MIN);

            if (x != LONG_MIN && y != LONG_MIN) {

                g_ptr_absolute = 1; g_ptr_x = (int32_t)x; g_ptr_y = (int32_t)y;

            } else if (dx != LONG_MIN || dy != LONG_MIN) {

                g_ptr_absolute = 0;

                g_ptr_x = (int32_t)(dx == LONG_MIN ? 0 : dx);

                g_ptr_y = (int32_t)(dy == LONG_MIN ? 0 : dy);

            } else {

                send_json(fd, 400, "{\"error\":\"pointer needs x&y or dx&dy\"}"); return;

            }

            g_ptr_buttons = (int)query_long(query, "buttons", -1);   /* -1 = unchanged */

            do_marshalled(fd, REQ_PTR_SET);

        } else {                              /* 0.4: read back the pointer */

            do_marshalled(fd, REQ_PTR_GET);

        }

 * whose backend callbacks are all present: 0.4.0 needs set_pointer + get_pointer

 * (on top of 0.3); 0.3.0 needs inject_key + write_mem + capture_audio; 0.2.0

 * needs inject_key; else 0.1.0. Keeps a partial backend honest. */

#define RETRO_CONTROL_CONTRACT "0.4.0"

    /* 0.4: inject a pointer (mouse) move/click through the platform's native

     * pointer path. `absolute` nonzero => (x,y) are absolute pointer

     * coordinates (framebuffer/pointer space); zero => (x,y) are relative

     * deltas applied to the current position. `buttons` is a bitmask

     * (bit0 = primary, bit1 = secondary), or -1 to leave the button state

     * unchanged (a pure move). Return 1 on success, 0 if the platform has no

     * pointer (server -> 400). NULL => POST /pointer returns 501. */

    int (*set_pointer)(int absolute, int32_t x, int32_t y, int buttons);

    /* 0.4: report the current pointer position and button bitmask (same

     * semantics as set_pointer's `buttons`). Return 1 on success (values

     * written), 0 if no pointer is available. NULL => GET /pointer returns 501. */

    int (*get_pointer)(int32_t *x, int32_t *y, int *buttons);