HTTP control contract, portable server core, and shared client 961b3c610c66

# Python

__pycache__/

*.pyc

.venv/

.pytest_cache/

# C build artifacts

*.o

*.a

*.so

build/

# editor/OS

*.swp

.DS_Store

MIT License

Copyright (c) 2026 Andy McCall

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

# retro-remote-debug-controller

A tiny, portable **HTTP control API for retro-platform emulators**, and the

shared tooling that speaks it. One contract → one test harness across every

Doomsday One port.

An emulator launched with a control-port flag exposes a localhost HTTP server:

| Endpoint | Returns |

|---|---|

| `GET /status` | contract version, platform, frame counter, paused state |

| `GET /screenshot` | PPM image of the live screen |

| `GET /mem?addr=&len=&bank=` | raw memory bytes |

| `GET /regs` | CPU registers (JSON) |

| `POST /step?frames=` | advance N frames deterministically |

| `POST /key`, `/reset` | *(0.2)* inject input |

## Why

Every one of these ports (Pac-Man on X16, Neo6502, Agon; and whatever's next) is

chasing **frame-exact** arcade fidelity, and every one had its own fragile,

platform-specific way to check state headless (write to the SD card, dump 64 KB

of RAM on a magic jump, grep stdout — which lies). This replaces all of that

with one contract:

- **`GET /mem`** → assert game state (sprite table, actor positions).

- **`GET /screenshot`** → Pillow → assert pixels, or just catch "nothing

  rendered" (the exact class of bug that costs an afternoon otherwise).

- **`POST /step`** → deterministic, frame-addressable capture, so CI diffs don't

  flake against a free-running 60 Hz loop.

The payoff is uniformity: the same `emu_control.py` and the same pytest patterns

drive the X16, Neo6502, and Agon emulators.

## Layout

```

SPEC.md                 the normative HTTP contract (start here)

core/retro_control.h    portable backend vtable each emulator implements

core/retro_control.c    shared server: sockets, HTTP, PPM/JSON, marshalling  [next]

client/emu_control.py   shared pytest client

conformance/            tests an emulator runs to prove it conforms          [next]

```

## Adopting it in an emulator (the shape)

Write the server once, adapt per fork. Each fork vendors `core/` and implements

~5 callbacks, then calls the server:

```c

#include "retro_control.h"

static retro_control_backend_t backend = {

    .platform       = "x16",

    .read_mem       = x16_read_mem,      /* debug-read, no side effects */

    .get_regs_json  = x16_get_regs_json,

    .get_framebuffer= x16_get_framebuffer,

    .step_frames    = x16_step_frames,

    .get_frame_count= x16_get_frame_count,

};

if (control_port)              /* set by -controlport / --control-port */

    retro_control_start(control_port, &backend);

```

The socket loop, HTTP parsing, PPM encoding, JSON framing, and the

enqueue-to-emulator-thread marshalling live in the shared core — not in three

different codebases.

## Status

Early. `SPEC.md` (0.1.0) and the interfaces below are the stable target the

forks build against; the server `.c` and conformance suite are landing next.

Reference implementation: the Commander X16 fork (`x16-emulator`).

# Retro Remote Debug Controller — HTTP Control Contract

**Contract version: 0.1.0** (semver; clients assert on the MAJOR).

A minimal, portable HTTP API that a retro-platform emulator exposes so an

external harness can screenshot the screen, read memory and registers, step the

machine deterministically, and (later) inject input. The same contract is

implemented by the forked FAB Agon Emulator, the Neo6502 emulator, and the

Commander X16 emulator, so **one** pytest harness drives all three ports.

## Principles

- **Opt-in.** The server is OFF by default and starts only when the emulator is

  launched with a control-port flag. Zero cost to normal use.

- **Localhost only.** The server MUST bind `127.0.0.1` (never `0.0.0.0`).

  `/mem` and input injection are a memory-read / remote-control surface; they do

  not leave the machine.

- **The contract is the HTTP surface, not the flag.** Each emulator names its

  launch flag idiomatically (x16emu: `-controlport N`; FAB: `--control-port N`).

  Only the endpoints below are normative.

- **Determinism is a first-class requirement.** These are frame-exact ports.

  Every state read (`/mem`, `/regs`, `/screenshot`) MUST observe a consistent

  machine state — captured at an instruction/frame boundary on the emulator

  thread, never a torn mid-instruction read from the HTTP thread. See

  *Consistency* below.

## Conventions

- JSON responses are `application/json; charset=utf-8`.

- Binary responses use the stated content-type; no chunked encoding required.

- Errors: HTTP 4xx/5xx with body `{"error":"<message>"}`.

- Numbers in JSON are decimal unless a field is documented as a hex string.

- Methods are exactly as listed (`GET`/`POST`). Unknown path → 404. Unknown

  method on a known path → 405.

## Endpoints

### `GET /status`

Liveness + contract negotiation. Always available.

```json

{

  "contract": "0.1.0",

  "emulator": "x16emu",

  "platform": "x16",

  "frame": 12345,

  "paused": true,

  "running": true

}

```

- `contract` — this document's version. Clients MUST reject a mismatched MAJOR.

- `platform` — one of `x16`, `neo6502`, `agon` (extensible). Tells the client

  the memory/register model (see *Per-platform* appendix).

- `frame` — monotonic completed-frame counter since boot. The determinism

  anchor: a screenshot taken at `frame == N` shows the state after N complete

  frames.

- `paused` — true if the machine is halted (only advances via `/step`).

### `GET /screenshot`

The live screen as a Portable Pixmap.

- Response: `image/x-portable-pixmap`, binary **PPM P6**, 8-bit RGB, no alpha.

- Pixels are the most recent COMPLETE frame (never a half-scanned frame). The

  emulator keeps a snapshot the render thread fills at frame end; the HTTP

  thread serves that snapshot.

- Dimensions are the platform's native framebuffer (appendix). Clients read

  `width`/`height` from the PPM header — do not hardcode.

- Reserved: `?frame=N` (block until frame N) — not required in 0.1.

### `GET /mem?addr=<a>&len=<n>[&bank=<b>]`

Raw memory bytes.

- `addr` — start address, decimal or `0x`-hex. Interpreted in the platform's

  address space (appendix).

- `len` — byte count, decimal. Servers MAY cap `len` (recommend ≥ 65536); a

  capped request returns what it can with `Content-Length` telling the truth.

- `bank` — OPTIONAL bank selector for banked platforms (X16). Omitted → the

  machine's currently-selected bank. Ignored by flat-memory platforms.

- Response: `application/octet-stream`, exactly the requested bytes.

- Reads go through the emulator's debug-read path (no side effects, no I/O

  triggers, no access-flag mutation).

