romdev-mcp 0.1.1

package/src/host/callbacks.js

@@ -0,0 +1,444 @@
+// libretro callback wiring.
+//
+// Registers the four required callbacks (env, video_refresh, input_poll,
+// input_state) plus audio sample + sample_batch. State lives on a plain
+// CallbackState object closed over by the addFunction handlers.
+//
+// Env handler patterns are mirrored from retroemu/src/core/LibretroHost.js —
+// many cores call log_cb / GET_VARIABLE / etc. inside retro_load_game, so we
+// must respond correctly to avoid WASM "null function / signature mismatch"
+// traps on cold load.
+//
+// See memory `libretro-wasm-patterns` for rationale.
+
+import { RETRO_HW_FRAME_BUFFER_VALID } from "./retroConstants.js";
+
+/**
+ * @typedef {Object} Frame
+ * @property {number} width
+ * @property {number} height
+ * @property {number} pitch
+ * @property {number} format one of RETRO_PIXEL_FORMAT_*
+ * @property {Uint8Array} pixels copy, safe to keep across calls
+ */
+
+/**
+ * @typedef {Object} CallbackState
+ * @property {number} pixelFormat negotiated pixel format
+ * @property {Frame | null} lastFrame
+ * @property {Int16Array[]} audioRing interleaved S16 stereo samples
+ * @property {boolean} supportsNoGame
+ * @property {Uint16Array[]} inputPorts joypad bitmask per port
+ * @property {Map<string, { description: string, options: string[], value: string }>} coreVariables
+ * @property {boolean} variablesUpdated
+ * @property {string} systemDir absolute path the core can ask about
+ * @property {string} saveDir absolute path the core can ask about
+ * @property {number[]} _allocatedPtrs heap pointers we keep alive for the core's lifetime
+ * @property {number | null} _logCbPtr cached log function pointer
+ */
+
+import {
+  RETRO_ENVIRONMENT_EXPERIMENTAL,
+  RETRO_PIXEL_FORMAT_0RGB1555,
+  RETRO_PIXEL_FORMAT_RGB565,
+  RETRO_PIXEL_FORMAT_XRGB8888,
+  RETRO_DEVICE_JOYPAD,
+} from "./retroConstants.js";
+
+// Env command IDs (extended set from retroemu)
+const E = {
+  GET_OVERSCAN: 2,
+  GET_CAN_DUPE: 3,
+  SET_MESSAGE: 6,
+  SHUTDOWN: 7,
+  SET_PERFORMANCE_LEVEL: 8,
+  GET_SYSTEM_DIRECTORY: 9,
+  SET_PIXEL_FORMAT: 10,
+  SET_INPUT_DESCRIPTORS: 11,
+  SET_KEYBOARD_CALLBACK: 12,
+  SET_DISK_CONTROL_INTERFACE: 13,
+  SET_HW_RENDER: 14,
+  GET_VARIABLE: 15,
+  SET_VARIABLES: 16,
+  GET_VARIABLE_UPDATE: 17,
+  SET_SUPPORT_NO_GAME: 18,
+  GET_LIBRETRO_PATH: 19,
+  SET_FRAME_TIME_CALLBACK: 21,
+  SET_AUDIO_CALLBACK: 22,
+  GET_RUMBLE_INTERFACE: 23,
+  GET_INPUT_DEVICE_CAPABILITIES: 24,
+  GET_SENSOR_INTERFACE: 25,
+  GET_CAMERA_INTERFACE: 26,
+  GET_LOG_INTERFACE: 27,
+  GET_PERF_INTERFACE: 28,
+  GET_LOCATION_INTERFACE: 29,
+  GET_CONTENT_DIRECTORY: 30,
+  GET_SAVE_DIRECTORY: 31,
+  SET_SYSTEM_AV_INFO: 32,
+  SET_PROC_ADDRESS_CALLBACK: 33,
+  SET_SUBSYSTEM_INFO: 34,
+  SET_CONTROLLER_INFO: 35,
+  SET_MEMORY_MAPS: 36,
+  SET_GEOMETRY: 37,
+  GET_USERNAME: 38,
+  GET_LANGUAGE: 39,
+  GET_CURRENT_SOFTWARE_FRAMEBUFFER: 40,
+  GET_HW_RENDER_INTERFACE: 41,
+  SET_SUPPORT_ACHIEVEMENTS: 42,
+  SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE: 43,
+  SET_SERIALIZATION_QUIRKS: 44,
+  SET_HW_SHARED_CONTEXT: 44 | 0x10000, // 0x1004C
+  GET_VFS_INTERFACE: 45,
+  GET_LED_INTERFACE: 46,
+  GET_AUDIO_VIDEO_ENABLE: 47,
+  GET_MIDI_INTERFACE: 48,
+  GET_FASTFORWARDING: 49,
+  GET_TARGET_REFRESH_RATE: 50,
+  GET_INPUT_BITMASKS: 51,
+  GET_CORE_OPTIONS_VERSION: 52,
+  SET_CORE_OPTIONS: 53,
+  SET_CORE_OPTIONS_INTL: 54,
+  SET_CORE_OPTIONS_DISPLAY: 55,
+  GET_PREFERRED_HW_RENDER: 56,
+  GET_DISK_CONTROL_INTERFACE_VERSION: 57,
+  SET_DISK_CONTROL_EXT_INTERFACE: 58,
+  GET_MESSAGE_INTERFACE_VERSION: 59,
+  SET_MESSAGE_EXT: 60,
+  GET_INPUT_MAX_USERS: 61,
+  SET_AUDIO_BUFFER_STATUS_CALLBACK: 62,
+  SET_MINIMUM_AUDIO_LATENCY: 63,
+  SET_FASTFORWARDING_OVERRIDE: 64,
+  SET_CONTENT_INFO_OVERRIDE: 65,
+  GET_GAME_INFO_EXT: 66,
+  SET_CORE_OPTIONS_V2: 67,
+  SET_CORE_OPTIONS_V2_INTL: 68,
+  SET_CORE_OPTIONS_UPDATE_DISPLAY_CALLBACK: 69,
+  SET_VARIABLE: 70,
+};
+
+/** @returns {CallbackState} */
+export function newCallbackState({ systemDir = "", saveDir = "" } = {}) {
+  return {
+    pixelFormat: RETRO_PIXEL_FORMAT_0RGB1555,
+    lastFrame: null,
+    audioRing: [],
+    supportsNoGame: false,
+    inputPorts: [new Uint16Array(1), new Uint16Array(1)],
+    // Keyboard state: a set of currently-pressed RETRO_KEY_* codes. The core
+    // polls via input_state(port, KEYBOARD, 0, keyCode) and gets 1 if pressed.
+    keysDown: new Set(),
+    coreVariables: new Map(),
+    variablesUpdated: false,
+    systemDir,
+    saveDir,
+    _allocatedPtrs: [],
+    _logCbPtr: null,
+  };
+}
+
+/**
+ * @param {number} format
+ * @returns {number}
+ */
+export function pixelBytes(format) {
+  if (format === RETRO_PIXEL_FORMAT_XRGB8888) return 4;
+  if (format === RETRO_PIXEL_FORMAT_RGB565) return 2;
+  if (format === RETRO_PIXEL_FORMAT_0RGB1555) return 2;
+  return 4;
+}
+
+/**
+ * Register all libretro callbacks on the module. Must be called BEFORE
+ * `_retro_init()`.
+ * @param {Object} args
+ * @param {any} args.mod Emscripten Module
+ * @param {CallbackState} args.state
+ * @param {(level: number, msg: string) => void} [args.log]
+ */
+export function registerCallbacks(args) {
+  const { mod, state, log } = args;
+
+  const envCb = mod.addFunction((cmd, dataPtr) => {
+    return handleEnv(mod, state, cmd, dataPtr, log) ? 1 : 0;
+  }, "iii");
+  mod._retro_set_environment(envCb);
+
+  const videoCb = mod.addFunction((dataPtr, w, h, pitch) => {
+    if (dataPtr === 0 || dataPtr === RETRO_HW_FRAME_BUFFER_VALID) return;
+    const bytes = h * pitch;
+    const view = mod.HEAPU8.subarray(dataPtr, dataPtr + bytes);
+    state.lastFrame = {
+      width: w,
+      height: h,
+      pitch,
+      format: state.pixelFormat,
+      pixels: new Uint8Array(view),
+    };
+  }, "viiii");
+  mod._retro_set_video_refresh(videoCb);
+
+  const audioBatchCb = mod.addFunction((dataPtr, frames) => {
+    if (dataPtr === 0 || frames === 0) return frames;
+    const byteLen = frames * 2 * 2;
+    const samples = new Int16Array(mod.HEAPU8.buffer, dataPtr, byteLen / 2).slice();
+    state.audioRing.push(samples);
+    return frames;
+  }, "iii");
+  mod._retro_set_audio_sample_batch(audioBatchCb);
+
+  const audioOneCb = mod.addFunction((left, right) => {
+    const buf = new Int16Array(2);
+    buf[0] = left;
+    buf[1] = right;
+    state.audioRing.push(buf);
+  }, "vii");
+  mod._retro_set_audio_sample(audioOneCb);
+
+  const inputPollCb = mod.addFunction(() => {
+    // input set explicitly by MCP callers — nothing to poll.
+  }, "v");
+  mod._retro_set_input_poll(inputPollCb);
+
+  const inputStateCb = mod.addFunction((port, device, _idx, id) => {
+    // device 3 = RETRO_DEVICE_KEYBOARD — id is the libretro keycode
+    if (device === 3) {
+      return state.keysDown.has(id) ? 1 : 0;
+    }
+    // Default: JOYPAD (device 1) and unknown devices fall through to bitfield.
+    const portBits = state.inputPorts[port];
+    if (!portBits) return 0;
+    const bits = portBits[0];
+    if (id === 256) return bits; // RETRO_DEVICE_ID_JOYPAD_MASK
+    return bits & (1 << id) ? 1 : 0;
+  }, "iiiii");
+  mod._retro_set_input_state(inputStateCb);
+}
+
+function allocString(mod, state, str) {
+  const bytes = Buffer.from(str + "\0", "utf-8");
+  const ptr = mod._malloc(bytes.length);
+  mod.HEAPU8.set(bytes, ptr);
+  state._allocatedPtrs.push(ptr);
+  return ptr;
+}
+
+function handleEnv(mod, state, rawCmd, dataPtr, log) {
+  const cmd = rawCmd & ~RETRO_ENVIRONMENT_EXPERIMENTAL;
+
+  switch (cmd) {
+    case E.GET_CAN_DUPE:
+      mod.setValue(dataPtr, 1, "i8");
+      return true;
+
+    case E.GET_OVERSCAN:
+      mod.setValue(dataPtr, 0, "i8");
+      return true;
+
+    case E.SET_MESSAGE:
+      return true; // accept, no UI to show it
+
+    case E.SET_PIXEL_FORMAT: {
+      const fmt = mod.getValue(dataPtr, "i32");
+      if (
+        fmt === RETRO_PIXEL_FORMAT_XRGB8888 ||
+        fmt === RETRO_PIXEL_FORMAT_RGB565 ||
+        fmt === RETRO_PIXEL_FORMAT_0RGB1555
+      ) {
+        state.pixelFormat = fmt;
+        return true;
+      }
+      return false;
+    }
+
+    case E.SET_SUPPORT_NO_GAME: {
+      const v = mod.getValue(dataPtr, "i8");
+      state.supportsNoGame = v !== 0;
+      return true;
+    }
+
+    case E.GET_SYSTEM_DIRECTORY: {
+      mod.setValue(dataPtr, allocString(mod, state, state.systemDir), "i32");
+      return true;
+    }
+
+    case E.GET_SAVE_DIRECTORY: {
+      mod.setValue(dataPtr, allocString(mod, state, state.saveDir), "i32");
+      return true;
+    }
+
+    case E.GET_CONTENT_DIRECTORY: {
+      mod.setValue(dataPtr, allocString(mod, state, state.saveDir), "i32");
+      return true;
+    }
+
+    case E.GET_LIBRETRO_PATH: {
+      mod.setValue(dataPtr, allocString(mod, state, state.systemDir), "i32");
+      return true;
+    }
+
+    case E.GET_LOG_INTERFACE: {
+      // retro_log_callback { retro_log_printf_t log }
+      // Signature: void(enum level, const char *fmt, ...). In Emscripten the
+      // vararg comes through as a pointer-to-stack; we declare 'viii' so the
+      // function-table entry has the right arity for the WASM caller.
+      //
+      // We don't implement full vsnprintf in JS, but the fmt string itself is
+      // already a useful diagnostic — most cores pass a fully-formed message
+      // (no varargs substitution needed) or a message + N args we can't decode.
+      // Read the fmt as-is so log output is actually readable.
+      if (!state._logCbPtr) {
+        state._logCbPtr = mod.addFunction((level, fmtPtr, _vaPtr) => {
+          if (!log) return;
+          let msg = "<unreadable>";
+          try { msg = mod.UTF8ToString(fmtPtr); } catch {}
+          log(level, msg);
+        }, "viii");
+      }
+      mod.setValue(dataPtr, state._logCbPtr, "i32");
+      return true;
+    }
+
+    case E.SET_VARIABLES: {
+      // retro_variable[]; { key*, value* } pairs, terminated by null key.
+      let ptr = dataPtr;
+      while (true) {
+        const keyPtr = mod.getValue(ptr, "i32");
+        const descPtr = mod.getValue(ptr + 4, "i32");
+        if (keyPtr === 0) break;
+        const key = mod.UTF8ToString(keyPtr);
+        const desc = descPtr ? mod.UTF8ToString(descPtr) : "";
+        const semi = desc.indexOf("; ");
+        if (semi >= 0) {
+          const options = desc.substring(semi + 2).split("|");
+          state.coreVariables.set(key, {
+            description: desc.substring(0, semi),
+            options,
+            value: options[0],
+          });
+        }
+        ptr += 8;
+      }
+      return true;
+    }
+
+    case E.SET_CORE_OPTIONS:
+    case E.SET_CORE_OPTIONS_INTL:
+    case E.SET_CORE_OPTIONS_V2:
+    case E.SET_CORE_OPTIONS_V2_INTL:
+      // We accept but don't parse v1/v2 core options yet; defaults are used.
+      return true;
+
+    case E.GET_VARIABLE: {
+      const keyPtr = mod.getValue(dataPtr, "i32");
+      if (keyPtr === 0) return false;
+      const key = mod.UTF8ToString(keyPtr);
+      const v = state.coreVariables.get(key);
+      if (!v) {
+        mod.setValue(dataPtr + 4, 0, "i32");
+        return false;
+      }
+      const valPtr = allocString(mod, state, v.value);
+      mod.setValue(dataPtr + 4, valPtr, "i32");
+      return true;
+    }
+
+    case E.GET_VARIABLE_UPDATE: {
+      mod.setValue(dataPtr, state.variablesUpdated ? 1 : 0, "i8");
+      state.variablesUpdated = false;
+      return true;
+    }
+
+    case E.GET_CORE_OPTIONS_VERSION:
+      mod.setValue(dataPtr, 0, "i32");
+      return true;
+
+    case E.GET_LANGUAGE:
+      mod.setValue(dataPtr, 0, "i32"); // English
+      return true;
+
+    case E.GET_USERNAME: {
+      mod.setValue(dataPtr, allocString(mod, state, "player"), "i32");
+      return true;
+    }
+
+    case E.GET_INPUT_DEVICE_CAPABILITIES:
+      mod.setValue(dataPtr, 1 << RETRO_DEVICE_JOYPAD, "i32");
+      return true;
+
+    case E.GET_INPUT_BITMASKS:
+      return true;
+
+    case E.GET_AUDIO_VIDEO_ENABLE:
+      mod.setValue(dataPtr, 7, "i32"); // audio + video + fast savestates
+      return true;
+
+    case E.GET_FASTFORWARDING:
+      mod.setValue(dataPtr, 0, "i8");
+      return true;
+
+    case E.GET_TARGET_REFRESH_RATE:
+      mod.setValue(dataPtr, 60.0, "double");
+      return true;
+
+    case E.GET_INPUT_MAX_USERS:
+      mod.setValue(dataPtr, 2, "i32");
+      return true;
+
+    case E.GET_MESSAGE_INTERFACE_VERSION:
+      mod.setValue(dataPtr, 0, "i32");
+      return true;
+
+    case E.GET_DISK_CONTROL_INTERFACE_VERSION:
+      mod.setValue(dataPtr, 0, "i32");
+      return true;
+
+    case E.SHUTDOWN:
+      return true;
+
+    // Accept-and-ignore set: core declares info we don't use right now.
+    case E.SET_INPUT_DESCRIPTORS:
+    case E.SET_CONTROLLER_INFO:
+    case E.SET_SUBSYSTEM_INFO:
+    case E.SET_MEMORY_MAPS:
+    case E.SET_PERFORMANCE_LEVEL:
+    case E.SET_GEOMETRY:
+    case E.SET_KEYBOARD_CALLBACK:
+    case E.SET_FRAME_TIME_CALLBACK:
+    case E.SET_AUDIO_CALLBACK:
+    case E.SET_AUDIO_BUFFER_STATUS_CALLBACK:
+    case E.SET_MINIMUM_AUDIO_LATENCY:
+    case E.SET_DISK_CONTROL_INTERFACE:
+    case E.SET_DISK_CONTROL_EXT_INTERFACE:
+    case E.SET_SUPPORT_ACHIEVEMENTS:
+    case E.SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE:
+    case E.SET_SERIALIZATION_QUIRKS:
+    case E.SET_CORE_OPTIONS_DISPLAY:
+    case E.SET_CORE_OPTIONS_UPDATE_DISPLAY_CALLBACK:
+    case E.SET_FASTFORWARDING_OVERRIDE:
+    case E.SET_CONTENT_INFO_OVERRIDE:
+    case E.SET_VARIABLE:
+    case E.SET_SYSTEM_AV_INFO:
+    case E.SET_PROC_ADDRESS_CALLBACK:
+      return true;
+
+    // Things we can't or don't want to support — reject so core falls back.
+    case E.SET_HW_RENDER: // no GL in headless mode
+    case E.GET_RUMBLE_INTERFACE:
+    case E.GET_SENSOR_INTERFACE:
+    case E.GET_CAMERA_INTERFACE:
+    case E.GET_PERF_INTERFACE:
+    case E.GET_LOCATION_INTERFACE:
+    case E.GET_VFS_INTERFACE:
+    case E.GET_LED_INTERFACE:
+    case E.GET_MIDI_INTERFACE:
+    case E.GET_HW_RENDER_INTERFACE:
+    case E.GET_PREFERRED_HW_RENDER:
+    case E.GET_CURRENT_SOFTWARE_FRAMEBUFFER:
+    case E.GET_GAME_INFO_EXT:
+      return false;
+
+    default:
+      if (log) log(0, `unhandled retro_environment cmd ${cmd}`);
+      return false;
+  }
+}

