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

package/dist/lowering/wifi.js

@@ -122,6 +122,29 @@ export function wifiInitLines() {
         `    }`,
         `    __tc_wifi.inited = true;`,
         `}`,
+        ``,
+        `// ── blocking-wait pump ───────────────────────────────────────────────────`,
+        `// Blocking wifi waits hold the main thread, which suspends the loop()-driven`,
+        `// ui_tick — a 15s association would freeze the display for its whole`,
+        `// duration. Each wait slice sleeps 20ms and, in the entry TU of a UI build`,
+        `// (the only TU carrying the ui_tick definition), pumps one frame so`,
+        `// animations and touch stay live during the wait. Constraint: do NOT call`,
+        `// blocking wifi waits from inside UI event handlers — that re-enters`,
+        `// ui_tick mid-tick; use wifi.connect_start + wifi.is_connected there.`,
+        `#ifdef CUTTLEFISH_ENTRY_UI_TU`,
+        `static void ui_tick(uint16_t deltaMs);   // defined by the UI runtime header`,
+        `#endif`,
+        `static void __tc_wifi_wait_slice(uint32_t slice_ms) {`,
+        `    k_msleep(slice_ms);`,
+        `#ifdef CUTTLEFISH_ENTRY_UI_TU`,
+        `    static uint32_t last_ms = 0U;`,
+        `    uint32_t now_ms = k_uptime_get_32();`,
+        `    uint32_t delta = (last_ms != 0U) ? (now_ms - last_ms) : 0U;`,
+        `    if (delta > 250U) delta = 250U;   // same clamp as the loop() tick injection`,
+        `    last_ms = now_ms;`,
+        `    ui_tick(static_cast<uint16_t>(delta));`,
+        `#endif`,
+        `}`,
         `// CUTTLEFISH_WIFI_CORE_END`,
         ``,
         `// ── connect / disconnect (net_mgmt — conn_mgr monitor supplies L4 events) ─`,
@@ -176,8 +199,9 @@ export function wifiInitLines() {
         `static void __tc_wifi_connect(const char* ssid, const char* password, int32_t timeout_ms) {`,
         `    __tc_wifi_connect_start(ssid, password);`,
         `    // Block until the L4 handler signals connectivity or the deadline passes.`,
+        `    // 20ms slices let __tc_wifi_wait_slice pump the UI between polls.`,
         `    int32_t waited = 0;`,
-        `    while (!__tc_wifi.connected && waited < timeout_ms) { k_msleep(100); waited += 100; }`,
+        `    while (!__tc_wifi.connected && waited < timeout_ms) { __tc_wifi_wait_slice(20); waited += 20; }`,
         `    printk("tc-wifi: connect %s after %dms\\n", __tc_wifi.connected ? "ok" : "timeout", waited);`,
         `}`,
         `// CUTTLEFISH_WIFI_CONNECT_BLOCKING_END`,
@@ -241,7 +265,7 @@ export function wifiInitLines() {
         ``,
         `static void __tc_wifi_scan_blocking(void) {`,
         `    __tc_wifi_scan_start();`,
-        `    while (__tc_wifi.scanning) { k_msleep(100); }`,
+        `    while (__tc_wifi.scanning) { __tc_wifi_wait_slice(20); }`,
         `}`,
         ``,
         `static const char* __tc_wifi_scan_ssid(int32_t i) {`,
@@ -309,13 +333,12 @@ export function wifiInitLines() {
         `static void __tc_wifi_wait_connected(int32_t timeout_ms) {`,
         `    __tc_wifi_ensure_init();`,
         `    int32_t waited = 0;`,
-        `    while (!__tc_wifi.connected && waited < timeout_ms) { k_msleep(100); waited += 100; }`,
+        `    while (!__tc_wifi.connected && waited < timeout_ms) { __tc_wifi_wait_slice(20); waited += 20; }`,
         `}`,
-        ``,
         `static void __tc_wifi_wait_disconnected(void) {`,
         `    __tc_wifi_ensure_init();`,
         `    // No timeout in the HAL surface — block until the L4 handler clears the flag.`,
-        `    while (__tc_wifi.connected) { k_msleep(100); }`,
+        `    while (__tc_wifi.connected) { __tc_wifi_wait_slice(20); }`,
         `}`,
         ``,
         `// ── AP mode (NET_REQUEST_WIFI_AP_ENABLE / DISABLE) ──────────────────────`,

package/dist/strategy.d.ts

@@ -32,6 +32,26 @@ export declare class ZephyrStrategy implements PlatformStrategy {
      * nodes whose resolved `raw` code references it.
      */
     private programUsesAsyncRuntime;
+    /** 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. */
+    private collectGpioPinUsage;
+    /** 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. */
+    private collectRawMatches;
+    /** 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. */
+    private needsGpioReadShim;
     shimLines(program?: ProgramIR, ctx?: PlatformContext): string[];
     profileDiagnostics(program?: ProgramIR, ctx?: PlatformContext): Diagnostic[];
     /**

package/dist/strategy.js

@@ -21,6 +21,58 @@ import { entryHasUI } from '@typecad/cuttlefish/ui-hook';
 import { chipForTarget, setActiveChip } from './chips/index.js';
 import { resolveChipFromBoard } from './chips/resolve.js';
 import { emitGpioDevDispatcher } from './chips/controllers.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.
+ *
+ * `pwm` also covers tone.* — the tone lowering drives the descriptor's
+ * first PWM spec regardless of pin, so any tone op marks it used.
+ */
+function collectUsedPins(program, kind, chip) {
+    if (!program)
+        return undefined;
+    const pins = new Set();
+    let usesTone = false;
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            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'))
+                    pins.add(pin);
+                if (kind === 'pwm' && name.startsWith('pwm.'))
+                    pins.add(pin);
+            }
+            if (kind === 'pwm' && typeof name === 'string' && name.startsWith('tone.'))
+                usesTone = true;
+        }
+        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);
+    if (kind === 'pwm' && usesTone) {
+        const first = chip?.pwm?.specs[0];
+        if (first)
+            pins.add(first.pin);
+    }
+    return pins;
+}
 import { lowerHalOp } from './lowering/index.js';
 import { buildZephyrWorkerBacking } from './lowering/worker-backing.js';
 import { adcInitLines } from './lowering/adc.js';
@@ -44,7 +96,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 +165,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 +307,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, collectUsedPins(program, 'adc')));
         if (uses('usesPWM') && chip.pwm)
-            lines.push(...pwmInitLines(chip));
+            guardBody.push(...pwmInitLines(chip, collectUsedPins(program, 'pwm', 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 +485,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 +553,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,12 +571,14 @@ 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)), __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); }', '#ifndef __TC_DELAY_US_DEFINED', '#define __TC_DELAY_US_DEFINED', 'inline void __tc_delay_us(uint32_t us) { k_busy_wait(us); }', '#endif');
+            lines.push('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); }', '#endif');
         }
         return lines;
     }
@@ -1017,6 +1197,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 +1250,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 +1457,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';