### `GET /regs`

CPU registers as JSON. Keys are platform-specific (appendix); values are decimal

unless suffixed `_hex`. Example (x16 / 65C02):

```json

{ "a":0, "x":16, "y":2, "sp":505, "pc":49152, "status":32,

  "ram_bank":1, "rom_bank":0 }

```

### `POST /step?frames=<n>`  *(recommended; required for frame-exact tests)*

Advance the machine by exactly `n` complete frames (default 1), then halt.

- Only meaningful when the machine is paused (see `/pause`). On a free-running

  machine, servers SHOULD pause, run `n` frames, and stay paused.

- Response: `{ "frame": <new frame counter> }`.

- `POST /step?cycles=<n>` MAY be offered for sub-frame stepping.

### `POST /pause` / `POST /resume`  *(recommended)*

Halt / free-run. `{ "paused": true|false }`. A machine launched with a

`--control-pause`-style option SHOULD boot paused so tests are deterministic

from frame 0.

### `POST /key` / `POST /reset`  *(reserved for 0.2)*

Input injection. Proposed shape — `POST /key` body

`{ "code": <keycode>, "down": true|false }` or `{ "text": "..." }`; `/reset`

performs a cold reset. Not required in 0.1, but reserve the paths. Injection

plus `/step` is what retires scripted-autoexec input.

