@typecad/framework-zephyr 1.0.0-alpha.10

package/src/chips/types.ts

@@ -0,0 +1,163 @@
+// ---------------------------------------------------------------------------
+// Zephyr chip descriptor — pure-data model
+//
+// Mirrors the per-framework chip-descriptor pattern established by
+// framework-esp32 (Esp32ChipDescriptor) and framework-avr (AVRChipDescriptor):
+// the framework owns its own device-tree-derived descriptor, keyed off the
+// Zephyr board target string in frameworkData.buildTarget. The board/MCU
+// packages are deliberately NOT read at emit time (see the framework-package
+// data-flow split); this descriptor is the source the lowering reads.
+//
+// No behavior — the lowering code in src/lowering/*.ts reads getActiveChip()
+// to resolve pins to devicetree specs and raw-controller fallbacks.
+// ---------------------------------------------------------------------------
+
+/**
+ * A GPIO pin described as a devicetree spec.
+ *
+ * Zephyr addresses GPIO via `struct gpio_dt_spec` resolved from devicetree
+ * aliases/labels (e.g. DT_ALIAS(led0)). The dtSpec form is preferred because
+ * `gpio_pin_set_dt()` honors the node's polarity flags — so an active-low LED
+ * (logical 1 = LED on) is handled by the DT `GPIO_ACTIVE_LOW` flag, not by the
+ * generated C++.
+ */
+export interface ZephyrGpioDtSpec {
+  /** GPIO number — matches the HAL op `pin` field (P0.X → X, P1.X → 32+X). */
+  readonly pin: number;
+  /**
+   * Devicetree alias/nodelabel macro, e.g. `led0`, `sw0`, `led1`.
+   * Emitted as `GPIO_DT_SPEC_GET(DT_ALIAS(<dtSpec>), gpios)`.
+   */
+  readonly dtSpec: string;
+}
+
+/**
+ * A GPIO controller devicetree node, and the HAL pin-number range it owns.
+ *
+ * Most SoCs expose a single GPIO controller (nRF52840: `gpio0` owns every
+ * pin). SoCs that split GPIO across multiple devicetree nodes — e.g. the
+ * ESP32-S3 (`gpio0`: pins 0–31, `gpio1`: pins 32–48) — list one entry per
+ * controller so the lowering can route a HAL pin to the owning controller at
+ * runtime. Pin numbers match the HAL op `pin` field.
+ */
+export interface ZephyrGpioController {
+  /** Devicetree nodelabel, e.g. 'gpio0', 'gpio1'. */
+  readonly nodelabel: string;
+  /** First HAL pin number owned by this controller (inclusive). */
+  readonly minPin: number;
+  /** Last HAL pin number owned by this controller (inclusive). */
+  readonly maxPin: number;
+}
+
+/**
+ * A bus controller (I2C / SPI / UART) described by its devicetree nodelabel.
+ *
+ * Zephyr resolves the `const struct device*` at compile time via
+ * `DEVICE_DT_GET(DT_NODELABEL(<nodeLabel>))`, so unlike ESP-IDF there is no
+ * lazy handle resolution — the lowering emits the macro directly.
+ */
+export interface ZephyrBusController {
+  /** Devicetree nodelabel, e.g. 'i2c1', 'spi2', 'uart0'. */
+  readonly nodeLabel: string;
+}
+
+/**
+ * A PWM channel described as a devicetree spec.
+ *
+ * Emitted as `struct pwm_dt_spec __tc_pwm<N> = PWM_DT_SPEC_GET(DT_ALIAS(<dtSpec>))`.
+ * `pwm_set_pulse_dt(&__tc_pwm<N>, pulse_ns)` honors the spec's period/polarity.
+ */
+export interface ZephyrPwmSpec {
+  /** GPIO number (matches the HAL op `pin` field). */
+  readonly pin: number;
+  /** Devicetree alias, e.g. 'pwm-led0'. */
+  readonly dtSpec: string;
+}
+
+/**
+ * A GPIO pin usable as an interrupt source.
+ *
+ * Emitted as `struct gpio_dt_spec __tc_int<N> = GPIO_DT_SPEC_GET(DT_ALIAS(<dtSpec>), gpios)`
+ * + a `struct gpio_callback` registered via `gpio_add_callback`.
+ */
+export interface ZephyrInterruptPin {
+  /** GPIO number (matches the HAL op `pin` field). */
+  readonly pin: number;
+  /** Devicetree alias, e.g. 'sw0', or a nodelabel. */
+  readonly dtSpec: string;
+}
+
+/**
+ * An ADC channel: which SAADC input a given HAL pin maps to.
+ *
+ * The XIAO nRF52840 has no pre-declared ADC channel nodes in devicetree, so the
+ * lowering emits `adc_channel_setup` against `DEVICE_DT_GET(DT_NODELABEL(adc))`
+ * using the `channel` index here (SAADC AIN0–AIN7).
+ */
+export interface ZephyrAdcChannel {
+  /** GPIO number (matches the HAL op `pin` field). */
+  readonly pin: number;
+  /** SAADC channel index (AIN0–AIN7). */
+  readonly channel: number;
+}
+
+/**
+ * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
+ */
+export interface ZephyrChipDescriptor {
+  /** Zephyr board target (the `west build -b <id>` argument), e.g. 'xiao_ble'. */
+  readonly id: string;
+  /** SoC family, e.g. 'nrf52840'. */
+  readonly soc: string;
+  /**
+   * Default GPIO controller nodelabel for the raw-pin fallback. Pins not in
+   * `gpio.dtSpecs` are addressed via
+   * `DEVICE_DT_GET(DT_NODELABEL(<gpioController>))` + gpio_pin_*_raw().
+   *
+   * For SoCs that split GPIO across multiple devicetree nodes, `gpioControllers`
+   * overrides this per pin range; this field is then only the out-of-range
+   * fallback (so a single-controller board is unaffected by it).
+   */
+  readonly gpioController: string;
+  /**
+   * Per-range GPIO controllers for SoCs that split GPIO across multiple
+   * devicetree nodes (ESP32-S3: `gpio0` 0–31, `gpio1` 32–48). When present, the
+   * lowering routes a HAL pin to its owning controller at runtime via the
+   * emitted `__tc_gpio_dev(pin)` dispatcher; `gpioController` is the fallback.
+   * Omit on single-controller SoCs (nRF52840, RP2040, …) — every pin is on the
+   * one controller described by `gpioController`.
+   */
+  readonly gpioControllers?: readonly ZephyrGpioController[];
+  /** GPIO pins with devicetree specs (LEDs, buttons, board-defined pins). */
+  readonly gpio: {
+    readonly dtSpecs: readonly ZephyrGpioDtSpec[];
+    /** Interrupt-capable pins with DT specs (buttons etc.). */
+    readonly interruptPins?: readonly ZephyrInterruptPin[];
+  };
+  /** I2C controllers (board-wired). Index 0 = the primary bus. */
+  readonly i2c?: { readonly controllers: readonly ZephyrBusController[] };
+  /** SPI controllers (board-wired). Index 0 = the primary bus. */
+  readonly spi?: { readonly controllers: readonly ZephyrBusController[] };
+  /** UART controllers (board-wired). Index 0 = the primary port. */
+  readonly uart?: { readonly controllers: readonly ZephyrBusController[] };
+  /** PWM channels with DT specs. */
+  readonly pwm?: { readonly specs: readonly ZephyrPwmSpec[] };
+  /** ADC: the SAADC node label + the pin→channel map. */
+  readonly adc?: {
+    readonly nodeLabel: string;
+    readonly channels: readonly ZephyrAdcChannel[];
+    /** Reference voltage in millivolts (nRF internal = 3000 for VDD/4 + gain 1/4… use 3000). */
+    readonly vrefMv: number;
+    /** ADC resolution in bits. */
+    readonly resolution: number;
+  };
+  /** Watchdog node label, e.g. 'wdt0'. */
+  readonly wdt?: { readonly nodeLabel: string };
+  /**
+   * 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.
+   * Omit on radioless chips (nRF52840) — its absence is the "no WiFi" signal.
+   */
+  readonly wifi?: { readonly supported: true };
+}
+

