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

package/dist/display/ui-adapter-native.d.ts

@@ -0,0 +1,10 @@
+import type { DisplayAdapterCode } from "@typecad/cuttlefish/api/shared";
+import type { ZephyrDisplayProfile } from "./profiles.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 declare function zephyrDisplayApiAdapter(profile: ZephyrDisplayProfile): DisplayAdapterCode;

package/dist/display/ui-adapter-native.js

@@ -0,0 +1,295 @@
+// ---------------------------------------------------------------------------
+// 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 { 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) {
+    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/dist/display/ui-adapter-shared.d.ts

@@ -0,0 +1,11 @@
+/** Offscreen canvas lifecycle + accessors (malloc + placement-new; PSRAM via
+ *  Zephyr's shared multi-heap when BOARD_HAS_PSRAM). */
+export declare const CANVAS_LIFECYCLE_SECTION = "\n// \u2500\u2500 Canvas lifecycle + accessors (offscreen rgb565 compositing) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// Allocate the canvas object via malloc + placement-new (not operator new).\n// Under CONFIG_REQUIRES_FULL_LIBCPP without CONFIG_CPP_EXCEPTIONS, operator new\n// throws std::bad_alloc on OOM and the nothrow wrapper's internal catch cannot\n// unwind (no EH runtime) \u2192 std::terminate \u2192 abort. malloc returns NULL on\n// failure with no exception path; placement-new then constructs the object in\n// place (vtable included). display_deleteCanvas mirrors with an explicit dtor\n// + free. The runtime's callers already null-check the return, so an OOM\n// degrades gracefully instead of aborting.\nstatic inline CuttlefishCanvas16* display_createCanvas(int16_t cw, int16_t ch) {\n  void* mem = malloc(sizeof(CuttlefishCanvas16));\n  if (!mem) return nullptr;\n  return new (mem) CuttlefishCanvas16(cw, ch);\n}\n// psramFound() shim: the Arduino ESP32 core provides this, but Zephyr does not.\n// Under BOARD_HAS_PSRAM the ESP heap serves PSRAM, so report it as present. The\n// runtime's ui_create_canvas_best calls this under #if defined(BOARD_HAS_PSRAM).\n#if defined(BOARD_HAS_PSRAM) && !defined(psramFound)\n#include <zephyr/multi_heap/shared_multi_heap.h>\nstatic inline bool psramFound() {\n  // Compile-time truth: if BOARD_HAS_PSRAM is defined, the build targets a\n  // PSRAM board with CONFIG_ESP_SPIRAM enabled (the framework emits both).\n  return true;\n}\n// Allocate from PSRAM via Zephyr's shared multi-heap (the ESP32 SoC code\n// registers PSRAM as an SMH_REG_ATTR_EXTERNAL region at boot).\nstatic inline void* ui_psram_malloc(size_t bytes) {\n  return shared_multi_heap_alloc(SMH_REG_ATTR_EXTERNAL, bytes);\n}\n#endif\nstatic inline CuttlefishCanvas16* display_createCanvasPsram(int16_t cw, int16_t ch) {\n  // Allocate the pixel buffer in PSRAM (large: w*h*2 bytes) and the small\n  // canvas object in SRAM. The canvas takes ownership of the PSRAM buffer and\n  // frees it via free() in its dtor (the SMH allocator's free is compatible\n  // with the standard k_free/free path). Returns nullptr if PSRAM isn't\n  // available or the allocation fails \u2014 ui_create_canvas_best falls back.\n#if defined(BOARD_HAS_PSRAM)\n  if ((cw > 0) && (ch > 0)) {\n    size_t bytes = static_cast<size_t>(cw) * static_cast<size_t>(ch) * sizeof(uint16_t);\n    uint16_t* psramBuf = static_cast<uint16_t*>(ui_psram_malloc(bytes));\n    if (psramBuf) {\n      void* mem = malloc(sizeof(CuttlefishCanvas16));\n      if (mem) {\n        return new (mem) CuttlefishCanvas16(cw, ch, psramBuf, 1);\n      }\n      free(psramBuf);\n    }\n  }\n#else\n  (void)cw; (void)ch;\n#endif\n  return nullptr;\n}\nstatic inline void display_deleteCanvas(CuttlefishCanvas16* canvas) {\n  if (!canvas) return;\n  canvas->~CuttlefishCanvas16();\n  free(canvas);\n}\nstatic inline int16_t display_canvasWidth(CuttlefishCanvas16* c) { return c->width(); }\nstatic inline int16_t display_canvasHeight(CuttlefishCanvas16* c) { return c->height(); }\n// Canvas buffers are addressed in UI_COLOR_T units by every runtime caller;\n// the underlying CuttlefishCanvas16 storage is 16-bit (the 565/mono world the\n// canvas machinery was built for). Gray8/full-frame targets never allocate\n// canvases, so the reinterpret never dereferences on those builds.\nstatic inline UI_COLOR_T* display_canvasBuffer(CuttlefishCanvas16* c) {\n  return reinterpret_cast<UI_COLOR_T*>(c->getBuffer());\n}\nstatic inline uint16_t display_canvasGetPixel(CuttlefishCanvas16* c, int16_t x, int16_t y) { return c->getPixel(x, y); }\nstatic inline void display_canvasFillScreen(CuttlefishCanvas16* c, UI_COLOR_T color) { c->fillScreen(static_cast<uint16_t>(color)); }\nstatic inline void display_canvasFillRect(CuttlefishCanvas16* c, int16_t x, int16_t y, int16_t cw, int16_t ch, UI_COLOR_T color) {\n  c->fillRect(x, y, cw, ch, static_cast<uint16_t>(color));\n}\n";
+/** Target-polymorphic draw passthroughs (panel or canvas via
+ *  CuttlefishDisplayTarget*). Pure virtual dispatch on the target object. */
+export declare const TARGET_FORWARDERS_SECTION = "\n// \u2500\u2500 Target-polymorphic draw (panel or canvas via CuttlefishDisplayTarget*) \u2500\nstatic 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)); }\nstatic inline int16_t display_targetWidth(CuttlefishDisplayTarget* t) { return t->width(); }\nstatic inline int16_t display_targetHeight(CuttlefishDisplayTarget* t) { return t->height(); }\nstatic inline void display_targetDrawRGBBitmap(CuttlefishDisplayTarget* t, int16_t x, int16_t y, const UI_COLOR_T* bitmap, int16_t bw, int16_t bh) {\n  t->drawRGBBitmap(x, y, reinterpret_cast<const uint16_t*>(bitmap), bw, bh);\n}\nstatic 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)); }\nstatic 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)); }\nstatic 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)); }\nstatic 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)); }\nstatic 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)); }\nstatic 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)); }\nstatic 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)); }\nstatic 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)); }\nstatic 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)); }\nstatic inline void display_targetSetCursor(CuttlefishDisplayTarget* t, int16_t x, int16_t y) { t->setCursor(x, y); }\nstatic inline void display_targetSetTextColor(CuttlefishDisplayTarget* t, UI_COLOR_T fg) { t->setTextColor(static_cast<uint16_t>(fg)); }\nstatic 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)); }\nstatic inline void display_targetSetTextSize(CuttlefishDisplayTarget* t, uint8_t s) { t->setTextSize(s); }\nstatic inline void display_targetSetTextWrap(CuttlefishDisplayTarget* t, bool wp) { t->setTextWrap(wp); }\nstatic inline void display_targetPrint(CuttlefishDisplayTarget* t, const char* s) { t->print(s); }\n";
+/** 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 declare function profileMarkerLine(driver: string): string;

package/dist/display/ui-adapter-shared.js

@@ -0,0 +1,122 @@
+// ---------------------------------------------------------------------------
+// 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) {
+    return `// typecad-display-profile: ${driver}`;
+}