package/src/host/chafa-render.js

@@ -0,0 +1,170 @@
+// chafa-render.js — wrap @monteslu/chafa-wasm into a "give me an RGBA
+// buffer + target cell size, get back an ANSI string" helper.
+//
+// One char cell = 2 vertical pixels via half-block symbols (▀ ▄ █),
+// so a 256×224 NES frame at 1:1 pixel mapping is 256 cols × 112 rows.
+// Most agents will pass smaller dimensions (e.g. cols=80) and let
+// chafa downsample for a readable context-window-sized view.
+//
+// Chafa init is a few hundred ms — keep the canvas + symbol map alive
+// between calls. setupCanvas() reuses the canvas when dimensions and
+// settings haven't changed (same pattern as retroemu's videoWorker).
+
+let chafa = null;
+let initPromise = null;
+
+let symbolMap = 0;
+let canvasConfig = 0;
+let canvas = 0;
+let lastSettings = "";
+
+// chafa.h CHAFA_SYMBOL_TAG_* bitmask flags. Real values cross-checked
+// against retroemu's videoWorker.js (which uses this lib in
+// production). My original constants were guessed and wrong — e.g.
+// I had BLOCK=1, ASCII=2; real BLOCK=0x8, ASCII=0x4000. The bad
+// values silently picked an unrelated tag, which is why "ascii"
+// mode was still rendering Unicode block glyphs.
+const TAG_SPACE     = 0x1;
+const TAG_SOLID     = 0x2;
+const TAG_STIPPLE   = 0x4;
+const TAG_BLOCK     = 0x8;
+const TAG_BORDER    = 0x10;
+const TAG_QUAD      = 0x80;
+const TAG_VHALF     = 0x200;
+const TAG_BRAILLE   = 0x800;
+const TAG_ASCII     = 0x4000;
+const TAG_SEXTANT   = 0x400000;
+const TAG_OCTANT    = 0x4000000;
+
+const SYMBOL_TAGS = {
+  // Pure ASCII glyphs (space + printable 7-bit) — most text-shaped,
+  // safest for any environment, lossiest visually.
+  ascii:     TAG_SPACE | TAG_ASCII,
+  // Half-block (▀ ▄ █) — 1 cell = 2 stacked pixels (top fg / bottom bg).
+  // Best image fidelity for retro frames; requires Unicode.
+  halfblock: TAG_SPACE | TAG_VHALF,
+  // Mixed half/full-block + borders — chafa picks the best glyph
+  // per cell. Denser than pure half-block.
+  block:     TAG_SPACE | TAG_BLOCK | TAG_BORDER,
+  // Quad (▘ ▝ ▖ ▗ ▙ etc.) — 1 cell = 2×2 pixels. Doubles horizontal
+  // density at the cost of glyph variety.
+  quad:      TAG_SPACE | TAG_QUAD,
+  // Sextant (1 cell = 2×3 pixels) — Unicode 13+ font support required.
+  sextant:   TAG_SPACE | TAG_SEXTANT,
+};
+
+// chafa canvas-mode constants (from chafa.h). Values cross-checked
+// against retroemu's videoWorker.js which uses this exact lib in
+// production. (I had these flipped originally — TRUECOLOR=0 not 5,
+// FGBG=5 not 0 — which made `colors:'true'` silently render in
+// no-color mode and emit zero SGR escapes.)
+const COLOR_MODES = {
+  true:  0,  // CHAFA_CANVAS_MODE_TRUECOLOR
+  "256": 1,  // CHAFA_CANVAS_MODE_INDEXED_256
+  "16":  3,  // CHAFA_CANVAS_MODE_INDEXED_16
+  fgbg:  5,  // CHAFA_CANVAS_MODE_FGBG (no color, only fg/bg shape)
+};
+
+const CHAFA_OPTIMIZATION_ALL = 0xff;
+
+async function loadChafa() {
+  if (chafa) return chafa;
+  if (initPromise) return initPromise;
+  initPromise = (async () => {
+    const mod = await import("@monteslu/chafa-wasm");
+    let c = mod.default || mod;
+    if (typeof c === "function") c = await c();
+    chafa = c;
+    return chafa;
+  })();
+  return initPromise;
+}
+
+function setupCanvas(termCols, termRows, symbols, colors) {
+  const settings = `${termCols}x${termRows}|${symbols}|${colors}`;
+  if (settings === lastSettings && canvas) return;
+
+  // Tear down stale instances.
+  if (canvas) { chafa._chafa_canvas_unref(canvas); canvas = 0; }
+  if (canvasConfig) { chafa._chafa_canvas_config_unref(canvasConfig); canvasConfig = 0; }
+  if (symbolMap) { chafa._chafa_symbol_map_unref(symbolMap); symbolMap = 0; }
+
+  symbolMap = chafa._chafa_symbol_map_new();
+  const tags = SYMBOL_TAGS[symbols] ?? SYMBOL_TAGS.halfblock;
+  chafa._chafa_symbol_map_add_by_tags(symbolMap, tags);
+
+  canvasConfig = chafa._chafa_canvas_config_new();
+  chafa._chafa_canvas_config_set_geometry(canvasConfig, termCols, termRows);
+  const mode = COLOR_MODES[colors] ?? COLOR_MODES.true;
+  chafa._chafa_canvas_config_set_canvas_mode(canvasConfig, mode);
+  chafa._chafa_canvas_config_set_symbol_map(canvasConfig, symbolMap);
+  chafa._chafa_canvas_config_set_optimizations(canvasConfig, CHAFA_OPTIMIZATION_ALL);
+
+  canvas = chafa._chafa_canvas_new(canvasConfig);
+  lastSettings = settings;
+}
+
+// Serial mutex for the singleton canvas/symbolMap. Two concurrent
+// renderRgbaToAnsi calls (different MCP sessions, or even one session
+// firing back-to-back without awaiting) would race on the shared
+// WASM-side state — at best garbled output, at worst a heap corruption
+// crash. Chain everything onto a promise queue so only one render
+// runs at a time.
+let renderQueue = Promise.resolve();
+
+/**
+ * Render an RGBA8888 image to an ANSI escape-sequence string.
+ *
+ * Calls are serialized via an internal mutex — safe to invoke from
+ * multiple concurrent contexts (e.g. two MCP sessions). Each call
+ * still completes in <10ms so the queue doesn't grow.
+ *
+ * @param {Uint8Array} rgba   width*height*4 bytes
+ * @param {number}     width  pixel width of `rgba`
+ * @param {number}     height pixel height of `rgba`
+ * @param {object}     opts
+ * @param {number}     opts.cols    terminal columns to render into
+ * @param {number}     opts.rows    terminal rows to render into
+ * @param {string}     opts.symbols 'halfblock' | 'block' | 'quad' | 'sextant' | 'ascii'
+ * @param {string}     opts.colors  'true' | '256' | '16' | 'fgbg'
+ * @returns {Promise<string>} ANSI string ready to write to a terminal
+ */
+export async function renderRgbaToAnsi(rgba, width, height, opts) {
+  const ticket = renderQueue.then(() => renderOnce(rgba, width, height, opts));
+  // Replace the queue tail BEFORE awaiting, so subsequent callers
+  // chain behind our work. Use .catch to swallow this caller's error
+  // (it still propagates to the actual awaiter); without this, one
+  // bad call would poison the queue and break every future call.
+  renderQueue = ticket.catch(() => {});
+  return ticket;
+}
+
+async function renderOnce(rgba, width, height, opts) {
+  const c = await loadChafa();
+  const cols    = opts.cols    | 0;
+  const rows    = opts.rows    | 0;
+  const symbols = opts.symbols || "ascii";
+  const colors  = opts.colors  || "true";
+
+  setupCanvas(cols, rows, symbols, colors);
+
+  // Pump pixels into chafa WASM heap.
+  const ptr = c._malloc(rgba.length);
+  if (!ptr) throw new Error("chafa-render: out of WASM heap (rgba alloc)");
+  try {
+    c.HEAPU8.set(rgba, ptr);
+    c._chafa_canvas_set_contents_rgba8(canvas, ptr, width, height, width * 4);
+  } finally {
+    c._free(ptr);
+  }
+
+  const gsPtr = c._chafa_canvas_build_ansi(canvas);
+  if (!gsPtr) return "";
+  const strPtr = c._g_string_free_and_steal(gsPtr);
+  if (!strPtr) return "";
+  try {
+    return c.UTF8ToString(strPtr);
+  } finally {
+    c._free(strPtr);
+  }
+}

