@typecad/framework-zephyr 1.0.0-alpha.10 → 1.0.0-alpha.12

package/dist/chips/esp32.js

@@ -56,4 +56,16 @@ export const ESP32_DEVKITC = {
     // the ESP32 is AMP (dual-image procpu/appcpu), not SMP, by default — so the
     // dependency is satisfied. Omitted on radioless targets.
     wifi: { supported: true },
+    // DAC: the ESP32 has two 8-bit DAC channels on GPIO25 (channel 1) and GPIO26
+    // (channel 2). The Zephyr esp32 DAC driver (drivers/dac/dac_esp32.c) exposes
+    // them via the `dac0` node; the lowering emits dac_channel_setup +
+    // dac_write_value against DEVICE_DT_GET(DT_NODELABEL(dac0)). The overlay
+    // enables the node when the program uses dac.*. ESP32-S3 has no DAC.
+    dac: {
+        device: 'dac0',
+        channels: [
+            { pin: 25, channel: 1, resolution: 8 },
+            { pin: 26, channel: 2, resolution: 8 },
+        ],
+    },
 };

package/dist/chips/types.d.ts

@@ -81,6 +81,18 @@ export interface ZephyrAdcChannel {
     /** SAADC channel index (AIN0–AIN7). */
     readonly channel: number;
 }
+/**
+ * A DAC channel: which DAC output a given HAL pin maps to. The lowering emits
+ * `dac_channel_setup` + `dac_write_value` against the DAC device node.
+ */
+export interface ZephyrDacChannel {
+    /** GPIO number (matches the HAL op `pin` field). */
+    readonly pin: number;
+    /** DAC channel index (ESP32: GPIO25 → 1, GPIO26 → 2). */
+    readonly channel: number;
+    /** DAC resolution in bits (ESP32 DAC is 8-bit). */
+    readonly resolution: number;
+}
 /**
  * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
  */
@@ -139,10 +151,28 @@ export interface ZephyrChipDescriptor {
         /** ADC resolution in bits. */
         readonly resolution: number;
     };
+    /**
+     * DAC: the DAC device node label + the pin→channel map. Present only on chips
+     * with a DAC (ESP32 has 2 channels on GPIO25/26; ESP32-S3 and nRF52840 have
+     * none). Read by profileDiagnostics to flag dac.* usage on chips without it.
+     */
+    readonly dac?: {
+        readonly device: string;
+        readonly channels: readonly ZephyrDacChannel[];
+    };
     /** Watchdog node label, e.g. 'wdt0'. */
     readonly wdt?: {
         readonly nodeLabel: string;
     };
+    /**
+     * Hardware timers exposed as Zephyr counter devices. `instance` (the HAL
+     * hwtimer.* op's instance index) maps to `controllers[instance].nodeLabel`.
+     * Omit on chips whose counter nodes are kernel-owned or unavailable; the
+     * lowering then lowers to a comment and profileDiagnostics flags usage.
+     */
+    readonly hwtimer?: {
+        readonly controllers: readonly ZephyrBusController[];
+    };
     /**
      * WiFi capability marker. Present only on chips with a WiFi radio (ESP32-S3).
      * Read by profileDiagnostics to flag wifi.* usage on chips without a radio.

package/dist/chips/xiao-ble.js

@@ -58,4 +58,10 @@ export const XIAO_BLE = {
         ],
     },
     wdt: { nodeLabel: 'wdt0' },
+    // Hardware timer: nRF RTC1 is the free counter (RTC0 is kernel-owned by the
+    // softdevice/clock driver). The hwtimer lowering drives it as a Zephyr
+    // counter device (counter_start/stop + a top-value alarm for set_frequency).
+    // Verified against the nRF52840 SoC dtsi (rtc0/rtc1 nodes). The kernel uses
+    // RTC0 for the system tick; RTC1 is available for application use.
+    hwtimer: { controllers: [{ nodeLabel: 'rtc1' }] },
 };

package/dist/display/gfx.d.ts

@@ -10,8 +10,17 @@ export interface DisplayRuntimeResult {
     readonly fontTable: string;
 }
 /**
- * Build the display runtime C++ for a profile. The line buffer is one row
- * (width pixels × 2 bytes rgb565); fill_rect/draw_rect/draw_text compute into
- * it row-by-row and display_write each row. No full framebuffer.
+ * Build the display runtime C++ for a profile.
+ *
+ * Two rendering models, selected by `profile.colorFormat`:
+ *  - `'rgb565'` (TFT): a one-row line buffer (no full framebuffer — see
+ *    AGENTS.md rendering guardrails); fill_rect/draw_rect/draw_text stream
+ *    each row via display_write.
+ *  - `'mono'` (OLED, e.g. SSD1306): a full framebuffer — the standard model
+ *    for page-buffered monochrome panels (the AGENTS.md "no full framebuffer"
+ *    guardrail targets RGB SPI TFTs, not mono OLEDs). draw ops set bits;
+ *    display_flush pushes the whole framebuffer. The MONO01 packing is
+ *    horizontal, MSB-first (Zephyr convention): byte = (y*rowBytes)+(x>>3),
+ *    bit = 0x80>>(x&7).
  */
 export declare function buildDisplayRuntime(profile: ZephyrDisplayProfile): DisplayRuntimeResult;

