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

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/init-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

@@ -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

@@ -19,7 +19,7 @@
 // ---------------------------------------------------------------------------
 import { spawnSync } from 'node:child_process';
 import { basename, dirname, join } from 'node:path';
-import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { readdirSync, readFileSync, mkdirSync, rmSync } from 'node:fs';
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
 import { scaffoldZephyrProject, writeIfChanged } from './scaffold.js';
 import { westSpawn, buildEnv } from './west-spawn.js';
@@ -145,6 +145,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
@@ -277,6 +300,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,6 +338,7 @@ export const Toolchain = {
             if (usesXpt) {
                 touchWiring = { controller: 'xpt2046', ...(touchWiring ?? {}) };
             }
+            const overlayDiagnostics = [];
             const overlay = generateOverlay(chip, {
                 usesI2c: uses('i2c_'),
                 usesSpi: uses('spi_'),
@@ -322,7 +347,10 @@ export const Toolchain = {
                 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
@@ -336,16 +364,23 @@ export const Toolchain = {
         // 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 +409,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';

package/dist/toolchain/scaffold.js

@@ -24,26 +24,35 @@ export function writeIfChanged(filePath, content) {
     writeFileSync(filePath, content);
     return true;
 }
+/**
+ * Names of the cuttlefish-emitted C/C++ sources under src/ (top level only,
+ * matching the old `src/*.cpp src/*.c` glob; sorted so the generated
+ * CMakeLists.txt is stable across readdir orderings). Empty when no sources
+ * exist yet (first prepare call).
+ */
+function listEmittedSources(srcDir) {
+    if (!existsSync(srcDir))
+        return [];
+    const names = readdirSync(srcDir).filter((name) => name.endsWith('.cpp') || name.endsWith('.c'));
+    names.sort();
+    return names;
+}
 /**
  * Concatenate all emitted source under src/ so the scaffold can detect which
  * peripherals the program actually uses. The cuttlefish lowering emits
  * well-known driver API tokens (adc_read, spi_transceive, bt_*, …), so scanning
- * the post-transpile source is an authoritative usage signal — and it keeps the
- * scaffold self-contained (no need to thread analysis through the toolchain
+ * the post-transpile source is an authoritative usage signal — and it keeps
+ * the scaffold self-contained (no need to thread analysis through the toolchain
  * contract). Returns '' when no sources exist yet (first prepare call).
  */
 function readEmittedSources(srcDir) {
-    if (!existsSync(srcDir))
-        return '';
     let out = '';
-    for (const name of readdirSync(srcDir)) {
-        if (name.endsWith('.cpp') || name.endsWith('.c')) {
-            try {
-                out += readFileSync(join(srcDir, name), 'utf8');
-            }
-            catch {
-                // ignore unreadable files
-            }
+    for (const name of listEmittedSources(srcDir)) {
+        try {
+            out += readFileSync(join(srcDir, name), 'utf8');
+        }
+        catch {
+            // ignore unreadable files
         }
     }
     return out;
@@ -118,8 +127,13 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     };
     let changed = false;
     // ── Root CMakeLists.txt ─────────────────────────────────────────────────
-    // The canonical Zephyr CMake application. GLOB src/*.cpp so future multi-
-    // file emits are picked up automatically; cuttlefish owns the file contents.
+    // The canonical Zephyr CMake application. The emitted source list is
+    // explicit (no file(GLOB CONFIGURE_DEPENDS ...)): CONFIGURE_DEPENDS puts a
+    // cmake.verify_globs step in the ninja graph that spawns CMake to re-check
+    // the glob on every build, and the scaffold already rewrites this file via
+    // writeIfChanged whenever the emitted file set changes — which flips
+    // configChanged and reconfigures with the new list baked in.
+    const sourceFiles = listEmittedSources(srcDir);
     const cmakeLists = [
         '# Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts.',
         'cmake_minimum_required(VERSION 3.20.0)',
@@ -128,12 +142,18 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         '',
         'project(zephyr_app)',
         '',
-        '# Collect cuttlefish-emitted sources. CONFIGURE_DEPENDS makes CMake re-',
-        '# check the glob when the source set changes (e.g. the transpiler removes',
-        '# a stale entry), instead of linking a file list from the last configure.',
-        'file(GLOB app_sources CONFIGURE_DEPENDS src/*.cpp src/*.c)',
-        '',
-        'target_sources(app PRIVATE ${app_sources})',
+        ...(sourceFiles.length > 0
+            ? [
+                '# Cuttlefish-emitted sources. This list is regenerated whenever the',
+                '# emitted file set changes (the scaffold rewrites CMakeLists.txt).',
+                'target_sources(app PRIVATE',
+                ...sourceFiles.map((name) => `  src/${name}`),
+                ')',
+            ]
+            : [
+                '# No emitted sources yet — the scaffold regenerates this list on the',
+                '# next compile once src/ contains .cpp/.c files.',
+            ]),
         // When PSRAM is configured, define BOARD_HAS_PSRAM so the UI runtime's
         // PSRAM canvas allocator (ui_create_canvas_best) is compiled in.
         ...(psram ? ['', '# PSRAM enabled: activate the runtime PSRAM canvas paths.', 'target_compile_definitions(app PRIVATE BOARD_HAS_PSRAM)', ''] : ['']),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/framework-zephyr",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.13",
   "description": "TypeCAD framework package for the Zephyr RTOS — west/CMake build, devicetree-driven GPIO",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,11 +38,11 @@
     "test:hw:mqtt": "cd ../../tests/hardware && npm exec -- cuttlefish-test mqtt-client.test.ts"
   },
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.12"
+    "@typecad/cuttlefish": "1.0.0-alpha.13"
   },
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.12",
-    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.12",
+    "@typecad/expect": "1.0.0-alpha.13",
+    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.13",
     "typescript": "^5.7.3"
   },
   "license": "MIT",

package/src/display/index.ts

@@ -18,7 +18,7 @@ import { DEFAULT_ZEPHYR_DISPLAY_PROFILE, type ZephyrDisplayProfile } from './pro
 // and consumers can reach them from the package barrel.
 export { zephyrUiDisplayAdapter, zephyrDisplayAdapterGenerator } from './ui-adapter.js';
 export { zephyrTouchAdapter } from './touch-adapter.js';
-export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
+export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE, BUILT_IN_PROFILES } from './profiles.js';
 export type { ZephyrDisplayProfile } from './profiles.js';
 
 export interface DisplayState {

package/src/display/profiles.ts

@@ -114,3 +114,26 @@ export const ZEPHYR_DISPLAY_PROFILES: Record<string, ZephyrDisplayProfile> = {
 /** The default profile used when resolveDisplayOp is probed without a display.init. */
 export const DEFAULT_ZEPHYR_DISPLAY_PROFILE: ZephyrDisplayProfile =
   ZEPHYR_DISPLAY_PROFILES['ili9341-zephyr'];
+
+/**
+ * The Zephyr profiles mapped to the shared DisplayProfile shape — the single
+ * mapping, so no consumer needs to know the DT-binding descriptor layout.
+ * The strategy's getProfileRegistry() and the preview's profile-registry
+ * loader both consume this (the same role `BUILT_IN_PROFILES` plays in
+ * framework-arduino's displays modules).
+ */
+export const BUILT_IN_PROFILES: Record<string, import('@typecad/cuttlefish/api/shared').DisplayProfile> =
+  Object.fromEntries(
+    Object.entries(ZEPHYR_DISPLAY_PROFILES).map(([name, p]) => [
+      name,
+      {
+        driver: p.driver,
+        width: p.width,
+        height: p.height,
+        nativeWidth: p.nativeWidth,
+        nativeHeight: p.nativeHeight,
+        colorFormat: p.colorFormat,
+        rotation: p.rotation ?? 1,
+      },
+    ]),
+  );

package/src/display/ui-adapter.ts

@@ -46,6 +46,10 @@ export interface ZephyrDisplayReadbackOptions {
   scanlineSync?: boolean;
   /** MISO/SDO GPIO; readback is disabled when it is not explicitly wired. */
   miso?: number;
+  /** Tearing-effect GPIO (panel TE output). When set, panel updates wait for
+   *  the TE frame pulse instead of GET_SCANLINE readback — no MISO required.
+   *  The overlay adds te-gpios to the display DT node from this. */
+  tearingEffectPin?: number;
 }
 
 export function zephyrUiDisplayAdapter(
@@ -74,6 +78,9 @@ export function zephyrUiDisplayAdapter(
   // react badly to GSCAN reads. Both an explicit opt-in and an explicit MISO
   // pin are required before emitting an active synchronization path.
   const scanlineSync = readback.scanlineSync === true && readback.miso !== undefined;
+  // TE (hardware tearing-effect) sync: strictly opt-in via a configured GPIO.
+  // Preferred over GET_SCANLINE when wired — no readback traffic, no MISO.
+  const tePin = typeof readback.tearingEffectPin === 'number' ? readback.tearingEffectPin : undefined;
 
   const includes = [
     `// --- Zephyr UI display adapter (${profile.driver}) ---`,
@@ -140,6 +147,22 @@ export function zephyrUiDisplayAdapter(
     `// controller-specific validation are required; otherwise the display stays`,
     `// on the existing retained/composited path with no extra SPI reads.`,
     `static const bool __tc_pnl_scanline_sync = ${scanlineSync ? 'true' : 'false'};`,
+    `// Tearing-effect (TE) hardware sync: the panel pulses its TE line once`,
+    `// per frame. When te-gpios is present on the display DT node, panel`,
+    `// updates arm on the TE edge — tear-free writes with no MISO readback.`,
+    `#if DT_NODE_HAS_PROP(DT_NODELABEL(${dtLabel}), te_gpios)`,
+    `#define __TC_TE_SYNC 1`,
+    `static const struct gpio_dt_spec __tc_te =`,
+    `    GPIO_DT_SPEC_GET(DT_NODELABEL(${dtLabel}), te_gpios);`,
+    `static struct gpio_callback __tc_te_cb;`,
+    `static volatile uint32_t __tc_te_count = 0;`,
+    `static void __tc_te_isr(const struct device* port, struct gpio_callback* cb, uint32_t pins) {`,
+    `    (void)port; (void)cb; (void)pins;`,
+    `    __tc_te_count++;`,
+    `}`,
+    `#else`,
+    `#define __TC_TE_SYNC 0`,
+    `#endif`,
     `// Stashed address window from the last setAddrWindow call. The runtime`,
     `// calls setAddrWindow + writePixels as a matched pair, so we stash the rect`,
     `// here and consume it in writePixels.`,
@@ -157,6 +180,18 @@ export function zephyrUiDisplayAdapter(
   // with DT_HAS_ALIAS (the safe primitive for an alias that may be absent —
   // DT_NODE_HAS_STATUS(DT_ALIAS(...)) is version-dependent when the alias is
   // missing and can fail the build).
+  // TE pin: input + rising-edge interrupt (the ST7796 TE pulse), then tell
+  // the controller to drive the line (TEON 0x35, mode 1 = vertical sync only).
+  const teInit = tePin !== undefined ? `#if __TC_TE_SYNC
+    if (device_is_ready(__tc_te.port)) {
+      gpio_pin_configure_dt(&__tc_te, GPIO_INPUT);
+      gpio_init_callback(&__tc_te_cb, __tc_te_isr, BIT(__tc_te.pin));
+      (void)gpio_add_callback(__tc_te.port, &__tc_te_cb);
+      (void)gpio_pin_interrupt_configure_dt(&__tc_te, GPIO_INT_EDGE_RISING);
+      __tc_pnl_cmd1(0x35, 0x01); // TEON: TE output = vsync pulse
+    }
+#endif` : '';
+
   const blInit = backlightAlias
     ? `#if DT_HAS_ALIAS(${backlightAlias})\n    const struct gpio_dt_spec __bl = GPIO_DT_SPEC_GET(DT_ALIAS(${backlightAlias}), gpios);\n    if (device_is_ready(__bl.port)) { gpio_pin_configure_dt(&__bl, GPIO_OUTPUT_ACTIVE); }\n#endif`
     : '';
@@ -479,6 +514,19 @@ static uint16_t __tc_pnl_read_scanline(void) {
 // have no safe post-rectangle interval, so they retain the normal single-burst
 // behavior; the caller's framebuffer still prevents intermediate software frames.
 static void __tc_pnl_wait_for_safe_rect(int16_t y, int16_t rh) {
+#if __TC_TE_SYNC
+  // TE variant: arm on the next frame pulse, then start the burst — the write
+  // chases the scan beam from the top of the rect. Bounded so a stuck TE line
+  // can never hang the UI loop.
+  if (rh < 8 || y < 0) return;
+  uint32_t __was = __tc_te_count;
+  uint32_t __deadline = k_uptime_get_32() + 25U;
+  while (__tc_te_count == __was) {
+    if (static_cast<int32_t>(k_uptime_get_32() - __deadline) >= 0) break;
+    k_msleep(0);
+  }
+  return;
+#endif
   if (!__tc_pnl_scanline_sync || rh < 8 || y < 0) return;
   int16_t __last = static_cast<int16_t>(y + rh - 1);
   if (__last >= static_cast<int16_t>(${h} - 2)) return;
@@ -578,8 +626,10 @@ const CuttlefishPanelOps __tc_display_ops = {
 CuttlefishGFX __tc_display(&__tc_display_ops, nullptr);
 ${initBlock}
 // ── display_init (called from setup) ────────────────────────────────────
+
 static inline void display_init() {
   printk("TC_DISPLAY: device ready\\n");
+${teInit}
 ${blInit}
   gpio_pin_configure_dt(&__tc_pnl_cs, GPIO_OUTPUT);
   gpio_pin_configure_dt(&__tc_pnl_dc, GPIO_OUTPUT);
@@ -726,5 +776,6 @@ export const zephyrDisplayAdapterGenerator: DisplayAdapterGenerator = (display)
   return zephyrUiDisplayAdapter(profile, {
     scanlineSync: display.scanlineSync,
     miso: display.spiPins?.miso,
+    tearingEffectPin: (display as { tearingEffectPin?: number }).tearingEffectPin,
   });
 };