@typecad/cuttlefish 1.0.0-alpha.3 → 1.0.0-alpha.7

package/dist/ir/timer0-pwm-timing-conflict.js

@@ -43,7 +43,7 @@ function getTimer0PwmPins(boardConstants) {
     }
     return timer0Pins;
 }
-export function validateTimer0PWMTimingConflict(usage, boardConstants) {
+export function validateTimer0PWMTimingConflict(usage, boardConstants, filePath) {
     if (!usage.timer0 || usage.pwmPinsUsed.size === 0) {
         return [];
     }
@@ -65,6 +65,7 @@ export function validateTimer0PWMTimingConflict(usage, boardConstants) {
     return [{
             severity: 'info',
             code: 'timer0-pwm-timing-conflict',
+            filePath,
             source: 'timer0-pwm-timing-conflict',
             message: `${pinReferences.join(', ')} use Timer0 PWM${boardLabel}, and your program also relies on Timer0-backed timing APIs such as delay(), millis(), or micros(). This coupling is common on AVR boards, so prefer non-Timer0 PWM pins when you want PWM behavior isolated from core timing.`,
         }];

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,43 @@
 // 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(...)
     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 (s.callee === 'delay' || s.callee === 'delayMicroseconds')
+                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,24 +56,40 @@ 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,
                     code: 'blocking-delay-in-loop',
                     source: 'timing-validation',
                 });

package/dist/ir/transformers/expressions.js

@@ -16,6 +16,17 @@ export function expressionStatementToIR(statement, fileName, sourceText, diagnos
         if (callStmt && callStmt.kind === "call") {
             return { ...callStmt, isAwaited: true };
         }
+        // Awaited network HAL ops (WiFi.connect / WiFi.untilConnected / Http.send
+        // / ...) resolve to hal-op statements, which would otherwise lower to the
+        // BLOCKING shim call even inside an async state machine. Rewrite them to
+        // an awaited __WIFI_WAIT__/__HTTP_WAIT__ marker call carrying the original
+        // op; the async state-machine generator turns it into a start + poll state
+        // pair, and the statement renderer falls back to the blocking form when
+        // the marker is rendered outside a state machine (top-level await, awaits
+        // nested in unsupported positions).
+        const netMarker = awaitedNetMarker(callStmt);
+        if (netMarker)
+            return netMarker;
         return callStmt;
     }
     // ── Register bit-field write ────────────────────────────────────────
@@ -404,3 +415,50 @@ export function expressionStatementToIR(statement, fileName, sourceText, diagnos
     }
     return undefined;
 }
+/** HAL ops with a start/poll split available in the async state machine
+ *  (see async-state-machine.ts netWaitInfo — keep the two in sync).
+ *  timing.delay is included because `delay()` from @typecad/hal resolves to a
+ *  hal-op, dropping the isAwaited flag the state machine keys on. */
+const AWAITABLE_HAL_OPS = new Set([
+    "timing.delay",
+    "wifi.connect",
+    "wifi.wait_connected",
+    "wifi.wait_disconnected",
+    "wifi.scan",
+    "http.send",
+    "ble.until_connected",
+]);
+/**
+ * Rewrite an awaited hal-op statement (or a block whose LAST statement is
+ * one — chained HAL calls resolve to blocks of hal-ops) into an awaited
+ * `__WIFI_WAIT__` / `__HTTP_WAIT__` / `__HAL_WAIT__` marker call carrying the
+ * original op as a hal-expr argument. Returns undefined when the statement is
+ * not an awaitable HAL op.
+ */
+function awaitedNetMarker(stmt) {
+    if (!stmt)
+        return undefined;
+    if (stmt.kind === "hal-op" && AWAITABLE_HAL_OPS.has(stmt.operation.operation)) {
+        const opName = stmt.operation.operation;
+        const callee = opName.startsWith("http.") ? "__HTTP_WAIT__"
+            : opName.startsWith("wifi.") ? "__WIFI_WAIT__"
+                : opName.startsWith("ble.") ? "__BLE_WAIT__"
+                    : "__HAL_WAIT__";
+        return {
+            kind: "call",
+            sourceSpan: stmt.sourceSpan,
+            leadingComments: stmt.leadingComments,
+            trailingComments: stmt.trailingComments,
+            callee,
+            args: [{ kind: "hal-expr", operation: stmt.operation }],
+            isAwaited: true,
+        };
+    }
+    if (stmt.kind === "block" && stmt.body.length > 0) {
+        const last = awaitedNetMarker(stmt.body[stmt.body.length - 1]);
+        if (last) {
+            return { ...stmt, body: [...stmt.body.slice(0, -1), last] };
+        }
+    }
+    return undefined;
+}