package/dist/display/gfx.js

@@ -71,18 +71,23 @@ function fontTableCpp() {
     return lines.join('\n');
 }
 /**
- * Build the display runtime C++ for a profile. The line buffer is one row
- * (width pixels × 2 bytes rgb565); fill_rect/draw_rect/draw_text compute into
- * it row-by-row and display_write each row. No full framebuffer.
+ * Build the display runtime C++ for a profile.
+ *
+ * Two rendering models, selected by `profile.colorFormat`:
+ *  - `'rgb565'` (TFT): a one-row line buffer (no full framebuffer — see
+ *    AGENTS.md rendering guardrails); fill_rect/draw_rect/draw_text stream
+ *    each row via display_write.
+ *  - `'mono'` (OLED, e.g. SSD1306): a full framebuffer — the standard model
+ *    for page-buffered monochrome panels (the AGENTS.md "no full framebuffer"
+ *    guardrail targets RGB SPI TFTs, not mono OLEDs). draw ops set bits;
+ *    display_flush pushes the whole framebuffer. The MONO01 packing is
+ *    horizontal, MSB-first (Zephyr convention): byte = (y*rowBytes)+(x>>3),
+ *    bit = 0x80>>(x&7).
  */
 export function buildDisplayRuntime(profile) {
     const w = profile.width;
-    const stateLines = [
-        '// CUTTLEFISH_DISPLAY_BEGIN',
-        `static const struct device* __tc_display = DEVICE_DT_GET(DT_NODELABEL(${profile.dtLabel}));`,
-        `static uint16_t __tc_display_line[${w}];  // one-row line buffer (rgb565)`,
-        '// CUTTLEFISH_DISPLAY_END',
-    ];
+    const h = profile.height;
+    const isMono = profile.colorFormat === 'mono';
     // Backlight is optional: the overlay emits the DT alias only when a backlight
     // GPIO is configured. Guard with DT_HAS_ALIAS so this compiles whether or not
     // the alias exists (DT_NODE_HAS_STATUS(DT_ALIAS(...)) is version-dependent
@@ -90,7 +95,122 @@ export function buildDisplayRuntime(profile) {
     const blInit = profile.backlight
         ? `#if DT_HAS_ALIAS(${profile.backlight})\n    const struct device* __bl = DEVICE_DT_GET(DT_ALIAS(${profile.backlight}));\n    gpio_pin_configure(__bl, 0, GPIO_OUTPUT); gpio_pin_set(__bl, 0, 1);\n#endif`
         : '';
-    const helpers = `
+    const stateLines = isMono
+        ? [
+            '// CUTTLEFISH_DISPLAY_BEGIN',
+            `static const struct device* __tc_display = DEVICE_DT_GET(DT_NODELABEL(${profile.dtLabel}));`,
+            `// Mono framebuffer (Zephyr MONO01: horizontal, MSB-first). ${(w + 7) >> 3} bytes/row x ${h} rows.`,
+            `static uint8_t __tc_display_fb[((${w} * ${h}) + 7) / 8];`,
+            '// CUTTLEFISH_DISPLAY_END',
+        ]
+        : [
+            '// CUTTLEFISH_DISPLAY_BEGIN',
+            `static const struct device* __tc_display = DEVICE_DT_GET(DT_NODELABEL(${profile.dtLabel}));`,
+            `static uint16_t __tc_display_line[${w}];  // one-row line buffer (rgb565)`,
+            '// CUTTLEFISH_DISPLAY_END',
+        ];
+    const helpers = isMono
+        ? monoHelpers(w, h, blInit)
+        : rgb565Helpers(w, blInit);
+    const fontTable = fontTableCpp();
+    return {
+        includes: ['<zephyr/drivers/display.h>'],
+        stateLines,
+        helpers,
+        fontTable,
+    };
+}
+/**
+ * Mono (OLED) helpers: a full framebuffer + bit-packing. SSD1306-class panels
+ * are page-buffered, so draw ops set bits in the framebuffer and display_flush
+ * pushes the whole buffer. color != 0 ⇒ lit.
+ */
+function monoHelpers(w, h, blInit) {
+    const rowBytes = (w + 7) >> 3; // bytes per row (w is byte-aligned for 128-wide panels)
+    return `
+// MONO01 pixel packing: byte = (y * ${rowBytes}) + (x >> 3), bit = 0x80 >> (x & 7).
+static inline void __tc_set_pixel(uint16_t x, uint16_t y, uint8_t on) {
+    if ((x >= ${w}U) || (y >= ${h}U)) { return; }
+    uint16_t idx = static_cast<uint16_t>((static_cast<uint32_t>(y) * ${rowBytes}U) + (x >> 3));
+    uint8_t mask = static_cast<uint8_t>(0x80U >> (x & 7U));
+    if (on != 0U) {
+        __tc_display_fb[idx] = static_cast<uint8_t>(__tc_display_fb[idx] | mask);
+    } else {
+        __tc_display_fb[idx] = static_cast<uint8_t>(__tc_display_fb[idx] & static_cast<uint8_t>(~mask));
+    }
+}
+
+static inline void display_init(void) {
+    if (!device_is_ready(__tc_display)) { for (;;) { k_msleep(1000); } }
+${blInit}
+    for (uint16_t i = 0; i < static_cast<uint16_t>(sizeof(__tc_display_fb)); i++) { __tc_display_fb[i] = 0U; }
+    display_blanking_off(__tc_display);
+}
+
+static inline void display_fill_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t rh, uint16_t color) {
+    uint8_t on = (color != 0U) ? 1U : 0U;
+    for (uint16_t row = 0; row < rh; row++) {
+        for (uint16_t i = 0; i < rw; i++) {
+            __tc_set_pixel(static_cast<uint16_t>(x + i), static_cast<uint16_t>(y + row), on);
+        }
+    }
+}
+
+static inline void display_draw_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t rh, uint16_t color) {
+    uint8_t on = (color != 0U) ? 1U : 0U;
+    for (uint16_t i = 0; i < rw; i++) {
+        __tc_set_pixel(static_cast<uint16_t>(x + i), y, on);
+        __tc_set_pixel(static_cast<uint16_t>(x + i), static_cast<uint16_t>(y + rh - 1U), on);
+    }
+    for (uint16_t row = 1U; row < rh - 1U; row++) {
+        __tc_set_pixel(x, static_cast<uint16_t>(y + row), on);
+        __tc_set_pixel(static_cast<uint16_t>(x + rw - 1U), static_cast<uint16_t>(y + row), on);
+    }
+}
+
+static inline void display_draw_text(uint16_t x, uint16_t y, const char* text, uint16_t color) {
+    uint8_t on = (color != 0U) ? 1U : 0U;
+    uint16_t cx = x;
+    for (const char* p = text; *p != 0; p++) {
+        uint8_t uc = static_cast<uint8_t>(*p);
+        if (uc >= 128U) { uc = static_cast<uint8_t>(' '); }
+        const uint8_t* glyph = &__tc_font5x7[uc][0];
+        if (uc >= static_cast<uint8_t>('a') && uc <= static_cast<uint8_t>('z')) {
+            glyph = &__tc_font5x7[uc - 32U][0];
+        } else if (uc < static_cast<uint8_t>('0')
+                   || (uc > static_cast<uint8_t>('9') && uc < static_cast<uint8_t>('A'))
+                   || uc > static_cast<uint8_t>('Z')) {
+            glyph = &__tc_font5x7[static_cast<uint8_t>(' ')][0];
+        }
+        for (uint16_t col = 0; col < 5U; col++) {
+            uint8_t bits = glyph[col];
+            for (uint16_t row = 0; row < 7U; row++) {
+                if ((bits & static_cast<uint8_t>(1U << row)) != 0U) {
+                    __tc_set_pixel(static_cast<uint16_t>(cx + col), static_cast<uint16_t>(y + row), on);
+                }
+            }
+        }
+        cx = static_cast<uint16_t>(cx + 6U);
+    }
+}
+
+static inline void display_flush(void) {
+    struct display_buffer_descriptor __desc;
+    __desc.buf_size = sizeof(__tc_display_fb);   // ${rowBytes} * ${h} bytes
+    __desc.width = ${w}U;
+    __desc.height = ${h}U;
+    __desc.pitch = ${rowBytes}U;                  // bytes per row
+    __desc.frame_incomplete = false;
+    (void)display_write(__tc_display, 0, 0, &__desc, __tc_display_fb);
+}
+`;
+}
+/**
+ * RGB565 (TFT) helpers: a one-row line buffer; each op streams rows via
+ * display_write. No full framebuffer (AGENTS.md rendering guardrails).
+ */
+function rgb565Helpers(w, blInit) {
+    return `
 // Write a single row of \`rw\` rgb565 pixels at (x,y). Builds the
 // display_buffer_descriptor the Zephyr display_write API requires (rgb565 =
 // 2 bytes/pixel) and pushes the one-row line buffer.
@@ -161,11 +281,4 @@ static inline void display_flush(void) {
     // No-op: writes are immediate via display_write; there is no framebuffer to push.
 }
 `;
-    const fontTable = fontTableCpp();
-    return {
-        includes: ['<zephyr/drivers/display.h>'],
-        stateLines,
-        helpers,
-        fontTable,
-    };
 }

