@typecad/framework-zephyr 1.0.0-alpha.18 → 1.0.0-alpha.19

package/src/display/ui-adapter-native.ts

@@ -0,0 +1,304 @@
+// ---------------------------------------------------------------------------
+// Zephyr UI display adapter — 'zephyr-display' transport.
+//
+// Emits the same display_ / display_target_ / display_canvas_ surface the UI
+// runtime expects (see ui-adapter.ts), but reaches the panel through Zephyr's
+// display API: display_write() with a buffer descriptor on the DT display
+// device (the overlay's display0 node under the mipi-dbi-spi bridge), with
+// display_get_capabilities() consulted for the panel's pixel format. An
+// in-tree panel driver (e.g. ilitek,ili9341 with CONFIG_ILI9341) owns the
+// init sequence, rotation, and wire format — this adapter carries no panel
+// registers at all.
+//
+// Why this transport exists alongside 'direct-spi': the direct path is the
+// escape hatch for panels the in-tree drivers cannot init (clone ST7796S —
+// the generic mipi-dbi-spi bridge deasserts CS between the command byte and
+// its parameters, scrambling those panels). Standard ILI9341-class SPI
+// modules tolerate per-transaction CS (upstream Zephyr boards wire them this
+// way), so they can ride the in-tree driver and drop the per-controller
+// emitted init tables. Choose per profile via ZephyrDisplayProfile.transport;
+// flip a profile here only after hardware verification on a rig.
+//
+// display_write() is a dirty-rect API — the descriptor's x/y/width/height
+// become the controller address window — so the UI engine's
+// setAddrWindow+writePixels pairs map onto it directly. Batching notes:
+// display_write calls are atomic per call (the mipi-dbi layer serializes on a
+// per-device mutex), so startWrite/endWrite are no-ops; solid fills tile a
+// reused block buffer into multi-row display_write chunks, the same
+// fewer/larger-transfers lesson the direct path learned (~40 instead of ~320
+// writes on a full 480x320 clear).
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+//
+// AGENTS.md rendering guardrails honored: scratch buffers are static and
+// reused (no per-frame heap allocation); fills are block-buffered.
+// ---------------------------------------------------------------------------
+
+import type { DisplayAdapterCode } from "@typecad/cuttlefish/api/shared";
+import type { ZephyrDisplayProfile } from "./profiles.js";
+import { dbiHostFor, displayFactsLine } from "./profiles.js";
+import { localHoldCsDbiHost } from "./mipi-dbi-host.js";
+import { CANVAS_LIFECYCLE_SECTION, TARGET_FORWARDERS_SECTION, profileMarkerLine } from "./ui-adapter-shared.js";
+
+/**
+ * Build the display-API UI adapter for a profile. The profile's dtLabel must
+ * name a display node an in-tree driver binds (the overlay generates it; the
+ * Kconfig layer enables the driver symbol for the profile's controller).
+ * Profiles whose dbiHost is 'local-hold-cs' additionally emit an app-local
+ * CS-holding mipi-dbi host the panel driver sits on (see mipi-dbi-host.ts).
+ */
+export function zephyrDisplayApiAdapter(profile: ZephyrDisplayProfile): DisplayAdapterCode {
+  const w = profile.width;
+  const h = profile.height;
+  const maxDim = Math.max(w, h);
+  const dtLabel = profile.dtLabel;
+  const backlightAlias = profile.backlight;
+  const rbSwap = profile.channelSwapRb === true;
+  const nativeW = profile.nativeWidth ?? w;
+  const nativeH = profile.nativeHeight ?? h;
+  const host = dbiHostFor(profile) === 'local-hold-cs' ? localHoldCsDbiHost(profile) : undefined;
+
+  const includes = [
+    `// --- Zephyr UI display adapter (${profile.driver}, zephyr-display transport) ---`,
+    profileMarkerLine(profile.driver),
+    displayFactsLine(profile),
+    `// Native CuttlefishGFX path: do NOT #define CuttlefishCanvas16 so the`,
+    `// runtime header emits the in-tree CuttlefishGFX/CuttlefishCanvas16 class.`,
+    `#define CuttlefishDisplayTarget CuttlefishGFX`,
+    `#include <zephyr/kernel.h>`,
+    `#include <zephyr/drivers/display.h>`,
+    `#include <zephyr/drivers/gpio.h>`,
+    ...(host ? host.includes : []),
+  ].join("\n");
+
+  const declaration = [
+    `// CUTTLEFISH_DISPLAY_BEGIN`,
+    `// The panel device: the overlay's display0 node, bound by an in-tree panel`,
+    `// driver (CONFIG enabled for the profile's controller). Compile-time`,
+    `// constant — DEVICE_DT_GET requires the driver to exist at build time,`,
+    `// which the Kconfig layer guarantees for this transport.`,
+    `static const struct device* __tc_zd_dev = DEVICE_DT_GET(DT_NODELABEL(${dtLabel}));`,
+    `// Panel facts from display_get_capabilities, read once in display_init.`,
+    `static struct display_capabilities __tc_zd_caps;`,
+    `// Zephyr pixel formats carry byte-order semantics: PIXEL_FORMAT_RGB_565`,
+    `// is little-endian (Red in byte 1, Blue in byte 0) — exactly the memory`,
+    `// layout of the UI's uint16_t rgb565 words on little-endian targets — and`,
+    `// PIXEL_FORMAT_RGB_565X is the byte-swapped variant. Clone panels with`,
+    `// crossed 16-bit channel routing (verified ST7796S quirk) additionally`,
+    `// need an R/B channel swap. __tc_zd_fix_pixel applies the panel's fixup`,
+    `// chain before pixels reach display_write.`,
+    `static bool __tc_zd_swap = false;`,
+    `static const bool __tc_zd_rb = ${rbSwap};`,
+    `// Multi-row block buffer for solid fills AND the byte-swap scratch for`,
+    `// 565X pixel streams (8 rows of maxDim px, rgb565 — fillRect and`,
+    `// writePixels never interleave mid-call, so one buffer serves both).`,
+    `// fillRect tiles it once with the color, then delivers the rect in a`,
+    `// few large display_write calls instead of one per row — the same`,
+    `// per-call-overhead lesson as the direct transport. Reused, not per-frame`,
+    `// (AGENTS.md: no per-frame heap allocation).`,
+    `#define __TC_FILL_ROWS 8`,
+    `static uint16_t __tc_zd_block[${maxDim} * __TC_FILL_ROWS];`,
+    `// Stashed address window from the last setAddrWindow call. The runtime`,
+    `// calls setAddrWindow + writePixels as a matched pair, so we stash the rect`,
+    `// here and consume it in writePixels.`,
+    `static int16_t __tc_aw_x = 0;`,
+    `static int16_t __tc_aw_y = 0;`,
+    `static int16_t __tc_aw_w = ${w};`,
+    `static int16_t __tc_aw_h = ${h};`,
+    `// CUTTLEFISH_DISPLAY_END`,
+  ].join("\n");
+
+  // Backlight: same DT-alias drive as the direct transport (the overlay emits
+  // the gpio-leds node + alias only when a backlight GPIO is configured).
+  const blInit = backlightAlias
+    ? `#if DT_HAS_ALIAS(${backlightAlias})\n    const struct gpio_dt_spec __bl = GPIO_DT_SPEC_GET(DT_ALIAS(${backlightAlias}), gpios);\n    if (device_is_ready(__bl.port)) { gpio_pin_configure_dt(&__bl, GPIO_OUTPUT_ACTIVE); }\n#endif`
+    : '';
+
+  const functions = `${host ? host.functions : ''}
+// ── display-API transport ───────────────────────────────────────────────
+// Every panel write is one display_write() carrying its own address window
+// (the descriptor's x/y/width/height) — no CASET/RASET bookkeeping here. The
+// in-tree driver beneath the device owns init, rotation, and the wire format.
+
+static void __tc_zd_write_rect(int16_t x, int16_t y, int16_t rw, int16_t rows,
+                               const uint16_t* px) {
+  if (rw <= 0 || rows <= 0) return;
+  struct display_buffer_descriptor __desc = {};
+  __desc.width = static_cast<uint16_t>(rw);
+  __desc.height = static_cast<uint16_t>(rows);
+  __desc.pitch = static_cast<uint16_t>(rw);
+  __desc.buf_size = static_cast<size_t>(rw) * static_cast<size_t>(rows) * 2U;
+  (void)display_write(__tc_zd_dev, static_cast<uint16_t>(x), static_cast<uint16_t>(y),
+                      &__desc, px);
+}
+
+// The panel's pack-time pixel fixup chain: R/B channel swap (clone panels
+// whose 16-bit routing is crossed — lossless, verified equivalent to the
+// direct transport's 18-bit mode), then byte swap when the panel reports
+// RGB565X. No-op for well-behaved panels on little-endian targets.
+static inline uint16_t __tc_zd_fix_pixel(uint16_t c) {
+  if (__tc_zd_rb) {
+    c = static_cast<uint16_t>(((c & 0x1Fu) << 11) | ((c >> 11) & 0x1Fu) | (c & 0x07E0u));
+  }
+  if (__tc_zd_swap) {
+    c = static_cast<uint16_t>((c >> 8) | ((c & 0xFFu) << 8));
+  }
+  return c;
+}
+
+// Fix a pixel run into the block scratch (passthrough when the panel needs
+// no fixup — the common case). count ≤ maxDim*__TC_FILL_ROWS — the largest
+// call is a full writePixels batch.
+static const uint16_t* __tc_zd_fixup_run(const uint16_t* px, uint32_t count) {
+  if (!__tc_zd_rb && !__tc_zd_swap) return px;
+  for (uint32_t i = 0; i < count; i++) {
+    __tc_zd_block[i] = __tc_zd_fix_pixel(px[i]);
+  }
+  return __tc_zd_block;
+}
+
+// ── Panel-ops consumed by CuttlefishGFX ─────────────────────────────────
+// startWrite/endWrite are no-ops: display_write is atomic per call (the
+// mipi-dbi layer serializes on a per-device mutex), so there is no CS batch
+// to bracket. The depth-counter concept from the direct transport does not
+// apply.
+static void __tc_op_startWrite(void* /*ctx*/) { }
+static void __tc_op_endWrite(void* /*ctx*/) { }
+
+// Stash the target rect. The runtime always follows this with writePixels
+// delivering (w*h) pixels for this rect, OR fillRect/writePixel which ignore
+// the stash.
+static void __tc_op_setAddrWindow(void* /*ctx*/, int16_t x, int16_t y, int16_t winW, int16_t winH) {
+  __tc_aw_x = x; __tc_aw_y = y; __tc_aw_w = winW; __tc_aw_h = winH;
+}
+
+// Push the stashed rect's worth of rgb565 pixels, delivered in multi-row
+// display_write chunks (≤ __TC_FILL_ROWS rows per call) so a canvas push
+// stays a handful of calls instead of one per row. A trailing partial row
+// (count not a multiple of the window width) goes out as its own 1-row rect.
+static void __tc_op_writePixels(void* /*ctx*/, const uint16_t* px, uint32_t n) {
+  if (n == 0U || __tc_aw_w <= 0) return;
+  const uint32_t __full = static_cast<uint32_t>(__tc_aw_w);
+  uint32_t __rows = n / __full;
+  int16_t __row = 0;
+  const uint16_t* __p = px;
+  while (__rows > 0U) {
+    uint32_t __batch = (__rows > static_cast<uint32_t>(__TC_FILL_ROWS))
+        ? static_cast<uint32_t>(__TC_FILL_ROWS) : __rows;
+    __tc_zd_write_rect(__tc_aw_x, static_cast<int16_t>(__tc_aw_y + __row), __tc_aw_w,
+                       static_cast<int16_t>(__batch),
+                       __tc_zd_fixup_run(__p, __full * __batch));
+    __p += __full * __batch;
+    __rows -= __batch;
+    __row = static_cast<int16_t>(__row + __batch);
+  }
+  const uint32_t __rem = n % __full;
+  if (__rem > 0U) {
+    __tc_zd_write_rect(__tc_aw_x, static_cast<int16_t>(__tc_aw_y + __row),
+                       static_cast<int16_t>(__rem), 1, __tc_zd_fixup_run(__p, __rem));
+  }
+}
+
+// Single pixel: one 1x1 write.
+static void __tc_op_writePixel(void* /*ctx*/, int16_t x, int16_t y, uint16_t c) {
+  uint16_t __buf[1];
+  __buf[0] = __tc_zd_fix_pixel(c);
+  __tc_zd_write_rect(x, y, 1, 1, __buf);
+}
+
+// Fill a rect with a solid color: tile the block buffer with the color, then
+// deliver the rect in multi-row display_write chunks.
+static void __tc_op_fillRect(void* /*ctx*/, int16_t x, int16_t y, int16_t rw, int16_t rh, uint16_t c) {
+  if (rw <= 0 || rh <= 0) return;
+  const uint16_t __word = __tc_zd_fix_pixel(c);
+  for (int16_t r = 0; r < __TC_FILL_ROWS; r++) {
+    for (int16_t i = 0; i < rw; i++) {
+      __tc_zd_block[static_cast<uint32_t>(r) * static_cast<uint32_t>(rw) + static_cast<uint32_t>(i)] = __word;
+    }
+  }
+  int16_t remaining = rh;
+  int16_t yy = y;
+  while (remaining > 0) {
+    int16_t chunk = (remaining > __TC_FILL_ROWS) ? __TC_FILL_ROWS : remaining;
+    __tc_zd_write_rect(x, yy, rw, chunk, __tc_zd_block);
+    remaining -= chunk;
+    yy = static_cast<int16_t>(yy + chunk);
+  }
+}
+
+// Width/height are the profile's compile-time effective dimensions — the
+// CuttlefishGFX global below is constructed before main() runs, so it cannot
+// wait for display_get_capabilities. display_init cross-checks the caps
+// against these and reports a mismatch (a wiring/binding problem worth
+// surfacing, not silently rendering at the wrong resolution).
+static int16_t __tc_op_width(void* /*ctx*/) { return ${w}; }
+static int16_t __tc_op_height(void* /*ctx*/) { return ${h}; }
+
+// flush is nullptr — immediate-mode panel (TFT); the dirty loop's writes are
+// already on the glass.
+struct CuttlefishPanelOps;
+extern const CuttlefishPanelOps __tc_display_ops;
+
+const CuttlefishPanelOps __tc_display_ops = {
+  __tc_op_startWrite,
+  __tc_op_endWrite,
+  __tc_op_setAddrWindow,
+  __tc_op_writePixels,
+  __tc_op_writePixel,
+  __tc_op_fillRect,
+  __tc_op_width,
+  __tc_op_height,
+  nullptr,  // flush — immediate-mode panel
+};
+
+// The live display target: a CuttlefishGFX driven by the panel-ops vtable.
+CuttlefishGFX __tc_display(&__tc_display_ops, nullptr);
+
+// ── display_init (called from setup) ────────────────────────────────────
+
+static inline void display_init() {
+  printk("TC_DISPLAY: display-API transport (${dtLabel})\\n");
+${blInit}
+  if (!device_is_ready(__tc_zd_dev)) {
+    printk("TC_DISPLAY: device not ready — is the panel driver enabled?\\n");
+    return;
+  }
+  display_get_capabilities(__tc_zd_dev, &__tc_zd_caps);
+  __tc_zd_swap = (__tc_zd_caps.current_pixel_format == PIXEL_FORMAT_RGB_565X);
+  if (__tc_zd_caps.current_pixel_format != PIXEL_FORMAT_RGB_565
+      && __tc_zd_caps.current_pixel_format != PIXEL_FORMAT_RGB_565X) {
+    printk("TC_DISPLAY: unexpected pixel format %u (expected RGB565) — rendering best-effort\\n",
+           static_cast<unsigned int>(__tc_zd_caps.current_pixel_format));
+  }
+  if (__tc_zd_caps.x_resolution != static_cast<uint16_t>(${nativeW})
+      || __tc_zd_caps.y_resolution != static_cast<uint16_t>(${nativeH})) {
+    printk("TC_DISPLAY: panel reports %ux%u, DT node carries ${nativeW}x${nativeH} — check the display node geometry\\n",
+           static_cast<unsigned int>(__tc_zd_caps.x_resolution),
+           static_cast<unsigned int>(__tc_zd_caps.y_resolution));
+  }
+  (void)display_blanking_off(__tc_zd_dev);
+  __tc_op_fillRect(nullptr, 0, 0, ${w}, ${h}, 0x0000);
+  printk("TC_DISPLAY: display-API init done (RGB565, black fill)\\n");
+}
+
+static inline void display_fillScreen(UI_COLOR_T color) {
+  __tc_op_fillRect(nullptr, 0, 0, ${w}, ${h}, static_cast<uint16_t>(color));
+}
+static inline CuttlefishDisplayTarget* display_defaultTarget() { return &__tc_display; }
+static inline int16_t display_width() { return ${w}; }
+static inline int16_t display_height() { return ${h}; }
+
+static inline void display_startWrite() { }
+static inline void display_endWrite() { }
+static inline void display_setAddrWindow(int16_t x, int16_t y, int16_t winW, int16_t winH) {
+  __tc_op_setAddrWindow(nullptr, x, y, winW, winH);
+}
+static inline void display_writePixels(const UI_COLOR_T* pixels, uint32_t count) {
+  uint16_t* px = const_cast<uint16_t*>(static_cast<const uint16_t*>(pixels));
+  __tc_op_writePixels(nullptr, px, count);
+}
+${CANVAS_LIFECYCLE_SECTION}${TARGET_FORWARDERS_SECTION}`;
+
+  return { includes, declaration, functions };
+}

