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

package/src/strategy.ts

@@ -1,9 +1,12 @@
 // ---------------------------------------------------------------------------
 // ZephyrStrategy — Zephyr RTOS target
 //
-// Outputs C++ built with `west` (the Zephyr build tool). Programs use the
-// Arduino-style setup()/loop() pair; a generated main() bridges them into
-// Zephyr's standard C entry point and yields to the scheduler between loops.
+// Outputs C++ built with `west` (the Zephyr build tool). Zephyr is a standard
+// C main()-based RTOS, so the program's entrypoint IS main(): top-level
+// statements lower straight into it. Worker programs keep the scaffolded
+// top-level `while (true)`; event-driven programs (UI / async / native
+// timers) end with a scheduler loop in main() that ticks the UI runtime and
+// pumps microtasks each frame, yielding to the kernel with k_msleep(1).
 //
 // GPIO is lowered through devicetree specs (gpio_pin_*_dt) so an active-low
 // LED's polarity is honored by the DT flags, not by the generated code. See
@@ -19,6 +22,7 @@ import type {
   PlatformStrategy,
   ExpressionIR,
   ProgramIR,
+  StatementIR,
   Diagnostic,
   PlatformContext,
   BoardConstants,
@@ -35,24 +39,335 @@ import type {
   TouchAdapterCodegen,
 } from '@typecad/cuttlefish/api/shared';
 import { DEFAULT_STDLIB_SUPPORT } from '@typecad/cuttlefish/api/shared';
-import { buildWorkerRuntimePolyfill } from '@typecad/cuttlefish/api/shared';
 import { applyStringMethodRewrites } from '@typecad/cuttlefish/api/shared';
 import { programUsesSafety } from '@typecad/cuttlefish/api';
 import { entryHasUI } from '@typecad/cuttlefish/ui-hook';
-import { chipForTarget, setActiveChip, getActiveChip } from './chips/index.js';
+import { generateBoard, generateBoardModuleFromContract } from './boardgen.js';
+import {
+  syncBoardCatalog,
+  ensureFreshBoardCatalog,
+  type BoardCatalogSyncReport,
+  type BoardCatalogEnsureResult,
+} from './sdk/board-catalog-sync.js';
+import { setActiveChip, getActiveChip, NO_BOARD_CHIP } from './chips/index.js';
 import { resolveChipFromBoard } from './chips/resolve.js';
 import { emitGpioDevDispatcher } from './chips/controllers.js';
+import type { ZephyrChipDescriptor } from './chips/types.js';
+
+/**
+ * Deep-walk the program IR and collect the HAL pin numbers the program
+ * actually touches for a peripheral family ('adc' | 'pwm') — the same walk
+ * profileDiagnostics does. Emit paths gate per-channel state on these sets
+ * so nothing unused reaches the single generated TU (-Wunused-function
+ * hygiene: every emitted function/variable is referenced). `undefined`
+ * (no program — probe paths) means "no information": callers emit every
+ * descriptor channel, preserving probe behavior.
+ */
+function collectUsedPins(
+  program: ProgramIR | undefined,
+  kind: 'adc' | 'pwm',
+  chip?: ZephyrChipDescriptor,
+): Set<number> | undefined {
+  if (!program) return undefined;
+  const pins = new Set<number>();
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+    const op = n.operation;
+    if (op && typeof op === 'object') {
+      const o = op as Record<string, unknown>;
+      const name = o.operation;
+      const pin = o.pin;
+      if (typeof name === 'string' && typeof pin === 'number') {
+        if (kind === 'adc' && (name === 'adc.read' || name === 'adc.read_voltage' || name === 'adc.read_raw' || name === 'adc.read_mv')) pins.add(pin);
+        if (kind === 'pwm' && name.startsWith('pwm.')) pins.add(pin);
+      }
+    }
+    for (const v of Object.values(n)) {
+      if (Array.isArray(v)) { for (const item of v) visit(item); }
+      else if (v && typeof v === 'object') visit(v);
+    }
+  };
+  visit(program);
+  return pins;
+}
+
+/**
+ * The inline-override escape hatch: ADC ops carrying construction-time
+ * device overrides (hal/adc-pin.ts opts) name DT device labels the manifest
+ * may not know — the shim's init block must declare their device handles
+ * (the reads reference them) and fire even when the chip has no adc facts
+ * at all.
+ */
+function collectAdcOverrideDevices(program: ProgramIR | undefined): Set<string> {
+  const devices = new Set<string>();
+  if (!program) return devices;
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+    const op = n.operation;
+    if (op && typeof op === 'object') {
+      const o = op as Record<string, unknown>;
+      if (typeof o.operation === 'string' && o.operation.startsWith('adc.')
+          && typeof o.deviceOverride === 'string' && o.deviceOverride !== '') {
+        devices.add(o.deviceOverride);
+      }
+    }
+    for (const v of Object.values(n)) {
+      if (Array.isArray(v)) { for (const item of v) visit(item); }
+      else if (v && typeof v === 'object') visit(v);
+    }
+  };
+  visit(program);
+  return devices;
+}
+
+/**
+ * PWM construction-time overrides (the escape hatch): controller+channel
+ * vouched for by the user on pins the manifest may not map. The shim emits
+ * their alias vars; the overlay regen's marker merge creates the DT nodes.
+ */
+function collectPwmOverrideSpecs(program: ProgramIR | undefined): { pin: number; controller: string; channel: number }[] {
+  const specs: { pin: number; controller: string; channel: number }[] = [];
+  if (!program) return specs;
+  const seen = new Set<number>();
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+    const op = n.operation;
+    if (op && typeof op === 'object') {
+      const o = op as Record<string, unknown>;
+      const ctrl = typeof o.controllerOverride === 'string' && o.controllerOverride !== '' ? o.controllerOverride : undefined;
+      const ch = typeof o.channelOverride === 'number' && o.channelOverride >= 0 ? o.channelOverride : undefined;
+      if (typeof o.operation === 'string' && o.operation.startsWith('pwm.')
+          && typeof o.pin === 'number' && (ctrl || ch !== undefined) && !seen.has(o.pin)) {
+        seen.add(o.pin);
+        specs.push({ pin: o.pin, controller: ctrl ?? 'pwm0', channel: ch ?? 0 });
+      }
+    }
+    for (const v of Object.values(n)) {
+      if (Array.isArray(v)) { for (const item of v) visit(item); }
+      else if (v && typeof v === 'object') visit(v);
+    }
+  };
+  visit(program);
+  return specs;
+}
+
+/**
+ * Which I2C/SPI/UART controller indexes the program actually drives (parsed
+ * from the ops' bus/port id, same as the lowerings' parseControllerIndex).
+ * `undefined` (no program — probe paths) means "no information": callers
+ * emit every declared controller, preserving probe behavior.
+ *
+ * The per-controller state blocks are emitted only for these indexes — an
+ * unused declared controller's `__tc_<bus>N_dev` would trip -Werror's
+ * -Wunused-variable (Zephyr builds with warnings-as-errors), the same
+ * hygiene collectUsedPins enforces for per-channel ADC/PWM state.
+ */
+function collectUsedBusIndices(program: ProgramIR | undefined): { i2c: Set<number>; spi: Set<number>; uart: Set<number> } | undefined {
+  if (!program) return undefined;
+  const indices = { i2c: new Set<number>(), spi: new Set<number>(), uart: new Set<number>() };
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+      const op = n.operation;
+    if (op && typeof op === 'object') {
+      const o = op as Record<string, unknown>;
+      const name = o.operation;
+      if (typeof name === 'string') {
+        const m = name.match(/^(i2c|spi|uart)\./);
+        if (m) {
+          const bus = m[1] as 'i2c' | 'spi' | 'uart';
+          const id = typeof o.bus === 'string' ? o.bus : typeof o.port === 'string' ? o.port : undefined;
+          // parseControllerIndex() (what the lowering uses to pick the state
+          // prefix) maps a digitless alias like 'Wire'/'SPI'/'Serial' to
+          // controller 0 — the collector must agree, or the state block for
+          // controller 0 is skipped and every __tc_<bus>0_* reference dangles.
+          const idx = id?.match(/(\d+)$/);
+          indices[bus].add(idx ? parseInt(idx[1], 10) : 0);
+        }
+      }
+    }
+    for (const v of Object.values(n)) {
+      if (Array.isArray(v)) { for (const item of v) visit(item); }
+      else if (v && typeof v === 'object') visit(v);
+    }
+  };
+  visit(program);
+  return indices;
+}
+
+/**
+ * Collect the distinct DT-bound sensors the program's ops reference, as
+ * `${part}|${bus}|${address}` keys (same shape as peripheral-usage's
+ * sensorPartsUsed). Feeds the per-sensor device-handle state block — only
+ * constructed sensors emit state, and only sensors whose ops were emitted
+ * get a DT node.
+ */
+export function collectSensors(program: ProgramIR | undefined): Map<string, { part: string; bus: string; port: number | string; busKind: string; spiHz: number | string; spiMode: number | string; alertPin: number | string }> | undefined {
+  if (!program) return undefined;
+  const sensors = new Map<string, { part: string; bus: string; port: number | string; busKind: string; spiHz: number | string; spiMode: number | string; alertPin: number | string }>();
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+    const op = n.operation;
+    if (op && typeof op === 'object') {
+      const o = op as Record<string, unknown>;
+      if (o.operation === 'sensor.fetch' || o.operation === 'sensor.get') {
+        const part = String(o.part ?? '');
+        const bus = String(o.bus ?? '');
+        const port = (o.port as number | string) ?? 0;
+        const busKind = String(o.busKind ?? 'i2c');
+        const spiHz = (o.spiHz as number | string) ?? 0;
+        const spiMode = (o.spiMode as number | string) ?? 0;
+        const alertPin = (o.alertPin as number | string) ?? -1;
+        const key = `${part}|${bus}|${port}|${busKind}`;
+        if (!sensors.has(key)) sensors.set(key, { part, bus, port, busKind, spiHz, spiMode, alertPin });
+      }
+    }
+    for (const v of Object.values(n)) {
+      if (Array.isArray(v)) { for (const item of v) visit(item); }
+      else if (v && typeof v === 'object') visit(v);
+    }
+  };
+  visit(program);
+  return sensors;
+}
+
+/**
+ * Collect the distinct thin SPI targets the program's ops reference
+ * (spi.transceive / spi.dev_write), keyed `${bus}|${cs}`. Mirrors
+ * collectSensors: only constructed targets whose ops were emitted get a
+ * spi_dt_spec state block and a DT child node.
+ */
+export function collectSpiTargets(program: ProgramIR | undefined): Map<string, { bus: string; cs: number; hz: number; mode: number }> | undefined {
+  if (!program) return undefined;
+  const targets = new Map<string, { bus: string; cs: number; hz: number; mode: number }>();
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+    const op = n.operation;
+    if (op && typeof op === 'object') {
+      const o = op as Record<string, unknown>;
+      if (o.operation === 'spi.transceive' || o.operation === 'spi.dev_write' || o.operation === 'spi.reg_read') {
+        const bus = String(o.bus ?? '');
+        const cs = (o.cs as number) ?? 0;
+        const key = `${bus}|${cs}`;
+        if (!targets.has(key)) {
+          targets.set(key, { bus, cs, hz: (o.hz as number) ?? 0, mode: (o.mode as number) ?? 0 });
+        }
+      }
+    }
+    for (const v of Object.values(n)) {
+      if (Array.isArray(v)) { for (const item of v) visit(item); }
+      else if (v && typeof v === 'object') visit(v);
+    }
+  };
+  visit(program);
+  return targets;
+}
+
+/**
+ * Collect the distinct UART RX rings the program reads (uart.rx_* ops),
+ * keyed by controller index. Mirrors collectSpiTargets: only ports whose RX
+ * ops were emitted get a ring + ISR (an unused ISR is -Wunused-function
+ * under Zephyr's -Werror).
+ */
+export function collectUartRings(program: ProgramIR | undefined): Map<number, { index: number; ring: number }> | undefined {
+  if (!program) return undefined;
+  const rings = new Map<number, { index: number; ring: number }>();
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+    const op = n.operation;
+    if (op && typeof op === 'object') {
+      const o = op as Record<string, unknown>;
+      if (o.operation === 'uart.rx_arm' || o.operation === 'uart.rx_available'
+        || o.operation === 'uart.rx_peek' || o.operation === 'uart.rx_read') {
+        const port = String(o.port ?? 'UART0');
+        const m = port.match(/(UART|uart)(\d+)/) ?? port.match(/(\d+)/);
+        const index = m ? parseInt(m[m.length - 1], 10) : 0;
+        if (!rings.has(index)) {
+          rings.set(index, { index, ring: (o.ring as number) ?? 64 });
+        }
+      }
+    }
+    for (const v of Object.values(n)) {
+      if (Array.isArray(v)) { for (const item of v) visit(item); }
+      else if (v && typeof v === 'object') visit(v);
+    }
+  };
+  visit(program);
+  return rings;
+}
+
+/**
+ * Collect the distinct threads the program STARTS (thread.start ops), keyed
+ * by instance. Only started threads emit state — see shimLines.
+ */
+export function collectThreads(program: ProgramIR | undefined): Map<number, { instance: number; stackBytes: number; priority: number }> | undefined {
+  if (!program) return undefined;
+  const threads = new Map<number, { instance: number; stackBytes: number; priority: number }>();
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+    const op = n.operation;
+    if (op && typeof op === 'object') {
+      const o = op as Record<string, unknown>;
+      if (o.operation === 'thread.start') {
+        const instance = (o.instance as number) ?? 0;
+        if (!threads.has(instance)) {
+          threads.set(instance, { instance, stackBytes: (o.stackBytes as number) ?? 2048, priority: (o.priority as number) ?? 5 });
+        }
+      }
+    }
+    for (const v of Object.values(n)) {
+      if (Array.isArray(v)) { for (const item of v) visit(item); }
+      else if (v && typeof v === 'object') visit(v);
+    }
+  };
+  visit(program);
+  return threads;
+}
 import { lowerHalOp } from './lowering/index.js';
