@typecad/framework-zephyr 1.0.0-alpha.13 → 1.0.0-alpha.15

package/src/dt-config/overlay.ts

@@ -1,450 +1,1058 @@
-// ---------------------------------------------------------------------------
-// Devicetree overlay generator
-//
-// Generates <project>/app/boards/<board>.overlay — the standard Zephyr overlay
-// path. Content is additive: for each used peripheral with a DT binding the chip
-// descriptor knows, emit a `&nodelabel { status = "okay"; }` block enabling it.
-// West merges this over the board's base DT; we never rewrite the base.
-//
-// This is the Zephyr analog of Arduino's library-resolution hooks: the artifact
-// that brings external capabilities into a build. (Arduino does it by parsing
-// library headers into .d.ts; Zephyr does it by enabling DT nodes + Kconfig.)
-// ---------------------------------------------------------------------------
-
-import type { ZephyrChipDescriptor } from '../chips/types.js';
-import type { ZephyrDisplayProfile } from '../display/profiles.js';
-import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
-import type { KconfigUsage } from './kconfig.js';
-
-/**
- * Generate the overlay source for a board + usage. Returns the overlay text
- * (caller writes it to app/boards/<board>.overlay via writeIfChanged).
- */
-/** Display wiring from cuttlefish.config.ts (cs/dc/rst/spiFrequency/spiPins). */
-export interface DisplayWiring {
-  cs?: number;
-  dc?: number;
-  rst?: number;
-  /** Tearing-effect (TE) GPIO from display.tearingEffectPin — emitted as
-   *  te-gpios on the display DT node. Opt-in; most boards don't wire TE. */
-  tearingEffectPin?: number;
-  spiFrequency?: number;
-  /** SPI bus pins. When present, the overlay remuxes the SPI controller's
-   *  pinctrl to these pins (the board defaults rarely match a breakout's
-   *  wiring — e.g. demo-st's panel is on SCK=18/MOSI=23, not the devkitc
-   *  default 12/11). */
-  sck?: number;
-  mosi?: number;
-  miso?: number;
-  /** Optional GPIO driving the panel backlight. When set, the overlay emits a
-   *  `gpio-leds` node + DT alias (named by the profile's `backlight`) so the
-   *  display adapter can drive it high at init. When absent (e.g. the panel's
-   *  backlight is hardwired to 3.3V), no node or alias is emitted — the C++
-   *  backlight init is guarded by `DT_HAS_ALIAS` and compiles away. */
-  backlightPin?: number;
-}
-
-/** Touch wiring from cuttlefish.config.ts (irq/resetPin/sda/scl; cs for SPI
- *  resistive controllers, calibration for the XPT2046 DT binding). */
-export interface TouchWiring {
-  /** Touch controller kind — selects the DT node shape (FT6336U node on I2C0
-   *  vs XPT2046 node on the display's SPI bus). Default 'ft6336u'. */
-  controller?: 'ft6336u' | 'xpt2046';
-  irq?: number;
-  resetPin?: number;
-  sda?: number;
-  scl?: number;
-  /** XPT2046 only: SPI CS pin (second cs-gpios entry on the panel's bus). */
-  cs?: number;
-  /** XPT2046 only: raw ADC calibration — feeds the binding's min-x/max-x/
-   *  min-y/max-y (required props). Defaults span the full 12-bit range. */
-  calibration?: { xMin: number; xMax: number; yMin: number; yMax: number };
-  /** XPT2046 only: pen-detect Z1 threshold (binding's z-threshold). Resistive
-   *  panels need a few hundred 12-bit counts; default 400. */
-  minPressure?: number;
-}
-
-export interface OverlayDiagnostic {
-  severity: "warning" | "error";
-  message: string;
-}
-
-export function generateOverlay(
-  chip: ZephyrChipDescriptor,
-  usage: KconfigUsage,
-  display: ZephyrDisplayProfile | undefined,
-  wiring?: DisplayWiring,
-  touch?: TouchWiring,
-  diagnostics: OverlayDiagnostic[] = [],
-): string {
-  // An I2C touch controller with no explicit bus pins: the overlay enables
-  // i2c0 and instantiates the node, but nothing remuxes the controller to
-  // the wired SDA/SCL (the board's default I2C pins rarely match a
-  // breakout). Every I2C read then fails and touch silently does nothing —
-  // surface it at build time instead of leaving it to a multimeter.
-  if (touch && touch.controller !== 'xpt2046' && (touch.sda === undefined || touch.scl === undefined)) {
-    diagnostics.push({
-      severity: "warning",
-      message: `touch: I2C controller '${touch.controller}' has no sda/scl pins in cuttlefish.config.ts — the overlay enables the bus without a pin assignment, so the controller may never answer. Add touch.sda and touch.scl (the board's default I2C pins are rarely the wired ones).`,
-    });
-  }
-  const lines: string[] = [
-    '/* Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts. */',
-    '/* Enables peripherals the program uses. West merges this over the board DT. */',
-    '',
-  ];
-
-  // Pinctrl override blocks reference the esp32s3 pinmux tokens; the include
-  // must precede them. Emitted when the display SPI pins are overridden.
-  if (wiring?.sck !== undefined && wiring?.mosi !== undefined) {
-    lines.splice(2, 0, '#include <zephyr/dt-bindings/pinctrl/esp32s3-pinctrl.h>', '');
-  }
-
-  const block = (label: string, extra: string[] = []): void => {
-    lines.push(`&${label} {`);
-    lines.push(`    status = "okay";`);
-    for (const e of extra) lines.push(`    ${e}`);
-    lines.push('};');
-    lines.push('');
-  };
-
-  if (usage.usesI2c && chip.i2c) {
-    for (const c of chip.i2c.controllers) block(c.nodeLabel);
-  }
-  if (usage.usesSpi && chip.spi) {
-    for (const c of chip.spi.controllers) block(c.nodeLabel);
-  }
-  if (usage.usesUart && chip.uart) {
-    for (const c of chip.uart.controllers) block(c.nodeLabel);
-  }
-  // DAC: enable the chip's DAC device node when the program uses dac.*. The
-  // lowering references DEVICE_DT_GET(DT_NODELABEL(<dac.device>)).
-  if (usage.usesDac && chip.dac) {
-    block(chip.dac.device);
-  }
-  if (display) {
-    // Emit a full display DT node definition. Boards like the ESP32 devkit
-    // have no display node in their base DT, so a bare `&display0 { status }`
-    // fails (the nodelabel doesn't exist). Define the node attached to a SPI
-    // controller with the panel's compatible string + dimensions. The pin
-    // wiring (cs/dc/rst) uses ESP32 GPIO defaults from the demo config; a
-    // real board overlay would carry its own binding.
-    // An XPT2046 on the same bus needs its CS as the second cs-gpios entry,
-    // so thread it into the display block (DT assignment replaces the whole
-    // property — both entries must be written together).
-    emitDisplayNode(
-      lines,
-      display,
-      wiring,
-      touch?.controller === 'xpt2046' ? (touch?.cs ?? DEFAULT_XPT2046_CS) : undefined,
-    );
-  }
-  // Touch — FT6336U capacitive on I2C (references DT_NODELABEL(ft6336u)) or
-  // XPT2046 resistive on the display's SPI bus (references
-  // DT_NODELABEL(xpt2046)). Same rationale as the display node: the bare
-  // devkit has no such node. Gated on usesTouch (not usesI2c/chip.i2c) so it
-  // emits even when the chip descriptor doesn't declare bus controllers.
-  if (usage.usesTouch) {
-    emitTouchNode(lines, touch, display);
-  }
-
-  // Preferences (ZMS settings backend): point the settings subsystem at the
-  // board's storage_partition. The backend looks for /chosen
-  // zephyr,settings-partition first, then falls back to a fixed-partition
-  // labeled storage_partition — most Zephyr boards define that label, so this
-  // chosen entry makes the lookup explicit and survives boards that name the
-  // partition differently. It only adds a /chosen pointer (never redeclares
-  // the partition node — west errors if a node is multiply-defined).
-  if (usage.usesPreferences) {
-    lines.push('/ {');
-    lines.push('    chosen {');
-    lines.push('        zephyr,settings-partition = &storage_partition;');
-    lines.push('    };');
-    lines.push('};');
-    lines.push('');
-  }
-
-  // PSRAM: enable the psram0 DT node with the correct size. The devkitc board
-  // DT defaults to a no-PSRAM module variant (e.g. wroom_n8); a PSRAM-capable
-  // module (N16R8, N8R8) needs the node enabled + sized so the linker maps
-  // .ext_ram sections into the real PSRAM. OPI on ESP32-S3 = 8MB octal PSRAM.
-  if (usage.psram) {
-    lines.push('&psram0 {');
-    lines.push('    status = "okay";');
-    lines.push('    size = <(DT_SIZE_M(8))>;');
-    lines.push('};');
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Emit a display DT node definition. The node is attached to the profile's SPI
- * controller (default spi2, the ESP32's first user SPI controller) via a MIPI
- * DBI SPI bridge. Pin wiring comes from the display config (cs/dc/rst);
- * defaults match the demo-st wiring if absent. The compatible string + node
- * props come from the profile's panel controller (st7796s carries the required
- * pgc/ngc gamma + madctl; ili9341's binding defaults everything else).
- *
- * spiTouchCs: when an XPT2046 SPI touch controller shares the bus, its CS is
- * appended as the second cs-gpios entry (the touch node uses reg = <1>) — DT
- * property assignment replaces, so both entries must be written together.
- */
-function emitDisplayNode(
-  lines: string[],
-  display: ZephyrDisplayProfile,
-  wiring?: DisplayWiring,
-  spiTouchCs?: number,
-): void {
-  const bus = display.busLabel ?? 'spi2';
-  const controller = panelControllerFor(display);
-  const compatible = display.dtCompatible ?? PANEL_CONTROLLER_DEFAULTS[controller].dtCompatible;
-  const dc = wiring?.dc ?? 17;
-  const rst = wiring?.rst ?? 16;
-  const cs = wiring?.cs ?? 5;
-  const freq = wiring?.spiFrequency ?? 80000000;
-  // DT node describes the NATIVE panel geometry; the effective (rotated)
-  // dimensions live in the display profile.
-  const nativeW = display.nativeWidth ?? display.width;
-  const nativeH = display.nativeHeight ?? display.height;
-  const sck = wiring?.sck;
-  const mosi = wiring?.mosi;
-  const miso = wiring?.miso;
-  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
-  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
-  // The board's spim2_default pinctrl group usually targets the devkitc's
-  // default SPI pins (SCLK=12/MOSI=11), which rarely match the display's
-  // wiring. When the config declares spiPins, override the pinctrl groups to
-  // remux the controller onto the panel's actual pins. Raw ESP32_PINMUX()
-  // macros are used instead of the named SPIM2_*_GPIOxx tokens because the
-  // bindings header omits GPIOs 22-25 from those lists.
-  if (sck !== undefined && mosi !== undefined) {
-    // 'spi2' → pinctrl group 'spim2_default' (ESP32 SPI-master naming).
-    const pinctrlGroup = bus.replace(/^spi(\d)$/, 'spim$1') + '_default';
-    lines.push(`&${pinctrlGroup} {`);
-    lines.push('    group1 {');
-    lines.push(`        pinmux = <ESP32_PINMUX(${miso ?? 19}, ESP_FSPIQ_IN, ESP_NOSIG)>,`);
-    lines.push(`                 <ESP32_PINMUX(${sck}, ESP_NOSIG, ESP_FSPICLK_OUT)>,`);
-    lines.push('                 <ESP32_PINMUX(10, ESP_NOSIG, ESP_FSPICS0_OUT)>;');
-    lines.push('    };');
-    lines.push('    group2 {');
-    lines.push(`        pinmux = <ESP32_PINMUX(${mosi}, ESP_NOSIG, ESP_FSPID_OUT)>;`);
-    lines.push('        output-low;');
-    lines.push('    };');
-    lines.push('};');
-    lines.push('');
-  }
-  lines.push('&dma {');
-  lines.push('    status = "okay";');
-  lines.push('};');
-  lines.push('');
-  lines.push(`&${bus} {`);
-  lines.push('    status = "okay";');
-  lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>${spiTouchCs !== undefined ? `, <&${gpioController(spiTouchCs)} ${spiTouchCs} GPIO_ACTIVE_LOW>` : ''};`);
-  // Enable GDMA for the SPI2 host. The ESP32 SPI driver uses DMA only when
-  // dma-enabled is set AND dmas wires tx/rx channels to the GDMA controller;
-  // without it, transfers run PIO through the 64-byte FIFO (~4MHz effective at
-  // 80MHz requested). The GDMA driver allocates channels per peripheral based
-  // on spi2's dma-host=<0> (set in the SoC dtsi), so the channel cells are the
-  // GDMA instance's rx/tx slot ids (2 here = an SPI2-dedicated pair; the GDMA
-  // binding's #dma-cells = <1> carries the channel).
-  lines.push('    dma-enabled;');
-  lines.push('    dmas = <&dma 0>, <&dma 1>;');
-  lines.push('    dma-names = "rx", "tx";');
-  lines.push('};');
-  lines.push('');
-  lines.push('/ {');
-  lines.push('    mipi_dbi: mipi-dbi {');
-  lines.push('        compatible = "zephyr,mipi-dbi-spi";');
-  lines.push(`        spi-dev = <&${bus}>;`);
-  lines.push(`        dc-gpios = <&${gpioController(dc)} ${dc} GPIO_ACTIVE_HIGH>;`);
-  lines.push(`        reset-gpios = <&${gpioController(rst)} ${rst} GPIO_ACTIVE_LOW>;`);
-  lines.push('        write-only;');
-  lines.push('        #address-cells = <1>;');
-  lines.push('        #size-cells = <0>;');
-  lines.push(`        ${display.dtLabel}: display@0 {`);
-  lines.push(`            compatible = "${compatible}";`);
-  lines.push('            reg = <0>;');
-            if (wiring?.tearingEffectPin !== undefined) {
-              const tePin = wiring.tearingEffectPin!;
-              // Tearing-effect input on the display node: GPIO_DT_SPEC_GET(
-              // DT_NODELABEL(display0), te_gpios) in the adapter. Opt-in —
-              // most modules don't break the TE pad out.
-              lines.push(`            te-gpios = <&${gpioController(tePin)} ${tePin} GPIO_ACTIVE_HIGH>;`);
-            }
-            lines.push(`            mipi-max-frequency = <${freq}>;`);
-            lines.push('            mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE";');
-            // Required by the lcd-controller binding (Zephyr 4.x): 0 = RGB565,
-            // matching upstream ILI9341 boards (esp_wrover_kit) and the C++
-            // runtime, which drives these SPI TFTs as RGB565.
-            lines.push('            pixel-format = <0>;');
-  lines.push(`            width = <${nativeW}>;`);
-  lines.push(`            height = <${nativeH}>;`);
-  if (controller === 'st7796s') {
-    // MADCTL: rotation 1 (landscape, MV=1) + BGR bit, matching the adapter's
-    // direct-drive init (0x28). The DT copy keeps the stock driver's init
-    // consistent if it is ever exercised.
-    lines.push('            madctl = <0x28>;');
-    lines.push('            pgc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
-    lines.push('            ngc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
-  } else {
-    // ILI9341: the ilitek,ili9341 binding carries defaults for every register
-    // (gamma, power, porch) and expresses orientation via `rotation` (degrees)
-    // instead of a raw MADCTL — no panel-specific props are required.
-    lines.push(`            rotation = <${display.rotation ?? 0}>;`);
-  }
-  lines.push('        };');
-  lines.push('    };');
-  lines.push('};');
-  lines.push('');
-  // Backlight node: emit only when the config provides a backlight GPIO. The
-  // pin was previously hardcoded to 4, which collided with the FT6336U
-  // reset-gpios on the same pin (demo-st's backlight is hardwired to 3.3V, so
-  // no backlight node is correct there). When present, use the configured pin
-  // and the profile's alias name so the display adapter can drive it.
-  const blPin = wiring?.backlightPin;
-  if (display.backlight && blPin !== undefined) {
-    lines.push('/ {');
-    lines.push('    aliases {');
-    lines.push(`        ${display.backlight} = &bl_led;`);
-    lines.push('    };');
-    lines.push('    bl_gpio: bl-gpio-leds {');
-    lines.push('        compatible = "gpio-leds";');
-    lines.push('        bl_led: led {');
-    lines.push(`            gpios = <&${gpioController(blPin)} ${blPin} GPIO_ACTIVE_HIGH>;`);
-    lines.push('        };');
-    lines.push('    };');
-    lines.push('};');
-    lines.push('');
-  }
-}
-
-/** Default XPT2046 CS/IRQ pins (ESP32-S3 GPIOs clear of the demo-st display
- *  wiring: 5/17/16/15 and the remuxed SPI pins). Config values override. */
-const DEFAULT_XPT2046_CS = 6;
-const DEFAULT_XPT2046_IRQ = 7;
-
-/**
- * Emit the touch DT node for the configured controller.
- *
- * FT6336U (capacitive, I2C): node on i2c0 at the FT6336U default address
- * (0x38); the C++ touch adapter reads it via i2c_write_read_dt.
- *
- * XPT2046 (resistive, SPI): node on the display's SPI bus as CS index 1. The
- * in-tree xptek,xpt2046 binding (drivers/input) is register-matched for the
- * raw SPI access — CONFIG_INPUT stays off, so the in-tree input driver does
- * not build and the adapter owns the chip (same pattern as FT6336U reusing
- * the ft5336 binding). The binding requires int-gpios, touchscreen-size-*,
- * and min/max calibration props, so defaults are filled for anything the
- * config omits.
- */
-function emitTouchNode(
-  lines: string[],
-  touch: TouchWiring | undefined,
-  display: ZephyrDisplayProfile | undefined,
-): void {
-  if (touch?.controller === 'xpt2046') {
-    emitXpt2046Node(lines, touch, display);
-    return;
-  }
-  emitFt6336uNode(lines, touch);
-}
-
-/** FT6336U capacitive touch node on the first I2C controller. */
-function emitFt6336uNode(lines: string[], touch?: TouchWiring): void {
-  const irq = touch?.irq ?? 15;
-  const resetPin = touch?.resetPin;
-  const sda = touch?.sda;
-  const scl = touch?.scl;
-  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
-  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
-  // Zephyr has no ft6336 binding — the FT6336U is register-compatible with the
-  // ft5336 binding (same Focaltech register map: TD_STATUS at 0x02, coordinate
-  // registers 0x03-0x06). The C++ touch adapter reads these directly via I2C,
-  // so the binding just needs to exist for the DT node to resolve.
-  // When SDA/SCL are provided, remux the I2C bus to those pins via pinctrl
-  // (the board's default I2C pins rarely match a breakout's wiring).
-  if (sda !== undefined && scl !== undefined) {
-    lines.push('&pinctrl {');
-    lines.push('    i2c0_touch: i2c0_touch {');
-    lines.push('        group1 {');
-    lines.push(`            pinmux = <I2C0_SDA_GPIO${sda}>, <I2C0_SCL_GPIO${scl}>;`);
-    lines.push('            bias-pull-up;');
-    lines.push('            drive-open-drain;');
-    lines.push('        };');
-    lines.push('    };');
-    lines.push('};');
-    lines.push('');
-    lines.push('&i2c0 {');
-    lines.push('    status = "okay";');
-    lines.push('    pinctrl-0 = <&i2c0_touch>;');
-    lines.push('    pinctrl-names = "default";');
-  } else {
-    lines.push('&i2c0 {');
-    lines.push('    status = "okay";');
-  }
-  lines.push('    ft6336u: ft6336u@38 {');
-  lines.push('        compatible = "focaltech,ft5336";');
-  lines.push('        reg = <0x38>;');
-  // NOTE: int-gpios is intentionally omitted. The ft5336 Zephyr driver
-  // registers a GPIO interrupt on int-gpios, which triggers an assertion
-  // failure in the ESP32 interrupt controller (VECDESC_FL_SHARED conflict).
-  // The cuttlefish touch adapter polls touch_isTouched() via I2C every frame
-  // — it never uses the IRQ pin, so the interrupt registration is unnecessary.
-  if (resetPin !== undefined) {
-    lines.push(`        reset-gpios = <&${gpioController(resetPin)} ${resetPin} GPIO_ACTIVE_LOW>;`);
-  }
-  lines.push('    };');
-  lines.push('};');
-  lines.push('');
-}
-
-/** XPT2046 resistive touch node on the display's SPI bus (CS index 1). */
-function emitXpt2046Node(
-  lines: string[],
-  touch: TouchWiring,
-  display: ZephyrDisplayProfile | undefined,
-): void {
-  const bus = display?.busLabel ?? 'spi2';
-  const cs = touch.cs ?? DEFAULT_XPT2046_CS;
-  const irq = touch.irq ?? DEFAULT_XPT2046_IRQ;
-  const cal = touch.calibration;
-  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
-  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
-  const zThreshold = touch.minPressure ?? 400;
-  // touchscreen-size-* describe the panel the touch layer sits on (the display
-  // profile's effective size); a touch-only build falls back to the 12-bit
-  // full-scale range so the binding's required props still resolve.
-  const sizeX = display?.width ?? cal?.xMax ?? 320;
-  const sizeY = display?.height ?? cal?.yMax ?? 240;
-  // The display block already wrote cs-gpios with both entries (its CS at
-  // index 0, the touch CS at index 1). When there is no display block, enable
-  // the bus here with the touch CS as the only entry.
-  if (!display) {
-    lines.push(`&${bus} {`);
-    lines.push('    status = "okay";');
-    lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>;`);
-    lines.push('};');
-    lines.push('');
-  }
-  lines.push(`&${bus} {`);
-  lines.push('    xpt2046: xpt2046@1 {');
-  lines.push('        compatible = "xptek,xpt2046";');
-  lines.push('        reg = <1>;');
-  // The XPT2046 datasheet max SPI clock is 2.5MHz — the panel bus may run at
-  // 80MHz, but this node's spi-max-frequency gates only its own transactions
-  // (the adapter's SPI_DT_SPEC picks it up).
-  lines.push('        spi-max-frequency = <2500000>;');
-  lines.push(`        int-gpios = <&${gpioController(irq)} ${irq} GPIO_ACTIVE_LOW>;`);
-  lines.push(`        touchscreen-size-x = <${sizeX}>;`);
-  lines.push(`        touchscreen-size-y = <${sizeY}>;`);
-  lines.push(`        min-x = <${cal?.xMin ?? 0}>;`);
-  lines.push(`        max-x = <${cal?.xMax ?? 4095}>;`);
-  lines.push(`        min-y = <${cal?.yMin ?? 0}>;`);
-  lines.push(`        max-y = <${cal?.yMax ?? 4095}>;`);
-  lines.push(`        z-threshold = <${zThreshold}>;`);
-  lines.push('    };');
-  lines.push('};');
-  lines.push('');
-}
+// ---------------------------------------------------------------------------
+// Devicetree overlay generator
+//
+// Generates <project>/app/boards/<board>.overlay — the standard Zephyr overlay
+// path. Content is additive: for each used peripheral with a DT binding the chip
+// descriptor knows, emit a `&nodelabel { status = "okay"; }` block enabling it.
+// West merges this over the board's base DT; we never rewrite the base.
+//
+// Framework library-resolution hook: the artifact
+// that brings external capabilities into a build. (Arduino does it by parsing
+// library headers into .d.ts; Zephyr does it by enabling DT nodes + Kconfig.)
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+import type { ZephyrDisplayProfile } from '../display/profiles.js';
+import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
+import { SENSOR_PART_INFO } from '@typecad/hal';
+import type { KconfigUsage } from './kconfig.js';
+
+/** Display panel CS default — shared by the display block and the SPI-sensor
+ *  cs-gpios merge so both sites write the same entry. */
+const DEFAULT_DISPLAY_CS = 5;
+
+/**
+ * Generate the overlay source for a board + usage. Returns the overlay text
+ * (caller writes it to app/boards/<board>.overlay via writeIfChanged).
+ */
+/** Display wiring from cuttlefish.config.ts (cs/dc/rst/spiFrequency/spiPins). */
+export interface DisplayWiring {
+  cs?: number;
+  dc?: number;
+  rst?: number;
+  /** Tearing-effect (TE) GPIO from display.tearingEffectPin — emitted as
+   *  te-gpios on the display DT node. Opt-in; most boards don't wire TE. */
+  tearingEffectPin?: number;
+  spiFrequency?: number;
+  /** SPI bus pins. When present, the overlay remuxes the SPI controller's
+   *  pinctrl to these pins (the board defaults rarely match a breakout's
+   *  wiring — e.g. demo-st's panel is on SCK=18/MOSI=23, not the devkitc
+   *  default 12/11). */
+  sck?: number;
+  mosi?: number;
+  miso?: number;
+  /** Optional GPIO driving the panel backlight. When set, the overlay emits a
+   *  `gpio-leds` node + DT alias (named by the profile's `backlight`) so the
+   *  display adapter can drive it high at init. When absent (e.g. the panel's
+   *  backlight is hardwired to 3.3V), no node or alias is emitted — the C++
+   *  backlight init is guarded by `DT_HAS_ALIAS` and compiles away. */
+  backlightPin?: number;
+}
+
+/** Touch wiring from cuttlefish.config.ts (irq/resetPin/sda/scl; cs for SPI
+ *  resistive controllers, calibration for the XPT2046 DT binding). */
+export interface TouchWiring {
+  /** Touch controller kind — selects the DT node shape (FT6336U node on I2C0
+   *  vs XPT2046 node on the display's SPI bus). Default 'ft6336u'. */
+  controller?: 'ft6336u' | 'xpt2046';
+  irq?: number;
+  resetPin?: number;
+  sda?: number;
+  scl?: number;
+  /** XPT2046 only: SPI CS pin (second cs-gpios entry on the panel's bus). */
+  cs?: number;
+  /** XPT2046 only: raw ADC calibration — feeds the binding's min-x/max-x/
+   *  min-y/max-y (required props). Defaults span the full 12-bit range. */
+  calibration?: { xMin: number; xMax: number; yMin: number; yMax: number };
+  /** XPT2046 only: pen-detect Z1 threshold (binding's z-threshold). Resistive
+   *  panels need a few hundred 12-bit counts; default 400. */
+  minPressure?: number;
+}
+
+export interface OverlayDiagnostic {
+  severity: "warning" | "error";
+  message: string;
+}
+
+export function generateOverlay(
+  chip: ZephyrChipDescriptor,
+  usage: KconfigUsage,
+  display: ZephyrDisplayProfile | undefined,
+  wiring?: DisplayWiring,
+  touch?: TouchWiring,
+  diagnostics: OverlayDiagnostic[] = [],
+): string {
+  // An I2C touch controller with no explicit bus pins: the overlay enables
+  // i2c0 and instantiates the node, but nothing remuxes the controller to
+  // the wired SDA/SCL (the board's default I2C pins rarely match a
+  // breakout). Every I2C read then fails and touch silently does nothing —
+  // surface it at build time instead of leaving it to a multimeter.
+  if (touch && touch.controller !== 'xpt2046' && (touch.sda === undefined || touch.scl === undefined)) {
+    diagnostics.push({
+      severity: "warning",
+      message: `touch: I2C controller '${touch.controller}' has no sda/scl pins in cuttlefish.config.ts — the overlay enables the bus without a pin assignment, so the controller may never answer. Add touch.sda and touch.scl (the board's default I2C pins are rarely the wired ones).`,
+    });
+  }
+  const lines: string[] = [
+    '/* Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts. */',
+    '/* Enables peripherals the program uses. West merges this over the board DT. */',
+    '',
+  ];
+
+  // Pinctrl override blocks reference the esp32s3 pinmux tokens; the include
+  // must precede them. Emitted when the display SPI pins are overridden.
+  if (wiring?.sck !== undefined && wiring?.mosi !== undefined) {
+    lines.splice(2, 0, '#include <zephyr/dt-bindings/pinctrl/esp32s3-pinctrl.h>', '');
+  }
+
+  const block = (label: string, extra: string[] = []): void => {
+    lines.push(`&${label} {`);
+    lines.push(`    status = "okay";`);
+    for (const e of extra) lines.push(`    ${e}`);
+    lines.push('};');
+    lines.push('');
+  };
+
+  // Controllers whose board DT ships no default pinctrl group (rp2xxx uart1)
+  // carry synthesis data: emit the group under &pinctrl, then enable the
+  // controller referencing it. Controllers with a pinctrlRef wire an existing
+  // group instead; `props` adds raw property lines for bindings with
+  // required properties the board only sets on its own wired nodes.
+  // The pinmux header include is collected and spliced before all blocks
+  // (tokens must be defined before use).
+  const pinctrlIncludes = new Map<string, string[]>();
+  const controllerBlock = (c: { nodeLabel: string; pinctrlRef?: string; props?: readonly string[]; pinctrl?: { include: string; pinmux: readonly string[]; inputPinmux?: readonly string[]; defines?: readonly string[] } }): void => {
+    const extra: string[] = [...(c.props ?? [])];
+    if (c.pinctrl) {
+      pinctrlIncludes.set(c.pinctrl.include, c.pinctrl.defines ? [...c.pinctrl.defines] : []);
+      const group = `${c.nodeLabel}_default`;
+      lines.push('&pinctrl {');
+      lines.push(`    ${group}: ${group} {`);
+      lines.push(`        group1 {`);
+      lines.push(`            pinmux = <${c.pinctrl.pinmux.join(', ')}>;`);
+      lines.push(`        };`);
+      if (c.pinctrl.inputPinmux && c.pinctrl.inputPinmux.length > 0) {
+        lines.push(`        group2 {`);
+        lines.push(`            pinmux = <${c.pinctrl.inputPinmux.join(', ')}>;`);
+        lines.push(`            input-enable;`);
+        lines.push(`        };`);
+      }
+      lines.push(`    };`);
+      lines.push('};');
+      lines.push('');
+      extra.push(`pinctrl-0 = <&${group}>;`, `pinctrl-names = "default";`);
+    } else if (c.pinctrlRef) {
+      extra.push(`pinctrl-0 = <&${c.pinctrlRef}>;`, `pinctrl-names = "default";`);
+    }
+    block(c.nodeLabel, extra);
+  };
+
+  // Sensors ride a bus: a constructed sensor must enable its controller even
+  // when the program never calls i2c.*/spi.* directly (the sensor device
+  // handle is the only bus user) — merge their instances into the used sets.
+  const sensorParts = usage.sensorParts ?? [];
+  const i2cSensors = sensorParts.filter((s) => s.busKind !== 'spi');
+  const spiSensors = sensorParts.filter((s) => s.busKind === 'spi');
+  const spiTargets = usage.spiTargets ?? [];
+  const i2cInstances = new Set(usage.i2cUsedInstances ?? []);
+  for (const sp of i2cSensors) i2cInstances.add(sp.busIndex);
+  if ((usage.usesI2c || i2cSensors.length > 0) && chip.i2c) {
+    for (const [i, c] of chip.i2c.controllers.entries()) {
+      if (usage.i2cUsedInstances && !i2cInstances.has(i)) continue;
+      controllerBlock(c);
+    }
+  }
+  const spiInstances = new Set(usage.spiUsedInstances ?? []);
+  for (const sp of spiSensors) spiInstances.add(sp.busIndex);
+  for (const t of spiTargets) spiInstances.add(t.busIndex);
+  if ((usage.usesSpi || spiSensors.length > 0 || spiTargets.length > 0) && chip.spi) {
+    for (const [i, c] of chip.spi.controllers.entries()) {
+      if (usage.spiUsedInstances && !spiInstances.has(i)) continue;
+      controllerBlock(c);
+    }
+  }
+  // One DT child node per constructed I2C sensor — THE enable switch for the
+  // driver (its Kconfig is `default y` on this node's presence). The nodelabel
+  // is derived identically to the lowering's DEVICE_DT_GET target
+  // (lowering/sensor.ts sensorNames) — the two cannot drift.
+  for (const sp of i2cSensors) {
+    const ctrl = chip.i2c?.controllers[sp.busIndex];
+    const info = SENSOR_PART_INFO[sp.part.replace(/^SENSOR\./, '')];
+    if (!ctrl || !info) continue; // the lowering already threw on unknown parts
+    const nodeName = info.compatible.split(',')[1] ?? sp.part;
+    const addrHex = sp.port.toString(16);
+    lines.push(`&${ctrl.nodeLabel} {`);
+    lines.push(`    tc_${sp.part.replace(/^SENSOR\./, '')}_i2c${sp.busIndex}_0x${addrHex}: ${nodeName}@${addrHex} {`);
+    lines.push(`        compatible = "${info.compatible}";`);
+    lines.push(`        reg = <0x${addrHex}>;`);
+    emitAlert(lines, chip, sp.alertPin, info.alert, 8);
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+  }
+  if (usage.usesSpi && chip.spi) {
+    for (const [i, c] of chip.spi.controllers.entries()) {
+      if (usage.spiUsedInstances && !usage.spiUsedInstances.includes(i)) continue;
+      controllerBlock(c);
+    }
+  }
+  if (usage.usesUart && chip.uart) {
+    for (const [i, c] of chip.uart.controllers.entries()) {
+      if (usage.uartUsedInstances && !usage.uartUsedInstances.includes(i)) continue;
+      controllerBlock(c);
+    }
+  }
+  // Synthesized pinctrl groups reference pinmux tokens — splice their header
+  // includes ahead of every block (same slot the display path uses), with
+  // ifndef-guarded #defines for upstream header bugs in front.
+  for (const [include, defines] of pinctrlIncludes) {
+    const pre: string[] = [];
+    for (const d of defines) {
+      const name = d.trim().split(/\s+/)[0];
+      pre.push(`#ifndef ${name}`, `#define ${d}`, `#endif`);
+    }
+    lines.splice(2, 0, ...pre, `#include <${include}>`, '');
+  }
+  // Watchdog: the SoC dtsi declares the node disabled (STM32 iwdg ships
+  // status = "disabled" until a board enables it) — the wdt.* lowering
+  // addresses DEVICE_DT_GET(DT_NODELABEL(<nodeLabel>)), which needs the
+  // driver instance built, so enable the node when wdt_* is used.
+  if (usage.usesWdt && chip.wdt) {
+    block(chip.wdt.nodeLabel);
+  }
+  // USB CDC-ACM: the "next" USB device stack composes classes as devicetree
+  // children of the UDC controller node. Enable the controller and declare one
+  // cdc_acm_uart<N> child per instance the chip descriptor declares — the
+  // lowering addresses instance N as DT_NODELABEL(cdc_acm_uart<N>), so the
+  // nodelabels here and in lowering/usb.ts cannot drift. Endpoints and
+  // descriptors are assigned by the class driver at build time.
+  if (usage.usesUsb && chip.usb) {
+    lines.push(`&${chip.usb.controller} {`);
+    lines.push('    status = "okay";');
+    for (let i = 0; i < chip.usb.cdcInstances; i++) {
+      lines.push(`    cdc_acm_uart${i}: cdc-acm-uart${i} {`);
+      lines.push('        compatible = "zephyr,cdc-acm-uart";');
+      lines.push('    };');
+    }
+    lines.push('};');
+    lines.push('');
+  }
+  // PWM: synthesized specs (controller + channel, no board-shipped alias) get
+  // a pwm-leds consumer node + tc-pwm<pin> alias here — the lowering addresses
+  // the channel as PWM_DT_SPEC_GET(DT_ALIAS(tc-pwm<pin>)), so the alias must
+  // exist in the merged DT. pwmDtAlias (lowering/pwm.ts) derives the same
+  // name from the pin; the two sides cannot drift. Filtered to the pins the
+  // program actually drives (pwmUsedPins) so the DT carries no dead channels;
+  // an undefined list (prepare-time overlay) emits all specs.
+  if (usage.usesPwm && chip.pwm) {
+    emitPwmNodes(lines, chip, usage.pwmUsedPins);
+  }
+  // ADC: enable the ADC device node, and on SoCs whose channels carry a
+  // pinctrl label (STM32: the pad stays in GPIO mode unless the ADC node's
+  // pinctrl-0 muxes it analog), rewrite pinctrl-0 to exactly the channels the
+  // program reads. DT assignment replaces the whole property — the board
+  // default (one pad) is deliberately dropped in favor of the used set.
+  if (usage.usesAdc && chip.adc) {
+    emitAdcNode(lines, chip, usage.adcReadPins);
+  }
+  // DAC: enable the chip's DAC device node when the program uses dac.*. The
+  // lowering references DEVICE_DT_GET(DT_NODELABEL(<dac.device>)); the used
+  // channels' pinctrl groups route the output to its pad.
+  if (usage.usesDac && chip.dac) {
+    emitDacNode(lines, chip, usage.dacWritePins);
+  }
+  // Counters: enable the free counter devices when the program uses hwtimer.
+  // Self form (nRF rtc1, STM32 rtc): enable the labeled node. Child form
+  // (ESP32 timer0-3): the counter device is an unlabeled `counter {}`
+  // child — the overlay defines the tc_counter<N> label the descriptor's
+  // nodeLabel references (the same label-less-child move the STM32 pwm
+  // path uses).
+  if (usage.usesHwtimer && chip.hwtimer) {
+    for (const c of chip.hwtimer.controllers) {
+      if (c.counterParent) {
+        lines.push(`&${c.counterParent} {`);
+        lines.push('    status = "okay";');
+        lines.push(`    ${c.nodeLabel}: counter {`);
+        lines.push('        status = "okay";');
+        lines.push('    };');
+        lines.push('};');
+        lines.push('');
+      } else {
+        lines.push(`&${c.nodeLabel} {`);
+        lines.push('    status = "okay";');
+        lines.push('};');
+        lines.push('');
+      }
+    }
+  }
+  if (display) {
+    // Emit a full display DT node definition. Boards like the ESP32 devkit
+    // have no display node in their base DT, so a bare `&display0 { status }`
+    // fails (the nodelabel doesn't exist). Define the node attached to a SPI
+    // controller with the panel's compatible string + dimensions. The pin
+    // wiring (cs/dc/rst) uses ESP32 GPIO defaults from the demo config; a
+    // real board overlay would carry its own binding.
+    // An XPT2046 on the same bus needs its CS as the second cs-gpios entry,
+    // so thread it into the display block (DT assignment replaces the whole
+    // property — both entries must be written together).
+    emitDisplayNode(
+      lines,
+      display,
+      wiring,
+      touch?.controller === 'xpt2046' ? (touch?.cs ?? DEFAULT_XPT2046_CS) : undefined,
+    );
+  }
+  // Touch — FT6336U capacitive on I2C (references DT_NODELABEL(ft6336u)) or
+  // XPT2046 resistive on the display's SPI bus (references
+  // DT_NODELABEL(xpt2046)). Same rationale as the display node: the bare
+  // devkit has no such node. Gated on usesTouch (not usesI2c/chip.i2c) so it
+  // emits even when the chip descriptor doesn't declare bus controllers.
+  if (usage.usesTouch) {
+    emitTouchNode(lines, touch, display);
+  }
+
+  // Preferences (ZMS settings backend): point the settings subsystem at the
+  // board's storage_partition. The backend looks for /chosen
+  // zephyr,settings-partition first, then falls back to a fixed-partition
+  // labeled storage_partition — most Zephyr boards define that label, so this
+  // chosen entry makes the lookup explicit and survives boards that name the
+  // partition differently. It only adds a /chosen pointer (never redeclares
+  // the partition node — west errors if a node is multiply-defined).
+  if (usage.usesPreferences || usage.usesFS) {
+    // Boards whose DTS ships no storage_partition (most STM32s define only
+    // the MCUboot boot/slot/scratch set) declare a synthesis region in the
+    // chip descriptor — emit it as a partition@<offset> child of the flash0
+    // partitions node. Adding a NEW child via overlay is legal; redeclaring
+    // an existing one is not, so boards that already carry the label
+    // (descriptor storage.preexisting — ESP32's AMP layout) skip the
+    // synthesis block and only the /chosen pointer lands here.
+    if (chip.storage && !chip.storage.preexisting) {
+      lines.push('&flash0 {');
+      // Explicit compatible + cells: boards whose DTS already carries a
+      // partitions node (rp2040, STM32 MCUboot sets) merge identically, and
+      // boards without one (rpi_pico2) would otherwise hit dtc's spec
+      // default of #address-cells 2 / #size-cells 1 — a 3-cell reg and a
+      // "length 8 not divisible by 12" error for the 2-cell reg below.
+      lines.push('    partitions {');
+      lines.push('        compatible = "fixed-partitions";');
+      lines.push('        #address-cells = <1>;');
+      lines.push('        #size-cells = <1>;');
+      lines.push(`        storage_partition: partition@${chip.storage.offset.toString(16)} {`);
+      lines.push('            label = "storage";');
+      lines.push(`            reg = <0x${chip.storage.offset.toString(16).padStart(8, '0')} 0x${chip.storage.size.toString(16).padStart(8, '0')}>;`);
+      lines.push('        };');
+      lines.push('    };');
+      lines.push('};');
+      lines.push('');
+    }
+    if (usage.usesPreferences) {
+      lines.push('/ {');
+      lines.push('    chosen {');
+      lines.push('        zephyr,settings-partition = &storage_partition;');
+      lines.push('    };');
+      lines.push('};');
+      lines.push('');
+    }
+  }
+
+  // PSRAM: enable the psram0 DT node with the correct size. The devkitc board
+  // DT defaults to a no-PSRAM module variant (e.g. wroom_n8); a PSRAM-capable
+  // module (N16R8, N8R8) needs the node enabled + sized so the linker maps
+  // .ext_ram sections into the real PSRAM. OPI on ESP32-S3 = 8MB octal PSRAM.
+  // SPI sensors: children whose reg is their cs-gpios INDEX. DT property
+  // assignment replaces the whole property, so cs-gpios is written here with
+  // every sensor CS on the controller, after the display block — a display
+  // panel sharing the bus is a wiring conflict this layer cannot merge (its
+  // CS comes from config wiring), so warn instead of silently dropping it.
+  // spi-max-frequency defaults to 1 MHz — conservative for sensors whose
+  // datasheet max isn't in any binding; the constructor opts override it.
+  const SPI_SENSOR_HZ = 1000000;
+  const spiByCtrl = new Map<number, typeof spiSensors>();
+  for (const sp of spiSensors) {
+    const list = spiByCtrl.get(sp.busIndex) ?? [];
+    list.push(sp);
+    spiByCtrl.set(sp.busIndex, list);
+  }
+  // Target-only controllers (no sensors) still need the cs-gpios block.
+  for (const t of spiTargets) {
+    if (!spiByCtrl.has(t.busIndex)) spiByCtrl.set(t.busIndex, []);
+  }
+  for (const [idx, sensors] of spiByCtrl) {
+    const ctrl = chip.spi?.controllers[idx];
+    if (!ctrl) continue;
+    // A display panel on the same controller already wrote cs-gpios earlier
+    // in this overlay (its CS at index 0, an XPT2046 at 1). DT property
+    // assignment replaces, so this rewrite carries BOTH: the display entries
+    // first — keeping the panel/touch reg indexes stable — then the sensor CS
+    // pins. The entry construction mirrors emitDisplayNode's defaults via the
+    // shared DEFAULT_DISPLAY_CS/DEFAULT_XPT2046_CS constants.
+    const displayEntries: string[] = [];
+    if (display && (display.busLabel ?? 'spi2') === ctrl.nodeLabel) {
+      const displayCs = wiring?.cs ?? DEFAULT_DISPLAY_CS;
+      displayEntries.push(`<&gpio${displayCs <= 31 ? '0' : '1'} ${displayCs} GPIO_ACTIVE_LOW>`);
+      if (touch?.controller === 'xpt2046') {
+        const touchCs = touch.cs ?? DEFAULT_XPT2046_CS;
+        displayEntries.push(`<&gpio${touchCs <= 31 ? '0' : '1'} ${touchCs} GPIO_ACTIVE_LOW>`);
+      }
+    }
+    // Thin SPI targets ride this controller too: their CS entries append
+    // after the sensor pins, and their child nodes carry no compatible —
+    // a raw spi_dt_spec peer, not a driver node.
+    const ctrlTargets = spiTargets.filter((t) => t.busIndex === idx);
+    lines.push(`&${ctrl.nodeLabel} {`);
+    lines.push(`    cs-gpios = ${displayEntries.concat(sensors.map((sp) => {
+      const gc = chip.gpioControllers?.find((g) => sp.port >= g.minPin && sp.port <= g.maxPin);
+      const ctrlLabel = gc?.nodelabel ?? 'gpio0';
+      return `<&${ctrlLabel} ${sp.port} GPIO_ACTIVE_LOW>`;
+    }), ctrlTargets.map((t) => {
+      const gc = chip.gpioControllers?.find((g) => t.cs >= g.minPin && t.cs <= g.maxPin);
+      const ctrlLabel = gc?.nodelabel ?? 'gpio0';
+      return `<&${ctrlLabel} ${t.cs} GPIO_ACTIVE_LOW>`;
+    })).join(', ')};`);
+    sensors.forEach((sp, sensorIdx) => {
+      const info = SENSOR_PART_INFO[sp.part.replace(/^SENSOR\./, '')];
+      if (!info) return;
+      const nodeName = info.compatible.split(',')[1] ?? sp.part;
+      const csIndex = displayEntries.length + sensorIdx;
+      lines.push(`    tc_${sp.part}_spi${idx}_cs${sp.port}: ${nodeName}@${csIndex} {`);
+      lines.push(`        compatible = "${info.compatible}";`);
+      lines.push(`        reg = <${csIndex}>;`);
+      lines.push(`        spi-max-frequency = <${sp.spiHz && sp.spiHz > 0 ? sp.spiHz : SPI_SENSOR_HZ}>;`);
+      // mode bits: 1 = CPHA, 2 = CPOL (presence props, no value).
+      if ((sp.spiMode ?? 0) & 2) lines.push('        spi-cpol;');
+      if ((sp.spiMode ?? 0) & 1) lines.push('        spi-cpha;');
+      emitAlert(lines, chip, sp.alertPin, info.alert, 8);
+      lines.push('    };');
+    });
+    ctrlTargets.forEach((t, targetIdx) => {
+      const csIndex = displayEntries.length + sensors.length + targetIdx;
+      lines.push(`    tc_spit_spi${idx}_cs${t.cs}: spidev@${csIndex} {`);
+      // The app-local cuttlefish,spi-target binding (no driver — it makes
+      // gen_defines emit the spi properties SPI_DT_SPEC_GET reads).
+      lines.push(`        compatible = "cuttlefish,spi-target";`);
+      lines.push(`        reg = <${csIndex}>;`);
+      lines.push(`        spi-max-frequency = <${t.hz && t.hz > 0 ? t.hz : SPI_SENSOR_HZ}>;`);
+      if ((t.mode ?? 0) & 2) lines.push('        spi-cpol;');
+      if ((t.mode ?? 0) & 1) lines.push('        spi-cpha;');
+      lines.push('    };');
+    });
+    lines.push('};');
+    lines.push('');
+  }
+
+  if (usage.psram) {
+    lines.push('&psram0 {');
+    lines.push('    status = "okay";');
+    lines.push('    size = <(DT_SIZE_M(8))>;');
+    lines.push('};');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Emit the pwm-leds consumer node + aliases for synthesized PWM specs.
+ *
+ * A board DTS may enable a PWM controller (`pwm4`) without aliasing any
+ * channel — the STM32 pattern — while the lowering addresses channels via
+ * DT_ALIAS. Each synthesized spec gets a `pwm-leds` child whose `pwms` cell
+ * binds the controller+channel (+ period/polarity), and a `tc-pwm<pin>`
+ * alias pointing at it. Alias/label names are valid DT identifiers (lowercase
+ * alphanumerics + dash/underscore).
+ */
+function emitPwmNodes(
+  lines: string[],
+  chip: ZephyrChipDescriptor,
+  usedPins?: readonly number[],
+): void {
+  const staticSynth = (chip.pwm?.specs ?? []).filter(
+    (s) => s.controller && s.channel != null && !s.dtSpec,
+  ).filter((s) => !usedPins || usedPins.includes(s.pin));
+
+  // Matrix PWM (ESP32 LEDC): channels are assigned here, over the pins the
+  // program actually drives (ascending — the same order lowering/pwm.ts
+  // emits the alias vars in; the C++ is channel-blind, so this is the single
+  // place a channel number is decided). The espressif,esp32-ledc binding
+  // needs three pieces per channel: a pinctrl pinmux token routing the
+  // channel to the pad (LEDC_CH<ch>_GPIO<pin> — every channel×pad pair
+  // exists in esp32s3-pinctrl.h, already included via the SoC dtsi), a
+  // channel child node (the driver's DT_INST_FOREACH_CHILD reads reg +
+  // timer from each), and the pwm-leds consumer the alias resolves to.
+  const m = chip.pwm?.matrix;
+  let matrixSynth: { pin: number; controller: string; channel: number }[] = [];
+  if (m) {
+    const pins = [...new Set(usedPins ? usedPins.filter((p) => m.pins.includes(p)) : m.pins)]
+      .sort((a, b) => a - b);
+    if (pins.length > m.channelCount) {
+      throw new Error(
+        `framework-zephyr: the program drives ${pins.length} PWM pins but ${chip.id}'s ` +
+        `${m.controller} exposes only ${m.channelCount} channels — drop ` +
+        `${pins.length - m.channelCount} pwm pin(s).`,
+      );
+    }
+    matrixSynth = pins.map((pin, ch) => ({ pin, controller: m.controller, channel: ch }));
+    // nRF shape: channels route to pads via psel (pinctrl psel order IS
+    // channel order — pwm_nrfx reads PSEL.OUT[ch] back), no channel child
+    // nodes, and the overlay carries the nrf pinctrl header for NRF_PSEL.
+    // P<port>.<pin> maps from the global number through the nRF controller
+    // layout (P0 = 0-31, P1 = 32-63).
+    const isNrfMatrix = /^nrf/.test(chip.soc);
+    if (isNrfMatrix) {
+      const inc = '#include <zephyr/dt-bindings/pinctrl/nrf-pinctrl.h>';
+      if (!lines.includes(inc)) lines.splice(2, 0, inc, '');
+      lines.push('&pinctrl {');
+      lines.push(`    tc_${m.controller}_default: tc-${m.controller}-default {`);
+      lines.push('        group1 {');
+      lines.push(`            psel = ${pins.map((p, ch) => `<NRF_PSEL(PWM_OUT${ch}, ${Math.floor(p / 32)}, ${p % 32})>`).join(', ')};`);
+      lines.push('        };');
+      lines.push('    };');
+      lines.push('};');
+      lines.push('');
+      lines.push(`&${m.controller} {`);
+      lines.push('    status = "okay";');
+      lines.push(`    pinctrl-0 = <&tc_${m.controller}_default>;`);
+      lines.push('    pinctrl-names = "default";');
+      lines.push('};');
+      lines.push('');
+    }
+    if (!isNrfMatrix) {
+    lines.push('&pinctrl {');
+    lines.push(`    tc_${m.controller}_default: tc-${m.controller}-default {`);
+    lines.push('        group1 {');
+    lines.push(`            pinmux = ${pins.map((p, ch) => `<LEDC_CH${ch}_GPIO${p}>`).join(', ')};`);
+    lines.push('            output-enable;');
+    lines.push('        };');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+    // The four LEDC timers are round-robined so co-driven channels share a
+    // timer only past four (sharing is fine at equal periods; the driver
+    // reconfigures on pwm_set_dt when they differ).
+    lines.push(`&${m.controller} {`);
+    lines.push('    status = "okay";');
+    lines.push(`    pinctrl-0 = <&tc_${m.controller}_default>;`);
+    lines.push('    pinctrl-names = "default";');
+    lines.push('    #address-cells = <1>;');
+    lines.push('    #size-cells = <0>;');
+    for (let ch = 0; ch < pins.length; ch++) {
+      lines.push(`    channel${ch}@${ch} {`);
+      lines.push(`        reg = <${ch}>;`);
+      lines.push(`        timer = <${ch % 4}>;`);
+      lines.push('    };');
+    }
+    lines.push('};');
+    lines.push('');
+    }
+  }
+
+  const synthesized = staticSynth.concat(matrixSynth);
+  if (synthesized.length === 0) return;
+  // The pwms cells name the polarity as a macro (PWM_POLARITY_NORMAL). It is
+  // NOT universally available: only dts include chains that already use PWM
+  // bindings pull <zephyr/dt-bindings/pwm/pwm.h> in (STM32 does; the
+  // ESP32-S3 chain does not), so the overlay carries its own include.
+  // Spliced after the header comments, the established pattern (see the
+  // esp32s3-pinctrl.h splice above); guarded for the double-emit case.
+  if (!lines.includes('#include <zephyr/dt-bindings/pwm/pwm.h>')) {
+    lines.splice(2, 0, '#include <zephyr/dt-bindings/pwm/pwm.h>', '');
+  }
+  // Enable each distinct PWM controller node (idempotent when already okay).
+  // 16-bit fit: STM32 timers count period cycles in a 16-bit ARR, and the
+  // SoC dtsi default is st,prescaler = <0> (÷1) — a 20 ms servo period at
+  // 96 MHz is 1.92M cycles and pwm_stm32 rejects the channel. When the
+  // descriptor declares the timer clock, derive the smallest divider that
+  // fits the controller's slowest used period and override the prescaler
+  // on the timers parent node (the property lives there, not on the pwm
+  // child). pwm4 → timers4 is the STM32 nodelabel convention. Matrix
+  // controllers are skipped — the block above already enabled them (with
+  // their pinctrl + channel children, which this loop doesn't know).
+  const clockHz = chip.pwm?.clockHz;
+  for (const controller of [...new Set(staticSynth.map((s) => s.controller!))]) {
+    const timersMatch = controller.match(/^pwm(\d+)$/);
+    const specs = staticSynth.filter((s) => s.controller === controller);
+    // Macro-form pinctrl tokens (uppercase — DT labels are lowercase by
+    // spec): the overlay synthesizes the pad-routing group itself. RP2's
+    // macros live in a dt-bindings header the board chain may not pull in
+    // (spliced via rp2PinctrlHeader); Kinetis/LPC/GD32 macros come from the
+    // part headers the board's own pinctrl dtsi includes, and Zephyr
+    // preprocesses overlays together with the base DTS — no splice needed.
+    const isMacro = (p: string | undefined): boolean => !!p && /^[A-Z][A-Z0-9_]*$/.test(p);
+    if (!timersMatch && specs.some((s) => isMacro(s.pinctrl))) {
+      const header = rp2PinctrlHeader(chip.soc);
+      if (header) {
+        const inc = `#include <zephyr/dt-bindings/pinctrl/${header}>`;
+        if (!lines.includes(inc)) lines.splice(2, 0, inc, '');
+      }
+      lines.push('&pinctrl {');
+      lines.push('    tc_pwm_default: tc-pwm-default {');
+      lines.push('        group1 {');
+      lines.push(`            pinmux = ${specs.filter((s) => s.pinctrl).map((s) => `<${s.pinctrl}>`).join(', ')};`);
+      lines.push('        };');
+      lines.push('    };');
+      lines.push('};');
+      lines.push('');
+      lines.push(`&${controller} {`);
+      lines.push('    status = "okay";');
+      // Atmel SAM TCC/TC in PWM mode: the SoC dtsi declares the base timer
+      // node (compatible atmel,sam0-tcc / …-tc, with clocks/assigned-clocks/
+      // channels/counter-size already present). The overlay overrides the
+      // compatible to the PWM binding, sets the required prescaler and the
+      // #pwm-cells the binding consts, and reuses the shared pinctrl group.
+      const samPwm = controller.match(/^(tcc|tc)(\d+)$/);
+      if (samPwm) {
+        lines.push(`    compatible = "${samPwm[1] === 'tcc' ? 'atmel,sam0-tcc-pwm' : 'atmel,sam0-tc-pwm'}";`);
+        lines.push('    prescaler = <1024>;');
+        lines.push('    #pwm-cells = <2>;');
+      }
+      lines.push('    pinctrl-0 = <&tc_pwm_default>;');
+      lines.push('    pinctrl-names = "default";');
+      lines.push('};');
+      lines.push('');
+      continue;
+    }
+    if (timersMatch) {
+      // STM32 shape: the SoC dtsi declares a LABEL-LESS pwm child under
+      // timers{N} — the overlay defines the label itself (pwmN: pwm), which
+      // the synthesized pwms cell below references. One block carries the
+      // parent enable, the pad-routing pinctrl groups (harvested silicon
+      // routes on the specs — without them the PWM runs but nothing leaves
+      // the chip), the prescaler, and the child enable.
+      const groups = specs.filter((s) => s.pinctrl).map((s) => `&${s.pinctrl}`);
+      const maxPeriodNs = Math.max(...specs.map((s) => s.periodNs ?? 20_000_000));
+      // cycles = clockHz * period_s / divider ≤ 65536 (driver allows
+      // UINT16_MAX + 1); binding value is divider - 1 (CLK/(prescaler+1)).
+      const divider = clockHz
+        ? Math.max(1, Math.ceil((clockHz * maxPeriodNs) / 1e9 / 65536))
+        : 1;
+      lines.push(`&timers${timersMatch[1]} {`);
+      lines.push('    status = "okay";');
+      if (divider > 1) {
+        lines.push(`    st,prescaler = <${divider - 1}>;`);
+      }
+      lines.push(`    ${controller}: pwm {`);
+      lines.push('        status = "okay";');
+      if (groups.length > 0) {
+        lines.push(`        pinctrl-0 = <${groups.join(' ')}>;`);
+        lines.push('        pinctrl-names = "default";');
+      }
+      lines.push('    };');
+      lines.push('};');
+      lines.push('');
+      continue;
+    }
+    // Lowercase pinctrl tokens (i.MX `iomuxc_…` node labels from the part
+    // dtsi) ride the controller's pinctrl-0 directly.
+    const pinRefs = specs.filter((s) => s.pinctrl && !isMacro(s.pinctrl)).map((s) => `&${s.pinctrl}`);
+    lines.push(`&${controller} {`);
+    lines.push('    status = "okay";');
+    if (pinRefs.length > 0) {
+      lines.push(`    pinctrl-0 = <${pinRefs.join(' ')}>;`);
+      lines.push('    pinctrl-names = "default";');
+    }
+    lines.push('};');
+    lines.push('');
+  }
+  lines.push('/ {');
+  lines.push('    tc_pwm_leds: tc-pwm-leds {');
+  lines.push('        compatible = "pwm-leds";');
+  for (const s of synthesized) {
+    // 20 ms / 50 Hz default — the servo convention; the duty scaling in the
+    // lowering normalizes 0-255 against whatever period is baked in.
+    const period = s.periodNs ?? 20_000_000;
+    const polarity = s.polarity ?? 'PWM_POLARITY_NORMAL';
+    lines.push(`        tc_pwm_${s.pin}: pwm-led-${s.pin} {`);
+    lines.push(`            pwms = <&${s.controller} ${s.channel} ${period} ${polarity}>;`);
+    lines.push('        };');
+  }
+  lines.push('    };');
+  lines.push('    aliases {');
+  for (const s of synthesized) {
+    lines.push(`        tc-pwm${s.pin} = &tc_pwm_${s.pin};`);
+  }
+  lines.push('    };');
+  lines.push('};');
+  lines.push('');
+}
+
+/**
+ * Emit the ADC device-node enable (+ optional pinctrl override). The pinctrl
+ * override applies only when the descriptor's channels carry pinctrl labels
+ * AND the caller knows which pins the program reads (compile-time regen scans
+ * the emitted `__tc_adc<N>_setup()` calls); the prepare-time overlay omits it
+ * and the compile regen rewrites the file before west runs.
+ *
+ * Two pinctrl forms by family: NODE labels (STM32's harvested
+ * `adc1_in1_pa1` groups — referenced as `&label`) and MACRO tokens (RP2's
+ * `ADC_CH0_P26` — DT labels are lowercase by spec and macros uppercase, so
+ * the case decides). The macro form synthesizes its own group under
+ * &pinctrl and splices the SoC's pinctrl dt-binding header so the token
+ * resolves in the overlay's compile.
+ *
+ * Multi-controller SoCs: channels may name their owning controller (STM32
+ * adc3-only routes, ESP32 units). One enable block is emitted per controller
+ * that owns used channels — the primary first, others sorted for
+ * deterministic output. Single-controller boards emit exactly one block, as
+ * before.
+ */
+/** The SoC's pinctrl dt-binding header (where the macro tokens are defined)
+ *  — RP2 shapes; undefined for socs that use node-label pinctrl exclusively. */
+function rp2PinctrlHeader(soc: string): string | undefined {
+  if (soc === 'rp2040') return 'rpi-pico-rp2040-pinctrl.h';
+  if (soc.startsWith('rp2350a')) return 'rpi-pico-rp2350a-pinctrl.h';
+  if (soc.startsWith('rp2350b')) return 'rpi-pico-rp2350b-pinctrl.h';
+  return undefined;
+}
+
+function emitAdcNode(
+  lines: string[],
+  chip: ZephyrChipDescriptor,
+  readPins?: readonly number[],
+): void {
+  const adc = chip.adc!;
+  const primary = adc.nodeLabel;
+  const controllerOf = (c: { controller?: string }) => c.controller ?? primary;
+  const used = readPins ? adc.channels.filter((c) => readPins.includes(c.pin)) : adc.channels;
+  const isMacro = (p: string | undefined): boolean => !!p && /^[A-Z][A-Z0-9_]*$/.test(p);
+  const macroChannels = used.filter((c) => isMacro(c.pinctrl));
+  if (macroChannels.length > 0) {
+    const header = rp2PinctrlHeader(chip.soc);
+    if (header) {
+      const inc = `#include <zephyr/dt-bindings/pinctrl/${header}>`;
+      if (!lines.includes(inc)) lines.splice(2, 0, inc, '');
+    }
+    lines.push('&pinctrl {');
+    lines.push('    tc_adc_default: tc-adc-default {');
+    lines.push('        group1 {');
+    lines.push(`            pinmux = ${macroChannels.map((c) => `<${c.pinctrl}>`).join(', ')};`);
+    lines.push('        };');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+  }
+  // Every controller that owns a USED channel gets an enable block — a
+  // controller left "disabled" in the SoC dtsi has no device instance, so a
+  // read against it fails to link. Nothing used: enable the primary only.
+  const controllers = used.length > 0
+    ? [...new Set(used.map(controllerOf))]
+        .sort((a, b) => (a === primary ? -1 : b === primary ? 1 : a.localeCompare(b, undefined, { numeric: true })))
+    : [primary];
+  for (const label of controllers) {
+    const mine = used.filter((c) => controllerOf(c) === label && c.pinctrl);
+    lines.push(`&${label} {`);
+    lines.push('    status = "okay";');
+    if (mine.length > 0) {
+      if (mine.every((c) => isMacro(c.pinctrl))) {
+        lines.push('    pinctrl-0 = <&tc_adc_default>;');
+      } else {
+        lines.push(`    pinctrl-0 = <${mine.map((c) => `&${c.pinctrl}`).join(' ')}>;`);
+      }
+      lines.push('    pinctrl-names = "default";');
+    }
+    lines.push('};');
+    lines.push('');
+  }
+}
+
+/**
+ * Emit the DAC device-node enable + the used output channels' pinctrl
+ * groups (the harvested `dac1_out1_pa4`-style nodes — the st,stm32-dac
+ * binding includes pinctrl-device, so without the group the channel never
+ * reaches its pad). Mirrors emitAdcNode.
+ */
+function emitDacNode(
+  lines: string[],
+  chip: ZephyrChipDescriptor,
+  writePins?: readonly number[],
+): void {
+  const dac = chip.dac!;
+  const labeled = dac.channels.filter((c) => c.pinctrl);
+  const used = labeled.filter((c) => !writePins || writePins.includes(c.pin));
+  lines.push(`&${dac.device} {`);
+  lines.push('    status = "okay";');
+  if (used.length > 0) {
+    lines.push(`    pinctrl-0 = <${used.map((c) => `&${c.pinctrl}`).join(' ')}>;`);
+    lines.push('    pinctrl-names = "default";');
+  }
+  lines.push('};');
+  lines.push('');
+}
+
+/**
+ * Emit a display DT node definition. The node is attached to the profile's SPI
+ * controller (default spi2, the ESP32's first user SPI controller) via a MIPI
+ * DBI SPI bridge. Pin wiring comes from the display config (cs/dc/rst);
+ * defaults match the demo-st wiring if absent. The compatible string + node
+ * props come from the profile's panel controller (st7796s carries the required
+ * pgc/ngc gamma + madctl; ili9341's binding defaults everything else).
+ *
+ * spiTouchCs: when an XPT2046 SPI touch controller shares the bus, its CS is
+ * appended as the second cs-gpios entry (the touch node uses reg = <1>) — DT
+ * property assignment replaces, so both entries must be written together.
+ */
+/** Emit alert-gpios for parts whose binding declares it (active high — the
+ *  bindings describe the sensor's output level, e.g. sht3xd's ALERT). */
+function emitAlert(lines: string[], chip: ZephyrChipDescriptor, alertPin: number | undefined, supported: boolean, indent: number): void {
+  if (alertPin === undefined || alertPin < 0 || !supported) return;
+  const gc = chip.gpioControllers?.find((g) => alertPin >= g.minPin && alertPin <= g.maxPin);
+  const pad = ' '.repeat(indent);
+  lines.push(`${pad}alert-gpios = <&${gc?.nodelabel ?? 'gpio0'} ${alertPin} GPIO_ACTIVE_HIGH>;`);
+}
+
+function emitDisplayNode(
+  lines: string[],
+  display: ZephyrDisplayProfile,
+  wiring?: DisplayWiring,
+  spiTouchCs?: number,
+): void {
+  const bus = display.busLabel ?? 'spi2';
+  const controller = panelControllerFor(display);
+  const compatible = display.dtCompatible ?? PANEL_CONTROLLER_DEFAULTS[controller].dtCompatible;
+  const dc = wiring?.dc ?? 17;
+  const rst = wiring?.rst ?? 16;
+  const cs = wiring?.cs ?? DEFAULT_DISPLAY_CS;
+  const freq = wiring?.spiFrequency ?? 80000000;
+  // DT node describes the NATIVE panel geometry; the effective (rotated)
+  // dimensions live in the display profile.
+  const nativeW = display.nativeWidth ?? display.width;
+  const nativeH = display.nativeHeight ?? display.height;
+  const sck = wiring?.sck;
+  const mosi = wiring?.mosi;
+  const miso = wiring?.miso;
+  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
+  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
+  // The board's spim2_default pinctrl group usually targets the devkitc's
+  // default SPI pins (SCLK=12/MOSI=11), which rarely match the display's
+  // wiring. When the config declares spiPins, override the pinctrl groups to
+  // remux the controller onto the panel's actual pins. Raw ESP32_PINMUX()
+  // macros are used instead of the named SPIM2_*_GPIOxx tokens because the
+  // bindings header omits GPIOs 22-25 from those lists.
+  if (sck !== undefined && mosi !== undefined) {
+    // 'spi2' → pinctrl group 'spim2_default' (ESP32 SPI-master naming).
+    const pinctrlGroup = bus.replace(/^spi(\d)$/, 'spim$1') + '_default';
+    lines.push(`&${pinctrlGroup} {`);
+    lines.push('    group1 {');
+    lines.push(`        pinmux = <ESP32_PINMUX(${miso ?? 19}, ESP_FSPIQ_IN, ESP_NOSIG)>,`);
+    lines.push(`                 <ESP32_PINMUX(${sck}, ESP_NOSIG, ESP_FSPICLK_OUT)>,`);
+    lines.push('                 <ESP32_PINMUX(10, ESP_NOSIG, ESP_FSPICS0_OUT)>;');
+    lines.push('    };');
+    lines.push('    group2 {');
+    lines.push(`        pinmux = <ESP32_PINMUX(${mosi}, ESP_NOSIG, ESP_FSPID_OUT)>;`);
+    lines.push('        output-low;');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+  }
+  lines.push('&dma {');
+  lines.push('    status = "okay";');
+  lines.push('};');
+  lines.push('');
+  lines.push(`&${bus} {`);
+  lines.push('    status = "okay";');
+  lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>${spiTouchCs !== undefined ? `, <&${gpioController(spiTouchCs)} ${spiTouchCs} GPIO_ACTIVE_LOW>` : ''};`);
+  // Enable GDMA for the SPI2 host. The ESP32 SPI driver uses DMA only when
+  // dma-enabled is set AND dmas wires tx/rx channels to the GDMA controller;
+  // without it, transfers run PIO through the 64-byte FIFO (~4MHz effective at
+  // 80MHz requested). The GDMA driver allocates channels per peripheral based
+  // on spi2's dma-host=<0> (set in the SoC dtsi), so the channel cells are the
+  // GDMA instance's rx/tx slot ids (2 here = an SPI2-dedicated pair; the GDMA
+  // binding's #dma-cells = <1> carries the channel).
+  lines.push('    dma-enabled;');
+  lines.push('    dmas = <&dma 0>, <&dma 1>;');
+  lines.push('    dma-names = "rx", "tx";');
+  lines.push('};');
+  lines.push('');
+  lines.push('/ {');
+  lines.push('    mipi_dbi: mipi-dbi {');
+  lines.push('        compatible = "zephyr,mipi-dbi-spi";');
+  lines.push(`        spi-dev = <&${bus}>;`);
+  lines.push(`        dc-gpios = <&${gpioController(dc)} ${dc} GPIO_ACTIVE_HIGH>;`);
+  lines.push(`        reset-gpios = <&${gpioController(rst)} ${rst} GPIO_ACTIVE_LOW>;`);
+  lines.push('        write-only;');
+  lines.push('        #address-cells = <1>;');
+  lines.push('        #size-cells = <0>;');
+  lines.push(`        ${display.dtLabel}: display@0 {`);
+  lines.push(`            compatible = "${compatible}";`);
+  lines.push('            reg = <0>;');
+            if (wiring?.tearingEffectPin !== undefined) {
+              const tePin = wiring.tearingEffectPin!;
+              // Tearing-effect input on the display node: GPIO_DT_SPEC_GET(
+              // DT_NODELABEL(display0), te_gpios) in the adapter. Opt-in —
+              // most modules don't break the TE pad out.
+              lines.push(`            te-gpios = <&${gpioController(tePin)} ${tePin} GPIO_ACTIVE_HIGH>;`);
+            }
+            lines.push(`            mipi-max-frequency = <${freq}>;`);
+            lines.push('            mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE";');
+            // Required by the lcd-controller binding (Zephyr 4.x): 0 = RGB565,
+            // matching upstream ILI9341 boards (esp_wrover_kit) and the C++
+            // runtime, which drives these SPI TFTs as RGB565.
+            lines.push('            pixel-format = <0>;');
+  lines.push(`            width = <${nativeW}>;`);
+  lines.push(`            height = <${nativeH}>;`);
+  if (controller === 'st7796s') {
+    // MADCTL: rotation 1 (landscape, MV=1) + BGR bit, matching the adapter's
+    // direct-drive init (0x28). The DT copy keeps the stock driver's init
+    // consistent if it is ever exercised.
+    lines.push('            madctl = <0x28>;');
+    lines.push('            pgc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
+    lines.push('            ngc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
+  } else {
+    // ILI9341: the ilitek,ili9341 binding carries defaults for every register
+    // (gamma, power, porch) and expresses orientation via `rotation` (degrees)
+    // instead of a raw MADCTL — no panel-specific props are required.
+    lines.push(`            rotation = <${display.rotation ?? 0}>;`);
+  }
+  lines.push('        };');
+  lines.push('    };');
+  lines.push('};');
+  lines.push('');
+  // Backlight node: emit only when the config provides a backlight GPIO. The
+  // pin was previously hardcoded to 4, which collided with the FT6336U
+  // reset-gpios on the same pin (demo-st's backlight is hardwired to 3.3V, so
+  // no backlight node is correct there). When present, use the configured pin
+  // and the profile's alias name so the display adapter can drive it.
+  const blPin = wiring?.backlightPin;
+  if (display.backlight && blPin !== undefined) {
+    lines.push('/ {');
+    lines.push('    aliases {');
+    lines.push(`        ${display.backlight} = &bl_led;`);
+    lines.push('    };');
+    lines.push('    bl_gpio: bl-gpio-leds {');
+    lines.push('        compatible = "gpio-leds";');
+    lines.push('        bl_led: led {');
+    lines.push(`            gpios = <&${gpioController(blPin)} ${blPin} GPIO_ACTIVE_HIGH>;`);
+    lines.push('        };');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+  }
+}
+
+/** Default XPT2046 CS/IRQ pins (ESP32-S3 GPIOs clear of the demo-st display
+ *  wiring: 5/17/16/15 and the remuxed SPI pins). Config values override. */
+const DEFAULT_XPT2046_CS = 6;
+const DEFAULT_XPT2046_IRQ = 7;
+
+/**
+ * Emit the touch DT node for the configured controller.
+ *
+ * FT6336U (capacitive, I2C): node on i2c0 at the FT6336U default address
+ * (0x38); the C++ touch adapter reads it via i2c_write_read_dt.
+ *
+ * XPT2046 (resistive, SPI): node on the display's SPI bus as CS index 1. The
+ * in-tree xptek,xpt2046 binding (drivers/input) is register-matched for the
+ * raw SPI access — CONFIG_INPUT stays off, so the in-tree input driver does
+ * not build and the adapter owns the chip (same pattern as FT6336U reusing
+ * the ft5336 binding). The binding requires int-gpios, touchscreen-size-*,
+ * and min/max calibration props, so defaults are filled for anything the
+ * config omits.
+ */
+function emitTouchNode(
+  lines: string[],
+  touch: TouchWiring | undefined,
+  display: ZephyrDisplayProfile | undefined,
+): void {
+  if (touch?.controller === 'xpt2046') {
+    emitXpt2046Node(lines, touch, display);
+    return;
+  }
+  emitFt6336uNode(lines, touch);
+}
+
+/** FT6336U capacitive touch node on the first I2C controller. */
+function emitFt6336uNode(lines: string[], touch?: TouchWiring): void {
+  const irq = touch?.irq ?? 15;
+  const resetPin = touch?.resetPin;
+  const sda = touch?.sda;
+  const scl = touch?.scl;
+  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
+  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
+  // Zephyr has no ft6336 binding — the FT6336U is register-compatible with the
+  // ft5336 binding (same Focaltech register map: TD_STATUS at 0x02, coordinate
+  // registers 0x03-0x06). The C++ touch adapter reads these directly via I2C,
+  // so the binding just needs to exist for the DT node to resolve.
+  // When SDA/SCL are provided, remux the I2C bus to those pins via pinctrl
+  // (the board's default I2C pins rarely match a breakout's wiring).
+  if (sda !== undefined && scl !== undefined) {
+    lines.push('&pinctrl {');
+    lines.push('    i2c0_touch: i2c0_touch {');
+    lines.push('        group1 {');
+    lines.push(`            pinmux = <I2C0_SDA_GPIO${sda}>, <I2C0_SCL_GPIO${scl}>;`);
+    lines.push('            bias-pull-up;');
+    lines.push('            drive-open-drain;');
+    lines.push('        };');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+    lines.push('&i2c0 {');
+    lines.push('    status = "okay";');
+    lines.push('    pinctrl-0 = <&i2c0_touch>;');
+    lines.push('    pinctrl-names = "default";');
+  } else {
+    lines.push('&i2c0 {');
+    lines.push('    status = "okay";');
+  }
+  lines.push('    ft6336u: ft6336u@38 {');
+  lines.push('        compatible = "focaltech,ft5336";');
+  lines.push('        reg = <0x38>;');
+  // NOTE: int-gpios is intentionally omitted. The ft5336 Zephyr driver
+  // registers a GPIO interrupt on int-gpios, which triggers an assertion
+  // failure in the ESP32 interrupt controller (VECDESC_FL_SHARED conflict).
+  // The cuttlefish touch adapter polls touch_isTouched() via I2C every frame
+  // — it never uses the IRQ pin, so the interrupt registration is unnecessary.
+  if (resetPin !== undefined) {
+    lines.push(`        reset-gpios = <&${gpioController(resetPin)} ${resetPin} GPIO_ACTIVE_LOW>;`);
+  }
+  lines.push('    };');
+  lines.push('};');
+  lines.push('');
+}
+
+/** XPT2046 resistive touch node on the display's SPI bus (CS index 1). */
+function emitXpt2046Node(
+  lines: string[],
+  touch: TouchWiring,
+  display: ZephyrDisplayProfile | undefined,
+): void {
+  const bus = display?.busLabel ?? 'spi2';
+  const cs = touch.cs ?? DEFAULT_XPT2046_CS;
+  const irq = touch.irq ?? DEFAULT_XPT2046_IRQ;
+  const cal = touch.calibration;
+  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
+  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
+  const zThreshold = touch.minPressure ?? 400;
+  // touchscreen-size-* describe the panel the touch layer sits on (the display
+  // profile's effective size); a touch-only build falls back to the 12-bit
+  // full-scale range so the binding's required props still resolve.
+  const sizeX = display?.width ?? cal?.xMax ?? 320;
+  const sizeY = display?.height ?? cal?.yMax ?? 240;
+  // The display block already wrote cs-gpios with both entries (its CS at
+  // index 0, the touch CS at index 1). When there is no display block, enable
+  // the bus here with the touch CS as the only entry.
+  if (!display) {
+    lines.push(`&${bus} {`);
+    lines.push('    status = "okay";');
+    lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>;`);
+    lines.push('};');
+    lines.push('');
+  }
+  lines.push(`&${bus} {`);
+  lines.push('    xpt2046: xpt2046@1 {');
+  lines.push('        compatible = "xptek,xpt2046";');
+  lines.push('        reg = <1>;');
+  // The XPT2046 datasheet max SPI clock is 2.5MHz — the panel bus may run at
+  // 80MHz, but this node's spi-max-frequency gates only its own transactions
+  // (the adapter's SPI_DT_SPEC picks it up).
+  lines.push('        spi-max-frequency = <2500000>;');
+  lines.push(`        int-gpios = <&${gpioController(irq)} ${irq} GPIO_ACTIVE_LOW>;`);
+  lines.push(`        touchscreen-size-x = <${sizeX}>;`);
+  lines.push(`        touchscreen-size-y = <${sizeY}>;`);
+  lines.push(`        min-x = <${cal?.xMin ?? 0}>;`);
+  lines.push(`        max-x = <${cal?.xMax ?? 4095}>;`);
+  lines.push(`        min-y = <${cal?.yMin ?? 0}>;`);
+  lines.push(`        max-y = <${cal?.yMax ?? 4095}>;`);
+  lines.push(`        z-threshold = <${zThreshold}>;`);
+  lines.push('    };');
+  lines.push('};');
+  lines.push('');
+}