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

package/src/display/touch-adapter.ts

@@ -1,15 +1,29 @@
 // ---------------------------------------------------------------------------
-// Zephyr touch adapters for the Cuttlefish UI rendering pipeline.
+// Zephyr touch adapters for the TypeCAD UI rendering pipeline.
 //
-// Two controllers, both driven directly (polling, no in-tree driver):
-//   - FT6336U capacitive over I2C (i2c_write_read_dt)
-//   - XPT2046 resistive over SPI (spi_transceive_dt) — the Zephyr analog of
-//     Arduino's XPT2046_Touchscreen adapter. The DT node uses the in-tree
-//     xptek,xpt2046 binding; CONFIG_INPUT stays off, so the in-tree input
-//     driver does not build and this adapter owns the chip.
+//   - FT6336U capacitive: through Zephyr's INPUT subsystem — the in-tree
+//     focaltech,ft5336 driver owns the controller (polling mode: the node
+//     carries no int-gpios, so the driver samples on a k_timer/work cycle
+//     and no GPIO IRQ is registered — sidestepping the ESP32
+//     VECDESC_FL_SHARED crash the direct-IRQ path hit). The adapter listens
+//     for the device's INPUT events and serves the runtime's
+//     touch_init/isTouched/readRaw contract from the latest event state.
+//     Hardware-verified on the demo rig (ESP32-S3 + FT6336U, SDA8/SCL9).
+//   - XPT2046 resistive: raw SPI polling (spi_transceive_dt) — the Zephyr
+//     analog of Arduino's XPT2046_Touchscreen adapter. NOT yet on the input
+//     subsystem: the in-tree xpt2046 driver scales coordinates through its
+//     DT min-x/max-x props, which would double-apply the runtime's
+//     calibration math (touch_readRaw must stay in raw controller units for
+//     ui_poll_touch's calibration + rotation). Converting needs the DT
+//     scaling reconciled with the config calibration — and hardware to
+//     verify it on. CONFIG_INPUT stays off for xpt2046-only builds.
 //
 // The adapters emit touch_init / touch_isTouched / touch_readRaw — the three
-// symbols the runtime's ui_poll_touch body calls.
+// symbols the runtime's ui_poll_touch body calls. For FT6336U the raw
+// coordinate space is unchanged (X/Y controller registers, native portrait
+// panel units): the overlay's swapped-xy property makes the driver's ABS_X/
+// ABS_Y events carry the register values verbatim, so ui_poll_touch's
+// calibration + rotation math applies as before.
 //
 // EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
 // Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