package/dist/display/profiles.d.ts

@@ -15,7 +15,32 @@ export interface ZephyrDisplayProfile {
     readonly rotation?: number;
     /** DT alias for the backlight GPIO (set high at init), if any. */
     readonly backlight?: string;
+    /** Panel controller the direct-drive UI adapter targets. Selects the init
+     *  sequence + pixel wire format (ST7796S: 18-bit; ILI9341: 16-bit RGB565).
+     *  Required for rgb565 profiles; mono profiles use the direct-op GFX
+     *  runtime and ignore it. */
+    readonly controller?: ZephyrPanelController;
+    /** DT compatible string for the display@0 node. Defaults per controller
+     *  (see PANEL_CONTROLLER_DEFAULTS) — override only for a panel whose DT
+     *  binding differs from its controller family. */
+    readonly dtCompatible?: string;
+    /** SPI controller nodelabel the panel hangs off (and SPI touch, if any).
+     *  Default 'spi2' — the ESP32-S3 first general-purpose SPI controller. */
+    readonly busLabel?: string;
+    /** Nodelabel of the MIPI DBI bridge node carrying the dc/reset GPIOs.
+     *  Default 'mipi_dbi' (the overlay emits the bridge under that label). */
+    readonly bridgeLabel?: string;
 }
+/** Panel controllers the direct-drive UI adapter knows how to init. */
+export type ZephyrPanelController = 'st7796s' | 'ili9341';
+/** Per-controller DT + transport defaults, shared by the overlay generator
+ *  (DT node props) and the UI adapter (init sequence + wire format). */
+export declare const PANEL_CONTROLLER_DEFAULTS: Record<ZephyrPanelController, {
+    dtCompatible: string;
+}>;
+/** Resolve a profile's panel controller, inferring it from the driver id when
+ *  the profile doesn't declare one (the '<controller>-zephyr' naming scheme). */
+export declare function panelControllerFor(profile: Pick<ZephyrDisplayProfile, 'driver' | 'controller'>): ZephyrPanelController;
 /**
  * Built-in profile registry. Looked up by driver id. Add a profile here when a
  * new board's display node is wired into its devicetree.

package/dist/display/profiles.js

@@ -6,6 +6,21 @@
 // pin wiring. The GFX runtime (gfx.ts) reads width/height/colorFormat from the
 // active profile to size its line buffer.
 // ---------------------------------------------------------------------------
+/** Per-controller DT + transport defaults, shared by the overlay generator
+ *  (DT node props) and the UI adapter (init sequence + wire format). */
+export const PANEL_CONTROLLER_DEFAULTS = {
+    st7796s: { dtCompatible: 'sitronix,st7796s' },
+    ili9341: { dtCompatible: 'ilitek,ili9341' },
+};
+/** Resolve a profile's panel controller, inferring it from the driver id when
+ *  the profile doesn't declare one (the '<controller>-zephyr' naming scheme). */
+export function panelControllerFor(profile) {
+    if (profile.controller)
+        return profile.controller;
+    if (profile.driver.startsWith('ili9341'))
+        return 'ili9341';
+    return 'st7796s';
+}
 /**
  * Built-in profile registry. Looked up by driver id. Add a profile here when a
  * new board's display node is wired into its devicetree.
@@ -17,6 +32,7 @@ export const ZEPHYR_DISPLAY_PROFILES = {
         width: 320,
         height: 240,
         colorFormat: 'rgb565',
+        controller: 'ili9341',
         rotation: 90,
         backlight: 'backlight',
     },
@@ -33,9 +49,23 @@ export const ZEPHYR_DISPLAY_PROFILES = {
         nativeWidth: 320,
         nativeHeight: 480,
         colorFormat: 'rgb565',
+        controller: 'st7796s',
         rotation: 1,
         backlight: 'backlight',
     },
+    'ssd1306-zephyr': {
+        // Monochrome OLED (SSD1306-class, 128x64, 1bpp). Driven through Zephyr's
+        // generic display API (the ssd1306 driver + a DT display node). The GFX
+        // runtime (gfx.ts mono branch) keeps a full page-framebuffer and pushes it
+        // on display_flush — the standard model for page-buffered OLEDs. Direct
+        // display.* ops only (no @typecad/ui CuttlefishGFX rendering on mono).
+        driver: 'ssd1306-zephyr',
+        dtLabel: 'display0',
+        width: 128,
+        height: 64,
+        colorFormat: 'mono',
+        rotation: 0,
+    },
 };
 /** The default profile used when resolveDisplayOp is probed without a display.init. */
 export const DEFAULT_ZEPHYR_DISPLAY_PROFILE = ZEPHYR_DISPLAY_PROFILES['ili9341-zephyr'];

