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

package/dist/ir/hal/hal-plugins.js

@@ -1,7 +1,8 @@
 import ts from "typescript";
-import { getCurrentBoardConstants, halInstances } from "../build-ir-state.js";
+import { getCurrentBoardConstants, halInstances, getContext } from "../build-ir-state.js";
 import { resolveExpressionText } from "./hal-emitter.js";
 import { renderExprAsText } from "../render-expr.js";
+import { hasSafetyHook, requireSafetyHook } from "../../safety-hook.js";
 /**
  * Split a comma-joined argument list back into individual arguments, respecting
  * nesting (parens/brackets/braces) and string literals so a comma inside one of
@@ -303,6 +304,17 @@ export function tryResolveCompoundSemanticReturn(expr, instance, paramNames, cal
  * Returns the HALOpIR if the function name is recognized, or null.
  */
 export function tryResolveSemanticCall(fnName, args, instance, paramNames, callArgTexts, paramDefaults, callArgs) {
+    // ── Safety (@typecad/safety — safe.read) ────────────────────────────────
+    // The safety package owns lowering for `safe.*` callees (v2: only safe.read;
+    // safe.pinMode was removed — mode config is the HAL's job via Pin.asInput()
+    // etc.). Check the hook before the switch so safety calls never fall
+    // through to GPIO/etc. hasSafetyHook() guards the call site (no-op when
+    // @typecad/safety absent).
+    if (hasSafetyHook()) {
+        const op = requireSafetyHook().resolveSemanticCall?.(fnName, callArgs ?? []);
+        if (op)
+            return op;
+    }
     // Extract MCU port name from instance (set by Pin.fromPort())
     const port = portFromInstance(instance);
     switch (fnName) {
@@ -774,7 +786,18 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
             return { operation: "ble.add_service", uuid: quoteNonIdentifier(uuid) };
         }
         case "bleAddChar": {
-            const index = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            // The characteristic index is assigned HERE from a per-file counter, not
+            // resolved from `this._charCount`. resolveHALReceiver re-resolves the
+            // receiver (Ble.server(name)) freshly for each chain level when emitting,
+            // so a value stamped onto the instance field in the resolver would be
+            // dropped — leaving every characteristic on slot 0, clobbering the
+            // previous on_read/on_write handler. Consuming the counter at the single
+            // emit site (this plugin, called once per characteristic in declaration
+            // order) makes indices sequential (0,1,2,…) and stable. The counter is
+            // per-file (reset in resetHALResolver). onRead/onWrite/onConnect don't
+            // need a compile-time index — the C++ shim keys them off
+            // __tc_ble.current_char, which __tc_ble_add_char sets at runtime from
+            // this index.
             const uuid = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
             const type = resolveSemanticArg(args, 2, instance, paramNames, callArgTexts, paramDefaults);
             const perms = resolveNumericOrExpression(args, 3, instance, paramNames, callArgTexts, paramDefaults);
@@ -792,7 +815,7 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
             const resolvedPerms = resolveBlePermExpr(perms);
             return {
                 operation: "ble.add_char",
-                index: index ?? 0,
+                index: getContext().bleCharCounter++,
                 uuid: quoteNonIdentifier(uuid),
                 type: resolvedType,
                 perms: resolvedPerms,
@@ -944,6 +967,144 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
                 return null;
             return { operation: "preferences.get_string", key: quoteNonIdentifier(key), defaultValue: quoteNonIdentifier(def) };
         }
+        // ── FS (filesystem) ──
+        case "fsBegin":
+            return { operation: "fs.begin" };
+        case "fsReadText": {
+            const path = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (path === null)
+                return null;
+            return { operation: "fs.read_text", path };
+        }
+        case "fsWriteText": {
+            const path = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const content = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (path === null || content === null)
+                return null;
+            return { operation: "fs.write_text", path, content };
+        }
+        case "fsExists": {
+            const path = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (path === null)
+                return null;
+            return { operation: "fs.exists", path };
+        }
+        case "fsRemove": {
+            const path = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (path === null)
+                return null;
+            return { operation: "fs.remove", path };
+        }
+        // ── mDNS ──
+        case "mdnsStart": {
+            const hostname = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (hostname === null)
+                return null;
+            return { operation: "mdns.start", hostname };
+        }
+        case "mdnsSetHostname": {
+            const name = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (name === null)
+                return null;
+            return { operation: "mdns.set_hostname", name };
+        }
+        case "mdnsAddService": {
+            const instanceName = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const proto = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            const port = resolveNumericOrExpression(args, 2, instance, paramNames, callArgTexts, paramDefaults);
+            if (instanceName === null || proto === null || port === null)
+                return null;
+            return { operation: "mdns.add_service", instance: instanceName, proto, port };
+        }
+        case "mdnsAnnounce":
+            return { operation: "mdns.announce" };
+        case "mdnsStop":
+            return { operation: "mdns.stop" };
+        // ── MQTT ──
+        case "mqttConnect": {
+            const brokerUri = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const clientId = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (brokerUri === null || clientId === null)
+                return null;
+            return { operation: "mqtt.connect", brokerUri, clientId };
+        }
+        case "mqttOnMessage": {
+            const handler = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (handler === null)
+                return null;
+            return { operation: "mqtt.on_message", handler };
+        }
+        case "mqttSubscribe": {
+            const topic = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (topic === null)
+                return null;
+            return { operation: "mqtt.subscribe", topic };
+        }
+        case "mqttPublish": {
+            const topic = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const data = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (topic === null || data === null)
+                return null;
+            return { operation: "mqtt.publish", topic, data };
+        }
+        case "mqttConnected":
+            return { operation: "mqtt.connected" };
+        case "mqttDisconnect":
+            return { operation: "mqtt.disconnect" };
+        // ── OTA ──
+        case "otaFromUrl": {
+            const url = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (url === null)
+                return null;
+            return { operation: "ota.from_url", url };
+        }
+        case "otaBegin":
+            return { operation: "ota.begin" };
+        case "otaWrite": {
+            const chunk = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (chunk === null)
+                return null;
+            return { operation: "ota.write", chunk };
+        }
+        case "otaApply":
+            return { operation: "ota.apply" };
+        // ── Temperature (die temp) ──
+        case "tempRead":
+            return { operation: "temp.read" };
+        // ── Hardware timer (GPTimer) ──
+        case "hwtimerSetFrequency": {
+            const inst = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const hz = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (inst === null || hz === null)
+                return null;
+            return { operation: "hwtimer.set_frequency", instance: inst, hz };
+        }
+        case "hwtimerOnOverflow": {
+            const inst = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const handler = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (inst === null || handler === null)
+                return null;
+            return { operation: "hwtimer.on_overflow", instance: inst, handler };
+        }
+        case "hwtimerStart": {
+            const inst = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (inst === null)
+                return null;
+            return { operation: "hwtimer.start", instance: inst };
+        }
+        case "hwtimerStop": {
+            const inst = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (inst === null)
+                return null;
+            return { operation: "hwtimer.stop", instance: inst };
+        }
+        // ── Capacitive touch pins ──
+        case "capacitiveRead": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null)
+                return null;
+            return { operation: "capacitive.read", port, pin };
+        }
         // ── Interrupts ──
         case "interruptAttach": {
             const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);

