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

package/src/dt-config/overlay.ts

@@ -1,1058 +1,1475 @@
-// ---------------------------------------------------------------------------
-// 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('');
-}
+// ---------------------------------------------------------------------------
+// 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 { controllerNodelabelForPin, controllerRawPinForPin } from '../chips/controllers.js';
+import type { ZephyrDisplayProfile } from '../display/profiles.js';
+import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor, transportFor, isDtCompatible } from '../display/profiles.js';
+import { readDisplayBinding, type RequiredProp } from '../display/bindings.js';
+import { isEinkDisplay } from '../display/profiles.js';
+
+/** Standard values for the mono-OLED family's default-free required props
+ *  (segment/page/display offsets, multiplex ratio, precharge period) — the
+ *  values upstream board overlays ship; tune per panel from here. */
+function monoPropFallback(prop: string, info: RequiredProp | undefined, nativeHeight: number): string | undefined {
+  if (prop === 'width' || prop === 'height' || prop === 'reg' || prop === 'compatible') return undefined;
+  const def = info?.default;
+  if (def?.kind === 'int') return `${prop} = <${def.value}>`;
+  if (prop === 'multiplex-ratio') return `multiplex-ratio = <${nativeHeight - 1}>`;
+  if (prop === 'prechargep') return 'prechargep = <0x22>';
+  if (prop === 'segment-offset' || prop === 'page-offset' || prop === 'display-offset') return `${prop} = <0>`;
+  // SSD1327-class (Stage 3 gray): required by solomon,ssd1327_5-common.yaml
+  // with no binding default. Panel-tunable — these are the datasheet/common-
+  // module starting points (scanline artifacts: raise oscillator-freq toward
+  // 0x70; striping: add 0x40 to remap-value per the binding's bit table).
+  if (prop === 'oscillator-freq') return 'oscillator-freq = <0x00>';
+  if (prop === 'start-line') return 'start-line = <0>';
+  if (prop === 'remap-value') return 'remap-value = <0x51>';
+  if (prop === 'phase-length') return 'phase-length = <0x1f>';
+  return undefined;
+}
+
+/** Format one binding-required property with its harvested default. Binding
+ *  props that are deliberately default-free ("panel specific" — e.g. the
+ *  sitronix gamma arrays) fall back to the rig-validated tuning the curated
+ *  profiles ship, so the generated node is always DT-valid. */
+function emitBindingProp(lines: string[], prop: string, info: RequiredProp | undefined): void {
+  const def = info?.default;
+  if (def?.kind === 'bytes' && def.value.length > 0) {
+    lines.push(`            ${prop} = [${def.value.map((b) => b.toString(16).padStart(2, '0')).join(' ')}];`);
+    return;
+  }
+  if (def?.kind === 'bool' && def.value) {
+    lines.push(`            ${prop};`);
+    return;
+  }
+  if (def?.kind === 'string') {
+    lines.push(`            ${prop} = "${def.value}";`);
+    return;
+  }
+  if (info?.type === 'uint8-array') {
+    // No binding default (panel-specific): emit the rig-validated gamma
+    // tuning the curated st7796 profile carries. Tune per panel from here.
+    lines.push(`            ${prop} = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];`);
+    return;
+  }
+  const v = def?.kind === 'int' ? def.value : 0;
+  lines.push(`            ${prop} = <${v}>;`);
+}
+import { SENSOR_PART_INFO } from '@typecad/hal';
+import type { KconfigUsage } from './kconfig.js';
+
+/** 1-Wire family codes (the high byte of the 64-bit ROM ID) for the parts
+ *  the catalog carries on the w1 bus — vendor silicon data, like the ESP32
+ *  DAC pin table. Unknown compatibles default to the DS18B20's 0x28. */
+const W1_FAMILY_CODES: Record<string, number> = {
+  'maxim,ds18b20': 0x28,
+  'maxim,ds18s20': 0x10,
+};
+
+/** 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 typecad-hal.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;
+  /** E-ink BUSY GPIO from display.busyPin — emitted as busy-gpios on the
+   *  panel child (required by the ssd16xx/uc81xx bindings, active-high). */
+  busyPin?: number;
+  spiFrequency?: number;
+  /** I2C address for i2c-family panels (mono OLEDs, ssd1306-class). */
+  address?: number;
+  /** I2C bus pins for i2c-family panels. When present, the overlay remuxes
+   *  the I2C controller's pinctrl to these pins — the board's default I2C
+   *  pins rarely match a breakout's wiring (same rationale as the SPI pins
+   *  below; the ESP32 pinctrl headers carry the named I2C0_*_GPIOn macros).
+   *  Shared bus: when touch wiring also remuxes, the last assignment wins —
+   *  wire both to the same pins. */
+  sda?: number;
+  scl?: 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 typecad-hal.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 typecad-hal.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 typecad-hal.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('');
+  }
+  // One w1-gpio master + sensor child per constructed 1-Wire sensor. The
+  // master bit-bangs the data pin (open-drain, internal pull-up enabled —
+  // the binding recommends an external 4.7 kΩ, the internal one is weak);
+  // the child's family-code comes from the vendor table below (part of the
+  // 64-bit ROM ID), resolution from the construction opts. The nodelabels
+  // match lowering/sensor.ts sensorNames — the tc-pwm discipline.
+  for (const sp of sensorParts.filter((s) => s.busKind === 'w1')) {
+    const info = SENSOR_PART_INFO[sp.part.replace(/^SENSOR\./, '')];
+    const family = W1_FAMILY_CODES[info?.compatible ?? ''] ?? 0x28;
+    if (!info) continue; // the lowering already threw on unknown parts
+    const pinCtrl = controllerNodelabelForPin(chip, sp.port);
+    const pinBit = controllerRawPinForPin(chip, sp.port);
+    const nodeName = info.compatible.split(',')[1] ?? sp.part;
+    const stem = `${sp.part.replace(/^SENSOR\./, '')}_w1_p${sp.port}`;
+    lines.push('/ {');
+    lines.push(`    tc_w1_p${sp.port}: tc-w1-p${sp.port} {`);
+    lines.push('        compatible = "zephyr,w1-gpio";');
+    lines.push(`        gpios = <&${pinCtrl} ${pinBit} (GPIO_OPEN_DRAIN | GPIO_PULL_UP)>;`);
+    lines.push('        status = "okay";');
+    lines.push(`        tc_${stem}: ${nodeName} {`);
+    lines.push(`            compatible = "${info.compatible}";`);
+    lines.push(`            family-code = <0x${family.toString(16)}>;`);
+    lines.push(`            resolution = <${sp.resolution}>;`);
+    lines.push('            status = "okay";');
+    lines.push('        };');
+    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('');
+      }
+    }
+  }
+  // LED strips: one ws2812-spi child per driven SPI controller. The frame
+  // tuning (6.4 MHz, one=0xf0 / zero=0xc0 — 625 ns bit halves) is the
+  // Zephyr led_strip sample's canonical SPI encoding; the color-mapping
+  // matches the WS2812's native GRB order (the driver reorders). The
+  // controller is enabled here too — a strip-only program emits no spi_*
+  // calls, so the bus enable cannot ride the generic SPI usage path.
+  // `line-idle-low` keeps MOSI low between frames, the WS2812 reset level.
+  if (usage.usesStrip && usage.strips && usage.strips.length > 0) {
+    lines.splice(2, 0, '#include <zephyr/dt-bindings/led/led.h>', '');
+    for (const s of usage.strips) {
+      const ctrl = chip.spi?.controllers[s.index];
+      if (!ctrl) continue;
+      lines.push(`&${ctrl.nodeLabel} {`);
+      lines.push('    status = "okay";');
+      lines.push('    line-idle-low;');
+      lines.push(`    tc_strip${s.index}: ws2812@0 {`);
+      lines.push('        compatible = "worldsemi,ws2812-spi";');
+      lines.push('        reg = <0>;');
+      lines.push('        spi-max-frequency = <6400000>;');
+      lines.push(`        chain-length = <${s.count}>;`);
+      lines.push('        spi-cpha;');
+      lines.push('        spi-one-frame = <0xf0>;');
+      lines.push('        spi-zero-frame = <0xc0>;');
+      lines.push('        color-mapping = <LED_COLOR_ID_GREEN LED_COLOR_ID_RED LED_COLOR_ID_BLUE>;');
+      lines.push('    };');
+      lines.push('};');
+      lines.push('');
+    }
+  }
+  // I2S: enable the board's own i2s@ controllers — their pinctrl groups
+  // are board-authored (the devkitC wires i2s0_default/i2s1_default), so
+  // status is the only synthesis needed. The GDMA the ESP32 I2S driver
+  // DMA-runs through also ships disabled — enable it alongside.
+  // Full-duplex: the RX side's I_BCK/I_WS inputs must be routed in the
+  // GPIO matrix to the same pads the TX outputs drive (input-enable on
+  // the TX clock pads — the same-pad GPIO matrix trick the CAN loopback
+  // uses; the devkitC's i2s0 clock pads are WS=36, BCK=37).
+  if (usage.usesI2s && chip.i2s) {
+    lines.push('&dma {');
+    lines.push('    status = "okay";');
+    lines.push('};');
+    lines.push('');
+    for (const c of chip.i2s.controllers) {
+      const n = c.nodeLabel.replace(/[^0-9]/g, '') || '0';
+      lines.push(`&${c.nodeLabel} {`);
+      lines.push('    status = "okay";');
+      lines.push('};');
+      lines.push('');
+      lines.push('&pinctrl {');
+      lines.push('    tc_i2s_clock_loop: tc-i2s-clock-loop {');
+      lines.push('        group1 {');
+      lines.push(`            pinmux = <I2S${n}_I_BCK_GPIO37>,`);
+      lines.push(`                     <I2S${n}_I_WS_GPIO36>;`);
+      lines.push('        };');
+      lines.push('    };');
+      lines.push('};');
+      lines.push(`&${c.nodeLabel} {`);
+      lines.push(`    pinctrl-0 = <&${c.nodeLabel}_default>, <&tc_i2s_clock_loop>;`);
+      lines.push('    pinctrl-names = "default";');
+      lines.push('};');
+      lines.push('');
+    }
+  }
+  // CAN: enable the board's own can@ controller (the harvested node —
+  // boards that ship pinctrl groups keep them; the bitrate is the begin()
+  // default, overridden at runtime by can_set_bitrate). Classic CAN only.
+  // LOOPBACK: the SJA1000 self-test transmits on the TX pad and receives
+  // on the RX pad — with no transceiver the overlay routes BOTH TWAI
+  // functions onto the TX pad (the Zephyr test suite's own
+  // twai-enable.overlay shape: output-enable on the RX mux, input-enable
+  // on the TX mux, one shared pad).
+  if (usage.usesCan && chip.can) {
+    for (const c of chip.can.controllers) {
+      lines.push(`&${c.nodeLabel} {`);
+      lines.push('    status = "okay";');
+      lines.push('    bitrate = <500000>;');
+      lines.push('};');
+      lines.push('');
+      if (usage.canLoopback && c.txPad !== undefined) {
+        lines.push('&pinctrl {');
+        lines.push('    tc_can_loopback: tc-can-loopback {');
+        lines.push('        group1 {');
+        lines.push(`            pinmux = <TWAI_RX_GPIO${c.txPad}>;`);
+        lines.push('            output-enable;');
+        lines.push('        };');
+        lines.push('        group2 {');
+        lines.push(`            pinmux = <TWAI_TX_GPIO${c.txPad}>;`);
+        lines.push('            input-enable;');
+        lines.push('        };');
+        lines.push('    };');
+        lines.push('};');
+        lines.push(`&${c.nodeLabel} { pinctrl-0 = <&tc_can_loopback>; pinctrl-names = "default"; };`);
+        lines.push('');
+      }
+    }
+  }
+  // Wall-clock shim: a zephyr,rtc-counter child on the board's first free
+  // counter node + the `rtc` alias (Zephyr's own discovery convention —
+  // the api tests filter on dt_alias_exists("rtc")). The shim is a CHILD:
+  // the counter driver keeps the parent node, so Counter and Clock
+  // coexist. V1 always synthesizes the shim (uniform semantics, no driver
+  // conflicts); preferring a board's own hardware-calendar alias — and the
+  // backup-domain persistence it buys — is the follow-up.
+  if (usage.usesClock && usage.clockShimCounter) {
+    const c = usage.clockShimCounter;
+    if (c.parent) {
+      // Child-form counters (ESP32 timerN children): the shim's parent
+      // must be the counter DEVICE, so it nests INSIDE the counter child —
+      // DT_INST_PARENT in the shim driver resolves to the counter, not the
+      // timer (which carries no device of its own).
+      lines.push(`&${c.parent} {`);
+      lines.push('    status = "okay";');
+      lines.push(`    ${c.label}: counter {`);
+      lines.push('        status = "okay";');
+      lines.push('        tc_rtc: tc-rtc {');
+      lines.push('            compatible = "zephyr,rtc-counter";');
+      lines.push('        };');
+      lines.push('    };');
+      lines.push('};');
+    } else {
+      lines.push(`&${c.label} {`);
+      lines.push('    tc_rtc: tc-rtc {');
+      lines.push('        compatible = "zephyr,rtc-counter";');
+      lines.push('    };');
+      lines.push('};');
+    }
+    lines.push('/ {');
+    lines.push('    aliases {');
+    lines.push('        rtc = &tc_rtc;');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+  }
+  // USB HID: one zephyr,hid-device interface per program (the v1 ceiling —
+  // Keyboard OR Mouse, not both). protocol-code stays "none": the boot
+  // subclass/protocol codes (keyboard/mouse) made Windows bind the
+  // collections but silently discard every input report on this stack,
+  // while "none" (pure report-protocol device, like Zephyr's own samples)
+  // delivers input normally. The report descriptor carries the real
+  // keyboard/mouse semantics either way.
+  if (usage.usesHid) {
+    lines.push('/ {');
+    lines.push('    tc_hid: tc-hid {');
+    lines.push('        compatible = "zephyr,hid-device";');
+    lines.push('        protocol-code = "none";');
+    lines.push('        in-report-size = <8>;');
+    lines.push('        in-polling-period-us = <1000>;');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+  }
+  // Key matrix: the gpio-kbd-matrix node from the construction pad lists.
+  // Rows are pull-up inputs (active-low); columns are driven one at a time.
+  // Pin → controller/bit via the same mapping the gpio lowering uses.
+  if (usage.usesMatrix && usage.matrix && usage.matrix.rows.length > 0) {
+    // Same mapping the gpio lowering uses — the canonical controller
+    // resolution (single-controller fallback included). The port-relative
+    // bit comes from controllerRawPinForPin (split-SoC offsets).
+    const gpioRef = (pin: number): string => {
+      return `&${controllerNodelabelForPin(chip, pin)} ${controllerRawPinForPin(chip, pin)} (GPIO_PULL_UP | GPIO_ACTIVE_LOW)`;
+    };
+    lines.push('/ {');
+    lines.push('    tc_matrix: matrix {');
+    lines.push('        compatible = "gpio-kbd-matrix";');
+    lines.push(`        row-gpios = ${usage.matrix.rows.map((pin) => `<${gpioRef(pin)}>`).join(', ')};`);
+    lines.push(`        col-gpios = ${usage.matrix.cols.map((pin) => `<${gpioRef(pin)}>`).join(', ')};`);
+    lines.push('    };');
+    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);
+  // Board-provided displays (native_sim's built-in sdl_dc): the board's own
+  // devicetree wires the panel — nothing to emit here.
+  if (display.boardProvidesDisplay) {
+    return;
+  }
+  // I2C-family panels (mono OLEDs, ssd1306-class): a plain &i2cN child node —
+  // no mipi-dbi bridge, no SPI bus block, no DMA. Bus pins come from the
+  // touch wiring's remux (shared bus) or the board's default I2C pins.
+  if (readDisplayBinding(display.dtCompatible ?? (isDtCompatible(display.driver) ? display.driver : ''))?.busFamily === 'i2c') {
+    const addr = wiring?.address ?? 0x3c;
+    // Optional I2C pin remux — mirrors the touch path's remux (the board's
+    // default I2C pins rarely match a breakout's wiring). Named macros from
+    // the SoC pinctrl header; the group lives under &pinctrl and overrides
+    // i2c0's default group via pinctrl-0.
+    const sda = wiring?.sda;
+    const scl = wiring?.scl;
+    if (sda !== undefined && scl !== undefined) {
+      lines.push('&pinctrl {');
+      lines.push('    i2c0_display: i2c0_display {');
+      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('');
+    }
+    // Node name from the compatible's panel segment (ssd1306/ssd1309/sh1106);
+    // DT node names are labels, not compatibles — but matching the panel
+    // keeps the built zephyr.dts readable.
+    const panel = (display.dtCompatible ?? display.driver).split(',')[1] ?? 'ssd1306';
+    lines.push('&i2c0 {');
+    lines.push('    status = "okay";');
+    // Fast mode: the full-frame mono push is bandwidth-bound (a 128x64 frame
+    // is 1KB — ~25ms at the 100kHz default, ~7ms at 400kHz), so animations
+    // step without it. OLED modules and the esp32s3/nRF i2c controllers all
+    // handle 400kHz; declare it whenever we own the bus node generation.
+    lines.push('    clock-frequency = <400000>;');
+    if (sda !== undefined && scl !== undefined) {
+      lines.push('    pinctrl-0 = <&i2c0_display>;');
+      lines.push('    pinctrl-names = "default";');
+    }
+    lines.push(`    ${display.dtLabel}: ${panel}@${addr.toString(16)} {`);
+    lines.push(`        compatible = "${display.dtCompatible ?? display.driver}";`);
+    lines.push(`        reg = <0x${addr.toString(16)}>;`);
+    lines.push(`        width = <${display.nativeWidth ?? display.width}>;`);
+    lines.push(`        height = <${display.nativeHeight ?? display.height}>;`);
+    const binding = readDisplayBinding(display.dtCompatible ?? display.driver);
+    if (binding) {
+      for (const [prop, info] of binding.required) {
+        const v = monoPropFallback(prop, info, display.nativeHeight ?? display.height);
+        if (v !== undefined) lines.push(`        ${v};`);
+      }
+    }
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+    return;
+  }
+  // Compatible resolution: explicit override → the registry controllers →
+  // the drop-in path (driver IS a compatible string) → a safe default.
+  // Drop-in drivers (DT-compatible shape) ARE the compatible — they win over
+  // the controller-default table (which only serves registry driver ids whose
+  // id isn't itself a compatible; the e-ink family entries exist for the
+  // Kconfig layer, not for node naming).
+  const compatible = display.dtCompatible
+    ?? (isDtCompatible(display.driver)
+      ? display.driver
+      : (controller !== undefined
+        ? PANEL_CONTROLLER_DEFAULTS[controller].dtCompatible
+        : PANEL_CONTROLLER_DEFAULTS.ili9341.dtCompatible));
+  const dc = wiring?.dc ?? 17;
+  const rst = wiring?.rst ?? 16;
+  const cs = wiring?.cs ?? DEFAULT_DISPLAY_CS;
+  // E-ink SPI tops out far below TFTs (the reel board runs ssd1673 at 4MHz;
+  // the controllers' shift registers clock 4-10MHz). Cap the default for the
+  // e-ink families; explicit spiFrequency always wins.
+  const einkFamily = isEinkDisplay({ driver: display.driver, displayClass: display.displayClass });
+  const freq = wiring?.spiFrequency ?? (einkFamily ? 4000000 : 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 && transportFor(display) === 'direct-spi') {
+              const tePin = wiring.tearingEffectPin!;
+              // Tearing-effect input on the display node: GPIO_DT_SPEC_GET(
+              // DT_NODELABEL(display0), te_gpios) in the direct-spi adapter.
+              // Opt-in — most modules don't break the TE pad out. NOT emitted
+              // on the zephyr-display transport: te-gpios makes the bound
+              // in-tree driver allocate the TE GPIO interrupt (the ESP32
+              // VECDESC_FL_SHARED conflict path) — the driver's TE handling
+              // needs re-verification before it can be wired there.
+              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";');
+            if (wiring?.busyPin !== undefined) {
+              // E-ink BUSY line — required by the ssd16xx/uc81xx bindings
+              // (the drivers block on it through the flash cycle). Active
+              // level fixed per family: ssd16xx BUSY is active-high.
+              lines.push(`            busy-gpios = <&${gpioController(wiring.busyPin)} ${wiring.busyPin} GPIO_ACTIVE_HIGH>;`);
+            }
+  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];');
+    // rgb-is-inverted flips the format the driver REPORTS (565 <-> 565X).
+    // Zephyr RGB_565 is little-endian storage, but an 8-bit SPI panel clocks
+    // the LOW byte first — each pixel arrives byte-swapped, which mixes the
+    // green channel into red/blue (white text reads purple, dark backgrounds
+    // read green — verified on the rig). With the flag, the driver reports
+    // 565X and the adapter byte-swaps at pack time, restoring wire order.
+    // (The binding documents the prop for "buggy modules that display RGB as
+    // BGR" — same mechanism, byte order.)
+    lines.push('            rgb-is-inverted;');
+  } else if (controller === 'ili9341') {
+    // 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}>;`);
+    // pixel-format is REQUIRED by the lcd-controller binding the ilitek
+    // ili9xxx family includes: 0 = RGB565 (dt-bindings/display/panel.h),
+    // matching upstream ILI9341 boards (esp_wrover_kit) and the C++ runtime.
+    // The sitronix,st7796s binding does NOT declare pixel-format (its branch
+    // omits the property — emitting it there is a DTC error, caught the hard
+    // way once the overlay stopped carrying the wrong ilitek compatible).
+    lines.push('            pixel-format = <0>;');
+  } else {
+    // Generic (drop-in) path: required properties come from the panel's own
+    // binding in the user's Zephyr tree — the harvest is the single source
+    // of truth, so the node is valid for ANY bound panel by construction.
+    // Geometry/frequency props above are already emitted; pixel-format is
+    // special (required by the lcd-controller family, value fixed to RGB565).
+    const binding = readDisplayBinding(compatible);
+    if (binding?.requiresPixelFormat) {
+      lines.push('            pixel-format = <0>;');
+    }
+    if (binding) {
+      for (const [prop, def] of binding.required) {
+        // Skip structural properties the generator emits itself.
+        if (prop === 'width' || prop === 'height' || prop === 'mipi-max-frequency'
+            || prop === 'pixel-format' || prop === 'reg' || prop === 'compatible'
+            || prop === 'status' || prop === 'mipi-mode'
+            // phandle-array props are structural (GPIO routing) — the
+            // generator emits them from config wiring (busy-gpios above),
+            // never from a numeric fallback.
+            || prop === 'busy-gpios' || prop === 'reset-gpios' || prop === 'dc-gpios') {
+          continue;
+        }
+        emitBindingProp(lines, prop, def);
+      }
+      // Rotation on madctl-style panels (st7796s family): the binding ships
+      // a neutral portrait default and the driver writes MADCTL verbatim, so
+      // the config's rotation MUST reach the node or the UI's landscape
+      // writes fall outside the portrait address window — half the screen
+      // scrambled, half fine (verified on the rig). Table = ST77xx rotation
+      // bits with BGR set (the verified clone convention; an R/B-swapped
+      // panel flips to the config's channelSwapRb flag instead).
+      // Byte-order quirk flag (clone panels): flips the format the driver
+      // reports so the adapter byte-swaps at pack time. Only bindings that
+      // declare the prop accept it — the DTC rejects it elsewhere, honestly.
+      if (display.rgbInverted === true) {
+        lines.push('            rgb-is-inverted;');
+      }
+      if (binding.props.has('madctl') && display.rotation !== undefined) {
+        const MADCTL_ROTATION = [0x08, 0x28, 0x48, 0xE8];
+        const r = ((display.rotation % 4) + 4) % 4;
+        lines.push(`            madctl = <0x${MADCTL_ROTATION[r]!.toString(16)}>;`);
+      }
+    }
+  }
+  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 driver's interrupt mode
+  // registers a GPIO IRQ (the ESP32 VECDESC_FL_SHARED crash); with no
+  // int-gpios the in-tree driver falls back to polling mode
+  // (CONFIG_INPUT_FT5336_PERIOD, default 10ms) — no IRQ is registered and
+  // the touch adapter consumes the driver's input events.
+  // swapped-x-y: the driver reports pos(col, row) — the Y-register value
+  // first. The swap makes its ABS_X/ABS_Y events carry the controller's
+  // X/Y registers verbatim, which is the raw coordinate space the runtime's
+  // calibration + rotation math (ui_poll_touch) expects from touch_readRaw.
+  lines.push('        swapped-x-y;');
+  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('');
+}