package/src/chips/xiao-ble.ts

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Seeed Studio XIAO nRF52840 — Zephyr board descriptor
+//
+// Board target: `xiao_ble` (mainline Zephyr, boards/seeed/xiao_ble).
+// The onboard user LED is active-low and exposed as the DT alias `led0`.
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+
+export const XIAO_BLE: ZephyrChipDescriptor = {
+  id: 'xiao_ble',
+  soc: 'nrf52840',
+  gpioController: 'gpio0',
+  gpio: {
+    dtSpecs: [
+      // Onboard RGB LEDs — active-low (GPIO_ACTIVE_LOW in xiao_ble_common.dtsi).
+      // Verified against the board's `aliases { led0 = &led0; led1 = &led1; led2 = &led2; }`.
+      { pin: 26, dtSpec: 'led0' },  // Red   (P0.26)
+      { pin: 30, dtSpec: 'led1' },  // Green (P0.30)
+      { pin: 6, dtSpec: 'led2' },   // Blue  (P0.06)
+    ],
+    // The XIAO nRF52840 has a user button on P0.04, but mainline Zephyr's
+    // xiao_ble board (verified against Zephyr 4.3.99) does NOT expose it as a
+    // DT `sw0` alias — there is no gpio-keys node in xiao_ble.dts. Emitting
+    // GPIO_DT_SPEC_GET(DT_ALIAS(sw0), gpios) therefore fails to compile
+    // ('DT_N_ALIAS_sw0_... was not declared'). Until a button node + alias is
+    // added (via an overlay or an upstream board update), interruptPins stays
+    // empty: attachInterrupt on this board lowers to the no-DT-spec comment
+    // fallback rather than a hard compile error.
+    interruptPins: [],
+  },
+  // The XIAO connector wiring (from seeed_xiao_connector.dtsi + xiao_ble-pinctrl.dtsi):
+  //   xiao_i2c     → i2c1  (SDA P0.04/D4, SCL P0.05/D5)
+  //   xiao_spi     → spi2  (SCK P1.13/D8, MOSI P1.15/D10, MISO P1.14/D9)
+  //   xiao_serial  → uart0 (TX P1.11/D6, RX P1.12/D7)
+  // The board DTS leaves i2c0/spi0/spi1 disabled (shared instances).
+  i2c: {
+    controllers: [{ nodeLabel: 'i2c1' }],
+  },
+  spi: {
+    controllers: [{ nodeLabel: 'spi2' }],
+  },
+  uart: {
+    controllers: [{ nodeLabel: 'uart0' }],
+  },
+  pwm: {
+    // pwm-led0 drives the board PWM LED (PWM_OUT0 on P0.17, inverted).
+    specs: [{ pin: 17, dtSpec: 'pwm-led0' }],
+  },
+  adc: {
+    // SAADC node is `adc`; no pre-declared channels. XIAO D0–D3 = AIN0–AIN3
+    // (P0.02/P0.03/P0.28/P0.29). Internal VREF ~0.6V with VDD/4 gain ⇒ 3000mV.
+    nodeLabel: 'adc',
+    resolution: 12,
+    vrefMv: 3000,
+    channels: [
+      { pin: 2, channel: 0 },   // P0.02 / D0 / AIN0
+      { pin: 3, channel: 1 },   // P0.03 / D1 / AIN1
+      { pin: 28, channel: 2 },  // P0.28 / D2 / AIN2
+      { pin: 29, channel: 3 },  // P0.29 / D3 / AIN3
+    ],
+  },
+  wdt: { nodeLabel: 'wdt0' },
+};

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,
+  };
+}