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

package/dist/display/gfx.js

@@ -10,6 +10,7 @@
 // EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
 // Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
 // ---------------------------------------------------------------------------
+import { displayFactsLine } from './profiles.js';
 // 5x7 bitmap glyphs for 0-9 and A-Z. Each glyph is 5 bytes (columns), MSB=top.
 // Unknown characters fall back to the space (all-zero columns).
 // (Compact hand-authored bitmaps; the test asserts presence of '0'..'9','A'..'Z'.)
@@ -80,9 +81,8 @@ function fontTableCpp() {
  *  - `'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).
+ *    display_flush pushes the whole framebuffer as VTILED MONO01 (the layout
+ *    the driver consumes; see monoHelpers).
  */
 export function buildDisplayRuntime(profile) {
     const w = profile.width;
@@ -99,8 +99,12 @@ export function buildDisplayRuntime(profile) {
         ? [
             '// 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];`,
+            `// Mono framebuffer, vtiled MONO01 — the layout Zephyr's ssd1306-class`,
+            `// drivers expect from display_write (SCREEN_INFO_MONO_VTILED, matching`,
+            `// cfb's draw_point): byte = fb[(y>>3)*${w} + x], bit = 1<<(y&7).`,
+            `// pitch must equal width and (y, height) must be multiples of 8 — the`,
+            `// full-frame flush satisfies both by construction.`,
+            `static uint8_t __tc_display_fb[(${w} * ${h} + 7) / 8];`,
             '// CUTTLEFISH_DISPLAY_END',
         ]
         : [
@@ -115,7 +119,10 @@ export function buildDisplayRuntime(profile) {
     const fontTable = fontTableCpp();
     return {
         includes: ['<zephyr/drivers/display.h>'],
-        stateLines,
+        // Profile marker: lets the toolchain recover which profile emitted this
+        // runtime (profileFromEmittedSource in profiles.ts) instead of re-deriving
+        // geometry from the emitted C.
+        stateLines: [`// typecad-display-profile: ${profile.driver}`, displayFactsLine(profile), ...stateLines],
         helpers,
         fontTable,
     };
@@ -123,86 +130,91 @@ export function buildDisplayRuntime(profile) {
 /**
  * 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.
+ * pushes the whole buffer. color != 0 ⇒ lit. The packing is VTILED MONO01
+ * (byte = 8 vertical pixels, fb[(y>>3)*W + x], bit = 1<<(y&7)) because that
+ * is what the driver's display_write consumes — a horizontal-packed buffer
+ * with pitch = rowBytes fails the driver's pitch==width check (-EINVAL) and
+ * nothing reaches the panel.
  */
 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);
-}
+    return `
+// VTILED MONO01 pixel packing: byte = fb[(y>>3)*${w}] + x, bit = 1<<(y&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) >> 3) * ${w}U + x);
+    uint8_t mask = static_cast<uint8_t>(1U << (y & 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) {
+    // Full-frame push. pitch = width and height a multiple of 8 are the
+    // ssd1306 driver's hard requirements — the full frame satisfies both.
+    struct display_buffer_descriptor __desc;
+    __desc.buf_size = sizeof(__tc_display_fb);   // ${w} * ${h} / 8 bytes
+    __desc.width = ${w}U;
+    __desc.height = ${h}U;
+    __desc.pitch = ${w}U;                        // vtiled: bytes per 8-pixel page row == width
+    __desc.frame_incomplete = false;
+    (void)display_write(__tc_display, 0, 0, &__desc, __tc_display_fb);
+}
 `;
 }
 /**
@@ -210,75 +222,75 @@ static inline void display_flush(void) {
  * 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.
-static inline void __tc_display_write_row(uint16_t x, uint16_t y, uint16_t rw) {
-    struct display_buffer_descriptor __desc;
-    __desc.buf_size = static_cast<uint32_t>(rw) * 2U;   // 2 bytes per rgb565 pixel
-    __desc.width = rw;
-    __desc.height = 1U;
-    __desc.pitch = rw;
-    __desc.frame_incomplete = false;
-    (void)display_write(__tc_display, x, y, &__desc, __tc_display_line);
-}
-
-static inline void display_init(void) {
-    if (!device_is_ready(__tc_display)) { for (;;) { k_msleep(1000); } }
-${blInit}
-    display_blanking_off(__tc_display);
-}
-
-static inline void display_fill_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t h, uint16_t color) {
-    for (uint16_t row = 0; row < h; row++) {
-        for (uint16_t i = 0; i < rw; i++) { __tc_display_line[i] = color; }
-        __tc_display_write_row(x, static_cast<uint16_t>(y + row), rw);
-    }
-}
-
-static inline void display_draw_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t h, uint16_t color) {
-    // Top + bottom edges.
-    for (uint16_t i = 0; i < rw; i++) { __tc_display_line[i] = color; }
-    __tc_display_write_row(x, y, rw);
-    __tc_display_write_row(x, static_cast<uint16_t>(y + h - 1U), rw);
-    // Left + right edges.
-    for (uint16_t row = 1U; row < h - 1U; row++) {
-        __tc_display_line[0] = color;
-        if (rw > 1U) { __tc_display_line[rw - 1U] = color; }
-        __tc_display_write_row(x, static_cast<uint16_t>(y + row), rw);
-    }
-}
-
-static inline void display_draw_text(uint16_t x, uint16_t y, const char* text, uint16_t color) {
-    uint16_t cx = x;
-    for (const char* p = text; *p != 0; p++) {
-        // Read the byte UNSIGNED so bytes >= 0x80 don't index the 128-entry
-        // font table negatively (signed char would make 0x80 == -128).
-        uint8_t uc = static_cast<uint8_t>(*p);
-        if (uc >= 128U) { uc = static_cast<uint8_t>(' '); }     // unknown → space
-        const uint8_t* glyph = &__tc_font5x7[uc][0];
-        // Lowercase → uppercase; anything outside 0-9/A-Z → space glyph.
-        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++) {
-                __tc_display_line[0] = ((bits & static_cast<uint8_t>(1U << row)) != 0U) ? color : 0U;
-                __tc_display_write_row(static_cast<uint16_t>(cx + col), static_cast<uint16_t>(y + row), 1U);
-            }
-        }
-        cx = static_cast<uint16_t>(cx + 6U);  // 5 cols + 1 space
-    }
-}
-
-static inline void display_flush(void) {
-    // No-op: writes are immediate via display_write; there is no framebuffer to push.
-}
+    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.
+static inline void __tc_display_write_row(uint16_t x, uint16_t y, uint16_t rw) {
+    struct display_buffer_descriptor __desc;
+    __desc.buf_size = static_cast<uint32_t>(rw) * 2U;   // 2 bytes per rgb565 pixel
+    __desc.width = rw;
+    __desc.height = 1U;
+    __desc.pitch = rw;
+    __desc.frame_incomplete = false;
+    (void)display_write(__tc_display, x, y, &__desc, __tc_display_line);
+}
+
+static inline void display_init(void) {
+    if (!device_is_ready(__tc_display)) { for (;;) { k_msleep(1000); } }
+${blInit}
+    display_blanking_off(__tc_display);
+}
+
+static inline void display_fill_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t h, uint16_t color) {
+    for (uint16_t row = 0; row < h; row++) {
+        for (uint16_t i = 0; i < rw; i++) { __tc_display_line[i] = color; }
+        __tc_display_write_row(x, static_cast<uint16_t>(y + row), rw);
+    }
+}
+
+static inline void display_draw_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t h, uint16_t color) {
+    // Top + bottom edges.
+    for (uint16_t i = 0; i < rw; i++) { __tc_display_line[i] = color; }
+    __tc_display_write_row(x, y, rw);
+    __tc_display_write_row(x, static_cast<uint16_t>(y + h - 1U), rw);
+    // Left + right edges.
+    for (uint16_t row = 1U; row < h - 1U; row++) {
+        __tc_display_line[0] = color;
+        if (rw > 1U) { __tc_display_line[rw - 1U] = color; }
+        __tc_display_write_row(x, static_cast<uint16_t>(y + row), rw);
+    }
+}
+
+static inline void display_draw_text(uint16_t x, uint16_t y, const char* text, uint16_t color) {
+    uint16_t cx = x;
+    for (const char* p = text; *p != 0; p++) {
+        // Read the byte UNSIGNED so bytes >= 0x80 don't index the 128-entry
+        // font table negatively (signed char would make 0x80 == -128).
+        uint8_t uc = static_cast<uint8_t>(*p);
+        if (uc >= 128U) { uc = static_cast<uint8_t>(' '); }     // unknown → space
+        const uint8_t* glyph = &__tc_font5x7[uc][0];
+        // Lowercase → uppercase; anything outside 0-9/A-Z → space glyph.
+        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++) {
+                __tc_display_line[0] = ((bits & static_cast<uint8_t>(1U << row)) != 0U) ? color : 0U;
+                __tc_display_write_row(static_cast<uint16_t>(cx + col), static_cast<uint16_t>(y + row), 1U);
+            }
+        }
+        cx = static_cast<uint16_t>(cx + 6U);  // 5 cols + 1 space
+    }
+}
+
+static inline void display_flush(void) {
+    // No-op: writes are immediate via display_write; there is no framebuffer to push.
+}
 `;
 }

package/dist/display/index.js

@@ -10,7 +10,7 @@
 // init, so when state is uninitialized we seed the DEFAULT profile and lower
 // anyway (the probe only checks code/expression is non-undefined).
 // ---------------------------------------------------------------------------
-import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
+import { DEFAULT_ZEPHYR_DISPLAY_PROFILE, ZEPHYR_DISPLAY_PROFILES, synthesizeZephyrProfile } from './profiles.js';
 // Re-export the UI display/touch adapters + profile registry so the strategy
 // and consumers can reach them from the package barrel.
 export { zephyrUiDisplayAdapter, zephyrDisplayAdapterGenerator } from './ui-adapter.js';
@@ -30,6 +30,25 @@ export function resolveZephyrDisplayOp(op, state) {
     // fields, so use the default profile.
     if (op.operation === 'display.init') {
         state.initialized = true;
+        // Drop-in panels (driver = DT compatible): seed the synthesized profile
+        // so the direct-op GFX runtime sizes itself for THIS panel (the mono
+        // framebuffer branch keys off the profile's colorFormat/geometry). The
+        // op carries the resolved profile's colorFormat — explicit mono wins;
+        // otherwise the compatible table decides (ssd1306-class → mono).
+        const registered = ZEPHYR_DISPLAY_PROFILES[o.driver];
+        if (registered) {
+            state.profile = registered;
+        }
+        else {
+            const synth = synthesizeZephyrProfile({
+                driver: o.driver,
+                width: o.width,
+                height: o.height,
+                colorFormat: o.colorFormat,
+            });
+            if (synth)
+                state.profile = synth;
+        }
         return { code: 'display_init();' };
     }
     // For non-init ops: if not initialized (validator probe path), seed the

package/dist/display/mipi-dbi-host.d.ts

@@ -0,0 +1,9 @@
+import type { ZephyrDisplayProfile } from "./profiles.js";
+/** Build the local CS-holding mipi-dbi host for a profile. Emits a device at
+ *  the overlay's bridge node (bridgeLabel) implementing
+ *  struct mipi_dbi_driver_api, plus the includes it needs. The panel driver
+ *  reaches it via DEVICE_DT_GET(DT_INST_PARENT(display0)). */
+export declare function localHoldCsDbiHost(profile: ZephyrDisplayProfile): {
+    includes: string[];
+    functions: string;
+};

