@typecad/framework-zephyr 1.0.0-alpha.12 → 1.0.0-alpha.14

package/dist/toolchain/debug-config.d.ts

@@ -13,8 +13,10 @@ export interface DebugConfigOptions {
     sourceMapPath?: string;
 }
 /**
- * Resolve the GDB binary path for the target from the build cache. Zephyr
- * records ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
+ * Resolve the GDB binary path for the target from the build cache, falling
+ * back to a filesystem scan of known Zephyr SDK locations when no build
+ * exists yet (the create-time starter artifacts path). Zephyr records
+ * ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
  * xtensa GDB lives at <sdk>/xtensa-espressif_esp32s3_zephyr-elf/bin/... (note
  * the Zephyr-SDK naming, distinct from the ESP-IDF xtensa-esp32s3-elf-gdb).
  *
@@ -22,6 +24,24 @@ export interface DebugConfigOptions {
  * omits gdbPath and relies on Cortex-Debug's default resolution).
  */
 export declare function resolveGdbPath(buildDir: string, target: string): string | undefined;
+/** The esp32s3 xtensa GDB location inside a Zephyr SDK root (verified against
+ *  zephyr-sdk-0.17.4). Returns a forward-slash absolute path or undefined. */
+export declare function gdbPathFromSdkRoot(sdkRoot: string): string | undefined;
+/**
+ * Probe the well-known Zephyr SDK install locations, newest version first:
+ *   1. $ZEPHYR_SDK_INSTALL_DIR (the var board.cmake reads)
+ *   2. <MAMBA_ROOT_PREFIX | ~/micromamba>/zephyr-sdk/zephyr-sdk-<ver> — the
+ *      @typecad/zephyr-installer layout
+ *   3. ~/zephyr-sdk-<ver> — the standalone download layout
+ *
+ * Only roots that actually contain the esp32s3 GDB are useful to callers;
+ * this returns candidate roots (gdbPathFromSdkRoot does the existence check)
+ * so tests can inject home/env overrides.
+ */
+export declare function discoverZephyrSdkRoots(opts?: {
+    home?: string;
+    env?: Record<string, string | undefined>;
+}): string[];
 /**
  * Resolve the Espressif OpenOCD binary path. The esp32s3 needs the Espressif
  * OpenOCD fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
@@ -80,3 +100,24 @@ export declare function generateGdbScript(sourceMapPath?: string): string | null
  *   <projectRoot>/.cuttlefish/.cuttlefish-gdb.py  (lambda frame filter, conditional)
  */
 export declare function writeDebugConfig(o: DebugConfigOptions): void;
+/**
+ * Create-time starter debug artifacts. Called by the cuttlefish `create` flow
+ * (via the package's `writeProjectDebugArtifacts` export) so a fresh project
+ * has a working F5 before any build exists:
+ *
+ * The launch.json's preLaunchTask runs `cuttlefish build --compile --upload
+ * --debug`, which builds + flashes AND rewrites this same launch entry (merged
+ * by name) with the CMakeCache-resolved gdbPath — so the starter files upgrade
+ * themselves on the first debug build.
+ *
+ * No-ops (returns []) for targets without native GDB support (debugMode() !==
+ * 'gdb'); the gdb frame-filter script is skipped (no source map exists yet).
+ *
+ * Returns the workspace-relative paths written, for CLI reporting.
+ */
+export declare function writeProjectDebugArtifacts(o: {
+    /** Absolute path to the cuttlefish project root (contains cuttlefish.config.ts). */
+    workspaceRoot: string;
+    /** The Zephyr board id from the project config (frameworkData.buildTarget). */
+    buildTarget?: string;
+}): string[];

package/dist/toolchain/debug-config.js

