@typecad/cuttlefish 0.1.0-alpha.1

package/dist/api/shared/display-adapters/sdl.js

@@ -0,0 +1,452 @@
+// ---------------------------------------------------------------------------
+// SDL2 display adapter — renders the UI to a native desktop window.
+//
+// Emits C++ implementing the display HAL contract (display_target*,
+// display_canvas*, display_*) against SDL2. Color arrives as true RGB888
+// (UI_COLOR_T == uint32_t under UI_COLOR_DEPTH 888) and is packed into an
+// RGBA8888 framebuffer (0xFF000000 | color). Mirrors HostAdafruitGFX
+// (preview/host-gfx.ts) — the C++ twin of that TS framebuffer renderer. The
+// circle/line/round-rect algorithms are direct ports of host-gfx.ts.
+//
+// SDL2 is a host prerequisite (same posture as the g++/clang++ toolchain).
+// On Windows/MSYS2 use the ucrt64 SDL2; on Linux/macOS install via the
+// system package manager. Linked with -lSDL2.
+// ---------------------------------------------------------------------------
+import { escapeCppStringLiteral } from "../../../utils/strings.js";
+export const sdlAdapter = (display) => {
+    // The SDL adapter renders to a 32-bit desktop framebuffer and is RGB888-only
+    // (uint32_t buf/fg/bg, drawChar args, present's 0xFF000000|color). UI_COLOR_T
+    // is emitted from the resolved profile's colorFormat — if a config forces
+    // rgb565/mono here, the emitter produces uint16_t while this adapter expects
+    // uint32_t (type mismatch / garbage colors). Fail loudly rather than emit
+    // broken code. The profile resolver defaults SDL to rgb888, so this only
+    // fires on explicit misconfiguration.
+    if (display.colorFormat !== "rgb888") {
+        throw new Error(`SDL display adapter requires colorFormat "rgb888" (a desktop window has a ` +
+            `32-bit framebuffer), but got "${display.colorFormat}". Remove the ` +
+            `colorFormat override from your SDL display config, or set it to "rgb888".`);
+    }
+    const w = display.width;
+    const h = display.height;
+    // Window title: default "cuttlefish", overridable via config (display.title)
+    // and at runtime (ui.window.setTitle → ui_window_set_title).
+    const title = `"${escapeCppStringLiteral(display.title ?? "cuttlefish")}"`;
+    // Window icon: optional BMP path from config (display.icon). Core SDL2 loads
+    // BMP only; .png/.ico would need SDL_image.
+    const icon = display.icon ? `"${escapeCppStringLiteral(display.icon)}"` : "";
+    return {
+        includes: [
+            `#define CuttlefishDisplayTarget SdlGfxCanvas`,
+            `#define CuttlefishCanvas16 SdlGfxCanvas`,
+            // Handle main() ourselves: SDL's default header renames main→SDL_main and
+            // expects an int(argc,argv) signature. The cuttlefish-generated main() is
+            // int main(void), so suppress the rename and call SDL_SetMainReady() in
+            // display_init() instead.
+            `#define SDL_MAIN_HANDLED`,
+            `#include <SDL2/SDL.h>`,
+            `#include <cstdint>`,
+            `#include <cstring>`,
+        ].join("\n"),
+        declaration: ``,
+        functions: [
+            `// --- Display adapter: SDL2 (RGB888 → RGBA8888 window) ---`,
+            ``,
+            `// Offscreen RGBA8888 framebuffer canvas. Mirrors HostAdafruitGFX`,
+            `// (preview/host-gfx.ts) — draw_* write 0xFF000000|color (opaque alpha).`,
+            `// Circle/line/round-rect math is a direct port of host-gfx.ts.`,
+            `class SdlGfxCanvas {`,
+            `public:`,
+            `  int16_t w_, h_;`,
+            `  uint32_t* buf;`,
+            `  int16_t cx = 0, cy = 0;`,
+            `  uint32_t fg = 0xFFFFFFu, bg = 0x000000u;`,
+            `  uint8_t textSize = 1;`,
+            `  bool wrap = true;`,
+            `  explicit SdlGfxCanvas(int16_t w, int16_t h) : w_(w), h_(h), buf(new uint32_t[(size_t)w * h]()) {}`,
+            `  virtual ~SdlGfxCanvas() { delete[] buf; }`,
+            `  int16_t width() const { return w_; }`,
+            `  int16_t height() const { return h_; }`,
+            `  inline void put(int16_t x, int16_t y, uint32_t rgba) {`,
+            `    if (x < 0 || y < 0 || x >= w_ || y >= h_) return;`,
+            `    buf[(size_t)y * w_ + x] = rgba;`,
+            `  }`,
+            `  inline uint32_t get(int16_t x, int16_t y) const {`,
+            `    if (x < 0 || y < 0 || x >= w_ || y >= h_) return 0;`,
+            `    return buf[(size_t)y * w_ + x];`,
+            `  }`,
+            `  void drawPixel(int16_t x, int16_t y, UI_COLOR_T color) { put(x, y, (uint32_t)color); }`,
+            `  void fillRect(int16_t x, int16_t y, int16_t rw, int16_t rh, UI_COLOR_T color) {`,
+            `    if (rw <= 0 || rh <= 0) return;`,
+            `    uint32_t rgba = (uint32_t)color;`,
+            `    int16_t x0 = x < 0 ? 0 : x;`,
+            `    int16_t y0 = y < 0 ? 0 : y;`,
+            `    int16_t x1 = x + rw; if (x1 > w_) x1 = w_;`,
+            `    int16_t y1 = y + rh; if (y1 > h_) y1 = h_;`,
+            `    if (x0 >= x1 || y0 >= y1) return;`,
+            `    for (int16_t j = y0; j < y1; j++)`,
+            `      for (int16_t i = x0; i < x1; i++) buf[(size_t)j * w_ + i] = rgba;`,
+            `  }`,
+            `  void fillScreen(UI_COLOR_T color) {`,
+            `    uint32_t rgba = (uint32_t)color;`,
+            `    for (size_t i = 0; i < (size_t)w_ * h_; i++) buf[i] = rgba;`,
+            `  }`,
+            `  void drawFastHLine(int16_t x, int16_t y, int16_t len, UI_COLOR_T c) { fillRect(x, y, len, 1, c); }`,
+            `  void drawFastVLine(int16_t x, int16_t y, int16_t len, UI_COLOR_T c) { fillRect(x, y, 1, len, c); }`,
+            `  void drawRect(int16_t x, int16_t y, int16_t rw, int16_t rh, UI_COLOR_T c) {`,
+            `    if (rw <= 0 || rh <= 0) return;`,
+            `    drawFastHLine(x, y, rw, c);`,
+            `    drawFastHLine(x, y + rh - 1, rw, c);`,
+            `    drawFastVLine(x, y, rh, c);`,
+            `    drawFastVLine(x + rw - 1, y, rh, c);`,
+            `  }`,
+            `  void drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1, UI_COLOR_T c) {`,
+            `    bool steep = (y1 - y0 < 0 ? -(y1 - y0) : (y1 - y0)) > (x1 - x0 < 0 ? -(x1 - x0) : (x1 - x0));`,
+            `    if (steep) { int16_t t; t = x0; x0 = y0; y0 = t; t = x1; x1 = y1; y1 = t; }`,
+            `    if (x0 > x1) { int16_t t; t = x0; x0 = x1; x1 = t; t = y0; y0 = y1; y1 = t; }`,
+            `    int16_t dx = x1 - x0;`,
+            `    int16_t dy = (y1 - y0 < 0) ? -(y1 - y0) : (y1 - y0);`,
+            `    int16_t err = dx / 2;`,
+            `    int16_t ystep = (y0 < y1) ? 1 : -1;`,
+            `    for (; x0 <= x1; x0++) {`,
+            `      if (steep) put(y0, x0, (uint32_t)c); else put(x0, y0, (uint32_t)c);`,
+            `      err -= dy; if (err < 0) { y0 += ystep; err += dx; }`,
+            `    }`,
+            `  }`,
+            `  void drawCircleHelper(int16_t x0, int16_t y0, int16_t r, uint8_t cn, UI_COLOR_T c) {`,
+            `    int16_t f = 1 - r, ddFx = 1, ddFy = -2 * r, x = 0, y = r;`,
+            `    while (x < y) {`,
+            `      if (f >= 0) { y--; ddFy += 2; f += ddFy; }`,
+            `      x++; ddFx += 2; f += ddFx;`,
+            `      if (cn & 0x4) { put(x0 + x, y0 + y, (uint32_t)c); put(x0 + y, y0 + x, (uint32_t)c); }`,
+            `      if (cn & 0x2) { put(x0 + x, y0 - y, (uint32_t)c); put(x0 + y, y0 - x, (uint32_t)c); }`,
+            `      if (cn & 0x8) { put(x0 - y, y0 + x, (uint32_t)c); put(x0 - x, y0 + y, (uint32_t)c); }`,
+            `      if (cn & 0x1) { put(x0 - y, y0 - x, (uint32_t)c); put(x0 - x, y0 - y, (uint32_t)c); }`,
+            `    }`,
+            `  }`,
+            `  void fillCircleHelper(int16_t x0, int16_t y0, int16_t r, uint8_t corners, int16_t delta, UI_COLOR_T c) {`,
+            `    int16_t f = 1 - r, ddFx = 1, ddFy = -2 * r, x = 0, y = r, px = x, py = y;`,
+            `    delta++;`,
+            `    while (x < y) {`,
+            `      if (f >= 0) { y--; ddFy += 2; f += ddFy; }`,
+            `      x++; ddFx += 2; f += ddFx;`,
+            `      if (x < y + 1) {`,
+            `        if (corners & 1) drawFastVLine(x0 + x, y0 - y, 2 * y + delta, c);`,
+            `        if (corners & 2) drawFastVLine(x0 - x, y0 - y, 2 * y + delta, c);`,
+            `      }`,
+            `      if (y != py) {`,
+            `        if (corners & 1) drawFastVLine(x0 + py, y0 - px, 2 * px + delta, c);`,
+            `        if (corners & 2) drawFastVLine(x0 - py, y0 - px, 2 * px + delta, c);`,
+            `        py = y;`,
+            `      }`,
+            `      px = x;`,
+            `    }`,
+            `  }`,
+            `  void drawCircle(int16_t x0, int16_t y0, int16_t r, UI_COLOR_T c) {`,
+            `    int16_t f = 1 - r, ddFx = 1, ddFy = -2 * r, x = 0, y = r;`,
+            `    put(x0, y0 + r, (uint32_t)c); put(x0, y0 - r, (uint32_t)c);`,
+            `    put(x0 + r, y0, (uint32_t)c); put(x0 - r, y0, (uint32_t)c);`,
+            `    while (x < y) {`,
+            `      if (f >= 0) { y--; ddFy += 2; f += ddFy; }`,
+            `      x++; ddFx += 2; f += ddFx;`,
+            `      put(x0 + x, y0 + y, (uint32_t)c); put(x0 - x, y0 + y, (uint32_t)c);`,
+            `      put(x0 + x, y0 - y, (uint32_t)c); put(x0 - x, y0 - y, (uint32_t)c);`,
+            `      put(x0 + y, y0 + x, (uint32_t)c); put(x0 - y, y0 + x, (uint32_t)c);`,
+            `      put(x0 + y, y0 - x, (uint32_t)c); put(x0 - y, y0 - x, (uint32_t)c);`,
+            `    }`,
+            `  }`,
+            `  void fillCircle(int16_t x0, int16_t y0, int16_t r, UI_COLOR_T c) {`,
+            `    drawFastVLine(x0, y0 - r, 2 * r + 1, c);`,
+            `    fillCircleHelper(x0, y0, r, 3, 0, c);`,
+            `  }`,
+            `  void drawRoundRect(int16_t x, int16_t y, int16_t rw, int16_t rh, int16_t r, UI_COLOR_T c) {`,
+            `    if (rw <= 0 || rh <= 0) return;`,
+            `    if (r <= 0) { drawRect(x, y, rw, rh, c); return; }`,
+            `    int16_t mr = rw < rh ? rw : rh; mr /= 2; if (r > mr) r = mr;`,
+            `    drawFastHLine(x + r, y, rw - 2 * r, c);`,
+            `    drawFastHLine(x + r, y + rh - 1, rw - 2 * r, c);`,
+            `    drawFastVLine(x, y + r, rh - 2 * r, c);`,
+            `    drawFastVLine(x + rw - 1, y + r, rh - 2 * r, c);`,
+            `    drawCircleHelper(x + r, y + r, r, 1, c);`,
+            `    drawCircleHelper(x + rw - r - 1, y + r, r, 2, c);`,
+            `    drawCircleHelper(x + rw - r - 1, y + rh - r - 1, r, 4, c);`,
+            `    drawCircleHelper(x + r, y + rh - r - 1, r, 8, c);`,
+            `  }`,
+            `  void fillRoundRect(int16_t x, int16_t y, int16_t rw, int16_t rh, int16_t r, UI_COLOR_T c) {`,
+            `    if (rw <= 0 || rh <= 0) return;`,
+            `    if (r <= 0) { fillRect(x, y, rw, rh, c); return; }`,
+            `    int16_t mr = rw < rh ? rw : rh; mr /= 2; if (r > mr) r = mr;`,
+            `    fillRect(x + r, y, rw - 2 * r, rh, c);`,
+            `    int16_t delta = rh - 2 * r - 1; if (delta < 0) delta = 0;`,
+            `    fillCircleHelper(x + rw - r - 1, y + r, r, 1, delta, c);`,
+            `    fillCircleHelper(x + r, y + r, r, 2, delta, c);`,
+            `  }`,
+            `  void drawRGBBitmap(int16_t x, int16_t y, const UI_COLOR_T* b, int16_t bw, int16_t bh) {`,
+            `    for (int16_t j = 0; j < bh; j++)`,
+            `      for (int16_t i = 0; i < bw; i++) {`,
+            `        put(x + i, y + j, (uint32_t)b[(size_t)j * bw + i]);`,
+            `      }`,
+            `  }`,
+            `  void setCursor(int16_t x, int16_t y) { cx = x; cy = y; }`,
+            `  void setTextColor(UI_COLOR_T c) { fg = (uint32_t)c; bg = fg; }`,
+            `  void setTextColorBg(UI_COLOR_T c, UI_COLOR_T b) { fg = (uint32_t)c; bg = (uint32_t)b; }`,
+            `  void setTextSize(uint8_t s) { textSize = s; }`,
+            `  void setTextWrap(bool wp) { wrap = wp; }`,
+            `  // print() uses the 5x8 glcd font (same bytes as Adafruit_GFX / the`,
+            `  // preview's HostAdafruitGFX). __sdl_glcdfont is defined below.`,
+            `  void drawChar(int16_t x, int16_t y, unsigned char ch, uint32_t fgc, uint32_t bgc, uint8_t size);`,
+            `  void print(const char* s);`,
+            `};`,
+            ``,
+            `// 5x8 bitmap font. Public-domain Adafruit glcdfont.c bytes — identical`,
+            `// to what HostAdafruitGFX (preview/host-gfx.ts) uses.`,
+            `// Each glyph is 5 columns of 8 vertical bits (bit 0 = top row).`,
+            `static const uint8_t __sdl_glcdfont[1280] = {`,
+            ...glcdfontBytes(),
+            `};`,
+            ``,
+            `void SdlGfxCanvas::drawChar(int16_t x, int16_t y, unsigned char ch, uint32_t fgc, uint32_t bgc, uint8_t size) {`,
+            `  if (ch >= 176 && ch < 255) ch++;`,
+            `  const uint8_t* glyph = &__sdl_glcdfont[(size_t)ch * 5];`,
+            `  for (int8_t i = 0; i < 5; i++) {`,
+            `    uint8_t line = glyph[i];`,
+            `    for (int8_t j = 0; j < 8; j++, line >>= 1) {`,
+            `      if (line & 1) {`,
+            `        if (size == 1) put(x + i, y + j, fgc);`,
+            `        else fillRect(x + i * size, y + j * size, size, size, fgc);`,
+            `      } else if (bgc != fgc) {`,
+            `        if (size == 1) put(x + i, y + j, bgc);`,
+            `        else fillRect(x + i * size, y + j * size, size, size, bgc);`,
+            `      }`,
+            `    }`,
+            `  }`,
+            `  if (bgc != fgc) {`,
+            `    if (size == 1) fillRect(x + 5, y, 1, 8, bgc);`,
+            `    else fillRect(x + 5 * size, y, size, 8 * size, bgc);`,
+            `  }`,
+            `}`,
+            `void SdlGfxCanvas::print(const char* s) {`,
+            `  while (*s) {`,
+            `    if (*s == '\\n') { cx = 0; cy += 8 * textSize; s++; continue; }`,
+            `    if (*s == '\\r') { s++; continue; }`,
+            `    if (wrap && cx + 6 * textSize > w_) { cx = 0; cy += 8 * textSize; }`,
+            `    drawChar(cx, cy, (unsigned char)*s, fg, bg, textSize);`,
+            `    cx += 6 * textSize;`,
+            `    s++;`,
+            `  }`,
+            `}`,
+            ``,
+            `class SdlGfxTarget : public SdlGfxCanvas {`,
+            `public:`,
+            `  SDL_Window* win = nullptr;`,
+            `  SDL_Renderer* ren = nullptr;`,
+            `  SDL_Texture* tex = nullptr;`,
+            `  explicit SdlGfxTarget(int16_t w, int16_t h) : SdlGfxCanvas(w, h) {}`,
+            `  void present() {`,
+            `    if (!tex) return;`,
+            `    // The framebuffer stores raw RGB888 (no alpha). The texture is`,
+            `    // ARGB8888, so set opaque alpha (0xFF) per pixel at present time.`,
+            `    static uint32_t* _presentBuf = nullptr;`,
+            `    static size_t _presentBufLen = 0;`,
+            `    size_t n = (size_t)w_ * h_;`,
+            `    if (!_presentBuf || _presentBufLen < n) { delete[] _presentBuf; _presentBuf = new uint32_t[n]; _presentBufLen = n; }`,
+            `    for (size_t i = 0; i < n; i++) _presentBuf[i] = 0xFF000000u | buf[i];`,
+            `    SDL_UpdateTexture(tex, nullptr, _presentBuf, w_ * (int)sizeof(uint32_t));`,
+            `    SDL_RenderClear(ren);`,
+            `    SDL_RenderCopy(ren, tex, nullptr, nullptr);`,
+            `    SDL_RenderPresent(ren);`,
+            `  }`,
+            `};`,
+            ``,
+            `// Global display instance (declared after the class definitions above).`,
+            `SdlGfxTarget __tc_display(${w}, ${h});`,
+            ``,
+            `static inline void display_init() {`,
+            `  SDL_SetMainReady();`,
+            `  SDL_Init(SDL_INIT_VIDEO);`,
+            // FULLSCREEN_DESKTOP scales the fixed w_×h_ framebuffer to fill the
+            // monitor without changing the display mode (vs SDL_WINDOW_FULLSCREEN,
+            // which requires a matching mode and can fail). Mouse coords from
+            // SDL_GetMouseState stay in window/logical space, so the touch clamp
+            // (display_width()/height()) still maps clicks correctly.
+            ...(display.fullscreen
+                ? [`  __tc_display.win = SDL_CreateWindow(${title},`,
+                    `    SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED,`,
+                    `    __tc_display.w_, __tc_display.h_, SDL_WINDOW_SHOWN | SDL_WINDOW_FULLSCREEN_DESKTOP);`]
+                : [`  __tc_display.win = SDL_CreateWindow(${title},`,
+                    `    SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED,`,
+                    `    __tc_display.w_, __tc_display.h_, SDL_WINDOW_SHOWN);`]),
+            ...(icon
+                ? [`  { SDL_Surface* __icon = SDL_LoadBMP(${icon});`,
+                    `    if (__icon) { SDL_SetWindowIcon(__tc_display.win, __icon); SDL_FreeSurface(__icon); } }`]
+                : []),
+            `  __tc_display.ren = SDL_CreateRenderer(__tc_display.win, -1,`,
+            `    SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC);`,
+            `  __tc_display.tex = SDL_CreateTexture(__tc_display.ren,`,
+            `    SDL_PIXELFORMAT_ARGB8888, SDL_TEXTUREACCESS_STREAMING,`,
+            `    __tc_display.w_, __tc_display.h_);`,
+            `  __tc_display.fillScreen(0);`,
+            `}`,
+            // Runtime window-title setter (lowered from ui.window.setTitle). SDL-only;
+            // the transpiler emits no call on hardware targets.
+            `static inline void ui_window_set_title(const char* title) {`,
+            `  if (__tc_display.win && title) SDL_SetWindowTitle(__tc_display.win, title);`,
+            `}`,
+            `static inline void display_fillScreen(UI_COLOR_T color) { __tc_display.fillScreen(color); }`,
+            `static inline CuttlefishDisplayTarget* display_defaultTarget() { return &__tc_display; }`,
+            `static inline int16_t display_width() { return __tc_display.width(); }`,
+            `static inline int16_t display_height() { return __tc_display.height(); }`,
+            `static int16_t __sdl_addr_x = 0;`,
+            `static int16_t __sdl_addr_y = 0;`,
+            `static int16_t __sdl_addr_w = 0;`,
+            `static int16_t __sdl_addr_h = 0;`,
+            `static uint32_t __sdl_write_pos = 0;`,
+            // Event-driven mouse state: the host event loop (NativeStrategy.
+            // hostEventLoop) writes these from SDL_MOUSEBUTTONDOWN/MOTION/BUTTONUP,
+            // and the SDL touch shim (touch_isTouched/touch_readRaw in display-
+            // profile.ts) reads them instead of polling SDL_GetMouseState every
+            // frame. Declared here so both layers see one definition.
+            `static uint8_t __sdl_mouse_down = 0;`,
+            `static int16_t __sdl_mouse_x = 0;`,
+            `static int16_t __sdl_mouse_y = 0;`,
+            `static inline void display_startWrite() {}`,
+            `static inline void display_endWrite() {}`,
+            `static inline void display_setAddrWindow(int16_t x, int16_t y, int16_t w, int16_t h) {`,
+            `  __sdl_addr_x = x; __sdl_addr_y = y; __sdl_addr_w = w; __sdl_addr_h = h;`,
+            `  __sdl_write_pos = 0;`,
+            `}`,
+            `static inline void display_writePixels(uint32_t* pixels, uint32_t count) {`,
+            `  if (!pixels || __sdl_addr_w <= 0 || __sdl_addr_h <= 0) return;`,
+            `  uint32_t max = (uint32_t)__sdl_addr_w * (uint32_t)__sdl_addr_h;`,
+            `  for (uint32_t i = 0; i < count && __sdl_write_pos < max; i++, __sdl_write_pos++) {`,
+            `    int16_t dx = (int16_t)(__sdl_addr_x + (__sdl_write_pos % (uint32_t)__sdl_addr_w));`,
+            `    int16_t dy = (int16_t)(__sdl_addr_y + (__sdl_write_pos / (uint32_t)__sdl_addr_w));`,
+            `    __tc_display.put(dx, dy, pixels[i]);`,
+            `  }`,
+            `}`,
+            `static inline CuttlefishCanvas16* display_createCanvas(int16_t w, int16_t h) { return new SdlGfxCanvas(w, h); }`,
+            `static inline CuttlefishCanvas16* display_createCanvasPsram(int16_t, int16_t) { return nullptr; }`,
+            `static inline void display_deleteCanvas(CuttlefishCanvas16* c) { delete c; }`,
+            `static inline int16_t display_canvasWidth(CuttlefishCanvas16* c) { return c->width(); }`,
+            `static inline int16_t display_canvasHeight(CuttlefishCanvas16* c) { return c->height(); }`,
+            `static inline uint32_t* display_canvasBuffer(CuttlefishCanvas16* c) { return c->buf; }`,
+            `static inline UI_COLOR_T display_canvasGetPixel(CuttlefishCanvas16* c, int16_t x, int16_t y) { return c->get(x, y); }`,
+            `static inline void display_canvasFillScreen(CuttlefishCanvas16* c, UI_COLOR_T color) { c->fillScreen(color); }`,
+            `static inline void display_canvasFillRect(CuttlefishCanvas16* c, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) { c->fillRect(x, y, w, h, color); }`,
+            ``,
+            `static inline void display_targetDrawPixel(CuttlefishDisplayTarget* t, int16_t x, int16_t y, UI_COLOR_T color) { t->drawPixel(x, y, color); }`,
+            `static inline int16_t display_targetWidth(CuttlefishDisplayTarget* t) { return t->width(); }`,
+            `static inline int16_t display_targetHeight(CuttlefishDisplayTarget* t) { return t->height(); }`,
+            `static inline void display_targetDrawRGBBitmap(CuttlefishDisplayTarget* t, int16_t x, int16_t y, const UI_COLOR_T* b, int16_t w, int16_t h) { t->drawRGBBitmap(x, y, b, w, h); }`,
+            `static inline void display_targetFillRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) { t->fillRect(x, y, w, h, color); }`,
+            `static inline void display_targetDrawFastHLine(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, UI_COLOR_T color) { t->drawFastHLine(x, y, w, color); }`,
+            `static inline void display_targetDrawFastVLine(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t h, UI_COLOR_T color) { t->drawFastVLine(x, y, h, color); }`,
+            `static inline void display_targetFillRoundRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) { t->fillRoundRect(x, y, w, h, r, color); }`,
+            `static inline void display_targetDrawRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) { t->drawRect(x, y, w, h, color); }`,
+            `static inline void display_targetDrawRoundRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) { t->drawRoundRect(x, y, w, h, r, color); }`,
+            `static inline void display_targetDrawLine(CuttlefishDisplayTarget* t, int16_t x0, int16_t y0, int16_t x1, int16_t y1, UI_COLOR_T color) { t->drawLine(x0, y0, x1, y1, color); }`,
+            `static inline void display_targetFillCircle(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t r, UI_COLOR_T color) { t->fillCircle(x, y, r, color); }`,
+            `static inline void display_targetDrawCircle(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t r, UI_COLOR_T color) { t->drawCircle(x, y, r, color); }`,
+            `static inline void display_targetSetCursor(CuttlefishDisplayTarget* t, int16_t x, int16_t y) { t->setCursor(x, y); }`,
+            `static inline void display_targetSetTextColor(CuttlefishDisplayTarget* t, UI_COLOR_T fg) { t->setTextColor(fg); }`,
+            `static inline void display_targetSetTextColorBg(CuttlefishDisplayTarget* t, UI_COLOR_T fg, UI_COLOR_T bg) { t->setTextColorBg(fg, bg); }`,
+            `static inline void display_targetSetTextSize(CuttlefishDisplayTarget* t, uint8_t s) { t->setTextSize(s); }`,
+            `static inline void display_targetSetTextWrap(CuttlefishDisplayTarget* t, bool wp) { t->setTextWrap(wp); }`,
+            `static inline void display_targetPrint(CuttlefishDisplayTarget* t, const char* s) { t->print(s); }`,
+            `// Called by the SDL event loop after each ui_tick to push the framebuffer.`,
+            `static inline void display_present() { __tc_display.present(); }`,
+        ].join("\n"),
+    };
+};
+// Full Adafruit GFX 5x7 glcdfont table (256 glyphs × 5 bytes). Kept inline so
+// the emitted C++ is self-contained and indexes glyphs exactly like preview.
+function glcdfontBytes() {
+    const lines = [];
+    for (let i = 0; i < GLCDFONT_BYTES.length; i += 16) {
+        lines.push(`  ${GLCDFONT_BYTES.slice(i, i + 16).map((b) => "0x" + b.toString(16).padStart(2, "0")).join(", ")},`);
+    }
+    return lines;
+}
+// Canonical Adafruit GFX 5x7 glcdfont. Public domain.
+// Source: Adafruit_GFX library glcdfont.c.
+const GLCDFONT_BYTES = [
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x3e, 0x5b, 0x4f, 0x5b, 0x3e, 0x3e, 0x6b, 0x4f, 0x6b, 0x3e, 0x1c,
+    0x3e, 0x7c, 0x3e, 0x1c, 0x18, 0x3c, 0x7e, 0x3c, 0x18, 0x1c, 0x57, 0x7d, 0x57, 0x1c, 0x1c, 0x5e,
+    0x7f, 0x5e, 0x1c, 0x00, 0x18, 0x3c, 0x18, 0x00, 0xff, 0xe7, 0xc3, 0xe7, 0xff, 0x00, 0x18, 0x24,
+    0x18, 0x00, 0xff, 0xe7, 0xdb, 0xe7, 0xff, 0x30, 0x48, 0x3a, 0x06, 0x0e, 0x26, 0x29, 0x79, 0x29,
+    0x26, 0x40, 0x7f, 0x05, 0x05, 0x07, 0x40, 0x7f, 0x05, 0x25, 0x3f, 0x5a, 0x3c, 0xe7, 0x3c, 0x5a,
+    0x7f, 0x3e, 0x1c, 0x1c, 0x08, 0x08, 0x1c, 0x1c, 0x3e, 0x7f, 0x14, 0x22, 0x7f, 0x22, 0x14, 0x5f,
+    0x5f, 0x00, 0x5f, 0x5f, 0x06, 0x09, 0x7f, 0x01, 0x7f, 0x00, 0x66, 0x89, 0x95, 0x6a, 0x60, 0x60,
+    0x60, 0x60, 0x60, 0x94, 0xa2, 0xff, 0xa2, 0x94, 0x08, 0x04, 0x7e, 0x04, 0x08, 0x10, 0x20, 0x7e,
+    0x20, 0x10, 0x08, 0x08, 0x2a, 0x1c, 0x08, 0x08, 0x1c, 0x2a, 0x08, 0x08, 0x1e, 0x10, 0x10, 0x10,
+    0x10, 0x0c, 0x1e, 0x0c, 0x1e, 0x0c, 0x30, 0x38, 0x3e, 0x38, 0x30, 0x06, 0x0e, 0x3e, 0x0e, 0x06,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x5f, 0x00, 0x00, 0x00, 0x07, 0x00, 0x07, 0x00, 0x14,
+    0x7f, 0x14, 0x7f, 0x14, 0x24, 0x2a, 0x7f, 0x2a, 0x12, 0x23, 0x13, 0x08, 0x64, 0x62, 0x36, 0x49,
+    0x56, 0x20, 0x50, 0x00, 0x08, 0x07, 0x03, 0x00, 0x00, 0x1c, 0x22, 0x41, 0x00, 0x00, 0x41, 0x22,
+    0x1c, 0x00, 0x2a, 0x1c, 0x7f, 0x1c, 0x2a, 0x08, 0x08, 0x3e, 0x08, 0x08, 0x00, 0x80, 0x70, 0x30,
+    0x00, 0x08, 0x08, 0x08, 0x08, 0x08, 0x00, 0x00, 0x60, 0x60, 0x00, 0x20, 0x10, 0x08, 0x04, 0x02,
+    0x3e, 0x51, 0x49, 0x45, 0x3e, 0x00, 0x42, 0x7f, 0x40, 0x00, 0x72, 0x49, 0x49, 0x49, 0x46, 0x21,
+    0x41, 0x49, 0x4d, 0x33, 0x18, 0x14, 0x12, 0x7f, 0x10, 0x27, 0x45, 0x45, 0x45, 0x39, 0x3c, 0x4a,
+    0x49, 0x49, 0x31, 0x41, 0x21, 0x11, 0x09, 0x07, 0x36, 0x49, 0x49, 0x49, 0x36, 0x46, 0x49, 0x49,
+    0x29, 0x1e, 0x00, 0x00, 0x14, 0x00, 0x00, 0x00, 0x40, 0x34, 0x00, 0x00, 0x00, 0x08, 0x14, 0x22,
+    0x41, 0x14, 0x14, 0x14, 0x14, 0x14, 0x00, 0x41, 0x22, 0x14, 0x08, 0x02, 0x01, 0x59, 0x09, 0x06,
+    0x3e, 0x41, 0x5d, 0x59, 0x4e, 0x7c, 0x12, 0x11, 0x12, 0x7c, 0x7f, 0x49, 0x49, 0x49, 0x36, 0x3e,
+    0x41, 0x41, 0x41, 0x22, 0x7f, 0x41, 0x41, 0x41, 0x3e, 0x7f, 0x49, 0x49, 0x49, 0x41, 0x7f, 0x09,
+    0x09, 0x09, 0x01, 0x3e, 0x41, 0x41, 0x51, 0x73, 0x7f, 0x08, 0x08, 0x08, 0x7f, 0x00, 0x41, 0x7f,
+    0x41, 0x00, 0x20, 0x40, 0x41, 0x3f, 0x01, 0x7f, 0x08, 0x14, 0x22, 0x41, 0x7f, 0x40, 0x40, 0x40,
+    0x40, 0x7f, 0x02, 0x1c, 0x02, 0x7f, 0x7f, 0x04, 0x08, 0x10, 0x7f, 0x3e, 0x41, 0x41, 0x41, 0x3e,
+    0x7f, 0x09, 0x09, 0x09, 0x06, 0x3e, 0x41, 0x51, 0x21, 0x5e, 0x7f, 0x09, 0x19, 0x29, 0x46, 0x26,
+    0x49, 0x49, 0x49, 0x32, 0x03, 0x01, 0x7f, 0x01, 0x03, 0x3f, 0x40, 0x40, 0x40, 0x3f, 0x1f, 0x20,
+    0x40, 0x20, 0x1f, 0x3f, 0x40, 0x38, 0x40, 0x3f, 0x63, 0x14, 0x08, 0x14, 0x63, 0x03, 0x04, 0x78,
+    0x04, 0x03, 0x61, 0x59, 0x49, 0x4d, 0x43, 0x00, 0x7f, 0x41, 0x41, 0x41, 0x02, 0x04, 0x08, 0x10,
+    0x20, 0x00, 0x41, 0x41, 0x41, 0x7f, 0x04, 0x02, 0x01, 0x02, 0x04, 0x40, 0x40, 0x40, 0x40, 0x40,
+    0x00, 0x03, 0x07, 0x08, 0x00, 0x20, 0x54, 0x54, 0x78, 0x40, 0x7f, 0x28, 0x44, 0x44, 0x38, 0x38,
+    0x44, 0x44, 0x44, 0x28, 0x38, 0x44, 0x44, 0x28, 0x7f, 0x38, 0x54, 0x54, 0x54, 0x18, 0x00, 0x08,
+    0x7e, 0x09, 0x02, 0x18, 0xa4, 0xa4, 0x9c, 0x78, 0x7f, 0x08, 0x04, 0x04, 0x78, 0x00, 0x44, 0x7d,
+    0x40, 0x00, 0x20, 0x40, 0x40, 0x3d, 0x00, 0x7f, 0x10, 0x28, 0x44, 0x00, 0x00, 0x41, 0x7f, 0x40,
+    0x00, 0x7c, 0x04, 0x78, 0x04, 0x78, 0x7c, 0x08, 0x04, 0x04, 0x78, 0x38, 0x44, 0x44, 0x44, 0x38,
+    0xfc, 0x18, 0x24, 0x24, 0x18, 0x18, 0x24, 0x24, 0x18, 0xfc, 0x7c, 0x08, 0x04, 0x04, 0x08, 0x48,
+    0x54, 0x54, 0x54, 0x24, 0x04, 0x04, 0x3f, 0x44, 0x24, 0x3c, 0x40, 0x40, 0x20, 0x7c, 0x1c, 0x20,
+    0x40, 0x20, 0x1c, 0x3c, 0x40, 0x30, 0x40, 0x3c, 0x44, 0x28, 0x10, 0x28, 0x44, 0x4c, 0x90, 0x90,
+    0x90, 0x7c, 0x44, 0x64, 0x54, 0x4c, 0x44, 0x00, 0x08, 0x36, 0x41, 0x00, 0x00, 0x00, 0x77, 0x00,
+    0x00, 0x00, 0x41, 0x36, 0x08, 0x00, 0x02, 0x01, 0x02, 0x04, 0x02, 0x3c, 0x26, 0x23, 0x26, 0x3c,
+    0x1e, 0xa1, 0xa1, 0x61, 0x12, 0x3a, 0x40, 0x40, 0x20, 0x7a, 0x38, 0x54, 0x54, 0x55, 0x59, 0x21,
+    0x55, 0x55, 0x79, 0x41, 0x22, 0x54, 0x54, 0x78, 0x42, 0x21, 0x55, 0x54, 0x78, 0x40, 0x20, 0x54,
+    0x55, 0x79, 0x40, 0x0c, 0x1e, 0x52, 0x72, 0x12, 0x39, 0x55, 0x55, 0x55, 0x59, 0x39, 0x54, 0x54,
+    0x54, 0x59, 0x39, 0x55, 0x54, 0x54, 0x58, 0x00, 0x00, 0x45, 0x7c, 0x41, 0x00, 0x02, 0x45, 0x7d,
+    0x42, 0x00, 0x01, 0x45, 0x7c, 0x40, 0x7d, 0x12, 0x11, 0x12, 0x7d, 0xf0, 0x28, 0x25, 0x28, 0xf0,
+    0x7c, 0x54, 0x55, 0x45, 0x00, 0x20, 0x54, 0x54, 0x7c, 0x54, 0x7c, 0x0a, 0x09, 0x7f, 0x49, 0x32,
+    0x49, 0x49, 0x49, 0x32, 0x3a, 0x44, 0x44, 0x44, 0x3a, 0x32, 0x4a, 0x48, 0x48, 0x30, 0x3a, 0x41,
+    0x41, 0x21, 0x7a, 0x3a, 0x42, 0x40, 0x20, 0x78, 0x00, 0x9d, 0xa0, 0xa0, 0x7d, 0x3d, 0x42, 0x42,
+    0x42, 0x3d, 0x3d, 0x40, 0x40, 0x40, 0x3d, 0x3c, 0x24, 0xff, 0x24, 0x24, 0x48, 0x7e, 0x49, 0x43,
+    0x66, 0x2b, 0x2f, 0xfc, 0x2f, 0x2b, 0xff, 0x09, 0x29, 0xf6, 0x20, 0xc0, 0x88, 0x7e, 0x09, 0x03,
+    0x20, 0x54, 0x54, 0x79, 0x41, 0x00, 0x00, 0x44, 0x7d, 0x41, 0x30, 0x48, 0x48, 0x4a, 0x32, 0x38,
+    0x40, 0x40, 0x22, 0x7a, 0x00, 0x7a, 0x0a, 0x0a, 0x72, 0x7d, 0x0d, 0x19, 0x31, 0x7d, 0x26, 0x29,
+    0x29, 0x2f, 0x28, 0x26, 0x29, 0x29, 0x29, 0x26, 0x30, 0x48, 0x4d, 0x40, 0x20, 0x38, 0x08, 0x08,
+    0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x38, 0x2f, 0x10, 0xc8, 0xac, 0xba, 0x2f, 0x10, 0x28, 0x34,
+    0xfa, 0x00, 0x00, 0x7b, 0x00, 0x00, 0x08, 0x14, 0x2a, 0x14, 0x22, 0x22, 0x14, 0x2a, 0x14, 0x08,
+    0x55, 0x00, 0x55, 0x00, 0x55, 0xaa, 0x55, 0xaa, 0x55, 0xaa, 0xff, 0x55, 0xff, 0x55, 0xff, 0x00,
+    0x00, 0x00, 0xff, 0x00, 0x10, 0x10, 0x10, 0xff, 0x00, 0x14, 0x14, 0x14, 0xff, 0x00, 0x10, 0x10,
+    0xff, 0x00, 0xff, 0x10, 0x10, 0xf0, 0x10, 0xf0, 0x14, 0x14, 0x14, 0xfc, 0x00, 0x14, 0x14, 0xf7,
+    0x00, 0xff, 0x00, 0x00, 0xff, 0x00, 0xff, 0x14, 0x14, 0xf4, 0x04, 0xfc, 0x14, 0x14, 0x17, 0x10,
+    0x1f, 0x10, 0x10, 0x1f, 0x10, 0x1f, 0x14, 0x14, 0x14, 0x1f, 0x00, 0x10, 0x10, 0x10, 0xf0, 0x00,
+    0x00, 0x00, 0x00, 0x1f, 0x10, 0x10, 0x10, 0x10, 0x1f, 0x10, 0x10, 0x10, 0x10, 0xf0, 0x10, 0x00,
+    0x00, 0x00, 0xff, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0xff, 0x10, 0x00, 0x00,
+    0x00, 0xff, 0x14, 0x00, 0x00, 0xff, 0x00, 0xff, 0x00, 0x00, 0x1f, 0x10, 0x17, 0x00, 0x00, 0xfc,
+    0x04, 0xf4, 0x14, 0x14, 0x17, 0x10, 0x17, 0x14, 0x14, 0xf4, 0x04, 0xf4, 0x00, 0x00, 0xff, 0x00,
+    0xf7, 0x14, 0x14, 0x14, 0x14, 0x14, 0x14, 0x14, 0xf7, 0x00, 0xf7, 0x14, 0x14, 0x14, 0x17, 0x14,
+    0x10, 0x10, 0x1f, 0x10, 0x1f, 0x14, 0x14, 0x14, 0xf4, 0x14, 0x10, 0x10, 0xf0, 0x10, 0xf0, 0x00,
+    0x00, 0x1f, 0x10, 0x1f, 0x00, 0x00, 0x00, 0x1f, 0x14, 0x00, 0x00, 0x00, 0xfc, 0x14, 0x00, 0x00,
+    0xf0, 0x10, 0xf0, 0x10, 0x10, 0xff, 0x10, 0xff, 0x14, 0x14, 0x14, 0xff, 0x14, 0x10, 0x10, 0x10,
+    0x1f, 0x00, 0x00, 0x00, 0x00, 0xf0, 0x10, 0xff, 0xff, 0xff, 0xff, 0xff, 0xf0, 0xf0, 0xf0, 0xf0,
+    0xf0, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f,
+    0x38, 0x44, 0x44, 0x38, 0x44, 0xfc, 0x4a, 0x4a, 0x4a, 0x34, 0x7e, 0x02, 0x02, 0x06, 0x06, 0x02,
+    0x7e, 0x02, 0x7e, 0x02, 0x63, 0x55, 0x49, 0x41, 0x63, 0x38, 0x44, 0x44, 0x3c, 0x04, 0x40, 0x7e,
+    0x20, 0x1e, 0x20, 0x06, 0x02, 0x7e, 0x02, 0x02, 0x99, 0xa5, 0xe7, 0xa5, 0x99, 0x1c, 0x2a, 0x49,
+    0x2a, 0x1c, 0x4c, 0x72, 0x01, 0x72, 0x4c, 0x30, 0x4a, 0x4d, 0x4d, 0x30, 0x30, 0x48, 0x78, 0x48,
+    0x30, 0xbc, 0x62, 0x5a, 0x46, 0x3d, 0x3e, 0x49, 0x49, 0x49, 0x00, 0x7e, 0x01, 0x01, 0x01, 0x7e,
+    0x2a, 0x2a, 0x2a, 0x2a, 0x2a, 0x44, 0x44, 0x5f, 0x44, 0x44, 0x40, 0x51, 0x4a, 0x44, 0x40, 0x40,
+    0x44, 0x4a, 0x51, 0x40, 0x00, 0x00, 0xff, 0x01, 0x03, 0xe0, 0x80, 0xff, 0x00, 0x00, 0x08, 0x08,
+    0x6b, 0x6b, 0x08, 0x36, 0x12, 0x36, 0x24, 0x36, 0x06, 0x0f, 0x09, 0x0f, 0x06, 0x00, 0x00, 0x18,
+    0x18, 0x00, 0x00, 0x00, 0x10, 0x10, 0x00, 0x30, 0x40, 0xff, 0x01, 0x01, 0x00, 0x1f, 0x01, 0x01,
+    0x1e, 0x00, 0x19, 0x1d, 0x17, 0x12, 0x00, 0x3c, 0x3c, 0x3c, 0x3c, 0x00, 0x00, 0x00, 0x00, 0x00,
+];