## Consistency (normative)

- `/mem`, `/regs`, and `/step` MUST be serviced on the emulator thread at an

  instruction boundary — e.g. the HTTP handler enqueues a command that the main

  loop drains between instructions/frames and signals back. The HTTP thread MUST

  NOT read CPU/RAM state directly while the CPU is executing.

- `/screenshot` MUST serve a complete-frame snapshot (double-buffer: render

  thread writes the back buffer, swaps under a lock at frame end; HTTP thread

  reads the front buffer).

- `frame` in `/status` MUST increment once per completed video frame and never

  go backwards (except across `/reset`).

## Versioning

- Semantic. MAJOR bump = breaking change to an existing endpoint's

  request/response. MINOR = additive (new endpoint / optional field). PATCH =

  clarification.

- Clients read `/status.contract` and fail fast on a MAJOR mismatch.

---

## Per-platform appendix

### Commander X16 — `x16emu`

- Flag: `-controlport <N>` (single-dash, matching x16emu's `-dump` style).

- Framebuffer: **640×480**, native order BGRA8888 (`framebuffer[i*4+2]=R`,

  `+1=G`, `+0=B`); the server swizzles to PPM RGB.

- Address space: 16-bit CPU (`0x0000–0xFFFF`). The banked window `0xA000–0xBFFF`

  is selected by `bank` → the emulator's `read6502(addr, bank)` / banked RAM

  (`BRAM`). `addr < 0xA000` or `≥ 0xC000` ignores `bank`.

- Registers: `a x y` (8), `sp pc` (16), `status` (8), plus `ram_bank`,

  `rom_bank`. Source: the `regs` struct + `memory_get_ram_bank/rom_bank()`.

- Frame source: `video.c` `frame_count`.

### Neo6502 — neo6502 emulator

- Flag: `--control-port <N>`.

- Address space: flat 64 KB; `bank` ignored.

- Registers: 6502 `a x y sp pc status`.

- Framebuffer: native resolution per the emulator's video mode.

### Agon (Console8 / Light 2) — FAB Agon Emulator

- Flag: `--control-port <N>`.

- Address space: eZ80 24-bit, flat 16 MB (`addr` up to `0xFFFFFF`); `bank`

  ignored. Program load base `0x040000`.

- Registers (ADL): `af bc de hl ix iy sp pc mbase` + ADL-mode flag.

- Framebuffer: from `vgabuf` (the VDP output), server swizzles to PPM RGB.

---

## Reference implementations in this repo

- `core/retro_control.h` — the portable backend vtable each fork implements.

- `core/retro_control.c` — the shared server (socket loop, HTTP parse, PPM/JSON

  encode, command marshalling). Forks vendor/submodule this and call

  `retro_control_start(port, &backend)`. *(server .c lands next.)*

- `client/emu_control.py` — the shared pytest client.

- `conformance/` — tests an emulator runs to prove it conforms. *(next.)*

"""emu_control.py — shared client for the Retro Remote Debug Controller.

One client for every port's pytest suite. Speaks the HTTP contract in

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

needed for .screenshot().

    from emu_control import EmuControl

    emu = EmuControl(port=8080)      # emulator started with -controlport 8080

    emu.wait_ready()

    emu.step(frames=120)

    assert emu.regs()["a"] == 0

    data = emu.mem(0x0400, 256, bank=1)

    img = emu.screenshot()           # PIL.Image (requires Pillow)

"""

from __future__ import annotations

import io

import json

import time

import urllib.error

import urllib.request

CONTRACT_MAJOR = 0

class EmuControlError(RuntimeError):

    pass

class EmuControl:

    def __init__(self, port: int, host: str = "127.0.0.1", timeout: float = 5.0):

        self.base = f"http://{host}:{port}"

        self.timeout = timeout

    # -- transport ---------------------------------------------------------

    def _get(self, path: str) -> tuple[bytes, str]:

        try:

            with urllib.request.urlopen(self.base + path, timeout=self.timeout) as r:

                return r.read(), r.headers.get_content_type()

        except urllib.error.HTTPError as e:

            raise EmuControlError(f"GET {path} -> {e.code}: {e.read()!r}") from e

    def _post(self, path: str) -> bytes:

        req = urllib.request.Request(self.base + path, method="POST", data=b"")

        try:

            with urllib.request.urlopen(req, timeout=self.timeout) as r:

                return r.read()

        except urllib.error.HTTPError as e:

            raise EmuControlError(f"POST {path} -> {e.code}: {e.read()!r}") from e

    # -- endpoints ---------------------------------------------------------

    def status(self) -> dict:

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

        st = json.loads(body)

        major = int(str(st.get("contract", "0")).split(".")[0])

        if major != CONTRACT_MAJOR:

            raise EmuControlError(

                f"contract major mismatch: emulator {st.get('contract')} "

                f"vs client {CONTRACT_MAJOR}.x"

            )

        return st

    def frame(self) -> int:

        return int(self.status()["frame"])

    def regs(self) -> dict:

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

        return json.loads(body)

    def mem(self, addr: int, length: int, bank: int | None = None) -> bytes:

        path = f"/mem?addr={addr}&len={length}"

        if bank is not None:

            path += f"&bank={bank}"

        body, _ = self._get(path)

        return body

    def step(self, frames: int = 1) -> int:

        body = self._post(f"/step?frames={frames}")

        return int(json.loads(body)["frame"])

    def pause(self) -> None:

        self._post("/pause")

    def resume(self) -> None:

        self._post("/resume")

    def screenshot(self):

        """Return the live screen as a PIL.Image (requires Pillow)."""

        body, ctype = self._get("/screenshot")

        try:

            from PIL import Image

        except ImportError as e:  # pragma: no cover

            raise EmuControlError("screenshot() needs Pillow (pip install pillow)") from e

        return Image.open(io.BytesIO(body))

    # -- helpers -----------------------------------------------------------

    def wait_ready(self, tries: int = 100, delay: float = 0.05) -> dict:

        """Poll /status until the server answers (emulator boot race)."""

        last = None

        for _ in range(tries):

            try:

                return self.status()

            except (EmuControlError, urllib.error.URLError, ConnectionError) as e:

                last = e

                time.sleep(delay)

        raise EmuControlError(f"emulator control port never came up: {last}")

    def run_to_frame(self, target: int) -> int:

        """Step until the frame counter reaches >= target."""

        cur = self.frame()

        if target > cur:

            self.step(frames=target - cur)

        return self.frame()

/* retro_control.c — portable emulator control server. See retro_control.h

 * and ../SPEC.md. POSIX (Linux/macOS); on Windows the entry points are no-ops.

 *

 * One accept thread, one request in flight at a time. State reads are marshalled

 * to the emulator thread via retro_control_service() so they observe a

 * consistent machine; /step is driven cooperatively by retro_control_on_frame().

 */

#include "retro_control.h"

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#if defined(_WIN32)

/* No server on Windows for now — stub out so the fork still builds. */

int  retro_control_start(int port, const retro_control_backend_t *b) { (void)port; (void)b; return -1; }

void retro_control_service(void) {}

int  retro_control_running(void) { return 1; }

void retro_control_on_frame(void) {}

void retro_control_stop(void) {}

#else

#include <pthread.h>

#include <unistd.h>

#include <errno.h>

#include <signal.h>

#include <sys/socket.h>

#include <netinet/in.h>

#include <arpa/inet.h>

#ifndef MSG_NOSIGNAL

#define MSG_NOSIGNAL 0

#endif

#define MEM_CAP (1u << 20)   /* /mem hard cap: 1 MiB per request */

static const retro_control_backend_t *g_be = NULL;

static int       g_listen_fd = -1;

static pthread_t g_thread;

static pthread_mutex_t g_lock = PTHREAD_MUTEX_INITIALIZER;

static pthread_cond_t  g_cv   = PTHREAD_COND_INITIALIZER;

/* run control: -1 free-run, 0 halted, >0 run this many frames then halt */

static long g_frames_to_run = -1;

static int  g_step_waiting  = 0;

/* single-slot marshalled request (mem / regs / screenshot) */

typedef enum { REQ_NONE = 0, REQ_MEM, REQ_REGS, REQ_SHOT } req_t;

static volatile req_t g_req = REQ_NONE;

static uint32_t g_req_addr, g_req_len;

static int32_t  g_req_bank;

static uint8_t    *g_resp_body  = NULL;

static size_t      g_resp_len   = 0;

static int         g_resp_status = 200;

static const char *g_resp_ctype = "application/octet-stream";

static int         g_resp_ready = 0;

/* ---- emulator-thread side ------------------------------------------------ */

static void build_ppm(void)

{

    retro_framebuffer_t fb;

    memset(&fb, 0, sizeof fb);

    g_be->get_framebuffer(&fb);

    int w = fb.width, h = fb.height;

    int bpp = (fb.fmt == RETRO_PIX_RGB888) ? 3 : 4;

    char hdr[64];

    int hl = snprintf(hdr, sizeof hdr, "P6\n%d %d\n255\n", w, h);

    size_t total = (size_t)hl + (size_t)3 * w * h;

    uint8_t *out = (uint8_t *)malloc(total ? total : 1);

    if (!out) { g_resp_body = NULL; g_resp_len = 0; g_resp_status = 500; return; }

    memcpy(out, hdr, hl);

    uint8_t *p = out + hl;

    const uint8_t *s = fb.pixels;

    for (int i = 0; i < w * h; i++) {

        const uint8_t *px = s + (size_t)i * bpp;

        if (fb.fmt == RETRO_PIX_BGRA8888) {

            p[0] = px[2]; p[1] = px[1]; p[2] = px[0];

        } else {                       /* RGB888 / RGBA8888 */

            p[0] = px[0]; p[1] = px[1]; p[2] = px[2];

        }

        p += 3;

    }

    g_resp_body = out;

    g_resp_len = total;

    g_resp_status = 200;

    g_resp_ctype = "image/x-portable-pixmap";

}

void retro_control_service(void)

{

    if (!g_be || g_req == REQ_NONE) return;   /* cheap unlocked fast-path */

    pthread_mutex_lock(&g_lock);

    switch (g_req) {

    case REQ_MEM: {

        uint32_t len = g_req_len > MEM_CAP ? MEM_CAP : g_req_len;

        uint8_t *buf = (uint8_t *)malloc(len ? len : 1);

        uint32_t got = 0;

        if (buf && g_be->read_mem) got = g_be->read_mem(g_req_addr, g_req_bank, len, buf, len);

        g_resp_body = buf; g_resp_len = got;

        g_resp_status = g_be->read_mem ? 200 : 501;

        g_resp_ctype = "application/octet-stream";

        break;

    }

    case REQ_REGS: {

        char *buf = (char *)malloc(1024);

        if (buf && g_be->get_regs_json) { g_be->get_regs_json(buf, 1024); }

        else if (buf) { buf[0] = 0; }

        g_resp_body = (uint8_t *)buf; g_resp_len = buf ? strlen(buf) : 0;

        g_resp_status = g_be->get_regs_json ? 200 : 501;

        g_resp_ctype = "application/json";

        break;

    }

    case REQ_SHOT:

        if (g_be->get_framebuffer) build_ppm();

        else { g_resp_body = NULL; g_resp_len = 0; g_resp_status = 501; }

        break;

    default: break;

    }

    g_req = REQ_NONE;

    g_resp_ready = 1;

    pthread_cond_broadcast(&g_cv);

    pthread_mutex_unlock(&g_lock);

}

int retro_control_running(void)

{

    if (!g_be) return 1;

    pthread_mutex_lock(&g_lock);

    long f = g_frames_to_run;

    pthread_mutex_unlock(&g_lock);

    return f != 0;

}

void retro_control_on_frame(void)

{

    if (!g_be) return;

    pthread_mutex_lock(&g_lock);

    if (g_frames_to_run > 0) {

        g_frames_to_run--;

        if (g_frames_to_run == 0 && g_step_waiting) {

            g_step_waiting = 0;

            g_resp_ready = 1;

            pthread_cond_broadcast(&g_cv);

        }

    }

    pthread_mutex_unlock(&g_lock);

}

/* ---- server-thread side -------------------------------------------------- */

static void write_all(int fd, const void *buf, size_t len)

{

    const char *p = (const char *)buf;

    while (len) {

        ssize_t w = send(fd, p, len, MSG_NOSIGNAL);

        if (w <= 0) return;

        p += w; len -= (size_t)w;

    }

}

static void send_http(int fd, int status, const char *ctype,

                      const uint8_t *body, size_t len)

{

    const char *reason =

        status == 200 ? "OK" :

        status == 400 ? "Bad Request" :

        status == 404 ? "Not Found" :

        status == 405 ? "Method Not Allowed" :

        status == 501 ? "Not Implemented" : "Error";

    char hdr[256];

    int hl = snprintf(hdr, sizeof hdr,

        "HTTP/1.1 %d %s\r\nContent-Type: %s\r\nContent-Length: %zu\r\n"

        "Connection: close\r\nAccess-Control-Allow-Origin: *\r\n\r\n",

        status, reason, ctype, len);

    write_all(fd, hdr, hl);

    if (body && len) write_all(fd, body, len);

}

static void send_json(int fd, int status, const char *json)

{

    send_http(fd, status, "application/json", (const uint8_t *)json, strlen(json));

}

/* value of query key, decimal or 0x-hex (strtol base 0); def if absent. */

static long query_long(const char *q, const char *key, long def)

{

    size_t kl = strlen(key);

    const char *p = q;

    while (p && *p) {

        if (!strncmp(p, key, kl) && p[kl] == '=')

            return strtol(p + kl + 1, NULL, 0);

        p = strchr(p, '&');

        if (p) p++;

    }

    return def;

}

/* marshal a read to the emulator thread, wait, send the response. */

static void do_marshalled(int fd, req_t r)

{

    pthread_mutex_lock(&g_lock);

    g_resp_ready = 0; g_resp_body = NULL; g_resp_len = 0;

    g_req = r;

    while (!g_resp_ready) pthread_cond_wait(&g_cv, &g_lock);

    uint8_t *body = g_resp_body; size_t len = g_resp_len;

    int st = g_resp_status; const char *ct = g_resp_ctype;

    g_resp_body = NULL;

    pthread_mutex_unlock(&g_lock);

    send_http(fd, st, ct, body, len);

    free(body);

}

static void do_status(int fd)

{

    pthread_mutex_lock(&g_lock);

    long f = g_frames_to_run;

    pthread_mutex_unlock(&g_lock);

    unsigned long long fc = g_be->get_frame_count ? g_be->get_frame_count() : 0;

    char buf[320];

    snprintf(buf, sizeof buf,

        "{\"contract\":\"%s\",\"emulator\":\"%s\",\"platform\":\"%s\","

        "\"frame\":%llu,\"paused\":%s,\"running\":true}",

        RETRO_CONTROL_CONTRACT,

        g_be->emulator ? g_be->emulator : "",

        g_be->platform ? g_be->platform : "",

        fc, (f == 0) ? "true" : "false");

    send_json(fd, 200, buf);

}

static void do_step(int fd, const char *query)

{

    long n = query_long(query, "frames", 1);

    if (n < 1) n = 1;

    pthread_mutex_lock(&g_lock);

    g_frames_to_run = n;

    g_step_waiting = 1;

    g_resp_ready = 0;

    while (!g_resp_ready) pthread_cond_wait(&g_cv, &g_lock);

    pthread_mutex_unlock(&g_lock);

    unsigned long long fc = g_be->get_frame_count ? g_be->get_frame_count() : 0;

    char buf[64];

    snprintf(buf, sizeof buf, "{\"frame\":%llu}", fc);

    send_json(fd, 200, buf);

}

static void do_setrun(int fd, long v, int paused)

{

    pthread_mutex_lock(&g_lock);

    g_frames_to_run = v;

    pthread_mutex_unlock(&g_lock);

    send_json(fd, 200, paused ? "{\"paused\":true}" : "{\"paused\":false}");

}

static void handle_conn(int fd)

{

    char req[2048];

    size_t n = 0;

    while (n < sizeof(req) - 1) {

        ssize_t r = recv(fd, req + n, sizeof(req) - 1 - n, 0);

        if (r <= 0) break;

        n += (size_t)r;

        if (strstr(req, "\r\n\r\n")) break;

    }

    req[n] = 0;

    char method[8] = {0}, target[1024] = {0};

    if (sscanf(req, "%7s %1023s", method, target) != 2) {

        send_json(fd, 400, "{\"error\":\"bad request\"}");

        return;

    }

    char *q = strchr(target, '?');

    const char *query = "";

    if (q) { *q = 0; query = q + 1; }

    int is_post = !strcmp(method, "POST");

    if (!strcmp(target, "/status"))          { do_status(fd); return; }

    if (!strcmp(target, "/regs"))            { do_marshalled(fd, REQ_REGS); return; }

    if (!strcmp(target, "/screenshot"))      { do_marshalled(fd, REQ_SHOT); return; }

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

        g_req_addr = (uint32_t)query_long(query, "addr", 0);

        g_req_len  = (uint32_t)query_long(query, "len", 0);

        g_req_bank = (int32_t)query_long(query, "bank", -1);

        do_marshalled(fd, REQ_MEM);

        return;

    }

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

        if (!is_post) { send_json(fd, 405, "{\"error\":\"POST only\"}"); return; }

        do_step(fd, query); return;

    }

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

        if (!is_post) { send_json(fd, 405, "{\"error\":\"POST only\"}"); return; }

        do_setrun(fd, 0, 1); return;

    }

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

        if (!is_post) { send_json(fd, 405, "{\"error\":\"POST only\"}"); return; }

        do_setrun(fd, -1, 0); return;

    }

    send_json(fd, 404, "{\"error\":\"not found\"}");

}

