@typecad/cuttlefish 0.1.0-alpha.2 → 1.0.0-alpha.10

package/dist/ir/pin-alias-conflict.js

@@ -1,5 +1,5 @@
 import { findBoardPinByName } from './board-pin-utils.js';
-export function validatePinAliasConflicts(usage, boardConstants) {
+export function validatePinAliasConflicts(usage, boardConstants, filePath) {
     if (!boardConstants || usage.pinsUsed.size === 0) {
         return [];
     }
@@ -26,6 +26,7 @@ export function validatePinAliasConflicts(usage, boardConstants) {
         diagnostics.push({
             severity: 'warning',
             code: 'pin-alias-conflict',
+            filePath,
             source: 'pin-alias-conflict',
             message: `Pin '${canonicalPinName}' is referenced through multiple names${boardLabel}: ${orderedNames.join(', ')}. These names refer to the same physical pin. Pick one name to keep pin usage and diagnostics unambiguous.`,
         });

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

@@ -77,10 +77,39 @@ 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
 // ---------------------------------------------------------------------------
-function checkCapability(operation, sourceLine, sourceCol, boardConstants, diagnostics) {
+function checkCapability(operation, sourceLine, sourceCol, filePath, boardConstants, diagnostics) {
     // Only operations with a pin field are capability-checked.
     const op = operation.operation;
     if (!('pin' in operation))
@@ -88,6 +117,13 @@ function checkCapability(operation, sourceLine, sourceCol, boardConstants, diagn
     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;
@@ -145,48 +181,49 @@ function checkCapability(operation, sourceLine, sourceCol, boardConstants, diagn
         hint,
         line: sourceLine,
         column: sourceCol,
+        filePath,
         source: 'pin-capability-validation',
     });
 }
 // ---------------------------------------------------------------------------
 // IR tree scanner
 // ---------------------------------------------------------------------------
-function scanExpression(expr, boardConstants, parentLine, parentCol, diagnostics) {
+function scanExpression(expr, boardConstants, parentLine, parentCol, parentFilePath, diagnostics) {
     if (!expr || typeof expr !== 'object')
         return;
     switch (expr.kind) {
         case 'binary': {
-            scanExpression(expr.left, boardConstants, parentLine, parentCol, diagnostics);
-            scanExpression(expr.right, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.left, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
+            scanExpression(expr.right, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             break;
         }
         case 'ternary': {
-            scanExpression(expr.condition, boardConstants, parentLine, parentCol, diagnostics);
-            scanExpression(expr.whenTrue, boardConstants, parentLine, parentCol, diagnostics);
-            scanExpression(expr.whenFalse, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.condition, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
+            scanExpression(expr.whenTrue, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
+            scanExpression(expr.whenFalse, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             break;
         }
         case 'property-access': {
-            scanExpression(expr.object, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.object, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             break;
         }
         case 'unary': {
-            scanExpression(expr.operand, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.operand, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             break;
         }
         case 'paren': {
-            scanExpression(expr.inner, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.inner, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             break;
         }
         case 'array': {
             for (const el of expr.elements) {
-                scanExpression(el, boardConstants, parentLine, parentCol, diagnostics);
+                scanExpression(el, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             }
             break;
         }
         case 'object': {
             for (const field of expr.fields) {
-                scanExpression(field.value, boardConstants, parentLine, parentCol, diagnostics);
+                scanExpression(field.value, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             }
             break;
         }
@@ -204,43 +241,43 @@ function scanExpression(expr, boardConstants, parentLine, parentCol, diagnostics
         }
         case 'method-call': {
             for (const arg of expr.args) {
-                scanExpression(arg, boardConstants, parentLine, parentCol, diagnostics);
+                scanExpression(arg, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             }
             break;
         }
         case 'element-access': {
-            scanExpression(expr.object, boardConstants, parentLine, parentCol, diagnostics);
-            scanExpression(expr.index, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.object, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
+            scanExpression(expr.index, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             break;
         }
         case 'string_concat': {
             for (const part of expr.parts) {
-                scanExpression(part, boardConstants, parentLine, parentCol, diagnostics);
+                scanExpression(part, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             }
             break;
         }
         case 'template_string': {
-            scanExpression(expr.expression, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.expression, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             break;
         }
         case 'spread_array': {
-            scanExpression(expr.spreadExpr, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.spreadExpr, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             for (const el of expr.additionalElements) {
-                scanExpression(el, boardConstants, parentLine, parentCol, diagnostics);
+                scanExpression(el, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             }
             break;
         }
         case 'instanceof': {
-            scanExpression(expr.object, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.object, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             break;
         }
         case 'await': {
-            scanExpression(expr.value, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.value, boardConstants, parentLine, parentCol, parentFilePath, diagnostics);
             break;
         }
         case 'hal-expr': {
             // Expression-form HAL operation (e.g. adc.read used as a value).
-            checkCapability(expr.operation, parentLine, parentCol, boardConstants, diagnostics);
+            checkCapability(expr.operation, parentLine, parentCol, parentFilePath, boardConstants, diagnostics);
             break;
         }
         case 'number':
@@ -249,6 +286,7 @@ function scanExpression(expr, boardConstants, parentLine, parentCol, diagnostics
         case 'identifier':
         case 'raw':
         case 'tuple-access':
+        case 'call':
             break;
         default:
             assertNever(expr);
@@ -259,20 +297,21 @@ function scanStatement(stmt, boardConstants, diagnostics) {
         return;
     const line = stmt.sourceSpan?.startLine;
     const col = stmt.sourceSpan?.startColumn;
+    const filePath = stmt.sourceSpan?.filePath;
     switch (stmt.kind) {
         case 'var_decl': {
             if (stmt.initializer)
-                scanExpression(stmt.initializer, boardConstants, line, col, diagnostics);
+                scanExpression(stmt.initializer, boardConstants, line, col, filePath, diagnostics);
             break;
         }
         case 'assign': {
             if (stmt.value)
-                scanExpression(stmt.value, boardConstants, line, col, diagnostics);
+                scanExpression(stmt.value, boardConstants, line, col, filePath, diagnostics);
             break;
         }
         case 'if': {
             if (stmt.condition)
-                scanExpression(stmt.condition, boardConstants, line, col, diagnostics);
+                scanExpression(stmt.condition, boardConstants, line, col, filePath, diagnostics);
             for (const s of stmt.thenBranch)
                 scanStatement(s, boardConstants, diagnostics);
             if (stmt.elseBranch)
@@ -283,14 +322,14 @@ function scanStatement(stmt, boardConstants, diagnostics) {
         case 'while':
         case 'do_while': {
             if (stmt.condition)
-                scanExpression(stmt.condition, boardConstants, line, col, diagnostics);
+                scanExpression(stmt.condition, boardConstants, line, col, filePath, diagnostics);
             for (const s of stmt.body)
                 scanStatement(s, boardConstants, diagnostics);
             break;
         }
         case 'for': {
             if (stmt.condition)
-                scanExpression(stmt.condition, boardConstants, line, col, diagnostics);
+                scanExpression(stmt.condition, boardConstants, line, col, filePath, diagnostics);
             if (stmt.initializer)
                 scanStatement(stmt.initializer, boardConstants, diagnostics);
             if (stmt.increment)
@@ -309,23 +348,23 @@ function scanStatement(stmt, boardConstants, diagnostics) {
         }
         case 'return': {
             if (stmt.value)
-                scanExpression(stmt.value, boardConstants, line, col, diagnostics);
+                scanExpression(stmt.value, boardConstants, line, col, filePath, diagnostics);
             break;
         }
         case 'call': {
             for (const arg of stmt.args) {
-                scanExpression(arg, boardConstants, line, col, diagnostics);
+                scanExpression(arg, boardConstants, line, col, filePath, diagnostics);
             }
             break;
         }
         case 'hal-op': {
             // Statement-form HAL operation — the primary capability check target.
-            checkCapability(stmt.operation, line, col, boardConstants, diagnostics);
+            checkCapability(stmt.operation, line, col, filePath, boardConstants, diagnostics);
             break;
         }
         case 'switch': {
             if (stmt.expression)
-                scanExpression(stmt.expression, boardConstants, line, col, diagnostics);
+                scanExpression(stmt.expression, boardConstants, line, col, filePath, diagnostics);
             for (const c of stmt.cases) {
                 for (const s of c.body)
                     scanStatement(s, boardConstants, diagnostics);
@@ -355,7 +394,7 @@ function scanStatement(stmt, boardConstants, diagnostics) {
         }
         case 'throw': {
             if (stmt.value)
-                scanExpression(stmt.value, boardConstants, line, col, diagnostics);
+                scanExpression(stmt.value, boardConstants, line, col, filePath, diagnostics);
             break;
         }
         case 'update':

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 = [];
@@ -43,6 +44,7 @@ export function validatePinModeConfig(program) {
                 message: `Analog pin '${receiver}' used as digital output. ` +
                     `Analog input capability (ADC) is lost while pin is in OUTPUT mode. ` +
                     `Call ${receiver}.asInput() to restore analog reading.`,
+                filePath: program.fileName,
                 code: 'analog-pin-as-output',
                 source: 'pin-mode-validation',
             });
@@ -55,6 +57,7 @@ export function validatePinModeConfig(program) {
                 severity: 'warning',
                 message: `Pin '${receiver}' read via '${method}()' without prior mode configuration. ` +
                     `Call ${receiver}.asInput() or ${receiver}.inputPullUp() first.`,
+                filePath: program.fileName,
                 code: 'pin-mode-not-set',
                 source: 'pin-mode-validation',
             });
@@ -63,7 +66,8 @@ 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',
             });
@@ -100,6 +104,7 @@ export function validatePinModeConfig(program) {
                 severity: 'warning',
                 message: `Pin ${op.pin} read without prior mode configuration. ` +
                     `Call asInput() or inputPullUp() first — reading a floating pin is undefined behavior.`,
+                filePath: program.fileName,
                 code: 'pin-mode-not-set',
                 source: 'pin-mode-validation',
             });
@@ -108,7 +113,8 @@ 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',
             });
@@ -143,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/pin-safety.d.ts

@@ -8,4 +8,4 @@ import type { Diagnostic } from '../types.js';
  * @param boardConstants - Board constants containing pins.unsafe array
  * @returns Array of diagnostic warnings for unsafe pin usage
  */
-export declare function validateUnsafePins(usage: PeripheralUsage, boardConstants: BoardConstants | undefined): Diagnostic[];
+export declare function validateUnsafePins(usage: PeripheralUsage, boardConstants: BoardConstants | undefined, filePath: string): Diagnostic[];

package/dist/ir/pin-safety.js

@@ -30,7 +30,7 @@ function buildUnsafePinMessage(pinName, boardConstants) {
  * @param boardConstants - Board constants containing pins.unsafe array
  * @returns Array of diagnostic warnings for unsafe pin usage
  */
-export function validateUnsafePins(usage, boardConstants) {
+export function validateUnsafePins(usage, boardConstants, filePath) {
     const diagnostics = [];
     if (!boardConstants)
         return diagnostics;
@@ -50,6 +50,7 @@ export function validateUnsafePins(usage, boardConstants) {
                 severity: 'warning',
                 message: buildUnsafePinMessage(pinName, boardConstants),
                 code: 'unsafe-pin-usage',
+                filePath,
                 source: 'pin-safety',
             });
         }

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

@@ -29,6 +29,22 @@ export interface ProgramAnalysisResult {
     usesTiming: boolean;
     usesWDT: boolean;
     usesStrPtr: boolean;
+    usesUart: boolean;
+    usesSPI: boolean;
+    usesI2C: boolean;
+    usesEEPROM: boolean;
+    usesTone: boolean;
+    /** map()/constrain() Arduino-API calls. framework-avr gates its native
+     *  _native_map/_native_constrain helpers on these (they're dead code
+     *  otherwise — no other internal caller references them). */
+    usesMap: boolean;
+    usesConstrain: boolean;
+    /** Comprehensive timing gate for the native millis() Timer0 ISR on AVR.
+     *  True when the program directly uses millis/delay/micros, OR has hidden
+     *  consumers of the soft clock: setInterval/setTimeout (timerCallCount),
+     *  async functions (the runtime polls millis), or a mounted UI (per-frame
+     *  tick injected by the emitter, not present in user source). */
+    usesNativeTiming: boolean;
     hasSerialBegin: boolean;
     hasGenerators: boolean;
     usesStdMap: boolean;
@@ -36,6 +52,71 @@ export interface ProgramAnalysisResult {
      *  __tc_TimerRuntime::MAX_TIMERS to the observed count (floor 1) rather than
      *  a blind constant, so a one-timer program links one slot, not eight. */
     timerCallCount: number;
+    /** ESP32 peripheral usage — framework-esp32 gates its IDF driver blocks and
+     *  forced includes on these. Detected from HAL-op operation names, the same
+     *  way usesUart/usesSPI/usesI2C are. Other frameworks have no CUTTLEFISH_*
+     *  blocks with these marker names so the setup.ts filters are no-ops there. */
+    usesGPIO: boolean;
+    usesPWM: boolean;
+    usesRmt: boolean;
+    usesADC: boolean;
+    usesDAC: boolean;
+    usesPower: boolean;
+    usesWdt: boolean;
+    usesInterrupts: boolean;
+    usesPulse: boolean;
+    usesShift: boolean;
+    /** WiFi / HTTP / BLE usage — framework-esp32 gates the __tc_wifi/__tc_http/
+     *  __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.