package/src/host/coreLoader.js

@@ -0,0 +1,57 @@
+// Load an Emscripten-built libretro core from disk and return the Module.
+//
+// Cores ship as two files: `<name>_libretro.js` (Emscripten glue) and
+// `<name>_libretro.wasm` (the binary). The .js is a factory.
+//
+// In Node we import the .js dynamically. Emscripten's Node glue locates the
+// .wasm next to the .js automatically unless we pass `wasmBinary`.
+
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { RETRO_API_VERSION } from "./retroConstants.js";
+
+/**
+ * @typedef {Object} LoadCoreArgs
+ * @property {string} jsPath absolute path to the `_libretro.js` glue
+ * @property {string} [wasmPath] absolute path to the `.wasm`; if omitted, Emscripten resolves next to the .js
+ */
+
+/**
+ * Loads a libretro core's Emscripten module. Does NOT call _retro_init() —
+ * the caller must register callbacks first, then init.
+ * @param {LoadCoreArgs} args
+ */
+export async function loadLibretroCore(args) {
+  const { jsPath, wasmPath } = args;
+
+  const url = pathToFileURL(jsPath).href + "?t=" + Date.now();
+  const ns = await import(url);
+  const factory = ns.default;
+  if (typeof factory !== "function") {
+    throw new Error(`Core glue at ${jsPath} did not default-export an Emscripten factory`);
+  }
+
+  /** @type {Record<string, unknown>} */
+  const opts = {
+    noInitialRun: true,
+    print: () => {},
+    printErr: () => {},
+  };
+  if (wasmPath) {
+    opts.wasmBinary = await readFile(wasmPath);
+  }
+
+  const mod = await factory(opts);
+
+  if (typeof mod._retro_api_version !== "function") {
+    throw new Error(`Core ${jsPath} missing _retro_api_version export`);
+  }
+  const version = mod._retro_api_version();
+  if (version !== RETRO_API_VERSION) {
+    throw new Error(
+      `Core ${jsPath} reports retro_api_version=${version}, expected ${RETRO_API_VERSION}`,
+    );
+  }
+
+  return mod;
+}