// Commander X16 Emulator — Debug Adapter Protocol (DAP) Server

// Speaks DAP over TCP for direct IDE integration (VS, VS Code, etc.)

// Transport: Content-Length framed JSON over TCP, default port 9009

#ifndef _DEBUG_SERVER_H_

#define _DEBUG_SERVER_H_

#include <stdbool.h>

#include <stdint.h>

#define DEBUG_SERVER_DEFAULT_PORT 9009

// The server needs cJSON, which is optional at configure time. When it is not

// available the emulator is built without it and every entry point below

// becomes a no-op, so callers -- the CPU loop, the debugger, the store path --

// do not have to be littered with #ifdefs for a feature they only notify.

#ifndef HAS_DAP

static inline int  debug_server_init(int port) { (void)port; return -1; }

static inline int  debug_server_poll(void) { return 0; }

static inline void debug_server_notify_stopped(const char *reason) { (void)reason; }

static inline bool debug_server_has_client(void) { return false; }

static inline bool debug_server_is_enabled(void) { return false; }

static inline void debug_server_output(const char *category, const char *text) { (void)category; (void)text; }

static inline void debug_server_invalidate_breakpoints_in_range(uint32_t start, uint32_t end) { (void)start; (void)end; }

static inline void debug_server_retry_unverified_breakpoints(void) { }

static inline void debug_server_note_resumed(void) { }

static inline void debug_server_shutdown(void) { }

#else

// Start listening on the given port. Returns 0 on success, -1 on error.

int  debug_server_init(int port);

// Poll for client commands. Non-blocking.

// Returns: 0 = no action, 1 = mode was changed by a remote command

int  debug_server_poll(void);

// Send DAP "stopped" event to the connected client.

// reason: "breakpoint", "step", "user", etc.

void debug_server_notify_stopped(const char *reason);

// Returns true if a debug client is currently connected.

bool debug_server_has_client(void);

// Returns true if the DAP server is enabled (--debugport was used).

bool debug_server_is_enabled(void);

// Forward text to a connected DAP client's debug console (OutputEvent). No-op

// if no client is connected. category is "console"/"stdout"/"stderr"/etc.

void debug_server_output(const char *category, const char *text);

// Breakpoint bookkeeping hooks driven by the shared runtime-load handler when a

// module is (re)loaded. No-ops when no DAP client is connected.

void debug_server_invalidate_breakpoints_in_range(uint32_t start, uint32_t end);

void debug_server_retry_unverified_breakpoints(void);

// Breakpoints are owned, not reconstructed. debug_core records which of -bp,

// the SDL debugger's F9, and the four kinds this file can ask for wants each

// entry, so a client session can clear everything it asked for with

// debug_bp_clear_owner() and nothing else is disturbed. Ask the core; do not

// rebuild that ownership out here from per-table flags or address refcounts.

//

// KNOWN LIMITATION, and a deliberate one: the core is the single source of

// truth for what is ARMED, but each front end owns its own VIEW. A breakpoint

// the user sets with F9 does not appear in a connected client's UI, and one the

// user deletes with F9 may be sent again by the client -- DAP's setBreakpoints

// replaces a source's whole list from the client's own model, and the

// specification tells clients to keep using their own properties rather than

// the adapter's. Emitting `breakpoint` events with reason `new`/`removed` would

// paper over this in VS Code specifically, but nothing in the protocol requires

// a client to act on them, so the divergence is documented rather than faked.

// The machine has resumed. Called from the debugger's own execution control, so

// that a local F5/F10/F11 is accounted for the same way a DAP continue is: the

// next stop is then reported once, rather than suppressed as a duplicate of a

// halt that is already over.

void debug_server_note_resumed(void);

// Clean shutdown — close sockets, free resources.

void debug_server_shutdown(void);

#endif // HAS_DAP

#endif