@typecad/framework-zephyr 1.0.0-alpha.8

package/src/debug-codegen.ts

@@ -0,0 +1,207 @@
+// ---------------------------------------------------------------------------
+// Zephyr debug code generator — printk-based debug output
+//
+// The Zephyr counterpart to framework-esp32/src/debug-codegen.ts. Zephyr's
+// minimal C++ config has no <iostream> (manifest: needsIostream=false,
+// stdlibSupport.hasIostream=false), so the GenericStrategy's std::cout fallback
+// used by the debug preprocessor would NOT compile. This module routes every
+// debug line through printk("...\n") — the always-available Zephyr console,
+// with no CONFIG_CONSOLE dependency — so `cuttlefish build --debug` produces
+// compiling output.
+//
+// The halt primitive is __tc_debug_wait_for_continue() (emitted in
+// ZephyrStrategy.shimLines when --debug is active): a k_console-input / busy
+// poll that yields to the scheduler so an unattended breakpoint does not trip
+// any watchdog. ENTER continues; 's' disables this breakpoint for the run.
+//
+// Used by ZephyrStrategy's generateDebug* overrides, dispatched by the
+// cuttlefish debug preprocessor (cuttlefish/src/debug/preprocessor.ts).
+// ---------------------------------------------------------------------------
+
+export interface CapturedVariable {
+  name: string;
+  isFunction?: boolean;
+  /** Coarse C++ type category (inferred by the preprocessor without a checker). */
+  cppType?: 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
+}
+
+export interface LogMessagePart {
+  type: 'text' | 'variable';
+  value: string;
+}
+
+/**
+ * Generate the debug-mode banner. printk is always wired (Zephyr console), so
+ * there is no init to perform — just confirm debug instrumentation is live.
+ */
+export function generateZephyrInitCode(): string[] {
+  return [
+    `// === DEBUG: Zephyr console (printk) ===`,
+    `printk("[TypeCAD] Debug Mode Active\\n");`,
+    `// === END DEBUG INIT ===`,
+    ``,
+  ];
+}
+
+/**
+ * Generate Zephyr code for a breakpoint.
+ *
+ * The halt is __tc_debug_wait_for_continue() (emitted in ZephyrStrategy.shimLines
+ * under --debug): blocks until a byte arrives on the console, yielding to the
+ * scheduler between polls. The user must have a console attached (`west serial`
+ * or a terminal on the USB-CDC port); ENTER continues, 's' skips this breakpoint
+ * for the rest of the run.
+ *
+ * When `breakpointId` is set, the whole halt block is wrapped in
+ * `if (!__tc_bp_disabled_<id>)`, so a skipped breakpoint becomes a no-op until
+ * reboot. The flag is `static` so it persists across loop() iterations.
+ */
+export function generateZephyrBreakpointCode(
+  fileName: string,
+  lineNum: number,
+  originalLine: string,
+  variables: CapturedVariable[],
+  normalizedCondition: string | undefined,
+  breakpointId?: number,
+): string[] {
+  const lines: string[] = [];
+  const hasDisableGuard = breakpointId !== undefined;
+  // Each wrap level adds two spaces of indent: the disable guard (outermost)
+  // then the condition (if any).
+  const indent = '  ' + (hasDisableGuard ? '  ' : '') + (normalizedCondition ? '  ' : '');
+
+  lines.push(`  // === BREAKPOINT: ${fileName}:${lineNum} ===`);
+
+  // Disable guard: a skipped breakpoint becomes a no-op until reboot. The
+  // disable state lives in the framework's debug shim (a static registry keyed
+  // by breakpointId) — NOT as a per-breakpoint declaration here, because the
+  // transpiler mangles `static bool` declarations injected into the source.
+  if (hasDisableGuard) {
+    lines.push(`  if (!__tc_bp_is_disabled(${breakpointId})) {`);
+  }
+
+  if (normalizedCondition) {
+    lines.push(`  ${hasDisableGuard ? '  ' : ''}if (${normalizedCondition}) {`);
+  }
+
+  lines.push(`${indent}printk("----------------------------------------\\n");`);
+
+  const headerText = normalizedCondition
+    ? `[BREAK] ${fileName}:${lineNum} (condition: ${escapeString(normalizedCondition)})`
+    : `[BREAK] ${fileName}:${lineNum}`;
+  lines.push(`${indent}printk("%s\\n", "${headerText}");`);
+
+  lines.push(`${indent}printk("  %s\\n", "${escapeString(originalLine)}");`);
+
+  if (variables.length > 0) {
+    lines.push(`${indent}printk("  Variables:\\n");`);
+    for (const v of variables) {
+      if (v.isFunction) {
+        lines.push(`${indent}printk("  - %s = [function]\\n", "${v.name}");`);
+      } else {
+        const { spec, arg } = formatSpecFor(v.name, v.cppType);
+        lines.push(`${indent}printk("  - %s = ${spec}\\n", "${v.name}", ${arg});`);
+      }
+    }
+  } else {
+    lines.push(`${indent}printk("  (no variables in scope)\\n");`);
+  }
+
+  lines.push(`${indent}printk("  [ENTER: continue | s: skip this breakpoint]\\n");`);
+  lines.push(`${indent}printk("----------------------------------------\\n");`);
+
+  // Halt — block on console input, scheduler-yielding. 's' records this id as
+  // disabled in the shim's registry. Pass -1 when no id (never disable).
+  lines.push(`${indent}__tc_debug_wait_for_continue(${hasDisableGuard ? breakpointId : -1});`);
+
+  if (normalizedCondition) {
+    lines.push(`  ${hasDisableGuard ? '  ' : ''}}`);
+  }
+
+  if (hasDisableGuard) {
+    lines.push(`  }`);
+  }
+
+  lines.push(`  // === END BREAKPOINT ===`);
+
+  return lines;
+}
+
+/**
+ * Generate Zephyr code for a logpoint (logs a message without halting).
+ */
+export function generateZephyrLogpointCode(
+  fileName: string,
+  lineNum: number,
+  parts: LogMessagePart[],
+  variables: CapturedVariable[],
+): string[] {
+  const lines: string[] = [];
+
+  lines.push(`  // === LOGPOINT: ${fileName}:${lineNum} ===`);
+  lines.push(`  printk("[LOG ${fileName}:${lineNum}] ");`);
+
+  for (const part of parts) {
+    if (part.type === 'text') {
+      lines.push(`  printk("${escapeString(part.value)}");`);
+    } else {
+      // variable part: only printable if it is a non-function value in scope.
+      const match = variables.find((v) => v.name === part.value && !v.isFunction);
+      if (match) {
+        const { spec, arg } = formatSpecFor(match.name, match.cppType);
+        lines.push(`  printk("${spec}", ${arg});`);
+      } else {
+        lines.push(`  printk("{${escapeString(part.value)}}"); // variable not in scope`);
+      }
+    }
+  }
+
+  lines.push(`  printk("\\n");`);
+  lines.push(`  // === END LOGPOINT ===`);
+
+  return lines;
+}
+
+/**
+ * Escape a string for use inside printk("..."). Same rules as the ESP-IDF
+ * generator: backslash, double-quote, newline, carriage return.
+ */
+function escapeString(s: string): string {
+  return s
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r');
+}
+
+/**
+ * Pick a printk format specifier + argument expression for a debug variable.
+ *
+ * The debug preprocessor has no TypeChecker, so `cppType` is a coarse category
+ * inferred from AST shape. For `unknown` we cast to `double` and use `%g` so
+ * the generated printk always compiles for any numeric/bool variable. printk
+ * supports the standard printf format specifiers.
+ *
+ * Returns `{ spec, arg }` where `spec` is the `%`-specifier substring to embed
+ * in the format string and `arg` is the C++ argument expression.
+ */
+function formatSpecFor(
+  varName: string,
+  cppType: CapturedVariable['cppType'],
+): { spec: string; arg: string } {
+  switch (cppType) {
+    case 'bool':
+    case 'int':
+      return { spec: '%d', arg: varName };
+    case 'long':
+      return { spec: '%ld', arg: varName };
+    case 'float':
+      return { spec: '%g', arg: varName };
+    case 'string':
+      return { spec: '%s', arg: varName };
+    case 'unknown':
+    default:
+      // Cast to double so printk compiles regardless of the real C++ type.
+      return { spec: '%g', arg: `static_cast<double>(${varName})` };
+  }
+}