-import { buildZephyrWorkerBacking } from './lowering/worker-backing.js';
-import { adcInitLines } from './lowering/adc.js';
+import { adcInitLines, adcChannelForPin } from './lowering/adc.js';
 import { pwmInitLines } from './lowering/pwm.js';
 import { dacInitLines } from './lowering/dac.js';
 import { fsInitLines } from './lowering/fs.js';
 import { hwtimerInitLines } from './lowering/hwtimer.js';
 import { i2cInitLines } from './lowering/i2c.js';
+import { sensorStateLines } from './lowering/sensor.js';
+import { spiTargetStateLines } from './lowering/spi.js';
+import { threadStateLines } from './lowering/thread.js';
+import { uartRingStateLines } from './lowering/uart.js';
 import { spiInitLines } from './lowering/spi.js';
 import { uartInitLines } from './lowering/uart.js';
-import { interruptInitLines } from './lowering/interrupts.js';
+import { usbInitLines, usbdDeviceLines } from './lowering/usb.js';
+
+/**
+ * STM32F4 boot-time DBGMCU setup: set DBG_SLEEP|DBG_STOP|DBG_STANDBY
+ * (DBGMCU_CR @ 0xE0042004, bits 0–2) so SWD stays attachable while the app
+ * sleeps. RCC_APB1ENR (0x40023840) bit 18 clocks the DBGMCU first — F4 gates
+ * register access behind it. Raw-register form (not the STM32 LL headers) so
+ * the shim stays include-light; AUTOSAR-clean via reinterpret_cast.
+ */
+function stm32f4DbgmcuLines(): string[] {
+  return [
+    '// CUTTLEFISH_STM32_DBGMCU_BEGIN',
+    '#include <zephyr/init.h>',
+    'static int __tc_stm32_dbgmcu_keep_swd_alive(void) {',
+    '    volatile uint32_t* const rcc_apb1enr = reinterpret_cast<volatile uint32_t*>(0x40023840);',
+    '    *rcc_apb1enr = *rcc_apb1enr | (1UL << 18);',
+    '    volatile uint32_t* const dbgmcu_cr = reinterpret_cast<volatile uint32_t*>(0xE0042004);',
+    '    *dbgmcu_cr = *dbgmcu_cr | 0x7u;',
+    '    return 0;',
+    '}',
+    'SYS_INIT(__tc_stm32_dbgmcu_keep_swd_alive, PRE_KERNEL_1, 0);',
+    '// CUTTLEFISH_STM32_DBGMCU_END',
+  ];
+}
+import { interruptInitLines, collectInterruptPins } from './lowering/interrupts.js';
 import { wdtInitLines } from './lowering/wdt.js';
 import { bleInitLines } from './lowering/ble.js';
 import { wifiInitLines } from './lowering/wifi.js';
@@ -62,7 +377,6 @@ import { preferencesInitLines } from './lowering/preferences.js';
 import { randomInitLines } from './lowering/random.js';
 import { generateZephyrInitCode, generateZephyrBreakpointCode, generateZephyrLogpointCode } from './debug-codegen.js';
 import { generateStaticAsyncRuntime } from '@typecad/cuttlefish/api/shared';
-import { buildTimerPolyfill } from './async/timer-polyfill.js';
 import { resolveZephyrDisplayOp, newDisplayState, type DisplayState } from './display/index.js';
 import { buildDisplayRuntime } from './display/gfx.js';
 import { ZEPHYR_DISPLAY_PROFILES, BUILT_IN_PROFILES } from './display/profiles.js';