static void *server_main(void *arg)

{

    (void)arg;

    for (;;) {

        int fd = accept(g_listen_fd, NULL, NULL);

        if (fd < 0) {

            if (errno == EINTR) continue;

            break;

        }

        handle_conn(fd);

        close(fd);

    }

    return NULL;

}

int retro_control_start(int port, const retro_control_backend_t *backend)

{

    g_be = backend;

    signal(SIGPIPE, SIG_IGN);

    int fd = socket(AF_INET, SOCK_STREAM, 0);

    if (fd < 0) return -1;

    int one = 1;

    setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &one, sizeof one);

    struct sockaddr_in addr;

    memset(&addr, 0, sizeof addr);

    addr.sin_family = AF_INET;

    addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);   /* 127.0.0.1 only */

    addr.sin_port = htons((uint16_t)port);

    if (bind(fd, (struct sockaddr *)&addr, sizeof addr) < 0) {

        fprintf(stderr, "[retro_control] bind 127.0.0.1:%d failed: %s\n",

                port, strerror(errno));

        close(fd);

        return -1;

    }

    if (listen(fd, 4) < 0) { close(fd); return -1; }

    g_listen_fd = fd;

    if (pthread_create(&g_thread, NULL, server_main, NULL) != 0) {

        close(fd); g_listen_fd = -1; return -1;

    }

    pthread_detach(g_thread);

    fprintf(stderr, "[retro_control] listening on 127.0.0.1:%d (contract %s)\n",

            port, RETRO_CONTROL_CONTRACT);

    return 0;

}