package/src/display/gfx.ts

@@ -0,0 +1,190 @@
+// ---------------------------------------------------------------------------
+// Zephyr display GFX runtime — generic display_write + ported GFX primitives
+//
+// Emits C++ that resolves a DT-bound display device, keeps a one-row line
+// buffer (no full framebuffer — see AGENTS.md rendering guardrails), and
+// implements fill_rect / draw_rect / draw_text / flush on top of display_write.
+// Text uses a minimal 5x7 bitmap font covering digits 0-9 and uppercase A-Z
+// only; unknown characters render as a space.
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+
+import type { ZephyrDisplayProfile } from './profiles.js';
+
+export interface DisplayRuntimeResult {
+  /** #include lines to force when the display is used. */
+  readonly includes: string[];
+  /** File-scope C++ declarations (device handle + line buffer). */
+  readonly stateLines: string[];
+  /** The C++ helper functions (display_init/fill_rect/draw_rect/draw_text/flush). */
+  readonly helpers: string;
+  /** The C++ font-table source (exposed for testing). */
+  readonly fontTable: string;
+}
+
+// 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'.)
+function fontTableCpp(): string {
+  // A flat map: char -> 5 bytes. Built so the test sees '0'..'9' and 'A'..'Z'.
+  const glyphs: Record<string, number[]> = {
+    '0': [0x3e, 0x51, 0x49, 0x45, 0x3e],
+    '1': [0x00, 0x42, 0x7f, 0x40, 0x00],
+    '2': [0x42, 0x61, 0x51, 0x49, 0x46],
+    '3': [0x21, 0x41, 0x45, 0x4b, 0x31],
+    '4': [0x18, 0x14, 0x12, 0x7f, 0x10],
+    '5': [0x27, 0x45, 0x45, 0x45, 0x39],
+    '6': [0x3c, 0x4a, 0x49, 0x49, 0x30],
+    '7': [0x01, 0x71, 0x09, 0x05, 0x03],
+    '8': [0x36, 0x49, 0x49, 0x49, 0x36],
+    '9': [0x06, 0x49, 0x49, 0x29, 0x1e],
+    'A': [0x7e, 0x11, 0x11, 0x11, 0x7e],
+    'B': [0x7f, 0x49, 0x49, 0x49, 0x36],
+    'C': [0x3e, 0x41, 0x41, 0x41, 0x22],
+    'D': [0x7f, 0x41, 0x41, 0x22, 0x1c],
+    'E': [0x7f, 0x49, 0x49, 0x49, 0x41],
+    'F': [0x7f, 0x09, 0x09, 0x09, 0x01],
+    'G': [0x3e, 0x41, 0x49, 0x49, 0x7a],
+    'H': [0x7f, 0x08, 0x08, 0x08, 0x7f],
+    'I': [0x00, 0x41, 0x7f, 0x41, 0x00],
+    'J': [0x20, 0x40, 0x41, 0x3f, 0x01],
+    'K': [0x7f, 0x08, 0x14, 0x22, 0x41],
+    'L': [0x7f, 0x40, 0x40, 0x40, 0x40],
+    'M': [0x7f, 0x02, 0x0c, 0x02, 0x7f],
+    'N': [0x7f, 0x04, 0x08, 0x10, 0x7f],
+    'O': [0x3e, 0x41, 0x41, 0x41, 0x3e],
+    'P': [0x7f, 0x09, 0x09, 0x09, 0x06],
+    'Q': [0x3e, 0x41, 0x51, 0x21, 0x5e],
+    'R': [0x7f, 0x09, 0x19, 0x29, 0x46],
+    'S': [0x46, 0x49, 0x49, 0x49, 0x31],
+    'T': [0x01, 0x01, 0x7f, 0x01, 0x01],
+    'U': [0x3f, 0x40, 0x40, 0x40, 0x3f],
+    'V': [0x1f, 0x20, 0x40, 0x20, 0x1f],
+    'W': [0x3f, 0x40, 0x38, 0x40, 0x3f],
+    'X': [0x63, 0x14, 0x08, 0x14, 0x63],
+    'Y': [0x07, 0x08, 0x70, 0x08, 0x07],
+    'Z': [0x61, 0x51, 0x49, 0x45, 0x43],
+  };
+  const lines: string[] = [
+    '// Minimal 5x7 font: digits 0-9 and uppercase A-Z. Unknown chars → space.',
+    '// (Rows for other codes are all-zero — the table is indexed by char code.)',
+    'static const uint8_t __tc_font5x7[128][5] = {',
+  ];
+  for (let c = 0; c < 128; c++) {
+    const ch = String.fromCharCode(c);
+    const known = Object.prototype.hasOwnProperty.call(glyphs, ch);
+    const g = glyphs[ch] ?? [0x00, 0x00, 0x00, 0x00, 0x00];
+    // Annotate known glyphs (0-9, A-Z) with their char literal; other rows use
+    // only the code point so the table carries no stray char literals.
+    const label = known ? ` '${ch}'` : ` ${c}`;
+    lines.push(`    {0x${g[0].toString(16).padStart(2, '0')}, 0x${g[1].toString(16).padStart(2, '0')}, 0x${g[2].toString(16).padStart(2, '0')}, 0x${g[3].toString(16).padStart(2, '0')}, 0x${g[4].toString(16).padStart(2, '0')}}, //${label}`);
+  }
+  lines.push('};');
+  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.
+ */
+export function buildDisplayRuntime(profile: ZephyrDisplayProfile): DisplayRuntimeResult {
+  const w = profile.width;
+  const stateLines: string[] = [
+    '// 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',
+  ];
+
+  // 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
+  // when the alias is missing).
+  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 = `
+// 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.
+}
+`;
+
+  const fontTable = fontTableCpp();
+
+  return {
+    includes: ['<zephyr/drivers/display.h>'],
+    stateLines,
+    helpers,
+    fontTable,
+  };
+}

package/src/display/index.ts

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// Zephyr display op resolver — maps DisplayHALOp → GFX runtime calls
+//
+// resolveZephyrDisplayOp is a pure function of (op, state): the strategy holds
+// a DisplayState (mirrors Arduino's _displayCtx) and passes it in. On
+// display.init the state is seeded with the active profile; subsequent ops
+// lower to the helpers in gfx.ts.
+//
+// Validator probes call fill_rect/draw_text/draw_rect/flush WITHOUT a prior
+// init, so when state is uninitialized we seed the DEFAULT profile and lower
+// anyway (the probe only checks code/expression is non-undefined).
+// ---------------------------------------------------------------------------
+
+import type { DisplayHALOp } from '@typecad/cuttlefish/api/shared';
+import { DEFAULT_ZEPHYR_DISPLAY_PROFILE, type ZephyrDisplayProfile } 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';
+export { zephyrTouchAdapter } from './touch-adapter.js';
+export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
+export type { ZephyrDisplayProfile } from './profiles.js';
+
+export interface DisplayState {
+  initialized: boolean;
+  profile: ZephyrDisplayProfile;
+}
+
+/** Fresh display state (used by the strategy per-build). */
+export function newDisplayState(): DisplayState {
+  return { initialized: false, profile: DEFAULT_ZEPHYR_DISPLAY_PROFILE };
+}
+
+/**
+ * Resolve a display.* op. Returns { code } for statement ops, undefined when
+ * the op is not recognized.
+ */
+export function resolveZephyrDisplayOp(
+  op: DisplayHALOp,
+  state: DisplayState,
+): { code?: string; expression?: string } | undefined {
+  const o = op as any;
+
+  // display.init seeds the state. The probe payload for init has no profile
+  // fields, so use the default profile.
+  if (op.operation === 'display.init') {
+    state.initialized = true;
+    return { code: 'display_init();' };
+  }
+
+  // For non-init ops: if not initialized (validator probe path), seed the
+  // default so the op still lowers.
+  if (!state.initialized) {
+    state.initialized = true;
+    state.profile = DEFAULT_ZEPHYR_DISPLAY_PROFILE;
+  }
+
+  switch (op.operation) {
+    case 'display.fill_rect':
+      return { code: `display_fill_rect(${o.x}, ${o.y}, ${o.w}, ${o.h}, ${o.color});` };
+    case 'display.draw_rect':
+      return { code: `display_draw_rect(${o.x}, ${o.y}, ${o.w}, ${o.h}, ${o.color});` };
+    case 'display.draw_text':
+      return { code: `display_draw_text(${o.x}, ${o.y}, "${o.text}", ${o.color});` };
+    case 'display.flush':
+      return { code: 'display_flush();' };
+    default:
+      return undefined;
+  }
+}

package/src/display/profiles.ts

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Zephyr display profiles — DT-binding descriptors
+//
+// Analog of framework-arduino/src/displays/, but profiles describe a Zephyr
+// devicetree node (DT_NODELABEL) to resolve via DEVICE_DT_GET, not Adafruit
+// pin wiring. The GFX runtime (gfx.ts) reads width/height/colorFormat from the
+// active profile to size its line buffer.
+// ---------------------------------------------------------------------------
+
+export interface ZephyrDisplayProfile {
+  /** Driver id, matched against ctx.frameworkData.display / manifest drivers. */
+  readonly driver: string;
+  /** Devicetree nodelabel, e.g. 'display0'. Emitted as DT_NODELABEL(<dtLabel>). */
+  readonly dtLabel: string;
+  /** Effective (screen-space) dimensions after rotation. */
+  readonly width: number;
+  readonly height: number;
+  /** Native panel dimensions before rotation, when they differ from the
+   *  effective size (e.g. a 320x480 panel mounted landscape = 480x320). */
+  readonly nativeWidth?: number;
+  readonly nativeHeight?: number;
+  readonly colorFormat: 'rgb565' | 'mono';
+  /** Applied via display_set_orientation (0/90/180/270). */
+  readonly rotation?: number;
+  /** DT alias for the backlight GPIO (set high at init), if any. */
+  readonly backlight?: string;
+}
+
+/**
+ * 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.
+ */
+export const ZEPHYR_DISPLAY_PROFILES: Record<string, ZephyrDisplayProfile> = {
+  'ili9341-zephyr': {
+    driver: 'ili9341-zephyr',
+    dtLabel: 'display0',
+    width: 320,
+    height: 240,
+    colorFormat: 'rgb565',
+    rotation: 90,
+    backlight: 'backlight',
+  },
+  'st7796-zephyr': {
+    // ST7796S SPI TFT, 320x480 RGB565 mounted landscape (effective 480x320).
+    // Same DT nodelabel convention as the ILI9341 — the board's devicetree
+    // carries the `display0` node bound to the ST7796 driver; the overlay
+    // enables it via status="okay". Effective dims match the Arduino
+    // st7796-spi profile (480x320 landscape, rotation 1).
+    driver: 'st7796-zephyr',
+    dtLabel: 'display0',
+    width: 480,
+    height: 320,
+    nativeWidth: 320,
+    nativeHeight: 480,
+    colorFormat: 'rgb565',
+    rotation: 1,
+    backlight: 'backlight',
+  },
+};
+
+/** The default profile used when resolveDisplayOp is probed without a display.init. */
+export const DEFAULT_ZEPHYR_DISPLAY_PROFILE: ZephyrDisplayProfile =
+  ZEPHYR_DISPLAY_PROFILES['ili9341-zephyr'];

package/src/display/touch-adapter.ts

@@ -0,0 +1,100 @@
+// ---------------------------------------------------------------------------
+// Zephyr touch adapter 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).
+//
+// 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.
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+
+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.
+ */
+export function zephyrTouchAdapter(touch: TouchProfile): TouchAdapterCodegen | undefined {
+  if (touch.library !== "FT6336U") return undefined;
+
+  const addr = touch.i2cAddress ?? 0x38;
+  const addrHex = "0x" + addr.toString(16).toUpperCase();
+
+  return {
+    includes: [
+      `#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));`,
+      `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;`,
+    ].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;`,
+      `}`,
+      ``,
+      `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.`,
+      `#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)`,
+      `    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`,
+      `  }`,
+      `#endif`,
+      `  (void)device_is_ready(__tc_touch.bus);`,
+      `}`,
+      ``,
+      `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;`,
+      `}`,
+      ``,
+      `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"),
+  };
+}