@typecad/cuttlefish 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/ir/program-analysis.js

@@ -38,6 +38,20 @@ function analyzeExpression(expr, result, strategy) {
                     }
                 }
             }
+            // Timer polyfill sizing — Timing.setInterval/Timing.setTimeout in
+            // expression position (e.g. `const id = Timing.setInterval(...)`) lower to
+            // a raw expression whose value contains `__tc_setInterval(...)`. The
+            // callee-based counter in the "call" case only fires for bare timer
+            // calls; without this the timer_methods polyfill is gated off and the
+            // link fails: "'__tc_setInterval' was not declared in this scope".
+            {
+                const intervals = expr.value.match(/__tc_setInterval\s*\(/g);
+                if (intervals)
+                    result.timerCallCount += intervals.length;
+                const timeouts = expr.value.match(/__tc_setTimeout\s*\(/g);
+                if (timeouts)
+                    result.timerCallCount += timeouts.length;
+            }
             if (/\bString\s*\(/.test(expr.value)) {
                 result.usesStringConversion = true;
             }
@@ -63,6 +77,24 @@ function analyzeExpression(expr, result, strategy) {
             if (expr.value.includes('__tc_str_ptr')) {
                 result.usesStrPtr = true;
             }
+            if (/std::chrono|steady_clock/.test(expr.value)) {
+                result.usesChrono = true;
+            }
+            if (/std::set\s*</.test(expr.value)) {
+                result.usesSet = true;
+            }
+            if (/std::(sort|find|transform|copy|fill|remove|count|reverse|accumulate)\s*\(/.test(expr.value)) {
+                result.usesAlgorithm = true;
+            }
+            if (/\b(printf|fprintf|sprintf|snprintf)\s*\(/.test(expr.value)) {
+                result.usesCstdio = true;
+            }
+            if (/\bdigitalRead\s*\(/.test(expr.value)) {
+                result.usesDigitalRead = true;
+            }
+            if (/cuttlefish_halt\s*\(/.test(expr.value)) {
+                result.usesHalt = true;
+            }
             break;
         case "method-call":
             if (strategy.isConsoleCall(expr.callee)) {
@@ -216,6 +248,108 @@ function analyzeExpression(expr, result, strategy) {
                 analyzeExpression(expr.expression, result, strategy);
             }
             break;
+        case "hal-expr":
+            // Value-position HAL ops (e.g. `const v = D32.readAnalog()` lowers to an
+            // adc.read hal-expr initializer; `const ip = WiFi.localIP()` to a wifi
+            // hal-expr) never pass through the statement-level hal-op detection
+            // below, so mirror the FULL peripheral-flag detection here. Without this,
+            // a value-returning HAL op used in a var-init or expression context fails
+            // to set its analysis flag — the framework then drops the matching init
+            // block + forced includes (e.g. __tc_adc_read was emitted but the
+            // CUTTLEFISH_ADC init block and adc_oneshot.h include were not). Keep this
+            // list in sync with the hal-op statement case at the bottom of this file.
+            if (expr.operation && typeof expr.operation.operation === "string") {
+                const opName = expr.operation.operation;
+                if (opName.startsWith("display.")) {
+                    result.usesGPIO = true;
+                    result.usesDisplay = true;
+                }
+                if (opName.startsWith("gpio."))
+                    result.usesGPIO = true;
+                if (opName === "gpio.read")
+                    result.usesDigitalRead = true;
+                if (opName.startsWith("pwm."))
+                    result.usesPWM = true;
+                if (opName.startsWith("rmt."))
+                    result.usesRmt = true;
+                if (opName.startsWith("adc."))
+                    result.usesADC = true;
+                if (opName.startsWith("dac."))
+                    result.usesDAC = true;
+                if (opName.startsWith("power."))
+                    result.usesPower = true;
+                if (opName.startsWith("wdt."))
+                    result.usesWdt = true;
+                // Safety HAL ops (@typecad/safety) — map each op to the
+                // __tc_safety_* polyfill helper it triggers, so the mode-table and
+                // voter polyfills survive tree-shaking when actually used. Matches
+                // the resolveSafetyOp output naming. Cast through string because the
+                // HALOpIR operation union is closed and doesn't include safety.* ops
+                // (those are owned by the optional @typecad/safety package).
+                const safetyOpName = opName;
+                if (safetyOpName === "safety.record_pin_mode") {
+                    result.usedPolyfillHelpers.add("__tc_safety_record_pin_mode");
+                }
+                if (safetyOpName === "safety.read_safe") {
+                    result.usedPolyfillHelpers.add("__tc_safety_read_safe");
+                }
+                if (safetyOpName === "safety.write_verify") {
+                    result.usedPolyfillHelpers.add("__tc_safety_write_verify");
+                }
+                if (opName.startsWith("interrupt."))
+                    result.usesInterrupts = true;
+                if (opName.startsWith("pulse."))
+                    result.usesPulse = true;
+                if (opName.startsWith("shift."))
+                    result.usesShift = true;
+                if (opName.startsWith("tone."))
+                    result.usesTone = true;
+                if (opName.startsWith("i2c."))
+                    result.usesI2C = true;
+                if (opName.startsWith("spi."))
+                    result.usesSPI = true;
+                if (opName.startsWith("uart."))
+                    result.usesUart = true;
+                if (opName.startsWith("wifi.")) {
+                    result.usesWifi = true;
+                    if (opName === "wifi.connect" || opName === "wifi.connect_start" || opName === "wifi.disconnect") {
+                        result.usesWifiConnect = true;
+                        if (opName === "wifi.connect")
+                            result.usesWifiConnectBlocking = true;
+                    }
+                    else if (opName.startsWith("wifi.scan"))
+                        result.usesWifiScan = true;
+                    else if (opName === "wifi.status" || opName === "wifi.local_ip" || opName === "wifi.rssi" || opName === "wifi.mac")
+                        result.usesWifiQuery = true;
+                    else if (opName === "wifi.set_hostname")
+                        result.usesWifiConfig = true;
+                }
+                if (opName.startsWith("http."))
+                    result.usesHttp = true;
+                if (opName.startsWith("ble."))
+                    result.usesBle = true;
+                if (opName.startsWith("preferences."))
+                    result.usesPreferences = true;
+                if (opName.startsWith("random."))
+                    result.usesRandom = true;
+                if (opName.startsWith("fs."))
+                    result.usesFS = true;
+                if (opName.startsWith("mdns."))
+                    result.usesMdns = true;
+                if (opName.startsWith("mqtt."))
+                    result.usesMqtt = true;
+                if (opName.startsWith("ota."))
+                    result.usesOta = true;
+                if (opName.startsWith("temp."))
+                    result.usesTemp = true;
+                if (opName.startsWith("hwtimer."))
+                    result.usesHwtimer = true;
+                if (opName.startsWith("capacitive."))
+                    result.usesCapacitive = true;
+                if (opName.startsWith("worker."))
+                    result.usesWorker = true;
+            }
+            break;
     }
 }
 /**
@@ -242,6 +376,11 @@ function analyzeStatement(statement, result, strategy) {
             if (statement.callee === "millis" || statement.callee === "delay") {
                 result.usesMillis = true;
             }
+            // Awaited HAL wait markers become async state-machine poll states that
+            // arm deadlines via currentTimeMillis().
+            if (statement.callee === "__WIFI_WAIT__" || statement.callee === "__HTTP_WAIT__" || statement.callee === "__HAL_WAIT__") {
+                result.usesMillis = true;
+            }
             // Namespace-qualified polyfill entry points used as bare call statements
             // (e.g. `Timing.delay(5);`). The expression-level analyzer (case
             // "method-call") already checks these prefixes, but a statement-form call
@@ -264,7 +403,10 @@ function analyzeStatement(statement, result, strategy) {
             if (statement.callee === "tone" || statement.callee === "noTone") {
                 result.usesTone = true;
             }
-            if (statement.callee.startsWith("console.") || statement.callee.startsWith("_uart_")) {
+            // console.* is NOT UART: on ESP-IDF it lowers to printf, on Arduino to
+            // Serial via hasConsoleCalls. Only real UART HAL / Serial peripheral
+            // usage should gate the uart shim (avoids unused __tc_uart*_init).
+            if (statement.callee.startsWith("_uart_")) {
                 result.usesUart = true;
             }
             if (statement.callee.startsWith("Serial.") || statement.callee === "Serial") {
@@ -284,6 +426,18 @@ function analyzeStatement(statement, result, strategy) {
                 result.usesMap = true;
             if (statement.callee === "constrain")
                 result.usesConstrain = true;
+            // Statement-form setInterval/setTimeout mirror the expression-level
+            // timer-count (analyzeExpression). A top-level `setInterval(...)` call
+            // stays a `call` statement (never becomes a method-call expression — see
+            // the comment above re: Timing./Num./WDT.), so without this mirror the
+            // timer polyfill gate (timerCallCount) stays 0 and __tc_setInterval is
+            // emitted as a call but never defined (demo: "'__tc_setInterval' was not
+            // declared in this scope"). The arrow-callback hoister renames the callee
+            // to __tc_setInterval/__tc_setTimeout, so check both pre- and post-rename.
+            if (statement.callee === "setInterval" || statement.callee === "setTimeout"
+                || statement.callee === "__tc_setInterval" || statement.callee === "__tc_setTimeout") {
+                result.timerCallCount++;
+            }
             // The HAL resolver lowers WDT.*/Timing.* namespace calls to bare AVR
             // library functions (WDT.reset() → wdt_reset(), Timing.delay() → delay(),
             // Timing.millis() → millis()). When that happens the `WDT.`/`Timing.`
@@ -311,6 +465,27 @@ function analyzeStatement(statement, result, strategy) {
                     }
                 }
             }
+            // Timer polyfill sizing for __EMIT__ statements (callee "__EMIT__"):
+            // Timing.setInterval/Timing.setTimeout can lower to an __EMIT__ call whose
+            // single string arg is the raw C++ payload, e.g.
+            // `return __tc_setInterval(<cb>, 500)`. The callee-based timer counter
+            // above only fires for bare setInterval/__tc_setInterval calls, so without
+            // this the timer_methods polyfill is gated off and the link fails:
+            // "'__tc_setInterval' was not declared in this scope". Count call sites
+            // embedded in the raw payload. (The hal-op raw-code path has a parallel
+            // counter below.)
+            if (statement.callee === "__EMIT__") {
+                for (const arg of statement.args) {
+                    if (arg && arg.kind === "string" && typeof arg.value === "string") {
+                        const matches = arg.value.match(/__tc_setInterval\s*\(/g);
+                        if (matches)
+                            result.timerCallCount += matches.length;
+                        const timeouts = arg.value.match(/__tc_setTimeout\s*\(/g);
+                        if (timeouts)
+                            result.timerCallCount += timeouts.length;
+                    }
+                }
+            }
             for (const arg of statement.args) {
                 analyzeExpression(arg, result, strategy);
             }
@@ -424,6 +599,95 @@ function analyzeStatement(statement, result, strategy) {
                     result.usesTone = true;
                 if (opName.startsWith("uart."))
                     result.usesUart = true;
+                // Display HAL ops (display.init from ui.mount, display.flush per frame)
+                // always imply GPIO usage (CS/DC/RST pins). Native SPI/I2C display
+                // adapters emit their own transport #includes (driver/spi_master.h,
+                // driver/i2c_master.h) — we don't force usesSPI/usesI2C here because
+                // that would pull headers even for non-display SPI/I2C code, and the
+                // display's transport type can't be determined from the op alone.
+                if (opName.startsWith("display.")) {
+                    result.usesGPIO = true;
+                    result.usesDisplay = true;
+                }
+                // ESP32 peripheral usage — framework-esp32 gates IDF driver blocks
+                // and forced includes on these. No-op for other frameworks (their
+                // shimLines emit no CUTTLEFISH_* blocks with these marker names).
+                if (opName.startsWith("gpio."))
+                    result.usesGPIO = true;
+                if (opName === "gpio.read")
+                    result.usesDigitalRead = true;
+                if (opName.startsWith("pwm."))
+                    result.usesPWM = true;
+                if (opName.startsWith("rmt."))
+                    result.usesRmt = true;
+                if (opName.startsWith("adc."))
+                    result.usesADC = true;
+                if (opName.startsWith("dac."))
+                    result.usesDAC = true;
+                if (opName.startsWith("power."))
+                    result.usesPower = true;
+                if (opName.startsWith("wdt."))
+                    result.usesWdt = true;
+                // Safety HAL ops (@typecad/safety) — map each op to the
+                // __tc_safety_* polyfill helper it triggers, so the mode-table and
+                // voter polyfills survive tree-shaking when actually used. Matches
+                // the resolveSafetyOp output naming. Cast through string because the
+                // HALOpIR operation union is closed and doesn't include safety.* ops
+                // (those are owned by the optional @typecad/safety package).
+                const safetyOpName = opName;
+                if (safetyOpName === "safety.record_pin_mode") {
+                    result.usedPolyfillHelpers.add("__tc_safety_record_pin_mode");
+                }
+                if (safetyOpName === "safety.read_safe") {
+                    result.usedPolyfillHelpers.add("__tc_safety_read_safe");
+                }
+                if (safetyOpName === "safety.write_verify") {
+                    result.usedPolyfillHelpers.add("__tc_safety_write_verify");
+                }
+                if (opName.startsWith("interrupt."))
+                    result.usesInterrupts = true;
+                if (opName.startsWith("pulse."))
+                    result.usesPulse = true;
+                if (opName.startsWith("shift."))
+                    result.usesShift = true;
+                if (opName.startsWith("wifi.")) {
+                    result.usesWifi = true;
+                    if (opName === "wifi.connect" || opName === "wifi.connect_start" || opName === "wifi.disconnect") {
+                        result.usesWifiConnect = true;
+                        if (opName === "wifi.connect")
+                            result.usesWifiConnectBlocking = true;
+                    }
+                    else if (opName.startsWith("wifi.scan"))
+                        result.usesWifiScan = true;
+                    else if (opName === "wifi.status" || opName === "wifi.local_ip" || opName === "wifi.rssi" || opName === "wifi.mac")
+                        result.usesWifiQuery = true;
+                    else if (opName === "wifi.set_hostname")
+                        result.usesWifiConfig = true;
+                }
+                if (opName.startsWith("http."))
+                    result.usesHttp = true;
+                if (opName.startsWith("ble."))
+                    result.usesBle = true;
+                if (opName.startsWith("preferences."))
+                    result.usesPreferences = true;
+                if (opName.startsWith("random."))
+                    result.usesRandom = true;
+                if (opName.startsWith("fs."))
+                    result.usesFS = true;
+                if (opName.startsWith("mdns."))
+                    result.usesMdns = true;
+                if (opName.startsWith("mqtt."))
+                    result.usesMqtt = true;
+                if (opName.startsWith("ota."))
+                    result.usesOta = true;
+                if (opName.startsWith("temp."))
+                    result.usesTemp = true;
+                if (opName.startsWith("hwtimer."))
+                    result.usesHwtimer = true;
+                if (opName.startsWith("capacitive."))
+                    result.usesCapacitive = true;
+                if (opName.startsWith("worker."))
+                    result.usesWorker = true;
                 // Timing HAL ops (timing.delay/millis/micros) carry a typed operation
                 // name, not raw code, so the regex scans below miss them. Mirror the
                 // raw-code timing detection here so usesMillis/usesTiming (and thus
@@ -461,13 +725,30 @@ function analyzeStatement(statement, result, strategy) {
                     result.usesTiming = true;
                     result.usesMillis = true;
                 }
+                // Timer polyfill sizing — `Timing.setInterval(...)` / `Timing.setTimeout(...)`
+                // are resolved by the HAL method resolver, which reads TimingClass's
+                // rawCpp body and emits a raw hal-op whose code is e.g.
+                // `return __tc_setInterval(<cb>, 500)`. The callee-based counter below
+                // (statement.callee === "__tc_setInterval") never fires for these — the
+                // statement is a hal-op, not a bare timer call — so without counting
+                // here the timer_methods polyfill is gated off (timerCallCount == 0)
+                // and the link fails: "'__tc_setInterval' was not declared in this
+                // scope". Count each __tc_setInterval/__tc_setTimeout call site in the
+                // raw code. The optional `return ` prefix is emitted by value-returning
+                // HAL methods (statement context), so match with or without it.
+                const intervalSites = code.match(/__tc_setInterval\s*\(/g);
+                if (intervalSites)
+                    result.timerCallCount += intervalSites.length;
+                const timeoutSites = code.match(/__tc_setTimeout\s*\(/g);
+                if (timeoutSites)
+                    result.timerCallCount += timeoutSites.length;
                 // Native AVR peripheral usage inside raw hal-op code (e.g. the
                 // EEPROM namespace lowers to `EEPROM.write(...)` in a raw hal-op;
                 // Serial/SPI/Wire may appear as lowered library calls too).
                 if (/\bEEPROM\b/.test(code) || /\beeprom_(read|write|update)_byte\b/.test(code)) {
                     result.usesEEPROM = true;
                 }
-                if (/\b(Serial|console)\b/.test(code)) {
+                if (/\bSerial\b/.test(code)) {
                     result.usesUart = true;
                 }
                 if (/\bSPI\b/.test(code)) {
@@ -535,6 +816,41 @@ export function analyzeProgram(program, strategy) {
         hasGenerators: false,
         usesStdMap: false,
         timerCallCount: 0,
+        usesGPIO: false,
+        usesPWM: false,
+        usesRmt: false,
+        usesADC: false,
+        usesDAC: false,
+        usesPower: false,
+        usesWdt: false,
+        usesInterrupts: false,
+        usesPulse: false,
+        usesShift: false,
+        usesWifi: false,
+        usesWifiConnect: false,
+        usesWifiConnectBlocking: false,
+        usesWifiQuery: false,
+        usesWifiScan: false,
+        usesWifiConfig: false,
+        usesHttp: false,
+        usesBle: false,
+        usesPreferences: false,
+        usesRandom: false,
+        usesFS: false,
+        usesMdns: false,
+        usesMqtt: false,
+        usesOta: false,
+        usesTemp: false,
+        usesHwtimer: false,
+        usesCapacitive: false,
+        usesWorker: false,
+        usesChrono: false,
+        usesSet: false,
+        usesAlgorithm: false,
+        usesCstdio: false,
+        usesDigitalRead: false,
+        usesDisplay: false,
+        usesHalt: false,
     };
     // Analyze type aliases
     for (const typeAlias of program.typeAliases) {

package/dist/ir/render-expr.js

@@ -85,6 +85,17 @@ export function renderExprAsText(expr) {
         case "lambda":
             return `/* __lambda__ */`;
         case "method-call": {
+            // Structured-receiver path: when the method-call IR carries a receiverExpr
+            // (set by the safe.read().ok().fail() chain builder), render the receiver
+            // recursively so nested lambda args are NOT flattened into the callee
+            // string as /* __lambda__ */ placeholders. The flat callee path below
+            // destroys lambdas; this preserves them.
+            const receiverExpr = expr.receiverExpr;
+            const methodName = expr.methodName;
+            if (receiverExpr !== undefined && methodName !== undefined) {
+                const argsText = expr.args.map(a => renderExprAsText(a)).join(", ");
+                return `${renderExprAsText(receiverExpr)}.${methodName}(${argsText})`;
+            }
             const argsText = expr.args.map(a => renderExprAsText(a)).join(", ");
             return `${expr.callee}(${argsText})`;
         }

package/dist/ir/timing-validation.d.ts

@@ -1,7 +1,12 @@
 import type { ProgramIR } from '../api/index.js';
 import type { Diagnostic } from '../types.js';
+import type { PlatformStrategy } from '../api/shared/index.js';
 /**
  * Detect blocking delay() calls inside loop()'s body. Emits a warning for
  * each, explaining the cooperative-async alternative.
+ *
+ * On RTOS targets (ESP-IDF), timing.delay lowers to vTaskDelay which yields
+ * the CPU — it does NOT freeze the async queue or UI. Only delayMicroseconds
+ * (busy-wait) triggers the warning.
  */
-export declare function validateBlockingDelayInLoop(program: ProgramIR): Diagnostic[];
+export declare function validateBlockingDelayInLoop(program: ProgramIR, strategy?: PlatformStrategy): Diagnostic[];

package/dist/ir/timing-validation.js

@@ -12,20 +12,52 @@
 // g++ sees only an ordinary function. This validator flags blocking delays in
 // loop()'s direct body so the user can replace them with the cooperative
 // Async.sleep() / millis()-comparison pattern.
+//
+// IMPORTANT: on RTOS targets (ESP-IDF / FreeRTOS), delay() lowers to
+// vTaskDelay which YIELDS the CPU — it does not freeze other tasks, UI
+// rendering, or the async queue. Only delayMicroseconds (esp_rom_delay_us)
+// is a true busy-wait. So for RTOS targets, only delay_microseconds triggers
+// the warning; delay is safe.
 // ---------------------------------------------------------------------------
-/** Check a single statement for a blocking delay call or hal-op. */
-function isBlockingDelay(stmt) {
+import { hasLoadedFramework, getLoadedFramework } from '../framework-registry.js';
+/** Check a single statement for a blocking delay call or hal-op.
+ *  On RTOS targets, timing.delay (vTaskDelay) is NOT blocking — only
+ *  timing.delay_microseconds (esp_rom_delay_us) is. */
+function isBlockingDelay(stmt, isRtos) {
     const s = stmt;
-    // Direct call: delay(...) or delayMicroseconds(...)
+    // Derive the blocking delay call names from the loaded framework's
+    // ISR-unsafe table (delay, delayMicroseconds on Wiring-derived frameworks).
+    // Fall back to those two names when no framework is loaded.
+    const frameworkUnsafe = hasLoadedFramework()
+        ? getLoadedFramework().strategy.isrUnsafeOperations?.()
+        : undefined;
+    const delayNames = frameworkUnsafe
+        ? [...frameworkUnsafe.keys()].filter(k => k === 'delay' || k === 'delayMicroseconds')
+        : ['delay', 'delayMicroseconds'];
+    // Direct call: a blocking delay call by name.
     if (stmt.kind === 'call' && typeof s.callee === 'string') {
-        if (s.callee === 'delay' || s.callee === 'delayMicroseconds')
-            return true;
+        if (isRtos) {
+            // On RTOS targets, only delayMicroseconds is a busy-wait.
+            if (s.callee === 'delayMicroseconds')
+                return true;
+        }
+        else {
+            if (delayNames.includes(s.callee))
+                return true;
+        }
     }
     // Hal-op: after HAL resolution, delay() becomes timing.delay /
     // timing.delay_microseconds.
     if (stmt.kind === 'hal-op' && s.operation?.operation) {
-        if (s.operation.operation === 'timing.delay' || s.operation.operation === 'timing.delay_microseconds') {
-            return true;
+        if (isRtos) {
+            // On RTOS targets, only timing.delay_microseconds is blocking.
+            if (s.operation.operation === 'timing.delay_microseconds')
+                return true;
+        }
+        else {
+            if (s.operation.operation === 'timing.delay' || s.operation.operation === 'timing.delay_microseconds') {
+                return true;
+            }
         }
     }
     return false;
@@ -33,22 +65,37 @@ function isBlockingDelay(stmt) {
 /**
  * Detect blocking delay() calls inside loop()'s body. Emits a warning for
  * each, explaining the cooperative-async alternative.
+ *
+ * On RTOS targets (ESP-IDF), timing.delay lowers to vTaskDelay which yields
+ * the CPU — it does NOT freeze the async queue or UI. Only delayMicroseconds
+ * (busy-wait) triggers the warning.
  */
-export function validateBlockingDelayInLoop(program) {
+export function validateBlockingDelayInLoop(program, strategy) {
     const diagnostics = [];
+    // Detect RTOS targets where delay() yields rather than blocks.
+    // framework-esp32 uses FreeRTOS; vTaskDelay is a yielding delay.
+    const isRtos = strategy?.isRtosTarget?.() === true
+        || (hasLoadedFramework() && getLoadedFramework().strategy.isRtosTarget?.() === true);
     const loopFn = program.functions.find(fn => fn.originalName === 'loop');
     if (!loopFn || !loopFn.statements)
         return diagnostics;
     const visit = (stmts) => {
         for (const stmt of stmts) {
-            if (isBlockingDelay(stmt)) {
+            if (isBlockingDelay(stmt, isRtos)) {
                 const s = stmt;
+                const message = isRtos
+                    ? `Blocking delayMicroseconds() inside loop() is a busy-wait that wastes CPU cycles. ` +
+                        `On RTOS targets (ESP-IDF), prefer timing.delay() (vTaskDelay) which yields the CPU to other tasks.`
+                    : `Blocking delay() inside loop() freezes the async microtask queue and UI rendering ` +
+                        `for the delay duration. This causes display tearing and makes the sketch unresponsive.`;
+                const hint = isRtos
+                    ? `Replace delayMicroseconds with delay() if the timing permits, or accept the brief busy-wait if sub-millisecond precision is required.`
+                    : `Use the cooperative pattern instead: track elapsed time with millis() comparisons, ` +
+                        `or use Async.sleep(ms) / Async.yield() to let other tasks run between checks.`;
                 diagnostics.push({
                     severity: 'warning',
-                    message: `Blocking delay() inside loop() freezes the async microtask queue and UI rendering ` +
-                        `for the delay duration. This causes display tearing and makes the sketch unresponsive.`,
-                    hint: `Use the cooperative pattern instead: track elapsed time with millis() comparisons, ` +
-                        `or use Async.sleep(ms) / Async.yield() to let other tasks run between checks.`,
+                    message,
+                    hint,
                     line: stmt.sourceSpan?.startLine,
                     column: stmt.sourceSpan?.startColumn,
                     filePath: stmt.sourceSpan?.filePath,

package/dist/ir/transformers/call-statement.js

@@ -4,6 +4,7 @@ import { getCurrentIrTypeScope } from "../symbol-types.js";
 import { extractNodeComments, makeSourceSpan } from "../ast-node-utils.js";
 import { tryResolveHALMethod } from "./hal-call-resolver.js";
 import { tryResolveUICall, isSignalName, resolveUIModuleImport, recordPressBinding, uiPressBindings, resolveNodeIndex, resolveNodeTag, watchPinSpecs, recordWatchPin, recordClickHandler, clickHandlers, pushUnknownElementDiagnostic } from "./ui-call-resolver.js";
+import { hasSafetyHook, requireSafetyHook } from "../../safety-hook.js";
 import { lowerCallbackStatements, resolveCallbackArg, getCanvasAmbientCtx, getCanvasAmbientDiagnostics, getCanvasAmbientSourceText, } from "./ui-callback-lowering.js";
 import { rewriteCanvasCall } from "./canvas-lowering.js";
 import { callbackContextLabel, unsupportedStatementHint } from "./callback-context-registry.js";
@@ -127,6 +128,64 @@ function lowerPreludeCallback(cbArg, fileName, sourceText, diagnostics, label, p
         sourceSpan,
     };
 }
+/** Detect `safe.<method>(...)` calls in statement position and lower them to
+ *  a hal-op statement via the safety hook's resolveSemanticCall. Mirrors the
+ *  UI call resolver pattern. Returns null when:
+ *  - the safety engine is not loaded (hasSafetyHook() === false), or
+ *  - the call is not a `safe.<method>(...)` shape, or
+ *  - the hook declines to lower it (returns undefined).
+ *
+ *  Expression-position safe.* calls (e.g. `const r = safe.read(pin)`) are
+ *  handled separately in the variable-declaration transformer. */
+function tryResolveSafetyCallStatement(call, fileName, sourceText) {
+    if (!hasSafetyHook())
+        return null;
+    // Shape: safe.<method>(args...) — PropertyAccessExpression on identifier "safe".
+    if (!ts.isPropertyAccessExpression(call.expression))
+        return null;
+    if (!ts.isIdentifier(call.expression.expression))
+        return null;
+    if (call.expression.expression.text !== "safe")
+        return null;
+    const method = call.expression.name.text;
+    // Extract simple literal/identifier arg values; non-literal args are passed
+    // as their rendered text so the hook can decide. The hook consumes
+    // safe.read (pin), safe.write (pin, value), and safe.pinMode (pin, mode).
+    // For safe.write, the value may be a property access (r.value), arithmetic
+    // expression, or variable — rendered to its C++ text form.
+    const argValues = call.arguments.map((a) => {
+        if (ts.isNumericLiteral(a))
+            return Number(a.text);
+        if (ts.isStringLiteral(a))
+            return a.text;
+        if (a.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+        if (a.kind === ts.SyntaxKind.FalseKeyword)
+            return false;
+        if (ts.isIdentifier(a)) {
+            const name = a.text;
+            if (name === "INPUT")
+                return 0;
+            if (name === "OUTPUT")
+                return 1;
+            if (name === "INPUT_PULLUP")
+                return 2;
+            return name;
+        }
+        // Property access (e.g. r.value), arithmetic, or other expression:
+        // render to the C++ expression text so the op can emit it inline.
+        return a.getText();
+    });
+    const op = requireSafetyHook().resolveSemanticCall?.(`safe.${method}`, argValues);
+    if (!op)
+        return null;
+    return {
+        kind: "hal-op",
+        operation: op,
+        returns_value: false,
+        sourceSpan: makeSourceSpan(call, fileName, sourceText),
+    };
+}
 export function callToStatement(statementNode, call, fileName, sourceText, diagnostics, pointerVars = new Map()) {
     const comments = extractNodeComments(statementNode, sourceText);
     // ── setInterval/setTimeout arrow-callback hoisting (BEFORE HAL) ────────
@@ -448,6 +507,52 @@ export function callToStatement(statementNode, call, fileName, sourceText, diagn
     const uiResolved = tryResolveUICall(call, fileName, sourceText, diagnostics);
     if (uiResolved)
         return uiResolved;
+    // ---- safe.* — @typecad/safety authoring calls (statement position) ---
+    // Handles statement-position safe.* calls like safe.pinMode(pin, mode).
+    // The expression-position form (const r = safe.read(pin)) is handled in
+    // the variable-declaration transformer. Both produce hal-op IR nodes that
+    // routeHALOp() later dispatches to the safety hook.
+    const safetyResolved = tryResolveSafetyCallStatement(call, fileName, sourceText);
+    if (safetyResolved)
+        return safetyResolved;
+    // ---- safe.read/safe.write chained with .ok/.fail/.fault/.always (statement) ----
+    // A statement like `safe.read(pin).ok(r => {...}).fail(r => {...})` is a
+    // method chain on a safe.* result. The terminal safe.* interceptor above
+    // returns null for it (the shape isn't `safe.<method>` — it's `.fail` on a
+    // chain). Delegate to expressionToIR, which has tryResolveSafetyChain to
+    // build the structured nested method-call IR that preserves lambda args,
+    // then render to text for a __RAW_STMT__ statement.
+    if (hasSafetyHook() && ts.isPropertyAccessExpression(call.expression)) {
+        let walk = call;
+        let isSafeChain = false;
+        while (ts.isCallExpression(walk) && ts.isPropertyAccessExpression(walk.expression)) {
+            walk = walk.expression.expression;
+            if (ts.isCallExpression(walk) &&
+                ts.isPropertyAccessExpression(walk.expression) &&
+                ts.isIdentifier(walk.expression.expression) &&
+                walk.expression.expression.text === "safe") {
+                isSafeChain = true;
+                break;
+            }
+        }
+        if (isSafeChain) {
+            // Build the structured chain IR via expressionToIR (the chain resolver
+            // produces nested method-call nodes with receiverExpr so lambdas survive).
+            // Carry it as the arg of a __EXPR_STMT__ call statement; the statement
+            // renderer renders it via the EMIT-TIME expression renderer (which has
+            // renderLambda for inline [&](){...} lambdas), NOT via the build-time
+            // renderExprAsText (which flattens lambdas to /* __lambda__ */).
+            const exprIR = expressionToIR(call, sourceText, diagnostics, pointerVars);
+            return {
+                kind: "call",
+                sourceSpan: makeSourceSpan(call, fileName, sourceText),
+                leadingComments: comments.leadingComments,
+                trailingComments: comments.trailingComments,
+                callee: "__EXPR_STMT__",
+                args: [exprIR],
+            };
+        }
+    }
     // Handle super() calls in constructors - transform to super_call IR for class emitter
     if (call.expression.kind === ts.SyntaxKind.SuperKeyword) {
         return {