package/dist/api/shared/display-adapters/ssd1309.d.ts

@@ -0,0 +1,2 @@
+import type { DisplayAdapterGenerator } from "../display-adapter.js";
+export declare const ssd1309Adapter: DisplayAdapterGenerator;

package/dist/api/shared/display-adapters/ssd1309.js

@@ -0,0 +1,136 @@
+// ---------------------------------------------------------------------------
+// SSD1309 OLED display adapter — 1-bit monochrome OLED panels over I2C.
+//
+// Targets the Adafruit_SSD1306 library (which supports SSD1309 via the same
+// API). The SSD1306 is a page-buffered Adafruit_GFX subclass: draw into its
+// buffer via drawPixel/fillRect, then call display() to flush over I2C.
+// Colors are 1-bit (SSD1306_WHITE / SSD1306_BLACK). The runtime's
+// UI_NATIVE_MONO snap converts 565 → black/white at the draw choke points.
+//
+// The SSD1306 IS the backing store (its internal buffer), so this adapter
+// follows the e-ink deferred-refresh pattern: the runtime draws dirty rects
+// into the buffer, then display_partial_refresh() flushes. The SSD1306 has
+// no true partial refresh — display() flushes the full page buffer — but
+// the dirty-rect tracking still minimizes draw calls into the buffer.
+//
+// I2C wiring: SDA/SCL (Wire bus) + reset pin + I2C address (default 0x3C).
+// ---------------------------------------------------------------------------
+export const ssd1309Adapter = (display) => {
+    const w = display.width;
+    const h = display.height;
+    const reset = display._mountReset;
+    const address = display._mountAddress;
+    const rotation = display.rotation ?? 0;
+    return {
+        includes: [
+            `#define CuttlefishDisplayTarget Adafruit_GFX`,
+            `#define CuttlefishCanvas16 GFXcanvas16`,
+            `#define SSD1306_NO_SPLASH`,
+            `#include <Adafruit_GFX.h>`,
+            `#include <Adafruit_SSD1306.h>`,
+            `#include <Wire.h>`,
+        ].join("\n"),
+        // I2C constructor: Adafruit_SSD1306(width, height, &Wire, resetPin)
+        declaration: `Adafruit_SSD1306 __tc_display(${w}, ${h}, &Wire, ${reset});`,
+        functions: [
+            `// --- Display adapter: SSD1309 OLED (1-bit mono, I2C, page-buffered) ---`,
+            `static inline void display_init() {`,
+            `  // SSD1306_SWITCHCAPVCC = generate display voltage from 3.3V internally.`,
+            `  __tc_display.begin(SSD1306_SWITCHCAPVCC, 0x${address.toString(16)});`,
+            `  __tc_display.setRotation(${rotation});`,
+            `  __tc_display.clearDisplay();`,
+            `  __tc_display.display();`,
+            `}`,
+            ``,
+            `static inline void display_fillScreen(uint32_t color) {`,
+            `  __tc_display.fillScreen(color ? SSD1306_WHITE : SSD1306_BLACK);`,
+            `}`,
+            `static inline CuttlefishDisplayTarget* display_defaultTarget() { return &__tc_display; }`,
+            `static inline int16_t display_width() { return __tc_display.width(); }`,
+            `static inline int16_t display_height() { return __tc_display.height(); }`,
+            `static inline void display_startWrite() {}`,
+            `static inline void display_endWrite() {}`,
+            `static int16_t __ssd1309_addr_x = 0;`,
+            `static int16_t __ssd1309_addr_y = 0;`,
+            `static int16_t __ssd1309_addr_w = 0;`,
+            `static int16_t __ssd1309_addr_h = 0;`,
+            `static uint32_t __ssd1309_addr_cursor = 0;`,
+            `static inline void display_setAddrWindow(int16_t x, int16_t y, int16_t w, int16_t h) {`,
+            `  __ssd1309_addr_x = x;`,
+            `  __ssd1309_addr_y = y;`,
+            `  __ssd1309_addr_w = w;`,
+            `  __ssd1309_addr_h = h;`,
+            `  __ssd1309_addr_cursor = 0;`,
+            `}`,
+            `static inline void display_writePixels(UI_COLOR_T* pixels, uint32_t count) {`,
+            `  // SSD1306 is page-buffered — write into the GFX buffer via drawPixel.`,
+            `  if (__ssd1309_addr_w <= 0 || __ssd1309_addr_h <= 0) return;`,
+            `  uint32_t windowPixels = (uint32_t)__ssd1309_addr_w * (uint32_t)__ssd1309_addr_h;`,
+            `  for (uint32_t i = 0; i < count; i++) {`,
+            `    if (__ssd1309_addr_cursor >= windowPixels) break;`,
+            `    uint32_t pos = __ssd1309_addr_cursor++;`,
+            `    int16_t px = (int16_t)(__ssd1309_addr_x + (int16_t)(pos % (uint32_t)__ssd1309_addr_w));`,
+            `    int16_t py = (int16_t)(__ssd1309_addr_y + (int16_t)(pos / (uint32_t)__ssd1309_addr_w));`,
+            `    __tc_display.drawPixel(px, py, pixels[i] ? SSD1306_WHITE : SSD1306_BLACK);`,
+            `  }`,
+            `}`,
+            ``,
+            `// The SSD1306 has no true partial refresh — display() flushes the full`,
+            `// page buffer. The runtime's dirty-rect tracking still minimizes the draw`,
+            `// calls INTO the buffer (only dirty nodes are redrawn); this just publishes`,
+            `// the result. Called once per frame after the dirty-rect union is drawn.`,
+            `static inline void display_partial_refresh(int16_t x, int16_t y, int16_t w, int16_t h) {`,
+            `  (void)x; (void)y; (void)w; (void)h;`,
+            `  __tc_display.display();`,
+            `}`,
+            // ── Canvas (offscreen GFXcanvas16 for AA text / scroll compositing) ──
+            `static inline uint16_t ssd_mono(uint16_t c);`,
+            `static inline CuttlefishCanvas16* display_createCanvas(int16_t w, int16_t h) { return new GFXcanvas16(w, h); }`,
+            `static inline CuttlefishCanvas16* display_createCanvasPsram(int16_t w, int16_t h) {`,
+            `#if defined(ESP32) && defined(BOARD_HAS_PSRAM)`,
+            `  return new (ps_malloc(sizeof(GFXcanvas16))) GFXcanvas16(w, h);`,
+            `#else`,
+            `  (void)w; (void)h;`,
+            `  return nullptr;`,
+            `#endif`,
+            `}`,
+            `static inline void display_deleteCanvas(CuttlefishCanvas16* canvas) { delete canvas; }`,
+            `static inline int16_t display_canvasWidth(CuttlefishCanvas16* c) { return c->width(); }`,
+            `static inline int16_t display_canvasHeight(CuttlefishCanvas16* c) { return c->height(); }`,
+            `static inline uint16_t* display_canvasBuffer(CuttlefishCanvas16* c) { return c->getBuffer(); }`,
+            `static inline uint16_t display_canvasGetPixel(CuttlefishCanvas16* c, int16_t x, int16_t y) { return c->getPixel(x, y); }`,
+            `static inline void display_canvasFillScreen(CuttlefishCanvas16* c, UI_COLOR_T color) { c->fillScreen(ssd_mono((uint16_t)color)); }`,
+            `static inline void display_canvasFillRect(CuttlefishCanvas16* c, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) { c->fillRect(x, y, w, h, ssd_mono((uint16_t)color)); }`,
+            // ── Color conversion: runtime uses 0xffff/0x0000 (565 mono snap), but the
+            //    SSD1306's drawPixel switch only accepts 0/1/2. Convert any nonzero to 1. ──
+            `static inline uint16_t ssd_mono(uint16_t c) { return c ? SSD1306_WHITE : SSD1306_BLACK; }`,
+            // ── Target-polymorphic draw (panel + canvas share CuttlefishDisplayTarget*) ──
+            `static inline void display_targetDrawPixel(CuttlefishDisplayTarget* t, int16_t x, int16_t y, UI_COLOR_T color) { t->drawPixel(x, y, ssd_mono((uint16_t)color)); }`,
+            `static inline int16_t display_targetWidth(CuttlefishDisplayTarget* t) { return t->width(); }`,
+            `static inline int16_t display_targetHeight(CuttlefishDisplayTarget* t) { return t->height(); }`,
+            `static inline void display_targetDrawRGBBitmap(CuttlefishDisplayTarget* t, int16_t x, int16_t y, const UI_COLOR_T* b, int16_t w, int16_t h) {`,
+            `  if (!b || w <= 0 || h <= 0) return;`,
+            `  for (int16_t yy = 0; yy < h; yy++) {`,
+            `    for (int16_t xx = 0; xx < w; xx++) {`,
+            `      t->drawPixel((int16_t)(x + xx), (int16_t)(y + yy), ssd_mono((uint16_t)b[(int32_t)yy * w + xx]));`,
+            `    }`,
+            `  }`,
+            `}`,
+            `static inline void display_targetFillRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) { t->fillRect(x, y, w, h, ssd_mono((uint16_t)color)); }`,
+            `static inline void display_targetDrawFastHLine(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, UI_COLOR_T color) { t->drawFastHLine(x, y, w, ssd_mono((uint16_t)color)); }`,
+            `static inline void display_targetDrawFastVLine(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t h, UI_COLOR_T color) { t->drawFastVLine(x, y, h, ssd_mono((uint16_t)color)); }`,
+            `static inline void display_targetFillRoundRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) { t->fillRoundRect(x, y, w, h, r, ssd_mono((uint16_t)color)); }`,
+            `static inline void display_targetDrawRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) { t->drawRect(x, y, w, h, ssd_mono((uint16_t)color)); }`,
+            `static inline void display_targetDrawRoundRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) { t->drawRoundRect(x, y, w, h, r, ssd_mono((uint16_t)color)); }`,
+            `static inline void display_targetDrawLine(CuttlefishDisplayTarget* t, int16_t x0, int16_t y0, int16_t x1, int16_t y1, UI_COLOR_T color) { t->drawLine(x0, y0, x1, y1, ssd_mono((uint16_t)color)); }`,
+            `static inline void display_targetFillCircle(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t r, UI_COLOR_T color) { t->fillCircle(x, y, r, ssd_mono((uint16_t)color)); }`,
+            `static inline void display_targetDrawCircle(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t r, UI_COLOR_T color) { t->drawCircle(x, y, r, ssd_mono((uint16_t)color)); }`,
+            `static inline void display_targetSetCursor(CuttlefishDisplayTarget* t, int16_t x, int16_t y) { t->setCursor(x, y); }`,
+            `static inline void display_targetSetTextColor(CuttlefishDisplayTarget* t, UI_COLOR_T fg) { t->setTextColor(ssd_mono((uint16_t)fg)); }`,
+            `static inline void display_targetSetTextColorBg(CuttlefishDisplayTarget* t, UI_COLOR_T fg, UI_COLOR_T bg) { t->setTextColor(ssd_mono((uint16_t)fg), ssd_mono((uint16_t)bg)); }`,
+            `static inline void display_targetSetTextSize(CuttlefishDisplayTarget* t, uint8_t s) { t->setTextSize(s); }`,
+            `static inline void display_targetSetTextWrap(CuttlefishDisplayTarget* t, bool w) { t->setTextWrap(w); }`,
+            `static inline void display_targetPrint(CuttlefishDisplayTarget* t, const char* s) { t->print(s); }`,
+        ].join("\n"),
+    };
+};

package/dist/api/shared/display-adapters/st7796.d.ts

@@ -0,0 +1,2 @@
+import type { DisplayAdapterGenerator } from "../display-adapter.js";
+export declare const st7796Adapter: DisplayAdapterGenerator;