@@ -16,9 +16,12 @@
 // ---------------------------------------------------------------------------
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname, relative } from 'node:path';
+import { ZephyrStrategy } from '../strategy.js';
 /**
- * Resolve the GDB binary path for the target from the build cache. Zephyr
- * records ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
+ * Resolve the GDB binary path for the target from the build cache, falling
+ * back to a filesystem scan of known Zephyr SDK locations when no build
+ * exists yet (the create-time starter artifacts path). Zephyr records
+ * ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
  * xtensa GDB lives at <sdk>/xtensa-espressif_esp32s3_zephyr-elf/bin/... (note
  * the Zephyr-SDK naming, distinct from the ESP-IDF xtensa-esp32s3-elf-gdb).
  *
@@ -26,27 +29,92 @@ import { join, resolve, dirname, relative } from 'node:path';
  * omits gdbPath and relies on Cortex-Debug's default resolution).
  */
 export function resolveGdbPath(buildDir, target) {
+    void target; // toolchain dir is esp32s3-specific today; see gdbPathFromSdkRoot
     const cachePath = join(buildDir, 'CMakeCache.txt');
-    if (!existsSync(cachePath))
-        return undefined;
-    let sdk = '';
-    try {
-        const cache = readFileSync(cachePath, 'utf-8');
-        const m = cache.match(/^ZEPHYR_SDK_INSTALL_DIR:PATH=(.+)$/m);
-        if (m)
-            sdk = m[1].trim();
+    if (existsSync(cachePath)) {
+        try {
+            const cache = readFileSync(cachePath, 'utf-8');
+            const m = cache.match(/^ZEPHYR_SDK_INSTALL_DIR:PATH=(.+)$/m);
+            if (m) {
+                const fromCache = gdbPathFromSdkRoot(m[1].trim());
+                if (fromCache)
+                    return fromCache;
+            }
+        }
+        catch {
+            // unreadable cache — fall through to the SDK scan
+        }
     }
-    catch {
-        return undefined;
+    // No build dir yet (project just created): probe known SDK locations.
+    for (const sdkRoot of discoverZephyrSdkRoots()) {
+        const p = gdbPathFromSdkRoot(sdkRoot);
+        if (p)
+            return p;
     }
-    if (!sdk)
-        return undefined;
-    // The Zephyr SDK toolchain dir is target-specific. For esp32s3 it is
-    // xtensa-espressif_esp32s3_zephyr-elf (verified against zephyr-sdk-0.17.4).
+    return undefined;
+}
+/** The esp32s3 xtensa GDB location inside a Zephyr SDK root (verified against
+ *  zephyr-sdk-0.17.4). Returns a forward-slash absolute path or undefined. */
+export function gdbPathFromSdkRoot(sdkRoot) {
     const gdbName = 'xtensa-espressif_esp32s3_zephyr-elf-gdb.exe';
-    const gdbPath = join(sdk, 'xtensa-espressif_esp32s3_zephyr-elf', 'bin', gdbName);
+    const gdbPath = join(sdkRoot, 'xtensa-espressif_esp32s3_zephyr-elf', 'bin', gdbName);
     return existsSync(gdbPath) ? gdbPath.replace(/\\/g, '/') : undefined;
 }
+/** Compare two dotted version strings numerically (0.17.10 > 0.17.4). */
+function compareSdkVersions(a, b) {
+    const segsOf = (v) => v.split('.').map((s) => parseInt(s, 10) || 0);
+    const aa = segsOf(a);
+    const bb = segsOf(b);
+    for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
+        const d = (aa[i] ?? 0) - (bb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/**
+ * Probe the well-known Zephyr SDK install locations, newest version first:
+ *   1. $ZEPHYR_SDK_INSTALL_DIR (the var board.cmake reads)
+ *   2. <MAMBA_ROOT_PREFIX | ~/micromamba>/zephyr-sdk/zephyr-sdk-<ver> — the
+ *      @typecad/zephyr-installer layout
+ *   3. ~/zephyr-sdk-<ver> — the standalone download layout
+ *
+ * Only roots that actually contain the esp32s3 GDB are useful to callers;
+ * this returns candidate roots (gdbPathFromSdkRoot does the existence check)
+ * so tests can inject home/env overrides.
+ */
+export function discoverZephyrSdkRoots(opts) {
+    const env = opts?.env ?? process.env;
+    const home = opts?.home ?? (env.USERPROFILE || env.HOME || '');
+    const scanned = [];
+    const versionedDirs = (base) => {
+        try {
+            return readdirSync(base)
+                .filter((d) => existsSync(join(base, d)) && d.startsWith('zephyr-sdk-'))
+                .map((d) => join(base, d));
+        }
+        catch {
+            return []; // dir absent
+        }
+    };
+    const mambaRoot = env.MAMBA_ROOT_PREFIX || (home ? join(home, 'micromamba') : '');
+    if (mambaRoot)
+        scanned.push(...versionedDirs(join(mambaRoot, 'zephyr-sdk')));
+    if (home)
+        scanned.push(...versionedDirs(home));
+    // Scanned roots newest version first; the env var stays pinned first
+    // (explicit user intent outranks any discovered location).
+    scanned.sort((a, b) => {
+        const va = a.match(/zephyr-sdk-([\d.]+)/)?.[1] ?? '';
+        const vb = b.match(/zephyr-sdk-([\d.]+)/)?.[1] ?? '';
+        return compareSdkVersions(vb, va);
+    });
+    const roots = env.ZEPHYR_SDK_INSTALL_DIR
+        ? [env.ZEPHYR_SDK_INSTALL_DIR, ...scanned]
+        : scanned;
+    // De-duplicate (an env var may repeat a scan hit) preserving order.
+    return roots.filter((r, i) => roots.indexOf(r) === i);
+}
 /**
  * Resolve the Espressif OpenOCD binary path. The esp32s3 needs the Espressif
  * OpenOCD fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
@@ -357,3 +425,47 @@ export function writeDebugConfig(o) {
     const task = buildTask(o);
     mergeJsonArrayEntry(join(vscodeDir, 'tasks.json'), 'tasks', 'label', task);
 }
+/**
+ * The Zephyr app dir a `cuttlefish create` scaffold produces, relative to the
+ * project root: the scaffold fixes entry `./src/main.ts` + outDir `./out`, and
+ * the CLI resolves output.outDir against the ENTRY's directory (cli.ts), so
+ * the emitted app root — and therefore the ELF, build dir, and .cuttlefish/
+ * debug artifacts — always lands at `src/out`. Keep in sync with
+ * generateProjectConfig in @typecad/cuttlefish create/templates.ts.
+ */
+const STARTER_SKETCH_REL = 'src/out';
+/**
+ * Create-time starter debug artifacts. Called by the cuttlefish `create` flow
+ * (via the package's `writeProjectDebugArtifacts` export) so a fresh project
+ * has a working F5 before any build exists:
+ *
+ * The launch.json's preLaunchTask runs `cuttlefish build --compile --upload
+ * --debug`, which builds + flashes AND rewrites this same launch entry (merged
+ * by name) with the CMakeCache-resolved gdbPath — so the starter files upgrade
+ * themselves on the first debug build.
+ *
+ * No-ops (returns []) for targets without native GDB support (debugMode() !==
+ * 'gdb'); the gdb frame-filter script is skipped (no source map exists yet).
+ *
+ * Returns the workspace-relative paths written, for CLI reporting.
+ */
+export function writeProjectDebugArtifacts(o) {
+    if (new ZephyrStrategy().debugMode(o.buildTarget) !== 'gdb')
+        return [];
+    const workspaceRoot = resolve(o.workspaceRoot);
+    const projectRoot = join(workspaceRoot, STARTER_SKETCH_REL);
+    writeDebugConfig({
+        projectRoot,
+        workspaceRoot,
+        sketchRel: STARTER_SKETCH_REL,
+        target: o.buildTarget ?? '',
+        // No build dir exists yet — resolveGdbPath falls back to probing known
+        // Zephyr SDK locations so gdbPath is still filled in when possible.
+        buildDir: join(projectRoot, 'build'),
+    });
+    return [
+        '.vscode/launch.json',
+        '.vscode/tasks.json',
+        `${STARTER_SKETCH_REL}/.cuttlefish/openocd.cfg`,
+    ];
+}

package/dist/toolchain/index.d.ts

@@ -26,7 +26,7 @@ export declare function projectRootFromOptions(o: ToolchainOptions): string;
  * Exported (pure) so the runner-selection contract is unit-testable without
  * spawning west.
  */
-export declare function buildFlashArgs(buildDir: string, board: string, userRunner: string | undefined, port: string | undefined): string[];
+export declare function buildFlashArgs(buildDir: string, board: string, userRunner: string | undefined, port: string | undefined, runnerArgs?: readonly string[]): string[];
 /**
  * Classify a `west flash` result as success/failure.
  *
@@ -59,6 +59,19 @@ export declare function classifyUploadResult(runner: string | undefined, status:
  * Exported (pure) so the cleansing is unit-testable without spawning west.
  */
 export declare function cleanseUploadOutput(runner: string | undefined, status: number | null, output: string): string;
+/**
+ * Whether a failed `west build` output carries ninja's `dependency cycle`
+ * signature. Zephyr 4.3.99-dev snapshots have a regression
+ * (zephyrproject-rtos/zephyr#104757, fixed upstream by the #104784 revert,
+ * in v4.4+): after CMake re-runs from a .config change, the build dir's
+ * .ninja_deps records an `offsets.h -> offsets.c.obj -> offsets.h` cycle and
+ * ninja aborts with `ninja: error: dependency cycle: ...` before compiling
+ * anything. The cycle lives in the build dir, not the sources, so compile()
+ * recovers by deleting the dir and retrying once.
+ *
+ * Exported (pure) so the detection is unit-testable without spawning west.
+ */
+export declare function isDependencyCycleFailure(output: string): boolean;
 /**
  * FrameworkToolchain for Zephyr. Spec §3.5 (mirror of the ESP-IDF toolchain).
  * The target board is carried via frameworkData.buildTarget; scaffolding

package/dist/toolchain/index.js

@@ -21,17 +21,77 @@ import { spawnSync } from 'node:child_process';
 import { basename, dirname, join } from 'node:path';
 import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
-import { scaffoldZephyrProject, writeIfChanged } from './scaffold.js';
+import { scaffoldZephyrProject, writeIfChanged, appendLibraryOverlayFragments } from './scaffold.js';
 import { westSpawn, buildEnv } from './west-spawn.js';
 import { discoverWest } from './west-discover.js';
 import { writeDebugConfig, resolveDebugLocations } from './debug-config.js';
 import { ZephyrStrategy } from '../strategy.js';
 import { generateOverlay } from '../dt-config/overlay.js';
 import { chipForTarget } from '../chips/index.js';
+import { resolveChipFromBoard } from '../chips/resolve.js';
+import { pwmDtAliasToken } from '../lowering/pwm.js';
 import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './compat.js';
 import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from '../display/profiles.js';
 /** Default board target — the framework's MVP canonical board. */
 const DEFAULT_BOARD = 'xiao_ble';
+/**
+ * Resolve the chip for a build the same way the strategy does at emit time —
+ * from the board constants the transpile persisted next to the emitted
+ * source (`board-constants.json`), falling back to the hardcoded registry.
+ * Board-package chips (rpi_pico, esp32c3/c6, blackpill) exist only in their
+ * board packages; the registry fallback would silently resolve them to the
+ * XIAO default and the overlay generator would emit wrong controller labels
+ * (e.g. `&uart0` on an STM32, whose node is `usart1`).
+ */
+function chipForBuild(projectRoot, board) {
+    try {
+        // The transpile writes the constants into the emit outDir, which is
+        // <projectRoot>/src for the standard layout (basename 'src' collapsed by
+        // projectRootFromOptions); check both locations.
+        const bcPath = [join(projectRoot, 'src', 'board-constants.json'), join(projectRoot, 'board-constants.json')]
+            .find(p => existsSync(p));
+        if (bcPath) {
+            const raw = JSON.parse(readFileSync(bcPath, 'utf8'));
+            const fromBoard = resolveChipFromBoard(new Map(Object.entries(raw)));
+            if (fromBoard)
+                return fromBoard;
+        }
+    }
+    catch { /* fall back to the registry below */ }
+    return chipForTarget(board);
+}
+/**
+ * HAL pins the emitted sources read via adc.* — scanned from the emitted
+ * `__tc_adc<N>_setup()` call sites (N = channel index, mapped back to the HAL
+ * pin via the chip descriptor). Feeds the overlay's ADC pinctrl rewrite: on
+ * SoCs that mux ADC pads via pinctrl (STM32), only the read channels are
+ * switched to analog mode.
+ */
+function scanAdcReadPins(src, chip) {
+    const pins = [];
+    // Match CALL SITES only (`__tc_adc<N>_setup()` with empty parens) — the
+    // setup definitions emitted by adcInitLines have a `(void)` parameter list
+    // and would otherwise mark every descriptor channel as used.
+    for (const m of src.matchAll(/__tc_adc(\d+)_setup\(\)/g)) {
+        const ch = Number(m[1]);
+        const c = chip.adc?.channels.find((x) => x.channel === ch);
+        if (c && !pins.includes(c.pin))
+            pins.push(c.pin);
+    }
+    return pins;
+}
+/**
+ * HAL pins the emitted sources drive with pwm.* — the emitted source
+ * references each used spec as `__tc_pwm_<alias token>` (pwmVarName in
+ * lowering/pwm.ts), and the lowering only emits specs for driven pins, so
+ * var-presence is the authoritative signal. Feeds the overlay's per-pin
+ * pwm-leds gating (no dead DT channels).
+ */
+function scanPwmUsedPins(src, chip) {
+    return (chip.pwm?.specs ?? [])
+        .filter((s) => src.includes(`__tc_pwm_${pwmDtAliasToken(s)}`))
+        .map((s) => s.pin);
+}
 function targetFromOptions(o) {
     // The cuttlefish CLI populates ToolchainOptions.buildTarget from
     // config.frameworkData.buildTarget. Accept frameworkData.target as an alias.
@@ -77,7 +137,7 @@ const FLASH_TIMEOUT_MS = 120_000;
  * Exported (pure) so the runner-selection contract is unit-testable without
  * spawning west.
  */
-export function buildFlashArgs(buildDir, board, userRunner, port) {
+export function buildFlashArgs(buildDir, board, userRunner, port, runnerArgs) {
     const args = ['flash', '-d', buildDir];
     if (userRunner) {
         args.push('--runner', userRunner);
@@ -85,6 +145,11 @@ export function buildFlashArgs(buildDir, board, userRunner, port) {
     if (port && board.startsWith('esp32')) {
         args.push('--esp-device', port);
     }
+    // Extra runner-specific flags, appended verbatim (west's runner parsers
+    // accept them after the runner is selected).
+    if (runnerArgs && runnerArgs.length > 0) {
+        args.push(...runnerArgs);
+    }
     return args;
 }
 /**
@@ -145,6 +210,29 @@ export function cleanseUploadOutput(runner, status, output) {
     }
     return output;
 }
+/**
+ * Whether a failed `west build` output carries ninja's `dependency cycle`
+ * signature. Zephyr 4.3.99-dev snapshots have a regression
+ * (zephyrproject-rtos/zephyr#104757, fixed upstream by the #104784 revert,
+ * in v4.4+): after CMake re-runs from a .config change, the build dir's
+ * .ninja_deps records an `offsets.h -> offsets.c.obj -> offsets.h` cycle and
+ * ninja aborts with `ninja: error: dependency cycle: ...` before compiling
+ * anything. The cycle lives in the build dir, not the sources, so compile()
+ * recovers by deleting the dir and retrying once.
+ *
+ * Exported (pure) so the detection is unit-testable without spawning west.
+ */
+export function isDependencyCycleFailure(output) {
+    return output.includes('dependency cycle');
+}
+/** stdout+stderr of a spawnSync result coerced to one string. Defensive about
+ *  the buffer form (spawnSync only returns strings when `encoding` is set,
+ *  which every call site here does — but the coercion costs nothing). */
+function combinedSpawnOutput(result) {
+    const so = typeof result.stdout === 'string' ? result.stdout : (result.stdout?.toString() ?? '');
+    const se = typeof result.stderr === 'string' ? result.stderr : (result.stderr?.toString() ?? '');
+    return so + se;
+}
 /**
  * FrameworkToolchain for Zephyr. Spec §3.5 (mirror of the ESP-IDF toolchain).
  * The target board is carried via frameworkData.buildTarget; scaffolding
@@ -159,7 +247,7 @@ export const Toolchain = {
         // resolution is a pre-build artifact step.
         const projectRoot = basename(outputDir) === 'src' ? dirname(outputDir) : outputDir;
         const board = DEFAULT_BOARD;
-        const chip = chipForTarget(board);
+        const chip = chipForBuild(projectRoot, board);
         // Scan the emitted source for usage tokens (same authoritative signal the
         // scaffold uses). entryPoint is the path to main.cpp; its dir is src/.
         const srcDir = dirname(entryPoint);
@@ -193,6 +281,10 @@ export const Toolchain = {
             usesI2c: uses('i2c_'),
             usesSpi: uses('spi_'),
             usesUart: uses('uart_'),
+            usesPwm: uses('pwm_'),
+            usesAdc: uses('adc_'),
+            adcReadPins: scanAdcReadPins(src, chip),
+            pwmUsedPins: scanPwmUsedPins(src, chip),
             usesDisplay,
             usesTouch: usesTouch || usesXpt,
             touchController: usesXpt ? 'xpt2046' : 'ft6336u',
@@ -230,7 +322,7 @@ export const Toolchain = {
         // the <default>.overlay it wrote does not match `west build -b <board>`.
         // Zephyr auto-detects boards/<board>.overlay under APPLICATION_CONFIG_DIR.
         try {
-            const chip = chipForTarget(board);
+            const chip = chipForBuild(projectRoot, board);
             const srcDir = join(projectRoot, 'src');
             let src = '';
             try {
@@ -277,6 +369,7 @@ export const Toolchain = {
                     mosi: typeof spiPins?.mosi === 'number' ? spiPins.mosi : undefined,
                     miso: typeof spiPins?.miso === 'number' ? spiPins.miso : undefined,
                     backlightPin: typeof dispCfg.backlightPin === 'number' ? dispCfg.backlightPin : undefined,
+                    tearingEffectPin: typeof dispCfg.tearingEffectPin === 'number' ? dispCfg.tearingEffectPin : undefined,
                 }
                 : undefined;
             // Extract touch pin wiring from the config display.touch section so the
@@ -314,38 +407,54 @@ export const Toolchain = {
             if (usesXpt) {
                 touchWiring = { controller: 'xpt2046', ...(touchWiring ?? {}) };
             }
+            const overlayDiagnostics = [];
             const overlay = generateOverlay(chip, {
                 usesI2c: uses('i2c_'),
                 usesSpi: uses('spi_'),
                 usesUart: uses('uart_'),
+                usesPwm: uses('pwm_'),
+                usesAdc: uses('adc_'),
+                adcReadPins: scanAdcReadPins(src, chip),
+                pwmUsedPins: scanPwmUsedPins(src, chip),
                 usesDisplay,
                 usesTouch: uses('ft6336u') || uses('touch_') || usesXpt,
                 touchController: usesXpt ? 'xpt2046' : 'ft6336u',
                 psram: o.psram,
-            }, displayProfile, wiring, touchWiring);
+            }, displayProfile, wiring, touchWiring, overlayDiagnostics);
+            for (const d of overlayDiagnostics) {
+                console.warn(`overlay: ${d.message}`);
+            }
             const overlayDir = join(projectRoot, 'boards');
             mkdirSync(overlayDir, { recursive: true });
             // Write the board-specific overlay (the one west loads). Zephyr looks for
             // boards/<board_id>.overlay under APPLICATION_CONFIG_DIR — use the bare
             // board id (before any hardware-qualifier suffix, e.g. 'esp32_devkitc'
-            // not the full 'esp32_devkitc/esp32/procpu' target string).
+            // not the full 'esp32_devkitc/esp32/procpu' target string). Library
+            // packages' overlay fragments are appended by the scaffold helper.
             const boardId = board.split('/')[0];
-            writeIfChanged(join(overlayDir, `${boardId}.overlay`), overlay);
+            writeIfChanged(join(overlayDir, `${boardId}.overlay`), appendLibraryOverlayFragments(overlay, projectRoot));
         }
         catch { /* best-effort overlay regen; the build surfaces DT errors */ }
         // Use a stable build dir so incremental builds reuse the Ninja graph.
         // west defaults to <projectRoot>/build.
         const buildDir = join(projectRoot, 'build');
-        // Nuke the build dir whenever a previous build exists. Zephyr's gen_offset
-        // flow (offsets.h is generated FROM offsets.c.obj, while gen_offset.h makes
-        // offsets.c include offsets.h) leaves a permanent `offsets.h ->
-        // offsets.c.obj -> offsets.h` cycle in the .ninja_deps log after the first
-        // incremental pass — ninja then fails every later build with `dependency
-        // cycle` even when nothing changed. This is a known Zephyr-on-Windows
-        // issue; the reliable fix is a pristine build dir per build. Also nukes
-        // when prj.conf/CMakeLists/overlay changed, so Kconfig symbols and
-        // generated headers never diverge from a cached graph.
-        if (configChanged || existsSync(join(buildDir, 'zephyr', 'zephyr.bin'))) {
+        // Reuse the build dir across builds so ninja recompiles only the changed
+        // app translation units and re-links — a pristine configure + the
+        // ~280-target Zephyr library rebuild costs minutes on Windows
+        // (demo-shadcn measures 69s of ninja wall time, 448s of summed compile
+        // work, and every build redid all of it). Nuke it only when the generated
+        // config changed (prj.conf / CMakeLists content), the one path that must
+        // not reuse a cached graph: Zephyr 4.3.99-dev snapshots carry a
+        // regression (zephyrproject-rtos/zephyr#104757, fixed by the #104784
+        // revert on 2026-03-03, in v4.4+) where re-running CMake after a .config
+        // change records an `offsets.h -> offsets.c.obj -> offsets.h` cycle in
+        // .ninja_deps, after which every ninja run fails with `dependency cycle`.
+        // Plain source edits never reconfigure CMake, so they cannot trigger it —
+        // and the retry after the spawn below self-heals any path that still does.
+        // Board switches need no nuke here: `west build` is --pristine=auto by
+        // default and recreates the dir itself when -b <board> mismatches the
+        // cached board.
+        if (configChanged) {
             try {
                 rmSync(buildDir, { recursive: true, force: true });
             }
@@ -374,10 +483,26 @@ export const Toolchain = {
             buildArgs.push(...userCmakeArgs);
         }
         const inv = westSpawn(buildArgs, { cwd: projectRoot, encoding: 'utf-8', timeout: BUILD_TIMEOUT_MS });
-        const result = spawnSync(inv.command, inv.args, inv.options);
+        let result = spawnSync(inv.command, inv.args, inv.options);
+        // Self-heal the Zephyr 4.3.99 dep-cycle regression (see the nuke comment
+        // above): when the cached .ninja_deps carries the cycle, ninja aborts with
+        // `dependency cycle` before compiling anything. The cycle lives in the
+        // build dir, not the sources — one pristine retry clears it and the build
+        // proceeds. On fixed Zephyr (>=4.4) this never fires.
+        let pristineRetry = false;
+        if (result.status !== 0 && isDependencyCycleFailure(combinedSpawnOutput(result))) {
+            try {
+                rmSync(buildDir, { recursive: true, force: true });
+            }
+            catch { /* may not exist */ }
+            result = spawnSync(inv.command, inv.args, inv.options);
+            pristineRetry = true;
+        }
         const stdout = typeof result.stdout === 'string' ? result.stdout : (result.stdout?.toString() ?? '');
         const stderr = typeof result.stderr === 'string' ? result.stderr : (result.stderr?.toString() ?? '');
-        const output = stdout + stderr;
+        const output = stdout + stderr + (pristineRetry
+            ? '\n[cuttlefish] dependency cycle detected in the cached build dir — retried with a pristine build'
+            : '');
         // Prefix the build log with how west was resolved, for transparency.
         const header = `Using west via ${inv.install.source}` +
             (inv.install.zephyrBase ? ` (ZEPHYR_BASE=${inv.install.zephyrBase})` : '') + '\n';
@@ -414,7 +539,8 @@ export const Toolchain = {
         const board = targetFromOptions(o);
         const zc = o.zephyrConfig;
         const runner = zc?.runner;
-        const args = buildFlashArgs(buildDir, board, runner, o.port);
+        const runnerArgs = zc?.runnerArgs;
+        const args = buildFlashArgs(buildDir, board, runner, o.port, runnerArgs);
         const inv = westSpawn(args, {
             cwd: projectRoot,
             encoding: 'utf-8',

package/dist/toolchain/scaffold.d.ts

@@ -1,6 +1,15 @@
 /** Write a file only if the content differs from the existing file.
  *  Returns true when the file was written (content changed or file was new). */
 export declare function writeIfChanged(filePath: string, content: string): boolean;
+/**
+ * Append cuttlefish library packages' devicetree overlay fragments to the
+ * generated overlay. Library entries come from the transpiler's libraries.json
+ * sidecar (next to the emitted sources) and are already gated on the
+ * library's include token appearing in the emitted sources — no re-detection.
+ * Fragments merge after the framework overlay so library nodes (e.g.
+ * @typecad/zephyr-esp32s3-rgb's WS2812 node on I2S0) layer over it.
+ */
+export declare function appendLibraryOverlayFragments(overlay: string, projectRoot: string): string;
 /**
  * Emit the Zephyr application skeleton around the generated src/main.cpp.
  *