@typecad/framework-zephyr 1.0.0-alpha.11 → 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'))
@@ -150,10 +166,11 @@ export class ZephyrStrategy {
         // program-analysis usesStdString detector doesn't see types generated by
         // the BLE lowering layer — so without forcing <string> here, any BLE server
         // with a Utf8 characteristic fails to compile ('std::string does not name a
-        // type'). Uses <string>, not <string.h>: the latter is the C flat-string
-        // header (already included for the shim's strncpy/strcmp).
+        // type'). <cstdlib>/<cstring> (not <stdlib.h>/<string.h>) back the shim's
+        // strtol/strcmp/strncpy — the same AUTOSAR-compliant spelling the HTTP,
+        // MQTT, and Preferences paths below already use.
         if (uses('usesBle'))
-            inc.push('<stdlib.h>', '<string.h>', '<string>', '<zephyr/bluetooth/bluetooth.h>', '<zephyr/bluetooth/conn.h>', '<zephyr/bluetooth/gatt.h>', '<zephyr/bluetooth/uuid.h>');
+            inc.push('<cstdlib>', '<cstring>', '<string>', '<zephyr/bluetooth/bluetooth.h>', '<zephyr/bluetooth/conn.h>', '<zephyr/bluetooth/gatt.h>', '<zephyr/bluetooth/uuid.h>');
         // Display: the analyzer's usesDisplay flag (set by display.* hal-ops) drives
         // this include. When ctx.analysis is absent (capability query), uses()
         // defaults to true so a real build never strips it.
@@ -238,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
@@ -328,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
@@ -377,20 +501,32 @@ 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;', '}');
-        // Safety shims: when the program uses @typecad/safety, provide __tc_gpio_read
-        // / __tc_gpio_write backed by the raw controller (a best-effort read that
-        // does not depend on a pin having a DT spec). __tc_delay_us uses k_busy_wait.
+        // 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 pin is a RUNTIME value here (safety's voter passes whatever pin it
-        // was handed), so the controller cannot be baked in as a single DT_NODELABEL
-        // on a multi-controller SoC (ESP32-S3: pins 0–31 → gpio0, 32–48 → gpio1).
-        // Emit a tiny __tc_gpio_dev(pin) 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.
-        if (program && programUsesSafety(program)) {
+        // 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
+        // arguments).
+        //
+        // The pin is a RUNTIME value here (the UI pin-watch table and safety's
+        // voter pass whatever pin they were handed), so the controller cannot be
+        // baked in as a single DT_NODELABEL on a multi-controller SoC (ESP32-S3:
+        // pins 0–31 → gpio0, 32–48 → gpio1). Emit a tiny __tc_gpio_dev(pin)
+        // 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.
+        if (this.needsGpioReadShim(program, ctx)) {
             lines.push(...emitGpioDevDispatcher(chip));
-            lines.push('inline int __tc_gpio_read(uint32_t pin) { return gpio_pin_get_raw(__tc_gpio_dev(pin), pin); }', '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 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)) {
+            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');
         }
         return lines;
     }
@@ -780,6 +916,61 @@ export class ZephyrStrategy {
     apiReservedEnumGuard() {
         return '';
     }
+    // ── Interrupt safety ─────────────────────────────────────────────────────
+    // Zephyr ISRs run above thread context: anything that sleeps (k_msleep),
+    // pends, or takes a driver lock is illegal there (asserted by the kernel in
+    // debug builds; corrupts scheduler state otherwise). The names below are the
+    // IR-level callees cuttlefish's interrupt-analysis pass matches (the same
+    // keys ArduinoStrategy uses; timing.delay/delay_microseconds hal-ops are
+    // mapped back to the bare names by the analyzer itself).
+    isrUnsafeOperations() {
+        return new Map([
+            ['delay', {
+                    reason: 'delay() lowers to k_msleep(), which sleeps the calling thread — illegal in Zephyr interrupt context (submit a k_work item or arm a k_timer instead)',
+                    severity: 'warning',
+                }],
+            ['delayMicroseconds', {
+                    reason: 'delayMicroseconds() busy-waits the CPU for the full delay, stalling every lower-priority interrupt and the scheduler for its duration',
+                    severity: 'warning',
+                }],
+            ['console.log', {
+                    reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
+                    severity: 'info',
+                }],
+            ['console.error', {
+                    reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
+                    severity: 'info',
+                }],
+            ['console.warn', {
+                    reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
+                    severity: 'info',
+                }],
+            ['I2C0', {
+                    reason: 'I2C transactions may sleep (driver locking + clock stretching) and are not callable from Zephyr interrupt context',
+                    severity: 'warning',
+                }],
+            ['I2C1', {
+                    reason: 'I2C transactions may sleep (driver locking + clock stretching) and are not callable from Zephyr interrupt context',
+                    severity: 'warning',
+                }],
+            ['SPI0', {
+                    reason: 'SPI transfers take driver locks and may wait on DMA completion — not safe in Zephyr interrupt context',
+                    severity: 'warning',
+                }],
+            ['SPI1', {
+                    reason: 'SPI transfers take driver locks and may wait on DMA completion — not safe in Zephyr interrupt context',
+                    severity: 'warning',
+                }],
+            ['UART0', {
+                    reason: 'UART output via uart_poll_out blocks until the TX FIFO has room — a full FIFO stalls the ISR',
+                    severity: 'info',
+                }],
+            ['UART1', {
+                    reason: 'UART output via uart_poll_out blocks until the TX FIFO has room — a full FIFO stalls the ISR',
+                    severity: 'info',
+                }],
+        ]);
+    }
     ambientTypeDeclarations() {
         // Preferences is the only HAL surface the framework lowers that is used as
         // a bare global (the HAL Preferences class is exported, but the canonical
@@ -954,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',
@@ -968,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
@@ -1098,7 +1297,11 @@ struct __tc_StaticArray {
                 id: 'async_runtime',
                 domain: 'embedded',
                 requiredIncludes: [],
-                forwardDeclarations: [],
+                // Polyfill definitions emit before shimLines, but the runtime's
+                // timer bodies call millis() (defined in shimLines) — declare it
+                // first so the polyfill compiles even for programs whose source
+                // has no explicit timing call.
+                forwardDeclarations: ['unsigned long millis();'],
                 helperStructs: [generateStaticAsyncRuntime(8, this.getAsyncRuntimeConfig().waitForPinEdge)],
                 helperFunctions: [],
                 shimMacros: [],
@@ -1184,11 +1387,12 @@ struct __tc_StaticArray {
     }
     // ── Strategy-owned display/touch adapter seam ────────────────────────────
     // Zephyr owns its display + touch adapters: the UI display adapter bridges
-    // the in-tree CuttlefishGFX class to Zephyr's display_write() API (see
-    // src/display/ui-adapter.ts), and the FT6336U touch adapter drives the I2C
-    // controller via Zephyr's i2c API (src/display/touch-adapter.ts). Both live
-    // in this package so cuttlefish carries no Zephyr/Wiring-specific display or
-    // touch knowledge. Mirrors ArduinoStrategy's provides*/resolve* pattern.
+    // the in-tree CuttlefishGFX class to the panel (per-controller init + wire
+    // format, see src/display/ui-adapter.ts), and the touch adapters drive the
+    // FT6336U (I2C capacitive) and XPT2046 (SPI resistive) controllers via
+    // Zephyr's bus APIs (src/display/touch-adapter.ts). Both live in this
+    // package so cuttlefish carries no Zephyr/Wiring-specific display or touch
+    // knowledge. Mirrors ArduinoStrategy's provides*/resolve* pattern.
     providesDisplayAdapter() { return true; }
     resolveDisplayAdapter(display) {
         const code = zephyrDisplayAdapterGenerator(display);
@@ -1201,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';