package/dist/display/mipi-dbi-host.js

@@ -0,0 +1,174 @@
+// ---------------------------------------------------------------------------
+// App-local CS-holding MIPI DBI host — the 'local-hold-cs' dbiHost.
+//
+// Implements the mipi-dbi host API for the overlay's zephyr,mipi-dbi-spi node
+// with CS held across each command+data burst (GPIO-managed, DC toggled
+// mid-burst — the Adafruit ST77xx protocol the direct transport verified on
+// the clone-ST7796S rig). The stock mipi-dbi-spi driver issues the command
+// byte and its parameters as two CS-deasserted SPI transactions, which
+// scrambles clone ST77xx panels; the mipi-hold-cs DT knob that would fix it
+// is documented by the binding but unimplemented in Zephyr 4.4.2. This host
+// is that behavior, emitted app-locally — the stock bridge stays compiled
+// out (CONFIG_MIPI_DBI_SPI=n) and the in-tree panel driver (e.g.
+// sitronix,st7796s, CONFIG_ST7796S=y) binds on top unchanged.
+//
+// A bus host is a normal Zephyr extension point (11 ship in-tree); once
+// upstream implements mipi-hold-cs, this section retires and the profile's
+// dbiHost flips back to 'spi-bridge'.
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+/** Build the local CS-holding mipi-dbi host for a profile. Emits a device at
+ *  the overlay's bridge node (bridgeLabel) implementing
+ *  struct mipi_dbi_driver_api, plus the includes it needs. The panel driver
+ *  reaches it via DEVICE_DT_GET(DT_INST_PARENT(display0)). */
+export function localHoldCsDbiHost(profile) {
+    const bus = profile.busLabel ?? 'spi2';
+    const bridge = profile.bridgeLabel ?? 'mipi_dbi';
+    const includes = [
+        `#include <zephyr/drivers/mipi_dbi.h>`,
+        `#include <zephyr/drivers/spi.h>`,
+    ];
+    const functions = `
+// ── App-local MIPI DBI host (CS held across command+data) ───────────────
+// The mipi-hold-cs behavior the zephyr,mipi-dbi-spi child binding documents:
+// CS asserted by GPIO around each complete command+data burst (or whole
+// display write), DC toggled mid-burst. The spi_config carried in the
+// panel's mipi_dbi_config is used verbatim EXCEPT .cs, which this host
+// nulls so the SPI driver never touches the CS line mid-burst.
+static const struct gpio_dt_spec __tc_dbi_dc = GPIO_DT_SPEC_GET(DT_NODELABEL(${bridge}), dc_gpios);
+static const struct gpio_dt_spec __tc_dbi_rst = GPIO_DT_SPEC_GET(DT_NODELABEL(${bridge}), reset_gpios);
+// CS comes from the SPI bus node's cs-gpios, selected by the panel's
+// dbi config .slave (= reg). The overlay puts the panel at index 0 and an
+// SPI touch controller, if any, at index 1 — each owner drives its own CS.
+static const struct gpio_dt_spec __tc_dbi_cs[] = {
+#if DT_PROP_LEN(DT_NODELABEL(${bus}), cs_gpios) > 0
+  GPIO_DT_SPEC_GET_BY_IDX(DT_NODELABEL(${bus}), cs_gpios, 0),
+#endif
+#if DT_PROP_LEN(DT_NODELABEL(${bus}), cs_gpios) > 1
+  GPIO_DT_SPEC_GET_BY_IDX(DT_NODELABEL(${bus}), cs_gpios, 1),
+#endif
+};
+#define __TC_DBI_CS_COUNT (sizeof(__tc_dbi_cs) / sizeof(__tc_dbi_cs[0]))
+// Staging buffer for display writes: display_write buffers may live in PSRAM
+// (not DMA-capable on ESP32); chunked SRAM staging is the pattern the direct
+// transport proved on this rig. Reused, never per-frame (AGENTS.md).
+static uint8_t __tc_dbi_bounce[4096];
+
+static const struct gpio_dt_spec* __tc_dbi_cs_for(const struct mipi_dbi_config* cfg) {
+  if (cfg->config.slave >= __TC_DBI_CS_COUNT) return nullptr;
+  return &__tc_dbi_cs[cfg->config.slave];
+}
+
+// One command byte (DC low) + its parameters (DC high) under one CS burst.
+static int __tc_dbi_command_write(const struct device* /*dev*/,
+                                  const struct mipi_dbi_config* cfg,
+                                  uint8_t cmd, const uint8_t* data, size_t len) {
+  const struct gpio_dt_spec* cs = __tc_dbi_cs_for(cfg);
+  if (cs == nullptr) return -EIO;
+  struct spi_config sc = cfg->config;
+  // This host owns CS — keep the SPI core off it. Both fields matter in
+  // Zephyr 4.4: the core gates on cs.cs_is_gpio (NOT the port pointer), and
+  // leaving it set makes spi_context_cs_control deref the port-less spec
+  // (EXCCAUSE 28 on the first panel init command — verified on hardware).
+  sc.cs.cs_is_gpio = false;
+  sc.cs.gpio.port = nullptr;
+  struct spi_buf __cb = { &cmd, 1 };
+  struct spi_buf_set __csb = { &__cb, 1 };
+  gpio_pin_set_dt(cs, 1);
+  gpio_pin_set_dt(&__tc_dbi_dc, 0);
+  int ret = spi_write(DEVICE_DT_GET(DT_NODELABEL(${bus})), &sc, &__csb);
+  if ((ret == 0) && (len > 0)) {
+    struct spi_buf __db = { const_cast<uint8_t*>(data), len };
+    struct spi_buf_set __dsb = { &__db, 1 };
+    gpio_pin_set_dt(&__tc_dbi_dc, 1);
+    ret = spi_write(DEVICE_DT_GET(DT_NODELABEL(${bus})), &sc, &__dsb);
+  }
+  gpio_pin_set_dt(cs, 0);
+  return ret;
+}
+
+// Write-only host: the bridge node carries 'write-only' (no MISO readback
+// path is wired for these panels).
+static int __tc_dbi_command_read(const struct device* /*dev*/,
+                                 const struct mipi_dbi_config* /*cfg*/,
+                                 uint8_t* /*cmds*/, size_t /*num_cmds*/,
+                                 uint8_t* /*response*/, size_t /*len*/) {
+  return -ENOTSUP;
+}
+
+// Stream desc->buf_size bytes to the panel (DC high) under one CS assertion,
+// chunked through the SRAM bounce buffer.
+static int __tc_dbi_write_display(const struct device* /*dev*/,
+                                  const struct mipi_dbi_config* cfg,
+                                  const uint8_t* framebuf,
+                                  struct display_buffer_descriptor* desc,
+                                  enum display_pixel_format /*pixfmt*/) {
+  const struct gpio_dt_spec* cs = __tc_dbi_cs_for(cfg);
+  if (cs == nullptr) return -EIO;
+  struct spi_config sc = cfg->config;
+  sc.cs.cs_is_gpio = false;
+  sc.cs.gpio.port = nullptr;
+  gpio_pin_set_dt(cs, 1);
+  gpio_pin_set_dt(&__tc_dbi_dc, 1);
+  const uint8_t* p = framebuf;
+  size_t remaining = desc->buf_size;
+  int ret = 0;
+  while ((remaining > 0) && (ret == 0)) {
+    size_t chunk = (remaining > sizeof(__tc_dbi_bounce)) ? sizeof(__tc_dbi_bounce) : remaining;
+    memcpy(__tc_dbi_bounce, p, chunk);
+    struct spi_buf __b = { __tc_dbi_bounce, chunk };
+    struct spi_buf_set __s = { &__b, 1 };
+    ret = spi_write(DEVICE_DT_GET(DT_NODELABEL(${bus})), &sc, &__s);
+    p += chunk;
+    remaining -= chunk;
+  }
+  gpio_pin_set_dt(cs, 0);
+  return ret;
+}
+
+// Assert reset for the requested delay, then release (the stock host's
+// semantics — st7796s calls mipi_dbi_reset(host, 100) at init).
+static int __tc_dbi_reset(const struct device* /*dev*/, k_timeout_t delay) {
+  gpio_pin_set_dt(&__tc_dbi_rst, 1);
+  k_sleep(delay);
+  return gpio_pin_set_dt(&__tc_dbi_rst, 0);
+}
+
+// Nothing is locked between calls (no per-panel spi reconfig here).
+static int __tc_dbi_release(const struct device* /*dev*/,
+                            const struct mipi_dbi_config* /*cfg*/) {
+  return 0;
+}
+
+static DEVICE_API(mipi_dbi, __tc_dbi_api) = {
+  __tc_dbi_command_write,
+  __tc_dbi_command_read,
+  __tc_dbi_write_display,
+  __tc_dbi_reset,
+  __tc_dbi_release,
+};
+
+static int __tc_dbi_host_init(const struct device* /*dev*/) {
+  if (!device_is_ready(__tc_dbi_dc.port)) return -ENODEV;
+  gpio_pin_configure_dt(&__tc_dbi_dc, GPIO_OUTPUT);
+  if (device_is_ready(__tc_dbi_rst.port)) {
+    gpio_pin_configure_dt(&__tc_dbi_rst, GPIO_OUTPUT_INACTIVE);
+  }
+  for (size_t i = 0; i < __TC_DBI_CS_COUNT; i++) {
+    if (device_is_ready(__tc_dbi_cs[i].port)) {
+      gpio_pin_configure_dt(&__tc_dbi_cs[i], GPIO_OUTPUT_INACTIVE);
+    }
+  }
+  return 0;
+}
+
+// Same init level/priority slot the stock bridge uses — panel drivers init
+// later (CONFIG_DISPLAY_INIT_PRIORITY=85 > MIPI_DBI_INIT_PRIORITY=80), so
+// the host's GPIOs are live before the panel's init commands run.
+DEVICE_DT_DEFINE(DT_NODELABEL(${bridge}), __tc_dbi_host_init, NULL, NULL, NULL,
+                 POST_KERNEL, CONFIG_MIPI_DBI_INIT_PRIORITY, &__tc_dbi_api);
+`;
+    return { includes, functions };
+}