@@ -135,69 +149,125 @@ function xpt2046Adapter(touch: TouchProfile): TouchAdapterCodegen {
 function ft6336uAdapter(_touch: TouchProfile): TouchAdapterCodegen {
   return {
     includes: [
+      `#include <zephyr/kernel.h>`,
+      `#include <zephyr/input/input.h>`,
+      // TEMPORARY DIAGNOSTIC (with __tc_touch_diag above).
       `#include <zephyr/drivers/i2c.h>`,
     ],
     declaration: [
-      `// Zephyr FT6336U touch — I2C device resolved via devicetree.`,
-      `// The board DT must define an 'ft6336u' nodelabel on an I2C bus.`,
-      `static const struct i2c_dt_spec __tc_touch = I2C_DT_SPEC_GET(DT_NODELABEL(ft6336u));`,
+      `// Zephyr FT6336U touch — INPUT subsystem listener. The in-tree`,
+      `// focaltech,ft5336 driver (CONFIG_INPUT_FT5336, polling mode — no`,
+      `// int-gpios on the node) owns the controller and reports events; this`,
+      `// adapter keeps the latest state and serves the runtime's per-frame`,
+      `// touch_isTouched/touch_readRaw poll. The overlay's swapped-xy DT prop`,
+      `// makes the driver's ABS_X/ABS_Y carry the controller's X/Y registers`,
+      `// verbatim — the same raw space the register-polling adapter reported,`,
+      `// so the runtime's calibration + rotation math is unchanged.`,
       `static int16_t __tc_touch_cached_x = 0;`,
       `static int16_t __tc_touch_cached_y = 0;`,
-      `static int16_t __tc_touch_cached_z = 0;`,
-      `static uint8_t __tc_touch_cached_valid = 0;`,
+      `static volatile bool __tc_touch_down = false;`,
     ].join("\n"),
     functions: [
-      `// Read N bytes starting from a register address. Returns 1 on success.`,
-      `// Uses i2c_write_read_dt for a combined write-read transaction (register`,
-      `// address write, then repeated-start read). The FT6336U is polled every`,
-      `// frame from ui_poll_touch, so a failed read (stuck SDA, no controller) is`,
-      `// non-fatal — returns 0 and touch_isTreated() returns false.`,
-      `static inline uint8_t __tc_touch_read_block(uint8_t reg, uint8_t* buf, uint8_t len) {`,
-      `  if (!device_is_ready(__tc_touch.bus)) return 0U;`,
-      `  int rc = i2c_write_read_dt(&__tc_touch, &reg, 1U, buf, len);`,
-      `  return (rc == 0) ? 1U : 0U;`,
+      `// Input listener: runs in the driver's work-handler context (poll mode`,
+      `// samples every CONFIG_INPUT_FT5336_PERIOD ms). Latest-value semantics —`,
+      `// plain int16 stores with no locking; the UI loop reads them once per`,
+      `// frame and a torn mid-write read only ever costs one sample of one axis.`,
+      `// The first events are logged once — a diagnostic that costs ten lines`,
+      `// ever and immediately answers "are events arriving, and in which space".`,
+      `static uint8_t __tc_touch_evt_logged = 0U;`,
+      `static void __tc_touch_input_cb(struct input_event* evt, void* /*user_data*/) {`,
+      `  if (__tc_touch_evt_logged < 10U) {`,
+      `    __tc_touch_evt_logged++;`,
+      `    printk("TC_TOUCH: evt type=%u code=%u value=%d sync=%u\\n",`,
+      `           static_cast<unsigned int>(evt->type),`,
+      `           static_cast<unsigned int>(evt->code),`,
+      `           static_cast<int>(evt->value),`,
+      `           static_cast<unsigned int>(evt->sync));`,
+      `  }`,
+      `  if (evt->type == INPUT_EV_ABS) {`,
+      `    if (evt->code == INPUT_ABS_X) {`,
+      `      __tc_touch_cached_x = static_cast<int16_t>(evt->value);`,
+      `    } else if (evt->code == INPUT_ABS_Y) {`,
+      `      __tc_touch_cached_y = static_cast<int16_t>(evt->value);`,
+      `    }`,
+      `  } else if ((evt->type == INPUT_EV_KEY) && (evt->code == INPUT_BTN_TOUCH)) {`,
+      `    __tc_touch_down = (evt->value != 0);`,
+      `  }`,
       `}`,
       ``,
+      `// Registered for the ft6336u device's events only (the _dev filter) —`,
+      `// other input devices on the system never reach the UI touch state.`,
+      `INPUT_CALLBACK_DEFINE(DEVICE_DT_GET(DT_NODELABEL(ft6336u)), __tc_touch_input_cb, NULL);`,
+      ``,
       `static inline void touch_init() {`,
-      `  // The I2C bus + device are configured by devicetree. The FT6336U needs a`,
-      `  // hardware reset (reset pin low → high) to enter normal mode after power-on.`,
+      `  // Power/reset enable — rig-verified sequence, matching the Arduino`,
+      `  // pin order this module needs (GPIO driven LOW 10ms, then HIGH, then`,
+      `  // 500ms settle before the controller answers). Without the drive the`,
+      `  // enable floats: the controller half-powers, ACKs briefly, then`,
+      `  // browns out — the 0xFF-then-NAK bus death reproduced identically on`,
+      `  // every firmware variant until this was wired. The in-tree driver`,
+      `  // pulses its own (shorter) reset at init; this re-drive with the`,
+      `  // verified timing runs from main before the UI starts polling.`,
       `#if DT_NODE_HAS_STATUS(DT_NODELABEL(ft6336u), okay) && DT_NODE_HAS_PROP(DT_NODELABEL(ft6336u), reset_gpios)`,
-      `  static const struct gpio_dt_spec __tc_touch_rst = GPIO_DT_SPEC_GET(DT_NODELABEL(ft6336u), reset_gpios);`,
-      `  if (device_is_ready(__tc_touch_rst.port)) {`,
-      `    gpio_pin_configure_dt(&__tc_touch_rst, GPIO_OUTPUT_ACTIVE);    // assert reset (active=low)`,
+      `  static const struct gpio_dt_spec __tc_touch_en = GPIO_DT_SPEC_GET(DT_NODELABEL(ft6336u), reset_gpios);`,
+      `  if (device_is_ready(__tc_touch_en.port)) {`,
+      `    gpio_pin_configure_dt(&__tc_touch_en, GPIO_OUTPUT_ACTIVE);   // drive LOW (active-low spec)`,
       `    k_msleep(10);`,
-      `    gpio_pin_set_dt(&__tc_touch_rst, 0);                            // release reset (inactive=high)`,
-      `    k_msleep(200);  // FT6336U needs ~50ms after reset before responding`,
+      `    gpio_pin_set_dt(&__tc_touch_en, 0);                          // drive HIGH`,
+      `    k_msleep(500);`,
       `  }`,
       `#endif`,
-      `  (void)device_is_ready(__tc_touch.bus);`,
+      `  const struct device* __tc_touch_dev = DEVICE_DT_GET(DT_NODELABEL(ft6336u));`,
+      `  if (!device_is_ready(__tc_touch_dev)) {`,
+      `    printk("TC_TOUCH: ft6336u device not ready\\n");`,
+      `    return;`,
+      `  }`,
+      `  // Self-test: dispatch one synthetic release event through the input`,
+      `  // core. If the listener is registered and dispatch works, the event`,
+      `  // logger above prints it; rc=-EAGAIN means the input queue is full`,
+      `  // (input thread wedged). K_NO_WAIT so a dead queue can never block`,
+      `  // boot.`,
+      `  int __rc = input_report_key(__tc_touch_dev, INPUT_BTN_TOUCH, 0, true, K_NO_WAIT);`,
+      `  printk("TC_TOUCH: ft6336u ready, self-test report rc=%d\\n", __rc);`,
+      `}`,
+      ``,
+      `// Boot-time bus diagnostic (self-limiting): reads TD_STATUS directly`,
+      `// over I2C — the register path the raw adapter proved on this rig —`,
+      `// dense (300ms) for the first 5s, sparse (3s) until 60s, then silent.`,
+      `// On the demo rig this caught a failing touch module: the controller`,
+      `// ACKs for the first ~700ms after every reset, returns 0xFF once, then`,
+      `// NAKs permanently — a power/connection fault, independent of firmware`,
+      `// (reproduced identically on the committed pre-migration build).`,
+      `static const struct i2c_dt_spec __tc_touch_probe = I2C_DT_SPEC_GET(DT_NODELABEL(ft6336u));`,
+      `static int32_t __tc_touch_probe_next = 0;`,
+      `static void __tc_touch_diag() {`,
+      `  int32_t __now = static_cast<int32_t>(k_uptime_get_32());`,
+      `  if (__now >= 60000) return;`,
+      `  int32_t __gap = (__now < 5000) ? 300 : 3000;`,
+      `  if (__now < __tc_touch_probe_next) return;`,
+      `  __tc_touch_probe_next = __now + __gap;`,
+      `  uint8_t __td = 0U;`,
+      `  uint8_t __reg = 0x02U;`,
+      `  int __rc = i2c_write_read_dt(&__tc_touch_probe, &__reg, 1U, &__td, 1U);`,
+      `  if ((__rc != 0) || (__td != 0U)) {`,
+      `    printk("TC_TOUCH: diag td_status=0x%02x rc=%d down=%d\\n",`,
+      `           static_cast<unsigned int>(__td), __rc,`,
+      `           __tc_touch_down ? 1 : 0);`,
+      `  }`,
       `}`,
       ``,
       `static inline bool touch_isTouched() {`,
-      `  __tc_touch_cached_valid = 0;`,
-      `  __tc_touch_cached_z = 0;`,
-      `  // Read TD_STATUS (0x02) + P1_XH/XL/YH/YL — 5 bytes in one transaction.`,
-      `  uint8_t buf[5] = {0, 0, 0, 0, 0};`,
-      `  if (!__tc_touch_read_block(0x02, buf, 5U)) return false;`,
-      `  uint8_t count = buf[0] & 0x0F;`,
-      `  if (count == 0U) return false;`,
-      `  __tc_touch_cached_x = static_cast<int16_t>((static_cast<uint16_t>(buf[1] & 0x0F) << 8) | buf[2]);`,
-      `  __tc_touch_cached_y = static_cast<int16_t>((static_cast<uint16_t>(buf[3] & 0x0F) << 8) | buf[4]);`,
-      `  __tc_touch_cached_z = 255;`,
-      `  __tc_touch_cached_valid = 1;`,
-      `  return true;`,
+      `  __tc_touch_diag();`,
+      `  return __tc_touch_down;`,
       `}`,
       ``,
       `static inline void touch_readRaw(int16_t* x, int16_t* y, int16_t* z) {`,
-      `  // touch_isTouched() is polled each frame by ui_poll_touch; the cached`,
-      `  // values are fresh. If something calls readRaw before isTouched, probe now.`,
-      `  if (!__tc_touch_cached_valid) {`,
-      `    (void)touch_isTouched();`,
-      `  }`,
+      `  // Latest reported position in controller register units (native panel`,
+      `  // space); the runtime applies calibration + rotation. z is saturation`,
+      `  // for capacitive (the driver reports press/release, not pressure).`,
       `  if (x) *x = __tc_touch_cached_x;`,
       `  if (y) *y = __tc_touch_cached_y;`,
-      `  if (z) *z = __tc_touch_cached_z;`,
-      `  __tc_touch_cached_valid = 0;`,
+      `  if (z) *z = 255;`,
       `}`,
     ].join("\n"),
   };

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

@@ -0,0 +1,13 @@
+// E-ink UI adapter (Stage 4) — the refresh-model proof. Same 1bpp format as
+// mono (the parameterized mono adapter: vtiled MONO01 backing store, always-
+// complemented MONO10 pushes — the ssd16xx/uc81xx families accept nothing
+// else); the NEW axis is the refresh model: the runtime's UI_REFRESH_DEFERRED
+// accumulator flushes on change, the adapter rate-limits pushes to the panel's
+// flash-cycle economics (TC_EINK_MIN_REFRESH_MS), and the panel sleeps between
+// flashes (the driver blocks through BUSY inside display_write).
+import type { ZephyrDisplayProfile } from "./profiles.js";
+import { zephyrMonoDisplayAdapter } from "./ui-adapter-mono.js";
+
+export function zephyrEinkDisplayAdapter(profile: ZephyrDisplayProfile) {
+  return zephyrMonoDisplayAdapter(profile, { eink: true });
+}

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

@@ -0,0 +1,178 @@
+// ---------------------------------------------------------------------------
+// Zephyr gray UI display adapter — Stage 3's gray8 lowering target.
+//
+// The panel accepts PIXEL_FORMAT_L_8 (8-bit luminance; the solomon,ssd1327
+// driver nibble-reduces to its 16 display levels). The adapter keeps a
+// row-major L_8 backing store (one byte per pixel — 4KB at 128x64) and
+// pushes the whole frame with ONE display_write, mirroring the mono
+// adapter's full-frame semantic at gray fidelity. UI_COLOR_T is uint8_t and
+// node values are luminance bytes, so every draw is a store.
+//
+// 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: one static framebuffer, no
+// per-frame allocation, one atomic push per frame.
+// ---------------------------------------------------------------------------
+
+import type { DisplayAdapterCode } from "@typecad/cuttlefish/api/shared";
+import type { ZephyrDisplayProfile } from "./profiles.js";
+import { displayFactsLine } from "./profiles.js";
+import { CANVAS_LIFECYCLE_SECTION, TARGET_FORWARDERS_SECTION, profileMarkerLine } from "./ui-adapter-shared.js";
+
+/**
+ * Build the gray8 UI adapter for a profile. The profile's dtLabel must name
+ * a display node bound by an L_8-capable driver (solomon,ssd1327-class —
+ * the overlay generates the node; the driver self-builds from it).
+ */
+export function zephyrGrayDisplayAdapter(profile: ZephyrDisplayProfile): DisplayAdapterCode {
+  const w = profile.width;
+  const h = profile.height;
+  const dtLabel = profile.dtLabel;
+
+  const includes = [
+    `// --- Zephyr gray UI display adapter (${profile.driver}, full-frame L_8) ---`,
+    profileMarkerLine(profile.driver),
+    displayFactsLine(profile),
+    `// Gray target: the adapter's ZephyrGrayTarget (a CuttlefishGFX writing an`,
+    `// L_8 backing store — one luminance byte per pixel; the driver reduces`,
+    `// to the panel's 16 display levels).`,
+    `#define CuttlefishDisplayTarget ZephyrGrayTarget`,
+    `#include <zephyr/kernel.h>`,
+    `#include <zephyr/drivers/display.h>`,
+    `#include <zephyr/drivers/gpio.h>`,
+  ].join("\n");
+
+  const declaration = [
+    `// CUTTLEFISH_DISPLAY_BEGIN`,
+    `// The panel device: the overlay's display0 node, bound by an L_8-capable`,
+    `// driver. Compile-time constant — DEVICE_DT_GET requires the driver to`,
+    `// exist at build time, which the Kconfig layer guarantees.`,
+    `static const struct device* __tc_zd_dev = DEVICE_DT_GET(DT_NODELABEL(${dtLabel}));`,
+    `static struct display_capabilities __tc_zd_caps;`,
+    `// Full-frame backing store, row-major L_8: one luminance byte per pixel`,
+    `// (${w}*${h} = ${w * h} bytes).`,
+    `static uint8_t __tc_gray_fb[${w} * ${h}];`,
+    `// Rig diagnostics: frames pushed since boot (see display_partial_refresh).`,
+    `static uint32_t __tc_gray_frames = 0;`,
+    `// Gray target clip (w <= 0 ⇒ no clip). Enforced in ZephyrGrayTarget's`,
+    `// drawPixel/fillRect so EVERY pixel — including ones emitted inside`,
+    `// CuttlefishGFX geometry algorithms — respects it.`,
+    `static int16_t __tc_mono_clip_x = 0;`,
+    `static int16_t __tc_mono_clip_y = 0;`,
+    `static int16_t __tc_mono_clip_w = 0;`,
+    `static int16_t __tc_mono_clip_h = 0;`,
+    `// CUTTLEFISH_DISPLAY_END`,
+  ].join("\n");
+
+  const functions = `
+// ── Gray target ───────────────────────────────────────────────────────────
+// A CuttlefishGFX whose pixels are backing-store bytes. All geometry/text
+// primitives the runtime draws funnel through these two overrides.
+class ZephyrGrayTarget final : public CuttlefishGFX {
+ public:
+  ZephyrGrayTarget() : CuttlefishGFX(nullptr, nullptr) {}
+  int16_t width() const { return ${w}; }
+  int16_t height() const { return ${h}; }
+  void drawPixel(int16_t x, int16_t y, uint16_t color) {
+    if (x < 0 || y < 0 || x >= ${w} || y >= ${h}) return;
+    if (__tc_mono_clip_w > 0 &&
+        (x < __tc_mono_clip_x || y < __tc_mono_clip_y ||
+         x >= __tc_mono_clip_x + __tc_mono_clip_w ||
+         y >= __tc_mono_clip_y + __tc_mono_clip_h)) return;
+    __tc_gray_fb[static_cast<uint32_t>(y) * ${w}u + static_cast<uint32_t>(x)] =
+      static_cast<uint8_t>(color);
+  }
+  void fillRect(int16_t x, int16_t y, int16_t rw, int16_t rh, uint16_t color) {
+    if (rw <= 0 || rh <= 0) return;
+    for (int16_t j = 0; j < rh; j++) {
+      for (int16_t i = 0; i < rw; i++) {
+        drawPixel(static_cast<int16_t>(x + i), static_cast<int16_t>(y + j), color);
+      }
+    }
+  }
+};
+static ZephyrGrayTarget __tc_display;
+
+// ── Gray clip (the runtime's full-frame scroll clipping) ──────────────────
+static inline void display_mono_set_clip(int16_t x, int16_t y, int16_t rw, int16_t rh) {
+  __tc_mono_clip_x = x;
+  __tc_mono_clip_y = y;
+  __tc_mono_clip_w = rw;
+  __tc_mono_clip_h = rh;
+}
+static inline void display_mono_clear_clip() {
+  __tc_mono_clip_w = 0;
+  __tc_mono_clip_h = 0;
+}
+
+// ── Frame push ─────────────────────────────────────────────────────────────
+// Full-frame redraw, ALWAYS (Stage 3): the ${w * h}-byte L_8 frame is one
+// display_write. The dirty-rect args are accepted and ignored — at
+// ~50-100ms a frame (I2C fast mode), incremental compositing has nothing
+// to optimize.
+static inline void display_partial_refresh(int16_t x, int16_t y, int16_t rw, int16_t rh) {
+  (void)x; (void)y; (void)rw; (void)rh;
+  struct display_buffer_descriptor __desc = {};
+  __desc.width = ${w}u;
+  __desc.height = ${h}u;
+  __desc.pitch = ${w}u;
+  __desc.buf_size = sizeof(__tc_gray_fb);
+  __desc.frame_incomplete = false;
+  int __ret = display_write(__tc_zd_dev, 0, 0, &__desc, __tc_gray_fb);
+  __tc_gray_frames++;
+  if (__ret != 0) {
+    printk("TC_DISPLAY: display_write failed: %d\\n", __ret);
+  } else if ((__tc_gray_frames & 0x0Fu) == 1u) {
+    printk("TC_DISPLAY: gray frame #%u pushed\\n", static_cast<unsigned int>(__tc_gray_frames));
+  }
+}
+
+// ── display_init (called from setup) ───────────────────────────────────────
+
+static inline void display_init() {
+  printk("TC_DISPLAY: gray full-frame transport (${dtLabel}, ${w}x${h}, L_8)\\n");
+  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);
+  printk("TC_DISPLAY: panel reports %ux%u fmt=%u screen_info=%u\\n",
+         static_cast<unsigned int>(__tc_zd_caps.x_resolution),
+         static_cast<unsigned int>(__tc_zd_caps.y_resolution),
+         static_cast<unsigned int>(__tc_zd_caps.current_pixel_format),
+         static_cast<unsigned int>(__tc_zd_caps.screen_info));
+  // L_8 is the driver's native format (it nibble-reduces to the panel's 16
+  // levels); request it in case the driver boots in something else.
+  if (__tc_zd_caps.current_pixel_format != PIXEL_FORMAT_L_8) {
+    if (display_set_pixel_format(__tc_zd_dev, PIXEL_FORMAT_L_8) != 0) {
+      printk("TC_DISPLAY: panel refused L_8 — check the driver\\n");
+    }
+  }
+  for (size_t i = 0; i < sizeof(__tc_gray_fb); i++) __tc_gray_fb[i] = 0u;
+  (void)display_blanking_off(__tc_zd_dev);
+  display_partial_refresh(0, 0, ${w}, ${h});
+  printk("TC_DISPLAY: gray init done (L_8 full-frame)\\n");
+}
+
+static inline void display_fillScreen(UI_COLOR_T color) {
+  for (size_t i = 0; i < sizeof(__tc_gray_fb); i++) __tc_gray_fb[i] = static_cast<uint8_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}; }
+
+// Immediate-push no-ops: all drawing targets the backing store; the frame
+// publishes atomically in display_partial_refresh.
+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) {
+  (void)x; (void)y; (void)winW; (void)winH;
+}
+static inline void display_writePixels(const UI_COLOR_T* pixels, uint32_t count) {
+  (void)pixels; (void)count;
+}
+${CANVAS_LIFECYCLE_SECTION}${TARGET_FORWARDERS_SECTION}`;
+
+  return { includes, declaration, functions };
+}

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

@@ -0,0 +1,238 @@
+// ---------------------------------------------------------------------------
+// Zephyr mono UI display adapter — Stage 2's 1bpp lowering target.
+//
+// The mono panel IS a backing store: the adapter keeps a full-frame vtiled
+// MONO01 framebuffer (byte = 8 vertical pixels, buf[(y>>3)*W + x], bit
+// 1<<(y&7) — the layout Zephyr's ssd1306-class drivers expect from
+// display_write: pitch == width, y and height multiples of 8). Every UI draw
+// lands in RAM through a CuttlefishGFX subclass; ui_refresh_flush pushes the
+// whole frame with ONE display_write call (full-frame redraw, always — a
+// 128×64 frame is 1KB, ~25ms over I²C; incremental compositing has nothing
+// to optimize).
+//
+// The runtime's scroll-canvas/band machinery is bypassed under
+// UI_FULL_FRAME_REDRAW (see the engine's runtime header); scroll clipping
+// rides this adapter's mono clip rect (display_mono_set_clip), which every
+// draw primitive enforces — including pixels emitted inside the CuttlefishGFX
+// geometry algorithms, which is why the clip lives here and not in the shim.
+//
+// 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: one static framebuffer, no per-frame
+// allocation, one atomic push per frame.
+// ---------------------------------------------------------------------------
+
+import type { DisplayAdapterCode } from "@typecad/cuttlefish/api/shared";
+import type { ZephyrDisplayProfile } from "./profiles.js";
+import { displayFactsLine } from "./profiles.js";
+import { CANVAS_LIFECYCLE_SECTION, TARGET_FORWARDERS_SECTION, profileMarkerLine } from "./ui-adapter-shared.js";
+
+/**
+ * Build the mono (1bpp) UI adapter for a profile. The profile's dtLabel must
+ * name a display node an in-tree mono driver binds (ssd1306-class over I²C —
+ * the overlay generates the node; the driver self-builds from it).
+ * `opts.eink` retunes it for the e-ink refresh model (Stage 4): skip the
+ * MONO01 negotiation (ssd16xx/uc81xx are MONO10-only) and throttle pushes
+ * to the panel's flash-cycle economics.
+ */
+export function zephyrMonoDisplayAdapter(profile: ZephyrDisplayProfile, opts?: { eink?: boolean }): DisplayAdapterCode {
+  const eink = opts?.eink === true;
+  const w = profile.width;
+  const h = profile.height;
+  const dtLabel = profile.dtLabel;
+  const nativeW = profile.nativeWidth ?? w;
+  const nativeH = profile.nativeHeight ?? h;
+
+  const includes = [
+    `// --- Zephyr mono UI display adapter (${profile.driver}, full-frame 1bpp) ---`,
+    profileMarkerLine(profile.driver),
+    displayFactsLine(profile),
+    `// Mono target: the adapter's ZephyrMonoTarget (a CuttlefishGFX writing a`,
+    `// vtiled MONO01 backing store), NOT the rgb565 panel-ops path.`,
+    `#define CuttlefishDisplayTarget ZephyrMonoTarget`,
+    `#include <zephyr/kernel.h>`,
+    `#include <zephyr/drivers/display.h>`,
+    `#include <zephyr/drivers/gpio.h>`,
+  ].join("\n");
+
+  const declaration = [
+    `// CUTTLEFISH_DISPLAY_BEGIN`,
+    `// The panel device: the overlay's display0 node, bound by an in-tree mono`,
+    `// driver (ssd1306-class). Compile-time constant — DEVICE_DT_GET requires`,
+    `// the driver to exist at build time, which the Kconfig layer guarantees.`,
+    `static const struct device* __tc_zd_dev = DEVICE_DT_GET(DT_NODELABEL(${dtLabel}));`,
+    `static struct display_capabilities __tc_zd_caps;`,
+    `// Full-frame backing store, vtiled MONO01: byte = 8 vertical pixels,`,
+    `// buf[(y>>3)*${w} + x], bit = 1<<(y&7). One bit per pixel ⇒ ${w}*${h}/8 = ${(w * h) / 8} bytes.`,
+    `static uint8_t __tc_mono_fb[(${w} * ${h} + 7) / 8];`,
+    `// Push scratch for panels that insist on MONO10 (1=black): the frame is`,
+    `// complemented here, never in the backing store itself.`,
+    `static uint8_t __tc_mono_inv[(${w} * ${h} + 7) / 8];`,
+    `// Rig diagnostics: frames pushed since boot (see display_partial_refresh).`,
+    `static uint32_t __tc_mono_frames = 0;`,
+    `// E-ink flush floor: one flash per push at most this often (the drivers
+// block through BUSY inside display_write — an unthrottled binding tick
+// would stall the app loop for seconds).
+#define TC_EINK_MIN_REFRESH_MS 2000u
+// Set when the panel insists on MONO10 (1=black): pushes invert the frame.`,
+    `static bool __tc_mono_invert = false;`,
+    `// Scroll-viewport clip in display coords (w <= 0 ⇒ no clip). Enforced in`,
+    `// ZephyrMonoTarget's drawPixel/fillRect so EVERY pixel — including ones`,
+    `// emitted inside CuttlefishGFX geometry algorithms — respects it.`,
+    `static int16_t __tc_mono_clip_x = 0;`,
+    `static int16_t __tc_mono_clip_y = 0;`,
+    `static int16_t __tc_mono_clip_w = 0;`,
+    `static int16_t __tc_mono_clip_h = 0;`,
+    `// CUTTLEFISH_DISPLAY_END`,
+  ].join("\n");
+
+  const functions = `
+// ── Mono target ───────────────────────────────────────────────────────────
+// A CuttlefishGFX whose pixels are backing-store bits. All geometry/text
+// primitives the runtime draws funnel through these two overrides.
+class ZephyrMonoTarget final : public CuttlefishGFX {
+ public:
+  ZephyrMonoTarget() : CuttlefishGFX(nullptr, nullptr) {}
+  int16_t width() const { return ${w}; }
+  int16_t height() const { return ${h}; }
+  void drawPixel(int16_t x, int16_t y, uint16_t color) {
+    if (x < 0 || y < 0 || x >= ${w} || y >= ${h}) return;
+    if (__tc_mono_clip_w > 0 &&
+        (x < __tc_mono_clip_x || y < __tc_mono_clip_y ||
+         x >= __tc_mono_clip_x + __tc_mono_clip_w ||
+         y >= __tc_mono_clip_y + __tc_mono_clip_h)) return;
+    uint8_t mask = static_cast<uint8_t>(1u << (y & 7));
+    uint8_t* b = &__tc_mono_fb[(static_cast<uint32_t>(y) >> 3) * ${w}u + static_cast<uint32_t>(x)];
+    if (color) *b = static_cast<uint8_t>(*b | mask);
+    else       *b = static_cast<uint8_t>(*b & static_cast<uint8_t>(~mask));
+  }
+  void fillRect(int16_t x, int16_t y, int16_t rw, int16_t rh, uint16_t color) {
+    if (rw <= 0 || rh <= 0) return;
+    for (int16_t j = 0; j < rh; j++) {
+      for (int16_t i = 0; i < rw; i++) {
+        drawPixel(static_cast<int16_t>(x + i), static_cast<int16_t>(y + j), color);
+      }
+    }
+  }
+};
+static ZephyrMonoTarget __tc_display;
+
+// ── Mono clip (the runtime's full-frame scroll clipping) ──────────────────
+static inline void display_mono_set_clip(int16_t x, int16_t y, int16_t rw, int16_t rh) {
+  __tc_mono_clip_x = x;
+  __tc_mono_clip_y = y;
+  __tc_mono_clip_w = rw;
+  __tc_mono_clip_h = rh;
+}
+static inline void display_mono_clear_clip() {
+  __tc_mono_clip_w = 0;
+  __tc_mono_clip_h = 0;
+}
+
+// ── Frame push ─────────────────────────────────────────────────────────────
+// Full-frame redraw, ALWAYS (Stage 2): the 1KB frame is one display_write.
+// The ssd1306-class drivers require pitch == width and (y, height) multiples
+// of 8 — the full frame satisfies both by construction. The dirty-rect args
+// are accepted and ignored: at ~25ms a frame, partial compositing has nothing
+// to optimize.
+static inline void display_partial_refresh(int16_t x, int16_t y, int16_t rw, int16_t rh) {
+  (void)x; (void)y; (void)rw; (void)rh;
+${eink ? `  // E-ink deferred flush: the flash cycle blocks inside display_write for
+  // 1-4s — rate-limit pushes, keep the newest frame pending in between.
+  static uint32_t last_push_ms = 0;
+  static bool pending = false;
+  const uint32_t now_ms = k_uptime_get_32();
+  if (pending && (now_ms - last_push_ms) < TC_EINK_MIN_REFRESH_MS) return;
+  pending = true;
+  last_push_ms = now_ms;` : ""}
+  struct display_buffer_descriptor __desc = {};
+  __desc.width = ${w}u;
+  __desc.height = ${h}u;
+  __desc.pitch = ${w}u;
+  __desc.buf_size = sizeof(__tc_mono_fb);
+  __desc.frame_incomplete = false;
+  const uint8_t* src = __tc_mono_fb;
+  if (__tc_mono_invert) {
+    // Panel insists on MONO10 (1=black): push the complement of the frame.
+    for (size_t i = 0; i < sizeof(__tc_mono_fb); i++) {
+      __tc_mono_inv[i] = static_cast<uint8_t>(~__tc_mono_fb[i]);
+    }
+    src = __tc_mono_inv;
+  }
+  int __ret = display_write(__tc_zd_dev, 0, 0, &__desc, src);
+  // Rig diagnostics: the first frame + every 64th reports liveness, and any
+  // write failure prints once-per-second-class errno (EIO = I2C NACK —
+  // address/wiring; ENODEV = device never initialized). A blank panel with
+  // these lines green means the failure is panel-side (power/quirks).
+  __tc_mono_frames++;
+  if (__ret != 0) {
+    printk("TC_DISPLAY: display_write failed: %d\\n", __ret);
+  } else if ((__tc_mono_frames & 0x3Fu) == 1u) {
+    printk("TC_DISPLAY: mono frame #%u pushed\\n", static_cast<unsigned int>(__tc_mono_frames));
+  }
+}
+
+// ── display_init (called from setup) ───────────────────────────────────────
+
+static inline void display_init() {
+  printk("TC_DISPLAY: ${eink ? 'e-ink deferred' : 'mono full-frame'} transport (${dtLabel}, ${w}x${h})\\n");
+  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);
+  // Rig diagnostics: what the driver reports — geometry/format mismatches
+  // print here before anything reaches the panel.
+  printk("TC_DISPLAY: panel reports %ux%u fmt=%u screen_info=%u\\n",
+         static_cast<unsigned int>(__tc_zd_caps.x_resolution),
+         static_cast<unsigned int>(__tc_zd_caps.y_resolution),
+         static_cast<unsigned int>(__tc_zd_caps.current_pixel_format),
+         static_cast<unsigned int>(__tc_zd_caps.screen_info));
+  // MONO01 (0=black, 1=white) matches our packing. A MONO10 panel gets asked
+  // to switch once; if it refuses, frames push bit-inverted (still correct).
+  if (${!eink} && __tc_zd_caps.current_pixel_format == PIXEL_FORMAT_MONO10) {
+    if (display_set_pixel_format(__tc_zd_dev, PIXEL_FORMAT_MONO01) == 0) {
+      display_get_capabilities(__tc_zd_dev, &__tc_zd_caps);
+    }
+  }
+  if (__tc_zd_caps.current_pixel_format == PIXEL_FORMAT_MONO10) {
+    __tc_mono_invert = true;
+  } else if (${!eink} && __tc_zd_caps.current_pixel_format != PIXEL_FORMAT_MONO01) {
+    printk("TC_DISPLAY: unexpected pixel format %u (expected MONO01) — 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));
+  }
+  for (size_t i = 0; i < sizeof(__tc_mono_fb); i++) __tc_mono_fb[i] = 0u;
+  (void)display_blanking_off(__tc_zd_dev);
+  display_partial_refresh(0, 0, ${w}, ${h});
+  printk("TC_DISPLAY: ${eink ? 'e-ink init done (1bpp deferred, min 2s/flash)' : 'mono init done (1bpp full-frame)'}\\n");
+}
+
+static inline void display_fillScreen(UI_COLOR_T color) {
+  const uint8_t fill = color ? 0xFFu : 0x00u;
+  for (size_t i = 0; i < sizeof(__tc_mono_fb); i++) __tc_mono_fb[i] = fill;
+}
+static inline CuttlefishDisplayTarget* display_defaultTarget() { return &__tc_display; }
+static inline int16_t display_width() { return ${w}; }
+static inline int16_t display_height() { return ${h}; }
+
+// Immediate-push no-ops: all drawing targets the backing store; the frame
+// publishes atomically in display_partial_refresh.
+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) {
+  (void)x; (void)y; (void)winW; (void)winH;
+}
+static inline void display_writePixels(const UI_COLOR_T* pixels, uint32_t count) {
+  (void)pixels; (void)count;
+}
+${CANVAS_LIFECYCLE_SECTION}${TARGET_FORWARDERS_SECTION}`;
+
+  return { includes, declaration, functions };
+}