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

package/dist/strategy.js

@@ -15,7 +15,9 @@
 // repository root) and are not subject to the license of this tool source.
 // ---------------------------------------------------------------------------
 import { buildWorkerRuntimePolyfill } from '@typecad/cuttlefish/api/shared';
+import { applyStringMethodRewrites } from '@typecad/cuttlefish/api/shared';
 import { programUsesSafety } from '@typecad/cuttlefish/api';
+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';
@@ -23,6 +25,9 @@ import { lowerHalOp } from './lowering/index.js';
 import { buildZephyrWorkerBacking } from './lowering/worker-backing.js';
 import { adcInitLines } from './lowering/adc.js';
 import { pwmInitLines } from './lowering/pwm.js';
+import { dacInitLines } from './lowering/dac.js';
+import { fsInitLines } from './lowering/fs.js';
+import { hwtimerInitLines } from './lowering/hwtimer.js';
 import { i2cInitLines } from './lowering/i2c.js';
 import { spiInitLines } from './lowering/spi.js';
 import { uartInitLines } from './lowering/uart.js';
@@ -125,6 +130,16 @@ export class ZephyrStrategy {
             inc.push('<zephyr/drivers/adc.h>');
         if (uses('usesPWM'))
             inc.push('<zephyr/drivers/pwm.h>');
+        if (uses('usesDAC'))
+            inc.push('<zephyr/drivers/dac.h>');
+        // Filesystem: littlefs on the storage partition. <cstring> backs the
+        // shim's strlen; the storage/flash_map + fs/littlefs headers carry the
+        // FIXED_PARTITION_ID macro + FS_LITTLEFS_DECLARE_DEFAULT_CONFIG the shim uses.
+        if (uses('usesFS'))
+            inc.push('<zephyr/fs/fs.h>', '<zephyr/fs/littlefs.h>', '<zephyr/storage/flash_map.h>', '<cstring>');
+        // Hardware timers via the counter driver.
+        if (uses('usesHwtimer'))
+            inc.push('<zephyr/drivers/counter.h>');
         if (uses('usesWDT'))
             inc.push('<zephyr/drivers/watchdog.h>');
         if (uses('usesPower'))
@@ -135,10 +150,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.
@@ -290,22 +306,28 @@ export class ZephyrStrategy {
             lines.push(...adcInitLines(chip));
         if (uses('usesPWM') && chip.pwm)
             lines.push(...pwmInitLines(chip));
+        if (uses('usesDAC') && chip.dac)
+            lines.push(...dacInitLines(chip));
+        if (uses('usesHwtimer') && chip.hwtimer)
+            lines.push(...hwtimerInitLines(chip));
         if (uses('usesInterrupts'))
             lines.push(...interruptInitLines(chip));
         if (uses('usesWDT') && chip.wdt)
             lines.push(...wdtInitLines(chip));
         if (uses('usesBle'))
             lines.push(...bleInitLines());
-        // Display runtime (minimal rect/text renderer): gated on the analyzer's
-        // usesDisplay flag (set by display.* hal-ops). This is the DIRECT-call
-        // display path (user code calling screen.display.fillRect etc.). It is
-        // SUPPRESSED when the UI display adapter is active — the adapter seam
-        // (providesDisplayAdapter/resolveDisplayAdapter) emits its own display_*
-        // runtime that drives the UI rendering pipeline via CuttlefishGFX, and the
-        // two define the same symbols (display_init, __tc_display_line) so emitting
-        // both causes redefinition errors. The adapter is active for the
-        // strategy-owned drivers (ili9341-zephyr, st7796-zephyr).
-        if (uses('usesDisplay') && !this.providesDisplayAdapter()) {
+        // 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
+        // adapter (emitted by cuttlefish's emitUIRuntime, solely under entryHasUI())
+        // defines the same display_init symbol, so emitting both would collide.
+        // `providesDisplayAdapter()` is a static capability (always true here) and
+        // does NOT track whether the adapter is actually emitted for THIS build, so
+        // the per-program UI signal (entryHasUI) is the correct gate. Without this,
+        // a direct display.* program has no definition for display_init/
+        // display_fill_rect/draw_rect/draw_text/flush (the gfx runtime was
+        // previously dead code).
+        if (uses('usesDisplay') && !entryHasUI()) {
             const rt = buildDisplayRuntime(this._displayState.profile);
             lines.push(...rt.stateLines);
             lines.push(rt.fontTable);
@@ -319,6 +341,8 @@ export class ZephyrStrategy {
             lines.push(...mqttInitLines());
         if (uses('usesPreferences'))
             lines.push(...preferencesInitLines());
+        if (uses('usesFS'))
+            lines.push(...fsInitLines());
         if (uses('usesRandom'))
             lines.push(...randomInitLines());
         lines.push('#endif // CUTTLEFISH_SHIM_DEFINED');
@@ -354,20 +378,27 @@ 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: 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.
+        // 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 (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.
+        // 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.
+        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)) {
-            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 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;
     }
@@ -384,6 +415,8 @@ export class ZephyrStrategy {
         const outputPins = new Set();
         const adcReadPins = new Set();
         const interruptPins = new Set();
+        const dacPins = new Set();
+        const hwtimerInstances = new Set();
         let usesWifiOps = false;
         let usesHttpOps = false;
         let usesMqttOps = false;
@@ -404,6 +437,16 @@ export class ZephyrStrategy {
                     if (op.operation === 'interrupt.attach' && typeof op.pin === 'number') {
                         interruptPins.add(op.pin);
                     }
+                    if (op.operation === 'dac.write' && typeof op.pin === 'number') {
+                        dacPins.add(op.pin);
+                    }
+                    if (typeof op.operation === 'string' && op.operation.startsWith('hwtimer.')) {
+                        const inst = typeof op.instance === 'number'
+                            ? op.instance
+                            : parseInt(String(op.instance), 10);
+                        if (!isNaN(inst))
+                            hwtimerInstances.add(inst);
+                    }
                     if (typeof op.operation === 'string' && op.operation.startsWith('wifi.')) {
                         usesWifiOps = true;
                     }
@@ -464,6 +507,55 @@ export class ZephyrStrategy {
                 });
             }
         }
+        // ── DAC pin validity ────────────────────────────────────────────────────
+        // dac.write resolves a HAL pin to a channel via the chip descriptor's
+        // dac.channels map. A pin not in that map lowers to a comment (silent
+        // no-op), and a chip without a `dac` entry (nRF52840, ESP32-S3) has no DAC
+        // at all. Flag either case so the user gets a clear message instead of a
+        // pin that silently does nothing.
+        if (dacPins.size > 0) {
+            const dacChannels = new Set((chip.dac?.channels ?? []).map((c) => c.pin));
+            for (const pin of dacPins) {
+                if (!dacChannels.has(pin)) {
+                    diags.push({
+                        severity: 'error',
+                        code: 'zephyr-dac-pin-unavailable',
+                        message: `GPIO ${pin} is not a DAC channel on ${chip.id} and cannot be driven with dac.write.`,
+                        hint: dacChannels.size > 0
+                            ? `Use a DAC-capable pin. On ${chip.id}: ${[...dacChannels].sort((x, y) => x - y).join(', ')}.`
+                            : `${chip.id} has no DAC. Use an esp32_devkitc target (ESP32 DAC on GPIO25/26).`,
+                        source: program.fileName,
+                    });
+                }
+            }
+        }
+        // ── Hardware-timer instance validity ────────────────────────────────────
+        // hwtimer.* resolves the instance index to a counter device via the chip
+        // descriptor's hwtimer.controllers. A chip without that entry (or an
+        // out-of-range instance) lowers to a comment — flag it so the user knows
+        // the timer will never fire.
+        if (hwtimerInstances.size > 0) {
+            const controllerCount = chip.hwtimer?.controllers.length ?? 0;
+            for (const inst of hwtimerInstances) {
+                if (controllerCount === 0) {
+                    diags.push({
+                        severity: 'error',
+                        code: 'zephyr-hwtimer-unavailable',
+                        message: `Hardware timer instance ${inst} is used but ${chip.id} exposes no free counter device.`,
+                        hint: `${chip.id} declares no hwtimer.controllers. Use a target with a free counter (e.g. nRF RTC1).`,
+                        source: program.fileName,
+                    });
+                }
+                else if (inst < 0 || inst >= controllerCount) {
+                    diags.push({
+                        severity: 'error',
+                        code: 'zephyr-hwtimer-instance-out-of-range',
+                        message: `Hardware timer instance ${inst} is out of range on ${chip.id} (0..${controllerCount - 1}).`,
+                        source: program.fileName,
+                    });
+                }
+            }
+        }
         // ── WiFi target validity ────────────────────────────────────────────────
         // WiFi ops require a chip with a WiFi radio. The ESP32-S3 descriptor sets
         // wifi.supported; the XIAO nRF52840 omits it (no radio). Flag wifi usage on
@@ -592,6 +684,18 @@ export class ZephyrStrategy {
             v = v.replace(/\bundefined\b/g, 'CUTTLEFISH_UNDEFINED');
             v = v.replace(/\bnull\b/g, 'CUTTLEFISH_UNDEFINED');
         }
+        // String-method lowering is shared across targets (see string-method-
+        // registry). Zephyr's strings are const char*, so the __tc_* helpers this
+        // rewrites to (defined by the string_methods polyfill) take const char*.
+        // includes/startsWith lower to inline strstr/strncmp (matching framework-
+        // arduino); everything else → a __tc_* helper call.
+        v = applyStringMethodRewrites(v, {
+            wrapReceiverFor: new Set(['indexOf']),
+            special: {
+                includes: (recv, args) => `(strstr(${recv}, ${args[0]}) != NULL)`,
+                startsWith: (recv, args) => `(strncmp(${recv}, ${args[0]}, strlen(${args[0]})) == 0)`,
+            },
+        });
         return v;
     }
     nullValue() {
@@ -684,6 +788,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
@@ -840,15 +999,22 @@ export class ZephyrStrategy {
         };
     }
     // ── Polyfills ───────────────────────────────────────────────────────────
-    // No native polyfills for the MVP — the shared runtime's string/array
-    // polyfills are pulled in when a program uses them. cuttlefish_halt is the
-    // one symbol the runtime header may reference; supply it as a halt loop.
+    // Zephyr is a no-STL target (hasVector/hasString = false), so array/string
+    // literals lower to __tc_StaticArray / const char* and string methods lower
+    // to __tc_* helpers — both need STL-free definitions emitted here (there is
+    // no shared-runtime fallback; the pipeline sources 100% of polyfills from
+    // generateNativePolyfills). Mirrors framework-arduino's AVR polyfills.
     nativePolyfills() {
         // cuttlefish_halt: always (the runtime header may reference it).
+        // string_methods / static_array: STL-free array + string helpers a no-STL
+        //   target needs (mutated/struct array literals + any string method).
         // timer_methods: k_timer/k_work pool for setInterval/setTimeout (gated on
         //   timerCallCount at emit time in generateNativePolyfills).
         // async_runtime: heap-free static Promise/microtask runtime (no STL needed).
-        return new Set(['cuttlefish_halt', 'wiring_compat', 'timer_methods', 'async_runtime']);
+        return new Set([
+            'cuttlefish_halt', 'wiring_compat', 'string_methods', 'static_array',
+            'timer_methods', 'async_runtime',
+        ]);
     }
     generateNativePolyfills(program, ctx) {
         const polyfills = [
@@ -897,6 +1063,75 @@ export class ZephyrStrategy {
                 ],
                 dependencies: [],
             },
+            {
+                // STL-free string-method polyfills. String methods (.toUpperCase(),
+                // .includes(), .substring(), …) lower at IR level to __tc_* helpers for
+                // every target; this supplies their definitions. Minimal-libc friendly:
+                // only <cstring> primitives (no <cctype> — case conversion is inline
+                // ASCII so the polyfill is self-contained). Mirrors framework-arduino.
+                kind: 'polyfill',
+                id: 'string_methods',
+                domain: 'embedded',
+                requiredIncludes: ['<cstring>'],
+                forwardDeclarations: [],
+                helperStructs: [],
+                helperFunctions: [`
+// TypeCAD string method polyfills (Zephyr, minimal-libc).
+#ifndef CUTTLEFISH_STR_BUF_SIZE
+#define CUTTLEFISH_STR_BUF_SIZE 64
+#endif
+bool __tc_endsWith(const char* s, const char* suffix) { int sl = strlen(s), tl = strlen(suffix); return sl >= tl && strcmp(s + sl - tl, suffix) == 0; }
+const char* __tc_toUpperCase(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; for (char* p = b; *p; p++) { if (*p >= 'a' && *p <= 'z') { *p = static_cast<char>(*p - 32); } } return b; }
+const char* __tc_toLowerCase(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; for (char* p = b; *p; p++) { if (*p >= 'A' && *p <= 'Z') { *p = static_cast<char>(*p + 32); } } return b; }
+const char* __tc_trim(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; while (*s == ' ' || *s == '\\t' || *s == '\\n' || *s == '\\r') s++; int len = strlen(s); while (len > 0 && (s[len-1] == ' ' || s[len-1] == '\\t' || s[len-1] == '\\n' || s[len-1] == '\\r')) len--; int cplen = len < CUTTLEFISH_STR_BUF_SIZE - 1 ? len : CUTTLEFISH_STR_BUF_SIZE - 1; strncpy(b, s, cplen); b[cplen] = '\\0'; return b; }
+const char* __tc_substring2(const char* s, int start, int end) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; int slen = strlen(s); if (start < 0) start = 0; if (end > slen) end = slen; if (end < start) end = start; int len = end - start; if (len >= CUTTLEFISH_STR_BUF_SIZE) len = CUTTLEFISH_STR_BUF_SIZE - 1; strncpy(b, s + start, len); b[len] = '\\0'; return b; }
+const char* __tc_substring1(const char* s, int start) { return __tc_substring2(s, start, strlen(s)); }
+const char* __tc_slice2(const char* s, int start, int end) { return __tc_substring2(s, start, end); }
+const char* __tc_slice1(const char* s, int start) { return __tc_substring2(s, start, strlen(s)); }
+const char* __tc_replace(const char* s, const char* old, const char* repl) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; const char* pos = strstr(s, old); if (!pos) { strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; return b; } int beforeLen = static_cast<int>(pos - s); int oldLen = static_cast<int>(strlen(old)); int replLen = static_cast<int>(strlen(repl)); if (beforeLen + replLen + static_cast<int>(strlen(pos + oldLen)) >= CUTTLEFISH_STR_BUF_SIZE) { strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; return b; } memcpy(b, s, beforeLen); memcpy(b + beforeLen, repl, replLen); strcpy(b + beforeLen + replLen, pos + oldLen); return b; }
+const char* __tc_charAt(const char* s, int idx) { static char buf[2][2]; static uint8_t slot = 0; slot ^= 1; buf[slot][0] = s[idx]; buf[slot][1] = '\\0'; return buf[slot]; }
+int __tc_charCodeAt(const char* s, int idx) { return static_cast<int>(static_cast<unsigned char>(s[idx])); }
+int __tc_indexOf(const char* s, const char* needle) { const char* p = strstr(s, needle); return p ? static_cast<int>(p - s) : -1; }
+`],
+                shimMacros: [],
+                dependencies: [],
+            },
+            {
+                // STL-free fixed-size array wrapper. Mutated/struct-element array
+                // literals and array methods (.push/.pop/.map/.filter) lower to
+                // __tc_StaticArray<T,N>; this supplies the template. Idempotent guard
+                // so a redefinition is a no-op. Mirrors framework-arduino.
+                kind: 'polyfill',
+                id: 'static_array',
+                domain: 'embedded',
+                requiredIncludes: [],
+                forwardDeclarations: [],
+                helperStructs: [],
+                helperFunctions: [`
+#ifndef __TC_STATIC_ARRAY_DEFINED
+#define __TC_STATIC_ARRAY_DEFINED
+template<typename T, int N>
+struct __tc_StaticArray {
+    T data[N];
+    int _size;
+    __tc_StaticArray() : _size(0) {}
+    int length() const { return _size; }
+    int size() const { return _size; }
+    void push(T val) { if (_size < N) data[_size++] = val; }
+    T pop() { return (_size > 0) ? data[--_size] : T(); }
+    int indexOf(T val) const { for (int i = 0; i < _size; i++) if (data[i] == val) return i; return -1; }
+    T& operator[](int i) { return data[i]; }
+    const T& operator[](int i) const { return data[i]; }
+    T* begin() { return &data[0]; }
+    T* end() { return &data[_size]; }
+    const T* begin() const { return &data[0]; }
+    const T* end() const { return &data[_size]; }
+};
+#endif
+`],
+                shimMacros: [],
+                dependencies: [],
+            },
         ];
         // Worker-offload runtime (Phase 1). Emitted only when the program uses
         // worker.* ops, backed by the Zephyr primitives in worker-backing.ts
@@ -926,7 +1161,11 @@ export class ZephyrStrategy {
                 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: [],
@@ -1012,11 +1251,12 @@ export class ZephyrStrategy {
     }
     // ── 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);

package/dist/toolchain/compat.js

@@ -15,6 +15,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import manifest from '../framework.manifest.js';
+import { discoverWest } from './west-discover.js';
 // ── minimal semver ──────────────────────────────────────────────────────────
 /** Parse "4.3.99" / "v4.3" / "4.3.99-rc1" → [4, 3, 99]. Undefined if unparseable. */
 export function parseVersion(v) {
@@ -70,7 +71,15 @@ export function satisfiesRange(version, range) {
  * and a bare "4.3.99".
  */
 export function detectZephyrVersion() {
-    const base = process.env.ZEPHYR_BASE;
+    let base = process.env.ZEPHYR_BASE;
+    if (!base) {
+        // Fall back to the discovered west install's zephyrBase — covers the
+        // micromamba env from @typecad/zephyr-installer WITHOUT activation.
+        // (micromamba run sets ZEPHYR_BASE only inside the west subprocess; this
+        // makes the compat check work in the parent cuttlefish process too.)
+        const install = discoverWest();
+        base = install?.zephyrBase;
+    }
     if (!base)
         return undefined;
     let content;

package/dist/toolchain/env-check.d.ts

@@ -0,0 +1,93 @@
+import { type WestInstall } from './west-discover.js';
+import { type CompatStatus } from './compat.js';
+/**
+ * Raw west facts gathered from discovery + a `west --version` probe. Mirrors
+ * ArduinoCliProbeData: `westFound` is true when a usable west install was
+ * discovered (discovery itself probes responsiveness).
+ */
+export interface WestProbeData {
+    /** A usable west install was discovered. */
+    westFound: boolean;
+    /** west version string if the `--version` probe parsed one, e.g. "1.3.0". */
+    westVersion: string | undefined;
+    /** Which discovery strategy found west, for surfacing to the user. */
+    source: WestInstall['source'] | undefined;
+    /** Effective ZEPHYR_BASE (env var, else a base discovery surfaced). */
+    zephyrBase: string | undefined;
+}
+/**
+ * Test-injection seam for checkZephyrEnv. Mirrors Arduino's
+ * CheckArduinoEnvOptions.fakeProbe so tests never spawn a real west/python.
+ */
+export interface CheckZephyrEnvOptions {
+    /** FOR TESTS ONLY: skip the real probe and use this data directly. */
+    fakeWestProbe?: WestProbeData;
+    /** FOR TESTS ONLY: override the board-existence lookup. */
+    fakeBoardExists?: (boardId: string, zephyrBase: string | undefined) => boolean | undefined;
+}
+export interface ZephyrEnvCheck {
+    /** west (the Zephyr build tool) was discovered and responsive. */
+    westFound: boolean;
+    /** west version string if known, e.g. "1.3.0". */
+    westVersion: string | undefined;
+    /** Discovery strategy that found west, for display. */
+    westSource: WestInstall['source'] | undefined;
+    /** Effective ZEPHYR_BASE (env var, else a discovered base). */
+    zephyrBase: string | undefined;
+    /** Detected Zephyr RTOS version from $ZEPHYR_BASE/VERSION, if readable. */
+    zephyrVersion: string | undefined;
+    /** Declared supported range (manifest.compat.zephyr), if any. */
+    compatRange: string | undefined;
+    /** Result of the compat-range check against the detected version. */
+    compatStatus: CompatStatus;
+    /** Raw board target from cuttlefish.config.ts, if configured. */
+    buildTarget: string | undefined;
+    /** buildTarget normalized for the installed Zephyr version (may equal it). */
+    resolvedBoardTarget: string | undefined;
+    /** Does the resolved board exist in the checkout? undefined = undetermined. */
+    boardTargetSupported: boolean | undefined;
+}
+export type ZephyrEnvOk = {
+    ok: true;
+    check: ZephyrEnvCheck;
+};
+export type ZephyrEnvFailure = {
+    ok: false;
+    reason: 'west-not-found' | 'zephyr-out-of-range' | 'board-not-supported';
+    check: ZephyrEnvCheck;
+    /** Human-readable lines ready to print. */
+    messages: string[];
+    /** Exact remediation hint, when applicable. */
+    fixCommand: string | undefined;
+};
+export type ZephyrEnvResult = ZephyrEnvOk | ZephyrEnvFailure;
+/** Clear the west-probe cache (for tests). Also resets discovery cache. */
+export declare function resetWestProbeCacheForTest(): void;
+/**
+ * Gather west facts: discover a usable install, then run `west --version`
+ * through it to capture the version. Memoized for the process lifetime (west
+ * installs don't move). Never throws — returns westFound:false on any failure.
+ */
+export declare function probeWestEnv(): WestProbeData;
+/**
+ * Does `boardId` exist as a board directory in the Zephyr checkout? Checks the
+ * HWMv2 vendor layout used by Zephyr 4.x: $ZEPHYR_BASE/boards/<vendor>/<boardId>.
+ * Returns true/false when determinable; undefined when the base is unknown or
+ * the boards/ tree can't be read (so callers never fail on an inconclusive
+ * lookup — they just skip the board check).
+ */
+export declare function boardExistsInCheckout(boardId: string, zephyrBase: string | undefined): boolean | undefined;
+/**
+ * Verify the environment can build for `buildTarget`. Cheap and
+ * side-effect-free: discovers west, reads the Zephyr version, checks the compat
+ * range, and — when a target is configured — verifies the board exists in the
+ * checkout. Reports what (if anything) is wrong.
+ *
+ * - If `buildTarget` is undefined/empty, the board check is skipped (not a
+ *   failure), mirroring Arduino's no-FQBN path.
+ * - Never installs anything. Never mutates the user environment.
+ * - Never throws — always returns a result. Callers decide how to react.
+ *
+ * `options` is for-test only (injects fake probe data / board lookup).
+ */
+export declare function checkZephyrEnv(buildTarget?: string, options?: CheckZephyrEnvOptions): ZephyrEnvResult;