@@ -79,26 +393,44 @@ export class ZephyrStrategy implements PlatformStrategy {
    * by the methods that need the descriptor (shimLines, resolveHALOperation
    * via lowerHalOp).
    *
-   * Tries to derive the chip descriptor from the board/MCU package's zephyr
-   * fields (via boardConstants) first. Falls back to the hardcoded
-   * chipForTarget registry for boards that haven't shipped zephyr config yet.
+   * The chip descriptor derives from the board/MCU manifest's zephyr
+   * fields (via boardConstants). There is no registry fallback — a board
+   * that never generated a manifest stays NO_BOARD_CHIP.
+   */
+  /**
+   * Eagerly resolve + cache the chip for `program`. The emitter calls this
+   * before rendering any bodies — hal-op lowering reads the module-global
+   * chip cache, and the lazy resolve (inside shimLines) runs later than the
+   * first lowered statement.
+   */
+  prepareChip(program: ProgramIR | undefined, ctx?: PlatformContext): void {
+    this.resolveChip(ctx, program);
+  }
+
+  /**
+   * Contract-board generation: a custom PCB spec (typecad contract) names
+   * its wired pads and bus families; the SoC's bus controller labels come
+   * from the installed Zephyr tree's soc dtsi. Same builder as every board.
    */
+  generateContractBoardModule(opts: {
+    soc: string;
+    zephyrBase: string;
+    pinNames: readonly string[];
+    padAliases?: readonly { exportName: string; padName: string }[];
+    peripherals: { i2c: boolean; spi: boolean; uart: boolean };
+  }): { boardTs: string; boardJson: string } {
+    return generateBoardModuleFromContract(opts);
+  }
+
   private resolveChip(ctx?: PlatformContext, program?: ProgramIR) {
-    // 1. Try board/MCU package constants (new path)
+    // The chip view reconstructs from the project's generated board
+    // manifest (boardgen's zephyr.* constants) — the one path, for every
+    // board. No curated registry, no target-based fallback: a program with
+    // no board data resolves NO_BOARD_CHIP and the lowering reports
+    // unsupported per subsystem.
     const fromBoard = resolveChipFromBoard(program?.boardConstants);
-    if (fromBoard) {
-      setActiveChip(fromBoard);
-      return fromBoard;
-    }
-
-    // 2. Fall back to frameworkData.buildTarget → hardcoded registry
-    const fd = ctx?.frameworkData as Record<string, unknown> | undefined;
-    const target =
-      (fd?.target as string | undefined) ??
-      (fd?.buildTarget as string | undefined);
-    const chip = chipForTarget(target);
-    setActiveChip(chip);
-    return chip;
+    setActiveChip(fromBoard ?? NO_BOARD_CHIP);
+    return fromBoard ?? NO_BOARD_CHIP;
   }
 
   /**
@@ -131,6 +463,7 @@ export class ZephyrStrategy implements PlatformStrategy {
     // true so nothing is stripped — mirrors framework-esp32's forcedIncludes.
     const a = (ctx as any)?.analysis;
     const uses = (f: string): boolean => (a ? !!a[f] : true);
+    const chip = this.resolveChip(ctx, _program);
     // <zephyr/drivers/gpio.h> and <cstdint> stay unconditional: gpio.h is
     // cross-cutting (gpio/power/interrupt/spi/pulse lowerings + the DT-spec
     // machinery all reference its API, and no single usesX flag owns it), and
@@ -144,10 +477,11 @@ export class ZephyrStrategy implements PlatformStrategy {
     // A program touching none of those needs no <cstdio>.
     const helpers = (a as { usedPolyfillHelpers?: Set<string> } | undefined)?.usedPolyfillHelpers;
     const needsCstdio = uses('usesCstdio') || uses('usesFS') || uses('usesPreferences')
-      || uses('usesUart')
+      || uses('usesUart') || uses('usesUsb')
       || !!helpers?.has('__tc_print') || !!helpers?.has('__tc_println');
     if (needsCstdio) inc.push('<cstdio>');
     if (uses('usesI2C')) inc.push('<zephyr/drivers/i2c.h>');
+    if (uses('usesSensor')) inc.push('<zephyr/drivers/sensor.h>');
     if (uses('usesSPI')) inc.push('<zephyr/drivers/spi.h>');
     if (uses('usesUart')) inc.push('<zephyr/drivers/uart.h>');
     // uart.h is also needed by the printf-mode debug halt shim
@@ -155,6 +489,15 @@ export class ZephyrStrategy implements PlatformStrategy {
     // program itself does not use the UART HAL. In gdb mode the shim is not
     // emitted, so skip the include there to avoid pulling in an unused header.
     if (isPrintf && !inc.includes('<zephyr/drivers/uart.h>')) inc.push('<zephyr/drivers/uart.h>');
+    // USB CDC serial: the class instance is a UART device (uart.h); the
+    // device context macros + usbd_* API live in the next-stack header.
+    if (uses('usesUsb')) {
+      if (!inc.includes('<zephyr/drivers/uart.h>')) inc.push('<zephyr/drivers/uart.h>');
+      inc.push('<zephyr/usb/usbd.h>');
+      // touch-to-reset shim callback reboots via NVIC_SystemReset()
+      // (RAM-retaining Cortex-M reset — no CONFIG_REBOOT needed).
+      if (chip?.usb?.touchReset) inc.push('<cmsis_core.h>');
+    }
     if (uses('usesADC')) inc.push('<zephyr/drivers/adc.h>');
     if (uses('usesPWM')) inc.push('<zephyr/drivers/pwm.h>');
     if (uses('usesDAC')) inc.push('<zephyr/drivers/dac.h>');
@@ -164,8 +507,7 @@ export class ZephyrStrategy implements PlatformStrategy {
     if (uses('usesFS')) inc.push('<zephyr/fs/fs.h>', '<zephyr/fs/littlefs.h>', '<zephyr/storage/flash_map.h>', '<cstring>');
     // Hardware timers via the counter driver.
     if (uses('usesHwtimer')) inc.push('<zephyr/drivers/counter.h>');
-    if (uses('usesWDT')) inc.push('<zephyr/drivers/watchdog.h>');
-    if (uses('usesPower')) inc.push('<zephyr/pm/pm.h>', '<zephyr/pm/state.h>', '<zephyr/pm/policy.h>');
+    if (uses('usesWDT') || uses('usesWdt')) inc.push('<zephyr/drivers/watchdog.h>');
     // BLE: the bt_* GATT API + the flat-string headers the shim uses. <string>
     // is needed because a Utf8 (BleValueType.Utf8) read handler lowers to a
     // std::string-returning function (the string literal return type), and the
@@ -367,70 +709,203 @@ export class ZephyrStrategy implements PlatformStrategy {
         'template<typename T, typename U> inline T cuttlefish_nullish(const T& a, U b) { return !cuttlefish_is_nullish(a) ? a : (T)b; }',
       );
     }
-    // millis() backed by the Zephyr uptime counter. uint32_t return matches
-    // the Arduino API the shared runtime expects (wraps every ~49.7 days).
-    // Kept when the program reads the clock itself — usesWallClock,
-    // deliberately WITHOUT the delay() conflation usesMillis carries, because
-    // Zephyr's delay lowers straight to k_msleep — or has a hidden poller:
-    // async functions / the async runtime, the setInterval/setTimeout
-    // scheduler, or a mounted UI's per-frame tick.
+    // The runtime clock contract: __tc_now_ms() is the monotonic ms clock
+    // the shared runtimes (UI per-frame tick, async timers, scheduler)
+    // and currentTimeMillis() lower onto. Emitted whenever anything could
+    // read the clock: explicit Time calls, async, the interval/timeout
+    // scheduler, or a mounted UI. uint32_t wraps every ~49.7 days — every
+    // consumer compares by subtraction, so the wrap is harmless.
     if (uses('usesWallClock') || uses('hasAsync') || (!a || a.timerCallCount > 0)
         || this.programUsesAsyncRuntime(program) || entryHasUI()) {
       guardBody.push(
-        'inline unsigned long millis() { return static_cast<unsigned long>(k_uptime_get_32()); }',
+        'inline uint32_t __tc_now_ms(void) { return k_uptime_get_32(); }',
       );
     }
-    // PROGMEM: only the (Arduino-oriented) UI runtime header can reference it.
-    if (entryHasUI()) {
+    // Num fluent math (Num.abs/min/max) + the free math trio.
+    // On Zephyr newlib none of these
+    // names are macros, so the underscore-escape rewrite the
+    // strategy needs is not. abs(long)/min/max deliberately overload (not
+    // shadow) newlib's abs(int) — exact-match int calls still resolve to the
+    // libc overload.
+    if (uses('usesNum')) {
       guardBody.push(
-        '#ifndef PROGMEM', '#define PROGMEM', '#endif',
+        'struct __tc_Num {',
+        '    static long abs(long x) { return x < 0 ? -x : x; }',
+        '    static long min(long a, long b) { return a < b ? a : b; }',
+        '    static long max(long a, long b) { return a > b ? a : b; }',
+        // The core emitter escapes abs/min/max member calls to a trailing
+        // underscore (C-library collision) — provide the escaped spellings so
+        // Num.abs_()/Num.min_()/Num.max_() resolve too.
+        '    static long abs_(long x) { return x < 0 ? -x : x; }',
+        '    static long min_(long a, long b) { return a < b ? a : b; }',
+        '    static long max_(long a, long b) { return a > b ? a : b; }',
+        '} Num;',
+        'inline long abs(long v) { return v < 0 ? -v : v; }',
+        'inline long min(long a, long b) { return a < b ? a : b; }',
+        'inline long max(long a, long b) { return a > b ? a : b; }',
+        // Escaped free-function spellings — the escape applies to bare call
+        // sites on some paths (abs_(-42)); cover both.
+        'inline long abs_(long v) { return v < 0 ? -v : v; }',
+        'inline long min_(long a, long b) { return a < b ? a : b; }',
+        'inline long max_(long a, long b) { return a > b ? a : b; }',
       );
     }
-    // map()/constrain() Arduino-API helpers — dead code unless called. The
-    // setup emitter ORs entryHasUI() into usesConstrain before we see it (the
-    // UI runtime's progress/range draw calls constrain).
-    if (uses('usesMap')) {
-      guardBody.push(
-        'inline long map(long x, long in_min, long in_max, long out_min, long out_max) { return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min; }',
-      );
+    // Random PRNG shim: the Random namespace lowers to the __tc_rand_* PRNG.
+    // Emitted when the program actually uses the random.* ops, so a minimal
+    // program's shim stays empty. The dispatcher + PRNG helpers must precede
+    // the shims that call them (the guard block emits in push order, and
+    // C++ needs the definitions before use).
+    if (this.needsGpioReadShim(program, ctx)) {
+      guardBody.push(...emitGpioDevDispatcher(chip));
+    }
+    if (uses('usesRandom')) {
+      guardBody.push(...randomInitLines());
     }
-    if (uses('usesConstrain')) {
+    // PROGMEM note: only some UI runtime headers reference it.
+    if (entryHasUI()) {
       guardBody.push(
-        'inline long constrain(long x, long a, long b) { return x < a ? a : (x > b ? b : x); }',
+        '#ifndef PROGMEM', '#define PROGMEM', '#endif',
       );
     }
     // Test-runner console helpers: @typecad/expect's Zephyr shim calls these
     // for protocol output. Overloaded for string (const char*) and numeric
     // (double) so the same call site works for markers and test values.
-    // Emitted only when the expect preprocessor actually injected the calls
-    // (tracked as usedPolyfillHelpers).
-    if (!a || !!helpers?.has('__tc_print') || !!helpers?.has('__tc_println')) {
+    // The fs lowering bakes __tc_println into its error paths too, so the
+    // overloads are emitted unconditionally — ctx.analysis can be absent or
+    // stale on UI programs, and missing definitions would be a link error.
+    //
+    // The numeric form formats via INTEGER conversions only: libc float
+    // printf is not dependable across SDKs — the 0.17.5 toolchain swapped
+    // newlib for picolibc, whose default build silently prints NOTHING for
+    // %g (the same trap as newlib-nano's -u _printf_float), which emptied
+    // every [TC:EXPECT:...:value:] line. Integer %lld works in every libc
+    // configuration, and the host parser accepts plain fixed-point.
+    {
       guardBody.push(
         'inline void __tc_print(const char* s) { printf("%s", s); }',
-        'inline void __tc_print(double v) { printf("%g", v); }',
+        [
+          'static inline char* __tc_fmt_num_buf(double v, char* out, size_t cap) {',
+          '    if (v != v) { snprintf(out, cap, "nan"); return out; }',
+          '    double a = v < 0 ? -v : v;',
+          '    long long ip = (long long)a;',
+          '    long long fr = (long long)((a - (double)ip) * 1000000.0 + 0.5);',
+          '    if (fr >= 1000000LL) { ip += 1LL; fr = 0LL; }',
+          '    int used = 0;',
+          '    if (v < 0 && (ip != 0LL || fr != 0LL)) { out[used++] = \'-\'; out[used] = \'\\0\'; }',
+          '    if (fr == 0LL) { snprintf(out + used, cap - (size_t)used, "%lld", ip); return out; }',
+          '    char fbuf[8];',
+          '    int len = snprintf(fbuf, sizeof(fbuf), "%06lld", fr);',
+          '    while (len > 0 && fbuf[len - 1] == \'0\') { fbuf[--len] = \'\\0\'; }',
+          '    snprintf(out + used, cap - (size_t)used, "%lld.%s", ip, fbuf);',
+          '    return out;',
+          '}',
+          'static void __tc_fmt_num(double v) { char __b[32]; printf("%s", __tc_fmt_num_buf(v, __b, sizeof(__b))); }',
+        ].join('\n'),
+        'inline void __tc_print(double v) { __tc_fmt_num(v); }',
         'inline void __tc_println(const char* s) { printf("%s\\n", s); }',
-        'inline void __tc_println(double v) { printf("%g\\n", v); }',
+        'inline void __tc_println(double v) { __tc_fmt_num(v); printf("\\n"); }',
+      );
+    }
+    // Serial-port write helper: writes a scalar to a UART/CDC device a byte at
+    // a time. Overloaded on const char* (strings, snprintf buffers) and double
+    // (numbers/booleans) so a single __tc_dev_put(dev, value) call site formats
+    // any writable scalar — the same overload contract __tc_print uses. Emitted
+    // when the program writes a UART or USB port (both include uart.h).
+    if (uses('usesUart') || uses('usesUsb')) {
+      guardBody.push(
+        'static inline void __tc_dev_put(const struct device* dev, const char* s) {',
+        '    for (; *s != \'\\0\'; ++s) { uart_poll_out(dev, *s); }',
+        '}',
+        'static inline void __tc_dev_put(const struct device* dev, double v) {',
+        '    char __b[32];',
+        '    __tc_dev_put(dev, __tc_fmt_num_buf(v, __b, sizeof(__b)));',
+        '}',
       );
     }
 
     // Per-peripheral bus state — gated on the same ctx.analysis.usesX flags as
     // forcedIncludes, so an unused peripheral emits no state (and its header is
-    // not included). Mirrors framework-esp32's shimLines espInit block.
+    // not included). Mirrors framework-esp32's shimLines espInit block. Within
+    // a bus, only the instances the program drives get state — an unused
+    // declared controller's __tc_<bus>N_dev trips -Wunused-variable under
+    // Zephyr's -Werror (collectUsedBusIndices; probes with no program emit all).
+    const usedBuses = collectUsedBusIndices(program);
     if (uses('usesI2C') && chip.i2c) {
-      for (let i = 0; i < chip.i2c.controllers.length; i++) guardBody.push(...i2cInitLines(chip, i));
+      for (let i = 0; i < chip.i2c.controllers.length; i++) {
+        if (usedBuses && !usedBuses.i2c.has(i)) continue;
+        guardBody.push(...i2cInitLines(chip, i));
+      }
     }
     if (uses('usesSPI') && chip.spi) {
-      for (let i = 0; i < chip.spi.controllers.length; i++) guardBody.push(...spiInitLines(chip, i));
+      for (let i = 0; i < chip.spi.controllers.length; i++) {
+        if (usedBuses && !usedBuses.spi.has(i)) continue;
+        guardBody.push(...spiInitLines(chip, i));
+      }
     }
     if (uses('usesUart') && chip.uart) {
-      for (let i = 0; i < chip.uart.controllers.length; i++) guardBody.push(...uartInitLines(chip, i));
+      for (let i = 0; i < chip.uart.controllers.length; i++) {
+        if (usedBuses && !usedBuses.uart.has(i)) continue;
+        guardBody.push(...uartInitLines(chip, i));
+      }
+      // Thin UART RX rings — one interrupt-drained ring per port the program
+      // reads (uart.rx_* ops). Emitted after the device handles it references.
+      const rings = collectUartRings(program);
+      if (rings) {
+        for (const r of rings.values()) {
+          guardBody.push(...uartRingStateLines(r.index, r.ring));
+        }
+      }
+    }
+    // DT-bound sensors — one state block per constructed part (device handle
+    // + sensor_value scratch). The lowering's __tc_sensor_* references and the
+    // overlay's DT child nodes derive from the same facts (lowering/sensor.ts).
+    if (uses('usesSensor')) {
+      const sensors = collectSensors(program);
+      if (sensors) {
+        for (const s of sensors.values()) {
+          guardBody.push(...sensorStateLines(s.part, s.bus, s.port, s.busKind, s.spiHz, s.spiMode, s.alertPin));
+        }
+      }
+    }
+    // Thin SPI targets — one spi_dt_spec per constructed target, against the
+    // DT child node the overlay emits. Same shared-facts discipline (the
+    // tc-spit-cfg comment is the overlay scanner's channel).
+    if (uses('usesSPI')) {
+      const targets = collectSpiTargets(program);
+      if (targets) {
+        for (const t of targets.values()) {
+          guardBody.push(...spiTargetStateLines(t.bus, t.cs, t.hz, t.mode));
+        }
+      }
+    }
+    // Thin Threads — one stack + k_thread + trampoline per started slot.
+    // Keyed on thread.start ops only: join() without a prior start() on the
+    // same index is a user error that surfaces as the undefined slot symbol.
+    {
+      const threads = collectThreads(program);
+      if (threads) {
+        for (const t of threads.values()) {
+          guardBody.push(...threadStateLines(t.instance, t.stackBytes));
+        }
+      }
+    }
+    if (uses('usesUsb') && chip.usb) {
+      guardBody.push(...usbdDeviceLines(chip));
+      for (let i = 0; i < chip.usb.cdcInstances; i++) guardBody.push(...usbInitLines(chip, i));
+    }
+    // PWM init also fires (with alias vars for the override pins) when a
+    // program drives ONLY inline-override channels on a chip with no pwm
+    // facts — the lowered calls reference those aliases.
+    {
+      const pwmUserSpecs = collectPwmOverrideSpecs(program);
+      if ((uses('usesPWM') && chip.pwm) || pwmUserSpecs.length > 0) {
+        guardBody.push(...pwmInitLines(chip, collectUsedPins(program, 'pwm', chip), pwmUserSpecs));
+      }
     }
-    if (uses('usesADC') && chip.adc) guardBody.push(...adcInitLines(chip));
-    if (uses('usesPWM') && chip.pwm) guardBody.push(...pwmInitLines(chip));
     if (uses('usesDAC') && chip.dac) guardBody.push(...dacInitLines(chip));
     if (uses('usesHwtimer') && chip.hwtimer) guardBody.push(...hwtimerInitLines(chip));
-    if (uses('usesInterrupts')) guardBody.push(...interruptInitLines(chip));
-    if (uses('usesWDT') && chip.wdt) guardBody.push(...wdtInitLines(chip));
+    if (uses('usesInterrupts')) guardBody.push(...interruptInitLines(chip, program ? collectInterruptPins(program) : undefined));
+    if ((uses('usesWDT') || uses('usesWdt')) && chip.wdt) guardBody.push(...wdtInitLines(chip));
     if (uses('usesBle')) guardBody.push(...bleInitLines());
     // Display runtime (rect/text renderer): the DIRECT-call display path (user
     // code calling screen.display.fillRect etc., no @typecad/ui). Emitted only
@@ -454,7 +929,29 @@ export class ZephyrStrategy implements PlatformStrategy {
     if (uses('usesMqtt')) guardBody.push(...mqttInitLines());
     if (uses('usesPreferences')) guardBody.push(...preferencesInitLines());
     if (uses('usesFS')) guardBody.push(...fsInitLines());
-    if (uses('usesRandom')) guardBody.push(...randomInitLines());
+    // The ADC init block also fires (with the override devices' handles)
+    // when a program uses ONLY inline-override reads on a chip with no adc
+    // facts — otherwise those reads reference undeclared device handles.
+    {
+      const adcOverrideDevices = collectAdcOverrideDevices(program);
+      if ((uses('usesADC') && chip.adc) || adcOverrideDevices.size > 0) {
+        guardBody.push(...adcInitLines(chip, collectUsedPins(program, 'adc'), adcOverrideDevices));
+      }
+    }
+    // STM32F4: keep the core debug port alive across WFI sleep. The DBGMCU
+    // gates PPB access while the core sleeps unless DBGMCU_CR DBG_SLEEP/
+    // DBG_STOP/DBG_STANDBY are set — without them openocd cannot examine or
+    // halt the running target ("Failed to read memory at 0xe000ed04", "AP
+    // write error, reset will not halt"), and with no RST pad on boards like
+    // the Black Pill the only recovery is the BOOT0 bootloader. Zephyr's
+    // CONFIG_STM32_ENABLE_DEBUG_SLEEP_STOP sets only DBG_STOP on F4 (the
+    // soc_config.c F1/L1 branch is the one that sets DBG_SLEEP), so the bits
+    // are set here at boot, unconditionally for dev boards.
+    // (soc is empty on board-resolved chips — the SoC name rides in the
+    // qualified id's variant segment, e.g. 'blackpill_f411ce/stm32f411xe'.)
+    if (chip.soc.startsWith('stm32f4') || /stm32f4\d*/.test(chip.id)) {
+      guardBody.push(...stm32f4DbgmcuLines());
+    }
 
     const lines: string[] = [];
     if (guardBody.length > 0) {
@@ -516,6 +1013,11 @@ export class ZephyrStrategy implements PlatformStrategy {
         'static inline bool __tc_bp_is_disabled(int id) { return id >= 0 && id < 256 && __tc_bp_disabled[id]; }',
         // Console input: poll the UART console device. DEVICE_DT_GET(DT_CHOSEN(zephyr_console))
         // resolves to the board's console (UART0 USB-CDC on the XIAO nRF52840).
+        // Not every board DTS declares a zephyr,console chosen (STM32MP1 M-side,
+        // display/carrier boards): there is nothing to print a prompt on and
+        // nothing to read a key from, so breakpoints auto-continue instead of
+        // hanging an unattended run.
+        '#if DT_HAS_CHOSEN(zephyr_console)',
         'static inline char __tc_debug_wait_for_continue(int id) {',
         '    const struct device* __con = DEVICE_DT_GET(DT_CHOSEN(zephyr_console));',
         '    unsigned char __c = 0;',
@@ -528,33 +1030,21 @@ export class ZephyrStrategy implements PlatformStrategy {
         "    if ((__c == 's') || (__c == 'S')) { if (id >= 0 && id < 256) __tc_bp_disabled[id] = true; }",
         '    return static_cast<char>(__c);',
         '}',
+        '#else',
+        'static inline char __tc_debug_wait_for_continue(int id) { (void)id; return static_cast<char>(0); }',
+        '#endif // DT_HAS_CHOSEN(zephyr_console)',
         '#endif // __TC_BP_DISABLED_DEFINED',
         '',
       );
     }
 
-    // --- Zephyr entrypoint: main() runs setup()/loop() directly ---
-    // The cuttlefish synthesizer emits setup() and loop() (it keys off
-    // entrypointFunctionName()="setup" and requiresLoopFunction()=true). Zephyr
-    // is a standard C main()-based RTOS, so main() bridges the two: it calls
-    // setup() once, then loops loop() forever, yielding to the scheduler with
-    // k_msleep(1) each iteration (cheap cooperative yield — matches the esp32
-    // app_main pattern). Declared extern here because setup/loop live in a
-    // separate translation unit when generateHeaderFile() splits them into the
-    // header.
-    lines.push(
-      'extern void setup(void);',
-      'extern void loop(void);',
-      '',
-      'int main(void) {',
-      '    setup();',
-      '    for (;;) {',
-      '        loop();',
-      '        k_msleep(1);',
-      '    }',
-      '    return 0;',
-      '}',
-    );
+    // --- Zephyr entrypoint ---------------------------------------------------
+    // No bridge here: the synthesizer emits main() itself (it keys off
+    // entrypointFunctionName()="main" and requiresLoopFunction()=false), with
+    // the top-level statements inlined. Per-frame driving (ui_tick, microtask
+    // pumping, async task .run()) is appended to main() by the driver
+    // machinery via asyncDriverFunctionName()="main" + hostEventLoop() — see
+    // asyncLoopInjection for the scheduler loop it closes over.
 
     // GPIO read shim: emitted only when something actually reads a pin at
     // runtime — user digitalRead() calls, the @typecad/safety voter (calls
@@ -574,17 +1064,19 @@ export class ZephyrStrategy implements PlatformStrategy {
     // dispatcher that resolves the owning controller's device per pin;
     // single-controller SoCs collapse it to a one-liner. Each DT_NODELABEL is
     // still compile-time-resolved per branch, so it is always statically valid.
+    // (The dispatcher itself now lives at the top of the guard block — it must
+    // precede the wiring-ambient shims and the PinGroup factory there; the
+    // __tc_gpio_read body below is what still needs emitting here.)
     if (this.needsGpioReadShim(program, ctx)) {
-      lines.push(...emitGpioDevDispatcher(chip));
       lines.push(
-        'inline int __tc_gpio_read(int pin) { return gpio_pin_get_raw(__tc_gpio_dev(static_cast<uint32_t>(pin)), static_cast<gpio_pin_t>(pin)); }',
+        'inline int __tc_gpio_read(int pin) { return gpio_pin_get_raw(__tc_gpio_dev(static_cast<uint32_t>(pin)), __tc_gpio_pin(static_cast<uint32_t>(pin))); }',
       );
     }
     // __tc_gpio_write / __tc_delay_us are only referenced via @typecad/safety
     // lowering, so they stay gated on it.
     if (program && programUsesSafety(program)) {
       lines.push(
-        'inline void __tc_gpio_write(uint32_t pin, uint32_t value) { gpio_pin_set_raw(__tc_gpio_dev(pin), pin, value); }',
+        'inline void __tc_gpio_write(uint32_t pin, uint32_t value) { gpio_pin_set_raw(__tc_gpio_dev(pin), __tc_gpio_pin(pin), value); }',
         '#ifndef __TC_DELAY_US_DEFINED',
         '#define __TC_DELAY_US_DEFINED',
         'inline void __tc_delay_us(uint32_t us) { k_busy_wait(us); }',
@@ -604,11 +1096,16 @@ export class ZephyrStrategy implements PlatformStrategy {
     // Collect the pins the program uses for output config, ADC reads, and
     // interrupt attaches — deep-walking the IR the same way framework-esp32
     // does (its profileDiagnostics walks program to find gpio.set_mode /
-    // power.deep_sleep_pin / adc.read nodes).
+    // adc.read nodes).
     const outputPins = new Set<number>();
     const adcReadPins = new Set<number>();
+    const adcOverriddenPins = new Set<number>();
+    const pwmOverriddenPins = new Set<number>();
     const interruptPins = new Set<number>();
+    const wdtOps = new Set<string>();
     const dacPins = new Set<number>();
+    const pwmPins = new Set<number>();
+    const busInstances = { i2c: new Set<number>(), spi: new Set<number>(), uart: new Set<number>() };
     const hwtimerInstances = new Set<number>();
     let usesWifiOps = false;
     let usesHttpOps = false;
@@ -623,16 +1120,50 @@ export class ZephyrStrategy implements PlatformStrategy {
               && typeof op.pin === 'number') {
             outputPins.add(op.pin);
           }
-          if ((op.operation === 'adc.read' || op.operation === 'adc.read_voltage')
+          if ((op.operation === 'adc.read' || op.operation === 'adc.read_voltage'
+                || op.operation === 'adc.read_raw' || op.operation === 'adc.read_mv')
               && typeof op.pin === 'number') {
             adcReadPins.add(op.pin);
+            // Inline routing overrides (construction opts): the user vouches
+            // for the pin — the unavailable-pin diagnostic does not apply.
+            if ((typeof op.channelOverride === 'number' && op.channelOverride >= 0)
+                || (typeof op.deviceOverride === 'string' && op.deviceOverride !== '')) {
+              adcOverriddenPins.add(op.pin);
+            }
           }
-          if (op.operation === 'interrupt.attach' && typeof op.pin === 'number') {
+          if (op.operation === 'interrupt.attach_flags' && typeof op.pin === 'number') {
             interruptPins.add(op.pin);
           }
-          if (op.operation === 'dac.write' && typeof op.pin === 'number') {
+          if (typeof op.operation === 'string' && op.operation.startsWith('wdt.')) {
+            wdtOps.add(op.operation);
+          }
+          if ((op.operation === 'dac.write' || op.operation === 'dac.write_value')
+              && typeof op.pin === 'number') {
             dacPins.add(op.pin);
           }
+          if ((op.operation === 'pwm.set_pulse' || op.operation === 'pwm.set_duty'
+                || op.operation === 'pwm.set_period')
+              && typeof op.pin === 'number') {
+            pwmPins.add(op.pin);
+            if ((typeof op.controllerOverride === 'string' && op.controllerOverride !== '')
+                || (typeof op.channelOverride === 'number' && op.channelOverride >= 0)) {
+              pwmOverriddenPins.add(op.pin);
+            }
+          }
+          // Bus instance usage: which I2C/SPI/UART controller indexes the
+          // program drives (the lowering resolves index N against
+          // chip.<bus>.controllers[N]; an undeclared index emits references
+          // to a state block that is never declared → link error).
+          if (typeof op.operation === 'string') {
+            const busMatch = op.operation.match(/^(i2c|spi|uart)\./);
+            if (busMatch) {
+              const bus = busMatch[1] as 'i2c' | 'spi' | 'uart';
+              const id = typeof op.bus === 'string' ? op.bus
+                : typeof op.port === 'string' ? op.port : undefined;
+              const m = id?.match(/(\d+)$/);
+              if (m) busInstances[bus].add(parseInt(m[1], 10));
+            }
+          }
           if (typeof op.operation === 'string' && op.operation.startsWith('hwtimer.')) {
             const inst = typeof op.instance === 'number'
               ? op.instance
@@ -659,42 +1190,53 @@ export class ZephyrStrategy implements PlatformStrategy {
     visit(program);
 
     // ── ADC pin validity ────────────────────────────────────────────────────
-    // The SAADC lowering resolves a HAL pin to a channel via the chip
-    // descriptor's adc.channels map. A pin not in that map resolves to -1,
-    // which emits __tc_adc-1_setup() — an undefined symbol → link error. Flag
-    // it at compile time with a clear message instead of an opaque link failure.
+    // The SAADC lowering resolves the adc.read argument to a channel via the
+    // chip descriptor's adc.channels map (pin-first, then channel-number
+    // fallback for the Arduino-compat ADC.read(n) form — see
+    // adcChannelForPin). A number resolving to neither emits
+    // __tc_adc-1_setup() — an undefined symbol → link error. Flag it at
+    // compile time with a clear message instead of an opaque link failure.
     const adcPins = new Set((chip.adc?.channels ?? []).map((c) => c.pin));
     for (const pin of adcReadPins) {
-      if (!adcPins.has(pin)) {
+      if (adcOverriddenPins.has(pin)) continue;
+      if (adcChannelForPin(chip, pin) < 0) {
         const valid = [...adcPins].sort((x, y) => x - y).join(', ');
+        // Cross-peripheral suggestion: the facts know what this pin IS wired
+        // to — a PWM-capable pin misread as analog is the classic mix-up.
+        const pwmOnPin = (chip.pwm?.specs ?? []).find((s) => s.pin === pin);
+        const mixup = pwmOnPin
+          ? ` GPIO ${pin} carries PWM on this board (${pwmOnPin.controller} ch ${pwmOnPin.channel}) — did you mean new PWM(${pin}, …)?`
+          : '';
         diags.push({
           severity: 'error',
           code: 'zephyr-adc-pin-unavailable',
           message: `GPIO ${pin} is not a SAADC channel on ${chip.id} and cannot be read with adc.read.`,
           hint: valid
-            ? `Use an analog-capable pin. On ${chip.id} (SAADC): ${valid}.`
-            : `This target has no ADC channels mapped in its chip descriptor.`,
+            ? `Use an analog-capable pin. On ${chip.id} (SAADC): ${valid}.${mixup}`
+            : `This target has no ADC channels mapped in its chip descriptor.${mixup}`,
           source: program.fileName,
         });
       }
     }
 
     // ── Interrupt pin validity ──────────────────────────────────────────────
-    // interrupt.attach only wires a real callback for pins listed in the chip
-    // descriptor's gpio.interruptPins (the lowering needs a DT spec to build
-    // the gpio_callback struct at init). An attach on an unlisted pin emits
-    // only a comment — silent no-op. Flag it so the user knows the handler
-    // will never fire.
+    // GPIO.onInterrupt works on every REAL GPIO: pins listed in the chip
+    // descriptor's gpio.interruptPins wire through the DT-spec chain, any
+    // other in-range pin through the raw-controller chain. What cannot work
+    // is a pin number no declared controller range covers (e.g. 99 on a
+    // 34-pin SoC) — that lowering is a comment (silent no-op). Flag only
+    // that case.
     const intPins = new Set((chip.gpio.interruptPins ?? []).map((p) => p.pin));
     for (const pin of interruptPins) {
-      if (!intPins.has(pin)) {
+      if (intPins.has(pin)) continue;
+      const inRange = !chip.gpioControllers || chip.gpioControllers.length === 0
+        || chip.gpioControllers.some((r) => pin >= r.minPin && pin <= r.maxPin);
+      if (!inRange) {
         diags.push({
           severity: 'error',
           code: 'zephyr-interrupt-pin-unavailable',
-          message: `GPIO ${pin} has no interrupt DT spec on ${chip.id}; interrupt.attach is a no-op.`,
-          hint: intPins.size > 0
-            ? `Add the pin to the chip descriptor's gpio.interruptPins, or use an interrupt-capable pin: ${[...intPins].sort((x, y) => x - y).join(', ')}.`
-            : `This target declares no interrupt pins in its chip descriptor; interrupts are not available.`,
+          message: `GPIO ${pin} does not exist on ${chip.id}; onInterrupt is a no-op.`,
+          hint: `Use a real GPIO on this board (controller ranges: ${chip.gpioControllers.map((r) => `${r.nodelabel} ${r.minPin}-${r.maxPin}`).join(', ')}).`,
           source: program.fileName,
         });
       }
@@ -710,13 +1252,82 @@ export class ZephyrStrategy implements PlatformStrategy {
       const dacChannels = new Set((chip.dac?.channels ?? []).map((c) => c.pin));
       for (const pin of dacPins) {
         if (!dacChannels.has(pin)) {
+          const adcCh = (chip.adc?.channels ?? []).find((c) => c.pin === pin);
+          const mixup = adcCh
+            ? ` GPIO ${pin} is an ADC channel (${adcCh.controller ?? chip.adc?.nodeLabel ?? 'adc'} ch ${adcCh.channel}) — did you mean new ADC(${pin})?`
+            : '';
           diags.push({
             severity: 'error',
             code: 'zephyr-dac-pin-unavailable',
             message: `GPIO ${pin} is not a DAC channel on ${chip.id} and cannot be driven with dac.write.`,
             hint: dacChannels.size > 0
-              ? `Use a DAC-capable pin. On ${chip.id}: ${[...dacChannels].sort((x, y) => x - y).join(', ')}.`
-              : `${chip.id} has no DAC. Use an esp32_devkitc target (ESP32 DAC on GPIO25/26).`,
+              ? `Use a DAC-capable pin. On ${chip.id}: ${[...dacChannels].sort((x, y) => x - y).join(', ')}.${mixup}`
+              : `${chip.id} has no DAC. Use an esp32_devkitc target (ESP32 DAC on GPIO25/26).${mixup}`,
+            source: program.fileName,
+          });
+        }
+      }
+    }
+
+    // ── PWM pin validity ────────────────────────────────────────────────────
+    // pwm.write resolves a HAL pin to a DT spec via the chip descriptor's
+    // pwm.specs (static) or pwm.matrix (ESP32 LEDC: any matrix pin synthesizes
+    // a spec at build time). A pin on neither lowers to a comment — the pin
+    // silently never toggles. Flag it so the user knows (warning, not error:
+    // boards legitimately ship partial PWM coverage, e.g. only the aliased LED
+    // channel, and the rest of the program still works).
+    const pwmMatrix = chip.pwm?.matrix;
+    const pwmSpecPins = new Set([
+      ...(chip.pwm?.specs ?? []).map((s) => s.pin),
+      ...(pwmMatrix?.pins ?? []),
+    ]);
+    const pwmValid = [...pwmSpecPins].sort((x, y) => x - y).join(', ');
+    for (const pin of pwmPins) {
+      if (pwmOverriddenPins.has(pin)) continue;
+      if (!pwmSpecPins.has(pin)) {
+        // Cross-peripheral suggestion: an analog pin driven as PWM is the
+        // other classic mix-up.
+        const adcCh = (chip.adc?.channels ?? []).find((c) => c.pin === pin);
+        const mixup = adcCh
+          ? ` GPIO ${pin} is an ADC channel (${adcCh.controller ?? chip.adc?.nodeLabel ?? 'adc'} ch ${adcCh.channel}) — did you mean new ADC(${pin})?`
+          : '';
+        diags.push({
+          severity: 'warning',
+          code: 'zephyr-pwm-pin-unavailable',
+          message: pwmMatrix
+            ? `pwm on GPIO ${pin} lowers to a no-op: the pin is outside ${chip.id}'s PWM-capable set (USB, flash/PSRAM, strapping, and console pads are excluded), so nothing is driven.`
+            : `pwm on GPIO ${pin} lowers to a no-op: the pin has no PWM spec in ${chip.id}'s chip descriptor, so nothing is driven.`,
+          hint: pwmValid
+            ? pwmMatrix
+              ? `PWM-capable pins on ${chip.id} (first ${pwmMatrix.channelCount} driven get channels): ${pwmValid}.${mixup}`
+              : `PWM-capable pins on ${chip.id}: ${pwmValid}.${mixup}`
+            : `${chip.id} maps no PWM channels in its chip descriptor — pwm.* are no-ops on this target.${mixup}`,
+          source: program.fileName,
+        });
+      }
+    }
+    // ── Bus instance validity ───────────────────────────────────────────────
+    // The bus lowerings resolve instance N against chip.<bus>.controllers[N]
+    // and emit `__tc_<bus>N_dev` references; the state block is only declared
+    // for declared controllers, so an out-of-range instance is an undefined
+    // symbol at link time. Flag it here with the board's real controller set
+    // instead (mirrors how the ADC gate replaces an opaque link error).
+    const busLabels: Record<'i2c' | 'spi' | 'uart', { name: string; label: string }> = {
+      i2c: { name: 'I2C', label: 'Wire' },
+      spi: { name: 'SPI', label: 'SPI' },
+      uart: { name: 'UART', label: 'Serial' },
+    };
+    for (const bus of ['i2c', 'spi', 'uart'] as const) {
+      const controllers = chip[bus]?.controllers ?? [];
+      for (const inst of busInstances[bus]) {
+        if (inst < 0 || inst >= controllers.length) {
+          diags.push({
+            severity: 'error',
+            code: 'zephyr-bus-instance-unavailable',
+            message: `${busLabels[bus].name}${inst} is used but ${chip.id} declares only ${controllers.length} ${busLabels[bus].name} controller(s) in its Zephyr chip data — the generated code would not link.`,
+            hint: controllers.length > 0
+              ? `Use ${busLabels[bus].name}0 (the board's default-enabled controller: ${controllers.map((c) => c.nodeLabel).join(', ')}).`
+              : `${chip.id} declares no ${busLabels[bus].name} controllers for Zephyr.`,
             source: program.fileName,
           });
         }
@@ -750,12 +1361,36 @@ export class ZephyrStrategy implements PlatformStrategy {
       }
     }
 
+    // ── Watchdog availability ───────────────────────────────────────────────
+    // wdt.* resolves the device via the chip descriptor's wdt.nodeLabel. A
+    // chip without that entry (e.g. SAM D21 — Zephyr's samd21 dtsi exposes
+    // no watchdog node) lowers to a comment — flag it so the user knows the
+    // watchdog never arms.
+    if (wdtOps.size > 0 && !chip.wdt) {
+      diags.push({
+        severity: 'error',
+        code: 'zephyr-wdt-unavailable',
+        message: `Watchdog ops are used but ${chip.id} exposes no watchdog device.`,
+        hint: `${chip.id} declares no wdt.nodeLabel (Zephyr's devicetree for this SoC has no watchdog node). Use a target with a watchdog, or drop the wdt.* calls.`,
+        source: program.fileName,
+      });
+    }
+
+    // ── Radio presence: family-derived, not board-curated ───────────────────
+    // Espressif ESP32 variants carry a 2.4GHz WiFi radio; every other Zephyr
+    // family in the catalog is radioless (until an Ethernet/board-wifi fact
+    // exists). Derived from the soc name — or, when no board module was
+    // generated, from the raw build target the config carries.
+    const familyTarget = `${chip.soc || ''} ${(ctx?.frameworkData as Record<string, unknown> | undefined)?.target ?? ''} ${(ctx?.frameworkData as Record<string, unknown> | undefined)?.buildTarget ?? ''}`.toLowerCase();
+    const wifiSupported = chip.wifi?.supported
+      ?? familyTarget.split(/[^a-z0-9]+/).some((t) => t.startsWith('esp32'));
+
     // ── WiFi target validity ────────────────────────────────────────────────
     // WiFi ops require a chip with a WiFi radio. The ESP32-S3 descriptor sets
     // wifi.supported; the XIAO nRF52840 omits it (no radio). Flag wifi usage on
     // a radioless chip so the user gets a clear "use an ESP32 target" message
     // instead of an opaque link/DT failure.
-    if (usesWifiOps && !chip.wifi?.supported) {
+    if (usesWifiOps && !wifiSupported) {
       diags.push({
         severity: 'error',
         code: 'zephyr-wifi-unavailable-on-target',
@@ -773,7 +1408,7 @@ export class ZephyrStrategy implements PlatformStrategy {
     // gets a clear "use an ESP32 target" message instead of an opaque link or
     // runtime failure. (HTTP rides over WiFi here; an Ethernet target would
     // set wifi.supported via a different transport flag if/when added.)
-    if (usesHttpOps && !chip.wifi?.supported) {
+    if (usesHttpOps && !wifiSupported) {
       diags.push({
         severity: 'error',
         code: 'zephyr-http-unavailable-on-target',
@@ -786,7 +1421,7 @@ export class ZephyrStrategy implements PlatformStrategy {
     // ── MQTT target validity ─────────────────────────────────────────────
     // Same constraint as HTTP: MQTT needs a network transport to reach a broker.
     // Flag mqtt usage on a radioless chip so the user picks a networked target.
-    if (usesMqttOps && !chip.wifi?.supported) {
+    if (usesMqttOps && !wifiSupported) {
       diags.push({
         severity: 'error',
         code: 'zephyr-mqtt-unavailable-on-target',
@@ -805,16 +1440,30 @@ export class ZephyrStrategy implements PlatformStrategy {
   }
 
   /**
-   * `loop` is forward-declared `extern` by the main() bridge shim
-   * (extern void loop(void); → int main(void) {...}), so emitting a
-   * `static void loop()` definition redeclares it with conflicting linkage,
-   * which GCC rejects. Exclude it from the static forward-declaration path
-   * — mirrors how ArduinoStrategy excludes `loop` (the Arduino core forward-
-   * declares it extern). `setup` is already handled because it equals
+   * Strip Arduino library headers that @typecad/hal's class surfaces register
+   * (I2CBus → <Wire.h>, SPIBus → <SPI.h>). The Zephyr
+   * equivalents are usage-gated forcedIncludes (<zephyr/drivers/i2c.h>, …),
+   * so an unstripped Wire.h reaches the west build and gcc rejects it
+   * ("Wire.h: No such file or directory") — this hook is why I2C/SPI class
+   * usage on Zephyr used to fail at compile time.
+   */
+  filterRequiredIncludes(includes: string[]): string[] {
+    // Arduino-core / AVR-only headers the HAL classes declare via __includes.
+    // On Zephyr the watchdog lowers to the Zephyr driver (<zephyr/drivers/
+    // watchdog.h>, forced under usesWDT) — <avr/wdt.h> does not exist there.
+    const arduinoOnlyHeaders = new Set(['<Wire.h>', '<SPI.h>', '<avr/wdt.h>', '<avr/io.h>', '<avr/interrupt.h>', '<avr/sleep.h>', '<avr/power.h>']);
+    return includes.filter((i) => !arduinoOnlyHeaders.has(i));
+  }
+
+  /**
+   * Nothing to exclude: no shim or Zephyr core header forward-declares a user
+   * function extern (the old setup()/loop() bridge was the only consumer of
+   * this hook, excluding `loop`). The entrypoint itself (`main`) is already
+   * excluded from the static forward-declaration path because it equals
    * entrypointFunctionName().
    */
   forwardDeclarationExclusions(): string[] {
-    return ['loop'];
+    return [];
   }
 
   // ── File shape ──────────────────────────────────────────────────────────
@@ -824,11 +1473,11 @@ export class ZephyrStrategy implements PlatformStrategy {
   }
 
   entrypointFunctionName(): string {
-    return 'setup';
+    return 'main';
   }
 
   requiresLoopFunction(): boolean {
-    return true;
+    return false;
   }
 
   overrideBaseName(
@@ -838,17 +1487,17 @@ export class ZephyrStrategy implements PlatformStrategy {
     isNpmPackage: boolean,
   ): string {
     // npm packages are library-style — don't rename. Entry files (non-npm) take
-    // the out-dir name (mirrors Arduino's .ino-must-match-dir rule). Everything
-    // else passes through. (The manifest's entrypoint.overrideBaseName field is
-    // dead — never read in src/ — so this method is the sole name source.)
+    // the out-dir name (mirrors the directory-name-must-match-entry rule).
+    // Everything else passes through. (The manifest's entrypoint.overrideBaseName
+    // field is dead — never read in src/ — so this method is the sole name source.)
     if (isNpmPackage) return originalBaseName;
     if (isEntryFile) return outDirBaseName;
     return originalBaseName;
   }
 
   effectiveEmitMode(requestedMode: string, _isNpmPackage: boolean): string {
-    // Zephyr always emits .cpp (no .ino equivalent to force away from), so this
-    // is passthrough regardless of npm/app. The 2-param shape matches the
+    // Zephyr always emits .cpp (no single-file entry equivalent to force away
+    // from), so this is passthrough regardless of npm/app. The 2-param shape
     // interface and Arduino; behavior is identical across branches.
     return requestedMode;
   }
@@ -869,7 +1518,6 @@ export class ZephyrStrategy implements PlatformStrategy {
 
   mapReturnType(functionName: string, returnType: string): string {
     if (functionName === 'main') return 'int';
-    if (functionName === 'setup' || functionName === 'loop') return 'void';
     return this.normalizeCppType(returnType);
   }
 
@@ -974,28 +1622,6 @@ export class ZephyrStrategy implements PlatformStrategy {
     return 'for (;;) { k_msleep(1000); }';
   }
 
-  isConsoleCall(callee: string): boolean {
-    return callee.startsWith('console.');
-  }
-
-  transformConsoleCall(method: string, renderedArgs: string, forHeader: boolean): string {
-    const semi = forHeader ? '' : ';';
-    const empty = !renderedArgs || renderedArgs.trim() === '';
-    const tag = method === 'error' ? '[ERROR] ' : method === 'warn' ? '[WARN] ' : '';
-    if (empty) return `printk("%s\\n", "${tag}")${semi}`;
-    const parts = renderedArgs.split(' << ');
-    if (parts.length === 1) {
-      return `printk("%s%s\\n", "${tag}", (${renderedArgs}))${semi}`;
-    }
-    const fmt = '%s' + '%s'.repeat(parts.length) + '\\n';
-    const args = [`"${tag}"`, ...parts].join(', ');
-    return `printk("${fmt}", ${args})${semi}`;
-  }
-
-  transformConsoleExpression(_method: string, _renderedArgs: string): string | undefined {
-    return undefined;
-  }
-
   objectFieldInitializer(): string | undefined {
     return undefined;
   }
@@ -1039,18 +1665,6 @@ export class ZephyrStrategy implements PlatformStrategy {
         reason: 'delayMicroseconds() busy-waits the CPU for the full delay, stalling every lower-priority interrupt and the scheduler for its duration',
         severity: 'warning',
       }],
-      ['console.log', {
-        reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
-        severity: 'info',
-      }],
-      ['console.error', {
-        reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
-        severity: 'info',
-      }],
-      ['console.warn', {
-        reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
-        severity: 'info',
-      }],
       ['I2C0', {
         reason: 'I2C transactions may sleep (driver locking + clock stretching) and are not callable from Zephyr interrupt context',
         severity: 'warning',
@@ -1138,20 +1752,18 @@ export class ZephyrStrategy implements PlatformStrategy {
   }
 
   mathHeader(): string {
-    // <math.h> is the schema-permitted value (the manifest enum allows none |
-    // <math.h> | <Arduino.h>). Zephyr's toolchain provides it; the C++ <cmath>
-    // names are available via it as well.
-    return '<math.h>';
+    // <cmath>, not <math.h>: the shared lowering emits Math.<fn>() as
+    // std::<fn>() (expression-to-ir), and picolibc's <math.h> declares the
+    // C names in the global namespace only — std::round et al. fail to
+    // compile. Builds run with CONFIG_REQUIRES_FULL_LIBCPP (real libstdc++),
+    // whose <cmath> provides the std:: names.
+    return '<cmath>';
   }
 
   cstringHeader(): string {
     return '<cstring>';
   }
 
-  needsVectorOverload(): boolean {
-    return true;
-  }
-
   needsLargeEnumUnderlying(): boolean {
     return false;
   }
@@ -1167,10 +1779,10 @@ export class ZephyrStrategy implements PlatformStrategy {
   }
 
   // ── Async ───────────────────────────────────────────────────────────────
-  // Hybrid: timers are native (k_timer + k_work, see src/async/timer-polyfill.ts);
-  // Promises use the heap-free static runtime (generateStaticAsyncRuntime), pumped
-  // cooperatively in loop() via cuttlefish_pump_microtasks(). There is no
-  // __tc_timer_runtime.run() poll — native timers fire from their own expiry path.
+  // Promises use the heap-free static runtime (generateStaticAsyncRuntime),
+  // pumped cooperatively via cuttlefish_pump_microtasks(). There is no
+  // __tc_timer_runtime.run() poll — periodic work is a Thread (k_thread) or a
+  // Counter (hardware timer), never a cooperative timer queue.
 
   getAsyncRuntimeConfig(): AsyncRuntimeConfig {
     return {
@@ -1178,12 +1790,52 @@ export class ZephyrStrategy implements PlatformStrategy {
       scheduler: 'microtask',
       waitForPinEdge: 'stub',
       hasPromiseRuntime: true,
-      hasTimers: true,
+      hasTimers: false,
       // Static (heap-free) runtime — no STL headers required.
       requiredIncludes: [],
     };
   }
 
+  /**
+   * Board module generation: join the Zephyr board data pack (extracted
+   * from the pinned tree) with the curated soc descriptors. See
+   * src/boardgen.ts.
+   */
+  generateBoardModule(
+    target: string,
+    opts?: { factsJson?: string; asBuiltJson?: string },
+  ): { boardTs: string; boardJson: string; warnings?: readonly string[] } | undefined {
+    try {
+      const g = generateBoard(target, { factsJson: opts?.factsJson, asBuiltJson: opts?.asBuiltJson });
+      return { boardTs: g.boardTs, boardJson: g.boardJson, ...(g.warnings ? { warnings: g.warnings } : {}) };
+    } catch (err) {
+      // A malformed facts/as-built file is the USER's error — surface it
+      // verbatim instead of the generic "cannot generate" below.
+      if (err instanceof Error && (err.message.includes('cuttlefish.facts.json') || err.message.includes('as-built.json'))) throw err;
+      return undefined;
+    }
+  }
+
+  /**
+   * Regenerate the board catalog overlay from the user's own Zephyr tree —
+   * `cuttlefish board sync`. After a `west update`, this is how new/changed/
+   * removed boards reach projects without a cuttlefish release. See
+   * src/sdk/board-catalog-sync.ts.
+   */
+  syncBoardCatalog(zephyrBase?: string): BoardCatalogSyncReport {
+    return syncBoardCatalog(zephyrBase ? { zephyrBase } : {});
+  }
+
+  /**
+   * Refresh the overlay only when it is stale (provenance no longer matches
+   * the tree) — the pre-step `cuttlefish board regen` runs so a regen after
+   * `west update` picks up the tree's boards automatically. Tree walk only
+   * happens when there is actual refreshing to do.
+   */
+  ensureFreshBoardCatalog(): BoardCatalogEnsureResult {
+    return ensureFreshBoardCatalog();
+  }
+
   asyncLoopInjection(taskVarNames: string[], config: AsyncRuntimeConfig): string[];
   asyncLoopInjection(taskVarNames: string[], hasPromiseRuntime: boolean, hasTimers: boolean): string[];
   asyncLoopInjection(
@@ -1195,25 +1847,61 @@ export class ZephyrStrategy implements PlatformStrategy {
       typeof configOrBool === 'boolean'
         ? { hasPromiseRuntime: configOrBool, hasTimers: _hasTimers ?? false }
         : configOrBool;
-    // Drive every async state-machine task once per loop() iteration. The task
-    // globals auto-start on their first .run() (constructor sets STATE_0, which
-    // runs unconditionally), so this is both the start and the per-frame advance.
-    // The state machine no-ops in its terminal/cyclic state, so unconditional
-    // .run() is correct (mirrors framework-arduino). No isComplete() gating.
-    const lines: string[] = [];
+    // Drive every async state-machine task once per scheduler iteration. The
+    // task globals auto-start on their first .run() (constructor sets STATE_0,
+    // which runs unconditionally), so this is both the start and the per-frame
+    // advance. The state machine no-ops in its terminal/cyclic state, so
+    // unconditional .run() is correct (mirrors framework-arduino). No
+    // isComplete() gating.
+    const work: string[] = [];
     if (cfg.hasPromiseRuntime) {
-      lines.push('cuttlefish_pump_microtasks();');
+      work.push('cuttlefish_pump_microtasks();');
     }
     for (const n of taskVarNames) {
-      lines.push(`${n}.run();`);
+      work.push(`${n}.run();`);
     }
-    // NOTE: no __tc_timer_runtime.run() — Zephyr timers are native k_timer
-    // (timer-polyfill.ts), not a cooperative poll.
-    return lines;
+    // NOTE: no timer-queue poll — periodic work is a Thread (k_thread) or a
+    // Counter (hardware timer), never a cooperative poll.
+    //
+    // main() runs once, so the per-frame work must close over its own loop.
+    // Under a mounted UI the emitter's hostEventLoop() already wraps ui_tick +
+    // these lines in `while (...) { ...; k_msleep(1); }` — return flat lines
+    // there. Otherwise (async/timer programs with no UI) self-wrap the same
+    // scheduler loop here. For a program whose top-level `while (true)` never
+    // exits, the loop below it is unreachable — harmless, and identical to the
+    // old bridge behavior (whose for(;;) around loop() was equally dead).
+    if (entryHasUI()) {
+      return work;
+    }
+    return ['for (;;) {', ...work.map((l) => `  ${l}`), '  k_msleep(1);', '}'];
   }
 
   asyncDriverFunctionName(): string {
-    return 'loop';
+    return 'main';
+  }
+
+  /**
+   * Zephyr's scheduler loop for event-driven programs (UI mounted). The
+   * emitter wraps the per-frame work — ui_tick plus the asyncLoopInjection
+   * lines — in `while (__tc_zephyr_event_loop) { ...; k_msleep(1); }`: a
+   * 1 ms cooperative yield to the kernel each frame, matching the cadence the
+   * old setup()/loop() bridge gave loop(). The flag is never cleared — the
+   * loop is the program's lifetime — but keeping the bool gives the condition
+   * a used symbol (a bare `while (true)` would leave nothing to name, and an
+   * unused flag would trip -Werror's -Wunused-variable).
+   */
+  hostEventLoop(): {
+    flagName: string;
+    continueCondition: string;
+    preIteration: string;
+    postIteration: string;
+  } | null {
+    return {
+      flagName: '__tc_zephyr_event_loop',
+      continueCondition: '__tc_zephyr_event_loop',
+      preIteration: '',
+      postIteration: 'k_msleep(1);',
+    };
   }
 
   // ── Type aliases ────────────────────────────────────────────────────────
@@ -1229,7 +1917,7 @@ export class ZephyrStrategy implements PlatformStrategy {
   }
 
   currentTimeMillis(): string {
-    return 'millis()';
+    return '__tc_now_ms()';
   }
 
   // ── Build configuration ──────────────────────────────────────────────────
@@ -1280,12 +1968,10 @@ export class ZephyrStrategy implements PlatformStrategy {
     // cuttlefish_halt: always (the runtime header may reference it).
     // string_methods / static_array: STL-free array + string helpers a no-STL
     //   target needs (mutated/struct array literals + any string method).
-    // timer_methods: k_timer/k_work pool for setInterval/setTimeout (gated on
-    //   timerCallCount at emit time in generateNativePolyfills).
     // async_runtime: heap-free static Promise/microtask runtime (no STL needed).
     return new Set<string>([
       'cuttlefish_halt', 'wiring_compat', 'string_methods', 'static_array',
-      'timer_methods', 'async_runtime',
+      'async_runtime',
     ]);
   }
 
@@ -1415,23 +2101,6 @@ struct __tc_StaticArray {
       },
     ];
 
-    // Worker-offload runtime (Phase 1). Emitted only when the program uses
-    // worker.* ops, backed by the Zephyr primitives in worker-backing.ts
-    // (k_work system workqueue + k_sem for the completion barrier).
-    const usesWorker = !!((ctx as any)?.analysis?.usesWorker);
-    if (program && usesWorker) {
-      const workerPoly = buildWorkerRuntimePolyfill(program, this, buildZephyrWorkerBacking(), { poolSize: 4 });
-      if (workerPoly) polyfills.push(workerPoly);
-    }
-
-    // timer_methods — k_timer/k_work pool. Gated on observed timer call count;
-    // a program with no setInterval/setTimeout emits nothing.
-    const analysis = (ctx as { analysis?: { timerCallCount?: number } } | undefined)?.analysis;
-    const timerCallCount = analysis?.timerCallCount ?? 0;
-    if (timerCallCount > 0) {
-      polyfills.push(buildTimerPolyfill(timerCallCount));
-    }
-
     // async_runtime — heap-free static Promise/microtask runtime. Emitted when
     // the program declares an async function OR references an async-runtime
     // symbol (Async.sleep/.then from a non-async fn). The static path requires
@@ -1445,10 +2114,10 @@ struct __tc_StaticArray {
         domain: 'embedded',
         requiredIncludes: [],
         // Polyfill definitions emit before shimLines, but the runtime's
-        // timer bodies call millis() (defined in shimLines) — declare it
-        // first so the polyfill compiles even for programs whose source
+        // timer bodies call __tc_now_ms() (defined in shimLines) — declare
+        // it first so the polyfill compiles even for programs whose source
         // has no explicit timing call.
-        forwardDeclarations: ['unsigned long millis();'],
+        forwardDeclarations: ['uint32_t __tc_now_ms(void);'],
         helperStructs: [generateStaticAsyncRuntime(8, this.getAsyncRuntimeConfig().waitForPinEdge)],
         helperFunctions: [],
         shimMacros: [],
@@ -1514,31 +2183,15 @@ struct __tc_StaticArray {
   // ── RTOS ─────────────────────────────────────────────────────────────────
 
   isRtosTarget(): boolean {
-    // Zephyr is a preemptive RTOS — delay()/k_msleep inside loop() is the
+    // Zephyr is a preemptive RTOS — delay()/k_msleep inside main() is the
     // expected cooperative yield, not an anti-pattern to warn about.
     return true;
   }
 
-  // ── Worker offload backing (Phase 1) ─────────────────────────────────────
-  // Delegates to the Zephyr backing (worker-backing.ts): k_work system
-  // workqueue + k_sem for completion. k_sem provides the kernel memory barrier
-  // the dual-core contract requires (the worker runs on a workqueue thread).
-  private _workerBacking = buildZephyrWorkerBacking();
-
   // Display state (mirrors Arduino's _displayCtx). Seeded on display.init; the
   // validator-probe path seeds the default profile lazily.
   private _displayState: DisplayState = newDisplayState();
 
-  workerSpawnLines(handleId: number, trampolineName: string, waiterExpr: string): string[] | undefined {
-    return this._workerBacking.spawnLines(handleId, trampolineName, waiterExpr);
-  }
-  workerSignalDoneExpr(handleId: number): string | undefined {
-    return this._workerBacking.signalDoneExpr(handleId);
-  }
-  workerIsDoneExpr(handleId: number): string | undefined {
-    return this._workerBacking.isDoneExpr(handleId);
-  }
-
   // ── Graphics ──────────────────────────────────────────────────────────────
   // Generic <zephyr/drivers/display.h> + ported GFX primitives (see src/display/).
   // resolveDisplayOp delegates to resolveZephyrDisplayOp with the per-build
@@ -1618,6 +2271,12 @@ struct __tc_StaticArray {
     if (boardId === 'esp32s3_devkitc' || boardId.startsWith('esp32s3')) {
       return 'gdb';
     }
+    // The STM32 Black Pill ships a verified ST-Link probe method in its board
+    // package (openocd runner over SWD, with the reset_config quirk for the
+    // unwired SRST line), so F5 attaches natively out of the box.
+    if (boardId.startsWith('blackpill_')) {
+      return 'gdb';
+    }
     // The plain ESP32 (esp32_devkitc) intentionally stays on 'printf': unlike
     // the S3 it has NO built-in USB-JTAG, so gdb needs an external ESP-PROG
     // probe + a different OpenOCD cfg/toolchain dir (deferred). Falls through.