void retro_control_stop(void)

{

    if (g_listen_fd >= 0) { close(g_listen_fd); g_listen_fd = -1; }

}

#endif /* !_WIN32 */

/* retro_control.h — portable emulator control server (see ../SPEC.md).

 *

 * A retro-platform emulator implements the small read-only backend below and

 * calls retro_control_start(). The shared server (retro_control.c) owns the

 * socket loop, HTTP parsing, PPM/JSON encoding, and control flow

 * (pause / step / free-run). It always binds 127.0.0.1. Contract 0.1.0.

 *

 * Integration is three calls in the emulator's main loop:

 *   retro_control_service();                 // once per iteration (cheap)

 *   if (!retro_control_running()) { idle; }  // gate advancing the machine

 *   ... run one instruction / frame ...

 *   if (frame_completed) retro_control_on_frame();

 *

 * Threading: the server runs on its own thread but never touches machine state

 * there. State-reading endpoints (/mem, /regs, /screenshot) are executed inside

 * retro_control_service() ON THE EMULATOR THREAD, so every read is consistent.

 * The backend callbacks are therefore called from the emulator thread (except

 * get_frame_count, which the server may also read for /status — make it a plain

 * atomic-ish counter read).

 */

#ifndef RETRO_CONTROL_H

#define RETRO_CONTROL_H