package/dist/ir/transformers/hal-emit-helpers.js

@@ -27,7 +27,7 @@ export function collectChainedHALEmits(expr, sourceText, diagnostics, pointerVar
             }
         }
         // Continue recursion to collect deeper chain levels
-        if (ts.isCallExpression(innerReceiver) && ts.isPropertyAccessExpression(innerReceiver)) {
+        if (ts.isCallExpression(innerReceiver) && ts.isPropertyAccessExpression(innerReceiver.expression)) {
             collectChainedHALEmits(innerReceiver, sourceText, diagnostics, pointerVars, emitLines, halOps);
         }
     }

package/dist/ir/transformers/variables.js

@@ -7,13 +7,17 @@ import { getCurrentIrTypeScope, setScopeLocalType } from "../symbol-types.js";
 import { renderExprAsText } from "../render-expr.js";
 import { expressionToIR } from "../expression-to-ir.js";
 import { buildInlineForLoop } from "./array-methods.js";
-import { isKnownHALClass, getCtorIncludes, registerFloatVariable, resolveHALReceiver, isHALSingleton, } from "../hal-resolver.js";
+import { isKnownHALClass, getCtorIncludes, getHALCtorFieldMap, registerFloatVariable, resolveHALReceiver, isHALSingleton, } from "../hal-resolver.js";
+import { httpFactoryVerb, httpUrlArgText } from "../hal/hal-parser.js";
 import { resolveHALCallForVarInit } from "./hal-call-resolver.js";
 import { recordSignal } from "./ui-call-resolver.js";
 function replaceHalReadBufferPlaceholder(op, varName) {
     if (op.operation === "i2c.read_buffer" && op.buffer === "__HAL_READ_BUF__") {
         return { ...op, buffer: varName };
     }
+    if (op.operation === "spi.read_buffer" && op.buffer === "__HAL_READ_BUF__") {
+        return { ...op, buffer: varName };
+    }
     return op;
 }
 export function assignmentOperatorToString(kind) {
@@ -405,9 +409,26 @@ export function variableStatementToIR(statement, fileName, sourceText, diagnosti
                             }
                         }
                     }
