@typecad/framework-zephyr 1.0.0-alpha.8

package/dist/lowering/random.js

@@ -0,0 +1,129 @@
+// ---------------------------------------------------------------------------
+// Random lowering — Zephyr random subsystem (sys_rand_get) + xorshift32 PRNG
+//
+// Zephyr's <zephyr/random/random.h> exposes sys_rand_get(dst, len), backed by
+// the configured entropy source (the nRF52840 hardware RNG when
+// CONFIG_HARDWARE_DEVICE_RANDOM_GENERATOR is selected, or the default test/
+// xoroshiro generator otherwise). It is seeded automatically at boot from the
+// entropy driver, so unlike Arduino there is no implicit seeding step.
+//
+// The HAL random surface is the Arduino-core model:
+//   random.int()    → a non-negative 31-bit integer [0, 2^31 - 1]
+//   random.range(a,b) → [a, b-1]   (Random.upTo(n) collapses to range(0, n))
+//   random.seed(s)  → re-seed the PRNG (Arduino randomSeed makes the sequence
+//                     deterministic from s)
+//
+// To honor random.seed (which sys_rand_get cannot, being a non-seedable
+// entropy tap), the lowering keeps a userspace xorshift32 PRNG. It is seeded
+// once from sys_rand_get on first use (so an unseeded program gets
+// hardware-random behavior), and re-seeded verbatim by random.seed (so a
+// program that calls Random.seed(42) gets a deterministic sequence, matching
+// the Arduino contract). xorshift32 is a 2^32-1-period PRNG adequate for the
+// non-cryptographic random.* surface; sys_csrand_get exists for crypto use the
+// HAL does not expose.
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+/**
+ * The random runtime shim. The xorshift32 state is a 32-bit word seeded from
+ * sys_rand_get on first use; random.seed overwrites it. Helpers are
+ * `static`/`inline` so the single generated TU does not trip -Wunused-function
+ * when only a subset of the ops is used (mirrors preferences.ts / wifi.ts).
+ */
+export function randomInitLines() {
+    return [
+        `// CUTTLEFISH_RANDOM_BEGIN`,
+        `#include <zephyr/random/random.h>`,
+        ``,
+        `// xorshift32 state. Seeded from sys_rand_get on first use; random.seed`,
+        `// overwrites it. uint32_t (not int32_t) so the sign bit never leaks into`,
+        `// the HAL's non-negative random.int range.`,
+        `static uint32_t __tc_rand_state = 0U;`,
+        `static bool __tc_rand_seeded = false;`,
+        ``,
+        `// One-time seed from the Zephyr entropy tap. Called lazily so a program`,
+        `// that only ever calls Random.seed never touches sys_rand_get (and so a`,
+        `// capability probe with no board never needs the entropy driver at all).`,
+        `static inline void __tc_rand_ensure_seeded(void) {`,
+        `    if (!__tc_rand_seeded) {`,
+        `        uint32_t seed = 0U;`,
+        `        (void)sys_rand_get(&seed, sizeof(seed));`,
+        `        // xorshift32 needs a non-zero state; if the entropy tap returns 0`,
+        `        // (vanishingly unlikely), fall back to a fixed odd constant so the`,
+        `        // sequence is still well-defined rather than stuck at 0.`,
+        `        if (seed == 0U) { seed = 0x9E3779B9U; }`,
+        `        __tc_rand_state = seed;`,
+        `        __tc_rand_seeded = true;`,
+        `    }`,
+        `}`,
+        ``,
+        `// Advance the xorshift32 state one step and return the raw 32-bit word.`,
+        `static inline uint32_t __tc_rand_next(void) {`,
+        `    __tc_rand_ensure_seeded();`,
+        `    uint32_t x = __tc_rand_state;`,
+        `    x ^= x << 13;`,
+        `    x ^= x >> 17;`,
+        `    x ^= x << 5;`,
+        `    __tc_rand_state = x;`,
+        `    return x;`,
+        `}`,
+        ``,
+        `// Re-seed the PRNG. After this call the sequence is deterministic from`,
+        `// \`seed\`, matching Arduino randomSeed. A literal zero seed is accepted and`,
+        `// remapped to the same odd constant (xorshift32 cannot start from 0).`,
+        `static inline void __tc_rand_seed(uint32_t seed) {`,
+        `    __tc_rand_state = (seed == 0U) ? 0x9E3779B9U : seed;`,
+        `    __tc_rand_seeded = true;`,
+        `}`,
+        ``,
+        `// Non-negative 31-bit integer [0, 2^31 - 1]. Mask the top bit so the value`,
+        `// is always non-negative even though int32_t is the HAL return type.`,
+        `static inline int32_t __tc_rand_int(void) {`,
+        `    return static_cast<int32_t>(__tc_rand_next() & 0x7FFFFFFFU);`,
+        `}`,
+        ``,
+        `// Half-open range [min, max-1]. Implements the HAL contract directly rather`,
+        `// than calling Arduino random(min, max): the modulus rejection-free form`,
+        `// avoids the modulo bias a naive (rand % (max-min)) introduces. max > min`,
+        `// is assumed (the HAL validates this at the source level).`,
+        `static inline int32_t __tc_rand_range(int32_t min, int32_t max) {`,
+        `    if (max <= min) { return min; }`,
+        `    uint32_t span = static_cast<uint32_t>(max) - static_cast<uint32_t>(min);`,
+        `    uint32_t r = __tc_rand_next();`,
+        `    return static_cast<int32_t>(min + static_cast<int32_t>(r % (span + 1U)));`,
+        `}`,
+        `// CUTTLEFISH_RANDOM_END`,
+        ``,
+    ];
+}
+/**
+ * Resolve a HAL random.* op to Zephyr C++ via the __tc_rand_* shim.
+ * Returns `{ code }` for the statement op (seed), `{ expression }` for the
+ * value-returning ops (int / range). The `default` arm throws the standard
+ * unsupported-op error so the manifest validator's per-op probe stays honest.
+ */
+export function lowerRandom(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'random.int':
+            return { expression: '__tc_rand_int()' };
+        case 'random.range': {
+            // When min is a literal 0 (the Random.upTo(max) collapse), emit the
+            // single-arg __tc_rand_range(0, max) form for readability — it is the
+            // exact equivalent range and matches what the HAL upTo path expects.
+            if (String(o.min) === '0')
+                return { expression: `__tc_rand_range(0, ${String(o.max)})` };
+            return { expression: `__tc_rand_range(${String(o.min)}, ${String(o.max)})` };
+        }
+        case 'random.seed': {
+            // The manifest validator's probe sends no seed field; tolerate it with a
+            // literal 0 (mirrors how wdt.lowering tolerates an absent timeout).
+            const seed = o.seed === undefined ? 0 : o.seed;
+            return { code: `__tc_rand_seed(static_cast<uint32_t>(${String(seed)}));` };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/spi.d.ts

@@ -0,0 +1,17 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the per-controller SPI state. The bus device resolves at compile time;
+ * a static spi_config holds the base operation flags, and mutable runtime fields
+ * hold the mode (CPOL/CPHA bits) + bit order (lsb) so set_mode/set_bit_order can
+ * rebuild operation at init time (Zephyr's spi_config.operation is the only knob).
+ */
+export declare function spiInitLines(chip: ZephyrChipDescriptor, controllerIndex: number): string[];
+/**
+ * Resolve a HAL spi.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export declare function lowerSpi(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/spi.js

@@ -0,0 +1,113 @@
+// ---------------------------------------------------------------------------
+// SPI lowering — spi_transceive_dt against a spi_dt_spec; CS as GPIO
+//
+// Zephyr's `spi_transceive_dt(&spec, tx, rx)` is stateless per-call, so there
+// is no pending-tx-buffer (unlike I2C). The CS pin is driven as a plain GPIO
+// (like ESP32), since the DT spec's CS handling is configured at compile time
+// but the HAL's explicit cs_low/cs_high ops want manual control.
+//
+// The board's SPI node (spi2 on the XIAO) has no pre-declared client device
+// node, so the lowering cannot use SPI_DT_SPEC_GET (which needs a client node).
+// Instead we build a `struct spi_config` at runtime against
+// DEVICE_DT_GET(DT_NODELABEL(spi2)) and call spi_transceive directly.
+// ---------------------------------------------------------------------------
+import { parseControllerIndex } from './util.js';
+import { controllerNodelabelForPin } from '../chips/controllers.js';
+/** The C variable prefix for a controller's state. */
+function prefix(idx) {
+    return `__tc_spi${idx}`;
+}
+/**
+ * Emit the per-controller SPI state. The bus device resolves at compile time;
+ * a static spi_config holds the base operation flags, and mutable runtime fields
+ * hold the mode (CPOL/CPHA bits) + bit order (lsb) so set_mode/set_bit_order can
+ * rebuild operation at init time (Zephyr's spi_config.operation is the only knob).
+ */
+export function spiInitLines(chip, controllerIndex) {
+    const ctrl = chip.spi?.controllers[controllerIndex];
+    if (!ctrl)
+        return [];
+    const p = prefix(controllerIndex);
+    return [
+        '// CUTTLEFISH_SPI_BEGIN',
+        `static const struct device* ${p}_dev = DEVICE_DT_GET(DT_NODELABEL(${ctrl.nodeLabel}));`,
+        `static bool ${p}_ready = false;`,
+        `static uint8_t ${p}_mode = 0;   // bit0=CPOL, bit1=CPHA`,
+        `static bool ${p}_lsb = false;   // false=MSB (default), true=LSB`,
+        `static struct spi_config ${p}_cfg = {`,
+        `    .frequency = 1000000,`,
+        `};`,
+        `static void ${p}_init(void) {`,
+        `    if (!${p}_ready) {`,
+        `        ${p}_cfg.bus = ${p}_dev;`,
+        `        ${p}_cfg.operation = SPI_OP_MODE_MASTER | SPI_WORD_SET(8)`,
+        `            | (${p}_lsb ? SPI_TRANSFER_LSB : SPI_TRANSFER_MSB)`,
+        `            | ((${p}_mode & 0x1) ? SPI_MODE_CPOL : 0)`,
+        `            | ((${p}_mode & 0x2) ? SPI_MODE_CPHA : 0);`,
+        `        ${p}_ready = true;`,
+        `    }`,
+        `}`,
+        '// CUTTLEFISH_SPI_END',
+    ];
+}
+/**
+ * Resolve a HAL spi.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerSpi(op, chip) {
+    const o = op;
+    const idx = parseControllerIndex(o.bus);
+    const p = prefix(idx);
+    switch (op.operation) {
+        case 'spi.begin':
+            return { code: `${p}_init();` };
+        case 'spi.end':
+            return { code: `spi_release(${p}_dev, &${p}_cfg);` };
+        case 'spi.begin_transaction':
+            // Config is static; transaction begin is a no-op (frequency/mode baked in).
+            return { code: `${p}_init();` };
+        case 'spi.end_transaction':
+            return { code: `(void)0;` };
+        case 'spi.set_mode':
+            // Apply CPOL/CPHA: store the mode byte then re-init so the next transfer
+            // picks up the rebuilt operation flags. The ready flag is cleared so
+            // _init() rebuilds rather than early-returning.
+            return { code: `{ ${p}_mode = static_cast<uint8_t>(${o.mode}); ${p}_ready = false; ${p}_init(); }` };
+        case 'spi.set_bit_order': {
+            // The HAL payload `order` is a string ("lsb" | "msb"), per SpiSetBitOrderOp.
+            // Normalize here in TS so we emit a boolean literal, not the raw string
+            // (which would be an undeclared C++ identifier).
+            const key = String(o.order).replace(/^["']|["']$/g, '').toLowerCase();
+            const lsb = (key === 'lsb' || key === 'lsbfirst') ? 'true' : 'false';
+            return { code: `{ ${p}_lsb = ${lsb}; ${p}_ready = false; ${p}_init(); }` };
+        }
+        case 'spi.transfer': {
+            // Single-byte full-duplex, returns the received byte (GCC stmt-expr).
+            return {
+                expression: `({ uint8_t __tx = static_cast<uint8_t>(${o.data}); uint8_t __rx = 0; struct spi_buf __tb = { .buf = &__tx, .len = 1 }; struct spi_buf_set __tbs = { .buffers = &__tb, .count = 1 }; struct spi_buf __rb = { .buf = &__rx, .len = 1 }; struct spi_buf_set __rbs = { .buffers = &__rb, .count = 1 }; ${p}_init(); spi_transceive(${p}_dev, &${p}_cfg, &__tbs, &__rbs); __rx; })`,
+            };
+        }
+        case 'spi.read_buffer': {
+            // Read count bytes by sending 0xFF dummy bytes (full-duplex read).
+            const count = o.count;
+            return {
+                code: `{ uint8_t __dummy[${count}] = {0}; for (int __i = 0; __i < (int)(${count}); __i++) __dummy[__i] = 0xFF; struct spi_buf __tb = { .buf = __dummy, .len = ${count} }; struct spi_buf_set __tbs = { .buffers = &__tb, .count = 1 }; struct spi_buf __rb = { .buf = reinterpret_cast<void*>(${o.buffer}), .len = ${count} }; struct spi_buf_set __rbs = { .buffers = &__rb, .count = 1 }; ${p}_init(); spi_transceive(${p}_dev, &${p}_cfg, &__tbs, &__rbs); }`,
+            };
+        }
+        case 'spi.cs_low':
+        case 'spi.cs_high': {
+            // CS driven as a plain GPIO via the owning controller (the CS pin comes
+            // from the op's `pin` field; Zephyr uses gpio_pin_set_raw). Resolve the
+            // controller by pin so a CS on a high-numbered pin (ESP32-S3 gpio1) lands
+            // on the right node.
+            const val = op.operation === 'spi.cs_low' ? 0 : 1;
+            const gpioController = controllerNodelabelForPin(chip, o.pin);
+            return {
+                code: `gpio_pin_set_raw(DEVICE_DT_GET(DT_NODELABEL(${gpioController})), ${o.pin}, ${val});`,
+            };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/timing.d.ts

@@ -0,0 +1,9 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * Resolve a HAL timing.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export declare function lowerTiming(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/timing.js

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Timing lowering — Zephyr kernel timing
+//
+// delay/millis/delay_microseconds/micros/free_heap lower directly. The four
+// timer ops (set_interval/set_timeout/clear_interval/clear_timeout) call the
+// timer_methods polyfill helpers (k_timer + k_work pool), declared as 'polyfill'
+// status in the manifest — the validator skips the resolver probe for these
+// (they legitimately return polyfill-helper calls, not direct lowering).
+// free_heap has no portable Zephyr query without CONFIG_SYS_HEAP_RUNTIME_STATS;
+// it returns 0 with a comment (honest limitation).
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a HAL timing.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerTiming(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'timing.delay': {
+            // Milliseconds — k_msleep is the blocking Zephyr call. Because
+            // isRtosTarget() returns true, the transpiler does not warn about
+            // blocking delays inside loop().
+            const ms = o.ms;
+            return { code: `k_msleep(${ms});` };
+        }
+        case 'timing.delay_microseconds': {
+            // k_busy_wait spins (does not yield); for cooperative μs delays.
+            return { code: `k_busy_wait(${o.us});` };
+        }
+        case 'timing.millis':
+            // k_uptime_get_32() returns int64_t milliseconds since boot. Cast to the
+            // Arduino-millis() return type (uint32_t) so overflow wraps identically.
+            return { expression: 'static_cast<uint32_t>(k_uptime_get_32())' };
+        case 'timing.micros': {
+            // Convert hardware cycles to microseconds. k_cycle_get_32 + the cycles/sec
+            // macro (note: sys_clock_hw_cycles_per_sec is a MACRO — needs parens).
+            return {
+                expression: '(uint32_t)(((uint64_t)k_cycle_get_32() * 1000000ULL) / sys_clock_hw_cycles_per_sec())',
+            };
+        }
+        case 'timing.free_heap':
+            // No portable free-heap query without CONFIG_SYS_HEAP_RUNTIME_STATS.
+            // Return 0 with a comment so callers don't get a link error.
+            return { expression: '(0 /* free_heap: enable CONFIG_SYS_HEAP_RUNTIME_STATS for real value */)' };
+        case 'timing.set_interval':
+            // Backed by the timer_methods polyfill (k_timer + k_work). The handler is
+            // the resolved C++ callback name; timeout is the repeat period (ms).
+            // NOTE: these ops are declared 'polyfill' in the manifest, so setInterval
+            // is rewritten to __tc_setInterval before reaching the lowering — these
+            // cases are a fallback/defense and use the real op fields (handler/timeout).
+            return { expression: `__tc_setInterval(${o.handler}, ${o.timeout})` };
+        case 'timing.set_timeout':
+            // One-shot: k_timer with K_FOREVER period.
+            return { expression: `__tc_setTimeout(${o.handler}, ${o.timeout})` };
+        case 'timing.clear_interval':
+            return { code: `__tc_clearInterval(${o.id});` };
+        case 'timing.clear_timeout':
+            return { code: `__tc_clearTimeout(${o.id});` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/tone.d.ts

@@ -0,0 +1,10 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Resolve a HAL tone.* op to Zephyr C++ via PWM.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export declare function lowerTone(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/tone.js

@@ -0,0 +1,50 @@
+// ---------------------------------------------------------------------------
+// Tone lowering — PWM-based square-wave generation
+//
+// tone is a convenience wrapper around PWM: a square wave at `frequency` Hz with
+// a 50% duty cycle. The lowering maps frequency → period (ns) and sets the PWM
+// channel to a 50% pulse. stop turns the output off (0% duty). The PWM spec is
+// resolved from the chip descriptor (pwm-led0 on the XIAO).
+//
+// An optional duration is honored by scheduling a stop via k_sleep in a detached
+// fashion — but the simple lowering is blocking (k_msleep(duration) then stop),
+// matching the synchronous Arduino tone() semantics. For non-blocking tone,
+// a workqueue would be needed (deferred).
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a HAL tone.* op to Zephyr C++ via PWM.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerTone(op, chip) {
+    const o = op;
+    switch (op.operation) {
+        case 'tone.play': {
+            // period_ns = 1e9 / freq; pulse_ns = period / 2 (50% duty).
+            // Build a fake pwm.write would need the spec var directly; emit the
+            // pwm_set_dt call against the same spec var the PWM lowering uses.
+            const spec = chip.pwm?.specs[0];
+            if (!spec) {
+                return { code: `/* tone.play(${o.frequency}): no PWM spec in chip descriptor */` };
+            }
+            const v = `__tc_pwm_${spec.dtSpec.replace(/-/g, '_')}`;
+            const freq = o.frequency;
+            const duration = o.duration;
+            const setTone = `uint32_t __period = (${freq} > 0) ? (1000000000ULL / static_cast<uint64_t>(${freq})) : 0; pwm_set_dt(&${v}, __period, __period / 2);`;
+            if (duration !== undefined) {
+                // Blocking tone for the requested duration, then stop.
+                return { code: `${setTone} k_msleep(${duration}); pwm_set_pulse_dt(&${v}, 0);` };
+            }
+            return { code: setTone };
+        }
+        case 'tone.stop': {
+            const spec = chip.pwm?.specs[0];
+            if (!spec)
+                return { code: `/* tone.stop: no PWM spec */` };
+            const v = `__tc_pwm_${spec.dtSpec.replace(/-/g, '_')}`;
+            return { code: `pwm_set_pulse_dt(&${v}, 0);` };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/uart.d.ts

@@ -0,0 +1,15 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the per-controller UART device + an init helper. Called from shimLines
+ * when the program uses UART.
+ */
+export declare function uartInitLines(chip: ZephyrChipDescriptor, controllerIndex: number): string[];
+/**
+ * Resolve a HAL uart.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export declare function lowerUart(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/uart.js

@@ -0,0 +1,102 @@
+// ---------------------------------------------------------------------------
+// UART lowering — uart_poll_out / uart_poll_in per-byte
+//
+// Zephyr's UART API is byte-oriented (uart_poll_out / uart_poll_in). The HAL's
+// uart.print/println/write lower to per-byte poll_out loops. For console output
+// the strategy's transformConsoleCall routes to printk; these uart.* ops are
+// for a specific UART port (the XIAO exposes uart0 on D6/D7).
+//
+// The device resolves at compile time via DEVICE_DT_GET(DT_NODELABEL(uart0)).
+// uart.begin configures the baud via uart_configure.
+// ---------------------------------------------------------------------------
+import { parseControllerIndex } from './util.js';
+/** The C variable prefix for a controller's state. */
+function prefix(idx) {
+    return `__tc_uart${idx}`;
+}
+/**
+ * Emit the per-controller UART device + an init helper. Called from shimLines
+ * when the program uses UART.
+ */
+export function uartInitLines(chip, controllerIndex) {
+    const ctrl = chip.uart?.controllers[controllerIndex];
+    if (!ctrl)
+        return [];
+    const p = prefix(controllerIndex);
+    return [
+        '// CUTTLEFISH_UART_BEGIN',
+        `static const struct device* ${p}_dev = DEVICE_DT_GET(DT_NODELABEL(${ctrl.nodeLabel}));`,
+        `static void ${p}_init(uint32_t baud) {`,
+        `    const struct uart_config cfg = { .baudrate = (baud ? baud : 115200), .parity = UART_CFG_PARITY_NONE, .stop_bits = UART_CFG_STOP_BITS_1, .data_bits = UART_CFG_DATA_BITS_8, .flow_ctrl = UART_CFG_FLOW_CTRL_NONE };`,
+        `    uart_configure(${p}_dev, &cfg);`,
+        `}`,
+        '// CUTTLEFISH_UART_END',
+    ];
+}
+/** Render a string-literal or expression to a per-byte poll_out loop. */
+function renderWrite(dev, value, newline) {
+    // String literal → emit a char-array loop (known length). Otherwise fall back
+    // to a const char* cast with a strlen-guarded loop.
+    if (/^".*"$/.test(value)) {
+        const body = `for (size_t __i = 0; __i < sizeof(${value}) - 1; __i++) { uart_poll_out(${dev}, (${value})[__i]); }`;
+        return newline ? `${body} uart_poll_out(${dev}, '\\n');` : body;
+    }
+    const body = `for (const char* __s = (const char*)(${value}); *__s; __s++) { uart_poll_out(${dev}, *__s); }`;
+    return newline ? `${body} uart_poll_out(${dev}, '\\n');` : body;
+}
+/**
+ * Resolve a HAL uart.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerUart(op) {
+    const o = op;
+    const idx = parseControllerIndex(o.port);
+    const p = prefix(idx);
+    const dev = `${p}_dev`;
+    switch (op.operation) {
+        case 'uart.begin':
+            return { code: `${p}_init(static_cast<uint32_t>(${o.baud}));` };
+        case 'uart.end':
+            return { code: `(void)${dev};` };
+        case 'uart.print':
+            return { code: renderWrite(dev, o.value, false) };
+        case 'uart.println':
+            return { code: renderWrite(dev, o.value, true) };
+        case 'uart.write':
+            return { code: renderWrite(dev, o.data, false) };
+        case 'uart.printf': {
+            // snprintf into a buffer, then poll_out each byte.
+            const fmt = o.format;
+            const args = (o.args ?? []).join(', ');
+            const argList = args ? `, ${args}` : '';
+            return {
+                code: `char __buf[128]; int __n = snprintk(__buf, sizeof(__buf), ${fmt}${argList}); for (int __i = 0; __i < __n; __i++) { uart_poll_out(${dev}, __buf[__i]); }`,
+            };
+        }
+        case 'uart.read':
+            // Non-blocking poll; returns the byte or -1 if none available.
+            return { expression: `({ unsigned char __b = 0; (uart_poll_in(${dev}, &__b) == 0) ? (int)__b : -1; })` };
+        case 'uart.peek':
+            // The poll API has no buffered-byte store, so there is no true peek.
+            // Return -1 (the Arduino "no data" sentinel) rather than blocking. This
+            // is an honest limitation of the byte-level poll driver; an interrupt- or
+            // DMA-backed UART driver would be needed for real peek semantics.
+            return { expression: '(-1)' };
+        case 'uart.available':
+            // The poll API reports only "at least one byte ready" via uart_poll_in's
+            // return code — it has no buffered-byte count, and probing with poll_in
+            // would DRAIN the very byte the caller next wants to read. So we cannot
+            // honestly report availability. Return 0 (Arduino's "no data" value)
+            // rather than the old truthy -1, so `if (uart.available())` loops don't
+            // spin forever on a false-positive. Callers should instead just call
+            // uart.read() directly (it returns -1 when no byte is ready). For true
+            // buffered availability, use an interrupt/DMA-backed UART driver.
+            return { expression: '(0)' };
+        case 'uart.flush':
+            // poll_out is synchronous (blocking until sent); flush is a no-op.
+            return { code: `(void)${dev};` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/util.d.ts

@@ -0,0 +1,4 @@
+/** Parse a peripheral bus/port string like "UART0" / "I2C1" / "SPI2" → numeric
+ *  index. The HAL op stream carries the bus as a TS-side name (I2C0, SPI0);
+ *  the index selects which controller in the chip descriptor is used. */
+export declare function parseControllerIndex(busOrPort: string | undefined): number;

package/dist/lowering/util.js

@@ -0,0 +1,12 @@
+// ---------------------------------------------------------------------------
+// Shared lowering utilities
+// ---------------------------------------------------------------------------
+/** Parse a peripheral bus/port string like "UART0" / "I2C1" / "SPI2" → numeric
+ *  index. The HAL op stream carries the bus as a TS-side name (I2C0, SPI0);
+ *  the index selects which controller in the chip descriptor is used. */
+export function parseControllerIndex(busOrPort) {
+    if (!busOrPort)
+        return 0;
+    const m = busOrPort.match(/(\d+)$/);
+    return m ? parseInt(m[1], 10) : 0;
+}

package/dist/lowering/wdt.d.ts

@@ -0,0 +1,15 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the WDT device + channel state. Called from shimLines when the program
+ * uses the watchdog.
+ */
+export declare function wdtInitLines(chip: ZephyrChipDescriptor): string[];
+/**
+ * Resolve a HAL wdt.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export declare function lowerWdt(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/wdt.js

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// WDT lowering — nRF watchdog via wdt0
+//
+// Zephyr's WDT API: install a timeout (before setup), then setup, then feed
+// periodically. The lowering caches the channel id returned by
+// wdt_install_timeout in a static var so wdt.reset can feed it.
+//
+// enable(timeout): wdt_install_timeout + wdt_setup. Zephyr expects the timeout
+// in milliseconds (wdt_window.max). The HAL passes a "250ms" string or WDTO_*
+// constant or a number; we parse to ms in the lowering.
+// ---------------------------------------------------------------------------
+/** Parse a HAL wdt timeout ("250ms", WDTO_2S, or a bare number) to ms.
+ *  Tolerates undefined (the manifest validator's probe sends a minimal op). */
+function timeoutToMs(timeout) {
+    if (typeof timeout === 'number')
+        return timeout;
+    if (!timeout)
+        return 1000; // default 1s when absent (e.g. the validator probe)
+    // Arduino WDTO_* constants.
+    const wdto = {
+        WDTO_15MS: 15, WDTO_30MS: 30, WDTO_60MS: 60, WDTO_120MS: 120,
+        WDTO_250MS: 250, WDTO_500MS: 500, WDTO_1S: 1000, WDTO_2S: 2000,
+        WDTO_4S: 4000, WDTO_8S: 8000,
+    };
+    if (wdto[timeout])
+        return wdto[timeout];
+    const m = timeout.match(/^(\d+)\s*ms$/i);
+    if (m)
+        return parseInt(m[1], 10);
+    const s = timeout.match(/^(\d+)\s*s$/i);
+    if (s)
+        return parseInt(s[1], 10) * 1000;
+    const n = parseInt(timeout, 10);
+    return isNaN(n) ? 1000 : n;
+}
+/**
+ * Emit the WDT device + channel state. Called from shimLines when the program
+ * uses the watchdog.
+ */
+export function wdtInitLines(chip) {
+    const nodeLabel = chip.wdt?.nodeLabel ?? 'wdt0';
+    return [
+        '// CUTTLEFISH_WDT_BEGIN',
+        `static const struct device* __tc_wdt_dev = DEVICE_DT_GET(DT_NODELABEL(${nodeLabel}));`,
+        'static int __tc_wdt_channel = -1;',
+        'static bool __tc_wdt_setup_done = false;',
+        '// CUTTLEFISH_WDT_END',
+    ];
+}
+/**
+ * Resolve a HAL wdt.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerWdt(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'wdt.enable': {
+            const ms = timeoutToMs(o.timeout);
+            // Install a timeout then set up the watchdog. Both are idempotent via
+            // the static flags. WDT_FLAG_RESET_CPU_CORE = full reset on timeout.
+            return {
+                code: [
+                    `if (!__tc_wdt_setup_done) {`,
+                    `    const struct wdt_timeout_cfg __cfg = { .window = { .min = 0, .max = ${ms} }, .callback = NULL, .flags = WDT_FLAG_RESET_CPU_CORE };`,
+                    `    __tc_wdt_channel = wdt_install_timeout(__tc_wdt_dev, &__cfg);`,
+                    `    wdt_setup(__tc_wdt_dev, WDT_OPT_PAUSE_HALTED_BY_DBG);`,
+                    `    __tc_wdt_setup_done = true;`,
+                    `}`,
+                ].join(' '),
+            };
+        }
+        case 'wdt.reset':
+            return { code: `if (__tc_wdt_channel >= 0) { wdt_feed(__tc_wdt_dev, __tc_wdt_channel); }` };
+        case 'wdt.disable':
+            return { code: `wdt_disable(__tc_wdt_dev); __tc_wdt_setup_done = false;` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/wifi.d.ts

@@ -0,0 +1,21 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * The WiFi runtime shim. All helpers are `static` so unused ones don't trip
+ * -Wunused-function in the single generated TU (mirrors ble.ts).
+ *
+ * State is driven by two net_mgmt event handlers:
+ *  - L4 connectivity (NET_EVENT_L4_CONNECTED/DISCONNECTED) → connected flag.
+ *    This reflects IP connectivity (post-DHCP), not just the WiFi link — the
+ *    events are raised by conn_mgr's monitoring layer (conn_mgr_monitor.c).
+ *  - WiFi scan (NET_EVENT_WIFI_SCAN_RESULT/SCAN_DONE) → scan_results pool.
+ */
+export declare function wifiInitLines(): string[];
+/**
+ * Resolve a HAL wifi.* op to Zephyr C++ via the __tc_wifi_* shim. Returns
+ * `{ code }` for statement ops, `{ expression }` for value-returning ops,
+ * `undefined` for out-of-scope ops (the manifest declares those unsupported).
+ */
+export declare function lowerWifi(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+} | undefined;