#include <stdint.h>

#include <stddef.h>

#define RETRO_CONTROL_CONTRACT "0.1.0"

/* Native framebuffer pixel layout; the server swizzles to PPM RGB. */

typedef enum {

    RETRO_PIX_RGB888 = 0,   /* 3 bytes/px: R,G,B                       */

    RETRO_PIX_RGBA8888,     /* 4 bytes/px: R,G,B,A                     */

    RETRO_PIX_BGRA8888      /* 4 bytes/px: B,G,R,A (x16 framebuffer)   */

} retro_pix_fmt_t;

typedef struct {

    const uint8_t *pixels;  /* start of the current complete frame     */

    int width;

    int height;

    retro_pix_fmt_t fmt;

} retro_framebuffer_t;

/* The emulator implements these. Any may be NULL: the matching endpoint then

 * returns 501 Not Implemented. */

typedef struct retro_control_backend {

    const char *platform;   /* "x16" | "neo6502" | "agon" | ...        */

    const char *emulator;   /* human name, e.g. "x16emu"               */

    /* Debug-read up to min(len, out_cap) bytes at addr into out, side-effect

     * free. bank is the optional bank selector (<0 = current bank). Returns the

     * number of bytes written. */

    uint32_t (*read_mem)(uint32_t addr, int32_t bank, uint32_t len,

                         uint8_t *out, uint32_t out_cap);

    /* Write a JSON object of registers into buf (NUL-terminated). */

    void (*get_regs_json)(char *buf, size_t cap);

    /* Report the current complete-frame framebuffer. */

    void (*get_framebuffer)(retro_framebuffer_t *out);

    /* Monotonic completed-frame counter. */

    uint64_t (*get_frame_count)(void);

} retro_control_backend_t;

/* Start the server thread bound to 127.0.0.1:port. Non-blocking; 0 on success,

 * negative on error. backend must outlive the server. */

int  retro_control_start(int port, const retro_control_backend_t *backend);

/* Drain a pending control request. Call once per main-loop iteration, at an

 * instruction/frame boundary. Cheap no-op when idle and when control is off. */

void retro_control_service(void);

/* Nonzero => the machine should advance this iteration. Returns 1 always when

 * control is off or the machine is free-running; 0 when paused with no steps

 * left. */

int  retro_control_running(void);

/* Call when a video frame completes. Drives /step (decrements the step budget,

 * halts and answers when it reaches zero). No-op when control is off. */

void retro_control_on_frame(void);

/* Stop the server (optional; process exit is fine too). */

void retro_control_stop(void);

#endif /* RETRO_CONTROL_H */