+                    // new HttpRequest(method, url) — positional ctor fields. The URL is
+                    // stored as C++ expression text (quoted literal or identifier).
+                    if (className === "HttpRequest" && ctorArgs && ctorArgs.length >= 2) {
+                        const methodArg = ctorArgs[0];
+                        if (ts.isStringLiteral(methodArg))
+                            fieldValues.set("_method", methodArg.text.toUpperCase());
+                        const urlText = httpUrlArgText(ctorArgs[1]);
+                        if (urlText)
+                            fieldValues.set("_url", urlText);
+                    }
                     if (ctorArgs) {
+                        // Resolve a Pin-identifier ctor arg to its _pin number, for any HAL
+                        // class whose first constructor field is _pin (Pin itself, plus
+                        // pin-bearing wrappers like RmtChannel). Mirrors the Pin branch
+                        // above but keyed off the class's registered ctor field map so new
+                        // pin-keyed classes work without a per-class branch here.
+                        const ctorFieldMap = getHALCtorFieldMap(className);
+                        const firstFieldIsPin = ctorFieldMap && Array.from(ctorFieldMap.keys())[0] === "_pin";
                         for (const arg of ctorArgs) {
-                            if (ts.isIdentifier(arg) && className === "Pin") {
+                            if (ts.isIdentifier(arg) && (className === "Pin" || firstFieldIsPin)) {
                                 const existing = halInstances.get(arg.text);
                                 if (existing && existing.fieldValues.has("_pin")) {
                                     fieldValues.set("_pin", existing.fieldValues.get("_pin"));
@@ -430,6 +451,45 @@ export function variableStatementToIR(statement, fileName, sourceText, diagnosti
                 const isSingletonReceiver = ts.isIdentifier(receiver) && isHALSingleton(receiver.text);
                 if (result && (!isOwnershipMethod || isSingletonReceiver)) {
                     const isHalOpReturn = result.returnValue === "__hal_op_return__";
+                    // A __TYPED_ARRAY__ return comes ONLY from a HAL method body
+                    // (`return new Uint8Array(count)` in e.g. I2CDevice.readBytes /
+                    // SPIDevice.readRegister). The method's side-effect HAL ops (the
+                    // i2c.read_buffer / spi.read_buffer fill loops) write INTO this buffer
+                    // via the __HAL_READ_BUF__ placeholder (rewritten to `varName`). So the
+                    // buffer var_decl MUST precede the fill ops in emitted order — at top
+                    // level the var_decl is hoisted to file scope which masks this, but a
+                    // function-local `const data = ...readBytes()` would otherwise emit the
+                    // fill loop referencing `data` before its declaration. Detect the typed
+                    // array up front so we can emit its declaration first.
+                    const isTypedArrayReturn = typeof result.returnValue === "string" && result.returnValue.startsWith("__TYPED_ARRAY__:");
+                    if (isTypedArrayReturn && typeof result.returnValue === "string") {
+                        const parts = result.returnValue.split(":");
+                        const elementType = parts[1];
+                        const size = parts[2];
+                        // Force non-const storage (the buffer is written by the fill op) and
+                        // synthesize a zero-init array initializer so the var_decl renderer
+                        // emits `T data[] = { 0, 0, ... }` — a bare `const T data[N];` that
+                        // is later written would fail to compile (assignment to const).
+                        // Mirrors plain `new Uint8Array(N)` (expression-to-ir.ts).
+                        const count = parseInt(size, 10);
+                        const initElements = !isNaN(count) && count > 0 && count <= 256
+                            ? Array(count).fill(0).map(() => ({ kind: "number", value: 0 }))
+                            : [];
+                        lowered.push({
+                            kind: "var_decl",
+                            sourceSpan: makeSourceSpan(declaration, fileName, sourceText),
+                            leadingComments: commentsAssigned ? [] : statementComments.leadingComments,
+                            trailingComments: [],
+                            name: varName,
+                            storage: "let",
+                            cppType: `${elementType}[${size}]`,
+                            initializer: initElements.length > 0
+                                ? { kind: "array", elements: initElements, elementType }
+                                : undefined,
+                        });
+                        activeCArrayVars.add(varName);
+                        commentsAssigned = true;
+                    }
                     if (result.halOps && result.halOps.length > 0) {
                         const sideEffectOps = isHalOpReturn ? result.halOps.slice(0, -1) : result.halOps;
                         const halStmts = sideEffectOps.map(op => ({
@@ -474,6 +534,19 @@ export function variableStatementToIR(statement, fileName, sourceText, diagnosti
                                 }
                             }
                         }
+                        // For Http factory calls (const req = Http.get(url)), record the
+                        // HTTP verb + URL so req.send() can resolve this._method/this._url.
+                        if (result.returnClassName === "HttpRequest") {
+                            const verb = httpFactoryVerb(init.expression.name.text);
+                            if (verb)
+                                fieldValues.set("_method", verb);
+                            const urlArg = init.arguments?.[0];
+                            if (urlArg) {
+                                const urlText = httpUrlArgText(urlArg);
+                                if (urlText)
+                                    fieldValues.set("_url", urlText);
+                            }
+                        }
                         halInstances.set(varName, {
                             className: result.returnClassName,
                             fieldValues,
@@ -527,24 +600,18 @@ export function variableStatementToIR(statement, fileName, sourceText, diagnosti
                             if (/\b\d+\.\d+\b/.test(result.returnValue)) {
                                 registerFloatVariable(varName);
                             }
+                            // __TYPED_ARRAY__ returns are handled above (declared BEFORE the
+                            // fill ops). Everything else is a scalar/value return captured
+                            // after the side-effect ops.
                             const isTypedArray = result.returnValue.startsWith("__TYPED_ARRAY__:");
-                            if (isTypedArray) {
-                                const parts = result.returnValue.split(":");
-                                const elementType = parts[1];
-                                const size = parts[2];
-                                lowered.push({
-                                    kind: "var_decl",
-                                    sourceSpan: makeSourceSpan(declaration, fileName, sourceText),
-                                    leadingComments: commentsAssigned ? [] : statementComments.leadingComments,
-                                    trailingComments: [],
-                                    name: varName,
-                                    storage,
-                                    cppType: `${elementType}[${size}]`,
-                                    initializer: undefined,
-                                });
-                                activeCArrayVars.add(varName);
-                            }
-                            else {
+                            // A factory returning a compile-time HAL instance (e.g.
+                            // `const req = Http.get(url)` → returnValue `new HttpRequest(...)`)
+                            // is fully tracked via halInstances — every later method call on
+                            // the variable resolves at compile time. Emitting the raw
+                            // `new HttpRequest(...)` would reference a class that doesn't
+                            // exist in the C++ output.
+                            const isHalInstanceReturn = !!result.returnClassName && /^new\s/.test(result.returnValue.trim());
+                            if (!isTypedArray && !isHalInstanceReturn) {
                                 lowered.push({
                                     kind: "var_decl",
                                     sourceSpan: makeSourceSpan(declaration, fileName, sourceText),

package/dist/ir/try-catch-validation.js

@@ -39,6 +39,7 @@ export function validateTryCatch(program, boardConstants, strategy) {
                 hint: `function readSensor(): number | null {\n  const data = sensor.read();\n  if (!data) return null;  // error path\n  return data.value;       // success path\n}`,
                 line: stmt.sourceSpan?.startLine,
                 column: stmt.sourceSpan?.startColumn,
+                filePath: stmt.sourceSpan?.filePath,
                 source: 'try-catch-validation',
             });
             // Still recurse into nested blocks to find other try/catch
@@ -57,6 +58,7 @@ export function validateTryCatch(program, boardConstants, strategy) {
                 hint: `return null;  // or return an error code`,
                 line: stmt.sourceSpan?.startLine,
                 column: stmt.sourceSpan?.startColumn,
+                filePath: stmt.sourceSpan?.filePath,
                 source: 'try-catch-validation',
             });
             return;

package/dist/ir/type-resolution.js

@@ -33,9 +33,9 @@ const PIN_INTERFACE_TYPE_NAMES = new Set([
     "PinMode", "InterruptMode",
 ]);
 const BUS_INTERFACE_TYPE_NAMES = new Set([
-    "II2CBus", "ISPIBus", "ISerialPort", "IUART",
+    "II2CBus", "ISPIBus", "ISerialPort",
     "I2CConfig", "SPIConfig", "UARTConfig",
-    "I2CAddress", "UARTStatus", "SPITransferOptions",
+    "I2CAddress", "SPITransferOptions",
 ]);
 const STRATEGY_TYPE_NAMES = new Set([
     "NativeStrategy", "ArduinoStrategy", "BoardStrategy",

package/dist/ir/unit-suspicion-validation.js

@@ -130,7 +130,7 @@ function checkSPIFrequency(value) {
  * baud rate used as SPI freq, etc.). Only literal numbers are checked —
  * expressions/variables are opaque to this validator.
  */
-function checkConfigValue(kind, rawValue, diagnostics) {
+function checkConfigValue(kind, rawValue, filePath, diagnostics) {
     // HAL ops carry resolved numeric values as `number` when the source arg was
     // a literal, or as `string` expression text otherwise. Only check numbers.
     const value = typeof rawValue === 'number' ? rawValue
@@ -146,6 +146,7 @@ function checkConfigValue(kind, rawValue, diagnostics) {
             severity: 'warning',
             message,
             code: 'unit-suspicion',
+            filePath,
             source: 'unit-suspicion-validation',
         });
     }
@@ -160,15 +161,16 @@ function scanStatement(stmt, diagnostics) {
     if (!stmt || typeof stmt !== 'object')
         return;
     const s = stmt;
+    const filePath = s.sourceSpan?.filePath;
     // HAL-op statements carry structured operations with resolved values.
     if (stmt.kind === 'hal-op' && s.operation) {
         const op = s.operation;
         switch (op.operation) {
             case 'i2c.set_clock':
-                checkConfigValue('i2c', op.hz, diagnostics);
+                checkConfigValue('i2c', op.hz, filePath, diagnostics);
                 break;
             case 'uart.begin':
-                checkConfigValue('baud', op.baud, diagnostics);
+                checkConfigValue('baud', op.baud, filePath, diagnostics);
                 break;
             // SPI frequency flows through SPISettings construction text, which the
             // HAL op carries as a string — the numeric extraction in
@@ -178,7 +180,7 @@ function scanStatement(stmt, diagnostics) {
                     // SPISettings({freq}, ...) — try to extract the leading frequency.
                     const m = op.settings.match(/^\s*(\d+)/);
                     if (m)
-                        checkConfigValue('spi', parseInt(m[1], 10), diagnostics);
+                        checkConfigValue('spi', parseInt(m[1], 10), filePath, diagnostics);
                 }
                 break;
         }
@@ -188,18 +190,18 @@ function scanStatement(stmt, diagnostics) {
     if (stmt.kind === 'call' && typeof s.callee === 'string' && Array.isArray(s.args)) {
         const method = s.callee.split('.').pop() ?? s.callee;
         if (method === 'setClock' && s.args.length >= 2) {
-            checkConfigValue('i2c', extractNumericValue(s.args[1]), diagnostics);
+            checkConfigValue('i2c', extractNumericValue(s.args[1]), filePath, diagnostics);
         }
         else if (method === 'setBaudRate' || method === 'begin') {
             // Serial.begin(baud) / setBaudRate(baud) — last numeric arg is the baud.
             for (const arg of s.args) {
                 const v = extractNumericValue(arg);
                 if (v !== undefined)
-                    checkConfigValue('baud', v, diagnostics);
+                    checkConfigValue('baud', v, filePath, diagnostics);
             }
         }
         else if (method === 'setFrequency' && s.args.length >= 2) {
-            checkConfigValue('spi', extractNumericValue(s.args[1]), diagnostics);
+            checkConfigValue('spi', extractNumericValue(s.args[1]), filePath, diagnostics);
         }
     }
     // Recurse into nested statements

package/dist/ir/validation-orchestrator.js

@@ -18,18 +18,19 @@ import { validateBlockingDelayInLoop } from "./timing-validation.js";
 import { validateUnitSuspicion } from "./unit-suspicion-validation.js";
 import { validateOwnership } from "./ownership-analysis.js";
 import { validatePinCapabilities } from "./pin-capability-validation.js";
+import { validateNetworkUsage } from "./network-validation.js";
 export function runProgramValidations(program, strategy) {
     const resolvedStrategy = strategy ?? (hasLoadedFramework() ? getLoadedFramework().strategy : resolveStrategy('generic'));
     const diagnostics = [];
     const peripheralUsage = program.peripheralUsage ?? createEmptyPeripheralUsage();
     diagnostics.push(...validatePinCapabilities(program));
-    diagnostics.push(...validatePeripherals(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validateUnsafePins(peripheralUsage, program.boardConstants));
+    diagnostics.push(...validatePeripherals(peripheralUsage, program.boardConstants, program.fileName));
+    diagnostics.push(...validateUnsafePins(peripheralUsage, program.boardConstants, program.fileName));
     diagnostics.push(...analyzeResources(program, resolvedStrategy));
-    diagnostics.push(...validatePinAliasConflicts(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validatePWMTimerSharing(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validateTimer0PWMTimingConflict(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validatePulldownSupport(peripheralUsage, program.boardConstants));
+    diagnostics.push(...validatePinAliasConflicts(peripheralUsage, program.boardConstants, program.fileName));
+    diagnostics.push(...validatePWMTimerSharing(peripheralUsage, program.boardConstants, program.fileName));
+    diagnostics.push(...validateTimer0PWMTimingConflict(peripheralUsage, program.boardConstants, program.fileName));
+    diagnostics.push(...validatePulldownSupport(peripheralUsage, program.boardConstants, program.fileName));
     diagnostics.push(...analyzeInterruptSafety(program, peripheralUsage));
     inferVolatileForIsrSharedVars(program, diagnostics);
     detectReentrancyRisk(program, diagnostics);
@@ -40,6 +41,7 @@ export function runProgramValidations(program, strategy) {
     diagnostics.push(...validateOwnership(program));
     diagnostics.push(...validateTryCatch(program, program.boardConstants, resolvedStrategy));
     diagnostics.push(...validateMemoryBudget(program, program.boardConstants));
-    diagnostics.push(...validateBlockingDelayInLoop(program));
+    diagnostics.push(...validateBlockingDelayInLoop(program, resolvedStrategy));
+    diagnostics.push(...validateNetworkUsage(program));
     return diagnostics;
 }

package/dist/libdef/c-to-decl.d.ts

@@ -0,0 +1,27 @@
+/**
+ * C-header to TypeScript declaration generator.
+ *
+ * Complements cpp-to-decl.ts (which is class-focused). ESP-IDF components
+ * are mostly C: free functions, opaque handles, typedef'd enums and structs.
+ *
+ * EMISSION POLICY — names match the C header 1-to-1.
+ *
+ *   esp_err_t esp_wifi_init(const wifi_config_t *config);
+ *
+ * becomes
+ *
+ *   export declare function esp_wifi_init(config: number): esp_err_t;
+ *
+ * not `esp_wifi.init(...)`. ESP-IDF examples call `esp_wifi_init`, never
+ * `esp_wifi.init`; the dotted form has no C++ representation (there is no
+ * `esp_wifi` object or namespace in the real header) and would not link.
+ * Mirroring the C names verbatim means the transpiler lowers TS calls
+ * directly to valid C with zero translation.
+ *
+ * Spec: docs/superpowers/specs/2026-07-19-demo-wifi-design.md
+ */
+/**
+ * Top-level entry: read a header file, write `<header>.d.ts` alongside it.
+ * Returns the output path, or null if no declarations could be extracted.
+ */
+export declare function generateCDecl(filePath: string, outputPath?: string): string | null;