package/src/display/ui-adapter-shared.ts

@@ -0,0 +1,125 @@
+// ---------------------------------------------------------------------------
+// Shared C++ sections for the Zephyr UI display adapters.
+//
+// The canvas lifecycle + target-polymorphic sections of the emitted adapter
+// are transport-independent (they operate on CuttlefishCanvas16 /
+// CuttlefishDisplayTarget and never touch the panel), so both transports
+// (direct-spi in ui-adapter.ts, zephyr-display in ui-adapter-native.ts)
+// emit them verbatim from this module. Keeping one copy prevents the two
+// transports from drifting apart.
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+
+/** Offscreen canvas lifecycle + accessors (malloc + placement-new; PSRAM via
+ *  Zephyr's shared multi-heap when BOARD_HAS_PSRAM). */
+export const CANVAS_LIFECYCLE_SECTION = `
+// ── Canvas lifecycle + accessors (offscreen rgb565 compositing) ──────────
+// Allocate the canvas object via malloc + placement-new (not operator new).
+// Under CONFIG_REQUIRES_FULL_LIBCPP without CONFIG_CPP_EXCEPTIONS, operator new
+// throws std::bad_alloc on OOM and the nothrow wrapper's internal catch cannot
+// unwind (no EH runtime) → std::terminate → abort. malloc returns NULL on
+// failure with no exception path; placement-new then constructs the object in
+// place (vtable included). display_deleteCanvas mirrors with an explicit dtor
+// + free. The runtime's callers already null-check the return, so an OOM
+// degrades gracefully instead of aborting.
+static inline CuttlefishCanvas16* display_createCanvas(int16_t cw, int16_t ch) {
+  void* mem = malloc(sizeof(CuttlefishCanvas16));
+  if (!mem) return nullptr;
+  return new (mem) CuttlefishCanvas16(cw, ch);
+}
+// psramFound() shim: the Arduino ESP32 core provides this, but Zephyr does not.
+// Under BOARD_HAS_PSRAM the ESP heap serves PSRAM, so report it as present. The
+// runtime's ui_create_canvas_best calls this under #if defined(BOARD_HAS_PSRAM).
+#if defined(BOARD_HAS_PSRAM) && !defined(psramFound)
+#include <zephyr/multi_heap/shared_multi_heap.h>
+static inline bool psramFound() {
+  // Compile-time truth: if BOARD_HAS_PSRAM is defined, the build targets a
+  // PSRAM board with CONFIG_ESP_SPIRAM enabled (the framework emits both).
+  return true;
+}
+// Allocate from PSRAM via Zephyr's shared multi-heap (the ESP32 SoC code
+// registers PSRAM as an SMH_REG_ATTR_EXTERNAL region at boot).
+static inline void* ui_psram_malloc(size_t bytes) {
+  return shared_multi_heap_alloc(SMH_REG_ATTR_EXTERNAL, bytes);
+}
+#endif
+static inline CuttlefishCanvas16* display_createCanvasPsram(int16_t cw, int16_t ch) {
+  // Allocate the pixel buffer in PSRAM (large: w*h*2 bytes) and the small
+  // canvas object in SRAM. The canvas takes ownership of the PSRAM buffer and
+  // frees it via free() in its dtor (the SMH allocator's free is compatible
+  // with the standard k_free/free path). Returns nullptr if PSRAM isn't
+  // available or the allocation fails — ui_create_canvas_best falls back.
+#if defined(BOARD_HAS_PSRAM)
+  if ((cw > 0) && (ch > 0)) {
+    size_t bytes = static_cast<size_t>(cw) * static_cast<size_t>(ch) * sizeof(uint16_t);
+    uint16_t* psramBuf = static_cast<uint16_t*>(ui_psram_malloc(bytes));
+    if (psramBuf) {
+      void* mem = malloc(sizeof(CuttlefishCanvas16));
+      if (mem) {
+        return new (mem) CuttlefishCanvas16(cw, ch, psramBuf, 1);
+      }
+      free(psramBuf);
+    }
+  }
+#else
+  (void)cw; (void)ch;
+#endif
+  return nullptr;
+}
+static inline void display_deleteCanvas(CuttlefishCanvas16* canvas) {
+  if (!canvas) return;
+  canvas->~CuttlefishCanvas16();
+  free(canvas);
+}
+static inline int16_t display_canvasWidth(CuttlefishCanvas16* c) { return c->width(); }
+static inline int16_t display_canvasHeight(CuttlefishCanvas16* c) { return c->height(); }
+// Canvas buffers are addressed in UI_COLOR_T units by every runtime caller;
+// the underlying CuttlefishCanvas16 storage is 16-bit (the 565/mono world the
+// canvas machinery was built for). Gray8/full-frame targets never allocate
+// canvases, so the reinterpret never dereferences on those builds.
+static inline UI_COLOR_T* display_canvasBuffer(CuttlefishCanvas16* c) {
+  return reinterpret_cast<UI_COLOR_T*>(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(static_cast<uint16_t>(color)); }
+static inline void display_canvasFillRect(CuttlefishCanvas16* c, int16_t x, int16_t y, int16_t cw, int16_t ch, UI_COLOR_T color) {
+  c->fillRect(x, y, cw, ch, static_cast<uint16_t>(color));
+}
+`;
+
+/** Target-polymorphic draw passthroughs (panel or canvas via
+ *  CuttlefishDisplayTarget*). Pure virtual dispatch on the target object. */
+export const TARGET_FORWARDERS_SECTION = `
+// ── Target-polymorphic draw (panel or canvas via CuttlefishDisplayTarget*) ─
+static inline void display_targetDrawPixel(CuttlefishDisplayTarget* t, int16_t x, int16_t y, UI_COLOR_T color) { t->drawPixel(x, y, static_cast<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* bitmap, int16_t bw, int16_t bh) {
+  t->drawRGBBitmap(x, y, reinterpret_cast<const uint16_t*>(bitmap), bw, bh);
+}
+static inline void display_targetFillRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, int16_t bh, UI_COLOR_T color) { t->fillRect(x, y, bw, bh, static_cast<uint16_t>(color)); }
+static inline void display_targetDrawFastHLine(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, UI_COLOR_T color) { t->drawFastHLine(x, y, bw, static_cast<uint16_t>(color)); }
+static inline void display_targetDrawFastVLine(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bh, UI_COLOR_T color) { t->drawFastVLine(x, y, bh, static_cast<uint16_t>(color)); }
+static inline void display_targetFillRoundRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, int16_t bh, int16_t r, UI_COLOR_T color) { t->fillRoundRect(x, y, bw, bh, r, static_cast<uint16_t>(color)); }
+static inline void display_targetDrawRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, int16_t bh, UI_COLOR_T color) { t->drawRect(x, y, bw, bh, static_cast<uint16_t>(color)); }
+static inline void display_targetDrawRoundRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, int16_t bh, int16_t r, UI_COLOR_T color) { t->drawRoundRect(x, y, bw, bh, r, static_cast<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, static_cast<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, static_cast<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, static_cast<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(static_cast<uint16_t>(fg)); }
+static inline void display_targetSetTextColorBg(CuttlefishDisplayTarget* t, UI_COLOR_T fg, UI_COLOR_T bg) { t->setTextColor(static_cast<uint16_t>(fg), static_cast<uint16_t>(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); }
+`;
+
+/** The marker line every adapter stamps into its includes so the toolchain
+ *  can recover the emitting profile. Pairs with displayFactsLine() from
+ *  profiles.ts, which adapters emit alongside it (the facts line carries
+ *  synthesized, compatible-driven profiles too). */
+export function profileMarkerLine(driver: string): string {
+  return `// typecad-display-profile: ${driver}`;
+}