package/dist/display/touch-adapter.d.ts

@@ -1,9 +1,8 @@
 import type { TouchAdapterCodegen } from "@typecad/cuttlefish/api/shared";
 import type { TouchProfile } from "@typecad/cuttlefish/api/shared";
 /**
- * Generate the FT6336U touch adapter for Zephyr. Emits touch_init /
- * touch_isTouched / touch_readRaw — the three symbols the runtime's
- * ui_poll_touch body calls. Returns undefined for other libraries so the
- * strategy can decline.
+ * Generate a Zephyr touch adapter for the profile's library. Returns
+ * undefined for libraries this framework doesn't handle so the strategy can
+ * decline and cuttlefish surfaces a clear error.
  */
 export declare function zephyrTouchAdapter(touch: TouchProfile): TouchAdapterCodegen | undefined;

package/dist/display/touch-adapter.js

@@ -1,29 +1,132 @@
 // ---------------------------------------------------------------------------
-// Zephyr touch adapter for the Cuttlefish UI rendering pipeline.
+// Zephyr touch adapters for the Cuttlefish UI rendering pipeline.
 //
-// FT6336U capacitive touch controller over I2C, driven via Zephyr's
-// device-tree-bound I2C API (i2c_write_read_dt). This is the Zephyr analog of
-// the Arduino FT6336U adapter in framework-arduino (touch-adapters-codegen.ts)
-// and the stale native ESP32 reference (demo-display/.../main.cc).
+// 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.
 //
