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

package/dist/strategy.js

@@ -44,7 +44,7 @@ import { generateStaticAsyncRuntime } from '@typecad/cuttlefish/api/shared';
 import { buildTimerPolyfill } from './async/timer-polyfill.js';
 import { resolveZephyrDisplayOp, newDisplayState } from './display/index.js';
 import { buildDisplayRuntime } from './display/gfx.js';
-import { ZEPHYR_DISPLAY_PROFILES } from './display/profiles.js';
+import { ZEPHYR_DISPLAY_PROFILES, BUILT_IN_PROFILES } from './display/profiles.js';
 import { zephyrDisplayAdapterGenerator } from './display/ui-adapter.js';
 import { zephyrTouchAdapter } from './display/touch-adapter.js';
 export class ZephyrStrategy {
@@ -113,7 +113,23 @@ export class ZephyrStrategy {
         // true so nothing is stripped — mirrors framework-esp32's forcedIncludes.
         const a = ctx?.analysis;
         const uses = (f) => (a ? !!a[f] : true);
-        const inc = ['<zephyr/kernel.h>', '<zephyr/drivers/gpio.h>', '<cstdio>', '<cstdint>'];
+        // <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
+        // the fixed-width types come via <zephyr/kernel.h> regardless — DIRECT_CPP_TYPE_MAP
+        // passes int32_t/uint8_t through verbatim.
+        const inc = ['<zephyr/kernel.h>', '<zephyr/drivers/gpio.h>', '<cstdint>'];
+        // <cstdio> backs the printf family only: __tc_print/__tc_println (emitted
+        // solely when @typecad/expect's preprocessor injected them — tracked via
+        // usedPolyfillHelpers), raw printf/snprintf in user code (usesCstdio), and
+        // the fs/preferences/uart shims (their lowerings snprintf into buffers).
+        // A program touching none of those needs no <cstdio>.
+        const helpers = a?.usedPolyfillHelpers;
+        const needsCstdio = uses('usesCstdio') || uses('usesFS') || uses('usesPreferences')
+            || uses('usesUart')
+            || !!helpers?.has('__tc_print') || !!helpers?.has('__tc_println');
+        if (needsCstdio)
+            inc.push('<cstdio>');
         if (uses('usesI2C'))
             inc.push('<zephyr/drivers/i2c.h>');
         if (uses('usesSPI'))
@@ -239,83 +255,171 @@ export class ZephyrStrategy {
         visit(program);
         return found;
     }
+    /** Pins referenced by gpio.* hal-ops in the program IR. lowerGpio routes a
+     *  pin to its devicetree spec by pin NUMBER, so the structured hal-op pins
+     *  are the authoritative signal for which __tc_dt_* specs are needed —
+     *  regardless of when the final call text is rendered. */
+    collectGpioPinUsage(program) {
+        const pins = new Set();
+        if (!program)
+            return pins;
+        const visit = (node) => {
+            if (!node || typeof node !== 'object')
+                return;
+            if (node.operation && typeof node.operation === 'object'
+                && typeof node.operation.operation === 'string'
+                && node.operation.operation.startsWith('gpio.')
+                && typeof node.operation.pin === 'number') {
+                pins.add(node.operation.pin);
+            }
+            for (const v of Object.values(node)) {
+                if (Array.isArray(v)) {
+                    for (const item of v)
+                        visit(item);
+                }
+                else if (v && typeof v === 'object')
+                    visit(v);
+            }
+        };
+        visit(program);
+        return pins;
+    }
+    /** Run `re` (global) against every raw string in the IR — raw expression
+     *  values plus raw hal-op codes — returning capture group 1 of each match
+     *  (the full match when the regex has no group). This is how references the
+     *  text scanners must see but that never appear as IR call nodes (e.g. a
+     *  rawCpp() escape hatch naming `__tc_dt_sw0` directly) are discovered. */
+    collectRawMatches(program, re) {
+        const found = new Set();
+        if (!program)
+            return found;
+        const scan = (text) => {
+            for (const m of text.matchAll(re))
+                found.add(m[1] ?? m[0]);
+        };
+        const visit = (node) => {
+            if (!node || typeof node !== 'object')
+                return;
+            if (node.kind === 'raw' && typeof node.value === 'string')
+                scan(node.value);
+            if (node.operation && typeof node.operation === 'object'
+                && node.operation.operation === 'raw' && typeof node.operation.code === 'string') {
+                scan(node.operation.code);
+            }
+            for (const v of Object.values(node)) {
+                if (Array.isArray(v)) {
+                    for (const item of v)
+                        visit(item);
+                }
+                else if (v && typeof v === 'object')
+                    visit(v);
+            }
+        };
+        visit(program);
+        return found;
+    }
+    /** Whether the wiring-compat GPIO read surface (__tc_gpio_read definition,
+     *  __tc_gpio_dev dispatcher, and the wiring_compat polyfill's digitalRead /
+     *  HIGH / LOW macros) must be emitted. Consumers: user digitalRead() calls
+     *  (usesDigitalRead), the @typecad/safety voter (calls __tc_gpio_read
+     *  directly via lowered raw text), and the UI runtime header's
+     *  unconditional digitalRead() poll (entryHasUI — build-global, so every TU
+     *  in a UI build carries the macros). With no analysis present (capability
+     *  query), default to emitting — same convention as the uses() helper. */
+    needsGpioReadShim(program, ctx) {
+        if (program && programUsesSafety(program))
+            return true;
+        if (entryHasUI())
+            return true;
+        const a = ctx?.analysis;
+        return a ? !!a.usesDigitalRead : true;
+    }
     shimLines(program, ctx) {
         const chip = this.resolveChip(ctx, program);
         const isPrintf = this.resolveDebugMode(ctx) === 'printf';
-        const lines = [
-            '// cuttlefish runtime shim. Wrapped in a single include guard so the',
-            '// block is safe to emit into multiple headers and .cpp files within',
-            '// one translation unit (a .cpp may #include several headers that each',
-            '// carry the shim). The guard ensures the definitions are seen exactly',
-            '// once per TU.',
-            '#ifndef CUTTLEFISH_SHIM_DEFINED',
-            '#define CUTTLEFISH_SHIM_DEFINED',
-            '#ifndef CUTTLEFISH_UNDEFINED',
-            '#define CUTTLEFISH_UNDEFINED 0',
-            '#endif',
-            'template<typename T> inline bool cuttlefish_is_nullish(const T& v) { return false; }',
-            'inline bool cuttlefish_is_nullish(long long v) { return v == CUTTLEFISH_UNDEFINED; }',
-            'inline bool cuttlefish_is_nullish(int v) { return v == CUTTLEFISH_UNDEFINED; }',
-            'inline bool cuttlefish_is_nullish(double v) { return v == static_cast<double>(CUTTLEFISH_UNDEFINED); }',
-            'inline bool cuttlefish_is_nullish(bool v) { return v == false; }',
-            'template<typename T> inline bool cuttlefish_is_nullish(T* v) { return v == nullptr; }',
-            'template<typename T> inline bool cuttlefish_exists(const T& v) { return !cuttlefish_is_nullish(v); }',
-            '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).
-            'inline unsigned long millis() { return static_cast<unsigned long>(k_uptime_get_32()); }',
-            // Arduino-compat defines referenced by the shared runtime polyfills.
-            '#ifndef HIGH', '#define HIGH 1', '#endif',
-            '#ifndef LOW', '#define LOW 0', '#endif',
-            '#ifndef PROGMEM', '#define PROGMEM', '#endif',
-            '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; }',
-            'inline long constrain(long x, long a, long b) { return x < a ? a : (x > b ? b : x); }',
-            // 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.
-            'inline void __tc_print(const char* s) { printf("%s", s); }',
-            'inline void __tc_print(double v) { printf("%g", v); }',
-            'inline void __tc_println(const char* s) { printf("%s\\n", s); }',
-            'inline void __tc_println(double v) { printf("%g\\n", v); }',
-        ];
-        // Devicetree specs for every board-defined GPIO pin. Emitted unconditionally
-        // (guarded by the include guard) so any of them is available whether or not
-        // a given program uses it. Safe because every spec references a node that
-        // exists in the active board's devicetree.
-        for (const spec of chip.gpio.dtSpecs) {
-            lines.push(`static const struct gpio_dt_spec __tc_dt_${spec.dtSpec} = GPIO_DT_SPEC_GET(DT_ALIAS(${spec.dtSpec}), gpios);`);
+        const a = ctx?.analysis;
+        const uses = (f) => (a ? !!a[f] : true);
+        const helpers = a?.usedPolyfillHelpers;
+        // --- Core shim, gated item by item on actual use ------------------------
+        // A minimal program (blink) uses none of these, and its output carries no
+        // shim block at all. Everything up to the #endif composes into one guard
+        // body; the guard itself is only stamped when the body is non-empty.
+        const guardBody = [];
+        // CUTTLEFISH_UNDEFINED: needed when the file references null/undefined
+        // literals (usesNullish), emits nullish helper CALLS (usesNullishHelper),
+        // or has async functions (the async state machine uses the macro for
+        // default waitFor* timeouts — not visible to the nullish scanners).
+        if (uses('usesNullish') || uses('usesNullishHelper') || uses('hasAsync')) {
+            guardBody.push('#ifndef CUTTLEFISH_UNDEFINED', '#define CUTTLEFISH_UNDEFINED 0', '#endif');
+        }
+        // Nullish helpers: only when the file actually emits cuttlefish_nullish /
+        // cuttlefish_exists CALLS (?? / ?. lowering). A file that only references
+        // null/undefined literals needs just the macro above — the same
+        // distinction the setup emitter's strip filter documents.
+        if (uses('usesNullishHelper')) {
+            guardBody.push('template<typename T> inline bool cuttlefish_is_nullish(const T& v) { return false; }', 'inline bool cuttlefish_is_nullish(long long v) { return v == CUTTLEFISH_UNDEFINED; }', 'inline bool cuttlefish_is_nullish(int v) { return v == CUTTLEFISH_UNDEFINED; }', 'inline bool cuttlefish_is_nullish(double v) { return v == static_cast<double>(CUTTLEFISH_UNDEFINED); }', 'inline bool cuttlefish_is_nullish(bool v) { return v == false; }', 'template<typename T> inline bool cuttlefish_is_nullish(T* v) { return v == nullptr; }', 'template<typename T> inline bool cuttlefish_exists(const T& v) { return !cuttlefish_is_nullish(v); }', '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.
+        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()); }');
+        }
+        // PROGMEM: only the (Arduino-oriented) UI runtime header can reference it.
+        if (entryHasUI()) {
+            guardBody.push('#ifndef PROGMEM', '#define PROGMEM', '#endif');
+        }
+        // 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; }');
+        }
+        if (uses('usesConstrain')) {
+            guardBody.push('inline long constrain(long x, long a, long b) { return x < a ? a : (x > b ? b : x); }');
+        }
+        // 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')) {
+            guardBody.push('inline void __tc_print(const char* s) { printf("%s", s); }', 'inline void __tc_print(double v) { printf("%g", v); }', 'inline void __tc_println(const char* s) { printf("%s\\n", s); }', 'inline void __tc_println(double v) { printf("%g\\n", v); }');
         }
         // 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.
-        const a = ctx?.analysis;
-        const uses = (f) => (a ? !!a[f] : true);
         if (uses('usesI2C') && chip.i2c) {
             for (let i = 0; i < chip.i2c.controllers.length; i++)
-                lines.push(...i2cInitLines(chip, i));
+                guardBody.push(...i2cInitLines(chip, i));
         }
         if (uses('usesSPI') && chip.spi) {
             for (let i = 0; i < chip.spi.controllers.length; i++)
-                lines.push(...spiInitLines(chip, i));
+                guardBody.push(...spiInitLines(chip, i));
         }
         if (uses('usesUart') && chip.uart) {
             for (let i = 0; i < chip.uart.controllers.length; i++)
-                lines.push(...uartInitLines(chip, i));
+                guardBody.push(...uartInitLines(chip, i));
         }
         if (uses('usesADC') && chip.adc)
-            lines.push(...adcInitLines(chip));
+            guardBody.push(...adcInitLines(chip));
         if (uses('usesPWM') && chip.pwm)
-            lines.push(...pwmInitLines(chip));
+            guardBody.push(...pwmInitLines(chip));
         if (uses('usesDAC') && chip.dac)
-            lines.push(...dacInitLines(chip));
+            guardBody.push(...dacInitLines(chip));
         if (uses('usesHwtimer') && chip.hwtimer)
-            lines.push(...hwtimerInitLines(chip));
+            guardBody.push(...hwtimerInitLines(chip));
         if (uses('usesInterrupts'))
-            lines.push(...interruptInitLines(chip));
+            guardBody.push(...interruptInitLines(chip));
         if (uses('usesWDT') && chip.wdt)
-            lines.push(...wdtInitLines(chip));
+            guardBody.push(...wdtInitLines(chip));
         if (uses('usesBle'))
-            lines.push(...bleInitLines());
+            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
         // when the program uses display.* but is NOT a UI program — the UI display
@@ -329,23 +433,42 @@ export class ZephyrStrategy {
         // previously dead code).
         if (uses('usesDisplay') && !entryHasUI()) {
             const rt = buildDisplayRuntime(this._displayState.profile);
-            lines.push(...rt.stateLines);
-            lines.push(rt.fontTable);
-            lines.push(rt.helpers);
+            guardBody.push(...rt.stateLines);
+            guardBody.push(rt.fontTable);
+            guardBody.push(rt.helpers);
         }
         if (uses('usesWifi'))
-            lines.push(...wifiInitLines());
+            guardBody.push(...wifiInitLines());
         if (uses('usesHttp'))
-            lines.push(...httpInitLines());
+            guardBody.push(...httpInitLines());
         if (uses('usesMqtt'))
-            lines.push(...mqttInitLines());
+            guardBody.push(...mqttInitLines());
         if (uses('usesPreferences'))
-            lines.push(...preferencesInitLines());
+            guardBody.push(...preferencesInitLines());
         if (uses('usesFS'))
-            lines.push(...fsInitLines());
+            guardBody.push(...fsInitLines());
         if (uses('usesRandom'))
-            lines.push(...randomInitLines());
-        lines.push('#endif // CUTTLEFISH_SHIM_DEFINED');
+            guardBody.push(...randomInitLines());
+        const lines = [];
+        if (guardBody.length > 0) {
+            lines.push('// cuttlefish runtime shim. Wrapped in a single include guard so the', '// block is safe to emit into multiple headers and .cpp files within', '// one translation unit (a .cpp may #include several headers that each', '// carry the shim). The guard ensures the definitions are seen exactly', '// once per TU.', '#ifndef CUTTLEFISH_SHIM_DEFINED', '#define CUTTLEFISH_SHIM_DEFINED', ...guardBody, '#endif // CUTTLEFISH_SHIM_DEFINED');
+        }
+        // Devicetree specs — one per board-defined GPIO pin, but ONLY for pins the
+        // program actually addresses (lowerGpio routes by pin number, and the
+        // structured gpio.* hal-op pins are visible here) plus aliases named
+        // verbatim in raw code (rawCpp escape hatches). Emitted OUTSIDE the single
+        // CUTTLEFISH_SHIM_DEFINED guard with a per-symbol guard: per-file pin sets
+        // differ, and in a multi-header TU the first header's TU-wide guard would
+        // otherwise hide the second header's specs. Without a program (capability
+        // query), emit them all.
+        const usedPins = this.collectGpioPinUsage(program);
+        const dtTextRefs = this.collectRawMatches(program, /__tc_dt_([A-Za-z0-9_]+)/g);
+        for (const spec of chip.gpio.dtSpecs) {
+            if (program && !usedPins.has(spec.pin) && !dtTextRefs.has(spec.dtSpec))
+                continue;
+            const guard = `__TC_DT_${spec.dtSpec.replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()}_SPEC`;
+            lines.push(`#ifndef ${guard}`, `#define ${guard}`, `static const struct gpio_dt_spec __tc_dt_${spec.dtSpec} = GPIO_DT_SPEC_GET(DT_ALIAS(${spec.dtSpec}), gpios);`, `#endif // ${guard}`);
+        }
         // --- Debug-mode halt + per-breakpoint disable registry ---
         //
         // Printf mode only. In gdb mode the cuttlefish debug preprocessor is
@@ -378,9 +501,12 @@ export class ZephyrStrategy {
         // 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;', '}');
-        // GPIO read shim: the wiring_compat polyfill routes the UI runtime
-        // header's unconditional digitalRead() poll (init-press-input.ts) to
-        // __tc_gpio_read, so the definition must NOT be gated on @typecad/safety.
+        // GPIO read shim: emitted only when something actually reads a pin at
+        // runtime — user digitalRead() calls, the @typecad/safety voter (calls
+        // __tc_gpio_read directly), or the UI runtime header's digitalRead() poll
+        // (init-press-input.ts). A program that only writes/toggles GPIO needs
+        // neither the dispatcher nor the reader.
+        //
         // The signature is `int` to match wiring_compat's forward declaration —
         // a uint32_t definition alongside it would leave the declared int
         // overload undefined (int wins overload resolution for small integer
@@ -393,8 +519,10 @@ export class ZephyrStrategy {
         // 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.
-        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)); }');
+        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)); }');
+        }
         // __tc_gpio_write / __tc_delay_us are only referenced via @typecad/safety
         // lowering, so they stay gated on it.
         if (program && programUsesSafety(program)) {
@@ -1017,6 +1145,45 @@ export class ZephyrStrategy {
         ]);
     }
     generateNativePolyfills(program, ctx) {
+        // wiring_compat (digitalRead/HIGH/LOW macros + the __tc_gpio_read forward
+        // declaration) is emitted only when something reads a pin: user
+        // digitalRead() calls, the @typecad/safety voter, or the UI runtime
+        // header's unconditional digitalRead() poll (init-press-input.ts — the
+        // loop body is dead when no pin watchers are configured but must
+        // compile). needsGpioReadShim defaults to true without analysis so
+        // capability queries keep seeing it.
+        const wiringCompat = {
+            // Wiring-compatibility shims for symbols the UI runtime header
+            // references unconditionally (e.g. init-press-input.ts polls pin
+            // watchers via digitalRead/HIGH/LOW even when none are configured —
+            // the loop body is dead but must compile). Zephyr lowers GPIO through
+            // its __tc_gpio_* helpers (defined in shimLines); these macros route
+            // the Wiring tokens to them.
+            kind: 'polyfill',
+            id: 'wiring_compat',
+            domain: 'standard',
+            requiredIncludes: [],
+            forwardDeclarations: [
+                // Forward-declared so the digitalRead macro (below) can reference it
+                // before the shim block defines the body. The shim emits the full
+                // definition via gpio_pin_get_raw.
+                'int __tc_gpio_read(int pin);',
+            ],
+            helperStructs: [],
+            helperFunctions: [],
+            shimMacros: [
+                '#ifndef HIGH',
+                '#define HIGH 1',
+                '#endif',
+                '#ifndef LOW',
+                '#define LOW 0',
+                '#endif',
+                '#ifndef digitalRead',
+                '#define digitalRead(pin) __tc_gpio_read(pin)',
+                '#endif',
+            ],
+            dependencies: [],
+        };
         const polyfills = [
             {
                 kind: 'polyfill',
@@ -1031,38 +1198,7 @@ export class ZephyrStrategy {
                 shimMacros: [],
                 dependencies: [],
             },
-            {
-                // Wiring-compatibility shims for symbols the UI runtime header
-                // references unconditionally (e.g. init-press-input.ts polls pin
-                // watchers via digitalRead/HIGH/LOW even when none are configured —
-                // the loop body is dead but must compile). Zephyr lowers GPIO through
-                // its __tc_gpio_* helpers (defined in shimLines); these macros route
-                // the Wiring tokens to them.
-                kind: 'polyfill',
-                id: 'wiring_compat',
-                domain: 'standard',
-                requiredIncludes: [],
-                forwardDeclarations: [
-                    // Forward-declared so the digitalRead macro (below) can reference it
-                    // before the shim block defines the body. The shim emits the full
-                    // definition via gpio_pin_get_raw.
-                    'int __tc_gpio_read(int pin);',
-                ],
-                helperStructs: [],
-                helperFunctions: [],
-                shimMacros: [
-                    '#ifndef HIGH',
-                    '#define HIGH 1',
-                    '#endif',
-                    '#ifndef LOW',
-                    '#define LOW 0',
-                    '#endif',
-                    '#ifndef digitalRead',
-                    '#define digitalRead(pin) __tc_gpio_read(pin)',
-                    '#endif',
-                ],
-                dependencies: [],
-            },
+            ...(this.needsGpioReadShim(program, ctx) ? [wiringCompat] : []),
             {
                 // STL-free string-method polyfills. String methods (.toUpperCase(),
                 // .includes(), .substring(), …) lower at IR level to __tc_* helpers for
@@ -1269,22 +1405,10 @@ struct __tc_StaticArray {
     // Named display-profile registry: maps config `profile` values (e.g.
     // "st7796-zephyr") to the shared DisplayProfile shape so transpile.ts can
     // resolve them per-framework. The Zephyr profiles are DT-binding descriptors;
-    // they're mapped to the shared shape (driver/width/height/colorFormat/
-    // rotation) the profile resolver expects.
+    // BUILT_IN_PROFILES (display/profiles.ts) is the single DT-binding →
+    // shared-shape mapping, shared with the preview's registry loader.
     getProfileRegistry() {
-        const m = new Map();
-        for (const [name, p] of Object.entries(ZEPHYR_DISPLAY_PROFILES)) {
-            m.set(name, {
-                driver: p.driver,
-                width: p.width,
-                height: p.height,
-                nativeWidth: p.nativeWidth,
-                nativeHeight: p.nativeHeight,
-                colorFormat: p.colorFormat,
-                rotation: p.rotation ?? 1,
-            });
-        }
-        return m;
+        return new Map(Object.entries(BUILT_IN_PROFILES));
     }
     colorFormat() {
         return 'rgb565';

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[];