package/src/display/ui-adapter.ts

@@ -33,8 +33,13 @@
 // ---------------------------------------------------------------------------
 
 import type { DisplayAdapterCode, DisplayAdapterGenerator } from "@typecad/cuttlefish/api/shared";
-import { ZEPHYR_DISPLAY_PROFILES, panelControllerFor } from "./profiles.js";
+import { ZEPHYR_DISPLAY_PROFILES, panelControllerFor, transportFor, synthesizeZephyrProfile, displayFactsLine } from "./profiles.js";
 import type { ZephyrDisplayProfile } from "./profiles.js";
+import { CANVAS_LIFECYCLE_SECTION, TARGET_FORWARDERS_SECTION, profileMarkerLine } from "./ui-adapter-shared.js";
+import { zephyrDisplayApiAdapter } from "./ui-adapter-native.js";
+import { zephyrMonoDisplayAdapter } from "./ui-adapter-mono.js";
+import { zephyrGrayDisplayAdapter } from "./ui-adapter-gray.js";
+import { zephyrEinkDisplayAdapter } from "./ui-adapter-eink.js";
 
 /**
  * Build the Zephyr UI display adapter for a profile. Emits the full
@@ -84,6 +89,8 @@ export function zephyrUiDisplayAdapter(
 
   const includes = [
     `// --- Zephyr UI display adapter (${profile.driver}) ---`,
+    profileMarkerLine(profile.driver),
+    displayFactsLine(profile),
     `// Native CuttlefishGFX path: do NOT #define CuttlefishCanvas16 so the`,
     `// runtime header emits the in-tree CuttlefishGFX/CuttlefishCanvas16 class.`,
     `#define CuttlefishDisplayTarget CuttlefishGFX`,
@@ -661,100 +668,11 @@ static inline void display_endWrite() { __tc_op_endWrite(nullptr); }
 static inline void display_setAddrWindow(int16_t x, int16_t y, int16_t winW, int16_t winH) {
   __tc_op_setAddrWindow(nullptr, x, y, winW, winH);
 }
-static inline void display_writePixels(uint16_t* pixels, uint32_t count) {
-  __tc_op_writePixels(nullptr, pixels, count);
+static inline void display_writePixels(const UI_COLOR_T* pixels, uint32_t count) {
+  uint16_t* px = const_cast<uint16_t*>(static_cast<const uint16_t*>(pixels));
+  __tc_op_writePixels(nullptr, px, count);
 }
-
-// ── Canvas lifecycle + accessors (offscreen rgb565 compositing) ──────────
-// Allocate the canvas object via malloc + placement-new (not operator new).
-// Under CONFIG_REQUIRES_FULL_LIBCPP without CONFIG_CPP_EXCEPTIONS, operator new
-// throws std::bad_alloc on OOM and the nothrow wrapper's internal catch cannot
-// unwind (no EH runtime) → std::terminate → abort. malloc returns NULL on
-// failure with no exception path; placement-new then constructs the object in
-// place (vtable included). display_deleteCanvas mirrors with an explicit dtor
-// + free. The runtime's callers already null-check the return, so an OOM
-// degrades gracefully instead of aborting.
-static inline CuttlefishCanvas16* display_createCanvas(int16_t cw, int16_t ch) {
-  void* mem = malloc(sizeof(CuttlefishCanvas16));
-  if (!mem) return nullptr;
-  return new (mem) CuttlefishCanvas16(cw, ch);
-}
-// psramFound() shim: the Arduino ESP32 core provides this, but Zephyr does not.
-// Under BOARD_HAS_PSRAM the ESP heap serves PSRAM, so report it as present. The
-// runtime's ui_create_canvas_best calls this under #if defined(BOARD_HAS_PSRAM).
-#if defined(BOARD_HAS_PSRAM) && !defined(psramFound)
-#include <zephyr/multi_heap/shared_multi_heap.h>
-static inline bool psramFound() {
-  // Compile-time truth: if BOARD_HAS_PSRAM is defined, the build targets a
-  // PSRAM board with CONFIG_ESP_SPIRAM enabled (the framework emits both).
-  return true;
-}
-// Allocate from PSRAM via Zephyr's shared multi-heap (the ESP32 SoC code
-// registers PSRAM as an SMH_REG_ATTR_EXTERNAL region at boot).
-static inline void* ui_psram_malloc(size_t bytes) {
-  return shared_multi_heap_alloc(SMH_REG_ATTR_EXTERNAL, bytes);
-}
-#endif
-static inline CuttlefishCanvas16* display_createCanvasPsram(int16_t cw, int16_t ch) {
-  // Allocate the pixel buffer in PSRAM (large: w*h*2 bytes) and the small
-  // canvas object in SRAM. The canvas takes ownership of the PSRAM buffer and
-  // frees it via free() in its dtor (the SMH allocator's free is compatible
-  // with the standard k_free/free path). Returns nullptr if PSRAM isn't
-  // available or the allocation fails — ui_create_canvas_best falls back.
-#if defined(BOARD_HAS_PSRAM)
-  if ((cw > 0) && (ch > 0)) {
-    size_t bytes = static_cast<size_t>(cw) * static_cast<size_t>(ch) * sizeof(uint16_t);
-    uint16_t* psramBuf = static_cast<uint16_t*>(ui_psram_malloc(bytes));
-    if (psramBuf) {
-      void* mem = malloc(sizeof(CuttlefishCanvas16));
-      if (mem) {
-        return new (mem) CuttlefishCanvas16(cw, ch, psramBuf, 1);
-      }
-      free(psramBuf);
-    }
-  }
-#else
-  (void)cw; (void)ch;
-#endif
-  return nullptr;
-}
-static inline void display_deleteCanvas(CuttlefishCanvas16* canvas) {
-  if (!canvas) return;
-  canvas->~CuttlefishCanvas16();
-  free(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(static_cast<uint16_t>(color)); }
-static inline void display_canvasFillRect(CuttlefishCanvas16* c, int16_t x, int16_t y, int16_t cw, int16_t ch, UI_COLOR_T color) {
-  c->fillRect(x, y, cw, ch, static_cast<uint16_t>(color));
-}
-
-// ── Target-polymorphic draw (panel or canvas via CuttlefishDisplayTarget*) ─
-static inline void display_targetDrawPixel(CuttlefishDisplayTarget* t, int16_t x, int16_t y, UI_COLOR_T color) { t->drawPixel(x, y, static_cast<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 uint16_t* bitmap, int16_t bw, int16_t bh) {
-  t->drawRGBBitmap(x, y, bitmap, bw, bh);
-}
-static inline void display_targetFillRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, int16_t bh, UI_COLOR_T color) { t->fillRect(x, y, bw, bh, static_cast<uint16_t>(color)); }
-static inline void display_targetDrawFastHLine(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, UI_COLOR_T color) { t->drawFastHLine(x, y, bw, static_cast<uint16_t>(color)); }
-static inline void display_targetDrawFastVLine(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bh, UI_COLOR_T color) { t->drawFastVLine(x, y, bh, static_cast<uint16_t>(color)); }
-static inline void display_targetFillRoundRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, int16_t bh, int16_t r, UI_COLOR_T color) { t->fillRoundRect(x, y, bw, bh, r, static_cast<uint16_t>(color)); }
-static inline void display_targetDrawRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, int16_t bh, UI_COLOR_T color) { t->drawRect(x, y, bw, bh, static_cast<uint16_t>(color)); }
-static inline void display_targetDrawRoundRect(CuttlefishDisplayTarget* t, int16_t x, int16_t y, int16_t bw, int16_t bh, int16_t r, UI_COLOR_T color) { t->drawRoundRect(x, y, bw, bh, r, static_cast<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, static_cast<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, static_cast<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, static_cast<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(static_cast<uint16_t>(fg)); }
-static inline void display_targetSetTextColorBg(CuttlefishDisplayTarget* t, UI_COLOR_T fg, UI_COLOR_T bg) { t->setTextColor(static_cast<uint16_t>(fg), static_cast<uint16_t>(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); }
-`;
+${CANVAS_LIFECYCLE_SECTION}${TARGET_FORWARDERS_SECTION}`;
 
   return { includes, declaration, functions };
 }
@@ -767,12 +685,45 @@ static inline void display_targetPrint(CuttlefishDisplayTarget* t, const char* s
  */
 export const zephyrDisplayAdapterGenerator: DisplayAdapterGenerator = (display) => {
   const profile = ZEPHYR_DISPLAY_PROFILES[display.driver];
-  if (!profile) return undefined as unknown as DisplayAdapterCode;
-  // The UI adapter is RGB565/SPI (TFT) only. Monochrome panels (OLED) use the
-  // direct display.* GFX runtime (gfx.ts mono branch) — there is no
-  // CuttlefishGFX UI rendering path for mono. Decline so cuttlefish does not
-  // emit an incompatible RGB565 adapter for a mono profile.
-  if (profile.colorFormat === 'mono') return undefined as unknown as DisplayAdapterCode;
+  // Drop-in path: a DT compatible as the driver id (no registry profile)
+  // synthesizes a native-transport profile — the in-tree driver bound by the
+  // overlay's node owns the panel, the config's quirk flags carry the rest.
+  // Mono compatibles (ssd1306/1309-class via the compatible table or an
+  // explicit colorFormat) take the full-frame 1bpp adapter, NOT the rgb565
+  // display-API one.
+  if (!profile) {
+    const synth = synthesizeZephyrProfile(display);
+    if (synth) {
+      if (synth.colorFormat === 'mono') {
+        if (synth.displayClass === 'eink') return zephyrEinkDisplayAdapter(synth);
+        return zephyrMonoDisplayAdapter(synth);
+      }
+      if (synth.colorFormat === 'gray8') return zephyrGrayDisplayAdapter(synth);
+      return zephyrDisplayApiAdapter(synth);
+    }
+    return undefined as unknown as DisplayAdapterCode;
+  }
+  // Mono panels (Stage 2): the full-frame 1bpp adapter — a vtiled MONO01
+  // backing store pushed whole each frame through display_write. No transport
+  // split: mono profiles ride the in-tree driver (zephyr-display); the
+  // ssd1306-class I2C node owns init/geometry.
+  if (profile.colorFormat === 'mono') {
+    // E-ink (Stage 4): same 1bpp adapter retuned for the deferred refresh
+    // model — MONO10-always + flash-cycle-throttled flushes.
+    if (profile.displayClass === 'eink') return zephyrEinkDisplayAdapter(profile);
+    return zephyrMonoDisplayAdapter(profile);
+  }
+  // Gray panels (Stage 3): the full-frame L_8 adapter — same full-frame
+  // semantic as mono at 8-bit luminance fidelity.
+  if (profile.colorFormat === 'gray8') {
+    return zephyrGrayDisplayAdapter(profile);
+  }
+  // Transport switch: 'zephyr-display' profiles get the display-API adapter
+  // (display_write on the DT device, in-tree panel driver); everything else
+  // keeps the hardware-verified direct-SPI path.
+  if (transportFor(profile) === 'zephyr-display') {
+    return zephyrDisplayApiAdapter(profile);
+  }
   return zephyrUiDisplayAdapter(profile, {
     scanlineSync: display.scanlineSync,
     miso: display.spiPins?.miso,