-// The touch node is resolved via DEVICE_DT_GET(DT_NODELABEL(ft6336u)). The
-// board's devicetree must carry an `ft6336u` nodelabel with the I2C spec +
-// the `focaltech,ft6336u` (or compatible) binding so the device is ready.
+// The adapters emit touch_init / touch_isTouched / touch_readRaw — the three
+// symbols the runtime's ui_poll_touch body calls.
 //
 // EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
 // Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
 // ---------------------------------------------------------------------------
 /**
- * Generate the FT6336U touch adapter for Zephyr. Emits touch_init /
- * touch_isTouched / touch_readRaw — the three symbols the runtime's
- * ui_poll_touch body calls. Returns undefined for other libraries so the
- * strategy can decline.
+ * Generate a Zephyr touch adapter for the profile's library. Returns
+ * undefined for libraries this framework doesn't handle so the strategy can
+ * decline and cuttlefish surfaces a clear error.
  */
 export function zephyrTouchAdapter(touch) {
-    if (touch.library !== "FT6336U")
-        return undefined;
-    const addr = touch.i2cAddress ?? 0x38;
-    const addrHex = "0x" + addr.toString(16).toUpperCase();
+    if (touch.library === "XPT2046_Touchscreen")
+        return xpt2046Adapter(touch);
+    if (touch.library === "FT6336U")
+        return ft6336uAdapter(touch);
+    return undefined;
+}
+/** XPT2046 control bytes (12-bit differential mode, auto power-down). */
+const XPT2046_CMD_X = 0x90;
+const XPT2046_CMD_Y = 0xd0;
+const XPT2046_CMD_Z1 = 0xb0;
+const hex = (v) => `0x${v.toString(16).toUpperCase()}`;
+function xpt2046Adapter(touch) {
+    // Pen-detect Z1 threshold (raw 12-bit counts). Resistive panels need a few
+    // hundred counts above noise; the TouchProfile default (10) is far too low
+    // for raw Z1, so the adapter defaults to 400 (the Arduino XPT2046
+    // library's Z_THRESHOLD) unless the config sets one explicitly.
+    const zThreshold = touch.minPressure ?? 400;
+    return {
+        includes: [
+            `#include <zephyr/kernel.h>`,
+            `#include <zephyr/drivers/spi.h>`,
+            `#include <zephyr/drivers/gpio.h>`,
+        ],
+        declaration: [
+            `// Zephyr XPT2046 resistive touch — SPI device resolved via devicetree.`,
+            `// The overlay defines the 'xpt2046' nodelabel on the panel's SPI bus`,
+            `// (CS index 1) with the xptek,xpt2046 binding; the bus + CS + 2.5MHz`,
+            `// ceiling come from that node. Raw X/Y/Z1 values are reported — the`,
+            `// runtime applies the profile calibration + rotation.`,
+            `static const struct spi_dt_spec __tc_touch =`,
+            `    SPI_DT_SPEC_GET(DT_NODELABEL(xpt2046), SPI_OP_MODE_MASTER | SPI_WORD_SET(8), 0U);`,
+            `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;`,
+            `#if DT_NODE_HAS_PROP(DT_NODELABEL(xpt2046), int_gpios)`,
+            `static const struct gpio_dt_spec __tc_touch_irq = GPIO_DT_SPEC_GET(DT_NODELABEL(xpt2046), int_gpios);`,
+            `static uint8_t __tc_touch_irq_ready = 0;`,
+            `#endif`,
+        ].join("\n"),
+        functions: [
+            `// One XPT2046 conversion: clock out a control byte, read the 12-bit`,
+            `// result. The rx byte during the command phase is a dummy; the value is`,
+            `// MSB-aligned across the following 16 bits ((b1<<8 | b2) >> 3). The`,
+            `// control byte's PD bits are 00 (auto power-down between transactions),`,
+            `// so the bus stays shareable with the panel. Touch is polled every frame`,
+            `// from ui_poll_touch, so a failed transfer is non-fatal — returns 0 and`,
+            `// touch_isTouched() reports false.`,
+            `static uint16_t __tc_xpt_read(uint8_t cmd) {`,
+            `  if (!device_is_ready(__tc_touch.bus)) return 0U;`,
+            `  uint8_t __tx[3] = { cmd, 0U, 0U };`,
+            `  uint8_t __rx[3] = { 0U, 0U, 0U };`,
+            `  struct spi_buf __bt = { __tx, sizeof(__tx) };`,
+            `  struct spi_buf __br = { __rx, sizeof(__rx) };`,
+            `  struct spi_buf_set __st = { &__bt, 1 };`,
+            `  struct spi_buf_set __sr = { &__br, 1 };`,
+            `  if (spi_transceive_dt(&__tc_touch, &__st, &__sr) != 0) return 0U;`,
+            `  return static_cast<uint16_t>(((static_cast<uint16_t>(__rx[1]) << 8) | __rx[2]) >> 3);`,
+            `}`,
+            ``,
+            `static inline void touch_init() {`,
+            `  // The SPI bus + CS are configured by devicetree. Configure the pen IRQ`,
+            `  // input (active low) when the overlay wired it — the cheap detect path.`,
+            `#if DT_NODE_HAS_PROP(DT_NODELABEL(xpt2046), int_gpios)`,
+            `  if (device_is_ready(__tc_touch_irq.port)) {`,
+            `    gpio_pin_configure_dt(&__tc_touch_irq, GPIO_INPUT);`,
+            `    __tc_touch_irq_ready = 1U;`,
+            `  }`,
+            `#endif`,
+            `  (void)device_is_ready(__tc_touch.bus);`,
+            `}`,
+            ``,
+            `static inline bool touch_isTouched() {`,
+            `  __tc_touch_cached_valid = 0;`,
+            `  __tc_touch_cached_z = 0;`,
+            `#if DT_NODE_HAS_PROP(DT_NODELABEL(xpt2046), int_gpios)`,
+            `  if (__tc_touch_irq_ready != 0U) {`,
+            `    // PENIRQ asserts (active low) while the panel is pressed — no SPI`,
+            `    // traffic needed to answer the per-frame poll.`,
+            `    if (gpio_pin_get_dt(&__tc_touch_irq) <= 0) return false;`,
+            `  }`,
+            `#endif`,
+            `  // No IRQ (or it fired): confirm via Z1 pressure before reading coords.`,
+            `  uint16_t __z1 = __tc_xpt_read(${hex(XPT2046_CMD_Z1)});`,
+            `  if (__z1 <= ${zThreshold}) return false;`,
+            `  __tc_touch_cached_x = static_cast<int16_t>(__tc_xpt_read(${hex(XPT2046_CMD_X)}));`,
+            `  __tc_touch_cached_y = static_cast<int16_t>(__tc_xpt_read(${hex(XPT2046_CMD_Y)}));`,
+            `  __tc_touch_cached_z = static_cast<int16_t>(__z1);`,
+            `  __tc_touch_cached_valid = 1;`,
+            `  return true;`,
+            `}`,
+            ``,
+            `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();`,
+            `  }`,
+            `  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;`,
+            `}`,
+        ].join("\n"),
+    };
+}
+function ft6336uAdapter(_touch) {
     return {
         includes: [
             `#include <zephyr/drivers/i2c.h>`,