package/dist/ir/identifier-collector.js

@@ -423,6 +423,22 @@ function collectHALOpIdentifiers(op) {
             // handler is a resolved C++ function name (e.g. "myIsr" or a placeholder)
             identifiers.add(op.handler);
             break;
+        case "mqtt.on_message":
+            // handler is the user's onMessage callback name (callback() resolves it to
+            // a string). Without this the tree-shaker drops the function declaration —
+            // the mqtt.on_message op only carries the name, so the function has no
+            // other reference and looks unreachable. Same shape as interrupt.attach.
+            identifiers.add(op.handler);
+            break;
+        case "wifi.on_event":
+            identifiers.add(op.handler);
+            break;
+        case "ble.on_read":
+        case "ble.on_write":
+        case "ble.on_connect":
+        case "ble.on_disconnect":
+            identifiers.add(op.handler);
+            break;
         case "raw": {
             // Raw C++ code may reference user-defined identifiers
             const matches = op.code.match(/[A-Za-z_][A-Za-z0-9_]*/g);
@@ -435,11 +451,12 @@ function collectHALOpIdentifiers(op) {
         }
         // Other HAL ops have only numeric/literal fields — no identifier references
     }
-    // wifi.* / http.* ops carry resolved C++ expression texts in their string
-    // fields (e.g. wifi.connect ssid: `WIFI_SSID` — a top-level const, or a
-    // quoted literal). Scan every string field for identifiers so referenced
+    // wifi.* / http.* / mqtt.* ops carry resolved C++ expression texts in their
+    // string fields (e.g. wifi.connect ssid: `WIFI_SSID` — a top-level const, or
+    // a quoted literal). Scan every string field for identifiers so referenced
     // globals survive tree-shaking; quoted literals are skipped.
-    if (op.operation.startsWith("wifi.") || op.operation.startsWith("http.")) {
+    if (op.operation.startsWith("wifi.") || op.operation.startsWith("http.")
+        || op.operation.startsWith("mqtt.")) {
         for (const value of Object.values(op)) {
             if (typeof value !== "string" || value === op.operation)
                 continue;

package/dist/ir/interrupt-analysis.d.ts

@@ -1,4 +1,4 @@
-import type { ProgramIR } from '../api/index.js';
+import type { ProgramIR, StatementIR } from '../api/index.js';
 import type { PeripheralUsage } from './peripheral-usage.js';
 import type { Diagnostic } from '../types.js';
 export { walkNestedStatements as scanNestedStatements } from './utils/walk-ir.js';
@@ -24,6 +24,10 @@ export interface InterruptHandlerInfo {
  * @returns Array of diagnostics for interrupt-related issues
  */
 export declare function analyzeInterruptSafety(program: ProgramIR, usage: PeripheralUsage, isrUnsafeOps?: Map<string, IsrUnsafeOp>): Diagnostic[];
+/** Collect variable names assigned (written) within a statement body. */
+export declare function collectAssignedNames(stmts: readonly StatementIR[], names: Set<string>): void;
+/** Collect variable names read (referenced) within a statement body. */
+export declare function collectReadNames(stmts: readonly StatementIR[], names: Set<string>): void;
 /**
  * Infer `volatile` for global variables shared between ISR callbacks and main
  * code. Mutates the IR (sets isVolatile=true on qualifying var_decls) and

package/dist/ir/interrupt-analysis.js

@@ -7,21 +7,13 @@
 import { walkNestedStatements, walkExpressionsInExpression } from './utils/walk-ir.js';
 export { walkNestedStatements as scanNestedStatements } from './utils/walk-ir.js';
 /**
- * Default ISR-unsafe operations used when no platform-specific map is provided.
- * Platforms should supply their own list via PlatformStrategy.isrUnsafeOperations().
+ * Fallback ISR-unsafe operations used when no platform-specific map is provided.
+ * Empty by design — the Wiring-derived specifics (delay, Serial.*, I2C*, SPI*)
+ * live in ArduinoStrategy.isrUnsafeOperations(). A generic target has no known
+ * ISR-unsafe surface. The orchestrator passes the loaded framework's map; this
+ * default only applies when none is supplied.
  */
-const DEFAULT_ISR_UNSAFE_OPERATIONS = new Map([
-    ['delay', { reason: 'delay() blocks the CPU and should not be used in interrupt context', severity: 'warning' }],
-    ['delayMicroseconds', { reason: 'delayMicroseconds() blocks and should be avoided in ISRs', severity: 'warning' }],
-    ['Serial.print', { reason: 'Serial.print() may not work correctly in interrupt context', severity: 'info' }],
-    ['Serial.println', { reason: 'Serial.println() may not work correctly in interrupt context', severity: 'info' }],
-    ['Serial.write', { reason: 'Serial.write() may not work correctly in interrupt context', severity: 'info' }],
-    ['Serial.read', { reason: 'Serial.read() may not work correctly in interrupt context', severity: 'info' }],
-    ['I2C0', { reason: 'I2C operations can cause lockups in interrupt context', severity: 'warning' }],
-    ['I2C1', { reason: 'I2C operations can cause lockups in interrupt context', severity: 'warning' }],
-    ['SPI0', { reason: 'SPI operations may cause issues in interrupt context', severity: 'info' }],
-    ['SPI1', { reason: 'SPI operations may cause issues in interrupt context', severity: 'info' }],
-]);
+const DEFAULT_ISR_UNSAFE_OPERATIONS = new Map();
 /**
  * Analyze a program for interrupt handler issues.
  *
@@ -243,7 +235,7 @@ function scanExpressionForCallbacks(expr, callback, parentExpr) {
 // emission path already handles isVolatile (statement-renderer.ts).
 // ---------------------------------------------------------------------------
 /** Collect variable names assigned (written) within a statement body. */
-function collectAssignedNames(stmts, names) {
+export function collectAssignedNames(stmts, names) {
     for (const stmt of stmts) {
         const s = stmt;
         if (stmt.kind === 'assign') {
@@ -265,7 +257,7 @@ function collectAssignedNames(stmts, names) {
     }
 }
 /** Collect variable names read (referenced) within a statement body. */
-function collectReadNames(stmts, names) {
+export function collectReadNames(stmts, names) {
     for (const stmt of stmts) {
         walkExpressionsInStatement(stmt, (expr) => {
             if (expr.kind === 'identifier' && typeof expr.value === 'string') {

package/dist/ir/ownership-analysis.js

@@ -765,6 +765,12 @@ function analyzeExpression(expr, scope, diagnostics, fallbackSpan) {
             analyzeExpression(expr.inner, scope, diagnostics, span);
             break;
         }
+        case 'call': {
+            for (const arg of expr.args) {
+                analyzeExpression(arg, scope, diagnostics, span);
+            }
+            break;
+        }
         case 'number':
         case 'string':
         case 'boolean':

package/dist/ir/pin-capability-validation.js

@@ -77,6 +77,35 @@ function findPinsWithCapability(capability, boardConstants) {
     }
     return result;
 }
+/**
+ * Does the board declare ANY per-pin `type:'pwm'` function entry anywhere?
+ *
+ * AVR-family boards (atmega328p, etc.) hardwire PWM to specific timer-output
+ * pins, so their MCU descriptors list `{ type:'pwm', ... }` per pin and the
+ * capability check correctly rejects PWM on non-timer pins. ESP32-family
+ * boards route LEDC to ANY output GPIO via the GPIO matrix, so their MCU
+ * descriptors carry zero `type:'pwm'` entries — PWM is a board-wide property
+ * (the `pins.pwm` collection), not a per-pin function. On such boards the
+ * per-pin capability check would false-positive on every pin, so the caller
+ * skips it when this returns false. This distinguishes the two families
+ * cleanly (AVR has entries, ESP32 has none) without special-casing arch names.
+ */
+function boardHasAnyPwmFunctionEntries(boardConstants) {
+    if (!boardConstants)
+        return false;
+    for (let i = 0; i < 100; i++) {
+        if (boardConstants.get(`pins.all.${i}.name`) === undefined)
+            continue;
+        for (let j = 0; j < 10; j++) {
+            const type = boardConstants.get(`pins.all.${i}.functions.${j}.type`);
+            if (type === undefined)
+                break;
+            if (String(type) === 'pwm')
+                return true;
+        }
+    }
+    return false;
+}
 // ---------------------------------------------------------------------------
 // Capability check for a single HAL operation
 // ---------------------------------------------------------------------------
@@ -88,6 +117,13 @@ function checkCapability(operation, sourceLine, sourceCol, filePath, boardConsta
     const capability = operationToCapability(op);
     if (!capability)
         return; // GPIO/timing — always available.
+    // ESP32-family boards route PWM (LEDC) to any output GPIO via the GPIO
+    // matrix, so they carry zero per-pin `type:'pwm'` entries (unlike AVR,
+    // which hardwires PWM to timer-output pins). On such boards the per-pin PWM
+    // capability check would reject every pin; skip it and let the framework's
+    // LEDC driver handle routing. This does NOT weaken AVR, which has entries.
+    if (capability === 'pwm' && !boardHasAnyPwmFunctionEntries(boardConstants))
+        return;
     const pin = operation.pin;
     if (typeof pin !== 'number' || pin < 0)
         return;
@@ -250,6 +286,7 @@ function scanExpression(expr, boardConstants, parentLine, parentCol, parentFileP
         case 'identifier':
         case 'raw':
         case 'tuple-access':
+        case 'call':
             break;
         default:
             assertNever(expr);

package/dist/ir/pin-mode-validation.d.ts

@@ -4,7 +4,7 @@ import type { Diagnostic } from '../types.js';
  * Validate that GPIO I/O operations are preceded by mode configuration.
  *
  * - Read without prior mode → **warning** (undefined behavior on floating pin)
- * - Write without prior mode → **info** (Arduino implicitly sets OUTPUT, but
- *   explicit configuration is recommended)
+ * - Write without prior mode → **info** (Wiring-derived frameworks implicitly
+ *   set OUTPUT, but explicit configuration is recommended)
  */
 export declare function validatePinModeConfig(program: ProgramIR): Diagnostic[];

package/dist/ir/pin-mode-validation.js

@@ -5,6 +5,7 @@
 // configuration. Generates warnings for reads and info for writes.
 // ---------------------------------------------------------------------------
 import { scanNestedStatements } from './interrupt-analysis.js';
+import { hasLoadedFramework, getLoadedFramework } from '../framework-registry.js';
 /** Methods that configure pin mode. */
 const MODE_SET_METHODS = new Set([
     'inputPullUp', 'inputPullDown', 'outputOpenDrain',
@@ -14,7 +15,7 @@ const MODE_SET_METHODS = new Set([
 const READ_METHODS = new Set([
     'read', 'isHigh', 'isLow', 'readAnalog', 'readVoltage',
 ]);
-/** Write operations that implicitly set OUTPUT mode on Arduino. */
+/** Write operations that implicitly set OUTPUT mode on Wiring-derived frameworks. */
 const WRITE_METHODS = new Set([
     'write', 'high', 'low', 'toggle', 'pulse', 'pwm', 'tone',
 ]);
@@ -26,8 +27,8 @@ const PIN_RECEIVER_KINDS = new Set([
  * Validate that GPIO I/O operations are preceded by mode configuration.
  *
  * - Read without prior mode → **warning** (undefined behavior on floating pin)
- * - Write without prior mode → **info** (Arduino implicitly sets OUTPUT, but
- *   explicit configuration is recommended)
+ * - Write without prior mode → **info** (Wiring-derived frameworks implicitly
+ *   set OUTPUT, but explicit configuration is recommended)
  */
 export function validatePinModeConfig(program) {
     const diagnostics = [];
@@ -65,7 +66,7 @@ export function validatePinModeConfig(program) {
             diagnostics.push({
                 severity: 'info',
                 message: `Pin '${receiver}' written via '${method}()' without explicit mode configuration. ` +
-                    `Arduino implicitly sets OUTPUT, but explicit ${receiver}.asOutput() is recommended.`,
+                    `The target framework implicitly sets OUTPUT, but explicit ${receiver}.asOutput() is recommended.`,
                 filePath: program.fileName,
                 code: 'pin-mode-not-set',
                 source: 'pin-mode-validation',
@@ -112,7 +113,7 @@ export function validatePinModeConfig(program) {
             diagnostics.push({
                 severity: 'info',
                 message: `Pin ${op.pin} written without explicit mode configuration. ` +
-                    `Arduino implicitly sets OUTPUT, but explicit asOutput() is recommended.`,
+                    `The target framework implicitly sets OUTPUT, but explicit asOutput() is recommended.`,
                 filePath: program.fileName,
                 code: 'pin-mode-not-set',
                 source: 'pin-mode-validation',
@@ -148,21 +149,51 @@ export function validatePinModeConfig(program) {
         // Raw nodes: after full HAL resolution, some pin ops land as their C++ text
         // (e.g. `digitalRead(2)`, `digitalWrite(2, 1)`) rather than structured
         // hal-expr nodes. Extract the pin number and apply the same mode check.
-        // This mirrors how peripheral-usage.ts detects gpio via emitted text.
+        // Detect GPIO ops in lowered raw C++ text. Build the read/write name
+        // patterns from the loaded framework's HAL vocabulary (halCallNames),
+        // classifying names containing "Read" as reads and "Write" as writes (the
+        // Wiring-derived convention). Seed with digitalRead/digitalWrite as the
+        // canonical Wiring forms so the validator works even when no framework is
+        // loaded. Non-Wiring frameworks that emit other call forms register them
+        // via halCallNames; this loop picks them up.
         if (e.kind === 'raw' && typeof e.value === 'string') {
-            const readMatch = e.value.match(/digitalRead\((\d+)\)/);
-            const writeMatch = e.value.match(/digitalWrite\((\d+)/);
-            const toggleMatch = e.value.match(/digitalWrite\((\d+),\s*digitalRead/);
-            const pin = readMatch ? parseInt(readMatch[1], 10)
-                : writeMatch ? parseInt(writeMatch[1], 10)
-                    : null;
-            if (pin !== null) {
-                const op = toggleMatch
-                    ? { operation: 'gpio.toggle', pin }
-                    : readMatch ? { operation: 'gpio.read', pin }
-                        : { operation: 'gpio.write', pin };
-                checkGpioHalOp(op);
+            const frameworkHalNames = hasLoadedFramework()
+                ? getLoadedFramework().strategy.halCallNames?.()
+                : undefined;
+            const halNames = frameworkHalNames ?? new Set(['digitalRead', 'digitalWrite']);
+            const readNames = [...halNames].filter(n => /read/i.test(n));
+            const writeNames = [...halNames].filter(n => /write/i.test(n));
+            let pin = null;
+            let op = null;
+            for (const rn of readNames) {
+                const esc = rn.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const m = e.value.match(new RegExp(`${esc}\\((\\d+)\\)`));
+                if (m) {
+                    pin = parseInt(m[1], 10);
+                    op = { operation: 'gpio.read', pin };
+                    break;
+                }
+            }
+            if (!op) {
+                for (const wn of writeNames) {
+                    const esc = wn.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                    const m = e.value.match(new RegExp(`${esc}\\((\\d+)`));
+                    if (m) {
+                        pin = parseInt(m[1], 10);
+                        op = { operation: 'gpio.write', pin };
+                        break;
+                    }
+                }
+            }
+            // toggle: a write call whose second arg is a read call on the same pin.
+            if (!op) {
+                const tm = e.value.match(/\((\d+),\s*\w*[Rr]ead/);
+                if (tm) {
+                    op = { operation: 'gpio.toggle', pin: parseInt(tm[1], 10) };
+                }
             }
+            if (op)
+                checkGpioHalOp(op);
         }
         // Recurse into nested expressions
         if (e.args && Array.isArray(e.args)) {

package/dist/ir/program-analysis.d.ts

@@ -70,11 +70,53 @@ export interface ProgramAnalysisResult {
      *  __tc_ble runtime shims and their esp_wifi/esp_http_client/nimble includes
      *  on these. Detected from wifi.* / http.* / ble.* HAL-op operation names. */
     usesWifi: boolean;
+    /** Fine-grained WiFi sub-feature tracking — gates individual shim sub-blocks
+     *  so that unused static helper functions don't trigger -Wunused-function. */
+    usesWifiConnect: boolean;
+    usesWifiConnectBlocking: boolean;
+    usesWifiQuery: boolean;
+    usesWifiScan: boolean;
+    usesWifiConfig: boolean;
     usesHttp: boolean;
     usesBle: boolean;
     /** Preferences (NVS) usage — framework-esp32 gates the __tc_prefs runtime shim
      *  and its nvs_flash/nvs includes on this. Detected from preferences.* ops. */
     usesPreferences: boolean;
+    /** Random usage — frameworks gate their PRNG runtime/include on this
+     *  (e.g. framework-esp32 includes <esp_random.h>). Detected from random.* ops. */
+    usesRandom: boolean;
+    /** FS (filesystem) usage — frameworks gate their VFS/SD runtime shim on this.
+     *  Detected from fs.* ops. */
+    usesFS: boolean;
+    /** mDNS usage — frameworks gate the esp_mdns runtime/include on this. */
+    usesMdns: boolean;
+    /** MQTT usage — frameworks gate the esp_mqtt runtime/include on this. */
+    usesMqtt: boolean;
+    /** OTA usage — frameworks gate the esp_https_ota runtime/include on this. */
+    usesOta: boolean;
+    /** Temperature (die temp) usage. Detected from temp.* ops. */
+    usesTemp: boolean;
+    /** Hardware timer (GPTimer) usage. Detected from hwtimer.* ops. */
+    usesHwtimer: boolean;
+    /** Capacitive touch pins usage. Detected from capacitive.* ops. */
+    usesCapacitive: boolean;
+    /** Worker offload usage. Detected from worker.* ops. Frameworks gate the
+     *  worker_runtime polyfill (and its per-framework backing) on this. */
+    usesWorker: boolean;
+    /** Native/desktop: std::chrono / steady_clock usage (gates <chrono>). */
+    usesChrono: boolean;
+    /** Native/desktop: std::set usage (gates <set>). */
+    usesSet: boolean;
+    /** Native/desktop: std::algorithm usage (std::sort/find/transform etc., gates <algorithm>). */
+    usesAlgorithm: boolean;
+    /** Native/desktop: cstdio usage (printf/fprintf/snprintf, gates <cstdio>). */
+    usesCstdio: boolean;
+    /** digitalRead() in lowered raw text or gpio.read hal-op (gates the native digitalRead shim). */
+    usesDigitalRead: boolean;
+    /** display.* hal-op present, or a UI is mounted (replaces ad-hoc programUsesDisplay walks). */
+    usesDisplay: boolean;
+    /** cuttlefish_halt() in lowered raw text (gates the cuttlefish_halt macro polyfill). */
+    usesHalt: boolean;
 }
 /**
  * Analyze a program IR in a single pass to detect all features.